refactor(contracts): extract ironclaw_product_contracts and land the adapter half (WS1.4)

[BenKurrek]

Stacked on #6977 (→ #6975) — merges after them; diff shown is against that branch.

WS1.4 of the target architecture: carve the product tier's neutral contracts out of ironclaw_host_api into crates/ironclaw_product_contracts, and land the WS1.3 adapter half it exists to unblock — ChannelAdapter, ToolAdapter, and RestrictedEgress now live in ironclaw_extension_contracts where §6.1.2 assigns them. Flat crate directory today; the contracts/ family directory arrives in Wave 5.

git mv moved 15 modules at 83–100% similarity, so the diff reads as a move, not a rewrite:

→ ironclaw_product_contracts	Owns
surface (from host_api::product_surface)	ProductSurface, BoundProductSurface, ProductSurfaceCaller, the invoke/query/stream DTOs, ChannelInboundProductSurface, the ProductSurfaceError family
inbound	inbound envelope/payload/ack/rejection DTOs + channel-inbound classification
outbound	the product projection wire, approval prompt views, capability activity views, ProjectionCursor
projection	ProjectionStream + the read/subscribe request DTOs
interaction_commands	the channel-neutral interaction-reply grammar
operator_llm	the operator LLM menu vocabulary
package_lifecycle (from extension_contracts)	Lifecycle*, ChannelConnectStrategy, ChannelConfigField

→ ironclaw_extension_contracts	Owns
channel_adapter	ChannelAdapter + its whole DTO family, incl. ProductTriggerReason
tool_adapter	ToolAdapter + RestrictedEgress
egress	ProtocolHttpEgress, the Egress* types, DeliveryStatus/OutboundDeliverySink
external	ExternalActorRef/ExternalConversationRef/ExternalEventId/ProductAttachmentDescriptor/Kind
auth_prompt	the channel-rendered auth challenge family + render_channel_auth_prompt
test_support	the §11.2.10 channel-adapter conformance suite + the egress/delivery fakes

The adapter-move mechanics

PR #6977's headline finding was that a type cannot leave host_api while a type staying in host_api names it, because host_api's allowlist is "no ironclaw_*". The corollary nobody had measured is that host_api::product_adapter is one connected component: channel_adapter names inbound::ProductTriggerReason; inbound names channel_adapter::ChannelAttachmentRef and outbound::ProjectionCursor; projection names inbound and outbound; interaction_commands names inbound; product_surface names all of them. So the adapters could only move once inbound, outbound, projection, interaction_commands, and product_surface moved too. That co-movement, not the ProductSurface trait alone, is the real content of WS1.4 — and it is why this slice is one PR rather than two.

Three placements were then forced by the one-way street (product_contracts → extension_contracts, never the reverse):

• ProductTriggerReason went to the extension tier. It is stamped by the adapter on every NormalizedInboundMessage; leaving it in inbound would have inverted the dependency. It sits in channel_adapter beside the field that carries it.
• external and egress went to the extension tier, as §6.1.2's "fed by" list already said. §6.1.3's "external product-halves" is empty at this base: all five external types — including ProductAttachmentDescriptor/Kind — are named by ChannelAdapter's own cone, so there is no product half to keep back.
• identity and product_adapter_error could not leave host_api at all. host_api::user_identity names AdapterInstallationId; host_api::product_adapter::auth (which stays until WS1's sealed-evidence row moves it) names ProductAdapterError. Both contracts tiers reach them downward, which is the only placement serving both. §6.1.3's "fed by" naming product_adapter_error is not achievable while auth stays — recorded, not worked around.

Six more dispositions the lead sheet did not predict

1. §6.1.3's "auth/approval prompt-view DTOs" splits, and the auth half is extension-tier. ChannelAdapter's own OutboundPart::AuthPrompt carries Box<AuthPromptView>, and both shipped channel packages call render_channel_auth_prompt from deliver (slack_extension/src/channel.rs:157, telegram_extension/src/channel.rs:278). That is a membrane crossing by adapter signature, so the auth family is now extension_contracts::auth_prompt. The approval half (ApprovalPrompt*View), reached only by product and WebUI, stayed in product_contracts::outbound. One deliberate, recorded cost: two ~15-line display-text validators now exist in both crates. Hoisting them instead would have made a generic text validator part of the extension membrane's public API to serve a product-tier caller — the worse trade. WS1's "evict behavior from host_api" row already owns render_channel_auth_prompt and is where they converge.

2. package_lifecycle came back to product_contracts — the §6.1.3 ruling. WS1.3 placed it in extension_contracts as a forced co-mover and explicitly recorded it as interim rather than a decision. The § text is unambiguous (§6.1.3's Owns names "package_lifecycle UI projections"; §6.1.2's Owns does not), and the code agrees: LifecycleProductAction/LifecycleProductResponse are the vocabulary of LifecycleProductService, which §6.1.3 also assigns here, and its consumers are product/CLI, not the channel packages or lanes. Zero cost, because this crate may depend on extension_contracts, so the four §6.1.2 types it is typed on stay reachable from below.

The #6930 merge-down happened during review, and the ruling held. Slot 3's parent branch landed origin/ws1/extension-contracts@492f0f4d8 ("reconcile WS1.3 with hosted MCP registration"), which relocated host_api::hosted_mcp into ironclaw_extension_contracts — the disposition this PR had independently recommended from hosted_mcp's own module doc and its consumer set. Merging it down made the predicted constraint live: extension_contracts::hosted_mcp names LifecyclePackageId, and package_lifecycle had just moved to product_contracts, which is the forbidden direction.

Resolved by splitting the id from the projections, which is the only resolution the one-way street allows and the one recorded in advance: LifecyclePackageId (with LifecycleBlockerRef, which shares its bounded-string template — splitting them would have traded one home for two) now lives in a new ironclaw_extension_contracts::lifecycle_id module, and product_contracts::package_lifecycle imports it from below. The projections stayed product-tier per §6.1.3. The rejected alternative — dragging hosted_mcp up into product_contracts with the projections — would have handed ironclaw_mcp, ironclaw_extensions, ironclaw_auth, and ironclaw_host_runtime a product-tier edge, which is exactly what §6.1.2 exists to prevent. Four conflicted files were resolved by hand (extension_contracts/{CLAUDE.md,src/lib.rs}, extension_host/{extension_lifecycle_command.rs,product_lifecycle.rs}); parent-introduced references in webui/handlers.rs, extension_host/product_lifecycle.rs, and the new tests/integration/hosted_mcp_registration.rs were repointed to follow the move, never by resurrecting the old path. Full gauntlet re-run on the merged tree: fmt, workspace --all-targets --all-features check, cargo metadata --locked, the architecture suite, and clippy + tests on all six merge-affected crates.

3. AppEvent did not come, because it is dead. §6.1.3 and the WS1.4 row both assign "the 43-variant AppEvent wire enum (today common::event)" here, on the premise that a transport streams it to a client. Re-measured on this base: crates/ironclaw_common/src/event.rs is 1,234 lines with zero consumers outside ironclaw_common itself — the only other workspace reference is reborn_dependency_boundaries.rs:2332, an architecture test asserting the Reborn OpenAI-compatible routes must not stream it. Importing it would seed a brand-new contracts crate with dead weight and a §11.2.3 size-ceiling problem. It stays in common, flagged on the "Narrow ironclaw_common" row, which owns event.rs anyway. Inventory correction, not a scope cut.

4. Four re-export chains gave one trait two import paths, and all four are deleted. ChannelAdapter through ironclaw_product and through ironclaw_reborn_composition (a re-export of a re-export); OutboundDeliverySink + ProtocolHttpEgress through ironclaw_product; ProjectionStream and ChannelInboundProductSurface through ironclaw_product. Consumers repoint to the owning crate. Slot 3's scan caught the first three the moment the types gained an owner; the new scan pins the rest.

5. Two name collisions the new scan can see and the extension tier's could not, both same name, different layer rather than duplicate definitions, both recorded in COLLISION_EXEMPT with the colliding definition named: ProjectionCursor (ironclaw_event_projections/src/lib.rs:116 is the structured internal position { runtime: EventCursor, scope: ProjectionScope } with rebase semantics; ours is the opaque serde(transparent) wire token it stands for) and ProjectionSubscriptionRequest (ironclaw_outbound/src/types.rs:157 is the durable subscription-store record request, with a different cursor type and two extra fields). The shared name is the real defect and renaming is a §5.1 WS10 decision.

6. Slot 3's scan needed four collision exemptions too, surfaced when channel_adapter/external/tool_adapter arrived from host_api where it could not see them. ToolCall/ToolResult vs ironclaw_llm::provider are not the same concept (the LLM pair is Serialize wire vocabulary a model emitted; the extension pair is the in-process invocation envelope whose module doc says "nothing here serializes"). ExternalActorRef/ExternalConversationRef vs ironclaw_conversations::ids are the same concept declared twice — a real duplicate-surface finding, since conversations::ids carries a parallel copy of the adapter-identity vocabulary including AdapterInstallationId and ExternalEventId that the walk cannot even see (bounded_string_id! expansions, the same blind spot slot 3 recorded for LifecyclePackageRef). Exempted so the finding is visible and attributable rather than blocking; unifying them changes the conversations record grammar, which is a domain call.

Deferred by design, with the analysis those rows need

§6.1.3's Owns list also names the product-side ports and the command/view/capability descriptor types. Those are sourced from ironclaw_product, not from ironclaw_host_api, and the CHECKLIST assigns them elsewhere by name: WS2's first row ("flip extension_host's implemented ports to product_contracts/extension_contracts definitions — delivery resolver, reply-context source, admission, pairing sources, account-status") and WS6's operator row ("implements product_contracts ports; product dep dropped"). Moving a port definition without repointing its implementor buys no dependency-edge removal, and both moves are the §12.1c ordering-constrained class. This PR builds the crate they land in. The movability map, so those rows do not have to re-derive it:

Movable with import repointing only (11): ChannelDeliveryResolver + ResolvedChannelDelivery; DeliveryReplyContextSource + NoReplyContext; LlmConfigService + ActiveModelReader + the 15-type LLM DTO group (needs external secrecy on the manifest); OperatorStatusService, OperatorLogsService, OperatorServiceLifecycleService + their DTOs (carry or inline operator_surface_unavailable()); ChannelConfigProductService; AccountConnectionStatusSource; ProductSurfaceCommandDescriptor, ProductCapabilityDescriptor, ProductView.

Blocked, with the blocker (3): ProductOutboundTargetResolver — needs ValidatedReplyTargetBinding from ironclaw_outbound and ProductSurfaceFailure (product/src/error.rs, whose cone pulls ironclaw_turns::{TurnError, TurnErrorCategory}); both are forbidden deps, so it cannot move without type surgery. ProductCommandAdmissionService — needs ProductActionId/ActionFingerprintKey (product::action, itself needing ironclaw_turns) and ProductCommand (product::commands, 565 lines); note it has zero out-of-crate implementors, so moving it removes no edge — lowest value, highest cost. LifecycleProductService — single blocker, LifecycleProductContext::Command(Box<ProductCommandContext>), which inherits the previous cone; and extension_host's impl additionally imports ProductSurfaceFailure + lifecycle_product_surface_error, so even a fixed context would not fully cut that edge.

Exception delta: zero, by design and re-verified

Each of the 13 LAYER_MATRIX_EXCEPTIONS was re-read against this branch's base. Not one is a host_api, product, or product_contracts edge, so no contracts carve-out at this tier can dissolve any of them — the same structural reason WS1.3 recorded, re-checked rather than inherited. The five mcp/scripts lane exceptions still wait on the registry DTOs in ironclaw_extensions (CHECKLIST WS3's mcp row); conversations → turns is turn admission authority, not vocabulary, and is authority-gated to WS5 — not chased here, per the wave floor. Count stays at 13.

What this PR does delete is four re-export edges the layer matrix cannot see (one trait, two import paths), each now pinned.

New-crate rule inventory

• §11.2.3 contracts purity — internal-dependency allowlist (ironclaw_host_api + ironclaw_extension_contracts, the one-way street §6.1.3 grants explicitly "for channel-facing DTO reuse"); an allowlist, not a blocklist, so a future product/operator edge cannot slip past a list of today's offenders. Plus the crate added to the shared framework/driver deny roster.
• §11.2.4 port-location scan — new reborn_product_contract_location_scan.rs, 7 tests (2 gates + 5 self-tests). One home: every type the crate defines, discovered rather than enumerated. One import path: the crate's traits (discovered, so a new port inherits the rule) plus the three membrane value types the row names. Ships with positive and negative fixtures per WS10 — including the three real chains this PR deleted, asserted by exact (line, name) — and both discovery helpers assert they measured something before asserting anything else. Its module doc states plainly what is out of scope (ironclaw_product's ~120 DTO re-exports) and why.
• boundary_rules() entry naming the edges whose appearance would be most damaging (ironclaw_product itself, ironclaw_operator and ironclaw_extension_host — the two crates whose ports it declares — and ironclaw_webui/ironclaw_host_ingress, since a transport edge would mean HTTP reached contracts).
• Scan reach preserved, and one path-keyed gate repointed: the crate joined untrusted_ingress_paths_cannot_submit_host_trusted_inbound's roots; reborn_service_method_freeze_ratchet's HOST_PRODUCT_SURFACE_SOURCE constant now points at product_contracts/src/surface.rs — it failed loudly on the missing file, which is the property that gate was built with; and the extension-specificity allowlist's four outbound.rs entries were repointed to auth_prompt.rs, not added, so the shrink-only baseline is untouched (the gate reported both halves — 4 new hits and 4 stale entries — and the repoint zeroed both).
• CI lane selectors: root members, [package.metadata.ironclaw] layer = "contracts", classify-test-scope.sh's shared arm, and reborn-crate-test-buckets.sh's product-workflow bucket (beside ironclaw_product — the bucket groups by what a change can break). Verified, not assumed: discover-reborn-package-crates.sh resolves it through the shipped-binary closure; both CI self-tests pass; the bash/python crate inventories agree at 66.
• Guidance: crate CLAUDE.md (admission test, module table, the three rulings above, the deferred-by-design section), a crates/AGENTS.md row, ironclaw_extension_contracts/CLAUDE.md rewritten for its four arrivals and one departure, and the live docs/reborn/ + .claude/skills/ references repointed (how-to-port-channel-to-reborn.md, contracts/auth-product.md, webui/CLAUDE.md, webui/AGENTS.md, reborn-extension-surfaces/SKILL.md).

Un-masking

ironclaw_host_api 335 → 243 (−92, gained 0). ironclaw_extension_contracts 44 → 65 (+24 arrived, −3 departed). ironclaw_product_contracts has 71. Set-differencing the rosters leaves zero unaccounted names in either direction: the 92 host_api departures are exactly 24 (→ extension_contracts) + 68 (→ product_contracts), and the only three arrivals with no host_api origin are exactly the three package_lifecycle::tests::* that came from extension_contracts. No surviving test was edited for content — the moved files are 83–100% similar and every other test diff is an import line. Two host_api_contract.rs integration tests moved verbatim with the types they pin, into product_contracts/tests/product_contract.rs.

Verification

Lean gauntlet, all local (see the CI note below):

• cargo fmt --all -- --check clean.
• Per-touched-crate cargo clippy --all-targets --all-features -- -D warnings over all 15 touched crates: zero warnings. This is where a real masking bug surfaced — product_contracts' tests use ProtocolAuthEvidence::test_verified, which is behind host_api's test-support seam; it only compiled while host_api was in the same multi--p invocation (feature unification). Fixed with an explicit dev-dependency, not by widening a feature.
• Per-touched-crate unfiltered cargo test -p <crate> --all-features: green. One observed flake, not a defect: ironclaw's smoke::serve_mounts_cli_login_route_without_sso failed once under parallel load and passed in isolation plus two consecutive full re-runs (145/145 each).
• Full ironclaw_architecture suite green, including both location scans. Four enumerating gates failed first and were fixed rather than relaxed: the CLI's exact-dependency allowlist, the composition pub-use snapshot (docs/plans/composition-pubuse.snapshot line 43 deleted with the re-export), the extension-specificity allowlist (repointed), and the product-surface method-freeze path constant.
• cargo check --workspace --all-targets --all-features clean, run last — workspace-root tests/ targets are invisible to -p lanes, and 3 of them needed repointing.
• cargo metadata --locked resolves; git status re-checked after every cargo invocation.
• All 10 exact-test selectors in scripts/reborn-e2e-rust.sh executed, each matching exactly one test (grep -Fcx = 1). (Method note: the first sweep reported 10 false failures because this shell is zsh, which does not word-split unquoted variables, and because cargo was consuming the loop's stdin — re-run under bash with </dev/null.)
• No cross-crate include_str!/include_bytes! reaches into any file this PR moved code out of; scripts/ci/check-include-str-paths.sh passes (119 references).
• scripts/ci/critical_mutation_gate.py --selection-only against this diff prints false — no named invariant source or watch path changed, so that gate has nothing to enforce here (substitute evidence per the dispatch limitation below).

CI note

While this PR targets ws1/extension-contracts, the four pull_request: branches: [main]-gated workflows do not attach; the evidence above is local. Full Reborn workflow dispatched against this branch: https://github.com/nearai/ironclaw/actions/runs/30670580505 at head 12fcc339a.

Judge that run by its per-job tally, not the roll-up. Per #6978, workflow_dispatch runs of reborn-tests.yml always fail the Tests (Reborn) roll-up structurally: the critical-mutation gate is pull_request-gated, so it skips under dispatch, and the roll-up disallows skipped for that job. The --selection-only result above is the substitute evidence for that one gate.

Coverage-floor recapture and any changed-coverage exemption are deliberately not pre-written: the exemption step is pull_request/merge_group-gated and produces no artifact under dispatch, so entries would be guesses. Both obligations are executed in steward mode once real gate output exists. Note for that step: tests/integration/coverage-floor.toml has no ironclaw_host_api entry, but ironclaw_product's numerator is untouched by this PR (no product source moved out of it) — only its import lines changed.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 975194c8-9946-4b05-ae39-b48b9cb49fe0

📥 Commits

Reviewing files that changed from the base of the PR and between 1d8e32c and b74e093.

📒 Files selected for processing (1)

• tests/integration/changed-coverage-exemptions.toml

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added shared contracts for channel and tool adapters, lifecycle identifiers, operator model settings, and product-surface operations.
  • Added authentication prompt views with pairing details, validation, serialization, and channel-specific rendering.
  • Added reusable contract and delivery testing utilities.

• Documentation

  • Updated architecture, integration, and channel-porting documentation for the new contract locations and completed milestones.

• Refactor

  • Reorganized shared interfaces while preserving existing runtime behavior and workflows.

Walkthrough

The PR adds ironclaw_product_contracts, expands ironclaw_extension_contracts, removes migrated host API modules, updates workspace consumers, and adds architecture and CI enforcement for the new contract boundaries.

Changes

Contract extraction and migration

Layer / File(s)	Summary
Contract crate foundation crates/ironclaw_product_contracts/*, crates/ironclaw_extension_contracts/*	Adds product-surface, lifecycle, operator LLM, authentication, adapter, egress, and test-support contracts.
Architecture enforcement crates/ironclaw_architecture/tests/*	Adds product-contract location and dependency scans, collision checks, and a service-method ratchet update.
Runtime and consumer migration crates/ironclaw_product/*, crates/ironclaw_extension_host/*, crates/ironclaw_reborn_composition/*, crates/ironclaw_webui/*, crates/ironclaw_*extension/*	Updates traits, request/response types, implementations, and tests to use the dedicated contract crates.
Host API reduction and CI integration crates/ironclaw_host_api/*, scripts/ci/*, docs/reborn/*, tests/integration/*	Removes migrated host API modules and re-exports, updates documentation, and registers the new crate in CI scopes and buckets.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related issues

• Refactor reborn composition into owned crates with CI-enforced boundaries #4470: The contract-crate extraction and dependency-boundary enforcement support ownership and dependency checks across Reborn crates.

Possibly related PRs

• nearai/ironclaw#6977: Extracts extension contracts that this PR further relocates and consumes.
• nearai/ironclaw#6441: Establishes the ProductSurface boundary updated by this PR.
• nearai/ironclaw#6918: Adds the product-contract architecture implemented by this PR.

Suggested reviewers: serrrfirat

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides strong technical detail and validation evidence, but it omits most required template sections, including change type, linked issue, security, database, rollback, and review follow-through.	Rewrite the description using every template heading and explicitly state change type, linked issue, security and database impact, blast radius, rollback plan, review follow-through, and review track.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses Conventional Commits format and accurately describes the contracts extraction and adapter migration.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[railway-app]

🚅 Deployed to the ironclaw-pr-6980 environment in ironclaw-ci-preview

Service	Status	Web	Updated (UTC)
ironclaw	✅ Success (View Logs)	Web	Aug 1, 2026 at 1:43 am

[BenKurrek]

Coordinator sign-off (Wave 1 slot 4 — WS1.4 ironclaw_product_contracts + the adapter co-movement).

• The slice's real content was a measured discovery: host_api::product_adapter is one connected component, so the adapter traits could only leave as a 15-module co-movement — established by import-graph evidence before any code moved. Three placements were forced by naming-couplings and recorded as such; the package_lifecycle ruling followed §6.1.3's explicit Owns entry, with the feat(extensions): register hosted MCP servers #6930 collision resolved by splitting the lifecycle id downward rather than leaking product-tier edges into four kernel crates.
• Collapse verified to the file: post-merge diff is the identical 209-file set to the pre-collapse delta with exactly one deliberate difference (adopting main's walk-exclusion into the new scan for consistency). The conflict-marker sweep caught a staged rename-conflict block that had escaped the UU list plus two swallowed base-marker lines — the class of artifact that ships silently.
• The coverage close-out found a genuine regression and fixed it with tests, not exemptions: 134 lines + 22 branch arms in the two new modules had lost their unit coverage in the move (the owning crates' suites didn't follow) — now driven 134 → 0 by 15 new tests covering the auth-prompt render path both shipped channel packages call, the full validator rejection surface, and the wire round-trips. Seven lines exempted, each with per-site evidence of unreachability. Final replay: 285/285 lines, 38/38 branches, exit 0, byte-identical harness.
• Un-masking exact (−92 from host_api, every name accounted); four enumerating gates updated-not-relaxed; AppEvent correctly left dead for the wave-closer's deletion; exceptions floor 13 re-verified.

Ready to merge. Stack note: #6981 (evidence-mint) syncs this branch down next; its collapse follows this merge.