@xandreed/core 0.3.0

package/dist/ports/settings-store.port.d.ts

@@ -0,0 +1,85 @@
+import { Context, Option, Schema } from "effect";
+import type { Effect } from "effect";
+declare const EngineSettings_base: Schema.Class<EngineSettings, {
+    model: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
+    codeModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
+    fastModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
+    fallbackModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
+    sandbox: Schema.PropertySignature<":", Option.Option<boolean>, never, "?:", boolean | undefined, true, never>;
+    viMode: Schema.PropertySignature<":", Option.Option<boolean>, never, "?:", boolean | undefined, true, never>;
+    maxAttempts: Schema.PropertySignature<":", Option.Option<number>, never, "?:", number | undefined, true, never>;
+    budgetMillis: Schema.PropertySignature<":", Option.Option<number>, never, "?:", number | undefined, true, never>;
+    /** Selected after the model because the accepted levels are model-specific. */
+    reasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
+    codeReasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
+    fastReasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
+}, Schema.Struct.Encoded<{
+    model: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
+    codeModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
+    fastModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
+    fallbackModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
+    sandbox: Schema.PropertySignature<":", Option.Option<boolean>, never, "?:", boolean | undefined, true, never>;
+    viMode: Schema.PropertySignature<":", Option.Option<boolean>, never, "?:", boolean | undefined, true, never>;
+    maxAttempts: Schema.PropertySignature<":", Option.Option<number>, never, "?:", number | undefined, true, never>;
+    budgetMillis: Schema.PropertySignature<":", Option.Option<number>, never, "?:", number | undefined, true, never>;
+    /** Selected after the model because the accepted levels are model-specific. */
+    reasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
+    codeReasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
+    fastReasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
+}>, never, {
+    readonly model?: Option.Option<string>;
+} & {
+    readonly codeModel?: Option.Option<string>;
+} & {
+    readonly fastModel?: Option.Option<string>;
+} & {
+    readonly fallbackModel?: Option.Option<string>;
+} & {
+    readonly sandbox?: Option.Option<boolean>;
+} & {
+    readonly viMode?: Option.Option<boolean>;
+} & {
+    readonly maxAttempts?: Option.Option<number>;
+} & {
+    readonly budgetMillis?: Option.Option<number>;
+} & {
+    readonly reasoningEffort?: Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">;
+} & {
+    readonly codeReasoningEffort?: Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">;
+} & {
+    readonly fastReasoningEffort?: Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">;
+}, {}, {}>;
+export declare class EngineSettings extends EngineSettings_base {
+}
+declare const SettingsError_base: Schema.TaggedErrorClass<SettingsError, "SettingsError", {
+    readonly _tag: Schema.tag<"SettingsError">;
+} & {
+    message: typeof Schema.String;
+}>;
+export declare class SettingsError extends SettingsError_base {
+}
+/** The three model roles a selection can be persisted under. */
+export type ModelRole = "general" | "code" | "fast";
+/** The non-role keys the keyed setter may write — a closed vocabulary, so a
+ *  typo can never land a dead key in the user's config. */
+export declare const SETTINGS_KEYS: readonly ["fallbackModel", "sandbox", "viMode", "maxAttempts", "budgetMillis", "reasoningEffort", "codeReasoningEffort", "fastReasoningEffort"];
+export type SettingsKey = (typeof SETTINGS_KEYS)[number];
+declare const SettingsStore_base: Context.TagClass<SettingsStore, "@xandreed/core/SettingsStore", {
+    readonly load: Effect.Effect<EngineSettings, SettingsError>;
+    /** Persist one role's model selection (the human's `:model` action);
+     *  `None` clears the role so it falls back to its default again. */
+    readonly setRole: (role: ModelRole, selection: Option.Option<string>) => Effect.Effect<void, SettingsError>;
+    /** Persist one non-role key from its STRING form (the `:settings`
+     *  action): the adapter validates + coerces per key ("true", "3",
+     *  "provider:model") and rejects a value that doesn't parse; `None`
+     *  clears the key. */
+    readonly set: (key: SettingsKey, value: Option.Option<string>) => Effect.Effect<void, SettingsError>;
+}>;
+/**
+ * Read-through settings port. `load` re-reads the backing store on every call
+ * so a value changed mid-session takes effect on the next turn — callers must
+ * not cache the result across turns.
+ */
+export declare class SettingsStore extends SettingsStore_base {
+}
+export {};

package/dist/ports/settings-store.port.js

@@ -0,0 +1,36 @@
+import { Context, Option, Schema } from "effect";
+import { ReasoningEffort } from "../domain/model-call-policy.entity.js";
+const optionField = (schema) => Schema.optionalWith(schema, { as: "Option" }).pipe(Schema.withConstructorDefault(Option.none));
+
+export class EngineSettings extends Schema.Class("EngineSettings")({
+  model: optionField(Schema.String),
+  codeModel: optionField(Schema.String),
+  fastModel: optionField(Schema.String),
+  fallbackModel: optionField(Schema.String),
+  sandbox: optionField(Schema.Boolean),
+  viMode: optionField(Schema.Boolean),
+  maxAttempts: optionField(Schema.Number),
+  budgetMillis: optionField(Schema.Number),
+  reasoningEffort: optionField(ReasoningEffort),
+  codeReasoningEffort: optionField(ReasoningEffort),
+  fastReasoningEffort: optionField(ReasoningEffort)
+}) {
+}
+
+export class SettingsError extends Schema.TaggedError()("SettingsError", {
+  message: Schema.String
+}) {
+}
+export const SETTINGS_KEYS = [
+  "fallbackModel",
+  "sandbox",
+  "viMode",
+  "maxAttempts",
+  "budgetMillis",
+  "reasoningEffort",
+  "codeReasoningEffort",
+  "fastReasoningEffort"
+];
+
+export class SettingsStore extends Context.Tag("@xandreed/core/SettingsStore")() {
+}

package/dist/ports/shell.port.d.ts

@@ -0,0 +1,44 @@
+import { Context, Schema } from "effect";
+import type { Effect } from "effect";
+declare const ShellError_base: Schema.TaggedErrorClass<ShellError, "ShellError", {
+    readonly _tag: Schema.tag<"ShellError">;
+} & {
+    message: typeof Schema.String;
+}>;
+export declare class ShellError extends ShellError_base {
+}
+declare const ShellResult_base: Schema.Class<ShellResult, {
+    stdout: typeof Schema.String;
+    stderr: typeof Schema.String;
+    exitCode: typeof Schema.Number;
+}, Schema.Struct.Encoded<{
+    stdout: typeof Schema.String;
+    stderr: typeof Schema.String;
+    exitCode: typeof Schema.Number;
+}>, never, {
+    readonly stdout: string;
+} & {
+    readonly stderr: string;
+} & {
+    readonly exitCode: number;
+}, {}, {}>;
+export declare class ShellResult extends ShellResult_base {
+}
+declare const Shell_base: Context.TagClass<Shell, "@xandreed/core/Shell", {
+    readonly exec: (command: string, options?: {
+        readonly cwd?: string;
+        readonly timeoutMs?: number;
+        /** BEST-EFFORT live tap: called with each output chunk (stdout and
+         *  stderr) as it arrives, so a long build stops looking dead. Sync
+         *  and advisory — the settled `ShellResult` stays the contract. */
+        readonly onChunk?: (chunk: string) => void;
+    }) => Effect.Effect<ShellResult, ShellError>;
+}>;
+/**
+ * Subprocess execution. A non-zero exit is a RESULT (the model reads the
+ * code + stderr and adapts), never an error — the error channel carries only
+ * spawn/timeout infrastructure failures.
+ */
+export declare class Shell extends Shell_base {
+}
+export {};

package/dist/ports/shell.port.js

@@ -0,0 +1,16 @@
+import { Context, Schema } from "effect";
+
+export class ShellError extends Schema.TaggedError()("ShellError", {
+  message: Schema.String
+}) {
+}
+
+export class ShellResult extends Schema.Class("ShellResult")({
+  stdout: Schema.String,
+  stderr: Schema.String,
+  exitCode: Schema.Number
+}) {
+}
+
+export class Shell extends Context.Tag("@xandreed/core/Shell")() {
+}

package/dist/ports/utility-llm.port.d.ts

@@ -0,0 +1,48 @@
+import { Context, Schema } from "effect";
+import type { Effect } from "effect";
+declare const UtilityError_base: Schema.TaggedErrorClass<UtilityError, "UtilityError", {
+    readonly _tag: Schema.tag<"UtilityError">;
+} & {
+    message: typeof Schema.String;
+}>;
+export declare class UtilityError extends UtilityError_base {
+}
+declare const UtilityCompletion_base: Schema.Class<UtilityCompletion, {
+    text: typeof Schema.String;
+    usage: Schema.Struct<{
+        inputTokens: typeof Schema.Number;
+        outputTokens: typeof Schema.Number;
+        totalTokens: typeof Schema.Number;
+        cacheReadTokens: typeof Schema.Number;
+    }>;
+}, Schema.Struct.Encoded<{
+    text: typeof Schema.String;
+    usage: Schema.Struct<{
+        inputTokens: typeof Schema.Number;
+        outputTokens: typeof Schema.Number;
+        totalTokens: typeof Schema.Number;
+        cacheReadTokens: typeof Schema.Number;
+    }>;
+}>, never, {
+    readonly text: string;
+} & {
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly totalTokens: number;
+        readonly cacheReadTokens: number;
+    };
+}, {}, {}>;
+export declare class UtilityCompletion extends UtilityCompletion_base {
+}
+declare const UtilityLlm_base: Context.TagClass<UtilityLlm, "@xandreed/core/UtilityLlm", {
+    readonly complete: (prompt: string) => Effect.Effect<UtilityCompletion, UtilityError>;
+}>;
+/**
+ * One-shot helper completions OFF the agent loop (session titles, digests,
+ * quick judgments) — backed by the fast-role model so a helper call is cheap
+ * and can never park a turn. Never a substitute for the loop's LanguageModel.
+ */
+export declare class UtilityLlm extends UtilityLlm_base {
+}
+export {};

package/dist/ports/utility-llm.port.js

@@ -0,0 +1,16 @@
+import { Context, Schema } from "effect";
+import { TokenUsage } from "../domain/token-usage.entity.js";
+
+export class UtilityError extends Schema.TaggedError()("UtilityError", {
+  message: Schema.String
+}) {
+}
+
+export class UtilityCompletion extends Schema.Class("UtilityCompletion")({
+  text: Schema.String,
+  usage: TokenUsage
+}) {
+}
+
+export class UtilityLlm extends Context.Tag("@xandreed/core/UtilityLlm")() {
+}

package/dist/session/chassis.d.ts

@@ -0,0 +1,59 @@
+import { Effect, Stream } from "effect";
+import type { ConversationId } from "../domain/message.entity.js";
+/**
+ * The session chassis — the one runtime shape every agent driver needs, over
+ * ONE persisted conversation and an append-only in-memory event ledger:
+ *
+ * - `send` runs a whole agent turn and SERIALIZES: a second send while a
+ *   turn runs waits its turn (drivers coalesce user actions before here).
+ * - `interrupt` stops the in-flight turn's fiber; the ledger survives.
+ * - `subscribe(since)` replays the ledger from a cursor, then streams live,
+ *   deduped by `seq` (the identity) — a client reconnecting mid-turn gets
+ *   each event exactly once.
+ *
+ * Generic over the event vocabulary: a product composes `LoopEvent` with its
+ * own `{ type: ... }` events and hands the chassis a `runTurn` that publishes
+ * through the given sink. Turn failures and defects are CONTAINED: they
+ * become an event (via `onError`), never a dead session.
+ */
+export interface SeqEvent<E> {
+    readonly seq: number;
+    readonly event: E;
+}
+export interface Session<E> {
+    readonly conversationId: ConversationId;
+    /** Run one agent turn (serialized with any in-flight turn). */
+    readonly send: (text: string) => Effect.Effect<void>;
+    /** Interrupt the in-flight turn, if any (idempotent). */
+    readonly interrupt: Effect.Effect<void>;
+    /** The full ledger + the next cursor (subscribe from here for live-only). */
+    readonly state: Effect.Effect<{
+        readonly log: ReadonlyArray<SeqEvent<E>>;
+        readonly cursor: number;
+    }>;
+    /** Every event with `seq >= since`: the replay prefix, then live. */
+    readonly subscribe: (since: number) => Stream.Stream<SeqEvent<E>>;
+    /**
+     * The live-only lossy channel: events `isTransient` claimed (token
+     * deltas). Never ledgered, never replayed, sliding — safe to drop because
+     * every transient fact is restated by a ledgered finalizer. Empty forever
+     * when no `isTransient` was given.
+     */
+    readonly transient: Stream.Stream<E>;
+    /** Interrupt the in-flight turn — the process-exit finalizer. */
+    readonly shutdown: Effect.Effect<void>;
+}
+export declare const makeSession: <E, RS = never>(args: {
+    readonly conversationId: ConversationId;
+    /** Run one turn, publishing events through the sink. Errors/defects are
+     *  contained by the chassis via `onError`. */
+    readonly runTurn: (text: string, publish: (event: E) => Effect.Effect<void>) => Effect.Effect<void, unknown, RS>;
+    /** Map a turn failure into the product's error event. */
+    readonly onError: (message: string) => E;
+    /** The event an INTERRUPTED turn leaves on the ledger — without one the
+     *  ledger simply stops mid-turn and every driver has to say so by hand. */
+    readonly onInterrupt?: () => E;
+    /** Route matching events to the lossy `transient` channel INSTEAD of the
+     *  ledger — a delta flood must never grow the replay log. */
+    readonly isTransient?: (event: E) => boolean;
+}) => Effect.Effect<Session<E>, never, RS>;

package/dist/session/chassis.js

@@ -0,0 +1,27 @@
+import { Effect, Exit, Fiber, Option, PubSub, Ref, Stream } from "effect";
+export const makeSession = (args) => Effect.gen(function* () {
+  const context = yield* Effect.context(), log = yield* Ref.make([]), hub = yield* PubSub.sliding(512), transientHub = yield* PubSub.sliding(128), running = yield* Ref.make(Option.none()), gate = yield* Effect.makeSemaphore(1), publish = (event) => args.isTransient?.(event) === !0 ? PubSub.publish(transientHub, event).pipe(Effect.asVoid) : Ref.modify(log, (entries) => {
+    const entry = { seq: entries.length, event };
+    return [entry, [...entries, entry]];
+  }).pipe(Effect.flatMap((entry) => PubSub.publish(hub, entry)), Effect.asVoid), runContained = (text) => args.runTurn(text, publish).pipe(Effect.provide(context), Effect.catchAll((error) => publish(args.onError(String(error)))), Effect.catchAllDefect((defect) => publish(args.onError(`turn crashed: ${String(defect)}`)))), send = (text) => gate.withPermits(1)(Effect.gen(function* () {
+    const fiber = yield* Effect.fork(runContained(text));
+    yield* Ref.set(running, Option.some(fiber));
+    yield* Fiber.await(fiber).pipe(Effect.asVoid);
+    yield* Ref.set(running, Option.none());
+  })), interrupt = Ref.get(running).pipe(Effect.flatMap(Option.match({
+    onNone: () => Effect.void,
+    onSome: (fiber) => Fiber.interrupt(fiber).pipe(Effect.flatMap((exit) => Exit.isInterrupted(exit) && args.onInterrupt !== void 0 ? publish(args.onInterrupt()) : Effect.void))
+  })));
+  return {
+    conversationId: args.conversationId,
+    send,
+    interrupt,
+    state: Ref.get(log).pipe(Effect.map((entries) => ({ log: entries, cursor: entries.length }))),
+    subscribe: (since) => Stream.unwrapScoped(Effect.gen(function* () {
+      const sub = yield* PubSub.subscribe(hub), entries = yield* Ref.get(log), replay = Stream.fromIterable(entries.filter((e) => e.seq >= since)), seenThrough = entries.length, live = Stream.fromQueue(sub).pipe(Stream.filter((e) => e.seq >= Math.max(since, seenThrough)));
+      return Stream.concat(replay, live);
+    })),
+    transient: Stream.fromPubSub(transientHub),
+    shutdown: interrupt
+  };
+});

package/dist/session/chassis.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spec/SpecDoc.d.ts

@@ -0,0 +1,162 @@
+import { Option, Schema } from "effect";
+/**
+ * The SPEC artifact of the spec-driven pipeline: a rough idea becomes a
+ * SpecDoc (drafted by the refiner agent, refined WITH the human, LOCKED by
+ * the human), and only a locked spec forges. Persisted as
+ * `<workspace>/.efferent/specs/<slug>.md` — git-committable provenance (the
+ * persisted `FactoryRun.spec` ties back to it). See `docs/agents/coder.md`.
+ *
+ * The wire format is markdown: flat YAML-ish frontmatter (the machine half —
+ * the shared `parseFrontmatter` is flat `key: value` only) + strict sections
+ * (the human half): `# Goal`, `## Acceptance`, `## Checks` (`- name: command`
+ * bullets — machine-checkable acceptance, which drivers turn into rank-2
+ * command gates), `## Constraints`, `## Non-goals`. The codec lives in
+ * `usecases/specCodec.ts` and round-trips deterministically.
+ */
+/** Kebab-case spec identity — the file's basename, minted once. */
+export declare const SpecSlug: Schema.brand<Schema.filter<typeof Schema.String>, "SpecSlug">;
+export type SpecSlug = typeof SpecSlug.Type;
+export declare const SpecStatus: Schema.Literal<["draft", "locked"]>;
+export type SpecStatus = typeof SpecStatus.Type;
+declare const SpecCheck_base: Schema.Class<SpecCheck, {
+    name: Schema.filter<typeof Schema.String>;
+    command: typeof Schema.NonEmptyString;
+}, Schema.Struct.Encoded<{
+    name: Schema.filter<typeof Schema.String>;
+    command: typeof Schema.NonEmptyString;
+}>, never, {
+    readonly name: string;
+} & {
+    readonly command: string;
+}, {}, {}>;
+/** A machine-checkable acceptance criterion: a named shell command that must
+ *  exit 0. Drivers append one rank-2 command gate per check (`accept:<name>`). */
+export declare class SpecCheck extends SpecCheck_base {
+}
+declare const SpecLimits_base: Schema.Class<SpecLimits, {
+    maxAttempts: Schema.filter<typeof Schema.Int>;
+    budgetMinutes: typeof Schema.Positive;
+}, Schema.Struct.Encoded<{
+    maxAttempts: Schema.filter<typeof Schema.Int>;
+    budgetMinutes: typeof Schema.Positive;
+}>, never, {
+    readonly maxAttempts: number;
+} & {
+    readonly budgetMinutes: number;
+}, {}, {}>;
+/** Forge-loop bounds (mirrors foundry's ForgeLimits, in human units). */
+export declare class SpecLimits extends SpecLimits_base {
+}
+declare const SpecGates_base: Schema.Class<SpecGates, {
+    config: Schema.optionalWith<typeof Schema.NonEmptyString, {
+        as: "Option";
+    }>;
+    testCommand: Schema.optionalWith<typeof Schema.NonEmptyString, {
+        as: "Option";
+    }>;
+    noTest: Schema.optionalWith<typeof Schema.Boolean, {
+        default: () => false;
+    }>;
+    /** The rank-4 LLM judge — ON by default; a spec opts out with `judge: false`. */
+    judge: Schema.optionalWith<typeof Schema.Boolean, {
+        default: () => true;
+    }>;
+}, Schema.Struct.Encoded<{
+    config: Schema.optionalWith<typeof Schema.NonEmptyString, {
+        as: "Option";
+    }>;
+    testCommand: Schema.optionalWith<typeof Schema.NonEmptyString, {
+        as: "Option";
+    }>;
+    noTest: Schema.optionalWith<typeof Schema.Boolean, {
+        default: () => false;
+    }>;
+    /** The rank-4 LLM judge — ON by default; a spec opts out with `judge: false`. */
+    judge: Schema.optionalWith<typeof Schema.Boolean, {
+        default: () => true;
+    }>;
+}>, never, {
+    readonly config: Option.Option<string>;
+} & {
+    readonly testCommand: Option.Option<string>;
+} & {
+    readonly noTest?: boolean;
+} & {
+    readonly judge?: boolean;
+}, {}, {}>;
+/** Gate-suite selection overrides; absent fields fall through to the driver's
+ *  workspace discovery (precedence: CLI flags > these > discovery). */
+export declare class SpecGates extends SpecGates_base {
+}
+declare const SpecDoc_base: Schema.Class<SpecDoc, {
+    slug: Schema.brand<Schema.filter<typeof Schema.String>, "SpecSlug">;
+    status: Schema.Literal<["draft", "locked"]>;
+    /** ISO timestamps — strings on purpose (stable round-trip, no Date drift). */
+    created: typeof Schema.NonEmptyString;
+    locked: Schema.optionalWith<typeof Schema.NonEmptyString, {
+        as: "Option";
+    }>;
+    /** One imperative paragraph — becomes foundry `Spec.goal`. */
+    goal: typeof Schema.NonEmptyString;
+    /** Rendered verbatim into the implementor brief; also foundry `Spec.acceptance`. */
+    acceptance: Schema.Array$<typeof Schema.NonEmptyString>;
+    /** Hard boundaries for the implementor (brief-only; never enter foundry's Spec). */
+    constraints: Schema.Array$<typeof Schema.NonEmptyString>;
+    /** Explicit scope fences (brief-only). */
+    nonGoals: Schema.Array$<typeof Schema.NonEmptyString>;
+    checks: Schema.Array$<typeof SpecCheck>;
+    limits: typeof SpecLimits;
+    gates: typeof SpecGates;
+}, Schema.Struct.Encoded<{
+    slug: Schema.brand<Schema.filter<typeof Schema.String>, "SpecSlug">;
+    status: Schema.Literal<["draft", "locked"]>;
+    /** ISO timestamps — strings on purpose (stable round-trip, no Date drift). */
+    created: typeof Schema.NonEmptyString;
+    locked: Schema.optionalWith<typeof Schema.NonEmptyString, {
+        as: "Option";
+    }>;
+    /** One imperative paragraph — becomes foundry `Spec.goal`. */
+    goal: typeof Schema.NonEmptyString;
+    /** Rendered verbatim into the implementor brief; also foundry `Spec.acceptance`. */
+    acceptance: Schema.Array$<typeof Schema.NonEmptyString>;
+    /** Hard boundaries for the implementor (brief-only; never enter foundry's Spec). */
+    constraints: Schema.Array$<typeof Schema.NonEmptyString>;
+    /** Explicit scope fences (brief-only). */
+    nonGoals: Schema.Array$<typeof Schema.NonEmptyString>;
+    checks: Schema.Array$<typeof SpecCheck>;
+    limits: typeof SpecLimits;
+    gates: typeof SpecGates;
+}>, never, {
+    readonly status: "draft" | "locked";
+} & {
+    readonly locked: Option.Option<string>;
+} & {
+    readonly slug: string & import("effect/Brand").Brand<"SpecSlug">;
+} & {
+    readonly created: string;
+} & {
+    readonly goal: string;
+} & {
+    readonly limits: SpecLimits;
+} & {
+    readonly gates: SpecGates;
+} & {
+    readonly acceptance: readonly string[];
+} & {
+    readonly constraints: readonly string[];
+} & {
+    readonly nonGoals: readonly string[];
+} & {
+    readonly checks: readonly SpecCheck[];
+}, {}, {}>;
+export declare class SpecDoc extends SpecDoc_base {
+}
+export declare const DEFAULT_SPEC_LIMITS: SpecLimits;
+/**
+ * The prompt section a spec-carrying session renders each turn — the
+ * deterministic successor of the old Directive section: the agent works TO
+ * the acceptance criteria, and deterministic gates (not an LLM judge) decide
+ * whether the work is done.
+ */
+export declare const renderSpecSection: (doc: SpecDoc) => string;
+export {};

package/dist/spec/SpecDoc.js

@@ -0,0 +1,59 @@
+import { Option, Schema } from "effect";
+export const SpecSlug = Schema.String.pipe(Schema.pattern(/^[a-z0-9][a-z0-9-]*$/), Schema.brand("SpecSlug")), SpecStatus = Schema.Literal("draft", "locked");
+
+export class SpecCheck extends Schema.Class("SpecCheck")({
+  name: Schema.String.pipe(Schema.pattern(/^[a-z0-9][a-z0-9-]*$/)),
+  command: Schema.NonEmptyString
+}) {
+}
+
+export class SpecLimits extends Schema.Class("SpecLimits")({
+  maxAttempts: Schema.Int.pipe(Schema.between(1, 10)),
+  budgetMinutes: Schema.Positive
+}) {
+}
+
+export class SpecGates extends Schema.Class("SpecGates")({
+  config: Schema.optionalWith(Schema.NonEmptyString, { as: "Option" }),
+  testCommand: Schema.optionalWith(Schema.NonEmptyString, { as: "Option" }),
+  noTest: Schema.optionalWith(Schema.Boolean, { default: () => !1 }),
+  judge: Schema.optionalWith(Schema.Boolean, { default: () => !0 })
+}) {
+}
+
+export class SpecDoc extends Schema.Class("SpecDoc")({
+  slug: SpecSlug,
+  status: SpecStatus,
+  created: Schema.NonEmptyString,
+  locked: Schema.optionalWith(Schema.NonEmptyString, { as: "Option" }),
+  goal: Schema.NonEmptyString,
+  acceptance: Schema.Array(Schema.NonEmptyString),
+  constraints: Schema.Array(Schema.NonEmptyString),
+  nonGoals: Schema.Array(Schema.NonEmptyString),
+  checks: Schema.Array(SpecCheck),
+  limits: SpecLimits,
+  gates: SpecGates
+}) {
+}
+export const DEFAULT_SPEC_LIMITS = new SpecLimits({ maxAttempts: 3, budgetMinutes: 15 }), renderSpecSection = (doc) => {
+  const bullets = (items) => items.map((item) => `- ${item}`).join(`
+`), acceptance = doc.acceptance.length === 0 ? "" : `
+
+## Acceptance
+${bullets(doc.acceptance)}`, checks = doc.checks.length === 0 ? "" : `
+
+## Machine checks (deterministic gates \u2014 these MUST pass)
+${doc.checks.map((check) => `- ${check.name}: \`${check.command}\``).join(`
+`)}`, constraints = doc.constraints.length === 0 ? "" : `
+
+## Constraints
+${bullets(doc.constraints)}`, nonGoals = doc.nonGoals.length === 0 ? "" : `
+
+## Non-goals
+${bullets(doc.nonGoals)}`;
+  return `# Spec (${doc.status}): ${doc.slug}
+
+${doc.goal}${acceptance}${checks}${constraints}${nonGoals}
+
+Work to this spec. The acceptance criteria are the contract; deterministic gates judge the workspace \u2014 the spec is done when the gates say so, not when the work feels finished.`;
+};

package/dist/spec/codec.d.ts

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+import { SpecDoc } from "./SpecDoc.js";
+import type { SpecSlug } from "./SpecDoc.js";
+declare const SpecDocParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SpecDocParseError";
+} & Readonly<A>;
+/** A SpecDoc file that doesn't decode — names the exact violation. */
+export declare class SpecDocParseError extends SpecDocParseError_base<{
+    readonly message: string;
+}> {
+}
+/**
+ * Decode a SpecDoc file's text. The slug comes from the FILE NAME (the file
+ * owns identity — it is not repeated in the frontmatter). Round-trip law:
+ * `decodeSpecDocText(slug, encodeSpecDocText(doc)) ≡ doc`.
+ */
+export declare const decodeSpecDocText: (slug: string, text: string) => Effect.Effect<SpecDoc, SpecDocParseError>;
+/** Prose bullets are single-line BY GRAMMAR — collapse any whitespace runs
+ *  (incl. newlines) a model slipped in. Safe for prose; NEVER applied to
+ *  check commands (semantics — the propose handler rejects those instead). */
+export declare const normalizeBullet: (text: string) => string;
+/** Deterministic inverse of {@link decodeSpecDocText}: stable key order,
+ *  canonical section order, absent options omitted. Prose bullets are
+ *  normalized to keep the encode inside its own grammar (round-trip law). */
+export declare const encodeSpecDocText: (doc: SpecDoc) => string;
+/** Deterministic kebab slug from a goal/idea (mint once; the file owns it). */
+export declare const specSlug: (goal: string) => SpecSlug;
+/** First-wins collision suffixing over an existing-name predicate. */
+export declare const uniqueSlug: (base: SpecSlug, taken: (slug: string) => boolean) => SpecSlug;
+export {};