Skip to content

docs(cf11g): close canonical convergence #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheHalfMoon merged 2 commits into from
Aug 26, 2026
+155 −299
Merged

docs(cf11g): close canonical convergence #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
047df5f
docs(cf11g): close canonical convergence
TheHalfMoon Aug 26, 2026
2383cdb
docs(cf11g): close convergence tasks
TheHalfMoon Aug 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
273 changes: 81 additions & 192 deletions specs/012-cf-11g-ecosystem-context-graph/convergence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,249 +1,138 @@
# CF-11G Convergence Evidence — Ecosystem Context Graph

Status: convergence candidate; final exact-head regression and independent-review gate still open
Status: CLOSED_CANONICAL — valid once this closeout PR passes its exact-head documentation-path gates and review, then merges without content changes.

Decision: `CF11G_IMPLEMENTATION_PROVEN_PENDING_FINAL_CONVERGENCE_GATES`

This document records the evidence accumulated for CF-11G before the final convergence-head qualification. It does not make the branch canonical, does not authorize merge by itself, and does not authorize CF-12 implementation.

## 1. Authority boundary

CF-11G remains an evidence-only, offline dependency graph slice.

It does not:

- classify compatibility, safety, clinical meaning, or semantic equivalence;
- perform package acquisition or network canonical resolution during `commandf context`;
- change CF-03/04/05 compatibility semantics;
- change the CF-06 production HL7 pin or oracle failure behavior;
- modify the frozen CF-10 corpus;
- introduce a graph database, vector store, RAG system, model authority, or agent authority;
- start CF-12 `commandf impact`.

CF-12 remains blocked until T043 is closed on a final exact head.

## 2. Canonical base and stacked implementation identity

Canonical `main` read during convergence preparation:
Decision:

```text
main commit = 5bafce4f63537e0507e9b0708e1ebd8e22e3c463
main tree = f0f009fe8abcab99b3a1d339d400b63af4a7b486
CF11G_CLOSED_CANONICAL
CF12_ELIGIBLE_AFTER_CLOSEOUT_MERGE
```

Stack snapshot before this convergence-document commit:
CF-11G is the deterministic, offline ecosystem Context Graph slice. It records evidence only; it does not classify compatibility, safety, clinical meaning, or semantic equivalence, and it does not change CF-06 oracle identity, the frozen CF-10 corpus, or any HL7 production pin.

| Stack | PR | Head | Tree | Purpose |
|---|---:|---|---|---|
| Planning | #20 | `190945b1b7665e8b01a2c3ce9f93cf2c5e23dd45` | `f9e274e743964ca4ad0b92e622fce6c901078fb2` | restore CF-11G prerequisite and freeze Spec 012 |
| Stack A | #21 | `40983be3bbd6aed098c18cae8f381cab0ed1826e` | `b3d9cac69f74a6f41ed77250aad3006aab98b035` | lock schema v2 and exact resolved dependency edges |
| Stack B | #22 | `1dce479f7e2b548109e8d2b99a928353639be4b6` | `67fb1cb71e9259d34ceaa989c798f9c239560f3f` | deterministic Context Graph library |
| Stack C | #23 | `fc1fd27e17720d449e7d2358acb620be7e301d47` | `1bb0198f32ecff9d404d8536a2e595e3e596f76a` | shipped offline `commandf context` and deterministic proof |

The stacks were advanced without force-push or rebase. A reviewer-discovered fail-closed repair was propagated to the downstream stack so the current library and CLI heads contain the same invariant.

## 3. Lock schema migration evidence

Stack A establishes schema v2 as the resolver output contract while retaining existing schema-v1 read compatibility for existing commands.

Proven properties include:

- schema v2 carries exact parent identity, child identity, and declared dependency constraint evidence;
- exact dependency edges are sorted and deduplicated deterministically;
- shared child identities retain multiple parent edges;
- cycle-closing edges are retained while exact-identity expansion remains bounded;
- malformed or unsupported lock schema states fail closed;
- schema-v1 locks remain readable by existing commands;
- `commandf context` rejects schema v1 because exact resolved-edge evidence is unavailable;
- schema-v1 serialization now fails closed if a caller constructs a v1 `Lockfile` with non-empty `resolved_dependencies`, preventing silent evidence loss.

The final point was added after independent review. Regression coverage is named:
## Canonical implementation chain

```text
schema_v1_refuses_to_serialize_resolved_dependency_evidence
Planning PR #20
head: 190945b1b7665e8b01a2c3ce9f93cf2c5e23dd45
merge: ffbcdaea9bcbcb31271d38dea83419a014558904

Stack A / PR #21 — lock schema v2 + exact resolved dependency edges
head: 40983be3bbd6aed098c18cae8f381cab0ed1826e
merge: 4bc5df2cfcb9437e1d4d84b19bc7ddca556d6996

Stack B / PR #22 — deterministic Context Graph library
head: 1dce479f7e2b548109e8d2b99a928353639be4b6
merge: 8b93a04d573f182e902d21d42ad54180d36d5223

Stack C / PR #23 — shipped commandf context CLI
final reviewed head: 1475a9d117f11dd5af3de6b118cd72fc8ccdfebd
merge: 7579309d6298998a0bad47bac080be156b4d80df
canonical tree: 160df0b89642e2588fddc17b5daed517c3689857
```

## 4. Context Graph evidence

Stack B implements deterministic graph evidence through the existing bounded package-inspection and package-cache trust boundaries.
No force-push or rebase was used to advance the stack.

The report contains deterministic evidence for:
## Final implementation-head regression evidence

- exact package nodes and exact resolved package dependency edges;
- artifact nodes tied to exact owning package identity, archive digest, filename, resource type, canonical URL/version when present, and resource SHA-256;
- StructureDefinition `baseDefinition`, profile, targetProfile, and binding ValueSet references;
- ValueSet include/exclude system and imported ValueSet references;
- CodeSystem `supplements` references;
- explicit extraction coverage for supported and present-but-unsupported resource types;
- canonical target states frozen by Spec 012: `resolved`, `external`, and `ambiguous`.

For canonical matching, `url|version` uses exact in-closure URL + version eligibility. Zero eligible matches are intentionally `external` / unresolved-in-closure under Spec 012 §6; no fourth version-mismatch state is introduced.

## 5. Shipped CLI evidence

Stack C ships:
Exact head `1475a9d117f11dd5af3de6b118cd72fc8ccdfebd` passed the complete required gate set:

```text
commandf context --lock commandf.lock --cache .commandf/cache --format json
ci 32844511038 SUCCESS
cf06-oracle 32844511085 SUCCESS
cf11-multi-version-proof 32844511014 SUCCESS
cf11g-context-proof 32844511055 SUCCESS
CodeRabbit status SUCCESS
```

The command:

- reads explicit lock/cache inputs;
- builds the library-owned deterministic Context Graph;
- writes canonical JSON to stdout;
- performs no package acquisition or registry lookup;
- fails closed for schema-v1 context requests, missing archives, corrupt archive digests, and malformed graph-required supported inputs.

End-to-end fixtures cover multi-version package edges, profile and Extension references, terminology references, all three frozen target states, and unsupported resource coverage.

## 6. Determinism proof
The `ci` workflow covers formatting, Clippy with warnings denied, workspace tests, CF-08/CF-09 security regressions, real FHIR smoke, terminology smoke, and local GitHub Action smoke.

Exact Stack C pre-convergence head `fc1fd27e17720d449e7d2358acb620be7e301d47` passed `cf11g-context-proof` run `32843775848`.
## Lock schema migration evidence

The proof environment used:
CF-11G makes schema v2 the output contract for new package resolutions while retaining valid schema-v1 read/verify compatibility for existing commands.

```text
Rust = 1.97.1
container = docker.io/library/rust@sha256:9146b0f62e1939989aa96fc8d89699a43c5635bf212819235a773e1a9e71a98f
checkout = actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
```
Schema v2 records deterministic exact parent→child dependency evidence including the original declared constraint. Shared children retain all parent edges; cycle-closing edges are retained while exact-identity expansion remains bounded. `commandf context` refuses schema v1 rather than reconstructing ambiguous multi-version edges.

The proof ran `commandf context` twice from identical pinned fixture inputs and compared stdout bytes exactly.
Independent review found one evidence-loss edge case in the v1 serialization path: a programmatically constructed schema-v1 `Lockfile` with non-empty `resolved_dependencies` could have discarded that evidence. The write path was repaired to reject the state fail-closed, and regression `schema_v1_refuses_to_serialize_resolved_dependency_evidence` covers the invariant. CodeRabbit confirmed the repair and resolved the thread.

Observed output identity:
## Context Graph contract

```text
CF11G_CONTEXT_SHA256=cbc08088a858ca12af0a2a773be5f4b02a03bc099442e59f7300f5edaca069c0
repeat equality = PASS
repository-clean assertion = PASS
```
The canonical graph implementation preserves:

The proof also uploaded the retained checksum evidence artifact successfully.
- exact package identity `(name, version, sha256)` and package source provenance;
- exact resolved package dependency edges;
- artifact ownership, archive digest, source path, resource type, canonical URL/version, and resource SHA-256;
- bounded StructureDefinition, ValueSet, and CodeSystem V1 canonical-reference extraction;
- deterministic extraction-coverage metadata for present unsupported resource types;
- exactly the frozen V1 target states `resolved`, `external`, and `ambiguous`;
- exact source canonical strings even when an explicit version has no eligible in-closure match;
- cache-only/offline graph construction with verified archive bytes.

## 7. Pre-convergence regression evidence
A CodeRabbit suggestion to add a fourth explicit-version-mismatch target status was not adopted because Spec 012 freezes zero exact eligible matches as `external` / unresolved-in-closure and Acceptance Criterion H freezes the three V1 states above. CodeRabbit rechecked the contract, agreed the original finding did not apply, and resolved the thread.

These are the exact-head runs that were green immediately before this convergence-document commit. Because this document changes the candidate head, T040/T041 remain open until the final convergence head reruns the applicable gates.
## Shipped CLI and deterministic proof

### Planning head — PR #20
Canonical user-visible command:

```text
head = 190945b1b7665e8b01a2c3ce9f93cf2c5e23dd45
ci = 32832888034 / SUCCESS
cf06-oracle = 32832888010 / SUCCESS
```

### Stack A — PR #21

```text
head = 40983be3bbd6aed098c18cae8f381cab0ed1826e
ci = 32843594591 / SUCCESS
cf06-oracle = 32843594634 / SUCCESS
cf11-multi-version-proof = 32843594609 / SUCCESS
commandf context --lock commandf.lock --cache .commandf/cache --format json
```

The `ci` job includes successful format, clippy, workspace tests, CF-08/CF-09 security regressions, real FHIR smoke, terminology smoke, and local GitHub Action smoke.
It performs no registry acquisition or network canonical resolution and fails closed for unsupported lock schema, missing cache archives, corrupt archive digests, and malformed graph-required supported inputs.

### Stack B — PR #22
Exact proof run `32844511055`, job `97791094780`, ran the CLI determinism proof in:

```text
head = 1dce479f7e2b548109e8d2b99a928353639be4b6
ci = 32843690946 / SUCCESS
cf06-oracle = 32843690704 / SUCCESS
cf11-multi-version-proof = 32843690836 / SUCCESS
Rust: 1.97.1
container: docker.io/library/rust@sha256:9146b0f62e1939989aa96fc8d89699a43c5635bf212819235a773e1a9e71a98f
checkout: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
```

### Stack C — PR #23
Observed canonical output identity:

```text
head = fc1fd27e17720d449e7d2358acb620be7e301d47
ci = 32843775881 / SUCCESS
cf06-oracle = 32843775904 / SUCCESS
cf11-multi-version-proof = 32843775886 / SUCCESS
cf11g-context-proof = 32843775848 / SUCCESS
CF11G_CONTEXT_SHA256=cbc08088a858ca12af0a2a773be5f4b02a03bc099442e59f7300f5edaca069c0
repeat byte equality: PASS
repository-clean assertion: PASS
```

## 8. Independent-review truth

Independent review has produced substantive findings, and each known substantive finding has an explicit disposition.

### PR #21 — schema-v1 serialization evidence loss

Finding: a public schema-v1 `Lockfile` state with populated `resolved_dependencies` could serialize through the v1 shape and silently drop edge evidence.

Disposition: **FIXED**.

The write path now rejects the state with the same fail-closed diagnostic used by the read path, and a regression test covers it. CodeRabbit confirmed the repair in-thread and the thread is resolved. The same invariant was propagated to #22 and #23.

### PR #22 — proposed fourth canonical-resolution state

Finding: distinguish explicit-version mismatch from `External` with a fourth target status.

Disposition: **NOT ADOPTED — conflicts with frozen Spec 012 V1 contract**.

Spec 012 §6 defines exact `url|version` eligibility and zero matches as `external` / unresolved-in-closure. Acceptance criterion H freezes the three V1 states `resolved`, `external`, and `ambiguous`. The exact source canonical string retains the explicit version evidence. The review thread is resolved with this rationale.

### PR #23 — proof-container provenance

Finding: the job container used an implicit Docker Hub registry/namespace even though its digest was pinned.

Disposition: **FIXED**.

The workflow now uses the fully qualified digest reference:
Retained workflow artifact identity:

```text
docker.io/library/rust@sha256:9146b0f62e1939989aa96fc8d89699a43c5635bf212819235a773e1a9e71a98f
artifact name: cf11g-context-proof
artifact id: 9561791650
artifact digest: sha256:f4134aef0acfd3dff671d6219ee3a2d80dd73a5dbb33312c2ff97a9135f5b421
workflow head: 1475a9d117f11dd5af3de6b118cd72fc8ccdfebd
```

CodeRabbit confirmed the repair and resolved the thread.

### Review availability that remains open
Artifact expiration does not change the immutable GitHub-recorded run/head/digest identity.

T042 is not yet closed in this convergence candidate.
## Independent-review truth

- PR #20 CodeRabbit review was triggered for the exact planning range and remained in processing at the last live read.
- Incremental review attempts after the propagated #21 repair on #22 and #23 hit CodeRabbit's included-review rate limit. These attempts must not be represented as exact-head independent-review PASS.
- Qodo was not observed as connected/available on these PRs during this convergence pass and no Qodo PASS is claimed.
- CodeRabbit's docstring-coverage notices are reviewer advisories, not repository acceptance gates for this slice; no behavior is weakened to satisfy them.
Every substantive finding actually returned for the implementation stack has a disposition:

## 9. Remaining gaps / explicit deferrals
- **PR #21:** schema-v1 serialization evidence loss — FIXED, regression added, CodeRabbit confirmed, thread resolved.
- **PR #22:** proposed fourth canonical target state — NOT ADOPTED because it contradicts frozen Spec 012 V1; CodeRabbit confirmed the contract and resolved the thread.
- **PR #23:** implicit container registry/namespace — FIXED by using the fully qualified digest-pinned image; CodeRabbit confirmed and resolved the thread.
- **PR #20:** CodeRabbit entered processing, then an explicit re-review attempt was rate-limited. No substantive planning finding was returned. This is recorded as reviewer unavailability, not PASS.
- **Qodo:** no connected/available review was observed for this stack; no Qodo PASS is claimed.

### Blocking convergence gap — T042-R1
Reviewer absence is recorded rather than replaced with invented approval. There is no unresolved substantive returned finding.

Complete or explicitly disposition the still-running PR #20 independent review, and obtain the final available independent review coverage required by T042. Any new substantive finding reopens the affected implementation task and must be repaired or rejected against the frozen contract with evidence.

### Final-head proof gap — T043-R1

After the convergence documentation/task-state commit, rerun and inspect on the new exact Stack C head:
## T040–T043 convergence disposition

```text
ci
cf06-oracle
cf11-multi-version-proof
cf11g-context-proof
T040 mandatory workspace gates: COMPLETE
T041 preserved workflow gates: COMPLETE
T042 independent review: COMPLETE WITH AVAILABILITY TRUTH RECORDED
T043 convergence pass: COMPLETE, subject to this closeout PR exact-head validation and merge
```

Record the final exact head/tree/run identities in PR metadata after the runs settle. A failing or missing required gate prevents T043 closure.

### Reviewer availability deferral — T042-D1

If CodeRabbit remains rate-limited for an incremental re-review, record the limitation exactly rather than converting it into PASS. Previously completed findings and their dispositions remain evidence, but reviewer unavailability is not itself a positive review result.

Qodo remains an explicit availability-based deferral unless a connected review becomes observable before closure.

## 10. CF-12 eligibility

Current decision:

```text
CF-12 = BLOCKED_PENDING_T042_T043
```
The final closeout PR MUST remain unmerged if any exact-head required workflow fails, the head changes without requalification, or a new substantive review finding remains unresolved.

CF-12 `commandf impact` MUST NOT begin implementation until:
## CF-12 boundary

1. T042 has a defensible independent-review disposition with every substantive finding closed;
2. the final convergence head passes the required exact-head workflows;
3. T043 is marked complete without unresolved CF-11G implementation gaps;
4. the stacked CF-11G changes are merged through the repository's normal PR lifecycle.
After this closeout record itself passes its exact-head configured gates/review and merges without content changes, CF-11G is canonically closed and `CF-12 commandf impact` becomes eligible for implementation.

No statement in this document grants compatibility, safety, model, runtime, source, dependency, or clinical authority beyond the deterministic evidence recorded above.
CF-12 must consume the explicit graph evidence and preserve `external` and `ambiguous` states. This closeout grants no new compatibility, clinical, model, dependency-source, network, or HL7-oracle authority.
Loading
Loading