platform-types 1.10.708 → 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/cjs/serviceOrder.js

@@ -180,6 +180,9 @@ exports.MAX_SERVICE_PICTURES = 20;
  *   someone else wrote the ticket between your read and your write, and nothing
  *   of yours was written. Refetch and let the operator retry against the new
  *   state — the body that lost was built on the old one.
+ *   `_EDIT_CHANGED` also answers a stale `expectedUpdatedAt`
+ *   ({@link ServiceOrderRevisionFence}) and carries the current row as
+ *   {@link ServiceOrderEditChangedRefusal}.
  * - `SERVICE_ORDER_ILLEGAL_TRANSITION` · 409 — the body is
  *   {@link ServiceOrderIllegalTransitionRefusal}; its `allowed[]` is the menu to
  *   offer instead.

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/dist/serviceOrder.d.ts

@@ -1170,6 +1170,109 @@ declare global {
         message: string;
         allowed: readonly ServiceCustody[];
     }
+    /**
+     * Optional revision fence on `POST /services` `mode: 'edit'` and
+     * `mode: 'diagnosis'` — request-only, never persisted or returned.
+     *
+     * Send the `updatedAt` of the {@link ServiceOrder} the operator REVIEWED
+     * (from `GET /services/{id}`, a strong read; for a row carrying no
+     * `updatedAt`, its `createdAt`). The write is refused `409
+     * SERVICE_ORDER_EDIT_CHANGED` — body {@link ServiceOrderEditChangedRefusal},
+     * nothing written — when `updatedAt` has moved since, both at the handler's
+     * read and again at the commit. A refusal at the read uploads and deletes no
+     * photo; one at the commit deletes none, but bytes already uploaded for new
+     * photos stay in storage unreferenced.
+     *
+     * **What the fence sees.** `updatedAt` moves on every write of an
+     * operator-entered field, and only those: every `POST /services` mode that
+     * writes the row — `create`, `edit`, `diagnosis`, `hold`, `quote`, `parts`,
+     * `worklog`, `timer` (the stop that books the hours), `deposit`, `status`
+     * (including the delivery mint) and `disable`. It does NOT see system
+     * bookkeeping that leaves `updatedAt` alone, deliberately so a phone is not
+     * sent back to re-review for it: the appointment link
+     * (`appointmentId`/`appointmentDate`/`appointmentTime`, written by
+     * `/appointments`), the invoice stamp (`invoiceId`, written when a factura
+     * settles or is rejected), and notification bookkeeping (`notifiedAt`,
+     * appended by `status` and `renotify`). Those fields can differ from what the
+     * client reviewed while its fenced write still succeeds.
+     *
+     * **Chained writes.** A follow-up write in the same submission — a diagnosis
+     * then a photo edit — fences on the PREVIOUS write's success response,
+     * `data.updatedAt`, never on the revision first reviewed: the first write
+     * moved it, so echoing the original value refuses the second. Both success
+     * bodies carry it — `diagnosis` returns the committed row, `edit` the row
+     * with the `updatedAt` it committed.
+     *
+     * On `diagnosis` a TERMINAL ticket still answers its own codes first
+     * (`SERVICE_ORDER_TERMINAL` at the read, `SERVICE_ORDER_STATUS_CHANGED` when
+     * it closed mid-request), and the stored `diagnosedBy`/`diagnosedAt` stay
+     * server-stamped.
+     *
+     * Absent means today's behaviour: the handler's own read is the lock (`edit`)
+     * or no revision is asserted at all (`diagnosis`).
+     */
+    interface ServiceOrderRevisionFence {
+        expectedUpdatedAt?: number;
+    }
+    /**
+     * The `409 SERVICE_ORDER_EDIT_CHANGED` body of `POST /services`
+     * `mode: 'edit'` and `mode: 'diagnosis'`. `data.current` is the stored row as
+     * a strong read returns it now — without the read-time derivations
+     * (`customer`, `depositBalance`, `slaStatus`); refetch the point read for
+     * those.
+     *
+     * `data` is absent when the row could not be re-read (both modes), and on
+     * `edit` also when the row no longer exists — refetch the point read. A
+     * fenced `diagnosis` whose row is gone answers `SERVICE_ORDER_STATUS_CHANGED`
+     * instead, as it does unfenced.
+     */
+    interface ServiceOrderEditChangedRefusal {
+        error: 'SERVICE_ORDER_EDIT_CHANGED';
+        message: string;
+        data?: {
+            current: ServiceOrder;
+        };
+    }
+    /**
+     * The body of `POST /services` `mode: 'diagnosis'`: it REPLACES the stored
+     * `diagnosis` whole. `diagnosedBy`/`diagnosedAt` are not accepted — the api
+     * stamps the authorizer user and the server time. Success answers the
+     * committed {@link ServiceOrder} as `data`.
+     *
+     * Tied to the handler's schema by `AssertServiceOrderDiagnosisRequestMatchesSchema`
+     * (`stacks/lambdas/services/_diagnosis.ts`).
+     */
+    interface ServiceOrderDiagnosisRequest extends ServiceOrderRevisionFence {
+        mode: 'diagnosis';
+        serviceOrderId: string;
+        /** Internal technician notes, 1–4000 characters. Operator-only. */
+        notes: string;
+        /** What was actually wrong, as told to the customer — at most 4000 characters. */
+        faultFound?: string;
+    }
+    /**
+     * The photo-only body of `POST /services` `mode: 'edit'` — the edit a
+     * technician's phone sends. The mode accepts more fields; this names only the
+     * photo half, so a client typed on it cannot send anything else by accident.
+     *
+     * `pictures` ABSENT means "don't touch", `[]` means "clear"; it is the WHOLE
+     * array, at most {@link MAX_SERVICE_PICTURES} entries. An entry with `base64`
+     * is a new upload (its `url` is a placeholder the api replaces); one without
+     * is a pointer to a photo already on THIS ticket, and may not change its
+     * `stage`. `removePictures` names stored photos to delete after the commit.
+     * Success answers the updated {@link ServiceOrder} as `data`.
+     *
+     * Tied to the handler's schema by `AssertServiceOrderEditPicturesRequestMatchesSchema`
+     * (`stacks/lambdas/services/_edit.ts`).
+     */
+    interface ServiceOrderEditPicturesRequest extends ServiceOrderRevisionFence {
+        mode: 'edit';
+        serviceOrderId: string;
+        pictures?: ServiceOrderPicture[];
+        removePictures?: {
+            url: string;
+        }[];
+    }
 }
 /**
  * The legal moves on a service order. Exhaustive over `ServiceStatus` by
@@ -1294,6 +1397,9 @@ export declare const MAX_SERVICE_PICTURES = 20;
  *   someone else wrote the ticket between your read and your write, and nothing
  *   of yours was written. Refetch and let the operator retry against the new
  *   state — the body that lost was built on the old one.
+ *   `_EDIT_CHANGED` also answers a stale `expectedUpdatedAt`
+ *   ({@link ServiceOrderRevisionFence}) and carries the current row as
+ *   {@link ServiceOrderEditChangedRefusal}.
  * - `SERVICE_ORDER_ILLEGAL_TRANSITION` · 409 — the body is
  *   {@link ServiceOrderIllegalTransitionRefusal}; its `allowed[]` is the menu to
  *   offer instead.

package/dist/serviceOrder.js

@@ -177,6 +177,9 @@ export const MAX_SERVICE_PICTURES = 20;
  *   someone else wrote the ticket between your read and your write, and nothing
  *   of yours was written. Refetch and let the operator retry against the new
  *   state — the body that lost was built on the old one.
+ *   `_EDIT_CHANGED` also answers a stale `expectedUpdatedAt`
+ *   ({@link ServiceOrderRevisionFence}) and carries the current row as
+ *   {@link ServiceOrderEditChangedRefusal}.
  * - `SERVICE_ORDER_ILLEGAL_TRANSITION` · 409 — the body is
  *   {@link ServiceOrderIllegalTransitionRefusal}; its `allowed[]` is the menu to
  *   offer instead.

package/package.json

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