@voltro/runtime 0.75.0 → 0.77.0

package/dist/index.d.ts

@@ -128,6 +128,7 @@ import { WorkflowControlRequest } from '@voltro/workflow';
 import { WorkflowControlResult as WorkflowControlResult_2 } from '@voltro/protocol';
 import { WorkflowParentClosePolicy } from '@voltro/protocol';
 import { WorkflowQueuedCancellationResult } from '@voltro/protocol';
+import { WorkflowRetryObservation } from '@voltro/protocol';
 import { WorkflowRunHandle } from '@voltro/protocol';
 import { WorkflowRunSnapshot as WorkflowRunSnapshot_2 } from '@voltro/protocol';
 import { WorkflowStartResolution } from '@voltro/workflow';
@@ -1843,6 +1844,13 @@ export declare const bindSubscriptionUntyped: (descriptor: QueryDescriptor, disp
     readonly reconcile?: string;
 }) => Stream.Stream<SubscriptionEvent<ReadonlyArray<Row>>, never, never>;
 
+export declare const BOOT_REFUSAL_NAME = "VoltroBootRefusal";
+
+/** An error the boot path raised on purpose. The launcher prints its message
+ *  once and exits 1 instead of degrading to a fallback path or printing a
+ *  stack. */
+export declare const bootRefusal: (message: string) => Error;
+
 export declare interface BrandedScheduleDefinition extends ScheduleDefinition {
     readonly [SCHEDULE_BRAND]: true;
 }
@@ -2502,6 +2510,27 @@ export declare interface CoordinatedScheduleDeps {
     readonly disarmWhenIdle?: boolean;
 }
 
+export declare interface CoordinatedScheduleDiagnostics {
+    readonly task: string;
+    readonly state: 'armed' | 'running' | 'disarmed' | 'externalized' | 'stopped';
+    readonly baseIntervalMs: number;
+    readonly currentIntervalMs: number;
+    readonly maxIdleIntervalMs: number;
+    readonly nextTickAt: number | null;
+    readonly disarmWhenIdle: boolean;
+    readonly ticks: number;
+    readonly claimWins: number;
+    readonly claimLosses: number;
+    readonly claimFailures: number;
+    readonly taskFailures: number;
+    readonly wakes: number;
+    readonly coalescedWakes: number;
+    readonly lastTickAt: number | null;
+    readonly lastWakeAt: number | null;
+    readonly lastDecision: 'starting' | 'idle-backoff' | 'idle-disarmed' | 'active' | 'claim-lost' | 'claim-failed' | 'task-failed' | 'wake';
+    readonly lastOutcome: CoordinatedTickOutcome | null;
+}
+
 export declare interface CoordinatedScheduleHandle {
     /** Stop the periodic task. Idempotent. */
     readonly stop: () => void;
@@ -3480,6 +3509,8 @@ export declare const deliveredRowCount: (value: unknown) => number;
  */
 export declare const deriveKey: (passphrase: string) => Buffer;
 
+export declare const describeOtelReasons: (why: OtelNeededBecause) => ReadonlyArray<string>;
+
 /**
  * Detach a live subscription for possible resume. The sink is redirected to
  * ring-recording only; after the window the subscription is truly
@@ -4715,6 +4746,8 @@ export declare interface ExpectationState {
     readonly name: string;
     readonly table: string;
     readonly invariant: ExpectationInvariant['kind'];
+    /** Full declarative condition used by the evaluator. */
+    readonly rule: ExpectationInvariant;
     readonly severity: ExpectationSeverity;
     readonly status: ExpectationStatus;
     /** The measured metric: freshness → age in ms; nullRate / valueBounds(rate) →
@@ -5651,6 +5684,10 @@ export declare const insertManyRowsEffect: <T extends AnyWritableTable>(store: E
  */
 export declare const insertRowEffect: <T extends AnyWritableTable>(store: EffectInsertStore, table: T, row: InferInsertRow<T>) => Effect.Effect<InferRow<T>, StoreError>;
 
+/** Process-local counters, not fleet totals. Unknown/custom handles return null.
+ * Reading never ticks, claims, queries storage, or exposes task payloads/errors. */
+export declare const inspectCoordinatedSchedule: (handle: Pick<CoordinatedScheduleHandle, "stop" | "wake">) => CoordinatedScheduleDiagnostics | null;
+
 export { InspectedStep }
 
 export { InspectedWorkflow }
@@ -5663,6 +5700,9 @@ export { InspectedWorkflow }
  * dep on the cli's manifest shape.
  */
 export declare interface InspectRoute {
+    /** Exact binary paths are dispatched before UTF-8 body decoding. Each
+     * handler owns authentication and bounded consumption of its byte stream. */
+    readonly binary?: Readonly<Record<string, (url: string, headers: Readonly<Record<string, string>>, method: string, body: ReadableStream<Uint8Array>, signal: AbortSignal) => Promise<Awaited<ReturnType<InspectRoute['handle']>>>>>;
     /** Synchronous handler taking the full request URL (e.g.
      *  `/_voltro/inspect/app`) and returning the response triple.
      *  Returns `null` only for non-inspect paths, which can't happen
@@ -5817,6 +5857,8 @@ export declare const ipToBytes: (ip: string) => Uint8Array | undefined;
 
 export declare const isAggregateDefinition: (value: unknown) => value is AggregateDefinition;
 
+export declare const isBootRefusal: (error: unknown) => boolean;
+
 export declare const isCompressibleContentType: (contentType: string | undefined) => boolean;
 
 export declare const isCostBudgetDefinition: (value: unknown) => value is CostBudgetDefinition;
@@ -7408,7 +7450,50 @@ export declare type OriginGuardMode = 'off' | 'same-origin';
  * that relabels every failure is how a diagnosis gets buried — the same reason
  * the serve bundle marks its deliberate refusals instead of swallowing throws.
  */
-export declare const otelImportFailure: (cause: unknown) => Error;
+export declare const otelImportFailure: (cause: unknown, reasons?: ReadonlyArray<string>) => Error;
+
+/**
+ * `@effect/opentelemetry` is an OPTIONAL peer, so this import can legitimately
+ * fail — and the failure has to be readable.
+ *
+ * Why it is optional: it is reached only from here, only when tracing is on,
+ * and it declares SEVEN non-optional OpenTelemetry peers of its own, two of
+ * which we do not supply (`@opentelemetry/sdk-logs`, and
+ * `@opentelemetry/sdk-trace-web`, which is the BROWSER tracer and has no
+ * business in a server dependency). Carrying it as a hard dependency printed 24
+ * lines of unmet-peer warnings on every `pnpm install` of every consumer,
+ * describing a condition that broke nothing.
+ *
+ * A deployment's argument for why that is worth fixing is the one that decided
+ * it: *"a check that is loud on every upgrade teaches people to skip the
+ * output, and the next warning in that block is the one that matters. We read
+ * past this one for four releases."*
+ *
+ * The trade is that an app which turns tracing ON without installing it now
+ * gets an error instead of a warning — so this message has to name the exact
+ * install, not surface a bare `ERR_MODULE_NOT_FOUND` for a package the app
+ * never wrote down.
+ */
+/**
+ * Why the OpenTelemetry SDK is about to be loaded — one line per cause, each
+ * with the switch that removes it. Computed by `buildTracingLayer` from the
+ * same predicates that decide whether the SDK is needed at all, so the message
+ * cannot claim a cause the layer did not act on.
+ *
+ * The first shipped message said "tracing is enabled … turn it off:
+ * FRAMEWORK_TRACING=off". Measured with the package hidden: `voltro dev` with
+ * NO tracing variable set refuses on that line, because dev arms its trace ring
+ * unconditionally — and `FRAMEWORK_TRACING=off` does nothing to the ring. The
+ * reader was told the wrong knob for the only cause that applied.
+ */
+export declare interface OtelNeededBecause {
+    readonly mode: TracingMode;
+    readonly metricsMode: MetricsMode;
+    readonly traceSink: boolean;
+    readonly traceSinkOrigin?: string | undefined;
+    readonly pluginSpanProcessors: number;
+    readonly pluginMetricReaders: number;
+}
 
 /**
  * Retention, part 1 of 2 — the PER-ENTRY cap.
@@ -11859,6 +11944,12 @@ export declare interface TracingOptions {
      *  tracer layer instead of `Layer.empty` — so dashboards work without
      *  forcing console/otlp export. */
     readonly traceSink?: SpanProcessor;
+    /** What armed `traceSink`, and how to disarm it — in the caller's words,
+     *  because the runtime cannot know whether the sink is `voltro dev`'s
+     *  always-on ring or `voltro serve`'s opt-in one, and a refusal that names
+     *  the wrong switch sends the reader to change a variable that does nothing.
+     *  Printed only when the OpenTelemetry SDK turns out to be missing. */
+    readonly traceSinkOrigin?: string;
     /** Override the metrics-export env resolution. */
     readonly metricsMode?: MetricsMode;
     /** Export interval in ms for the periodic metric reader. Defaults to
@@ -12712,11 +12803,13 @@ export declare interface WorkflowFacadeOptions {
      *  facade builder, which owns the `_voltro_workflow_runs` store query;
      *  the runtime stays storage-agnostic (same shape as `signal`/`update`). */
     readonly listRuns?: (filter: WorkflowRunListFilter | undefined) => Promise<ReadonlyArray<WorkflowRunSummary>>;
+    /** Read a persisted retry observation without dispatching work. */
+    readonly readRetry?: (runId: string, requestId: string) => Promise<WorkflowRetryObservation>;
     /** Backs {@link WorkflowsAppContext.retry}. Supplied by the CLI's facade
      *  builder, which owns the runs store + workflow registry resolution.
      *  Inspect HTTP + the `voltro workflows retry` CLI delegate to the same
      *  implementation. */
-    readonly retry?: (runId: string, options: WorkflowRetryOptions | undefined) => Promise<WorkflowRetryResult>;
+    readonly retry?: (runId: string, options: WorkflowRetryOptions) => Promise<WorkflowRetryResult>;
     /** Backs {@link WorkflowsAppContext.redrive}. Supplied by the CLI's facade
      *  builder, which owns the runs/steps store query + the cluster journal
      *  adapter. Inspect HTTP + `voltro workflows redrive` delegate to the same
@@ -12902,17 +12995,16 @@ export declare interface WorkflowRedriveResult {
 
 /** Options for {@link WorkflowsAppContext.retry}. */
 export declare interface WorkflowRetryOptions {
+    /** Persist once per deliberate retry and reuse after a lost response. */
+    readonly requestId: string;
     /** Re-run the workflow against this payload instead of the original
      *  run's recorded payload. Lets a handler replay a failed run against
      *  a corrected input without reading the stored payload first. */
     readonly payloadOverride?: unknown;
 }
 
-/** Result of {@link WorkflowsAppContext.retry} — the engine-assigned
- *  execution id of the freshly started run. */
-export declare interface WorkflowRetryResult {
-    readonly executionId: string;
-}
+/** Durable retry observation; engine acceptance is not execution completion. */
+export declare type WorkflowRetryResult = WorkflowRetryObservation;
 
 /**
  * May `caller` read — or control — a row owned by `rowSubject`? The ONE
@@ -13085,7 +13177,9 @@ export declare interface WorkflowsAppContext {
      *  primary key, not the engine execution id). Resolves the original
      *  workflow by tag and re-executes it; pass `payloadOverride` to replay
      *  against a corrected input. */
-    retry(runId: string, options?: WorkflowRetryOptions): Promise<WorkflowRetryResult>;
+    retry(runId: string, options: WorkflowRetryOptions): Promise<WorkflowRetryResult>;
+    /** Observe a durable retry intent without submitting another attempt. */
+    readRetry(runId: string, requestId: string): Promise<WorkflowRetryObservation>;
     /** Re-drive a terminally-`failed` run from the step it died on, reusing
      *  its durable journal — the counterpart to {@link retry} (fresh execution,
      *  empty journal) and to {@link resume} (which only re-drives a *suspended*