@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/flows-actors/human-decision.shared.schemas.js

@@ -0,0 +1,754 @@
+import { ApplicationConfigVocabulary, LABEL_KEY_SEGMENT_PATTERN } from '../i18n/application-config-vocabulary.shared.js';
+import { z } from 'zod';
+import { ExecutionContext_ExecutionType } from '../runtime/execution-context.shared.schemas.js';
+//===============================================================
+//  HUMAN DECISION — one payload for every question a person is asked
+//
+// ## What this is, and what it deliberately is NOT
+//
+// This is the CONTRACT for "something is waiting for a person": what they are being asked, what
+// answers they may give, and what a given answer means. It is not a store.
+//
+// That distinction was measured rather than assumed, and it is the whole reason this file is small.
+// Three surfaces suspend on a human, and where each keeps its pending state has MOVED since this was
+// written — the table is the current state, 2026-09-20:
+//
+// | question | pending state lives in | its own shape |
+// |---|---|---|
+// | a mid-run clarification | the run's own ACTOR EXECUTION row — `suspension` (this payload) + `checkpoint` (the resume inputs), status `AWAITING_APPROVAL` | `PlaybookRunSuspensionCheckpoint` |
+// | a parked coding run | the durable actor-task row (`output.suspension`) — moves onto the same two execution fields with the coding lane (#1359) | `CodingAgent_SessionSuspension` |
+// | a playbook's up-front interview | nowhere — it is DECLARED on the playbook and asked before a run exists | `MetaWorkflow_ElicitationSpec` |
+//
+// The history, because the first line of that table was argued the other way twice. Until 2026-09-20
+// this header said "a playbook run creates no execution row at all, so there is no single plane to
+// move them onto" — true until #1343 gave a run an `ActorSystem_Execution`. It then said the
+// conclusion was unchanged because "that row records the RUN, not what the run is waiting for", and
+// that a clarification was "a disposable checkpoint whose whole point is that it costs nothing to
+// lose". #1360 measured that and reversed it: once the engine DRIVES the run (#1358), a wait that
+// lives beside the row needs a second handle, a second store and a second listing to say what the
+// row's own status should, and a suspended run settled `COMPLETED` on the plane while waiting on a
+// person. The row now says what the run is waiting for, and the engine resumes it under the same id.
+//
+// The up-front interview stays where it is for the reason it always had: it is answered BEFORE a run
+// exists to hang it on.
+//
+// Each host PROJECTS what it is waiting for into a `HumanDecision_Request`, and every reader — a
+// workbench panel, a CLI, a future notification — consumes only this. On the actor-system plane the
+// engine persists that projection itself (`ActorExecution_Suspension.decision`); elsewhere it is
+// built on read. What a person is being asked is everyone's either way.
+//
+// ## Why not extend the existing paused-approval state
+//
+// `FlowActorExecution_PausedApproval` looks like the obvious host and is the wrong one. It carries
+// `sdkModelMessages` ("the AI-SDK model-message array to RESUME from — opaque to us"),
+// `pendingToolName` and `pendingToolArgs`: it is an agent-STREAM resume contract. A playbook
+// interview has no model stream and no pending tool, so extending it would leave three required
+// fields meaningless for half its uses. Two distinct concepts, two schemas.
+//
+// ## Two lists, because one question is the special case and not the rule
+//
+// The pre-existing decision components each model exactly ONE question — an options-only choice, or
+// a single text input. A playbook interview asks fifteen at once, so neither fits, and a payload
+// built around "the question" would have had to grow a second shape immediately.
+//
+// So a request carries a FIELD SET and a RESPONSE SET, and every existing surface is a special case:
+// an options-only choice is fields `[]`; a single text prompt is one field with one option; a gated
+// tool call is fields plus approve/deny.
+//
+// ## The serialization trap this schema is written against
+//
+// `FlowActorExecution_PausedApproval.approvalId` was once typed as a uuid on the reasonable
+// assumption that an id is a uuid; the producing SDK emits `aitxt-…`. Serializing is `JSON.stringify`
+// and does NOT validate — only the resume's `parse` does — so every paused turn persisted perfectly
+// and became unresumable, reported as a corrupted blob naming the wrong cause. The unit fixtures used
+// real uuids and were therefore more conformant than production, so they could never reproduce it.
+//
+// Consequence, applied here: every identifier this schema BORROWS from a producer it does not own is
+// an opaque non-empty string, never a format. Assert a format only for ids this layer mints.
+//===============================================================
+/**
+ * What a person is being asked FOR in one field.
+ *
+ * The one named source for this vocabulary. `MetaWorkflow_ElicitationQuestionKind` in the
+ * application-creation layer is an alias of this enum rather than a second copy — the values decide
+ * how an answer is validated, so two enums that drift would mean a CHOICE accepted against the wrong
+ * option set.
+ */
+export var HumanDecision_FieldKind;
+(function (HumanDecision_FieldKind) {
+    /** Prose. The answer is whatever the person writes, trimmed, and must not be empty. */
+    HumanDecision_FieldKind["FREE_TEXT"] = "free_text";
+    /** One of a closed set the request states. An answer outside `options` is REFUSED, never coerced. */
+    HumanDecision_FieldKind["CHOICE"] = "choice";
+    /**
+     * Yes or no.
+     *
+     * The answer must resolve to an unambiguous affirmative or negative and is stored CANONICALLY, not
+     * as the person typed it — downstream readers compare a token rather than re-parsing prose. An
+     * answer that does not resolve ("probably") is refused rather than guessed, because these decide
+     * things: the regulated-domain screening questions are `CONFIRM`s, and one of them silently
+     * meaning "yes" is a compliance posture nobody chose. Resolution lives with the creation layer
+     * that owns the canonical vocabulary.
+     */
+    HumanDecision_FieldKind["CONFIRM"] = "confirm";
+})(HumanDecision_FieldKind || (HumanDecision_FieldKind = {}));
+/**
+ * What giving a particular answer MEANS for the work that is waiting.
+ *
+ * Closed, and deliberately three members rather than one per button. Hosts spell their buttons
+ * differently — accept/decline/cancel, submit/cancel, approve/deny — and a vocabulary with one
+ * member per spelling would have to grow every time a surface is added. What a reader actually needs
+ * to know is whether the waiting work proceeds, and whether it proceeds WITH the values.
+ */
+export var HumanDecision_ResponseIntent;
+(function (HumanDecision_ResponseIntent) {
+    /** Proceed, using the values supplied. Fields are validated and required. */
+    HumanDecision_ResponseIntent["PROCEED_WITH_VALUES"] = "proceed_with_values";
+    /**
+     * Proceed WITHOUT values — the person declined to answer and the work continues on its own
+     * judgement, stating the assumption it made.
+     *
+     * This is also what a DENIAL is, and the distinction matters: denying a gated tool call does not
+     * abort the turn, it resumes it so the model can answer the refusal. Anything that ends the work
+     * is `ABORT`.
+     */
+    HumanDecision_ResponseIntent["PROCEED_WITHOUT_VALUES"] = "proceed_without_values";
+    /** End the waiting work. Nothing is produced and no values are read. */
+    HumanDecision_ResponseIntent["ABORT"] = "abort";
+})(HumanDecision_ResponseIntent || (HumanDecision_ResponseIntent = {}));
+/** One thing a person is asked. `why` is the rationale a host may supply; an interview usually has none. */
+export const HumanDecision_FieldSchema = z.object({
+    /** Stable id the answer is matched by. Host-minted and OPAQUE to this layer — never a format. */
+    ref: z.string().min(1),
+    /** The question, in the words the person should read. Never derived from `ref`. */
+    question: z.string().min(1),
+    kind: z.enum(HumanDecision_FieldKind),
+    /** The complete set, and REQUIRED when `kind` is CHOICE — a choice with no options is unanswerable. */
+    options: z.array(z.string().min(1)).optional(),
+    /** What the waiting work would do differently depending on the answer, when the host can say. */
+    why: z.string().min(1).optional(),
+}).superRefine((field, context) => {
+    if (field.kind !== HumanDecision_FieldKind.CHOICE)
+        return;
+    if ((field.options ?? []).length === 0) {
+        context.addIssue({
+            code: 'custom',
+            message: `Field "${field.ref}" is a CHOICE and states no options, so it cannot be answered.`,
+            path: ['options'],
+        });
+    }
+});
+/**
+ * The two options every TOOL APPROVAL offers (#1594 D1): approve runs the call, deny resumes the turn so the
+ * agent can answer the refusal. Shared because a client answers a tool approval in the one answer shape
+ * (`HumanDecision_Answer.optionRef`), and the option refs it may send are these and no others.
+ */
+export var HumanDecision_ToolApprovalOption;
+(function (HumanDecision_ToolApprovalOption) {
+    HumanDecision_ToolApprovalOption["APPROVE"] = "approve";
+    HumanDecision_ToolApprovalOption["DENY"] = "deny";
+})(HumanDecision_ToolApprovalOption || (HumanDecision_ToolApprovalOption = {}));
+/** One answer a person may give, and what it means for the waiting work. */
+export const HumanDecision_ResponseOptionSchema = z.object({
+    /** Host-defined id echoed back on the answer. Open by design: a host names its own buttons. */
+    ref: z.string().min(1),
+    /** What the button says. Authored text, never humanized from `ref`. */
+    label: z.string().min(1),
+    intent: z.enum(HumanDecision_ResponseIntent),
+    /** Why a person would pick this one, when it is not obvious from the label. */
+    description: z.string().min(1).optional(),
+});
+/**
+ * @wildo_source:part:start saas.models.agent-work-decision-surface facet:layer:shared facet:family:flows-actors facet:audience:app-developer
+ *
+ * Where a decision on an AGENT'S PROPOSAL was taken (#1599). Only a decision on something an agent proposed is
+ * recorded as agent-work review — a clarifying question is not, or it would inflate the override rate's denominator.
+ * An actor-system question is a review only when its `HumanDecision_Request` carries `review: { surface }`.
+ */
+export var AgentWorkDecisionSurface;
+(function (AgentWorkDecisionSurface) {
+    /** A person approved, edited or denied a tool call the agent proposed (the paused-turn approval). Always a proposal. */
+    AgentWorkDecisionSurface["TOOL_CALL_APPROVAL"] = "tool_call_approval";
+    /** A person answered an actor-system suspension that asked them to review the actor's work. */
+    AgentWorkDecisionSurface["ACTOR_REVIEW"] = "actor_review";
+    /** A person reviewed output an agent drafted into the application's own rows (`recordOutputReview`). */
+    AgentWorkDecisionSurface["OUTPUT_REVIEW"] = "output_review";
+})(AgentWorkDecisionSurface || (AgentWorkDecisionSurface = {}));
+/**
+ * A reason code an expert gives for a correction (#1599): one value of the vocabulary the APPLICATION declared
+ * (`agentWorkReview.reasonCodes`). A code outside that vocabulary is refused before anything moves, never stored.
+ *
+ * No `.` (#1921): a code is also the last segment of its label key, `system_enums.AgentWorkReasonCode.<code>`, and
+ * the label tree is addressed by dotted path — a dotted code would name a label nobody could resolve, so it would
+ * render as its raw code forever with nothing reporting why.
+ */
+export const AgentWorkReasonCodeSchema = z.string().min(1).max(80).regex(LABEL_KEY_SEGMENT_PATTERN);
+/**
+ * The NAMED VOCABULARY the reason codes' words live under (#1921): `system_enums.AgentWorkReasonCode.<code>`.
+ *
+ * The VALUES are the application's (`agentWorkReview.reasonCodes`); the NAME is the framework's, so a reviewer surface
+ * and the labelling pipeline agree on where each code's words are without either inventing them. The pipeline plans one
+ * key per declared code; a code with no authored word renders as the code itself — a missing label that looks missing.
+ */
+// The wire value is `'AgentWorkReasonCode'`: the words live under `system_enums.AgentWorkReasonCode.<code>`.
+export const AGENT_WORK_REASON_CODE_VOCABULARY = ApplicationConfigVocabulary.AGENT_WORK_REASON_CODE;
+/** @wildo_source:part:end saas.models.agent-work-decision-surface */
+/**
+ * Something is waiting for a person.
+ *
+ * Projected by whichever host owns the suspended work; never persisted by this layer.
+ */
+export const HumanDecision_RequestSchema = z.object({
+    /**
+     * Correlates this request with the answer that settles it.
+     *
+     * OPAQUE — hosts key it to whatever they already have (a run id, an ACP session id, an actor-task
+     * id), and this layer asserts only that it is present. See the file header for what asserting a
+     * format on a borrowed id once cost.
+     */
+    decisionId: z.string().min(1),
+    /** One line naming what is waiting, for a reader who has not been following the run. */
+    title: z.string().min(1),
+    /** What answering will cause, and what happens if nobody does. */
+    description: z.string().min(1),
+    /** May be empty: a pure approve/deny asks for a verdict and no values. */
+    fields: z.array(HumanDecision_FieldSchema),
+    /** At least one — a request nobody can answer is not a request. */
+    options: z.array(HumanDecision_ResponseOptionSchema).min(1),
+    /** ISO instant the request was raised. */
+    requestedAt: z.string().min(1),
+    /**
+     * ISO instant after which answering is refused.
+     *
+     * Optional, and ABSENT MEANS IT DOES NOT LAPSE — which is the honest reading for work that simply
+     * waits, such as a playbook checkpoint on disk. Do not default it: a deadline nothing enforces is
+     * the defect the paused-approval expiry was fixed for, where the field was declared, rendered, and
+     * never written by any producer.
+     */
+    expiresAt: z.string().min(1).optional(),
+    /** @wildo_source:part:start saas.models.human-decision-review-marker facet:layer:shared facet:family:flows-actors facet:audience:app-developer */
+    /**
+     * Marks the request as a REVIEW of an agent's proposal (#1599): its settlement is recorded as an agent-work
+     * decision on this surface. Absent for a question that asks for information rather than a verdict on work.
+     * A tool approval is always a proposal and needs no marker.
+     */
+    review: z.strictObject({
+        surface: z.enum(AgentWorkDecisionSurface),
+    }).optional(),
+    /** @wildo_source:part:end saas.models.human-decision-review-marker */
+});
+/** What a person answered. */
+export const HumanDecision_AnswerSchema = z.object({
+    decisionId: z.string().min(1),
+    /** Which `options[].ref` was chosen. */
+    optionRef: z.string().min(1),
+    /** One entry per answered field. Empty for an option whose intent is not PROCEED_WITH_VALUES. */
+    values: z.array(z.object({ ref: z.string().min(1), value: z.string() })).default([]),
+});
+/** Refused because the answer does not settle the request it names. */
+export class HumanDecisionAnswerError extends Error {
+}
+/**
+ * Check an answer against the request it claims to settle, and return the values by ref.
+ *
+ * Refuses rather than coerces, at every branch, for the reason the CONFIRM doc gives: these answers
+ * decide things, and a silently-accepted wrong one becomes the record. `CONFIRM` resolution is NOT
+ * done here — this layer does not own the canonical affirmative/negative vocabulary — so a CONFIRM
+ * field is validated as non-empty and the creation layer canonicalises it.
+ *
+ * Note what is deliberately NOT validated: an option this request never offered is refused, but the
+ * INTENT is trusted, because the host authored both the option and its meaning.
+ */
+export function resolveHumanDecisionAnswer(request, answer) {
+    if (answer.decisionId !== request.decisionId) {
+        throw new HumanDecisionAnswerError(`Answer names decision "${answer.decisionId}" but the request is "${request.decisionId}".`);
+    }
+    const option = request.options.find((candidate) => candidate.ref === answer.optionRef);
+    if (!option) {
+        throw new HumanDecisionAnswerError(`Decision "${request.decisionId}" never offered "${answer.optionRef}". Offered: ${request.options.map((entry) => entry.ref).join(', ')}.`);
+    }
+    if (option.intent !== HumanDecision_ResponseIntent.PROCEED_WITH_VALUES) {
+        if (answer.values.length > 0) {
+            throw new HumanDecisionAnswerError(`Option "${option.ref}" does not carry values, but ${answer.values.length} were supplied.`);
+        }
+        return { option, values: {} };
+    }
+    const byRef = new Map(request.fields.map((field) => [field.ref, field]));
+    const values = {};
+    for (const entry of answer.values) {
+        const field = byRef.get(entry.ref);
+        if (!field) {
+            throw new HumanDecisionAnswerError(`Decision "${request.decisionId}" never asks "${entry.ref}". Asked: ${[...byRef.keys()].join(', ')}.`);
+        }
+        if (Object.hasOwn(values, entry.ref)) {
+            throw new HumanDecisionAnswerError(`Field "${entry.ref}" was answered more than once.`);
+        }
+        const trimmed = entry.value.trim();
+        if (trimmed.length === 0) {
+            throw new HumanDecisionAnswerError(`Field "${entry.ref}" was answered with empty text.`);
+        }
+        if (field.kind === HumanDecision_FieldKind.CHOICE && !(field.options ?? []).includes(trimmed)) {
+            throw new HumanDecisionAnswerError(`Field "${entry.ref}" is a CHOICE; "${trimmed}" is not one of its options (${(field.options ?? []).join(', ')}).`);
+        }
+        values[entry.ref] = trimmed;
+    }
+    /*
+     * Every field must be answered, and the contract declares no optional ones.
+     *
+     * A missing answer is a gap in the interview rather than an implicit "no" — several questions are
+     * written to be answerable when they do not apply ("answer 'none' if there is no trigger"), so
+     * silently proceeding is how a record acquires an empty field that later reads as a decision
+     * somebody made.
+     */
+    const missing = request.fields.filter((field) => !Object.hasOwn(values, field.ref)).map((field) => field.ref);
+    if (missing.length > 0) {
+        throw new HumanDecisionAnswerError(`Decision "${request.decisionId}" needs an answer to every field it asks; missing: ${missing.join(', ')}.`);
+    }
+    return { option, values };
+}
+//===============================================================
+//  WHO MAY SETTLE A PENDING DECISION, AND WHAT SETTLING IT MEANT (#1594)
+//
+// Both planes that suspend on a person — the conversational tool approval (`pausedApproval` on an
+// execution row) and the actor-system suspension — describe the same three things: what is asked
+// (`HumanDecision_Request`, above), WHO may answer it (`HumanDecision_Route`), and on whose authority
+// the waiting work was raised (`HumanDecision_Requester`). Each plane stores these on the row that
+// holds its resume compare-and-swap, so a reassignment and an answer can never both win; this file
+// owns only the shapes and the pure decisions over them.
+//===============================================================
+/** @wildo_source:part:start saas.models.flows-actors.human-decision-vocabulary facet:layer:shared facet:family:flows-actors facet:audience:app-developer */
+/**
+ * How a pending decision ended. The ONE vocabulary every outcome column, audit event and record reads
+ * from — the conversational release, the lapse sweep, a withdrawn task, the actor-plane resume.
+ *
+ * `LAPSED` is not a refusal. Nobody said no; nobody answered in time. A report that counts it as
+ * `REJECTED` overstates how often reviewers refuse agents, which is exactly the figure an auditor asks
+ * for, so the two stay distinct members rather than one "not approved".
+ */
+export var HumanDecision_Outcome;
+(function (HumanDecision_Outcome) {
+    /** A person approved, unchanged. */
+    HumanDecision_Outcome["ACCEPTED"] = "accepted";
+    /** A person approved after changing what was proposed. Which arguments changed is recorded by NAME only. */
+    HumanDecision_Outcome["ACCEPTED_WITH_MODIFICATIONS"] = "accepted_with_modifications";
+    /** A person declined, or ended the waiting work. */
+    HumanDecision_Outcome["REJECTED"] = "rejected";
+    /** Nobody answered before `expiresAt`. Written only by the expiry path, never by an answer. */
+    HumanDecision_Outcome["LAPSED"] = "lapsed";
+    /** The waiting work was withdrawn (a cancelled task, an aborted run) before anyone answered. */
+    HumanDecision_Outcome["WITHDRAWN"] = "withdrawn";
+    /**
+     * A person answered, but the authority the work was raised under no longer holds (a revoked
+     * membership, a disabled credential, a revoked delegation). The work did NOT run: approving an
+     * action nobody may now perform is not an approval of anything.
+     */
+    HumanDecision_Outcome["REQUESTER_AUTHORITY_LAPSED"] = "requester_authority_lapsed";
+})(HumanDecision_Outcome || (HumanDecision_Outcome = {}));
+/** @wildo_source:part:end saas.models.flows-actors.human-decision-vocabulary */
+/**
+ * The outcome an ANSWER produces. Pure; the system outcomes (LAPSED, WITHDRAWN,
+ * REQUESTER_AUTHORITY_LAPSED) are never derived from an answer and are written by their own paths.
+ *
+ * `modified` is the host's judgement that the approved values differ from the proposal — the host
+ * holds both, this layer does not.
+ */
+export function humanDecisionOutcomeOf(request, answer, options) {
+    const option = request.options.find((candidate) => candidate.ref === answer.optionRef);
+    if (!option) {
+        throw new HumanDecisionAnswerError(`Decision "${request.decisionId}" never offered "${answer.optionRef}". Offered: ${request.options.map((entry) => entry.ref).join(', ')}.`);
+    }
+    switch (option.intent) {
+        case HumanDecision_ResponseIntent.PROCEED_WITH_VALUES:
+            return options.modified ? HumanDecision_Outcome.ACCEPTED_WITH_MODIFICATIONS : HumanDecision_Outcome.ACCEPTED;
+        case HumanDecision_ResponseIntent.PROCEED_WITHOUT_VALUES:
+        case HumanDecision_ResponseIntent.ABORT:
+            return HumanDecision_Outcome.REJECTED;
+        default: {
+            const unmapped = option.intent;
+            throw new HumanDecisionAnswerError(`Response intent "${String(unmapped)}" has no outcome.`);
+        }
+    }
+}
+/**
+ * Which suspension mechanism holds a decision. Both describe it with the same request, route and
+ * requester; only how the waiting work resumes differs, so an audit row says which to look in.
+ */
+export var HumanDecision_Plane;
+(function (HumanDecision_Plane) {
+    /** A conversational turn paused on an approval-gated tool (`pausedApproval` on the execution row). */
+    HumanDecision_Plane["CONVERSATIONAL"] = "conversational";
+    /** An actor-system execution suspended on a person (`suspension` on the actor execution row). */
+    HumanDecision_Plane["ACTOR_SYSTEM"] = "actor_system";
+    /**
+     * A client organization's approval of one expert a service firm assigned to it (#1612). The waiting work is the
+     * firm's ASSIGNMENT (`serviceEngagementAssignments`, status `PENDING_CLIENT_APPROVAL`), which holds the decision id
+     * and is settled by a compare-and-swap on it; the route is always the client's administrator ROLE, derived from the
+     * row rather than stored beside it. No agent is involved, so audit rows name the assignment as `executionId`.
+     */
+    HumanDecision_Plane["SERVICE_PROVIDER_EXPERT_ADMISSION"] = "service_provider_expert_admission";
+})(HumanDecision_Plane || (HumanDecision_Plane = {}));
+/** @wildo_source:part:start saas.models.flows-actors.human-decision-vocabulary facet:layer:shared facet:family:flows-actors facet:audience:app-developer */
+/** Who a pending decision is routed to. */
+export var HumanDecision_RouteKind;
+(function (HumanDecision_RouteKind) {
+    /** The person whose turn raised it. Cannot be reassigned, claimed or escalated. */
+    HumanDecision_RouteKind["OWNER"] = "owner";
+    /** One named person, who must hold the route's eligible role. Set by a declared resolver, a claim, a reassignment or an escalation. */
+    HumanDecision_RouteKind["ASSIGNEE"] = "assignee";
+    /** Anyone holding the eligible role in the decision's organization (or in a unit containing the decision's unit). */
+    HumanDecision_RouteKind["ROLE"] = "role";
+})(HumanDecision_RouteKind || (HumanDecision_RouteKind = {}));
+/** @wildo_source:part:end saas.models.flows-actors.human-decision-vocabulary */
+/** What kind of principal the waiting work was raised under — the authority it resumes under. */
+export var HumanDecision_RequesterKind;
+(function (HumanDecision_RequesterKind) {
+    /** A person, first-party. */
+    HumanDecision_RequesterKind["USER"] = "user";
+    /** A background principal (#1611's autonomous entry point). Never routed to OWNER: a machine answers nothing. */
+    HumanDecision_RequesterKind["MACHINE"] = "machine";
+    /** A person acting through an external OAuth client they delegated to. Resumes only while the delegation holds. */
+    HumanDecision_RequesterKind["DELEGATED_CLIENT"] = "delegated_client";
+})(HumanDecision_RequesterKind || (HumanDecision_RequesterKind = {}));
+/** What a person is attempting to do to a pending decision. */
+export var HumanDecision_Act;
+(function (HumanDecision_Act) {
+    HumanDecision_Act["ANSWER"] = "answer";
+    /** Move it to someone else. An answerer may, and so may a holder of the org-admin anchor role (supervisor takeover). */
+    HumanDecision_Act["REASSIGN"] = "reassign";
+    /** Take a ROLE-routed decision for yourself. */
+    HumanDecision_Act["CLAIM"] = "claim";
+    /** Give a claimed decision back to its role. */
+    HumanDecision_Act["UNCLAIM"] = "unclaim";
+    /** Move it up — to the gate's declared `escalateTo`, or a target the escalator names. Never a denial. */
+    HumanDecision_Act["ESCALATE"] = "escalate";
+    /**
+     * Stop the decision's CLAIM and DECISION clocks while the reviewer waits on something outside their
+     * control, naming one of the gate's declared pause states (#1628). Never stops the lapse: a paused
+     * decision still ends LAPSED when its window closes.
+     */
+    HumanDecision_Act["PAUSE_CLOCK"] = "pause_clock";
+    /** Restart the CLAIM and DECISION clocks; the paused time is added to both deadlines. */
+    HumanDecision_Act["RESUME_CLOCK"] = "resume_clock";
+})(HumanDecision_Act || (HumanDecision_Act = {}));
+//===============================================================
+//  Deadlines and escalation (#1628)
+//
+//  A pending decision has three clocks. Two are SERVICE TARGETS — CLAIM (someone should take it) and
+//  DECISION (someone should settle it) — whose breach fires reminders or a reassignment and changes
+//  nothing else. The third is the LAPSE, the hard stop, which ends the decision LAPSED. Practice
+//  converges on exactly this split: WS-HumanTask 1.1 §4.9 separates start and completion deadlines from
+//  expiration, and on a timeout "The state of the task is not changed."
+//  spec-cite: OASIS WS-HumanTask 1.1 (cs-01) §4.9 "Elements for Handling Timeouts and Escalations", fetched 2026-09-27 from https://docs.oasis-open.org/bpel4people/ws-humantask-1.1-spec-cs-01.html
+//===============================================================
+/** @wildo_source:part:start saas.models.flows-actors.review-deadline-vocabulary facet:layer:shared facet:family:flows-actors facet:audience:app-developer */
+/**
+ * The two service-target clocks of a pending decision. Neither ever ends it: missing one notifies
+ * people, or moves the decision, and the decision stays exactly as answerable as it was.
+ */
+export var ReviewDeadlineKind;
+(function (ReviewDeadlineKind) {
+    /**
+     * By when someone should have TAKEN the decision. Met by a claim or by an answer. An ASSIGNEE or
+     * OWNER route has no claim act, so there it is met only by the answer and acts as a first reminder:
+     * being assigned a task is not the same as having started it (WS-HumanTask's start deadline).
+     */
+    ReviewDeadlineKind["CLAIM"] = "claim";
+    /** By when someone should have ANSWERED it. Always earlier than the lapse. */
+    ReviewDeadlineKind["DECISION"] = "decision";
+})(ReviewDeadlineKind || (ReviewDeadlineKind = {}));
+/**
+ * The finite points at which a decision's deadlines fire. Each fires AT MOST ONCE per decision, across
+ * every host running the sweep: its own marker is written by a compare-and-swap, and only the writer
+ * that won runs the stage's actions.
+ */
+export var ReviewDeadlineStage;
+(function (ReviewDeadlineStage) {
+    /** Before the CLAIM deadline, by the gate's `claim.warnBefore`. Armed only when that is declared. */
+    ReviewDeadlineStage["CLAIM_WARNING"] = "claim_warning";
+    /** The CLAIM deadline passed with nobody having taken the decision. */
+    ReviewDeadlineStage["CLAIM_MISSED"] = "claim_missed";
+    /** Before the DECISION deadline, by the gate's `decision.warnBefore`. Armed only when that is declared. */
+    ReviewDeadlineStage["DECISION_WARNING"] = "decision_warning";
+    /** The DECISION deadline passed with nobody having answered. */
+    ReviewDeadlineStage["DECISION_MISSED"] = "decision_missed";
+})(ReviewDeadlineStage || (ReviewDeadlineStage = {}));
+/**
+ * What a stage does when it fires — the two escalation actions WS-HumanTask defines, and nothing
+ * else. There is no action that answers: a deadline can never approve, and never reject.
+ */
+export var ReviewEscalationActionKind;
+(function (ReviewEscalationActionKind) {
+    /** Tell the people who may answer it (and, at a DECISION stage, the gate's owner) that it is waiting. */
+    ReviewEscalationActionKind["NOTIFY"] = "notify";
+    /**
+     * Move the decision to the rule's declared target, who must be able to answer it. Opt-in per gate and
+     * never inferred; a target that cannot be resolved or may not answer falls back to NOTIFY, recorded.
+     */
+    ReviewEscalationActionKind["REASSIGN"] = "reassign";
+})(ReviewEscalationActionKind || (ReviewEscalationActionKind = {}));
+/** How a service-target deadline counts time. The lapse always counts ELAPSED time. */
+export var ReviewClockBasis;
+(function (ReviewClockBasis) {
+    /** Wall-clock time, 24/7. The default. */
+    ReviewClockBasis["ELAPSED"] = "elapsed";
+    /**
+     * Only the working hours of the application's declared `reviewCalendar`. A gate asking for it in an
+     * application that declares no calendar is refused at startup, never silently treated as ELAPSED.
+     */
+    ReviewClockBasis["CALENDAR"] = "calendar";
+})(ReviewClockBasis || (ReviewClockBasis = {}));
+/** Whether a service-target deadline was met, recorded on the decision's RESOLVED event. */
+export var ReviewDeadlineOutcome;
+(function (ReviewDeadlineOutcome) {
+    ReviewDeadlineOutcome["MET"] = "met";
+    ReviewDeadlineOutcome["MISSED"] = "missed";
+})(ReviewDeadlineOutcome || (ReviewDeadlineOutcome = {}));
+/**
+ * Who changed a decision's route. Carried on `HUMAN_DECISION_REASSIGNED`, so a reassignment an
+ * escalation rule made is never read as one a person chose.
+ */
+export var HumanDecision_RouteChangeTrigger;
+(function (HumanDecision_RouteChangeTrigger) {
+    /** A person reassigned it (an answerer handing it over, or a supervisor taking it over). */
+    HumanDecision_RouteChangeTrigger["PERSON"] = "person";
+    /** A deadline stage's REASSIGN rule moved it. The actor is the application. */
+    HumanDecision_RouteChangeTrigger["ESCALATION_RULE"] = "escalation_rule";
+})(HumanDecision_RouteChangeTrigger || (HumanDecision_RouteChangeTrigger = {}));
+/** @wildo_source:part:end saas.models.flows-actors.review-deadline-vocabulary */
+/** Why an act was refused. Recorded on the `HUMAN_DECISION_ANSWER_REFUSED` event, so it is a closed vocabulary. */
+export var HumanDecision_RefusalReason;
+(function (HumanDecision_RefusalReason) {
+    /** Only a signed-in person may act on a decision; a machine, a public caller or the system may not. */
+    HumanDecision_RefusalReason["NOT_A_USER_PRINCIPAL"] = "not_a_user_principal";
+    /** OWNER route: the actor is not the person whose turn raised it. */
+    HumanDecision_RefusalReason["NOT_THE_REQUESTER"] = "not_the_requester";
+    /** ASSIGNEE route: the actor is not the assignee. */
+    HumanDecision_RefusalReason["NOT_THE_ASSIGNEE"] = "not_the_assignee";
+    /** The actor does not hold the eligible role in the decision's organization or unit. */
+    HumanDecision_RefusalReason["ELIGIBLE_ROLE_NOT_HELD"] = "eligible_role_not_held";
+    /** Separation of duties: under a non-OWNER route, the requester may never act on their own decision. */
+    HumanDecision_RefusalReason["REQUESTER_MAY_NOT_ACT"] = "requester_may_not_act";
+    /** An OWNER route is fixed: it cannot be reassigned, claimed, unclaimed or escalated. */
+    HumanDecision_RefusalReason["OWNER_ROUTE_IS_FIXED"] = "owner_route_is_fixed";
+    /** CLAIM on a decision that is not an unclaimed ROLE route. */
+    HumanDecision_RefusalReason["NOT_CLAIMABLE"] = "not_claimable";
+    /** UNCLAIM on a decision nobody claimed from a role. */
+    HumanDecision_RefusalReason["NOT_CLAIMED"] = "not_claimed";
+    /** The route names no organization, so no role can be matched. The pause should have been refused. */
+    HumanDecision_RefusalReason["ROUTE_HAS_NO_ORGANIZATION"] = "route_has_no_organization";
+    /** A MACHINE requester on an OWNER route: nobody can answer it. The pause should have been refused. */
+    HumanDecision_RefusalReason["NOBODY_CAN_ANSWER"] = "nobody_can_answer";
+    /** An act this build does not know — a stale client. Refused, never guessed. */
+    HumanDecision_RefusalReason["UNKNOWN_ACT"] = "unknown_act";
+    /**
+     * A reassignment named nobody, or an escalation found no target: the gate declares no `escalateTo` and
+     * the escalator named none. A move is never a denial, so a move with nowhere to go leaves the decision
+     * exactly where it was.
+     */
+    HumanDecision_RefusalReason["NO_TARGET"] = "no_target";
+    /** PAUSE_CLOCK on a decision whose clocks are already paused. */
+    HumanDecision_RefusalReason["CLOCK_ALREADY_PAUSED"] = "clock_already_paused";
+    /** RESUME_CLOCK on a decision whose clocks are running. */
+    HumanDecision_RefusalReason["CLOCK_NOT_PAUSED"] = "clock_not_paused";
+    /** PAUSE_CLOCK naming a pause state the gate does not declare. */
+    HumanDecision_RefusalReason["PAUSE_STATE_NOT_DECLARED"] = "pause_state_not_declared";
+    /**
+     * An act this decision's plane does not offer. An expert-admission approval (#1612) is routed to the client's
+     * administrators as a ROLE and never to a named person, so it cannot be claimed, reassigned or escalated, and it
+     * arms no clocks to pause.
+     */
+    HumanDecision_RefusalReason["ACT_NOT_OFFERED"] = "act_not_offered";
+})(HumanDecision_RefusalReason || (HumanDecision_RefusalReason = {}));
+/**
+ * Who may settle a pending decision. Stored on the row that holds the resume compare-and-swap, never
+ * beside it (#1360: a second store lets a reassignment and an answer both win).
+ */
+export const HumanDecision_RouteSchema = z.object({
+    kind: z.enum(HumanDecision_RouteKind),
+    /**
+     * The role every holder must meet — the floor a reassignment, a claim or an escalation target must
+     * also meet. Required for ASSIGNEE and ROLE; meaningless for OWNER.
+     */
+    eligibleRole: z.string().min(1).optional(),
+    /** The organization the role is matched in. Required for ASSIGNEE and ROLE. */
+    organizationId: z.string().min(1).optional(),
+    /** When present, a unit-scoped holder matches only for a unit containing this one. When absent, only org-wide holders match. */
+    organizationUnitId: z.string().min(1).optional(),
+    /** ASSIGNEE only: the one person who may answer. */
+    assigneeUserId: z.string().min(1).optional(),
+    /** Set when an ASSIGNEE route came from CLAIMING a ROLE route; UNCLAIM restores ROLE. */
+    claimedAt: z.string().min(1).optional(),
+});
+/** The authority the waiting work was raised under, and resumes under. */
+export const HumanDecision_RequesterSchema = z.object({
+    kind: z.enum(HumanDecision_RequesterKind),
+    /** The user id for USER and DELEGATED_CLIENT; the credential id for MACHINE. */
+    ref: z.string().min(1),
+    /** DELEGATED_CLIENT only: the external client the person delegated to. */
+    clientId: z.string().min(1).optional(),
+});
+/**
+ * How a decision ENDED, written in the same statement that ends the wait (#1594 I4) — so a crash after
+ * that statement still leaves who decided what. The conversational plane spreads these facts over its
+ * own columns (`decidedByUserId`, `decisionOutcome`…); the actor plane carries this object on the status
+ * change that took the run out of waiting.
+ */
+export const HumanDecision_ResolutionSchema = z.object({
+    decisionRef: z.string().min(1),
+    outcome: z.enum(HumanDecision_Outcome),
+    /** The person who decided. Absent when nobody did — a lapse, or a withdrawal by the system. */
+    decidedByUserId: z.string().min(1).optional(),
+    decidedAt: z.iso.datetime(),
+});
+/**
+ * Whether the predicate admitted the act. A named discriminant rather than an `allowed` boolean: the
+ * backend packages compile with `strict: false`, where a boolean-literal discriminant narrows nothing,
+ * so `if (!verdict.allowed) verdict.reason` would not type-check at the doors that need the reason.
+ */
+export var HumanDecision_VerdictKind;
+(function (HumanDecision_VerdictKind) {
+    HumanDecision_VerdictKind["ALLOWED"] = "allowed";
+    HumanDecision_VerdictKind["REFUSED"] = "refused";
+})(HumanDecision_VerdictKind || (HumanDecision_VerdictKind = {}));
+const ALLOWED = Object.freeze({ kind: HumanDecision_VerdictKind.ALLOWED });
+const refuse = (reason) => ({ kind: HumanDecision_VerdictKind.REFUSED, reason });
+/** Is the actor the requester, as a person? A MACHINE requester is never a person. */
+function actorIsRequester(actor, requester) {
+    return requester.kind !== HumanDecision_RequesterKind.MACHINE && actor.userId === requester.ref;
+}
+/** Holds the eligible role where the route is matched: org-wide, or unit-scoped for a unit containing the decision's unit. */
+function holdsEligibleRole(route, roleFacts) {
+    if (roleFacts.holdsEligibleRoleOrgWide)
+        return true;
+    // A decision with no unit admits only org-wide holders: a unit-scoped role says nothing about work
+    // raised outside every unit.
+    return route.organizationUnitId !== undefined && roleFacts.eligibleRoleCoveredUnitIds.includes(route.organizationUnitId);
+}
+/**
+ * May this person perform this act on this pending decision?
+ *
+ * The ONE authorization predicate for pending decisions: every door — the WebSocket answer, the REST
+ * verbs, the listing re-check, the companion's actor-plane doors, a reassignment TARGET's eligibility
+ * (I8, asked with `act: ANSWER`) — calls this and nothing else. Pure: role facts arrive pre-resolved,
+ * so it can be pinned as a truth table and cannot drift between doors.
+ *
+ * It answers WHETHER the person may act. It never lends them anything: the waiting work resumes under
+ * the REQUESTER's current authority, rebuilt at resume, so a reviewer's wider rights never reach the
+ * requester's agent.
+ */
+export function authorizeHumanDecisionActor(input) {
+    const { actor, roleFacts, route, requester, act } = input;
+    if (actor.executionType !== ExecutionContext_ExecutionType.USER_REQUEST || !actor.userId) {
+        return refuse(HumanDecision_RefusalReason.NOT_A_USER_PRINCIPAL);
+    }
+    if (route.kind === HumanDecision_RouteKind.OWNER) {
+        // Pausing the clocks is admitted exactly as answering is (#1628): it moves nothing and nobody.
+        const answerLike = act === HumanDecision_Act.ANSWER || act === HumanDecision_Act.PAUSE_CLOCK || act === HumanDecision_Act.RESUME_CLOCK;
+        if (!answerLike)
+            return refuse(HumanDecision_RefusalReason.OWNER_ROUTE_IS_FIXED);
+        if (requester.kind === HumanDecision_RequesterKind.MACHINE)
+            return refuse(HumanDecision_RefusalReason.NOBODY_CAN_ANSWER);
+        return actorIsRequester(actor, requester) ? ALLOWED : refuse(HumanDecision_RefusalReason.NOT_THE_REQUESTER);
+    }
+    // assurance-control: WILDO.ACCESS.SEGREGATION_OF_DUTIES — the person or principal whose turn raised a decision can never answer it under a non-OWNER route.
+    // Every act, not only ANSWER: a requester who could reassign or escalate their own decision could
+    // choose who reviews them, which defeats the separation just as surely.
+    if (actorIsRequester(actor, requester))
+        return refuse(HumanDecision_RefusalReason.REQUESTER_MAY_NOT_ACT);
+    if (!route.organizationId)
+        return refuse(HumanDecision_RefusalReason.ROUTE_HAS_NO_ORGANIZATION);
+    const mayAnswer = () => {
+        if (route.kind === HumanDecision_RouteKind.ASSIGNEE && actor.userId !== route.assigneeUserId) {
+            return refuse(HumanDecision_RefusalReason.NOT_THE_ASSIGNEE);
+        }
+        // The eligibility floor holds for the assignee too, re-checked at the moment they act: a role lost
+        // after the assignment is a role no longer held.
+        return holdsEligibleRole(route, roleFacts) ? ALLOWED : refuse(HumanDecision_RefusalReason.ELIGIBLE_ROLE_NOT_HELD);
+    };
+    switch (act) {
+        case HumanDecision_Act.ANSWER:
+        // #1628: whoever may answer may stop and restart the clocks while they wait on something outside their
+        // control. It changes no route and no outcome, so it needs nothing beyond the right to answer.
+        case HumanDecision_Act.PAUSE_CLOCK:
+        case HumanDecision_Act.RESUME_CLOCK:
+            return mayAnswer();
+        case HumanDecision_Act.REASSIGN:
+        case HumanDecision_Act.ESCALATE: {
+            const answer = mayAnswer();
+            return answer.kind === HumanDecision_VerdictKind.ALLOWED || roleFacts.holdsOrgAdminAnchor ? ALLOWED : answer;
+        }
+        case HumanDecision_Act.CLAIM:
+            if (route.kind !== HumanDecision_RouteKind.ROLE)
+                return refuse(HumanDecision_RefusalReason.NOT_CLAIMABLE);
+            return holdsEligibleRole(route, roleFacts) ? ALLOWED : refuse(HumanDecision_RefusalReason.ELIGIBLE_ROLE_NOT_HELD);
+        case HumanDecision_Act.UNCLAIM:
+            if (route.kind !== HumanDecision_RouteKind.ASSIGNEE || !route.claimedAt)
+                return refuse(HumanDecision_RefusalReason.NOT_CLAIMED);
+            return actor.userId === route.assigneeUserId ? ALLOWED : refuse(HumanDecision_RefusalReason.NOT_THE_ASSIGNEE);
+        default: {
+            // A new act is a compile error here; at run time an unknown value (a stale client) is refused.
+            const unmapped = act;
+            void unmapped;
+            return refuse(HumanDecision_RefusalReason.UNKNOWN_ACT);
+        }
+    }
+}
+/**
+ * What an act on a pending decision came to, as every door reports it (#1594 D6).
+ *
+ * One vocabulary for the WebSocket answer, the REST verbs and any future door, so a client branches on a
+ * name rather than on an HTTP status that means different things on different routes.
+ */
+export var HumanDecision_ActOutcomeKind;
+(function (HumanDecision_ActOutcomeKind) {
+    /** The act took effect: the decision was answered, or moved. */
+    HumanDecision_ActOutcomeKind["APPLIED"] = "applied";
+    /**
+     * Nothing this person may act on. Deliberately ONE outcome for a decision that does not exist, one
+     * already settled, and one whose route does not admit them: telling those apart would disclose that a
+     * decision exists to someone it was not routed to.
+     */
+    HumanDecision_ActOutcomeKind["NOT_ACTIONABLE"] = "not_actionable";
+    /** The decision's window had closed; it is now ended LAPSED. */
+    HumanDecision_ActOutcomeKind["LAPSED"] = "lapsed";
+    /** The requester no longer holds the authority the work was raised under; it is ended and nothing ran. */
+    HumanDecision_ActOutcomeKind["REQUESTER_AUTHORITY_LAPSED"] = "requester_authority_lapsed";
+    /** Edited arguments the tool's own schema refuses. The decision still stands and can be answered. */
+    HumanDecision_ActOutcomeKind["MODIFICATION_REJECTED"] = "modification_rejected";
+    /**
+     * A reason code the application does not declare (`agentWorkReview.reasonCodes`, #1599). Refused before anything
+     * moves, so the decision still stands and can be answered with a declared code, or with none.
+     */
+    HumanDecision_ActOutcomeKind["REASON_CODE_REJECTED"] = "reason_code_rejected";
+    /** The requester has not granted a purpose the resumed turn needs. The decision still stands. */
+    HumanDecision_ActOutcomeKind["CONSENT_REQUIRED"] = "consent_required";
+    /** The person a move named may not answer this decision (I8). The decision stays where it was. */
+    HumanDecision_ActOutcomeKind["TARGET_REFUSED"] = "target_refused";
+    /**
+     * Another answer or move landed first, so this one matched nothing. Only ever returned to someone the
+     * route admitted, who therefore already knows the decision exists.
+     */
+    HumanDecision_ActOutcomeKind["SUPERSEDED"] = "superseded";
+})(HumanDecision_ActOutcomeKind || (HumanDecision_ActOutcomeKind = {}));
+/**
+ * The body of `POST /flows-actors/decisions/:decisionRef/:act`. Which fields mean anything depends on the
+ * act: `answer` (or `approved`) and `modifiedToolArgs` answer, `targetUserId` names who a reassignment or escalation goes
+ * to, and `reason` is the person's own words — sent to the model on an answer, never written to the trail.
+ */
+export const HumanDecision_ActRequestSchema = z.object({
+    /**
+     * ANSWER, in the one shape every decision is answered in (#1594 D12): the option chosen, and a value per
+     * field. Refused when it names another decision or an option this one never offered.
+     */
+    answer: HumanDecision_AnswerSchema.optional(),
+    /** ANSWER, for a tool approval: `true` approves, `false` denies. Ignored when `answer` is present. */
+    approved: z.boolean().optional(),
+    reason: z.string().max(4000).optional(),
+    /** ANSWER: a reason code of the application's declared vocabulary (#1599), recorded on the agent-work decision. */
+    reasonCode: AgentWorkReasonCodeSchema.optional(),
+    modifiedToolArgs: z.record(z.string(), z.unknown()).optional(),
+    targetUserId: z.string().min(1).optional(),
+    /** PAUSE_CLOCK: which of the gate's declared pause states the reviewer is waiting in (#1628). */
+    pauseStateRef: z.string().trim().min(1).optional(),
+});
+//# sourceMappingURL=human-decision.shared.schemas.js.map