Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .socraticodecontextartifacts.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

<!-- BEGIN socraticode-policy -->
## Code Exploration Policy
Expand Down
4 changes: 2 additions & 2 deletions docs/DEPENDENCIES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
67 changes: 44 additions & 23 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,33 +7,37 @@ 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
# - `version-only` co_core_sync/__init__.py
#
# **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:**
#
Expand All @@ -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:
#
Expand Down Expand Up @@ -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",
Expand Down
4 changes: 2 additions & 2 deletions tests/test_dependency_index.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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():
Expand Down
24 changes: 12 additions & 12 deletions uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.