Skip to content

Document exact pins versus floating dependencies - #106

Merged
CompleteDotTech merged 2 commits into
mainfrom
docs/50-dependency-pins
Nov 13, 2026
Merged

CompleteDotTech merged 2 commits into
mainfrom
docs/50-dependency-pins

Conversation

@CompleteDotTech

@CompleteDotTech CompleteDotTech commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem

README.md and docs/INTEGRATIONS.md said the pins are "not a fully resolved dependency lock" but never said which requirements are exact and which float, or which tracked files are locks.

Change

  • docs/INTEGRATIONS.md: new "Pinned and floating dependencies" section.
    • It states that the Python package has no current resolved lock and that the tables cover Python requirements only.
    • It names the two tracked lock-like files and their scope. examples/ai-gateway/package-lock.json is a real npm lock (lockfileVersion 3, integrity hashes) for the optional Node gateway smoke only, with ai pinned at 7.0.114 in package.json. reports/resolved-lock-windows-py313.txt is a stale historical pip freeze (2026-09-19, CPython 3.13.13 on Windows, old systemone-compiler name, dspy==3.3.1), not maintained and not authoritative. That file is not modified.
    • It lists the exact Python pins (typesafe-sdk==0.7.0, dspy[typesafe]==3.4.0, dspy[litellm,typesafe]==3.4.0, gepa==0.1.4), every bounded range from pyproject.toml and examples/ai-gateway/requirements.txt, and the [build-system] bounds.
    • It explains that transitive packages are unpinned and unhashed, and that CI resolves fresh on every run.
  • README.md: the existing sentence now names the exact Python pins, says the Python package has no current resolved lock, names the npm lock and the stale freeze, and links to the new section.
  • tests/test_packaging_metadata.py: four new tests, all deriving expectations from the declared files rather than from the doc.
    • Every pyproject and gateway requirement must appear in the correct table, its "Declared in" cell must match the exact set of extras (or base dependencies, or the gateway file), and the tables may not list anything undeclared.
    • The build-system sentence must match [build-system].requires.
    • Every examples/ai-gateway/package.json dependency must be an exact pin that the section names.
    • The test walks the source tree, skipping .git, venvs, node_modules, runs, .claude, caches, build output, and other ignored directories. It looks for lock-like names (package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock, uv.lock, Pipfile.lock, pdm.lock, *.lock, *lock*.txt, *lock*.toml, constraints*.txt, *freeze*.txt, and so on) and requires each one found to be named in the section.
  • CHANGELOG.md entry; refreshed MANIFEST.sha256 entries for README.md, docs/INTEGRATIONS.md and tests/test_packaging_metadata.py only.

No lock was generated. Nothing about dependency resolution was verified beyond reading the declared files.

Validation (local, Python 3.14.8, dspy/gepa/typesafe-sdk absent)

  • Rebased onto origin/main 3859256 (Validate gateway destinations before credentialed dispatch #98); CHANGELOG conflict resolved by keeping both entries.
  • pytest -q: 741 passed, 79 skipped on the rebased head (this PR adds 4 tests in tests/test_packaging_metadata.py; skips unchanged; before the rebase onto 3859256: 610 passed vs 606 baseline on 6532cc8)
  • ruff check src tests examples: clean
  • Mutation checks, each reverted afterwards. Dropping optimize from the gepa==0.1.4 row, dropping wheel from the build-system sentence, and removing the backticked freeze path from the section each made the corresponding test fail.
  • The three refreshed MANIFEST entries pass sha256sum -c. A full sha256sum -c MANIFEST.sha256 already fails on origin/main (pre-existing stale entries plus missing src/s1compiler/... paths from the rename). This PR does not touch those entries; they need a separate refresh.

Not executed

No live, paid, or hosted-provider calls. No npm ci or Node smoke run. No optional SDK integration tests locally (SDKs absent; skips preserved).

Refs #50

🤖 Generated with Claude Code

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T02:59:04.639737Z 701169d New commits
🔒 Security Review ✅ Completed 2026-11-13T02:49:01.833437Z 7e6a64e PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@CompleteDotTech

Copy link
Copy Markdown
Contributor Author

Fresh-context review (round 1) of head 7e6a64e

Local results (Python 3.14.8, dspy/gepa/typesafe-sdk absent)

  • pytest -q: 608 passed, 79 skipped (baseline on 6532cc8: 606 passed, 79 skipped; +2 new tests, skips unchanged)
  • ruff check src tests examples: clean
  • sha256sum -c on the three refreshed MANIFEST entries (README.md, docs/INTEGRATIONS.md, tests/test_packaging_metadata.py): all OK

The Python dependency tables match pyproject.toml and examples/ai-gateway/requirements.txt exactly, and the CI description matches .github/workflows/ci.yml. There are no code, schema, or import-boundary changes.

Findings

BLOCKING: docs/INTEGRATIONS.md:22 says "There is no lock file in this repository", but the repo tracks two

  • examples/ai-gateway/package-lock.json (lockfileVersion 3, with resolved URLs and integrity sha512 hashes for every package), plus examples/ai-gateway/package.json, which pins "ai": "7.0.114" exactly. examples/ai-gateway/README.md:87 tells users to run npm ci against it.
  • reports/resolved-lock-windows-py313.txt, titled "Resolved dependency lock", a 97-line pip freeze from 2026-09-19. It is scoped to Win/CPython 3.13.13 and dspy==3.3.1, uses the old systemone-compiler name, and is listed in MANIFEST.sha256:40.

The section also says "nothing is hashed" (line 24), which the npm lock contradicts. README.md:148-151 ("Only typesafe-sdk, gepa, and DSPy ... are exact pins; everything else ... floats") leaves out the exact npm ai pin and its locked transitive tree. CHANGELOG.md:6 repeats "no lock file". The PR's purpose is an honest account of what is pinned and what floats, so a false absolute claim defeats it. Scenario: a reader who trusts the new section doesn't know the gateway's Node smoke path is fully locked and hashed. They also don't know a stale Windows-only Python freeze is shipped and might be mistaken for authoritative, or for one this PR says doesn't exist.

Fix: scope the claim to the Python package, for example "no lock file for the Python package". Name package-lock.json as the only real lock, covering the Node gateway smoke only. Name reports/resolved-lock-windows-py313.txt as a historical, platform-scoped freeze that is not maintained and does not match current pins (DSPy 3.4.0 in compile/all, package rename). Also list ai@7.0.114 under the exact pins, or say outright that the table covers Python only.

BLOCKING: tests/test_packaging_metadata.py:90-94, the lock-absence test checks only the repo root, so it passes while the doc claim is false

test_dependency_doc_matches_absence_of_lock_file looks for seven filenames under ROOT and nothing else. It never sees examples/ai-gateway/package-lock.json or reports/resolved-lock-windows-py313.txt, so it asserts "no lock file" while two tracked locks exist. It is a regression test for the claim, and the claim is wrong today. Fix: walk the tracked tree (git ls-files, or rglob with exclusions for .venv/.git) for lock-like names (*.lock, package-lock.json, pnpm-lock.yaml, yarn.lock, *lock*.txt, pylock*.toml). Assert that each one found is named in the section, instead of asserting a blanket "no lock file" phrase.

NIT: tests/test_packaging_metadata.py:84-87 doesn't check the "Declared in" column or the build-system requirements

The test finds the requirement string in the correct table. If a pin moves between extras, though (for example gepa==0.1.4 dropped from optimize), the "Declared in" cell goes stale and the test still passes. The setuptools>=77/wheel sentence (INTEGRATIONS.md:50-51) isn't tied to [build-system].requires either. Low risk; checking (requirement, extra) pairs would cover it.

No issues found with the import boundary, source contract, split isolation, budgets or identity checks, eval/exec/pickle, credentials, or synthetic-result labeling. The PR touches none of them.

@CompleteDotTech

Copy link
Copy Markdown
Contributor Author

Round 1 findings addressed in 513736c (rebased on current origin/main, 6532cc8):

  • BLOCKING 1 (false "no lock file" / "nothing is hashed"): fixed. I confirmed both files are tracked: examples/ai-gateway/package-lock.json (lockfileVersion 3, ai 7.0.114 with sha512 integrity) and reports/resolved-lock-windows-py313.txt (2026-09-19 Win/CPython 3.13.13 freeze, systemone-compiler, dspy==3.3.1). The section now says the Python package has no current resolved lock, that no Python requirement is hashed, and that the tables cover Python only. It names the npm lock and the ai@7.0.114 pin, scoped to the Node gateway smoke, and names the freeze as stale, historical, unmaintained, and not authoritative. README and CHANGELOG are scoped the same way. The freeze file is unchanged.
  • BLOCKING 2 (root-only lock test): fixed. The suite doesn't use git anywhere else, so test_dependency_doc_names_every_lock_like_file_in_the_tree walks the source tree with rglob instead. It skips .git, venvs, node_modules, runs, .claude, caches, build/dist, and *.egg-info, which keeps untracked local files in those directories from affecting it. It matches lock-like names and patterns and asserts that each match is named in the section. It also asserts that the scan reaches the nested package-lock.json, so a broken walk can't pass silently. A separate test requires every package.json dependency to be an exact pin that the section names.
  • NIT ("Declared in" / build-system): fixed. The table test now compares each row's "Declared in" cell with the exact set of extras from pyproject (or base dependencies, or the gateway file), and fails if a table lists an undeclared requirement. A new test ties the build-system sentence to [build-system].requires.

I mutation-checked the tests, reverting each change afterwards. Moving gepa==0.1.4 out of optimize, dropping wheel, and unnaming the freeze each failed the right test. Local results: pytest 610 passed, 79 skipped (baseline 606/79); ruff is clean; the three refreshed MANIFEST entries pass sha256sum -c.

CompleteDotTech and others added 2 commits November 12, 2026 21:56
List every exact pin and bounded range declared in pyproject.toml and the
gateway example requirements, state that transitive packages are unpinned and
unhashed, that CI resolves fresh on every run, and that no lock file exists.
Link the section from the README and add a regression test that derives the
expected list from pyproject.toml. Refresh the three touched MANIFEST entries.

Refs #50

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The dependency section said the repository has no lock file, but it tracks
the npm lock for the Node gateway smoke (ai pinned at 7.0.114, integrity
hashes) and a stale Windows/CPython 3.13 pip freeze in reports/. Scope the
claim to the Python package, name both files with their scope, and mark
the freeze as historical and not authoritative.

The lock test now walks the source tree (skipping ignored and local-only
directories) for lock-like names and requires each to be named in the
section. The table test also checks the Declared in column against
pyproject extras, and a new test ties the build-system sentence to
[build-system].requires and the npm pins to package.json.

Refs #50

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@CompleteDotTech

Copy link
Copy Markdown
Contributor Author

Rebased onto origin/main 3859256 (#98). I resolved the CHANGELOG conflict by keeping both entries, so the new head is 701169d. Content is unchanged from 513736c. Local results: pytest 741 passed, 79 skipped; ruff is clean; the three refreshed MANIFEST entries are OK.

@CompleteDotTech

Copy link
Copy Markdown
Contributor Author

Fresh-context review (round 2) of head 701169d

Scope: #50, "dependency honesty" item only. I read the diff, pyproject.toml, examples/ai-gateway/{requirements.txt,package.json,package-lock.json}, reports/resolved-lock-windows-py313.txt, and .github/workflows/ci.yml, and I checked out the head locally.

Validation (local, Python 3.14.8, dspy/gepa/typesafe-sdk/numpy absent)

  • pytest -q: 741 passed, 79 skipped. Baseline on origin/main 3859256 is 737 passed, 79 skipped, so the difference is exactly the 4 new tests and the skips are unchanged.
  • ruff check src tests examples: clean.
  • The three refreshed MANIFEST entries (README.md, docs/INTEGRATIONS.md, tests/test_packaging_metadata.py) match sha256sum. No other entries were touched. The stale entries tracked in MANIFEST.sha256 is stale on main: 32 hash mismatches, 29 pre-rename paths #108 are out of scope.
  • I checked each doc claim against its source:
    • The exact pins and ranges, and every "Declared in" cell, match pyproject.toml and the gateway requirements.
    • The build-system sentence matches [build-system].requires.
    • package-lock.json is lockfileVersion 3, all 11 packages have a resolved URL and a sha512 integrity hash, and ai is 7.0.114.
    • The freeze header says 2026-09-19, CPython 3.13.13, Windows 11 win_amd64, pip install -e ".[all,dev]", systemone-compiler and dspy==3.3.1.
    • The CI install steps match the workflow, apart from the omission noted below.
  • Tracked lock-like files are only examples/ai-gateway/package-lock.json and reports/resolved-lock-windows-py313.txt. Both are named. No lock was generated, and no file other than the docs, the test, the CHANGELOG and the MANIFEST changed.
  • Every new test takes its expectations from the declared files, not from the doc. None recomputes its expectation with the code under test.
  • No source, schema, fixture or artifact changes, so the import boundary and runtime invariants are unaffected.

Findings

  1. NIT, docs/INTEGRATIONS.md:74-76: the CI description says the optional job "installs .[all,dev] and then reinstalls dspy[litellm]==<matrix version> and gepa==0.1.4". The optional job also installs examples/ai-gateway/requirements.txt (.github/workflows/ci.yml:59). Someone reproducing the optional CI environment from the doc would leave out httpx and python-dotenv. Nothing in the doc is false, only incomplete.
  2. NIT, docs/INTEGRATIONS.md:51: "float to the newest release inside the range at install time" is not quite how pip behaves. pip keeps an already-installed version that satisfies the range, and the resolver can pick an older one to satisfy other constraints. For example, pip install -e . into an env that already has pydantic 2.10 keeps 2.10. Suggested wording: "resolve to whatever version inside the range the installer picks (usually the newest)".
  3. NIT, tests/test_packaging_metadata.py:117: the table test checks only that each requirement is in its correct table and that the union of both tables equals the declared set. A requirement listed in both tables still passes. For example, adding | `gepa==0.1.4` | `optimize`, `all` extras | to the Bounded ranges table would wrongly present an exact pin as floating, and the test would not catch it. assert not set(exact_rows) & set(range_rows) would close the gap.
  4. NIT, tests/test_packaging_metadata.py:148: _lock_like_files walks the filesystem rather than tracked files, so the test result depends on untracked local files outside SKIP_DIRS. For example, a developer's untracked constraints.txt at the repo root fails the test. This is arguably intended, since it errs toward naming every lock, and the coordinator checkout currently has no extra matches. rglob also still descends into skipped directories before filtering them out. That costs time in a checkout with a large .venv or runs/, but the result is still correct.

The dependency-honesty acceptance item is met. The docs say which Python requirements are exact pins and which float, that transitive packages float and are unhashed, and that CI resolves fresh on every run. They also name the real npm lock and the stale freeze with their scope, and no lock was fabricated. This PR does not address the other #50 items (CI, branch protection, stale branches), which is consistent with Refs #50.

REVIEW CLEAN

@CompleteDotTech

Copy link
Copy Markdown
Contributor Author

Coordinator: approved for merge on head 701169d. Review round 2 posted REVIEW CLEAN. Round 1 found 2 BLOCKING items (the false 'no lock file' claim and a lock test that only checked the repo root), and both were fixed in this head. All 10 hosted checks pass on this exact head.

Round-2 NITs are left as noted, not fixed, because fixing them would move the head and need another review round:

  1. docs/INTEGRATIONS.md:74-76: the CI description leaves out that optional-contracts also installs examples/ai-gateway/requirements.txt.
  2. docs/INTEGRATIONS.md:51: 'float to the newest release' overstates what pip does; it keeps an installed version that already fits the range.
  3. tests/test_packaging_metadata.py:117: nothing asserts that the exact-pin and range tables don't overlap.
  4. tests/test_packaging_metadata.py:148: the lock scan walks the filesystem rather than tracked files, so an untracked root constraints.txt would fail it.

@CompleteDotTech
CompleteDotTech merged commit 43903f0 into main Nov 13, 2026
10 checks passed
@CompleteDotTech
CompleteDotTech deleted the docs/50-dependency-pins branch November 13, 2026 03:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant