Skip to content

docs(protocol): lifecycle wire contract v2 + Python goldens for refresh/cancel/replace (#101, 1/2) - #107

Merged
AetherAI3 merged 3 commits into
mainfrom
claude/nano101-lifecycle-wire-v2
Nov 8, 2026
Merged

AetherAI3 merged 3 commits into
mainfrom
claude/nano101-lifecycle-wire-v2

Conversation

@AetherAI3

Copy link
Copy Markdown
Owner

Summary

Publishes nano.qsearch.lifecycle-wire.v2, an additive contract that lets non-Python hosts use the existing explicit refresh / cancel / replace controls. It comes with golden fixtures generated by the real service and Python client, using fake providers only. v1 (status) and its files are unchanged, and the service, lifecycle and client code are untouched. PR 1 of 2 for #101; the TypeScript client (PR 2) stacks on this branch.

Key Changes

  • Frozen v2 contract — Specifies a caller-chosen capability set, POST framing, and that replace must bind both the descriptor digest and lineage. A lost acknowledgement means "observe", and a cancel response is not cancellation.
  • Python-exact canonical replacement bytes — Specifies code-point key order, number kind taken from the lexeme, and repr floats. Every rule was checked against nano_qsearch.canonical before freezing.
  • Goldens from real code paths — 15 canonical vectors with 21 refusals, signing for every control, 8 control histories (including cancel raced by completion), 18 real service errors and 18 negatives.
  • Recorded Python gaps — 7 strict xfails: Python's replace takes an already-parsed Mapping (so duplicates and depth are the caller's), and Python has no capability set.

Verification

  • New v2 test file: 189 passed, 7 xfailed (strict), 0 skipped. regen.py --check and SHA256SUMS pass, and v1 files and sums are byte-identical.
  • v1 contract and lifecycle group green. Conformance: 55/55 on a clean archive of this head. In the local worktree, one release test fails only because of a git-ignored .ruff_cache that is not in CI.
  • Full suite, one file at a time (agent, pre-rebase): 3616 passed. The 4 failures are pre-existing on base (j6_a2 ×2, quantum_prepare) or that local cache.

🤖 Generated with Claude Code

AetherAI3 and others added 3 commits November 8, 2026 07:27
…ancel/replace)

Additive to v1 (status unchanged, v1 files untouched): explicit capability
set, POST framing and headers, Python-exact canonical replacement bytes
(code-point key order, lexeme-kind numbers, repr floats), replace binding to
the descriptor digest plus lineage, lost-acknowledgement semantics and the
rule that a cancel response is not cancellation. Canonicalisation claims were
checked against nano_qsearch.canonical before freezing.

Refs #101

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

Add fixtures/regen.py and the five v2 fixture files (canonical replacement
bytes, control signing, control histories, control errors, control
negatives) produced from the real Python service and client with injected
clocks, synthetic keys and a fake provider adapter, plus SHA256SUMS over
every v2 file.

tests/test_qsearch_lifecycle_wire_v2.py checks regen --check, the sums,
wire.v2.json against the Python constants, every vector against an
independent reference reader and canonicaliser, one transport call per
control, POST transport failure as MANUAL_RECONCILIATION, and v1
byte identity. Python discrepancies are strict xfails: duplicate members
and depth 65 in replacement text, and the missing capability set.

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

The v1 contract leaves 'field' unspecified for INVALID_RESPONSE (a client may
report null or a static schema path) and v1 negatives never pin it. The v2
negatives pinned Python's null on all 15 such cases, which over-specified the
contract and failed the TypeScript client on a schema-invalid replace body.
Negatives now carry only the mandated keys; comparisons check those keys.

Refs #101

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@AetherAI3
AetherAI3 merged commit 31b30df into main Nov 8, 2026
9 of 11 checks passed
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