clinkx 0.2.3 → 1.0.0

package/clinkx-workflows/dist/shutdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAcrC;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IACb,OAAO,GAAG,IAAI,GAAG,EAAiC,CAAC;IAC5D,UAAU,GAAG,CAAC,CAAC;IACf,YAAY,GAAG,KAAK,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CACN,OAAqB,EACrB,UAA2B,EAC3B,YAA4B;QAE5B,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;QAC/B,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;QAChE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,MAAsB;QAC/B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,MAAc;QAC3B,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,mCAAmC,CAAC,CAAC;YAC7D,OAAO;QACT,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAEzB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,0BAA0B,CAAC,CAAC;QAEpD,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,aAAa,MAAM,EAAE,CAAC,CAAC,CAAC;QAEvD,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,2BAA2B,CAAC,CAAC;IACvD,CAAC;IAED,0EAA0E;IAClE,KAAK,CAAC,SAAS,CAAC,WAAkB;QACxC,0EAA0E;QAC1E,0DAA0D;QAC1D,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QACpD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;YACvC,2BAA2B;YAC3B,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;YAEpC,mCAAmC;YACnC,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,YAAY,EAAE,CAAC;YAC7B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,KAAK,CACV,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EACzD,yCAAyC,CAC1C,CAAC;YACJ,CAAC;YAED,6BAA6B;YAC7B,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YAClC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,KAAK,CACV,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EACzD,mDAAmD,CACpD,CAAC;YACJ,CAAC;YAED,uCAAuC;YACvC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;CACF;AAED,sCAAsC;AACtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,mBAAmB,EAAE,CAAC"}

package/clinkx-workflows/dist/state-schema.d.ts

@@ -19,18 +19,32 @@
  */
 import type { ChildFailureMetadata } from "./errors.js";
 import type { FidelityMetadata } from "./fidelity.js";
+import type { WorkflowContext } from "./context-preflight.js";
+import type { ContextBuilderLifecycleStateV1 } from "./context-builder-lifecycle-contract.js";
+import type { WorkflowContextPolicy } from "./context-mode-resolver.js";
+import type { PlanReviewRunState } from "./plan-review/run-state.js";
+import type { CouncilPlanReviewError } from "./plan-review/publication.js";
 /** Call-level state progression. */
 export type CallState = "pending" | "running" | "succeeded" | "failed" | "cancelled";
 /** Run-level state progression. */
 export type RunStatus = "pending" | "running" | "succeeded" | "failed" | "cancelled";
 /** Failure classification for diagnostics and retry decisions. */
 export type FailureClass = "transient" | "permanent";
+/** The canonical run-level terminal fields overwritten by a generic resume. */
+export interface PreviousTerminalEnvelope {
+    readonly status: "succeeded" | "failed" | "cancelled";
+    readonly completedAt?: string | undefined;
+    readonly error?: string | undefined;
+    readonly failureClass?: FailureClass | undefined;
+}
 /** Per-call state entry in the run state. */
 export interface CallStateEntry {
     readonly callId: string;
     readonly stageId: string;
     readonly state: CallState;
     readonly retryCount: number;
+    /** Durable count of provider attempts already dispatched for this call. */
+    readonly attemptsConsumed?: number | undefined;
     readonly startedAt?: string | undefined;
     readonly completedAt?: string | undefined;
     readonly durationMs?: number | undefined;
@@ -112,6 +126,10 @@ export interface RunState {
     readonly workflowVersion: string;
     /** Overall run status. */
     readonly status: RunStatus;
+    /** Most recently overwritten generic terminal envelope; never recursive. */
+    readonly previousTerminal?: PreviousTerminalEnvelope | undefined;
+    /** Effective context policy fixed at initial admission for deterministic resume. */
+    readonly initialContextPolicy?: WorkflowContextPolicy | undefined;
     /** Whether this run is resumable (requires explicit child config). */
     readonly resumable: boolean;
     /** Child config fingerprint for fast mismatch rejection. */
@@ -130,6 +148,24 @@ export interface RunState {
     readonly stages: readonly StageStateEntry[];
     /** Resolved variables snapshot (non-secret only per 0-11a). */
     readonly variables: Readonly<Record<string, unknown>>;
+    /** Optional context-builder provenance metadata for preflight-enabled runs. */
+    readonly workflow_context?: WorkflowContext | undefined;
+    /**
+     * Latest live workflow-preflight lifecycle snapshot. This is observability
+     * only: workflow_context remains the sole durable completion/reuse fence.
+     */
+    readonly context_builder_lifecycle?: ContextBuilderLifecycleStateV1 | undefined;
+    /**
+     * Optional plan-review aux subtree (A-5). Present only for typed
+     * plan-review runs (`plan-review-receipts`, or the pre-rename name
+     * `council-plan-review`). Strictly Zod-validated on create and on read —
+     * unlike the rest of this state, a corrupt subtree here is a hard failure, not
+     * a degraded read, because it is the SOLE resume input for the execution
+     * contract, the immutable snapshot, and the per-call bindings.
+     */
+    readonly plan_review_state?: PlanReviewRunState | undefined;
+    /** Structured plan-review failure details; generic `error` remains canonical for older clients. */
+    readonly plan_review_error?: CouncilPlanReviewError | undefined;
     /** Run-level timing. */
     readonly startedAt?: string | undefined;
     readonly completedAt?: string | undefined;
@@ -138,4 +174,6 @@ export interface RunState {
     readonly failureClass?: FailureClass | undefined;
     /** Retain run directory on success for debugging when true. */
     readonly debugKeepArtifacts?: boolean | undefined;
+    /** Whether the run was admitted for detached async execution. */
+    readonly async?: boolean | undefined;
 }

package/clinkx-workflows/dist/state.d.ts

@@ -1,23 +1,64 @@
 import type { EngineHooks, EngineResumeState } from "./engine.js";
 import type { NormalizedWorkflowDefinition } from "./definition-normalizer.js";
-import type { RunState } from "./state-schema.js";
-export type RunDirectoryClassification = "failed" | "cancelled" | "debug_kept" | "active_locked" | "running_or_pending" | "unknown";
+import type { FailureClass, RunState } from "./state-schema.js";
+import { type WorkflowContext } from "./context-preflight.js";
+import type { WorkflowContextBuilderLifecycleTransition } from "./context-builder-lifecycle-router.js";
+import type { WorkflowContextPolicy } from "./context-mode-resolver.js";
+import { type PlanReviewContextProvenance, type PlanReviewRunState } from "./plan-review/run-state.js";
+import { type CouncilPlanReviewError } from "./plan-review/publication.js";
+/**
+ * Reader-side staleness floor the shipped cadence is designed against; the
+ * dashboard observer derives its own threshold from the declared interval.
+ * Re-exported for tests and cross-module documentation only — nothing in this
+ * module consults it, because run-lock CONTROL decisions
+ * (`classifyRunLockSync`, `reapRunCancelled`, pruning) must never depend on
+ * mtime freshness.
+ */
+export { RUN_LOCK_HEARTBEAT_STALE_FLOOR_MS } from "./run-lock-heartbeat.js";
+/**
+ * Run-level error written by reconcileStaleRunDirectories. Deliberately
+ * distinct from STALE_RUNNING_RECOVERY_ERROR (the resume-path recovery string)
+ * so the two reconcile paths remain distinguishable in persisted state.
+ */
+export declare const STALE_RUN_RECONCILE_ERROR = "Reconciled stale running run: no live worker process";
+export type RunDirectoryClassification = "failed" | "cancelled" | "debug_kept" | "succeeded_async" | "succeeded_sync" | "active_locked" | "running_or_pending" | "unknown";
 export interface PruneRunDirectoriesOptions {
     readonly retainFailedDays?: number | undefined;
     readonly retainCancelledDays?: number | undefined;
     readonly retainDebugDays?: number | undefined;
+    readonly retainAsyncDays?: number | undefined;
+    readonly retainSucceededDays?: number | undefined;
 }
 export interface PruneRunDirectoriesResult {
     readonly pruned: number;
     readonly skipped: number;
     readonly errors: number;
 }
+export interface ReconcileStaleRunDirectoriesResult {
+    readonly scanned: number;
+    readonly reconciled: number;
+    readonly skipped_held: number;
+    readonly skipped_terminal: number;
+    readonly errors: number;
+}
+export type RunLockStatus = "held" | "stale_or_absent" | "unknown";
 export interface CreateWorkflowStateOptions {
     readonly runId: string;
     readonly definition: NormalizedWorkflowDefinition;
     readonly variables: Readonly<Record<string, unknown>>;
     readonly runDir?: string | undefined;
     readonly debugKeepArtifacts?: boolean | undefined;
+    readonly async?: boolean | undefined;
+    readonly initialContextPolicy?: WorkflowContextPolicy | undefined;
+}
+/**
+ * Warn-only signal recorded at create() when a sibling run with byte-identical
+ * workflow + inputs snapshot hashes previously failed with
+ * `failureClass:"permanent"`. Advisory only — see detectDuplicateReplay.
+ */
+export interface DuplicateReplaySignal {
+    readonly runId: string;
+    readonly completedAt?: string | undefined;
 }
 export interface ResumeWorkflowStateOptions {
     readonly runId: string;
@@ -28,8 +69,15 @@ export declare function classifyRunDirectory(runDirPath: string): RunDirectoryCl
 export declare function pruneRunDirectories(runsRootDir: string, options?: PruneRunDirectoriesOptions): Promise<PruneRunDirectoriesResult>;
 export declare class WorkflowStateStore {
     readonly runDir: string;
+    /** Portable journal identity; absent only for a legacy or failed-open run. */
+    readonly sessionLogGeneration: string | undefined;
+    /**
+     * Warn-only duplicate-replay signal detected at create(); undefined on
+     * resume and when no permanently-failed identical sibling was found.
+     */
+    readonly duplicateOfFailedRun: DuplicateReplaySignal | undefined;
     readonly definition: NormalizedWorkflowDefinition;
-    readonly variables: Readonly<Record<string, unknown>>;
+    variables: Readonly<Record<string, unknown>>;
     readonly hooks: EngineHooks;
     readonly resume: EngineResumeState;
     private state;
@@ -37,14 +85,133 @@ export declare class WorkflowStateStore {
     private readonly debugKeepArtifacts;
     private writeChain;
     private lockHeld;
+    private planReviewTerminalResult;
+    private readonly lockToken;
+    private heartbeat;
+    private heartbeatInFlight;
+    private heartbeatError;
     private constructor();
     static create(options: CreateWorkflowStateOptions): Promise<WorkflowStateStore>;
     static resume(options: ResumeWorkflowStateOptions): Promise<WorkflowStateStore>;
     get runState(): RunState;
+    /**
+     * Open a new generic resume attempt before any context preflight or provider
+     * setup. Provider-call attempt counters remain untouched; only the run-level
+     * terminal envelope is cleared so a pre-dispatch failure/cancellation can be
+     * persisted as the outcome of this resume attempt.
+     *
+     * Plan-review stale-run recovery has its own terminal-intent protocol and is
+     * deliberately left unchanged here.
+     */
+    beginResumeAttempt(): Promise<void>;
     markCancelled(reason?: string): Promise<void>;
+    /**
+     * Idempotently mark the run failed. Only applies when the current status is
+     * non-terminal (pending/running) so it never clobbers a richer engine-emitted
+     * terminal status (succeeded/failed/cancelled).
+     */
+    markFailed(error: string, failureClass?: FailureClass, planReviewError?: CouncilPlanReviewError): Promise<void>;
     flush(): Promise<void>;
+    commitPreflightContext({ variables, workflow_context, }: {
+        readonly variables: Readonly<Record<string, unknown>>;
+        readonly workflow_context: WorkflowContext;
+    }): Promise<void>;
+    observeContextBuilderLifecycleTransition(transition: WorkflowContextBuilderLifecycleTransition): Promise<void>;
+    /**
+     * Persist the plan-review aux subtree (A-5).
+     *
+     * Called immediately after `create()` and BEFORE any seat can be dispatched.
+     * It cannot be a `create()` argument in the runtime path: the subtree binds
+     * the canonical snapshot's hash, and the snapshot can only be materialized
+     * into a run directory that `create()` itself makes — and the plan requires a
+     * snapshot/digest failure to be a POST-state `failed` run, not a pre-state
+     * reject. `create()` still validates+persists the subtree when a caller
+     * already has one (e.g. a rebuild), so both entry points are strict.
+     */
+    commitPlanReviewState(state: PlanReviewRunState): Promise<void>;
+    /**
+     * Record that the plan-review context policy was actually enforced at the
+     * preflight seam, together with the post-filtered copied paths (A-7).
+     *
+     * Committed before stage dispatch so a resumed run replays the same enforced
+     * exclusion instead of re-deriving it from caller variables.
+     */
+    commitPlanReviewContextProvenance(provenance: PlanReviewContextProvenance): Promise<void>;
+    /** Persisted-state terminal projection used only by the engine's opt-in policy. */
+    projectPlanReviewTerminalResult(): Promise<string>;
+    /**
+     * Refresh this store's own `run.lock` mtime so a reader that cannot verify our
+     * PID namespace (a containerized or bind-mounted dashboard) has portable
+     * liveness evidence. Observation only — nothing in this module reads the
+     * mtime, and no control path consults it.
+     */
+    private startHeartbeat;
+    /**
+     * One descriptor-bound heartbeat beat: open the lock O_NOFOLLOW read-only,
+     * fstat + bounded positional read through the SAME handle, verify it is still
+     * our token, then utimes that still-open handle. Throws
+     * `RunLockOwnershipLostError` only on a complete valid record whose token
+     * differs; every other failure is an ordinary Error.
+     */
+    private beatRunLock;
+    private stopHeartbeat;
     close(): Promise<void>;
     private applyRetryUpdate;
+    /** Runs inside the caller's existing queue task; never enqueue from here. */
+    private finalizePlanReviewTerminalIntent;
     private enqueueWrite;
     private writeState;
 }
+export declare function readRunStateForStatus(runId: string): Promise<{
+    state: RunState;
+    lock: RunLockStatus;
+} | null>;
+/**
+ * Reap a run that has no live worker (orphaned/stale/prior-process) by writing a
+ * terminal "cancelled" state and unlinking its lock. Used by cancel_workflow when
+ * the run is not in this process's in-memory cancel registry.
+ *
+ * The run.lock is the single source of truth for ownership: this acquires the
+ * lock itself (reusing acquireRunLock, which atomically creates the lock and
+ * reclaims a stale same-host/dead-PID lock) BEFORE mutating, closing the TOCTOU
+ * where a concurrent resume_workflow could grab the lock between a caller's
+ * status read and the reap write.
+ *
+ * Returns:
+ *  - "locked"    — a LIVE lock blocks acquisition (held by a running worker, or a
+ *                  same-process blocking run); nothing is mutated.
+ *  - "ownership_unknown" — the lock is malformed/unreadable; nothing is mutated
+ *                           or reclaimed.
+ *  - "skipped"   — lock acquired but the run is already terminal (not
+ *                  pending/running); the lock is released and nothing is mutated.
+ *                  The caller re-reads to report already_terminal.
+ *  - "cancelled" — lock acquired and run was pending/running; terminal
+ *                  "cancelled" state is written and the lock removed.
+ *
+ * NOTE: This intentionally does NOT use WorkflowStateStore.resume() (which
+ * recovers + re-locks the run — the wrong intent here).
+ */
+export declare function reapRunCancelled(runId: string): Promise<"cancelled" | "skipped" | "locked" | "ownership_unknown">;
+/**
+ * Terminalize run directories frozen as running/pending with no live worker.
+ *
+ * A worker that dies between state writes (e.g. during a retry backoff delay,
+ * where applyRetryUpdate has already persisted errorMessage/failureClass while
+ * the call state stays "running") leaves the run persisted as `running`
+ * forever: the only other reconcile lives in WorkflowStateStore.resume(),
+ * which non-resumable runs never reach, and pruning skips running_or_pending
+ * directories. This scan converts such runs to terminal `failed` so status
+ * projection and retention can move on. No new persisted status is introduced;
+ * STALE_RUN_RECONCILE_ERROR is the distinct terminal representation.
+ *
+ * Liveness authority is classifyRunLockSync's same-host PID probe only:
+ * a run is touched solely when its lock is "stale_or_absent" (missing lock or
+ * same-host dead PID). "held" (live PID, or ANY foreign-host lock) and
+ * "unknown" (malformed lock) are skipped entirely, and no decision here
+ * consults heartbeat mtime freshness. TOCTOU-safety mirrors reapRunCancelled:
+ * acquire the run.lock (no heartbeat declaration, like other reap
+ * acquisitions), re-read state under the lock, re-verify non-terminal, write
+ * once, then release. Idempotent: reconciled runs are terminal `failed` and
+ * count as skipped_terminal on re-scan.
+ */
+export declare function reconcileStaleRunDirectories(runsRootDir: string): Promise<ReconcileStaleRunDirectoriesResult>;