platform-types 1.10.709 → 1.10.710

package/dist/cjs/cycleCount.js

@@ -124,7 +124,16 @@ exports.isOverCycleCountToleranceRule = isOverCycleCountToleranceRule;
  * - `CYCLE_COUNT_VERSION_CONFLICT` · 409 — a cancel or finalise that lost the
  *   compare-and-set on the session row. ⚠️ On finalise it is CONDITIONAL: the
  *   handler re-reads consistently, and a winner that FINALISED the session makes
- *   it a `200` replay instead; only a concurrent CANCEL surfaces as this.
+ *   it a `200` replay instead; only a concurrent CANCEL surfaces as this. Never
+ *   answered to `mode: 'edit'`.
+ * - `CYCLE_COUNT_CONTENT_CONFLICT` · 409 — the session is still `open` but no
+ *   longer at the revision the request was composed against; top-level
+ *   `currentUpdatedAt` is the revision to re-send after re-reviewing, and
+ *   nothing was written. ONE meaning in both modes: a finalise whose lines or
+ *   tolerance moved (or whose `expectedUpdatedAt` was stale on arrival), and an
+ *   edit whose `expectedUpdatedAt` is stale — on arrival or overtaken before
+ *   the write — or a token-less edit overtaken on both of its attempts. On an
+ *   edit `data` is {@link CycleCountEditConflict}.
  * - `CYCLE_COUNT_TOLERANCE_EXCEEDED` · 403 — a finalise with at least one
  *   over-tolerance line, from a caller who is neither ADMIN nor MANAGER. The
  *   session stays `open` and NO stock moved.
@@ -187,12 +196,13 @@ exports.CYCLE_COUNT_ERROR_CODES = [
     'CYCLE_COUNT_NOT_OPEN',
     'CYCLE_COUNT_ILLEGAL_TRANSITION',
     'CYCLE_COUNT_VERSION_CONFLICT',
-    // Finalise refuses a session whose COUNTED CONTENT moved since the caller's
-    // read, distinct from the row-version conflict above: the caller's revision
-    // is stale, and committing it would finalise a count nobody took. Answered
-    // by `cycle-counts/_finalize.ts`; landed one PR after this list was
-    // published, and the guard test that keeps this list honest caught it on
-    // `main` rather than in either PR's own gate.
+    // The session is still open but its revision moved since the caller's read,
+    // distinct from the row-version conflict above (the session went terminal):
+    // committing would finalise a count nobody took, or overwrite lines nobody
+    // reviewed. Answered by `cycle-counts/_finalize.ts` and `_edit.ts`. The
+    // finalise case landed one PR after this list was published, and the guard
+    // test that keeps this list honest caught it on `main` rather than in either
+    // PR's own gate.
     'CYCLE_COUNT_CONTENT_CONFLICT',
     'CYCLE_COUNT_TOLERANCE_EXCEEDED',
     // Finalise refuses a line that is neither counted nor skipped rather than

package/dist/cycleCount.d.ts

@@ -187,8 +187,9 @@ declare global {
         /** Unix ms the session was opened. */
         createdAt: number;
         /**
-         * Unix ms of the last write. ABSENT on a session never revised since it
-         * was opened — this platform is forward-only and nothing backfills it.
+         * Unix ms of the last write. Stamped at creation too, so ABSENT only on a
+         * legacy row written before that — this platform is forward-only and
+         * nothing backfills it.
          *
          * ⚠️ **`updatedAt ?? createdAt` is the session's VERSION TOKEN**, and
          * `POST /cycle-counts { mode: 'finalize' }` accepts it as the OPTIONAL
@@ -211,8 +212,28 @@ declare global {
          * an already-`finalized` session, deliberately: a consumer that collapses
          * the three cannot tell "re-confirm" from "it is over" from "it already
          * landed".
+         *
+         * ⚠️ `mode: 'edit'` accepts the same token as its OPTIONAL
+         * `expectedUpdatedAt` ({@link CycleCountEditRequest}), refusing a stale one on
+         * a still-`open` session with the SAME `409 CYCLE_COUNT_CONTENT_CONFLICT` and
+         * top-level `currentUpdatedAt`, plus the current row as `data.current` — so
+         * one client handler serves both modes.
          */
         updatedAt?: number;
+        /**
+         * The operator whose `mode: 'edit'` wrote the current revision, stamped by
+         * the server on EVERY edit. ABSENT on a session never edited since it was
+         * opened (and on every edit made before this field existed — nothing is
+         * backfilled). Only `mode: 'edit'` writes it: a finalise records
+         * `finalizedBy`, and a cancel leaves it as it was.
+         *
+         * Read it on an edit's `409 CYCLE_COUNT_CONTENT_CONFLICT` `data.current`: own
+         * actor plus every field the caller sent being identical is CONSISTENT
+         * with the caller's own earlier edit having landed — never proof of it,
+         * since this is a user id and the same operator on a second device reads
+         * the same.
+         */
+        updatedBy?: string;
         /** The operator who opened it. */
         userId: string;
         status: CycleCountStatus;
@@ -472,6 +493,55 @@ declare global {
         /** Why the line was skipped. Only with `skippedAt`. ⚠️ Never personal data — same un-scrubbed, TTL-less row as `note`. */
         skippedReason?: string;
     }
+    /**
+     * `POST /cycle-counts { mode: 'edit' }` — revise an OPEN session. At least one
+     * of `items`, `dated`, `name`, `zone`, `notes`, `tolerancePercent` is
+     * required; `expectedUpdatedAt` alone is refused 400.
+     *
+     * ⚠️ `items` is a WHOLE-ARRAY replace, never a per-line merge.
+     */
+    interface CycleCountEditRequest {
+        mode: 'edit';
+        cycleCountId: string;
+        items?: CycleCountItem[];
+        /** `YYYYMMDD`, as a string or a number. */
+        dated?: string | number;
+        name?: string;
+        zone?: string;
+        notes?: string;
+        /** `null` CLEARS the per-count rung, returning the session to the store default. */
+        tolerancePercent?: number | null;
+        /**
+         * The revision the operator REVIEWED — {@link CycleCount.updatedAt} `??`
+         * {@link CycleCount.createdAt} of the row the screen shows, read from
+         * `GET /cycle-counts?cycleCountId=` (strongly consistent).
+         *
+         * When sent, the write is fenced on it: a session still `open` but revised
+         * since is refused `409 CYCLE_COUNT_CONTENT_CONFLICT` — the code a finalise
+         * answers for the same case — with the revision to re-send as top-level
+         * `currentUpdatedAt` and the current {@link CycleCount} as `data.current`,
+         * and NOTHING is written. Compare `current.updatedBy` and EVERY field that
+         * was sent: a match is consistent with an own edit whose response was lost
+         * (not proof — same user, another device, reads the same); anything else is
+         * another write. Never retry automatically. A session that went terminal
+         * underneath stays `409 CYCLE_COUNT_NOT_OPEN`.
+         *
+         * Optional for compatibility: omitted, the edit is NOT fenced on a
+         * revision — last writer wins, as before. The server still stamps the new
+         * revision strictly past the stored one, re-reading and retrying once when
+         * a concurrent edit took that value first, so it never re-issues a token
+         * another client holds; a session that churns through both attempts is
+         * answered the same `409 CYCLE_COUNT_CONTENT_CONFLICT`.
+         */
+        expectedUpdatedAt?: number;
+    }
+    /**
+     * `data` of a `409 CYCLE_COUNT_CONTENT_CONFLICT` answered to `mode: 'edit'`
+     * (a finalise's carries no `data`; both carry top-level `currentUpdatedAt`).
+     */
+    interface CycleCountEditConflict {
+        current: CycleCount;
+    }
 }
 export {};
 /**
@@ -557,7 +627,16 @@ export declare const isOverCycleCountToleranceRule: (input: {
  * - `CYCLE_COUNT_VERSION_CONFLICT` · 409 — a cancel or finalise that lost the
  *   compare-and-set on the session row. ⚠️ On finalise it is CONDITIONAL: the
  *   handler re-reads consistently, and a winner that FINALISED the session makes
- *   it a `200` replay instead; only a concurrent CANCEL surfaces as this.
+ *   it a `200` replay instead; only a concurrent CANCEL surfaces as this. Never
+ *   answered to `mode: 'edit'`.
+ * - `CYCLE_COUNT_CONTENT_CONFLICT` · 409 — the session is still `open` but no
+ *   longer at the revision the request was composed against; top-level
+ *   `currentUpdatedAt` is the revision to re-send after re-reviewing, and
+ *   nothing was written. ONE meaning in both modes: a finalise whose lines or
+ *   tolerance moved (or whose `expectedUpdatedAt` was stale on arrival), and an
+ *   edit whose `expectedUpdatedAt` is stale — on arrival or overtaken before
+ *   the write — or a token-less edit overtaken on both of its attempts. On an
+ *   edit `data` is {@link CycleCountEditConflict}.
  * - `CYCLE_COUNT_TOLERANCE_EXCEEDED` · 403 — a finalise with at least one
  *   over-tolerance line, from a caller who is neither ADMIN nor MANAGER. The
  *   session stays `open` and NO stock moved.

package/dist/cycleCount.js

@@ -119,7 +119,16 @@ export const isOverCycleCountToleranceRule = (input, tolerancePercent) => {
  * - `CYCLE_COUNT_VERSION_CONFLICT` · 409 — a cancel or finalise that lost the
  *   compare-and-set on the session row. ⚠️ On finalise it is CONDITIONAL: the
  *   handler re-reads consistently, and a winner that FINALISED the session makes
- *   it a `200` replay instead; only a concurrent CANCEL surfaces as this.
+ *   it a `200` replay instead; only a concurrent CANCEL surfaces as this. Never
+ *   answered to `mode: 'edit'`.
+ * - `CYCLE_COUNT_CONTENT_CONFLICT` · 409 — the session is still `open` but no
+ *   longer at the revision the request was composed against; top-level
+ *   `currentUpdatedAt` is the revision to re-send after re-reviewing, and
+ *   nothing was written. ONE meaning in both modes: a finalise whose lines or
+ *   tolerance moved (or whose `expectedUpdatedAt` was stale on arrival), and an
+ *   edit whose `expectedUpdatedAt` is stale — on arrival or overtaken before
+ *   the write — or a token-less edit overtaken on both of its attempts. On an
+ *   edit `data` is {@link CycleCountEditConflict}.
  * - `CYCLE_COUNT_TOLERANCE_EXCEEDED` · 403 — a finalise with at least one
  *   over-tolerance line, from a caller who is neither ADMIN nor MANAGER. The
  *   session stays `open` and NO stock moved.
@@ -182,12 +191,13 @@ export const CYCLE_COUNT_ERROR_CODES = [
     'CYCLE_COUNT_NOT_OPEN',
     'CYCLE_COUNT_ILLEGAL_TRANSITION',
     'CYCLE_COUNT_VERSION_CONFLICT',
-    // Finalise refuses a session whose COUNTED CONTENT moved since the caller's
-    // read, distinct from the row-version conflict above: the caller's revision
-    // is stale, and committing it would finalise a count nobody took. Answered
-    // by `cycle-counts/_finalize.ts`; landed one PR after this list was
-    // published, and the guard test that keeps this list honest caught it on
-    // `main` rather than in either PR's own gate.
+    // The session is still open but its revision moved since the caller's read,
+    // distinct from the row-version conflict above (the session went terminal):
+    // committing would finalise a count nobody took, or overwrite lines nobody
+    // reviewed. Answered by `cycle-counts/_finalize.ts` and `_edit.ts`. The
+    // finalise case landed one PR after this list was published, and the guard
+    // test that keeps this list honest caught it on `main` rather than in either
+    // PR's own gate.
     'CYCLE_COUNT_CONTENT_CONFLICT',
     'CYCLE_COUNT_TOLERANCE_EXCEEDED',
     // Finalise refuses a line that is neither counted nor skipped rather than

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.709",
+	"version": "1.10.710",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",