okengine 0.3.5 → 0.4.3

package/src/kernel/fx.ts

@@ -32,9 +32,21 @@ import {
   touchDryRunStore,
 } from "./dry-run.ts";
 import { fail, type FailOptions, type FlowFailure } from "./errors.ts";
+import { currentAbortSignal } from "./abort-scope.ts";
+import {
+  fxAll,
+  fxRace,
+  fxRetry,
+  fxUsing,
+  type FxRetryOptions,
+  type FxThunk,
+} from "./concurrency.ts";
+import { maskRedactedDeep, Redacted } from "./redacted.ts";
 import type { JournalSession } from "./journal.ts";
 import type { RunTelemetry } from "./run-telemetry.ts";
 
+export type { FxRetryOptions, FxThunk } from "./concurrency.ts";
+
 /** Named ref: plain string or `{ name }` element handle. */
 export type NamedRef = string | { readonly name: string };
 
@@ -258,9 +270,13 @@ export interface Fx {
   /**
    * Read a vault secret (records `secret`).
    *
+   * Returns a {@link Redacted} — printing / logging / serializing it yields a
+   * placeholder, never the value. Call `.reveal()` at the one boundary that
+   * needs the real value (e.g. passing a credential to a driver).
+   *
    * @param secret - Secret name or handle
    */
-  vault(secret: NamedRef): string;
+  vault(secret: NamedRef): Redacted<string>;
   /** Cache surface. */
   readonly cache: FxCache;
   /**
@@ -337,6 +353,48 @@ export interface Fx {
    * @param fn - Step body
    */
   step<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+  /**
+   * Ambient abort signal for the current structured-concurrency branch.
+   * Outside `all` / `race`, a never-aborted signal.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Run thunks in parallel. On first rejection, abort sibling branches and
+   * rethrow. Pass thunks (not started Promises) so abort scopes exist first.
+   *
+   * @param thunks - Parallel work units
+   */
+  all<const T extends readonly unknown[]>(thunks: {
+    readonly [K in keyof T]: FxThunk<T[K]>;
+  }): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
+  /**
+   * Race thunks. The first settle wins; losers are aborted.
+   *
+   * @param thunks - Competing work units
+   */
+  race<T>(thunks: ReadonlyArray<FxThunk<T>>): Promise<T>;
+  /**
+   * Retry a thunk with exponential backoff and optional full jitter.
+   * Prefer wrapping inside {@link Fx.step} so durable replay skips completed work.
+   *
+   * @param fn - Operation
+   * @param opts - Retry policy
+   */
+  retry<T>(fn: FxThunk<T>, opts?: FxRetryOptions): Promise<T>;
+  /**
+   * Scope a resource to `use` — `release` runs exactly once when `use`
+   * settles or the ambient abort signal fires (e.g. a sibling `fx.race`
+   * winner). Same-attempt cleanup; not journaled.
+   *
+   * @param acquire - Open the resource
+   * @param release - Cleanup, always run
+   * @param use - Work with the resource
+   */
+  using<A, T>(
+    acquire: () => A | Promise<A>,
+    release: (resource: A) => void | Promise<void>,
+    use: (resource: A) => T | Promise<T>,
+  ): Promise<T>;
 }
 
 /**
@@ -818,9 +876,12 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     data?: Record<string, unknown>,
   ): { message: string; data?: Record<string, unknown> } {
     const vault = options.vaultRuntime;
-    if (!vault) return { message, data };
+    // Redacted<T> never yields the real value, but replace instances with a
+    // placeholder so payloads stay plain JSON (and never re-wrap on replay).
+    const maskedData = data ? maskRedactedDeep(data) : undefined;
+    if (!vault) return { message, data: maskedData };
     const safeMessage = vault.redactString(message);
-    const safeData = data ? (vault.redact(data) as Record<string, unknown>) : undefined;
+    const safeData = maskedData ? (vault.redact(maskedData) as Record<string, unknown>) : undefined;
     return { message: safeMessage, data: safeData };
   }
 
@@ -893,7 +954,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         duration: Math.max(0, now() - timestamp),
         reversibility: reversibilityOf("secret"),
       });
-      return value;
+      return new Redacted(value);
     },
     cache,
     send(template, opts) {
@@ -1035,6 +1096,21 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       }
       return await fn();
     },
+    get signal(): AbortSignal {
+      return currentAbortSignal();
+    },
+    all(thunks) {
+      return fxAll(thunks);
+    },
+    race(thunks) {
+      return fxRace(thunks);
+    },
+    retry(fn, opts) {
+      return fxRetry(fn, opts);
+    },
+    using(acquire, release, use) {
+      return fxUsing(acquire, release, use);
+    },
   };
 
   return { fx, ledger, capability };

package/src/kernel/index.ts

@@ -118,14 +118,36 @@ export {
   type FxJson,
   type FxLog,
   type FxOperator,
+  type FxRetryOptions,
   type FxSearchOptions,
   type FxSendOptions,
   type FxStoreHandle,
   type FxTenant,
+  type FxThunk,
   type JsonResult,
   type NamedRef,
 } from "./fx.ts";
 
+export {
+  abortError,
+  abortableSleep,
+  currentAbortSignal,
+  isAbortError,
+  linkAbort,
+  withAbortSignal,
+} from "./abort-scope.ts";
+
+export {
+  defaultRetryWhen,
+  fxAll,
+  fxRace,
+  fxRetry,
+  fxUsing,
+  resolveRetryDelayMs,
+} from "./concurrency.ts";
+
+export { isRedacted, maskRedactedDeep, REDACTED_PLACEHOLDER, Redacted } from "./redacted.ts";
+
 export {
   DryRunWriteIsolationError,
   dryRunWouldHaveFired,
@@ -200,6 +222,7 @@ export {
   type PluginOptions,
   type PluginRegistration,
   type TableContribution,
+  type PluginTableMeta,
   type PluginTableOptions,
 } from "./plugin.ts";
 

package/src/kernel/journal.ts

@@ -201,6 +201,12 @@ export interface JournalSession {
    * @param execute - Side-effecting body
    */
   effect<T>(effectKind: string, resource: string, execute: () => T | Promise<T>): Promise<T>;
+  /**
+   * Rewind the replay cursor to the start of the entry list.
+   * Used by flow-level retry so a re-entered `do` replays completed steps
+   * instead of treating the cursor as past them.
+   */
+  rewind(): void;
   /** Persist current run status / output. */
   commit(
     status: JournalRunStatus,
@@ -325,6 +331,9 @@ export function createJournal(options: CreateJournalOptions): Journal {
         await persist();
         return value;
       },
+      rewind() {
+        cursor = 0;
+      },
       async commit(status, patch) {
         run.status = status;
         if (patch?.wakeAt !== undefined) run.wakeAt = patch.wakeAt;

package/src/kernel/plugin/capabilities.test.ts

@@ -81,4 +81,22 @@ describe("plugin capability capture", () => {
       },
     });
   });
+
+  test("table description lands on capabilities.tables", () => {
+    const audit = plugin("audit", { version: "1.0.0" }).table("audit_events", undefined, {
+      description: "Immutable audit log",
+      plane: "operator",
+    });
+    const { api, snapshot } = createRecordingApi({
+      name: "audit",
+      version: "1.0.0",
+    });
+    audit.register(api);
+    expect(snapshot().capabilities.tables).toEqual({
+      audit_events: {
+        description: "Immutable audit log",
+        plane: "operator",
+      },
+    });
+  });
 });

package/src/kernel/plugin.ts

@@ -111,9 +111,7 @@ export interface TableContribution {
    * Non-column metadata (e.g. data plane). Prefer this over stuffing `plane`
    * into the column map.
    */
-  readonly options?: {
-    readonly plane?: "operator" | "user" | "shared" | string;
-  };
+  readonly options?: PluginTableOptions;
   /**
    * Opaque schema descriptor (legacy). Prefer {@link columns} + {@link options}.
    * Still set for plane-only contributions so older readers keep working.
@@ -124,6 +122,14 @@ export interface TableContribution {
 /** Options for {@link PluginApi.table} / {@link PluginDef.table}. */
 export interface PluginTableOptions {
   readonly plane?: "operator" | "user" | "shared" | string;
+  /** Optional human description for Console / docs (falls back to the table name). */
+  readonly description?: string;
+}
+
+/** Per-table metadata captured on {@link PluginCapabilities} / Manifest Plugin. */
+export interface PluginTableMeta {
+  readonly plane?: string;
+  readonly description?: string;
 }
 
 /** Driver contribution. */
@@ -253,6 +259,8 @@ export interface PluginCapabilities {
   readonly intercepts: readonly string[];
   /** Declared dependencies from `.needs()`. */
   readonly needs: readonly string[];
+  /** Optional metadata for contributed tables (description / plane). */
+  readonly tables?: Readonly<Record<string, PluginTableMeta>>;
 }
 
 /** Snapshot of everything a registration requested. */

package/src/kernel/redacted.ts

@@ -0,0 +1,74 @@
+/**
+ * `Redacted<T>` — a plain value wrapper that keeps a secret value out of
+ * logs, traces, and accidental serialization.
+ *
+ * Not an effect type: effect tracking only records which secret *names* a
+ * flow touches. This is value hygiene inside a flow body.
+ */
+
+/** Placeholder used for any representation of a {@link Redacted}. */
+export const REDACTED_PLACEHOLDER = "[redacted]";
+
+/**
+ * Wrap a value so printing / logging / JSON serialization never yields the
+ * real value. The only way to read the wrapped value is {@link reveal}.
+ */
+export class Redacted<T> {
+  readonly #value: T;
+
+  constructor(value: T) {
+    this.#value = value;
+  }
+
+  /** The one explicit way to get the real value. */
+  reveal(): T {
+    return this.#value;
+  }
+
+  toString(): string {
+    return REDACTED_PLACEHOLDER;
+  }
+
+  toJSON(): string {
+    return REDACTED_PLACEHOLDER;
+  }
+
+  [Symbol.toPrimitive](): string {
+    return REDACTED_PLACEHOLDER;
+  }
+
+  /** `util.inspect` / `console.log` — never the real value. */
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return REDACTED_PLACEHOLDER;
+  }
+}
+
+/** Type guard for {@link Redacted}. */
+export function isRedacted(value: unknown): value is Redacted<unknown> {
+  return value instanceof Redacted;
+}
+
+/**
+ * Deep-walk a log/trace payload: replace every {@link Redacted} with the
+ * placeholder (never the wrapped value); leave everything else untouched.
+ *
+ * @param value - Arbitrary structured data
+ */
+export function maskRedactedDeep<T>(value: T): T {
+  return maskRedactedValue(value) as T;
+}
+
+function maskRedactedValue(value: unknown): unknown {
+  if (isRedacted(value)) return REDACTED_PLACEHOLDER;
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) return value.map(maskRedactedValue);
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = maskRedactedValue(v);
+    }
+    return out;
+  }
+  return value;
+}

package/src/kernel/registry.ts

@@ -166,6 +166,7 @@ export function createRecordingApi(identity: { readonly name: string; readonly v
   return {
     api,
     snapshot(): PluginRegistration {
+      const tableMeta = tablesMetaFromContributions(tables);
       return {
         capabilities: {
           name: identity.name,
@@ -173,6 +174,7 @@ export function createRecordingApi(identity: { readonly name: string; readonly v
           declares: declares.slice(),
           intercepts: intercepts.slice(),
           needs: needs.slice(),
+          ...(tableMeta ? { tables: tableMeta } : {}),
         },
         hooks: { ...hooks },
         edges: edges.slice(),
@@ -440,9 +442,12 @@ function normalizeTableContribution(
     };
   }
 
-  if (columnsOrOptions && isPlaneOnlyOptions(columnsOrOptions)) {
+  if (columnsOrOptions && isLegacyTableOptions(columnsOrOptions)) {
     const planeOptions: PluginTableOptions = {
-      plane: columnsOrOptions.plane as string,
+      ...(typeof columnsOrOptions.plane === "string" ? { plane: columnsOrOptions.plane } : {}),
+      ...(typeof columnsOrOptions.description === "string"
+        ? { description: columnsOrOptions.description }
+        : {}),
     };
     return {
       name,
@@ -462,9 +467,27 @@ function normalizeTableContribution(
   return { name };
 }
 
-function isPlaneOnlyOptions(
-  value: Readonly<Record<string, unknown>>,
-): value is { readonly plane: string } {
+function isLegacyTableOptions(value: Readonly<Record<string, unknown>>): boolean {
   const keys = Object.keys(value);
-  return keys.length === 1 && keys[0] === "plane" && typeof value.plane === "string";
+  if (keys.length === 0) return false;
+  return keys.every((k) => k === "plane" || k === "description");
+}
+
+function tablesMetaFromContributions(
+  contributions: readonly TableContribution[],
+): Record<string, { readonly plane?: string; readonly description?: string }> | undefined {
+  if (contributions.length === 0) return undefined;
+  const out: Record<string, { readonly plane?: string; readonly description?: string }> = {};
+  let any = false;
+  for (const t of contributions) {
+    const plane = t.options?.plane;
+    const description = t.options?.description;
+    if (plane === undefined && description === undefined) continue;
+    any = true;
+    out[t.name] = {
+      ...(plane !== undefined ? { plane } : {}),
+      ...(description !== undefined ? { description } : {}),
+    };
+  }
+  return any ? out : undefined;
 }

package/src/kernel/router.ts

@@ -1,6 +1,6 @@
 /**
- * HTTP router — compiled RegExp matching with a Trie fallback
- * (Hono's SmartRouter idea), plus a linear preset for cold-start edge builds.
+ * HTTP router — compiled RegExp matching with a Trie fallback, plus a linear
+ * preset for cold-start edge builds.
  *
  * Chosen at build/startup: try RegExp first; on unsupported patterns fall
  * back to Trie. The `edge` preset uses LinearRouter for fast registration.
@@ -141,7 +141,7 @@ function matchCompiled<T>(dyn: CompiledDynamic<T>, path: string): RouteMatch<T>
 
 /**
  * Compiled RegExp router — O(1) static map, plus per-bucket compiled
- * regular expressions for parametric routes (Hono RegExpRouter idea).
+ * regular expressions for parametric routes.
  */
 export class RegExpRouter<T> implements Router<T> {
   readonly name = "RegExpRouter";

package/src/manifest/types.ts

@@ -165,6 +165,8 @@ export interface Flow {
 /** One Signal declaration. */
 export interface Signal {
   delivery: SignalDelivery;
+  /** Optional human description (falls back to the signal map key). */
+  description?: string;
   retries?: number;
   deadLetter?: boolean;
   schema?: JsonSchema;
@@ -201,6 +203,8 @@ export interface DeclaredColumn extends ColumnClassification {
   default?: string | number | boolean | null;
   /** Database column name (snake_case by default). */
   sqlName?: string;
+  /** Optional human description (falls back to the column map key). */
+  description?: string;
   /** Foreign key when `.references()` was declared. */
   references?: DeclaredColumnReference;
 }
@@ -217,6 +221,8 @@ export interface Table {
 /** One Store declaration. */
 export interface Store {
   facet: StoreFacet;
+  /** Optional human description (falls back to the store map key). */
+  description?: string;
   tables?: Record<string, Table>;
   namespaces?: string[];
   buckets?: string[];
@@ -230,6 +236,8 @@ export interface Clock {
   every?: string;
   timezone?: string;
   overridable?: boolean;
+  /** Optional human description (falls back to the clock map key). */
+  description?: string;
 }
 
 /** Named gate — policy or rate strategy. */
@@ -242,6 +250,8 @@ export interface Gate {
   keyBy?: string;
   scopes?: string[];
   roles?: string[];
+  /** Optional human description (falls back to the gate map key). */
+  description?: string;
 }
 
 /** Vault secret / config contract (never a secret value). */
@@ -258,6 +268,8 @@ export interface SecretContract {
 
 /** Channel template. */
 export interface Channel {
+  /** Optional human description (falls back to the channel map key). */
+  description?: string;
   medium?: ChannelMedium;
   locales?: string[];
   schema?: JsonSchema;
@@ -302,12 +314,21 @@ export interface Ai {
   agents?: Record<string, AiAgent>;
 }
 
+/** Per-table metadata on a Manifest {@link Plugin}. */
+export interface PluginTable {
+  plane?: string;
+  /** Optional human description (falls back to the table name). */
+  description?: string;
+}
+
 /** Plugin capability declaration. */
 export interface Plugin {
   origin?: PluginOrigin;
   version?: string;
   declares?: string[];
   intercepts?: string[];
+  /** Optional metadata for `table:*` contributions. */
+  tables?: Record<string, PluginTable>;
 }
 
 /** Tenancy configuration (resolver is code; isolation is data). */

package/src/release/measure.ts

@@ -36,6 +36,10 @@ const EXPORT_BUILD_EXTERNALS = [
   "ajv-formats",
   "oxc-parser",
   "zod",
+  "@libsql/client",
+  "@libsql/*",
+  "@electric-sql/pglite",
+  "@electric-sql/*",
 ] as const;
 
 /** How a sample is gated. */

package/src/test/provisions.integration.test.ts

@@ -56,7 +56,7 @@ describe("Provisions integration", () => {
       effects: { secrets: ["STRIPE_KEY"], emits: ["order-news"] },
       do: async ({ orderId }, fx) => {
         const key = fx.vault(stripeKey);
-        expect(key.startsWith("sk_")).toBe(true);
+        expect(key.reveal().startsWith("sk_")).toBe(true);
 
         await fx.step("create-intent", async () => ({ id: `pi_${orderId}` }));
         await fx.clock.sleep("verify-window", "2m");

package/site/content/docs/get-started/comparison.mdx

@@ -1,65 +0,0 @@
----
-title: Comparison
-description: How OKE compares to Hono, Elysia, Encore.ts, and iii — and when to pick it.
-source: docs/spec/unified-theory.md
-icon: Scale
----
-
-> **OKE is the batteries-included TypeScript backend for the Bun era:** contract-first APIs with end-to-end type safety, declarative infrastructure primitives, an OpenTelemetry-native Console, secure-by-default auth and ABAC — pure TypeScript, Web-Standards portable, MIT-licensed, self-hostable with zero cloud lock-in.
-
-_"Encore's batteries and dashboard, Elysia's speed and DX, Hono's portability — without the Rust lock-in, the cloud gravity, or the source-available license."_
-
-## When to pick OKE
-
-Choose OKE if you want:
-
-- **One mental model** for HTTP, jobs, consumers, and durable work (`on(Trigger) → Effects`)
-- **Batteries included** — store, signals, clock, gates, vault, channels, and AI as first-class elements
-- **A local Console** derived from your code (not a separate SaaS product you must adopt)
-- **MIT + self-host** with drivers named after protocols (`postgres`, `redis`, `s3`), not vendors
-- Effects that power cache invalidation, live queries, and least privilege **without hand annotations**
-
-Prefer a thinner router (Hono / Elysia alone) if you only need HTTP and will assemble queues, cron, and auth yourself.
-
-## Matrix
-
-|                                                 | Hono            | Elysia      | Encore.ts           | iii                   | **OKE**                           |
-| ----------------------------------------------- | --------------- | ----------- | ------------------- | --------------------- | --------------------------------- |
-| Primary runtime                                 | Multi (Web Std) | Bun-first   | Node + Rust core    | Rust engine, polyglot | **Bun-first, Web-Std portable**   |
-| License                                         | MIT             | MIT         | MPL-2.0             | ELv2 engine           | **MIT**                           |
-| Typed client                                    | hc RPC          | Eden Treaty | generated           | SDK                   | **contract-first + live queries** |
-| DB · queue · cron · storage                     | ❌              | ❌          | ✅                  | ✅                    | **✅ (7 elements)**               |
-| Durable workflows                               | ❌              | ❌          | ❌                  | partial               | **✅ (a flag)**                   |
-| Local Console                                   | ❌              | ❌          | ✅                  | ✅                    | **✅ (dev + prod)**               |
-| Auto cache invalidation                         | ❌              | ❌          | ❌                  | ❌                    | **✅ (from effects)**             |
-| Least-privilege by compiler                     | ❌              | ❌          | ❌                  | ❌                    | **✅**                            |
-| Human channels (email/SMS/WA)                   | ❌              | ❌          | ❌                  | ❌                    | **✅ (7th element)**              |
-| AI in the application (models, prompts, agents) | ❌              | ❌          | ❌                  | ❌                    | **✅ (8th element)**              |
-| Self-host, no lock-in                           | ✅              | ✅          | ✅ (Cloud optional) | ⚠️                    | **✅ first-class**                |
-
-## vs Collections of libraries
-
-Frameworks that ship a router plus a queue library plus a cron library plus websockets share one flaw: the concepts do not derive from one another. Documentation sprawls; each new fashion adds a concept that never gets removed.
-
-OKE starts from one law so docs, traces, hooks, and agent surfaces stay **one shape**.
-
-## vs Cloud-gravity platforms
-
-OKE is MIT, self-hostable, and names drivers after **protocols** — not vendors. Vendor choice lives in images keyed by role. There is no separate “deploy to our cloud” product you must adopt to get the Console.
-
-## vs Rolling your own effect system
-
-Effects are inferred from what a Flow touches through `fx`. Cache invalidation, live queries, least privilege, deterministic tests, and Manifest Diff fall out of that one decision — without hand-written annotations for each capability.
-
-<Cards>
-  <Card
-    title="Installation"
-    description="Install and scaffold in minutes."
-    href="/docs/get-started/installation"
-  />
-  <Card
-    title="Introduction"
-    description="The one law, eight elements, ten exports."
-    href="/docs/get-started/introduction"
-  />
-</Cards>