@xema/omni-protocol 0.1.91 → 0.1.93

package/dist/index.d.ts

@@ -236,7 +236,7 @@ export interface AuthenticationFailure {
 /** What a lead may do with their team. Declared by presence. */
 export interface TeamCapabilities {
     /**
-     * This lead may act on their team's breaks through `executeTeamBreak` -- place, release, decide,
+     * This lead may act on their team's breaks through `executeTeamBreak` -- force-break, end-forced-break, decide-break-request,
      * set policy -- as far as the provider supports; a command it lacks answers
      * `omni.capability-not-enabled`. Requires `executeTeamBreak`.
      */
@@ -1254,7 +1254,7 @@ export interface BreakRequest {
     reasonId?: string;
 }
 /**
- * A break placed on the agent rather than requested by them.
+ * 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
@@ -1390,7 +1390,7 @@ export interface TeamListenCommandRequest {
     command: TeamListenCommand;
 }
 export type TeamBreakCommand = {
-    type: "decide";
+    type: "decide-break-request";
     memberId: UserId;
     decision: "granted" | "denied";
     reason?: string;
@@ -1400,12 +1400,12 @@ export type TeamBreakCommand = {
 }
 /** `reasonId` names a published `BreakReason.id`, required whenever the provider publishes reasons: the member's forced break carries it as `activeReasonId`. */
  | {
-    type: "place";
+    type: "force-break";
     memberId: UserId;
     reasonId?: string;
     reason?: string;
 } | {
-    type: "release";
+    type: "end-forced-break";
     memberId: UserId;
 };
 export type TeamCommandResult = {

package/dist/testing.d.ts

@@ -202,7 +202,7 @@ export declare class BreakStream {
 /**
  * A break follows its requests. Given a provider's stream -- seeded with its initial snapshot,
  * either supplied separately or carried by a snapshot event -- every `break-state` moves the way the guide describes: a commit's states only
- * after a grant, never backwards, and a break placed on the agent arriving in effect with `forced`.
+ * after a grant, never backwards, and a break forced on the agent arriving in effect with `forced`.
  */
 export declare function assertBreakFollowsItsRequests(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
 /**

package/dist/testing.js

@@ -1867,7 +1867,7 @@ async function driveOneCall(drive) {
 }
 // A request goes not-requested -> awaiting-decision | granted; a commit goes granted ->
 // starting-after-task | in-effect; work ending goes starting-after-task -> in-effect; a denial,
-// a cancel, an end or a release goes back to not-requested; a placed break arrives in-effect
+// a cancel, an agent end or a lead end goes back to not-requested; a forced break arrives in-effect
 // 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 {
@@ -1914,7 +1914,7 @@ export class BreakStream {
 /**
  * A break follows its requests. Given a provider's stream -- seeded with its initial snapshot,
  * either supplied separately or carried by a snapshot event -- every `break-state` moves the way the guide describes: a commit's states only
- * after a grant, never backwards, and a break placed on the agent arriving in effect with `forced`.
+ * after a grant, never backwards, and a break forced on the agent arriving in effect with `forced`.
  */
 export function assertBreakFollowsItsRequests(envelopes, snapshot) {
     const stream = new BreakStream();

package/dist/validation.d.ts

@@ -51,7 +51,7 @@ export declare function validateTask(task: unknown, context: TaskValidationConte
 export declare function validateBreakStatus(state: unknown, tasks: unknown, path?: string): ProtocolViolation[];
 /**
  * Checks lead break dispatch using current authentication, transport, team member list (`team`) and,
- * for place/release, the target's full `memberBreak`. The provider must authorize the target
+ * for force-break/end-forced-break, the target's full `memberBreak`. The provider must authorize the target
  * and recheck the decision atomically; a team member list is not authority to act after it has changed.
  */
 export declare function validateTeamBreakCommand(request: unknown, context: unknown, path?: string): ProtocolViolation[];

package/dist/validation.js

@@ -1301,7 +1301,7 @@ function validateForcedBreak(value, path, into) {
     // `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 placed it");
+    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`);
     }
@@ -1350,7 +1350,7 @@ export function validateBreakStatus(state, tasks, path = "snapshot") {
 }
 /**
  * Checks lead break dispatch using current authentication, transport, team member list (`team`) and,
- * for place/release, the target's full `memberBreak`. The provider must authorize the target
+ * for force-break/end-forced-break, the target's full `memberBreak`. The provider must authorize the target
  * and recheck the decision atomically; a team member list is not authority to act after it has changed.
  */
 export function validateTeamBreakCommand(request, context, path = "teamBreakCommand") {
@@ -1366,8 +1366,8 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
     into.require(isPlainObject(caps.team) && caps.team.breakControl === true, "team.break.command.capability", path, "the login must declare team.breakControl");
     const command = request.command;
     const allowed = {
-        decide: ["type", "memberId", "decision", "reason"], policy: ["type", "policy"],
-        place: ["type", "memberId", "reasonId", "reason"], release: ["type", "memberId"],
+        "decide-break-request": ["type", "memberId", "decision", "reason"], policy: ["type", "policy"],
+        "force-break": ["type", "memberId", "reasonId", "reason"], "end-forced-break": ["type", "memberId"],
     };
     const fields = typeof command.type === "string" && Object.hasOwn(allowed, command.type) ? allowed[command.type] : undefined;
     if (!fields) {
@@ -1390,20 +1390,20 @@ export function validateTeamBreakCommand(request, context, path = "teamBreakComm
     const member = members.find((m) => isPlainObject(m) && m.id === command.memberId);
     const self = isPlainObject(auth.identity) ? auth.identity.id : undefined;
     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") {
+    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");
     }
     else {
         validateBreakState(context.memberBreak, `${path}.memberBreak`, into);
         const state = isPlainObject(context.memberBreak) ? context.memberBreak : {};
-        if (command.type === "release")
-            into.require(state.forced !== undefined && (state.approval === "in-effect" || state.approval === "starting-after-task"), "team.break.command.release", path, "release a currently forced break");
-        if (command.type === "place") {
+        if (command.type === "end-forced-break")
+            into.require(state.forced !== undefined && (state.approval === "in-effect" || state.approval === "starting-after-task"), "team.break.command.endForcedBreak", path, "end a currently forced break");
+        if (command.type === "force-break") {
             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 : [];
-            into.require(state.reasons === undefined ? command.reasonId === undefined : reasons.some((r) => isPlainObject(r) && r.id === command.reasonId), "team.break.command.reasonId", path, "place uses the target's currently published reason codes");
+            into.require(state.reasons === undefined ? command.reasonId === undefined : reasons.some((r) => isPlainObject(r) && r.id === command.reasonId), "team.break.command.reasonId", path, "force-break uses the target's currently published reason codes");
         }
     }
     return into.violations;
@@ -1459,7 +1459,7 @@ export function validateBreakCommand(method, request, state, context, path = "br
             into.require(approval === "awaiting-decision" || approval === "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 === "in-effect", "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 releases it");
+            into.require(state.forced === undefined, "break.command.end.forced", path, "an agent cannot end a forced break; an authorized lead ends it");
         }
     }
     return into.violations;
@@ -1518,7 +1518,7 @@ function validateBreakState(value, path, into) {
     }
     if (value.forced !== undefined) {
         validateForcedBreak(value.forced, `${path}.forced`, into);
-        // A forced break is a break somebody placed; beside `not-requested` there is no break.
+        // 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 in-effect or
         // starting-after-task and nothing else. Beside granted, the host would commit a break nobody asked for.
         into.require(value.approval === "in-effect" || 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`);
@@ -1557,7 +1557,7 @@ function validateBreakState(value, path, into) {
         into.require(seen.has(value.activeReasonId), "break.activeReasonId.known", `${path}.activeReasonId`, `activeReasonId names a reason the provider did not publish: ${value.activeReasonId}`);
     }
     // A break in effect, or about to be, on a provider that publishes reasons is on one of them: an
-    // forced one included, since the lead's place named it. A break of no kind is a break whose
+    // 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 === "in-effect" || value.approval === "starting-after-task")) {

package/guide.md

@@ -1034,10 +1034,10 @@ type TeamLeadAssistCommand =
   | { type: "decline"; requestId: string; reason?: string };
 
 type TeamBreakCommand =
-  | { type: "decide"; memberId: UserId; decision: "granted" | "denied"; reason?: string }
+  | { type: "decide-break-request"; memberId: UserId; decision: "granted" | "denied"; reason?: string }
   | { type: "policy"; policy: "ask" | "auto-approve" | "suspended" }
-  | { type: "place"; memberId: UserId; reasonId?: string; reason?: string }
-  | { type: "release"; memberId: UserId };
+  | { type: "force-break"; memberId: UserId; reasonId?: string; reason?: string }
+  | { type: "end-forced-break"; memberId: UserId };
 
 type TeamBreakCommandRequest = {
   command: TeamBreakCommand;
@@ -1924,7 +1924,7 @@ them from what arrives later.
 | --- | --- |
 | `breaks` | This login may request a break. Requires the four break methods on the connection. |
 | `team` | This login leads a team. The provider publishes a `TeamMembers` object to it on every snapshot — `members: []` when nobody is in it — and to nobody else. |
-| `team.breakControl` | This lead may act on their team's breaks through `executeTeamBreak` — place, release, decide, set policy — as far as the provider supports; a command it lacks answers `omni.capability-not-enabled`. Omni asks for a decision only against a member whose `break` is `awaiting-decision`, so a provider that grants on request is never asked to decide. Requires `executeTeamBreak`. |
+| `team.breakControl` | This lead may act on their team's breaks through `executeTeamBreak` — force-break, end-forced-break, decide-break-request, set policy — as far as the provider supports; a command it lacks answers `omni.capability-not-enabled`. Omni asks for a decision only against a member whose `break` is `awaiting-decision`, so a provider that grants on request is never asked to decide. Requires `executeTeamBreak`. |
 | `team.leadAssistControl` | This lead may join a member's call on request. Requires `executeTeamLeadAssist`. |
 | `team.listeningControl` | This lead may listen to a member's call unasked, in the listed modes and no others: `listen`, `coach`, `join-call`. The list always includes `listen`, since the other two begin from one. Requires `executeTeamListen`. See **Listening to a call**. |
 | `team.policyControl` | This lead sets the team's policy per capability — on, off, or the person's — within what the queue allows. Requires `executeTeamPolicy`; the team member list carries `policies`. |
@@ -3614,7 +3614,7 @@ nothing while none are being accepted — so they are not published separately.
 | `retryAfterMs` | How long until the agent may retry, when the provider can say. |
 | `reasons` | Not-ready codes this provider offers. Omitted when it defines none; an empty list is refused, being a second spelling of the same fact. |
 | `activeReasonId` | The `BreakReason.id` the current break is on. Omitted when there is no break. Required on a break `in-effect` or `starting-after-task` where the provider publishes `reasons`, a forced break included (`break.activeReasonId.required`): a break with a kind the provider cannot name is a break whose rules nobody can apply. |
-| `forced` | Set when the break was placed on the agent rather than requested. |
+| `forced` | Set when the break was forced on the agent rather than requested. |
 
 A request can be waiting for two unrelated things, and they are separate values because
 rendering one as the other tells an agent to wait for somebody who is never coming:
@@ -3646,12 +3646,20 @@ Migration: ImposedBreak is now `ForcedBreak`, and the former imposed field is no
 `BreakState.forced`. Diagnostic and harness coverage names use `break.forced`; the agent-end
 diagnostic is `break.command.end.forced`. Update hosts and providers together. The old field
 is rejected, including when both spellings are sent; no compatibility alias is provided.
-The `place` and `release` commands and break ordering rules are unchanged.
-
-`ForcedBreak` says who placed the break, whether automatic ending is enabled, and, when enabled,
+The team break command formerly named decide is now `decide-break-request`. The former
+spelling is rejected without an alias; the granted/denied decisions and pending-request
+prerequisite are unchanged.
+The team break command formerly named place is now `force-break`. Hosts and providers must
+adopt the new command together; place and the interim force spelling are rejected without aliases.
+The team break command formerly named release is now `end-forced-break`, and its diagnostic is
+`team.break.command.endForcedBreak`. The former release command and the interim end spelling are rejected without aliases.
+**End a forced break** is a lead action through `executeTeamBreak`; the agent’s `endBreak`
+method still cannot end a forced break. Break ordering and permission rules are unchanged.
+
+`ForcedBreak` says who forced the break, whether automatic ending is enabled, and, when enabled,
 when the provider will end it. A break the agent did not choose is not manually resumable by them.
 
-**Every forced break has a person behind it.** A lead or a manager placed it; there is no such
+**Every forced break has a person behind it.** A lead or a manager forced it; there is no such
 thing as a break the platform forced on its own. Where a platform applies one automatically, it is
 executing a preference somebody configured, and that person is the owner of the action — `by` names
 them, not the machinery that carried it out.
@@ -3662,7 +3670,7 @@ a display name.
 **A forced break travels with `in-effect` or `starting-after-task`, and nothing else.** It is a
 break in progress or about to be; beside `granted` or `awaiting-decision` the host would read a
 request the agent never made and commit it (`break.forced.approval`). Where the provider publishes
-`reasons`, the lead's `place` named one, and the member's state carries it as `activeReasonId`.
+`reasons`, the lead's `force-break` named one, and the member's state carries it as `activeReasonId`.
 
 For example:
 
@@ -3677,7 +3685,7 @@ forced: {
 The presence of `forced` means the agent cannot end the break manually, so Omni withdraws its
 Resume control from that agent. With `endsAutomatically: true`, the provider ends the break at
 `endsAt`; with `endsAutomatically: false`, it does not end the break on a timer. An authorized lead
-may end either form with **Resume**, not only whoever placed it. Omni shows **Stopped by <who>**,
+may end either form with **Resume**, not only whoever forced it. Omni shows **Stopped by <who>**,
 resolving the name with `describeUsers()`, and shows when the break will end where automatic ending
 is enabled.
 
@@ -3768,10 +3776,10 @@ request object only to the request method, and undefined to the other three.
 | `cancelBreak` | `awaiting-decision` or `granted`. A concurrent commit winning still answers `omni.break-already-committed` and requires recovery. |
 | `endBreak` | `in-effect` or `starting-after-task` during reconciliation; an agent cannot end a forced break. |
 
-Use `validateTeamBreakCommand(request, context)` for lead decisions, placement, release and
+Use `validateTeamBreakCommand(request, context)` for lead decisions, forcing a break, ending a forced break and
 policy commands. It requires the live lead capability and active transport, a current target
-team member list for member commands, and the target's complete break state for placement/release.
-Approve/deny requires an awaiting decision; placement uses the target's reason codes; release
+team member list for member commands, and the target's complete break state for forcing/ending a break.
+Approve/deny requires an awaiting decision; forcing a break uses the target's reason codes; ending a forced break
 requires a forced committed break. The context's target state must belong to the named member;
 that association and backend authorization are provider responsibilities.
 
@@ -3860,7 +3868,7 @@ and the other scheduled maintenance, match on it, and nothing could tell the dif
 specificity: about this agent's own work is `coaching`, else something they must know afterwards is
 `training`, else `meeting`.
 
-**A break somebody placed on the agent is not automatically one of these.** Where the agent was
+**A break somebody forced on the agent is not automatically one of these.** Where the agent was
 stopped rather than choosing to stop — see **Forced breaks** — set `BreakState.forced` and prefer
 omitting `kind` to reaching for `other`. None of the ten describes "something was done to this
 agent", and `other` claims a classification that was never made.
@@ -4098,10 +4106,10 @@ One method, `executeTeamBreak`, taking a discriminated command exactly as `execu
 
 | Command | Effect |
 | --- | --- |
-| `{ type: "decide", memberId: UserId, decision, reason? }` | Settles one pending request. `decision` is `granted` or `denied`. A grant moves the member to `granted`; a denial ends the request and moves it directly to `not-requested`. |
+| `{ type: "decide-break-request", memberId: UserId, decision, reason? }` | Settles one pending request. `decision` is `granted` or `denied`. A grant moves the member to `granted`; a denial ends the request and moves it directly to `not-requested`. |
 | `{ type: "policy", policy }` | `ask`, `auto-approve`, or `suspended`. |
-| `{ type: "place", memberId: UserId, reasonId?, reason? }` | Puts a member on a break they did not ask for. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. |
-| `{ type: "release", memberId: UserId }` | Ends a forced break on that member, whoever placed it. |
+| `{ type: "force-break", memberId: UserId, reasonId?, reason? }` | Puts a member on a break they did not ask for. `reasonId` names a published `BreakReason.id` and is required whenever the provider publishes `reasons`; the member's forced break carries it as `activeReasonId`, so its kind is known. |
+| `{ type: "end-forced-break", memberId: UserId }` | Ends a forced break on that member, whoever forced it. |
 
 `memberId` is this provider's own identifier for the member, as published on its team member list. It is
 never an identifier from another provider, and Omni does not translate between them; names come
@@ -4109,7 +4117,7 @@ from `describeUsers()`.
 
 `suspended` means requests are **rejected outright** rather than left pending — nobody is coming to
 approve them. A provider that suspends breaks must also publish `mayAsk: false` to the team's
-agents so they see it before asking. A `place` must likewise reach that member as an `forced` break
+agents so they see it before asking. A `force-break` must likewise reach that member as a `forced` break
 on their own `BreakState`, or they are stopped from working with no way to see why.
 
 What happens when no lead is online — auto-approving, for instance — is the provider's decision and is
@@ -4947,7 +4955,7 @@ Replaces this provider's complete `break` object. Its `approval` uses the canoni
 reasons, retry details, and any forced break.
 
 Each state is also held to the one before it. A commit's states, `starting-after-task` and
-`in-effect`, follow a grant — the one arrival in a committed state nobody asked for is a placed
+`in-effect`, follow a grant — the one arrival in a committed state nobody asked for is a forced
 break, which says so with `forced`: in effect at once, or `starting-after-task` while the member
 finishes the call they are on (`stream.breakState.commitBeforeGrant`); and a break never moves backwards —
 from `in-effect` or `starting-after-task` to a grant or a request, or from `granted` to
@@ -4980,7 +4988,7 @@ operation is dispatched. The source must fence delayed operations against its ow
 Normal order is `not-requested` → `awaiting-decision` → `granted` →
 `starting-after-task` → `in-effect` → `not-requested`. Auto-approval may go directly to
 `granted`; a commit with no outstanding work may go directly to `in-effect`. Denial/cancel
-returns a precommit request to `not-requested`; an authorized end/release returns a committed
+returns a precommit request to `not-requested`; an authorized agent or lead end returns a committed
 break there. Same-state restatements are allowed. An evidenced forced break is the explicit
 exception to requesting/granting, and must carry its forced actor/state. Neither skipped
 publication nor a host-local guess creates another exception. A later normal attempt starts
@@ -5380,7 +5388,7 @@ cannot be established from TypeScript structure alone.
 | `assertReconnectWithMissedAssignments(before, reconnect, ids)` | A reconnect snapshot restores assignments received while offline. |
 | `stillHost(report?, guarantees?, mute?)` | A host that reports one thing and never changes, for a test context: `{ online: true }` by default, a report with audio for a softphone voice adapter, and never for a desk phone. |
 | `TaskStream`, `BreakStream` | The cross-event models the harness applies after the connect snapshot, exported for a host that wants the same rules at its boundary: `seed(snapshot)`, then `apply(envelope)` returns the violations. |
-| `assertBreakFollowsItsRequests(envelopes, snapshot?)` | A break follows its requests: a commit's states only after a grant, never backwards, and a placed break arriving in effect with `forced`. The harness applies the same rules after the connect snapshot. |
+| `assertBreakFollowsItsRequests(envelopes, snapshot?)` | A break follows its requests: a commit's states only after a grant, never backwards, and a forced break arriving in effect with `forced`. The harness applies the same rules after the connect snapshot. |
 | `assertMediaFollowsTheTask(envelopes, snapshot?)` | The media follows the task and never decides it: every task is introduced once, `task-media-started` and `task-media-ended` alternate on work that has begun, media ends only where it arrived, and what follows the media ending is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). A sequence with no media satisfies it by never testing it — pair it with the assertion that the media end is present. |
 | `assertBreakAttemptProviders(candidates, asked)` | A break attempt asks every usable provider holding capacity, `refreshing` included, and nothing of a provider whose login is `expired`. |
 | `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `in-effect` only once nothing is outstanding — never beside a task, never later than the step that has none. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.91",
+  "version": "0.1.93",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",