@decidio/sdk 0.3.0 → 0.3.5

package/dist/resume.d.ts

@@ -129,11 +129,12 @@ export interface ExecutionRecord {
         at: string;
         workerStopped?: boolean;
     };
-    /** DERIVED AT READ TIME, never persisted: set when a DENIED decision also carries an execution
-     *  marker. That pair is the single most alarming state the machine can hold — a human refused it
-     *  and something ran anyway — so it must never resolve to silence. Only the file store can hold
-     *  it (the memory store keeps one record per decision); a crash between writing a marker and
-     *  sweeping the weaker ones, or a 0.1.x report migrated beside a tombstone, both produce it. */
+    /** Set when a DENIED decision also carries an execution record. That pair is the single most
+     *  alarming state the machine can hold — a human refused it and something ran anyway — so it must
+     *  never resolve to silence. The revision chain cannot produce it (no transition publishes over
+     *  a denial); it is DERIVED by the legacy-marker reader, and PERSISTED only when a 0.2/0.3
+     *  directory that held a denial marker beside an execution marker is migrated onto the chain —
+     *  there it is the record of what that layout held. */
     executionDespiteDenial?: {
         state: ExecutionState;
         at: string;
@@ -346,19 +347,37 @@ export declare class FilePendingStore implements PendingStore {
     constructor(dir: string);
     private key;
     private path;
-    /** One marker file per state. The FILENAME carries the state so a scan never has to parse,
-     *  and the content carries the record. */
-    private statePath;
-    /** Durable write: temp file in the SAME directory → fsync → atomic rename. A crash can then
-     *  only leave the old complete file or the new complete file, never a truncated one. The
-     *  0.1.x journal wrote straight to its final path with O_TRUNC, so a crash mid-write
-     *  destroyed the record that proved an action had already run. */
+    private revPath;
+    /** Legacy (0.2/0.3) marker path, read for migration and never written. */
+    private markerPath;
+    private listRevs;
+    private legacyMarkers;
+    /** Write `text` to a fresh temp file beside `target`, fsynced. Returns the temp path. */
+    private writeTemp;
+    /** Durable write for the PAYLOAD file (not the chain): temp → fsync → atomic rename. */
     private writeAtomic;
-    /** The authoritative record: the STRONGEST state present on disk. A crash between "write the
-     *  new marker" and "remove the old one" leaves two markers; taking the strongest means an
-     *  executed action can never read back as parked, so a partial transition is safe rather than
-     *  merely unlikely. Corruption is reported, never silently treated as absent. */
-    private resolve;
+    /** The head of the chain, or the migrated reading of a legacy layout that has not been
+     *  upgraded. Corruption is REPORTED, never treated as absent: an unreadable record is the one
+     *  that proves an action already ran. */
+    private readHead;
+    /** TEST SEAM, a no-op in production. Called with the operation name and the state about to be
+     *  published, AFTER validation and BEFORE the publish — the exact window a concurrent writer
+     *  can land in. The deterministic two-process suites subclass the store and block here so the
+     *  race the retest found is reproduced on purpose, every run, rather than by luck. */
+    protected _barrier(_op: string, _id: string, _next: ExecutionState): void;
+    /** ONE TRANSITION = read head → compute successor → publish with link(). `compute` receives the
+     *  current record (null if none) and returns the successor, or null for "nothing to write" (a
+     *  refusal that is a return value, like a lost claim, rather than an error). Every rule runs
+     *  INSIDE `compute`, against the revision that is about to be superseded; if a rival publishes
+     *  first, `compute` runs again against the rival's record. */
+    private transition;
+    /** The 0.2/0.3 reading of a marker layout — strongest marker wins, a denial marker wins at any
+     *  rank, and a denial beside an execution marker is reported as both. Used ONLY to migrate an
+     *  older directory and to report one that could not be migrated; nothing writes markers. */
+    private resolveLegacyMarkers;
+    /** The generic ADVANCE, with every fence evaluated against the head the publish will supersede.
+     *  `pre` is a per-method check (markInvoking's claim requirement) that must ALSO run inside the
+     *  transition — a check that runs before it is a check against a snapshot. */
     private setState;
     put(p: PendingAction): Promise<void>;
     get(id: string): Promise<PendingAction | null>;
@@ -374,10 +393,11 @@ export declare class FilePendingStore implements PendingStore {
     markDiscarded(id: string, verdict: "rejected" | "blocked", reason?: string): Promise<void>;
     getExecution(id: string): Promise<ExecutionRecord | null>;
     listExecutions(): Promise<ExecutionRecord[]>;
-    /** OPERATOR RECONCILIATION — see MemoryPendingStore.settle. Writes the new marker first and
-     *  then clears every other state file for this decision, including the STRONGER ones: this is
-     *  the single place where a state legitimately moves backwards, so leaving a stronger marker
-     *  behind would let resolve()'s strongest-wins rule undo the operator's decision. */
+    /** OPERATOR RECONCILIATION — see MemoryPendingStore.settle. The one legal backwards move, and
+     *  now a transition like any other: two conflicting settlements both validate, both try to
+     *  publish the next revision, exactly one wins, and the loser re-validates against the winner's
+     *  record — where `assertSettlable` refuses it (captured evidence protects a `committed`; a
+     *  `parked` record refuses `committed`). Before this, both won and the second erased the first. */
     settle(id: string, outcome: SettleOutcome, opts?: {
         evidence?: unknown;
         reason?: string;
@@ -385,14 +405,20 @@ export declare class FilePendingStore implements PendingStore {
         workerStopped?: boolean;
     }): Promise<void>;
     releasePreinvoke(id: string, attemptId: string): Promise<void>;
-    /** ONE-WAY MIGRATION from the 0.1.x layout, run once at construction. `<id>.json` → parked;
-     *  `<id>.claimed` → INDETERMINATE, never parked: a claimed 0.1.x entry may have been mid-flight
-     *  when the process died, and assuming it did not run is the assumption that duplicates a
-     *  payment. Nothing ambiguous is made executable by an upgrade. */
+    /** ONE-WAY MIGRATION of older layouts, run at construction.
+     *    0.2/0.3 one-marker-per-state  → the head of a fresh revision chain (markers removed)
+     *    0.1.x `<id>.json` with no state → parked
+     *    0.1.x `<id>.claimed`           → INDETERMINATE, never parked: a claimed 0.1.x entry may have
+     *                                     been mid-flight when the process died, and assuming it did
+     *                                     not run is the assumption that duplicates a payment
+     *    0.1.x `reports/<id>.json`      → executed_unreported (the report can be re-sent)
+     *  Nothing ambiguous is made executable by an upgrade, and nothing unreadable is silently
+     *  dropped: a key whose markers cannot be parsed is left exactly as found and reads as corrupt. */
     migrateLegacy(): {
         migrated: number;
         indeterminate: number;
         reports: number;
+        chained: number;
     };
     /** 0.1.x wrote execution reports to `<pendingDir>/reports/<id>.json` — evidence that an action
      *  ALREADY RAN and still owes Decidio a report. 0.2.0 keeps that in the ledger, so without this
@@ -424,7 +450,10 @@ export declare class DecidioSuspendedError extends Error {
 /** `indeterminate` (0.2.0): the handler was INVOKED and then threw. Whether the downstream
  *  effect committed is not knowable from here, so the action is never retried automatically —
  *  it waits for reconcile(). Callers that switch exhaustively on this union must handle it. */
-export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate";
+/** `already_resolved` (0.3.5): this resume signal LOST the transition race to an earlier, final answer
+ *  (a denial, or an execution that already ran) — `reason` names which. It used to read `unknown`,
+ *  which is the word for "not ours"; safety was right and the diagnosis was not (prodsec V033-06). */
+export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate" | "already_resolved";
 /** The states a durable action can actually be in — every one of them nameable, including the
  *  one nobody likes. */
 export type RecoveryState = 
@@ -446,7 +475,9 @@ export type RecoveryState =
  *  and must never be retried automatically. */
  | "indeterminate"
 /** Executed, result captured, report not yet accepted by Decidio. Safe to `reconfirm`. */
- | "executed_unreported";
+ | "executed_unreported"
+/** a parked row whose payload is gone: cannot execute, not awaiting anyone (0.3.5) */
+ | "orphaned_state";
 export interface RecoveryItem {
     decisionId: string;
     action?: string;