@avantf/dsh-mission 0.3.0

package/lib/interface-version.json

@@ -0,0 +1,4 @@
+{
+  "baseVersion": "0.4.0",
+  "interfaceVersion": 3
+}

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

@@ -0,0 +1,100 @@
+/**
+ * Capacity vocabulary: how much of ONE machine a mission may occupy, and how the machine's own
+ * capacity is derived. Both are plain numbers, deliberately — this module never imports `node:os`
+ * (the core builds without Node types) and never guesses at the hardware.
+ *
+ * ## The two numbers, and why they are not the same
+ *
+ * - **`weight`** is declared by a NODE: "this mission will occupy about N cores-equivalent while it
+ *   runs". It defaults to 1, which is the ordinary slot every mission used to take.
+ * - **`capacity`** is derived for the HOST: how many of those units may run at once on this machine.
+ *
+ * The engine admits a candidate only while `Σ running.weight + candidate.weight ≤ capacity`. That is
+ * the master gate; `maxConcurrent` survives as a ceiling on the NUMBER of units (see `engine.ts`).
+ * Both are injected into the core as numbers, so every scheduling decision is deterministic under
+ * test; the machine reading itself happens at the plugin/host seam, in `resource.ts`'s probe.
+ *
+ * @module @avantf/mission-core/capacity
+ */
+/** Ceiling on derived capacity. 64 is far past any single machine this engine is meant to drive, and
+ *  it keeps a wild reading (a container reporting 4096 CPUs) from materialising 4000 claims. */
+export declare const CAPACITY_CEILING = 64;
+/** Parallelism assumed when the host cannot read the machine at all (chain step ④). */
+export declare const CAPACITY_FALLBACK_PARALLELISM = 4;
+/** Cores left to the host/UI: one, matching this family's long-standing `cores - 1` convention. The
+ *  engine itself, the owner's turns and the browser half all live on the same box. */
+export declare const RESERVED_CORES = 1;
+/**
+ * Where a capacity reading came from, in priority order. The literal is part of the start-up log
+ * (`capacity=N (source=…)`) and is therefore observed by operators, not just by tests.
+ */
+export type CapacitySource = 'config' | 'availableParallelism' | 'cores' | 'default';
+export interface CapacityInput {
+    /** Step ①: the operator's explicit number. Used AS GIVEN (clamped), with no `-1` reservation:
+     *  an explicit number is already the answer, and silently subtracting from it would make a
+     *  configured 4 mean 3. */
+    readonly configured?: number | null;
+    /** Step ②: `os.availableParallelism()` — respects cgroup quotas and CPU affinity. */
+    readonly availableParallelism?: number | null;
+    /** Step ③: `os.cpus().length` — the physical/logical core count, ignoring quotas. */
+    readonly cores?: number | null;
+}
+export interface CapacityReading {
+    /** The number the engine gates on. */
+    readonly capacity: number;
+    readonly source: CapacitySource;
+    /** The raw parallelism the source reported, BEFORE the host reservation and the clamp. */
+    readonly parallelism: number;
+    /** Cores withheld from the engine: 1 for a derived reading, 0 for an explicit configuration. */
+    readonly reserved: number;
+}
+/** Clamp one capacity into `[1, CAPACITY_CEILING]`; a non-number degrades to the floor. */
+export declare function clampCapacity(value: number): number;
+/**
+ * The derivation chain, in ONE pure function so "which source won" is decided (and tested) in one
+ * place:
+ *
+ * ① explicit config → ② `os.availableParallelism()` → ③ `os.cpus().length` → ④ 4,
+ * then `capacity = clamp(max(1, derived - RESERVED_CORES), 1, CAPACITY_CEILING)`.
+ *
+ * Step ① is the exception to the reservation: an explicit number is used as-is (clamped). Measured
+ * on the development host (2026-10-02): `availableParallelism` = 12 → capacity 11, `cpus().length`
+ * = 12, cgroup `cpu.max` = `max 100000` (no quota).
+ */
+export declare function deriveCapacity(input?: CapacityInput): CapacityReading;
+/** The weight of a node that declares none: one ordinary slot. */
+export declare const DEFAULT_WEIGHT = 1;
+/** Lowest meaningful weight: a mission that runs at all occupies at least one slot. */
+export declare const MIN_WEIGHT = 1;
+/** Highest declared weight. Matches the capacity ceiling, so even a "give me the whole machine"
+ *  declaration (`weight` far above any real capacity) clamps to a number the engine can compare
+ *  without a special case; `weight > capacity` remains reachable on every real host. */
+export declare const MAX_WEIGHT = 64;
+/**
+ * Read a declared weight into range. Missing, dirty or non-numeric values read as
+ * {@link DEFAULT_WEIGHT}, exactly like a record written before the field existed; a fractional value
+ * floors; anything below 1 rises to 1 and anything above {@link MAX_WEIGHT} falls to it.
+ *
+ * This is the ONE normalizer: the tool layer, the persistence load path and `makeNode` all call it,
+ * so a weight cannot mean two different things in two places.
+ */
+export declare function normalizeWeight(raw: unknown): number;
+/**
+ * How long a node may be repeatedly deferred by the capacity gate before it RESERVES the machine:
+ * past this, no new node is admitted until the reserved one fits. Five minutes sits inside the
+ * recommended 3–10 minute band for one reason on each side: shorter windows turn an ordinary burst
+ * of weight-1 work into a reservation (which idles capacity the moment the heavy node cannot fit),
+ * while longer windows let a heavy mission wait through a whole work cycle before the engine stops
+ * feeding the queue in front of it.
+ */
+export declare const DEFAULT_CAPACITY_WAIT_MS: number;
+/** Floor on a configured aging window. Below a minute, a reservation is indistinguishable from a
+ *  scheduling hiccup, and work-conserving filling would be defeated by normal jitter. */
+export declare const MIN_CAPACITY_WAIT_MS: number;
+/**
+ * Default free-memory floor. A worker session is a model call plus tooling; below ~256 MiB the
+ * process is at real OOM risk. Deliberately low, because the host's floor signal is `os.freemem()`,
+ * which is a COARSE lower bound (see the probe) and a high threshold would stall ordinary work.
+ * `0` disables the gate.
+ */
+export declare const DEFAULT_MIN_FREE_MEMORY_BYTES: number;

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

@@ -0,0 +1,106 @@
+/**
+ * Continuation drift: what changed on a node since the prompt its session was handed, and the
+ * threshold at which continuing that session stops being honest.
+ *
+ * The question this answers is "what does a COLD WAKE owe the session it is about to resume?" A
+ * parked session is woken while its own picture is still current (it parked cleanly one turn ago);
+ * a session that was interrupted mid-thought may wake up over a node that moved underneath it. The
+ * delta is that difference, computed by subtracting the dispatch baseline the session's own prompt
+ * left behind.
+ *
+ * @module @avantf/mission-core/continuation
+ */
+import type { NodeRecord } from './types.js';
+/** The node's accumulating channels as the delta reads them. */
+export interface ContinuationDelta {
+    /** `false` when the node carries no baseline (a record written before the field existed, or one
+     * whose prompt was never built by this plugin). The counts below are then the conservative
+     * reading — never "nothing changed" — and the wake renders an honest caveat instead. */
+    readonly baselineKnown: boolean;
+    /** Corrections this session has NOT seen, in order. The union of two marks: the delivery
+     * watermark (`correctionsDeliveredUpTo`, advanced by a live steer or by a previous wake) and the
+     * baseline's own count (everything that already existed when this session's prompt was built and
+     * was therefore rendered into it). Taking the LATER of the two is what keeps a fresh spawn's
+     * corrections from being reported as unseen forever. On an unknown baseline it falls back to the
+     * watermark alone, which is exactly the previous generation's reading. */
+    readonly corrections: readonly string[];
+    /** Notes appended to the node since the baseline. Only a session that held the node can append,
+     * so these are normally the interrupted attempt's OWN notes — reported back so the resumed
+     * session sees what it had already concluded. */
+    readonly notes: readonly string[];
+    /** Children that reached a terminal state since the baseline. Rendered, never a reason to refuse
+     * the continuation; `0` when the baseline is unknown. */
+    readonly terminalChildren: number;
+    /** Whether title or description changed since the baseline; `false` when unknown. */
+    readonly titleOrContentChanged: boolean;
+    /** The node's latest analysis was written by somebody OTHER than the session this baseline belongs
+     * to, and the node carries notes at all. It is the closest thing the record has to "another
+     * executor has been writing this node's judgement", which is a freshness signal the next wake must
+     * not ignore.
+     *
+     * Compared by IDENTITY (`analysisAuthor` vs the baseline's `holder`) whenever both are known: the
+     * generation number alone misreads the common case this field exists for — a session's OWN note
+     * outliving its dispatch, which happens to every parent that wrote its analysis and decomposed.
+     * When either side is missing (a record written before the fields existed) it falls back to the
+     * generation comparison (`analysisAttempt` vs `baseline.attempts`), which is the conservative
+     * reading: a false positive only costs a fresh executor. */
+    readonly analysisFromAnotherDispatch: boolean;
+}
+/**
+ * A compact fingerprint of the mission HEADLINE (title + description), hashed rather than stored
+ * verbatim because a description can be long and this rides every node record; the fingerprint is
+ * only ever COMPARED, never read. Two 32-bit FNV-1a passes with different seeds (64 bits together)
+ * are far more than the "did somebody rewrite this mission" question needs, and the core stays
+ * dependency-free — it is deliberately built without `node:crypto`.
+ */
+export declare function nodeFingerprint(title: string, description: string): string;
+/**
+ * Subtract the node's dispatch baseline from its current state. Pure, so the arithmetic is testable
+ * without a tree.
+ *
+ * `terminalChildren` is passed in rather than read off the node because the node record carries
+ * child IDS, not their statuses.
+ */
+export declare function computeContinuationDelta(node: NodeRecord, terminalChildren: number): ContinuationDelta;
+/**
+ * Whether the drift since a session's own prompt is large enough that continuing it would be
+ * dishonest, and a fresh executor is the better answer.
+ *
+ * The rule is a disjunction of STRONG signals, each of which already carries its own threshold; it
+ * is deliberately not a weighted score, because every one of these means "this session's picture of
+ * the mission cannot be trusted", and there is no reading under which two weak signals should
+ * outvote one strong one.
+ *
+ * 1. `corrections` non-empty — the owner changed the direction of the mission while the session was
+ *    away. The session's plan was built under the old direction, and a correction handed to a
+ *    session that is already committed to a plan is exactly the case the fresh path is better at
+ *    (the new executor reads the correction before it reads anything else). This is also why the
+ *    delta's correction clause is normally empty: unread corrections do not reach the delta, they
+ *    change the route.
+ * 2. `analysisFromAnotherDispatch` — the node's latest analysis was written by somebody other than
+ *    this session, i.e. the node's judgement channel has been advanced by a different executor.
+ *    Conservative by construction: a false positive only costs a fresh executor, which is always a
+ *    correct answer, while a false negative would resume a session over a judgement it never wrote.
+ *    Compared by holder identity where the record carries it; the pre-identity generation comparison
+ *    is the fallback (see the field's own note).
+ * 3. `titleOrContentChanged` — the mission was re-defined under the session. It would be resuming a
+ *    mission it was never handed.
+ *
+ * **`terminalChildren` is deliberately absent, and this is a hard requirement.** For a PARKED
+ * session, "all children reached a terminal state" is not drift — it is the ENGINE's own trigger
+ * for the wake (`decompose_mission` is followed by a synchronous `pump()`, so the parent parks the
+ * moment its children are created). Counting it as material would demote every parked wake to a
+ * fresh spawn and delete the feature the previous generation shipped. Excluding it here means the
+ * exclusion survives even if a later change routes both wakes through one decision point; the
+ * regression is pinned by a test on both sides (`the parked session is woken, not replaced`).
+ *
+ * An UNKNOWN baseline answers `false`: the caller continues the session and says so honestly (the
+ * prompt renders "the drift cannot be determined, trust the current view over your memory"). The
+ * opposite choice — treat unknown as material — would throw the session away on the one-time
+ * migration of every in-flight mission, which is a permanent loss of context for a question the
+ * prompt can answer in one sentence. That also settles the one signal an unknown baseline could
+ * still offer: its `corrections` are the raw delivery-watermark tail, i.e. exactly what the previous
+ * generation rendered into the wake, and a record from before the baseline existed must keep being
+ * resumed on that reading rather than be re-judged by a rule it predates.
+ */
+export declare function isMaterialChange(delta: ContinuationDelta): boolean;

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

@@ -0,0 +1,165 @@
+import { type NodeRecord, type TreeRecord, type WaitingFor } from './types.js';
+/** One tree as the admission policy sees it. Structurally satisfied by `TreeState`, so this module
+ *  never imports the class that owns the state. */
+export interface DispatchScope {
+    readonly tree: TreeRecord;
+    readonly nodes: ReadonlyMap<string, NodeRecord>;
+}
+export declare function spawnBackoffMs(n: number): number;
+/** Order candidates: oldest first (cross-tree fairness), then by id for stability. */
+export declare function byCreatedAtThenId(a: NodeRecord, b: NodeRecord): number;
+/**
+ * A declared unit as stored: trimmed, path-normalized, and `null` for "nothing declared". A blank
+ * string is the way a caller opts OUT of a lease explicitly (see `@avantf/dsh-mission`'s tool layer),
+ * and it is the same value a missing field loads as, so the two cannot diverge.
+ *
+ * ## Why the lease key is normalized
+ *
+ * `unit` is model-authored free text, and the exclusion it buys is an exact string comparison. Two
+ * executors told to change the same directory will not necessarily spell it the same way — `a/b`,
+ * `a/b/`, `./a/b` and `a\b` are one scope to a human and four different lease keys to the engine, so
+ * the guarantee ("two parallel lanes never touch one file") held only when the two agents happened to
+ * type byte-identical text.
+ *
+ * The canonical form, chosen conservatively:
+ *
+ * - case: ASCII lower-cased, so `Mission/x` and `mission/x` are one lease. The tool text promises
+ *   this ("大小写、分隔符、结尾斜杠不同都算同一个范围") and Windows paths are case-insensitive; it is
+ *   deliberate that a case-SENSITIVE filesystem now serializes two spellings that would not actually
+ *   collide there — the safe direction is to keep the scope busy, not to hand it out twice.
+ * - separators: `\` reads as `/` (a Windows-authored path and a POSIX one name the same scope). At
+ *   most one leading `/` survives, so `//srv/x` (a UNC spelling) and `/srv/x` still differ by the
+ *   leading slash and are NOT conflated.
+ * - redundant separators collapse (`a//b` → `a/b`).
+ * - `.` segments are dropped and trailing separators are trimmed (`./a/b/` → `a/b`).
+ * - `..` segments are resolved LEXICALLY (`a/b/../c` → `a/c`), but a `..` that would escape the front
+ *   of the path is PRESERVED (`../a` stays `../a`), so distinctly-named scopes stay distinct. This is
+ *   textual, not filesystem-aware: no `realpath`, no cwd, no symlink resolution — resolving against
+ *   the real filesystem would make the lease depend on which process asked, and the core has no cwd.
+ *
+ * **What this still does not cover (v1, declared in `mission/docs/design/2026-10-02-unit-lease.md`):
+ * containment.** `a` and `a/b` remain two different keys, so a parent directory and a file inside it
+ * are not mutually exclusive. Only the identical-scope case is guaranteed; a caller that wants
+ * isolation must name the exact same scope on both nodes (the tool text recommends a path relative
+ * to the repository root, e.g. `mission/packages/core`).
+ */
+export declare function normalizeUnit(raw: string | null | undefined): string | null;
+/**
+ * The unit a decomposed child runs under. `undefined` — the spec said nothing — INHERITS the
+ * parent's unit, which is the safe default: siblings of one decomposition then cannot run at the
+ * same time. An explicit value (including a blank string = "no lease") overrides that.
+ */
+export declare function resolveChildUnit(parentUnit: string | null, declared: string | null | undefined): string | null;
+/**
+ * A child's weight. `undefined` — the spec said nothing — does NOT inherit the parent's estimate:
+ * a parent that needs 8 cores may be split into children that need 1 each, and inheriting would
+ * re-serialize work the decomposition just made parallel. Anything declared is clamped by
+ * {@link normalizeWeight}, the same normalizer every other entry point uses.
+ */
+export declare function resolveChildWeight(declared: number | undefined): number;
+/** Every unit currently held by a `running` node, ACROSS every tree: a collision is cross-root by
+ *  nature (two owners' missions that touch one file collide exactly like two siblings), so a
+ *  per-tree answer would not describe the resource. */
+export declare function heldUnits(scopes: Iterable<DispatchScope>): ReadonlySet<string>;
+/**
+ * The `running` node holding `unit`, if any, excluding `exceptId` (the node asking). `undefined`
+ * means the unit is free. The scan deliberately spans every tree, including closed ones: a running
+ * node holds its lease no matter which tree it belongs to, and the safe direction is to keep the
+ * unit busy rather than to hand it out twice.
+ */
+export declare function unitHolder(scopes: Iterable<DispatchScope>, unit: string, exceptId?: string): NodeRecord | undefined;
+/**
+ * The live admission arithmetic the capacity gate needs. Supplied by the engine (it owns the aging
+ * clock and the per-node "deferred since" memory); absent means the gate is OPEN, which is exactly
+ * how the engine behaved before capacity existed and keeps `MissionTree.nextDispatchable()`'s
+ * low-level contract unchanged.
+ */
+export interface CapacityPolicy {
+    /** Master gate, in the same unit as `weight`. */
+    readonly capacity: number;
+    /** Backstop on the NUMBER of running units (`maxConcurrent`). */
+    readonly maxConcurrent: number;
+    readonly runningCount: number;
+    readonly runningWeight: number;
+    /** Node id → the time the capacity gate first deferred it. Drives aging; the engine owns it so a
+     *  test can move the injected clock instead of waiting. */
+    readonly deferredSince: ReadonlyMap<string, number>;
+    /** Wait past which a deferred node RESERVES the machine (no new admissions until it fits). */
+    readonly agingMs: number;
+    readonly now: number;
+    /** A machine-wide gate (the free-memory floor) that blocks EVERY dispatch while set. */
+    readonly globalBlock?: WaitingFor;
+}
+/** One candidate the plan did not select, with the reason it is waiting. */
+export interface DeferredCandidate {
+    readonly node: NodeRecord;
+    readonly waitingFor: WaitingFor;
+}
+/**
+ * The machine-side half of the admission arithmetic: what the gate compares a candidate against.
+ * Deliberately split from {@link CapacityPolicy}, which adds the caller's SNAPSHOT of the load, the
+ * aging clock and the machine-wide block. The lock-held recheck takes these numbers as given but
+ * FILLS THEM FROM LIVE STATE (`MissionTree.runningLoad()`), which is exactly why the shared judgement
+ * cannot read the policy's snapshot itself.
+ */
+export interface CapacityLoad {
+    /** Master gate, in the same unit as `weight`. */
+    readonly capacity: number;
+    /** Backstop on the NUMBER of running units (`maxConcurrent`). */
+    readonly maxConcurrent: number;
+    readonly runningCount: number;
+    readonly runningWeight: number;
+}
+/**
+ * The ONE capacity judgement, shared by {@link planDispatch} and by the tree's lock-held recheck so
+ * the two can never drift: `undefined` when `node` may be admitted right now, otherwise the
+ * structured reason it must wait.
+ *
+ * The rule: a candidate heavier than the whole machine (`weight > capacity`) is EXCLUSIVE and fits
+ * only when nothing else is running — the arithmetic form of "it is the reservation that waited the
+ * longest"; otherwise `Σ running.weight + weight ≤ capacity`. In both cases the `maxConcurrent` slot
+ * ceiling must have room. The reason keeps the projection's long-standing precedence: capacity
+ * (the master gate) before the slot ceiling.
+ */
+export declare function capacityWaitingFor(node: NodeRecord, load: CapacityLoad): WaitingFor | undefined;
+/** What one admission scan resolved to. */
+export interface DispatchPlan {
+    readonly selected: NodeRecord | undefined;
+    /** Every candidate examined and left behind, in FIFO order, with its live waiting reason. */
+    readonly deferred: readonly DeferredCandidate[];
+    /**
+     * True when an aged node has RESERVED the machine and does not fit yet: the caller must not admit
+     * anything else this pass. `selected` is then `undefined` by construction.
+     */
+    readonly reserved: boolean;
+}
+/** What {@link selectNextDispatchable} needs to know beyond the node states themselves. */
+export interface DispatchPolicy {
+    /** Node ids already spoken for in this pass; they must not be selected twice. */
+    readonly exclude?: ReadonlySet<string>;
+    readonly now: number;
+    readonly isAgentLive: (sessionId: string) => boolean;
+    /** Capacity/slot admission arithmetic; absent means "no capacity gate" (the legacy contract). */
+    readonly capacity?: CapacityPolicy;
+}
+/**
+ * The next node to dispatch, or `undefined`. Kept as the simple projection of {@link planDispatch}
+ * for callers that only need the answer (and for the pre-capacity contract).
+ */
+export declare function selectNextDispatchable(scopes: Iterable<DispatchScope>, policy: DispatchPolicy): NodeRecord | undefined;
+/**
+ * The full admission scan: pick at most one node to dispatch AND describe every candidate left
+ * behind. Selection rules, in order:
+ *
+ * 1. Collect the eligible candidates exactly as the pre-capacity engine did (open tree, live owner,
+ *    not excluded, dispatchable, no live binding, no parked session, no held unit, not in spawn
+ *    backoff), FIFO by {@link byCreatedAtThenId}.
+ * 2. A machine-wide block (the free-memory floor) defers everything, nothing ages, no reservation.
+ * 3. The slot ceiling, if reached, defers everything (capacity may still have room).
+ * 4. An AGED candidate (waiting for capacity at least `agingMs`) that is not unit-blocked takes the
+ *    machine: if it fits — or it is heavier than the whole capacity and nothing is running — it is
+ *    selected; otherwise `reserved` is true and nothing else is admitted.
+ * 5. Otherwise the first FITTING candidate in FIFO order is selected, skipping heavier ones, so
+ *    spare capacity is filled (work-conserving).
+ */
+export declare function planDispatch(scopes: Iterable<DispatchScope>, policy: DispatchPolicy): DispatchPlan;