Chore/backlog sweep 2026 07

[macanderson]

Pull request

Summary

What changed

Checklist

• One logical change per PR (smaller lands faster)
• Gate is green locally — fmt, clippy -D warnings, test
• A witness test is included, or a reason there isn't one is stated below
• Docs updated in the same PR if behavior or flags changed (README.md,
  docs/, doc comments, --help text)
• All commits signed off (git commit -s, DCO)
• CHANGELOG.md updated under [Unreleased] if user-visible

Protocol-stability impact (if a spec/wire change)

• Not applicable — no wire or spec change
• Additive (new optional field/check) — safe within contextgraph/1
• Wire-breaking — requires contextgraph/2; explain below

License

By submitting this pull request, I agree to dual-license this contribution
under MIT OR Apache-2.0, as certified by my DCO sign-off.

Summary by Sourcery

Enforce and document stricter protocol and transport guarantees around HTTP credentials and error codes, introduce a conformance registry and downstream canary tooling ahead of the 1.0 freeze, and add automated, gated publishing workflows for crates and SDKs.

New Features:

• Add bearer credential support for HTTP providers with redacted rendering and explicit Unauthorized handling, plus loopback-only plaintext allowance and refusal of insecure non-loopback transports.
• Introduce a conformance registry and badge for providers, including initial entry for the bundled example provider and guidance on how to get listed.
• Add explicit error codes for unsupported representations and incompatible protocol versions, wiring them through host errors so callers can react structurally.
• Extend the protocol spec with usage-reporting requirements and a deferred sketch for multi-hop graph traversal, and align documentation around these semantics.
• Expose a host API for adding HTTP providers with optional credentials and re-export the new Credential type.

Enhancements:

• Tighten malformed-input conformance checks to require a structured bad_request code rather than accepting arbitrary errors, with new fixture behavior and tests.
• Preserve provider error codes through HostError so hosts can distinguish structured provider failures instead of relying on free-form messages.
• Clarify schema $id hosting and validation strategy to point at a resolvable GitHub-raw URL while keeping the site mirror byte-identical as future hosting is wired.
• Document and partially automate downstream canary builds for stella and (future) oxagen to detect breaking changes against external consumers before releases.
• Clarify host reactions and retry semantics for new and existing ErrorCode variants, including permanent drop behavior for incompatible version handshakes.

Build:

• Add a crates.io dry-run CI job to ensure contextgraph-types still packages cleanly for publishing.
• Introduce a tag-triggered Release workflow that publishes crates to crates.io in dependency order, waiting for index propagation between steps.
• Add a guarded publish-sdks workflow and detailed SDK publishing guide covering npm, PyPI, and Go module release flows and safety constraints.
• Add helper scripts for waiting on crate index propagation and for running downstream canary builds of stella against a local CGP checkout.

CI:

• Add downstream-canary workflow to build and test stella (and stub out oxagen) against this repository’s HEAD on schedule and relevant PRs, reporting failures as advisory warnings.
• Wire SDK and crate publish workflows to GitHub Environments and secrets so that publishing is gated on manual approval and presence of credentials, never happening on tag push alone.

Documentation:

• Document the conformance registry, submission process, and usage of the static conformant badge in both Rust and site docs.
• Update SPEC and protocol-surface docs with usage-report (UR1) semantics, clarify HTTP transport rules C7/C8 conformance status, and describe deferral of multi-hop traversal.
• Expand provider implementation docs with guidance on getting listed in the registry and clarify adaptive-context reconciliation and downstream canary behavior.
• Add publishing guidance for the Rust crates and each SDK, including CI-driven release paths, environment setup, and one-way-door caveats.
• Add crates.io and docs.rs badges to root and per-crate READMEs, and clarify SDK README status for not-yet-published Python and Go packages.

Tests:

• Add unit tests for HTTP transport security and credential handling, including loopback plaintext allowance, non-loopback refusal, bearer header attachment, and redacted credential rendering.
• Strengthen conformance tests for malformed input handling, including a mislabelled-malformed case to ensure only bad_request is accepted for malformed lines.

Chores:

• Add a static conformant SVG badge and a captured conformance report asset under the site’s public tree for use by the registry and external READMEs.
• Adjust various call sites to the updated Host::add_http / HttpProvider APIs and error shapes to accommodate credentials and structured error codes.

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[sourcery-ai]

Reviewer's Guide

Implements HTTP transport hardening and credential redaction in the host, wires through structured error codes, and adds CI + documentation scaffolding for publishing crates/SDKs and tracking conformant providers and downstream consumers ahead of the protocol freeze.

File-Level Changes

Change	Details	Files
Harden HTTP provider transport by enforcing TLS for non-loopback hosts and supporting optional bearer credentials with full redaction guarantees.	Introduce a Credential wrapper type whose Debug/Display render as a fixed redacted placeholder and are only exposable via a crate-private method for header attachment. Add loopback host detection and a refuse_insecure_transport guard that rejects plaintext http:// URLs to non-loopback hosts with a new HostError::InsecureTransport before any network I/O. Extend HttpProvider to carry an optional Credential, add a connect_with_auth constructor, and ensure every HTTP exchange (handshake, query, verify, shutdown) attaches the bearer token via reqwest::RequestBuilder::bearer_auth when present. Update post_envelope to take an optional Credential, attach Authorization headers, and translate HTTP 401 into a typed HostError::Unauthorized; propagate provider error codes through HostError::Provider. Add targeted unit tests verifying C7/C8 semantics: refusing non-loopback plaintext, allowing loopback, attaching Authorization correctly, and ensuring credentials never appear in debug output or surfaced HostError strings.	contextgraph-host/src/http.rs contextgraph-host/src/error.rs contextgraph-host/src/host.rs contextgraph-host/src/stdio.rs
Tighten conformance behavior and error semantics, especially around malformed input handling and structured ErrorCode mapping.	Refine the malformed-input-tolerance conformance check to require a bad_request ErrorCode (not just any error) when a provider rejects malformed input, and treat other codes as failures. Add new ErrorCode variants (UnsupportedRepresentation, IncompatibleVersion) and map them to appropriate HostReaction values, including a new DropProvider reaction for permanent incompatibility. Update ErrorCode tests to cover new variants and non-retryability semantics, and ensure they serialize/deserialize correctly. Extend conformance fixtures to support a MislabelMalformed misbehavior mode and add a test that such providers fail malformed-input-tolerance while still passing handshake.	contextgraph-conformance/src/lib.rs contextgraph-conformance/src/bin/contextgraph-example-docs.rs contextgraph-conformance/tests/conformance_suite.rs contextgraph-types/src/error_code.rs
Introduce a conformance registry and guidance for getting providers listed, including a static badge asset and corresponding site/docs wiring.	Add docs/registry.md and site/content/docs/registry.mdx describing the registry, listing the bundled contextgraph-example-docs provider with a captured JSON report, and documenting the submission process and badge usage. Add a static conformant.svg badge and publish the captured example-docs conformance report under site/public/registry. Link the registry from the main docs index pages and extend provider-implementation docs with a "Getting listed once you're green" section and badge instructions. Update the PR template with a Registry submission checklist requiring an exact, reproducible contextgraph-inspect --json invocation and all-pass report before adding rows.	docs/registry.md site/content/docs/registry.mdx site/public/badges/conformant.svg site/public/registry/contextgraph-example-docs.report.json docs/implementing-a-provider.md site/content/docs/implementing-a-provider.mdx .github/PULL_REQUEST_TEMPLATE.md docs/index.md site/content/docs/index.mdx
Document and automate crate and SDK publishing, including a tag-triggered crates.io release workflow, SDK registry workflows, and dry-run CI.	Add PUBLISHING.md guidance for using a tag-triggered GitHub Actions Release workflow that publishes contextgraph-types -> contextgraph-host -> contextgraph-conformance in dependency order, including a wait-for-crate sparse-index poller script. Add sdk/PUBLISHING.md documenting npm, PyPI, and Go module release procedures, one-way-door constraints, and post-publish verification steps; clarify that TypeScript is already published while Python/Go are not. Introduce publish-sdks.yml that separates credential-free verify-* jobs (build + conformance) from manual, environment-gated publish-* jobs for npm and PyPI, ensuring tag pushes alone cannot publish and refusing to run without required secrets. Add a publish-dry-run job to CI that runs cargo publish --dry-run -p contextgraph-types on every PR as a cheap packaging sanity check. Update SDK and crate README files with crates.io/docs.rs badges and "not yet published" notes where applicable, and clarify manual vs workflow-driven tag ordering in PUBLISHING docs.	PUBLISHING.md sdk/PUBLISHING.md .github/workflows/release.yml .github/workflows/publish-sdks.yml .github/workflows/ci.yml .github/scripts/wait-for-crate.sh README.md contextgraph-types/README.md contextgraph-host/README.md contextgraph-conformance/README.md sdk/README.md sdk/python/README.md sdk/go/README.md
Clarify and extend SPEC and surrounding docs regarding usage reports, traversal deferral, HTTP transport guarantees, attribution, and downstream canary CI.	Add SPEC §7.3 describing usage reports and define UR1, and update references in context-reuse.md and protocol-surface.md from U1 to UR1. Add SPEC §8.3 explicitly deferring multi-hop traversal to a post-1.0 additive minor, and introduce docs/sketches/context-neighbors.md with a concrete design sketch consistent with G4 anchoring. Update SPEC §10 verification section to record that C7 (TLS for non-loopback) and C8 (credential non-logging) are now enforced and unit-tested, while live TLS-peer conformance remains future work; also clarify bad_request expectations for malformed input handling. Adjust attribution requirement A1 in SPEC to reference usage reports §7.3 and add explanatory notes in adaptive-context-reconciliation docs and ADR 0007 about the new downstream-canary workflow. Introduce schema/validate-examples.py commentary and behavior for an interim $id pointing at the GitHub raw schema URL, while keeping a byte-identical copy under site/public/schema for future domain hosting fixes.	SPEC.md docs/context-reuse.md docs/protocol-surface.md docs/adaptive-context-reconciliation.md docs/adr/0007-protocol-product-boundary.md docs/sketches/context-neighbors.md schema/validate-examples.py
Add downstream canary CI to detect breaking changes in known consumers, with stella wired today and oxagen reserved for future integration.	Add downstream-canary.yml workflow that periodically and on relevant PRs builds stella against this repo’s HEAD via a local Cargo [patch], treating failures as advisory warnings and summarizing them in the job output. Provide .github/scripts/downstream-canary-stella.sh to auto-discover contextgraph-* crates in this repo, patch stella’s Cargo.toml accordingly, identify dependent stella crates, and run cargo build/test on them. Stub an oxagen-canary job that will check private oxagen-platform fixtures once a cross-org token is configured, currently emitting a notice when the token is absent and asserting fixture layout when present.	.github/workflows/downstream-canary.yml .github/scripts/downstream-canary-stella.sh docs/adaptive-context-reconciliation.md docs/adr/0007-protocol-product-boundary.md

---

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

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.