@xema/omni-protocol 0.1.94 → 0.1.96

package/dist/index.d.ts

@@ -1217,9 +1217,9 @@ export type DialResult = {
     status: "failed";
     failure: ProtocolFailure;
 };
-export type BreakApproval = "not-requested"
+export type BreakStatus = "not-requested"
 /** Somebody has to decide. The agent is waiting on a person. */
- | "awaiting-decision"
+ | "awaiting-approval"
 /** Granted, and a promise to honour a later commit. */
  | "granted"
 /** Granted and begins when the current task ends. Nobody needs to act. */
@@ -1249,28 +1249,19 @@ export interface BreakReason {
     alwaysAvailable?: true;
 }
 export interface BreakRequest {
+    /** Optional explanatory text. Omit when no explanation is needed; separate from reasonId. */
     reason?: string;
     /** The chosen `BreakReason.id`, where the provider publishes codes. */
     reasonId?: string;
 }
-/**
- * A break forced on the agent rather than requested by them.
- *
- * `by` is required in both arms. Who put somebody off the floor survives whether or not the
- * break ends on a clock -- a forced break with no origin is a state the agent cannot reason
- * about, and one that ends on a condition is still somebody's decision.
- */
+/** A break forced on the agent; the agent must explicitly resume when ready. */
 export type ForcedBreak = {
     by: UserId;
-    endsAutomatically: true;
-    endsAt: IsoTimestamp;
-} | {
-    by: UserId;
-    endsAutomatically: false;
-    endsAt?: never;
+    /** Optional expected time on break, in milliseconds from actual start. Advisory only. */
+    expectedDurationMs?: number;
 };
 export interface BreakState {
-    approval: BreakApproval;
+    status: BreakStatus;
     /** Whether the agent may ask at all. Distinct from the fate of a request already made. */
     canRequestBreak: boolean;
     /** Shown when `canRequestBreak` is false, such as "Busy hours". */
@@ -1321,7 +1312,7 @@ export interface TeamMember {
     /** Omitted rather than invented: Omni renders it as a duration. */
     since?: IsoTimestamp;
     /** A request in flight or a grant not yet in effect. `not-requested` is absence, and `on-break` is `availability: "on-break"`. */
-    break?: Extract<BreakApproval, "awaiting-decision" | "granted" | "starting-after-task">;
+    break?: Extract<BreakStatus, "awaiting-approval" | "granted" | "starting-after-task">;
 }
 /** A member asking this lead to join their call. */
 export interface LeadRequest {
@@ -1398,13 +1389,16 @@ export type TeamBreakCommand = {
     type: "set-break-policy";
     policy: "approval-required" | "automatically-approved" | "requests-suspended";
 }
-/** `reasonId` names a published `BreakReason.id`, required whenever the provider publishes reasons: the member's forced break carries it as `activeReasonId`. */
+/** `reason` text is optional. `reasonId` selects a published `BreakReason.id`, required when reasons are published; the forced break carries it as `activeReasonId`. */
  | {
     type: "force-break";
     memberId: UserId;
     reasonId?: string;
     reason?: string;
-} | {
+    expectedDurationMs?: number;
+}
+/** Clears forced metadata only; preserves the committed break until the agent explicitly resumes. */
+ | {
     type: "end-forced-break";
     memberId: UserId;
 };
@@ -1693,7 +1687,7 @@ export interface Connection<C extends Channel = Channel> {
     execute(request: TaskCommandRequest<C>): Promise<TaskCommandResult>;
     disconnect(): Promise<void>;
     /** Required of any adapter publishing a `UserId` -- on a forced break, a team member list, or history. */
-    describeUsers?(ids: UserId[]): Promise<User[]>;
+    getUserDetails?(ids: UserId[]): Promise<User[]>;
     /** Required when the manifest declares `idleCapabilities.dial`. */
     dial?(request: DialRequest): Promise<DialResult>;
     /**

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostMute, type LoginStore, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type TaskCompletion, type BreakStatus, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostMute, type LoginStore, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
 import { type ProtocolViolation } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
 /**
@@ -135,11 +135,11 @@ export declare function assertReconnectWithMissedAssignments<C extends Channel>(
  * pending request nobody is coming to decide is worse than none. So the scenario is a request
  * that goes back to not-requested, and a later one that is granted.
  *
- * A request shows as `awaiting-decision` where a person decides, and as `granted` at once where
+ * A request shows as `awaiting-approval` where a person decides, and as `granted` at once where
  * the provider decides alone; either is the request being made, and the rule is the same for
  * both.
  */
-export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
+export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakStatus[]): void;
 /**
  * The event kinds a snapshot restates, and so supersedes when delivered while it is read. Every
  * other kind reports a transaction no snapshot carries, and a host applies it after the snapshot.
@@ -242,7 +242,7 @@ export interface BreakCandidate {
 export declare function assertBreakAttemptProviders(candidates: readonly BreakCandidate[], asked: readonly string[]): void;
 /** One published moment of a break asked for on a task: the approval, and how many tasks were outstanding. */
 export interface BreakOnTaskStep {
-    approval: BreakApproval;
+    approval: BreakStatus;
     outstanding: number;
 }
 /**

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateBreakTransition, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateDescribedUsers, observeRules, ruleEvaluated, validateHostMute, validateHostRecording, validateLoginStore, validateInteractionReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateBreakTransition, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateUserDetails, observeRules, ruleEvaluated, validateHostMute, validateHostRecording, validateLoginStore, validateInteractionReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
  * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
@@ -356,7 +356,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             violations.push(...undeterminedTasks(eventTasks(envelope), "event"));
             lockedPartySeen ||= eventTasks(envelope).some(locksParty);
             if (eventNamesUsers(envelope))
-                requireMethod(live, "describeUsers", "an event publishes a UserId");
+                requireMethod(live, "getUserDetails", "an event publishes a UserId");
             // Work is pulled, never pushed: an offer before the host stated capacity is an allocation
             // against nothing, and an offer beyond the count is one too many -- unless the task is the
             // host's own dial arriving, which counts against nothing.
@@ -458,22 +458,22 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             violations.push(...undeterminedTasks(tasks, `${path}.tasks`));
             lockedPartySeen ||= tasks.some(locksParty);
             if (publishesUserIds(read)) {
-                requireMethod(source, "describeUsers", "the snapshot publishes a UserId");
+                requireMethod(source, "getUserDetails", "the snapshot publishes a UserId");
                 // Required by presence is not enough: the names the snapshot published are looked up, and what
                 // comes back is held to the shape -- an empty answer to a team member list of colleagues is named.
                 const named = userIdsIn(read);
-                if (typeof source.describeUsers === "function" && named.length > 0) {
+                if (typeof source.getUserDetails === "function" && named.length > 0) {
                     let described;
                     try {
-                        described = await source.describeUsers(named);
-                        violations.push(...validateDescribedUsers(described, named, "connection.describeUsers"));
+                        described = await source.getUserDetails(named);
+                        violations.push(...validateUserDetails(described, named, "connection.getUserDetails"));
                         if (Array.isArray(described) && described.length === 0) {
-                            violations.push({ rule: "connection.describeUsers.empty", path: "connection.describeUsers",
+                            violations.push({ rule: "connection.getUserDetails.empty", path: "connection.getUserDetails",
                                 message: `asked about ${named.join(", ")}, whom the snapshot itself named, the provider described nobody` });
                         }
                     }
                     catch (error) {
-                        violations.push({ rule: "connection.describeUsers.rejected", path: "connection.describeUsers", message: `describeUsers rejected rather than answered: ${String(error)}` });
+                        violations.push({ rule: "connection.getUserDetails.rejected", path: "connection.getUserDetails", message: `getUserDetails rejected rather than answered: ${String(error)}` });
                     }
                 }
             }
@@ -532,7 +532,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         violations.push(...malformed);
         // The provider republishes the agent's day: once connected, the identity carries the zone the
         // host sent. That proves the round trip, not the store -- an echo passes it -- and the name
-        // says only what it tests; storage is proved by a colleague's zone arriving from describeUsers().
+        // says only what it tests; storage is proved by a colleague's zone arriving from getUserDetails().
         // A zone is judged by what it denotes: Asia/Kolkata and Asia/Calcutta are one zone, and a
         // provider that keeps the canonical name has kept the zone.
         if (isTimeZone(context.timeZone) && !sameTimeZone(current().identity.timeZone, context.timeZone)) {
@@ -938,12 +938,12 @@ export function assertReconnectWithMissedAssignments(before, reconnect, missedTa
  * pending request nobody is coming to decide is worse than none. So the scenario is a request
  * that goes back to not-requested, and a later one that is granted.
  *
- * A request shows as `awaiting-decision` where a person decides, and as `granted` at once where
+ * A request shows as `awaiting-approval` where a person decides, and as `granted` at once where
  * the provider decides alone; either is the request being made, and the rule is the same for
  * both.
  */
 export function assertDeniedAndRetriedBreak(approvals) {
-    const asked = approvals.findIndex(approval => approval === "awaiting-decision" || approval === "granted");
+    const asked = approvals.findIndex(approval => approval === "awaiting-approval" || approval === "granted");
     if (asked < 0)
         throw new Error("Break retry scenario requires an initial request");
     const refused = approvals.indexOf("not-requested", asked + 1);
@@ -1865,9 +1865,10 @@ async function driveOneCall(drive) {
     nothingLate();
     return found;
 }
-// A request goes not-requested -> awaiting-decision | granted; a commit goes granted ->
+// A request goes not-requested -> awaiting-approval | granted; a commit goes granted ->
 // starting-after-task | on-break; work ending goes starting-after-task -> on-break; a denial,
-// a cancel, an agent end or a lead end goes back to not-requested; a forced break arrives on-break
+// a cancel or an explicit agent end goes back to not-requested; a lead lifting forced status
+// preserves the committed break. A forced break arrives on-break
 // with `forced`. Nothing else is a move the guide describes.
 /** What a stream has said about the agent's break, and the moves it may not make. */
 export class BreakStream {
@@ -1994,7 +1995,7 @@ export function assertBreakAttemptProviders(candidates, asked) {
  * outstanding -- never beside a task, and never later than the step that has none.
  */
 export function assertBreakBeginsAfterTask(steps) {
-    const asked = steps.findIndex(step => step.approval === "awaiting-decision" || step.approval === "granted");
+    const asked = steps.findIndex(step => step.approval === "awaiting-approval" || step.approval === "granted");
     if (asked < 0)
         throw new Error("Break-on-task scenario requires a request");
     if ((steps[asked]?.outstanding ?? 0) < 1)

package/dist/validation.d.ts

@@ -150,11 +150,11 @@ export declare function sameTimeZone(a: unknown, b: unknown): boolean;
 /** The zone a host sends at connect: required, and an IANA name. */
 export declare function validateTimeZone(value: unknown, path?: string): ProtocolViolation[];
 /**
- * What `describeUsers(ids)` answered: an array of users, each one asked for, each a valid identity.
+ * What `getUserDetails(ids)` answered: an array of users, each one asked for, each a valid identity.
  * The provider may answer fewer than asked, which is what "unknown to it" looks like; it never
  * answers somebody nobody asked about.
  */
-export declare function validateDescribedUsers(users: unknown, asked: readonly string[], path?: string): ProtocolViolation[];
+export declare function validateUserDetails(users: unknown, asked: readonly string[], path?: string): ProtocolViolation[];
 /** What a login is validated against beyond its own shape. */
 export interface LoginValidationContext {
     /** The level ids in force, from the manifest. The defaults when absent. */

package/dist/validation.js

@@ -52,7 +52,7 @@ const AUTHENTICATION_STATUSES = membersOf({
     "signed-out": true, authenticating: true, authenticated: true, refreshing: true, expired: true,
 });
 const BREAK_APPROVALS = membersOf({
-    "not-requested": true, "awaiting-decision": true, granted: true, "starting-after-task": true, "on-break": true,
+    "not-requested": true, "awaiting-approval": true, granted: true, "starting-after-task": true, "on-break": true,
 });
 const TEAM_AVAILABILITIES = membersOf({
     ready: true, "on-task": true, "on-break": true, reserved: true, "signed-out": true,
@@ -80,7 +80,7 @@ const SNAPSHOT_REASONS = membersOf({
 });
 const SESSION_CAPABILITIES = membersOf({ breaks: true, team: true, preferences: true });
 const MEMBER_BREAKS = membersOf({
-    "awaiting-decision": true, granted: true, "starting-after-task": true,
+    "awaiting-approval": true, granted: true, "starting-after-task": true,
 });
 const OFFERABLE_PHASES = membersOf({
     pending: true,
@@ -1298,19 +1298,12 @@ function validateForcedBreak(value, path, into) {
         into.add("break.forced.shape", path, "a forced break must be an object");
         return;
     }
-    // `by` is required either way. Who put somebody off the floor survives whether or not the
-    // break ends on a clock -- a forced break with no origin is a state the agent cannot
-    // reason about.
     into.require(isUserId(value.by), "break.forced.by", `${path}.by`, "a forced break must say who forced it");
-    if (value.endsAutomatically === true) {
-        into.timestamp(value.endsAt, "break.forced.endsAt", `${path}.endsAt`);
-    }
-    else if (value.endsAutomatically === false) {
-        into.require(value.endsAt === undefined, "break.forced.endsAt.unexpected", `${path}.endsAt`, "a break that does not end automatically must not carry an end time");
-    }
-    else {
-        into.add("break.forced.endsAutomatically", `${path}.endsAutomatically`, "a forced break must say whether it ends automatically");
+    for (const field of ["endsAutomatically", "endsAt"]) {
+        into.require(!Object.hasOwn(value, field), "break.forced.manualResume", `${path}.${field}`, "automatic ending fields are unsupported; the agent must resume manually");
     }
+    if (value.expectedDurationMs !== undefined)
+        into.require(typeof value.expectedDurationMs === "number" && Number.isFinite(value.expectedDurationMs) && value.expectedDurationMs > 0, "break.forced.expectedDurationMs", `${path}.expectedDurationMs`, "expectedDurationMs must be a positive finite number of milliseconds");
 }
 /** Checks break status against the full currently retained task set, after a transaction. */
 export function validateBreakStatus(state, tasks, path = "snapshot") {
@@ -1329,11 +1322,11 @@ export function validateBreakStatus(state, tasks, path = "snapshot") {
     // no task is a break waiting on work that does not exist, and an empty list reading as "still
     // finishing" is the plausible nought.
     ruleEvaluated("break.starting-after-task.tasks");
-    if (isPlainObject(state) && state.approval === "starting-after-task"
+    if (isPlainObject(state) && state.status === "starting-after-task"
         && Array.isArray(tasks) && tasks.length === 0) {
-        into.add("break.starting-after-task.tasks", `${path}.break.approval`, "a break starting after the task waits on a task, and the snapshot carries none: with nothing outstanding the break is on-break");
+        into.add("break.starting-after-task.tasks", `${path}.break.status`, "a break starting after the task waits on a task, and the snapshot carries none: with nothing outstanding the break is on-break");
     }
-    if (isPlainObject(state) && state.approval === "on-break"
+    if (isPlainObject(state) && state.status === "on-break"
         && Array.isArray(tasks) && tasks.length > 0) {
         const listening = tasks.every((task) => isPlainObject(task) && task.listening !== undefined);
         if (!listening) {
@@ -1367,7 +1360,7 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
     const command = request.command;
     const allowed = {
         "decide-break-request": ["type", "memberId", "decision", "reason"], "set-break-policy": ["type", "policy"],
-        "force-break": ["type", "memberId", "reasonId", "reason"], "end-forced-break": ["type", "memberId"],
+        "force-break": ["type", "memberId", "reasonId", "reason", "expectedDurationMs"], "end-forced-break": ["type", "memberId"],
     };
     const fields = typeof command.type === "string" && Object.hasOwn(allowed, command.type) ? allowed[command.type] : undefined;
     if (!fields) {
@@ -1392,14 +1385,16 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
     into.require(isPlainObject(member) && command.memberId !== self, "team.break.command.member", path, "the target must be another member of the current authorized team member list");
     if (command.type === "decide-break-request") {
         into.require(command.decision === "granted" || command.decision === "denied", "team.break.command.decision", path, "decide granted or denied");
-        into.require(isPlainObject(member) && member.break === "awaiting-decision", "team.break.command.awaiting", path, "decide only a currently awaiting-decision request");
+        into.require(isPlainObject(member) && member.break === "awaiting-approval", "team.break.command.awaiting", path, "decide only a currently awaiting-approval request");
     }
     else {
         validateBreakState(context.memberBreak, `${path}.memberBreak`, into);
         const state = isPlainObject(context.memberBreak) ? context.memberBreak : {};
         if (command.type === "end-forced-break")
-            into.require(state.forced !== undefined && (state.approval === "on-break" || state.approval === "starting-after-task"), "team.break.command.endForcedBreak", path, "end a currently forced break");
+            into.require(state.forced !== undefined && (state.status === "on-break" || state.status === "starting-after-task"), "team.break.command.endForcedBreak", path, "lift a current forced-break restriction without resuming the agent");
         if (command.type === "force-break") {
+            if (command.expectedDurationMs !== undefined)
+                into.require(typeof command.expectedDurationMs === "number" && Number.isFinite(command.expectedDurationMs) && command.expectedDurationMs > 0, "team.break.command.expectedDurationMs", `${path}.expectedDurationMs`, "expectedDurationMs must be positive finite milliseconds; it never resumes the agent");
             if (command.reasonId !== undefined)
                 into.filled(command.reasonId, "team.break.command.reasonId", path, "reasonId must not be empty");
             const reasons = Array.isArray(state.reasons) ? state.reasons : [];
@@ -1431,9 +1426,9 @@ export function validateBreakCommand(method, request, state, context, path = "br
     }
     if (!isPlainObject(state) || into.violations.length)
         return into.violations;
-    const approval = state.approval;
+    const status = state.status;
     if (method === "requestBreak") {
-        into.require(approval === "not-requested", "break.command.request.pending", path, "a new request starts only from not-requested");
+        into.require(status === "not-requested", "break.command.request.pending", path, "a new request starts only from not-requested");
         if (!isPlainObject(request)) {
             into.add("break.request.shape", path, "requestBreak takes a request object");
             return into.violations;
@@ -1454,12 +1449,12 @@ export function validateBreakCommand(method, request, state, context, path = "br
     else {
         into.require(request === undefined, "break.command.arguments", path, "this break method takes no arguments");
         if (method === "commitBreak")
-            into.require(approval === "granted" || approval === "starting-after-task" || approval === "on-break", "break.command.commit.grant", path, "commit requires a grant; repeated committed state is idempotent");
+            into.require(status === "granted" || status === "starting-after-task" || status === "on-break", "break.command.commit.grant", path, "commit requires a grant; repeated committed state is idempotent");
         if (method === "cancelBreak")
-            into.require(approval === "awaiting-decision" || approval === "granted", "break.command.cancel.precommit", path, "cancel only a pre-commit request; a raced commit requires commit recovery");
+            into.require(status === "awaiting-approval" || status === "granted", "break.command.cancel.precommit", path, "cancel only a pre-commit request; a raced commit requires commit recovery");
         if (method === "endBreak") {
-            into.require(approval === "starting-after-task" || approval === "on-break", "break.command.end.started", path, "end a committed break, including a returning provider still finishing work");
-            into.require(state.forced === undefined, "break.command.end.forced", path, "an agent cannot end a forced break; an authorized lead ends it");
+            into.require(status === "starting-after-task" || status === "on-break", "break.command.end.started", path, "end a committed break, including a returning provider still finishing work");
+            // A forced break also ends only when the agent explicitly resumes.
         }
     }
     return into.violations;
@@ -1477,17 +1472,17 @@ export function validateBreakTransition(before, after, path = "break") {
     validateBreakState(after, `${path}.after`, into);
     if (into.violations.length || !isPlainObject(before) || !isPlainObject(after))
         return into.violations;
-    const from = before.approval;
-    const to = after.approval;
+    const from = before.status;
+    const to = after.status;
     const committed = to === "starting-after-task" || to === "on-break";
-    if (committed && (from === "not-requested" || from === "awaiting-decision") && after.forced === undefined) {
-        into.add("stream.breakState.commitBeforeGrant", `${path}.after.approval`, `${to} follows a commit, and a commit follows granted; the break stood at ${from}`);
+    if (committed && (from === "not-requested" || from === "awaiting-approval") && after.forced === undefined) {
+        into.add("stream.breakState.commitBeforeGrant", `${path}.after.status`, `${to} follows a commit, and a commit follows granted; the break stood at ${from}`);
     }
-    const backwards = (from === "on-break" && (to === "awaiting-decision" || to === "granted" || to === "starting-after-task")) ||
-        (from === "starting-after-task" && (to === "awaiting-decision" || to === "granted")) ||
-        (from === "granted" && to === "awaiting-decision");
+    const backwards = (from === "on-break" && (to === "awaiting-approval" || to === "granted" || to === "starting-after-task")) ||
+        (from === "starting-after-task" && (to === "awaiting-approval" || to === "granted")) ||
+        (from === "granted" && to === "awaiting-approval");
     if (backwards)
-        into.add("stream.breakState.backwards", `${path}.after.approval`, `a break does not go from ${from} back to ${to}; a new request passes through not-requested`);
+        into.add("stream.breakState.backwards", `${path}.after.status`, `a break does not go from ${from} back to ${to}; a new request passes through not-requested`);
     return into.violations;
 }
 function validateBreakState(value, path, into) {
@@ -1496,7 +1491,8 @@ function validateBreakState(value, path, into) {
         return;
     }
     into.require(!Object.hasOwn(value, "imposed"), "break.forced.renamed", `${path}.imposed`, "imposed was renamed to forced; use only forced");
-    into.oneOf(value.approval, BREAK_APPROVALS, "break.approval", `${path}.approval`);
+    into.require(!Object.hasOwn(value, "approval"), "break.status.renamed", `${path}.approval`, "BreakState.approval was renamed to status; use only status");
+    into.oneOf(value.status, BREAK_APPROVALS, "break.status", `${path}.status`);
     into.require(!Object.hasOwn(value, "mayAsk"), "break.canRequestBreak.renamed", `${path}.mayAsk`, "mayAsk was renamed to canRequestBreak; use only canRequestBreak");
     into.require(typeof value.canRequestBreak === "boolean", "break.canRequestBreak", `${path}.canRequestBreak`, "canRequestBreak says whether the agent may ask for a break: a boolean");
     into.require(!Object.hasOwn(value, "refusedReason"), "break.requestUnavailableReason.renamed", `${path}.refusedReason`, "refusedReason was renamed to requestUnavailableReason; use only requestUnavailableReason");
@@ -1517,14 +1513,14 @@ function validateBreakState(value, path, into) {
         into.filled(value.activeReasonId, "break.activeReasonId", `${path}.activeReasonId`, "activeReasonId must not be empty when present");
         // A break nobody is on has no reason. Reporting one beside `not-requested` describes a
         // break that is not happening.
-        into.require(value.approval !== "not-requested", "break.activeReasonId.approval", `${path}.activeReasonId`, "activeReasonId must be omitted when no break is requested or in effect");
+        into.require(value.status !== "not-requested", "break.activeReasonId.status", `${path}.activeReasonId`, "activeReasonId must be omitted when no break is requested or in effect");
     }
     if (value.forced !== undefined) {
         validateForcedBreak(value.forced, `${path}.forced`, into);
         // A forced break is a break somebody forced; beside `not-requested` there is no break.
         // A forced break is a break in progress or about to be: it travels with on-break or
         // starting-after-task and nothing else. Beside granted, the host would commit a break nobody asked for.
-        into.require(value.approval === "on-break" || value.approval === "starting-after-task", "break.forced.approval", `${path}.forced`, `a forced break is in effect or starting after the task; ${describeValue(value.approval)} says the agent asked, or that there is none`);
+        into.require(value.status === "on-break" || value.status === "starting-after-task", "break.forced.status", `${path}.forced`, `a forced break is in effect or starting after the task; ${describeValue(value.status)} says the agent asked, or that there is none`);
     }
     if (value.reasons === undefined)
         return;
@@ -1563,8 +1559,8 @@ function validateBreakState(value, path, into) {
     // forced one included, since the lead's force-break command named it. A break of no kind is a break whose
     // rules -- who may listen through it, whether it counts -- nobody can apply.
     ruleEvaluated("break.activeReasonId.required");
-    if (seen.size > 0 && (value.approval === "on-break" || value.approval === "starting-after-task")) {
-        into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${describeValue(value.approval)} on a provider that publishes reasons names the one it is on`);
+    if (seen.size > 0 && (value.status === "on-break" || value.status === "starting-after-task")) {
+        into.require(typeof value.activeReasonId === "string" && value.activeReasonId.length > 0, "break.activeReasonId.required", `${path}.activeReasonId`, `a break ${describeValue(value.status)} on a provider that publishes reasons names the one it is on`);
     }
 }
 export function validateTeamMembers(teamMembers, path = "team", context = {}) {
@@ -2653,21 +2649,21 @@ export function validateTimeZone(value, path = "context.timeZone") {
     return into.violations;
 }
 /**
- * What `describeUsers(ids)` answered: an array of users, each one asked for, each a valid identity.
+ * What `getUserDetails(ids)` answered: an array of users, each one asked for, each a valid identity.
  * The provider may answer fewer than asked, which is what "unknown to it" looks like; it never
  * answers somebody nobody asked about.
  */
-export function validateDescribedUsers(users, asked, path = "describeUsers") {
+export function validateUserDetails(users, asked, path = "getUserDetails") {
     const into = new Collector();
     if (!Array.isArray(users)) {
-        into.add("describeUsers.shape", path, "describeUsers answers an array of users, empty when it knows none of them");
+        into.add("getUserDetails.shape", path, "getUserDetails answers an array of users, empty when it knows none of them");
         return into.violations;
     }
     users.forEach((user, index) => {
         const at = `${path}[${index}]`;
-        validateUser(user, "describeUsers.user", at, into);
+        validateUser(user, "getUserDetails.user", at, into);
         if (isPlainObject(user) && typeof user.id === "string") {
-            into.require(asked.includes(user.id), "describeUsers.unasked", `${at}.id`, `${user.id} was not among the ids asked for`);
+            into.require(asked.includes(user.id), "getUserDetails.unasked", `${at}.id`, `${user.id} was not among the ids asked for`);
         }
     });
     return into.violations;