@decidio/sdk 0.2.1 → 0.3.0

package/dist/resume.d.ts

@@ -46,13 +46,32 @@ export interface PendingAction {
  *  `indeterminate` is the honest answer to the case an SDK cannot decide: the handler was
  *  invoked and then threw. Whether the downstream write committed is not knowable from here, so
  *  the action is never automatically retried — it waits for `reconcile()`. */
-export type ExecutionState = "parked" | "claimed_preinvoke" | "invoking" | "executed_unreported" | "indeterminate" | "reported";
+export type ExecutionState = "parked" | "claimed_preinvoke"
+/** A human or policy said NO. Terminal: the handler must never run for this decision. */
+ | "discarded" | "invoking" | "executed_unreported" | "indeterminate" | "reported";
 /** Ordered weakest→strongest. Resolution ALWAYS takes the strongest state present for a
  *  decision, which is what makes a partially-failed transition safe: if a crash leaves both the
  *  old and new markers on disk, the stronger one wins and an executed action can never read
  *  back as parked. */
+/** `discarded` sits ABOVE the pre-invocation states and BELOW the execution ones, and the position
+ *  is load-bearing in both directions:
+ *
+ *  - above `parked`/`claimed_preinvoke`, so a denial beats a payload whose deletion FAILED. That is
+ *    the whole F-001 fix: the old code deleted the payload and wrote no state, the shipped file
+ *    store swallows unlink errors, and the ledger therefore still read `parked` — so a later,
+ *    out-of-order `approved` signal executed an action a human had explicitly refused.
+ *  - below `invoking`…`reported` — but rank is NOT how the two are reconciled, and relying on it
+ *    was wrong in both directions. A stronger marker written beside a tombstone outranked the
+ *    denial AND was then deleted by setState's weaker-marker sweep, so a refused decision read back
+ *    as runnable. `resolve()` therefore prefers the DENIAL whenever its marker is present, at any
+ *    rank. That decides authority, not truth: if an execution marker is there too, something DID
+ *    run, and swallowing that is the opposite failure — so resolve() flags the conflict on the
+ *    record (`executionDespiteDenial`), recover() reports it, and reconfirm() says so instead of
+ *    "this process never executed it". A denial governs the decision; it never edits history. */
 export declare const EXECUTION_STATES: readonly ExecutionState[];
-/** States from which the handler must NEVER be invoked again automatically. */
+/** States from which the handler must NEVER be invoked again automatically. `discarded` is here
+ *  FOREVER — `claim()` gates on this list, so a denied decision can never be claimed again, by this
+ *  process or any future one. */
 export declare const NON_REPLAYABLE: readonly ExecutionState[];
 export interface ExecutionRecord {
     decisionId: string;
@@ -84,6 +103,11 @@ export interface ExecutionRecord {
         kind: "ed25519" | "hmac";
         sig: string;
     };
+    /** WHY this decision is `discarded` — the verdict a human or policy returned, and any reason
+     *  text. Recorded on the tombstone so recovery can say "a human rejected this" rather than
+     *  reporting a bare terminal state an operator would have to go and look up. */
+    verdict?: "rejected" | "blocked";
+    discardReason?: string;
     /** Set when this row was reconstructed by an upgrade rather than written by a live execution —
      *  currently only `"0.1.x report journal"`. Such a row predates evidence binding and can never
      *  carry a valid signature, so the strict check exempts it EXPLICITLY. The exemption must be a
@@ -95,10 +119,25 @@ export interface ExecutionRecord {
     confirmation?: string;
     /** Set when an OPERATOR settled this decision rather than the SDK observing it. Kept so an
      *  audit of the agent-side ledger can tell an observed execution from an asserted one. */
+    /** `workerStopped` records that a HUMAN asserted the claiming worker was stopped before this
+     *  decision was released — the assertion that made the release legal. It is stamped here because
+     *  the whole point of requiring it is to put a name against that judgement: without it the ledger
+     *  showed a decision released from `invoking` with no trace that anyone had claimed to check. */
     reconciled?: {
         outcome: SettleOutcome;
         reason?: string;
         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. */
+    executionDespiteDenial?: {
+        state: ExecutionState;
+        at: string;
+        hasEvidence: boolean;
     };
     at: string;
 }
@@ -127,8 +166,38 @@ export declare class DecidioAlreadySettledError extends Error {
     decisionId: string;
     constructor(decisionId: string);
 }
+/** A DENIAL IS TERMINAL, and that has to be enforced where the state is WRITTEN — not only where
+ *  it is reconciled. Refusing `settle` from `discarded` closed the operator's door and left three
+ *  others open, each of which walked a refused action all the way to execution:
+ *    - `discarded` sits mid-rank in EXECUTION_STATES, so the advance-only rule happily accepted
+ *      `discarded → invoking → executed_unreported`;
+ *    - `markDiscarded` leaves the record UNOWNED (`attemptId: ""`) when nothing had claimed it, so
+ *      the ownership fence — which skips when there is no owner — did not stop that walk either;
+ *    - reachable through the shipped controller, not just the store API: an `approved` signal
+ *      claims, a `rejected` signal writes the tombstone, and the first call then invokes anyway.
+ *  Typed, for the same reason DecidioAlreadySettledError is: the reporting stage deliberately keeps
+ *  going when the ledger fails, so a generic error here would read as "the disk write failed" and
+ *  send an authority report for an action a human refused. */
+/** `recover()` could not enumerate the ledger. It is a THROW, not an empty list, because those two
+ *  are the same value to a caller and mean opposite things: `[]` is "you owe nothing", and this is
+ *  "I cannot tell you what you owe". The old code logged to stderr and returned `[]`, so a script
+ *  reading `if (!(await recover()).length) allClear()` treated an unreadable store — a permissions
+ *  change, a mounted volume gone, a corrupt directory — as proof that no action was left
+ *  outstanding. A crash is the correct failure here; silence is not. */
+export declare class DecidioRecoveryUnavailableError extends Error {
+    cause: unknown;
+    constructor(cause: unknown);
+}
+export declare class DecidioDeniedError extends Error {
+    decisionId: string;
+    verdict: string;
+    constructor(decisionId: string, verdict: string);
+}
 export declare const SETTLE_OUTCOMES: readonly SettleOutcome[];
-export declare function assertSettlable(id: string, state: ExecutionState, outcome: SettleOutcome, hasObservedEvidence?: boolean): void;
+export declare function assertSettlable(id: string, state: ExecutionState, outcome: SettleOutcome, opts?: {
+    hasObservedEvidence?: boolean;
+    workerStopped?: boolean;
+}): void;
 export interface ClaimResult {
     /** True only when THIS attempt may proceed to invoke. */
     ok: boolean;
@@ -148,8 +217,13 @@ export interface ClaimResult {
 export interface PendingStore {
     put(p: PendingAction): Promise<void>;
     get(decisionId: string): Promise<PendingAction | null>;
-    /** CLEANUP ONLY. Removing a row must never be what prevents a second execution. */
-    delete(decisionId: string): Promise<void>;
+    /** CLEANUP ONLY. Removing a row must never be what prevents a second execution.
+     *
+     *  `attemptId` scopes the cleanup to its OWNER. A superseded attempt tidies up on its way out
+     *  (see the stale-attempt branch of the reporting stage), and without this it deleted the payload
+     *  of the attempt that had legitimately taken over — the live worker's own recovery data, removed
+     *  by the dead one. Omit it for genuine housekeeping that is not attributable to an attempt. */
+    delete(decisionId: string, attemptId?: string): Promise<void>;
     /** Parked entries only — anything claimed or beyond is excluded. */
     list(): Promise<PendingAction[]>;
     /** Atomically take ownership for THIS attempt. Must refuse when the decision is already
@@ -164,6 +238,12 @@ export interface PendingStore {
     markIndeterminate(decisionId: string, attemptId: string, error: string): Promise<void>;
     /** Decidio accepted the execution report. */
     markReported(decisionId: string, attemptId: string, confirmation: string): Promise<void>;
+    /** A human or policy DENIED this decision. Writes the terminal tombstone that makes the decision
+     *  permanently unclaimable — and it must be written BEFORE any payload cleanup, because cleanup
+     *  is best-effort and a store that swallows its failure would otherwise leave the row readable as
+     *  `parked`. A conforming store persists this durably; returning without persisting reintroduces
+     *  F-001. Safe to call more than once (a denial is idempotent). */
+    markDiscarded(decisionId: string, verdict: "rejected" | "blocked", reason?: string): Promise<void>;
     /** The authoritative state for one decision, or null if this store has never seen it. */
     getExecution(decisionId: string): Promise<ExecutionRecord | null>;
     /** Every execution record the store holds — the basis for honest recovery reporting. */
@@ -181,6 +261,7 @@ export interface PendingStore {
         evidence?: unknown;
         reason?: string;
         evidenceSig?: ExecutionRecord["evidenceSig"];
+        workerStopped?: boolean;
     }): Promise<void>;
     /** Release a claim taken BEFORE invocation, so a pre-invoke failure stays retryable. It is a
      *  contract error to call this once `markInvoking` has been written, and a conforming store
@@ -200,13 +281,16 @@ export declare class MemoryPendingStore implements PendingStore {
     private advance;
     put(p: PendingAction): Promise<void>;
     get(id: string): Promise<PendingAction | null>;
-    delete(id: string): Promise<void>;
+    /** Cleanup only — the execution record STAYS. Scoped to the owning attempt: see PendingStore. */
+    delete(id: string, attemptId?: string): Promise<void>;
+    private ownsPayload;
     list(): Promise<PendingAction[]>;
     claim(id: string, attemptId: string): Promise<ClaimResult>;
     markInvoking(id: string, attemptId: string): Promise<void>;
     recordExecuted(id: string, attemptId: string, evidence: unknown, evidenceSig?: ExecutionRecord["evidenceSig"], evidenceError?: string): Promise<void>;
     markIndeterminate(id: string, attemptId: string, error: string): Promise<void>;
     markReported(id: string, attemptId: string, confirmation: string): Promise<void>;
+    markDiscarded(id: string, verdict: "rejected" | "blocked", reason?: string): Promise<void>;
     getExecution(id: string): Promise<ExecutionRecord | null>;
     listExecutions(): Promise<ExecutionRecord[]>;
     /** OPERATOR RECONCILIATION — the ONE legal backwards transition, and the only exit from
@@ -220,9 +304,28 @@ export declare class MemoryPendingStore implements PendingStore {
         evidence?: unknown;
         reason?: string;
         evidenceSig?: ExecutionRecord["evidenceSig"];
+        workerStopped?: boolean;
     }): Promise<void>;
     releasePreinvoke(id: string, attemptId: string): Promise<void>;
 }
+/** The ACL principal for THIS process, resolved from the token SID rather than the login name.
+ *
+ *  Shared by every hardening site (F-009): the durable pending directory AND the `.env` the CLI
+ *  writes. `writeSecretFile` had its own weaker copy that granted `userInfo().username` — who
+ *  logged IN, which is not always who is writing. A Windows service, a scheduled task or an
+ *  impersonated thread has a different effective identity, and granting the wrong name while
+ *  `/inheritance:r` strips every other ACE is how a hardening step locks the writer out of its own
+ *  secrets. A SID also needs no localisation or escaping, where a name can carry spaces, a domain
+ *  prefix, or be renamed out from under the ACE. */
+export declare function windowsPrincipal(): string;
+/** Restrict a FILE to its owner on Windows, with the same verify-then-roll-back discipline as
+ *  `hardenDir`. Returns null on success, or the reason it could not be done.
+ *
+ *  The verification is the point, and it is what the CLI's own version lacked: a SUCCESSFUL
+ *  `icacls` that locks this process out of the file it just wrote is more dangerous than a failed
+ *  one, and it printed nothing at all. Here the file is read back, and if that fails the
+ *  inheritance goes back rather than leaving credentials the SDK can no longer read. */
+export declare function hardenFile(file: string): string | null;
 /** Restrict a directory to its owner. On Windows POSIX modes are a no-op, so strip inheritance
  *  and grant only the effective user. A FAILURE IS SAID, never swallowed: these files hold the
  *  arguments of actions awaiting approval, and "silently kept the directory's inherited
@@ -261,13 +364,14 @@ export declare class FilePendingStore implements PendingStore {
     get(id: string): Promise<PendingAction | null>;
     /** CLEANUP ONLY — the payload goes, the execution record STAYS. That is the whole point of
      *  the v2 model: a failed or skipped delete can no longer make an executed action runnable. */
-    delete(id: string): Promise<void>;
+    delete(id: string, attemptId?: string): Promise<void>;
     list(): Promise<PendingAction[]>;
     claim(id: string, attemptId: string): Promise<ClaimResult>;
     markInvoking(id: string, attemptId: string): Promise<void>;
     recordExecuted(id: string, attemptId: string, evidence: unknown, evidenceSig?: ExecutionRecord["evidenceSig"], evidenceError?: string): Promise<void>;
     markIndeterminate(id: string, attemptId: string, error: string): Promise<void>;
     markReported(id: string, attemptId: string, confirmation: string): Promise<void>;
+    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
@@ -278,6 +382,7 @@ export declare class FilePendingStore implements PendingStore {
         evidence?: unknown;
         reason?: string;
         evidenceSig?: ExecutionRecord["evidenceSig"];
+        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;
@@ -331,6 +436,11 @@ export type RecoveryState =
  *  operator releases it. Reporting this as "parked" (as 0.2.0's first draft did) told a UI an
  *  approved action was still queued to resume when in fact it had been silently dropped. */
  | "claimed_stalled"
+/** DENIED, and an execution marker exists anyway. Nothing here will run it and nothing will
+ *  report it — the decision is closed — but an effect may exist downstream, so this is the one
+ *  recovery row that asks a human to go and look. It cannot be reconciled or retried; a denial is
+ *  terminal. Callers switching exhaustively on this union must handle it. */
+ | "denied_with_evidence"
 /** Claimed for execution and NOT journalled: the process died somewhere between claiming and
  *  recording the result. The action MAY OR MAY NOT have run — this cannot be resolved locally
  *  and must never be retried automatically. */
@@ -492,6 +602,7 @@ export interface ResumeController extends ResumeConfig {
         outcome: SettleOutcome;
         evidence?: unknown;
         reason?: string;
+        workerStopped?: boolean;
     }): Promise<EvidenceOutcome>;
     /** Every durable item that needs a human's attention, with its state named — including the one
      *  state that CANNOT be resolved automatically: `indeterminate`, where a process died between