@supernovae-st/nika 0.71.0 → 0.118.7

package/dist/index.d.cts

@@ -0,0 +1,593 @@
+interface NikaSharedConfig {
+    /** Bound for each event subscriber. Default: 256 events. */
+    eventBufferSize?: number;
+    /** Bound for buffered diagnostics and one machine frame. Default: 64 KiB. */
+    machineBufferBytes?: number;
+}
+/** The default configuration drives a native `nika` process. */
+interface NikaLocalConfig extends NikaSharedConfig {
+    /** Working directory used by the native process transport. */
+    cwd?: string;
+    /** Binary resolution: this value, then NIKA_BIN, then the host payload package. */
+    bin?: string;
+    url?: never;
+    token?: never;
+    allowInsecureHttp?: never;
+    requestTimeout?: never;
+    fetch?: never;
+}
+/** Supplying a URL selects the authenticated HTTP transport. */
+interface NikaRemoteConfig extends NikaSharedConfig {
+    /** A `nika serve --bind` base URL. */
+    url: string;
+    /** Bearer token matching the server's `--token-file`. */
+    token: string;
+    /** Plain HTTP is refused unless this is explicitly true. */
+    allowInsecureHttp?: boolean;
+    /** Bound for HTTP admission. Default: 30 seconds. */
+    requestTimeout?: number;
+    /** Fetch implementation used by the HTTP transport. */
+    fetch?: typeof globalThis.fetch;
+    /** Working directory used while capturing the immutable snapshot locally. */
+    cwd?: string;
+    /** Local engine used to capture the immutable snapshot before HTTP admission. */
+    bin?: string;
+}
+/** Public configuration for the one Nika client surface. */
+type NikaConfig = NikaLocalConfig | NikaRemoteConfig;
+type NikaTransportKind = 'native-process' | 'http';
+/**
+ * Brand carrier for engine-issued identities. The SDK brands an identity
+ * only where the engine (or its durable record) issues it; it never invents
+ * one itself.
+ */
+declare const NikaIdentityBrand: unique symbol;
+interface NikaIdentity<Name extends string> {
+    readonly [NikaIdentityBrand]: Name;
+}
+/** A run identity issued by `run()` or `attachRun()`. Assignable to `string`. */
+type NikaRunId = string & NikaIdentity<'NikaRunId'>;
+/** An engine execution identity carried by terminal settlements and receipts. */
+type NikaExecutionId = string & NikaIdentity<'NikaExecutionId'>;
+/** A durable `nika serve` job identity accepted by `attachRun()`. */
+type NikaJobId = string & NikaIdentity<'NikaJobId'>;
+/** Machine vocabulary is additive. Known words aid completion without closing the set. */
+type NikaRunStatus = 'queued' | 'running' | 'paused' | 'succeeded' | 'failed' | 'interrupted' | 'cancelled' | (string & {});
+/** A machine check report. Unknown engine fields deliberately ride through. */
+interface NikaCheckResult {
+    report_version?: number;
+    clean?: boolean;
+    exitCode?: number;
+    [key: string]: unknown;
+}
+/** Fields every engine event can carry, whether its kind is known or not. */
+interface NikaEventFields {
+    status?: NikaRunStatus;
+    sequence?: number;
+    receipt?: NikaReceipt;
+    outputs?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** The workflow graph started executing. */
+interface NikaWorkflowStartedEvent extends NikaEventFields {
+    kind: 'workflow_started';
+}
+/** A task was scheduled for execution. */
+interface NikaTaskScheduledEvent extends NikaEventFields {
+    kind: 'task_scheduled';
+}
+/** A task started executing. */
+interface NikaTaskStartedEvent extends NikaEventFields {
+    kind: 'task_started';
+}
+/** A task settled. Per-task payloads ride the open fields. */
+interface NikaTaskCompletedEvent extends NikaEventFields {
+    kind: 'task_completed';
+}
+/**
+ * The workflow graph settled. This is the terminal frame of a native-process
+ * run and carries the run's outputs, receipt, and final status together.
+ */
+interface NikaWorkflowCompletedEvent<Outputs extends Record<string, unknown> = Record<string, unknown>> extends NikaEventFields {
+    kind: 'workflow_completed';
+    status?: NikaRunStatus;
+    outputs?: Outputs;
+    receipt?: NikaReceipt;
+}
+/** The workflow graph failed. */
+interface NikaWorkflowFailedEvent extends NikaEventFields {
+    kind: 'workflow_failed';
+    error?: NikaMachineError;
+}
+/** The workflow graph was interrupted before settling. */
+interface NikaWorkflowInterruptedEvent extends NikaEventFields {
+    kind: 'workflow_interrupted';
+}
+/**
+ * The terminal settlement frame of a native engine process: the one frame
+ * that carries the run's outputs, receipt, and final status together. Its
+ * HTTP peer is `execution.settled`; one guard narrows both.
+ */
+interface NikaRunSettledEvent<Outputs extends Record<string, unknown> = Record<string, unknown>> extends NikaEventFields {
+    kind: 'run_settled';
+    status?: NikaRunStatus;
+    /** Why the run settled this way (engine 0.118+ · flattened on this frame). */
+    cause?: NikaRunCause;
+    elapsed_ms?: number;
+    tasks?: NikaTaskTally;
+    spend?: NikaSpend;
+    outputs?: Outputs;
+    receipt?: NikaReceipt;
+    /**
+     * The cause of a `failed` settlement (engine 0.117+): the first failed
+     * task's code, message and task id. Absent on a succeeded or paused run,
+     * and on engines that only name the cause on their `task_failed` frame.
+     */
+    error?: NikaMachineError;
+}
+/** The run's trace chain was sealed. */
+interface NikaRunSealedEvent extends NikaEventFields {
+    kind: 'run_sealed';
+    receipt?: NikaReceipt;
+}
+/**
+ * The HTTP transport admitted the execution and it is running. This is the
+ * first lifecycle frame `nika serve --bind` streams for a durable job.
+ */
+interface NikaExecutionStartedEvent extends NikaEventFields {
+    kind: 'execution.started';
+}
+/**
+ * The terminal settlement frame of the HTTP transport, and the peer of
+ * `run_settled`: the one frame that carries the run's outputs, receipt, and
+ * final status together.
+ */
+interface NikaExecutionSettledEvent<Outputs extends Record<string, unknown> = Record<string, unknown>> extends NikaEventFields {
+    kind: 'execution.settled';
+    status?: NikaRunStatus;
+    outputs?: Outputs;
+    receipt?: NikaReceipt;
+    /** The settlement the resident nests whole on this frame (engine 0.118+ · ADR-128). */
+    settlement?: NikaSettlement;
+}
+/**
+ * The resident cancelled the execution: a queued job cancelled before it was
+ * claimed, or a running one whose owner settled the request as a
+ * cancellation. It carries the settlement when the runtime built one.
+ */
+interface NikaExecutionCancelledEvent extends NikaEventFields {
+    kind: 'execution.cancelled';
+    settlement?: NikaSettlement;
+}
+/** The server refused the execution. */
+interface NikaExecutionRefusedEvent extends NikaEventFields {
+    kind: 'execution.refused';
+}
+/**
+ * The execution was interrupted before settling. A resident that restarts
+ * marks an orphaned running job with either word, so both are one variant.
+ */
+interface NikaExecutionInterruptedEvent extends NikaEventFields {
+    kind: 'execution.interrupted' | 'interrupted';
+}
+/**
+ * Forward-compatibility variant: any kind this SDK version does not know
+ * yet stays representable, so the event union is intentionally
+ * non-exhaustive.
+ */
+interface NikaUnknownEvent extends NikaEventFields {
+    kind?: string;
+}
+/**
+ * One engine-owned run event, from either transport: the native process emits
+ * the `workflow_*` / `task_*` / `run_*` kinds, `nika serve` emits the
+ * `execution.*` kinds. Known kinds discriminate on `kind`; unknown kinds fall
+ * back to `NikaUnknownEvent`. Future fields stay open on every variant.
+ * `Outputs` types the terminal frames' outputs and defaults to the transport
+ * shape, so untyped callers see no change.
+ */
+type NikaEvent<Outputs extends Record<string, unknown> = Record<string, unknown>> = NikaWorkflowStartedEvent | NikaTaskScheduledEvent | NikaTaskStartedEvent | NikaTaskCompletedEvent | NikaWorkflowCompletedEvent<Outputs> | NikaWorkflowFailedEvent | NikaWorkflowInterruptedEvent | NikaRunSettledEvent<Outputs> | NikaRunSealedEvent | NikaExecutionStartedEvent | NikaExecutionSettledEvent<Outputs> | NikaExecutionCancelledEvent | NikaExecutionRefusedEvent | NikaExecutionInterruptedEvent | NikaUnknownEvent;
+/**
+ * Engine-issued proof material. The SDK transports it but never constructs,
+ * reads a workflow to enrich it, or verifies its claims itself.
+ */
+type NikaReceipt = Readonly<Record<string, unknown>>;
+interface NikaMachineError {
+    code?: string;
+    message?: string;
+    /** The task that failed, when a native `task_failed` frame named it. */
+    task?: string;
+    [key: string]: unknown;
+}
+/** Why a run settled the way it did (engine 0.118+ · ADR-128). */
+type NikaRunCause = 'normal' | 'human_gate' | 'task_failed' | 'output_contract' | 'budget' | 'operator' | 'refused' | (string & {});
+/**
+ * How much of the spend is priced (engine 0.118+): `unmetered` = no metered
+ * call · `unpriced` = a local or subscription seat, never free · `partially_priced`
+ * · `priced`.
+ */
+type NikaCostQualifier = 'priced' | 'partially_priced' | 'unpriced' | 'unmetered' | (string & {});
+/** How the run's tasks ended (engine 0.118+): `recovered` is a tally, never a state. */
+interface NikaTaskTally {
+    total?: number;
+    ok?: number;
+    failed?: number;
+    recovered?: number;
+    skipped?: number;
+    cancelled?: number;
+    never_started?: number;
+    [key: string]: unknown;
+}
+/** What the run spent and how much of it is priced (engine 0.118+). */
+interface NikaSpend {
+    /** Present only when at least one call metered real spend; unknown cost is never zero. */
+    total_cost_usd?: number | null;
+    priced_calls?: number;
+    unpriced_calls?: number;
+    qualifier?: NikaCostQualifier;
+    pricing_as_of?: string | null;
+    /** Spend per pricing source, when the engine broke it down. */
+    by_source?: Record<string, number>;
+    [key: string]: unknown;
+}
+/**
+ * The run's settlement as the engine built it once (ADR-128): the state's
+ * cause, the task tally, the spend and its qualifier, the elapsed time.
+ * Absent on engines before 0.118; never derived from an exit code.
+ */
+interface NikaSettlement {
+    /**
+     * The state word the settlement itself carries (`succeeded` · `failed` ·
+     * `paused` · `cancelled`) on the resident's nested projection; the native
+     * `run_settled` frame states it on the frame instead.
+     */
+    status?: NikaRunStatus;
+    cause?: NikaRunCause;
+    elapsed_ms?: number;
+    tasks?: NikaTaskTally;
+    spend?: NikaSpend;
+    /** The failure named on a `failed` settlement: code, message and the task, when one failed. */
+    error?: NikaMachineError;
+    [key: string]: unknown;
+}
+/** The only terminal value for a run. */
+interface NikaRunResult<Outputs extends Record<string, unknown> = Record<string, unknown>> {
+    id: NikaRunId;
+    status: NikaRunStatus;
+    transport: NikaTransportKind;
+    exitCode?: number;
+    outputs?: Outputs;
+    receipt?: NikaReceipt;
+    error?: NikaMachineError;
+    /** Engine execution identity, when the transport surface reports one. */
+    execution_id?: NikaExecutionId;
+    /** The settlement's cause, tally and spend (engine 0.118+), when the terminal frame carried them. */
+    settlement?: NikaSettlement;
+    [key: string]: unknown;
+}
+/** A run identity plus its one terminal settlement. */
+interface NikaRun<Outputs extends Record<string, unknown> = Record<string, unknown>> {
+    readonly id: NikaRunId;
+    readonly done: Promise<NikaRunResult<Outputs>>;
+}
+interface NikaCancelResult {
+    runId: NikaRunId;
+    accepted: boolean;
+    /**
+     * `cancelled`: the job settled cancelled on the cancel reply itself.
+     * `already_settled`: the run had already ended, nothing was cancelled.
+     * `cancellation_requested`: the request was accepted while the execution
+     * owner had not settled yet (a native SIGTERM, or the resident's 202); the
+     * run then settles on its own terminal, read from `run.done`, which may be
+     * `cancelled`, `succeeded`, `failed`, or `interrupted` once the resident's
+     * grace expired. Open to the engine's future words.
+     */
+    status: 'cancelled' | 'already_settled' | 'cancellation_requested' | (string & {});
+    transport: NikaTransportKind;
+    [key: string]: unknown;
+}
+/** Server-owned metadata for one contained resident workflow. */
+interface NikaWorkflowMetadata {
+    workflow: string;
+    [key: string]: unknown;
+}
+interface NikaTraceVerifyResult {
+    verified: boolean;
+    /**
+     * Engine-owned trace verdict. The native path answers `verified` or
+     * `invalid`; the resident's door answers `unavailable` while it has no
+     * trace-journal authority (engine 0.118), and will speak the CLI's tiers
+     * (`OK` · `SEALED` · `ANCHORED` · `REPLAYED` hold · `INCOMPLETE` ·
+     * `TAMPERED` do not) once it does. Open to additive future vocabulary.
+     */
+    verdict?: 'verified' | 'invalid' | 'unavailable' | 'OK' | 'SEALED' | 'ANCHORED' | 'REPLAYED' | 'INCOMPLETE' | 'TAMPERED' | (string & {});
+    /** Engine-owned explanation for a negative or unavailable verdict; a verdict that holds carries none. */
+    reason?: 'trace_invalid' | 'receipt_mismatch' | 'run_not_terminal' | 'trace_journal_unavailable' | (string & {});
+    trace_id?: string;
+    exitCode?: number;
+    output?: string;
+    [key: string]: unknown;
+}
+interface NikaCheckOptions {
+    model?: string;
+    nativeStrict?: boolean;
+    /** Stops only this check request/process. */
+    signal?: AbortSignal;
+}
+interface NikaRunOptions {
+    vars?: Record<string, string | number | boolean>;
+    model?: string;
+    maxCostUsd?: number;
+    /** Retained for HTTP admission deduplication. */
+    idempotencyKey?: string;
+}
+/** Resume observation of an already-admitted durable HTTP job. */
+interface NikaAttachRunOptions {
+    /** Last SSE sequence durably consumed by the caller. Default: 0. */
+    lastEventId?: number;
+}
+interface NikaEventsOptions {
+    /** Stops this subscriber view. It never cancels the run. */
+    signal?: AbortSignal;
+    /** Per-view queue bound, capped by the client eventBufferSize. */
+    bufferSize?: number;
+}
+interface NikaTraceVerifyOptions {
+    /** Stops only the verification request/process. */
+    signal?: AbortSignal;
+}
+/** The SDK operations whose engine refusal can be returned as a typed error. */
+type NikaOperation = 'check' | 'run' | 'attachRun' | 'status' | 'cancel' | 'listWorkflows' | 'workflow' | 'traceVerify' | 'schedule' | 'scheduleStatus';
+/** One engine-owned schedule finding. The vocabulary remains additive. */
+interface NikaScheduleFinding {
+    code: string;
+    detail: string;
+    [key: string]: unknown;
+}
+/** Findings carried by the one operation-error taxonomy. */
+type NikaOperationFinding = NikaScheduleFinding;
+type NikaScheduleWhen = {
+    kind: 'once';
+    at: string;
+} | {
+    kind: 'cadence';
+    expression: string;
+};
+/** Exact declarative input accepted by PUT /v1/schedules/{id}. */
+interface NikaScheduleOptions {
+    /** Stable path identity for the resident schedule. */
+    id: string;
+    when: NikaScheduleWhen;
+    maxCostUsd: number;
+    missed: 'catch-up' | 'catch-up-once' | 'skip';
+    maxLatenessSeconds?: number;
+    overlap?: 'skip' | 'queue' | 'replace';
+    afterSkip?: 'next_slot' | 'on_completion';
+    jitter?: 'hash';
+    tolerance?: string;
+    active?: boolean;
+    pauseReason?: string;
+    /** ISO calendar date (`YYYY-MM-DD`) required when active is false. */
+    pauseUntil?: string;
+    /** Exact prior revision for an update. Omit for create-if-absent. */
+    revision?: string;
+}
+type NikaScheduleMissed = 'catch-up' | 'catch-up-once' | 'skip' | (string & {});
+type NikaScheduleOverlap = 'skip' | 'queue' | 'replace' | (string & {});
+type NikaScheduleAfterSkip = 'next_slot' | 'on_completion' | (string & {});
+/** The engine-normalized schedule definition; the SDK never normalizes it. */
+interface NikaScheduleDefinition {
+    id: string;
+    workflow: string;
+    when: NikaScheduleWhen | {
+        kind: string;
+        [key: string]: unknown;
+    };
+    maxCostUsd: number;
+    missed: NikaScheduleMissed;
+    maxLatenessSeconds: number | null;
+    overlap: NikaScheduleOverlap;
+    afterSkip: NikaScheduleAfterSkip;
+    jitter: 'hash' | (string & {}) | null;
+    tolerance: string | null;
+    active: boolean;
+    pauseReason: string | null;
+    pauseUntil: string | null;
+    [key: string]: unknown;
+}
+interface NikaScheduleSlot {
+    slotId: string;
+    scheduledFor: string;
+    requestedCivil: string | null;
+    shift: 'exact' | 'advanced_first_valid' | 'folded_first' | (string & {});
+    [key: string]: unknown;
+}
+type NikaScheduleDue = {
+    kind: 'scheduled';
+    slot: NikaScheduleSlot;
+} | {
+    kind: 'catch_up';
+    slot: NikaScheduleSlot;
+    missedSlots: number;
+} | {
+    kind: 'skipped_missed';
+    slot: NikaScheduleSlot;
+    missedSlots: number;
+} | {
+    kind: 'skipped_too_late';
+    slot: NikaScheduleSlot;
+    latenessSeconds: number;
+    maximumSeconds: number;
+} | {
+    kind: 'paused';
+    reason: string | null;
+    pauseUntil: string | null;
+} | {
+    kind: 'once_consumed';
+    slotId: string;
+    scheduledFor: string;
+} | {
+    kind: 'not_due';
+} | {
+    kind: string & {};
+    [key: string]: unknown;
+};
+interface NikaSchedulePause {
+    reason: string | null;
+    until: string | null;
+}
+interface NikaScheduleClaim {
+    runId: string;
+    executionId: string;
+    traceId: string;
+    generation: string;
+    [key: string]: unknown;
+}
+interface NikaScheduleLastDecision {
+    action: 'claimed' | 'skipped' | (string & {});
+    decision: 'scheduled' | 'catch_up' | (string & {});
+    revision: string;
+    slotId: string;
+    scheduledFor: string;
+    decidedAt: string;
+    reason: string | null;
+    claim: NikaScheduleClaim | null;
+    [key: string]: unknown;
+}
+/** Fresh engine planning facts. The SDK transports them without interpretation. */
+interface NikaScheduleStatus {
+    definition: NikaScheduleDefinition;
+    origin: 'api' | (string & {});
+    revision: string;
+    active: boolean;
+    pause: NikaSchedulePause | null;
+    due?: NikaScheduleDue;
+    finding?: NikaScheduleFinding;
+    next: NikaScheduleSlot[];
+    earliestWakeHint: string | null;
+    lastDecision: NikaScheduleLastDecision | null;
+    [key: string]: unknown;
+}
+/** Durable apply acknowledgement. It does not wait for a scheduled fire. */
+interface NikaScheduleApplyResult {
+    applied: true;
+    changed: boolean;
+    status: NikaScheduleStatus;
+}
+
+declare class NikaError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+declare class NikaConfigurationError extends NikaError {
+    constructor(message: string);
+}
+declare class NikaTransportError extends NikaError {
+    readonly transport: NikaTransportKind;
+    constructor(transport: NikaTransportKind, message: string, options?: ErrorOptions);
+}
+/** A typed engine/adapter capability gap, not a workflow failure. */
+declare class NikaCompatibilityError extends NikaError {
+    readonly capability: string;
+    readonly transport: NikaTransportKind;
+    constructor(capability: string, transport: NikaTransportKind, message: string);
+}
+declare class NikaProtocolError extends NikaTransportError {
+    constructor(transport: NikaTransportKind, message: string, options?: ErrorOptions);
+}
+/**
+ * Observation broke before terminal settlement and the final durable read
+ * stayed non-terminal. The cursor feeds attachRun(id, { lastEventId }).
+ */
+declare class NikaObservationInterrupted extends NikaTransportError {
+    readonly runId: string;
+    readonly lastSequence: number;
+    readonly attempts: number;
+    constructor(transport: NikaTransportKind, runId: string, lastSequence: number, attempts: number);
+}
+/** One taxonomy for engine refusals returned by an SDK operation. */
+declare class NikaOperationError extends NikaError {
+    readonly operation: NikaOperation;
+    readonly code: string;
+    readonly transport: NikaTransportKind;
+    readonly status: number;
+    readonly findings?: readonly NikaOperationFinding[];
+    readonly currentRevision?: string | null;
+    readonly machineCode?: string;
+    constructor(operation: NikaOperation, transport: NikaTransportKind, code: string, message: string, details: {
+        status: number;
+        findings?: readonly NikaOperationFinding[];
+        currentRevision?: string | null;
+        machineCode?: string;
+    });
+}
+declare class NikaEventBufferOverflowError extends NikaError {
+    readonly runId: string;
+    readonly limit: number;
+    constructor(runId: string, limit: number);
+}
+declare class NikaRunOwnershipError extends NikaError {
+    constructor();
+}
+
+/** The local engine could not be resolved without an implicit PATH lookup. */
+declare class NikaEngineUnavailable extends NikaError {
+    readonly code = "NIKA_ENGINE_UNAVAILABLE";
+    readonly platform: string;
+    readonly arch: string;
+    readonly packageName?: string;
+    constructor(platform: string, arch: string, packageName?: string);
+}
+
+/**
+ * Narrows any run event to the terminal settlement frame, which carries the
+ * run's status, outputs, and receipt together. Both transports have one: the
+ * native process emits `run_settled`, `nika serve` emits `execution.settled`.
+ * Kind equality alone cannot exclude the forward-compatibility variant; this
+ * guard can.
+ */
+declare function isNikaRunSettledEvent<Outputs extends Record<string, unknown> = Record<string, unknown>>(event: NikaEvent<Outputs>): event is NikaRunSettledEvent<Outputs> | NikaExecutionSettledEvent<Outputs>;
+/**
+ * Narrows any run event to a terminal one by the status the engine reported,
+ * not by its kind, so it holds on either transport and across kinds this SDK
+ * version does not know yet. It therefore also covers the frames that end a
+ * run without settling outputs: `execution.cancelled`, `execution.refused`,
+ * `interrupted`, `workflow_failed` and `workflow_cancelled` (the engine's
+ * four run terminals are `workflow_completed` · `workflow_failed` ·
+ * `workflow_paused` · `workflow_cancelled` · ADR-128).
+ */
+declare function isNikaTerminalEvent<Outputs extends Record<string, unknown> = Record<string, unknown>>(event: NikaEvent<Outputs>): event is NikaEvent<Outputs> & {
+    status: 'succeeded' | 'failed' | 'interrupted' | 'cancelled';
+};
+/** Narrows any run event to the frame that sealed the run's trace chain. */
+declare function isNikaRunSealedEvent<Outputs extends Record<string, unknown> = Record<string, unknown>>(event: NikaEvent<Outputs>): event is NikaRunSealedEvent;
+
+/** One client surface for a local engine process or a live nika serve URL. */
+declare class Nika {
+    readonly transportKind: NikaTransportKind;
+    private readonly transport;
+    private readonly sessions;
+    private readonly eventBufferSize;
+    constructor(config?: NikaConfig);
+    check(workflow: string, options?: NikaCheckOptions): Promise<NikaCheckResult>;
+    /**
+     * `Outputs` is the caller's projection of the engine-emitted outputs map;
+     * the SDK transports outputs without validating their shape.
+     */
+    run<Outputs extends Record<string, unknown> = Record<string, unknown>>(workflow: string, options?: NikaRunOptions): Promise<NikaRun<Outputs>>;
+    /** Reattach this client process to an already-admitted durable HTTP job. */
+    attachRun<Outputs extends Record<string, unknown> = Record<string, unknown>>(id: string, options?: NikaAttachRunOptions): Promise<NikaRun<Outputs>>;
+    /** List contained workflow names from a resident HTTP authority. */
+    listWorkflows(): Promise<readonly string[]>;
+    /** Read path-free metadata for one contained workflow. */
+    workflow(name: string): Promise<NikaWorkflowMetadata>;
+    events<Outputs extends Record<string, unknown> = Record<string, unknown>>(run: NikaRun<Outputs>, options?: NikaEventsOptions): AsyncIterable<NikaEvent<Outputs>>;
+    cancel(run: NikaRun): Promise<NikaCancelResult>;
+    /** Read the current durable status without waiting for terminal settlement. */
+    status(run: NikaRun): Promise<NikaRunStatus>;
+    schedule(workflow: string, options: NikaScheduleOptions): Promise<NikaScheduleApplyResult>;
+    scheduleStatus(id: string): Promise<NikaScheduleStatus>;
+    traceVerify(receipt: NikaReceipt, options?: NikaTraceVerifyOptions): Promise<NikaTraceVerifyResult>;
+    private session;
+}
+
+export { Nika, type NikaAttachRunOptions, type NikaCancelResult, type NikaCheckOptions, type NikaCheckResult, NikaCompatibilityError, type NikaConfig, NikaConfigurationError, type NikaCostQualifier, NikaEngineUnavailable, NikaError, type NikaEvent, NikaEventBufferOverflowError, type NikaEventsOptions, type NikaExecutionCancelledEvent, type NikaExecutionId, type NikaExecutionInterruptedEvent, type NikaExecutionRefusedEvent, type NikaExecutionSettledEvent, type NikaExecutionStartedEvent, type NikaJobId, type NikaLocalConfig, type NikaMachineError, NikaObservationInterrupted, type NikaOperation, NikaOperationError, type NikaOperationFinding, NikaProtocolError, type NikaReceipt, type NikaRemoteConfig, type NikaRun, type NikaRunCause, type NikaRunId, type NikaRunOptions, NikaRunOwnershipError, type NikaRunResult, type NikaRunSealedEvent, type NikaRunSettledEvent, type NikaRunStatus, type NikaScheduleAfterSkip, type NikaScheduleApplyResult, type NikaScheduleClaim, type NikaScheduleDefinition, type NikaScheduleDue, type NikaScheduleFinding, type NikaScheduleLastDecision, type NikaScheduleMissed, type NikaScheduleOptions, type NikaScheduleOverlap, type NikaSchedulePause, type NikaScheduleSlot, type NikaScheduleStatus, type NikaScheduleWhen, type NikaSettlement, type NikaSpend, type NikaTaskCompletedEvent, type NikaTaskScheduledEvent, type NikaTaskStartedEvent, type NikaTaskTally, type NikaTraceVerifyOptions, type NikaTraceVerifyResult, NikaTransportError, type NikaTransportKind, type NikaUnknownEvent, type NikaWorkflowCompletedEvent, type NikaWorkflowFailedEvent, type NikaWorkflowInterruptedEvent, type NikaWorkflowMetadata, type NikaWorkflowStartedEvent, isNikaRunSealedEvent, isNikaRunSettledEvent, isNikaTerminalEvent };