okengine 0.22.0 → 0.23.1

package/src/kernel/decision-label-store.ts

@@ -0,0 +1,441 @@
+/**
+ * Decision labels and the drift flag on the journal driver.
+ *
+ * A sibling of `oke_idempotency`. Rows are not journal runs. Tables are
+ * created only when this store is opened, which boot does when the app
+ * declares decisions.
+ *
+ * @module
+ */
+
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { DecisionCandidate, DecisionLabel } from "../elements/ai/decisions/certificate.ts";
+
+/** SQL surface the postgres journal client already exposes. */
+export interface DecisionLabelSql {
+  query(sql: string, params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
+  exec(sql: string, params?: readonly unknown[]): Promise<{ changes: number }>;
+}
+
+/** Drift for one decision. A later certificate (`certifiedAt` newer) ignores it. */
+export interface DecisionDriftFlag {
+  readonly suspended: boolean;
+  /** Epoch ms of the certificate that was current when the flag was written. */
+  readonly certifiedAt: number;
+}
+
+/** @deprecated Use {@link DecisionDriftFlag}. Kept for stored rows. */
+export interface DecisionDriftRecord extends DecisionDriftFlag {}
+
+/** Thrown when the postgres label store cannot open or query. */
+export class DecisionLabelStoreError extends Error {
+  /**
+   * @param message - What failed
+   * @param options - Underlying driver error
+   */
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "DecisionLabelStoreError";
+  }
+}
+
+/** Persistence for review labels and the app drift flag. */
+export interface DecisionLabelStore {
+  insert(label: DecisionLabel, at: number): Promise<void>;
+  /**
+   * Labels for one decision. Omit `tenant` to read every tenant.
+   *
+   * @param decision - Decision name
+   * @param tenant - Tenant filter
+   */
+  list(decision?: string, tenant?: string | null): Promise<DecisionLabel[]>;
+  /** Drift flags keyed by decision name. */
+  drift(): Promise<Readonly<Record<string, DecisionDriftFlag>>>;
+  /**
+   * Persist one decision's suspension flag.
+   *
+   * @param decision - Decision name
+   * @param record - Flag and the certificate time it belongs to
+   */
+  setDrift(decision: string, record: DecisionDriftFlag): Promise<void>;
+  /**
+   * Store one candidate on this journal. Any instance can read it after a restart.
+   *
+   * @param decision - Decision name
+   * @param entry - Lock entry the clock fitted
+   */
+  putCandidate(decision: string, entry: DecisionCandidate): Promise<void>;
+  /**
+   * Candidate last written for this decision.
+   *
+   * @param decision - Decision name
+   */
+  getCandidate(decision: string): Promise<DecisionCandidate | undefined>;
+  /** Decision names that have a candidate. */
+  listCandidates(): Promise<readonly string[]>;
+}
+
+interface StoredLabel extends DecisionLabel {
+  readonly at: number;
+}
+
+/**
+ * In-memory label store.
+ */
+export function createMemoryDecisionLabelStore(): DecisionLabelStore {
+  const rows: StoredLabel[] = [];
+  const candidates = new Map<string, DecisionCandidate>();
+  const driftFlags = new Map<string, DecisionDriftFlag>();
+  return {
+    async insert(label, at) {
+      rows.push({ ...label, at });
+    },
+    async list(decision, tenant) {
+      return rows
+        .filter((row) => decision === undefined || row.decision === decision)
+        .filter((row) => tenant === undefined || (row.tenant ?? null) === tenant)
+        .map(toLabel);
+    },
+    async drift() {
+      return Object.fromEntries(driftFlags);
+    },
+    async setDrift(decision, next) {
+      if (next.suspended) driftFlags.set(decision, next);
+      else driftFlags.delete(decision);
+    },
+    async putCandidate(decision, entry) {
+      candidates.set(decision, entry);
+    },
+    async getCandidate(decision) {
+      return candidates.get(decision);
+    },
+    async listCandidates() {
+      return [...candidates.keys()];
+    },
+  };
+}
+
+/**
+ * File-backed label store beside the journal file.
+ *
+ * @param path - JSON file path
+ */
+export function createFileDecisionLabelStore(path: string): DecisionLabelStore {
+  let rows: StoredLabel[] | undefined;
+  let candidates: Record<string, DecisionCandidate> = {};
+  let driftFlags: Record<string, DecisionDriftFlag> = {};
+  const load = async (): Promise<void> => {
+    if (rows) return;
+    rows = [];
+    const file = Bun.file(path);
+    if (await file.exists()) {
+      const raw = (await file.json()) as {
+        rows?: StoredLabel[];
+        suspended?: boolean;
+        certifiedAt?: number;
+        drifts?: Record<string, DecisionDriftFlag>;
+        candidates?: Record<string, DecisionCandidate>;
+      };
+      rows = raw.rows ?? [];
+      candidates = raw.candidates ?? {};
+      driftFlags = raw.drifts ?? {};
+      const legacy =
+        driftFlags["*"] ??
+        (raw.suspended === true && Object.keys(driftFlags).length === 0
+          ? { suspended: true as const, certifiedAt: raw.certifiedAt ?? 0 }
+          : undefined);
+      if (legacy?.suspended) {
+        delete driftFlags["*"];
+        for (const name of declaredDriftDecisions) {
+          driftFlags[name] = { suspended: legacy.suspended, certifiedAt: legacy.certifiedAt };
+        }
+        await mkdir(dirname(path), { recursive: true });
+        await Bun.write(path, JSON.stringify({ rows, candidates, drifts: driftFlags }));
+      }
+    }
+  };
+  const flush = async (): Promise<void> => {
+    await mkdir(dirname(path), { recursive: true });
+    await Bun.write(
+      path,
+      JSON.stringify({
+        rows,
+        candidates,
+        drifts: driftFlags,
+      }),
+    );
+  };
+  return {
+    async insert(label, at) {
+      await load();
+      rows!.push({ ...label, at });
+      await flush();
+    },
+    async list(decision, tenant) {
+      await load();
+      return rows!
+        .filter((row) => decision === undefined || row.decision === decision)
+        .filter((row) => tenant === undefined || (row.tenant ?? null) === tenant)
+        .map(toLabel);
+    },
+    async drift() {
+      await load();
+      return driftFlags;
+    },
+    async setDrift(decision, next) {
+      await load();
+      if (next.suspended) driftFlags[decision] = next;
+      else delete driftFlags[decision];
+      await flush();
+    },
+    async putCandidate(decision, entry) {
+      await load();
+      candidates[decision] = entry;
+      await flush();
+    },
+    async getCandidate(decision) {
+      await load();
+      return candidates[decision];
+    },
+    async listCandidates() {
+      await load();
+      return Object.keys(candidates);
+    },
+  };
+}
+
+/** Decision names an old app-wide drift flag is copied onto. Boot sets this before open. */
+let declaredDriftDecisions: readonly string[] = [];
+
+/**
+ * Declare which decisions receive a legacy app-wide drift flag.
+ *
+ * @param names - Decision names from the manifest
+ */
+export function setDeclaredDriftDecisions(names: readonly string[]): void {
+  declaredDriftDecisions = names;
+}
+
+/**
+ * Postgres label store on the journal connection. Creates the tables.
+ * A failed init or query throws {@link DecisionLabelStoreError}.
+ *
+ * @param sql - Journal SQL client
+ */
+export async function createPostgresDecisionLabelStore(
+  sql: DecisionLabelSql,
+): Promise<DecisionLabelStore> {
+  try {
+    await sql.exec(`CREATE TABLE IF NOT EXISTS oke_decision_labels (
+      decision_id TEXT NOT NULL,
+      question TEXT NOT NULL,
+      value TEXT NOT NULL,
+      propensity DOUBLE PRECISION NOT NULL,
+      reviewer TEXT NOT NULL,
+      locale TEXT,
+      model TEXT,
+      tenant TEXT,
+      score DOUBLE PRECISION,
+      loss INTEGER,
+      raw TEXT,
+      at BIGINT NOT NULL,
+      input TEXT
+    )`);
+    await sql.exec(`ALTER TABLE oke_decision_labels ADD COLUMN IF NOT EXISTS input TEXT`);
+    await sql.exec(`ALTER TABLE oke_decision_labels ADD COLUMN IF NOT EXISTS review_id TEXT`);
+    await migrateDecisionDriftTable(sql, declaredDriftDecisions);
+    await sql.exec(`CREATE TABLE IF NOT EXISTS oke_decision_candidates (
+      decision_id TEXT PRIMARY KEY,
+      body TEXT NOT NULL
+    )`);
+  } catch (cause) {
+    throw new DecisionLabelStoreError("decision label store failed to open", { cause });
+  }
+  const query = async (
+    statement: string,
+    params?: readonly unknown[],
+  ): Promise<Record<string, unknown>[]> => {
+    try {
+      return await sql.query(statement, params);
+    } catch (cause) {
+      throw new DecisionLabelStoreError("decision label store query failed", { cause });
+    }
+  };
+  const exec = async (statement: string, params?: readonly unknown[]): Promise<void> => {
+    try {
+      await sql.exec(statement, params);
+    } catch (cause) {
+      throw new DecisionLabelStoreError("decision label store query failed", { cause });
+    }
+  };
+  return {
+    async insert(label, at) {
+      await exec(
+        `INSERT INTO oke_decision_labels
+          (decision_id, question, value, propensity, reviewer, locale, model, tenant, score, loss, raw, at, input, review_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          label.decision,
+          label.question,
+          JSON.stringify(label.value),
+          label.propensity,
+          label.reviewer,
+          label.locale ?? null,
+          label.model ?? null,
+          label.tenant ?? null,
+          label.score ?? null,
+          label.loss ?? null,
+          label.raw === undefined ? null : JSON.stringify(label.raw),
+          at,
+          label.input === undefined ? null : JSON.stringify(label.input),
+          label.reviewId ?? null,
+        ],
+      );
+    },
+    async list(decision, tenant) {
+      const clauses: string[] = [];
+      const args: (string | null)[] = [];
+      if (decision !== undefined) {
+        clauses.push("decision_id = ?");
+        args.push(decision);
+      }
+      if (tenant !== undefined) {
+        clauses.push("tenant IS NOT DISTINCT FROM ?");
+        args.push(tenant);
+      }
+      const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+      const found = await query(
+        `SELECT decision_id, question, value, propensity, reviewer, locale, model, tenant, score, loss, raw, at, input, review_id
+         FROM oke_decision_labels ${where}`,
+        args,
+      );
+      return found.map((row) => ({
+        decision: String(row.decision_id),
+        question: String(row.question),
+        value: JSON.parse(String(row.value)) as unknown,
+        propensity: Number(row.propensity),
+        reviewer: String(row.reviewer),
+        ...(row.locale != null ? { locale: String(row.locale) } : {}),
+        ...(row.model != null ? { model: String(row.model) } : {}),
+        ...(row.tenant != null ? { tenant: String(row.tenant) } : {}),
+        ...(row.score != null ? { score: Number(row.score) } : {}),
+        ...(row.loss != null ? { loss: Number(row.loss) } : {}),
+        ...(row.raw != null ? { raw: JSON.parse(String(row.raw)) as unknown } : {}),
+        ...(row.input != null ? { input: JSON.parse(String(row.input)) as unknown } : {}),
+        ...(row.review_id != null ? { reviewId: String(row.review_id) } : {}),
+        at: Number(row.at),
+      }));
+    },
+    async drift() {
+      const rows = await query(
+        `SELECT decision_id, suspended, certified_at FROM oke_decision_drift`,
+      );
+      const flags: Record<string, DecisionDriftFlag> = {};
+      for (const row of rows) {
+        const name = String(row.decision_id ?? "");
+        if (!name) continue;
+        flags[name] = {
+          suspended: Number(row.suspended) === 1,
+          certifiedAt: Number(row.certified_at ?? 0),
+        };
+      }
+      return flags;
+    },
+    async setDrift(decision, next) {
+      if (!next.suspended) {
+        await exec(`DELETE FROM oke_decision_drift WHERE decision_id = ?`, [decision]);
+        return;
+      }
+      await exec(
+        `INSERT INTO oke_decision_drift (decision_id, suspended, certified_at) VALUES (?, ?, ?)
+         ON CONFLICT (decision_id) DO UPDATE SET suspended = excluded.suspended, certified_at = excluded.certified_at`,
+        [decision, 1, next.certifiedAt],
+      );
+    },
+    async putCandidate(decision, entry) {
+      await exec(
+        `INSERT INTO oke_decision_candidates (decision_id, body) VALUES (?, ?)
+         ON CONFLICT (decision_id) DO UPDATE SET body = excluded.body`,
+        [decision, JSON.stringify(entry)],
+      );
+    },
+    async getCandidate(decision) {
+      const rows = await query(`SELECT body FROM oke_decision_candidates WHERE decision_id = ?`, [
+        decision,
+      ]);
+      const body = rows[0]?.body;
+      if (typeof body !== "string") return undefined;
+      const parsed = JSON.parse(body) as DecisionCandidate;
+      if (!parsed || typeof parsed.model !== "string" || !parsed.questions) return undefined;
+      return parsed;
+    },
+    async listCandidates() {
+      const rows = await query(`SELECT decision_id FROM oke_decision_candidates`);
+      return rows.map((row) => String(row.decision_id));
+    },
+  };
+}
+
+function toLabel(row: StoredLabel): DecisionLabel {
+  return {
+    decision: row.decision,
+    question: row.question,
+    value: row.value,
+    propensity: row.propensity,
+    reviewer: row.reviewer,
+    ...(row.locale !== undefined ? { locale: row.locale } : {}),
+    ...(row.model !== undefined ? { model: row.model } : {}),
+    ...(row.tenant !== undefined ? { tenant: row.tenant } : {}),
+    ...(row.score !== undefined ? { score: row.score } : {}),
+    ...(row.loss !== undefined ? { loss: row.loss } : {}),
+    ...(row.raw !== undefined ? { raw: row.raw } : {}),
+    ...(row.input !== undefined ? { input: row.input } : {}),
+    ...(row.reviewId !== undefined ? { reviewId: row.reviewId } : {}),
+    at: row.at,
+  };
+}
+
+/**
+ * Recreate `oke_decision_drift` when it still uses an app-wide `id` row.
+ * A suspended flag is copied onto every declared decision.
+ *
+ * @param sql - Journal SQL client
+ * @param names - Declared decision names
+ */
+async function migrateDecisionDriftTable(
+  sql: DecisionLabelSql,
+  names: readonly string[],
+): Promise<void> {
+  const create = `CREATE TABLE IF NOT EXISTS oke_decision_drift (
+      decision_id TEXT PRIMARY KEY,
+      suspended INTEGER NOT NULL,
+      certified_at BIGINT NOT NULL
+    )`;
+  let columns: string[] = [];
+  try {
+    const rows = await sql.query(
+      `SELECT column_name FROM information_schema.columns WHERE table_name = 'oke_decision_drift'`,
+    );
+    columns = rows.map((row) => String(row.column_name ?? "").toLowerCase());
+  } catch {
+    columns = [];
+  }
+  if (columns.includes("id") && !columns.includes("decision_id")) {
+    const old = await sql.query(`SELECT * FROM oke_decision_drift`);
+    const flag = old[0];
+    await sql.exec(`DROP TABLE oke_decision_drift`);
+    await sql.exec(create.replace("IF NOT EXISTS ", ""));
+    if (flag && Number(flag.suspended) === 1) {
+      const certifiedAt = Number(flag.certified_at ?? 0);
+      for (const name of names) {
+        await sql.exec(
+          `INSERT INTO oke_decision_drift (decision_id, suspended, certified_at) VALUES (?, ?, ?)`,
+          [name, 1, certifiedAt],
+        );
+      }
+    }
+    return;
+  }
+  await sql.exec(create);
+}

package/src/kernel/effects.test.ts

@@ -21,9 +21,10 @@ describe("effects — reversibility tiers", () => {
       secret: "capability",
       call: "portal",
       fetch: "irreversible",
+      decide: "irreversible",
     };
 
-    expect(EFFECT_KIND_TIERS).toHaveLength(9);
+    expect(EFFECT_KIND_TIERS).toHaveLength(10);
     for (const { kind, reversibility } of EFFECT_KIND_TIERS) {
       expect(reversibility).toBe(expected[kind]);
       expect(reversibilityOf(kind)).toBe(expected[kind]);

package/src/kernel/effects.ts

@@ -17,7 +17,8 @@ export type EffectKind =
   | "embed"
   | "secret"
   | "call"
-  | "fetch";
+  | "fetch"
+  | "decide";
 
 /**
  * Reversibility tier — console §9.1 ranking, applied to all effect kinds.
@@ -65,6 +66,11 @@ export interface EffectEntry {
    * Omitted for in-process work (PGlite, mock AI, local channel console).
    */
   readonly external?: EffectExternal;
+  /**
+   * Agent run this `fx.run` or nested agent call started.
+   * Absent on prompt asks and on calls that are not agents.
+   */
+  readonly agentRunId?: string;
 }
 
 /** Append-only ledger of effect entries for one flow invocation. */
@@ -92,6 +98,7 @@ const TIER_BY_KIND: Readonly<Record<EffectKind, ReversibilityTier>> = {
   secret: "capability",
   call: "portal",
   fetch: "irreversible",
+  decide: "irreversible",
 };
 
 /**
@@ -143,6 +150,7 @@ export async function recordEffect<T>(
   externalOf?:
     | EffectExternal
     | ((result: T | undefined, error: unknown) => EffectExternal | undefined),
+  stamp?: (result: T | undefined) => { readonly agentRunId?: string } | undefined,
 ): Promise<T> {
   const timestamp = now();
   const t0 = performance.now();
@@ -163,6 +171,7 @@ export async function recordEffect<T>(
       timestamp,
       resolveDurationMs(now() - timestamp, performance.now() - t0),
       external,
+      stamp?.(result),
     );
   }
 }
@@ -187,7 +196,9 @@ export function recordObservedEffect(
   timestamp: number,
   duration: number,
   external?: EffectExternal,
+  stamp?: { readonly agentRunId?: string },
 ): void {
+  const agentRunId = stamp?.agentRunId;
   ledger.record({
     kind,
     resource,
@@ -195,6 +206,7 @@ export function recordObservedEffect(
     duration,
     reversibility: reversibilityOf(kind),
     ...(external !== undefined ? { external } : {}),
+    ...(agentRunId !== undefined && agentRunId.length > 0 ? { agentRunId } : {}),
   });
 }
 

package/src/kernel/element-registries.ts

@@ -16,6 +16,7 @@
 
 import type {
   AiAgentDecl,
+  AiDecisionDecl,
   AiEmbedDecl,
   AiMcpServerDecl,
   AiModelDecl,
@@ -52,3 +53,5 @@ export const aiEmbedRegistry: AiEmbedDecl[] = [];
 export const aiAgentRegistry: AiAgentDecl[] = [];
 /** `ai.mcpServer` declarations since the last reset. */
 export const aiMcpServerRegistry: AiMcpServerDecl[] = [];
+/** `ai.decision` declarations since the last reset. */
+export const aiDecisionRegistry: AiDecisionDecl[] = [];

package/src/kernel/errors-compiler.ts

@@ -12,6 +12,17 @@ import type { OkeErrorDefinition } from "./errors.ts";
  * A Flow hides `fx` from effect inference, or an explicit `effects` block
  * omits an effect the walk can see.
  */
+/**
+ * A durable Flow calls `fx.fetch` or `fx.send` outside `fx.step`.
+ * Those effects are irreversible and must be an explicit step so replay skips them.
+ */
+export const DURABLE_BARE_EFFECT: OkeErrorDefinition = {
+  code: 1901,
+  domain: "compiler",
+  cause: 'Durable flow "{flow}" calls fx.{effect} outside fx.step.',
+  fix: "Wrap fx.fetch and fx.send in fx.step so replay returns the journaled value instead of repeating the call.",
+};
+
 export const FX_INFERENCE_OPAQUE: OkeErrorDefinition = {
   code: 1900,
   domain: "compiler",

package/src/kernel/errors-text.ts

@@ -52,6 +52,10 @@ export const OKE_ERROR_TEXT: Readonly<Record<string, OkeErrorText>> = {
     cause: 'Flow "{flow}" embeds with "{resource}" without declaring it.',
     fix: 'Add "{resource}" to this flow\'s effects.embeds.',
   },
+  UNDECLARED_DECIDE: {
+    cause: 'Flow "{flow}" decides "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.decides.',
+  },
   NO_EFFECTS_DECLARED: {
     cause: 'Flow "{flow}" has no declared effects and no Manifest to derive them from.{extract}',
     fix:
@@ -80,6 +84,22 @@ export const OKE_ERROR_TEXT: Readonly<Record<string, OkeErrorText>> = {
       'Live signal "{signal}" is exposed twice with the same gates ({gates}) and match ({match}).',
     fix: "Use a different gate or path-param filter, or drop the extra route.",
   },
+  JOURNAL_STALE_LEASE: {
+    cause: 'Journal run "{runId}" rejected a write from an expired lease holder.',
+    fix: "Resume the run so the current holder acquires a new lease token. Do not write with a token from a previous holder.",
+  },
+  JOURNAL_REPLAY_DIVERGENCE: {
+    cause: 'Journal run "{runId}" expected {expected} but the code called {actual}.',
+    fix: "Keep step names, sleep labels, and effect order stable for in-flight runs. A code change that reorders journal calls cannot resume the old run.",
+  },
+  JOURNAL_CODE_VERSION: {
+    cause: 'Journal run "{runId}" was started on code {expected} and this process is {actual}.',
+    fix: "Finish or abandon in-flight runs before deploying a different code version. Do not replay them on the new build.",
+  },
+  JOURNAL_VALUE_NOT_JSON: {
+    cause: "A durable journal entry held a value that is not JSON ({detail}).",
+    fix: "Return plain JSON from fx.step. fx.fetch and fx.send must run inside fx.step so the journal can store a JSON snapshot.",
+  },
   MCP_TOOL_DUPLICATE: {
     cause: 'MCP tool "{tool}" is bound twice (flow "{flow}").',
     fix: "Give each MCP tool exposure a unique tool name.",

package/src/kernel/errors.ts

@@ -270,6 +270,8 @@ const OKE_ERROR_ROWS = {
   UNDECLARED_FETCH: { code: 1008, domain: "kernel" },
   /** Flow embeds via a model not listed in `effects.embeds`. */
   UNDECLARED_EMBED: { code: 1009, domain: "kernel" },
+  /** Flow decides a decision not listed in `effects.decides`. */
+  UNDECLARED_DECIDE: { code: 1010, domain: "kernel" },
   /**
    * Flow has no declared `effects` and no Manifest-derived effects were
    * available to stamp at boot (dev+compose / prod — never a silent open token).
@@ -292,6 +294,14 @@ const OKE_ERROR_ROWS = {
   LIVE_EXPOSURE_DUPLICATE: { code: 1050, domain: "kernel" },
   /** Two MCP tool bindings share the same exposed tool name. */
   MCP_TOOL_DUPLICATE: { code: 1060, domain: "kernel" },
+  /** A journal write arrived from a holder whose lease token no longer matches. */
+  JOURNAL_STALE_LEASE: { code: 1074, domain: "kernel" },
+  /** Replay called a different step or effect than the next journal entry. */
+  JOURNAL_REPLAY_DIVERGENCE: { code: 1075, domain: "kernel" },
+  /** Resume of a run stamped with a different code version. */
+  JOURNAL_CODE_VERSION: { code: 1076, domain: "kernel" },
+  /** A journaled value could not be stored as JSON. */
+  JOURNAL_VALUE_NOT_JSON: { code: 1077, domain: "kernel" },
   /**
    * Emit target has no subscriber (unified-theory §21).
    * Thrown at emit when `optional` is false and nobody is subscribed.

package/src/kernel/flow.test.ts

@@ -46,9 +46,8 @@ describe("flow — one species", () => {
     on(signal, shared);
 
     const app = oke({ autoBoot: false, name: "one-species" });
-    expect(app.bindings).toHaveLength(2);
-    expect(app.bindings[0]?.flow).toBe(shared);
-    expect(app.bindings[1]?.flow).toBe(shared);
+    const sharedBindings = app.bindings.filter((binding) => binding.flow === shared);
+    expect(sharedBindings).toHaveLength(2);
 
     const httpResult = await app.execute(shared, { n: 3 }, shared.triggers[0]!);
     const signalResults = await app.dispatchSignal("order-placed", { n: 4 });

package/src/kernel/flow.ts

@@ -49,9 +49,9 @@ export interface FlowOptions<I = unknown, O = unknown> {
    */
   readonly retry?: FxRetryOptions;
   /**
-   * Cache policy. Read-only flows cache automatically from inferred
-   * effects (`true` / omitted). `false` opts out; a duration string
-   * (`"30s"`) adds a TTL on top of write invalidation.
+   * Cache policy. Omitted caches a pure store-read flow. `true` or a duration
+   * (`"30s"`) opts one flow in when the app set `cache: { auto: false }`.
+   * `false` always disables. The key includes tenant, locale, scopes, and roles.
    */
   readonly cache?: boolean | string;
   /**
@@ -124,6 +124,10 @@ export type InferFlowOut<Opts> = Opts extends { readonly do: FlowHandler<infer _
  * `FlowDef<…, undefined>` remains assignable into `on()` before rebinding.
  */
 declare const triggerPhantom: unique symbol;
+/** Covariant input phantom so `fx.call` can read `I` without hitting `do`. */
+declare const inputPhantom: unique symbol;
+/** Covariant output phantom so `fx.call` can read `O` without hitting `do`. */
+declare const outputPhantom: unique symbol;
 
 /**
  * A Flow definition — one species, trigger-agnostic until {@link on} binds.
@@ -151,6 +155,10 @@ export interface FlowDef<
    * `$trigger` / `triggers[0]` for the value.
    */
   readonly [triggerPhantom]?: T;
+  /** Type-level input. Not present at runtime. */
+  readonly [inputPhantom]?: I;
+  /** Type-level output. Not present at runtime. */
+  readonly [outputPhantom]?: O;
   /** Stable name (auto-assigned when omitted). */
   readonly name: string;
   /** Unit scope — derived from `name`'s first dot segment (e.g. `"auth.refresh"` → `"auth"`). */
@@ -255,6 +263,28 @@ export interface FlowDef<
   ): FlowDef<I, O, E, D & (P extends PluginDef<infer PD> ? PD : Record<string, never>), T>;
 }
 
+/**
+ * Input type of a Flow handle. `unknown` when `F` is a string name.
+ *
+ * @typeParam F - Flow handle or other call target
+ */
+export type FlowInput<F> = F extends { readonly [inputPhantom]?: infer I }
+  ? [I] extends [undefined]
+    ? unknown
+    : Exclude<I, undefined>
+  : unknown;
+
+/**
+ * Output type of a Flow handle. `unknown` when `F` is a string name.
+ *
+ * @typeParam F - Flow handle or other call target
+ */
+export type FlowOutput<F> = F extends { readonly [outputPhantom]?: infer O }
+  ? [O] extends [undefined]
+    ? unknown
+    : Exclude<O, undefined>
+  : unknown;
+
 /** Unique brand symbol for {@link FlowDef}. */
 export const flowBrand: unique symbol = Symbol("oke.flow");