indusagi 0.12.32 → 0.12.33

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;
+}

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";