indusagi 0.12.32 → 0.12.34

package/dist/types/swarm/kernel/jsonl-log.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `JsonlLog<T>` — an append-only, schema-validated event log.
+ *
+ * Where {@link import("./json-cell").JsonCell} owns a single mutable value,
+ * a log owns an immutable, ever-growing sequence. Entries are stored one JSON
+ * object per line (NDJSON / JSONL): appending is a single `appendFile`, and
+ * reading is a line scan. Immutability is the point — nothing rewrites earlier
+ * lines, which makes appends cheap and concurrent-append-safe without a
+ * read-modify-write transaction.
+ *
+ * Two surfaces:
+ *
+ *   - {@link JsonlLog.append} / {@link JsonlLog.readAll} — the core log.
+ *     Every entry is validated against the cell's zod schema on the way in and
+ *     on the way out, so a corrupt line is caught rather than silently trusted.
+ *   - {@link JsonlLog.threadOf} — a parent-pointer tree helper. When entries
+ *     carry an `id` and an optional `parentId`, this walks the parent chain
+ *     from a leaf back to its root, returning the lineage root→…→leaf. This is
+ *     the conversation/reply-threading pattern, kept as a *pattern* only:
+ *     fresh code, generic over any entry that exposes those two fields.
+ *
+ * The log is deliberately not a mutex-guarded value. POSIX append writes of a
+ * single short line are atomic enough for our append-only use; correctness here
+ * comes from never mutating existing lines, not from locking.
+ */
+import { type ZodType } from "zod";
+/**
+ * The minimal shape an entry must expose to participate in {@link
+ * JsonlLog.threadOf}. The log's own type `T` only needs to be assignable to
+ * this when `threadOf` is used; plain `append`/`readAll` impose no such
+ * constraint.
+ */
+export interface TreeNode {
+    /** This entry's own id. */
+    readonly id: string;
+    /** The id of the entry this one descends from, if any. */
+    readonly parentId?: string | null;
+}
+/**
+ * An append-only JSONL log of `T`, validated against a zod schema.
+ *
+ * Open with {@link JsonlLog.open}; the factory ensures the parent directory
+ * exists so the first {@link append} cannot fail on a missing folder.
+ */
+export declare class JsonlLog<T> {
+    /** Absolute path of the `.jsonl` file backing this log. */
+    readonly path: string;
+    private readonly schema;
+    private constructor();
+    /** Open (or adopt) the log at `path`, ensuring its parent directory exists. */
+    static open<T>(path: string, schema: ZodType<T>): Promise<JsonlLog<T>>;
+    /**
+     * Validate and append one entry as a single JSONL line.
+     *
+     * The entry is run through the schema first; a rejection raises a
+     * `validation` fault before anything touches disk. Returns the entry as
+     * validated/normalized by the schema.
+     */
+    append(entry: T): Promise<T>;
+    /**
+     * Read and validate every entry, in append order.
+     *
+     * A missing file is an empty log, not an error. Blank lines are skipped. A
+     * line that is not valid JSON, or that fails the schema, raises a
+     * `validation` fault naming the offending line number.
+     */
+    readAll(): Promise<T[]>;
+    /**
+     * Resolve the ancestry chain ending at `id`, root-first.
+     *
+     * Reads the whole log, indexes entries by `id`, then walks `parentId`
+     * pointers from the named leaf up to a root (an entry with no resolvable
+     * parent), and returns the chain in root→…→leaf order. A `not_found` fault is
+     * raised if `id` itself is absent; a `conflict` fault is raised if the parent
+     * chain contains a cycle. Entries whose `parentId` points at a missing id are
+     * treated as roots (the chain simply stops there).
+     *
+     * Only available when the log's `T` exposes {@link TreeNode}'s fields.
+     */
+    threadOf(this: JsonlLog<T & TreeNode>, id: string): Promise<(T & TreeNode)[]>;
+}

package/dist/types/swarm/postbox/channel.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `Channel` — a cursor-based mailbox over the swarm kernel.
+ *
+ * Every message sent on a channel is appended to a *single* shared
+ * {@link JsonlLog} of envelopes. There is deliberately **no file-per-recipient**
+ * fan-out: a channel is one ordered stream, and each reader keeps a private
+ * **cursor** — a persisted count of how many log entries it has already
+ * consumed. Polling reads everything past the cursor, hands back the new
+ * envelopes addressed to that reader, and advances the cursor. This makes reads
+ * incremental (O(new lines), not O(whole mailbox)) and makes "have I seen this?"
+ * a per-reader offset rather than a delete-on-read mutation of shared state.
+ *
+ * The class is a thin wrapper over two kernel primitives, exactly as the kernel
+ * mandates:
+ *
+ *   - the **transcript** is a {@link JsonlLog}<{@link Envelope}> — append-only,
+ *     schema-validated, concurrent-append-safe. `send` is one `append`.
+ *   - each reader's **cursor** is a {@link JsonCell} holding a small offset
+ *     record. Advancing it goes through `JsonCell.mutate`, so two pollers for
+ *     the same reader serialize through the cell's lock and can never skip or
+ *     double-count entries.
+ *
+ * The channel never touches `node:fs` locking, temp renames, or coercion
+ * directly — all of that lives in the kernel.
+ *
+ * Three read surfaces:
+ *
+ *   - {@link Channel.send}  — validate + append an envelope to the transcript.
+ *   - {@link Channel.poll}  — return new-since-cursor envelopes for a reader and
+ *     advance that reader's cursor past them.
+ *   - {@link Channel.peek}  — return new-since-cursor envelopes *without*
+ *     advancing the cursor (a non-destructive look-ahead).
+ */
+import { type GuardOptions } from "../kernel";
+import { type Envelope } from "./codecs";
+/**
+ * A cursor-based mailbox shared by every teammate that opens the same `root`.
+ *
+ * Construct with {@link Channel.open}; the factory is async because it opens the
+ * underlying {@link JsonlLog} (which ensures the directory exists).
+ */
+export declare class Channel {
+    /** Absolute root directory backing this channel. */
+    readonly root: string;
+    private readonly transcript;
+    private readonly guard?;
+    private constructor();
+    /**
+     * Open (or adopt) the channel rooted at `root`.
+     *
+     * Opens the shared transcript log; per-reader cursor cells are opened lazily
+     * on first {@link poll}/{@link peek} for that reader. `guard` tunes the lock
+     * acquisition used when advancing a cursor.
+     */
+    static open(root: string, guard?: GuardOptions): Promise<Channel>;
+    /**
+     * Validate `env` and append it to the shared transcript.
+     *
+     * One `JsonlLog.append`: the envelope is schema-checked on the way in (a bad
+     * envelope raises a `validation` fault before disk is touched) and appended as
+     * a single line. Returns the normalized envelope. Sending does not touch any
+     * cursor — delivery is a pull, driven by each reader's `poll`.
+     */
+    send(env: Envelope): Promise<Envelope>;
+    /**
+     * Return the envelopes addressed to `readerId` that it has not yet consumed,
+     * then advance its cursor past *everything scanned* so they are not returned
+     * again.
+     *
+     * The cursor advances to the end of the transcript-as-of-this-read, not just
+     * past the matched envelopes: messages addressed to other readers are skipped
+     * permanently for this reader, which is what keeps polling incremental. The
+     * advance is a single {@link JsonCell.mutate}, so concurrent polls for the
+     * same reader serialize and never double-deliver.
+     */
+    poll(readerId: string): Promise<Envelope[]>;
+    /**
+     * Return the envelopes addressed to `readerId` that it has not yet consumed,
+     * **without** advancing its cursor.
+     *
+     * A non-destructive look-ahead: a subsequent {@link peek} or {@link poll}
+     * sees the same envelopes. Useful for inspecting an inbox without committing
+     * to having processed it.
+     */
+    peek(readerId: string): Promise<Envelope[]>;
+    /** Open the cursor cell for a reader (offset starts at 0 when absent). */
+    private cursorCell;
+}

package/dist/types/swarm/postbox/codecs.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Envelope codecs — a *table* of per-type wire schemas, not an `if`/`switch`
+ * ladder.
+ *
+ * Everything that flows through a {@link import("./channel").Channel} is an
+ * {@link Envelope}: a small, self-describing record carrying a `type` tag and a
+ * `type`-specific `payload`. The four traffic classes the swarm exchanges are:
+ *
+ *   - `task`    — a unit of work handed from one teammate to another.
+ *   - `result`  — the outcome of a previously dispatched task.
+ *   - `note`    — free-form chatter / status with no contractual shape.
+ *   - `control` — a lifecycle signal (pause, resume, drain, …) addressed at a
+ *     reader rather than at the work itself.
+ *
+ * Rather than branch on `type` everywhere a message is read or written, each
+ * class registers a zod schema for its `payload` in a single {@link
+ * CODEC_TABLE}. {@link encode} and {@link decode} dispatch *through the table*
+ * by looking the tag up — adding a fifth class is one table row, not a new
+ * `case` scattered across the codebase. Validation is the schema's job; there
+ * are no hand-rolled `is*` guards anywhere in this module.
+ */
+import { z, type ZodType } from "zod";
+/** The closed set of message classes the postbox understands. */
+export declare const ENVELOPE_TYPES: readonly ["task", "result", "note", "control"];
+/** A single message class tag — the table key and the envelope discriminant. */
+export type EnvelopeType = (typeof ENVELOPE_TYPES)[number];
+/**
+ * The codec table: message-class tag → its codec row. This is the single source
+ * of truth {@link encode}/{@link decode} dispatch through. Declared `satisfies`
+ * a `Record<EnvelopeType, …>` so dropping a class — or adding one without a
+ * row — is a compile error, keeping the table exhaustive over
+ * {@link EnvelopeType}.
+ */
+declare const CODEC_TABLE: {
+    readonly task: {
+        readonly payload: z.ZodObject<{
+            title: z.ZodString;
+            brief: z.ZodString;
+            ticketId: z.ZodOptional<z.ZodString>;
+            priority: z.ZodDefault<z.ZodEnum<{
+                low: "low";
+                high: "high";
+                normal: "normal";
+            }>>;
+        }, z.core.$strip>;
+    };
+    readonly result: {
+        readonly payload: z.ZodObject<{
+            taskId: z.ZodString;
+            status: z.ZodEnum<{
+                error: "error";
+                ok: "ok";
+                skipped: "skipped";
+            }>;
+            summary: z.ZodString;
+            artifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>;
+    };
+    readonly note: {
+        readonly payload: z.ZodObject<{
+            text: z.ZodString;
+        }, z.core.$strip>;
+    };
+    readonly control: {
+        readonly payload: z.ZodObject<{
+            signal: z.ZodEnum<{
+                pause: "pause";
+                resume: "resume";
+                drain: "drain";
+                shutdown: "shutdown";
+            }>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+};
+/** The decoded payload type for a given message class, inferred from its row. */
+export type PayloadOf<K extends EnvelopeType> = z.infer<(typeof CODEC_TABLE)[K]["payload"]>;
+/**
+ * The full wire envelope schema, as a discriminated union over `type`.
+ *
+ * Each branch is built *from the table*, reusing the row's `payload` schema
+ * rather than re-declaring it, so the table stays the single source of truth
+ * for what each class may carry. The branch tuple is written out explicitly so
+ * zod keeps full per-class inference (narrowing on `type` narrows `payload`);
+ * it is checked exhaustive against {@link ENVELOPE_TYPES} just below.
+ */
+declare const envelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"task">;
+    payload: z.ZodObject<{
+        title: z.ZodString;
+        brief: z.ZodString;
+        ticketId: z.ZodOptional<z.ZodString>;
+        priority: z.ZodDefault<z.ZodEnum<{
+            low: "low";
+            high: "high";
+            normal: "normal";
+        }>>;
+    }, z.core.$strip> | z.ZodObject<{
+        taskId: z.ZodString;
+        status: z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+            skipped: "skipped";
+        }>;
+        summary: z.ZodString;
+        artifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip> | z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strip> | z.ZodObject<{
+        signal: z.ZodEnum<{
+            pause: "pause";
+            resume: "resume";
+            drain: "drain";
+            shutdown: "shutdown";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    id: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"result">;
+    payload: z.ZodObject<{
+        title: z.ZodString;
+        brief: z.ZodString;
+        ticketId: z.ZodOptional<z.ZodString>;
+        priority: z.ZodDefault<z.ZodEnum<{
+            low: "low";
+            high: "high";
+            normal: "normal";
+        }>>;
+    }, z.core.$strip> | z.ZodObject<{
+        taskId: z.ZodString;
+        status: z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+            skipped: "skipped";
+        }>;
+        summary: z.ZodString;
+        artifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip> | z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strip> | z.ZodObject<{
+        signal: z.ZodEnum<{
+            pause: "pause";
+            resume: "resume";
+            drain: "drain";
+            shutdown: "shutdown";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    id: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"note">;
+    payload: z.ZodObject<{
+        title: z.ZodString;
+        brief: z.ZodString;
+        ticketId: z.ZodOptional<z.ZodString>;
+        priority: z.ZodDefault<z.ZodEnum<{
+            low: "low";
+            high: "high";
+            normal: "normal";
+        }>>;
+    }, z.core.$strip> | z.ZodObject<{
+        taskId: z.ZodString;
+        status: z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+            skipped: "skipped";
+        }>;
+        summary: z.ZodString;
+        artifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip> | z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strip> | z.ZodObject<{
+        signal: z.ZodEnum<{
+            pause: "pause";
+            resume: "resume";
+            drain: "drain";
+            shutdown: "shutdown";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    id: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"control">;
+    payload: z.ZodObject<{
+        title: z.ZodString;
+        brief: z.ZodString;
+        ticketId: z.ZodOptional<z.ZodString>;
+        priority: z.ZodDefault<z.ZodEnum<{
+            low: "low";
+            high: "high";
+            normal: "normal";
+        }>>;
+    }, z.core.$strip> | z.ZodObject<{
+        taskId: z.ZodString;
+        status: z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+            skipped: "skipped";
+        }>;
+        summary: z.ZodString;
+        artifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip> | z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strip> | z.ZodObject<{
+        signal: z.ZodEnum<{
+            pause: "pause";
+            resume: "resume";
+            drain: "drain";
+            shutdown: "shutdown";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    id: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>], "type">;
+/**
+ * A message as it travels through a channel. The `type` discriminant ties
+ * `payload` to exactly one row of the {@link CODEC_TABLE}; narrowing on `type`
+ * narrows `payload` to that class's shape.
+ */
+export type Envelope = z.infer<typeof envelopeSchema>;
+/** The zod schema for a fully-formed {@link Envelope}. Reused by the channel. */
+export declare const ENVELOPE_SCHEMA: ZodType<Envelope>;
+/**
+ * Validate and serialize an envelope to its one-line wire form.
+ *
+ * Dispatch is table-driven: validation runs the discriminated-union schema,
+ * which selects the branch — and thus the payload row — by the envelope's own
+ * `type`. A malformed envelope raises a `validation` fault rather than emitting
+ * a bad line. Returns compact JSON (no trailing newline; the log adds framing).
+ */
+export declare function encode(env: Envelope): string;
+/**
+ * Parse and validate one wire line back into a typed {@link Envelope}.
+ *
+ * The same table dispatch runs in reverse: JSON is parsed, then the
+ * discriminated union routes by `type` to the right payload row for validation.
+ * Unparseable text or a row mismatch raises a `validation` fault.
+ */
+export declare function decode(line: string): Envelope;
+export {};

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

@@ -0,0 +1,16 @@
+/**
+ * The swarm postbox — public surface.
+ *
+ * A {@link Channel} is the swarm's mailbox: one shared, append-only transcript
+ * of {@link Envelope}s with a per-reader cursor for incremental, non-destructive
+ * delivery. Built strictly on the kernel ({@link import("../kernel").JsonlLog}
+ * for the transcript, {@link import("../kernel").JsonCell} for each cursor) — it
+ * owns no locking or coercion of its own.
+ *
+ * Envelope wire format lives in {@link import("./codecs")}: a *table* of
+ * per-`type` zod codecs that {@link encode}/{@link decode} dispatch through,
+ * with no `if`/`switch` ladder.
+ */
+export { Channel } from "./channel";
+export { encode, decode, ENVELOPE_SCHEMA, ENVELOPE_TYPES, } from "./codecs";
+export type { Envelope, EnvelopeType, PayloadOf } from "./codecs";

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

@@ -0,0 +1,16 @@
+/**
+ * The roster — public surface.
+ *
+ * The team-configuration slice of the swarm: who is on the crew and which model
+ * each member runs on. Two exports, both thin layers over the kernel:
+ *
+ *   - {@link CrewManifest} — the persisted, concurrency-safe crew record
+ *     service, a thin wrapper over {@link import("../kernel").JsonCell}.
+ *   - {@link ModelPolicy} — a small per-role model-selection table the host
+ *     uses to fill in any member that did not pin its own model.
+ *
+ * The type vocabulary callers branch on ({@link CrewMember}, {@link CrewRecord},
+ * {@link MemberDraft}, {@link CrewToolCollection}) is re-exported alongside.
+ */
+export { CrewManifest, ModelPolicy } from "./manifest";
+export type { CrewMember, CrewRecord, MemberDraft, CrewToolCollection, } from "./manifest";

package/dist/types/swarm/roster/manifest.d.ts

@@ -0,0 +1,185 @@
+/**
+ * `CrewManifest` — the team configuration service.
+ *
+ * A crew is the cast of teammate agents the swarm runs with: who is on it, what
+ * role each plays, which model backs them, and which slice of the tool surface
+ * they are trusted with. This module persists that roster and nothing else. It
+ * is a deliberately thin wrapper over {@link JsonCell}: every read and write
+ * goes through the kernel's lock + atomic-publish + schema-validate machinery,
+ * so this file never touches `node:fs` locking, temp-file renames, or
+ * hand-rolled coercion. It only owns the *shape* of a crew and the small set of
+ * roster edits a caller is allowed to make.
+ *
+ * The persisted document is a single {@link CrewRecord}:
+ *
+ *   { crewId; members: CrewMember[]; createdAt }
+ *
+ * Each {@link CrewMember} names a role and optionally pins a model and a tool
+ * collection. A member that leaves its `model` unset defers to the
+ * {@link ModelPolicy} table, which maps a role to its default model — so the
+ * common case ("the reviewer always runs on the heavy model") lives in one
+ * place rather than being repeated at every `addMember` call site.
+ *
+ * Surface:
+ *   - {@link CrewManifest.create}      — mint an empty crew (idempotent-friendly).
+ *   - {@link CrewManifest.addMember}   — enroll a teammate; rejects duplicate ids.
+ *   - {@link CrewManifest.removeMember}— dismiss a teammate by id.
+ *   - {@link CrewManifest.get}         — the whole crew record.
+ *   - {@link CrewManifest.members}     — just the roster array.
+ *
+ * Concurrency, durability, and validation are inherited wholesale from
+ * {@link JsonCell}; the methods here are pure transforms handed to
+ * `cell.mutate`, so two processes editing the same manifest serialize correctly
+ * with zero lost updates.
+ */
+/**
+ * The tool surface a teammate is trusted with, mirroring the named collections
+ * the capabilities layer publishes:
+ *   - `read-only` — observe the workspace and the web; never mutate.
+ *   - `coding`    — read-only plus write/edit/bash/todo/process.
+ *   - `all`       — every registered tool.
+ *
+ * Kept as a local literal union (not an import of the capabilities type) so the
+ * roster schema stays self-contained and zod can validate against it directly;
+ * the three names are intentionally identical to the capabilities collections.
+ */
+export type CrewToolCollection = "read-only" | "coding" | "all";
+/**
+ * One teammate on the crew.
+ *
+ * `id` is the stable handle other services address the member by. `role` is the
+ * functional slot (`planner`, `coder`, `reviewer`, …) the {@link ModelPolicy}
+ * keys off. `model` and `toolCollection` are optional overrides; when omitted,
+ * the resolver and the host's defaults fill them in.
+ */
+export interface CrewMember {
+    /** Stable member handle, unique within a crew. */
+    readonly id: string;
+    /** The functional role this member fills (drives model defaulting). */
+    readonly role: string;
+    /** Pinned model id; when absent, {@link ModelPolicy} supplies one for the role. */
+    readonly model?: string;
+    /** The tool slice this member may call; when absent, the host decides. */
+    readonly toolCollection?: CrewToolCollection;
+}
+/**
+ * The persisted crew document — exactly what lives in the manifest cell.
+ *
+ * `crewId` identifies the crew, `createdAt` is its birth time (epoch ms), and
+ * `members` is the ordered roster. The order is enrollment order and is
+ * preserved across edits.
+ */
+export interface CrewRecord {
+    /** Identifier for this crew. */
+    readonly crewId: string;
+    /** The roster, in enrollment order. */
+    readonly members: readonly CrewMember[];
+    /** Crew creation time, epoch milliseconds. */
+    readonly createdAt: number;
+}
+/** Inputs accepted when enrolling a member; the id may be left for us to mint. */
+export interface MemberDraft {
+    /** Optional explicit id; when omitted a fresh `mbr_…` id is minted. */
+    readonly id?: string;
+    /** The member's role (required — it drives model defaulting). */
+    readonly role: string;
+    /** Optional pinned model id. */
+    readonly model?: string;
+    /** Optional tool collection. */
+    readonly toolCollection?: CrewToolCollection;
+}
+/**
+ * Per-role model selection, expressed as a small lookup table.
+ *
+ * A crew member may pin its own `model`; when it does not, the role decides.
+ * This resolver holds the role→model table and answers {@link ModelPolicy.for}:
+ * "given a member, which model should it actually run on?" The precedence is
+ * deliberate and total:
+ *
+ *   1. an explicit `member.model`, if present;
+ *   2. otherwise the table entry for `member.role`;
+ *   3. otherwise the configured `fallback`.
+ *
+ * The table is data, not branching logic — a new role is a new row, not a new
+ * `if`. Construct one with {@link ModelPolicy.of}.
+ */
+export declare class ModelPolicy {
+    private readonly table;
+    private readonly fallback;
+    private constructor();
+    /**
+     * Build a policy from a `{ role: model }` table and a fallback model used for
+     * any role the table does not name.
+     */
+    static of(table: Readonly<Record<string, string>>, fallback: string): ModelPolicy;
+    /**
+     * The model a `role` resolves to by the table alone (ignoring any per-member
+     * override) — the table entry, or the fallback when the role is unlisted.
+     */
+    modelForRole(role: string): string;
+    /**
+     * The model a concrete member should run on: its own pin if set, else the
+     * role's table entry, else the fallback. Never returns `undefined`.
+     */
+    for(member: Pick<CrewMember, "role" | "model">): string;
+    /** The roles this policy has explicit table rows for. */
+    roles(): string[];
+}
+/**
+ * The team-config service: a typed, concurrency-safe view over one crew
+ * manifest file.
+ *
+ * Open with {@link CrewManifest.open}; the factory wires up the underlying
+ * {@link JsonCell} (which ensures the parent directory exists) and returns a
+ * ready service. Every mutator is a pure transform fed to `cell.mutate`, so
+ * concurrent edits from separate processes serialize through the kernel guard.
+ */
+export declare class CrewManifest {
+    private readonly cell;
+    private constructor();
+    /** Absolute path of the JSON file backing this manifest. */
+    get path(): string;
+    /**
+     * Open (or adopt) the manifest stored at `path`.
+     *
+     * The cell is born "unborn" — {@link get} on a fresh path yields an empty crew
+     * until {@link create} writes a real record. The parent directory is created
+     * by the underlying cell if missing.
+     */
+    static open(path: string): Promise<CrewManifest>;
+    /**
+     * Initialize the crew record.
+     *
+     * Mints a `crew_…` id when `crewId` is omitted, stamps `createdAt` with the
+     * current time, and starts the roster empty. Refuses to overwrite a crew that
+     * already exists (raises a `conflict` fault) so `create` is safe to call
+     * without first checking — call it once when standing a crew up.
+     */
+    create(crewId?: string): Promise<CrewRecord>;
+    /**
+     * Enroll a teammate and return the stored {@link CrewMember}.
+     *
+     * The draft's `id` is used if given, otherwise a fresh `mbr_…` id is minted.
+     * Appends to the end of the roster (enrollment order is preserved). Raises a
+     * `conflict` fault if the crew has not been {@link create}d yet, or if a
+     * member with the same id is already enrolled.
+     *
+     * Note the returned member is read back out of the freshly persisted record,
+     * so the caller always sees exactly what was stored (including the minted id).
+     */
+    addMember(draft: MemberDraft): Promise<CrewMember>;
+    /**
+     * Dismiss the teammate with `id` and return the trimmed roster.
+     *
+     * Raises a `conflict` fault if the crew is unborn, and a `not_found` fault if
+     * no member carries that id. On success the member is dropped and the
+     * remaining order is preserved.
+     */
+    removeMember(id: string): Promise<readonly CrewMember[]>;
+    /** The whole crew record (lock-free read; unborn crews read back empty). */
+    get(): Promise<CrewRecord>;
+    /** Just the roster array, in enrollment order. */
+    members(): Promise<readonly CrewMember[]>;
+    /** Guard a mutation against an uninitialized crew. */
+    private assertBorn;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Golden tests for the swarm coordination layer.
+ *
+ * Every case runs against a real on-disk sandbox under {@link os.tmpdir} so the
+ * kernel's lock + atomic-publish + schema-validate machinery is genuinely
+ * exercised — no stubs for the filesystem, no network, no model. Teammate agents
+ * are *scripted fakes*: each implements the runtime {@link Agent} surface but its
+ * `submit` resolves to a canned snapshot, so a coordination round runs
+ * deterministically.
+ *
+ * Five behaviours are pinned, mirroring the load-bearing guarantees of each layer:
+ *
+ *   1. {@link JsonCell} concurrency — two parallel `mutate()`s serialize with no
+ *      lost update; a bad shape is rejected by the schema.
+ *   2. {@link TicketBoard} — a dep edge gates readiness; claim is atomic;
+ *      completing a dep unblocks its dependent; a cycle is rejected.
+ *   3. {@link Channel} — per-reader cursors deliver each envelope exactly once and
+ *      independently; the codec rejects an unknown type.
+ *   4. {@link Crew.runRound} — two scripted members complete two tickets; the
+ *      activity timeline records the coordination events.
+ *   5. {@link Workspace} — a real git worktree round-trips when git is available;
+ *      the assertion soft-skips (does not fail the suite) when git is absent.
+ */
+export {};