@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/src/loop/serve.ts

@@ -0,0 +1,307 @@
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { err, ok, type Result } from "neverthrow";
+
+import { ioFailed, type RuntimeError } from "../model/index.ts";
+import type { LoopOutcome, LoopRunError } from "./builder/index.ts";
+import { createLoopChildSpec, spawnLoopChild, type ChildHandle, type ChildSpawner } from "./firing.ts";
+import type { Sink, Source } from "./io/index.ts";
+
+export {
+  exitCodeForRun,
+  exitCodeForStop,
+} from "./firing.ts";
+export type {
+  ChildHandle,
+  ChildSpec,
+  ChildSpawner,
+} from "./firing.ts";
+
+// L11 loop distribution surface (spec distribution; design D8). A LoopDefinition binds a loop's
+// trigger Source and output Sink to a one-shot runner; `defineLoop` is the authoring front door.
+// Discovery is import-only (registers, never fires), `serve` is a thin supervisor that spawns an
+// ephemeral child per trigger firing. No Effect type appears here (facade gate, design D2).
+
+/** A registered loop: its trigger `Source`, output `Sink`, and a one-shot runner. */
+export interface LoopDefinition<E = unknown, A = unknown, S = unknown> {
+  readonly name: string;
+  readonly source: Source<E>;
+  readonly sink: Sink<A>;
+  /** Run the loop once for a trigger event, emit its output to the sink, resolve to the stop outcome. */
+  run(event: E): Promise<Result<LoopOutcome<S>, LoopRunError>>;
+}
+
+/** What one loop firing produces: the stop outcome plus the value to emit to the sink. */
+export interface LoopEmission<A = unknown, S = unknown> {
+  readonly outcome: LoopOutcome<S>;
+  readonly output: A;
+}
+
+/** Authoring config for `defineLoop`. `onTrigger` runs the loop; the sink emit is wired for you. */
+export interface LoopConfig<E = unknown, A = unknown, S = unknown> {
+  readonly name: string;
+  readonly source: Source<E>;
+  readonly sink: Sink<A>;
+  /** Execute the loop once for `event`; return the stop outcome and the value to emit. */
+  readonly onTrigger: (event: E) => Promise<Result<LoopEmission<A, S>, LoopRunError>>;
+}
+
+/**
+ * Package a loop with its Source + Sink into a discoverable definition. A loop module exports the
+ * result; importing the module only registers it (no Source fires, no backend runs, no Sink emits)
+ * so `orcats loops` discovery is side-effect-free. `run` folds the sink emit into one Result so the
+ * CLI and the `serve` child share identical output behavior.
+ */
+export function defineLoop<E = unknown, A = unknown, S = unknown>(
+  config: LoopConfig<E, A, S>,
+): LoopDefinition<E, A, S> {
+  return {
+    name: config.name,
+    source: config.source,
+    sink: config.sink,
+    async run(event) {
+      const fired = await config.onTrigger(event);
+      if (fired.isErr()) {
+        return err(fired.error);
+      }
+      const emitted = await config.sink.emit(fired.value.output);
+      if (emitted.isErr()) {
+        return err(emitted.error);
+      }
+      return ok(fired.value.outcome);
+    },
+  };
+}
+
+/** Structural guard: an object with a name, a `run`, and Source/Sink-shaped seams. */
+export function isLoopDefinition(value: unknown): value is LoopDefinition {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate.name === "string" &&
+    typeof candidate.run === "function" &&
+    isSeam(candidate.source) &&
+    isSeam(candidate.sink)
+  );
+}
+
+function isSeam(value: unknown): boolean {
+  return typeof value === "object" && value !== null && typeof (value as { kind?: unknown }).kind === "string";
+}
+
+// --- Discovery: import loop modules and collect their exported definitions (import-only). ---
+
+/** Imports a module by absolute path, returning its export namespace. */
+export type ModuleImporter = (absolutePath: string) => Promise<Record<string, unknown>>;
+/** Lists candidate loop-module files under a directory. */
+export type FileLister = (dir: string) => Promise<string[]>;
+
+const defaultLister: FileLister = async (dir) => {
+  if (!existsSync(dir)) {
+    return [];
+  }
+  const glob = new Bun.Glob("**/*.ts");
+  const files: string[] = [];
+  for await (const entry of glob.scan({ cwd: dir, absolute: true })) {
+    files.push(entry);
+  }
+  return files;
+};
+
+const defaultImporter: ModuleImporter = async (absolutePath) => {
+  const module: unknown = await import(pathToFileURL(absolutePath).href);
+  return module as Record<string, unknown>;
+};
+
+/** Scan imported module namespaces for exported LoopDefinitions, keyed by loop name. */
+export function collectDefinitions(modules: Iterable<Record<string, unknown>>): Map<string, LoopDefinition> {
+  const found = new Map<string, LoopDefinition>();
+  for (const module of modules) {
+    for (const exported of Object.values(module)) {
+      if (isLoopDefinition(exported)) {
+        found.set(exported.name, exported);
+      }
+    }
+  }
+  return found;
+}
+
+export interface DiscoverOptions {
+  readonly dir: string;
+  readonly list?: FileLister;
+  readonly import?: ModuleImporter;
+}
+
+/**
+ * Discover loop definitions under `dir` (by convention `.orca/loops`, holding export-only loop
+ * modules — NOT self-executing flow scripts). Import-only: constructing a definition via
+ * `defineLoop` fires no Source, backend, or Sink, so discovery has no side effects.
+ */
+export async function discoverLoops(
+  options: DiscoverOptions,
+): Promise<Result<Map<string, LoopDefinition>, RuntimeError>> {
+  const list = options.list ?? defaultLister;
+  const load = options.import ?? defaultImporter;
+  let files: string[];
+  try {
+    files = await list(options.dir);
+  } catch (error) {
+    return err(ioFailed("source", "discover", String(error)));
+  }
+  const modules: Record<string, unknown>[] = [];
+  for (const file of files) {
+    try {
+      modules.push(await load(file));
+    } catch (error) {
+      return err(ioFailed("source", "discover", `failed to import ${file}: ${String(error)}`));
+    }
+  }
+  return ok(collectDefinitions(modules));
+}
+
+export interface LoadOptions {
+  readonly cwd: string;
+  readonly import?: ModuleImporter;
+  readonly list?: FileLister;
+  /** Directory scanned when the target is a registered name; default `<cwd>/.orca/loops`. */
+  readonly loopsDir?: string;
+}
+
+/**
+ * Resolve a loop by module path OR registered name (spec distribution). A path imports that one
+ * module; a name discovers the `.orca/loops` directory and looks it up. Import-only: no firing.
+ */
+export async function loadDefinition(
+  target: string,
+  options: LoadOptions,
+): Promise<Result<LoopDefinition, RuntimeError>> {
+  const load = options.import ?? defaultImporter;
+  const asPath = isAbsolute(target) ? target : resolve(options.cwd, target);
+  if (existsSync(asPath) && statSync(asPath).isFile()) {
+    let module: Record<string, unknown>;
+    try {
+      module = await load(asPath);
+    } catch (error) {
+      return err(ioFailed("source", "load", `failed to import ${target}: ${String(error)}`));
+    }
+    const picked = pickDefinition(module, collectDefinitions([module]));
+    if (picked === undefined) {
+      return err(ioFailed("source", "load", `no loop definition exported from ${target}`));
+    }
+    return ok(picked);
+  }
+  const dir = options.loopsDir ?? join(options.cwd, ".orca", "loops");
+  const discovered = await discoverLoops({
+    dir,
+    ...(options.import === undefined ? {} : { import: options.import }),
+    ...(options.list === undefined ? {} : { list: options.list }),
+  });
+  if (discovered.isErr()) {
+    return err(discovered.error);
+  }
+  const found = discovered.value.get(target);
+  if (found === undefined) {
+    return err(ioFailed("source", "load", `no loop named "${target}" found in ${dir}`));
+  }
+  return ok(found);
+}
+
+/** A `default` export wins; otherwise a sole named definition; ambiguous (>1, no default) → none. */
+function pickDefinition(
+  module: Record<string, unknown>,
+  defs: Map<string, LoopDefinition>,
+): LoopDefinition | undefined {
+  const fallback = module.default;
+  if (isLoopDefinition(fallback)) {
+    return fallback;
+  }
+  if (defs.size === 1) {
+    return [...defs.values()].at(0);
+  }
+  return undefined;
+}
+
+// --- Listing: project definitions to rows; reads metadata only, fires nothing. ---
+
+export interface LoopListing {
+  readonly name: string;
+  readonly source: string;
+  readonly sink: string;
+}
+
+/** Project loop definitions to listing rows — reads `kind` metadata only, never `start`/`emit`/`run`. */
+export function listLoops(definitions: Iterable<LoopDefinition>): LoopListing[] {
+  const rows: LoopListing[] = [];
+  for (const definition of definitions) {
+    rows.push({ name: definition.name, source: definition.source.kind, sink: definition.sink.kind });
+  }
+  return rows;
+}
+
+/** Render the loop listing as text for `orcats loops`. */
+export function formatLoopListing(rows: readonly LoopListing[]): string {
+  if (rows.length === 0) {
+    return "No loops defined. Add an export-only module under .orca/loops that exports a defineLoop(...) result.";
+  }
+  return rows.map((row) => `${row.name}\tsource=${row.source}\tsink=${row.sink}`).join("\n");
+}
+
+// --- serve: a thin long-lived supervisor that spawns an ephemeral child per trigger firing (D8). ---
+
+export interface ServeOptions {
+  /** Spawn an ephemeral child per firing; default re-invokes `orcats run <loop>` as a subprocess. */
+  readonly spawn?: ChildSpawner;
+  /** What the child runs: a loop name or path. Default: the definition name. */
+  readonly loopRef?: string;
+}
+
+/** Live supervisor handle: owns the trigger and the in-flight children, not the loop runs. */
+export interface Supervisor {
+  /** In-flight child handles, one per firing not yet exited. */
+  children(): readonly ChildHandle[];
+  /** Stop the trigger and `SIGKILL` any in-flight children. */
+  stop(): Promise<Result<void, RuntimeError>>;
+}
+
+/**
+ * The thin `serve` supervisor (design D8): a long-lived process owning ONLY the trigger. Each
+ * firing spawns an ephemeral child that runs the loop and exits — the loop never runs in the
+ * supervisor, so one loop's crash/OOM cannot take down the supervisor or its siblings, and a
+ * runaway child is killable at the OS level. Cross-loop coordination is via the shared manifest
+ * store (L05), not shared process memory.
+ */
+export async function serve(
+  definition: LoopDefinition,
+  options: ServeOptions = {},
+): Promise<Result<Supervisor, RuntimeError>> {
+  const spawnChild = options.spawn ?? spawnLoopChild;
+  const loopRef = options.loopRef ?? definition.name;
+  const children = new Set<ChildHandle>();
+
+  const started = await definition.source.start((event: unknown) => {
+    const child = spawnChild(createLoopChildSpec(loopRef, event));
+    children.add(child);
+    const forget = (): void => {
+      children.delete(child);
+    };
+    void child.exited.then(forget, forget);
+  });
+  if (started.isErr()) {
+    return err(started.error);
+  }
+  const subscription = started.value;
+
+  return ok({
+    children: () => [...children],
+    async stop() {
+      for (const child of children) {
+        child.kill("SIGKILL");
+      }
+      children.clear();
+      return subscription.stop();
+    },
+  });
+}

package/src/loop/state/index.ts

@@ -0,0 +1,4 @@
+export * from "./port.ts";
+export * from "./manifest.ts";
+export * from "./snapshot.ts";
+export * from "./sqlite.ts";

package/src/loop/state/manifest.ts

@@ -0,0 +1,56 @@
+import { type Result } from "neverthrow";
+import { z } from "zod";
+import { parseStructuredOutput, type RuntimeError } from "../../model/index.ts";
+
+// The loop manifest is runtime state (design D4) — the "Ralph" pattern. It is the
+// single spine for progress, the termination variant, and the monitor stream, all
+// projected from the same pass-flags. It does NOT replace `.orca/plan-<hash>.md`,
+// which remains the human plan artifact recovered by the plans-and-review APIs.
+
+/** A single atomic subtask; `passes` is the progress flag flipped by the loop. */
+export const ManifestTaskSchema = z.object({
+  id: z.string(),
+  passes: z.boolean()
+});
+
+/** Typed loop manifest — the single progress/variant/monitor spine. */
+export const TaskManifestSchema = z.object({
+  tasks: z.array(ManifestTaskSchema)
+});
+
+export type ManifestTask = z.infer<typeof ManifestTaskSchema>;
+export type TaskManifest = z.infer<typeof TaskManifestSchema>;
+
+/** Validate raw state against the manifest schema each cycle; a validation
+ * failure surfaces as `err(RuntimeError)` (`StructuredOutputValidationFailed`). */
+export function parseManifest(raw: unknown): Result<TaskManifest, RuntimeError> {
+  return parseStructuredOutput(TaskManifestSchema, raw).map((parsed) => parsed.value);
+}
+
+/** The single shared projection: count of tasks not yet passing. The termination
+ * variant, reported progress, and the monitor signal all read this one value, so
+ * they always reflect the same number. */
+export function measure(manifest: TaskManifest): number {
+  return manifest.tasks.reduce((pending, task) => (task.passes ? pending : pending + 1), 0);
+}
+
+export interface ManifestProgress {
+  readonly total: number;
+  readonly passed: number;
+  readonly pending: number;
+  /** Fraction of tasks passing in `[0, 1]`; `1` for an empty manifest. */
+  readonly ratio: number;
+}
+
+/** Progress report derived from {@link measure} so it cannot drift from the variant. */
+export function progress(manifest: TaskManifest): ManifestProgress {
+  const total = manifest.tasks.length;
+  const pending = measure(manifest);
+  const passed = total - pending;
+  return { total, passed, pending, ratio: total === 0 ? 1 : passed / total };
+}
+
+/** Termination predicate: the manifest is complete when nothing is pending. */
+export function isComplete(manifest: TaskManifest): boolean {
+  return measure(manifest) === 0;
+}

package/src/loop/state/port.ts

@@ -0,0 +1,43 @@
+import type { Result } from "neverthrow";
+import type { RuntimeError } from "../../model/index.ts";
+import type { TaskManifest } from "./manifest.ts";
+
+// The StateStore port is the single seam for loop state (design D4). Loop code
+// targets this interface; swapping the adapter (snapshot -> sqlite -> ...) never
+// changes the loop definition. branch/merge/history are first-class operations:
+// fan-out = branch, fan-in = merge, monitoring = history. Store-backed fan-out
+// additionally requires BranchWritableStateStore for non-history branch saves.
+
+/** Content hash identifying a per-cycle state snapshot. */
+export type StateHash = string;
+
+/** Service-free-by-default adapters (design D4). `dbos`/`dolt` stay deferred but
+ * the port shape keeps them expressible. */
+export type StateAdapterId = "snapshot" | "sqlite";
+
+/** Fan-in merge: the ONLY place branch state combines (event-sourced/reduce,
+ * never shared-mutable). */
+export type StateReducer<S> = (states: readonly S[]) => S;
+
+/**
+ * StateStore port — `load / checkpoint / branch / merge / history`, all Result-typed
+ * over `RuntimeError`. Default state is the {@link TaskManifest}.
+ */
+export interface StateStore<S = TaskManifest> {
+  /** Read a snapshot by hash, or the most recent checkpoint when omitted. */
+  load(hash?: StateHash): Promise<Result<S, RuntimeError>>;
+  /** Validate and persist a cycle's state, returning its content hash. */
+  checkpoint(state: S): Promise<Result<StateHash, RuntimeError>>;
+  /** Fan-out: copy a snapshot into an isolated branch handle. */
+  branch(from: StateHash): Promise<Result<StateHash, RuntimeError>>;
+  /** Fan-in: combine branch snapshots through the reducer (the only merge point). */
+  merge(branches: readonly StateHash[], reducer: StateReducer<S>): Promise<Result<S, RuntimeError>>;
+  /** Monitoring: the ordered hashes of prior cycle snapshots. */
+  history(): Promise<Result<readonly StateHash[], RuntimeError>>;
+}
+
+/** Store capability required only by store-backed fan-out branch result persistence. */
+export interface BranchWritableStateStore<S = TaskManifest> extends StateStore<S> {
+  /** Persist isolated branch state without appending to the cycle history. */
+  saveBranch(branch: StateHash, state: S): Promise<Result<StateHash, RuntimeError>>;
+}

package/src/loop/state/snapshot.ts

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { err, ok, type Result } from "neverthrow";
+import type { RuntimeError } from "../../model/index.ts";
+import { createFsTool, type FsTool } from "../../tools/index.ts";
+import { parseManifest, type TaskManifest } from "./manifest.ts";
+import type { BranchWritableStateStore, StateHash, StateReducer } from "./port.ts";
+
+// `snapshot` is the zero-config default adapter (design D4): the whole manifest is
+// written as JSON to `.orca/state-<hash>.json` per cycle — human-readable,
+// git-diffable, zero deps. `branch` = copy-on-fanout, `saveBranch` = non-history
+// branch result write, `merge` = reducer (the only merge point), `history` = the
+// in-process cycle stream. The snapshot adapter
+// trades durability for simplicity: an interrupt loses the current cycle, so the
+// monitor history lives in memory; finer per-step resume is the `sqlite` adapter.
+
+export interface SnapshotStoreOptions {
+  /** Repo/working root; snapshots land under `<root>/.orca/`. */
+  readonly root: string;
+  /** Injectable filesystem for tests; defaults to the real adapter. */
+  readonly fsTool?: FsTool;
+}
+
+/** Content hash of a manifest — canonical JSON so equal manifests share a file. */
+export function stateHash(manifest: TaskManifest): StateHash {
+  const canonical = JSON.stringify({
+    tasks: manifest.tasks.map(({ id, passes }) => ({ id, passes }))
+  });
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 12);
+}
+
+/** Per-cycle snapshot path: `<root>/.orca/state-<hash>.json`. */
+export function statePath(root: string, hash: StateHash): string {
+  return join(root, ".orca", `state-${hash}.json`);
+}
+
+export function createSnapshotStore(options: SnapshotStoreOptions): BranchWritableStateStore {
+  const { root } = options;
+  const fsTool = options.fsTool ?? createFsTool();
+  const cycles: StateHash[] = [];
+  let branchNonce = 0;
+
+  async function read(hash: StateHash): Promise<Result<TaskManifest, RuntimeError>> {
+    const text = await fsTool.readText(statePath(root, hash));
+    if (text.isErr()) {
+      return err(text.error);
+    }
+    let raw: unknown;
+    try {
+      raw = JSON.parse(text.value);
+    } catch (error) {
+      return err({ _tag: "FileSystemError", path: statePath(root, hash), message: String(error) });
+    }
+    return parseManifest(raw);
+  }
+
+  async function write(manifest: TaskManifest): Promise<Result<StateHash, RuntimeError>> {
+    const hash = stateHash(manifest);
+    const written = await fsTool.writeText(statePath(root, hash), `${JSON.stringify(manifest, null, 2)}\n`);
+    if (written.isErr()) {
+      return err(written.error);
+    }
+    return ok(hash);
+  }
+
+  return {
+    async load(hash) {
+      const target = hash ?? cycles.at(-1);
+      if (target === undefined) {
+        return err({ _tag: "FileSystemError", path: join(root, ".orca"), message: "no checkpoint to load" });
+      }
+      return read(target);
+    },
+
+    async checkpoint(state) {
+      const validated = parseManifest(state);
+      if (validated.isErr()) {
+        return err(validated.error);
+      }
+      const written = await write(validated.value);
+      if (written.isErr()) {
+        return err(written.error);
+      }
+      cycles.push(written.value);
+      return ok(written.value);
+    },
+
+    async branch(from) {
+      const source = await read(from);
+      if (source.isErr()) {
+        return err(source.error);
+      }
+      const hash = createHash("sha256").update(`${from}:${String(branchNonce++)}`).digest("hex").slice(0, 12);
+      const written = await fsTool.writeText(statePath(root, hash), `${JSON.stringify(source.value, null, 2)}\n`);
+      if (written.isErr()) {
+        return err(written.error);
+      }
+      return ok(hash);
+    },
+
+    async saveBranch(branch, state) {
+      const source = await read(branch);
+      if (source.isErr()) {
+        return err(source.error);
+      }
+      const validated = parseManifest(state);
+      if (validated.isErr()) {
+        return err(validated.error);
+      }
+      return write(validated.value);
+    },
+
+    async merge(branches, reducer: StateReducer<TaskManifest>) {
+      const states: TaskManifest[] = [];
+      for (const hash of branches) {
+        const loaded = await read(hash);
+        if (loaded.isErr()) {
+          return err(loaded.error);
+        }
+        states.push(loaded.value);
+      }
+      return parseManifest(reducer(states));
+    },
+
+    history() {
+      return Promise.resolve(ok([...cycles]));
+    }
+  };
+}