Pre-freeze: normative completeness + enforcement + host conformance (top-10 build) - #60
Merged
Merged
Conversation
…#13) Fold every shipped wire surface into SPEC.md, the single normative home, and restore the consent-scopes text a prior merge dropped. - §9 Verification (verify/verified, V1-V4) - §6.3 Frame identity (D1-D4); §6.4 Representations (P1-P5) - §6.4.1: context/resolve scoped OUT of 1.0 (deferred to a 1.x additive minor; docs/sketches/resolve.md). Remote providers should not emit un-rehydratable reference frames — closes the dead-capability surface (#50). - §4.1 egress scopes + consent receipts (C5-C6); restored context-reuse.md §3 (recovered from d229ed9, the text the #38 merge destroyed) - §4.2 transport security: C7 (TLS for non-loopback), C8 (no credential logging) (#13) - §13 Extensibility: U1-U4 (ignore-unknown, closed FrameKind / open vocabularies, reserved : namespaces, no-repurpose/deprecation) — schema is authoring-strict, U1 is the interop contract (#48) - §10 error codes: unsupported_representation, incompatible_version No wire-shape change: documents surfaces the schema and reference types already carry. Schema examples validate; contextgraph-conformance green. Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
…half) additionalProperties:false stays as an authoring/CI lint; the interop contract is SPEC.md §13 U1 (receivers MUST ignore unknown members). No behavioral change, so downstream drift gates that pin this schema keep working. Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
Frame the CEP profile that layers the deferred write-path (#5), resolve (#50), retention, and attestation on top of core contextgraph/1.0 — the concrete path to a second independent implementation (freeze criterion 1). Summarizes the in-progress Oxagen reference implementation and marks every unresolved contract decision [OPEN]. Explicitly a draft skeleton, not a normative profile. Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.
Please try again later or upgrade to continue using Sourcery
…rity to SPEC.md (#49, #21) - Fix stale capability structs: drop removed upsert/subscribe/filters, add the shipped correlation/representations/resolve; relabel DataFlow.writes as the consent-surface declaration ADR 0004 made it; add representation_preferences. - Reconcile the triple-claimed authority: protocol-surface.md's conformance table is now an index that MIRRORS SPEC.md (normative on conflict); GOVERNANCE points at SPEC.md as the conformance home. Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
Remove the dangling RELEASING.md link and stella write-access / tag-namespace references — this repo publishes the three crates independently. Crate metadata verified publish-ready (contextgraph-types `cargo publish --dry-run` packages clean). NOT published and NOT tagged here: that is an irreversible, rights-gated step for a maintainer to run from this checklist. Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
Four enforcement gaps the shipped surface opened, each with an adversarial witness (conformance-red.sh: all 17 misbehave modes caught). - P1-P3 representation invariants: check_frames now calls representation_invariants() on every frame; witness `lying-representation` (reference frame with inline content). - F4 as_of probe: new `as-of-temporal` check fires an as_of-pinned query and fails frames whose valid_from is after the pin; fixture frames given disjoint validity windows; witness `ignore-as-of`. - B4 host-side max_frames audit: ProviderResult::FrameFlood, respects_frame_limit, frame_floods() — drops the leg loudly, symmetric to the B2 budget-lie drop. - E1 embedding fingerprint: reference provider declares a fingerprint and replies bad_request to a wrong-dimension vector; new stdio raw-wire `embedding-fingerprint` check; witness `accept-bad-embedding`. Documented stdio-only limitation. cargo test -p contextgraph-conformance -p contextgraph-host green (13 + 71); cargo test --workspace green; conformance-red.sh: "All misbehaviour modes caught." Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
The remaining half of F5: the provider-facing suite checks digest grammar; a
host re-reads the source bytes and checks they hash to the declared digest.
- contextgraph-host/src/verify.rs: verify_provenance_digest / verify_file_provenance
returning DigestVerification { Verified | Mismatch{expected,actual} |
Unreadable{reason} | NotFileProvenance }. Reads the exact bytes addressed by
uri+range per SPEC §6.2 — no normalization (no line-ending translation, no \r
strip, no trailing-newline adjustment); no range = whole resource; line ranges
L<s>-<e> inclusive; unknown range grammar => Unreadable (never silent fallback);
file:// only, percent-decoded, non-local host rejected.
- 11 tests incl. known-answer sha256 vectors (interop, not just self-consistency),
CRLF no-normalization, sub-range, missing file.
- Deliberately NOT auto-wired into query_all: re-reading a provider-named uri is a
confinement/consent decision left to the host-side harness (#14). SPEC §11.1 updated.
cargo test -p contextgraph-host green (82); cargo fmt clean.
Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
The golden set downstream consumers copy + drift-gate predated #33/#41. - Fix B3 dishonesty flagged in the issue: context-frame.valid.json declared token_cost 42 (content is 49 bytes => ceil(49/4)=13) and 0 (39 bytes => 10). Corrected; the golden test never caught it because it runs check_frames, not check_budget. Regenerated the embedded JCS + per-case sha256. - Add representation goldens: context-frame.compact.valid.json (all 5 required fields, B3-honest token_cost 28) and context-frame.reference.valid.json (no inline content, token_cost 0). Real sha256 digests over the actual bytes. - Regenerate manifest.json (7 entries, correct on-disk hashes). - golden_fixtures.rs: extend FIXTURE_FILES 5->7 and add a test asserting the two vectors satisfy representation_invariants + B3. Note: FRAME_FIELDS strict allow-list excludes content_digest by a pre-existing comment, so compact frames can't pass strict_frame; representation vectors are validated as real ContextFrames instead. Whether to widen that frozen allow-list is left for the maintainer. cargo test -p contextgraph-conformance green (golden_fixtures 8); workspace green. Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
…nings gate (#51) The #51 misbehave dispatch used nested `if cond { if let Some(x) = .. }`, which `cargo clippy --workspace --all-targets -- -D warnings` (CI's gate) flags as collapsible_if under MSRV 1.90 (let-chains stable since 1.88). Collapsed to `if cond && let Some(x) = ..`; behavior-preserving (identical short-circuit, no else). conformance-red.sh re-run: all misbehave modes still caught. Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
…is checkable (#14) Makes GOVERNANCE freeze criterion 4 real for the host-binding rules. Drives the reference host against adversarial in-process providers (the host-side analog of --misbehave), each check asserting the host CATCHES a bad provider AND ACCEPTS a good one (non-vacuous in both directions). - host-budget-drop (B2): over-budget frames dropped-with-report. - host-frame-limit (B4): >max_frames flood dropped-with-report. - host-consent-gate (C1/C2): unconsented egress refused; ProbeProvider's queried flag proves the payload was never transmitted; queried+accepted after consent. - host-scope-receipt (C6): unreceipted off-machine scope refused with the typed scope error, payload not transmitted; accepted after a receipt. - host-provenance-bytes (F5-bytes): wires #12's verify_file_provenance over a harness-owned temp file; tampered digest caught as Mismatch, matching Verified. - host-content-quoting (R3): content fenced as quoted material. Honestly scoped: checks the delimiting contract, NOT breakout-resistance (issue #15). Surfaced via `contextgraph-inspect host [--json]` and .github/scripts/host-conformance.sh (host-side red-detection analog), wired into CI. SPEC §11.1 rewritten: B2/B4/C1/C2/ C6/F5-bytes/R3-delimiting now checked; honest residual = C4/C7/C8 transport (need a TLS/network peer), R3-breakout (#15), F5 provider-path confinement. cargo clippy --workspace --all-targets -D warnings clean; cargo test --workspace green (21 groups); host-conformance.sh: all 6 PASS; conformance-red.sh: all caught. Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
macanderson
changed the title
macanderson
marked this pull request as ready for review
July 24, 2026 01:01
…s in example providers (#51) The new embedding-fingerprint (§E1) conformance check skips a provider that declares no fingerprint, and conformance-external.sh (like conformance-green.sh) treats a skip as non-conformant — a deliberate, symmetric "every check green, none skipped" bar. #51 updated the Rust reference provider to declare a fingerprint and reject wrong-dimension embeddings; the three SDK example providers now mirror it so they pass the same bar (rather than relaxing it). - Each example provider declares embeddings_fingerprint "bge-small-en-v1.5/384/l2" and replies error{code: bad_request} to a query embedding whose length != 384. - Small runtime additions so an example can signal a coded protocol error: Python ProviderError, Go ProviderError + (result, error) Query signature + the missing ContextQuery.Embedding field, TypeScript ProviderError. Verified locally against the real CI steps: python / go (vet+build) / ts (tsc) each `All 9 checks passed — external provider is conformant`, embedding-fingerprint OK. Claude-Session: https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw
macanderson
enabled auto-merge (squash)
July 24, 2026 01:03
macanderson
disabled auto-merge
July 24, 2026 01:03
There was a problem hiding this comment.
Sorry @macanderson, your pull request is larger than the review limit of 150000 diff characters
This was referenced Jul 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pre-freeze normative + enforcement work (top-10 build)
Builds the pre-freeze top-10 triaged on issue #22. The audit found most of the
original normative backlog already landed on main (PRs #33/#38/#41), so the
real freeze-blocking work was largely untracked — filed as #48–#52 and built
here. Sequenced by "breaking or impossible if deferred past the freeze."
All green:
cargo clippy --workspace --all-targets -D warningsclean ·cargo test --workspace(21 groups, 0 failed) ·conformance-green·conformance-red(all 17 misbehave modes caught) ·host-conformance(all 6) ·schema examples validate.
Normative completeness — SPEC.md is the true single normative home (#49, #50, #48, #13)
verify/verified, V1–V4); §6.3 Frame identity (D1–D4); §6.4 Representations (P1–P5).context/resolvescoped OUT of 1.0 — grep proved stella usesfullonly andcontent_ref.urihas zero consumers; resolve deferred to a1.xadditive minor (docs/sketches/resolve.md), remote providers told not to emit un-rehydratablereferenceframes. Closes the dead-capability surface (Decide context/resolve before the freeze: specify it or cut reference representations — and define B3 for compact/reference frames #50).docs/context-reuse.md§3 destroyed by the feat: context/verify — pull-based frame revalidation #38 merge (recovered fromd229ed9).unsupported_representation,incompatible_version.Enforcement — closing GOVERNANCE freeze criterion 4
lying-representation),as_ofprobe (ignore-as-of), host-sidemax_framesaudit (FrameFlood), E1 fingerprint witness (accept-bad-embedding) — each caught by exactly its intended check.contextgraph_host::verifyre-reads the exact bytes afileprovenance addresses (§6.2: no normalization, range-aware) and checks they hash to the declared digest — the byte-truth half of F5. 11 tests incl. known-answer sha256 vectors.contextgraph-inspect host+host-conformance.sh, wired into CI. §11.1 honestly narrowed the residual to C4/C7/C8 transport and R3-breakout (P2: Reference prompt-composition module: global budget, cross-provider dedup, injection-resistant rendering #15).Ecosystem / release
cargo publish --dry-runpasses). Not published, not tagged — that irreversible, rights-gated step is left as a checklist for a maintainer.Deliberately out of scope (left for the maintainer)
cargo publish+ the1.0.0/version-tag bump (P1: Release: pick the version and publish the three crates to crates.io #16) — irreversible, needs publish rights.FRAME_FIELDSstrict allow-list to admitcontent_digest(a compact frame can't passstrict_frame) — flagged in P1: Cut the attested fixture bundle tag for downstreams (regeneration shipped in #60) #52's commit; a semantic change to a pinned profile.Closes #48, #49, #50, #12, #51, #52. Advances #13, #14, #21, #28. Related: #16, #30.
https://claude.ai/code/session_01NGCCkBsqCdJiNvFBHQKgyw