Propose hexagonal hardening, architecture checks, and a gated Paralegal experiment

[leynos]

Summary

Add three proposed RFCs, three proposed ADRs, and a roadmap continuation for the initial hexagonal hardening and architectural checking programme. The roadmap contains four phases (26–29), 13 steps, and 32 unchecked implementation tasks, each with acceptance criteria and dependencies.

• RFC 0026 / ADR-029: model-owned resolved operations, explicit dependency-only semantics, interpreter-bound lowering, CLI-independent application execution, and typed semantic diagnostics. Preserve existing capability, process, environment, and dyndep-lease boundaries.
• RFC 0027 / ADR-030: a Wildside-derived Rust boundary checker, Corbusier-style abstraction ownership and shared contracts, and Hecate-inspired declarative policy, origin-aware diagnostics, explicit analysis coverage, and narrowly governed migration exceptions. Include negative controls for the enforcement machinery itself.
• RFC 0028 / ADR-031: a bounded, measurable Paralegal experiment, not an adoption decision or new required check.

Index all seven new documents in docs/contents.md without deleting or rewriting existing entries.

Paralegal: compatibility before policy work

The first executable task is 29.1.2, following preregistration in 29.1.1: establish whether Paralegal can actually analyse the real production implementation using Netsuke's required Rust toolchain.

Source inspection found Netsuke on nightly-2026-08-23 and the inspected Paralegal revision on nightly-2026-04-20. This is recorded as a risk, not an executed compatibility result. The experiment's status is not run.

P0 requires an ordinary production build, actual analysis-compiler identity, a non-empty graph containing independently specified production roots/symbols, and repeatable extraction. A toy, copied implementation, excluded relevant feature, old-compiler borrowing workaround, or Netsuke compiler downgrade cannot count as success. Incompatible or inconclusive outcomes stop later gates; an upstream analyser port requires a separate proposal.

Only a compatible configuration proceeds to at most two policy pilots: resolved-recipe flow and accepted redirect-target flow. Each retained policy needs six seeded violations, three legitimate controls, two reviewer-selected hold-out violations, complete declared coverage, and a demonstrated regression caught beyond existing types, structural rules, and tests.

Record provisioning/extraction/policy costs separately, use pinned cached tooling, and stay within the proposed 4-vCPU/8-GiB build/analysis and 1-vCPU/2-GiB report limits. Proposed trial ceilings are 30 minutes for P0 provisioning plus first extraction, then 15 minutes cold and 3 minutes warm for a provisioned suite. These are reviewable experimental ceilings, not measured performance claims. Ten representative shadow changes precede an explicit retain/defer/reject decision. Blocking adoption requires separate approval.

Scope and sequencing

• Documentation only: eight Markdown files. No runtime code, toolchain, lockfile, schema, dependency, workflow, lint suppression, analyser installation, or scheduled job changes.
• Every RFC and ADR remains Proposed. Writing the plan completes no implementation checkbox.
• The initial H1–H4 transformation proceeds independently of Paralegal and need not wait for the entire checker rollout.
• H5 provenance remains conditional integration with v0.4.0: design and implement a Netsukefile linter inspired by mbake #592/v0.2.0: land structured recipes, Git-aware change detection, and OrthoConfig v0.10 integration #593 and composition; H6 acquisition remains conditional reuse under v0.3.0: add non-file dependency providers, starting with URLs #590. v0.3.0: implement the first-class Netsukefile testing framework #591 retains manifest-testing ownership.
• The current graph already has canonical edge storage from Store multi-output build edges once instead of cloning them per output #652 / Store multi-output build edges once (#652) #714. Preserve it rather than reimplement it. Inspect Type the redirect target at the transport boundary instead of passing a raw Location #705's current redirect boundary before further extraction.
• Preserve the quickstart, unannotated manifests, and current compiler contract. This programme adds no v0.1.0 release gate.
• Avoid number collisions: Split the RFC 0006 accepted set into focused child RFCs (6.1.1) #697 reserves RFCs 0013–0020; Propose progressive orchestration RFCs and implementation roadmap #741 reserves RFCs 0021–0025 and phases 20–25. Open ADR allocations through 028 were checked before selecting 029–031.

Review order

Start with RFC 0026, then RFC 0027, and RFC 0028. Each links its narrower decision record. The roadmap supplies delivery and stopping criteria.

Validation and limitations

• 185/185 local static documentation assertions passed: Markdown structure, proposed statuses, captions, relative links against fetched source paths/the existing index/new documents, unique phase/step/task identifiers, acceptance/dependency fields, acyclic unconditional task prerequisites, five distinct P0 procedure steps, experiment criteria, and one index entry per new document.
• Verified the downloaded original index against its Git blob hash and checked that its edits are additive only.
• Rechecked main before publication; the inspected baseline remains 79545e124b4a13dbe8352fd23df97619a91a0b5c.
• Not run: repository make check-fmt, make markdownlint, make nixie, Rust lint/test gates, or the Paralegal compatibility experiment. The required repository tools/toolchain are unavailable in this editing environment. The custom static checks do not substitute for those gates.

This PR is a draft pending repository validation and design review.

Summary by Sourcery

Establish a proposed roadmap for strengthening semantic and application boundaries, enforcing architectural contracts, and evaluating Paralegal only through a bounded compatibility-first experiment.

New Features:

• Propose semantic compiler and execution-boundary hardening through model-owned resolved operations, interpreter-bound lowering, CLI-independent application requests, and typed diagnostics.
• Define layered executable architecture enforcement with explicit coverage, origin-aware policies, reviewed migration exceptions, and negative controls.
• Define a compatibility-gated Paralegal experiment with production-code validation, measurable policy pilots, resource ceilings, and an explicit retain/defer/reject outcome.

Enhancements:

• Add a four-phase roadmap covering implementation sequencing, dependencies, acceptance criteria, and stopping conditions for hexagonal hardening, architecture checks, and the Paralegal trial.

Documentation:

• Index the three proposed RFCs, three proposed ADRs, and the hexagonal hardening roadmap in the documentation contents page.

Tests:

• Specify comprehensive validation requirements for semantic boundaries, architecture enforcement, experiment compatibility, coverage, reproducibility, and regression controls.

[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 documentation-only PR proposes semantic compiler and application-boundary hardening, layered architecture enforcement, and a separately gated Paralegal experiment, delivered through phases 26–29 with explicit acceptance criteria, dependencies, coverage checks, and stopping rules; it adds and indexes three RFCs, three ADRs, and the continuation roadmap without changing runtime code or CI.

Sequence diagram for the gated Paralegal compatibility experiment

sequenceDiagram
    participant Reviewer
    participant Trial as P0 trial
    participant Build as Netsuke production build
    participant Analyzer as Paralegal analyzer
    participant Graph as Production graph
    Reviewer->>Trial: Freeze revisions, toolchain, target, features, roots
    Trial->>Build: Establish ordinary production build
    Build-->>Trial: Build result and compiler identity
    Trial->>Analyzer: Check compiler-driver compatibility
    Analyzer-->>Trial: Provisioned analyzer and actual analysis compiler
    Trial->>Graph: Extract production roots and symbols
    Graph-->>Trial: Non-empty graph and path coverage
    Trial->>Graph: Repeat extraction
    Graph-->>Trial: Reproducible extraction result
    Trial-->>Reviewer: compatible, incompatible, or inconclusive
    alt incompatible or inconclusive
        Reviewer-->>Trial: Stop later gates
    else compatible
        Reviewer-->>Trial: Authorize at most two policy pilots
    end

Loading

Flow diagram for layered architecture enforcement

flowchart TD
    SRC[First-party Rust sources] --> INV[Source inventory and coverage]
    INV --> ANA[Bounded dependency analysis]
    ANA --> FACTS[Origin-aware analysis facts]
    FACTS --> POLICY[Policy evaluation and exception ledger]
    POLICY --> REPORT[Deterministic diagnostics]
    REPORT --> GATE[Qualified architecture gate]
    GATE -->|violations or incomplete coverage| FAIL[Fail enforcement]
    GATE -->|compliant and covered| PASS[Pass enforcement]

Loading

Flow diagram for Paralegal experiment gates

flowchart TD
    P0[P0: required-toolchain compatibility] -->|incompatible or inconclusive| STOP[Stop and record outcome]
    P0 -->|compatible production analysis| P1[P1: qualify up to two semantic policies]
    P1 --> P2[P2: verify coverage, reproducibility, and cost]
    P2 --> SHADOW[P3: shadow ten representative changes]
    SHADOW --> DECIDE[Retain, defer, or reject]
    DECIDE -->|retain| APPROVAL[Separate approval for blocking adoption]
    DECIDE -->|defer or reject| CLEANUP[Retain evidence and remove unused tooling]

Loading

File-Level Changes

Change	Details	Files
Define semantic ownership and execution boundaries for compiler, model, application, and presentation layers.	Propose resolved model operations that distinguish executable and dependency-only semantics. Bind lowered recipes to their interpreter and preserve existing graph, capability, lease, and escaping contracts. Separate CLI-independent application requests and execution adapters from Ninja orchestration. Represent semantic diagnostics as typed facts with presentation-specific rendering. Specify characterization, migration, compatibility, and acceptance work across phases 26–27.	docs/rfcs/0026-hexagonal-domain-hardening.md docs/adr-029-semantic-compiler-boundaries.md
Specify layered, executable architecture enforcement with explicit coverage and governed migration debt.	Combine a bounded Rust dependency checker with type/API restrictions, effect lints, port contracts, and integration tests. Define responsibility roles, supported import analysis, origin-aware diagnostics, and explicit failure for missing or incomplete coverage. Introduce narrow, reviewed exception schemas with stale, broadened, malformed, and unowned entries rejected. Require positive and negative fixtures, enforcement self-tests, real gate failure propagation, and measured resource budgets. Keep the checker independent of the optional Paralegal experiment and defer gate activation until qualification.	docs/rfcs/0027-executable-architecture-contract.md docs/adr-030-layered-architecture-enforcement.md
Establish a compatibility-first, evidence-gated Paralegal experiment without making adoption mandatory.	Record compiler-pin observations as an unexecuted risk and require native production compatibility verification first. Require actual compiler identity, ordinary production build, non-empty production graph, expected roots/symbols, and repeatable extraction. Stop on incompatible or inconclusive P0 results without downgrading Netsuke or introducing an implicit analyser port. Limit follow-on pilots to resolved-recipe and redirect-target flows with seeded violations, legitimate controls, hold-outs, coverage, incremental-value, and cost criteria. Require bounded provisioning and runtime measurements, shadow evaluation on ten representative changes, and a separate retain/defer/reject decision.	docs/rfcs/0028-paralegal-architecture-experiment.md docs/adr-031-gate-paralegal-on-measured-evidence.md
Extend the delivery roadmap with four independently sequenced phases and detailed gated implementation tasks.	Add phases 26–29 covering resolved semantics, application/diagnostic ownership, architecture enforcement, and Paralegal evaluation. Define 13 steps and 32 unchecked tasks with acceptance criteria, dependencies, stopping conditions, and conditional ownership for provenance and acquisition work. Preserve existing issue/ADR/RFC allocations, canonical graph storage, toolchain, release scope, quickstart, and manifest-testing ownership. Make Paralegal phase 29 independent of the hardening and checker rollouts, beginning with preregistration and compatibility.	docs/roadmap-hexagonal-hardening.md
Add the seven proposed RFC, ADR, and roadmap documents to the documentation index without replacing existing entries.	Index RFCs 0026–0028, ADRs 029–031, and the hexagonal-hardening roadmap. Keep all new records explicitly marked Proposed and describe the documentation-only scope.	docs/contents.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.