diff --git a/.socraticodecontextartifacts.json b/.socraticodecontextartifacts.json index d844c36..2b6982d 100644 --- a/.socraticodecontextartifacts.json +++ b/.socraticodecontextartifacts.json @@ -163,7 +163,7 @@ { "name": "dependency-contract", "path": "./pyproject.toml", - "description": "Project and tooling contract. The co-core / co-core-aio / co-core-sync pins (>=0.45.0,<0.46 since #192's one-minor catch-up; 0.44.0 was #184's three-minor catch-up, the first on the co-pypi index; 0.41.0 was #179's catch-up; 0.40.1 was #177's, for #63's render field; 0.40.0 was #172's catch-up; 0.39 was #153's, ahead of #138's capture consumer; 0.37 was #136's, for FetchPolicyState.generation and fetch_policy_supersedes; 0.36 was #140's catch-up; each raise's wheel diff covers the whole import closure; 0.19.6 brought the content.persist contract, cannobserv#493, and 0.19.3 the shared content-addressed BlobStore, cannobserv#475) with no extra on co-core (its [extract] parsers were unused, dropped by #142) and [bus,gcs] / [gcs] on the other two, the floor history that explains each raise, the explicit co-pypi [[tool.uv.index]] with a [tool.uv.sources] entry per co-core package (#183), the ruff rule set and its skills-vendor exclusion, the ty exclusion, the replicator-worker console script, pytest configuration (asyncio auto mode, the integration and gcs markers both deselected by default, timeout) and the 80% coverage gate. The [build-system] uv_build bound is one minor (>=0.13.0,<0.14 since #195), mirrored by ci.yml's setup-uv version: inputs." + "description": "Project and tooling contract. The co-core / co-core-aio / co-core-sync pins (>=0.46.0,<0.47 since #199's one-minor catch-up, locked at 0.46.1; 0.45.0 was #192's catch-up; 0.44.0 was #184's three-minor catch-up, the first on the co-pypi index; 0.41.0 was #179's catch-up; 0.40.1 was #177's, for #63's render field; 0.40.0 was #172's catch-up; 0.39 was #153's, ahead of #138's capture consumer; 0.37 was #136's, for FetchPolicyState.generation and fetch_policy_supersedes; 0.36 was #140's catch-up; each raise's wheel diff covers the whole import closure; 0.19.6 brought the content.persist contract, cannobserv#493, and 0.19.3 the shared content-addressed BlobStore, cannobserv#475) with no extra on co-core (its [extract] parsers were unused, dropped by #142) and [bus,gcs] / [gcs] on the other two, the floor history that explains each raise, the explicit co-pypi [[tool.uv.index]] with a [tool.uv.sources] entry per co-core package (#183), the ruff rule set and its skills-vendor exclusion, the ty exclusion, the replicator-worker console script, pytest configuration (asyncio auto mode, the integration and gcs markers both deselected by default, timeout) and the 80% coverage gate. The [build-system] uv_build bound is one minor (>=0.13.0,<0.14 since #195), mirrored by ci.yml's setup-uv version: inputs." }, { "name": "main-checkout-guard", diff --git a/AGENTS.md b/AGENTS.md index 9c0f004..8ae7157 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ Override vendored `brainstorming`'s defaults: Python ≥3.12, uv, pytest, ruff. `ty` (`uv run ty check`) is a **non-gating** type checker — no pre-commit or CI gate. -**co-core comes from the private co-pypi index, not PyPI.** `uv lock` and a cold `uv sync` need its token: `bash scripts/co-pypi.sh uv …`, never the writer's ADC. Pin the current minor — `>=0.45.0,<0.46` — and raise the **patch** floor with every co-core feature the code starts depending on. Both, and each skew so far: [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md). +**co-core comes from the private co-pypi index, not PyPI.** `uv lock` and a cold `uv sync` need its token: `bash scripts/co-pypi.sh uv …`, never the writer's ADC. Pin the current minor — `>=0.46.0,<0.47` — and raise the **patch** floor with every co-core feature the code starts depending on. Both, and each skew so far: [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md). ## Code Exploration Policy diff --git a/docs/DEPENDENCIES.md b/docs/DEPENDENCIES.md index e3ffbc4..25e76df 100644 --- a/docs/DEPENDENCIES.md +++ b/docs/DEPENDENCIES.md @@ -80,11 +80,11 @@ or `uv lock` asks the index. ## The co-core pin, and why the patch floor is load-bearing -Pin the current minor — `>=0.45.0,<0.46`, on all three. The **patch** floor is load-bearing, not tidiness: the change-bus payloads are `extra="ignore"`, so on an older wheel a model constructed with fields it does not have yet succeeds and silently discards them. Raise the floor with every co-core feature the code starts depending on, or a version skew publishes facts that look right and carry nothing (#10). Both floors since fail *loudly* instead — a ValidationError at construction (0.8.0 requires `info_source_id` on all three fetch payloads, #19/#28) or an ImportError at load, never reaching a running worker (0.9.4 cuts the replicate contracts, #29; 0.19.3 ships the shared `BlobStore`, #114; 0.19.6 cuts the persist contract, #114 step 6). +Pin the current minor — `>=0.46.0,<0.47`, on all three. The **patch** floor is load-bearing, not tidiness: the change-bus payloads are `extra="ignore"`, so on an older wheel a model constructed with fields it does not have yet succeeds and silently discards them. Raise the floor with every co-core feature the code starts depending on, or a version skew publishes facts that look right and carry nothing (#10). Both floors since fail *loudly* instead — a ValidationError at construction (0.8.0 requires `info_source_id` on all three fetch payloads, #19/#28) or an ImportError at load, never reaching a running worker (0.9.4 cuts the replicate contracts, #29; 0.19.3 ships the shared `BlobStore`, #114; 0.19.6 cuts the persist contract, #114 step 6). **The 0.10 → 0.13 jump (#77) was the first departure from "pin the current minor", and what justified it is evidence rather than judgement.** The hazard that rule guards is payload fields moving under `extra="ignore"`; every module this service imports proved byte-identical between the two wheels — `pure/models/changes.py`, `pure/adapters/bus/{envelope,exceptions}.py`, `effects/{bus,fetch,gcs}.py`, `pure/util/{hashing,gcs}.py`, and all of `co_core_aio` bar its `__version__`. Only `streams.py` gained anything (`group_name`, `stream_kind` — cannobserv#384), and Replicator imports no `co_v1` adapter, which is where 0.13.2's other changes landed. That `diff -rq` of both wheels from the then-wheelhouse took a minute and turned a deferred change into a safe one. -**Diff the import closure before every pin move**, a single minor included: #136 needed it for one. The version distance is not the risk, the moved surface is, and the import lines are not the surface. At 0.19 → 0.36 (#140), `changes.py`'s import of `extract.canonical` brought in the `pure/extract` package, which had changed (cannobserv#523), and no import line in Replicator names it. `scripts/co_core_closure_diff.py OLD NEW` (#145) walks the closure from `src/` and `scripts/` through all three wheels at each version, fetched first ([Moving the pin](#moving-the-pin)). It prints the counts, a verdict per file that isn't identical, the Requires-Dist delta and the closure's third-party imports, and `--diff` adds each changed file's code diff. Paste the report into the pin comment and write the reasons around it by hand. `version-only` and `docstrings-only` need no reading. `changed` does, a model under `extra="ignore"` above all. `added` and `removed` are modules joining or leaving the closure. An **Unresolved imports** line names a module that is imported but isn't in the wheel, which fails at import. A **Not parsed** line names a file whose imports the walk couldn't follow. Each prints only when there's something to list. The walk follows `TYPE_CHECKING` imports and lists dynamic ones without following them. At 0.45.0 that's co-core-sync's two lazy `__getattr__` sites in `drivers/` and `drivers/blobstore/`. Both are expected, because each target is named again under `TYPE_CHECKING`. A new site whose targets aren't named there is a gap to read by hand. Flags: `--root`, `--package`, `--wheels` (required); the defaults are this repo's. +**Diff the import closure before every pin move**, a single minor included: #136 needed it for one. The version distance is not the risk, the moved surface is, and the import lines are not the surface. At 0.19 → 0.36 (#140), `changes.py`'s import of `extract.canonical` brought in the `pure/extract` package, which had changed (cannobserv#523), and no import line in Replicator names it. `scripts/co_core_closure_diff.py OLD NEW` (#145) walks the closure from `src/` and `scripts/` through all three wheels at each version, fetched first ([Moving the pin](#moving-the-pin)). It prints the counts, a verdict per file that isn't identical, the Requires-Dist delta and the closure's third-party imports, and `--diff` adds each changed file's code diff. Paste the report into the pin comment and write the reasons around it by hand. `version-only` and `docstrings-only` need no reading. `changed` does, a model under `extra="ignore"` above all. `added` and `removed` are modules joining or leaving the closure. An **Unresolved imports** line names a module that is imported but isn't in the wheel, which fails at import. A **Not parsed** line names a file whose imports the walk couldn't follow. Each prints only when there's something to list. The walk follows `TYPE_CHECKING` imports and lists dynamic ones without following them. At 0.46.1 that's co-core-sync's two lazy `__getattr__` sites in `drivers/` and `drivers/blobstore/`. Both are expected, because each target is named again under `TYPE_CHECKING`. A new site whose targets aren't named there is a gap to read by hand. Flags: `--root`, `--package`, `--wheels` (required); the defaults are this repo's. ## The build backend's bound, and CI's uv diff --git a/pyproject.toml b/pyproject.toml index 8f92428..0be996a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,21 +7,25 @@ license = "MIT" license-files = ["LICENSE"] requires-python = ">=3.12" dependencies = [ - # Floor is 0.45.0, and it carries no new feature: a one-minor catch-up - # (#192), in #184's shape. `co-core-aio` and `co-core-sync` 0.45.0 require - # `co-core>=0.45,<0.46`, so the three move together. 0.45.0's one library - # change is co/v1's `EventModel.url`, which reads the Event's `website` link - # and falls back to its `event_url` link, and a malformed `links` embed now - # raises `CoV1ResponseAnomaly` (cannobserv#663). Both sit outside this - # closure. - # - # **`scripts/co_core_closure_diff.py 0.44.0 0.45.0`** (#145), verbatim: - # - # ## Import closure, 0.44.0 → 0.45.0 + # Floor is 0.46.0, and it carries no new feature: a one-minor catch-up + # (#199), in #192's shape. The lock takes 0.46.1, the index's newest. The + # floor stays at .0 because nothing here depends on 0.46.1's one change, + # `co-core[extract]`'s soupsieve floor (cannobserv#667), an extra this + # project doesn't declare. `co-core-aio` and `co-core-sync` 0.46.x require + # `co-core>=0.46,<0.47`, so the three move together. 0.46.0's library + # changes are both on co/v1's read path, outside this closure: a CPT-backed + # record's `PostModel.wp_link` reads the server's `permalink` + # (cannobserv#664), and `EventModel.url` drops its `link` fallback + # (cannobserv#663). Its breaking removal, `WordPressMetadata`'s three + # `wp_view_*_url` templates, ships in none of the three wheels locked here. + # + # **`scripts/co_core_closure_diff.py 0.45.0 0.46.1`** (#145), verbatim: + # + # ## Import closure, 0.45.0 → 0.46.1 # # Roots `src`, `scripts`; packages `co_core`, `co_core_aio`, `co_core_sync`. # - # 58 files at 0.44.0, 58 at 0.45.0. 3 not identical: + # 58 files at 0.45.0, 58 at 0.46.1. 3 not identical: # # - `version-only` co_core/__init__.py # - `version-only` co_core_aio/__init__.py @@ -29,11 +33,11 @@ dependencies = [ # # **Requires-Dist:** # - # - co_core: unchanged - # - co_core_aio: removed `co-core<0.45,>=0.44`; added `co-core<0.46,>=0.45` - # - co_core_sync: removed `co-core<0.45,>=0.44`; added `co-core<0.46,>=0.45` + # - co_core: removed `soupsieve<3,>=2.0; extra == 'extract'`; added `soupsieve<5,>=4.1; extra == 'extract'` + # - co_core_aio: removed `co-core<0.46,>=0.45`; added `co-core<0.47,>=0.46` + # - co_core_sync: removed `co-core<0.46,>=0.45`; added `co-core<0.47,>=0.46` # - # **Third-party imports** (at 0.45.0): `google`, `google_auth_oauthlib`, `googleapiclient`, `httpx`, `pydantic`, `redis`, `requests`, `urllib3`. + # **Third-party imports** (at 0.46.1): `google`, `google_auth_oauthlib`, `googleapiclient`, `httpx`, `pydantic`, `redis`, `requests`, `urllib3`. # # **Dynamic imports, not followed:** # @@ -42,10 +46,27 @@ dependencies = [ # # Nothing to read by hand: the three files are `version-only`, and the # closure is the same with `tests/` as a root. The dynamic imports are the - # same two as at 0.44.0. Outside the closure, 0.45.0 changed eight co/v1 - # adapter modules, `pure/models/link.py` and `co_core_sync/services/`'s - # `event.py` and `transcript.py`, and added or removed no module. Nothing in - # `src/`, `scripts/` or `tests/` reaches any of them. + # same two as at 0.45.0. The soupsieve change is under `[extract]`, and + # soupsieve is not in `uv.lock`. Outside the closure, 0.46.x changed + # `pure/adapters/co_v1/`'s `event.py` and `responses.py`, + # `pure/models/link.py` (docstring) and `co_core_sync/services/event.py` + # (docstring), and added or removed no module. Nothing in `src/`, + # `scripts/` or `tests/` reaches any of them. + # + # Previously: + # + # Floor was 0.45.0, and it carried no new feature: a one-minor catch-up + # (#192), in #184's shape. 0.45.0's one library change was co/v1's + # `EventModel.url`, which read the Event's `website` link and fell back to + # its `event_url` link, and a malformed `links` embed began raising + # `CoV1ResponseAnomaly` (cannobserv#663). Both sat outside this closure. + # + # **Diffing the closure, 0.44.0 → 0.45.0** (58 files, both sides): 3 not + # identical, all `version-only`; Requires-Dist moved only the aio/sync + # `co-core` bound. Outside the closure, 0.45.0 changed eight co/v1 adapter + # modules, `pure/models/link.py` and `co_core_sync/services/`'s `event.py` + # and `transcript.py`. Nothing in `src/`, `scripts/` or `tests/` reached any + # of them. # # Previously: # @@ -423,9 +444,9 @@ dependencies = [ # at module load, so a skew cannot reach a running worker at all. Additive over # 0.8.0 for everything the fetch path uses — no field on ContentFetchCommand, # BlobAvailableEvent or FetchFailedEvent moved between the two. - "co-core>=0.45.0,<0.46", - "co-core-aio[bus,gcs]>=0.45.0,<0.46", - "co-core-sync[gcs]>=0.45.0,<0.46", + "co-core>=0.46.0,<0.47", + "co-core-aio[bus,gcs]>=0.46.0,<0.47", + "co-core-sync[gcs]>=0.46.0,<0.47", "fastapi>=0.126.0,<1", "pydantic>=2.9,<3", "pydantic-settings>=2.5.0,<3", diff --git a/tests/test_dependency_index.py b/tests/test_dependency_index.py index a317ff7..17a1cb3 100644 --- a/tests/test_dependency_index.py +++ b/tests/test_dependency_index.py @@ -60,7 +60,7 @@ def test_every_file_from_the_index_is_hashed_and_there_is_a_wheel(): def test_the_locked_versions_sit_inside_the_pin(): - """The index lists nothing past 0.45.0 [measured 2026-11-13, #192]; the pin's + """The index lists nothing past 0.46.1 [measured 2026-11-14, #199]; the pin's upper bound keeps the next minor out until the change that moves it.""" pins = { (r := Requirement(spec)).name: r.specifier @@ -69,7 +69,7 @@ def test_the_locked_versions_sit_inside_the_pin(): } for package in _from_index(): assert package["version"] in pins[package["name"]], package - assert package["version"] not in SpecifierSet(">=0.46"), package + assert package["version"] not in SpecifierSet(">=0.47"), package def test_no_other_source_kind_names_a_wheelhouse(): diff --git a/uv.lock b/uv.lock index 4cd42e7..5970dc9 100644 --- a/uv.lock +++ b/uv.lock @@ -285,28 +285,28 @@ wheels = [ [[package]] name = "co-core" -version = "0.45.0" +version = "0.46.1" source = { registry = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/simple/" } dependencies = [ { name = "dateparser" }, { name = "pydantic" }, ] -sdist = { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core/co_core-0.45.0.tar.gz", hash = "sha256:4fad480d2926be2ddae20cc0f9c79f85a0bd4b6fc2721ba203eacd238a97ddd7" } +sdist = { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core/co_core-0.46.1.tar.gz", hash = "sha256:b54608c1a52b2d7fd2317efb40111d4d20e30490703404c654fd14692f6f9e20" } wheels = [ - { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core/co_core-0.45.0-py3-none-any.whl", hash = "sha256:ecf7fcf79675054c93e0194d98c35674171fc2e1a4600a69f7db0274f6145354" }, + { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core/co_core-0.46.1-py3-none-any.whl", hash = "sha256:70848e808df30bacb74b2d7a0627cb44c85e151b0c7521e5338d89e502b9891d" }, ] [[package]] name = "co-core-aio" -version = "0.45.0" +version = "0.46.1" source = { registry = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/simple/" } dependencies = [ { name = "co-core" }, { name = "httpx" }, ] -sdist = { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core-aio/co_core_aio-0.45.0.tar.gz", hash = "sha256:9d099122563e4c957e5ccf4090bbda0d2b11831cf6a62e904f37d4962309e306" } +sdist = { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core-aio/co_core_aio-0.46.1.tar.gz", hash = "sha256:217a3628dd87342c3164ab4c0bcea1ed58fa49796456181593d54ff4e43c1e0b" } wheels = [ - { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core-aio/co_core_aio-0.45.0-py3-none-any.whl", hash = "sha256:a876e948d20c13d025cef7f1fd8fab2a23ed299167bcae9681aaeaf395f2b3e8" }, + { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core-aio/co_core_aio-0.46.1-py3-none-any.whl", hash = "sha256:d732f301bcd0cf7fb0f072a49f16915785fd804b2dda9fc2892e496d7014dc16" }, ] [package.optional-dependencies] @@ -320,16 +320,16 @@ gcs = [ [[package]] name = "co-core-sync" -version = "0.45.0" +version = "0.46.1" source = { registry = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/simple/" } dependencies = [ { name = "co-core" }, { name = "requests" }, { name = "urllib3" }, ] -sdist = { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core-sync/co_core_sync-0.45.0.tar.gz", hash = "sha256:2c234ef7c9e34c01451a07829a9caa179e54e6585fd4f42ebfc7de9dae8feabb" } +sdist = { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core-sync/co_core_sync-0.46.1.tar.gz", hash = "sha256:4f9eafefaf96e68f3c5c5c566b1911be841e53317ee41e5e1290c74db8f948b9" } wheels = [ - { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core-sync/co_core_sync-0.45.0-py3-none-any.whl", hash = "sha256:9abce3edc7f5102f91219bafce070f3b8c9a36986e9276d82d39b436aafa62b7" }, + { url = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/co-core-sync/co_core_sync-0.46.1-py3-none-any.whl", hash = "sha256:f61930a1655b530fad4352756c06252c1234c08ddbd7268f1aa6a87e198be8a9" }, ] [package.optional-dependencies] @@ -1346,9 +1346,9 @@ dev = [ [package.metadata] requires-dist = [ - { name = "co-core", specifier = ">=0.45.0,<0.46", index = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/simple/" }, - { name = "co-core-aio", extras = ["bus", "gcs"], specifier = ">=0.45.0,<0.46", index = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/simple/" }, - { name = "co-core-sync", extras = ["gcs"], specifier = ">=0.45.0,<0.46", index = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/simple/" }, + { name = "co-core", specifier = ">=0.46.0,<0.47", index = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/simple/" }, + { name = "co-core-aio", extras = ["bus", "gcs"], specifier = ">=0.46.0,<0.47", index = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/simple/" }, + { name = "co-core-sync", extras = ["gcs"], specifier = ">=0.46.0,<0.47", index = "https://us-west1-python.pkg.dev/co-gcs/co-pypi/simple/" }, { name = "fastapi", specifier = ">=0.126.0,<1" }, { name = "playwright", specifier = "==1.64.1" }, { name = "pydantic", specifier = ">=2.9,<3" },