@fabricorg/platform 1.9.0 → 1.10.1

package/dist/actions/index.d.cts

@@ -1,91 +1,91 @@
-import { SurfaceDeclaration } from '../discovery/index.cjs';
-
-type ActionId = `${string}.${string}`;
-interface SchemaParseIssue {
-    path: PropertyKey[];
-    message: string;
+import { t as SurfaceDeclaration } from "../index-CIl1rYRv.cjs";
+//#region actions/index.d.ts
+export type ActionId = `${string}.${string}`;
+export interface SchemaParseIssue {
+  path: PropertyKey[];
+  message: string;
 }
-type SchemaParseResult<T = unknown> = {
-    success: true;
-    data: T;
+export type SchemaParseResult<T = unknown> = {
+  success: true;
+  data: T;
 } | {
-    success: false;
-    error: {
-        issues: SchemaParseIssue[];
-    };
+  success: false;
+  error: {
+    issues: SchemaParseIssue[];
+  };
 };
-interface SchemaValidator<T = unknown> {
-    parse(input: unknown): T;
-    safeParse(input: unknown): SchemaParseResult<T>;
+export interface SchemaValidator<T = unknown> {
+  parse(input: unknown): T;
+  safeParse(input: unknown): SchemaParseResult<T>;
 }
-type ActorType = "natural_person" | "agent" | "system" | "service_account" | "external_system" | "integration";
-declare const ACTOR_TYPES: readonly ActorType[];
-declare function isActorType(value: string): value is ActorType;
-declare function assertActorType(value: string): asserts value is ActorType;
-type ActionStatus = "pending" | "running" | "completed" | "failed" | "blocked_by_policy" | "waiting_for_approval" | "reconciliation_required" | "validation_failed";
-interface FabricRuntimeServices {
-    readonly [serviceName: string]: unknown;
+export type ActorType = "natural_person" | "agent" | "system" | "service_account" | "external_system" | "integration";
+export declare const ACTOR_TYPES: readonly ActorType[];
+export declare function isActorType(value: string): value is ActorType;
+export declare function assertActorType(value: string): asserts value is ActorType;
+export type ActionStatus = "pending" | "running" | "completed" | "failed" | "blocked_by_policy" | "waiting_for_approval" | "reconciliation_required" | "validation_failed";
+export interface FabricRuntimeServices {
+  readonly [serviceName: string]: unknown;
 }
-interface ActionContext<TDb = unknown> {
-    actionInvocationId: string;
-    tenantId: string;
-    spaceId: string;
-    actorId: string;
-    actorType: ActorType;
-    correlationId: string;
-    causationId?: string;
-    provenance?: {
-        source: string;
-        auditAttributes?: Record<string, string>;
-    };
-    db: TDb;
-    services?: FabricRuntimeServices;
-    /**
-     * When the host admitted this invocation's submission through the
-     * action's `admitSubmission` check, read from the durable invocation
-     * record. Absent when the action declares no check, or when the runtime
-     * that built this context does not run declared admission checks (a host
-     * older than the one that introduced them). A handler whose action
-     * declares `admitSubmission` can refuse to run without it.
-     */
-    admittedAt?: Date;
+export interface ActionContext<TDb = unknown> {
+  actionInvocationId: string;
+  tenantId: string;
+  spaceId: string;
+  actorId: string;
+  actorType: ActorType;
+  correlationId: string;
+  causationId?: string;
+  provenance?: {
+    source: string;
+    auditAttributes?: Record<string, string>;
+  };
+  db: TDb;
+  services?: FabricRuntimeServices;
+  /**
+   * When the host admitted this invocation's submission through the
+   * action's `admitSubmission` check, read from the durable invocation
+   * record. Absent when the action declares no check, or when the runtime
+   * that built this context does not run declared admission checks (a host
+   * older than the one that introduced them). A handler whose action
+   * declares `admitSubmission` can refuse to run without it.
+   */
+  admittedAt?: Date;
 }
 /**
  * Trusted facts a host gives an action's `admitSubmission` check. Scope and
  * actor come from the host's authenticated submission, never from the
  * parameters.
  */
-interface ActionAdmissionInput {
-    readonly actionId: ActionId;
-    readonly tenantId: string;
-    readonly spaceId: string;
-    readonly actorId: string;
-    readonly actorType: ActorType;
-    /**
-     * The submitted parameters, unvalidated, as a copy made for this check.
-     * `@fabricorg/platform-host` records its own copy of the same value, taken
-     * before the check ran, and only if the check admits it; changing this
-     * copy changes nothing the host records.
-     */
-    readonly parameters: Readonly<Record<string, unknown>>;
-    /**
-     * Aborted when the host's admission deadline passes. Hosts pass an
-     * `AbortSignal`. `@fabricorg/platform-host` refuses an answer that settles
-     * at or after the deadline, even one that settles before the abort.
-     */
-    readonly signal: ActionAdmissionSignal;
+export interface ActionAdmissionInput {
+  readonly actionId: ActionId;
+  readonly tenantId: string;
+  readonly spaceId: string;
+  readonly actorId: string;
+  readonly actorType: ActorType;
+  /**
+   * The submitted parameters, unvalidated, as a copy made for this check.
+   * `@fabricorg/platform-host` records its own copy of the same value, taken
+   * before the check ran, and only if the check admits it; changing this
+   * copy changes nothing the host records.
+   */
+  readonly parameters: Readonly<Record<string, unknown>>;
+  /**
+   * Aborted when the host's admission deadline passes. Hosts pass an
+   * `AbortSignal`. `@fabricorg/platform-host` refuses an answer that settles
+   * at or after the deadline, even one that settles before the abort.
+   */
+  readonly signal: ActionAdmissionSignal;
 }
 /**
  * The part of an `AbortSignal` an admission check can rely on. Declared
  * structurally so this module compiles without DOM or Node type libraries; a
  * host passes a real `AbortSignal`, which satisfies it.
  */
-interface ActionAdmissionSignal {
-    readonly aborted: boolean;
-    addEventListener(type: "abort", listener: () => void, options?: {
-        once?: boolean;
-    }): void;
-    removeEventListener(type: "abort", listener: () => void): void;
+export interface ActionAdmissionSignal {
+  readonly aborted: boolean;
+  addEventListener(type: "abort", listener: () => void, options?: {
+    once?: boolean;
+  }): void;
+  removeEventListener(type: "abort", listener: () => void): void;
 }
 /**
  * An admission check's answer. Only `{ admitted: true }` admits. A refusal's
@@ -93,11 +93,11 @@ interface ActionAdmissionSignal {
  * then letters, digits, `_`, `.`, `:` or `-`, at most 128 characters), never
  * a submitted value: the host puts it in the error it throws.
  */
-type ActionAdmissionDecision = {
-    readonly admitted: true;
+export type ActionAdmissionDecision = {
+  readonly admitted: true;
 } | {
-    readonly admitted: false;
-    readonly code: string;
+  readonly admitted: false;
+  readonly code: string;
 };
 /**
  * Decides whether a submission may be recorded at all. A host that supports
@@ -105,165 +105,164 @@ type ActionAdmissionDecision = {
  * anything durable for the submission; a refusal, a throw, a timeout or any
  * answer other than `{ admitted: true }` refuses the submission.
  */
-type ActionAdmission = (input: ActionAdmissionInput) => Promise<ActionAdmissionDecision>;
-interface ActionResult {
-    success: boolean;
-    data?: Record<string, unknown>;
-    error?: string;
+export type ActionAdmission = (input: ActionAdmissionInput) => Promise<ActionAdmissionDecision>;
+export interface ActionResult {
+  success: boolean;
+  data?: Record<string, unknown>;
+  error?: string;
 }
-type ActionHandler<TDb = unknown> = (ctx: ActionContext<TDb>, params: unknown) => Promise<ActionResult>;
-interface AdapterStepRetryPolicy {
-    idempotent: boolean;
-    maxAttempts?: number;
-    initialDelayMs?: number;
-    backoffMultiplier?: number;
-    maxDelayMs?: number;
+export type ActionHandler<TDb = unknown> = (ctx: ActionContext<TDb>, params: unknown) => Promise<ActionResult>;
+export interface AdapterStepRetryPolicy {
+  idempotent: boolean;
+  maxAttempts?: number;
+  initialDelayMs?: number;
+  backoffMultiplier?: number;
+  maxDelayMs?: number;
 }
-interface AdapterStep {
-    adapterType: string;
-    operation: string;
-    retryPolicy?: AdapterStepRetryPolicy;
-    getInput: (params: unknown, handlerResult: Record<string, unknown>) => Record<string, unknown> | undefined;
+export interface AdapterStep {
+  adapterType: string;
+  operation: string;
+  retryPolicy?: AdapterStepRetryPolicy;
+  getInput: (params: unknown, handlerResult: Record<string, unknown>) => Record<string, unknown> | undefined;
 }
-interface ActionStateMachineBinding {
-    entityType: string;
-    targetState: string | ((params: unknown) => string);
-    getEntityId: (params: unknown) => string | undefined;
+export interface ActionStateMachineBinding {
+  entityType: string;
+  targetState: string | ((params: unknown) => string);
+  getEntityId: (params: unknown) => string | undefined;
 }
-interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {
-    actionId: ActionId;
-    namespace: string;
-    version: number;
-    schema: SchemaValidator;
-    /**
-     * Optional check a host runs on every submission before it records
-     * anything durable for it (invocation, idempotency key, events, errors).
-     * Use it when parameters must be validated against trusted context, for
-     * example a secret reference the tenant's secret store must hold, before
-     * they may be persisted. `@fabricorg/platform-host` runs it from the
-     * release that introduced it; an older host ignores it, so a handler that
-     * relies on it should require `ActionContext.admittedAt`.
-     */
-    admitSubmission?: ActionAdmission;
-    /** Optional validation contract for the public handler result data. */
-    resultSchema?: SchemaValidator;
-    handler?: ActionHandler<TDb>;
-    requiredRoles?: string[];
-    requiredPermissions?: string[];
-    policies?: `${string}.v${number}`[];
-    emitsEvents: string[];
-    idempotent: boolean;
-    mutatesDomain: boolean;
-    /** Portable execution semantics used by hosts, gateways, and generated capability contracts. */
-    execution?: ActionExecutionContract;
-    stateMachine?: ActionStateMachineBinding;
-    adapterSteps?: AdapterStep[];
-    /** Completion actions can attest only after all external adapter work succeeds. */
-    eventPhase?: "before_adapters" | "after_adapters";
-    /**
-     * If "saga", the action is a multi-step orchestration. The worker dispatches
-     * to a registered saga implementation instead of running `handler` directly.
-     */
-    kind?: "atomic" | "saga";
+export interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {
+  actionId: ActionId;
+  namespace: string;
+  version: number;
+  schema: SchemaValidator;
+  /**
+   * Optional check a host runs on every submission before it records
+   * anything durable for it (invocation, idempotency key, events, errors).
+   * Use it when parameters must be validated against trusted context, for
+   * example a secret reference the tenant's secret store must hold, before
+   * they may be persisted. `@fabricorg/platform-host` runs it from the
+   * release that introduced it; an older host ignores it, so a handler that
+   * relies on it should require `ActionContext.admittedAt`.
+   */
+  admitSubmission?: ActionAdmission;
+  /** Optional validation contract for the public handler result data. */
+  resultSchema?: SchemaValidator;
+  handler?: ActionHandler<TDb>;
+  requiredRoles?: string[];
+  requiredPermissions?: string[];
+  policies?: `${string}.v${number}`[];
+  emitsEvents: string[];
+  idempotent: boolean;
+  mutatesDomain: boolean;
+  /** Portable execution semantics used by hosts, gateways, and generated capability contracts. */
+  execution?: ActionExecutionContract;
+  stateMachine?: ActionStateMachineBinding;
+  adapterSteps?: AdapterStep[];
+  /** Completion actions can attest only after all external adapter work succeeds. */
+  eventPhase?: "before_adapters" | "after_adapters";
+  /**
+   * If "saga", the action is a multi-step orchestration. The worker dispatches
+   * to a registered saga implementation instead of running `handler` directly.
+   */
+  kind?: "atomic" | "saga";
 }
-type ActionConnectivity = "online-required" | "offline-capturable";
-type AuthorityMoment = "capture" | "execution" | "both";
-type ActionIdempotencyStance = "required" | "supported" | "prohibited";
-type ActionCompletionMode = "immediate" | "accepted" | "long-running";
-type ActionConsistency = "authoritative-now" | "provisional-until-reconciled";
-type ActionDataSensitivity = "public" | "internal" | "confidential" | "restricted";
-interface ActionExecutionContract {
-    connectivity: ActionConnectivity;
-    authorityMoment: AuthorityMoment;
-    idempotency: ActionIdempotencyStance;
-    /**
-     * `immediate`: the invocation settles within the host's execution.
-     * `accepted` and `long-running`: an adapter may hand the work to an
-     * external system and the invocation stays running until that system
-     * completes it by reference through the host's completion ingress.
-     * Declare `completionDeadlineMs` on a `long-running` action so a callback
-     * that never comes is noticed rather than waited on forever.
-     */
-    completion: ActionCompletionMode;
-    /**
-     * How long an accepted handoff may wait for its completion before the host
-     * moves the invocation to reconciliation. Without it, nothing sweeps the
-     * handoff. Refused on `immediate`, since nothing external completes it.
-     */
-    completionDeadlineMs?: number;
-    consistency: ActionConsistency;
-    sensitivity?: ActionDataSensitivity;
+export type ActionConnectivity = "online-required" | "offline-capturable";
+export type AuthorityMoment = "capture" | "execution" | "both";
+export type ActionIdempotencyStance = "required" | "supported" | "prohibited";
+export type ActionCompletionMode = "immediate" | "accepted" | "long-running";
+export type ActionConsistency = "authoritative-now" | "provisional-until-reconciled";
+export type ActionDataSensitivity = "public" | "internal" | "confidential" | "restricted";
+export interface ActionExecutionContract {
+  connectivity: ActionConnectivity;
+  authorityMoment: AuthorityMoment;
+  idempotency: ActionIdempotencyStance;
+  /**
+   * `immediate`: the invocation settles within the host's execution.
+   * `accepted` and `long-running`: an adapter may hand the work to an
+   * external system and the invocation stays running until that system
+   * completes it by reference through the host's completion ingress.
+   * Declare `completionDeadlineMs` on a `long-running` action so a callback
+   * that never comes is noticed rather than waited on forever.
+   */
+  completion: ActionCompletionMode;
+  /**
+   * How long an accepted handoff may wait for its completion before the host
+   * moves the invocation to reconciliation. Without it, nothing sweeps the
+   * handoff. Refused on `immediate`, since nothing external completes it.
+   */
+  completionDeadlineMs?: number;
+  consistency: ActionConsistency;
+  sensitivity?: ActionDataSensitivity;
 }
-interface SagaContext {
-    actionInvocationId: string;
-    tenantId: string;
-    spaceId: string;
-    parameters: unknown;
-    sleep?: (delayMs: number) => Promise<void>;
-    query?: <T = unknown>(model: string, operation: string, args: unknown) => Promise<T>;
-    /**
-     * Wait for a named external signal carrying a payload of `T`, with a timeout.
-     *
-     * Resolves with the payload of the first signal received, or `null` if the timeout
-     * fires first. Subsequent distinct signals with the same name received before
-     * another `awaitSignal` call are buffered in FIFO order so none is lost.
-     *
-     * A signal may carry a stable signal ID that the sender keeps the same on each redelivery
-     * (for example a webhook delivery ID or an approval decision ID). A runtime drops
-     * a signal whose ID it has already received for this saga, so a sender retrying
-     * after a timeout does not wake the saga twice. Signals without an ID are not
-     * deduplicated. `@fabricorg/platform-temporal` provides `createSagaSignalInbox()`
-     * for Temporal runtimes.
-     *
-     * Intended for agent-driven and webhook-driven coordination: replace polling loops
-     * with push-based wakeups while preserving the saga's deterministic replay
-     * semantics (the runtime is responsible for capturing signals into workflow history).
-     *
-     * Optional. Runtimes that cannot implement push-based signaling (e.g. an in-memory
-     * test harness) may omit this; sagas should treat absence as a fallback condition
-     * and use `sleep` + `query` polling instead.
-     *
-     * Signal *senders* are runtime-specific (e.g. a Temporal `WorkflowClient.signal()`
-     * call from an action handler). Apps that need to send signals from action
-     * handlers should expose a coordination service via `ActionContext.services`
-     * — the platform does not prescribe the sender API.
-     *
-     * @example
-     * const payload = await ctx.awaitSignal?.<{ result: Record<string, unknown> }>(
-     *   "userInputProcessed",
-     *   5 * 60 * 1000,
-     * );
-     * if (payload) { /* handle pushed result *\/ }
-     * else        { /* timeout — fall back to deterministic path *\/ }
-     */
-    awaitSignal?: <T = unknown>(signalName: string, timeoutMs: number) => Promise<T | null>;
+export interface SagaContext {
+  actionInvocationId: string;
+  tenantId: string;
+  spaceId: string;
+  parameters: unknown;
+  sleep?: (delayMs: number) => Promise<void>;
+  query?: <T = unknown>(model: string, operation: string, args: unknown) => Promise<T>;
+  /**
+   * Wait for a named external signal carrying a payload of `T`, with a timeout.
+   *
+   * Resolves with the payload of the first signal received, or `null` if the timeout
+   * fires first. Subsequent distinct signals with the same name received before
+   * another `awaitSignal` call are buffered in FIFO order so none is lost.
+   *
+   * A signal may carry a stable signal ID that the sender keeps the same on each redelivery
+   * (for example a webhook delivery ID or an approval decision ID). A runtime drops
+   * a signal whose ID it has already received for this saga, so a sender retrying
+   * after a timeout does not wake the saga twice. Signals without an ID are not
+   * deduplicated. `@fabricorg/platform-temporal` provides `createSagaSignalInbox()`
+   * for Temporal runtimes.
+   *
+   * Intended for agent-driven and webhook-driven coordination: replace polling loops
+   * with push-based wakeups while preserving the saga's deterministic replay
+   * semantics (the runtime is responsible for capturing signals into workflow history).
+   *
+   * Optional. Runtimes that cannot implement push-based signaling (e.g. an in-memory
+   * test harness) may omit this; sagas should treat absence as a fallback condition
+   * and use `sleep` + `query` polling instead.
+   *
+   * Signal *senders* are runtime-specific (e.g. a Temporal `WorkflowClient.signal()`
+   * call from an action handler). Apps that need to send signals from action
+   * handlers should expose a coordination service via `ActionContext.services`
+   * — the platform does not prescribe the sender API.
+   *
+   * @example
+   * const payload = await ctx.awaitSignal?.<{ result: Record<string, unknown> }>(
+   *   "userInputProcessed",
+   *   5 * 60 * 1000,
+   * );
+   * if (payload) { /* handle pushed result *\/ }
+   * else        { /* timeout — fall back to deterministic path *\/ }
+   */
+  awaitSignal?: <T = unknown>(signalName: string, timeoutMs: number) => Promise<T | null>;
 }
-interface SagaChildActionInput {
-    suffix: string;
-    actionId: string;
-    parameters: Record<string, unknown>;
+export interface SagaChildActionInput {
+  suffix: string;
+  actionId: string;
+  parameters: Record<string, unknown>;
 }
-type SagaRunChild = (input: SagaChildActionInput) => Promise<Record<string, unknown>>;
-interface SagaCompletionEvent {
-    eventType: string;
-    subjectType: string;
-    subjectId: string;
-    payload: unknown;
-    eventSchemaVersion?: number;
+export type SagaRunChild = (input: SagaChildActionInput) => Promise<Record<string, unknown>>;
+export interface SagaCompletionEvent {
+  eventType: string;
+  subjectType: string;
+  subjectId: string;
+  payload: unknown;
+  eventSchemaVersion?: number;
 }
-interface SagaCompletion {
-    resultData: Record<string, unknown>;
-    event?: SagaCompletionEvent;
+export interface SagaCompletion {
+  resultData: Record<string, unknown>;
+  event?: SagaCompletionEvent;
 }
-type SagaImplementation = (ctx: SagaContext, runChild: SagaRunChild) => Promise<SagaCompletion>;
-declare function assertActionId(actionId: string): asserts actionId is ActionId;
-interface ActionRegistry<TDb = unknown> {
-    register(definition: ActionDefinition<TDb>): void;
-    registerIfMissing(definition: ActionDefinition<TDb>): void;
-    resolve(actionId: ActionId): ActionDefinition<TDb> | undefined;
-    has(actionId: string): actionId is ActionId;
-    ids(): ActionId[];
+export type SagaImplementation = (ctx: SagaContext, runChild: SagaRunChild) => Promise<SagaCompletion>;
+export declare function assertActionId(actionId: string): asserts actionId is ActionId;
+export interface ActionRegistry<TDb = unknown> {
+  register(definition: ActionDefinition<TDb>): void;
+  registerIfMissing(definition: ActionDefinition<TDb>): void;
+  resolve(actionId: ActionId): ActionDefinition<TDb> | undefined;
+  has(actionId: string): actionId is ActionId;
+  ids(): ActionId[];
 }
-declare function createActionRegistry<TDb = unknown>(definitions?: readonly ActionDefinition<TDb>[]): ActionRegistry<TDb>;
-
-export { ACTOR_TYPES, type ActionAdmission, type ActionAdmissionDecision, type ActionAdmissionInput, type ActionAdmissionSignal, type ActionCompletionMode, type ActionConnectivity, type ActionConsistency, type ActionContext, type ActionDataSensitivity, type ActionDefinition, type ActionExecutionContract, type ActionHandler, type ActionId, type ActionIdempotencyStance, type ActionRegistry, type ActionResult, type ActionStateMachineBinding, type ActionStatus, type ActorType, type AdapterStep, type AdapterStepRetryPolicy, type AuthorityMoment, type FabricRuntimeServices, type SagaChildActionInput, type SagaCompletion, type SagaCompletionEvent, type SagaContext, type SagaImplementation, type SagaRunChild, type SchemaParseIssue, type SchemaParseResult, type SchemaValidator, assertActionId, assertActorType, createActionRegistry, isActorType };
+export declare function createActionRegistry<TDb = unknown>(definitions?: readonly ActionDefinition<TDb>[]): ActionRegistry<TDb>;
+//#endregion