diff --git a/docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md b/docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md index 293e8d73..fbd153cf 100644 --- a/docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md +++ b/docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md @@ -119,6 +119,20 @@ Any future source profiler that touches instances must be a separate on-premises Each CF slice is a Spec Kit-style feature unit with `spec.md`, `plan.md`, and `tasks.md`, followed by consistency analysis, implementation, deterministic evidence, and a convergence pass. The specification states **what/why**; the plan states **how**; tasks are independently verifiable work items. Feature architecture must not be smuggled into the constitution or treated as completed merely because documentation exists. +## Roadmap identity reconciliation + +Canonical execution used `CF-11` for the multi-version package-graph foundation correction required to represent real transitive FHIR package closures. That completed history is retained exactly and is not renamed. + +The ecosystem Context Graph originally planned under numeric CF-11 still remains a required prerequisite for `CF-12 commandf impact`. To restore that missing product capability without rewriting history or shifting every downstream identifier, the graph-gap restoration slice is named: + +```text +CF-11G = ecosystem Context Graph + `commandf context` +``` + +`CF-11G` is a product slice identity. Its Spec Kit package uses sequence `012` only because that is the next available spec-directory sequence. CF-12 and later product identifiers remain unchanged. + +The graph slice consumes exact multi-version package identity from canonical CF-11 and canonical artifact inspection from CF-02. It does not depend on the external CF-06/CF-10 HL7-maintainer gate. + ## First execution stack | Slice | User-visible result | Depends on | @@ -133,12 +147,13 @@ Each CF slice is a Spec Kit-style feature unit with `spec.md`, `plan.md`, and `t | CF-08 | GitHub Action + annotations | CF-05 | | CF-09 | FSH source mapping | CF-08 | | CF-10 | public real-IG delta corpus | CF-06, CF-07 | -| CF-11 | ecosystem context graph | CF-02 | -| CF-12 | `commandf impact` | CF-11 | +| CF-11 | multi-version package graph foundation correction | CF-01 | +| CF-11G | ecosystem Context Graph + `commandf context` | CF-02, CF-11 | +| CF-12 | `commandf impact` | CF-11G | | CF-13 | baselines/suppression/quality gates | CF-05 | | CF-14 | on-prem aggregate-only source profiler | CF-02 | | CF-15 | verified dry-run recipes | CF-04, CF-09 | -| CF-16 | mapping analysis IR, parse-only | CF-11 | +| CF-16 | mapping analysis IR, parse-only | CF-11G | ## Mandatory acceptance gates diff --git a/specs/012-cf-11g-ecosystem-context-graph/consistency.md b/specs/012-cf-11g-ecosystem-context-graph/consistency.md new file mode 100644 index 00000000..3612873b --- /dev/null +++ b/specs/012-cf-11g-ecosystem-context-graph/consistency.md @@ -0,0 +1,211 @@ +# CF-11G Consistency Analysis — Ecosystem Context Graph + +Status: PASS / planning consistency closed + +## Inputs reviewed + +- `AGENTS.md`; +- `.specify/memory/constitution.md`; +- `docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md`; +- `docs/COMMAND_F_DISCOVERY_COVERAGE_2026-08-13.md`; +- canonical CF-11 multi-version package-graph `spec.md` and `plan.md`; +- current `Lockfile` schema-v1 implementation; +- current resolver implementation; +- current CF-02 `PackageInspection` / `ResourceArtifact` model; +- current CLI command surface; +- issue #19 roadmap reconciliation boundary. + +## Roadmap contradiction + +### Observed + +The Master Architecture originally assigned: + +```text +CF-11 = ecosystem context graph +CF-12 = commandf impact +``` + +Canonical execution later used CF-11 for the multi-version package-graph foundation correction, and that work is already merged/history-bearing. + +### Resolution + +Use `CF-11G` as the graph-gap restoration identity. + +Properties of this decision: + +- completed CF-11 history is not renamed or rewritten; +- CF-12 remains `commandf impact`; +- CF-13..CF-16 do not shift; +- the next Spec Kit sequence is `012`, but sequence number and product slice identity are explicitly separate; +- mapping IR work that requires the Context Graph depends on CF-11G rather than the historical numeric CF-11 alone. + +Result: PASS. + +## Vertical-slice check + +### Constitution requirement + +Every feature must produce a user-visible command, report, annotation, or independently executable verification result. + +### Resolution + +CF-11G ships `commandf context` with deterministic JSON graph output. The graph is independently inspectable before `commandf impact` exists. + +Result: PASS. + +## Determinism check + +### Risk + +Resolver traversal and graph extraction can inherit queue/hash/input ordering. + +### Resolution + +- exact resolved dependency edges are stored canonically; +- public graph collections use stable explicit sort keys; +- repeat-run byte equality is an acceptance criterion; +- root-order permutation is tested for both lock-v2 and graph output. + +Result: PASS. + +## Multi-version provenance check + +### Risk + +Schema-v1 locks cannot always reconstruct exact parent→child edges when multiple concrete versions satisfy similar constraints. + +### Resolution + +- new resolver runs write schema v2 with exact resolved edge evidence; +- existing commands keep valid v1 compatibility; +- `commandf context` fails closed on v1 instead of guessing. + +Result: PASS. + +## Backward-compatibility check + +### Risk + +A lock schema bump could unnecessarily invalidate existing user workflows. + +### Resolution + +Schema-specific decoding retains v1 support for commands that do not require exact resolved-edge evidence. Only the new Context Graph command requires v2. + +Result: PASS. + +## Canonical-resolution authority check + +### Risk + +An unversioned canonical URL can match multiple in-closure versions. Choosing one would create false graph authority. + +### Resolution + +The graph explicitly serializes `resolved`, `external`, and `ambiguous` target states. No first/newest/root-nearest heuristic is allowed. + +Result: PASS. + +## Extraction-completeness check + +### Risk + +FHIR contains more canonical/reference-bearing fields than the first graph slice can responsibly implement. Silently ignoring them while claiming a complete Context Graph would violate evidence rules. + +### Resolution + +CF-11G V1 has an explicit extractor contract for StructureDefinition, ValueSet, and CodeSystem dependency fields, while all present unsupported source resource types are listed in deterministic coverage metadata. Artifact nodes may exist without a claim of complete outgoing-edge extraction. + +Result: PASS. + +## Snapshot/differential check + +### Risk + +Extracting all element references from generated StructureDefinition snapshots can duplicate inherited dependencies and present them as local declarations. + +### Resolution + +Use top-level `baseDefinition` plus differential element profile/targetProfile/binding references in V1. This gives author-local dependency evidence without snapshot inheritance inflation. + +Result: PASS. + +## Storage-architecture check + +### Master Architecture constraint + +Graph-plane persistence should be relational-first unless measurement justifies a graph database. + +### Resolution + +CF-11G does not introduce a database at all. Its canonical output is a normalized deterministic relation set in JSON. If a persisted index becomes necessary for CF-12, embedded relational storage is the first candidate. Graph databases/vector stores require later evidence. + +Result: PASS. + +## Dependency check + +### Risk + +Adding a graph crate/database before a shipped consumer would violate repository dependency discipline. + +### Resolution + +The plan prefers no new Rust dependency. Existing serde, archive, digest, and deterministic collection facilities are sufficient for CF-11G V1. + +Result: PASS. + +## Trust-boundary check + +### Risk + +Graph build could accidentally become a second package acquisition path or bypass archive bounds. + +### Resolution + +`commandf context` is cache-only/offline, verifies lock digests, and reuses the CF-02 bounded archive inspection boundary. No registry lookup participates in graph construction. + +Result: PASS. + +## CF-06 / CF-10 independence check + +### Risk + +The blocked upstream HL7-maintainer path could become an accidental prerequisite or motivate a semantic workaround. + +### Resolution + +CF-11G depends only on canonical package/canonical inspection foundations. It does not change CF-06 oracle identity, reinterpret oracle failures, or modify the frozen CF-10 corpus. + +Result: PASS. + +## CF-12 sequencing check + +`commandf impact` requires a working graph. Tasks explicitly prohibit CF-12 implementation until CF-11G convergence closes. + +Result: PASS. + +## Open design questions + +No blocking design ambiguity remains for implementation start. + +Implementation may refine Rust type names and private module boundaries provided it does not change these normative contracts: + +- explicit lock-v2 resolved-edge evidence; +- v1 backward compatibility for existing commands; +- v1 refusal for Context Graph build; +- deterministic graph JSON; +- explicit canonical target state; +- V1 extractor coverage; +- offline verified-cache boundary; +- no compatibility authority in CF-11G. + +## Final classification + +```text +SPEC_PLAN_TASKS_CONSISTENCY = PASS +ROADMAP_IDENTITY = CF-11G +IMPLEMENTATION_ORDER = T010 -> T011 -> T012 -> T020... +CF-12_ELIGIBLE = NO / requires CF-11G convergence +CF-06_PIN_CHANGE = NOT AUTHORIZED BY THIS SLICE +``` diff --git a/specs/012-cf-11g-ecosystem-context-graph/plan.md b/specs/012-cf-11g-ecosystem-context-graph/plan.md new file mode 100644 index 00000000..5cc8244b --- /dev/null +++ b/specs/012-cf-11g-ecosystem-context-graph/plan.md @@ -0,0 +1,329 @@ +# CF-11G Plan — Ecosystem Context Graph + +Status: planning candidate + +## Base and sequencing + +```text +repository: TheHalfMoon/commandF +planning base: 5bafce4f63537e0507e9b0708e1ebd8e22e3c463 +planning branch: docs/cf11g-context-graph-planning +historical CF-11: multi-version package graph / PR #13 +new product slice: CF-11G ecosystem context graph +next downstream slice: CF-12 commandf impact +``` + +CF-11G is independent of the blocked CF-10/HL7 upstream-maintainer path. It consumes canonical package/canonical inspection foundations already present in commandF and does not require a production oracle-pin decision. + +## Architectural decision + +### Keep historical numbering stable + +Do not rename completed CF-11 commits, specs, PRs, or evidence. Do not shift CF-12..CF-16 identifiers. + +Insert `CF-11G` as the graph-gap restoration slice. Spec Kit sequence `012` is a documentation/package sequence only and is not a product renumbering. + +### Ship a graph report, not a database scaffold + +The first Context Graph vertical slice is a deterministic normalized JSON relation set exposed by `commandf context`. + +No graph database is introduced. The report itself is the canonical evidence artifact. If CF-12 later needs indexed persistence, evaluate embedded relational storage first. This follows the Master Architecture's relational-first constraint without creating a storage dependency before a shipped query requires one. + +## Current-state constraints that drive the design + +### Lock schema v1 cannot prove exact multi-version dependency edges + +Current `Lockfile` schema v1 stores: + +- roots; +- exact locked packages; +- package digest/source; +- each manifest's declared dependency constraints. + +The current resolver selects exact `(name, version)` identities but the v1 lock does not retain which exact child identity was selected for each parent request. With multiple versions of one package name in the same closure, reconstructing that edge after the fact can be ambiguous. + +CF-11G therefore earns the explicit resolved-edge schema that CF-11 intentionally deferred until a shipped consumer required it. + +### CF-02 already owns artifact inspection + +Reuse the existing bounded package archive reader and `PackageInspection`/`ResourceArtifact` concepts. Do not build a second unbounded tar/JSON ingestion path. + +## Implementation shape + +### 1. Lock schema v2 + +Add a deterministic top-level relation such as: + +```text +resolved_dependencies: [ + { + from_name, + from_version, + to_name, + to_version, + declared_constraint + } +] +``` + +Exact field names may be refined during implementation, but the semantic contract is fixed: + +- parent and child exact package identities are explicit; +- declared dependency constraint is retained; +- collection ordering is canonical; +- duplicate identical edge records are deduplicated deterministically; +- source/digest identity remains on `LockedPackage` and is not copied inconsistently into each edge. + +#### Backward compatibility + +Implement a version-aware lock decoder. + +- v1 remains accepted by existing commands; +- v2 is emitted by new `pkg resolve` runs; +- `pkg verify` accepts both; +- graph construction requires v2 and produces a stable fail-closed error on v1. + +Avoid `#[serde(default)]` behavior that would make a v1 lock indistinguishable from a malformed v2 lock. Schema-specific validation must be explicit. + +### 2. Resolver edge capture + +Change the resolver queue from a bare `PackageRequest` to an internal pending request carrying optional exact parent identity plus the declared constraint that created the request. + +Processing order: + +1. deterministically select concrete version for the request; +2. form exact child identity; +3. if a parent exists, record the exact parent→child edge immediately; +4. if child identity was already expanded, stop there for this queue item; +5. otherwise acquire/verify/cache child package, record package node, and enqueue its dependencies with this child as parent. + +This preserves shared-child and cycle edges without repeated expansion. + +### 3. Context Graph model + +Add a library-owned model in `commandf-pkg`, not CLI-only ad hoc JSON. + +Recommended model families: + +```text +ContextGraphReport +ContextPackageNode +ContextArtifactNode +PackageDependencyEdge +CanonicalReferenceEdge +CanonicalTargetResolution +ContextCoverage +``` + +All public collections sort by stable explicit keys before serialization. + +### 4. Artifact extraction + +For each locked package: + +1. verify cache digest; +2. load the archive through existing bounded inspection helpers; +3. create artifact nodes from CF-02 metadata; +4. inspect the same bounded resource JSON for only the V1 reference extractors defined in `spec.md`; +5. retain exact source canonical strings and deterministic relation labels. + +Do not normalize or dereference canonical URLs through the network. + +### 5. Canonical target matching + +Build a deterministic in-closure canonical index keyed by canonical URL and optional canonical version. + +For each extracted reference: + +- exact `url|version` + one candidate → `resolved`; +- unversioned URL + one candidate → `resolved`; +- no candidate → `external`; +- more than one candidate → `ambiguous`, with candidates sorted by exact package/artifact identity. + +Do not use package order, root distance, publication recency, or semantic guessing to choose among ambiguous candidates. + +### 6. Coverage metadata + +The report must distinguish: + +- supported source resource types with active extractors; +- resource types present in the closure but not covered by a canonical-reference extractor; +- extractor schema/version. + +This prevents a partial V1 graph from being mistaken for exhaustive FHIR dependency coverage. + +### 7. CLI + +Add: + +```text +commandf context \ + --lock commandf.lock \ + --cache .commandf/cache \ + --format json +``` + +Behavior: + +- reads only local lock/cache inputs; +- validates lock schema and package cache before graph extraction; +- writes canonical JSON to stdout; +- exits nonzero on invalid lock, schema-v1 graph request, missing/corrupt cache content, malformed required package content, or graph invariant violation; +- never performs package acquisition. + +No output file flag is required in this slice; shell redirection is sufficient and keeps the CLI surface small. + +## Security and trust boundaries + +### Package/archive boundary + +Reuse CF-01/CF-02 archive controls. The graph implementation must not call a raw tar reader with looser limits. + +### Provenance boundary + +A graph edge is evidence only when its origin is reconstructable from pinned lock/archive bytes. No mutable registry lookup participates in graph build. + +### Canonical resolution boundary + +`resolved` means "uniquely matched inside this exact closure", not "globally authoritative canonical owner". + +`external` means not found inside the closure, not invalid. + +`ambiguous` is retained as evidence and must remain fail-closed for downstream claims. + +### Data boundary + +This slice processes public/synthetic FHIR conformance metadata only. No patient instances or PHI. + +## Dependency policy + +Prefer no new Rust dependency for CF-11G. + +Existing serde/JSON, archive, digest, semver, and deterministic collection facilities are sufficient for the first graph report. Do not add SQLite, petgraph, Oxigraph, Qdrant, RDF, or vector-search dependencies in this slice. + +A future persisted relational index may add one embedded relational dependency only when a shipped CF-12 query requires it and the relevant PR exercises it immediately. + +## Test strategy + +### Resolver/lock unit and integration tests + +- v2 exact edge recording; +- multiple same-name versions with correct branch-local edges; +- shared child edge retention; +- cycle closing edge retention + bounded expansion; +- root-order byte identity; +- v1 decode compatibility; +- malformed v2 missing/inconsistent edge fields fail closed; +- `pkg verify` v1/v2 regression. + +### Graph model tests + +- deterministic node/edge ordering; +- duplicate edge deduplication; +- exact artifact provenance; +- stable JSON bytes. + +### Canonical extraction fixtures + +Create small synthetic/publicly redistributable package archives covering: + +- StructureDefinition profile + extension; +- `baseDefinition`; +- differential type `profile` and `targetProfile`; +- differential binding `valueSet`; +- ValueSet include/exclude systems and imported ValueSets; +- CodeSystem `supplements`; +- unsupported resource type coverage reporting. + +### Canonical resolution fixtures + +- exact versioned target; +- unique unversioned target; +- external target; +- ambiguous unversioned target where two canonical versions are present. + +### CLI tests + +- v2 success; +- v1 refusal; +- corrupted cache refusal; +- missing cache refusal; +- repeat-run byte equality; +- no network/source invocation during context build. + +### Regression gates + +At every implementation PR head: + +```text +cargo fmt --all -- --check +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test --workspace --all-features +``` + +Preserve existing CF-08/CF-09 security tests, real FHIR smoke, `cf06-oracle`, and `cf11-multi-version-proof` workflows. + +## PR stack + +Keep implementation stack independently reviewable: + +### PR A — resolved-edge evidence / lock v2 + +- version-aware lock decoding; +- v2 writer; +- resolver edge capture; +- backward compatibility tests. + +No Context Graph CLI yet, but this PR is immediately executable through `pkg resolve`/`pkg verify` and is required evidence plumbing for the shipped graph consumer stacked above it. + +### PR B — Context Graph library + +- deterministic graph model; +- bounded canonical extraction; +- target resolution + coverage metadata; +- fixture tests. + +### PR C — `commandf context` + +- CLI surface; +- end-to-end graph build; +- deterministic output proof; +- negative cache/schema paths; +- workflow/regression qualification. + +Do not merge PR A alone to main unless PR B/C exact candidate stack is ready or the maintainer explicitly decides the lock-v2 migration is independently desirable. This prevents an unused schema migration from becoming canonical by accident. + +## Review focus + +1. any inferred package edge not directly recorded during resolver selection; +2. v1/v2 decoder ambiguity; +3. silent first-match canonical resolution; +4. snapshot-inheritance edge inflation presented as local declaration; +5. unsupported resource types hidden from coverage metadata; +6. traversal/hash-order nondeterminism; +7. archive/cache trust-boundary bypass; +8. accidental network access during graph build; +9. graph state presented as compatibility authority; +10. downstream API choices that make CF-12 require semantic guessing. + +## Migration impact + +New `pkg resolve` lock bytes change from schema v1 to v2. This is intentional and must be explicitly called out in release notes/convergence evidence. + +Existing valid v1 locks remain supported for existing commands, so users are not forced to regenerate locks unless they want `commandf context`. + +## Exit criteria + +CF-11G can converge only when: + +- roadmap reconciliation is canonical; +- spec/plan/tasks consistency is closed; +- all implementation tasks are complete; +- exact-head mandatory CI is green; +- lock v2 deterministic migration evidence is retained; +- Context Graph repeat runs are byte-identical; +- all ambiguity/external/unsupported states are explicit; +- CodeRabbit and Qodo findings are dispositioned when available; +- convergence identifies no untracked blocker for CF-12. + +Only then may CF-12 `commandf impact` begin implementation. diff --git a/specs/012-cf-11g-ecosystem-context-graph/spec.md b/specs/012-cf-11g-ecosystem-context-graph/spec.md new file mode 100644 index 00000000..666729b1 --- /dev/null +++ b/specs/012-cf-11g-ecosystem-context-graph/spec.md @@ -0,0 +1,229 @@ +# CF-11G Specification — Ecosystem Context Graph + +Status: planning candidate + +## Identity and roadmap role + +`CF-11G` is the gap-restoration slice for the ecosystem Context Graph originally planned as CF-11 in `docs/COMMAND_F_MASTER_ARCHITECTURE_V2.md`. + +Canonical repository history already used `CF-11` for the multi-version package-graph foundation correction merged in PR #13. That history remains unchanged. `CF-11G` does not renumber or reinterpret completed CF-11 work, and it does not shift downstream product identities: `CF-12` remains `commandf impact` and depends on a working CF-11G Context Graph. + +Spec Kit sequence directory `012-*` is only the next available planning-package sequence; the product slice identity is `CF-11G`. + +## Problem + +commandF can resolve exact package identities, inspect canonical FHIR artifacts, and diff/check individual packages, but it cannot yet answer deterministic cross-artifact dependency questions. + +Two foundation facts make a Context Graph require explicit evidence rather than reconstruction by guesswork: + +1. CF-11 permits multiple concrete versions of the same package name in one closure. +2. `commandf.lock` schema v1 stores each package manifest's declared dependency constraints but does not store the exact parent-to-child resolved dependency edges selected during traversal. + +For a patch wildcard or other branch-local request, a v1 lock containing multiple matching concrete package versions is therefore insufficient to reconstruct which exact child identity was selected for a specific parent. A graph built by choosing the first or highest matching locked version would violate commandF's provenance and fail-closed rules. + +Likewise, canonical references such as an unversioned `StructureDefinition.baseDefinition` may resolve to zero, one, or multiple in-closure canonical artifacts. The graph must retain that state explicitly rather than silently selecting a target. + +## User-visible outcome + +A new command: + +```text +commandf context --lock commandf.lock --cache .commandf/cache --format json +``` + +builds a deterministic Context Graph report from one verified package closure. + +The report is independently useful before CF-12. It provides exact package nodes, canonical artifact nodes, resolved package-dependency edges, supported canonical-reference edges, explicit unresolved/ambiguous target state, extraction coverage, and source provenance. + +Identical pinned lock/cache inputs MUST produce byte-identical JSON output. + +## Normative behavior + +### 1. Exact package identities + +Every package node is identified by: + +```text +(name, concrete version, archive sha256) +``` + +The graph MUST preserve the package source/provenance already recorded by the lockfile. + +### 2. Explicit resolved dependency evidence + +New package resolutions MUST record the exact parent-to-child package identity selected for every dependency request, together with the declared dependency constraint that caused that edge. + +The resolver MUST record an edge even when the selected child package was already present and therefore does not need to be downloaded or expanded again. + +Cycles MUST terminate by exact-identity expansion deduplication while retaining the cycle edge itself. + +### 3. Lockfile migration boundary + +The explicit resolved-edge evidence requires a lock schema revision. + +- New `pkg resolve` output MUST use lock schema v2. +- Schema v2 MUST retain all v1 package identity, digest, source, root, and declared dependency information. +- Existing commands that do not require explicit graph edges MUST continue to read valid schema-v1 locks. +- `pkg verify` MUST continue to verify all package digests for valid v1 and v2 locks. +- `commandf context` MUST fail closed on schema v1 because exact package dependency edges cannot always be reconstructed from it. +- No command may silently synthesize v2 edge evidence from an ambiguous v1 lock. + +### 4. Canonical artifact nodes + +For every verified locked package archive, CF-11G MUST reuse the CF-02 artifact inspection boundary to identify FHIR resources and retain at least: + +- owning package exact identity; +- archive digest; +- resource filename; +- resource type; +- resource id when present; +- canonical URL when present; +- canonical version when present; +- resource content SHA-256. + +Multiple versions of the same canonical URL are distinct artifact nodes. + +### 5. Canonical reference edges — V1 coverage + +CF-11G V1 MUST deterministically extract the following dependency relations from supported FHIR conformance resources: + +#### StructureDefinition (including profiles and extensions) + +- `baseDefinition`; +- differential `element[].type[].profile[]`; +- differential `element[].type[].targetProfile[]`; +- differential `element[].binding.valueSet`. + +Differential elements are used for element-level profile/binding references to avoid silently treating every inherited snapshot constraint as a newly declared local dependency. The top-level `baseDefinition` remains an explicit edge. + +#### ValueSet + +- `compose.include[].system`; +- `compose.include[].valueSet[]`; +- `compose.exclude[].system`; +- `compose.exclude[].valueSet[]`. + +#### CodeSystem + +- `supplements` when present. + +Resources outside this extractor set MAY still appear as artifact nodes, but the report MUST expose their resource types in deterministic extraction-coverage metadata. Unsupported resource types MUST NOT be presented as fully analyzed canonical-reference sources. + +### 6. Canonical reference target resolution + +Canonical reference strings MUST be preserved exactly as source evidence. commandF MUST NOT perform network lookup or mutable-registry resolution during `context`. + +For graph matching only: + +- `url|version` targets an exact in-closure canonical URL + canonical version when exactly one exists; +- unversioned `url` resolves when exactly one in-closure artifact has that canonical URL; +- zero matches are retained as `external` / unresolved-in-closure edges; +- multiple eligible matches are retained as `ambiguous` edges with deterministic candidate identities; +- commandF MUST NOT silently pick the first, newest, root-nearest, or otherwise preferred candidate. + +Fragments and source strings MUST be retained; any supported parsing rule must be explicit and tested. + +### 7. Deterministic relational graph representation + +The canonical JSON report MUST use normalized sorted collections rather than relying on traversal or hash-map order. At minimum it contains deterministic relations equivalent to: + +```text +packages +artifacts +package_dependency_edges +canonical_reference_edges +coverage +``` + +CF-11G does not introduce a graph database. If CF-12 demonstrates a need for indexed persistent storage, the Master Architecture's relational-first rule applies: embedded relational storage is the first candidate, and a graph database requires measurement-based justification. + +### 8. Cache and trust boundary + +`commandf context` MUST be offline with respect to package acquisition. + +Before reading an archive, it MUST verify the cached bytes against the lockfile SHA-256 using the existing package-cache trust boundary. Missing or corrupted required archive bytes MUST fail the command. + +No PHI or instance data is required or accepted by this slice. + +### 9. Bounded input behavior + +Existing archive size, entry-count, path, decompression, and JSON safety bounds MUST remain authoritative. CF-11G MUST NOT add an unbounded second archive reader or bypass existing package inspection protections. + +### 10. Downstream authority boundary + +CF-11G records deterministic dependency evidence. It does not itself classify a change as breaking, risky, additive, clinically safe, or semantically equivalent. + +`CF-12 commandf impact` may consume the graph later, but must preserve explicit `external` and `ambiguous` states rather than converting them to compatibility claims. + +## Acceptance criteria + +### A. Multi-version exact edge proof + +A synthetic closure where two parents request different concrete versions of the same dependency name MUST contain two exact package nodes and the correct parent-to-child resolved edge for each request. + +### B. Shared identity edge proof + +Two parents selecting the same concrete child identity MUST produce two dependency edges to one deduplicated child node. + +### C. Cycle proof + +A cycle MUST retain the closing dependency edge and terminate without repeated archive expansion. + +### D. V1 fail-closed proof + +Existing valid schema-v1 locks remain readable by existing commands, while `commandf context` rejects them with a stable diagnostic explaining that resolved-edge evidence is unavailable. + +### E. Canonical ownership proof + +A package containing multiple canonical resources MUST produce stable artifact nodes tied to the exact owning package identity and archive digest. + +### F. StructureDefinition edge proof + +Fixtures MUST cover `baseDefinition`, profile, targetProfile, and binding ValueSet edges, including an Extension StructureDefinition. + +### G. Terminology graph proof + +Fixtures MUST cover ValueSet system/valueSet references and CodeSystem supplements. + +### H. Target-state proof + +Fixtures MUST prove all three target states: exactly resolved, external/unresolved-in-closure, and ambiguous due to multiple in-closure canonical versions. + +### I. Coverage proof + +At least one unsupported resource type MUST remain an artifact node while appearing in explicit coverage metadata rather than being silently treated as fully analyzed. + +### J. Determinism + +Equivalent resolver root-order permutations and repeated `context` builds over identical bytes MUST produce byte-identical lock v2 and Context Graph JSON respectively. + +### K. Regression + +All existing workspace tests, security regressions, CF-06 oracle workflow, CF-11 multi-version proof, and real FHIR smoke gates remain green. + +## Explicit non-goals + +CF-11G does not: + +- implement `commandf impact` or blast-radius policy; +- change CF-03/04/05 compatibility classification; +- change CF-06 HL7 oracle identity or exception semantics; +- modify the frozen CF-10 corpus; +- crawl the public FHIR registry or internet to complete missing canonical references; +- introduce RDF/SPARQL, Oxigraph, Neo4j, Qdrant, embeddings, vector search, or AI authority; +- parse SQL-on-FHIR, CQL, SearchParameter expressions, or FHIRPath invariants yet; +- claim exhaustive FHIR canonical-reference extraction outside the explicit V1 extractor set; +- infer package dependency edges from schema-v1 constraints when exact resolved identity is not recorded. + +## Evidence and provenance + +Every graph report must be reconstructable from: + +- exact lock bytes/schema; +- exact package name/version identities; +- package archive SHA-256 values; +- recorded package source provenance; +- verified cached archive bytes; +- graph schema/extractor version. + +Mutable package aliases or registry state are not graph evidence. diff --git a/specs/012-cf-11g-ecosystem-context-graph/tasks.md b/specs/012-cf-11g-ecosystem-context-graph/tasks.md new file mode 100644 index 00000000..6bb07570 --- /dev/null +++ b/specs/012-cf-11g-ecosystem-context-graph/tasks.md @@ -0,0 +1,155 @@ +# CF-11G Tasks — Ecosystem Context Graph + +Status: planning candidate + +Tasks are dependency ordered. A task is complete only with executable evidence on the exact candidate state. + +## Planning and governance + +- [x] T001 — Reconcile slice identity without rewriting canonical CF-11 history. + - Product identity: `CF-11G`. + - Spec Kit sequence: `012`. + - `CF-12` remains `commandf impact` and depends on CF-11G. + - No CF-10/CF-06 production-oracle dependency is introduced. + +- [x] T002 — Define the user-visible vertical slice. + - Command: `commandf context --lock ... --cache ... --format json`. + - Output: deterministic package/artifact/reference graph report. + - Graph build is offline and evidence-only. + +- [x] T003 — Close spec/plan/tasks consistency before implementation. + - Record analysis in `consistency.md`. + - Any contradiction discovered during review reopens this task. + +## Stack A — explicit resolved package-edge evidence + +- [ ] T010 — Introduce explicit lock schema v2 model and version-aware decoding. + - Preserve roots, packages, digests, source provenance, and declared manifest dependency constraints. + - Add deterministic exact resolved dependency edge relation. + - Existing commands continue accepting valid schema-v1 locks. + - New resolver output writes schema v2. + - Malformed or unsupported schema states fail closed. + +- [ ] T011 — Capture exact parent→child dependency edges during resolver traversal. + - Record edge after concrete child selection and before expansion dedup short-circuit. + - Preserve declared constraint on edge evidence. + - Shared exact child identities remain one node with multiple parent edges. + - Cycle closing edges are retained while exact-identity expansion remains bounded. + +- [ ] T012 — Prove lock v2 determinism and v1 compatibility. + - Multi-version branch-local edge fixture. + - Shared-child fixture. + - Cycle fixture. + - Equivalent root-order byte identity. + - v1 read + verify regression. + - Existing inspect/diff/check/terminology/oracle v1 behavior remains supported. + +## Stack B — deterministic Context Graph library + +- [ ] T020 — Add library-owned Context Graph schema v1. + - Deterministic package nodes. + - Deterministic artifact nodes. + - Package dependency edges. + - Canonical reference edges. + - Explicit target resolution state. + - Explicit extraction coverage metadata. + - Stable pretty-JSON bytes with trailing newline. + +- [ ] T021 — Build artifact nodes through the existing bounded CF-02 inspection boundary. + - Verify each lock digest before reading archive bytes. + - Preserve exact owner package identity, archive digest, filename, resource type, canonical URL/version, resource SHA. + - No second unbounded archive path. + +- [ ] T022 — Implement StructureDefinition V1 reference extraction. + - top-level `baseDefinition`; + - differential `element[].type[].profile[]`; + - differential `element[].type[].targetProfile[]`; + - differential `element[].binding.valueSet`; + - cover both profile and extension StructureDefinitions. + +- [ ] T023 — Implement ValueSet and CodeSystem V1 reference extraction. + - ValueSet include/exclude `system` and imported `valueSet[]`; + - CodeSystem `supplements`. + +- [ ] T024 — Implement deterministic in-closure canonical target resolution. + - exact versioned unique target → `resolved`; + - unique unversioned target → `resolved`; + - no target → `external`; + - multiple eligible targets → `ambiguous` with sorted candidate identities; + - source canonical string retained exactly; + - no network lookup or preferred-candidate heuristic. + +- [ ] T025 — Expose explicit extraction coverage. + - Supported source resource types/extractor version. + - Present-but-unsupported resource types sorted deterministically. + - Unsupported types remain artifact nodes. + +- [ ] T026 — Prove Context Graph byte determinism and graph invariants. + - Repeat build on identical lock/cache bytes is byte-identical. + - Package/artifact/edge input-order permutations do not affect output. + - Duplicate identical edges deduplicate deterministically. + - No ambiguous target is serialized as resolved. + +## Stack C — shipped `commandf context` + +- [ ] T030 — Add `commandf context` CLI command. + - `--lock` path. + - `--cache` path. + - JSON-only format in V1. + - Canonical JSON to stdout. + - No package acquisition or registry access. + +- [ ] T031 — Enforce lock/cache fail-closed behavior at CLI boundary. + - schema-v1 context request rejects with stable migration diagnostic; + - missing archive rejects; + - corrupted archive rejects; + - malformed graph-required resource input rejects according to existing bounded parser policy; + - runtime diagnostic sanitization remains intact. + +- [ ] T032 — Add end-to-end graph fixtures. + - exact multi-version package edges; + - StructureDefinition profile + extension edges; + - ValueSet/CodeSystem edges; + - resolved/external/ambiguous canonical states; + - unsupported resource type coverage. + +- [ ] T033 — Add exact-head deterministic CLI proof. + - run `commandf context` twice from identical pinned fixture inputs; + - compare output bytes exactly; + - retain SHA-256 evidence in CI logs or artifact metadata. + +## Regression, review, and convergence + +- [ ] T040 — Run mandatory workspace gates on the exact final stack head. + - `cargo fmt --all -- --check`. + - `cargo clippy --workspace --all-targets --all-features -- -D warnings`. + - `cargo test --workspace --all-features`. + +- [ ] T041 — Preserve existing workflow gates. + - `ci`. + - `cf06-oracle`. + - `cf11-multi-version-proof`. + - existing real FHIR smoke and CF-08/CF-09 security regressions. + +- [ ] T042 — Independent review. + - CodeRabbit review when available. + - Qodo review when connected/available. + - Every substantive finding dispositioned on the exact candidate head. + +- [ ] T043 — Run convergence pass. + - Record final heads/trees/workflow runs. + - Record lock schema migration evidence. + - Record Context Graph output SHA-256/repeat equality. + - Append every remaining gap as a task or explicit deferral. + - Confirm `CF-12` is either eligible or blocked by an explicit remaining CF-11G gap. + +## Hard sequencing rules + +1. T010–T012 precede graph consumption because schema-v1 does not contain sufficient exact edge evidence. +2. T020 precedes extractor tasks. +3. T021 precedes graph-wide canonical resolution. +4. T022/T023 precede T024 because target resolution consumes extracted reference edges. +5. T020–T026 precede CLI shipping. +6. T030–T033 precede final regression/review/convergence. +7. `CF-12 commandf impact` MUST NOT begin implementation until T043 closes CF-11G canonical convergence. +8. The blocked external HL7 maintainer path does not block these independent tasks and must not be used to alter CF-06 production semantics implicitly.