okengine 0.1.4

package/src/kernel/effects.ts

@@ -0,0 +1,140 @@
+/**
+ * Effect recording and the typed effect ledger.
+ *
+ * Every `fx` world access appends an {@link EffectEntry}. The ledger is what
+ * the journal, tests, runs store, and capability check all read.
+ */
+
+/** The seven load-bearing effect kinds (manifest `effects` keys, singular). */
+export type EffectKind =
+  | "read"
+  | "write"
+  | "emit"
+  | "send"
+  | "ask"
+  | "secret"
+  | "call";
+
+/**
+ * Reversibility tier — console §9.1 ranking, applied to all seven kinds.
+ *
+ * - `none` — reads; no world change
+ * - `reversible` — writes; undoable in-transaction
+ * - `deferred` — emits; commit with the txn, then fan-out
+ * - `irreversible` — sends / asks; cannot be undone by the runtime
+ * - `capability` — secrets; authority held, not an effect caused
+ * - `portal` — calls; expands to the callee's transitive effects
+ */
+export type ReversibilityTier =
+  | "none"
+  | "reversible"
+  | "deferred"
+  | "irreversible"
+  | "capability"
+  | "portal";
+
+/** One recorded effect call. */
+export interface EffectEntry {
+  /** Which of the seven kinds. */
+  readonly kind: EffectKind;
+  /** Resource / signal / template / prompt / secret / flow ref. */
+  readonly resource: string;
+  /** Epoch-ms when the call started. */
+  readonly timestamp: number;
+  /** Wall duration in milliseconds. */
+  readonly duration: number;
+  /** Reversibility tier for {@link kind}. */
+  readonly reversibility: ReversibilityTier;
+}
+
+/** Append-only ledger of effect entries for one flow invocation. */
+export interface EffectLedger {
+  /** Snapshot of recorded entries in call order. */
+  readonly entries: readonly EffectEntry[];
+  /**
+   * Append a completed effect entry.
+   *
+   * @param entry - Entry to record
+   */
+  record(entry: EffectEntry): void;
+  /** Clear all entries (test helper). */
+  clear(): void;
+}
+
+/** Fixed mapping: kind → reversibility tier. */
+const TIER_BY_KIND: Readonly<Record<EffectKind, ReversibilityTier>> = {
+  read: "none",
+  write: "reversible",
+  emit: "deferred",
+  send: "irreversible",
+  ask: "irreversible",
+  secret: "capability",
+  call: "portal",
+};
+
+/**
+ * Reversibility tier for an effect kind.
+ *
+ * @param kind - One of the seven effect kinds
+ */
+export function reversibilityOf(kind: EffectKind): ReversibilityTier {
+  return TIER_BY_KIND[kind];
+}
+
+/**
+ * Create an empty in-memory effect ledger.
+ */
+export function createEffectLedger(): EffectLedger {
+  const entries: EffectEntry[] = [];
+  return {
+    get entries() {
+      return entries;
+    },
+    record(entry: EffectEntry): void {
+      entries.push(entry);
+    },
+    clear(): void {
+      entries.length = 0;
+    },
+  };
+}
+
+/**
+ * Record an effect around an async (or sync) body, measuring duration.
+ *
+ * @param ledger - Target ledger
+ * @param kind - Effect kind
+ * @param resource - Resource ref
+ * @param now - Clock (injectable for tests)
+ * @param body - Work to time
+ */
+export async function recordEffect<T>(
+  ledger: EffectLedger,
+  kind: EffectKind,
+  resource: string,
+  now: () => number,
+  body: () => T | Promise<T>,
+): Promise<T> {
+  const timestamp = now();
+  try {
+    return await body();
+  } finally {
+    ledger.record({
+      kind,
+      resource,
+      timestamp,
+      duration: Math.max(0, now() - timestamp),
+      reversibility: reversibilityOf(kind),
+    });
+  }
+}
+
+/**
+ * All seven kinds with their tiers — useful for exhaustive tests.
+ */
+export const EFFECT_KIND_TIERS: ReadonlyArray<{
+  kind: EffectKind;
+  reversibility: ReversibilityTier;
+}> = (
+  Object.entries(TIER_BY_KIND) as Array<[EffectKind, ReversibilityTier]>
+).map(([kind, reversibility]) => ({ kind, reversibility }));

package/src/kernel/errors.registry.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Error-code registry gate — unique codes, cause/fix/docsUrl shape (§21).
+ *
+ * Docs pages (docs/e/{code}.md) are deferred to a dedicated docs prompt;
+ * this gate enforces registry invariants only.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  OKE_ERRORS,
+  OkeError,
+  type OkeErrorDefinition,
+} from "./errors.ts";
+
+describe("OKE error-code registry", () => {
+  test("every code is unique", () => {
+    const codes = Object.values(OKE_ERRORS).map((d) => d.code);
+    expect(new Set(codes).size).toBe(codes.length);
+  });
+
+  test("every entry has non-empty cause and fix templates", () => {
+    for (const [key, def] of Object.entries(OKE_ERRORS)) {
+      expect(def.cause.trim().length, `${key}.cause`).toBeGreaterThan(0);
+      expect(def.fix.trim().length, `${key}.fix`).toBeGreaterThan(0);
+      expect(Number.isInteger(def.code), `${key}.code`).toBe(true);
+      expect(def.code, `${key}.code`).toBeGreaterThan(0);
+    }
+  });
+
+  test("OkeError docsUrl matches https://oke.dev/e/{code}", () => {
+    for (const def of Object.values(OKE_ERRORS) as OkeErrorDefinition[]) {
+      const err = new OkeError(def);
+      expect(err.docsUrl).toBe(`https://oke.dev/e/${def.code}`);
+      expect(err.message).toContain(err.docsUrl);
+      expect(err.message).toContain(`OKE${def.code}`);
+      expect(err.message).toContain("→");
+    }
+  });
+});

package/src/kernel/errors.ts

@@ -0,0 +1,225 @@
+/**
+ * Typed framework errors and flow-boundary failure values.
+ *
+ * Every framework error has a stable numeric code, a one-line cause,
+ * a suggested fix, and a docs URL (unified-theory §21). Codes are
+ * permanent from the moment they enter this registry.
+ */
+
+/** Numeric OKE error code (permanent once published). */
+export type OkeErrorCode = number;
+
+/** One registry entry — cause/fix may include `{name}` placeholders. */
+export interface OkeErrorDefinition {
+  /** Permanent numeric code. */
+  readonly code: OkeErrorCode;
+  /** One-line cause template. */
+  readonly cause: string;
+  /** Suggested fix template. */
+  readonly fix: string;
+}
+
+/** Context values interpolated into cause/fix templates. */
+export type OkeErrorParams = Readonly<Record<string, string>>;
+
+/**
+ * Framework error: thrown for invariant violations (capability, wiring).
+ * Distinct from flow-boundary failures returned by {@link fail}.
+ */
+export class OkeError extends Error {
+  /** Permanent numeric code. */
+  readonly code: OkeErrorCode;
+  /** Interpolated one-line cause. */
+  readonly causeText: string;
+  /** Interpolated suggested fix. */
+  readonly fix: string;
+  /** Docs URL for this code. */
+  readonly docsUrl: string;
+  /** Interpolation params used to build the message. */
+  readonly params: OkeErrorParams;
+
+  /**
+   * @param definition - Registry entry
+   * @param params - Values for `{placeholders}` in cause/fix
+   */
+  constructor(definition: OkeErrorDefinition, params: OkeErrorParams = {}) {
+    const causeText = interpolate(definition.cause, params);
+    const fix = interpolate(definition.fix, params);
+    const docsUrl = `https://oke.dev/e/${definition.code}`;
+    const message = formatOkeMessage(definition.code, causeText, fix, docsUrl);
+    super(message);
+    this.name = "OkeError";
+    this.code = definition.code;
+    this.causeText = causeText;
+    this.fix = fix;
+    this.docsUrl = docsUrl;
+    this.params = params;
+  }
+}
+
+/**
+ * Flow-boundary failure value produced by {@link fail}.
+ * Errors are values (`{ data, error }`), not exceptions, at the flow boundary.
+ */
+export interface FlowFailure<E = unknown> {
+  readonly data: null;
+  readonly error: FlowErrorValue<E>;
+}
+
+/** Payload carried by a flow-boundary failure. */
+export interface FlowErrorValue<E = unknown> {
+  /**
+   * Declared error code from the flow's `errors` map
+   * (e.g. `"FlightFull"`, `"ValidationError"`) — not an OKE#### number.
+   * Clients narrow with `error?.code === "FlightFull"`.
+   */
+  readonly code: string;
+  /** Typed error data from the flow. */
+  readonly data: E;
+  /** Optional localized or custom message. */
+  readonly message?: string;
+}
+
+/** Optional extras for {@link fail}. */
+export interface FailOptions {
+  /** Override message (often from `fx.t(...)`). */
+  readonly message?: string;
+}
+
+/**
+ * Permanent error registry. Codes never change meaning once published.
+ *
+ * Ranges (convention):
+ * - `1000–1099` — capability / undeclared-effect violations
+ * - `1042` — reserved by unified-theory §21 example (orphan emit)
+ */
+export const OKE_ERRORS = {
+  /** Flow reads a store resource not listed in `effects.reads`. */
+  UNDECLARED_READ: {
+    code: 1001,
+    cause:
+      'Flow "{flow}" reads "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.reads.',
+  },
+  /** Flow writes a store resource not listed in `effects.writes`. */
+  UNDECLARED_WRITE: {
+    code: 1002,
+    cause:
+      'Flow "{flow}" writes "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.writes.',
+  },
+  /** Flow emits a signal not listed in `effects.emits`. */
+  UNDECLARED_EMIT: {
+    code: 1003,
+    cause:
+      'Flow "{flow}" emits "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.emits.',
+  },
+  /** Flow sends a channel template not listed in `effects.sends`. */
+  UNDECLARED_SEND: {
+    code: 1004,
+    cause:
+      'Flow "{flow}" sends "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.sends.',
+  },
+  /** Flow asks a prompt not listed in `effects.asks`. */
+  UNDECLARED_ASK: {
+    code: 1005,
+    cause:
+      'Flow "{flow}" asks "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.asks.',
+  },
+  /** Flow reads a secret not listed in `effects.secrets`. */
+  UNDECLARED_SECRET: {
+    code: 1006,
+    cause:
+      'Flow "{flow}" reads secret "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.secrets.',
+  },
+  /** Flow calls another flow not listed in `effects.calls`. */
+  UNDECLARED_CALL: {
+    code: 1007,
+    cause:
+      'Flow "{flow}" calls "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.calls.',
+  },
+  /**
+   * Emit target has no subscriber (unified-theory §21 example).
+   * Reserved now so the number stays permanent.
+   */
+  ORPHAN_EMIT: {
+    code: 1042,
+    cause:
+      'Flow "{flow}" emits signal "{resource}" with no subscriber.',
+    fix: 'Add `on({resource}, …)` or mark the signal `{ optional: true }`.',
+  },
+} as const satisfies Record<string, OkeErrorDefinition>;
+
+/**
+ * Build and throw a registered framework error.
+ *
+ * @param key - Key into {@link OKE_ERRORS}
+ * @param params - Interpolation params
+ * @returns Never
+ */
+export function throwOke(
+  key: keyof typeof OKE_ERRORS,
+  params: OkeErrorParams = {},
+): never {
+  throw new OkeError(OKE_ERRORS[key], params);
+}
+
+/**
+ * Look up a registry entry by numeric code.
+ *
+ * @param code - Permanent numeric code
+ */
+export function lookupOkeError(
+  code: OkeErrorCode,
+): OkeErrorDefinition | undefined {
+  for (const def of Object.values(OKE_ERRORS)) {
+    if (def.code === code) return def;
+  }
+  return undefined;
+}
+
+/**
+ * Create a flow-boundary failure value (does not throw).
+ *
+ * @param code - Declared error code from the flow's `errors` map
+ * @param data - Error payload
+ * @param opts - Optional message override
+ */
+export function fail<E>(
+  code: string,
+  data: E,
+  opts?: FailOptions,
+): FlowFailure<E> {
+  const error: FlowErrorValue<E> = opts?.message !== undefined
+    ? { code, data, message: opts.message }
+    : { code, data };
+  return { data: null, error };
+}
+
+/**
+ * Format the canonical multi-line OKE error message (§21).
+ *
+ * @param code - Numeric code
+ * @param cause - Interpolated cause
+ * @param fix - Interpolated fix
+ * @param docsUrl - Docs URL
+ */
+export function formatOkeMessage(
+  code: OkeErrorCode,
+  cause: string,
+  fix: string,
+  docsUrl: string,
+): string {
+  return `OKE${code}  ${cause}\n         → ${fix}\n         ${docsUrl}`;
+}
+
+function interpolate(template: string, params: OkeErrorParams): string {
+  return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, key: string) => {
+    return params[key] ?? `{${key}}`;
+  });
+}

package/src/kernel/flow.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test, beforeEach } from "bun:test";
+import { oke } from "./app.ts";
+import { flow, isFlow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import {
+  every,
+  http,
+  internal,
+  table,
+} from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("flow — one species", () => {
+  test("flow() returns a branded FlowDef", () => {
+    const f = flow({
+      name: "ping",
+      do: () => ({ ok: true }),
+    });
+    expect(isFlow(f)).toBe(true);
+    expect(f.name).toBe("ping");
+    expect(f.triggers).toEqual([]);
+    expect(f.durable).toBe(false);
+  });
+
+  test("on() returns the same flow object and records the trigger", () => {
+    const f = flow({ name: "create", do: () => 1 });
+    const bound = on(http.post("/notes"), f);
+    // Same runtime object; trigger stamp is type-only so identities differ at the type level.
+    expect(bound as object).toBe(f);
+    expect(f.triggers).toHaveLength(1);
+    expect(f.triggers[0]?.kind).toBe("http");
+    expect(bound.$trigger?.kind).toBe("http");
+  });
+
+  test("the same flow object is reachable from HTTP and signal triggers", async () => {
+    const calls: string[] = [];
+    const shared = flow({
+      name: "shared.work",
+      do: (input: { n: number }) => {
+        calls.push(`n=${input.n}`);
+        return { n: input.n * 2 };
+      },
+    });
+
+    const signal = { name: "order-placed", delivery: "once" as const };
+    on(http.post("/work"), shared);
+    on(signal, shared);
+
+    const app = oke({ name: "one-species" });
+    expect(app.bindings).toHaveLength(2);
+    expect(app.bindings[0]?.flow).toBe(shared);
+    expect(app.bindings[1]?.flow).toBe(shared);
+
+    const httpResult = await app.execute(
+      shared,
+      { n: 3 },
+      shared.triggers[0]!,
+    );
+    const signalResults = await app.dispatchSignal("order-placed", { n: 4 });
+
+    expect(httpResult.output).toEqual({ n: 6 });
+    expect(signalResults[0]?.output).toEqual({ n: 8 });
+    expect(calls).toEqual(["n=3", "n=4"]);
+  });
+});
+
+describe("five trigger kinds", () => {
+  test("http · every · signal · table.changed · internal", async () => {
+    const seen: string[] = [];
+
+    const httpFlow = on(
+      http.get("/:code"),
+      flow({
+        name: "t.http",
+        do: ({ code }: { code: string }) => {
+          seen.push(`http:${code}`);
+          return { code };
+        },
+      }),
+    );
+
+    on(
+      every("1h"),
+      flow({
+        name: "t.every",
+        do: () => {
+          seen.push("every");
+        },
+      }),
+    );
+
+    on(
+      { name: "link-clicked", delivery: "once" },
+      flow({
+        name: "t.signal",
+        do: ({ code }: { code: string }) => {
+          seen.push(`signal:${code}`);
+        },
+      }),
+    );
+
+    on(
+      table("orders").changed("status"),
+      flow({
+        name: "t.cdc",
+        do: (p: { before: { status: string }; after: { status: string } }) => {
+          seen.push(`cdc:${p.before.status}->${p.after.status}`);
+        },
+      }),
+    );
+
+    on(
+      internal,
+      flow({
+        name: "t.internal",
+        do: () => {
+          seen.push("internal");
+          return { ok: true };
+        },
+      }),
+    );
+
+    const app = oke({ name: "five" });
+
+    const res = await app.fetch(
+      new Request("http://localhost/abc", { method: "GET" }),
+    );
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ data: { code: "abc" }, error: null });
+
+    await app.dispatchEvery("1h");
+    await app.dispatchSignal("link-clicked", { code: "sa" });
+    await app.dispatchCdc("orders", {
+      before: { status: "open" },
+      after: { status: "paid" },
+    }, "status");
+
+    const internalResult = await app.call("t.internal");
+    expect(internalResult).toEqual({ ok: true });
+
+    expect(seen).toEqual([
+      "http:abc",
+      "every",
+      "signal:sa",
+      "cdc:open->paid",
+      "internal",
+    ]);
+    expect(httpFlow.triggers[0]?.kind).toBe("http");
+  });
+});