docs(automation): three declaration-truth residues on the run-history row — a one-way discriminator, the row's step log, and the write that names its reader (#17549)

* docs(automation): correct three declaration-truth residues on the run-history row

`variables_json`'s description stated presence and "this run had a pause its
resume consumed" as EQUIVALENT. Only the forward direction is true: the
terminal write is an upsert that always writes the four snapshot columns,
NULL included, so a run that stranded, was restored and then finished has its
row rewritten with NULLs — leaving it indistinguishable, in exactly those
columns, from a run that never paused. The text is what was wrong; the
clearing is the ruled design, and nothing reads the reverse direction.

`deserializeConsumedSuspension` described the rebuilt snapshot's steps as the
step log AS OF THE PAUSE. That is true of the engine's process-local journal
copy only (it slices `run.steps` back to the step count at the pause); the
row's `steps_json` is the terminal row's log of the WHOLE run, and both bounds
on it — history compaction and the byte cap — deliberately keep the failure
and trim the head.

`recordTerminal` now names the verb that reads what it writes, and the three
properties of this write that are that verb's inputs. Its summary line also
said "completed / failed" where the terminal vocabulary has had four members
since #15223.

Pins the two falsifying shapes in `suspended-run-store.test.ts`; the
cross-reference has no executable surface and is not pinned.

Claude-Session: https://claude.ai/code/session_01ToDPcx9AESFubJkDiFMtKW
Co-authored-by: Claude <noreply@anthropic.com>

* chore(changeset): patch for the run-history declaration-truth corrections

The `variables_json` description reaches `dist/index.js` and `dist/index.cjs`,
and `recordTerminal`'s docblock reaches `dist/index.d.ts` — measured on the
built tree against this package's own `files[]`, with a pre-existing
description as the positive control and the module-private docblock (0 hits,
comments stripped) as the negative one. Published bytes move, so this is a
`patch`, not `skip-changeset`.

Claude-Session: https://claude.ai/code/session_01ToDPcx9AESFubJkDiFMtKW
Co-authored-by: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/automation-run-declaration-truth-residues.md

@@ -0,0 +1,45 @@
+---
+'@objectstack/service-automation': patch
+---
+
+`sys_automation_run.variables_json` states its presence discriminator in ONE direction, and a row-rebuilt snapshot no longer claims its steps are the pause's
+
+Three corrections to text this package ships. No behaviour changes; every shape
+described below is the ruled design, measured as it already is.
+
+**`variables_json` said `⇔` where only `⇒` holds.** The field description
+declared "present on a completed/failed row" and "the row's run had a pause its
+resume consumed before a downstream node failed" to be equivalent. The forward
+direction holds — nothing but the consumed-suspension path writes that column on
+a terminal row. The reverse does not, for one shape: a run that stranded, was
+restored and then finished. `recordTerminal` upserts the SAME `run_<id>` row
+with all four snapshot columns explicitly `null` — deliberately, so
+"restorable" cannot outlive the condition it describes — which leaves that row
+equal, across every column the discriminator is read from, to the row of a run
+that never paused at all. Absence means "nothing to restore now", never "this
+run never had one", and the restore verb already refuses in exactly those terms:
+it names the status it observed and declines to say which. The description now
+says so.
+
+**A snapshot rebuilt from a row does not carry the step log as of the pause.**
+`deserializeConsumedSuspension`'s docblock said its `steps` are the log "AS OF
+THE PAUSE". That is true of the engine's process-local journal copy only, which
+slices `run.steps` back to the step count at the pause; the trimmed array is
+never persisted. `steps` are the one field the rebuild takes from the row's own
+`steps_json`, which is the terminal row's log of the WHOLE run — and both bounds
+on that column keep the failure on purpose (history compaction retains every
+failure; the byte cap trims the head). A row-rebuilt snapshot therefore carries
+steps the pause did not have. It re-arms the same run regardless: the pause is
+`nodeId` plus `variables` / `context` / `correlation`, none of which the step log
+feeds.
+
+**`recordTerminal` now names the verb that reads what it writes** — the
+restore path in `engine.ts` — and the three properties of the write that are
+that verb's inputs rather than local detail. Its summary line also said
+"completed / failed" where the terminal vocabulary has had four members since
+the fold was removed from both ends of this write.
+
+Both falsifying shapes are pinned in `suspended-run-store.test.ts`, including the
+indistinguishability itself: the restored-then-finished row and a never-paused
+row compare equal across those five columns, with the same comparison separating
+them while the snapshot is still there.

packages/services/service-automation/src/suspended-run-store.test.ts

@@ -467,6 +467,182 @@ describe('ObjectStoreSuspendedRunStore — run-history retention + durable detai
     });
 });
 
+// ─── What a terminal row does NOT say (#15336) ───────────────────────────────
+
+/**
+ * [#15336] Two declaration-truth residues of #13909 / #13937, each pinned by
+ * the SHAPE that falsifies the sentence rather than by the sentence.
+ *
+ *  1. ⭐ `variables_json`'s presence discriminator holds ONE WAY. The object
+ *     declared presence and "this run had a pause its resume consumed" as
+ *     equivalent; the reverse fails for a run that stranded, was restored and
+ *     then finished. `recordTerminal` upserts the SAME `run_<id>` row with all
+ *     four snapshot columns explicitly NULL — deliberately, so "restorable"
+ *     cannot outlive the condition — which leaves that row byte-identical, in
+ *     those columns, to the row of a run that never paused at all. The second
+ *     test measures that indistinguishability directly, so the claim is not
+ *     "the column is null" but "no reader can recover the difference".
+ *  2. ⭐ A snapshot rebuilt FROM A ROW does not carry the step log as of the
+ *     pause. `steps` are the one field `deserializeConsumedSuspension` takes
+ *     from the row's own `steps_json` rather than from the snapshot, and that
+ *     column holds the WHOLE run's compacted log — the failed attempt
+ *     included. Only the engine's process-local journal trims back to the step
+ *     count at the pause, and that trimmed array is never persisted.
+ *
+ * ⛔ Neither is a behaviour change: both shapes are the ruled design (a
+ * restored run MUST clear what it carried; the terminal row's step log MUST
+ * keep the failure). What was wrong was the text, and these pins are what stop
+ * the corrected text from decaying back.
+ */
+describe('ObjectStoreSuspendedRunStore — what a terminal row does NOT say (#15336)', () => {
+    /** The pause a strand's resume consumed — two steps, as of the pause. */
+    const pauseSnapshot = (): SuspendedRun => ({
+        runId: 'strandy',
+        flowName: 'busy_flow',
+        nodeId: 'hold',
+        nodeType: 'hold',
+        variables: { approved: true },
+        steps: [
+            { nodeId: 'start', nodeType: 'start', status: 'success', startedAt: '2026-01-01T00:00:01.000Z' },
+            { nodeId: 'hold', nodeType: 'hold', status: 'success', startedAt: '2026-01-01T00:00:02.000Z' },
+        ],
+        context: { object: 'crm_deal', tenantId: 'org_1' } as any,
+        startedAt: '2026-01-01T00:00:00.000Z',
+        startTime: 1735689600000,
+        correlation: 'areq_9',
+    });
+
+    /** The step log `recordLog` hands the store: the pause's steps AND the
+     *  failed attempt that ran after the resume consumed it. */
+    const wholeRunSteps = (): RunRecord['steps'] => [
+        ...pauseSnapshot().steps,
+        {
+            nodeId: 'tail', nodeType: 'script', status: 'failure',
+            startedAt: '2026-01-01T00:00:03.000Z',
+            error: { code: 'TAIL_FAILED', message: 'tail exploded' },
+        },
+    ];
+
+    /** The strand: a resume consumed the pause, then a downstream node threw. */
+    const strandRecord = (): RunRecord => ({
+        runId: 'strandy',
+        flowName: 'busy_flow',
+        status: 'failed',
+        startedAt: '2026-01-01T00:00:00.000Z',
+        error: 'tail exploded',
+        // The PAUSE node, not the node that threw (#13937).
+        nodeId: 'hold',
+        steps: wholeRunSteps(),
+        consumedSuspension: pauseSnapshot(),
+    });
+
+    it('writes the snapshot on the strand, then CLEARS all four columns when the restored run finishes', async () => {
+        const engine = createFakeEngine();
+        const store = new ObjectStoreSuspendedRunStore(engine, createTestLogger());
+
+        await store.recordTerminal(strandRecord());
+        const stranded = engine.rows.get('run_strandy');
+        // Positive control for the nulls below: the row really did carry a
+        // restorable snapshot, in all four columns, before the second write.
+        expect(typeof stranded.variables_json).toBe('string');
+        expect(stranded.node_type).toBe('hold');
+        expect(stranded.correlation).toBe('areq_9');
+        expect((await store.loadTerminal('strandy'))!.consumedSuspension).toBeDefined();
+
+        // …an operator restores it, the run resumes and this time it finishes.
+        await store.recordTerminal({
+            runId: 'strandy',
+            flowName: 'busy_flow',
+            status: 'completed',
+            startedAt: '2026-01-01T00:00:00.000Z',
+            steps: wholeRunSteps(),
+        });
+
+        // The SAME row — an upsert, not a second history row.
+        expect(engine.rows.size).toBe(1);
+        const finished = engine.rows.get('run_strandy');
+        expect(finished.variables_json).toBeNull();
+        expect(finished.context_json).toBeNull();
+        expect(finished.screen_json).toBeNull();
+        expect(finished.node_type).toBeNull();
+        expect(finished.correlation).toBeNull();
+
+        const reread = (await store.loadTerminal('strandy'))!;
+        expect(reread.status).toBe('completed');
+        expect(reread.consumedSuspension).toBeUndefined();
+        // Not the drop notice either: the snapshot was not too big, it is gone
+        // because the run that carried it moved on.
+        expect(reread.consumedSuspensionDropped).toBeUndefined();
+    });
+
+    it('⛔ leaves that row indistinguishable from a run that NEVER paused — the direction the column cannot answer', async () => {
+        const engine = createFakeEngine();
+        const store = new ObjectStoreSuspendedRunStore(engine, createTestLogger());
+
+        // A run that stranded, was restored, and finished.
+        await store.recordTerminal(strandRecord());
+        await store.recordTerminal({
+            runId: 'strandy', flowName: 'busy_flow', status: 'completed',
+            startedAt: '2026-01-01T00:00:00.000Z', steps: wholeRunSteps(),
+        });
+        // A run that never paused at all, same flow, same shape of log.
+        await store.recordTerminal({
+            runId: 'plain', flowName: 'busy_flow', status: 'completed',
+            startedAt: '2026-01-01T00:00:00.000Z', steps: wholeRunSteps(),
+        });
+
+        const columns = (id: string) => {
+            const row = engine.rows.get(id);
+            return {
+                variables_json: row.variables_json, context_json: row.context_json,
+                screen_json: row.screen_json, node_type: row.node_type, correlation: row.correlation,
+            };
+        };
+        // The whole finding, in one assertion: the row of a run that DID have a
+        // consumed suspension and the row of one that never had any are equal
+        // across every column the discriminator is read from.
+        expect(columns('run_strandy')).toEqual(columns('run_plain'));
+        // Firing control — the same comparison DOES separate them while the
+        // snapshot is still on the row, so the equality above is a measurement
+        // and not a comparison of two things this helper cannot see.
+        const engine2 = createFakeEngine();
+        const store2 = new ObjectStoreSuspendedRunStore(engine2, createTestLogger());
+        await store2.recordTerminal(strandRecord());
+        await store2.recordTerminal({
+            runId: 'plain', flowName: 'busy_flow', status: 'completed',
+            startedAt: '2026-01-01T00:00:00.000Z', steps: wholeRunSteps(),
+        });
+        const columns2 = (id: string) => {
+            const row = engine2.rows.get(id);
+            return {
+                variables_json: row.variables_json, context_json: row.context_json,
+                screen_json: row.screen_json, node_type: row.node_type, correlation: row.correlation,
+            };
+        };
+        expect(columns2('run_strandy')).not.toEqual(columns2('run_plain'));
+    });
+
+    it('rebuilds a row snapshot with the WHOLE run\'s step log — ⛔ not the steps as of the pause', async () => {
+        const engine = createFakeEngine();
+        const store = new ObjectStoreSuspendedRunStore(engine, createTestLogger());
+        await store.recordTerminal(strandRecord());
+
+        const rebuilt = (await store.loadTerminal('strandy'))!.consumedSuspension!;
+        // Positive control: the rebuild IS the snapshot's — every field that
+        // comes from the four snapshot columns round-trips.
+        expect(rebuilt.nodeId).toBe('hold');
+        expect(rebuilt.nodeType).toBe('hold');
+        expect(rebuilt.correlation).toBe('areq_9');
+        expect(rebuilt.variables).toEqual({ approved: true });
+
+        // `steps` alone do not: they are the terminal row's log, so the failed
+        // attempt the pause never saw comes back inside the "snapshot".
+        expect(rebuilt.steps).toEqual(wholeRunSteps());
+        expect(rebuilt.steps).not.toEqual(pauseSnapshot().steps);
+        expect(rebuilt.steps.map((s) => s.nodeId)).toContain('tail');
+    });
+});
+
 // ─── Trigger attribution columns (#7533) ─────────────────────────────────────
 //
 // The defect was information dropped ON THE WAY TO THE ROW, so these assertions

packages/services/service-automation/src/suspended-run-store.ts

@@ -624,11 +624,33 @@ export class ObjectStoreSuspendedRunStore implements SuspendedRunStore {
   }
 
   /**
-   * Persist a TERMINAL run (completed / failed) as durable history. Keyed by a
-   * `run_`-prefixed id so it NEVER collides with a live suspended run's row
-   * (id = raw `runId`, status `paused`) — the suspend save/load/delete/list
-   * path (which only touches raw ids and `status:'paused'` rows) is untouched.
-   * Upsert so a re-emitted terminal (e.g. a resumed run) updates in place.
+   * Persist a TERMINAL run as durable history — whichever member of the one
+   * terminal vocabulary the run reached ({@link isTerminalStatus}); ⛔ not
+   * completed/failed only, which is the two-member fold #15223 removed from
+   * both ends of this write. Keyed by a `run_`-prefixed id so it NEVER collides
+   * with a live suspended run's row (id = raw `runId`, status `paused`) — the
+   * suspend save/load/delete/list path (which only touches raw ids and
+   * `status:'paused'` rows) is untouched. Upsert so a re-emitted terminal
+   * (e.g. a resumed run) updates in place.
+   *
+   * ⭐ [#15336] The other end of this write lives in `engine.ts`: the row is
+   * what `AutomationEngine.restoreConsumedSuspension` reads — through
+   * {@link ObjectStoreSuspendedRunStore.loadTerminal} and
+   * {@link deserializeConsumedSuspension} — when an operator asks for a
+   * stranded run to be put back on its pause, and it is the only witness any
+   * OTHER replica (or this one after a restart) has. Three things below are
+   * that verb's inputs rather than local detail, so ⛔ do not change one
+   * without reading it:
+   *
+   *  - the four consumed-suspension columns are ALWAYS written, `null`
+   *    included — a restored run that later finishes must CLEAR what it
+   *    carried, which is also why an absent snapshot never means the run never
+   *    had one (`sys-automation-run.object.ts` states that direction at
+   *    `variables_json`);
+   *  - `node_id` carries the PAUSE node on a stranded row, because the
+   *    snapshot's node is rebuilt from that one column;
+   *  - an over-budget snapshot is recorded as a drop notice rather than
+   *    dropped silently, because a bare NULL reads as "the run moved on".
    */
   async recordTerminal(record: RunRecord): Promise<void> {
     const now = new Date().toISOString();
@@ -1007,10 +1029,23 @@ function serializeConsumedSuspension(
  *
  * Keyed off `variables_json`, which no other terminal-row writer populates —
  * see the call site. `correlation` and `node_type` come back from their own
- * columns, written by the same helper. `steps` come from the row's own `steps_json`: they are the
- * step log AS OF THE PAUSE (the engine trims the failed attempt's steps off the
- * snapshot before recording), bounded by the same cap every terminal row's
- * steps are.
+ * columns, written by the same helper.
+ *
+ * ⚠️ [#15336] `steps`, alone among them, do NOT come from the snapshot: they
+ * come from the row's own `steps_json`, which is the TERMINAL row's step log
+ * and covers the WHOLE run — the steps before the pause and the failed
+ * attempt's after it. Only the JOURNAL copy is as of the pause: the engine
+ * slices `run.steps` back to the step count at the pause when it journals a
+ * strand (`AutomationEngine.journalConsumedSuspension`), and that trimmed array
+ * never reaches this column — `recordTerminal` writes `record.steps`, the
+ * compacted log of the whole run, and compaction keeps every FAILURE on purpose
+ * while {@link serializeStepsBounded} trims the HEAD when the row is over
+ * budget, so the failed attempt's steps are the ones that survive both bounds.
+ * A snapshot rebuilt HERE therefore carries steps the pause did not have. It
+ * re-arms the same run regardless — the pause is `nodeId` plus `variables` /
+ * `context` / `correlation`, none of which the step log feeds — but ⛔ never
+ * read a row-rebuilt snapshot's `steps` as the state at the pause; the
+ * process-local journal is the only copy that is.
  */
 function deserializeConsumedSuspension(row: any): SuspendedRun | undefined {
   if (row.variables_json == null || row.variables_json === '') return undefined;

packages/services/service-automation/src/sys-automation-run.object.ts

@@ -269,10 +269,24 @@ export const SysAutomationRun = ObjectSchema.create({
     // `RunRecord.consumedSuspensionDropped`), so "present" now has two shapes
     // and only one of them is a restorable snapshot — stated in the
     // description rather than left to the reader of the column.
+    //
+    // [#15336] The description used to state that presence and "this run had a
+    // consumed suspension" imply EACH OTHER. Only the forward direction is
+    // true. The falsifying shape is a run that stranded, was restored and then
+    // finished: `recordTerminal` upserts the SAME `run_<id>` row and
+    // `serializeConsumedSuspension(undefined)` writes explicit NULLs into all
+    // four columns — deliberately, so "restorable" cannot outlive the condition
+    // it describes (`RunRecord.consumedSuspension` in `engine.ts` states the
+    // clearing rule from the producer's side). ⛔ The fix is the TEXT, not the
+    // clearing: nothing reads the reverse direction — `restoreConsumedSuspension`
+    // refuses a snapshot-less row by naming the status it observed and
+    // deliberately declines to say whether the run never paused or lost its
+    // snapshot, which is that direction being unavailable, honestly. The
+    // clearing itself is pinned in `suspended-run-store.test.ts`.
     variables_json: Field.textarea({
       label: 'Variables',
       required: false,
-      description: 'JSON snapshot of the flow variable map at suspend time. On a terminal row its PRESENCE is the discriminator: nothing but the consumed-suspension path writes it there, so variables_json present on a completed/failed row ⇔ the row\'s run had a pause that its resume consumed before a downstream node failed — the store\'s deserializer keys off exactly this. Two shapes on such a row: the snapshot itself (a restorable suspension), or a one-key notice `{"$consumedSuspensionDropped": …}` recording that the snapshot existed and was NOT persisted (over the store\'s row budget) — the notice is not a restorable snapshot; such a run can be restored only by the process that stranded it, while it runs.',
+      description: 'JSON snapshot of the flow variable map at suspend time. On a terminal row its PRESENCE is the discriminator: nothing but the consumed-suspension path writes it there, so variables_json present on a completed/failed row ⇒ the row\'s run had a pause that its resume consumed before a downstream node failed — the store\'s deserializer keys off exactly this. ⛔ It does NOT hold in reverse: the terminal write is an upsert that always writes these columns, NULL included, so a stranded run that was restored and then finished has its row rewritten with NULLs. Absence therefore means "nothing to restore NOW", never "this run never had a consumed suspension" — the restore verb says exactly that when it refuses, naming the status it observed instead of claiming which. Two shapes on such a row: the snapshot itself (a restorable suspension), or a one-key notice `{"$consumedSuspensionDropped": …}` recording that the snapshot existed and was NOT persisted (over the store\'s row budget) — the notice is not a restorable snapshot; such a run can be restored only by the process that stranded it, while it runs.',
       group: 'State',
     }),