feat(pkg): record exact resolved dependency edges

Merged
TH
3mo ago
+599-39

Stack

CF-11G implementation Stack A for tasks T010-T012.

Base PR: #20 (docs/cf11g-context-graph-planning)

Summary

Add the exact resolved package-edge evidence required by the planned ecosystem Context Graph without implementing graph extraction or commandf context yet.

Changes

  • add commandf.lock schema v2;
  • retain schema-v1 decoding/serialization compatibility for existing commands;
  • add exact parent/child ResolvedDependency evidence with the original declared manifest constraint;
  • record dependency edges during resolver traversal before exact-identity expansion deduplication;
  • retain shared-child and cycle-closing edges while keeping archive expansion bounded;
  • make new resolver output schema v2;
  • validate v2 as a complete deterministic evidence set:
    • canonical root/package/edge ordering;
    • unique exact package identities;
    • every edge endpoint exists;
    • every edge matches a declared parent dependency and constraint;
    • selected child version satisfies that constraint;
    • every declared dependency has exactly one resolved edge;
  • preserve v1 shape when serializing legacy v1 locks;
  • add multi-version, shared-child, cycle, root-order determinism, v1 compatibility, and malformed-v2 tests.

Authority boundary

This PR does not:

  • implement commandf context;
  • add a graph database or new dependency;
  • change CF-03/04/05 compatibility semantics;
  • change the CF-06 HL7 oracle pin or failure semantics;
  • modify the frozen CF-10 corpus;
  • depend on the external HL7 maintainer path;
  • start CF-12.

Migration boundary

New pkg resolve output is schema v2. Existing valid schema-v1 locks remain readable and verifiable by existing commands.

A later stacked Context Graph consumer will require v2 and fail closed on v1 rather than infer exact multi-version package edges.

Required qualification

Keep Draft until the exact head passes:

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

and the existing ci, cf06-oracle, and cf11-multi-version-proof workflows plus independent review are inspected.

Summary by cubic

Adds commandf.lock schema v2 to record exact parent→child dependency edges and makes the resolver emit v2 by default. v1 files still load and serialize unchanged, and v1 now rejects any embedded resolved edge evidence.

New Features

  • Validates v2 locks with canonical root/package/edge order and exactly one edge per declared dependency.
  • Ensures both endpoints exist and the selected version satisfies the declared constraint.
  • Deduplicates exact package identities while retaining edges for shared children and cycles.
  • Exposes ResolvedDependency from commandf-pkg and adds InvalidLockfile with clearer unsupported-schema errors.
  • Guarantees byte-stable output for equivalent root sets and multi-version graphs.

Migration

  • pkg resolve now writes schema: 2; valid v1 locks still load and serialize as v1.
  • v1 locks must not include resolved_dependencies; serialization fails if they are present.
  • v2 locks must include resolved_dependencies.
  • Future Context Graph consumers will require v2 and fail closed on v1.

Summary by CodeRabbit

  • New Features

    • Added lockfile schema v2 support with resolved dependency information.
    • Preserved compatibility with schema v1 lockfiles.
    • Improved dependency resolution for multi-version and cyclic dependency graphs.

  • Bug Fixes

    • Added validation for dependency relationships, versions, constraints, ordering, duplicates, and complete dependency coverage.
    • Added clearer errors for unsupported or invalid lockfiles.
    • Ensured deterministic lockfile output for equivalent dependency graphs.