@wildo-ai/saas-models 1.1.5 → 1.1.6

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

@@ -1,4 +1,6 @@
+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
 //
@@ -136,6 +138,16 @@ export const HumanDecision_FieldSchema = z.object({
         });
     }
 });
+/**
+ * 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. */
@@ -146,6 +158,41 @@ export const HumanDecision_ResponseOptionSchema = z.object({
     /** 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.
  *
@@ -179,6 +226,16 @@ export const HumanDecision_RequestSchema = z.object({
      * 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({
@@ -249,4 +306,449 @@ export function resolveHumanDecisionAnswer(request, answer) {
     }
     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