@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/flows-actors/flows-actors-execution.shared.schemas.js

@@ -0,0 +1,337 @@
+/**
+ * Flows-Actors Execution — Persisted Resource Schema (POLYMORPHIC)
+ * ================================================================
+ *
+ * A persisted record of a single flow/actor **system execution** — in v1 the
+ * durable source of truth for a conversational chat log (`messages[]`) plus the
+ * execution's lifecycle status.
+ *
+ * POLYMORPHIC ACROSS OWNER SCOPE. The SAME base envelope is stamped out as THREE
+ * genuine single-scope resources by `declarePolymorphicSchemas()`, one owner FK
+ * injected per variant:
+ *   - `userFlowActorExecutions`         (USER_SELF     — `userId`)         ← WS chat + user-delegated A2A
+ *   - `organizationFlowActorExecutions` (ORGANIZATIONS — `organizationId`) ← org-machine A2A
+ *   - `applicationFlowActorExecutions`  (APPLICATION   — `applicationId`)  ← app-machine A2A
+ *
+ * A conversation is owned by EXACTLY ONE scope (its injected owner FK). There is
+ * no cross-scope audit dimension on the base — ownership IS the scope. This is the
+ * honest "one concept, N owners" model (mirrors billing accounts / subscriptions)
+ * and needs ZERO core-authorizer change: each variant satisfies its own scope
+ * authorizer, and `polymorphicRole` resolves the operation roles per scope. A
+ * machine (API key / OIDC client) reaches its org/app variant exactly as it
+ * reaches any other org/app resource — standard RBAC via its granted roles.
+ *
+ * KIND-AGNOSTIC BY DESIGN. A `FlowActorSystem_Kind` discriminant lets the SAME
+ * resource persist both flow and actor executions. v1 implements the ACTOR
+ * conversational path; the FLOW path drops in without reshaping the base envelope.
+ *
+ * @see flows-actors.system.shared.schemas.ts — the base execution envelope
+ * @see billing-account.shared.schemas.ts — the polymorphic-scope precedent
+ * @see requests/websocket.shared.schemas.ts — the streamed message payload this
+ *   log mirrors (`WS_FlowsActorsMessagePayloadSchema`)
+ */
+import { z } from 'zod';
+import { initZodDecorators } from '@wildo-ai/zod-decorators';
+import { FlowsActors_Status } from './flows-actors.commons.shared.schemas.js';
+import { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas.js';
+import { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas.js';
+import { FlowActorSystem_Kind } from './flows-actors.system.shared.schemas.js';
+import { CoreResourceType, coreResourceShared_FieldIdentifier, } from '../resources/resources.shared.core.definitions.js';
+import { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey, } from '../resources/utils/resource-polymorphism.schemas.js';
+initZodDecorators(z);
+//===============================================================
+//  Conversational message log
+//===============================================================
+/**
+ * Author of a persisted conversational message. `TOOL` records a tool-call /
+ * tool-result turn (grounding retrieval); `SYSTEM` records a system/status note.
+ * WS-streamed messages are always server→client, so the transport shape carries
+ * no role — the persisted log adds it to reconstruct a full transcript.
+ */
+export var FlowsActors_ConversationRole;
+(function (FlowsActors_ConversationRole) {
+    FlowsActors_ConversationRole["USER"] = "user";
+    FlowsActors_ConversationRole["ASSISTANT"] = "assistant";
+    FlowsActors_ConversationRole["SYSTEM"] = "system";
+    FlowsActors_ConversationRole["TOOL"] = "tool";
+})(FlowsActors_ConversationRole || (FlowsActors_ConversationRole = {}));
+/**
+ * Rendering hint for a message body. Mirrors the streamed
+ * `WS_FlowsActorsMessagePayloadSchema.messageType` literal union exactly
+ * (`text | markdown | progress | data`) as an enum so the persisted log and the
+ * live stream share one vocabulary (framework rule: enums over literal unions).
+ */
+export var FlowsActors_MessageContentType;
+(function (FlowsActors_MessageContentType) {
+    FlowsActors_MessageContentType["TEXT"] = "text";
+    FlowsActors_MessageContentType["MARKDOWN"] = "markdown";
+    FlowsActors_MessageContentType["PROGRESS"] = "progress";
+    FlowsActors_MessageContentType["DATA"] = "data";
+})(FlowsActors_MessageContentType || (FlowsActors_MessageContentType = {}));
+export const FlowActorExecution_MessageSchema = z.object({
+    /** Stable per-message id (client-correlatable across stream deltas). */
+    id: z.uuid(),
+    role: z.enum(FlowsActors_ConversationRole),
+    contentType: z.enum(FlowsActors_MessageContentType).default(FlowsActors_MessageContentType.TEXT),
+    /** Rendered text content (may be assembled from streamed deltas). */
+    content: z.string(),
+    /** Structured payload for `DATA`/`PROGRESS` messages (tool results, progress). */
+    data: z.record(z.string(), z.unknown()).optional(),
+    createdAt: z.date().default(() => new Date()),
+});
+/**
+ * The SUSPENDED-TURN state persisted when an agent turn pauses at a human-in-the-loop
+ * approval boundary (execution `status` = `AWAITING_APPROVAL`). It is stored SERIALIZED as a
+ * JSON string in the `pausedApproval` scalar field — NOT as a nested Zod object — because heavy
+ * nested sub-structures do not round-trip through the Zod→Mongoose embedded-subdocument
+ * conversion (see the per-kind state note below). Parse/serialize ONLY via the helpers below at
+ * the persistence boundary; the record column itself stays a plain string.
+ */
+export const FlowActorExecution_PausedApprovalSchema = z.object({
+    /**
+     * Correlates the emitted approval REQUEST with the inbound decision (idempotency key).
+     *
+     * An OPAQUE identifier minted by the model SDK — NOT a Wildo id and NOT a UUID. It was typed
+     * `z.uuid()` on the reasonable-looking assumption that an id is a uuid, and the SDK produces
+     * values like `aitxt-3Xfhq68r7GTRXEuV1YzU4eEc`.
+     *
+     * That single wrong assumption made EVERY paused turn unresumable, and hid completely: serializing
+     * is `JSON.stringify` and does not validate, so the pause persisted perfectly; only the resume's
+     * `parse` rejected it, as a CORRUPTED blob. The turn then stayed paused forever with a
+     * "state is unreadable" error naming the wrong cause. Unit fixtures used a real uuid, so they were
+     * more conformant than production and could never reproduce it — the live lane found it.
+     *
+     * Validate it as an opaque non-empty string. We do not own the format and must not assert one.
+     */
+    approvalId: z.string().min(1),
+    /**
+     * The AI-SDK model-message array to RESUME from — opaque to us (the SDK's own resume
+     * contract). Captured when the approval-gated tool call suspended the stream; on the human
+     * decision the runtime appends a tool-approval-response and re-invokes with these messages.
+     */
+    sdkModelMessages: z.array(z.record(z.string(), z.unknown())),
+    /** The approval-gated tool the model wants to call (drives the human-facing prompt). */
+    pendingToolName: z.string(),
+    /** The pending tool call's arguments (drives the human-facing action description). */
+    pendingToolArgs: z.record(z.string(), z.unknown()).optional(),
+    /** ISO timestamp when the approval was requested. */
+    requestedAt: z.string(),
+    /** Optional ISO expiry after which the paused turn is auto-failed. */
+    expiresAt: z.string().optional(),
+});
+/** Serialize paused-approval state for the scalar `pausedApproval` string column. */
+export function serializeFlowActorPausedApproval(state) {
+    return JSON.stringify(state);
+}
+/**
+ * Parse the scalar `pausedApproval` string column back to typed state. Throws (ZodError /
+ * SyntaxError) on a malformed blob — a corrupted paused record must fail loudly at resume,
+ * never silently resume from garbage.
+ */
+export function parseFlowActorPausedApproval(raw) {
+    return FlowActorExecution_PausedApprovalSchema.parse(JSON.parse(raw));
+}
+//===============================================================
+//  Per-kind execution state (reused from the shared execution types)
+//===============================================================
+// NOTE (v1 scope): the persisted record is the CONVERSATIONAL envelope only —
+// `kind` + `status`/`statusChanges` + the `messages[]` chat log. The richer
+// per-kind graph-state slots (`flowState` node-states / `actorState` plan+tasks,
+// sliced from `FlowSystem_Execution` / `ActorSystem_Execution`) are intentionally
+// NOT persisted yet: the v1 conversational runtime never writes them, and those
+// heavy nested sub-structures (required `plan`/`walkthrough`/`standaloneTasks`
+// with embedded `_id`s) do not round-trip through the Zod→Mongoose embedded-
+// subdocument conversion as optional slots (empty subdocs get instantiated and
+// fail required-path validation). When the flow/actor orchestration runtime
+// actually produces graph state, add typed `flowState`/`actorState` back WITH the
+// embedded-subdocument treatment (see the zod↔mongoose nested-union / embedded-id
+// notes) rather than a raw `.pick()`. `kind` already preserves discrimination.
+//===============================================================
+//  Base execution record — NO owner scope FK (injected per variant)
+//===============================================================
+/**
+ * The conversation envelope shared by every scope variant. It carries NO owner
+ * scope FK: `declarePolymorphicSchemas()` injects exactly ONE (`userId` /
+ * `organizationId` / `applicationId`) per variant. Do NOT add an `initiator`
+ * snapshot here — a nested `initiator.userId`/`.organizationId` collides with the
+ * contextual scope filter (it matches the field identifier at every schema path
+ * and injects an exact-subdocument clause that never equals the stored snapshot,
+ * so every scoped read/update silently matches zero rows). Ownership lives ONLY on
+ * the single injected top-level owner FK.
+ */
+export const FlowActorExecutionBaseSchema = z.object({
+    /** MongoDB document id — auto-generated / auto-managed (excluded from create). */
+    _id: z.string().min(1).isPrimaryKey(),
+    /**
+     * Stable business id of the execution, generated by the conversational runtime
+     * and echoed over the WebSocket channel (`WS_FlowsActors*.executionId`). Unique
+     * per variant collection (a UUID — no cross-collection collision). Immutable
+     * once created.
+     */
+    executionId: z.uuid().isUnique({ scope: 'global', sparse: false }).excludeFromUpdate().isSummaryField(),
+    // === System identity (set on create, immutable) ===
+    /** Ref of the executed flow/actor system (`FlowActorSystem.ref`). */
+    systemRef: z.string().isDBIndexed().excludeFromUpdate().isSummaryField(),
+    /** Discriminant selecting which state slot is populated. */
+    kind: z.enum(FlowActorSystem_Kind).isDBIndexed().excludeFromUpdate().isSummaryField(),
+    // === Runtime status ===
+    /**
+     * WHICH agent this conversation was opened through — part of the read filter, not metadata.
+     *
+     * The task family carried this from gate #3; executions did not, so a caller holding a
+     * `contextId` could continue that thread through a DIFFERENT declared agent and load the prior
+     * transcript into the other agent's context. A2A agents are declared as separate resource servers
+     * with per-instance token audiences, and the plane at risk here holds the full message log — not
+     * a 120-character title (review finding G5-8).
+     *
+     * The WebSocket surface has no agent, and the default A2A agent is an identity of its own; both
+     * store {@link FLOWS_ACTORS_DEFAULT_AGENT_INSTANCE}.
+     */
+    resourceServerInstanceRef: z.string().min(1).isDBIndexed(),
+    /**
+     * WHICH machine credential opened this conversation — part of the read filter, not metadata.
+     *
+     * Identical axis and identical reasoning to the task family: the injected scope FK does not
+     * identify the principal on the machine variants (`applicationId` is a deployment singleton;
+     * `organizationId` is shared by every machine client of one tenant), so without it a
+     * separately-credentialed client could read and continue another client's conversation — which
+     * carries the full message log, not merely a title.
+     *
+     * User-delegated turns store {@link FLOWS_ACTORS_NO_MACHINE_CREDENTIAL}: the human is the
+     * principal there and the `userId` owner FK already discriminates.
+     */
+    machineCredentialId: z.string().min(1).isDBIndexed(),
+    status: z.enum(FlowsActors_Status).isDBIndexed().isSummaryField(),
+    statusChanges: z.array(z.object({
+        status: z.enum(FlowsActors_Status),
+        timestamp: z.date(),
+    })).default([]),
+    // === Conversational log (chat history) ===
+    /**
+     * The conversation transcript.
+     *
+     * ## Provenance: SUBJECT_PROVIDED, and the asymmetry is the reason (review finding F5-6)
+     *
+     * This array MIXES subject-authored turns (`role: USER`) with model-generated ones
+     * (`role: ASSISTANT`), and provenance is declared per FIELD — there is no per-element mechanism,
+     * so one classification must cover both. The two ways of being wrong are not equally bad:
+     *
+     *   • Classifying DERIVED would EXCLUDE the subject's own words from an Art. 20 bundle. That is a
+     *     failure of the right the article exists to serve.
+     *   • Classifying SUBJECT_PROVIDED includes the assistant's replies alongside them. That is
+     *     over-delivery — but of a transcript the subject was a party to and already saw, which is the
+     *     natural unit a person means by "my conversation".
+     *
+     * So the classification follows the ASYMMETRY, not a per-element truth we cannot express. Revisit
+     * only if per-element provenance ever exists; splitting the array by role at export time was
+     * considered and rejected as inventing a second mechanism for one field.
+     *
+     * ⚠️ **This is a LABELLING change, not a behaviour change**, and the first version of this note
+     * failed to say so. `resolvePortabilityFieldScope` maps `SUBJECT_PROVIDED` *and* `OBSERVED` to
+     * `INCLUDED`, and the resource default was already `OBSERVED` — so `messages` was in the Art. 20
+     * bundle before and after. Nothing about an export changes.
+     *
+     * The rejected alternative the first version omitted is the one that was actually in force:
+     * **`OBSERVED`** — "data generated by the subject's USE of the service", a defensible reading of a
+     * mixed transcript. It is rejected for precision rather than effect: the USER turns are authored
+     * BY the subject, not merely observed of them, and a classification should say the truest thing
+     * available even when two values resolve alike today.
+     *
+     * The task family's `output`/`artifacts` are DERIVED by contrast, and that is not an
+     * inconsistency: those are model output ABOUT the work, with no subject-authored content mixed in.
+     */
+    messages: FlowActorExecution_MessageSchema.array().default([])
+        .portabilityProvenance(DataPortabilityProvenance.SUBJECT_PROVIDED)
+        // The conversation itself. Category as well as provenance, so a notice can enumerate it: the two
+        // axes answer different questions and a provenance alone leaves the field an OUTSTANDING gap.
+        .dataCategories(PersonalDataCategory.USER_CONTENT),
+    // === HITL (human-in-the-loop) suspension ===
+    /**
+     * Serialized {@link FlowActorExecution_PausedApproval} — present ONLY while `status` is
+     * `AWAITING_APPROVAL`. A scalar JSON string (see that schema's doc for why it is NOT a nested
+     * object: the Zod→Mongoose round-trip). Set on pause, cleared on resume / terminal completion;
+     * never authored on create.
+     */
+    /**
+     * Serialized suspended-turn state; `null` once a decision releases the pause.
+     *
+     * `.nullish()`, not `.optional()`, and the difference is load-bearing at the READ. Clearing writes
+     * an explicit `null`; the write then re-parses the row to project its response, and under
+     * `.optional()` that projection throws `expected string, received null`. The clear PERSISTS (there
+     * is no transaction to roll back) and the operation still fails — so the pause was released and
+     * the resume aborted, leaving the turn `failed` with its work never done, reported as a resource
+     * transformation error that names nothing about approvals.
+     *
+     * The input contract needing `.nullish()` (see `FlowActorExecutionUpdateInternalSchema`) is a
+     * SEPARATE surface from this one. Fixing only that gets the value written and still throws on the
+     * way out — both must admit null or neither does.
+     */
+    // This blob contains SDK resume messages and pending tool arguments. It is
+    // runtime continuation state, not conversation content: generic client reads,
+    // summaries and generated API schemas must never disclose it.
+    pausedApproval: z.string().nullish().excludeFromCreate().isBackendOnly(),
+    // === Timing (system-managed; defaults are load-bearing — the create pipeline
+    //     strips these then date-coerces, so a missing default → Invalid Date) ===
+    createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
+    updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate().isSummaryField(),
+    /** Set on terminal completion (via UPDATE); never on create. */
+    finishedAt: z.date().optional().excludeFromCreate().isSummaryField(),
+});
+//===============================================================
+//  Polymorphic declaration — one owner-scope variant per scope
+//===============================================================
+/**
+ * The three owner-scope variants a flows-actors execution is stamped out for.
+ * Each is `isPrimaryScope: true` (the injected owner FK is the primary scope), and
+ * each opts OUT of the singleton auto-business-key: a conversation is MULTI-ROW
+ * per scope (many discussions per user/org/app), so the injected owner FK must NOT
+ * be marked `.isUnique()` — otherwise the second conversation per scope would fail
+ * with a duplicate-key error. Mirrors subscriptions / usage-records / SSO
+ * connections (all multi-row polymorphic resources).
+ */
+export const FLOW_ACTOR_EXECUTION_SCOPE_VARIANTS = [
+    { parentResourceType: CoreResourceType.USERS, parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USERS], isPrimaryScope: true },
+    { parentResourceType: CoreResourceType.ORGANIZATIONS, parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS], isPrimaryScope: true },
+    { parentResourceType: CoreResourceType.APPLICATION, parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION], isPrimaryScope: true },
+].map(optOutPolymorphicAutoBusinessKey);
+/**
+ * Polymorphic declaration for flows-actors executions. Produces 3 variants:
+ *   - users        → `userFlowActorExecutions`         (`userId` injected)
+ *   - organizations→ `organizationFlowActorExecutions` (`organizationId` injected)
+ *   - applications → `applicationFlowActorExecutions`   (`applicationId` injected)
+ */
+export const flowActorExecutionsPolymorphicDeclaration = declarePolymorphicSchemas({
+    baseResourceType: 'flowActorExecutions',
+    baseFieldIdentifier: 'flowActorExecutionId',
+    baseEnumKey: 'FLOW_ACTOR_EXECUTIONS',
+    baseSchema: FlowActorExecutionBaseSchema,
+    variants: FLOW_ACTOR_EXECUTION_SCOPE_VARIANTS,
+});
+/**
+ * Owner-agnostic UPDATE DTO — status transitions, appended messages, completion
+ * time. Shared across all variants because it references NO owner FK (owner is
+ * immutable). `updatedAt` is system-managed; identity fields are `.excludeFromUpdate()`.
+ */
+export const FlowActorExecutionUpdateInternalSchema = z.object({
+    status: FlowActorExecutionBaseSchema.shape.status.optional(),
+    statusChanges: FlowActorExecutionBaseSchema.shape.statusChanges.optional(),
+    messages: FlowActorExecutionBaseSchema.shape.messages.optional(),
+    finishedAt: FlowActorExecutionBaseSchema.shape.finishedAt,
+    /**
+     * The suspended-turn state, written when a turn pauses for a human decision and cleared when one
+     * arrives.
+     *
+     * ⚠️ THIS SCHEMA IS AN ALLOW-LIST, and omitting a field here does not fail — it makes the write
+     * SUCCEED and persist nothing. `pausedApproval` was added to the base envelope when the column was
+     * introduced but never here, so every approval pause wrote its status and its messages and
+     * silently dropped the one field that makes the turn resumable. The row read back as
+     * `AWAITING_APPROVAL` with no state to resume from: a turn stuck forever, with no error anywhere.
+     * Adding a persisted field is therefore never done without adding it to this contract.
+     *
+     * `.nullish()` rather than `.optional()` because clearing is a real transition: the resume writes
+     * an explicit `null` to release the pause, and under `.optional()` that null is rejected — which
+     * would leave a resumed turn still advertising a decision nobody can answer.
+     */
+    pausedApproval: FlowActorExecutionBaseSchema.shape.pausedApproval.nullish(),
+});
+//# sourceMappingURL=flows-actors-execution.shared.schemas.js.map

package/dist/esm/flows-actors/flows-actors-execution.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows-actors-execution.shared.schemas.js","sourceRoot":"","sources":["../../../../src/flows-actors/flows-actors-execution.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Flows-Actors Execution — Persisted Resource Schema (POLYMORPHIC)\n * ================================================================\n *\n * A persisted record of a single flow/actor **system execution** — in v1 the\n * durable source of truth for a conversational chat log (`messages[]`) plus the\n * execution's lifecycle status.\n *\n * POLYMORPHIC ACROSS OWNER SCOPE. The SAME base envelope is stamped out as THREE\n * genuine single-scope resources by `declarePolymorphicSchemas()`, one owner FK\n * injected per variant:\n *   - `userFlowActorExecutions`         (USER_SELF     — `userId`)         ← WS chat + user-delegated A2A\n *   - `organizationFlowActorExecutions` (ORGANIZATIONS — `organizationId`) ← org-machine A2A\n *   - `applicationFlowActorExecutions`  (APPLICATION   — `applicationId`)  ← app-machine A2A\n *\n * A conversation is owned by EXACTLY ONE scope (its injected owner FK). There is\n * no cross-scope audit dimension on the base — ownership IS the scope. This is the\n * honest \"one concept, N owners\" model (mirrors billing accounts / subscriptions)\n * and needs ZERO core-authorizer change: each variant satisfies its own scope\n * authorizer, and `polymorphicRole` resolves the operation roles per scope. A\n * machine (API key / OIDC client) reaches its org/app variant exactly as it\n * reaches any other org/app resource — standard RBAC via its granted roles.\n *\n * KIND-AGNOSTIC BY DESIGN. A `FlowActorSystem_Kind` discriminant lets the SAME\n * resource persist both flow and actor executions. v1 implements the ACTOR\n * conversational path; the FLOW path drops in without reshaping the base envelope.\n *\n * @see flows-actors.system.shared.schemas.ts — the base execution envelope\n * @see billing-account.shared.schemas.ts — the polymorphic-scope precedent\n * @see requests/websocket.shared.schemas.ts — the streamed message payload this\n *   log mirrors (`WS_FlowsActorsMessagePayloadSchema`)\n */\n\nimport { z } from 'zod';\nimport { initZodDecorators } from '@wildo-ai/zod-decorators';\n\nimport { FLOWS_ACTORS_DEFAULT_AGENT_INSTANCE, FLOWS_ACTORS_NO_MACHINE_CREDENTIAL, FlowsActors_Status } from './flows-actors.commons.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { FlowActorSystem_Kind } from './flows-actors.system.shared.schemas';\nimport {\n  CoreResourceType,\n  coreResourceShared_FieldIdentifier,\n} from '../resources/resources.shared.core.definitions';\nimport {\n  declarePolymorphicSchemas,\n  optOutPolymorphicAutoBusinessKey,\n  type PolymorphicVariantDefinition,\n} from '../resources/utils/resource-polymorphism.schemas';\n\ninitZodDecorators(z);\n\n//===============================================================\n//  Conversational message log\n//===============================================================\n\n/**\n * Author of a persisted conversational message. `TOOL` records a tool-call /\n * tool-result turn (grounding retrieval); `SYSTEM` records a system/status note.\n * WS-streamed messages are always server→client, so the transport shape carries\n * no role — the persisted log adds it to reconstruct a full transcript.\n */\nexport enum FlowsActors_ConversationRole {\n  USER = 'user',\n  ASSISTANT = 'assistant',\n  SYSTEM = 'system',\n  TOOL = 'tool',\n}\n\n/**\n * Rendering hint for a message body. Mirrors the streamed\n * `WS_FlowsActorsMessagePayloadSchema.messageType` literal union exactly\n * (`text | markdown | progress | data`) as an enum so the persisted log and the\n * live stream share one vocabulary (framework rule: enums over literal unions).\n */\nexport enum FlowsActors_MessageContentType {\n  TEXT = 'text',\n  MARKDOWN = 'markdown',\n  PROGRESS = 'progress',\n  DATA = 'data',\n}\n\nexport const FlowActorExecution_MessageSchema = z.object({\n  /** Stable per-message id (client-correlatable across stream deltas). */\n  id: z.uuid(),\n  role: z.enum(FlowsActors_ConversationRole),\n  contentType: z.enum(FlowsActors_MessageContentType).default(FlowsActors_MessageContentType.TEXT),\n  /** Rendered text content (may be assembled from streamed deltas). */\n  content: z.string(),\n  /** Structured payload for `DATA`/`PROGRESS` messages (tool results, progress). */\n  data: z.record(z.string(), z.unknown()).optional(),\n  createdAt: z.date().default(() => new Date()),\n});\nexport type FlowActorExecution_Message = z.infer<typeof FlowActorExecution_MessageSchema>;\n\n/**\n * The SUSPENDED-TURN state persisted when an agent turn pauses at a human-in-the-loop\n * approval boundary (execution `status` = `AWAITING_APPROVAL`). It is stored SERIALIZED as a\n * JSON string in the `pausedApproval` scalar field — NOT as a nested Zod object — because heavy\n * nested sub-structures do not round-trip through the Zod→Mongoose embedded-subdocument\n * conversion (see the per-kind state note below). Parse/serialize ONLY via the helpers below at\n * the persistence boundary; the record column itself stays a plain string.\n */\nexport const FlowActorExecution_PausedApprovalSchema = z.object({\n  /**\n   * Correlates the emitted approval REQUEST with the inbound decision (idempotency key).\n   *\n   * An OPAQUE identifier minted by the model SDK — NOT a Wildo id and NOT a UUID. It was typed\n   * `z.uuid()` on the reasonable-looking assumption that an id is a uuid, and the SDK produces\n   * values like `aitxt-3Xfhq68r7GTRXEuV1YzU4eEc`.\n   *\n   * That single wrong assumption made EVERY paused turn unresumable, and hid completely: serializing\n   * is `JSON.stringify` and does not validate, so the pause persisted perfectly; only the resume's\n   * `parse` rejected it, as a CORRUPTED blob. The turn then stayed paused forever with a\n   * \"state is unreadable\" error naming the wrong cause. Unit fixtures used a real uuid, so they were\n   * more conformant than production and could never reproduce it — the live lane found it.\n   *\n   * Validate it as an opaque non-empty string. We do not own the format and must not assert one.\n   */\n  approvalId: z.string().min(1),\n  /**\n   * The AI-SDK model-message array to RESUME from — opaque to us (the SDK's own resume\n   * contract). Captured when the approval-gated tool call suspended the stream; on the human\n   * decision the runtime appends a tool-approval-response and re-invokes with these messages.\n   */\n  sdkModelMessages: z.array(z.record(z.string(), z.unknown())),\n  /** The approval-gated tool the model wants to call (drives the human-facing prompt). */\n  pendingToolName: z.string(),\n  /** The pending tool call's arguments (drives the human-facing action description). */\n  pendingToolArgs: z.record(z.string(), z.unknown()).optional(),\n  /** ISO timestamp when the approval was requested. */\n  requestedAt: z.string(),\n  /** Optional ISO expiry after which the paused turn is auto-failed. */\n  expiresAt: z.string().optional(),\n});\nexport type FlowActorExecution_PausedApproval = z.infer<typeof FlowActorExecution_PausedApprovalSchema>;\n\n/** Serialize paused-approval state for the scalar `pausedApproval` string column. */\nexport function serializeFlowActorPausedApproval(state: FlowActorExecution_PausedApproval): string {\n  return JSON.stringify(state);\n}\n\n/**\n * Parse the scalar `pausedApproval` string column back to typed state. Throws (ZodError /\n * SyntaxError) on a malformed blob — a corrupted paused record must fail loudly at resume,\n * never silently resume from garbage.\n */\nexport function parseFlowActorPausedApproval(raw: string): FlowActorExecution_PausedApproval {\n  return FlowActorExecution_PausedApprovalSchema.parse(JSON.parse(raw));\n}\n\n//===============================================================\n//  Per-kind execution state (reused from the shared execution types)\n//===============================================================\n\n// NOTE (v1 scope): the persisted record is the CONVERSATIONAL envelope only —\n// `kind` + `status`/`statusChanges` + the `messages[]` chat log. The richer\n// per-kind graph-state slots (`flowState` node-states / `actorState` plan+tasks,\n// sliced from `FlowSystem_Execution` / `ActorSystem_Execution`) are intentionally\n// NOT persisted yet: the v1 conversational runtime never writes them, and those\n// heavy nested sub-structures (required `plan`/`walkthrough`/`standaloneTasks`\n// with embedded `_id`s) do not round-trip through the Zod→Mongoose embedded-\n// subdocument conversion as optional slots (empty subdocs get instantiated and\n// fail required-path validation). When the flow/actor orchestration runtime\n// actually produces graph state, add typed `flowState`/`actorState` back WITH the\n// embedded-subdocument treatment (see the zod↔mongoose nested-union / embedded-id\n// notes) rather than a raw `.pick()`. `kind` already preserves discrimination.\n\n//===============================================================\n//  Base execution record — NO owner scope FK (injected per variant)\n//===============================================================\n\n/**\n * The conversation envelope shared by every scope variant. It carries NO owner\n * scope FK: `declarePolymorphicSchemas()` injects exactly ONE (`userId` /\n * `organizationId` / `applicationId`) per variant. Do NOT add an `initiator`\n * snapshot here — a nested `initiator.userId`/`.organizationId` collides with the\n * contextual scope filter (it matches the field identifier at every schema path\n * and injects an exact-subdocument clause that never equals the stored snapshot,\n * so every scoped read/update silently matches zero rows). Ownership lives ONLY on\n * the single injected top-level owner FK.\n */\nexport const FlowActorExecutionBaseSchema = z.object({\n  /** MongoDB document id — auto-generated / auto-managed (excluded from create). */\n  _id: z.string().min(1).isPrimaryKey(),\n\n  /**\n   * Stable business id of the execution, generated by the conversational runtime\n   * and echoed over the WebSocket channel (`WS_FlowsActors*.executionId`). Unique\n   * per variant collection (a UUID — no cross-collection collision). Immutable\n   * once created.\n   */\n  executionId: z.uuid().isUnique({ scope: 'global', sparse: false }).excludeFromUpdate().isSummaryField(),\n\n  // === System identity (set on create, immutable) ===\n  /** Ref of the executed flow/actor system (`FlowActorSystem.ref`). */\n  systemRef: z.string().isDBIndexed().excludeFromUpdate().isSummaryField(),\n  /** Discriminant selecting which state slot is populated. */\n  kind: z.enum(FlowActorSystem_Kind).isDBIndexed().excludeFromUpdate().isSummaryField(),\n\n  // === Runtime status ===\n  /**\n   * WHICH agent this conversation was opened through — part of the read filter, not metadata.\n   *\n   * The task family carried this from gate #3; executions did not, so a caller holding a\n   * `contextId` could continue that thread through a DIFFERENT declared agent and load the prior\n   * transcript into the other agent's context. A2A agents are declared as separate resource servers\n   * with per-instance token audiences, and the plane at risk here holds the full message log — not\n   * a 120-character title (review finding G5-8).\n   *\n   * The WebSocket surface has no agent, and the default A2A agent is an identity of its own; both\n   * store {@link FLOWS_ACTORS_DEFAULT_AGENT_INSTANCE}.\n   */\n  resourceServerInstanceRef: z.string().min(1).isDBIndexed(),\n\n  /**\n   * WHICH machine credential opened this conversation — part of the read filter, not metadata.\n   *\n   * Identical axis and identical reasoning to the task family: the injected scope FK does not\n   * identify the principal on the machine variants (`applicationId` is a deployment singleton;\n   * `organizationId` is shared by every machine client of one tenant), so without it a\n   * separately-credentialed client could read and continue another client's conversation — which\n   * carries the full message log, not merely a title.\n   *\n   * User-delegated turns store {@link FLOWS_ACTORS_NO_MACHINE_CREDENTIAL}: the human is the\n   * principal there and the `userId` owner FK already discriminates.\n   */\n  machineCredentialId: z.string().min(1).isDBIndexed(),\n\n  status: z.enum(FlowsActors_Status).isDBIndexed().isSummaryField(),\n  statusChanges: z.array(z.object({\n    status: z.enum(FlowsActors_Status),\n    timestamp: z.date(),\n  })).default([]),\n\n  // === Conversational log (chat history) ===\n  /**\n   * The conversation transcript.\n   *\n   * ## Provenance: SUBJECT_PROVIDED, and the asymmetry is the reason (review finding F5-6)\n   *\n   * This array MIXES subject-authored turns (`role: USER`) with model-generated ones\n   * (`role: ASSISTANT`), and provenance is declared per FIELD — there is no per-element mechanism,\n   * so one classification must cover both. The two ways of being wrong are not equally bad:\n   *\n   *   • Classifying DERIVED would EXCLUDE the subject's own words from an Art. 20 bundle. That is a\n   *     failure of the right the article exists to serve.\n   *   • Classifying SUBJECT_PROVIDED includes the assistant's replies alongside them. That is\n   *     over-delivery — but of a transcript the subject was a party to and already saw, which is the\n   *     natural unit a person means by \"my conversation\".\n   *\n   * So the classification follows the ASYMMETRY, not a per-element truth we cannot express. Revisit\n   * only if per-element provenance ever exists; splitting the array by role at export time was\n   * considered and rejected as inventing a second mechanism for one field.\n   *\n   * ⚠️ **This is a LABELLING change, not a behaviour change**, and the first version of this note\n   * failed to say so. `resolvePortabilityFieldScope` maps `SUBJECT_PROVIDED` *and* `OBSERVED` to\n   * `INCLUDED`, and the resource default was already `OBSERVED` — so `messages` was in the Art. 20\n   * bundle before and after. Nothing about an export changes.\n   *\n   * The rejected alternative the first version omitted is the one that was actually in force:\n   * **`OBSERVED`** — \"data generated by the subject's USE of the service\", a defensible reading of a\n   * mixed transcript. It is rejected for precision rather than effect: the USER turns are authored\n   * BY the subject, not merely observed of them, and a classification should say the truest thing\n   * available even when two values resolve alike today.\n   *\n   * The task family's `output`/`artifacts` are DERIVED by contrast, and that is not an\n   * inconsistency: those are model output ABOUT the work, with no subject-authored content mixed in.\n   */\n  messages: FlowActorExecution_MessageSchema.array().default([])\n    .portabilityProvenance(DataPortabilityProvenance.SUBJECT_PROVIDED)\n    // The conversation itself. Category as well as provenance, so a notice can enumerate it: the two\n    // axes answer different questions and a provenance alone leaves the field an OUTSTANDING gap.\n    .dataCategories(PersonalDataCategory.USER_CONTENT),\n\n  // === HITL (human-in-the-loop) suspension ===\n  /**\n   * Serialized {@link FlowActorExecution_PausedApproval} — present ONLY while `status` is\n   * `AWAITING_APPROVAL`. A scalar JSON string (see that schema's doc for why it is NOT a nested\n   * object: the Zod→Mongoose round-trip). Set on pause, cleared on resume / terminal completion;\n   * never authored on create.\n   */\n  /**\n   * Serialized suspended-turn state; `null` once a decision releases the pause.\n   *\n   * `.nullish()`, not `.optional()`, and the difference is load-bearing at the READ. Clearing writes\n   * an explicit `null`; the write then re-parses the row to project its response, and under\n   * `.optional()` that projection throws `expected string, received null`. The clear PERSISTS (there\n   * is no transaction to roll back) and the operation still fails — so the pause was released and\n   * the resume aborted, leaving the turn `failed` with its work never done, reported as a resource\n   * transformation error that names nothing about approvals.\n   *\n   * The input contract needing `.nullish()` (see `FlowActorExecutionUpdateInternalSchema`) is a\n   * SEPARATE surface from this one. Fixing only that gets the value written and still throws on the\n   * way out — both must admit null or neither does.\n   */\n  // This blob contains SDK resume messages and pending tool arguments. It is\n  // runtime continuation state, not conversation content: generic client reads,\n  // summaries and generated API schemas must never disclose it.\n  pausedApproval: z.string().nullish().excludeFromCreate().isBackendOnly(),\n\n  // === Timing (system-managed; defaults are load-bearing — the create pipeline\n  //     strips these then date-coerces, so a missing default → Invalid Date) ===\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate().isSummaryField(),\n  /** Set on terminal completion (via UPDATE); never on create. */\n  finishedAt: z.date().optional().excludeFromCreate().isSummaryField(),\n});\nexport type FlowActorExecutionBase = z.infer<typeof FlowActorExecutionBaseSchema>;\n\n//===============================================================\n//  Polymorphic declaration — one owner-scope variant per scope\n//===============================================================\n\n/**\n * The three owner-scope variants a flows-actors execution is stamped out for.\n * Each is `isPrimaryScope: true` (the injected owner FK is the primary scope), and\n * each opts OUT of the singleton auto-business-key: a conversation is MULTI-ROW\n * per scope (many discussions per user/org/app), so the injected owner FK must NOT\n * be marked `.isUnique()` — otherwise the second conversation per scope would fail\n * with a duplicate-key error. Mirrors subscriptions / usage-records / SSO\n * connections (all multi-row polymorphic resources).\n */\nexport const FLOW_ACTOR_EXECUTION_SCOPE_VARIANTS: PolymorphicVariantDefinition[] = [\n  { parentResourceType: CoreResourceType.USERS,         parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USERS],         isPrimaryScope: true },\n  { parentResourceType: CoreResourceType.ORGANIZATIONS, parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS], isPrimaryScope: true },\n  { parentResourceType: CoreResourceType.APPLICATION,   parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION],   isPrimaryScope: true },\n].map(optOutPolymorphicAutoBusinessKey);\n\n/**\n * Polymorphic declaration for flows-actors executions. Produces 3 variants:\n *   - users        → `userFlowActorExecutions`         (`userId` injected)\n *   - organizations→ `organizationFlowActorExecutions` (`organizationId` injected)\n *   - applications → `applicationFlowActorExecutions`   (`applicationId` injected)\n */\nexport const flowActorExecutionsPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'flowActorExecutions',\n  baseFieldIdentifier: 'flowActorExecutionId',\n  baseEnumKey: 'FLOW_ACTOR_EXECUTIONS',\n  baseSchema: FlowActorExecutionBaseSchema,\n  variants: FLOW_ACTOR_EXECUTION_SCOPE_VARIANTS,\n});\n\n/**\n * Owner-agnostic UPDATE DTO — status transitions, appended messages, completion\n * time. Shared across all variants because it references NO owner FK (owner is\n * immutable). `updatedAt` is system-managed; identity fields are `.excludeFromUpdate()`.\n */\nexport const FlowActorExecutionUpdateInternalSchema = z.object({\n  status: FlowActorExecutionBaseSchema.shape.status.optional(),\n  statusChanges: FlowActorExecutionBaseSchema.shape.statusChanges.optional(),\n  messages: FlowActorExecutionBaseSchema.shape.messages.optional(),\n  finishedAt: FlowActorExecutionBaseSchema.shape.finishedAt,\n  /**\n   * The suspended-turn state, written when a turn pauses for a human decision and cleared when one\n   * arrives.\n   *\n   * ⚠️ THIS SCHEMA IS AN ALLOW-LIST, and omitting a field here does not fail — it makes the write\n   * SUCCEED and persist nothing. `pausedApproval` was added to the base envelope when the column was\n   * introduced but never here, so every approval pause wrote its status and its messages and\n   * silently dropped the one field that makes the turn resumable. The row read back as\n   * `AWAITING_APPROVAL` with no state to resume from: a turn stuck forever, with no error anywhere.\n   * Adding a persisted field is therefore never done without adding it to this contract.\n   *\n   * `.nullish()` rather than `.optional()` because clearing is a real transition: the resume writes\n   * an explicit `null` to release the pause, and under `.optional()` that null is rejected — which\n   * would leave a resumed turn still advertising a decision nobody can answer.\n   */\n  pausedApproval: FlowActorExecutionBaseSchema.shape.pausedApproval.nullish(),\n});\n\n//===============================================================\n//  Exported runtime type\n//===============================================================\n\n/**\n * Runtime shape of a persisted execution (the base envelope). The owner FK is\n * variant-specific (`userId` | `organizationId` | `applicationId`) and read from\n * the concrete variant; the conversational runtime supplies it explicitly on create.\n */\nexport type FlowActorExecution = z.infer<typeof FlowActorExecutionBaseSchema>;\n"]}

package/dist/esm/flows-actors/flows-actors-task.shared.resources-config.schemas.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Flows-Actors Task — Resource Configuration (POLYMORPHIC)
+ * ========================================================
+ *
+ * The persisted WORK record behind the A2A `Task` object, stamped out as THREE
+ * owner-scope variants from one polymorphic declaration (`userFlowActorTasks` /
+ * `organizationFlowActorTasks` / `applicationFlowActorTasks`). Spread the produced
+ * factories into the registry factory map:
+ *   ...flowActorTasksPolymorphicFactories
+ *
+ * This is a DIFFERENT PLANE from `flowActorExecutions`: executions own
+ * conversational session history, tasks own an addressable/pollable/cancelable
+ * work lifecycle. See the base schema for why merging them is wrong.
+ *
+ * Scope + access model (mirrors the execution family — same owner scopes, same
+ * RBAC shape — so a task is always readable by exactly the principal that drove
+ * the turn):
+ *   - Owner = the injected scope FK per variant. READ/LIST are `API_CALL`, roles
+ *     resolved PER VARIANT by `polymorphicRole`: a user reads its own (APP_USER +
+ *     USER_SELF filter), a machine reads its org/app variant with its granted
+ *     org/app role. NOTE these roles govern the HTTP surface only — the A2A
+ *     `tasks/get` path does NOT use them (it reads via the ACL-bypassing `readAsSystem`
+ *     and isolates by owner filter instead; see `A2ATaskBackendService`). Tightening
+ *     `polymorphicRole` therefore does not tighten `tasks/get`.
+ *   - CREATE/UPDATE are `INTERNAL_CALL` super-admin: only the runtime materialises
+ *     a task and advances its lifecycle, via `*AsSystem` (governed by
+ *     `systemAccessPolicy`, not the op RBAC). INTERNAL_CALL (not REPOSITORY_ONLY)
+ *     is mandatory — `*AsSystem` dispatches through the service tier and resolves
+ *     the op via `getServiceOperationPathDefault`, which only matches
+ *     INTERNAL_CALL / API_CALL variants.
+ *   - `tasks/cancel` is an UPDATE (status → `CANCELLED`), NOT a delete: the A2A
+ *     spec requires cancel to return the task's UPDATED STATE rather than remove it, so the record must
+ *     spec-cite: A2A v0.2.5 §7.4 (tasks/cancel returns a Task)
+ *     survive cancellation.
+ *   - DELETE exists as a single owner-facing `API_CALL` default. It is REQUIRED,
+ *     not optional: the polymorphic owner relationship is a COMPOSITION, and a
+ *     composition child with no core DELETE op makes the parent's cascade throw
+ *     `ErrorType.CONFIGURATION` inside the delete transaction and roll the parent
+ *     delete back (the exact latent bug the platform hit on
+ *     `wildoApplication*` children — see `resources-relationships.custom.shared.definitions.ts`).
+ *     Its role floor is DISTINCT from read: a user deletes only their own task;
+ *     org/app tasks are shared scope data and require org/app admin.
+ *
+ * @see flows-actors-task.shared.schemas.ts — the polymorphic declaration + base schema
+ * @see flows-actors-execution.shared.resources-config.schemas.ts — the sibling plane
+ */
+import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
+/**
+ * Polymorphic factory map for flows-actors tasks. Spread into
+ * `coreShared_ResourcesConfigurations_FactoryMap`:
+ *   ...flowActorTasksPolymorphicFactories
+ *
+ * Produces entries for:
+ *   - userFlowActorTasks
+ *   - organizationFlowActorTasks
+ *   - applicationFlowActorTasks
+ */
+export declare const flowActorTasksPolymorphicFactories: Record<string, import("..").ResourceConfiguration_InitializationFactory<undefined, CoreResourceOperation.READ | CoreResourceOperation.UPDATE | CoreResourceOperation.DELETE | CoreResourceOperation.CREATE | CoreResourceOperation.LIST, any>>;
+//# sourceMappingURL=flows-actors-task.shared.resources-config.schemas.d.ts.map

package/dist/esm/flows-actors/flows-actors-task.shared.resources-config.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows-actors-task.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/flows-actors-task.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AA2DzG;;;;;;;;;GASG;AACH,eAAO,MAAM,kCAAkC,gPA4H9C,CAAC"}