@victframework/runtime 0.1.0

package/dist/runtime.d.ts

@@ -0,0 +1,158 @@
+import type { OrchestrationRunResult, ProcessDueTimersOptions, ProcessDueTimersResult, ResolveBlockedInput, ResolveBlockedOutcome, SignalCommand, SignalResult, CancelCommand, CancelResult, RecoverOrchestrationOptions, RecoverOrchestrationSummary } from './orchestration-driver-types.js';
+import type { ApplicationGraphDefinition, KernelEvent } from '@victframework/kernel';
+import { CapabilityRegistry } from './registry.js';
+import type { RecoveryResult } from './store-types.js';
+import type { ActivationResult, ActiveGraphInfo, CapabilityDefinition, DoubleInvoke, RestorationResult, RunNodeOptions, RunOptions, RunRecord, RunResult, VictRuntimeOptions } from './types.js';
+declare const RECOVERY_CODE = "VICT_RUN_INTERRUPTED_BY_RESTART";
+declare const RECOVERY_REASON = "The process executing this run ended before the run reached a terminal state.";
+declare const RECOVERY_REMEDIATION = "Automatic resume is unavailable at this stage. Inspect the run and its events, then start a deliberate new run; the new run receives a new run id.";
+export { RECOVERY_CODE, RECOVERY_REASON, RECOVERY_REMEDIATION };
+/**
+ * The usable in-process Vict runtime.
+ *
+ * Composes a capability registry, the active activation snapshot, execution
+ * policy, and durable semantic stores (activation catalog + execution
+ * store). Contains no ARA-specific logic.
+ *
+ * Safety model:
+ * - Activation is atomic from the caller's perspective: the candidate is
+ *   compiled, snapshotted, and published/selected in the catalog BEFORE the
+ *   in-memory snapshot is replaced. A failed compile or storage write leaves
+ *   the previously active graph selected and runnable.
+ * - Activation manifests are immutable and durable; every run pins exactly
+ *   one activationVersion (RUN-001), persisted with the run.
+ * - Runs execute against the pinned snapshot; in-flight runs cannot observe
+ *   registry changes. Every run transition and its events are committed
+ *   atomically (DATA-003) with optimistic concurrency, and the durable
+ *   write-ahead rule holds: a capability is invoked only after its
+ *   `node.started` intent (and every preceding durable write) has committed.
+ * - Test doubles are snapshotted at run start; replacing a double mid-run
+ *   affects only later runs. Duplicate `registerDouble` is rejected; use
+ *   `replaceDouble`.
+ * - Effect policy is enforced before any capability runs (see effect-policy).
+ *   Irreversible effects never run their real implementation in simulate or
+ *   test modes; in those modes a registered safe double may run, and without
+ *   one the operation is blocked.
+ * - Run records are retained according to the runtime's `payloadRetention`
+ *   (default `'summary'`): complete payloads are stored only under explicit
+ *   `'full'` retention — which transfers responsibility for the persisted
+ *   content to the caller/operator. Thrown error messages are never stored.
+ */
+export declare class VictRuntime {
+    #private;
+    constructor(options?: VictRuntimeOptions);
+    /**
+     * Drive an existing orchestration run to terminal/quiescent against its
+     * EXACT pinned activation. Selection changes never affect this run; a
+     * newer selected activation applies only to future runs.
+     */
+    resumeRun<T = unknown>(runId: string, options?: {
+        concurrency?: number;
+        onEvent?: (event: KernelEvent) => void;
+    }): Promise<OrchestrationRunResult<T>>;
+    /** Idempotently deliver one signal to one exact durable wait. */
+    signal(command: SignalCommand): Promise<SignalResult>;
+    /** Idempotently request cancellation of one orchestration run. */
+    cancel(command: CancelCommand): Promise<CancelResult>;
+    /** Resolve bounded due timers (timer waits, wait timeouts, retry backoff). */
+    processDueTimers(options?: ProcessDueTimersOptions): Promise<ProcessDueTimersResult>;
+    /**
+     * Explicit boot-time effect-aware recovery for orchestration runs:
+     * reclaim policy-permitted expired claims (pure/read recompute; keyed
+     * write retries with the same key) and block ambiguous unsafe work.
+     * Historical Stage 02 sequential recovery is unchanged.
+     */
+    recoverOrchestration(options?: RecoverOrchestrationOptions): Promise<RecoverOrchestrationSummary>;
+    /**
+     * Bounded authorized operator resolution for one blocked run. Denied by
+     * default: only runtimes explicitly constructed with
+     * `orchestration.operatorAuthorized: true` may resolve blocked work.
+     */
+    resolveBlocked(input: ResolveBlockedInput): Promise<ResolveBlockedOutcome>;
+    registerCapability<I, O>(definition: CapabilityDefinition<I, O>): this;
+    /**
+     * Install a batch atomically (used by `installCapabilityPack`). Stages
+     * every contract/capability/double and commits only on full success.
+     */
+    installCapabilityPackBatch(install: (staging: {
+        registerContract(contract: Parameters<CapabilityRegistry['registerContract']>[0]): void;
+        registerCapability(definition: CapabilityDefinition): void;
+        registerDouble(capabilityId: string, invoke: DoubleInvoke, options?: {
+            readonly modes?: readonly ('test' | 'simulate')[];
+        }): void;
+    }) => void): void;
+    registerContract(contract: Parameters<CapabilityRegistry['registerContract']>[0]): this;
+    /** Register a test double. Duplicate registration is rejected; use `replaceDouble`. */
+    registerDouble(capabilityId: string, invoke: DoubleInvoke, options?: {
+        readonly modes?: readonly ('test' | 'simulate')[];
+    }): this;
+    /** Explicitly replace an existing test double. Later runs use the replacement; in-flight runs do not. */
+    replaceDouble(capabilityId: string, invoke: DoubleInvoke): this;
+    /** True when a test double is registered for the capability. */
+    hasDouble(capabilityId: string): boolean;
+    /** The eligible modes of a registered test double (undefined when none is registered). */
+    getDoubleModes(capabilityId: string): ReadonlySet<'test' | 'simulate'> | undefined;
+    /**
+     * Compile and activate a graph atomically from the caller's perspective:
+     *
+     * 1. compile and resolve the candidate completely;
+     * 2. snapshot capability and captured contract parsing semantics;
+     * 3. build and validate the serializable manifest;
+     * 4. publish and select it in the durable catalog (one transaction);
+     * 5. only then replace the active in-memory snapshot.
+     *
+     * A compile failure returns a structured rejection; a storage failure
+     * throws a structured store error. In both cases the previously active
+     * graph remains selected and runnable, and durable state never claims an
+     * activation the catalog did not select.
+     */
+    activate(definition: ApplicationGraphDefinition): Promise<ActivationResult>;
+    /**
+     * Restore the exact durable activation for a graph definition.
+     *
+     * The current registered code (capabilities and contracts) must reproduce
+     * the stored activation exactly: the definition is recompiled against the
+     * live registry, all three version identities are recomputed, and the
+     * rebuilt canonical manifest is compared with the stored one. On an exact
+     * match the activation becomes the active in-memory snapshot. On any
+     * mismatch the stored manifest is preserved, the currently active graph is
+     * left unchanged, no capability is executed, and no “closest” revision is
+     * chosen.
+     *
+     * By default the activation currently selected for `definition.id` is
+     * restored; pass `activationVersion` to restore a specific one.
+     */
+    restoreActivation(definition: ApplicationGraphDefinition, options?: {
+        activationVersion?: string;
+    }): Promise<RestorationResult>;
+    /**
+     * Explicit boot-time recovery (single local owner). Finds runs left in a
+     * nonterminal running state by a previous process, atomically transitions
+     * each to `blocked`, and appends one safe interruption event. Never
+     * invokes or replays a capability. Repeated recovery is idempotent.
+     */
+    recoverInterruptedRuns(): Promise<RecoveryResult>;
+    activeGraph(): ActiveGraphInfo | undefined;
+    /**
+     * Execute the active graph. Capability-only graphs keep the verified
+     * Stage 02 sequential engine; graphs with control nodes run on the Stage
+     * 03 durable orchestration driver (token/attempt state machine). Run
+     * transitions and events are committed to the store atomically as the
+     * run progresses; when `run()` resolves, the durable record is current.
+     */
+    run<T = unknown>(input: unknown, options?: RunOptions): Promise<RunResult<T>>;
+    /**
+     * Execute a single node of the active graph in isolation (mode forced to
+     * `'test'`). The isolated compile resolves against the activation snapshot,
+     * so post-activation registry changes cannot affect it. Does not traverse
+     * edges, does not change the active graph, and does not write durable run
+     * records. The trace is returned directly.
+     */
+    runNode<T = unknown>(nodeId: string, input: unknown, options?: RunNodeOptions): Promise<RunResult<T>>;
+    /** All stored runs (assembled views with their traces), oldest first. */
+    listRuns(): Promise<readonly RunRecord[]>;
+    /** One stored run (assembled view with its trace), or undefined. */
+    getRun(runId: string): Promise<RunRecord | undefined>;
+}
+/** Create a runtime instance. Application code should use the `@victframework/sdk` facade instead. */
+export declare function createRuntime(options?: VictRuntimeOptions): VictRuntime;