@voltro/runtime 0.25.0 → 0.27.0

package/dist/index.d.ts

@@ -43,6 +43,7 @@ import { Metric } from 'effect';
 import { MetricBoundaries } from 'effect';
 import { MetricReader } from '@opentelemetry/sdk-metrics';
 import { PluginHttpRoute } from '@voltro/protocol';
+import { PluginRefOrphanPolicy } from '@voltro/database';
 import { Predicate } from '@voltro/database';
 import { Query } from '@voltro/database';
 import { QueryDescriptor } from '@voltro/database';
@@ -871,10 +872,23 @@ export declare interface AppContext {
      *  `*.workflow.tsx` files. Starts return a run handle immediately;
      *  `wait`/`poll`/`signal`/`cancel` are explicit operations. */
     readonly workflows?: WorkflowsAppContext;
-    /** Domain event service — present when the app has workflow event
-     *  triggers. `emit(name, payload)` records the event and fans out to
-     *  matching workflow triggers. */
-    readonly events?: EventsAppContext;
+    /**
+     * `ctx.events.publish(descriptor, key, payload)` — present when the app
+     * declares `*.event.ts` files.
+     *
+     * This was typed as the OLD string-emitter facade (`emit(name, data)`) long
+     * after that facade was deleted, so the documented call was a `tsc` error
+     * while the runtime carried only `publish` — a consumer measured
+     * `eventKeys: ["publish"], emitType: undefined` with a cron probe because the
+     * type and the docs disagreed and they could not tell which was lying.
+     *
+     * What let it drift is worth naming: the builder installed the publisher with
+     * `as never`, so the compiler had the answer the whole time and was told not
+     * to give it. `appContext.ts` even carried a comment stating `emit` is gone —
+     * beside the cast that hid it. A context field is the one place this repo
+     * treats such a cast as a defect in its own right.
+     */
+    readonly events?: EventPublisher;
     /**
      * Transactional outbox (`ctx.outbox`). Absent when the app declares no
      * `*.outbox.ts` handler — an enqueue with nobody to deliver it would be a
@@ -936,6 +950,18 @@ export declare const applyInverse: (store: UndoApplyStore, op: InverseOp) => Pro
  *  `synthesizeInverse`), as the caller's transaction wraps them. */
 export declare const applyInverses: (store: UndoApplyStore, ops: ReadonlyArray<InverseOp>) => Promise<void>;
 
+/**
+ * Apply every rule matching `change`.
+ *
+ * Returns what it did, so a caller can log it. Never throws for a rule that
+ * finds nothing — an orphan rule firing on a row nobody references is the
+ * normal case, not an error.
+ */
+export declare const applyPluginRefRules: (store: PluginRefStore, rules: ReadonlyArray<PluginRefRule>, change: PluginRefChange) => Promise<ReadonlyArray<{
+    readonly rule: PluginRefRule;
+    readonly affected: number;
+}>>;
+
 /** AND-merge the row filter for `table` onto an existing predicate. */
 export declare const applyRowFilter: (scope: RowFilterScope, table: string, predicate: Predicate | undefined) => Predicate | undefined;
 
@@ -1125,15 +1151,6 @@ export declare interface BeginOAuthResult {
     readonly state: string;
 }
 
-/**
- * Override the subject for an active connection. Called from the
- * `auth.signin` (or any "I just authenticated this caller") handler
- * after the credential check passes. Future calls on the same
- * connection see the new subject via the AuthMiddleware fast-path.
- *
- * Emits to all `onBind` listeners synchronously so subscription
- * registries can re-scope active subscriptions.
- */
 export declare const bindConnectionSubject: (clientId: number, subject: Subject) => void;
 
 /**
@@ -1178,7 +1195,25 @@ export declare const bindMutation: <Input, Output, E = never>(execute: (input: I
  * finalizers run → the provider request aborts), reusing the same
  * per-connection interrupt registry subscriptions use.
  */
-export declare const bindStream: <Element, Err = unknown>(buildStream: (context: RuntimeContext) => Stream.Stream<Element, Err, never> | Effect.Effect<Stream.Stream<Element, Err, never>, unknown, never>, spanName?: string) => Stream.Stream<Element, Err, SubjectService | ConnectionInfo>;
+export declare const bindStream: <Element, Err = unknown>(buildStream: (context: RuntimeContext) => Stream.Stream<Element, Err, never> | Effect.Effect<Stream.Stream<Element, Err, never>, unknown, never>, spanName?: string, 
+/**
+ * The stream's declared `guards:`, when it has any.
+ *
+ * Checked once at subscribe AND before every element, exactly as a query's
+ * are. A stream was the one realtime primitive that could not express
+ * authorization at all, so whatever protection existed was hand-written in an
+ * executor where nothing could verify it was there.
+ *
+ * A denial ENDS the stream rather than dropping the element: a skipped
+ * element is indistinguishable from "nothing to send", and the client must
+ * learn it lost access instead of inferring it from silence.
+ */
+guards?: ReadonlyArray<unknown> | undefined, 
+/** The call's decoded input — the guard INPUT, so a resource-scoped guard
+ *  (`{ scope: 'x:read', from: 'id' }`) can see which resource was asked for.
+ *  Passed explicitly rather than read off RuntimeContext, which does not
+ *  carry it. */
+guardInput?: unknown) => Stream.Stream<Element, Err, SubjectService | ConnectionInfo>;
 
 /**
  * Build a `Stream<SubscriptionEvent<T>>` that an @effect/rpc streaming
@@ -1473,6 +1508,34 @@ export { clearRetentions }
 /** Clear the process-wide handle (test teardown). */
 export declare const clearSystemStoreHandle: () => void;
 
+/**
+ * Collect the declared rules from the discovered tables.
+ *
+ * `tables` is the boot's table set. Each column carrying a `pluginRef` spec
+ * contributes one rule, with the target resolved through the plugin's exported
+ * handle — so a rename carries the rule.
+ *
+ * Throws when a `pluginRef` names a table nothing registered: a declared rule
+ * against an absent plugin would sit there looking enforced and never fire,
+ * which is the exact failure this framework has shipped too often. The message
+ * names both sides so the fix is obvious (install the plugin, or drop the
+ * column).
+ */
+export declare const collectPluginRefRules: (tables: ReadonlyArray<{
+    readonly name: string;
+    /** The DECLARED references, carried on the built table. Reading the column
+     *  bag instead does not work: `table()` materialises builders into plain
+     *  field descriptors, so the spec is gone by the time anyone can ask. That
+     *  is how this collector silently produced ZERO rules while its own wiring
+     *  test — which only checked that it was CALLED — stayed green. */
+    readonly appliedPluginRefs?: ReadonlyArray<{
+        readonly column: string;
+        readonly target: () => unknown;
+        readonly orphanPolicy: PluginRefOrphanPolicy;
+        readonly onSoftDelete: boolean;
+    }>;
+}>, registered: ReadonlySet<string>) => ReadonlyArray<PluginRefRule>;
+
 /** Parse + return the compiled `Cron` for a definition. Throws the
  *  same way `defineSchedule` validated — callers that already hold a
  *  branded definition can trust this won't throw. */
@@ -2834,6 +2897,9 @@ export declare const formatServerOnlyLeaks: (leaks: ReadonlyArray<ServerOnlyLeak
 /** Serialise a span's context as a `traceparent` header value. */
 export declare const formatTraceparent: (ctx: TraceContext) => string;
 
+/** The boot warning for unresolved sources, or `undefined` when there are none. */
+export declare const formatUnresolvedSources: (found: ReadonlyArray<UnresolvedSource>) => string | undefined;
+
 /** One captured row change within a mutation invocation. */
 export declare interface ForwardChange {
     readonly table: string;
@@ -2874,6 +2940,8 @@ export declare const getConnectionResolver: () => ConnectionResolver | undefined
 /** Look up the override for a connection. Returns `undefined` if no override is set. */
 export declare const getConnectionSubject: (clientId: number) => Subject | undefined;
 
+export declare const getCredentialExpiry: (clientId: number) => number | undefined;
+
 /** The registered field cipher, if any. The store middleware reads this. */
 export declare const getFieldCipher: () => FieldCipher | undefined;
 
@@ -3267,6 +3335,20 @@ export declare const isSafeToApply: (current: Record<string, unknown> | null | u
 
 export declare const isScheduleDefinition: (v: unknown) => v is BrandedScheduleDefinition;
 
+/**
+ * Did this change soft-delete the row?
+ *
+ * A soft delete is NOT a `delete` event — it is an `update` that sets
+ * `deletedAt`. That distinction is why the first version of `onSoftDelete` was
+ * inert in every case: the matcher only looked at `op === 'delete'`, which a
+ * soft delete never is, so the option existed and could not fire. Exactly the
+ * defect this whole round was about, one level down.
+ *
+ * The transition matters, not the value: a row that was already deleted and is
+ * updated again must not re-fire the rule.
+ */
+export declare const isSoftDelete: (change: PluginRefChange) => boolean;
+
 /** A freshly issued key — `token` is shown ONCE and never stored in clear. */
 export declare interface IssuedApiKey {
     readonly id: string;
@@ -4474,6 +4556,34 @@ export declare const payloadPropertyNames: (schema: Schema.Schema.Any) => {
     readonly optional: ReadonlyArray<string>;
 };
 
+/** A change as the post-commit channel reports it. */
+export declare interface PluginRefChange {
+    readonly table: string;
+    readonly op: 'insert' | 'update' | 'delete';
+    readonly rowId: string;
+    readonly tenantId?: string | null;
+    /** The row before, when there was one — used to spot a soft delete. */
+    readonly old?: Record<string, unknown> | null;
+    /** The row after, when there is one. */
+    readonly new?: Record<string, unknown> | null;
+}
+
+/** One resolved rule: "when <targetTable> loses a row, do <policy> to <table.column>". */
+export declare interface PluginRefRule {
+    readonly table: string;
+    readonly column: string;
+    readonly targetTable: string;
+    readonly policy: PluginRefOrphanPolicy;
+    readonly onSoftDelete: boolean;
+}
+
+/** The store surface the enforcement needs. */
+export declare interface PluginRefStore {
+    query: (descriptor: unknown) => Promise<ReadonlyArray<Record<string, unknown>>>;
+    update: (table: string, id: string, patch: Record<string, unknown>) => Promise<unknown>;
+    delete: (table: string, id: string) => Promise<unknown>;
+}
+
 /** The 3-arg signature a plugin sees on its bind-ctx. */
 export declare type PluginScheduleCoordinated = (name: string, intervalMs: number, effect: () => void | Promise<void>) => CoordinatedScheduleHandle;
 
@@ -4762,6 +4872,8 @@ export declare interface RebacSubject {
     readonly scopes?: ReadonlyArray<string>;
 }
 
+export declare const recordCredentialExpiry: (clientId: number, exp: number | undefined) => void;
+
 /** What the framework emit-seams (servePipeline / rpcServer / plugin wrappers)
  *  hand to the registry. A flat, transport-agnostic sample shape the
  *  recording callbacks can build without touching Effect. */
@@ -5653,6 +5765,14 @@ export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
     readonly maxRpcBodyBytes?: number;
 }
 
+/**
+ * Rules that apply to one change, or an empty list.
+ *
+ * Exported separately from the execution so the matching is testable without a
+ * store: which rules fire is the part with the edge cases.
+ */
+export declare const rulesFor: (rules: ReadonlyArray<PluginRefRule>, change: PluginRefChange) => ReadonlyArray<PluginRefRule>;
+
 /**
  * Run `fn` with `SubjectService` bound to a `system` subject and a
  * system-scoped fluent `ctx.store`. Returns whatever `fn` returns.
@@ -7259,6 +7379,27 @@ export declare class UndoStack<E> {
     };
 }
 
+/** One `source:` entry that resolves to no declared table. */
+export declare interface UnresolvedSource {
+    /** The procedure that declares it. */
+    readonly procedure: string;
+    /** The name as written. */
+    readonly source: string;
+    /** A declared table whose name is close — the rename case, usually. */
+    readonly didYouMean: string | undefined;
+}
+
+/**
+ * Every `source:` across `procedures` that names no declared table.
+ *
+ * `declared` is the table-name set the boot already built. Procedures with no
+ * `source` are skipped — reactivity is opt-in and its absence is not a defect.
+ */
+export declare const unresolvedSources: (procedures: ReadonlyArray<{
+    readonly name: string;
+    readonly source: string | ReadonlyArray<string> | undefined;
+}>, declared: ReadonlySet<string>) => ReadonlyArray<UnresolvedSource>;
+
 export declare class UpdateBuilder {
     private readonly backend;
     private readonly scope;
@@ -7609,6 +7750,17 @@ export declare interface WorkflowFacadeOptions {
      *  Inspect HTTP + the `voltro workflows retry` CLI delegate to the same
      *  implementation. */
     readonly retry?: (runId: string, options: WorkflowRetryOptions | undefined) => 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
+     *  implementation. */
+    readonly redrive?: (runId: string) => Promise<WorkflowRedriveResult>;
+    /** Fired (fire-and-forget) right after a workflow is ENQUEUED — a start,
+     *  child, or run. The CLI wires this to a cross-replica "wake" broadcast so
+     *  the replica that OWNS the new run's shard polls immediately instead of
+     *  waiting for its next storage tick. No-op when unset (single replica / no
+     *  broker → the poll interval covers it). */
+    readonly onEnqueue?: () => void;
 }
 
 export declare interface WorkflowLayerExecutionContext {
@@ -7649,6 +7801,16 @@ export declare class WorkflowPayloadError extends Error {
     missingFields: ReadonlyArray<string>, detail: string);
 }
 
+/** Result of {@link WorkflowsAppContext.redrive} — whether the failed run's
+ *  durable journal was re-driven, how many failed step attempts were reset so
+ *  they re-execute, and a `reason` when it declined (no journal / still
+ *  running / already succeeded). */
+export declare interface WorkflowRedriveResult {
+    readonly redriven: boolean;
+    readonly activitiesReset: number;
+    readonly reason: string | null;
+}
+
 /** Options for {@link WorkflowsAppContext.retry}. */
 export declare interface WorkflowRetryOptions {
     /** Re-run the workflow against this payload instead of the original
@@ -7670,6 +7832,11 @@ export declare interface WorkflowRunListFilter {
     readonly workflowName?: string;
     readonly tag?: string;
     readonly status?: WorkflowRunRecordStatus;
+    /** The DEAD-LETTER view: failed runs an operator has NOT yet discarded
+     *  (`status = 'failed' AND discardedAt IS NULL`). Since the framework applies no
+     *  retry, a `failed` run is terminal — this is the queue of unhandled failures.
+     *  Combines with the other filters (e.g. by `workflowName`). */
+    readonly deadLettered?: boolean;
     readonly limit?: number;
     readonly offset?: number;
 }
@@ -7727,6 +7894,9 @@ export declare interface WorkflowRunSummary<Payload = unknown, Output = unknown>
     readonly durationMs: number | null;
     readonly traceId: string | null;
     readonly parentExecutionId: string | null;
+    /** When set, an operator has acknowledged this (failed) run — it is off the
+     *  dead-letter view. Null = unacknowledged. See `WorkflowRunListFilter.deadLettered`. */
+    readonly discardedAt: Date | null;
 }
 
 export declare interface WorkflowsAppContext {
@@ -7752,6 +7922,14 @@ export declare interface WorkflowsAppContext {
      *  workflow by tag and re-executes it; pass `payloadOverride` to replay
      *  against a corrected input. */
     retry(runId: string, options?: WorkflowRetryOptions): Promise<WorkflowRetryResult>;
+    /** 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*
+     *  run). Addressed by run id (`wfrun_…`). Completed steps replay from the
+     *  journal; only the failed steps re-execute. Fix the downstream cause
+     *  first, then redrive. Refuses a run that is not a not-yet-discarded
+     *  failure. */
+    redrive(runId: string): Promise<WorkflowRedriveResult>;
 }
 
 export declare interface WorkflowSignalTarget {