Plan: Record a revision-pinned model and consumer inventory (26.1.1)

[leynos]

Summary

This PR adds the ExecPlan for roadmap item 26.1.1, "Record a revision-pinned
model and consumer inventory", from the
hexagonal hardening roadmap.

ExecPlan:
docs/execplans/26-1-1-record-model-and-consumer-inventory.md

It is a plan only (Status: DRAFT). Nothing in it is implemented, and it
needs approval before implementation starts.

What the plan delivers once implemented

• docs/hexagonal-hardening-inventory.md: a reference document pinned to one
  commit. It lists every production constructor, mutator and consumer of the
  types that phases 26 and 27 will change, across seven areas: authored types,
  lowering, graph storage, backend consumers, CLI orchestration, diagnostics,
  and existing seams. It also records landed work (the #652 edge arena is
  recorded as done, not scheduled again), the remaining parts of H1 to H4,
  numbered observations, compatibility obligations, and a trace matrix
  covering the roadmap's dependency closure of 26.1.1.
• A compiler-based site oracle. In a disposable export under target/ that
  is never committed, each inventoried item is marked #[deprecated], so
  rustc reports every resolved use. Text sweeps cover what the oracle cannot
  see: trait-dispatched and derive-generated construction, cfg(kani) and
  other-platform code, and doctests. Twelve seeded faults, applied blind, show
  that the method can fail.
• tests/hexagonal_inventory_contract_tests.rs: an rstest document-integrity
  test that reads only docs/. It checks that the inventory has one pin,
  that register identifiers are unique, and that the trace matrix covers every
  task depending on 26.1.1, so a mapsplice renumbering cannot silently
  break the trace.
• Small pointers from docs/contents.md, RFC 0026, docs/netsuke-design.md,
  and the developers' guide's test suite map, and the roadmap checkbox.

No production Rust source, manifest behaviour, CLI behaviour or generated
output changes.

How the plan was built

• Reconnaissance: six Wyvern agents, one per boundary, at ebcedaef.
• Expert design review, round 1: three panel pairs (structure and contracts;
  alternatives and cost; failure modes and viability), with the verdict
  "revise". Revision 2 replaced the regex-only sweep, which missed generic
  trait impls, Self::Variant constructors and &mut free-function mutation,
  with the compiler oracle. It also added the integrity test, replaced the
  entry gate, widened the inventoried type set, and corrected several
  compatibility obligations.
• Closing review: revision 3 handles the oracle's trait-impl and derive blind
  spots, sweeps Kani-only modules, guards against an empty sweep list,
  prevents a vacuous empty-pin pass, and adds site-level identifiers.

Decision needed from the approver (D-6)

Roadmap 26.1.1 depends on "acceptance of RFC 0026". RFC 0026 and ADR-035 are
both still Proposed, and no RFC in docs/rfcs/ has ever left Proposed; ADRs
are the documents this project accepts. Please choose one:

• Option A: accept ADR-035 before implementation begins.
• Option B (recommended): produce the inventory now, as the
  characterization RFC 0026 asks for, and tick the roadmap box only once
  ADR-035 is Accepted.

Findings worth knowing now

These come from code reading at ebcedaef. The plan records each one for its
owning task and fixes none of them.

• A rule whose recipe is rule: other passes lowering and validation. The
  Ninja backend then panics in debug builds and returns a misleading
  UnsafeNinjaValue in release builds (26.1.2 and 26.2.2).
• netsuke graph and netsuke help targets lower with the host-default recipe
  shell rather than the resolved one (26.3.1).
• The action-hash comment claims sorted keys, but serde_json is built with
  preserve_order, so field order is part of action identity (26.2.3).

Validation

Each plan commit was gated with make check-fmt, make typecheck,
make lint, make test, make markdownlint and make nixie.

• The first commit passed everything: nextest reported 3413 tests passed.
• Revisions 2 and 3 passed every gate except one test: 3412 of 3413 passed,
  and packaging_smoke_tests::packaged_manifest_retains_build_script_sources
  timed out at its 300 s cap while the host load average was 11 to 21 on six
  cores. That test cold-builds cargo publish --dry-run and fails locally
  under load, independent of the change; it passed on the same Rust tree in
  the first run, and CI is the authoritative check for it.
• The doctest pass, skipped when nextest aborted, was run separately with
  make doctest and passed.

main has since gained #804 (version 0.1.0-beta4) and #728, neither of
which touches src/ or the inventoried types. The plan pins and rebases at
EP-M0, so the branch was not rebased now.

References

• Lody session:
  https://lody.ai/leynos/sessions/87392da2-6f4c-47f5-8990-bf106b4279fe

🤖 Generated with Claude Code

Summary by Sourcery

Add a draft execution plan for producing and validating a revision-pinned model and consumer inventory before the hexagonal hardening changes are implemented.

New Features:

• Add a draft execution plan for creating a revision-pinned inventory of model types, constructors, mutators, consumers, findings, obligations, and roadmap traceability across the hexagonal hardening work.
• Define a compiler-assisted discovery process, targeted text sweeps, seeded-fault validation, and a document-integrity contract test for the planned inventory.

Enhancements:

• Document the planned compatibility obligations, landed work, open design findings, approval gate, and milestone-based verification approach for roadmap item 26.1.1.

Documentation:

• Add the draft ExecPlan for roadmap item 26.1.1 and specify future documentation, roadmap, RFC, design, and developer-guide updates that will accompany implementation.

Tests:

• Plan an rstest-based contract test that validates the inventory pin, register identifiers, findings ownership, and complete dependency trace matrix.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

This PR adds a DRAFT-only ExecPlan for creating a commit-pinned inventory of model constructors, mutators, consumers, and compatibility obligations needed by roadmap phases 26 and 27. It specifies the inventory document, a compiler-assisted discovery methodology with targeted blind-spot sweeps, an rstest-based integrity contract, traceability and acceptance evidence, and an explicit decision over the RFC/ADR entry gate; it does not change production behavior.

Sequence diagram for planned inventory site discovery

sequenceDiagram
    participant Implementer
    participant Git
    participant Scratch as Disposable export
    participant Rustc
    participant Sweep as Text sweep
    participant Inventory

    Implementer->>Git: git archive <pin>
    Git-->>Scratch: Export pinned tree
    Implementer->>Scratch: Add #[deprecated] markers
    Scratch->>Rustc: cargo check --workspace --all-targets --all-features
    Rustc-->>Implementer: Deprecated-use diagnostics
    Implementer->>Sweep: Scan uncompiled and blind-spot code
    Sweep-->>Implementer: Trait, cfg, derive, and doctest sites
    Implementer->>Inventory: Classify and record register sites
    Implementer->>Scratch: Remove disposable export

Loading

Flow diagram for inventory acceptance and entry gate

flowchart TD
    Start["ExecPlan approved"] --> Gate{"D-6 entry option chosen"}
    Gate -->|"Option A: ADR-035 accepted"| Pin["Declare implementation pin"]
    Gate -->|"Option B: characterize first"| Pin
    Gate -->|"No decision"| Blocked["Set plan BLOCKED and stop"]
    Pin --> ContractRed["Contract test fails without inventory"]
    ContractRed --> Skeleton["Add skeleton inventory"]
    Skeleton --> Register["Build register and run oracle/sweeps"]
    Register --> Evidence["Record findings, obligations, and trace matrix"]
    Evidence --> Gates["Run repository gates"]
    Gates -->|"Pass"| Complete["Integrate docs and roadmap update"]
    Gates -->|"Fail"| Repair["Repair or escalate"]
    Repair --> Gates

Loading

File-Level Changes

Change	Details	Files
Adds a detailed draft ExecPlan for producing a revision-pinned hexagonal hardening inventory.	Defines the inventory’s scope across authored models, lowering, graph storage, backends, CLI orchestration, diagnostics, and seams. Specifies a compiler-based deprecation oracle supplemented by targeted sweeps, seeded-fault validation, reverse checks, and evidence requirements. Plans a document-integrity contract test covering pins, register identifiers, roadmap dependency closure, findings, obligations, and traceability. Defines milestones, entry-gate decision D-6, risks, tolerances, compatibility obligations, and repository validation gates.	docs/execplans/26-1-1-record-model-and-consumer-inventory.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.