@avantf/dsh-mission 0.3.0

package/lib/mission-core/types.d.ts

@@ -0,0 +1,409 @@
+/**
+ * Work-tree vocabulary: node states, capacities, durable record shapes. The tree is the only
+ * authoritative state holder — every execution reads what it needs from the node it was
+ * dispatched for, never from an agent's conversation.
+ *
+ * @module @avantf/mission-core/types
+ */
+export type NodeStatus = 
+/** Has non-terminal children; not dispatchable. */
+'blocked'
+/** The only spawnable status: no children yet, or all terminal. */
+ | 'ready'
+/** Dispatched; `claimedBy` holds the worker. */
+ | 'running'
+/** Worker vanished without submitting; dispatchable again. */
+ | 'interrupted'
+/** Terminal: a result was submitted. */
+ | 'done'
+/** Terminal: attempts exhausted, or rejected by a capacity check. */
+ | 'failed';
+/** Terminal statuses never change again. */
+export declare const TERMINAL: ReadonlySet<NodeStatus>;
+export declare const DISPATCHABLE: ReadonlySet<NodeStatus>;
+/** Capacities: exported so the tools and the engine validate against ONE source. */
+export declare const CAPACITY: {
+    /** Root is depth 1, so depth 8 allows at most seven consecutive decompositions. */
+    readonly maxDepth: 8;
+    readonly maxChildrenPerDecompose: 6;
+    /** Backstop ceiling on one tree's size, checked before a `decompose` commits: depth (8) ×
+     * children (6) leaves the count bounded but enormous, and the depth limit does not fire until
+     * the eighth level. */
+    readonly maxNodesPerTree: 200;
+    /** Execution-failure ceiling: a node reclaimed (vanished or stalled) this many times fails;
+     * successful rounds do not count. The same ceiling bounds consecutive failed STARTS
+     * (`spawnFailures`), tracked separately so an outage is not charged against the mission. */
+    readonly maxAttempts: 5;
+    /** A node reclaimed for silence this many times gets a heads-up, not a decision request — the
+     * engine recovers on its own, which is why it waits for a repeat. */
+    readonly maxStallsBeforeReport: 2;
+    /** A node reclaimed as `hung` (alive but unproductive, or past its round cap) this many times IN A
+     * ROW gets the same one-message heads-up, through the same durable marker. One higher than
+     * {@link maxStallsBeforeReport} because a hung round is already a whole stale/round window long, so
+     * three in a row is unambiguous rather than jitter — and because a single long-but-legitimate step
+     * must not page the owner. This is the ceiling the old behaviour lacked: hung still charges no
+     * budget, but it can no longer repeat forever without anyone being told. */
+    readonly maxHungsBeforeReport: 3;
+    /** Longer results are spilled to the store; the node keeps the summary. */
+    readonly maxInlineResultChars: 2000;
+};
+export interface TreeRecord {
+    /** Root node id; also the tree's id. */
+    readonly rootId: string;
+    /** The agent that created the root: no other agent sees the tree, and the tree is destroyed
+     * when this session stops existing. */
+    readonly ownerSessionId: string;
+    readonly createdAt: number;
+    /** When the owner closed the tree out (`finish_mission`); `null` while open. Closing is archival —
+     * nodes and results stay, but the tree leaves the guidance and the wake decision. */
+    readonly closedAt: number | null;
+    /** When the owner was woken about this tree reaching a terminal state. Durable on purpose: an
+     * in-memory guard re-reports on every dispatch pass after a restart. */
+    readonly reportedAt: number | null;
+}
+/**
+ * What one dispatch's prompt showed its session, frozen so a LATER wake can subtract it: "what has
+ * changed since this session last read this mission?" It is a snapshot of the node's ACCUMULATING
+ * channels, not of its execution state — the execution state is the binding's business.
+ *
+ * Every component exists for one consumer; none is decoration:
+ *
+ * - `corrections` — the second half of "corrections this session has NOT seen" (the delivery
+ *   watermark is the first). Both are needed: a FRESH spawn renders every correction but does not
+ *   advance the watermark, so a watermark-only reading would call those corrections unseen forever
+ *   and route every corrected mission to a fresh executor instead of continuing it.
+ * - `notes` — how many analysis entries existed when the prompt was built; entries beyond it are the
+ *   ones appended while this session held the node, which is what the delta reports.
+ * - `terminalChildren` — for the delta's wording only ("N 子任务达到终态"). Deliberately NOT part of
+ *   the material-change judgement, because for a PARKED session "all children terminal" is the
+ *   trigger of the wake itself (see `isMaterialChange`).
+ * - `fingerprint` — title+description at dispatch. A changed headline means this session would be
+ *   resuming a mission it was never handed.
+ * - `attempts` — the dispatch generation this prompt was built under, compared against
+ *   `analysisAttempt` to tell whether the node's latest note belongs to THIS dispatch.
+ * - `holder` — the session this prompt was delivered to. The generation number alone cannot answer
+ *   "is this note mine?": a session's own note survives into a LATER dispatch of the same node
+ *   (the parent that decomposed and is woken again is the common case), so `attempts` would call
+ *   its own judgement somebody else's. The wake compares this holder against the note's author
+ *   instead (`analysisAuthor`), and falls back to the generation comparison only when this is
+ *   `null` (a baseline written before the field existed).
+ *
+ * Missing on a record written before the field existed: that reads as "no baseline", which a wake
+ * must treat as UNKNOWN rather than as "nothing changed" (see `computeContinuationDelta`).
+ */
+export interface DispatchBaseline {
+    readonly corrections: number;
+    readonly notes: number;
+    readonly terminalChildren: number;
+    readonly fingerprint: string;
+    readonly attempts: number;
+    /** The session holding the node when this prompt was built; `null` on a pre-`holder` record, which
+     *  the delta reads as "author unknown" and judges by the generation comparison. */
+    readonly holder: string | null;
+}
+/**
+ * Why a `ready`/`interrupted` node has not been dispatched yet — computed live by the engine from
+ * the current admission state, never persisted. `null` (or a missing field on an older payload)
+ * means "nothing is holding it back".
+ *
+ * The four reasons are the four gates that can defer a dispatch:
+ *
+ * - `capacity` — the master gate: `Σ running.weight + weight > capacity`. `resource` distinguishes
+ *   the machine-derived compute capacity (`cpu`) from the host's free-memory floor (`memory`, whose
+ *   `needed`/`available` are BYTES, not cores). Only the `cpu` flavour can age into a reservation.
+ * - `unit` — another `running` node holds the same declared scope (the unit lease).
+ * - `slot` — the `maxConcurrent` ceiling on the NUMBER of units; capacity itself has room.
+ * - `aging` — an aged node has RESERVED the machine (past the aging window: no new admission until
+ *   it fits), so every OTHER queued candidate is held back even though `capacity` alone might have
+ *   room. Reported instead of `slot` because "capacity is free, the slots are just full" would be
+ *   false, and this is the one moment the anti-starvation mechanism is supposed to be visible.
+ *
+ * `needed`/`available` are filled only where a number is meaningful; a memory deferral whose signal
+ * is `null` ("cannot tell") carries no numbers at all, because there is nothing honest to show.
+ */
+export interface WaitingFor {
+    readonly reason: 'capacity' | 'unit' | 'slot' | 'aging';
+    readonly resource?: 'cpu' | 'memory';
+    readonly needed?: number;
+    readonly available?: number;
+    /** The unit another node holds, for `reason: 'unit'`. */
+    readonly unit?: string;
+}
+export interface NodeRecord {
+    readonly id: string;
+    readonly rootId: string;
+    /** The parent that created this node; `null` for the root. Provenance only: dedup reuse can list
+     * a node under several parents' `children` while it keeps the `parentId` it was born under. */
+    readonly parentId: string | null;
+    readonly title: string;
+    readonly description: string;
+    /** How many capacity units (cores-equivalent, the same unit as `EngineOptions.capacity`) this
+     * mission is expected to occupy while it runs. Declared by `create_mission` for a root and per
+     * child by `decompose_mission`; a child that declares nothing uses the DEFAULT 1 and deliberately
+     * does NOT inherit the parent's estimate — a parent's appetite says nothing about one child's.
+     * Persisted, and a record written before the field existed loads as 1; `DOMAIN_VERSION` stays 1. */
+    readonly weight: number;
+    /** The SCOPE this mission will modify — a directory or a file — and therefore the key of its
+     * engine-enforced lease: no two `running` nodes may carry the same non-null `unit` (see
+     * `@avantf/mission-core/dispatch`). Declared by `create_mission` for a root and per child by
+     * `decompose_mission`; a child that declares nothing INHERITS its parent's unit, so same-scope
+     * siblings cannot run at the same time.
+     *
+     * `null` means "no scope declared", which is also what a record written before this field existed
+     * loads as: such a node takes no part in the lease and behaves exactly as it did before the field
+     * existed. Persisted, `DOMAIN_VERSION` stays 1. */
+    readonly unit: string | null;
+    /** Per-mission RELAXATION of the engine's `roundMs` ceiling — how long ONE round of this mission
+     * may run before it is reclaimed as `hung`. Declared by `create_mission` for a root and per child by
+     * `decompose_mission`, exactly like `weight`; a child's declaration is its own and is deliberately
+     * NOT inherited (a parent's long build says nothing about one child). Relaxation ONLY: the engine
+     * compares `max(configured roundMs, this)`, so a declaration can never shorten the backstop that
+     * catches a transport retrying forever, and `normalizeRoundMs` caps it at 24 h so it cannot opt out
+     * of the backstop either. `null` means "use the engine's configured cap", which is also what a
+     * record written before the field existed loads as. Persisted, `DOMAIN_VERSION` stays 1. */
+    readonly roundMs: number | null;
+    /** Background facts: why this mission exists (written by the decomposer), or the owner's initial
+     * analysis for a root — the only channel carrying the vertical "why" down the mission chain. */
+    readonly context: readonly string[];
+    /** The owner's corrections for this mission, newest last. The name is load-bearing because the
+     * field is persisted: renaming it would make every earlier correction load as absent. Separate
+     * from `context` on purpose — different author and lifetime. */
+    readonly corrections: readonly string[];
+    /** Delivery watermark for {@link corrections}: how many LEADING entries are confirmed delivered
+     * to the executor that was holding this node. What it decides is the WAKE message — a cold resume
+     * renders only `corrections.slice(correctionsDeliveredUpTo)`, because the corrections already
+     * handed to that very session must not be argued to it a second time. A FRESH executor ignores
+     * the watermark entirely and sees every correction: it has read none of them.
+     *
+     * `0` means "nothing is confirmed delivered", which is also what a record written before this
+     * field existed loads as — the conservative reading, since a silently skipped correction is a
+     * direction the owner gave that nobody ever reads. Monotone: a raced, older report can never pull
+     * it back. Kept as a NUMBER beside the text array rather than turning `corrections` into objects,
+     * because changing that array's shape would make every historical correction load as absent. */
+    readonly correctionsDeliveredUpTo: number;
+    /** What this mission's executors recorded with `note_mission`, oldest first. The durable channel
+     * across sessions: the round that judges the mission is a fresh session reading only this node's
+     * prompt, and notes are appended, never replaced. */
+    readonly analysisNotes: readonly string[];
+    /** The `attempts` value of the dispatch that wrote the LAST entry; `0` when none. `decompose`
+     * compares it against the current `attempts`, so an executor cannot inherit a justification
+     * written by an earlier round. */
+    readonly analysisAttempt: number;
+    /** The session that wrote the LAST entry of {@link analysisNotes}; `null` when none, or on a record
+     * written before the field existed. The cold wake compares it against {@link DispatchBaseline}'s
+     * `holder` so a session's OWN note is not mistaken for a different dispatch's — which the
+     * generation number alone cannot tell once the same session's note outlives its dispatch. Persisted,
+     * `DOMAIN_VERSION` stays 1. */
+    readonly analysisAuthor: string | null;
+    readonly status: NodeStatus;
+    /** When this node was ACCEPTED into the tree (entered `ready`). The scheduling semantics are the
+     * reason this is not "when it started": capacity is a DISPATCH gate, not an admission gate (see
+     * `@avantf/mission-core/dispatch`), so a node can sit here for a long time waiting for room or for
+     * its unit. {@link dispatchedAt} minus this is the queue time. */
+    readonly createdAt: number;
+    /** When this node was dispatched for the FIRST time — the moment an executor was bound to it (the
+     * first transition into `running`, via `dispatch`/`adoptParked`/`adoptContinuation`). `null` means
+     * "never its turn yet": still queued for capacity or for a unit. Immutable after the first write, so
+     * a reclaim, a retry or a re-dispatch never rewrites it; a record written before this field existed
+     * loads as `null` (= never dispatched, the honest reading). Persisted, `DOMAIN_VERSION` stays 1. */
+    readonly dispatchedAt: number | null;
+    /** When this node entered a TERMINAL status (`done`/`failed`). `null` means "still in play" — ready,
+     * blocked, running or interrupted. Terminal is final, so this is written exactly once, by whichever
+     * path ends the node (`submitResult`, `failExhausted`, `cancelSubworks`, `cancelTree`); a node that
+     * is cancelled before ever running carries an `endedAt` with a `null` `dispatchedAt`. A record
+     * written before this field existed loads as `null` (= still in play). Persisted, `DOMAIN_VERSION`
+     * stays 1. */
+    readonly endedAt: number | null;
+    readonly depth: number;
+    /** Durable binding to the worker session id, persisted so a hot reload can tell "someone is
+     * still on this"; the agent's existence is always resolved live, never asserted from here. */
+    readonly claimedBy: string | null;
+    readonly claimedAt: number;
+    readonly attempts: number;
+    /** Execution-failure budget: how many times this node's worker was reclaimed (vanished or
+     * stalled) without producing a result. Separate from `attempts`, which counts EVERY dispatch —
+     * including successful aggregate/convergence rounds — so succeeding never burns this budget. */
+    readonly failures: number;
+    /** How many times in a row a dispatch failed to even START a worker (the runtime refused, or the
+     * tool filter could not be applied). An infrastructure failure, so it is budgeted separately
+     * from `failures` and pushes the next dispatch back by a cooldown; a successful start resets it. */
+    readonly spawnFailures: number;
+    /** The worker session that PARKED this node by decomposing it — a wake-up ADDRESS, not a claim:
+     * `claimedBy` is cleared exactly as usual, and the address is consumed by the next dispatch
+     * (adopted, or replaced by a fresh session). `nextDispatchable` excludes a parked node, because
+     * `decompose_mission` is followed by a synchronous `pump()` that would otherwise pre-empt the wake. */
+    readonly parkedWorker: string | null;
+    /** The session id of the worker most recently bound to this node, kept when the binding is
+     * dropped by an INTERRUPTION rather than by a clean hand-off — i.e. `reconcileOnOpen` demoting a
+     * `running` node whose worker is not materialized in this process (a restart or a crash), which
+     * is exactly when `claimedBy` alone loses the address for good. The next dispatch of this node
+     * first tries to CONTINUE that session (cold wake) instead of starting a fresh executor; a
+     * delivery the runtime refuses falls back to a brand-new session with no budget charged.
+     *
+     * Deliberately NOT the same thing as `parkedWorker`, and neither may overwrite the other:
+     * a parked worker is an ALIVE, actively waiting continuation (it decomposed and expects to be
+     * woken in the same run); `lastWorkerId` is a handle to a session that may no longer exist, and
+     * the cold resume that reaches it is allowed to fail. Only `reconcileOnOpen` writes it, and only
+     * `adoptContinuation` consumes it — a same-process reclaim does not, so ordinary re-dispatch
+     * behaviour is untouched. `null` for a node that was never dispatched or whose handle was spent,
+     * which is also the value a record written before this field existed loads as. */
+    readonly lastWorkerId: string | null;
+    /** The session id of the LAST executor this node was dispatched to — the display address behind
+     * the panel's "click the node id to open the session that ran it". Written at every transition
+     * INTO `running` (`dispatch` / `adoptParked` / `adoptContinuation`) and deliberately KEPT when the
+     * node leaves `running`: a finished mission must still be able to name who executed it, which is
+     * exactly what `claimedBy` (cleared on every exit) cannot do.
+     *
+     * A display address, NOT a continuation handle: nothing consumes it, and it is deliberately not
+     * `lastWorkerId` — that one is a one-shot cold-wake address that only `reconcileOnOpen` writes and
+     * only `adoptContinuation` spends, so overloading it would change ordinary re-dispatch behaviour (a
+     * same-process reclaim would start cold-resuming). A node dispatched several times keeps only the
+     * LAST attempt, because the projection carries one string and never a history array. `null` for a
+     * node that was never dispatched, which is also the value a record written before this field
+     * existed loads as. Persisted, `DOMAIN_VERSION` stays 1. */
+    readonly executorSessionId: string | null;
+    /** What the prompt of the LAST dispatch showed its session, stamped by the host the moment that
+     * prompt was ACCEPTED (not when the node was bound: a dispatch whose prompt was never built or
+     * never delivered must not leave a baseline claiming the session read something). The cold wake
+     * subtracts it to get the delta it renders, and the same delta decides whether continuing is honest
+     * at all; a FRESH spawn ignores it entirely, because a new executor has read nothing.
+     *
+     * Deliberately NOT the same thing as `analysisAttempt` (that is `note_mission`'s generation gate)
+     * and NOT derived from `correctionsDeliveredUpTo` (that is one half of the correction story, and
+     * the weaker half — see {@link DispatchBaseline}). `null` for a node never dispatched by a host
+     * that stamps baselines, which is also the value a record written before this field existed loads
+     * as; that direction is the safe one, because "unknown" renders an honest caveat and never a
+     * fabricated "nothing changed". */
+    readonly dispatchBaseline: DispatchBaseline | null;
+    /** When this node's worker last PRODUCED something: the model's committed output, a tool it asked
+     * for, or a tool that finished. This is what the stale check compares against — `progressAt` is
+     * about output, deliberately NOT about "an event arrived" (see {@link activityAt}); a long but
+     * productive run stays safe, while a provider that only retries stops refreshing it. `0` means
+     * "nothing produced yet" and falls back to `claimedAt`. */
+    readonly progressAt: number;
+    /** When this node's worker was last HEARD FROM at all — any durable session event, output or
+     * transport-layer noise (retry attempts, per-request route snapshots). Kept apart from
+     * `progressAt` so the engine can tell the two ways a live worker stops being useful: nothing at
+     * all (both go stale → `stalled`, which charges the failure budget) versus events with no output
+     * (this stays fresh while `progressAt` goes stale → `hung`, which charges nothing). `0` means
+     * never observed; the readers fall back to `claimedAt`, and a record written before this field
+     * existed loads as `0` — "cannot tell output from noise", the conservative direction that leaves
+     * the round cap to reclaim it rather than inventing a stall. Persisted, `DOMAIN_VERSION` stays 1. */
+    readonly activityAt: number;
+    /** Times this node was reclaimed because its worker went silent past the stale window; a worker
+     * that merely vanished is not the node's fault and does not count here. A `hung` reclaim is not
+     * counted either — see `MissionTree.reclaim` and {@link hungCount}. */
+    readonly stalls: number;
+    /** CONSECUTIVE `hung` reclaims since this node last PRODUCED something (real output, i.e. the
+     * `MissionTree.touchProgress` clock). Hung rounds charge no budget by design, so without this
+     * counter a worker that hangs every round re-runs forever and nothing ever reaches the owner. It is
+     * a STREAK, not a history: any real output clears it to 0, and a re-dispatch does NOT (the round
+     * after a hung reclaim is exactly the next link in the streak). At
+     * `CAPACITY.maxHungsBeforeReport` it trips `isTroubledNode`, which both flags the mission as
+     * 「反复出过问题」 and routes it to the owner through the same one-message-per-node trouble channel
+     * the stall and failed-start heads-ups use. `0` is also what a record written before the field
+     * existed loads as. Persisted, `DOMAIN_VERSION` stays 1. */
+    readonly hungCount: number;
+    /** When the owner was told this node keeps stalling; `null` until then. Durable for the same
+     * reason as `TreeRecord.reportedAt`: an in-memory memo is empty after a restart. */
+    readonly stalledNotifiedAt: number | null;
+    /** Inline result (the summary when the full text was spilled). */
+    readonly result: string | null;
+    /** Distinguishes "no result written" from "an empty result was written". */
+    readonly hasResult: boolean;
+    readonly resultReadAt: number | null;
+    readonly resultRef: string | null;
+    /** The backend's retrieval guidance for `resultRef`, persisted because a locator without its
+     * hint leaves the reader unable to fetch the full text. `null` when nothing was spilled. */
+    readonly resultHint: string | null;
+    /** Child ids in decomposition order. */
+    readonly children: readonly string[];
+    readonly updatedAt: number;
+}
+export interface ChildSpec {
+    readonly title: string;
+    readonly description: string;
+    readonly context: readonly string[];
+    /** This child's scope. `undefined` (the spec said nothing) inherits the parent's unit — the safe
+     * default; a non-blank string is the child's own scope; a blank string or `null` declares that
+     * this child takes no lease at all. Resolved by `resolveChildUnit`. */
+    readonly unit?: string | null;
+    /** This child's declared capacity weight, in cores-equivalent. `undefined` reads as the default 1
+     * and is deliberately NOT inherited from the parent — the parent's estimate is not the child's. */
+    readonly weight?: number;
+    /** This child's declared round-cap relaxation (see {@link NodeRecord.roundMs}). `undefined` reads
+     * as `null` — the engine's configured cap — and is deliberately NOT inherited from the parent. */
+    readonly roundMs?: number | null;
+}
+/** A dispatch candidate: the node plus its resolved mission chain and, exactly when the node is a
+ * ready aggregate, the current children results. */
+export interface DispatchView {
+    readonly node: NodeRecord;
+    /** Ancestors root → parent, each reduced to title + basic facts. */
+    readonly chain: readonly NodeRecord[];
+    /** Terminal children of an aggregate, in decomposition order. */
+    readonly children: readonly NodeRecord[];
+}
+export interface DecomposeOutcome {
+    readonly created: readonly string[];
+    /** Children whose equivalent already existed in the subtree and were reused. */
+    readonly reused: readonly string[];
+}
+/** Why a mutation was refused. Returned instead of thrown so tools can report it. */
+export type RefusalCode = 'not-found' | 'not-owner' | 'terminal'
+/** The node still has non-terminal children, so the mutation it refused must wait. */
+ | 'has-children' | 'not-dispatchable' | 'depth-exceeded' | 'too-many-children' | 'no-children'
+/** Nothing below the node is unfinished, so there is nothing to cancel. */
+ | 'nothing-to-cancel' | 'unread-result'
+/** The addressed node is not a root, and only a root takes the mutation. */
+ | 'not-root' | 'node-limit'
+/** The node is not terminal, so it is not the owner's to delete. */
+ | 'not-deletable' | 'closed'
+/** The caller is not a top-level session, so it has no authority to own a tree. */
+ | 'no-authority'
+/** The tool was reached with no caller agent bound at all, so there is nobody to check authority
+ *  against. Produced by the tool layer — the one place a call can arrive callerless — and listed
+ *  here so a consumer that exhausts this union does not silently drop it. */
+ | 'no-caller'
+/** `note_mission` was given text with no non-blank line, so there is nothing to record. */
+ | 'no-analysis'
+/** A required text argument reached the engine containing nothing but whitespace. The tool layer's
+ *  non-empty check only sees the EMPTY string, so without this a blank title, result or correction
+ *  was accepted and persisted — then rendered back into every later dispatch. */
+ | 'blank-text'
+/** `decompose_mission` was called by a dispatch that has not written its own analysis: a split
+ * must be argued for by the round performing it, not inherited from an earlier one. */
+ | 'analysis-missing'
+/** The node's declared `unit` is held by another `running` node, so dispatching it would put two
+ * executors on the same scope. Refused WITHOUT charging the node: the holder always leaves
+ * `running` on its own, and the node is a candidate again then (see
+ * `@avantf/mission-core/dispatch`). */
+ | 'unit-busy'
+/** The node does not fit the machine RIGHT NOW — its weight would push `Σ running.weight` past
+ * `capacity`, or the `maxConcurrent` slot ceiling is reached. Produced by the lock-held recheck
+ * (`MissionTree.capacityRefusal`), which re-runs the plan's own judgement against live state so two
+ * concurrent passes cannot both bind from one stale snapshot. Refused WITHOUT charging the node:
+ * capacity is a DISPATCH gate, so this is exactly the plan path's deferral — the node stays
+ * `ready`, with no `attempts`/`failures`/`spawnFailures`, no cooldown and no stall. A caller must
+ * never report it as a dispatch failure (see `MissionEngine.pass`). */
+ | 'capacity-busy';
+/** A refused mutation, with a stable code the caller can branch on. */
+export interface Refusal {
+    readonly ok: false;
+    readonly code: RefusalCode;
+    readonly message: string;
+}
+/** A successful mutation. */
+export interface Accepted<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export type MutationResult<T> = Accepted<T> | Refusal;
+/** One tree as stored: identity plus nodes keyed by id. The durable and in-memory shapes are the
+ * same value; the store validates on read and writes it whole. */
+export interface TreeDocument {
+    tree: TreeRecord;
+    nodes: Record<string, NodeRecord>;
+}
+export declare function refuse(code: RefusalCode, message: string): Refusal;
+export declare function accept<T>(value: T): Accepted<T>;

package/lib/mission-core/wellformed.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Well-formed text — the mission tree's LOCAL copy of the family's lone-surrogate repair, and the
+ * port the plugin injects the base's canonical implementation through.
+ *
+ * The defect has exactly one shape: a UTF-16 code unit in `D800–DFFF` with no partner (an unpaired
+ * high half, an unpaired low half, or half of an emoji). Such a string is not a valid Unicode scalar
+ * sequence, yet `JSON.stringify` emits it verbatim as the escape `"\ud800"`. JavaScript's own
+ * `JSON.parse` accepts that, so every test in this repository passes while a strict parser rejects
+ * the whole document — measured, not theorized:
+ *
+ *   - `printf '"\\ud800"' | jq .` → `parse error: Invalid \uXXXX\uXXXX surrogate pair escape`;
+ *   - Python's `json.load` accepts the document but `print` raises
+ *     `UnicodeEncodeError: surrogates not allowed`;
+ *   - the same half-code-unit also poisons FTS indexes, embeddings and the UI.
+ *
+ * The repair is `String.prototype.toWellFormed()` (Node ≥20): it replaces each lone surrogate with
+ * U+FFFD (`�`). {@link wellFormedText} uses the engine's own implementation when it exists and an
+ * EQUIVALENT `charCodeAt` scan when it does not, so an older Node degrades in behaviour, never in
+ * availability.
+ *
+ * ── this file is the DEGRADATION copy ───────────────────────────────────────────────────────────
+ *
+ * The CANONICAL implementation lives in the family base kit
+ * (`@avantf/dsh-plugin-base` → `src/kit/wellformed.ts`, interface v2, exported as `wellFormedText` /
+ * `wellFormedDeep`). The plugin loads that base at runtime and injects the loaded functions into the
+ * core through {@link WellFormedSource} (`TreeDeps.wellFormed`, `buildWorkerPrompt`'s third argument,
+ * `AvantfMissionHost.wellFormed`); {@link LOCAL_WELL_FORMED} is what runs only when the base is
+ * absent or predates v2 and does not carry the two functions. Per the root `AGENTS.md`, fixing the
+ * shared repair means one base release; this copy exists so a missing base still repairs instead of
+ * mounting without any repair at all. The plugin must NEVER import the base by value — it takes both
+ * halves off the module the inlined bootstrap loaded.
+ *
+ * ── NFC policy: well-formedness ONLY, deliberately no `normalize('NFC')` ─────────────────────────
+ *
+ * The base kit leaves Unicode normalization to the caller because it is a PERSISTENCE policy, and
+ * mission declines to add it. Mission's inbound texts are PROSE (titles, descriptions, analyses,
+ * results, corrections) that is rendered straight back to models; there is no index, no identity and
+ * no equivalence class that needs canonical spelling. The one consumer that could want it —
+ * decomposition dedup — compares trimmed, whitespace-collapsed, lowercased titles, which is already
+ * a heuristic and deliberately does NOT equate different descriptions. Applying NFC on the way in
+ * would silently rewrite the caller's own bytes, and mission has no caller that needs it; applying
+ * it on the way out would rewrite history. So ONE function serves both directions (this symmetry is
+ * also what makes the "inbound funnel" and the outbound fallback provably the same repair). A future
+ * feature that needs canonical identity must make that a separate, explicit write-side policy.
+ *
+ * @module @avantf/mission-core/wellformed
+ */
+/**
+ * Make ONE string well-formed: every lone surrogate becomes U+FFFD, every properly paired surrogate
+ * (a complete emoji, a CJK Extension B character) and every other code point is returned unchanged.
+ *
+ * Uses the engine's `String.prototype.toWellFormed()` when available and {@link scanAndRepair}
+ * otherwise; both produce the same result, so a pre-ES2024 Node never throws here. Idempotent and
+ * pure: quotes, backslashes, newlines and tabs come back byte-for-byte, and no NFC is applied
+ * (see the module note).
+ */
+export declare function wellFormedText(text: string): string;
+/**
+ * {@link wellFormedText} over a JSON-shaped value, so a whole result can be handed to a strict parser.
+ *
+ * Recursion rules, deliberately narrow — this member may repair strings but must never change a
+ * value's TYPE:
+ *
+ *  - strings are repaired with {@link wellFormedText};
+ *  - arrays are mapped (a new array; the input is never mutated);
+ *  - PLAIN records are rebuilt with well-formed keys and values. "Plain" means the prototype is
+ *    `Object.prototype` (an object literal) or `null` (`Object.create(null)`), and the object carries
+ *    no `toJSON` custom serialization. Object KEYS are repaired too: `JSON.stringify` emits a lone
+ *    surrogate in a property name verbatim, which breaks a strict parser exactly the same way;
+ *  - EVERYTHING ELSE — numbers, booleans, `null`, `undefined`, bigints, symbols, functions, and every
+ *    object that is not a plain record (`Date`, `RegExp`, `Map`, a class instance, anything with a
+ *    `toJSON`) — is returned AS-IS, by identity.
+ *
+ * Pure and type-preserving: the result is structurally identical to the input apart from lone
+ * surrogates, and the input value is never mutated.
+ */
+export declare function wellFormedDeep<T>(value: T): T;
+/**
+ * The pair of repairs every mission boundary needs. The plugin builds this from the base kit it
+ * loaded (`{ text: kit.wellFormedText, deep: kit.wellFormedDeep }`) and injects it; the core defaults
+ * to {@link LOCAL_WELL_FORMED}.
+ *
+ * The two members are separate because the boundaries are: a single model-written STRING (an
+ * analysis, a result, a correction, a command line) needs `text`, while a record or array that is
+ * about to be persisted or serialized (a `createRoot` input, a `children` array, a whole tool
+ * result, a dispatch view) needs `deep`. Both are pure.
+ */
+export interface WellFormedSource {
+    /** Repair one string (see {@link wellFormedText}). */
+    readonly text: (value: string) => string;
+    /** Repair every string in a JSON-shaped value (see {@link wellFormedDeep}). */
+    readonly deep: <T>(value: T) => T;
+}
+/**
+ * The degradation source: the local copy above. Used when the loaded base kit has no
+ * `wellFormedText` / `wellFormedDeep` (base absent, or older than interface v2).
+ */
+export declare const LOCAL_WELL_FORMED: WellFormedSource;

package/lib/types/claims.d.ts

@@ -0,0 +1,3 @@
+export declare function newClaimId(): string;
+export declare function isWorkerClaimId(sessionId: string): boolean;
+//# sourceMappingURL=claims.d.ts.map

package/lib/types/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/claims.ts"],"names":[],"mappings":"AASA,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE1D"}