@fabricorg/platform 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @fabricorg/platform
 
+## 1.13.0
+
+### Minor Changes
+
+- 749c507: Add host-owned staged descendant invocations. Actions declare an allowlist and return typed child
+  requests; Platform Host validates and redacts them atomically, releases them only after parent
+  completion, and dispatches them through fresh entitlement, authorization, admission, runtime
+  evidence, policy, and HITL decisions.
+
+  PostgreSQL migration 11 adds the staged-invocation ledger and caller-unforgeable child-origin unique
+  index. Child identity is a Host-only parent-invocation/stage-key origin. Child creation is
+  atomically fenced on the stage's pending status, lease owner, lease token, and unexpired lease;
+  PostgreSQL locks that stage row `FOR SHARE` while the fenced insert is in flight.
+
+  Each attempt settles a stage through one sequence. It first looks the child up by origin: a child
+  created by an earlier attempt is handed to the dispatcher again with its stable workflow ID while it
+  remains pending, without pre-submission checks or repeated governance, even after a deploy changes
+  the child's schema. Otherwise Host submits the child. When that submission did not itself return
+  the child (a failed check, a refusal, an error, or a timeout), Host rotates the lease token through
+  the store operation `rotateStagedInvocationLease` before an authoritative lookup, so the attempt's
+  own timed-out submission can no longer create the child. A stage is rejected only when that lookup
+  finds no child, and a dead-lettered stage records the child ID whenever the attempt found or created
+  a child. A stage becomes dispatched only after confirmed handoff, when no dispatcher is configured,
+  or when the child has already left pending. A failed child lookup settles the stage for retry and
+  does not dead-letter it. Settlements are compare-and-set on the lease owner and current token and
+  keep a child ID recorded earlier. A store error on one stage is reported through the sweep's
+  `onError` option (the Platform worker passes its own) and does not stop the rest of the batch.
+  Handoff failures retry after a constant one-second delay by default; callers provide `retryDelayMs`
+  for backoff. Public entitlement and authorization refusals now expose `SubmissionRefusalError` with
+  stable `code: "ACTION_SUBMISSION_REFUSED"`. The child inherits the parent's actor type: a
+  natural-person parent therefore does not enter agent HITL, while an agent parent follows the normal
+  agent approval route.
+
+## 1.12.0
+
+### Minor Changes
+
+- 71d306f: Add optional action-level finalization for atomic, immediate after_adapters actions, including non-idempotent actions. Export JSON finalization types, registration validation, a manifest protocol descriptor and defineFinalizingAction to guard handlers against older hosts.
+
+  Host requires atomic transactions, invocation locking and transaction-scoped lease fencing before application execution. On normal success the hook consumes stored redacted outputs and commits transaction-local domain writes, declared events, outbox and the merged result together. Hook or validation failure rolls back finalization and settles reconciliation_required when durable provider effects exist, or failed when there are none, with redacted error text. Lease loss escapes without a stale-worker verdict. Handler preparation writes remain separately committed.
+
+  If entry to or COMMIT of the final success transaction (after adapters) fails with an unknown outcome, Host raises RecoverableFinalizationError and records no verdict. An uncommitted invocation stays running for recovery; a committed completed invocation retains its stored verdict and result for re-execution.
+
+  Explicit undefined on the optional hook return fields events, resultPatch and eventSchemaVersion is treated as omitted. Payloads and result-patch values retain strict JSON validation and reject undefined.
+
+  Failed, ambiguous, degraded and accepted/handoff outcomes do not invoke the hook. Existing actions retain their lifecycle.
+
+  Before adapters, normalize hook parameters and public handler data through a JSON round-trip, stripping private handler carriers. Dates become ISO strings and undefined object properties drop; serialization failures such as cycles or BigInt fail before provider execution. Handler events are normalized separately. Hook event schema versions default to the action version when omitted.
+
+  Add optional Host eventContracts name validation for events returned by the finalize hook. It checks eventType and subjectType membership only; handler events, payload schemas and schema-version compatibility are outside this option's scope. Recovery refusal also preserves ambiguity evidence for in-flight adapter rows alongside succeeded effects.
+
+- d5e7caa: Add optional adapter-step deadlineMs durations overriding the Host-wide duration,
+  including when the Host duration is unset or zero. Action and module registration, manifest export,
+  and manifest normalization reject step durations that are not positive finite integers.
+  Host validates resolved steps before handler or adapter execution. Invalid
+  durations fail a first execution without invoking adapters; retries with recorded
+  applied effects or unknown adapter outcomes require reconciliation instead.
+  Manifests preserve valid step durations.
+
+  Correct adapterDeadlineMs documentation: it is a duration starting just before
+  step retry execution, not an epoch timestamp. Host-wide behavior is unchanged.
+  Budgets span retries; expiry prevents a subsequent attempt and signals cooperative
+  cancellation of an in-flight call. An aborted call that throws retains the existing
+  ambiguous-outcome reconciliation semantics.
+
 ## 1.11.0
 
 ### Minor Changes

package/README.md

@@ -88,6 +88,21 @@ const registry = createModuleRegistry([myModule]);
 
 The platform never auto-loads a module. The host app composes an instance-scoped registry and injects it into its hosts. Experience roles, slots, action intents, and display rendering live in `@fabricorg/experience-contracts`, carried through the namespaced `fabric.experience/v1` extension.
 
+## Staged descendant invocations
+
+An action may declare `stagesInvocations` as the child action IDs it is allowed to stage. Its
+handler returns requests through `ActionResult.stagedInvocations`; an `after_adapters` finalizer may
+add requests through `ActionFinalizationResult.stagedInvocations`. Each request contains only a
+stable key, an action ID, and parameters. Actor, tenant, space, correlation, causation,
+authorization, provenance, and child identity remain Host-owned.
+
+Module registration rejects unknown targets, self-targets, capture-authority targets, and targets
+in another module unless that module is a declared dependency. A staged child is not delegated
+under the parent's authorization decision: dispatch submits it through the current registered
+action, entitlement, authorization, admission, runtime-evidence, and dispatcher pipeline. See the
+[`@fabricorg/platform-host` staging contract](../platform-host/README.md#staged-descendant-invocations)
+for transaction, recovery, release, and limit semantics.
+
 ## Exporting a module manifest
 
 Downstream tooling — semantics exporters, docs generators, tool generators — often needs a module's ontology as data rather than live code. `@fabricorg/platform/manifest` exports a stable, JSON-serializable, versioned description of any `FabricModule`:
@@ -101,7 +116,7 @@ const json = JSON.stringify(manifest, null, 2);
 
 `exportModuleManifest` is a pure function of the module object: it does not touch the registries and the module does not need to be registered first. Declaration order is preserved everywhere, so the same module always produces byte-identical JSON. Function fields (`handler`, policy `evaluate`, transition `guard`, dynamic `targetState`, adapter `getInput`) are never serialized — the manifest contains definitions only, never raw parameter values, secrets, or runtime data. Manifest v2 object registrations may include `PortableJsonSchema`, qualified relations, namespaced semantic annotations, and enforcement-owned invariants. Actions whose validators expose `toJSONSchema()` include `parameterSchema` and optional `resultSchema` definitions. `normalizeModuleManifest` and `normalizeModuleManifestBundle` let v2 readers accept v1 input without promising down-conversion.
 
-An entity schema does not validate arbitrary writes through `TDb`. Persisted-record validation requires an explicit Host/database adapter. When an action declares `resultSchema`, Platform Host validates the public result after the handler and before events or adapters; failure rolls back domain writes only when the Host store has a transaction provider that includes them.
+An entity schema does not validate arbitrary writes through `TDb`. Persisted-record validation requires an explicit Host/database adapter. For actions without `finalize`, when an action declares `resultSchema`, Platform Host validates the public result after the handler and before events or adapters; failure rolls back domain writes only when the Host store has a transaction provider that includes them.
 
 An action may also declare `admitSubmission`, an async check that decides whether a submission may be recorded at all. It receives the trusted `tenantId`, `spaceId`, `actorId` and `actorType`, the submitted parameters and a `signal` (`ActionAdmissionSignal`, a structural subset of `AbortSignal`; Host passes a real one), and answers `{ admitted: true }` or `{ admitted: false, code }` with a fixed code. `@fabricorg/platform-host` 7.3.0 and later runs it after authorizing the submitter and before writing anything for the submission, refuses on a throw, timeout or any other answer, and passes the admission time to the handler as `ActionContext.admittedAt`. An older host ignores the field, so a handler that relies on it should refuse without `ctx.admittedAt`. Registration rejects an `admitSubmission` that is not a function.
 
@@ -141,6 +156,26 @@ Every `invokeAction(id, params)` call goes through:
    state-guard, adapter, or finalization failure semantics; see the
    [Host boundary and rollback contract](../platform-host/README.md#atomic-mutation-unit-of-work).
 
+   Provider-dependent records can use the optional action-level `finalize` hook through
+   `defineFinalizingAction`. It requires an atomic, immediate `after_adapters` action;
+   idempotency is not required. Before adapters, Host normalizes the hook's parameters and
+   public handler data with `JSON.parse(JSON.stringify(value))`, then validates the normalized
+   JSON: Dates become ISO strings, undefined object properties drop, class instances use their
+   JSON representation, and non-finite numbers become null. Serialization failures such as
+   cycles or BigInt fail before adapter execution. Host strips private `eventResultFields`
+   from hook handler data; handler events are normalized separately. The hook receives copies
+   of those saved inputs and ordered succeeded/skipped stored redacted adapter outputs, plus
+   transaction-bound `db` without services. Hook event schema versions default to
+   `action.version` when omitted.
+   It returns declared events and/or a shallow result patch. The manifest exports only
+   `finalization: { protocol: "atomic-after-adapters-v1" }`, not the callback.
+   The helper refuses older hosts before handler code runs. See the
+   [Host finalization contract](../platform-host/README.md#action-level-finalization) for
+   transaction requirements, validation, rollback and reconciliation semantics.
+   With a compatible durable preparation checkpoint, Host recovery reuses recorded outputs
+   and replays finalization without rerunning the handler. Missing or incompatible evidence
+   retains effect-aware refusal; see the Host finalization contract for rollout and limits.
+
 4. **Adapters** — for each `actionDef.adapterSteps`, the registered implementation runs via
    `executeWithAdapterRetry` (idempotent retry, exponential backoff, and an optional per-adapter
    circuit breaker; see [Adapter circuit breakers](#adapter-circuit-breakers)). Adapters may
@@ -534,6 +569,16 @@ Lifecycle evidence copies the supplied metadata's checksums; its options do not
 previously generated metadata. This option does not change `FieldRedactor`, `hash`,
 `tokenize`, `stableChecksum`, or packet-level checksum algorithms.
 
+## Adapter step deadlines
+
+Adapter steps may declare `deadlineMs`, a positive finite integer duration in
+milliseconds. Platform Host uses it instead of its `adapterDeadlineMs` duration for
+that step. The budget begins just before retry execution and spans attempts and
+retry delays. Action and module registration, manifest normalization and export,
+and Host execution validate step durations. Host rejects invalid resolved steps
+before handler or adapter execution. Manifest export preserves valid durations.
+See the Platform Host README for cooperative cancellation and failure semantics.
+
 ## License
 
 MIT

package/dist/actions/index.cjs

@@ -14,6 +14,33 @@ function isActorType(value) {
 function assertActorType(value) {
 	if (!isActorType(value)) throw new Error(`Invalid actorType: ${value}`);
 }
+/** Validate declarations at registration and at dynamically resolved execution boundaries. */
+function assertActionFinalization(action) {
+	if (action.finalize === void 0) return;
+	if (typeof action.finalize !== "function") throw new Error("Action finalization hook must be a function.");
+	if (action.eventPhase !== "after_adapters") throw new Error("Action finalization requires eventPhase after_adapters.");
+	if (action.kind !== void 0 && action.kind !== "atomic") throw new Error("Action finalization requires an atomic action.");
+	if (action.execution?.completion !== void 0 && action.execution.completion !== "immediate") throw new Error("Action finalization requires immediate completion.");
+}
+/** Refuse older hosts before application handler code executes. Use for distributed finalizing actions. */
+function defineFinalizingAction(action) {
+	assertActionFinalization(action);
+	const handler = action.handler;
+	return {
+		...action,
+		handler: async (ctx, params) => {
+			if (ctx.finalizationProtocol !== "atomic-after-adapters-v1") throw new Error("Host does not support atomic-after-adapters-v1 finalization.");
+			return handler ? handler(ctx, params) : {
+				success: true,
+				data: {}
+			};
+		}
+	};
+}
+/** Validate optional step execution budgets before accepting or executing an action. */
+function assertAdapterStepDeadlines(action) {
+	for (const step of action.adapterSteps ?? []) if (step.deadlineMs !== void 0 && (!Number.isInteger(step.deadlineMs) || step.deadlineMs <= 0)) throw new Error(`Action "${action.actionId}" adapter step deadlineMs must be a positive finite integer.`);
+}
 function assertActionId(actionId) {
 	if (!/^[a-z][a-z0-9-]*\.[a-z][a-z0-9_]*$/.test(actionId)) throw new Error(`Invalid action ID: ${actionId}`);
 }
@@ -24,6 +51,8 @@ function createActionRegistry(definitions = []) {
 		if (actions.has(definition.actionId)) throw new Error(`Action "${definition.actionId}" is already registered`);
 		if (definition.mutatesDomain && definition.emitsEvents.length === 0) throw new Error(`Action "${definition.actionId}" mutates domain but emits no events. Every mutating action must emit at least one AssetEvent.`);
 		if (definition.admitSubmission !== void 0 && typeof definition.admitSubmission !== "function") throw new Error(`Action "${definition.actionId}" declares admitSubmission that is not a function.`);
+		assertAdapterStepDeadlines(definition);
+		assertActionFinalization(definition);
 		actions.set(definition.actionId, definition);
 	};
 	for (const definition of definitions) register(definition);
@@ -39,9 +68,12 @@ function createActionRegistry(definitions = []) {
 }
 //#endregion
 exports.ACTOR_TYPES = ACTOR_TYPES;
+exports.assertActionFinalization = assertActionFinalization;
 exports.assertActionId = assertActionId;
 exports.assertActorType = assertActorType;
+exports.assertAdapterStepDeadlines = assertAdapterStepDeadlines;
 exports.createActionRegistry = createActionRegistry;
+exports.defineFinalizingAction = defineFinalizingAction;
 exports.isActorType = isActorType;
 
 //# sourceMappingURL=index.cjs.map

package/dist/actions/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../actions/index.ts"],"sourcesContent":["import type { SurfaceDeclaration } from \"../discovery\";\nexport type ActionId = `${string}.${string}`;\n\nexport interface SchemaParseIssue {\n\tpath: PropertyKey[];\n\tmessage: string;\n}\n\nexport type SchemaParseResult<T = unknown> =\n\t| { success: true; data: T }\n\t| { success: false; error: { issues: SchemaParseIssue[] } };\n\nexport interface SchemaValidator<T = unknown> {\n\tparse(input: unknown): T;\n\tsafeParse(input: unknown): SchemaParseResult<T>;\n}\n\nexport type ActorType =\n\t| \"natural_person\"\n\t| \"agent\"\n\t| \"system\"\n\t| \"service_account\"\n\t| \"external_system\"\n\t| \"integration\";\n\nexport const ACTOR_TYPES: readonly ActorType[] = [\n\t\"natural_person\",\n\t\"agent\",\n\t\"system\",\n\t\"service_account\",\n\t\"external_system\",\n\t\"integration\",\n] as const;\n\nexport function isActorType(value: string): value is ActorType {\n\treturn (ACTOR_TYPES as readonly string[]).includes(value);\n}\n\nexport function assertActorType(value: string): asserts value is ActorType {\n\tif (!isActorType(value)) {\n\t\tthrow new Error(`Invalid actorType: ${value}`);\n\t}\n}\n\nexport type ActionStatus =\n\t| \"pending\"\n\t| \"running\"\n\t| \"completed\"\n\t| \"failed\"\n\t| \"blocked_by_policy\"\n\t| \"waiting_for_approval\"\n\t| \"reconciliation_required\"\n\t| \"validation_failed\";\n\nexport interface FabricRuntimeServices {\n\treadonly [serviceName: string]: unknown;\n}\n\nexport interface ActionContext<TDb = unknown> {\n\tactionInvocationId: string;\n\ttenantId: string;\n\tspaceId: string;\n\tactorId: string;\n\tactorType: ActorType;\n\tcorrelationId: string;\n\tcausationId?: string;\n\tprovenance?: { source: string; auditAttributes?: Record<string, string> };\n\tdb: TDb;\n\tservices?: FabricRuntimeServices;\n\t/**\n\t * When the host admitted this invocation's submission through the\n\t * action's `admitSubmission` check, read from the durable invocation\n\t * record. Absent when the action declares no check, or when the runtime\n\t * that built this context does not run declared admission checks (a host\n\t * older than the one that introduced them). A handler whose action\n\t * declares `admitSubmission` can refuse to run without it.\n\t */\n\tadmittedAt?: Date;\n}\n\n/**\n * Trusted facts a host gives an action's `admitSubmission` check. Scope and\n * actor come from the host's authenticated submission, never from the\n * parameters.\n */\nexport interface ActionAdmissionInput {\n\treadonly actionId: ActionId;\n\treadonly tenantId: string;\n\treadonly spaceId: string;\n\treadonly actorId: string;\n\treadonly actorType: ActorType;\n\t/**\n\t * The submitted parameters, unvalidated, as a copy made for this check.\n\t * `@fabricorg/platform-host` records its own copy of the same value, taken\n\t * before the check ran, and only if the check admits it; changing this\n\t * copy changes nothing the host records.\n\t */\n\treadonly parameters: Readonly<Record<string, unknown>>;\n\t/**\n\t * Aborted when the host's admission deadline passes. Hosts pass an\n\t * `AbortSignal`. `@fabricorg/platform-host` refuses an answer that settles\n\t * at or after the deadline, even one that settles before the abort.\n\t */\n\treadonly signal: ActionAdmissionSignal;\n}\n\n/**\n * The part of an `AbortSignal` an admission check can rely on. Declared\n * structurally so this module compiles without DOM or Node type libraries; a\n * host passes a real `AbortSignal`, which satisfies it.\n */\nexport interface ActionAdmissionSignal {\n\treadonly aborted: boolean;\n\taddEventListener(type: \"abort\", listener: () => void, options?: { once?: boolean }): void;\n\tremoveEventListener(type: \"abort\", listener: () => void): void;\n}\n\n/**\n * An admission check's answer. Only `{ admitted: true }` admits. A refusal's\n * `code` must be a fixed code chosen by the action (lower-case first letter,\n * then letters, digits, `_`, `.`, `:` or `-`, at most 128 characters), never\n * a submitted value: the host puts it in the error it throws.\n */\nexport type ActionAdmissionDecision =\n\t| { readonly admitted: true }\n\t| { readonly admitted: false; readonly code: string };\n\n/**\n * Decides whether a submission may be recorded at all. A host that supports\n * it runs the check after authorizing the submitter and before it writes\n * anything durable for the submission; a refusal, a throw, a timeout or any\n * answer other than `{ admitted: true }` refuses the submission.\n */\nexport type ActionAdmission = (input: ActionAdmissionInput) => Promise<ActionAdmissionDecision>;\n\nexport interface ActionResult {\n\tsuccess: boolean;\n\tdata?: Record<string, unknown>;\n\terror?: string;\n}\n\nexport type ActionHandler<TDb = unknown> = (\n\tctx: ActionContext<TDb>,\n\tparams: unknown,\n) => Promise<ActionResult>;\n\nexport interface AdapterStepRetryPolicy {\n\tidempotent: boolean;\n\tmaxAttempts?: number;\n\tinitialDelayMs?: number;\n\tbackoffMultiplier?: number;\n\tmaxDelayMs?: number;\n}\n\nexport interface AdapterStep {\n\tadapterType: string;\n\toperation: string;\n\tretryPolicy?: AdapterStepRetryPolicy;\n\tgetInput: (\n\t\tparams: unknown,\n\t\thandlerResult: Record<string, unknown>,\n\t) => Record<string, unknown> | undefined;\n}\n\nexport interface ActionStateMachineBinding {\n\tentityType: string;\n\ttargetState: string | ((params: unknown) => string);\n\tgetEntityId: (params: unknown) => string | undefined;\n}\n\nexport interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {\n\tactionId: ActionId;\n\tnamespace: string;\n\tversion: number;\n\tschema: SchemaValidator;\n\t/**\n\t * Optional check a host runs on every submission before it records\n\t * anything durable for it (invocation, idempotency key, events, errors).\n\t * Use it when parameters must be validated against trusted context, for\n\t * example a secret reference the tenant's secret store must hold, before\n\t * they may be persisted. `@fabricorg/platform-host` runs it from the\n\t * release that introduced it; an older host ignores it, so a handler that\n\t * relies on it should require `ActionContext.admittedAt`.\n\t */\n\tadmitSubmission?: ActionAdmission;\n\t/** Optional validation contract for the public handler result data. */\n\tresultSchema?: SchemaValidator;\n\thandler?: ActionHandler<TDb>;\n\trequiredRoles?: string[];\n\trequiredPermissions?: string[];\n\tpolicies?: `${string}.v${number}`[];\n\temitsEvents: string[];\n\tidempotent: boolean;\n\tmutatesDomain: boolean;\n\t/** Portable execution semantics used by hosts, gateways, and generated capability contracts. */\n\texecution?: ActionExecutionContract;\n\tstateMachine?: ActionStateMachineBinding;\n\tadapterSteps?: AdapterStep[];\n\t/** Completion actions can attest only after all external adapter work succeeds. */\n\teventPhase?: \"before_adapters\" | \"after_adapters\";\n\t/**\n\t * If \"saga\", the action is a multi-step orchestration. The worker dispatches\n\t * to a registered saga implementation instead of running `handler` directly.\n\t */\n\tkind?: \"atomic\" | \"saga\";\n}\n\nexport type ActionConnectivity = \"online-required\" | \"offline-capturable\";\nexport type AuthorityMoment = \"capture\" | \"execution\" | \"both\";\nexport type ActionIdempotencyStance = \"required\" | \"supported\" | \"prohibited\";\nexport type ActionCompletionMode = \"immediate\" | \"accepted\" | \"long-running\";\nexport type ActionConsistency = \"authoritative-now\" | \"provisional-until-reconciled\";\nexport type ActionDataSensitivity = \"public\" | \"internal\" | \"confidential\" | \"restricted\";\n\nexport interface ActionExecutionContract {\n\tconnectivity: ActionConnectivity;\n\tauthorityMoment: AuthorityMoment;\n\tidempotency: ActionIdempotencyStance;\n\t/**\n\t * `immediate`: the invocation settles within the host's execution.\n\t * `accepted` and `long-running`: an adapter may hand the work to an\n\t * external system and the invocation stays running until that system\n\t * completes it by reference through the host's completion ingress.\n\t * Declare `completionDeadlineMs` on a `long-running` action so a callback\n\t * that never comes is noticed rather than waited on forever.\n\t */\n\tcompletion: ActionCompletionMode;\n\t/**\n\t * How long an accepted handoff may wait for its completion before the host\n\t * moves the invocation to reconciliation. Without it, nothing sweeps the\n\t * handoff. Refused on `immediate`, since nothing external completes it.\n\t */\n\tcompletionDeadlineMs?: number;\n\tconsistency: ActionConsistency;\n\tsensitivity?: ActionDataSensitivity;\n}\n\nexport interface SagaContext {\n\tactionInvocationId: string;\n\ttenantId: string;\n\tspaceId: string;\n\tparameters: unknown;\n\tsleep?: (delayMs: number) => Promise<void>;\n\tquery?: <T = unknown>(model: string, operation: string, args: unknown) => Promise<T>;\n\t/**\n\t * Wait for a named external signal carrying a payload of `T`, with a timeout.\n\t *\n\t * Resolves with the payload of the first signal received, or `null` if the timeout\n\t * fires first. Subsequent distinct signals with the same name received before\n\t * another `awaitSignal` call are buffered in FIFO order so none is lost.\n\t *\n\t * A signal may carry a stable signal ID that the sender keeps the same on each redelivery\n\t * (for example a webhook delivery ID or an approval decision ID). A runtime drops\n\t * a signal whose ID it has already received for this saga, so a sender retrying\n\t * after a timeout does not wake the saga twice. Signals without an ID are not\n\t * deduplicated. `@fabricorg/platform-temporal` provides `createSagaSignalInbox()`\n\t * for Temporal runtimes.\n\t *\n\t * Intended for agent-driven and webhook-driven coordination: replace polling loops\n\t * with push-based wakeups while preserving the saga's deterministic replay\n\t * semantics (the runtime is responsible for capturing signals into workflow history).\n\t *\n\t * Optional. Runtimes that cannot implement push-based signaling (e.g. an in-memory\n\t * test harness) may omit this; sagas should treat absence as a fallback condition\n\t * and use `sleep` + `query` polling instead.\n\t *\n\t * Signal *senders* are runtime-specific (e.g. a Temporal `WorkflowClient.signal()`\n\t * call from an action handler). Apps that need to send signals from action\n\t * handlers should expose a coordination service via `ActionContext.services`\n\t * — the platform does not prescribe the sender API.\n\t *\n\t * @example\n\t * const payload = await ctx.awaitSignal?.<{ result: Record<string, unknown> }>(\n\t *   \"userInputProcessed\",\n\t *   5 * 60 * 1000,\n\t * );\n\t * if (payload) { /* handle pushed result *\\/ }\n\t * else        { /* timeout — fall back to deterministic path *\\/ }\n\t */\n\tawaitSignal?: <T = unknown>(signalName: string, timeoutMs: number) => Promise<T | null>;\n}\n\nexport interface SagaChildActionInput {\n\tsuffix: string;\n\tactionId: string;\n\tparameters: Record<string, unknown>;\n}\n\nexport type SagaRunChild = (input: SagaChildActionInput) => Promise<Record<string, unknown>>;\n\nexport interface SagaCompletionEvent {\n\teventType: string;\n\tsubjectType: string;\n\tsubjectId: string;\n\tpayload: unknown;\n\teventSchemaVersion?: number;\n}\n\nexport interface SagaCompletion {\n\tresultData: Record<string, unknown>;\n\tevent?: SagaCompletionEvent;\n}\n\nexport type SagaImplementation = (\n\tctx: SagaContext,\n\trunChild: SagaRunChild,\n) => Promise<SagaCompletion>;\n\nexport function assertActionId(actionId: string): asserts actionId is ActionId {\n\tif (!/^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_]*$/.test(actionId)) {\n\t\tthrow new Error(`Invalid action ID: ${actionId}`);\n\t}\n}\n\nexport interface ActionRegistry<TDb = unknown> {\n\tregister(definition: ActionDefinition<TDb>): void;\n\tregisterIfMissing(definition: ActionDefinition<TDb>): void;\n\tresolve(actionId: ActionId): ActionDefinition<TDb> | undefined;\n\thas(actionId: string): actionId is ActionId;\n\tids(): ActionId[];\n}\n\nexport function createActionRegistry<TDb = unknown>(definitions: readonly ActionDefinition<TDb>[] = []): ActionRegistry<TDb> {\n\tconst actions = new Map<ActionId, ActionDefinition<TDb>>();\n\tconst register = (definition: ActionDefinition<TDb>): void => {\n\t\tassertActionId(definition.actionId);\n\t\tif (actions.has(definition.actionId)) throw new Error(`Action \"${definition.actionId}\" is already registered`);\n\t\tif (definition.mutatesDomain && definition.emitsEvents.length === 0) {\n\t\t\tthrow new Error(`Action \"${definition.actionId}\" mutates domain but emits no events. Every mutating action must emit at least one AssetEvent.`);\n\t\t}\n\t\tif (definition.admitSubmission !== undefined && typeof definition.admitSubmission !== \"function\") {\n\t\t\tthrow new Error(`Action \"${definition.actionId}\" declares admitSubmission that is not a function.`);\n\t\t}\n\t\tactions.set(definition.actionId, definition);\n\t};\n\tfor (const definition of definitions) register(definition);\n\treturn {\n\t\tregister,\n\t\tregisterIfMissing(definition) {\n\t\t\tif (!actions.has(definition.actionId)) register(definition);\n\t\t},\n\t\tresolve: (actionId) => actions.get(actionId),\n\t\thas: (actionId): actionId is ActionId => actions.has(actionId as ActionId),\n\t\tids: () => Array.from(actions.keys()),\n\t};\n}\n"],"mappings":";;AAyBA,MAAa,cAAoC;CAChD;CACA;CACA;CACA;CACA;CACA;AACD;AAEA,SAAgB,YAAY,OAAmC;CAC9D,OAAQ,YAAkC,SAAS,KAAK;AACzD;AAEA,SAAgB,gBAAgB,OAA2C;CAC1E,IAAI,CAAC,YAAY,KAAK,GACrB,MAAM,IAAI,MAAM,sBAAsB,OAAO;AAE/C;AA0QA,SAAgB,eAAe,UAAgD;CAC9E,IAAI,CAAC,qCAAqC,KAAK,QAAQ,GACtD,MAAM,IAAI,MAAM,sBAAsB,UAAU;AAElD;AAUA,SAAgB,qBAAoC,cAAgD,CAAC,GAAwB;CAC5H,MAAM,0BAAU,IAAI,IAAqC;CACzD,MAAM,YAAY,eAA4C;EAC7D,eAAe,WAAW,QAAQ;EAClC,IAAI,QAAQ,IAAI,WAAW,QAAQ,GAAG,MAAM,IAAI,MAAM,WAAW,WAAW,SAAS,wBAAwB;EAC7G,IAAI,WAAW,iBAAiB,WAAW,YAAY,WAAW,GACjE,MAAM,IAAI,MAAM,WAAW,WAAW,SAAS,+FAA+F;EAE/I,IAAI,WAAW,oBAAoB,KAAA,KAAa,OAAO,WAAW,oBAAoB,YACrF,MAAM,IAAI,MAAM,WAAW,WAAW,SAAS,mDAAmD;EAEnG,QAAQ,IAAI,WAAW,UAAU,UAAU;CAC5C;CACA,KAAK,MAAM,cAAc,aAAa,SAAS,UAAU;CACzD,OAAO;EACN;EACA,kBAAkB,YAAY;GAC7B,IAAI,CAAC,QAAQ,IAAI,WAAW,QAAQ,GAAG,SAAS,UAAU;EAC3D;EACA,UAAU,aAAa,QAAQ,IAAI,QAAQ;EAC3C,MAAM,aAAmC,QAAQ,IAAI,QAAoB;EACzE,WAAW,MAAM,KAAK,QAAQ,KAAK,CAAC;CACrC;AACD"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../actions/index.ts"],"sourcesContent":["import type { SurfaceDeclaration } from \"../discovery\";\nexport type ActionId = `${string}.${string}`;\n\nexport interface SchemaParseIssue {\n\tpath: PropertyKey[];\n\tmessage: string;\n}\n\nexport type SchemaParseResult<T = unknown> =\n\t| { success: true; data: T }\n\t| { success: false; error: { issues: SchemaParseIssue[] } };\n\nexport interface SchemaValidator<T = unknown> {\n\tparse(input: unknown): T;\n\tsafeParse(input: unknown): SchemaParseResult<T>;\n}\n\nexport type ActorType =\n\t| \"natural_person\"\n\t| \"agent\"\n\t| \"system\"\n\t| \"service_account\"\n\t| \"external_system\"\n\t| \"integration\";\n\nexport const ACTOR_TYPES: readonly ActorType[] = [\n\t\"natural_person\",\n\t\"agent\",\n\t\"system\",\n\t\"service_account\",\n\t\"external_system\",\n\t\"integration\",\n] as const;\n\nexport function isActorType(value: string): value is ActorType {\n\treturn (ACTOR_TYPES as readonly string[]).includes(value);\n}\n\nexport function assertActorType(value: string): asserts value is ActorType {\n\tif (!isActorType(value)) {\n\t\tthrow new Error(`Invalid actorType: ${value}`);\n\t}\n}\n\nexport type ActionStatus =\n\t| \"pending\"\n\t| \"running\"\n\t| \"completed\"\n\t| \"failed\"\n\t| \"blocked_by_policy\"\n\t| \"waiting_for_approval\"\n\t| \"reconciliation_required\"\n\t| \"validation_failed\";\n\nexport interface FabricRuntimeServices {\n\treadonly [serviceName: string]: unknown;\n}\n\nexport interface ActionContext<TDb = unknown> {\n\tactionInvocationId: string;\n\ttenantId: string;\n\tspaceId: string;\n\tactorId: string;\n\tactorType: ActorType;\n\tcorrelationId: string;\n\tcausationId?: string;\n\tprovenance?: { source: string; auditAttributes?: Record<string, string> };\n\tdb: TDb;\n\tservices?: FabricRuntimeServices;\n\tfinalizationProtocol?: \"atomic-after-adapters-v1\";\n\t/**\n\t * When the host admitted this invocation's submission through the\n\t * action's `admitSubmission` check, read from the durable invocation\n\t * record. Absent when the action declares no check, or when the runtime\n\t * that built this context does not run declared admission checks (a host\n\t * older than the one that introduced them). A handler whose action\n\t * declares `admitSubmission` can refuse to run without it.\n\t */\n\tadmittedAt?: Date;\n}\n\n/**\n * Trusted facts a host gives an action's `admitSubmission` check. Scope and\n * actor come from the host's authenticated submission, never from the\n * parameters.\n */\nexport interface ActionAdmissionInput {\n\treadonly actionId: ActionId;\n\treadonly tenantId: string;\n\treadonly spaceId: string;\n\treadonly actorId: string;\n\treadonly actorType: ActorType;\n\t/**\n\t * The submitted parameters, unvalidated, as a copy made for this check.\n\t * `@fabricorg/platform-host` records its own copy of the same value, taken\n\t * before the check ran, and only if the check admits it; changing this\n\t * copy changes nothing the host records.\n\t */\n\treadonly parameters: Readonly<Record<string, unknown>>;\n\t/**\n\t * Aborted when the host's admission deadline passes. Hosts pass an\n\t * `AbortSignal`. `@fabricorg/platform-host` refuses an answer that settles\n\t * at or after the deadline, even one that settles before the abort.\n\t */\n\treadonly signal: ActionAdmissionSignal;\n}\n\n/**\n * The part of an `AbortSignal` an admission check can rely on. Declared\n * structurally so this module compiles without DOM or Node type libraries; a\n * host passes a real `AbortSignal`, which satisfies it.\n */\nexport interface ActionAdmissionSignal {\n\treadonly aborted: boolean;\n\taddEventListener(type: \"abort\", listener: () => void, options?: { once?: boolean }): void;\n\tremoveEventListener(type: \"abort\", listener: () => void): void;\n}\n\n/**\n * An admission check's answer. Only `{ admitted: true }` admits. A refusal's\n * `code` must be a fixed code chosen by the action (lower-case first letter,\n * then letters, digits, `_`, `.`, `:` or `-`, at most 128 characters), never\n * a submitted value: the host puts it in the error it throws.\n */\nexport type ActionAdmissionDecision =\n\t| { readonly admitted: true }\n\t| { readonly admitted: false; readonly code: string };\n\n/**\n * Decides whether a submission may be recorded at all. A host that supports\n * it runs the check after authorizing the submitter and before it writes\n * anything durable for the submission; a refusal, a throw, a timeout or any\n * answer other than `{ admitted: true }` refuses the submission.\n */\nexport type ActionAdmission = (input: ActionAdmissionInput) => Promise<ActionAdmissionDecision>;\n\n/** A descendant invocation the Host durably stages with its parent mutation. */\nexport interface StagedInvocationRequest {\n\t/** Stable identity within one parent invocation. */\n\treadonly key: string;\n\treadonly actionId: ActionId;\n\treadonly parameters: Record<string, unknown>;\n}\n\nexport interface ActionResult {\n\tsuccess: boolean;\n\tdata?: Record<string, unknown>;\n\terror?: string;\n\t/** Host-owned descendants released only after this invocation completes. */\n\tstagedInvocations?: readonly StagedInvocationRequest[];\n}\n\nexport type ActionHandler<TDb = unknown> = (\n\tctx: ActionContext<TDb>,\n\tparams: unknown,\n) => Promise<ActionResult>;\n\nexport type FinalizationJson = null | boolean | number | string | readonly FinalizationJson[] | { readonly [key: string]: FinalizationJson };\nexport type FinalizationRecord = { readonly [key: string]: FinalizationJson };\nexport type ActionFinalizationContext<TDb = unknown> = Pick<ActionContext<TDb>,\n\t\"actionInvocationId\" | \"tenantId\" | \"spaceId\" | \"actorId\" | \"actorType\" |\n\t\"correlationId\" | \"causationId\" | \"provenance\" | \"db\">;\nexport type ActionFinalizationStep = {\n\treadonly stepIndex: number;\n\treadonly adapterType: string;\n\treadonly operation: string;\n} & ({ readonly status: \"succeeded\"; readonly adapterInvocationId: string; readonly output: FinalizationRecord } |\n\t{ readonly status: \"skipped\" });\nexport interface ActionFinalizationInput {\n\treadonly params: FinalizationJson;\n\treadonly handlerData: FinalizationRecord;\n\treadonly adapterOutputs: readonly ActionFinalizationStep[];\n}\nexport interface ActionFinalizationEvent {\n\treadonly eventType: string;\n\treadonly subjectType: string;\n\treadonly subjectId: string;\n\treadonly payload: FinalizationJson;\n\treadonly eventSchemaVersion?: number;\n}\nexport interface ActionFinalizationResult {\n\treadonly events?: readonly ActionFinalizationEvent[];\n\treadonly resultPatch?: FinalizationRecord;\n\t/** Additional descendants staged atomically with finalization and completion. */\n\treadonly stagedInvocations?: readonly StagedInvocationRequest[];\n}\nexport type ActionFinalizer<TDb = unknown> = (\n\tctx: ActionFinalizationContext<TDb>, input: ActionFinalizationInput,\n) => Promise<ActionFinalizationResult>;\n\n/** Validate declarations at registration and at dynamically resolved execution boundaries. */\nexport function assertActionFinalization<TDb>(action: Pick<ActionDefinition<TDb>, \"actionId\" | \"finalize\" | \"eventPhase\" | \"kind\" | \"execution\">): void {\n\tif (action.finalize === undefined) return;\n\tif (typeof action.finalize !== \"function\") throw new Error(\"Action finalization hook must be a function.\");\n\tif (action.eventPhase !== \"after_adapters\") throw new Error(\"Action finalization requires eventPhase after_adapters.\");\n\tif (action.kind !== undefined && action.kind !== \"atomic\") throw new Error(\"Action finalization requires an atomic action.\");\n\tif (action.execution?.completion !== undefined && action.execution.completion !== \"immediate\") throw new Error(\"Action finalization requires immediate completion.\");\n}\n\n/** Refuse older hosts before application handler code executes. Use for distributed finalizing actions. */\nexport function defineFinalizingAction<TDb>(action: ActionDefinition<TDb> & { finalize: ActionFinalizer<TDb> }): ActionDefinition<TDb> {\n\tassertActionFinalization(action);\n\tconst handler = action.handler;\n\treturn { ...action, handler: async (ctx, params) => {\n\t\tif (ctx.finalizationProtocol !== \"atomic-after-adapters-v1\") throw new Error(\"Host does not support atomic-after-adapters-v1 finalization.\");\n\t\treturn handler ? handler(ctx, params) : { success: true, data: {} };\n\t} };\n}\n\nexport interface AdapterStepRetryPolicy {\n\tidempotent: boolean;\n\tmaxAttempts?: number;\n\tinitialDelayMs?: number;\n\tbackoffMultiplier?: number;\n\tmaxDelayMs?: number;\n}\n\nexport interface AdapterStep {\n\tadapterType: string;\n\toperation: string;\n\tretryPolicy?: AdapterStepRetryPolicy;\n\t/** Positive finite integer duration in milliseconds; overrides Host adapterDeadlineMs for this step. */\n\tdeadlineMs?: number;\n\tgetInput: (\n\t\tparams: unknown,\n\t\thandlerResult: Record<string, unknown>,\n\t) => Record<string, unknown> | undefined;\n}\n\n/** Validate optional step execution budgets before accepting or executing an action. */\nexport function assertAdapterStepDeadlines(action: { actionId: string; adapterSteps?: readonly Pick<AdapterStep, \"deadlineMs\">[] }): void {\n\tfor (const step of action.adapterSteps ?? []) {\n\t\tif (step.deadlineMs !== undefined && (!Number.isInteger(step.deadlineMs) || step.deadlineMs <= 0)) {\n\t\t\tthrow new Error(`Action \"${action.actionId}\" adapter step deadlineMs must be a positive finite integer.`);\n\t\t}\n\t}\n}\n\nexport interface ActionStateMachineBinding {\n\tentityType: string;\n\ttargetState: string | ((params: unknown) => string);\n\tgetEntityId: (params: unknown) => string | undefined;\n}\n\nexport interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {\n\tactionId: ActionId;\n\tnamespace: string;\n\tversion: number;\n\tschema: SchemaValidator;\n\t/**\n\t * Optional check a host runs on every submission before it records\n\t * anything durable for it (invocation, idempotency key, events, errors).\n\t * Use it when parameters must be validated against trusted context, for\n\t * example a secret reference the tenant's secret store must hold, before\n\t * they may be persisted. `@fabricorg/platform-host` runs it from the\n\t * release that introduced it; an older host ignores it, so a handler that\n\t * relies on it should require `ActionContext.admittedAt`.\n\t */\n\tadmitSubmission?: ActionAdmission;\n\t/** Optional validation contract for the public handler result data. */\n\tresultSchema?: SchemaValidator;\n\thandler?: ActionHandler<TDb>;\n\tfinalize?: ActionFinalizer<TDb>;\n\trequiredRoles?: string[];\n\trequiredPermissions?: string[];\n\tpolicies?: `${string}.v${number}`[];\n\temitsEvents: string[];\n\tidempotent: boolean;\n\tmutatesDomain: boolean;\n\t/** Portable execution semantics used by hosts, gateways, and generated capability contracts. */\n\texecution?: ActionExecutionContract;\n\tstateMachine?: ActionStateMachineBinding;\n\tadapterSteps?: AdapterStep[];\n\t/** Child action IDs this action is permitted to stage for post-completion dispatch. */\n\tstagesInvocations?: readonly ActionId[];\n\t/** Completion actions can attest only after all external adapter work succeeds. */\n\teventPhase?: \"before_adapters\" | \"after_adapters\";\n\t/**\n\t * If \"saga\", the action is a multi-step orchestration. The worker dispatches\n\t * to a registered saga implementation instead of running `handler` directly.\n\t */\n\tkind?: \"atomic\" | \"saga\";\n}\n\nexport type ActionConnectivity = \"online-required\" | \"offline-capturable\";\nexport type AuthorityMoment = \"capture\" | \"execution\" | \"both\";\nexport type ActionIdempotencyStance = \"required\" | \"supported\" | \"prohibited\";\nexport type ActionCompletionMode = \"immediate\" | \"accepted\" | \"long-running\";\nexport type ActionConsistency = \"authoritative-now\" | \"provisional-until-reconciled\";\nexport type ActionDataSensitivity = \"public\" | \"internal\" | \"confidential\" | \"restricted\";\n\nexport interface ActionExecutionContract {\n\tconnectivity: ActionConnectivity;\n\tauthorityMoment: AuthorityMoment;\n\tidempotency: ActionIdempotencyStance;\n\t/**\n\t * `immediate`: the invocation settles within the host's execution.\n\t * `accepted` and `long-running`: an adapter may hand the work to an\n\t * external system and the invocation stays running until that system\n\t * completes it by reference through the host's completion ingress.\n\t * Declare `completionDeadlineMs` on a `long-running` action so a callback\n\t * that never comes is noticed rather than waited on forever.\n\t */\n\tcompletion: ActionCompletionMode;\n\t/**\n\t * How long an accepted handoff may wait for its completion before the host\n\t * moves the invocation to reconciliation. Without it, nothing sweeps the\n\t * handoff. Refused on `immediate`, since nothing external completes it.\n\t */\n\tcompletionDeadlineMs?: number;\n\tconsistency: ActionConsistency;\n\tsensitivity?: ActionDataSensitivity;\n}\n\nexport interface SagaContext {\n\tactionInvocationId: string;\n\ttenantId: string;\n\tspaceId: string;\n\tparameters: unknown;\n\tsleep?: (delayMs: number) => Promise<void>;\n\tquery?: <T = unknown>(model: string, operation: string, args: unknown) => Promise<T>;\n\t/**\n\t * Wait for a named external signal carrying a payload of `T`, with a timeout.\n\t *\n\t * Resolves with the payload of the first signal received, or `null` if the timeout\n\t * fires first. Subsequent distinct signals with the same name received before\n\t * another `awaitSignal` call are buffered in FIFO order so none is lost.\n\t *\n\t * A signal may carry a stable signal ID that the sender keeps the same on each redelivery\n\t * (for example a webhook delivery ID or an approval decision ID). A runtime drops\n\t * a signal whose ID it has already received for this saga, so a sender retrying\n\t * after a timeout does not wake the saga twice. Signals without an ID are not\n\t * deduplicated. `@fabricorg/platform-temporal` provides `createSagaSignalInbox()`\n\t * for Temporal runtimes.\n\t *\n\t * Intended for agent-driven and webhook-driven coordination: replace polling loops\n\t * with push-based wakeups while preserving the saga's deterministic replay\n\t * semantics (the runtime is responsible for capturing signals into workflow history).\n\t *\n\t * Optional. Runtimes that cannot implement push-based signaling (e.g. an in-memory\n\t * test harness) may omit this; sagas should treat absence as a fallback condition\n\t * and use `sleep` + `query` polling instead.\n\t *\n\t * Signal *senders* are runtime-specific (e.g. a Temporal `WorkflowClient.signal()`\n\t * call from an action handler). Apps that need to send signals from action\n\t * handlers should expose a coordination service via `ActionContext.services`\n\t * — the platform does not prescribe the sender API.\n\t *\n\t * @example\n\t * const payload = await ctx.awaitSignal?.<{ result: Record<string, unknown> }>(\n\t *   \"userInputProcessed\",\n\t *   5 * 60 * 1000,\n\t * );\n\t * if (payload) { /* handle pushed result *\\/ }\n\t * else        { /* timeout — fall back to deterministic path *\\/ }\n\t */\n\tawaitSignal?: <T = unknown>(signalName: string, timeoutMs: number) => Promise<T | null>;\n}\n\nexport interface SagaChildActionInput {\n\tsuffix: string;\n\tactionId: string;\n\tparameters: Record<string, unknown>;\n}\n\nexport type SagaRunChild = (input: SagaChildActionInput) => Promise<Record<string, unknown>>;\n\nexport interface SagaCompletionEvent {\n\teventType: string;\n\tsubjectType: string;\n\tsubjectId: string;\n\tpayload: unknown;\n\teventSchemaVersion?: number;\n}\n\nexport interface SagaCompletion {\n\tresultData: Record<string, unknown>;\n\tevent?: SagaCompletionEvent;\n}\n\nexport type SagaImplementation = (\n\tctx: SagaContext,\n\trunChild: SagaRunChild,\n) => Promise<SagaCompletion>;\n\nexport function assertActionId(actionId: string): asserts actionId is ActionId {\n\tif (!/^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_]*$/.test(actionId)) {\n\t\tthrow new Error(`Invalid action ID: ${actionId}`);\n\t}\n}\n\nexport interface ActionRegistry<TDb = unknown> {\n\tregister(definition: ActionDefinition<TDb>): void;\n\tregisterIfMissing(definition: ActionDefinition<TDb>): void;\n\tresolve(actionId: ActionId): ActionDefinition<TDb> | undefined;\n\thas(actionId: string): actionId is ActionId;\n\tids(): ActionId[];\n}\n\nexport function createActionRegistry<TDb = unknown>(definitions: readonly ActionDefinition<TDb>[] = []): ActionRegistry<TDb> {\n\tconst actions = new Map<ActionId, ActionDefinition<TDb>>();\n\tconst register = (definition: ActionDefinition<TDb>): void => {\n\t\tassertActionId(definition.actionId);\n\t\tif (actions.has(definition.actionId)) throw new Error(`Action \"${definition.actionId}\" is already registered`);\n\t\tif (definition.mutatesDomain && definition.emitsEvents.length === 0) {\n\t\t\tthrow new Error(`Action \"${definition.actionId}\" mutates domain but emits no events. Every mutating action must emit at least one AssetEvent.`);\n\t\t}\n\t\tif (definition.admitSubmission !== undefined && typeof definition.admitSubmission !== \"function\") {\n\t\t\tthrow new Error(`Action \"${definition.actionId}\" declares admitSubmission that is not a function.`);\n\t\t}\n\t\tassertAdapterStepDeadlines(definition);\n\t\tassertActionFinalization(definition);\n\t\tactions.set(definition.actionId, definition);\n\t};\n\tfor (const definition of definitions) register(definition);\n\treturn {\n\t\tregister,\n\t\tregisterIfMissing(definition) {\n\t\t\tif (!actions.has(definition.actionId)) register(definition);\n\t\t},\n\t\tresolve: (actionId) => actions.get(actionId),\n\t\thas: (actionId): actionId is ActionId => actions.has(actionId as ActionId),\n\t\tids: () => Array.from(actions.keys()),\n\t};\n}\n"],"mappings":";;AAyBA,MAAa,cAAoC;CAChD;CACA;CACA;CACA;CACA;CACA;AACD;AAEA,SAAgB,YAAY,OAAmC;CAC9D,OAAQ,YAAkC,SAAS,KAAK;AACzD;AAEA,SAAgB,gBAAgB,OAA2C;CAC1E,IAAI,CAAC,YAAY,KAAK,GACrB,MAAM,IAAI,MAAM,sBAAsB,OAAO;AAE/C;;AAqJA,SAAgB,yBAA8B,QAA0G;CACvJ,IAAI,OAAO,aAAa,KAAA,GAAW;CACnC,IAAI,OAAO,OAAO,aAAa,YAAY,MAAM,IAAI,MAAM,8CAA8C;CACzG,IAAI,OAAO,eAAe,kBAAkB,MAAM,IAAI,MAAM,yDAAyD;CACrH,IAAI,OAAO,SAAS,KAAA,KAAa,OAAO,SAAS,UAAU,MAAM,IAAI,MAAM,gDAAgD;CAC3H,IAAI,OAAO,WAAW,eAAe,KAAA,KAAa,OAAO,UAAU,eAAe,aAAa,MAAM,IAAI,MAAM,oDAAoD;AACpK;;AAGA,SAAgB,uBAA4B,QAA2F;CACtI,yBAAyB,MAAM;CAC/B,MAAM,UAAU,OAAO;CACvB,OAAO;EAAE,GAAG;EAAQ,SAAS,OAAO,KAAK,WAAW;GACnD,IAAI,IAAI,yBAAyB,4BAA4B,MAAM,IAAI,MAAM,8DAA8D;GAC3I,OAAO,UAAU,QAAQ,KAAK,MAAM,IAAI;IAAE,SAAS;IAAM,MAAM,CAAC;GAAE;EACnE;CAAE;AACH;;AAuBA,SAAgB,2BAA2B,QAA+F;CACzI,KAAK,MAAM,QAAQ,OAAO,gBAAgB,CAAC,GAC1C,IAAI,KAAK,eAAe,KAAA,MAAc,CAAC,OAAO,UAAU,KAAK,UAAU,KAAK,KAAK,cAAc,IAC9F,MAAM,IAAI,MAAM,WAAW,OAAO,SAAS,6DAA6D;AAG3G;AAqJA,SAAgB,eAAe,UAAgD;CAC9E,IAAI,CAAC,qCAAqC,KAAK,QAAQ,GACtD,MAAM,IAAI,MAAM,sBAAsB,UAAU;AAElD;AAUA,SAAgB,qBAAoC,cAAgD,CAAC,GAAwB;CAC5H,MAAM,0BAAU,IAAI,IAAqC;CACzD,MAAM,YAAY,eAA4C;EAC7D,eAAe,WAAW,QAAQ;EAClC,IAAI,QAAQ,IAAI,WAAW,QAAQ,GAAG,MAAM,IAAI,MAAM,WAAW,WAAW,SAAS,wBAAwB;EAC7G,IAAI,WAAW,iBAAiB,WAAW,YAAY,WAAW,GACjE,MAAM,IAAI,MAAM,WAAW,WAAW,SAAS,+FAA+F;EAE/I,IAAI,WAAW,oBAAoB,KAAA,KAAa,OAAO,WAAW,oBAAoB,YACrF,MAAM,IAAI,MAAM,WAAW,WAAW,SAAS,mDAAmD;EAEnG,2BAA2B,UAAU;EACrC,yBAAyB,UAAU;EACnC,QAAQ,IAAI,WAAW,UAAU,UAAU;CAC5C;CACA,KAAK,MAAM,cAAc,aAAa,SAAS,UAAU;CACzD,OAAO;EACN;EACA,kBAAkB,YAAY;GAC7B,IAAI,CAAC,QAAQ,IAAI,WAAW,QAAQ,GAAG,SAAS,UAAU;EAC3D;EACA,UAAU,aAAa,QAAQ,IAAI,QAAQ;EAC3C,MAAM,aAAmC,QAAQ,IAAI,QAAoB;EACzE,WAAW,MAAM,KAAK,QAAQ,KAAK,CAAC;CACrC;AACD"}

package/dist/actions/index.d.cts

@@ -40,6 +40,7 @@ export interface ActionContext<TDb = unknown> {
   };
   db: TDb;
   services?: FabricRuntimeServices;
+  finalizationProtocol?: "atomic-after-adapters-v1";
   /**
    * When the host admitted this invocation's submission through the
    * action's `admitSubmission` check, read from the durable invocation
@@ -106,12 +107,64 @@ export type ActionAdmissionDecision = {
  * answer other than `{ admitted: true }` refuses the submission.
  */
 export type ActionAdmission = (input: ActionAdmissionInput) => Promise<ActionAdmissionDecision>;
+/** A descendant invocation the Host durably stages with its parent mutation. */
+export interface StagedInvocationRequest {
+  /** Stable identity within one parent invocation. */
+  readonly key: string;
+  readonly actionId: ActionId;
+  readonly parameters: Record<string, unknown>;
+}
 export interface ActionResult {
   success: boolean;
   data?: Record<string, unknown>;
   error?: string;
+  /** Host-owned descendants released only after this invocation completes. */
+  stagedInvocations?: readonly StagedInvocationRequest[];
 }
 export type ActionHandler<TDb = unknown> = (ctx: ActionContext<TDb>, params: unknown) => Promise<ActionResult>;
+export type FinalizationJson = null | boolean | number | string | readonly FinalizationJson[] | {
+  readonly [key: string]: FinalizationJson;
+};
+export type FinalizationRecord = {
+  readonly [key: string]: FinalizationJson;
+};
+export type ActionFinalizationContext<TDb = unknown> = Pick<ActionContext<TDb>, "actionInvocationId" | "tenantId" | "spaceId" | "actorId" | "actorType" | "correlationId" | "causationId" | "provenance" | "db">;
+export type ActionFinalizationStep = {
+  readonly stepIndex: number;
+  readonly adapterType: string;
+  readonly operation: string;
+} & ({
+  readonly status: "succeeded";
+  readonly adapterInvocationId: string;
+  readonly output: FinalizationRecord;
+} | {
+  readonly status: "skipped";
+});
+export interface ActionFinalizationInput {
+  readonly params: FinalizationJson;
+  readonly handlerData: FinalizationRecord;
+  readonly adapterOutputs: readonly ActionFinalizationStep[];
+}
+export interface ActionFinalizationEvent {
+  readonly eventType: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly payload: FinalizationJson;
+  readonly eventSchemaVersion?: number;
+}
+export interface ActionFinalizationResult {
+  readonly events?: readonly ActionFinalizationEvent[];
+  readonly resultPatch?: FinalizationRecord;
+  /** Additional descendants staged atomically with finalization and completion. */
+  readonly stagedInvocations?: readonly StagedInvocationRequest[];
+}
+export type ActionFinalizer<TDb = unknown> = (ctx: ActionFinalizationContext<TDb>, input: ActionFinalizationInput) => Promise<ActionFinalizationResult>;
+/** Validate declarations at registration and at dynamically resolved execution boundaries. */
+export declare function assertActionFinalization<TDb>(action: Pick<ActionDefinition<TDb>, "actionId" | "finalize" | "eventPhase" | "kind" | "execution">): void;
+/** Refuse older hosts before application handler code executes. Use for distributed finalizing actions. */
+export declare function defineFinalizingAction<TDb>(action: ActionDefinition<TDb> & {
+  finalize: ActionFinalizer<TDb>;
+}): ActionDefinition<TDb>;
 export interface AdapterStepRetryPolicy {
   idempotent: boolean;
   maxAttempts?: number;
@@ -123,8 +176,15 @@ export interface AdapterStep {
   adapterType: string;
   operation: string;
   retryPolicy?: AdapterStepRetryPolicy;
+  /** Positive finite integer duration in milliseconds; overrides Host adapterDeadlineMs for this step. */
+  deadlineMs?: number;
   getInput: (params: unknown, handlerResult: Record<string, unknown>) => Record<string, unknown> | undefined;
 }
+/** Validate optional step execution budgets before accepting or executing an action. */
+export declare function assertAdapterStepDeadlines(action: {
+  actionId: string;
+  adapterSteps?: readonly Pick<AdapterStep, "deadlineMs">[];
+}): void;
 export interface ActionStateMachineBinding {
   entityType: string;
   targetState: string | ((params: unknown) => string);
@@ -148,6 +208,7 @@ export interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {
   /** Optional validation contract for the public handler result data. */
   resultSchema?: SchemaValidator;
   handler?: ActionHandler<TDb>;
+  finalize?: ActionFinalizer<TDb>;
   requiredRoles?: string[];
   requiredPermissions?: string[];
   policies?: `${string}.v${number}`[];
@@ -158,6 +219,8 @@ export interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {
   execution?: ActionExecutionContract;
   stateMachine?: ActionStateMachineBinding;
   adapterSteps?: AdapterStep[];
+  /** Child action IDs this action is permitted to stage for post-completion dispatch. */
+  stagesInvocations?: readonly ActionId[];
   /** Completion actions can attest only after all external adapter work succeeds. */
   eventPhase?: "before_adapters" | "after_adapters";
   /**

package/dist/actions/index.d.ts

@@ -40,6 +40,7 @@ export interface ActionContext<TDb = unknown> {
   };
   db: TDb;
   services?: FabricRuntimeServices;
+  finalizationProtocol?: "atomic-after-adapters-v1";
   /**
    * When the host admitted this invocation's submission through the
    * action's `admitSubmission` check, read from the durable invocation
@@ -106,12 +107,64 @@ export type ActionAdmissionDecision = {
  * answer other than `{ admitted: true }` refuses the submission.
  */
 export type ActionAdmission = (input: ActionAdmissionInput) => Promise<ActionAdmissionDecision>;
+/** A descendant invocation the Host durably stages with its parent mutation. */
+export interface StagedInvocationRequest {
+  /** Stable identity within one parent invocation. */
+  readonly key: string;
+  readonly actionId: ActionId;
+  readonly parameters: Record<string, unknown>;
+}
 export interface ActionResult {
   success: boolean;
   data?: Record<string, unknown>;
   error?: string;
+  /** Host-owned descendants released only after this invocation completes. */
+  stagedInvocations?: readonly StagedInvocationRequest[];
 }
 export type ActionHandler<TDb = unknown> = (ctx: ActionContext<TDb>, params: unknown) => Promise<ActionResult>;
+export type FinalizationJson = null | boolean | number | string | readonly FinalizationJson[] | {
+  readonly [key: string]: FinalizationJson;
+};
+export type FinalizationRecord = {
+  readonly [key: string]: FinalizationJson;
+};
+export type ActionFinalizationContext<TDb = unknown> = Pick<ActionContext<TDb>, "actionInvocationId" | "tenantId" | "spaceId" | "actorId" | "actorType" | "correlationId" | "causationId" | "provenance" | "db">;
+export type ActionFinalizationStep = {
+  readonly stepIndex: number;
+  readonly adapterType: string;
+  readonly operation: string;
+} & ({
+  readonly status: "succeeded";
+  readonly adapterInvocationId: string;
+  readonly output: FinalizationRecord;
+} | {
+  readonly status: "skipped";
+});
+export interface ActionFinalizationInput {
+  readonly params: FinalizationJson;
+  readonly handlerData: FinalizationRecord;
+  readonly adapterOutputs: readonly ActionFinalizationStep[];
+}
+export interface ActionFinalizationEvent {
+  readonly eventType: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly payload: FinalizationJson;
+  readonly eventSchemaVersion?: number;
+}
+export interface ActionFinalizationResult {
+  readonly events?: readonly ActionFinalizationEvent[];
+  readonly resultPatch?: FinalizationRecord;
+  /** Additional descendants staged atomically with finalization and completion. */
+  readonly stagedInvocations?: readonly StagedInvocationRequest[];
+}
+export type ActionFinalizer<TDb = unknown> = (ctx: ActionFinalizationContext<TDb>, input: ActionFinalizationInput) => Promise<ActionFinalizationResult>;
+/** Validate declarations at registration and at dynamically resolved execution boundaries. */
+export declare function assertActionFinalization<TDb>(action: Pick<ActionDefinition<TDb>, "actionId" | "finalize" | "eventPhase" | "kind" | "execution">): void;
+/** Refuse older hosts before application handler code executes. Use for distributed finalizing actions. */
+export declare function defineFinalizingAction<TDb>(action: ActionDefinition<TDb> & {
+  finalize: ActionFinalizer<TDb>;
+}): ActionDefinition<TDb>;
 export interface AdapterStepRetryPolicy {
   idempotent: boolean;
   maxAttempts?: number;
@@ -123,8 +176,15 @@ export interface AdapterStep {
   adapterType: string;
   operation: string;
   retryPolicy?: AdapterStepRetryPolicy;
+  /** Positive finite integer duration in milliseconds; overrides Host adapterDeadlineMs for this step. */
+  deadlineMs?: number;
   getInput: (params: unknown, handlerResult: Record<string, unknown>) => Record<string, unknown> | undefined;
 }
+/** Validate optional step execution budgets before accepting or executing an action. */
+export declare function assertAdapterStepDeadlines(action: {
+  actionId: string;
+  adapterSteps?: readonly Pick<AdapterStep, "deadlineMs">[];
+}): void;
 export interface ActionStateMachineBinding {
   entityType: string;
   targetState: string | ((params: unknown) => string);
@@ -148,6 +208,7 @@ export interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {
   /** Optional validation contract for the public handler result data. */
   resultSchema?: SchemaValidator;
   handler?: ActionHandler<TDb>;
+  finalize?: ActionFinalizer<TDb>;
   requiredRoles?: string[];
   requiredPermissions?: string[];
   policies?: `${string}.v${number}`[];
@@ -158,6 +219,8 @@ export interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {
   execution?: ActionExecutionContract;
   stateMachine?: ActionStateMachineBinding;
   adapterSteps?: AdapterStep[];
+  /** Child action IDs this action is permitted to stage for post-completion dispatch. */
+  stagesInvocations?: readonly ActionId[];
   /** Completion actions can attest only after all external adapter work succeeds. */
   eventPhase?: "before_adapters" | "after_adapters";
   /**

package/dist/actions/index.js

@@ -13,6 +13,33 @@ function isActorType(value) {
 function assertActorType(value) {
 	if (!isActorType(value)) throw new Error(`Invalid actorType: ${value}`);
 }
+/** Validate declarations at registration and at dynamically resolved execution boundaries. */
+function assertActionFinalization(action) {
+	if (action.finalize === void 0) return;
+	if (typeof action.finalize !== "function") throw new Error("Action finalization hook must be a function.");
+	if (action.eventPhase !== "after_adapters") throw new Error("Action finalization requires eventPhase after_adapters.");
+	if (action.kind !== void 0 && action.kind !== "atomic") throw new Error("Action finalization requires an atomic action.");
+	if (action.execution?.completion !== void 0 && action.execution.completion !== "immediate") throw new Error("Action finalization requires immediate completion.");
+}
+/** Refuse older hosts before application handler code executes. Use for distributed finalizing actions. */
+function defineFinalizingAction(action) {
+	assertActionFinalization(action);
+	const handler = action.handler;
+	return {
+		...action,
+		handler: async (ctx, params) => {
+			if (ctx.finalizationProtocol !== "atomic-after-adapters-v1") throw new Error("Host does not support atomic-after-adapters-v1 finalization.");
+			return handler ? handler(ctx, params) : {
+				success: true,
+				data: {}
+			};
+		}
+	};
+}
+/** Validate optional step execution budgets before accepting or executing an action. */
+function assertAdapterStepDeadlines(action) {
+	for (const step of action.adapterSteps ?? []) if (step.deadlineMs !== void 0 && (!Number.isInteger(step.deadlineMs) || step.deadlineMs <= 0)) throw new Error(`Action "${action.actionId}" adapter step deadlineMs must be a positive finite integer.`);
+}
 function assertActionId(actionId) {
 	if (!/^[a-z][a-z0-9-]*\.[a-z][a-z0-9_]*$/.test(actionId)) throw new Error(`Invalid action ID: ${actionId}`);
 }
@@ -23,6 +50,8 @@ function createActionRegistry(definitions = []) {
 		if (actions.has(definition.actionId)) throw new Error(`Action "${definition.actionId}" is already registered`);
 		if (definition.mutatesDomain && definition.emitsEvents.length === 0) throw new Error(`Action "${definition.actionId}" mutates domain but emits no events. Every mutating action must emit at least one AssetEvent.`);
 		if (definition.admitSubmission !== void 0 && typeof definition.admitSubmission !== "function") throw new Error(`Action "${definition.actionId}" declares admitSubmission that is not a function.`);
+		assertAdapterStepDeadlines(definition);
+		assertActionFinalization(definition);
 		actions.set(definition.actionId, definition);
 	};
 	for (const definition of definitions) register(definition);
@@ -37,6 +66,6 @@ function createActionRegistry(definitions = []) {
 	};
 }
 //#endregion
-export { ACTOR_TYPES, assertActionId, assertActorType, createActionRegistry, isActorType };
+export { ACTOR_TYPES, assertActionFinalization, assertActionId, assertActorType, assertAdapterStepDeadlines, createActionRegistry, defineFinalizingAction, isActorType };
 
 //# sourceMappingURL=index.js.map