@xema/omni-protocol 0.1.103 → 0.1.104

package/dist/index.d.ts

@@ -153,6 +153,12 @@ export interface Manifest<C extends Channel = Channel> {
     authenticationMethods: AuthenticationMethod[];
     idleCapabilities?: IdleCapabilities<C>;
     /** Optional provider-clock sampling through Connection.checkTime; absent means unsupported. */
+    /**
+     * Implements `checkTime`, and states `providerTime` on every snapshot. Required of a provider
+     * that publishes an instant the desk renders as a running duration -- a member's `since`, a
+     * lead's `listening.since`, an `onCall.since`, a shift's `signedInAt` -- so every screen counts
+     * from the provider's clock and two screens differ by their delay alone.
+     */
     timeCheck?: true;
     /** Provider uses its own timestamps for final records; host timestamps are advisory. Omission makes no trust promise. */
     timestampAuthority?: "provider";
@@ -1206,8 +1212,13 @@ export interface BreakRequest {
  */
 export type ForcedBreak = {
     by: UserId | "provider";
-    /** Optional expected time on break, in milliseconds from actual start. Advisory only. */
-    expectedDurationMs?: number;
+    /**
+     * How long the break is expected to run yet, in whole seconds from this publication, restated
+     * on every publication that carries it so every screen counts down the same number from
+     * receipt. Advisory only: nothing ends the break but the agent. Absent once it has run out, or
+     * where none was expected.
+     */
+    expectedEndsInSeconds?: DurationSeconds;
 };
 export interface BreakState {
     status: BreakStatus;
@@ -1264,10 +1275,10 @@ export interface TeamMember {
     break?: Extract<BreakStatus, "awaiting-approval" | "granted" | "starting-after-task">;
     /** The member's open tasks, trimmed, kept current by the provider; `[]` when they hold none, omitted only where the provider cannot see them. */
     tasks?: MemberTask[];
-    /** Present while this lead is on the member's call, listening, coaching or joined; absent otherwise. */
-    listening?: MemberListening;
-    /** The member's own history for the day: sign-in, sign-out, breaks and productivity. Omitted where the provider cannot say. */
-    shift?: MemberShift;
+    /** Every lead on this member's call, listening, coaching or joined, published to every lead alike; absent while none is. */
+    listening?: MemberListening[];
+    /** The member's own history for the day: sign-in, sign-out, breaks and productivity, the same numbers the member's own snapshot carries. Omitted where the provider cannot say. */
+    shift?: Shift;
     /** The member's standing ask for a lead on one of their calls; absent when they are not asking. */
     request?: MemberRequest;
 }
@@ -1310,11 +1321,14 @@ export type MemberTask<C extends Channel = Channel> = {
     audio?: never;
 });
 /**
- * The lead on this member's call: which of the member's calls, in the mode they are heard, since
- * when. Its appearance on the team member list is the provider's word that the lead's audio is up,
- * and the application opens `openAudio` on the assignment named; its disappearance closes it.
+ * A lead on this member's call: who, which of the member's calls, in the mode they are heard,
+ * since when. Every lead sees every entry; the application opens `openAudio` on the entry whose
+ * `leadId` is the signed-in lead, and closes it when that entry goes. A lead who is heard --
+ * `join-call` -- is also on the task's `onCall` as an `agent`; `listen` and `coach` leave no trace
+ * on the member's task.
  */
 export interface MemberListening {
+    leadId: UserId;
     assignmentId: AssignmentId;
     mode: ListeningMode;
     since: IsoTimestamp;
@@ -1326,11 +1340,13 @@ export interface ShiftEvent {
     kind: ShiftEventKind;
 }
 /**
- * The member's own history for the day, about the person rather than any one call: when they
+ * An agent's own history for the day, about the person rather than any one call: when they
  * signed in and out, today's totals as the provider counts them, each present only when the
- * provider knows it, and the day's sign-in, sign-out and break events, oldest first.
+ * provider knows it, and the day's sign-in, sign-out and break events, oldest first. Published
+ * to the agent on their snapshot and on `shift-updated`, and to their lead on the team member
+ * list: the same numbers from the same count.
  */
-export interface MemberShift {
+export interface Shift {
     signedInAt: IsoTimestamp;
     signedOutAt?: IsoTimestamp;
     talkSeconds?: DurationSeconds;
@@ -1550,6 +1566,12 @@ export type PreferenceResult = {
 export interface Snapshot<C extends Channel = Channel> {
     transport: TransportStatus;
     loginId: string;
+    /**
+     * The provider's own instant of this read, required of a provider that declares `timeCheck`:
+     * every duration the desk renders off the active call is counted from the provider's clock, and
+     * this sample saves a `checkTime` for it. Every envelope's `occurredAt` is a sample too.
+     */
+    providerTime?: IsoTimestamp;
     break: BreakState;
     /** Every task currently owned by this agent for this provider. */
     tasks: Task<C>[];
@@ -1557,6 +1579,8 @@ export interface Snapshot<C extends Channel = Channel> {
     taskCount: number;
     contacts?: Contact[];
     calendar?: ScheduledActivity[];
+    /** The agent's own day so far, as the provider counts it; replaced whole by `shift-updated`. Omitted where the provider cannot say. */
+    shift?: Shift;
     team?: TeamMembers;
 }
 /**
@@ -1668,6 +1692,11 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "calendar-updated";
     calendar: ScheduledActivity[];
+}
+/** The agent's own day, whole, whenever a total moves: a task ended, a break ended. */
+ | {
+    type: "shift-updated";
+    shift: Shift;
 };
 /**
  * The `Provider` prefix survives here for a mechanical reason rather than a naming one: `Event`

package/dist/testing.d.ts

@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
  * rules -- each optional part of a task, each optional part of the break state and team member list, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "contacts", "calendar", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.history", "task.onCall", "task.leadAssist", "task.takenOver", "task.audio", "task.acceptance", "task.outcomes", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.forced", "team.members", "team.request", "team.tasks", "team.listening", "team.shift", "shift", "contacts", "calendar", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];

package/dist/testing.js

@@ -28,6 +28,7 @@ const STATE_SUBJECTS = [
     "team.tasks",
     "team.listening",
     "team.shift",
+    "shift",
     "contacts",
     "calendar",
     "team.policies",
@@ -38,7 +39,7 @@ const EVENT_TYPES = {
     snapshot: true, "transport-status": true, "break-state": true, "task-offered": true, "task-updated": true,
     "task-audio-started": true, "task-audio-ended": true, "task-ended": true, "dial-outcome": true, announcement: true, "queue-summary": true, diagnostic: true,
     "team-updated": true, "team-member-updated": true, "team-member-removed": true, "team-policies-updated": true,
-    "contacts-updated": true, "calendar-updated": true,
+    "contacts-updated": true, "calendar-updated": true, "shift-updated": true,
 };
 const CONTRACT_SUBJECTS = [
     ...STATE_SUBJECTS,
@@ -94,7 +95,7 @@ function observeMember(member, seen) {
         return;
     if (some(member.tasks))
         seen.add("team.tasks");
-    if (member.listening !== undefined)
+    if (some(member.listening))
         seen.add("team.listening");
     if (member.shift !== undefined)
         seen.add("team.shift");
@@ -126,6 +127,8 @@ function observeSnapshot(value, seen) {
         seen.add("contacts");
     if (some(value.calendar))
         seen.add("calendar");
+    if (value.shift !== undefined)
+        seen.add("shift");
 }
 function observeEvent(envelope, seen) {
     const event = isRecord(envelope) ? envelope.event : undefined;
@@ -162,6 +165,9 @@ function observeEvent(envelope, seen) {
             if (some(event.calendar))
                 seen.add("calendar");
             break;
+        case "shift-updated":
+            seen.add("shift");
+            break;
         default: break;
     }
 }
@@ -719,9 +725,14 @@ function userIdsIn(snapshot) {
         add(snapshot?.break?.forced?.by);
     const team = snapshot?.team;
     if (isRecord(team)) {
-        for (const member of Array.isArray(team.members) ? team.members : [])
-            if (isRecord(member))
-                add(member.id);
+        for (const member of Array.isArray(team.members) ? team.members : []) {
+            if (!isRecord(member))
+                continue;
+            add(member.id);
+            for (const entry of Array.isArray(member.listening) ? member.listening : [])
+                if (isRecord(entry))
+                    add(entry.leadId);
+        }
     }
     for (const task of Array.isArray(snapshot?.tasks) ? snapshot.tasks : []) {
         const t = task;
@@ -1063,7 +1074,7 @@ const REACHABLE_PHASES = {
 export const SUPERSEDED_BY_A_SNAPSHOT = new Set([
     "snapshot", "transport-status", "break-state", "task-offered", "task-updated", "task-ended",
     "task-audio-started", "task-audio-ended", "team-updated", "team-member-updated", "team-member-removed", "team-policies-updated",
-    "contacts-updated", "calendar-updated",
+    "contacts-updated", "calendar-updated", "shift-updated",
 ]);
 export class TaskStream {
     tasks = new Map();

package/dist/validation.js

@@ -1313,8 +1313,9 @@ function validateForcedBreak(value, path, into) {
     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");
+    into.require(!Object.hasOwn(value, "expectedDurationMs"), "break.forced.expectedDurationMs.renamed", `${path}.expectedDurationMs`, "the state says how long is left, as expectedEndsInSeconds; the duration asked for travels on the lead's command alone");
+    if (value.expectedEndsInSeconds !== undefined)
+        into.require(isDurationSeconds(value.expectedEndsInSeconds), "break.forced.expectedEndsInSeconds", `${path}.expectedEndsInSeconds`, "expectedEndsInSeconds is how long the break is expected to run yet: a whole number of seconds, zero or more, counted from this publication");
 }
 /** Checks break status against the full currently retained task set, after a transaction. */
 export function validateBreakStatus(state, tasks, path = "snapshot") {
@@ -1435,7 +1436,8 @@ export function validateTeamCommand(request, context, path = "teamCommand") {
         into.require(asked !== undefined && (command.assignmentId === undefined || asked.assignmentId === command.assignmentId), "team.command.request", path, `${command.type} answers a request the team member list carries on the member, and this member has none`);
     }
     else if (command.type === "coach" || command.type === "join-call" || command.type === "leave") {
-        into.require(isPlainObject(target) && target.listening !== undefined, "team.command.listening", path, `${command.type} needs the lead on this member's call: the team member list shows listening on them`);
+        // Every lead's entry is on the member; the one this command moves is the signed-in lead's.
+        into.require(isPlainObject(target) && Array.isArray(target.listening) && target.listening.some((entry) => isPlainObject(entry) && entry.leadId === self), "team.command.listening", path, `${command.type} needs this lead on this member's call: the team member list shows listening on them naming this lead`);
     }
     return into.violations;
 }
@@ -1631,10 +1633,19 @@ function validateTeamMembersInto(teamMembers, path, context, into) {
         }
         validateTeamMemberInto(member, at, context, into);
     });
-    // One member's call at a time.
-    const listened = teamMembers.members.filter((member) => isPlainObject(member) && member.listening !== undefined);
-    if (listened.length > 1)
-        into.add("team.listening.single", `${path}.members`, "a lead is on one member's call at a time");
+    // One member's call at a time, per lead.
+    const onCalls = new Map();
+    for (const member of teamMembers.members) {
+        if (!isPlainObject(member) || !Array.isArray(member.listening))
+            continue;
+        const leads = new Set(member.listening.filter(isPlainObject).map(entry => entry.leadId).filter((id) => typeof id === "string"));
+        for (const leadId of leads)
+            onCalls.set(leadId, (onCalls.get(leadId) ?? 0) + 1);
+    }
+    for (const [leadId, count] of onCalls) {
+        if (count > 1)
+            into.add("team.listening.single", `${path}.members`, `${leadId} is on ${count} members' calls: a lead is on one member's call at a time`);
+    }
 }
 /** One member as the lead sees them, whole: on the list, and on `team-member-updated` alone. */
 export function validateTeamMember(member, path = "member", context = {}) {
@@ -1679,23 +1690,41 @@ function validateTeamMemberInto(member, at, context, into) {
             into.require(member.availability !== "signed-out" || member.tasks.length === 0, "team.member.tasks.availability", `${at}.tasks`, "a member signed out holds no task");
         }
     }
-    // The lead on this member's call, in the mode they are heard.
+    // Every lead on this member's call, in the mode they are heard, published to every lead alike.
     if (member.listening !== undefined) {
-        if (!isPlainObject(member.listening)) {
-            into.add("team.member.listening.shape", `${at}.listening`, "listening must be an object when present");
+        if (!Array.isArray(member.listening)) {
+            into.add("team.member.listening.shape", `${at}.listening`, "listening is an array of the leads on the member's call: absent while none is");
         }
         else {
-            const listened = member.listening;
-            if (into.require(isAssignmentId(member.listening.assignmentId), "team.member.listening.assignmentId", `${at}.listening.assignmentId`, "listening names which of the member's calls the lead is on: the application opens the lead's audio on it") && Array.isArray(member.tasks)) {
-                into.require(member.tasks.some((task) => isPlainObject(task) && task.assignmentId === listened.assignmentId), "team.member.listening.assignment", `${at}.listening.assignmentId`, "the call the lead is on is one the member's tasks carry");
-            }
-            into.oneOf(member.listening.mode, LISTENING_MODES, "team.member.listening.mode", `${at}.listening.mode`);
-            into.timestamp(member.listening.since, "team.member.listening.since", `${at}.listening.since`);
+            into.require(member.listening.length > 0, "team.member.listening.empty", `${at}.listening`, "nobody on the call is absence, not an empty list");
+            const leads = new Set();
+            member.listening.forEach((entry, index) => {
+                const here = `${at}.listening[${index}]`;
+                if (!isPlainObject(entry)) {
+                    into.add("team.member.listening.entry", here, "each listening entry must be an object");
+                    return;
+                }
+                if (into.require(isUserId(entry.leadId), "team.member.listening.leadId", `${here}.leadId`, "a listening entry names the lead on the call, by user id")) {
+                    if (leads.has(entry.leadId))
+                        into.add("team.member.listening.unique", `${here}.leadId`, `${entry.leadId} is listed twice on one member: a lead is on a member's call once`);
+                    leads.add(entry.leadId);
+                }
+                const task = Array.isArray(member.tasks) ? member.tasks.find((task) => isPlainObject(task) && task.assignmentId === entry.assignmentId) : undefined;
+                if (into.require(isAssignmentId(entry.assignmentId), "team.member.listening.assignmentId", `${here}.assignmentId`, "a listening entry names which of the member's calls the lead is on: the application opens its own audio on it") && Array.isArray(member.tasks)) {
+                    into.require(task !== undefined, "team.member.listening.assignment", `${here}.assignmentId`, "the call the lead is on is one the member's tasks carry");
+                }
+                if (into.oneOf(entry.mode, LISTENING_MODES, "team.member.listening.mode", `${here}.mode`) && entry.mode === "join-call"
+                    && isPlainObject(task) && Array.isArray(task.onCall) && isUserId(entry.leadId)) {
+                    // A lead who is heard is in the room the member sees; a silent one is not.
+                    into.require(task.onCall.some((who) => isPlainObject(who) && who.role === "agent" && who.userId === entry.leadId), "team.member.listening.heard", `${here}.mode`, `${entry.leadId} has joined the call and is heard, so the task's onCall carries them as an agent`);
+                }
+                into.timestamp(entry.since, "team.member.listening.since", `${here}.since`);
+            });
         }
     }
     // The member's own history for the day: about the person, not any one call.
     if (member.shift !== undefined)
-        validateShiftInto(member.shift, `${at}.shift`, into);
+        validateShiftInto(member.shift, `${at}.shift`, into, "team.member.shift");
     // The member's standing ask for a lead, on one of the calls they hold.
     if (member.request !== undefined) {
         if (!isPlainObject(member.request)) {
@@ -1721,6 +1750,18 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
     const levels = context.levels ?? manifestLevels(manifest);
     into.oneOf(snapshot.transport, TRANSPORT_STATUSES, "snapshot.transport", `${path}.transport`);
+    // The provider's own instant of the read: required where the provider has a clock to state, and
+    // a clock nobody declared is not one the desk may count from.
+    if (isPlainObject(manifest) && manifest.timeCheck === true) {
+        into.timestamp(snapshot.providerTime, "snapshot.providerTime", `${path}.providerTime`);
+    }
+    else if (snapshot.providerTime !== undefined) {
+        into.add("snapshot.providerTime.unexpected", `${path}.providerTime`, "providerTime is the clock of a provider that declares timeCheck; declare it, or send none");
+    }
+    requireClockInto(snapshot, manifest, path, into);
+    // The agent's own day, as the provider counts it: the same numbers their lead sees.
+    if (snapshot.shift !== undefined)
+        validateShiftInto(snapshot.shift, `${path}.shift`, into, "shift");
     if (into.filled(snapshot.loginId, "snapshot.loginId", `${path}.loginId`, "a snapshot needs the login id it belongs to")
         && context.loginId !== undefined) {
         into.require(snapshot.loginId === context.loginId, "snapshot.loginId.mismatch", `${path}.loginId`, `a snapshot for session ${describeValue(snapshot.loginId)} on a login whose session is ${context.loginId}`);
@@ -1894,6 +1935,9 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
         return into.violations;
     }
     const at = `${path}.event`;
+    // A snapshot event is read by validateSnapshot, which asks the clock question of it there.
+    if (event.type !== "snapshot")
+        requireClockInto(event, manifest, at, into);
     into.require(!Object.hasOwn(event, "taskId"), "event.assignmentId.renamed", `${at}.taskId`, "an event names a task by its assignment alone; the former field is not accepted");
     switch (event.type) {
         case "snapshot":
@@ -2004,6 +2048,9 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 event.contacts.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into, levels));
             }
             break;
+        case "shift-updated":
+            validateShiftInto(event.shift, `${at}.shift`, into, "shift");
+            break;
         case "calendar-updated":
             into.require(idle.calendar === true, "event.calendar.capability", `${at}.calendar`, "calendar-updated requires the calendar idle capability");
             if (!Array.isArray(event.calendar)) {
@@ -2055,38 +2102,65 @@ function validatePreferencesInto(value, path, into, levels) {
     });
 }
 /** The team's policy per capability as the lead sees it: the setting, who set it, who locked it. */
-function validateShiftInto(value, path, into) {
+/** Whether a publication carries an instant the desk renders as a running duration, which the provider's clock reads. */
+function carriesRunningInstant(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (isPlainObject(value.shift) && value.shift.signedInAt !== undefined)
+        return true;
+    const tasks = [
+        ...(Array.isArray(value.tasks) ? value.tasks : []),
+        ...(isPlainObject(value.task) ? [value.task] : []),
+    ];
+    if (tasks.some(task => isPlainObject(task) && Array.isArray(task.onCall) && task.onCall.some((who) => isPlainObject(who) && who.since !== undefined)))
+        return true;
+    const members = [
+        ...(isPlainObject(value.team) && Array.isArray(value.team.members) ? value.team.members : []),
+        ...(isPlainObject(value.member) ? [value.member] : []),
+    ];
+    return members.some(member => isPlainObject(member) && (member.since !== undefined
+        || (Array.isArray(member.listening) && member.listening.some((entry) => isPlainObject(entry) && entry.since !== undefined))
+        || (isPlainObject(member.shift) && member.shift.signedInAt !== undefined)
+        || (Array.isArray(member.tasks) && member.tasks.some((task) => isPlainObject(task) && Array.isArray(task.onCall) && task.onCall.some((who) => isPlainObject(who) && who.since !== undefined)))));
+}
+/** A running duration is counted from the provider's clock: a provider that publishes one declares timeCheck. */
+function requireClockInto(value, manifest, path, into) {
+    if (!isPlainObject(manifest) || manifest.timeCheck === true || !carriesRunningInstant(value))
+        return;
+    into.add("manifest.timeCheck.required", path, "this publishes an instant the desk renders as a running duration -- a since, a signedInAt -- and the manifest declares no timeCheck: every screen counts such a duration from the provider's clock, so the provider states one");
+}
+function validateShiftInto(value, path, into, rule) {
     if (!isPlainObject(value)) {
-        into.add("team.member.shift.shape", path, "shift must be an object when present");
+        into.add(`${rule}.shape`, path, "shift must be an object when present");
         return;
     }
-    const signedIn = into.timestamp(value.signedInAt, "team.member.shift.signedInAt", `${path}.signedInAt`);
-    if (value.signedOutAt !== undefined && into.timestamp(value.signedOutAt, "team.member.shift.signedOutAt", `${path}.signedOutAt`) && signedIn) {
-        into.require(Date.parse(value.signedOutAt) >= Date.parse(value.signedInAt), "team.member.shift.signedOutAt.order", `${path}.signedOutAt`, "a member signs out after signing in");
+    const signedIn = into.timestamp(value.signedInAt, `${rule}.signedInAt`, `${path}.signedInAt`);
+    if (value.signedOutAt !== undefined && into.timestamp(value.signedOutAt, `${rule}.signedOutAt`, `${path}.signedOutAt`) && signedIn) {
+        into.require(Date.parse(value.signedOutAt) >= Date.parse(value.signedInAt), `${rule}.signedOutAt.order`, `${path}.signedOutAt`, "a member signs out after signing in");
     }
     for (const field of ["talkSeconds", "holdSeconds", "breakSeconds"]) {
         if (value[field] !== undefined)
             into.require(isDurationSeconds(value[field]), `team.member.shift.${field}`, `${path}.${field}`, `${field} must be a whole number of seconds, zero or more, or omitted when unknown`);
     }
     if (value.tasksHandled !== undefined)
-        into.require(Number.isInteger(value.tasksHandled) && value.tasksHandled >= 0, "team.member.shift.tasksHandled", `${path}.tasksHandled`, "tasksHandled must be a whole number, zero or more, or omitted when unknown");
+        into.require(Number.isInteger(value.tasksHandled) && value.tasksHandled >= 0, `${rule}.tasksHandled`, `${path}.tasksHandled`, "tasksHandled must be a whole number, zero or more, or omitted when unknown");
     if (value.events !== undefined) {
         if (!Array.isArray(value.events)) {
-            into.add("team.member.shift.events.shape", `${path}.events`, "events must be an array when present");
+            into.add(`${rule}.events.shape`, `${path}.events`, "events must be an array when present");
             return;
         }
         let previous;
         value.events.forEach((event, index) => {
             const at = `${path}.events[${index}]`;
             if (!isPlainObject(event)) {
-                into.add("team.member.shift.event.shape", at, "each shift event must be an object");
+                into.add(`${rule}.event.shape`, at, "each shift event must be an object");
                 return;
             }
-            into.oneOf(event.kind, SHIFT_EVENT_KINDS, "team.member.shift.event.kind", `${at}.kind`);
-            if (into.timestamp(event.at, "team.member.shift.event.at", `${at}.at`)) {
+            into.oneOf(event.kind, SHIFT_EVENT_KINDS, `${rule}.event.kind`, `${at}.kind`);
+            if (into.timestamp(event.at, `${rule}.event.at`, `${at}.at`)) {
                 const instant = Date.parse(event.at);
                 if (previous !== undefined && instant < previous)
-                    into.add("team.member.shift.events.order", `${at}.at`, "shift events are oldest first; this event is earlier than the one before it");
+                    into.add(`${rule}.events.order`, `${at}.at`, "shift events are oldest first; this event is earlier than the one before it");
                 previous = instant;
             }
         });

package/guide.md

@@ -474,11 +474,13 @@ type PreferenceResult =
 type Snapshot = {
   transport: TransportStatus;
   loginId: string;
+  providerTime?: IsoTimestamp;
   break: BreakState;
   tasks: Task[];
   taskCount: number;
   contacts?: Contact[];
   calendar?: ScheduledActivity[];
+  shift?: Shift;
   team?: TeamMembers;
 };
 
@@ -933,7 +935,7 @@ type BreakRequest = {
 
 type ForcedBreak = {
   by: UserId | "provider";
-  expectedDurationMs?: number;
+  expectedEndsInSeconds?: DurationSeconds;
 };
 
 type BreakState = {
@@ -975,8 +977,8 @@ type TeamMember = {
   since?: IsoTimestamp;
   break?: Extract<BreakStatus, "awaiting-approval" | "granted" | "starting-after-task">;
   tasks?: MemberTask[];
-  listening?: MemberListening;
-  shift?: MemberShift;
+  listening?: MemberListening[];
+  shift?: Shift;
   request?: MemberRequest;
 };
 
@@ -1006,6 +1008,7 @@ type MemberTask<C extends Channel = Channel> = {
   : { onCall?: never; leadAssist?: never; takenOver?: never; audio?: never });
 
 type MemberListening = {
+  leadId: UserId;
   assignmentId: AssignmentId;
   mode: ListeningMode;
   since: IsoTimestamp;
@@ -1018,7 +1021,7 @@ type ShiftEvent = {
   kind: ShiftEventKind;
 };
 
-type MemberShift = {
+type Shift = {
   signedInAt: IsoTimestamp;
   signedOutAt?: IsoTimestamp;
   talkSeconds?: DurationSeconds;
@@ -1134,7 +1137,8 @@ type ProviderEvent =
   | { type: "team-member-removed"; memberId: UserId }
   | { type: "team-policies-updated"; policies: TeamPolicies }
   | { type: "contacts-updated"; contacts: Contact[] }
-  | { type: "calendar-updated"; calendar: ScheduledActivity[] };
+  | { type: "calendar-updated"; calendar: ScheduledActivity[] }
+  | { type: "shift-updated"; shift: Shift };
 
 type ProviderEventEnvelope = {
   id: string;
@@ -1626,7 +1630,7 @@ compile time.
 | `orgLevels` | The organisation's whole ladder as the provider calls it, each level with the label a desk shows for "who decided". Stated outright, `person` included: what it leaves out does not exist. Omitted for the typical four, `DEFAULT_LEVELS`. See **Who decides what an agent may do**. |
 | `phones` | Voice only, and required there: the phones this platform can put an agent on, `softphone` (the call's audio lands in the agent application) and/or `deskPhone` (a handset the platform rings; the agent application shows the call and opens nothing). The agent application picks one per login. See **How the agent hears the call**. |
 | `dialOutcomes` | Voice only. How a dial can end on this platform, as it distinguishes them: `answered` and at least one way of not reaching the destination. Required of a provider that dials at all — an idle dialpad, or tasks that conference or call back — and a `dial-outcome` carries only a declared member. See **Every dial has an outcome**. |
-| `timeCheck` | Optional `true`: implements `checkTime` for fresh provider-clock samples; agent application polling is independently opt-in. |
+| `timeCheck` | `true`: implements `checkTime` and states `providerTime` on every snapshot. Required of a provider that publishes an instant the desk renders as a running duration -- a member's `since`, a lead's `listening.since`, an `onCall.since`, a shift's `signedInAt` -- so every screen counts from the provider's clock (`manifest.timeCheck.required`); agent application polling is independently opt-in. See **Every screen counts from the provider's clock**. |
 | `timestampAuthority` | Optional `"provider"`: provider timestamps are final; agent application instants are advisory. Omission makes no trust promise. |
 | `runningStepReports` | The provider takes running reports of an agent application-performed step — `recordStep` with `seconds` so far and no `ended`. Omitted, the agent application sends exactly two reports per leg, when it began and when it ended, and a running one is refused. See **The agent application records what it performs**. |
 | `settleMs` | Required. How long after `applied` the wire shows what the provider did: the `task-ended` after a `complete`, the `calendar-updated` after a `schedule`. A positive whole number of milliseconds (`manifest.settleMs`). Stated per provider, since platforms settle at different speeds. See **`task-ended`**. |
@@ -2142,11 +2146,13 @@ a capability it agrees with the login: a lead's snapshot carries `team`, nobody
 | --- | --- |
 | `transport` | Current `TransportStatus` — whether this provider's transport can serve the login. Defined under **`transport-status`**. |
 | `loginId` | Identity of this login. It must match the connection context. |
+| `providerTime` | The provider's own instant of this read. Required of a provider that declares `timeCheck` (`snapshot.providerTime`), forbidden of one that does not (`snapshot.providerTime.unexpected`): a clock sample the desk counts durations from, saving it a `checkTime`. |
 | `break` | Complete break state, including status, whether the agent may ask, reasons, retry details, and any forced break. |
 | `tasks` | Complete set of tasks currently offered to or owned by this agent. |
 | `taskCount` | The provider's own count of those tasks, stated rather than inferred, and it must equal `tasks.length`. A snapshot with no work says `taskCount: 0` in so many words — a blank or unanswered state lacks the count and cannot pass as a confirmed empty. |
 | `contacts` | Required complete contact contribution when the manifest declares `contacts`; `[]` clears it. Omitted only when it does not. |
 | `calendar` | Required complete calendar contribution when the manifest declares `calendar`; `[]` clears it. Omitted only when it does not. |
+| `shift` | The agent's own day so far, as the provider counts it -- the same `Shift` their lead sees on the team member list, the same numbers from the same count. Replaced whole by `shift-updated`. Omitted only where the provider cannot say. See **The agent's day is on the wire**. |
 | `team` | Required `TeamMembers` when the login declares `capabilities.lead` and the lead has the team feature on, `members: []` when nobody is in it. Forbidden otherwise — the login is the permission, and a lead who turned the feature off gets nothing of the team. |
 
 ## Live connection
@@ -2798,6 +2804,11 @@ Migration from the earlier spellings:
 | schedule on voice alone | `schedule` on every channel, under a manifest that declares `calendar` (`task.capability.calendar.required`), bounded by `settleMs` (`drive.schedule.unsettled`) |
 | a forced break requesting breaks on the other providers | `setCapacity({ count: 0 })` on every other usable provider (`assertForcedBreakStopsTheRest`) |
 | end-forced-break on a break the platform imposed | refused: `team.command.endForcedBreak.provider`, `omni.break-forced-by-provider` |
+| ForcedBreak.expectedDurationMs | `expectedEndsInSeconds`: seconds left, restated (`break.forced.expectedEndsInSeconds`, `.expectedDurationMs.renamed`); the command keeps `expectedDurationMs` |
+| MemberShift; the day on the lead's list alone | `Shift`, on `Snapshot.shift` and `shift-updated` for the agent, on `TeamMember.shift` for the lead |
+| TeamMember.listening as this lead's one entry | `MemberListening[]`, every lead's, each with `leadId` (`team.member.listening.leadId`, `.unique`, `.empty`, `.entry`, `.heard`) |
+| a member's history trimmed on the lead's list | the record whole, as the member's desk holds it |
+| durations counted from the screen's clock | the provider's: `timeCheck` required of a provider publishing a running instant (`manifest.timeCheck.required`), `Snapshot.providerTime` with it (`snapshot.providerTime`, `.unexpected`) |
 
 Update producers, consumers, saved task snapshots, and validation-rule assertions together.
 History and report rule names use `history` and `historyReport`; assignment rules use
@@ -3747,14 +3758,14 @@ The team break command formerly named release is now `end-forced-break`, and its
 `team.break.command.endForcedBreak`. The former release command and the interim end spelling are rejected without aliases.
 The agent’s `endBreak` now applies to forced breaks as well as requested breaks.
 
-`ForcedBreak` names who forced the break and may include an advisory `expectedDurationMs`.
-The agent must explicitly resume when ready. The retired endsAutomatically and endsAt fields
-are rejected, including when an expected duration is also provided.
-
-**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.
+`ForcedBreak` names who forced the break and may say how long it is expected to run yet, as
+`expectedEndsInSeconds`: whole seconds from the publication that carries it, restated on every
+publication, so every screen -- the agent's, reloaded or not, and every lead's -- counts down the
+same number from receipt (`break.forced.expectedEndsInSeconds`). The duration the lead asked for
+travels on the `force-break` command alone; the state says what is left, and drops the field once
+it has run out. The agent must explicitly resume when ready. The retired endsAutomatically and
+endsAt fields are rejected, including when an expectation is also provided. Who forced it is
+`by`, as **A forced break is the provider's act** below sets out.
 
 Omni resolves the name to show with `getUserDetails()`, so a provider sends the identifier and never
 a display name.
@@ -3769,16 +3780,16 @@ For example:
 ```ts
 forced: {
   by: "manager-1042",
-  expectedDurationMs: 600000
+  expectedEndsInSeconds: 600
 }
 ```
 
 The agent application keeps **Resume** available for an agent on a forced break. The agent explicitly chooses
 Resume; the agent application sends `endBreak()` and follows the provider-confirmed state before resuming
-work. An expected duration is a positive finite number of milliseconds, measured from actual
-entry into `on-break`, excluding any `starting-after-task` wait. Omission means no expected
-duration was supplied. Neither duration expiry nor an overdue indication authorizes the agent application
-or provider to end the break, restore availability, or route work to the agent.
+work. The expectation is whole seconds still to run, restated on every publication; omission
+means none was stated, or it has run out. Neither its reaching zero nor an overdue indication
+authorizes the agent application or provider to end the break, restore availability, or route
+work to the agent.
 
 **A forced break is the provider's act.** A lead's `force-break` is a command to the provider,
 which forces the break on the member; `by` names the lead who asked it to. A break the platform
@@ -3802,9 +3813,9 @@ must correlate resumption to the authenticated agent's action; a state-only orde
 cannot establish the cause of a transition. The usual multi-provider end/reconciliation flow
 still applies, and work resumes only on confirmed provider state.
 
-An agent application may display the expected duration. A countdown requires an evidenced actual start;
-a received snapshot, replay or reconnect is not a new start and cannot restart the duration.
-Without that evidence, show the duration without inventing a start or return time.
+An agent application counts `expectedEndsInSeconds` down from receipt, on every publication that
+carries it, and shows nothing of it where the provider sends none. It invents no start and no
+return time, and nothing acts on the number reaching zero.
 
 A break applies to the **agent**, not to one provider. When a provider forces one, Omni stops the
 agent everywhere else at once, and not by asking: it states `setCapacity({ count: 0 })` on every
@@ -4210,10 +4221,10 @@ computes nothing. See **`team-updated`** and its companions.
 | `availability` | Required. What the member is doing now. |
 | `since` | Optional. When the current `availability` began — not when they signed in, and not when the team member list was read. |
 | `break` | Present only while the member has an outstanding break request. See **A member waiting for a break**. |
-| `tasks` | The member's open tasks as `MemberTask`s: the same task the member's desk holds, trimmed by the provider. The assignment, title, task type, phase, party, room and audio are what the lead reads; the task's history is carried in the same shape as on the member's desk, as much of it as the provider chooses to send; the workspace — controls, their source, browsers, completion terms — is the member's and travels only if the provider sends it. `[]` when the member holds none; omitted only where the provider cannot see them. |
-| `listening` | Present while this lead's channel is in this member's call — listening, coaching or joined — naming which of the member's calls by `assignmentId`, the `mode` they are heard in, and since when. Its appearance is what the lead's audio opens on. One member's call at a time (`team.listening.single`). |
+| `tasks` | The member's open tasks as `MemberTask`s: the same task the member's desk holds, trimmed by the provider. The assignment, title, task type, phase, party, room and audio are what the lead reads, and the task's record -- `history`, steps and totals -- travels whole, exactly as the member's desk holds it, so the lead's screen and the member's show the same record; only the workspace — controls, their source, browsers, completion terms — is the member's and travels only if the provider sends it. `[]` when the member holds none; omitted only where the provider cannot see them. |
+| `listening` | Every lead on this member's call — listening, coaching or joined — published to every lead alike: each entry names the lead by `leadId`, which of the member's calls by `assignmentId`, the `mode` they are heard in, and since when. The entry naming the signed-in lead is what their own audio opens on. Absent while nobody is on the call, never `[]` (`team.member.listening.*`); a lead is on one member's call at a time (`team.listening.single`), and a lead who is heard is also in the task's `onCall` (`team.member.listening.heard`). |
 | `request` | Present while the member is asking a lead to join one of their calls: which assignment, the note they wrote, since when. The call named is one their `tasks` carry (`team.member.request.assignment`). Absent when they are not asking. See **Lead assist**. |
-| `shift` | The member's own history for the day, about the person rather than any one call: `signedInAt`, `signedOutAt` once it has happened, today's totals as the provider counts them — `talkSeconds`, `holdSeconds`, `breakSeconds`, `tasksHandled`, each present only when the provider knows it — and the day's sign-in, sign-out and break `events`, oldest first. Omitted where the provider cannot say. |
+| `shift` | The member's own history for the day, about the person rather than any one call: `signedInAt`, `signedOutAt` once it has happened, today's totals as the provider counts them — `talkSeconds`, `holdSeconds`, `breakSeconds`, `tasksHandled`, each present only when the provider knows it — and the day's sign-in, sign-out and break `events`, oldest first. The same `Shift` the member's own snapshot carries, the same numbers from the same count. Omitted where the provider cannot say. |
 
 Each availability value means one thing:
 
@@ -4236,11 +4247,19 @@ by it, as a colleague signing in is. `team-member-removed` takes one off. Never
 member, never a task of theirs on its own: a hold on a member's desk is that member republished
 whole on the lead's, and nothing else on the lead's screen moves.
 
+**The agent's day is on the wire.** The lead sees `shift` totals as the provider counts them, and
+the agent sees the same: `Snapshot.shift` and `shift-updated` carry the agent's own day in the same
+shape, from the same count, so "calls today: 12" is one number on both screens. The desk computes
+nothing of the day; `tasksHandled` moves when a task ends and `talkSeconds` when a leg closes, and
+the active call's running time is the screen's own until then, as **Every screen counts from the
+provider's clock** sets out.
+
 **Omit `since` rather than inventing one.** Omni renders it as a duration, so a timestamp
 synthesised from the adapter's own clock at seed time reads as "on task for 0 seconds" for
 everybody — worse than showing nothing, because it looks like data. Send it only when the provider
 knows when the state actually began. It times the current `availability`, so it moves every time
-that value does.
+that value does. And it is counted from the provider's clock, never the screen's, so a provider
+that publishes it declares `timeCheck` -- see **Every screen counts from the provider's clock**.
 
 **The login is the permission.** A team member list goes to a login that declares
 `capabilities.lead`, once the team feature is on, and to nobody else. Omni never decides who
@@ -4333,9 +4352,10 @@ executeTeam({ command: { type: "decline", memberId: "A-1", reason: "In a call" }
 ```
 
 **On `join` the provider bridges the lead's channel into the call.** The member's task moves to
-`leadAssist: { stage: "joined", leadId }`, the member on the team member list carries
-`listening: { assignmentId, mode: "join-call", since }`, and the lead's audio opens on it as
-**Listening to a call** describes. Nothing is a task on the lead's desk: a join is the lead's act on the team surface, not
+`leadAssist: { stage: "joined", leadId }` and its `onCall` gains the lead as an `agent`, since a
+lead who is heard is in the room; the member on the team member list carries
+`listening: [{ leadId, assignmentId, mode: "join-call", since }]`, and the lead's audio opens on
+it as **Listening to a call** describes. Nothing is a task on the lead's desk: a join is the lead's act on the team surface, not
 work assigned to them.
 
 **A lead is on one member's call at a time.** A `join` from a lead already on a call -- their own
@@ -4403,10 +4423,11 @@ history. The three modes determine who hears the lead:
 All three come with the `lead` flag; a centre reserves none of them per lead.
 
 **There is no team audio.** Audio is the agent's or the lead's, and the lead's audio while
-listening follows the provider's published state exactly as a task's does: `listening` on the
-member is the provider's word that the lead's channel is in the call. When it appears, the
-application opens `openAudio({ assignmentId })` on the lead's connection for the call it names,
-and plays the `CallAudio` returned; when it goes, the application closes it. Nothing else says
+listening follows the provider's published state exactly as a task's does: the entry naming this
+lead in `listening` on the member is the provider's word that the lead's channel is in the call.
+When it appears, the application opens `openAudio({ assignmentId })` on the lead's connection for
+the call it names, and plays the `CallAudio` returned; when it goes, the application closes it.
+Another lead's entry opens nothing: it is shown, and that is all. Nothing else says
 when the lead's audio is up, and a reload reopens it from the snapshot's team member list as a task
 carried with `audio: "started"` is reopened.
 
@@ -4417,13 +4438,15 @@ The flow, end to end:
 // 2. The lead's channel joins it in silence. Conditions: the lead's voice channel is free --
 //    not on a call, not listening elsewhere. Capacity is not involved: nothing is assigned.
 executeTeam({ command: { type: "listen", memberId: "A-1", assignmentId: "alloc-42" } })
-// 3. The provider publishes the member whole on team-member-updated; the member carries
-//    listening: { assignmentId: "alloc-42", mode: "listen", since }
-//    -- the application opens openAudio({ assignmentId: "alloc-42" }) on the lead's connection.
-// 4. The lead changes how they are heard; the member is published again with the new listening.mode. The audio stays open.
+// 3. The provider publishes the member whole on team-member-updated, to every lead; the member carries
+//    listening: [{ leadId: "L-9", assignmentId: "alloc-42", mode: "listen", since }]
+//    -- L-9's application opens openAudio({ assignmentId: "alloc-42" }) on its own connection; every
+//    other lead's shows L-9 on the call and opens nothing.
+// 4. The lead changes how they are heard; the member is published again with the entry's new mode. The audio stays open.
+//    join-call is heard by everyone, so the member's task is also republished with L-9 on onCall as an agent.
 executeTeam({ command: { type: "coach", memberId: "A-1" } })
 executeTeam({ command: { type: "join-call", memberId: "A-1" } })
-// 5. The lead leaves: the provider publishes the member without listening; the application closes the audio.
+// 5. The lead leaves: the provider publishes the member without L-9's entry, and the task without L-9 in the room; the application closes the audio.
 executeTeam({ command: { type: "leave", memberId: "A-1" } })
 // 6. The member's call ends: the same as leave, from the provider's side.
 // 7. The lead takes the call: the member loses listening no later than the offer, the application
@@ -4434,22 +4457,29 @@ executeTeam({ command: { type: "take-over-call", memberId: "A-1" } })
 // 8. A join on the member's request is the same flow entered at step 3 with mode: "join-call",
 //    and the member's task shows leadAssist: joined.
 // 9. A reload of the lead's application: the switch is sent again, the team-updated that follows
-//    still carries listening on the member, so the audio is reopened.
+//    still carries this lead's entry in listening on the member, so the audio is reopened.
 ```
 
-**`listening` on the member is the state**, restated on every change of mode, naming the call so
-the application knows which audio to open (`team.member.listening.assignmentId`, and one the
-member's tasks carry, `team.member.listening.assignment`), and a lead is on one member's call at a
-time (`team.listening.single`).
+**`listening` on the member is the state**, one entry per lead on the call, restated on every
+change of mode, naming the lead (`team.member.listening.leadId`, once per member,
+`team.member.listening.unique`) and the call, so the application knows which audio is its own to
+open (`team.member.listening.assignmentId`, and one the member's tasks carry,
+`team.member.listening.assignment`). Every lead sees every entry: a silent lead is hidden from
+the agent, never from the other leads and managers watching the same member on other screens.
+A lead is on one member's call at a time (`team.listening.single`).
 
 **A lead listens while holding no call of their own.** Omni offers Listen to a lead whose voice
 channel is free, and a provider answers a `listen` from one whose channel is not `failed`. That
 includes a lead on a break: a lead working as lead alone is on a break of a working kind, and
 listens through it.
 
-**Nothing reaches the member.** The member's task carries no trace of a listening lead in any
-mode: not on `onCall`, not in the record. Whether coaching is announced to the agent is the
-platform's business and travels on the audio, not on this wire.
+**A silent lead reaches nobody but the leads.** In `listen` and `coach` the member's task carries
+no trace of the lead: not on `onCall`, not in the record. Whether coaching is announced to the
+agent is the platform's business and travels on the audio, not on this wire. In `join-call`, and
+on a `join` answering a request, the lead is heard by everyone and is in the room: the task's
+`onCall` carries them as an `agent` by user id, on the member's desk and on every lead's copy of
+the task alike, and `leave` takes the entry off as it takes the channel off
+(`team.member.listening.heard`).
 
 ### A member waiting for a break
 
@@ -4931,6 +4961,24 @@ must specify their uncertainty and validity; elapsed time should use monotonic a
 jump invalidates the estimate. The optional check below samples provider time without changing event timestamps. Report
 source-measured durations where required; timestamp subtraction is not a substitute.
 
+#### Every screen counts from the provider's clock
+
+Two screens watching the same agent -- their own desk, their lead's, a manager's on another floor
+-- must show the same numbers. Delay between them is fine; arithmetic that differs is not. So
+nothing the desk shows is its own count, with one exception: the running duration of the active
+task or call, which each screen times from the moment it saw the call begin, and which two screens
+may therefore disagree on, since their clocks differ. Everything else comes from the wire.
+
+Durations off the active call -- how long a member has been `on-break` from their `since`, how
+long a lead has been listening, how long since `signedInAt` -- are counted from the provider's
+clock, never the screen's. The desk keeps the latest provider instant it has received -- a
+snapshot's `providerTime`, an envelope's `occurredAt`, a `checkTime` result -- with the monotonic
+elapsed time since receipt, and renders every such duration from that; a sample older than
+`maxSampleAgeMs` is refreshed with `checkTime`. Without a usable sample the desk shows the instant
+and no count. A provider that publishes any of these instants therefore declares `timeCheck`
+(`manifest.timeCheck.required`) and states `providerTime` on every snapshot
+(`snapshot.providerTime`). Two screens then differ by their delay and nothing else.
+
 #### Optional periodic provider time checks and agent application estimates
 
 A provider may declare `Manifest.timeCheck: true` and implement `Connection.checkTime(request)`.
@@ -5316,6 +5364,13 @@ the `contacts` idle capability.
 Replaces this provider's complete scheduled-activity contribution. It is emitted only when the manifest
 declares the `calendar` idle capability.
 
+### `shift-updated`
+
+The agent's own day, whole, replacing `Snapshot.shift`: emitted whenever a total moves -- a task
+ended, a break ended, a sign-out -- and never to say nothing changed. It carries the same `Shift`
+the agent's lead sees for them on the team member list, so the two screens show one day. See
+**The agent's day is on the wire**.
+
 ## Utilities
 
 ### `assignmentKey(providerId, assignmentId)`
@@ -5380,7 +5435,9 @@ carries that agent reports `team.member.self`, on a `team-member-updated` and a
 reports `team.unentitled`, and a team event to such a login reports `event.team.capability`; given
 `leadFeatures: true`, a snapshot without a team reports `team.required`, and given `leadFeatures: false`,
 anything of the team reaching the lead reports `team.unexpected` or `event.team.features`. Without them those rules are not checked, because they cannot be.
-`exerciseAdapter` passes all three, holding the switch off until it has sent it.
+`exerciseAdapter` passes all three, holding the switch off until it has sent it. Given the manifest, a
+snapshot or event that carries an instant the desk renders as a running duration under a manifest
+without `timeCheck` reports `manifest.timeCheck.required`.
 
 `assertNoViolations(violations)` throws `ProtocolConformanceError` — which carries the full
 `violations` array — when the list is non-empty.

package/package.json

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