@xema/omni-protocol 0.1.30 → 0.1.31

package/dist/validation.js

@@ -632,6 +632,7 @@ function validateHandlingHistory(value, path, into) {
         into.add("task.handlingHistory.shape", path, "handlingHistory must be an array when present");
         return;
     }
+    let previous;
     value.forEach((entry, index) => {
         const at = `${path}[${index}]`;
         if (!isPlainObject(entry)) {
@@ -639,7 +640,15 @@ function validateHandlingHistory(value, path, into) {
             return;
         }
         into.oneOf(entry.step, HANDLING_STEPS, "task.handlingHistory.step", `${at}.step`);
-        into.timestamp(entry.at, "task.handlingHistory.at", `${at}.at`);
+        if (into.timestamp(entry.at, "task.handlingHistory.at", `${at}.at`)) {
+            // The record is one entry per occurrence, oldest first: a second hold is a second entry
+            // after the first, never a revision of it or an entry filed out of its turn.
+            const instant = Date.parse(entry.at);
+            if (previous !== undefined && instant < previous) {
+                into.add("task.handlingHistory.order", `${at}.at`, "handling steps are oldest first; this entry is earlier than the one before it");
+            }
+            previous = instant;
+        }
         if (entry.seconds !== undefined) {
             // Omitted while a leg is still running. Nought is a claim that it took no time.
             into.require(isDurationSeconds(entry.seconds) && entry.seconds > 0, "task.handlingHistory.seconds", `${at}.seconds`, "seconds must be a positive whole number; omit it while the step is still running");

package/guide.md

@@ -2260,6 +2260,8 @@ const immediateProviderCompletion = {
 handlingHistory: [
   { step: "queued",   at: "2026-08-21T00:59:00Z", seconds: 41 },
   { step: "answered", at: "2026-08-21T00:59:41Z", by: "a-17" },
+  { step: "held",     at: "2026-08-21T01:02:10Z", seconds: 35, by: "a-17" },
+  { step: "held",     at: "2026-08-21T01:06:48Z", by: "a-17" },
 ]
 ```
 
@@ -2273,6 +2275,16 @@ It rides in the snapshot and is replaced whole like everything else there.
 Steps are `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `conferenced`,
 `unanswered`, and each is defined on `TaskHandlingStep`.
 
+**The record is one entry per occurrence, oldest first.** Each hold is its own `held` entry — `at`
+when it began, `seconds` once it ended and omitted while it runs — and a second hold is a second
+entry after the first, never a revision of it. The same goes for every step: two mutes are two
+`muted` entries. Order is enforced: an entry earlier than the one before it is refused
+(`task.handlingHistory.order`). **Handle time is anchored, not restarted.** It runs from the
+`answered` step's `at` — from the task's first `in-progress` where the provider reports no
+history — until the task's media ends, and a hold neither pauses nor resets it: the hold's own
+duration is the `held` entry's `seconds`, and a desk that restarts its counter on resume is
+counting the wrong thing.
+
 `muted` is there because Omni performs the mute rather than the provider — see **Where a command
 executes** — so without a step the one participant that keeps the task's record would have no
 account of a period the agent could not be heard.

package/package.json

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