@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/src/loop/context/offload.ts

@@ -0,0 +1,79 @@
+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 { DEFAULT_COMPACTION_CONFIG } from "./compaction.ts";
+import type { OffloadPointer } from "./types.ts";
+
+// Large-output offload (design D10; task 7.2). A tool/step output larger than the configured size is
+// written in FULL to a scratch file under `<root>/.orca/scratch/`, and only a short pointer reference
+// is injected into context in its place — keeping one big payload from blowing the working window.
+// A later step resolves the pointer back to the full payload. Scratch files are content-addressed
+// (sha256 of the payload), so identical outputs dedupe to one file and the path is deterministic.
+
+export interface OffloadOptions {
+  /** Working root; scratch payloads land under `<root>/.orca/scratch/`. */
+  readonly root: string;
+  /** Char length above which an output is offloaded; defaults to the aggressive D10 default. */
+  readonly thresholdChars?: number;
+  /** Injectable filesystem for tests; defaults to the real adapter. */
+  readonly fsTool?: FsTool;
+}
+
+/**
+ * What interception did to one output: either it stayed inline (under threshold), or its body was
+ * offloaded and replaced by a short `ref` string plus the structured `pointer` to resolve later.
+ */
+export type OffloadOutcome =
+  | { readonly offloaded: false; readonly content: string }
+  | { readonly offloaded: true; readonly ref: string; readonly pointer: OffloadPointer };
+
+export interface OffloadStore {
+  /** Route one output: offload + return a pointer ref when oversized, otherwise pass it through. */
+  intercept(output: string): Promise<Result<OffloadOutcome, RuntimeError>>;
+  /** Resolve a pointer back to the full payload written at offload time. */
+  resolve(pointer: OffloadPointer): Promise<Result<string, RuntimeError>>;
+}
+
+/** The short reference injected into context in place of an offloaded payload. */
+export function offloadRef(pointer: OffloadPointer): string {
+  return `⟦offloaded ${String(pointer.bytes)}B → ${offloadDisplayPath(pointer.path)}⟧`;
+}
+
+export function createOffloadStore(options: OffloadOptions): OffloadStore {
+  const { root } = options;
+  const threshold = options.thresholdChars ?? DEFAULT_COMPACTION_CONFIG.offloadThresholdChars;
+  const fsTool = options.fsTool ?? createFsTool();
+
+  return {
+    async intercept(output) {
+      if (output.length <= threshold) {
+        return ok({ offloaded: false, content: output }); // small enough — leave it in context
+      }
+      const hash = createHash("sha256").update(output).digest("hex").slice(0, 16);
+      const path = join(root, ".orca", "scratch", `offload-${hash}.txt`);
+      const written = await fsTool.writeText(path, output, { mode: 0o600 });
+      if (written.isErr()) {
+        return err(written.error);
+      }
+      const pointer: OffloadPointer = { path, bytes: Buffer.byteLength(output, "utf8") };
+      return ok({ offloaded: true, ref: offloadRef(pointer), pointer });
+    },
+
+    async resolve(pointer) {
+      return fsTool.readText(pointer.path);
+    },
+  };
+}
+
+function offloadDisplayPath(path: string): string {
+  const normalized = path.replaceAll("\\", "/");
+  const marker = "/.orca/scratch/";
+  const index = normalized.lastIndexOf(marker);
+  if (index >= 0) {
+    return `.orca/scratch/${normalized.slice(index + marker.length)}`;
+  }
+  return normalized.split("/").at(-1) ?? "offload";
+}

package/src/loop/context/types.ts

@@ -0,0 +1,17 @@
+// Opt-in managed context (design D10): once enabled, staged compaction
+// (mask -> prune -> summarize) by token pressure plus large-output offload to a
+// scratch file with an injected pointer run automatically during the cycle.
+
+/** Tunable thresholds; aggressive defaults apply once managed context is enabled (design D10). */
+export interface CompactionConfig {
+  /** Small working-memory window: token pressure above which staged compaction begins. */
+  readonly workingWindowTokens: number;
+  /** Char length above which an output is offloaded to a scratch file + pointer. */
+  readonly offloadThresholdChars: number;
+}
+
+/** Pointer to an offloaded oversized output; resolves back to the full payload (see ./offload.ts). */
+export interface OffloadPointer {
+  readonly path: string;
+  readonly bytes: number;
+}

package/src/loop/engine/bridge.ts

@@ -0,0 +1,61 @@
+// Boundary bridge (design D2). Effect lives only inside src/loop/engine/**; everything that
+// crosses to the public API or the flow-authoring surface is a neverthrow `Result` or a plain
+// value. This module is the only seam between the two worlds:
+//   - inward   : Result  -> Effect            via result.match(Effect.succeed, Effect.fail)
+//   - outward  : Effect   -> Effect<Result>   via Effect.either + Either.match
+//   - boundary : Effect   -> Promise<Result>  (the single place an engine Effect is *run*)
+// The facade gate (scripts/check-facade-gate.ts) skips src/loop/engine/**, so the Effect
+// types named here never reach a scanned declaration.
+import { Cause, Effect, Either, Exit } from "effect";
+import { err, ok, type Result } from "neverthrow";
+
+/** Inward bridge: lift a neverthrow `Result` into the Effect world. */
+export function fromResult<A, E>(result: Result<A, E>): Effect.Effect<A, E> {
+  return result.match(
+    (value): Effect.Effect<A, E> => Effect.succeed(value),
+    (error): Effect.Effect<A, E> => Effect.fail(error),
+  );
+}
+
+/** Outward bridge: collapse an Effect's typed failure channel into a `Result`, still inside Effect. */
+export function toResult<A, E>(effect: Effect.Effect<A, E>): Effect.Effect<Result<A, E>> {
+  return Effect.either(effect).pipe(
+    Effect.map((either) => Either.match(either, { onLeft: (e) => err(e), onRight: (a) => ok(a) })),
+  );
+}
+
+export interface RunOptions {
+  /** When provided, aborting the signal interrupts the run; the resulting interruption becomes `err`. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Boundary runner — the single place an engine Effect is executed. Returns a `Result` and never
+ * throws an Effect, `Cause`, or interruption: typed failures become `err`, and interruption /
+ * defects are squashed into `err`, so no Effect type or `Cause` escapes the facade.
+ *
+ * Note on cancellation: engine work that wants a graceful `cancelled` outcome wires its own
+ * `AbortSignal` through `runCancellable` (which converts cancellation into a success value).
+ * The `signal` here is the blunt alternative — hard interruption surfaced as `err`.
+ */
+export async function runToResult<A, E>(
+  effect: Effect.Effect<A, E>,
+  options: RunOptions = {},
+): Promise<Result<A, E | Error>> {
+  const exit = await Effect.runPromiseExit(effect, options.signal ? { signal: options.signal } : undefined);
+  return Exit.match(exit, {
+    onSuccess: (value): Result<A, E | Error> => ok(value),
+    onFailure: (cause): Result<A, E | Error> => {
+      const failure = Cause.failureOption(cause);
+      return failure._tag === "Some" ? err(failure.value) : err(causeToError(cause));
+    },
+  });
+}
+
+function causeToError(cause: Cause.Cause<unknown>): Error {
+  if (Cause.isInterruptedOnly(cause)) {
+    return new Error("loop engine run was interrupted");
+  }
+  const squashed = Cause.squash(cause);
+  return squashed instanceof Error ? squashed : new Error(String(squashed));
+}

package/src/loop/engine/index.ts

@@ -0,0 +1,166 @@
+// INTERNAL loop engine — Effect lives here and ONLY here (design D2 facade gate).
+//
+// Public/authoring code never imports this module: src/loop/index.ts does NOT re-export it,
+// and the facade gate (scripts/check-facade-gate.ts) skips src/loop/engine/**. Everything
+// that crosses back out goes through ./bridge.ts as a neverthrow `Result`/plain value.
+//
+// This provides the three primitives the builder (L06) and fan-out / fan-in (L07) lower onto:
+//   1. recurrence with variant-stop    — runRecurrence  (variant floor ∩ ceiling)
+//   2. bounded structured concurrency  — runBranches    (Effect.all { concurrency })
+//   3. structured cancellation         — runCancellable (raceFirst → interrupt in-flight work)
+// plus internal Layer-based DI that resolves the plain FlowContext snapshot captured at the
+// boundary, without exposing any Effect type to the authoring accessors (design D2).
+import { Context, Effect, Layer } from "effect";
+import type { LoopStopReason } from "../builder/types.ts";
+import type { Result } from "neverthrow";
+import { currentFlowContext, type FlowContext } from "../../flow/context.ts";
+import { runToResult } from "./bridge.ts";
+
+export * from "./bridge.ts";
+
+/** Engine-internal outcome; the builder (L06) maps this to the public Effect-free `LoopOutcome`. */
+export interface EngineOutcome<S> {
+  readonly state: S;
+  readonly stopReason: LoopStopReason;
+  readonly iterations: number;
+  readonly measure: number;
+}
+
+/** One loop iteration as an internal Effect; the builder bridges plain step bodies inward via `fromResult`. */
+export type IterationStep<S, R = never> = (state: S, iteration: number) => Effect.Effect<S, Error, R>;
+
+export interface RecurrenceSpec<S, R = never> {
+  readonly initial: S;
+  readonly iterate: IterationStep<S, R>;
+  /** Loop variant (design D3): a measure bounded below that the loop drives toward `floor`. */
+  readonly measure: (state: S) => number;
+  /** Convergence floor; default 0. */
+  readonly floor?: number;
+  /** Iteration-ceiling seatbelt; default unbounded (termination then rests on the variant). */
+  readonly maxIterations?: number;
+}
+
+/**
+ * Drive a stateful loop to convergence. The body runs at least once; the variant measure is
+ * checked after each iteration against the convergence floor and iteration ceiling, so whichever
+ * limit trips first stops the loop — `converged` when the measure won, `ceiling` otherwise.
+ */
+export function runRecurrence<S, R = never>(spec: RecurrenceSpec<S, R>): Effect.Effect<EngineOutcome<S>, Error, R> {
+  const floor = spec.floor ?? 0;
+  const maxIterations =
+    spec.maxIterations === undefined || !Number.isFinite(spec.maxIterations)
+      ? Number.POSITIVE_INFINITY
+      : Math.max(0, Math.floor(spec.maxIterations));
+
+  const recur = (state: S, iterations: number): Effect.Effect<EngineOutcome<S>, Error, R> =>
+    Effect.suspend(() => {
+      const measure = spec.measure(state);
+      if (iterations > 0 && measure <= floor) {
+        return Effect.succeed({ state, stopReason: "converged", iterations, measure });
+      }
+      if (iterations > 0 && iterations >= maxIterations) {
+        return Effect.succeed({ state, stopReason: "ceiling", iterations, measure });
+      }
+      return spec.iterate(state, iterations).pipe(Effect.flatMap((next) => recur(next, iterations + 1)));
+    });
+
+  return recur(spec.initial, 0);
+}
+
+export interface BranchesSpec<A> {
+  readonly branches: readonly Effect.Effect<A, Error>[];
+  /** Bounded fan-out width (design D2/D8: in-process, ~3-10). */
+  readonly concurrency: number;
+}
+
+/**
+ * Run branches with bounded structured concurrency. This is the single concurrency primitive
+ * L07's `fanOut`/`fanIn` build on: interrupting the parent fiber interrupts every in-flight
+ * branch automatically (Effect structured concurrency), which is what `runCancellable` exploits.
+ */
+export function runBranches<A>(spec: BranchesSpec<A>): Effect.Effect<readonly A[], Error> {
+  return Effect.all(spec.branches, { concurrency: spec.concurrency });
+}
+
+/**
+ * Plain-boundary bounded fan-out — the Effect-free seam L07's `fanOut` builds on (design D2). Each
+ * thunk is a self-contained unit of branch work that resolves to its own outcome value and MUST
+ * NOT reject: the caller captures branch success/failure AS DATA so a partial-failure policy can
+ * weigh it, and a thunk that throws anyway is squashed into the outer `err`. Branches run with the
+ * given concurrency cap (`runBranches` ⇒ `Effect.all { concurrency }`); an aborted `signal` hard-
+ * interrupts every in-flight branch via structured concurrency and surfaces as `err`. Returning a
+ * `Result` here means `src/loop/fanout.ts` never names an Effect type — Effect stays in the engine.
+ */
+export async function runBoundedBranches<A>(
+  thunks: readonly (() => Promise<A>)[],
+  concurrency: number,
+  signal?: AbortSignal,
+): Promise<Result<readonly A[], Error>> {
+  const branches = thunks.map((thunk) =>
+    Effect.tryPromise({
+      try: () => thunk(),
+      catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+    }),
+  );
+  return runToResult(runBranches({ branches, concurrency }), signal === undefined ? {} : { signal });
+}
+
+/**
+ * Make a unit of engine work cancellable by an `AbortSignal`. When the signal fires, the cancel
+ * branch wins the race and the `work` fiber — together with any in-flight fan-out children under
+ * it — is interrupted via structured concurrency; `onCancel()` then produces a `cancelled`
+ * outcome (it is a thunk so the caller can fold in last-known/partial state). With no signal the
+ * work runs unchanged.
+ */
+export function runCancellable<S>(
+  work: Effect.Effect<EngineOutcome<S>, Error>,
+  onCancel: () => EngineOutcome<S>,
+  signal?: AbortSignal,
+): Effect.Effect<EngineOutcome<S>, Error> {
+  if (signal === undefined) {
+    return work;
+  }
+  const cancelled = abortEffect(signal).pipe(Effect.map(onCancel));
+  return Effect.raceFirst(work, cancelled);
+}
+
+function abortEffect(signal: AbortSignal): Effect.Effect<undefined> {
+  return Effect.async<undefined>((resume) => {
+    if (signal.aborted) {
+      resume(Effect.succeed(undefined));
+      return;
+    }
+    const onAbort = (): void => {
+      resume(Effect.succeed(undefined));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    return Effect.sync(() => {
+      signal.removeEventListener("abort", onAbort);
+    });
+  });
+}
+
+// --- Internal Layer-based DI (design D2): Layer DI inside the engine, plain accessors outside. ---
+
+/** Engine-internal DI tag carrying the plain `FlowContext` snapshot. */
+export const FlowContextTag = Context.GenericTag<FlowContext>("orca/loop/FlowContext");
+
+/** Build a Layer providing a captured `FlowContext` snapshot to engine effects. */
+export function flowContextLayer(context: FlowContext): Layer.Layer<FlowContext> {
+  return Layer.succeed(FlowContextTag, context);
+}
+
+/**
+ * Provide the ambient flow context to an engine effect. The snapshot is read with the plain,
+ * Effect-free `currentFlowContext()` accessor at the boundary and handed to the engine as a
+ * Layer — so DI is Effect `Layer` internally while the authoring accessors stay plain.
+ */
+export function withAmbientFlowContext<A, E>(effect: Effect.Effect<A, E, FlowContext>): Effect.Effect<A, E> {
+  return Effect.provide(effect, flowContextLayer(currentFlowContext()));
+}
+
+// In-engine equivalents of the plain fs()/git()/llm() authoring accessors, resolved from the
+// Layer. The public accessors stay Effect-free; these never leave src/loop/engine/**.
+export const engineFs = Effect.map(FlowContextTag, (context) => context.fs);
+export const engineGit = Effect.map(FlowContextTag, (context) => context.git);
+export const engineLlm = Effect.map(FlowContextTag, (context) => context.llm);