@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/_lib/continuity_slot.ts

@@ -0,0 +1,295 @@
+/**
+ * The continuity-record slot — capacity policy and state machine.
+ *
+ * `road-to-continuity-writer-activation` step 1.1. Until this module existed
+ * the slot had a producer (`session:recycle`), a consumer
+ * (`handoff_context_hook`) and no documented conflict ownership: the write was
+ * an unguarded `atomic_write_json`, so a second publish replaced whatever sat
+ * there and nobody had decided whether that was correct. With a MANUAL producer
+ * the question was theoretical — a human ran the verb once. Automatic
+ * production makes it routine, which is why the policy is settled here BEFORE
+ * any automatic writer exists.
+ *
+ * The full contract, including why the two rejected alternatives are rejected
+ * on tree evidence rather than on preference, is
+ * `docs/contracts/continuity-record-slot.md`. This module is that document in
+ * code; neither is the source of truth for the other's reasoning, and both are
+ * checked by `tests/scripts/_lib_continuity_slot.test.ts`.
+ *
+ * The policy in one line:
+ *
+ *   SUPERSEDE OWN · REFUSE FOREIGN · QUARANTINE UNUSABLE · NEVER GO BACKWARDS.
+ *
+ * Why not create-if-absent.
+ *
+ * Create-if-absent is the policy the roadmap's own Risk 2 describes as a silent
+ * data loss: "the successor resumes from something plausible and older". It is
+ * rejected. Within one session the resident and the incoming record share a
+ * key, a workspace and a predecessor — the incoming one is the same lineage at
+ * a later moment, so keeping the older is a pure loss with no compensating
+ * safety.
+ *
+ * Why not a bounded multi-record queue.
+ *
+ * Because the reader forbids the resolution such a queue would need. Picking
+ * one of several records requires recency, and `recycle_envelope_paths.ts`
+ * carries a recorded decision against exactly that ("No `latest` index, by
+ * decision" — a pointer to the newest "would restore the shared write target
+ * one layer up"). `resolveContinuityRecord` implements it: several candidates
+ * and no session id START CLEAN rather than pick. A queue would either
+ * contradict that lock or be unreadable.
+ *
+ * Where `consuming` lives.
+ *
+ * Nowhere on disk, and that is the answer rather than a gap. Consumption is a
+ * single `fs.renameSync` from the authoritative name to the consumed name
+ * (`handoff_context_hook.ts:199`), and publication is a single `fs.renameSync`
+ * from a pid-suffixed temp name to the authoritative name
+ * (`state_io.ts:_publish_text_locked`). A rename within one directory is
+ * atomic on every filesystem this package supports, so an interruption lands
+ * strictly before or strictly after it: the authoritative name holds either the
+ * previous complete record or the new complete record, never a partial one.
+ * `consuming` is therefore a transition, not a state, and no reader has to
+ * tolerate a half-written record.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    recycle_consumed_rel,
+    recycle_envelope_rel,
+    recycle_quarantine_rel,
+    RECYCLE_ENVELOPE_MAX_BYTES,
+    RECYCLE_MAX_AGE_HOURS,
+} from './recycle_envelope_paths.js';
+import { validateRecycleEnvelope } from './subagent_capsule.js';
+import { update_json_under_lock } from '../hooks/state_io.js';
+
+/**
+ * The slot's states.
+ *
+ * Five are observable on disk. `consuming` is declared because the roadmap step
+ * names it and a reader looking for it deserves to find the reason it is not a
+ * disk state rather than to conclude it was forgotten — see the module header.
+ */
+export const SLOT_STATES = [
+    'absent',
+    'published',
+    'consuming',
+    'consumed',
+    'quarantined',
+    'conflicting',
+] as const;
+export type SlotState = (typeof SLOT_STATES)[number];
+
+/** What a publish attempt did, and why. The reason is always present. */
+export interface PublishOutcome {
+    /** `published` on a write; otherwise the state that refused it. */
+    state: SlotState;
+    /** Did the authoritative record change as a result of this call? */
+    wrote: boolean;
+    /** One line, always present — emitted by callers, never dropped. */
+    reason: string;
+    /** Absolute path of the record moved aside, when one was. */
+    quarantined?: string;
+}
+
+/** What {@link inspectSlot} found, without changing anything. */
+export interface SlotInspection {
+    state: SlotState;
+    reason: string;
+    /** The authoritative path this session's records live at. */
+    target: string;
+    /** Parsed resident record, when one is present AND parseable. */
+    resident?: Record<string, unknown>;
+}
+
+/** Hours a record stays usable — the reader's own bound, not a second one. */
+const MAX_AGE_MS = RECYCLE_MAX_AGE_HOURS * 3600 * 1000;
+
+function _parse(file: string): Record<string, unknown> | null {
+    try {
+        const decoded: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (typeof decoded === 'object' && decoded !== null && !Array.isArray(decoded)) {
+            return decoded as Record<string, unknown>;
+        }
+        return null;
+    } catch {
+        return null;
+    }
+}
+
+/** Milliseconds since a record's `written_at`, or `null` when it has none. */
+function _ageMs(record: Record<string, unknown>, now: Date): number | null {
+    const raw = record['written_at'];
+    if (typeof raw !== 'string') return null;
+    const at = Date.parse(raw);
+    if (Number.isNaN(at)) return null;
+    return now.getTime() - at;
+}
+
+/**
+ * Read the slot for `session_id` without touching it.
+ *
+ * `conflicting` here is a statement about the RESIDENT relative to the caller's
+ * identity, which is why the session id is required rather than optional: a
+ * record is foreign only with respect to somebody.
+ */
+export function inspectSlot(
+    workspace_root: string,
+    session_id: string | null | undefined,
+    now: Date = new Date(),
+): SlotInspection {
+    const target = path.join(workspace_root, recycle_envelope_rel(session_id));
+    if (!fs.existsSync(target)) {
+        const consumed = path.join(workspace_root, recycle_consumed_rel(session_id));
+        if (fs.existsSync(consumed)) {
+            return { state: 'consumed', reason: 'the record for this session was consumed', target };
+        }
+        const quarantined = path.join(workspace_root, recycle_quarantine_rel(session_id));
+        if (fs.existsSync(quarantined)) {
+            return {
+                state: 'quarantined',
+                reason: 'the slot is free; an unusable record sits in quarantine',
+                target,
+            };
+        }
+        return { state: 'absent', reason: 'no record in this slot', target };
+    }
+    const resident = _parse(target);
+    if (resident === null) {
+        return { state: 'quarantined', reason: 'the resident record does not parse as an object', target };
+    }
+    const violations = validateRecycleEnvelope(resident);
+    if (violations.length > 0) {
+        return {
+            state: 'quarantined',
+            reason: `the resident record fails validation (${violations.length} violation(s))`,
+            target,
+            resident,
+        };
+    }
+    const age = _ageMs(resident, now);
+    if (age === null || age > MAX_AGE_MS) {
+        return {
+            state: 'quarantined',
+            reason:
+                age === null
+                    ? 'the resident record carries no parseable written_at'
+                    : `the resident record is older than ${RECYCLE_MAX_AGE_HOURS} h`,
+            target,
+            resident,
+        };
+    }
+    const owner = String(resident['session_id'] ?? '').trim();
+    const mine = String(session_id ?? '').trim();
+    if (owner !== '' && mine !== '' && owner !== mine) {
+        return {
+            state: 'conflicting',
+            reason: `the slot holds an unconsumed record belonging to session ${owner}`,
+            target,
+            resident,
+        };
+    }
+    return { state: 'published', reason: 'this session has an unconsumed record', target, resident };
+}
+
+/**
+ * Publish `record` into this session's slot under the capacity policy.
+ *
+ * Never throws for a policy reason: a refusal is a return value, because this
+ * runs on the Stop path where an exception is a worse outcome than a missed
+ * record. A genuine I/O failure is reported as `wrote: false` with the reason,
+ * for the same reason.
+ *
+ * The write itself goes through {@link update_json_under_lock} rather than
+ * `atomic_write_json`, and the difference is the whole point: the locked form
+ * gives a read-modify-write, so the resident is inspected and the decision
+ * taken INSIDE the exclusion that stops a peer from publishing between the
+ * inspection and the write. `atomic_write_json` — the path
+ * `session:recycle` still uses — has no such window and cannot express a
+ * refusal.
+ */
+export function publishContinuityRecord(
+    workspace_root: string,
+    session_id: string | null | undefined,
+    record: Record<string, unknown>,
+    now: Date = new Date(),
+): PublishOutcome {
+    const violations = validateRecycleEnvelope(record);
+    if (violations.length > 0) {
+        return {
+            state: 'absent',
+            wrote: false,
+            reason: `refused — the record to publish fails validation: ${violations[0] as string}`,
+        };
+    }
+    const bytes = Buffer.byteLength(JSON.stringify(record, null, 2), 'utf-8');
+    if (bytes > RECYCLE_ENVELOPE_MAX_BYTES) {
+        return {
+            state: 'absent',
+            wrote: false,
+            reason: `refused — ${bytes} bytes exceeds the ${RECYCLE_ENVELOPE_MAX_BYTES} byte slot cap`,
+        };
+    }
+
+    const target = path.join(workspace_root, recycle_envelope_rel(session_id));
+    const before = inspectSlot(workspace_root, session_id, now);
+
+    // A foreign, still-usable record is not this session's to move or replace.
+    // Refusing costs this session's resume; superseding costs another session's,
+    // and that one has no way to find out.
+    if (before.state === 'conflicting') {
+        return { state: 'conflicting', wrote: false, reason: `refused — ${before.reason}` };
+    }
+
+    // Monotonicity. A delayed or retried publisher must not roll the slot back
+    // to an earlier moment of the same session.
+    if (before.state === 'published' && before.resident !== undefined) {
+        const residentAt = Date.parse(String(before.resident['written_at'] ?? ''));
+        const incomingAt = Date.parse(String(record['written_at'] ?? ''));
+        if (!Number.isNaN(residentAt) && !Number.isNaN(incomingAt) && incomingAt < residentAt) {
+            return {
+                state: 'published',
+                wrote: false,
+                reason: 'refused — the resident record is newer than the one offered',
+            };
+        }
+    }
+
+    let quarantined: string | undefined;
+    if (before.state === 'quarantined' && fs.existsSync(target)) {
+        // Move aside, never delete. See `recycle_quarantine_rel`.
+        const dest = path.join(workspace_root, recycle_quarantine_rel(session_id));
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.renameSync(target, dest);
+            quarantined = dest;
+        } catch (exc) {
+            return {
+                state: 'quarantined',
+                wrote: false,
+                reason: `refused — could not quarantine the unusable resident: ${String(exc)}`,
+            };
+        }
+    }
+
+    const result = update_json_under_lock<Record<string, unknown>>(target, () => record);
+    if (result !== 'written') {
+        return {
+            state: before.state,
+            wrote: false,
+            reason: `refused — the slot write did not complete (${result})`,
+            ...(quarantined !== undefined ? { quarantined } : {}),
+        };
+    }
+    return {
+        state: 'published',
+        wrote: true,
+        reason:
+            before.state === 'published'
+                ? 'superseded this session’s earlier record'
+                : `published into a ${before.state} slot`,
+        ...(quarantined !== undefined ? { quarantined } : {}),
+    };
+}

package/src/scripts/_lib/continuity_surface.ts

@@ -0,0 +1,296 @@
+/**
+ * Continuity-surface inventory — the behavioural half of the ratchet.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `road-to-one-continuity-record` measured its own success as five numbers —
+ * public continuity commands, session resume pickers, persistent continuity
+ * artefacts, continuity schemas, normal-path manual actions — and its council
+ * of 2026-09-07 named the defect in measuring them by name:
+ *
+ *   "Any persisted state written for later session/run recovery, verification,
+ *   or context restoration must be listed, whether or not it is labeled
+ *   continuity."
+ *
+ * A count keyed on the WORD `continuity` is gameable by renaming. So the
+ * artefact axis is DISCOVERED behaviourally — every distinct leaf under
+ * `agents/runtime/state/` that any source file names — and the inventory then
+ * has to dispose of each one as `counted` or `excluded` WITH A REASON. A leaf
+ * nothing disposes of is a hard failure, which is what makes a newly added
+ * persisted-state surface impossible to slip past the count silently.
+ *
+ * The exclusions are the load-bearing half, not the leftovers. `checkpoints/`
+ * is the worked example the council named: it is kept (D2 — run-integrity
+ * evidence is keyed by run id, consumed by `run:supervise`, and a disagreement
+ * there is an integrity alarm rather than a degraded resume), so it is excluded
+ * from the continuity axis, and that exclusion is PRINTED on every run rather
+ * than buried in a predicate.
+ *
+ * WHAT THIS MODULE IS NOT
+ * -----------------------
+ * It does not decide policy. It reads a committed inventory, checks that the
+ * inventory still describes the tree (every `locus` resolves; every discovered
+ * leaf is disposed of), and derives the five numbers from the dispositions.
+ * The ratchet that forbids growth lives in `check_continuity_surface.ts`, which
+ * runs these same functions over a materialised base tree.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Repo-relative POSIX path of the committed inventory. */
+export const INVENTORY_POSIX = 'src/config/continuity-surface.json';
+
+/** Source roots the behavioural discovery walks. */
+export const DISCOVERY_ROOTS: readonly string[] = [
+    'src/scripts',
+    'src/agent-src/scripts',
+    'src/cli',
+    'src/shared',
+    'src/server',
+    'src/install',
+];
+
+/**
+ * The five axes, in the order the parent roadmap's goal states them. The order
+ * is part of the contract: the goal reads `0 / 0 / 1 / 1 / 0` positionally, and
+ * a reader comparing a run against that line needs the same positions.
+ */
+export const AXES = [
+    'public_continuity_commands',
+    'session_resume_pickers',
+    'persistent_continuity_artefacts',
+    'continuity_schemas',
+    'normal_path_manual_actions',
+] as const;
+
+export type Axis = (typeof AXES)[number];
+
+/** The target the parent roadmap's goal states, by axis. */
+export const TARGETS: Readonly<Record<Axis, number>> = {
+    public_continuity_commands: 0,
+    session_resume_pickers: 0,
+    persistent_continuity_artefacts: 1,
+    continuity_schemas: 1,
+    normal_path_manual_actions: 0,
+};
+
+export interface InventoryRow {
+    /** Stable identifier. For a discovered artefact this is the state leaf. */
+    id: string;
+    /** Which axis this row belongs to. */
+    axis: Axis;
+    /** `counted` contributes to the axis number; `excluded` does not. */
+    disposition: 'counted' | 'excluded';
+    /**
+     * Repo-relative `file` or `file:line` the row is anchored to. It must
+     * resolve, which is what makes a retirement MEASURED: deleting the surface
+     * without deleting or re-disposing its row reddens.
+     */
+    locus: string;
+    /**
+     * Why. Mandatory on every row, not only on exclusions — a `counted` row
+     * whose reason nobody wrote is a number without a meaning.
+     */
+    reason: string;
+}
+
+export interface Inventory {
+    rows: readonly InventoryRow[];
+}
+
+/** A leaf the discovery found, with the first source position that names it. */
+export interface DiscoveredLeaf {
+    leaf: string;
+    locus: string;
+}
+
+const LEAF_RE =
+    /agents\/runtime\/state\/([A-Za-z0-9_.-]+)|['"]runtime['"],\s*['"]state['"],\s*['"]([A-Za-z0-9_.-]+)['"]/g;
+
+const SOURCE_EXT = /\.(ts|js|mjs|sh|bash)$/;
+
+function _walk(dir: string, out: string[]): void {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            _walk(full, out);
+            continue;
+        }
+        if (!SOURCE_EXT.test(entry.name)) continue;
+        // Test files name state paths in fixtures; a fixture is not a surface.
+        if (entry.name.endsWith('.test.ts')) continue;
+        out.push(full);
+    }
+}
+
+/**
+ * Every distinct `agents/runtime/state/<leaf>` any source file names, with the
+ * first `file:line` that names it. Sorted, so two runs over the same tree
+ * produce byte-identical output and a diff of the count is a diff of the tree.
+ */
+export function discoverStateLeaves(root: string): DiscoveredLeaf[] {
+    const files: string[] = [];
+    for (const rel of DISCOVERY_ROOTS) {
+        _walk(path.join(root, rel), files);
+    }
+    files.sort();
+    const found = new Map<string, string>();
+    for (const file of files) {
+        let text: string;
+        try {
+            text = fs.readFileSync(file, 'utf-8');
+        } catch {
+            continue;
+        }
+        const rel = path.relative(root, file).split(path.sep).join('/');
+        const lines = text.split('\n');
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? '';
+            LEAF_RE.lastIndex = 0;
+            let match: RegExpExecArray | null;
+            while ((match = LEAF_RE.exec(line)) !== null) {
+                const raw = match[1] ?? match[2] ?? '';
+                // A trailing dot is string concatenation in the source
+                // (`'...json' + '.tmp'`), never part of the leaf name.
+                const leaf = raw.replace(/\.+$/, '');
+                if (leaf === '' || leaf === '.') continue;
+                if (!found.has(leaf)) found.set(leaf, `${rel}:${String(i + 1)}`);
+            }
+        }
+    }
+    return [...found.keys()].sort().map((leaf) => ({ leaf, locus: found.get(leaf) ?? '' }));
+}
+
+export function readInventory(root: string): Inventory {
+    const file = path.join(root, INVENTORY_POSIX);
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8')) as { rows?: unknown };
+    const rows = Array.isArray(parsed.rows) ? (parsed.rows as InventoryRow[]) : [];
+    return { rows };
+}
+
+/** Does a `file` or `file:line` locus still resolve in this tree? */
+export function locusResolves(root: string, locus: string): boolean {
+    const match = /^(.*?):(\d+)$/.exec(locus);
+    const rel = match ? (match[1] ?? '') : locus;
+    const target = path.join(root, rel);
+    let stat: fs.Stats;
+    try {
+        stat = fs.statSync(target);
+    } catch {
+        return false;
+    }
+    if (!match) return true;
+    if (!stat.isFile()) return false;
+    // A line anchor must still BE a line. Content is deliberately not compared:
+    // a locus that pins prose would rot on every reflow and turn the inventory
+    // into a line-number chore, which is how anchor checks get deleted.
+    const line = Number(match[2]);
+    let text: string;
+    try {
+        text = fs.readFileSync(target, 'utf-8');
+    } catch {
+        return false;
+    }
+    return line >= 1 && line <= text.split('\n').length;
+}
+
+export interface SurfaceCounts {
+    public_continuity_commands: number;
+    session_resume_pickers: number;
+    persistent_continuity_artefacts: number;
+    continuity_schemas: number;
+    normal_path_manual_actions: number;
+}
+
+export function countAxes(inv: Inventory): SurfaceCounts {
+    const counts = {
+        public_continuity_commands: 0,
+        session_resume_pickers: 0,
+        persistent_continuity_artefacts: 0,
+        continuity_schemas: 0,
+        normal_path_manual_actions: 0,
+    };
+    for (const row of inv.rows) {
+        if (row.disposition !== 'counted') continue;
+        if (!AXES.includes(row.axis)) continue;
+        counts[row.axis] += 1;
+    }
+    return counts;
+}
+
+export interface InventoryFinding {
+    kind: 'undisposed-leaf' | 'dead-locus' | 'bad-row' | 'duplicate-row';
+    detail: string;
+}
+
+/**
+ * Validate the inventory against the tree.
+ *
+ * Three failure classes, and each exists because a specific way of faking a
+ * lower number would otherwise work:
+ *
+ *   - `undisposed-leaf` — a persisted-state leaf the source names and the
+ *     inventory does not mention. This is the add-a-surface-quietly route.
+ *   - `dead-locus` — a row anchored to something that no longer exists. This
+ *     is the claim-a-retirement-that-did-not-happen route in reverse: it forces
+ *     the row to be deleted (a real subtraction) rather than left standing.
+ *   - `bad-row` / `duplicate-row` — shape defects that would make either of the
+ *     above unenforceable.
+ */
+export function validateInventory(
+    root: string,
+    inv: Inventory,
+    discovered: readonly DiscoveredLeaf[],
+): InventoryFinding[] {
+    const findings: InventoryFinding[] = [];
+    const seen = new Set<string>();
+    for (const row of inv.rows) {
+        const id = typeof row.id === 'string' ? row.id : '';
+        if (id === '') {
+            findings.push({ kind: 'bad-row', detail: 'a row carries no `id`' });
+            continue;
+        }
+        if (seen.has(id)) {
+            findings.push({ kind: 'duplicate-row', detail: `two rows share the id \`${id}\`` });
+        }
+        seen.add(id);
+        if (!AXES.includes(row.axis)) {
+            findings.push({ kind: 'bad-row', detail: `\`${id}\`: unknown axis \`${String(row.axis)}\`` });
+        }
+        if (row.disposition !== 'counted' && row.disposition !== 'excluded') {
+            findings.push({
+                kind: 'bad-row',
+                detail: `\`${id}\`: disposition must be \`counted\` or \`excluded\`, got \`${String(row.disposition)}\``,
+            });
+        }
+        if (typeof row.reason !== 'string' || row.reason.trim().length < 20) {
+            findings.push({
+                kind: 'bad-row',
+                detail: `\`${id}\`: every row needs a reason of substance — a number without a stated meaning is not an inventory`,
+            });
+        }
+        if (typeof row.locus !== 'string' || row.locus.trim() === '') {
+            findings.push({ kind: 'bad-row', detail: `\`${id}\`: no \`locus\`` });
+        } else if (!locusResolves(root, row.locus)) {
+            findings.push({
+                kind: 'dead-locus',
+                detail: `\`${id}\`: locus \`${row.locus}\` does not resolve — if the surface was retired, DELETE the row (that is the subtraction); if it moved, re-anchor it`,
+            });
+        }
+    }
+    for (const item of discovered) {
+        if (!seen.has(item.leaf)) {
+            findings.push({
+                kind: 'undisposed-leaf',
+                detail: `\`${item.leaf}\` (${item.locus}) is persisted state under agents/runtime/state/ that the inventory does not dispose of — add a row with \`disposition: counted\` (it is continuity state) or \`disposition: excluded\` with the reason it is not`,
+            });
+        }
+    }
+    return findings;
+}