okengine 0.1.4

package/src/kernel/flow.ts

@@ -0,0 +1,290 @@
+/**
+ * `flow` — the one species of backend behavior.
+ *
+ * A Flow is a typed contract (`in` / `out` / `errors`) plus a `do` body.
+ * Triggers are attached by {@link on}; a flow with no trigger is still a
+ * Flow and is callable via `fx.call` (unified-theory §4, Linkly ⑤).
+ */
+
+import type { Effects, FlowPlane, Slo } from "../manifest/types.ts";
+import type {
+  InferSchemaOutput,
+  SchemaInput,
+} from "../validation/standard-schema.ts";
+import type { FlowFailure } from "./errors.ts";
+import type { Fx } from "./fx.ts";
+import type { HookFn, HookStage } from "./hooks.ts";
+import type { PluginDef } from "./plugin.ts";
+import type { Trigger } from "./triggers.ts";
+
+export type {
+  SchemaInput,
+  StandardSchemaV1,
+} from "../validation/standard-schema.ts";
+
+/** Result of a Standard Schema validate call (re-export shape). */
+export type StandardSchemaResult<Output> =
+  | { readonly value: Output; readonly issues?: undefined }
+  | { readonly issues: ReadonlyArray<{ readonly message: string }> };
+
+/** Map of declared flow-boundary error names to their schemas. */
+export type FlowErrorMap = Readonly<Record<string, SchemaInput>>;
+
+/**
+ * Body of a Flow. Receives validated input and the `fx` door.
+ *
+ * @typeParam I - Input type
+ * @typeParam O - Output type
+ */
+export type FlowHandler<I = unknown, O = unknown> = (
+  input: I,
+  fx: Fx,
+) => O | FlowFailure | Promise<O | FlowFailure>;
+
+/** Options for {@link flow}. */
+export interface FlowOptions<
+  I = unknown,
+  O = unknown,
+  E extends FlowErrorMap = FlowErrorMap,
+> {
+  /** Optional stable name (used by `fx.call` and the Manifest). */
+  readonly name?: string;
+  /** Optional unit scope for unit-level hooks. */
+  readonly unit?: string;
+  /** Input schema (Standard Schema when present). */
+  readonly in?: SchemaInput;
+  /** Output schema (Standard Schema when present). */
+  readonly out?: SchemaInput;
+  /** Declared typed errors. */
+  readonly errors?: E;
+  /** Declared effects (capability token). Inferred later by AoT. */
+  readonly effects?: Effects;
+  /** Journal every effect call. */
+  readonly durable?: boolean;
+  /** Live-query / push result. */
+  readonly live?: boolean;
+  /** Cache TTL (`true` = default policy, or a duration string). */
+  readonly cache?: boolean | string;
+  /** Declared service-level objective. */
+  readonly slo?: Slo;
+  /**
+   * Plane — `user` (application) or `operator` (Console).
+   * Cross-plane invocation is a compile error.
+   */
+  readonly plane?: FlowPlane;
+  /** The behavior. */
+  readonly do: FlowHandler<I, O>;
+}
+
+/**
+ * Infer validated input from a flow options bag.
+ *
+ * @typeParam Opts - {@link FlowOptions} / call-site object
+ */
+export type InferFlowIn<Opts> = Opts extends { readonly in: infer S }
+  ? InferSchemaOutput<S>
+  : Opts extends { readonly do: FlowHandler<infer I, infer _O> }
+    ? I
+    : unknown;
+
+/**
+ * Infer success output from a flow options bag.
+ *
+ * @typeParam Opts - {@link FlowOptions} / call-site object
+ */
+export type InferFlowOut<Opts> = Opts extends { readonly out: infer S }
+  ? InferSchemaOutput<S>
+  : Opts extends { readonly do: FlowHandler<infer _I, infer O> }
+    ? O
+    : unknown;
+
+/**
+ * Infer the error schema map from a flow options bag.
+ *
+ * @typeParam Opts - {@link FlowOptions} / call-site object
+ */
+export type InferFlowErrors<Opts> = Opts extends {
+  readonly errors: infer E extends FlowErrorMap;
+}
+  ? E
+  : {};
+
+/**
+ * Phantom brand for the bound trigger type parameter. Optional so
+ * `FlowDef<…, undefined>` remains assignable into `on()` before rebinding.
+ */
+declare const triggerPhantom: unique symbol;
+
+/**
+ * A Flow definition — one species, trigger-agnostic until {@link on} binds.
+ *
+ * @typeParam I - Input type
+ * @typeParam O - Output type
+ * @typeParam E - Error map (schemas)
+ * @typeParam D - Accumulated decoration types from `.plug()`
+ * @typeParam T - Bound trigger (set by {@link on}; `undefined` when untriggered)
+ */
+export interface FlowDef<
+  I = unknown,
+  O = unknown,
+  E extends FlowErrorMap = FlowErrorMap,
+  D extends Record<string, unknown> = {},
+  T extends Trigger | undefined = undefined,
+> {
+  /** Brand for type guards. */
+  readonly [flowBrand]: true;
+  /**
+   * Type-level bound trigger (phantom). Not read at runtime — use
+   * `$trigger` / `triggers[0]` for the value.
+   */
+  readonly [triggerPhantom]?: T;
+  /** Stable name (auto-assigned when omitted). */
+  readonly name: string;
+  /** Optional unit scope. */
+  readonly unit: string | undefined;
+  /** Input schema. */
+  readonly in: SchemaInput | undefined;
+  /** Output schema. */
+  readonly out: SchemaInput | undefined;
+  /** Declared errors. */
+  readonly errors: E | undefined;
+  /** Declared effects. */
+  readonly effects: Effects | undefined;
+  /** Durability flag. */
+  readonly durable: boolean;
+  /** Live flag. */
+  readonly live: boolean;
+  /** Cache option. */
+  readonly cache: boolean | string | undefined;
+  /** SLO. */
+  readonly slo: Slo | undefined;
+  /** Plane (user vs operator). */
+  readonly plane: FlowPlane | undefined;
+  /** Handler body. */
+  readonly do: FlowHandler<I, O>;
+  /** Triggers bound via {@link on} (zero or more). */
+  readonly triggers: readonly Trigger[];
+  /**
+   * First bound trigger at runtime (`undefined` when untriggered).
+   * The precise trigger literal lives in the {@link triggerPhantom} type param.
+   */
+  readonly $trigger: Trigger | undefined;
+  /** Flow-scoped hooks, registration order. */
+  readonly hooks: Readonly<Partial<Record<HookStage, readonly HookFn[]>>>;
+  /**
+   * Plugins queued via {@link FlowDef.plug} until an app registry adopts them.
+   * @internal
+   */
+  readonly pendingPlugins: readonly PluginDef[];
+  /** Accumulated decoration types from `.plug()` (type-level only). */
+  readonly decorations?: D;
+  /**
+   * Register a flow-scoped hook (registration order, no priority numbers).
+   *
+   * @param stage - Pipeline stage
+   * @param fn - Hook function
+   */
+  hook(stage: HookStage, fn: HookFn): FlowDef<I, O, E, D, T>;
+  /**
+   * Attach a plugin to this flow only. Scope is the attachment point.
+   *
+   * @param pluginDef - Plugin from {@link plugin}
+   */
+  plug<P extends PluginDef>(
+    pluginDef: P,
+  ): FlowDef<
+    I,
+    O,
+    E,
+    D & (P extends PluginDef<infer PD> ? PD : Record<string, never>),
+    T
+  >;
+}
+
+/** Unique brand symbol for {@link FlowDef}. */
+export const flowBrand: unique symbol = Symbol("oke.flow");
+
+let flowSeq = 0;
+
+/**
+ * Define a Flow — the one species of backend behavior.
+ *
+ * Input / output types are inferred from Standard Schema `in` / `out` when
+ * present; otherwise from the `do` handler signature.
+ *
+ * @param options - Contract and handler
+ */
+export function flow<Opts extends FlowOptions<any, any, any>>(
+  options: Opts,
+): FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>> {
+  const name = options.name ?? `flow_${++flowSeq}`;
+  const triggers: Trigger[] = [];
+  const hooks: Partial<Record<HookStage, HookFn[]>> = {};
+  const pendingPlugins: PluginDef[] = [];
+
+  const def: FlowDef<
+    InferFlowIn<Opts>,
+    InferFlowOut<Opts>,
+    InferFlowErrors<Opts>
+  > = {
+    [flowBrand]: true,
+    name,
+    unit: options.unit,
+    in: options.in,
+    out: options.out,
+    errors: (options.errors ?? undefined) as InferFlowErrors<Opts> | undefined,
+    effects: options.effects,
+    durable: options.durable ?? false,
+    live: options.live ?? false,
+    cache: options.cache,
+    slo: options.slo,
+    plane: options.plane,
+    do: options.do as FlowHandler<InferFlowIn<Opts>, InferFlowOut<Opts>>,
+    triggers,
+    $trigger: undefined,
+    hooks,
+    pendingPlugins,
+    hook(stage, fn) {
+      const list = hooks[stage] ?? (hooks[stage] = []);
+      list.push(fn);
+      return def;
+    },
+    plug(pluginDef) {
+      pendingPlugins.push(pluginDef);
+      // Decorations accumulate on the interface; runtime object is unchanged.
+      return def as never;
+    },
+  };
+
+  return def;
+}
+
+/**
+ * Erased flow type for heterogenous registries (`on` bindings, app index).
+ * Individual flows keep their `I`/`O` at the declaration site; the registry
+ * cannot preserve every specialization without an erased carrier type.
+ */
+export type AnyFlowDef = FlowDef<any, any, any, any, any>;
+
+/**
+ * Type guard for {@link FlowDef}.
+ *
+ * @param value - Unknown value
+ */
+export function isFlow(value: unknown): value is AnyFlowDef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    flowBrand in value &&
+    (value as AnyFlowDef)[flowBrand] === true
+  );
+}
+
+/**
+ * Reset the auto-name sequence (tests only).
+ *
+ * @internal
+ */
+export function resetFlowSeq(): void {
+  flowSeq = 0;
+}

package/src/kernel/fx.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, test } from "bun:test";
+import { createCapabilityToken } from "./capability.ts";
+import { createEffectLedger, reversibilityOf } from "./effects.ts";
+import {
+  fail,
+  formatOkeMessage,
+  lookupOkeError,
+  OKE_ERRORS,
+  OkeError,
+} from "./errors.ts";
+import {
+  createFx,
+  createFxContext,
+  type Fx,
+  type FxStubStoreHandle,
+} from "./fx.ts";
+
+/** Narrow stub handle for tests that exercise the in-memory store. */
+function stub(fx: Fx, ref: string): FxStubStoreHandle {
+  return fx.store(ref) as FxStubStoreHandle;
+}
+
+describe("fx — capability enforcement", () => {
+  test("undeclared store read throws OKE1001 with flow, resource, and fix", async () => {
+    const { fx } = createFxContext({
+      flow: "bookings.create",
+      effects: { reads: ["sql:bookings"] },
+    });
+
+    let err: unknown;
+    try {
+      await stub(fx, "sql:users").get("u1");
+    } catch (e) {
+      err = e;
+    }
+
+    expect(err).toBeInstanceOf(OkeError);
+    const oke = err as OkeError;
+    expect(oke.code).toBe(1001);
+    expect(oke.causeText).toBe(
+      'Flow "bookings.create" reads "sql:users" without declaring it.',
+    );
+    expect(oke.fix).toBe(
+      'Add "sql:users" to this flow\'s effects.reads.',
+    );
+    expect(oke.docsUrl).toBe("https://oke.dev/e/1001");
+    expect(oke.message).toBe(
+      formatOkeMessage(1001, oke.causeText, oke.fix, oke.docsUrl),
+    );
+  });
+
+  test("declared store read succeeds", async () => {
+    const fx = createFx({
+      flow: "bookings.create",
+      effects: { reads: ["sql:bookings"] },
+      storeData: { "sql:bookings": { b1: { id: "b1" } } },
+    });
+    await expect(stub(fx, "sql:bookings").get("b1")).resolves.toEqual({
+      id: "b1",
+    });
+  });
+});
+
+describe("fx — effect ledger", () => {
+  test("read, write, emit → exactly three ledger entries in order", async () => {
+    const ledger = createEffectLedger();
+    const fx = createFx({
+      flow: "bookings.create",
+      effects: {
+        reads: ["sql:bookings"],
+        writes: ["sql:bookings"],
+        emits: ["order-placed"],
+      },
+      ledger,
+    });
+
+    await stub(fx, "sql:bookings").get("b1");
+    await stub(fx, "sql:bookings").insert({ seats: 2 });
+    await fx.emit("order-placed", { orderId: "o1" });
+
+    expect(ledger.entries).toHaveLength(3);
+    expect(ledger.entries.map((e) => e.kind)).toEqual([
+      "read",
+      "write",
+      "emit",
+    ]);
+    expect(ledger.entries.map((e) => e.resource)).toEqual([
+      "sql:bookings",
+      "sql:bookings",
+      "order-placed",
+    ]);
+    expect(ledger.entries.map((e) => e.reversibility)).toEqual([
+      "none",
+      "reversible",
+      "deferred",
+    ]);
+  });
+
+  test("all seven kinds receive the correct reversibility tier via fx", async () => {
+    const ledger = createEffectLedger();
+    const fx = createFx({
+      flow: "kitchen.sink",
+      effects: {
+        reads: ["sql:bookings"],
+        writes: ["sql:bookings"],
+        emits: ["order-placed"],
+        sends: ["order-confirmed"],
+        asks: ["triage@1"],
+        secrets: ["STRIPE_KEY"],
+        calls: ["payments.charge"],
+      },
+      ledger,
+      secrets: { STRIPE_KEY: "sk_test" },
+    });
+
+    await stub(fx, "sql:bookings").get("x");
+    await stub(fx, "sql:bookings").set("x", { ok: true });
+    await fx.emit("order-placed", {});
+    await fx.send("order-confirmed", { to: "u1" });
+    await fx.ask("triage@1", {});
+    expect(fx.vault("STRIPE_KEY")).toBe("sk_test");
+    await fx.call("payments.charge", {});
+
+    expect(ledger.entries).toHaveLength(7);
+    const kinds = ledger.entries.map((e) => e.kind);
+    expect(kinds).toEqual([
+      "read",
+      "write",
+      "emit",
+      "send",
+      "ask",
+      "secret",
+      "call",
+    ]);
+    for (const entry of ledger.entries) {
+      expect(entry.reversibility).toBe(reversibilityOf(entry.kind));
+    }
+  });
+});
+
+describe("fx — wholesale swap", () => {
+  test("fx is swappable wholesale (plain object interface)", async () => {
+    const calls: string[] = [];
+
+    const fake: Fx = {
+      store() {
+        throw new Error("store must not be used");
+      },
+      async emit(signal) {
+        calls.push(`emit:${typeof signal === "string" ? signal : signal.name}`);
+      },
+      async call() {
+        return null;
+      },
+      clock: {
+        now: () => 0,
+        sleep: async () => undefined,
+      },
+      vault() {
+        return "";
+      },
+      cache: {
+        get: async () => undefined,
+        set: async () => undefined,
+        getOrSet: async (_k, _t, produce) => produce(),
+      },
+      async send() {
+        return { ok: true };
+      },
+      async ask() {
+        return {};
+      },
+      async search() {
+        return [];
+      },
+      async run() {
+        return {};
+      },
+      async *stream() {
+        /* empty */
+      },
+      log: {
+        debug() {},
+        info() {},
+        warn() {},
+        error() {},
+      },
+      t: (key) => key,
+      id: () => "fixed-id",
+      auth: { userId: "u1", scopes: new Set(["a"]) },
+      operator: { id: null },
+      tenant: { id: "t1" },
+      fail,
+      async step(_name, fn) {
+        return fn();
+      },
+    };
+
+    // Any code that accepts `Fx` can run against a total replacement.
+    async function runFlow(fx: Fx): Promise<string> {
+      await fx.emit("order-placed", { id: fx.id() });
+      return fx.t("hello");
+    }
+
+    await expect(runFlow(fake)).resolves.toBe("hello");
+    expect(calls).toEqual(["emit:order-placed"]);
+  });
+});
+
+describe("errors — registry", () => {
+  test("OKE1042 is reserved with the §21 shape", () => {
+    const def = OKE_ERRORS.ORPHAN_EMIT;
+    expect(def.code).toBe(1042);
+    expect(lookupOkeError(1042)).toEqual(def);
+    const err = new OkeError(def, {
+      flow: "bookings.create",
+      resource: "order-placed",
+    });
+    expect(err.message).toContain("OKE1042");
+    expect(err.message).toContain("no subscriber");
+    expect(err.message).toContain("https://oke.dev/e/1042");
+    expect(err.message).toContain("→");
+  });
+
+  test("fx.fail returns a value, not an exception", () => {
+    const fx = createFx({ flow: "x", effects: {} });
+    const result = fx.fail("FlightFull", { seatsLeft: 0 }, {
+      message: "full",
+    });
+    expect(result).toEqual({
+      data: null,
+      error: { code: "FlightFull", data: { seatsLeft: 0 }, message: "full" },
+    });
+  });
+
+  test("capability token allows only declared resources", () => {
+    const token = createCapabilityToken("f", {
+      reads: ["sql:a"],
+      emits: ["s"],
+    });
+    expect(token.allows("read", "sql:a")).toBe(true);
+    expect(token.allows("read", "sql:b")).toBe(false);
+    expect(() => token.assert("emit", "missing")).toThrow(OkeError);
+  });
+});