Skip to content

Backlog sweep: clear the buildable pre-freeze backlog (18 issues) - #69

Merged
macanderson merged 17 commits into
mainfrom
chore/backlog-sweep-2026-07
Aug 1, 2026
Merged

Backlog sweep: clear the buildable pre-freeze backlog (18 issues)#69
macanderson merged 17 commits into
mainfrom
chore/backlog-sweep-2026-07

Conversation

@macanderson

@macanderson macanderson commented Jul 30, 2026

Copy link
Copy Markdown
Owner

Context Graph Protocol backlog sweep

Clears the buildable backlog ahead of the contextgraph/1.0 freeze. Triaged every open issue against the actual repo state, then built everything a coding agent can build — 18 issues, each landed as its own gated-green commit. Work that requires a human/privileged action (publishing, tagging, repo settings) is prepped in code but left for the owner (listed at the bottom).

Every commit passed the full local gate before landing: cargo fmt, clippy -D warnings, cargo test --workspace, the conformance scripts (green / --misbehave red / host-conformance), the three new external-provider suites, schema/validate-examples.py, and the pnpm site build.

Transport & host correctness

Conformance

Ecosystem

Spec & profile

Infra & docs

Also closed during triage (already resolved on main)

#27, #31, #51, #53, #54, #55, #56 — closed with evidence.


Remaining for the owner (cannot be done by a coding agent)

Draft until the above are reviewed. #22 (roadmap epic) stays open as the freeze tracker.

🤖 Generated with backlog-sweep.

Summary by Sourcery

Add a reference prompt-composition module, pipeline the stdio transport, and extend host, HTTP, and conformance logic to enforce version, budget, provenance, and transport guarantees ahead of the contextgraph/1.0 freeze.

New Features:

  • Introduce a reference prompt-composition module that splits a global budget across providers, deduplicates cross-provider evidence, orders frames by value, and produces a prompt, citation map, and composition audit.
  • Add an MCP→CGP bridge and CGP→MCP server to enable bidirectional interop between MCP resource servers and Context Graph Protocol hosts.
  • Ship two in-repo reference providers (ripgrep for Snippet frames and a treesitter-backed symbol graph for Symbol and Graph frames) that are green on the full provider conformance suite.
  • Provide HTTP adapters and scaffold generators for the TypeScript, Python, and Go SDKs so providers can be hosted over stdio or HTTP with conformance wired in from the first commit.
  • Define and implement the Context Exchange Provider lifecycle profile (contextgraph/lifecycle/1.0-draft) with a JSON Schema, Rust record types, fixtures, and a round-trip/hash conformance suite.

Bug Fixes:

  • Ensure malformed-input tolerance checks require a bad_request error code rather than passing on arbitrary errors.
  • Detect stale-but-well-formed provenance digests by re-reading fixture files and re-hashing them, closing a gap in digest correctness checks.

Enhancements:

  • Pipeline the stdio transport with correlation-id based demultiplexing so correlated queries can run concurrently and crashes fail all in-flight exchanges instead of hanging them.
  • Extend the HTTP provider transport with bearer credential support, plaintext-transport refusal for non-loopback hosts, and structured Unauthorized errors to enforce C7/C8.
  • Add a global-budget fan-out API to the host and a prompt-composition entrypoint that packs accepted frames under a single budget and explains every inclusion and exclusion.
  • Tighten host conformance with new scenarios for version-family rejection, composition audit behavior, and crash isolation, increasing confidence in host-side enforcement of SPEC rules.
  • Refine ErrorCode/HostReaction to carry structured error codes across the transport boundary, including unsupported_representation and incompatible_version mapped to explicit host reactions.
  • Update the core SPEC and protocol surface docs to incorporate usage reports, context-neighbors deferral, composition guidance, HTTP transport guarantees, and the lifecycle profile as a protocol-layer profile.
  • Improve schema validation tooling to assert $id URLs that resolve today and keep site-served schema copies byte-identical to their sources.

Build:

  • Add CI jobs to gate the reference providers, MCP bridge, SDK HTTP adapters, and scaffold generator by running the external conformance suite and HTTP probes.
  • Introduce a publish-dry-run CI job for contextgraph-types to validate crates.io packaging without credentials, and a tag-gated release workflow for publishing the core crates in dependency order.
  • Wire a downstream canary workflow that builds stella’s contextgraph-* consumers against this repo’s HEAD to detect code-level drift before the freeze.

CI:

  • Add GitHub Actions workflows to validate reference providers, MCP bridge, SDK HTTP implementations, scaffolded projects, schema examples, and crate publish dry runs as part of CI.
  • Extend host-conformance and provider-conformance tests to cover new error-code, provenance, composition, and crash-isolation behaviors.

Documentation:

  • Document the Context Exchange Provider lifecycle profile as a normative profile, including operations, record kinds, hashing, provenance, and error vocabulary.
  • Add provider implementation guides and site mirrors describing SDK usage, HTTP hosting, scaffold generation, and how to get listed in the conformance registry.
  • Update protocol overview, advantages, stability, protocol surface, context reuse, and new composition and MCP-composition walkthrough docs to reflect the current spec and ecosystem.
  • Introduce a public conformance registry page and badge, with a reproducible report backing each conformant provider entry.

Tests:

  • Add extensive tests for the prompt-composition module (budget splitting property tests, cross-provider dedup, value ordering, audit correctness, and injection resistance).
  • Add host-conformance scenarios for version-family rejection, crash isolation, and composition audit, and new provider-conformance checks for provenance-fixture consistency and malformed-input error labeling.
  • Add lifecycle-profile example tests that round-trip fixtures through Rust types, validate schema invariants, and recompute JCS-based record_hash values.

Chores:

  • Add CI and docs badges for the crates and README, and normalize CGP abbreviation usage across docs and site content.
  • Refine contribution and issue templates to mention CGP crate naming and add a registry submission checklist requiring reproducible contextgraph-inspect invocations.

…ma $id

Five file-disjoint backlog issues, all additive (no wire/Rust-logic change):

- #20 Conformance registry page + reproducible-report seed + badge + PR
  submission checklist. Seed report is a verified 12/12 capture of
  `contextgraph-inspect stdio --json` against the bundled example provider.
- #16 Tag-triggered, environment-gated crates.io release.yml + a credential-free
  `publish-dry-run` CI job + crates.io/docs.rs badges. Version cut and the
  crates-io environment/secret remain the owner's decision.
- #59 sdk/PUBLISHING.md + tag-gated publish-sdks.yml; PyPI/Go publishes and the
  Go tag remain human-only. npm already live via #46.
- #29 downstream-canary.yml builds stella's contextgraph-* consumers against
  HEAD (advisory); oxagen-canary activates once OXAGEN_PLATFORM_TOKEN is wired.
- #58 schema $id repointed to the GitHub-raw URL that resolves today (interim
  until #57's Vercel relink); schema validate-examples.py green, mirror
  byte-identical.

Closes #20, #29, #58
Refs #16, #59 (publish/tag/secret steps are human-only)
…mment (#49)

Closes the two remaining #49 "survivors":

- SPEC.md gains a normative §7.3 "Usage reports" (UR1): a host MUST be able to
  produce a usage report whose budget_consumed equals the summed token_cost of
  served frames, referencing them by FrameId — backed by the existing, tested
  contextgraph-host::FanOut::usage_report. Resolves the "U1" anchor collision
  with §13's ignore-unknown-members rule by labelling this UR1 across SPEC.md,
  docs/context-reuse.md, and docs/protocol-surface.md, and repointing §14's A1
  cross-reference at §7.3.
- Reword the schema canonical_token_cost $comment so tokenizer_ref pairs only
  with canonical_token_cost (the exact-count companion), never the byte-formula
  token_cost (§B3/§7.2) — resolving #50's tokenizer residual. Source and site
  schema copies stay byte-identical.

schema/validate-examples.py green.

Closes #49
Refs #50
The graph itself is already real and witnessed — §8 specifies graph frames, the
open `rel` vocabulary, and the G1/G2/G3/G4 checks (G4's anchored predicate and
its `anchor-relevance` check landed in #63/#64). The one remaining #7 acceptance
box was the design sketch for multi-hop traversal.

Adds docs/sketches/context-neighbors.md (a `context/neighbors { uri, rels, depth }`
envelope pair as a post-1.0 additive minor, defined so `depth: 1` ≡ the G4
anchored set) following the docs/sketches/resolve.md template, and a §8.3
forward-reference in SPEC.md mirroring the §6.4.1 deferral pattern. No wire
change — traversal beyond one hop is explicitly out of scope for the 1.0 freeze.

Closes #7
#9)

The wire already carried `code: Option<ErrorCode>`; nothing read it. This plumbs
it end to end and tightens the conformance floor:

- ErrorCode gains `unsupported_representation` (§P5) and `incompatible_version`
  (§H3), wired through as_str/From<&str>/reaction. incompatible_version is
  permanent — a new HostReaction::DropProvider (the request is fine, the provider
  is unusable; distinct from DoNotRetry/Respawn/ReportAndCount).
- HostError::Provider now carries `code`; the four http.rs/stdio.rs error arms
  pass it through instead of discarding it, so FanOut::failures surfaces it.
- The malformed-input-tolerance conformance check now passes only on a
  `bad_request` code (was: any Envelope::Error), per SPEC.md R1. A new
  `--misbehave mislabel-malformed` mode (answers `internal`) exercises the
  tightened check in conformance-red.sh, with a matching suite test.

Gate green: fmt, clippy -D warnings, test --workspace, conformance-green (12/12),
conformance-red (all misbehave modes caught).

Closes #9
C7/C8 were specified (§4.2) but listed as a live enforcement gap (§11.1). This
implements them in the reference host:

- C7 (TLS for non-loopback): HttpProvider refuses a plaintext http:// target to
  any non-loopback host with HostError::InsecureTransport, BEFORE the client is
  built or DNS resolves. Loopback (localhost / 127.0.0.0/8 / [::1]) stays exempt
  so the wiremock suite keeps working.
- C8 (credentials never logged): a new Credential type whose Debug AND Display
  both render only "Credential(<redacted>)" (secret reachable only via a
  crate-private expose); attached via reqwest bearer_auth, never a format
  string. A redaction test asserts no HostError/format string leaks the secret.
- connect_with_auth / Host::add_http take an optional Credential (connect stays
  as a back-compat None wrapper); a 401 surfaces as HostError::Unauthorized.
- SPEC.md §11.1 updated: C7/C8 now enforced + unit-tested at the
  transport-refusal/redaction level; full live-TLS-peer conformance remains the
  stated next increment (unchanged).

Gate green: fmt, clippy -D warnings, test (119 host + 4 new), conformance
green/red, schema validate. wiremock was already a dev-dep.

Closes #13
…cenarios (#14)

The host-conformance harness gained the two adversarial transport scenarios it
was missing (the primitives already existed in contextgraph-host; this wires
them in as witnessed checks). run_host_conformance now exposes 8 checks:

- host-version-reject (§3 H3, host-side): drives the reference host's handshake
  at a fixture declaring contextgraph/2.0 (mismatched major family), under an
  explicit tokio timeout so "never a hang" is a load-bearing assertion, and
  asserts HostError::VersionMismatch. Distinct from §3's provider-facing
  handshake check (both now named in the H3 "Verified by" cell).
- host-crash-isolation (§11): a query_all fan-out where one provider dies
  mid-query (ProviderCrashed via the BrokenPipe/EOF path) while a healthy peer
  is queried concurrently; asserts the fan-out still completes with the healthy
  frames and the crash is reported + excluded, never poisoning the query.

Each keeps the adversarial+well-behaved-counterpart discrimination pattern, and
both were red-then-green mutation-tested (invert the fixture → check fails).
SPEC.md §11.1 updated to name both host-side scenarios (added to #13's C7/C8
text, not reverting it).

Gate green: fmt, clippy -D warnings, test, host-conformance (8/8),
conformance green/red, schema validate.

Closes #14
…ick-starts (#17)

Fills the provider-SDK residue (skip Java; publishing is #59):

- HTTP adapter per SDK, mirroring the stdio provider loop as a single-endpoint
  POST handler: createHttpHandler (TypeScript), make_wsgi_app (Python),
  Handler (Go). Each ships a runnable example-docs-http provider that goes green
  under `contextgraph-inspect http` (9 passed / 3 skipped — the 3 skips are the
  harness's stdio-only wire probes, unavoidable over HTTP).
- create-contextgraph-provider: a zero-dep Node CLI with TypeScript + Python
  templates that scaffold a provider wired to both transports PLUS a bundled
  GitHub Actions workflow running contextgraph-inspect against the generated
  provider in its OWN CI from the first commit (the literal acceptance criterion).
- Quick-starts: TS + Python quick-starts, an HTTP-transport section, and a
  scaffold section appended to docs/implementing-a-provider.md and the docs-site
  mirror; HTTP APIs documented in each SDK README.

Validated via the pre-built contextgraph-inspect: TS/Python/Go HTTP all green,
existing stdio conformance still 12/12, both scaffolded templates conformant.
The CI jobs (sdk-*-http, sdk-scaffold) are applied to ci.yml separately.

Closes #17
…CHANGELOG

- ci.yml: add sdk-typescript-http, sdk-python-http, sdk-go-http (start each
  example server, run `contextgraph-inspect http` against it) and sdk-scaffold
  (generate a provider from create-contextgraph-provider and assert its own
  conformance check passes) for #17. actionlint clean.
- CHANGELOG [Unreleased]: record #9, #13, #14, #17.

Refs #9, #13, #14, #17
…ency check (#12)

The reference fixture now verifies its own digests end to end, closing the
"stdio fixture" survivor of #12 (the digest grammar + host verify API were
already done):

- The example-docs fixture gains real on-disk backing files
  (fixtures/example-docs/{getting-started,configuration}.md); fixture_digest now
  computes a genuine sha256 over those bytes at runtime and frames carry file://
  provenance, so verify_file_provenance can re-read and re-hash them.
- New provider check `provenance-fixture-consistency`: re-reads each frame's file
  provenance and re-hashes it against the bytes on disk (Verified→pass,
  Mismatch→fail, Unreadable→host-local skip). The suite is now 13 checks.
- New `--misbehave stale-digest` mode emits a WELL-FORMED sha256 (one hex digit
  flipped) that passes F5 grammar and verify-honesty but does not match the real
  bytes — provenance forgery only the new check catches. conformance-red.sh
  auto-discovers it (no script edit).
- sha2 moved from a conformance dev-dep to the workspace 0.10 normal dep (matches
  the host verifier); verify_wire.rs now computes real digests from the files.

Gate green: fmt, clippy -D warnings, test, conformance-green (13/13),
conformance-red (all modes incl. stale-digest), schema validate.

Closes #12
#12 added the provenance-fixture-consistency check (suite 12→13). Regenerate the
bundled contextgraph-example-docs conformance report from
`contextgraph-inspect stdio --json` and update the registry table to 13/13 so the
listed attestation stays a faithful capture, not a stale claim.

Refs #20, #12
…tex (#4)

Delivers the demux/pipelining half of ADR 0002 (the correlation-id decision half
already shipped). StdioProvider previously held one mutex across the whole query
round-trip, so concurrent queries serialized even when the provider negotiated
capabilities.correlation.

- The connection is split after handshake into a write-half (stdin mutex), a
  dedicated reader task, and a control handle (StdioControl) that reproduces the
  SHUTDOWN_GRACE + kill_group semantics exactly. RawStdioConnection::into_parts
  moves the fields out without running Drop (ManuallyDrop + one ptr::read per
  field — sound: each read once, destructor suppressed).
- A `pending: HashMap<id, oneshot::Sender>` demuxes replies. query (correlated)
  registers its oneshot before sending, holds the stdin mutex only for the write,
  then awaits its reply with no lock held — so two queries interleave. Reader
  drains every waiter on EOF/decode/transport error, so a crash fails in-flight
  queries instead of hanging them.
- Non-correlating providers and verify keep the strict lock-step path
  (exchange_lockstep), provably unchanged. RawStdioConnection's public raw
  send/recv API is byte-for-byte unchanged, so the conformance crate's wire
  probes compile and pass untouched.
- Witness test (ADR 0002): a fixture that reads both queries before answering
  either, then replies to the second FIRST — deadlocks a lock-step transport,
  demuxes correctly here. Ran 15x, no flakes.

Gate green: fmt, clippy -D warnings, test --workspace (+witness), conformance
green (13/13)/red/host, schema validate.

Closes #4
#15)

Layered on compose_context's byte-stability floor (the injection-escaping half
shipped in #63); this delivers the rest of #15:

- Host::query_all_budgeted splits a global token budget into per-provider shares
  before fan-out, so N honest legs sum to <= the whole budget instead of N x it.
- compose::dedup_cross_provider collapses the same evidence from two providers
  (content_digest match, then uri+range provenance overlap), keeping the
  higher-scored frame and merging provenance.
- order_by_value places the highest-value frames at the top/bottom edges
  (Lost in the Middle, Liu et al. 2024), byte-stable for a fixed set.
- compose_for_prompt returns an injection-resistant fenced prompt with an
  "evidence, not instructions" preamble, a citation map (label -> frame id +
  provenance), and a CompositionAudit that explains every included/excluded frame.
- New host-conformance check host-composition-audit (host suite now 9),
  red-then-green mutation-tested; a property test bounds composed tokens <=
  budget; an injection-corpus test proves no instruction-shaped payload escapes
  the fence. SPEC.md R3 now cites the host checks + the new reference doc.

Gate green: fmt, clippy -D warnings, test --workspace (+property +injection),
conformance green/red, host-conformance (9/9), schema validate.

Closes #15
Five new publish=false workspace crates, each conformance-green:

#18 — reference providers:
- contextgraph-ripgrep: Snippet frames from a ripgrep/built-in content search
  with real, re-verifiable file provenance.
- contextgraph-treesitter: Symbol + Graph frames (code.defines/calls/imports),
  via a self-contained pure-Rust symbol extractor (no tree-sitter C toolchain).
- contextgraph-refprov: the shared stdio-provider kit both binaries reuse.
Both providers pass all 13 provider checks under conformance-external.sh; git
history episodes deferred as the sanctioned stretch. See docs/reference-providers.md.

#19 — MCP interop, a bridge in each direction:
- contextgraph-mcp-bridge: wraps any MCP resource server as a budgeted, cited,
  consent-gated CGP provider (MCP resources -> Doc/Snippet frames with
  mcp-resource provenance; local file:// resources get a byte-verifiable digest).
  Goes fully conformance-green against a hermetic in-repo MCP fixture — no
  network, no npx.
- contextgraph-mcp-server: exposes a CGP host's fan-out as an MCP
  query_context(goal, budget, kinds) tool returning frames, provenance,
  citations, and a budget audit as structured content. See docs/composition-walkthrough.md.

CI gains reference-provider-ripgrep, reference-provider-treesitter, and mcp-bridge
jobs. No new external dependencies. Full workspace gate green: fmt, clippy
-D warnings, test, conformance green (13/13)/red/host, the three external-provider
suites, and schema validate.

Closes #18
Closes #19
)

Turns docs/profiles/context-exchange-provider.md from a draft skeleton into a
normative profile (contextgraph/lifecycle/1.0-draft) with RFC-2119 rows + stable
anchors and every [OPEN] resolved from ADR 0007 / the reconciliation doc:

- schema/contextgraph-lifecycle-record.schema.json (+ byte-identical site mirror):
  the discriminated ContextRecord union — common envelope + 12 record kinds
  (observation, knowledge, memory, directive, record_proposal, evidence,
  artifact_contract, contract_validation, outcome_assessment, promotion_event,
  context_use, context_use_feedback), closed via unevaluatedProperties:false.
- contextgraph-types::record: serde wire types for the envelope + kinds +
  detached RecordAttestation + envelope_invariants; the crate stays
  zero-runtime-dep beyond serde.
- tests/fixtures/: one golden fixture per record kind + an attestation + a README
  documenting the canonical fixture home and a worked RFC 8785 JCS -> sha256
  record_hash example (Python and Rust canonicalizers agree byte-for-byte).
- contextgraph-conformance/tests/lifecycle_profile_examples.rs: round-trip,
  envelope-invariant, and JCS hash-recomputation tests over the fixtures.
- Resolutions: context/resolve is profile-scoped (SPEC §6.4.1 reservation);
  E3 7-key scope (tenant_id/project_id dropped, schema rejects them); B5 3-value
  record_status; D6/D7 schema-vs-execution split; C5 provenance + detached
  attestation. Reconciliation rows D1/D4/D5/D6/D7/B3/B5/C5/E3 marked resolved;
  SPEC §6.4.1/§13 cross-linked (non-normative pointers).

Owner judgment calls flagged in the issue: origin-enum vs provenance boundary,
open `sensitivity` string, string-valued `extensions`, capability types doc-only.

Gate green: fmt, clippy -D warnings, test --workspace, schema validate (new
schema + fixtures + byte-identical mirror), build, conformance-green (13/13).

Closes #28
…partial)

- README, CONTRIBUTING, docs/, and the site/content/docs mirrors now expand
  "Context Graph Protocol (CGP)" on first mention and use "CGP" for subsequent
  body-prose mentions — matching the already-conventional SPEC.md / ADR 0002 /
  reconciliation doc. Titles, markdown link text, version strings
  (contextgraph/1.0-draft), crate names, and code fences left intact.
- Reconciled a stale OCP→full-name rename artifact in the protocol-advantages
  site mirror ("Open Context Protocol (Context Graph Protocol)" / doubled bold).
- Fixed the bug-report template grammar ("in an" → "in a").
- Added a CI status badge to README (the buildable half of #2; branch protection
  itself stays owner-only).

Closes #21
Refs #2 (branch-protection rule remains owner-only)
@sourcery-ai

sourcery-ai Bot commented Jul 30, 2026

Copy link
Copy Markdown

Reviewer's Guide

Implements the reference prompt-composition module and global budget split, pipelines the stdio transport with correlation-aware demux, hardens the HTTP transport and host conformance, ratifies the lifecycle Context Exchange Provider profile and fixtures, adds reference providers and MCP interop, and wires SDK HTTP adapters, scaffolding, CI, and release prep across the repo ahead of the contextgraph/1.0 freeze.

Sequence diagram for budgeted fan-out and prompt composition

sequenceDiagram
    participant Host
    participant ContextProvider as Provider
    participant Compose as ComposeModule

    Host->>Host: query_all_budgeted(template_query, global_budget)
    Host->>Host: capability_matches(capabilities, template_query)
    Host->>Compose: budget_split(global_budget, provider_count)
    loop per_matching_provider
        Host->>Provider: query(ContextQuery with max_tokens=share)
        Provider-->>Host: ContextQueryResult
    end
    Host->>Compose: compose_for_prompt(accepted_with_provider, global_budget)
    Compose->>Compose: dedup_cross_provider(frames)
    Compose->>Compose: order_by_value(included_frames)
    Compose-->>Host: ComposedPrompt(prompt, citations, CompositionAudit)
Loading

File-Level Changes

Change Details Files
Add a reference prompt-composition module and global-budget-aware fan-out plus audit support in the host.
  • Extend compose.rs with budget splitting, cross-provider deduplication, value-aware ordering, citation mapping, and a CompositionAudit/ComposedPrompt API.
  • Change render_frame to use a shared citation_label_for helper for consistent citation labels.
  • Add Host::query_all_budgeted and FanOut::compose_for_prompt to split a global token budget across providers and compose accepted frames under that budget.
  • Introduce comprehensive unit tests and property/injection corpus tests for the composition module to enforce budget bounds and injection resistance.
contextgraph-host/src/compose.rs
contextgraph-host/src/host.rs
Pipeline the stdio transport with correlation-id-based demultiplexing, shared IO helpers, and crash-consistent behavior.
  • Refactor RawStdioConnection to use shared read_framed_line/write_framed_line helpers and add into_parts for splitting stdin/stdout/control.
  • Introduce StdioControl and a dedicated reader task that demuxes replies on correlation id, manages pending tables and id-less slot, and drains waiters on exit.
  • Rewrite StdioProvider to own stdin, pending tables, a lock-step path for non-correlating/id-less exchanges, and correlation-aware query logic with verify.
  • Add ADR-0002 witness bash fixture and tests proving out-of-order correlated queries are correctly demuxed and that non-correlating providers remain lock-step.
contextgraph-host/src/stdio.rs
Harden the HTTP transport with TLS enforcement, credential redaction, and structured provider errors, and extend host error handling.
  • Add a redacted Credential type and is_loopback_host/refuse_insecure_transport helpers; enforce C7/C8 in HttpProvider::connect_with_auth.
  • Modify post_envelope to attach bearer auth, surface HTTP 401 as HostError::Unauthorized, and thread optional Credential through query/verify/shutdown.
  • Extend HostError with InsecureTransport and Unauthorized variants and propagate ErrorCode into HostError::Provider.
  • Add unit tests for plaintext non-loopback refusal, loopback allowance, bearer header attachment, and credential redaction and error rendering.
contextgraph-host/src/http.rs
contextgraph-host/src/error.rs
Expand host conformance with version-reject, composition-audit, and crash-isolation scenarios and wire new checks into the suite.
  • Add HCHECK_VERSION_REJECT, HCHECK_COMPOSITION_AUDIT, and HCHECK_CRASH_ISOLATION constants and implement corresponding checks in host_conformance.rs.
  • Drive stdio-based bash fixtures for mismatched version-family handshake, crashing-after-handshake, and healthy counterparts to assert host behavior.
  • Update run_host_conformance to include new checks and add tests that the reference host passes all host-binding rules including the new scenarios.
contextgraph-conformance/src/host_conformance.rs
contextgraph-conformance/src/lib.rs
contextgraph-conformance/tests/host_conformance_suite.rs
Ratify the Context Exchange Provider lifecycle profile with JSON Schema, Rust types, fixtures, and conformance round-trip/hash verification, and document the profile.
  • Replace the CEP profile draft skeleton with a normative profile doc, resolving open design points (scope, directive taxonomy, hashing, attestation, errors, operations).
  • Add contextgraph-lifecycle-record JSON Schema and a site mirror, plus validate-examples.py logic to check record fixtures and mirror byte-identity.
  • Introduce ContextRecord and related enums/types in contextgraph-types::record, re-export in lib.rs, and enforce envelope invariants (schema_version, hash grammar, origin/derivation matrix).
  • Add tests in lifecycle_profile_examples.rs to round-trip every record fixture through ContextRecord, check invariants, and recompute record_hash via RFC 8785 JCS and sha256; add attestation fixture signing the observation record.
docs/profiles/context-exchange-provider.md
schema/contextgraph-lifecycle-record.schema.json
site/public/schema/contextgraph-lifecycle-record.schema.json
schema/validate-examples.py
contextgraph-types/src/record.rs
contextgraph-types/src/lib.rs
contextgraph-conformance/tests/lifecycle_profile_examples.rs
tests/fixtures/*.json
tests/fixtures/README.md
Extend error code and host error handling with unsupported_representation and incompatible_version codes and host reactions.
  • Add ErrorCode::UnsupportedRepresentation and ErrorCode::IncompatibleVersion plus HostReaction::DropProvider, update is_retryable/reaction mappings and serde round-trip tests.
  • Thread structured ErrorCode through HostError::Provider and update sites that construct Provider errors to include the code (HTTP, stdio, host tests).
contextgraph-types/src/error_code.rs
contextgraph-host/src/error.rs
contextgraph-host/src/host.rs
Strengthen provider conformance around malformed input, embedding fingerprint, and provenance digest honesty, using the example-docs fixture.
  • Extend example-docs misbehave modes with MislabelMalformed and StaleDigest, implement honest verify that can be steered to malformed/stale digest behaviors.
  • Change malformed-input-tolerance check to require ErrorCode::BadRequest and add tests for crashing and mislabeling modes.
  • Add provenance-fixture-consistency check that re-reads file:// URIs from a trusted local fixture and re-hashes digests, plus tests for stale-digest misbehavior vs honest behavior.
  • Update example-docs fixtures to real files under fixtures/example-docs and compute genuine sha256 digests in both fixture and verify-wire tests.
contextgraph-conformance/src/bin/contextgraph-example-docs.rs
contextgraph-conformance/src/lib.rs
contextgraph-conformance/tests/conformance_suite.rs
contextgraph-conformance/tests/verify_wire.rs
contextgraph-conformance/fixtures/example-docs/*.md
Add reference provider binaries (ripgrep and treesitter) built on a shared refprov skeleton, plus docs and CI to prove them conformant.
  • Introduce contextgraph-refprov crate with shared stdio loop, FileFrame/DerivedFrame builders, walk/line_range_bytes helpers, and FrameSource trait.
  • Add contextgraph-ripgrep binary implementing FrameSource over a ripgrep or built-in search, re-reading exact line bytes and emitting Snippet frames with file provenance and edges.
  • Add contextgraph-treesitter binary implementing a line-based Rust symbol extractor to emit Symbol and Graph frames with code.defines/imports/calls edges and provenance.
  • Document the reference providers and add CI jobs that build and run conformance-external.sh against both binaries.
contextgraph-refprov/Cargo.toml
contextgraph-refprov/src/lib.rs
contextgraph-ripgrep/Cargo.toml
contextgraph-ripgrep/src/main.rs
contextgraph-ripgrep/fixtures/reference.md
contextgraph-treesitter/Cargo.toml
contextgraph-treesitter/src/main.rs
contextgraph-treesitter/fixtures/sample.rs
docs/reference-providers.md
.github/workflows/ci.yml
Implement MCP interop: a bridge that wraps MCP servers as CGP providers and an MCP server that exposes a CGP host as an MCP tool, plus tests.
  • Add contextgraph-mcp-bridge crate with an MCP client over stdio (initialize/resources/list/read), mapping resources to file-backed frames with mcp-resource+file provenance and honest costs, plus BridgeConfig for egress posture.
  • Add contextgraph-mcp-fixture MCP server binary serving a hermetic set of file:// resources from fixtures/mcp for bridge conformance and CI.
  • Add contextgraph-mcp-server crate implementing an MCP server exposing a query_context tool backed by a CGP Host, returning frames, citations, and budget audit as structured content.
  • Add end-to-end tests driving the bridge via Host::query_all and the server via JSON-RPC over stdio, asserting frames/provenance/citations and consent gating for remote bridges.
contextgraph-mcp-bridge/Cargo.toml
contextgraph-mcp-bridge/src/lib.rs
contextgraph-mcp-bridge/src/bin/contextgraph-mcp-bridge.rs
contextgraph-mcp-bridge/src/bin/contextgraph-mcp-fixture.rs
contextgraph-mcp-bridge/fixtures/mcp/*.md
contextgraph-mcp-server/Cargo.toml
contextgraph-mcp-server/src/lib.rs
contextgraph-mcp-server/src/bin/contextgraph-mcp-server.rs
contextgraph-mcp-server/tests/smoke.rs
docs/composition-walkthrough.md
.github/workflows/ci.yml
Add SDK HTTP adapters for TypeScript, Python, and Go and enhance SDK docs and examples to cover HTTP transport.
  • Implement a TypeScript HTTP adapter (handleEnvelope/respondToEnvelopeBody/createHttpHandler) in sdk/typescript, plus an example-docs-http server and CI job that probes it via contextgraph-inspect http.
  • Implement Python HTTP adapter (handle_envelope/respond_to_body/make_wsgi_app) and example_docs_http WSGI server, plus CI job probing it via contextgraph-inspect http.
  • Implement Go HTTP adapter (RespondToBody/Handler) and example-docs-http server using net/http, plus CI job probing it via contextgraph-inspect http.
  • Update provider implementation docs and site mirrors to describe SDK HTTP adapters, quick-starts, and conformance expectations over HTTP (skipped wire-level checks).
sdk/typescript/src/http.ts
sdk/typescript/src/index.ts
sdk/typescript/examples/example-docs-http.ts
sdk/typescript/README.md
sdk/python/contextgraph_sdk/http.py
sdk/python/examples/example_docs_http.py
sdk/python/README.md
sdk/go/contextgraph/http.go
sdk/go/examples/example-docs-http/main.go
sdk/go/README.md
docs/implementing-a-provider.md
site/content/docs/implementing-a-provider.mdx
.github/workflows/ci.yml
Add a scaffold generator for new providers and wire conformance into the generated projects.
  • Introduce create-contextgraph-provider CLI with TypeScript and Python templates (stdio and HTTP entrypoints, conformance scripts, GitHub Actions workflow) and parameterized SDK dependency.
  • Add SDK README and PUBLISHING.md documenting SDK release status and registry targets.
  • Add a CI job that builds the TypeScript SDK, scaffolds TS and Python projects, and runs their bundled conformance checks using the built contextgraph-inspect binary.
sdk/create-contextgraph-provider/index.js
sdk/create-contextgraph-provider/package.json
sdk/create-contextgraph-provider/templates/**
sdk/README.md
sdk/PUBLISHING.md
.github/workflows/ci.yml
Prepare crates.io release workflow and dry-run packaging for the Rust crates, and update README badges and publishing docs.
  • Add Release GitHub Actions workflow that publishes contextgraph-types -> contextgraph-host -> contextgraph-conformance in order, gated behind a crates-io environment and CARGO_REGISTRY_TOKEN, with sparse-index wait-for-crate script.
  • Add a publish-dry-run job in CI to package contextgraph-types on every PR without credentials.
  • Update PUBLISHING.md to describe the tag-triggered workflow vs manual release, token/environment setup, and one-way-door constraints.
  • Add crates.io/docs.rs badges to crate READMEs and the root README, noting they read "not found" until first publish.
.github/workflows/release.yml
.github/workflows/ci.yml
.github/scripts/wait-for-crate.sh
PUBLISHING.md
README.md
contextgraph-types/README.md
contextgraph-host/README.md
contextgraph-conformance/README.md
Add a downstream canary workflow to build stella against CGP HEAD and document adaptive-context reconciliation and governance links.
  • Add downsteam-canary GitHub Actions workflow that checks out stella, patches its Cargo.toml to use local CGP crates via [patch], and builds/tests stella contextgraph-* consumers, emitting advisory warnings on breakage.
  • Add helper script downstream-canary-stella.sh to implement the patch and build logic.
  • Update adaptive-context-reconciliation.md and ADR-0007 to mention the canary workflow and its advisory role in guarding code drift.
  • Wire oxagen platform canary placeholder job gated on an OXAGEN_PLATFORM_TOKEN for future cross-org fixture validation.
.github/workflows/downstream-canary.yml
.github/scripts/downstream-canary-stella.sh
docs/adaptive-context-reconciliation.md
docs/adr/0007-protocol-product-boundary.md
Tighten SPEC.md and protocol docs around usage reports, neighbors deferral, host-conformance coverage, composition, and CGP naming.
  • Add SPEC §7.3 Usage reports (UR1) and reference FanOut::usage_report; adjust protocol-surface/context-reuse docs to use UR1 anchor.
  • Clarify SPEC §8.3 that multi-hop traversal is deferred and reference design sketch docs/sketches/context-neighbors.md.
  • Expand SPEC §11.1 host-conformance description to include H3, crash isolation, composition, and HTTP transport enforcement gaps now closed in code.
  • Add docs/composing-frames-into-a-prompt.md describing the reference composer and link it from SPEC and protocol-surface.
  • Normalize documentation to use the CGP abbreviation and update multiple docs/README/site content accordingly.
SPEC.md
docs/protocol-surface.md
docs/context-reuse.md
docs/composing-frames-into-a-prompt.md
docs/sketches/context-neighbors.md
docs/overview.md
docs/protocol-advantages.md
docs/index.md
README.md
site/content/docs/*.mdx
docs/protocol-advantages.md
docs/adaptive-context-reconciliation.md

Assessment against linked issues

Issue Objective Addressed Explanation
#50 Eliminate the dead Capabilities.resolve/reference surface before 1.0 by either (a) fully specifying a context/resolve operation (envelope, wire shape, host API, conformance) or (b) cutting the reference representation and Capabilities.resolve from the frozen 1.0 core. The PR updates SPEC §6.4.1 to note that context/resolve is defined by the new Context Exchange Provider profile (contextgraph/lifecycle/1.0-draft), and clarifies that core contextgraph/1.0 still ships no resolve operation. However, it does not add a resolve/resolved envelope to the main envelope JSON Schema, does not introduce a wire-level resolve shape in contextgraph-host::wire, and does not implement a host API or conformance checks for context/resolve. It also does not remove the reference representation or Capabilities.resolve from the core 1.0 schema/types; they remain present but without a core resolve operation. The dead capability surface in the frozen core is therefore not removed; resolve is only described at the profile level, not fully specified or cut in the core code and schema as the issue requires.
#50 Fix budget semantics for frames without inline content (especially reference/compact frames) by ensuring B3 token-cost honesty applies to them and restating B3 rules for every representation the frozen spec ships so no frame can silently have token_cost = 0 for unbounded resolved content. The PR adds a prompt-composition module that packs frames under a global budget using ContextFrame::expected_inline_token_cost, and it strengthens usage-report semantics (§7.3). It does not, however, change the underlying token-cost behavior for frames with absent content in contextgraph-types/src/frame.rs or restate B3 explicitly for compact/reference representations. There is no change to the envelope/frame schema or types that would prevent a reference frame with unbounded resolved content from having token_cost = 0, and no per-representation B3 rules are added. As a result, the budget honesty hole for non-inline representations identified in the issue remains unaddressed in the core spec and code.

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@macanderson
macanderson marked this pull request as ready for review July 30, 2026 04:07

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @macanderson, your pull request is larger than the review limit of 150000 diff characters

Resolves the conflicts on PR #69. Most of this branch had already landed on
main via #66 and #67, so the merge is mainly about keeping what is genuinely
new (#28, #21, #2) and taking main's side everywhere #68 made a decision.

Resolution rules applied:

- site/ is retired (ADR 0008, #68). All nine modify/delete conflicts under
  site/ take main's deletion; the branch's edits to the .mdx mirrors and to
  site/public/schema/ are dropped rather than resurrected. tests/
  docs_site_witness_test.py goes with it — it asserted the site mirrored the
  markdown docs.
- Advertised artifact URLs take main's rewrite: cgp.oxagen.sh/badges/... and
  site/public/... become the GitHub-raw paths that check-deploy-hygiene.py
  enforces. This covers the three SDK READMEs, docs/registry.md,
  docs/implementing-a-provider.md and the CHANGELOG entry for #20.
- The CGP abbreviation convention (#21) is kept where it does not collide with
  the above: docs/index.md, docs/composition-walkthrough.md, and the
  "CGP maintainers" cell in the registry table now sit on top of main's paths.
- .github/workflows/ci.yml: the branch's publish-dry-run job is dropped
  because main already carries it (via #66) — keeping both would have created
  a duplicate YAML job key. The branch's `site: docs site builds` job is
  dropped for the same reason site/ is; main's deploy-hygiene job stands.
- schema/validate-examples.py keeps the new lifecycle-record section (#28) —
  13 fixtures plus the detached attestation — with its site/public/schema/
  mirror checks removed, since there is no second copy to keep in sync.
- docs/profiles/context-exchange-provider.md LF2 is restated: the normative
  MUST was a byte-identical site/public/schema/ mirror enforced by a check
  that no longer exists. It now pins the $id to GitHub-raw per ADR 0008. This
  was in cleanly auto-merged text, so git did not flag it.

Net contribution over main after the merge is 34 files / +2,507: the Context
Exchange Provider lifecycle profile (#28), the CGP abbreviation pass (#21),
and the README CI badge (#2 partial).

Verified: cargo fmt --check, cargo test --workspace --all-features,
cargo clippy -D warnings, python3 schema/validate-examples.py (all examples
validate), python3 .github/scripts/check-deploy-hygiene.py (deploy hygiene
holds), and all relative links in 58 markdown files resolve.
macanderson added a commit that referenced this pull request Jul 30, 2026
Resolves the conflicts on PR #69. Most of this branch had already landed on
main via #66 and #67, so the merge is mainly about keeping what is genuinely
new (#28, #21, #2) and taking main's side everywhere #68 made a decision.

Resolution rules applied:

- site/ is retired (ADR 0008, #68). All nine modify/delete conflicts under
  site/ take main's deletion; the branch's edits to the .mdx mirrors and to
  site/public/schema/ are dropped rather than resurrected. tests/
  docs_site_witness_test.py goes with it — it asserted the site mirrored the
  markdown docs.
- Advertised artifact URLs take main's rewrite: cgp.oxagen.sh/badges/... and
  site/public/... become the GitHub-raw paths that check-deploy-hygiene.py
  enforces. This covers the three SDK READMEs, docs/registry.md,
  docs/implementing-a-provider.md and the CHANGELOG entry for #20.
- The CGP abbreviation convention (#21) is kept where it does not collide with
  the above: docs/index.md, docs/composition-walkthrough.md, and the
  "CGP maintainers" cell in the registry table now sit on top of main's paths.
- .github/workflows/ci.yml: the branch's publish-dry-run job is dropped
  because main already carries it (via #66) — keeping both would have created
  a duplicate YAML job key. The branch's `site: docs site builds` job is
  dropped for the same reason site/ is; main's deploy-hygiene job stands.
- schema/validate-examples.py keeps the new lifecycle-record section (#28) —
  13 fixtures plus the detached attestation — with its site/public/schema/
  mirror checks removed, since there is no second copy to keep in sync.
- docs/profiles/context-exchange-provider.md LF2 is restated: the normative
  MUST was a byte-identical site/public/schema/ mirror enforced by a check
  that no longer exists. It now pins the $id to GitHub-raw per ADR 0008. This
  was in cleanly auto-merged text, so git did not flag it.

Net contribution over main after the merge is 34 files / +2,507: the Context
Exchange Provider lifecycle profile (#28), the CGP abbreviation pass (#21),
and the README CI badge (#2 partial).

Verified: cargo fmt --check, cargo test --workspace --all-features,
cargo clippy -D warnings, python3 schema/validate-examples.py (all examples
validate), python3 .github/scripts/check-deploy-hygiene.py (deploy hygiene
holds), and all relative links in 58 markdown files resolve.

Claude-Session: https://claude.ai/code/session_014H5SE4vnAP4Nw1MBMHfUpt
@macanderson
macanderson force-pushed the chore/backlog-sweep-2026-07 branch from a9a16a5 to af77fc0 Compare July 30, 2026 21:57
@macanderson
macanderson merged commit 6fa4e8d into main Aug 1, 2026
18 of 21 checks passed
@macanderson
macanderson deleted the chore/backlog-sweep-2026-07 branch August 1, 2026 01:00
macanderson added a commit that referenced this pull request Aug 1, 2026
…og, and backfill the gaps (#73)

CHANGELOG.md relied on every PR remembering to write its own [Unreleased]
entry. An audit of the 22 merges since v0.1.0 whose numbers never appear
in the file found 9 user-visible changes with no entry at all — including
the OCP -> CGP rename itself, the repo's biggest breaking change. The
Unreleased section had also accumulated duplicate category headings
(two '### Added', two '### Changed', two '### Fixed') from PRs appending
their own blocks.

Go-forward: .github/workflows/changelog.yml watches pushes to main. When
a merge lands without touching CHANGELOG.md, it drafts the missing
entries from the merge's actual diff (.github/scripts/changelog-ai.sh,
Vercel AI Gateway, degrade-open: no key or a failed call is a log line,
never a red check) and proposes them as a bot/changelog PR — a draft for
human review, never a direct push. The gap is measured from the last
commit that touched CHANGELOG.md, so merging the bot PR resets it, and
each run regenerates the whole current gap, so a superseded bot PR loses
nothing.

Backfill: entries for the rename (#1), frame identity/composition/usage
reports (#32), golden wire fixtures (#35), ADR 0007 (#61, #27),
composition conformance + the canary scheduled-run gate (#70) — written
from each PR's diff, in the file's existing voice. Three further audit
hits (#68, #69, #71) turned out to be already covered by newer entries
and were left alone. Duplicate category headings merged: one heading per
category, Keep-a-Changelog order.
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.

Decide context/resolve before the freeze: specify it or cut reference representations — and define B3 for compact/reference frames

1 participant