indusagi 0.12.32 → 0.12.33

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

package/dist/types/swarm/telemetry/activity.d.ts

@@ -0,0 +1,143 @@
+/**
+ * `ActivityLog` — the crew's append-only transcript of what happened, when.
+ *
+ * Where the {@link import("../workboard").TicketBoard} holds the *current* state
+ * of the work and the {@link import("../postbox").Channel} carries the *messages*
+ * between teammates, the activity log is the third leg: an immutable, ordered
+ * record of the coordination *events* themselves — a member was spawned, a ticket
+ * was claimed or completed, a result envelope was sent. It is what a transcript
+ * viewer replays and what an audit reads back; nothing in the crew depends on it
+ * for correctness, so it is a pure observer.
+ *
+ * It is a deliberately thin wrapper over the kernel's {@link JsonlLog}: every
+ * event is one schema-validated append, and the timeline is one validated read.
+ * The log never touches `node:fs` locking, temp renames, or coercion — that all
+ * lives in the kernel. Events are a small, table-like discriminated union keyed
+ * by `kind`, validated by zod on the way in and out, so a malformed event can
+ * never reach (or be trusted from) disk.
+ *
+ * Two verbs:
+ *   - {@link ActivityLog.record} — validate and append one {@link CrewEvent}.
+ *   - {@link ActivityLog.timeline} — read back every event in append order.
+ */
+import { z } from "zod";
+/** The closed set of coordination events the crew narrates. */
+export declare const CREW_EVENT_KINDS: readonly ["member_spawned", "ticket_posted", "ticket_claimed", "ticket_done", "ticket_failed", "message_sent"];
+/** One coordination-event class — the discriminant of {@link CrewEvent}. */
+export type CrewEventKind = (typeof CREW_EVENT_KINDS)[number];
+/**
+ * The event schema, as a discriminated union over `kind`. Each branch pins the
+ * fields that class of event carries — the role for a spawn, the ticket id for a
+ * lifecycle transition, the envelope id and endpoints for a message — so a
+ * timeline consumer can narrow on `kind` and read exactly the fields that apply.
+ */
+declare const crewEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"member_spawned">;
+    memberId: z.ZodString;
+    role: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ticket_posted">;
+    ticketId: z.ZodString;
+    title: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ticket_claimed">;
+    ticketId: z.ZodString;
+    memberId: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ticket_done">;
+    ticketId: z.ZodString;
+    memberId: z.ZodString;
+    summary: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ticket_failed">;
+    ticketId: z.ZodString;
+    memberId: z.ZodString;
+    error: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"message_sent">;
+    envelopeId: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    envelopeType: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>], "kind">;
+/** A validated crew coordination event. */
+export type CrewEvent = z.infer<typeof crewEventSchema>;
+/**
+ * What a caller hands to {@link ActivityLog.record}: any {@link CrewEvent}
+ * without the auto-stamped `id`/`ts` header (either may still be supplied to
+ * override the defaults). The id is minted and the timestamp is stamped by the
+ * log if absent.
+ */
+export type CrewEventInput = (Omit<Extract<CrewEvent, {
+    kind: "member_spawned";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "ticket_posted";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "ticket_claimed";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "ticket_done";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "ticket_failed";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "message_sent";
+}>, "id" | "ts"> & EventStamp);
+/** The optional header overrides a caller may pin on a recorded event. */
+interface EventStamp {
+    /** Override the minted id. */
+    readonly id?: string;
+    /** Override the stamped timestamp. */
+    readonly ts?: number;
+}
+/**
+ * The crew's audit/transcript observer, backed by one {@link JsonlLog}.
+ *
+ * Open with {@link ActivityLog.open}; the factory wires up the underlying log
+ * (which ensures the parent directory exists). It is an *observer*: the crew
+ * narrates events to it, but it holds no authority over the work and can be
+ * dropped without affecting correctness.
+ */
+export declare class ActivityLog {
+    private readonly log;
+    /** Injected clock, epoch ms — overridable for deterministic tests. */
+    private readonly now;
+    private constructor();
+    /** Absolute path of the `.jsonl` file backing this log. */
+    get path(): string;
+    /**
+     * Open (or adopt) the activity log stored at `path`.
+     *
+     * `now` defaults to `Date.now`; tests may inject a deterministic clock so
+     * recorded timestamps are reproducible.
+     */
+    static open(path: string, now?: () => number): Promise<ActivityLog>;
+    /**
+     * Validate and append one coordination event, returning the stored record.
+     *
+     * The event's `id` is minted (`act_<ULID>`) and its `ts` is stamped with the
+     * current time when the caller leaves them off. The completed event is run
+     * through the schema before it touches disk, so a malformed event raises a
+     * `validation` fault rather than corrupting the transcript.
+     */
+    record(event: CrewEventInput): Promise<CrewEvent>;
+    /**
+     * Read back every recorded event, in append (chronological) order.
+     *
+     * A missing log is an empty timeline, not an error. Each line is schema-checked
+     * on the way out, so a corrupt transcript surfaces as a `validation` fault
+     * naming the bad line rather than silently returning garbage.
+     */
+    timeline(): Promise<CrewEvent[]>;
+}
+export {};

package/dist/types/swarm/workboard/board.d.ts

@@ -0,0 +1,174 @@
+/**
+ * `TicketBoard` — the swarm's unit-of-work store.
+ *
+ * A board is the shared to-do list a crew of agent teammates pulls from. Each
+ * piece of work is a {@link Ticket}: a small, schema-validated record with a
+ * lifecycle (`open → claimed → done | failed`, plus a `blocked` side-state) and
+ * an optional set of `deps` on other tickets. The whole board lives in one JSON
+ * file, mediated by the kernel's {@link JsonCell}, so every mutation is a single
+ * guarded read-modify-write — the board never touches `node:fs` locking, temp
+ * renames, or coercion itself. It is, as intended, a thin domain wrapper over
+ * `JsonCell.mutate`.
+ *
+ * The dependency relation is a first-class concern. `deps` form a directed graph
+ * ("A must be `done` before B is workable"); {@link TicketBoard} keeps that graph
+ * honest in two ways, both delegated to {@link DepGraph}:
+ *
+ *   - **Edges once.** A dependency declared twice contributes a single edge; the
+ *     graph carries no parallel edges.
+ *   - **No cycles.** {@link TicketBoard.add} rebuilds the graph including the
+ *     incoming ticket and rejects the insert with a `conflict` fault if it would
+ *     introduce a cycle — a dependency loop can never reach disk.
+ *
+ * Readiness falls out of that graph: {@link TicketBoard.ready} returns the `open`
+ * tickets whose every dependency has reached `done`. Those are the tickets a
+ * member may safely {@link TicketBoard.claim}; claiming is atomic (it runs inside
+ * the cell's guarded transform), so two members racing for the same ticket cannot
+ * both win.
+ */
+import { z } from "zod";
+/** The lifecycle states a ticket moves through. */
+export declare const ticketStatuses: readonly ["open", "claimed", "blocked", "done", "failed"];
+/** A ticket's lifecycle state. */
+export type TicketStatus = (typeof ticketStatuses)[number];
+/**
+ * One unit of work on the board.
+ *
+ * `status` is the lifecycle discriminant; `assignee` names the member that holds
+ * a `claimed`/`blocked` ticket (and survives onto `done`/`failed` as the record
+ * of who did it). `deps` are the ids of tickets that must reach `done` before
+ * this one is workable. `result`/`error` capture the terminal payload of a
+ * completed/failed ticket. Timestamps are epoch milliseconds.
+ */
+export declare const ticketSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodString;
+    status: z.ZodEnum<{
+        done: "done";
+        failed: "failed";
+        open: "open";
+        claimed: "claimed";
+        blocked: "blocked";
+    }>;
+    assignee: z.ZodOptional<z.ZodString>;
+    deps: z.ZodArray<z.ZodString>;
+    result: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    blockReason: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+/** A validated ticket. */
+export type Ticket = z.infer<typeof ticketSchema>;
+/** Fields a caller may set when adding a ticket. */
+export interface TicketDraft {
+    /** 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[];
+}
+/**
+ * The shared, durable ticket store a swarm coordinates through.
+ *
+ * Open one with {@link TicketBoard.open}; every method is a thin pass over the
+ * underlying {@link JsonCell}. Mutators (`add`, `claim`, `complete`, `fail`,
+ * `block`, `unblock`) run inside a single guarded transform so concurrent crews
+ * sharing the file serialize correctly; readers (`get`, `list`, `ready`) are
+ * lock-free.
+ */
+export declare class TicketBoard {
+    private readonly cell;
+    /** Injected clock, epoch ms — overridable for deterministic tests. */
+    private readonly now;
+    private constructor();
+    /**
+     * Open (or adopt) the board backed by the JSON file at `path`.
+     *
+     * `now` defaults to `Date.now`; tests may inject a deterministic clock. The
+     * file is not created until the first mutation.
+     */
+    static open(path: string, now?: () => number): Promise<TicketBoard>;
+    /**
+     * Admit a new ticket, returning the persisted record.
+     *
+     * The ticket is born `open` with a freshly minted id and the current
+     * timestamp. Its `deps` are de-duplicated; every dep must already name a
+     * ticket on the board (a dangling dependency raises `not_found`). The
+     * dependency graph is rebuilt including the newcomer, and the insert is
+     * rejected with a `conflict` fault if it would introduce a cycle — the board
+     * never persists a cyclic dependency relation.
+     */
+    add(draft: TicketDraft): Promise<Ticket>;
+    /**
+     * Atomically claim an `open` ticket for `member`.
+     *
+     * Moves the ticket `open → claimed` and stamps `assignee = member`. The check
+     * and the write happen inside one guarded transform, so two members racing for
+     * the same ticket cannot both succeed — the loser sees a `conflict` fault. A
+     * ticket that is missing (`not_found`) or not currently `open` (`conflict`)
+     * cannot be claimed.
+     */
+    claim(id: string, member: string): Promise<Ticket>;
+    /**
+     * Mark a `claimed` ticket `done`, recording its `result`.
+     *
+     * Only a `claimed` ticket may complete; completing anything else raises
+     * `conflict`. Completion can unblock other tickets — see {@link ready}.
+     */
+    complete(id: string, result: string): Promise<Ticket>;
+    /**
+     * Mark a `claimed` ticket `failed`, recording the `error`.
+     *
+     * Only a `claimed` ticket may fail; failing anything else raises `conflict`. A
+     * failed dependency never satisfies a dependent (only `done` does), so its
+     * dependents stay out of {@link ready}.
+     */
+    fail(id: string, err: string): Promise<Ticket>;
+    /**
+     * Move an `open` or `claimed` ticket into the `blocked` side-state.
+     *
+     * Blocking records an optional human-readable `reason` and preserves the
+     * `assignee`. A terminal ticket (`done`/`failed`) cannot be blocked
+     * (`conflict`). Use {@link unblock} to return it to the queue.
+     */
+    block(id: string, reason?: string): Promise<Ticket>;
+    /**
+     * Return a `blocked` ticket to `open`, clearing its assignee and block reason.
+     *
+     * Only a `blocked` ticket may be unblocked (`conflict` otherwise). It re-enters
+     * the queue unowned, so any member may {@link claim} it next.
+     */
+    unblock(id: string): Promise<Ticket>;
+    /** Fetch one ticket by id, or `null` if the board has no such ticket. */
+    get(id: string): Promise<Ticket | null>;
+    /**
+     * List every ticket in insertion order, optionally filtered by status.
+     *
+     * The order is stable across reads and process restarts (it follows the
+     * persisted insertion sequence, not map iteration order).
+     */
+    list(status?: TicketStatus): Promise<Ticket[]>;
+    /**
+     * The `open` tickets that are workable right now.
+     *
+     * A ticket is ready when it is `open` and every id in its `deps` names a
+     * ticket that has reached `done`. Tickets with unmet, failed, or still-running
+     * dependencies are withheld. Results are in insertion order, so the board hands
+     * work out fairly (oldest first). These are exactly the tickets a member may
+     * {@link claim}.
+     */
+    ready(): Promise<Ticket[]>;
+    /**
+     * Guarded transform of a single ticket by id.
+     *
+     * Loads the named ticket, applies `change` (which stamps a fresh `updatedAt`),
+     * and writes the whole board back — all inside one {@link JsonCell.mutate}, so
+     * the read-decide-write is atomic against concurrent members. A missing id
+     * raises `not_found`; `change` may throw a `conflict` to veto an illegal
+     * transition.
+     */
+    private transition;
+}

package/dist/types/swarm/workboard/dep-graph.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `DepGraph` — the workboard's dependency relation, with edges added exactly once.
+ *
+ * A ticket may declare it `deps` on other tickets: ticket *B* depends on ticket
+ * *A* means "A must reach `done` before B is workable". That relation is a
+ * directed acyclic graph — an edge `A → B` ("A unblocks B") for every `A` in
+ * `B.deps`. This module is the pure, in-memory view of that graph, rebuilt from
+ * the ticket store whenever the board needs to reason about readiness or admit a
+ * new ticket.
+ *
+ * Two properties the workboard leans on, both enforced here rather than scattered
+ * across the board logic:
+ *
+ *   1. **Edges are added once.** Declaring the same dependency twice (a duplicate
+ *      in `deps`, or the same pair re-derived on a later rebuild) adds the edge a
+ *      single time. The adjacency sets are de-duplicating by construction, so the
+ *      graph carries no parallel edges and downstream traversals visit each
+ *      neighbour at most once.
+ *   2. **Cycles are detectable.** {@link DepGraph.firstCycle} returns the first
+ *      dependency cycle it finds (as the node path that closes the loop) or
+ *      `null` when the graph is acyclic. The board calls this when admitting a
+ *      ticket so a dependency loop is rejected at `add()` time instead of
+ *      deadlocking `ready()` forever.
+ *
+ * The graph is intentionally decoupled from persistence and from the `Ticket`
+ * shape: it speaks only in node ids and `id → deps` adjacency, so it is trivial
+ * to test and reuse.
+ */
+/**
+ * A directed dependency graph over ticket ids.
+ *
+ * Build one with {@link DepGraph.fromDeps}; the constructor is private so every
+ * graph goes through the de-duplicating edge-insertion path. Nodes are ticket
+ * ids; an edge `dep → ticket` records that `dep` must complete before `ticket`.
+ */
+export declare class DepGraph {
+    /** `dep → set of tickets it unblocks`. De-duplicating: each edge appears once. */
+    private readonly forward;
+    /** `ticket → set of tickets it depends on`. The reverse of {@link forward}. */
+    private readonly backward;
+    /** Every node known to the graph (a dependency may be named before it exists). */
+    private readonly nodes;
+    private constructor();
+    /**
+     * Build a graph from an `id → deps` mapping.
+     *
+     * Each `(dep, id)` pair becomes the edge `dep → id`, inserted via
+     * {@link addEdge} so duplicates collapse. Self-edges (`id` listing itself in
+     * its own `deps`) are admitted as ordinary edges so that {@link firstCycle}
+     * reports them as the trivial one-node cycle rather than silently dropping
+     * them.
+     */
+    static fromDeps(entries: Iterable<readonly [id: string, deps: readonly string[]]>): DepGraph;
+    /**
+     * Record the edge `from → to` (i.e. `from` must finish before `to`).
+     *
+     * Idempotent: the backing adjacency is a `Set`, so re-adding an existing edge
+     * is a no-op and the graph never accumulates parallel edges.
+     */
+    private addEdge;
+    /** Lazily fetch (or create) the adjacency set for `key` in `side`. */
+    private edgeSet;
+    /** The ids this node directly depends on (its in-neighbours). */
+    dependenciesOf(id: string): readonly string[];
+    /** The ids directly unblocked by this node (its out-neighbours). */
+    dependentsOf(id: string): readonly string[];
+    /**
+     * Find the first dependency cycle, or `null` if the graph is acyclic.
+     *
+     * Runs an iterative depth-first search colouring nodes white/grey/black; the
+     * first back-edge to a grey (on-stack) node closes a cycle, which is returned
+     * as the node path from the re-encountered node around to itself
+     * (`[a, b, …, a]`). Detection is what lets the board reject a cyclic `add()`
+     * up front rather than letting `ready()` starve.
+     */
+    firstCycle(): readonly string[] | null;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * The workboard — public surface.
+ *
+ * One domain service, {@link TicketBoard}: the swarm's shared, durable task store.
+ * It is a thin wrapper over the kernel's `JsonCell` (every mutation is one guarded
+ * read-modify-write) that adds a ticket lifecycle and an edges-once dependency
+ * graph with cycle detection. {@link DepGraph} is exported for callers that want
+ * to reason about the dependency relation directly.
+ */
+export { TicketBoard, ticketSchema, ticketStatuses } from "./board";
+export type { Ticket, TicketStatus, TicketDraft } from "./board";
+export { DepGraph } from "./dep-graph";

package/dist/types/tracing/adapter/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The adapter layer — public surface.
+ *
+ * The OPTIONAL runtime bridge {@link traceAgentRun}, which projects a runtime
+ * {@link import('../../runtime').RunEvent} stream onto a
+ * {@link import('../recorder/recorder').Recorder} as nested `run`/`inference`/
+ * `action` {@link import('../signal/segment').Segment}s. Importing it is the one
+ * place tracing knows the runtime's event vocabulary; the rest of the subsystem
+ * stays runtime-agnostic.
+ */
+export type { RunEventSubscribe } from "./runtime-trace";
+export { traceAgentRun } from "./runtime-trace";