design: decide whether write paths funnel through evaluate_state_transition or stay parallel

[Soushi888]

SoushAI analysis. Drafted by Soushi's AI assistant, reviewed and posted by @Soushi888.

Context

PR #132 built the evaluate half of the governance-as-operator architecture and deliberately left the request half open. evaluate_state_transition is a live #[hdk_extern] in zome_gouvernance/src/transition.rs, and GovernanceTransitionRequest / TransitionContext / GovernanceTransitionResult are defined in crates/shared/src/io/governance.rs. request_resource_transition, the resource-zome-side entry point that the design documents describe, does not exist.

So the operator runs as a parallel advisory path, not as the funnel. The module doc says so:

//! Parallel path alongside `propose_commitment` / `log_economic_event` —
//! Soft advisory UX lives here; Hard gates are still enforced by integrity
//! validation regardless of which coordinator entry point is used.
//!
//! TODO(§5 item 2): decide whether existing write paths should funnel through
//! this function or remain parallel. Currently parallel by design.

documentation/requirements/post-mvp/complete-resource-specification.md §5 item 2 records the same thing as an open question its author explicitly declined to settle alone.

The decision

Do propose_commitment, claim_commitment, and log_economic_event route through evaluate_state_transition, or stay parallel?

Correctness does not depend on the answer. Hard constraints live in integrity validation and fire no matter which coordinator function got there. What depends on it is the Soft advisory UX and the shape of the public API.

	Funnel	Parallel (current)
advisory_warnings return path	One place	Each write path needs its own { ..., advisory_warnings } extension
Matches specifications.md §3.2 and the three specifications/governance/ design docs	Yes	No, those docs describe a request/evaluate pair
REQ-ARCH-07 and REQ-ARCH-09 as written	Satisfied	Satisfied in spirit, not in interface
Cost	Rework of three write paths plus their Sweettests, and a breaking change to their return types	None now, but the design docs stay wrong and the divergence widens

Why this is filed now

PR #131 (docs sync) could not resolve it. It is a design decision, not doc drift, so #131 did the honest minimum instead: specifications/governance/cross-zome-api.md and governance-operator-architecture.md now open with a status banner naming which half of the architecture exists, specifications.md §3.2 marks request_resource_transition as a design target rather than an API, and pai/cursor-rules/20-architecture.md no longer teaches agents a call chain whose entry point is absent. Those banners are a holding pattern. They should come off once this is settled.

Done when

• The funnel-versus-parallel question has an answer recorded in complete-resource-specification.md §5.
• If funnel: request_resource_transition exists, the three write paths route through it, and their return types carry advisory_warnings.
• If parallel: the three specifications/governance/ documents and specifications.md §3.2 are rewritten to describe the parallel model, and request_resource_transition is removed from them rather than left as a phantom.
• Either way, the status banners added in docs(sync): harmonize documentation and READMEs across the repo #131 come off, and IMPLEMENTATION_STATUS.md § Governance-as-Operator Architecture reflects the outcome.

Related

• PR feat(resource)!: NDO Layer 1 typed governance rules, classification constraints, and OperationalState #132 (built the evaluate half)
• PR docs(sync): harmonize documentation and READMEs across the repo #131 (added the status banners as a holding pattern)
• Define cross-zome interface types for governance-as-operator protocol #41, Implement pure-function GovernanceEngine for state transition evaluation #42, test(v0.1.0): harden e2e and Sweettest coverage for the peer-mesh release #127 (governance-as-operator track)
• documentation/requirements/post-mvp/complete-resource-specification.md §5 item 2