feat(context): build deterministic ecosystem graph

Merged
TH
3mo ago
+1119-7

Stack

CF-11G implementation Stack B for tasks T020-T026.

Base PR: #21 (impl/cf11g-lock-v2-resolved-edges)
Planning PR: #20

Summary

Build the deterministic ecosystem Context Graph library on top of exact lock-v2 dependency evidence.

This stack deliberately ships the graph model and extraction engine before the CLI surface so the graph contract can be reviewed independently.

Changes

  • add library-owned deterministic Context Graph schema v1;
  • preserve exact package identity (name, version, sha256) and source provenance;
  • map lock-v2 exact package dependency edges into graph evidence;
  • read cache bytes through a verified single-read boundary;
  • reuse bounded CF-02 package inspection and archive scanning;
  • add canonical artifact nodes with exact owner package/archive/resource digests;
  • extract V1 canonical references from:
    • StructureDefinition baseDefinition;
    • differential type profile[] / targetProfile[];
    • differential binding valueSet;
    • ValueSet include/exclude system and valueSet[];
    • CodeSystem supplements;
  • retain exact source canonical strings and source paths;
  • resolve in-closure targets only as explicit resolved, external, or ambiguous states;
  • strip fragments only for matching, never from source evidence;
  • expose deterministic extraction coverage for present unsupported resource types;
  • reject schema-v1 graph construction instead of inferring missing multi-version package edges;
  • add deterministic, ambiguity, external-target, malformed-shape, and corrupted-cache tests.

Trust boundary

Graph construction is offline and cache-only. It performs no registry acquisition or network canonical lookup.

No graph database, new Rust dependency, vector search, AI authority, CF-06 pin change, frozen CF-10 corpus mutation, or CF-12 implementation is introduced.

Required qualification

Keep Draft until exact-head:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features

and existing ci, cf06-oracle, cf11-multi-version-proof, deterministic graph fixtures, and independent review are inspected.

Summary by cubic

Builds a deterministic, offline Context Graph library that resolves FHIR canonical references from lock‑v2 evidence. Requires schema v2 and fails closed on cache or resource errors; schema v1 now refuses to serialize when resolved_dependencies are present to prevent mixed-format locks.

  • New Features

    • Adds schema v1 graph model and exports build_context_graph with typed nodes and edges.
    • Preserves exact package identity (name, version, sha256) and source provenance.
    • Emits artifact nodes with canonical URL/version and resource digests; retains exact source paths/strings.
    • Extracts and deterministically resolves references from StructureDefinition, ValueSet, and CodeSystem with explicit Resolved/External/Ambiguous states.
    • Reports extractor coverage and unsupported resource types, and enforces a single verified cache read via PackageCache::read_verified (graph is cache-only and offline).

  • Bug Fixes

    • Schema v1 lock serialization now rejects resolved_dependencies instead of emitting invalid v1 files.

Summary by CodeRabbit

  • New Features
    • Added context graph generation from lockfile packages and cached artifacts.
    • Added package, artifact, dependency, and canonical reference tracking with resolution statuses and coverage details.
    • Added JSON serialization for context graph reports.
    • Added structured validation errors for invalid resources, malformed references, and artifact mismatches.
  • Bug Fixes
    • Centralized verified cache reads and integrity validation for cached packages.
    • Schema v1 serialization now rejects unsupported resolved dependency data instead of silently omitting it.