# Operation Contract Status: **frozen semantic contract, 2026-09-16; external Action authority clarification approved 2026-09-30**. This document is the authoritative owner of Operation Contract meaning. It records the approved contract from the completed PLAN audit and the subsequent explicit Operation-identity authority clarification. The bounded Business-scoped Type/Object representation, invocation foundation, no-network `send_email` simulation and IDY-009 demonstrator handlers are implemented and evidenced separately; the broader contract and integration surface remains incomplete. Owner: reusable Operation Contract semantics and its boundaries to invocation, Commands, governance, workflows, presentation and evidence. Canonical prerequisites: [Objects and types](objects-and-types.md), [Business model](business-model.md), [Identity and governance](identity-and-governance.md), [Semantics](semantics.md), [Time and events](time-and-events.md), and [Workflows and automation](workflows-and-automation.md). The [IDY-008 configuration contract](../implementation/idy-008-contract.md) consumes this contract; it does not replace it. ## Definition and Distinctions An **Operation** is a governed executable action that may be enacted within or support a Capability. An **Operation Contract** is its approved, versioned, declarative contract: it governs the Operation's authority context, inputs, targets, effects, approval requirements, execution and evidence. The reusable executable action meaning begins at the Operation Contract, but a Capability is a broader business/product composition that may include multiple Operations, Data, Workflow, Logic and presentation configuration. One-time execution data belongs to the invocation, Command and evidence layers. - **Capability**: the broader reusable or Business-configured business composition; its meaning is owned by the product capability model. - **Operation**: the governed executable action enacted within or supporting a Capability. - **Operation Contract**: the reusable semantic contract for that Operation. - **Operation Invocation**: one request to invoke an Operation with concrete inputs and targets. - **Command**: the governed stable-identity request produced for that invocation and submitted to the existing mutation boundary. - **Action Execution**: execution evidence for the invoked Operation. - **Attempt**, **Outcome**, **Event** and **Provenance**: execution and history evidence. `Operation Contract != Command` `Operation Contract != Policy` `Operation Contract != AuthorityGrant` `Operation Contract != Workflow` `Operation Contract != Action Execution` `Capability != Operation Contract` `Capability != Operation` `Operation Contract != executable code` An Operation Contract is not permission. Possessing an Operation reference does not authorize its use. ## User Admission Operations The identity lifecycle has two narrowly bounded, implemented admission Operations: `principal.register` and `principal.confirm` (legacy identifiers for the User registration and User confirmation Operations; the persisted User Type retains the legacy name Principal). Both are active revision `1` Operations resolved through the governed Command boundary and registered with trusted handlers. | Operation | ID | Revision | Trusted handler | | --- | --- | --- | --- | | `principal.register` | `9f4f6b8c-3d2e-4f10-8a11-223344556698` | `1` | `platform.principal-register` | | `principal.confirm` | `9f4f6b8c-3d2e-4f10-8a11-223344556699` | `1` | `platform.principal-confirm` | `principal.register` accepts only the approved registration inputs and creates server-owned pending User identity, normalized identity association, separate credential material and a protected confirmation challenge. It cannot accept caller-supplied User IDs, Business identity, Membership, AuthorityGrant, Policy, executor identity or arbitrary effects. Its result and durable evidence use the existing Command/idempotency/conflict boundary. The registration result is an admission outcome, not a transport contract for a verification secret. The trusted handler may create protected challenge material and hand an internal delivery request to the Communication responsibility, but an HTTP/API caller must not receive the raw challenge in a normal response. Confirmation is initiated from the out-of-band message and binds the supplied verification material to the intended User and identity. Delivery acceptance, delivery failure and unknown delivery outcome are recorded as communication outcomes and do not change User status; only successful `principal.confirm` changes identity state. `principal.confirm` consumes one correctly bound, unexpired challenge exactly once, rejects replay, mismatch, expiry and concurrent losers, transitions the pending User to confirmed/active state and atomically issues only the release-defined bounded onboarding AuthorityGrant for `business.create` against Type `Business`. It cannot elevate to general administration, issue grants, modify Policy or create a Business. Authentication establishes the runtime identity/session context; it does not itself grant Business authority. Both operations retain durable Command, Attempt, Outcome, Event and Provenance evidence as applicable; neither operation is permission to bypass authentication, Policy or the normal governed mutation boundary. Duplicate registration of an already-used normalized identity is a controlled conflict with non-enumerating feedback. A separate resend-confirmation capability may create a fresh challenge for a still-pending User under rate limits; old, consumed, expired or superseded challenges remain invalid. A challenge is never accepted by the password login path and is never a general authentication credential. The platform-scoped `business.create` operation is the governed first Business-creation operation after onboarding. Its User, Business, Membership, AuthorityGrant, Policy and evidence identifiers are server-owned; caller-supplied security identities or effect plans are rejected. Matching redelivery of the same Command identity and fingerprint is idempotent, while changed content under that identity is a conflict. Command/admission evidence and all resulting Business bootstrap effects commit atomically in the same transaction; a Business-effect failure leaves no durable admission evidence or partial bootstrap state. ## Platform Definition Publication `definition.publish` is the distinct generic governed platform-scoped Operation for publishing platform-owned Definitions. It accepts one complete Definition payload that has passed the applicable deterministic structural/type validation. Every such Definition uses the universal `OBJECT_DEFINITION_TYPE`, including platform User, Business, Capability and constituent Definitions. Draft authoring or editing is not part of this Operation. Inline recursive composition remains valid; each separately addressable Definition dependency must already be publication-available at the exact referenced Object revision before the dependent Definition may be published. The approved Candidate A reference carries only a target Object ID and exact positive Object revision; the target revision supplies its Type and exact Type revision. Inline constituents remain ordinary typed values without separate Object identity. The Operation may create a new Definition Object or revise an existing Definition Object. Creation establishes a new Object identity and its initial retained Object revision. Revision preserves the same Object identity and history and requires the exact expected Object revision; a stale revision is rejected rather than overwritten. A successful Command atomically commits the Definition mutation, required provenance/evidence and publication availability of the exact resulting Object revision. Availability is the outcome of the governed publication action, not a universal `status` field, Object existence, Type membership or a substitute for Object identity/revision. Definition payload fields, Object revision, Type revision and publication evidence remain distinct. Release and publication identifiers remain provenance/evidence, not Definition identity. The already-established project-owner User (a platform account; the User Type is persisted under the legacy name Principal) receives a direct platform AuthorityGrant for `definition.publish` and the matching active platform Policy through normal platform installation/configuration. The Operation is not self-authorising and does not repurpose `business.create`, an admission Operation, a Business-scoped Operation or Initialization. Publisher reassignment and revocation are deferred. See [Platform Definition Publication Authority](identity-and-governance.md#platform-definition-publication-authority) and the selected [publisher identity configuration](../implementation/security-and-operations.md#definition-publication-authority-configuration). The Definition mutation and required successful Command/execution evidence commit atomically. Retained provenance identifies the acting User, exact Operation revision, applicable AuthorityGrant and Policy revisions, Command and resulting Definition Object revision, together with the relevant Attempt, Outcome and Event evidence under their existing contracts. Rejection, stale revision or failure must not leave a successful publication effect or success evidence; failure evidence follows the existing Command contract. The Operation makes no Business instance, performs no Business application/adoption or migration, creates no Project, and does not execute Workflow or Logic. It is separate from draft authoring, Genesis, Initialization, platform opening, Explorer and IDY-008 application; none is a publication mechanism. Business application remains a separate contract that binds an exact Definition identity/revision. Manifests and the historical CapabilityProjector are not publication authority. This is the semantic Operation/Command contract; it does not assert that the Operation, its grant path, or runtime handler is installed or implemented. The runtime accepts only the canonical Definition reference form and bounded validation contract; it must not infer alternate encodings or latest-revision fallback. The universal Definition payload and dependency-readiness contract is specified in [Objects and Types](objects-and-types.md#generic-definition-payload-and-reference-contract). A successful Command makes only the exact resulting Object revision publication-available. Create/revise effects, provenance and required success evidence commit atomically; retries use the existing Command identity/fingerprint rules and stale expected Object versions fail without publication. ## Actions and Operation Contracts An Action is the provider-independent semantic request available within a Capability. For this foundation, its executable contract is the existing exact-revision Operation Contract Object. The Action meaning and Operation Contract identity are not duplicated into a second Action Type, registry or execution engine. An Operation Contract defines typed parameters, targets, validation/preconditions, result/failure contract and a trusted handler key; runtime and current governance determine whether it can be invoked. Workflow-control Operations and low-level mutation effects are not automatically user-facing Actions. Each Operation input may declare its `type`, human-readable `label` and `description`, `required` status, validation and a parameter `source`. Supported sources are explicit user input, the current Object, related Objects, Business configuration/context, another Action and trusted programmatic invocation. Resolution is server-side using authorized reads and exact referenced revisions where applicable; resolved source references accompany the semantic request. The runtime validates resolved values against the declaration. A caller cannot supply a value for an input whose source is server-controlled; such an override is rejected. Trusted programmatic values come only from the trusted invocation context, not the request. UI and API adapters transport user values but do not implement source semantics. Arbitrary expressions and caller-selected source paths are not permitted. `send_email` is the canonical provider-independent communication Action. Its declared inputs may include recipients, cc/bcc, sender, subject, body or template, attachments and channel context. Its Operation Contract does not name or depend on Outlook, Gmail, SMTP or another provider. The initial trusted stub may simulate this request; it cannot claim external delivery. An external Action with no local mutation target is authorized against its governed Operation Contract identity. Business invocation requires active Membership, a matching Business AuthorityGrant and an active allowing Policy scoped to the Operation Type and exact Operation Object ID. The Operation reference itself is not authority. The exact current Operation revision and applicable authority/Policy are rechecked at the Command boundary. Do not infer a Business, Connection, Action Execution or other target Type, and do not introduce a Connection Type or parallel authorization subsystem for this subject. In the current Operation representation, `execution_kind` distinguishes `mutation` from `external_action`; an external Action declares `authority_subject: operation_identity`. Operation Type descriptor revision 1 remains valid for existing Operations. Retained descriptor revision 2 adds the optional metadata without changing revision-1 contract values. The Type descriptor revision is distinct from the Operation Contract's own `revision` and from the generic Object's retained revision; invocation binds the exact Operation identity and revision. The initial `send_email` handler is a no-network simulation only. ## Representation The initial definition-driven initialization slice consumes Business-scoped Operation objects for constituent application. These Operations are exact-revision, trusted-handler references; they do not define a second initialization mutation path. Their effects are submitted through the existing Operation Invocation -> CommandHandler boundary with current Business authority and expected-version checks. **Operation Contract = ordinary addressable Object + dedicated Type.** The Operation Contract is independently addressable and revisioned data. It may have independent identity, retained revisions, Business scope, relationships to other addressable configuration, exact `id + revision` references, provenance/history and a governed lifecycle. The dedicated Type defines the structure of Operation Contract Objects. The Type does not contain executable code. The admission Operation identities and trusted handler keys above are current implementation identities. Other Operation Object identities, release identities and manifest identities remain governed by their approved release/build processes. ## Five Frozen Decisions ### 1. Representation The contract is an ordinary addressable Object with a dedicated Type. It is durable, independently addressable, revisioned and subject to the universal typed-object and governance model. ### 2. Execution model Operation Contracts are interpreted by fixed trusted handlers in the runtime, keyed by approved operation names. There is no general-purpose declarative effect compiler or expression language. The contract may describe identity and revision, machine-readable name, scope, typed inputs, target roles, required server-derived context, dependencies, status, handler key, optional result metadata and optional explanatory metadata. Trusted runtime code owns operation-specific invariants, target resolution, current-state checks, conditional behavior, effect construction, concrete Command construction and operation-specific semantic validation. `handler_key` is an allowlisted, non-executable semantic identifier only. It must not contain PHP class or method names, callbacks, scripts, SQL, dynamic loader paths or executable configuration. It names an approved runtime meaning; it does not select or load caller-supplied code. ### 3. Mutation boundary The authoritative execution path is: ```text Invocation Surface -> Operation Reference -> Exact Operation Revision Resolution -> Server Context -> Typed Input Validation -> Target Resolution -> Operation Preconditions/Invariants -> Policy/Authorization -> One Command -> CommandHandler -> Atomic Mutation -> Evidence ``` The existing `CommandHandler` remains the sole mutation authority. An Operation Contract provides no alternate mutation path and introduces no new mutation primitive. Views, Forms, Workflows, APIs and AI must not directly construct arbitrary generic effects. Multi-effect atomicity remains owned by `CommandHandler`. Foundation Command effects are distinct from persisted Operation Contracts. For the bounded generic Object and transition migration, `object.create`, `object.update` and `object.transition` remain governed Command effect identifiers; they are not revisioned Operation Object identities and must not be wrapped in manufactured `operation_reference` values. Their invocation still requires authenticated server context, authorization and Policy evaluation, expected-version checks, idempotency, provenance and the existing Command evidence boundary. A presentation action that invokes a persisted Operation Contract continues to use the exact Operation identity and revision defined below. A Form reference grants permission to neither kind of action. Generic transition effects resolve the current State Definition from either an exact persisted `state_id` or a data-defined `status` code when the target Type's existing descriptor stores lifecycle state as a value property. The transition and destination State Definitions are still exact Business-scoped references; the Command preserves the target's existing storage representation when revising it. No Type-specific transition branch or second lifecycle store is permitted. ### 4. Conditional behavior Conditional effects are not represented as an arbitrary declarative branch language. For `decide_qualification`, the fixed trusted handler: - creates the Decision; - transitions Qualification from `submitted` to `approved` or `rejected`; - also transitions Enquiry to `rejected` when determination is `rejected`; and - does not perform the Enquiry rejection transition when determination is `approved`. The contract declares the typed determination input, dependencies and approved operation semantics. The fixed handler owns the branch. Arbitrary expressions, predicates, scripts, selector languages, dynamic queries, nested conditions and caller-defined effect lists are forbidden. ### 5. Lifecycle and revision binding The lifecycle is: - `draft` - `active` - `retired` Only `active` revisions receive new invocations. `draft` revisions may be inspected and validated but cannot execute. `retired` revisions cannot receive new invocations. Historical Commands and execution evidence retain the exact Operation revision used. Retirement does not rewrite history. Delayed or replayed execution bound to a retired revision fails closed or undergoes explicit governed migration/rebinding. Lifecycle changes use the existing governed mutation path and remain subject to authority and Policy. Lifecycle status is not permission. Every execution surface binds an exact Operation Contract revision: | Consumer | Required binding | | --- | --- | | View Action | Exact Operation identity and revision | | Workflow Node | Exact Operation identity and revision | | API invocation | Resolution to and recording of an exact Operation revision | | AI proposal | Exact Operation identity and revision | | Historical Command | Retained exact Operation revision | Operation revisions are immutable. An active revision is never edited in place; a semantic change requires a new revision. A retired revision remains available for historical inspection/evidence, but not new execution. ## Contract Shape The authoritative minimum shape is: ### Required `id`, `revision`, `name`, `scope`, `inputs`, `targets`, `context`, `dependencies`, `status`, `handler_key`. ### Optional `label`, `result`, `policy_refs`, `description`, `execution_kind`, `authority_subject`. `execution_kind` and `authority_subject` are optional for legacy mutation Operations. An `external_action` must use `authority_subject: operation_identity`; the runtime rejects unsupported execution kinds and external handlers. `policy_refs` are dependency or association metadata only. They never grant permission, override Policy or establish authority. ### Forbidden Operation Contract data must not contain: - PHP, SQL, callbacks, executable code, class names, method names or scripts; - arbitrary expressions, predicates, selector/query languages or arbitrary effect arrays; - embedded conditional branches or arbitrary mutation identifiers; - Membership definitions, AuthorityGrant definitions or User authority; - Business ownership, subscription state or Policy overrides; - workflow execution logic, scheduling, queueing, retry logic or compensation; - external side effects; or - AI-generated executable content. `handler_key` is an allowlisted runtime semantic key and does not weaken this prohibition. ## Ownership Boundaries ### Operation Contract owns Reusable business capability identity, immutable semantic revision, machine name, scope, typed input declarations, target roles, required context categories, dependency references, lifecycle status, approved handler semantic key and optional result metadata. ### Runtime owns Operation-specific executable semantics, target resolution, preconditions and invariants, concrete generic effect construction, conditional behavior, Command construction, final authorization/admission and atomicity. ### Policy and Authorization own Permission, actor authority, Membership, AuthorityGrant, applicable Policy and current Business authority context. Policy still determines whether an authorized actor may perform an Operation. Policy and authority remain outside the Operation Contract. The contract can reference applicable Policy dependencies, but it cannot define permission, grant authority or override admission decisions. ### Command owns Invocation identity, concrete targets, expected object revisions, concrete payload/effects and the governed execution request. ### Evidence owns Action Execution, Attempt, Outcome, Event and Provenance, including historical execution state. ### Invocation surfaces own only invocation concerns View, Workflow, API and AI surfaces may reference an approved Operation and supply permitted inputs/context. They must not alter Operation effects, preconditions, invariants, Policy, authority, revision semantics or executable behavior. AI proposals remain non-authoritative. ## Dependencies An Operation may depend only on the following exhaustive global allowlist of Object Types: - Type; - State; - Transition; - Relationship Type; - Policy; - Business; and - Platform prerequisite. Anything outside this allowlist is ineligible. Views, Forms and Workflow Definitions are not semantic dependencies of an Operation; they consume Operations. Operation Type is prohibited as a dependency because recursive Operation composition is prohibited. This allowlist is not implicitly extensible. An object dependency is exactly: ```json {"kind":"object","id":"","revision":1,"expected_type":""} ``` The `kind` identifies the dependency form, `id` identifies the Object, `revision` identifies the exact retained Object revision, and `expected_type` declares the required Object Type. `expected_type` is mandatory and must match the authoritative Type of the exact referenced revision. The dependency never silently follows or substitutes the Object's current revision. A release dependency retains the existing form: ```json {"kind":"release","release_id":"","version":1,"digest":""} ``` Release dependencies remain structurally recognized, but they fail closed for Operation dependency resolution pending an authoritative release verifier. This contract does not create that verifier. Every object dependency must resolve to the exact declared Object revision, match `expected_type`, satisfy the permitted platform or Business scope, and satisfy the applicable availability predicate. Business-scoped dependencies must belong to the same Business as the Operation. Platform prerequisites must remain within the permitted platform scope. Dependency checks occur both before an Operation revision is persisted and again when the Operation is resolved for execution. Exact-revision availability is Type-specific: | Eligible Type | Exact-revision availability semantics | | --- | --- | | Type | The exact revision must exist, be structurally valid as a Type, be within permitted Business/platform scope, not be retired or invalidated, and otherwise be governed as usable by the Type system. Where the Type system exposes no authoritative usability predicate, resolution and persistence must fail closed rather than infer availability from existence or structural validity. | | State | The exact revision must exist, be structurally valid as a State, be within the permitted Business/scope boundary, and not be retired or otherwise explicitly made unavailable by authoritative State semantics. A newer State revision does not make the referenced revision unavailable. | | Transition | The exact revision must exist, be structurally valid as a Transition, be within the permitted Business/scope boundary, and not be retired or otherwise explicitly made unavailable by authoritative Transition semantics. A newer Transition revision does not make the referenced revision unavailable. | | Relationship Type | The exact revision must exist, be structurally valid as a Relationship Type, be within the permitted Business/scope boundary, and not be retired or otherwise explicitly made unavailable by authoritative Relationship Type semantics. A newer Relationship Type revision does not silently replace the referenced revision. | | Policy | The exact revision must exist, be structurally valid as a Policy, be within the permitted Business/scope boundary, remain governed and usable under the authoritative Policy model, and not be retired, revoked, invalidated, or otherwise explicitly made unavailable. Object existence alone is insufficient. | | Business | The exact Business Object revision must exist, represent the Business identified by the dependency, be an authoritative active/usable Business under the existing Business governance model, and not be retired, disabled, invalidated, or otherwise made unavailable. Business isolation remains mandatory. | | Platform prerequisite | The exact revision must exist, satisfy authoritative platform-prerequisite identity and Type requirements, remain within permitted platform scope, be approved/trusted under the existing platform governance mechanism, and not be revoked, invalidated, retired, or otherwise made unavailable. This contract does not create a release verifier or platform trust subsystem. | If a required authoritative availability predicate is not exposed for an eligible Type, the dependency is unavailable for this contract; implementation must fail closed and must not invent lifecycle semantics. A newer revision never makes the exact referenced revision unavailable merely because it is newer. If a dependency later becomes unavailable, the persisted Operation remains unchanged. Resolution fails while that exact revision is unavailable and may resume if the same exact revision becomes available again. There is no automatic rebinding to a current revision and no automatic Operation revision creation. Dependency failure does not mutate retained Operation history. An Operation Contract cannot establish or override User, Business authority, Membership, AuthorityGrant, Policy, subscription entitlement, target visibility, expected object revisions, current state, final effect authorization, Command admission or transaction ownership. The server remains authoritative. In particular, `Operation Contract != Permission` and `Operation Contract != Authority`. An Operation reference grants no installation authority, Business authority, workflow authority or subscription entitlement; it cannot bypass authority or subscription entitlement (intended future architecture; all Businesses are currently treated as active and no entitlement is enforced). ## Four Initial IDY-008 Validation Operations These are approved semantic validation examples, not installed Operation Objects, Type identities or release artifacts. ### `create_enquiry` Inputs are source, summary, received time and a contact reference or unmatched status. An optional Person or Organisation contact is resolved server-side. The handler creates an Enquiry in `received`, establishes the permitted contact relationship where applicable, enforces the contact invariant and executes through one governed Command. ### `submit_qualification` Inputs are requirements and fit assessment. The target is an Enquiry with its exact current revision. The Enquiry must be `received`; the handler creates Qualification, relates it to Enquiry and transitions Enquiry to `qualification_submitted`, atomically through one governed Command. ### `decide_qualification` Inputs are determination and rationale. Targets are Qualification and originating Enquiry with exact current revisions. Required context includes the authorized reviewer, recorded Qualification submitter, Business and applicable Policy. Qualification must be `submitted`, and reviewer and submitter must differ. The handler creates Decision, transitions Qualification to `approved` or `rejected`, and on rejection transitions Enquiry to `rejected`, atomically through one governed Command. ### `create_project_from_qualification` Inputs are scope summary and responsible User reference. Targets are Qualification and originating Enquiry with exact current revisions. A positive Decision must exist; Qualification must remain eligible; no active Project may already exist for the applicable Qualification; required relationship slots must be available; and the responsible User must be valid and authorized. The handler creates Project and required relationships, transitions Enquiry to `scoped` and executes atomically through one governed Command. None of these examples requires a new mutation primitive or a general-purpose interpreter. ## Security and Authority Boundary Operation Contract data cannot establish or override User, Business authority, Membership, AuthorityGrant, Policy, subscription entitlement, target visibility, expected object revisions, current state, final effect authorization, Command admission or transaction ownership. A caller cannot gain permission merely by possessing an Operation reference. Subscription gates are defined by the canonical subscription contract (intended future architecture; all Businesses are currently treated as active and no entitlement is enforced), and AI remains a proposal channel rather than an authority channel. Automation and AI hold no independent authority; they act only under [authority delegated by a User](identity-and-governance.md#delegated-authority-for-automation), with the technical executor recorded as execution provenance. ## IDY-008 Boundary and Future Work Freezing this contract does not start IDY-008 implementation. The following remain separate future work: ### Pending proposal: declaration-level configuration reconciliation This is a **pending owner-approval proposal**, recorded because the current IDY-008 installer correctly rejects a proven declaration drift and the existing Operation vocabulary has no declaration-level accept-drift action. The proposed Operation is deliberately narrower than configuration installation. It accepts one already-inspected IDY-008 declaration whose persisted Object is known to differ from the trusted release and produces one ordinary `object.update` Command through the existing invocation and Command boundaries. It does not force the installer to overwrite drift, reconcile a manifest in bulk or permit caller-defined effects. | Field | Proposed value | Status | | --- | --- | --- | | semantic name | `platform.reconcile_configuration_declaration` | pending owner approval | | candidate Operation ID | `9f4f6b8c-3d2e-4f10-8a11-22334455669a` | candidate only; not allocated | | revision | `1` | pending | | scope | existing Business context; one exact IDY-008 declaration | pending | | trusted handler key | `platform.configuration.reconcile-declaration` | pending registry approval | | Command effect | one `object.update` for the exact declaration runtime Object | existing generic effect | The candidate ID is not a settled platform identity and must be checked against the authoritative Operation vocabulary before implementation. The owner must approve the name, exact UUID, revision and handler key together; implementations must not reserve or register them before that approval. #### Inputs and server-side resolution The invocation identifies the trusted `manifest_id`, `release_id`, release version and digest, one declaration ID and kind, the exact target Object ID, Type ID and Type revision, the expected current Object version, the observed persisted-value digest and the trusted replacement declaration reference. The caller cannot supply an arbitrary replacement value or effect list. The trusted handler loads and validates the approved release declaration and compiles its replacement value using the IDY-008 configuration contract. The Business is resolved from the authenticated invocation context. A caller-supplied Business ID is at most a consistency assertion and never an authority source. The handler requires the target Object to be Business-owned by that resolved Business, to have the exact declared Type and Type revision, and to be the deterministic runtime identity of the declaration. Before submitting the Command, the handler verifies that the release identity and digest are trusted; the declaration and dependencies pass the complete IDY-008 validation barrier; the current Object version equals the expected version; the current Type, Type revision and Business equal the inspected snapshot; the canonical current value digest equals the supplied persisted-value digest; and the trusted replacement value applies only to the named declaration. Any mismatch is stale or conflicting state and is rejected without a revision, success evidence or mutation of another declaration. If the current value already equals the trusted replacement, the operation returns the existing settled state without creating a new revision, subject to the normal Command identity/fingerprint check. #### Authority, handler trust and Business scope Authentication, active Membership, Business context, scoped authority and applicable Policy remain required. The recommended proposal is a distinct authority action for intentional drift reconciliation rather than silently reusing ordinary `platform.install_configuration` authority: installation authority admits an approved release, while reconciliation accepts a changed persisted value. The exact AuthorityGrant operation and Policy binding are an owner decision. In either case, the handler must perform the same commit-time authorization check and cannot trust a request-supplied grant, User, Business or Policy. The handler key is an allowlisted semantic key resolved by the trusted registry. It is not a class name and cannot be selected to execute arbitrary caller configuration. The handler may return only the governed Command plan; `CommandHandler` remains responsible for final authorization, expected-version checks, locking, evidence and commit. #### Command identity, transaction and evidence The Command reuses the IDY-008 deterministic identity and canonicalization rules. Its pre-ID semantic basis includes the reconciliation rule version, manifest/release identity and digest, declaration ID/kind, Business ID, exact target Object and Type identity, expected current Object version, observed persisted-value digest, trusted replacement-value digest and the compiled `object.update` effect. Installation attempts, timestamps and transport metadata are excluded. The same semantic retry therefore resolves to the same Command identity; changed content under that identity is a fingerprint conflict. One declaration reconciliation is one atomic Command. The target Object revision, retained history, provenance, authorization evidence and applicable Action Execution/Attempt/Outcome/Event records commit together. A failure rolls back all effects of that Command. There is no bulk transaction that can partially rewrite unrelated declarations. Reconciling several declarations is an explicit sequence of independently authorized, independently expected-versioned Commands. The retained evidence identifies the manifest, release, trusted digest, declaration, inspected target and version, observed-value digest, replacement digest, authenticated User, resolved Business, Command identity and fingerprint, handler/Operation revision, authorization result and final outcome. It uses the existing Object revision, Command, Action Execution, Attempt, Outcome, Event and Provenance structures; no reconciliation ledger or parallel configuration store is introduced. #### Retry, concurrency and failure behaviour The Command coordination lock and stable identity protect concurrent matching requests. A matching committed retry is idempotent. A retry after an unknown result must inspect existing Command and evidence before continuing. A stale Object version, changed persisted-value digest, changed Type/Business identity, changed release digest, conflicting Command fingerprint, missing authority, unavailable dependency or non-matching current value fails closed. No retry may overwrite a newer configuration revision or unrelated configuration. #### Focused regression and STAGING acceptance proposal Before implementation, the disposable governed fixture must cover an authorized valid reconciliation; unauthenticated and unauthorized Users; missing Business authority; stale target version; changed persisted-value digest; conflicting Type or Business identity; matching Command retry; changed-content retry conflict; preservation of unrelated declarations; and rollback on handler or commit failure. These are required tests of the approved implementation, not evidence that this pending Operation already exists. After separate implementation and mutation approvals, STAGING acceptance is: (1) capture a read-only snapshot of all drifted declarations and unrelated Object versions; (2) verify the trusted release digest and exact target identities; (3) invoke only the approved declaration Commands under an authenticated User with the approved authority; (4) record each settled Command, resulting Object version and retained provenance; (5) rerun the normal installer and require `already_installed`; (6) verify unrelated declarations and Objects are byte-for-byte unchanged; and (7) repeat the same invocation to demonstrate idempotency without a new revision. Evidence must include pre/post canonical value digests, exact versions, Command and provenance IDs, authorization result, installer classification and failed attempts, if any. This proposal does not authorize any of those actions. The following remain separate future work: - Operation Contract Type implementation; - Operation Object installation and the four definitions; - remaining fixed handler implementations and Operation configuration installation (the explicit-unmatched `create_enquiry` handler is implemented separately); - View Action extension; - Workflow, API and AI integration; - IDY-008 manifest declarations; - IDY-008B trust verification; - release IDs and digests; and - canonicalisation questions explicitly open elsewhere. This document does not modify `CanonicalJson.php`, create a manifest, resolve release identities or begin 008B. It does not change IDY-001 through IDY-007C runtime behavior, IDY-006B behavior, Command semantics or Workflow implementation. ## Status and Evidence This remains a frozen semantic contract and documentation authority. The separately implemented Business-scoped invocation foundation provides exact Operation revision resolution, declaration-driven input validation, server-resolved Business membership, trusted-handler allowlisting, operation-level authorization and generic Command delegation. It does not install Spearmint Operations, create domain Types or provide the four IDY-009 handlers. Implementation evidence belongs to [Implementation status](../implementation/status.md). The current implementation extends this foundation additively for the bounded IDY-009 demonstrator: `submit_qualification`, `decide_qualification` and `create_project_from_qualification` are ordinary Business-scoped Operation declarations resolved by exact revision and dispatched to trusted handlers. A trusted Operation plan may contain create, update, relate and transition effects; all effects remain inside one generic Command transaction, with expected-version checks, transition-definition validation, authorization rechecks and durable Command/Attempt/Outcome/Event/Provenance evidence. The target presentation surface invokes these Operations through the existing `OperationInvocationService`; it does not create a parallel mutation path.