indusagi 0.12.32 → 0.12.34

package/dist/types/swarm/coordinator.d.ts

@@ -0,0 +1,192 @@
+/**
+ * `Crew` — the swarm coordinator that ties the domain services together.
+ *
+ * A crew is a roster of teammate agents working a shared board of tickets,
+ * talking over one channel, with every coordination step narrated to an activity
+ * log. This module is the conductor that wires those services into a single
+ * driveable object:
+ *
+ *   - a {@link CrewManifest} — who is on the crew (the roster);
+ *   - a {@link TicketBoard}  — the shared, dependency-aware to-do list;
+ *   - a {@link Channel}      — the cursor-based mailbox teammates post on;
+ *   - an {@link ActivityLog} — the append-only transcript of what happened;
+ *   - optionally a {@link Workspace} — git-worktree isolation per teammate.
+ *
+ * The crew owns no `node:fs` locking, temp renames, or coercion of its own — all
+ * of that lives in the kernel under the services. What the coordinator adds is
+ * the *policy*: how ready tickets are matched to idle members, how a teammate
+ * agent is spawned to work a ticket, and how its result is folded back onto the
+ * board and the channel.
+ *
+ * The agent spawner is **injectable**. By default a member is backed by a real
+ * {@link createAgent} bound to the member's model and tool collection; tests pass
+ * a scripted fake agent so a round runs deterministically with no model or
+ * network. The coordinator only depends on the {@link Agent} handle's `submit`
+ * and `snapshot` surface, so a fake need only implement those.
+ *
+ * One round of work — {@link Crew.runRound} — is the heartbeat:
+ *   1. read the board's ready tickets and the idle members;
+ *   2. pair each ready ticket with an idle member;
+ *   3. for each pair: claim the ticket, spawn the member's agent, let it work the
+ *      ticket, post a `result` envelope, complete (or fail) the ticket, and
+ *      narrate every step to the activity log.
+ */
+import type { Agent } from "../runtime";
+import type { CrewMember, MemberDraft } from "./roster";
+import type { Ticket } from "./workboard";
+import type { CrewEvent } from "./telemetry/activity";
+import { Workspace } from "./isolation";
+/**
+ * The injectable factory that brings a teammate agent up for a member.
+ *
+ * The default ({@link defaultSpawnAgent}) builds a real {@link createAgent} bound
+ * to the member's model and {@link toolBox} collection. Tests substitute a
+ * scripted fake whose `submit` resolves to a canned snapshot, exercising the
+ * coordination logic without a model or the network.
+ */
+export type SpawnAgent = (member: CrewMember) => Agent;
+/** What a caller may set when standing up a crew. */
+export interface CrewOptions {
+    /**
+     * Root directory the crew persists under. The manifest, board, channel, and
+     * activity log are all rooted here; the directory is created lazily by the
+     * underlying kernel services.
+     */
+    readonly dir: string;
+    /**
+     * Optional git repository the crew isolates teammates into via a
+     * {@link Workspace}. When present the workspace is constructed (and exposed on
+     * {@link Crew.workspace}) so a host can provision per-teammate worktrees; the
+     * coordinator itself does not force isolation on every round.
+     */
+    readonly baseRepo?: string;
+    /**
+     * Override the agent spawner. Defaults to {@link defaultSpawnAgent} (a real
+     * {@link createAgent}); tests inject a scripted fake.
+     */
+    readonly spawnAgent?: SpawnAgent;
+    /** Injected clock, epoch ms — threaded into the board and activity log for tests. */
+    readonly now?: () => number;
+}
+/**
+ * A point-in-time aggregate of the crew's state, assembled from the board, the
+ * roster, and the activity log. This is what a status pane renders.
+ */
+export interface CrewStatus {
+    /** The crew id from the manifest (empty until {@link Crew.create}). */
+    readonly crewId: string;
+    /** The full roster, in enrollment order. */
+    readonly members: readonly CrewMember[];
+    /** Every ticket on the board, in insertion order. */
+    readonly tickets: readonly Ticket[];
+    /** The ticket ids currently workable (open, all deps done). */
+    readonly ready: readonly string[];
+    /** Count of tickets in each lifecycle state. */
+    readonly counts: {
+        readonly open: number;
+        readonly claimed: number;
+        readonly blocked: number;
+        readonly done: number;
+        readonly failed: number;
+    };
+    /** The full activity timeline, oldest first. */
+    readonly activity: readonly CrewEvent[];
+}
+/**
+ * The swarm coordinator. Construct with {@link createCrew}; it owns the four
+ * domain services and the agent spawner, and exposes the small set of verbs a
+ * host drives a crew through.
+ */
+export declare class Crew {
+    private readonly manifest;
+    private readonly board;
+    private readonly channel;
+    private readonly activity;
+    private readonly spawnAgent;
+    /** The optional git-worktree isolation seam (present only with a `baseRepo`). */
+    readonly workspace: Workspace | null;
+    /** The base repository worktrees are provisioned against, if any. */
+    readonly baseRepo: string | null;
+    private constructor();
+    /**
+     * Stand up a crew rooted at `dir`, wiring up the manifest, board, channel, and
+     * activity log (and a {@link Workspace} when `baseRepo` is given). The crew
+     * record is created eagerly so a fresh crew is immediately usable by
+     * {@link addMember}.
+     */
+    static open(opts: CrewOptions): Promise<Crew>;
+    /**
+     * Enroll a teammate and narrate the spawn to the activity log.
+     *
+     * Delegates the roster edit to the {@link CrewManifest}; on success a
+     * `member_spawned` event is recorded so the transcript reflects the new member.
+     */
+    addMember(draft: MemberDraft): Promise<CrewMember>;
+    /**
+     * Post a unit of work to the board and narrate it.
+     *
+     * Accepts the same draft shape the board's {@link TicketBoard.add} takes
+     * (title, optional body, optional deps); returns the admitted ticket. A
+     * `ticket_posted` event is recorded on success.
+     */
+    postTask(draft: TaskDraft): Promise<Ticket>;
+    /**
+     * Drive one round of work, returning the tickets that reached a terminal state
+     * this round.
+     *
+     * Reads the board's ready tickets and pairs each with an idle member (one
+     * ticket per member per round). For each pair it: claims the ticket for the
+     * member, spawns the member's agent, lets the agent work the ticket, posts a
+     * `result` envelope on the channel, completes (or, on a thrown error, fails)
+     * the ticket, and records the corresponding activity events. A round with no
+     * ready work or no idle members is a no-op that returns an empty list.
+     */
+    runRound(): Promise<RoundOutcome>;
+    /**
+     * Assemble the crew's current state from the board, roster, and activity log.
+     * A pure read across the three services — it takes no locks and mutates
+     * nothing.
+     */
+    status(): Promise<CrewStatus>;
+    /**
+     * Work a single ticket with a single member, end to end.
+     *
+     * Claims the ticket (recording `ticket_claimed`), spawns the member's agent and
+     * runs it over the ticket brief, posts a `result` envelope back to the
+     * coordinator (recording `message_sent`), then completes the ticket (recording
+     * `ticket_done`). Any throw while the agent runs fails the ticket instead
+     * (recording `ticket_failed`), so one bad teammate cannot wedge the round.
+     */
+    private workOne;
+    /** The set of member ids currently holding a claimed (or blocked) ticket. */
+    private busyMemberIds;
+}
+/** The result of one {@link Crew.runRound}: which tickets settled and how. */
+export interface RoundOutcome {
+    /** Tickets that reached `done` this round. */
+    readonly completed: readonly Ticket[];
+    /** Tickets that reached `failed` this round. */
+    readonly failed: readonly Ticket[];
+}
+/** A ticket draft accepted by {@link Crew.postTask} (mirrors the board's draft). */
+export interface TaskDraft {
+    /** Short human-facing summary (required). */
+    readonly title: string;
+    /** Full task description; defaults to empty. */
+    readonly body?: string;
+    /** Ids of tickets that must complete first; defaults to none. */
+    readonly deps?: readonly string[];
+}
+/**
+ * Stand up a crew. The host-facing factory; see {@link CrewOptions} for the knobs
+ * and {@link Crew} for the verbs.
+ */
+export declare function createCrew(opts: CrewOptions): Promise<Crew>;
+/**
+ * The default agent spawner: a real {@link createAgent} bound to the member's
+ * model and tool collection. The member's `toolCollection` (a structural twin of
+ * the capabilities {@link ToolCollection}) is handed straight to {@link toolBox};
+ * an unset collection defaults to `read-only` (the safe floor). The member's
+ * pinned model — or {@link DEFAULT_MEMBER_MODEL} — backs the run.
+ */
+export declare function defaultSpawnAgent(member: CrewMember): Agent;

package/dist/types/swarm/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The swarm layer — public surface.
+ *
+ * The crew/swarm coordination stack, assembled into one import site. The
+ * coordinator ({@link Crew} / {@link createCrew}) ties together four domain
+ * services — each a thin wrapper over the frozen kernel — plus an optional
+ * git-worktree isolation seam:
+ *
+ *   - {@link CrewManifest} — the roster (who is on the crew);
+ *   - {@link TicketBoard}  — the dependency-aware shared task store;
+ *   - {@link Channel}      — the cursor-based mailbox;
+ *   - {@link ActivityLog}  — the append-only coordination transcript;
+ *   - {@link Workspace}    — per-teammate git-worktree isolation.
+ *
+ * The kernel primitives the services are built on ({@link JsonCell},
+ * {@link JsonlLog}, {@link newId}, {@link SwarmFault}) are re-exported too, so a
+ * host that wants to compose its own service over the same foundation can reach
+ * them from one place.
+ */
+export { createCrew, Crew, defaultSpawnAgent } from "./coordinator";
+export type { CrewOptions, CrewStatus, RoundOutcome, TaskDraft, SpawnAgent, } from "./coordinator";
+export { CrewManifest, ModelPolicy } from "./roster";
+export type { CrewMember, CrewRecord, MemberDraft, CrewToolCollection, } from "./roster";
+export { TicketBoard, ticketSchema, ticketStatuses, DepGraph } from "./workboard";
+export type { Ticket, TicketStatus, TicketDraft } from "./workboard";
+export { Channel, encode, decode, ENVELOPE_SCHEMA, ENVELOPE_TYPES } from "./postbox";
+export type { Envelope, EnvelopeType, PayloadOf } from "./postbox";
+export { Workspace, nodeRunner } from "./isolation";
+export type { WorktreeRef, WorktreeEntry, CreateOptions, RemoveOptions, ShellRunner, RunResult, } from "./isolation";
+export { ActivityLog, CREW_EVENT_KINDS } from "./telemetry/activity";
+export type { CrewEvent, CrewEventKind, CrewEventInput } from "./telemetry/activity";
+export { JsonCell, JsonlLog, newId, SwarmFault, swarmFault } from "./kernel";
+export type { GuardOptions, TreeNode, SwarmFaultKind, } from "./kernel";

package/dist/types/swarm/isolation/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The swarm isolation layer — public surface.
+ *
+ * Teammates run in isolated git worktrees so each can mutate its own working
+ * tree and branch without colliding with its peers. This module exposes the
+ * provisioning primitive ({@link Workspace}) and the injectable shell seam it
+ * runs git through ({@link ShellRunner} / {@link nodeRunner}).
+ *
+ * Git failures surface as `isolation`-kind {@link import("../kernel").SwarmFault}s.
+ */
+export { Workspace } from "./worktree";
+export type { WorktreeRef, WorktreeEntry, CreateOptions, RemoveOptions, } from "./worktree";
+export { nodeRunner } from "./runner";
+export type { ShellRunner, RunResult } from "./runner";

package/dist/types/swarm/isolation/runner.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The shell seam the {@link import("./worktree").Workspace} runs git through.
+ *
+ * Worktree provisioning is the one place in the isolation layer that has to
+ * shell out — `git worktree add/list/remove` has no in-process equivalent. To
+ * keep that I/O testable, the {@link Workspace} never reaches for
+ * `node:child_process` itself; it asks for a {@link ShellRunner} and invokes
+ * git through it. Tests inject a hand-written fake runner (asserting on the
+ * exact command strings, returning scripted output and exit codes); production
+ * code injects {@link nodeRunner}, a thin wrapper over `execFile` with the
+ * shell disabled.
+ *
+ * A run never throws on a non-zero exit. The runner always resolves with a
+ * {@link RunResult} carrying `{ stdout, stderr, code }`; it is the
+ * {@link Workspace}'s job to inspect `code` and translate a git failure into a
+ * typed `isolation` {@link import("../kernel").SwarmFault}. This keeps the
+ * seam dumb (it transports bytes and an exit status, nothing more) and the
+ * policy (what counts as a failure, what the error should say) in one place.
+ */
+/** The outcome of one shelled-out command. */
+export interface RunResult {
+    /** Everything the command wrote to stdout, decoded as UTF-8. */
+    readonly stdout: string;
+    /** Everything the command wrote to stderr, decoded as UTF-8. */
+    readonly stderr: string;
+    /**
+     * The process exit code. `0` is success; any other value is a failure the
+     * caller is expected to map onto a fault. A process killed by a signal (no
+     * numeric code) is reported as `null`.
+     */
+    readonly code: number | null;
+}
+/**
+ * A function that runs one command and resolves with its captured output and
+ * exit status. It must *not* reject on a non-zero exit — a failed command is a
+ * resolved {@link RunResult} with a non-zero `code`. Rejection is reserved for
+ * the runner itself being unable to spawn anything (e.g. the binary is
+ * missing), which the {@link Workspace} also folds into an `isolation` fault.
+ */
+export interface ShellRunner {
+    /**
+     * Execute `command` and resolve with its result. `command` is the full
+     * command line as a single string (e.g. `git worktree list --porcelain`).
+     * The optional `cwd` is the directory to run it in; when omitted the runner's
+     * own default applies.
+     */
+    exec(command: string, cwd?: string): Promise<RunResult>;
+}
+/**
+ * The production {@link ShellRunner}: a thin wrapper over `execFile`.
+ *
+ * The command string is split on whitespace into an argv vector and handed to
+ * `execFile` with **no shell** — there is no `/bin/sh -c`, so command
+ * substitution, globbing, pipes, and quoting do not apply. Every argument this
+ * layer ever passes to git is a literal token (a branch name, an absolute
+ * path, a flag), so the naive split is exactly right and the shell-less spawn
+ * removes an injection surface. A non-zero exit resolves (it does not reject):
+ * `execFile`'s error object still carries `stdout`/`stderr`/`code`, which we
+ * forward verbatim.
+ */
+export declare const nodeRunner: ShellRunner;

package/dist/types/swarm/isolation/worktree.d.ts

@@ -0,0 +1,142 @@
+/**
+ * `Workspace` — git-worktree isolation for teammates.
+ *
+ * Each teammate agent in the swarm needs its own checkout to mutate without
+ * trampling its peers: its own working tree, its own branch, its own index.
+ * Git's native answer is a *worktree* — a second working directory linked to
+ * one shared object store. `Workspace` is the thin class that provisions and
+ * reclaims those worktrees on the swarm's behalf.
+ *
+ * It deliberately owns no `node:child_process` of its own. Every git
+ * invocation flows through an injected {@link ShellRunner} (see
+ * {@link import("./runner").ShellRunner}); the default is the real
+ * {@link nodeRunner}, and tests pass a scripted fake that asserts on the exact
+ * git command and returns canned output. This is what makes worktree
+ * provisioning unit-testable without a repo on disk.
+ *
+ * Three verbs:
+ *   - {@link Workspace.create} runs `git worktree add` to materialize a fresh
+ *     working tree on a named branch and reports back its path and branch.
+ *   - {@link Workspace.list} parses `git worktree list --porcelain` into a
+ *     structured inventory of every worktree git knows about.
+ *   - {@link Workspace.remove} runs `git worktree remove` then prunes stale
+ *     administrative metadata, so a reclaimed slot leaves nothing behind.
+ *
+ * Every git failure — a non-zero exit, or the runner being unable to spawn git
+ * at all — is mapped onto a single typed {@link SwarmFault} of kind
+ * `isolation`, with the failing command and git's own stderr preserved in the
+ * message and the underlying error threaded onto `cause`. Callers branch on
+ * `SwarmFault.is(err, "isolation")` rather than scraping git's text.
+ */
+import type { ShellRunner } from "./runner";
+/** The coordinates of a provisioned worktree. */
+export interface WorktreeRef {
+    /** Absolute (or git-reported) path of the linked working directory. */
+    readonly path: string;
+    /**
+     * The branch checked out in that working directory, as a short ref name
+     * (e.g. `feature/login`, not `refs/heads/feature/login`). May be `null` for a
+     * detached-HEAD worktree surfaced by {@link Workspace.list}.
+     */
+    readonly branch: string | null;
+}
+/** One entry parsed from `git worktree list --porcelain`. */
+export interface WorktreeEntry extends WorktreeRef {
+    /** The commit the worktree's HEAD points at, when git reported one. */
+    readonly head: string | null;
+    /** True when the worktree is in detached-HEAD state (no branch). */
+    readonly detached: boolean;
+    /** True when git flagged the worktree as bare. */
+    readonly bare: boolean;
+    /** True when git flagged the worktree as locked. */
+    readonly locked: boolean;
+}
+/** Options accepted by {@link Workspace.create}. */
+export interface CreateOptions {
+    /**
+     * Where to place the new working directory. When omitted, the worktree is
+     * created at a sibling path git derives from the branch name; supply this to
+     * control placement (the usual case for per-teammate scratch dirs).
+     */
+    readonly path?: string;
+    /**
+     * The committish the new branch starts from (a branch, tag, or SHA). When
+     * omitted, git branches from the base repo's current `HEAD`.
+     */
+    readonly startPoint?: string;
+}
+/** Options accepted by {@link Workspace.remove}. */
+export interface RemoveOptions {
+    /**
+     * Pass `--force` to `git worktree remove`, letting git reclaim a worktree
+     * that still has uncommitted changes or a locked administrative file. Off by
+     * default so an accidental remove of dirty work is refused.
+     */
+    readonly force?: boolean;
+}
+/**
+ * Provisions and reclaims git worktrees through an injected shell runner.
+ *
+ * Construct directly; the runner defaults to {@link nodeRunner} so callers that
+ * just want real git can write `new Workspace()`. Pass a fake runner to drive
+ * the class in tests.
+ */
+export declare class Workspace {
+    private readonly runner;
+    /**
+     * @param runner The shell seam every git command is sent through. Defaults to
+     *   the production {@link nodeRunner}; inject a fake in tests.
+     */
+    constructor(runner?: ShellRunner);
+    /**
+     * Materialize a fresh worktree on a new branch.
+     *
+     * Runs `git worktree add [-b <branch>] <path> [<start-point>]` inside
+     * `baseRepo`. The branch is created (git's `-b`), so `branch` must not
+     * already exist as a worktree-checked-out ref. Returns the worktree's
+     * resolved path and branch on success; a non-zero exit (e.g. the branch
+     * already exists, the path is occupied) raises an `isolation` fault.
+     *
+     * @param baseRepo Directory of the repository the worktree links into.
+     * @param branch   Short name of the branch to create and check out.
+     * @param opts     Optional placement and start-point overrides.
+     */
+    create(baseRepo: string, branch: string, opts?: CreateOptions): Promise<WorktreeRef>;
+    /**
+     * Enumerate every worktree git tracks for `baseRepo`.
+     *
+     * Runs `git worktree list --porcelain` and parses the stable, machine-facing
+     * porcelain format into {@link WorktreeEntry} records (the first record is the
+     * main working tree; the rest are linked worktrees). A non-zero exit raises an
+     * `isolation` fault.
+     *
+     * @param baseRepo Directory of the repository to inventory.
+     */
+    list(baseRepo: string): Promise<WorktreeEntry[]>;
+    /**
+     * Remove a linked worktree and prune its leftover metadata.
+     *
+     * Runs `git worktree remove <path>` (with `--force` when
+     * `opts.force`) and then `git worktree prune`, so a removed worktree leaves no
+     * dangling administrative entry under `.git/worktrees`. Either step failing
+     * raises an `isolation` fault; the prune runs from the base repo so it can be
+     * invoked even after the worktree directory itself is gone.
+     *
+     * @param path     The worktree working directory to remove.
+     * @param baseRepo Directory of the owning repository the prune runs in. When
+     *   omitted, both commands run from the worktree `path` (sufficient while the
+     *   worktree still exists; pass `baseRepo` to prune after manual deletion).
+     */
+    remove(path: string, baseRepo?: string, opts?: RemoveOptions): Promise<void>;
+    /**
+     * Run one git command through the injected runner and assert success.
+     *
+     * Resolves with the {@link RunResult} on a zero exit. A non-zero exit, or the
+     * runner rejecting outright (git not spawnable), is folded into one
+     * `isolation` fault carrying the command, git's stderr, and the original
+     * trigger on `cause`.
+     */
+    private git;
+    /** Derive a default sibling worktree path from the branch name. */
+    private defaultPath;
+}

package/dist/types/swarm/kernel/faults.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The swarm fault model.
+ *
+ * Every failure the swarm kernel raises is a {@link SwarmFault} — a real
+ * `Error` subclass carrying a typed, discriminable `kind`. Callers branch on
+ * `fault.kind` (or `instanceof SwarmFault`) instead of matching message
+ * substrings or sniffing for sentinel prefixes. The underlying trigger, when
+ * there is one, is preserved verbatim on the standard `Error.cause` slot so a
+ * stack/cause chain survives across the kernel boundary.
+ *
+ * The `kind` axis is closed and exhaustive:
+ *
+ *   - `lock_timeout` — an exclusive guard could not be acquired before its
+ *     deadline. Transient; the caller may retry or treat it as "skip this poll".
+ *   - `validation`   — a value failed its zod schema on read or write. The
+ *     `cause` is the originating `ZodError` when available.
+ *   - `not_found`    — a cell, ticket, or log entry the caller named does not
+ *     exist.
+ *   - `conflict`     — a guarded mutation lost a race or violated an invariant
+ *     (e.g. claiming an already-claimed ticket).
+ *   - `isolation`    — a worktree / sandbox provisioning step failed.
+ *   - `spawn`        — a teammate agent could not be brought up.
+ *
+ * This file is pure (no I/O) and is the one dependency every other kernel
+ * module is allowed to lean on.
+ */
+/** The closed set of failure classes the swarm kernel can raise. */
+export type SwarmFaultKind = "lock_timeout" | "validation" | "not_found" | "conflict" | "isolation" | "spawn";
+/**
+ * A typed, discriminable failure raised anywhere inside the swarm kernel.
+ *
+ * It is a genuine `Error` (so it throws, stringifies, and carries a stack like
+ * any other), tagged with a {@link SwarmFaultKind} on {@link kind}. The
+ * `discriminated union on kind` the spec asks for is expressed structurally:
+ * narrowing on `fault.kind` narrows the value, and `instanceof SwarmFault`
+ * separates kernel faults from incidental errors.
+ */
+export declare class SwarmFault<K extends SwarmFaultKind = SwarmFaultKind> extends Error {
+    /** Which failure class this fault belongs to. */
+    readonly kind: K;
+    /** Stable error name, useful for logs and `error.name` consumers. */
+    readonly name = "SwarmFault";
+    constructor(kind: K, message: string, cause?: unknown);
+    /** Type guard narrowing an unknown value to a fault of a specific `kind`. */
+    static is<K extends SwarmFaultKind>(value: unknown, kind: K): value is SwarmFault<K>;
+}
+/**
+ * Construct a {@link SwarmFault}. The ergonomic front door — prefer this over
+ * `new SwarmFault(...)` at call sites so the kind/message/cause order stays
+ * uniform across the kernel.
+ */
+export declare function swarmFault<K extends SwarmFaultKind>(kind: K, message: string, cause?: unknown): SwarmFault<K>;

package/dist/types/swarm/kernel/ids.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Sortable unique identifiers for swarm entities.
+ *
+ * Every long-lived thing the swarm names — tickets, envelopes, channels,
+ * leases — gets an id from here. We use ULIDs rather than a monotonic
+ * high-water-mark counter: a ULID is lexicographically sortable by creation
+ * time (its leading 48 bits are a millisecond timestamp), globally unique
+ * without coordination, and needs no separate counter file or lock. That last
+ * property is what lets the workboard skip the bespoke `.highwatermark`
+ * sequence the old design serialized under its own mutex.
+ *
+ * Ids are optionally prefixed (`tkt_…`, `env_…`) so a bare string is
+ * self-describing in logs and on disk. The prefix is cosmetic — it is not part
+ * of the sortable suffix, so two ids with the same prefix still order by time.
+ */
+/**
+ * Mint a fresh, time-sortable unique id.
+ *
+ * With no argument it returns a bare 26-char ULID. With a `prefix` it returns
+ * `<prefix>_<ULID>` — handy for distinguishing id families at a glance. Ids
+ * minted later in wall-clock time sort lexicographically after earlier ones
+ * (within a shared prefix), so a plain string sort doubles as a chronological
+ * sort.
+ */
+export declare function newId(prefix?: string): string;

package/dist/types/swarm/kernel/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The swarm kernel — public surface.
+ *
+ * The frozen, load-bearing foundation the crew/swarm orchestration layer is
+ * built on. Four primitives, deliberately small:
+ *
+ *   - {@link JsonCell} — a lockable, schema-validated, atomically-published
+ *     JSON file. The single abstraction that collapses the lock + atomic-write
+ *     + read/validate trio every higher-level service needs.
+ *   - {@link JsonlLog} — an append-only, schema-validated event log with a
+ *     parent-pointer threading helper.
+ *   - {@link newId} — sortable, coordination-free unique ids (ULID-backed).
+ *   - {@link SwarmFault} — the typed, discriminable error every kernel
+ *     operation raises.
+ *
+ * Domain services (`TicketBoard`, `Channel`, `CrewManifest`, the driver lease)
+ * are expected to be thin wrappers over these — they should never reach for
+ * `node:fs` locking, temp-file renames, or hand-rolled coercion directly.
+ */
+export { JsonCell } from "./json-cell";
+export type { GuardOptions } from "./json-cell";
+export { JsonlLog } from "./jsonl-log";
+export type { TreeNode } from "./jsonl-log";
+export { newId } from "./ids";
+export { SwarmFault, swarmFault } from "./faults";
+export type { SwarmFaultKind } from "./faults";

package/dist/types/swarm/kernel/json-cell.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `JsonCell<T>` — the one abstraction the swarm kernel coordinates through.
+ *
+ * The old crew layer hand-rolled the same three-step dance in four different
+ * files: take a cooperative file lock, read-and-validate the JSON, write it
+ * back atomically. This module collapses that trio into a single, well-tested
+ * class so every domain service (manifest, ticket board, channel, lease) is a
+ * thin wrapper over it rather than another copy of the pattern.
+ *
+ * A cell owns exactly one JSON file plus a zod schema describing its contents:
+ *
+ *   - {@link JsonCell.read} — load the file, validate against the schema, and
+ *     return a typed value. A missing file yields the cell's `initial` value;
+ *     malformed JSON or a schema mismatch raises a `validation` fault.
+ *   - {@link JsonCell.mutate} — the transactional primitive. It takes an
+ *     exclusive lock, reads+validates the current value, applies the caller's
+ *     pure transform, re-validates the result, atomically publishes it
+ *     (temp file → `rename`), and releases the lock — even on error.
+ *
+ * Three deliberate divergences from the prior art:
+ *
+ *   1. **mkdir-lock, not `O_EXCL`.** The mutex is an atomic `mkdir` of a
+ *      `<file>.lockdir` directory. `mkdir` is atomic on POSIX and Windows and
+ *      fails with `EEXIST` when the directory already exists, giving the same
+ *      single-writer guarantee as an exclusive-create lockfile without opening
+ *      a file handle. A small JSON marker is dropped *inside* the lock dir for
+ *      stale detection and debuggability.
+ *   2. **Our own backoff.** Acquisition retries on a jittered exponential
+ *      schedule bounded by a deadline; a lock dir older than `staleMs` is
+ *      forcibly reclaimed (its owner is presumed dead).
+ *   3. **Schema-validated on every crossing.** Reads and writes both run the
+ *      passed zod schema, so a cell can never persist or surface a value that
+ *      violates its type. Validation failures are typed `SwarmFault`s carrying
+ *      the originating `ZodError` as `cause`.
+ */
+import { type ZodType } from "zod";
+/** Tunables for the exclusive-guard acquisition loop. */
+export interface GuardOptions {
+    /** Hard deadline for acquiring the lock, in ms. Default 10_000. */
+    readonly timeoutMs?: number;
+    /** A lock dir older than this (by marker/mtime age) is reclaimed. Default 30_000. */
+    readonly staleMs?: number;
+    /** First backoff sleep, in ms; subsequent sleeps grow exponentially. Default 12. */
+    readonly baseDelayMs?: number;
+    /** Ceiling on any single backoff sleep, in ms. Default 250. */
+    readonly maxDelayMs?: number;
+}
+/**
+ * A lockable, schema-validated, atomically-published JSON file.
+ *
+ * Construct one with {@link JsonCell.open}; never `new` it directly — the
+ * factory is `async` so it can ensure the parent directory exists up front.
+ */
+export declare class JsonCell<T> {
+    /** Absolute path of the JSON file this cell owns. */
+    readonly path: string;
+    private readonly schema;
+    private readonly initial;
+    private readonly guardOpts;
+    private constructor();
+    /**
+     * Open (or adopt) the cell at `path`.
+     *
+     * The `initial` value is what {@link read} returns when the file does not yet
+     * exist; it is validated against `schema` immediately so a bad default fails
+     * loudly at open time rather than on first read. The file itself is *not*
+     * eagerly created — it materializes on the first {@link mutate}. The parent
+     * directory is created if missing.
+     */
+    static open<T>(path: string, schema: ZodType<T>, initial: T, guard?: GuardOptions): Promise<JsonCell<T>>;
+    /**
+     * Load and validate the current value.
+     *
+     * A missing file returns the cell's `initial` value (the cell is born empty,
+     * not broken). Unparseable JSON or a schema mismatch raises a `validation`
+     * fault. Reads are lock-free: thanks to atomic publish, a reader either sees
+     * the previous complete value or the next complete value, never a torn one.
+     */
+    read(): Promise<T>;
+    /**
+     * Transactionally read-modify-write under the exclusive guard.
+     *
+     * Acquires the lock, reads+validates the current value, applies `fn`,
+     * validates the result, atomically publishes it, and releases the lock in a
+     * `finally`. `fn` must be pure and must not perform its own I/O on this cell
+     * (it runs while the lock is held). Returns the freshly persisted value.
+     */
+    mutate(fn: (current: T) => T): Promise<T>;
+    /** Parse + validate file text into a typed value. */
+    private decode;
+    /** Validate an outgoing value and serialize it. */
+    private encode;
+    /** Write to a unique temp sibling then `rename` over the target (atomic). */
+    private publishAtomic;
+    /** Path of this cell's lock directory. */
+    private get lockDir();
+    /**
+     * Run `body` while holding this cell's exclusive guard.
+     *
+     * Acquisition is an atomic `mkdir` of the lock dir; on `EEXIST` we back off
+     * and retry, reclaiming a lock dir that has gone stale. The lock is always
+     * released, including when `body` throws.
+     */
+    private withGuard;
+    /** Acquire the lock dir, backing off and breaking stale locks until the deadline. */
+    private acquire;
+    /** True when the held lock dir is older than `staleMs` (presumed abandoned). */
+    private lockIsStale;
+    /** Forcibly remove a stale lock dir so a fresh holder can take it. */
+    private breakLock;
+    /** Release the lock by removing its directory. Best-effort; never throws. */
+    private release;
+}