@reticlehq/server 2.11.0 → 2.12.0

package/dist/intent/inline-intent.js

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto';
+import { IntentStore } from './intent-store.js';
+import { sessionRoot } from '../project/session-root.js';
+/**
+ * Intent declared INLINE, on the tool that is already drawing the verdict.
+ *
+ * `reticle_intent` is on the extended surface, so declaring intent costs an agent a discovery, a
+ * decision and a round trip before it has done anything — three places the capture silently fails,
+ * and it does. `reticle_act_and_wait` and `reticle_assert` are in every agent's tool list already,
+ * so one optional argument there makes the declaration free and discoverable by construction.
+ *
+ * This is a shortcut into the EXISTING ledger, never a second one. It writes `.reticle/intent.json`
+ * through `IntentStore` exactly as `reticle_intent { action: "declare" }` does, so a reviewer reads
+ * one file in one vocabulary and cannot tell from the row which door the intent came in by. The
+ * pattern is `flows/flow-intent.ts`, which does the same job for a saved flow.
+ */
+/** Namespaced like `flow:`, so an inline id never collides with one an agent chose by hand. */
+const INLINE_INTENT_ID_PREFIX = 'inline:';
+const ID_SEPARATOR = ':';
+const SLUG_SEPARATOR = '-';
+const SLUG_MAX = 48;
+const HASH_LENGTH = 8;
+const HASH_ALGORITHM = 'sha1';
+const NON_SLUG = /[^a-z0-9]+/g;
+const SLUG_EDGES = /^-+|-+$/g;
+/**
+ * The ledger id a piece of inline prose is declared under.
+ *
+ * Derived from the statement rather than minted, so the same sentence declared on five verdicts is
+ * one row rather than five, and a DIFFERENT sentence is a different row rather than a false
+ * amendment of the first. The slug is there because the id is what an agent later types to reference
+ * the intent, and a bare digest is unreadable; the digest is there because the slug is truncated and
+ * two long statements sharing a prefix must not share a row.
+ */
+export function inlineIntentId(statement) {
+    const slug = statement
+        .toLowerCase()
+        .replace(NON_SLUG, SLUG_SEPARATOR)
+        .replace(SLUG_EDGES, '')
+        .slice(0, SLUG_MAX)
+        .replace(SLUG_EDGES, '');
+    const digest = createHash(HASH_ALGORITHM).update(statement).digest('hex').slice(0, HASH_LENGTH);
+    return `${INLINE_INTENT_ID_PREFIX}${slug}${SLUG_SEPARATOR}${digest}`;
+}
+/** What `provenBy` records: which tool drew the verdict, and when. */
+export function inlineVerdictId(tool, at) {
+    return `${tool}${ID_SEPARATOR}${String(at)}`;
+}
+/**
+ * Put an inline intent in the ledger and attach the predicate about to be evaluated. Returns the id
+ * the verdict may later discharge, or undefined when there was no intent to record.
+ *
+ * `intent` carries EITHER prose OR the id of an intent already in the ledger. One field rather than
+ * two because the surface is the scarce thing here and the two cases are told apart by the ledger
+ * itself: a string that names an existing row is a reference, anything else is prose. A statement
+ * that happens to equal an existing id is the same intent said twice, so pointing at the row is the
+ * right answer there too, not a collision.
+ *
+ * A referenced intent is never re-declared, which would overwrite the agent's own words with an id,
+ * and its binding is left alone when it already has one — a predicate bound deliberately through
+ * `reticle_intent { action: "bind" }` is a stronger statement than whatever this one call asserts,
+ * and quietly replacing it is exactly the narrowing the ledger exists to make visible.
+ *
+ * Best-effort by construction: a ledger that cannot be written is a small problem, and a verdict
+ * that fails to return because of one is a large problem.
+ */
+export async function linkInlineIntent(deps, sessionId, intent, 
+/** The predicate this verdict will evaluate, or undefined when it proves nothing (a bare settle). */
+binding) {
+    if (intent === undefined || 0 === intent.trim().length)
+        return undefined;
+    try {
+        const store = new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now });
+        const existing = (await store.read()).find((row) => row.id === intent);
+        const id = existing?.id ?? inlineIntentId(intent);
+        if (existing === undefined)
+            await store.declare([{ id, statement: intent }]);
+        if (binding !== undefined && existing?.binding === undefined)
+            await store.bind(id, binding);
+        return id;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Record that this verdict proved the intent. Call only for a verdict that actually proved something.
+ *
+ * The ledger's own rule does the rest: `dischargeIntent` refuses an intent with no binding, so an
+ * intent declared inline on a wait that asserted no consequence stays open and honest instead of
+ * collecting a proof nothing earned.
+ */
+export async function dischargeInlineIntent(deps, sessionId, id, proof) {
+    if (id === undefined)
+        return;
+    try {
+        const store = new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now });
+        await store.discharge(id, proof);
+    }
+    catch {
+        // The verdict already stood. The proof is simply not recorded — see dischargeFlowIntent.
+    }
+}

package/dist/intent/intent-store.d.ts

@@ -0,0 +1,37 @@
+import { type Intent, type IntentSurface } from '@reticlehq/core';
+import type { FileSystemPort } from '../project/fs-port.js';
+export interface Clock {
+    now: () => number;
+}
+export declare class IntentStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string, clock: Clock);
+    /** Every intent, in declaration order. */
+    read(): Promise<Intent[]>;
+    /** Everything not yet proved — what an agent asking "am I done?" still owes. */
+    open(): Promise<Intent[]>;
+    /**
+     * Declare one or more intents.
+     *
+     * Batched because the marginal cost of the whole mechanism has to stay at one call per feature; an
+     * agent that must make five calls to declare five things will make none.
+     */
+    declare(entries: readonly {
+        id: string;
+        statement: string;
+        surface?: IntentSurface;
+    }[]): Promise<Intent[]>;
+    /** Attach the predicate that would prove an intent. False when the id names nothing. */
+    bind(id: string, binding: unknown): Promise<boolean>;
+    /**
+     * Record that a verdict proved an intent.
+     *
+     * False rather than a throw on an unknown or unbound id: discharge runs off the back of a verdict,
+     * and must never be the reason one fails to return.
+     */
+    discharge(id: string, proof: {
+        verdictId: string;
+        grade: string;
+        at: number;
+    }): Promise<boolean>;
+}

package/dist/intent/intent-store.js

@@ -0,0 +1,112 @@
+import { bindIntent, declareIntent, dischargeIntent, emptyIntentFile, openIntents, parseIntentFile, upsertIntent, } from '@reticlehq/core';
+import { reticleDirPaths } from '../project/reticle-dir.js';
+import { withFileLock } from '../project/file-lock.js';
+/**
+ * The intent ledger on disk — `.reticle/intent.json`, git-checked and meant to be read in review.
+ *
+ * Git-checked deliberately. The one real defence against an agent quietly narrowing what it meant to
+ * match what it can already prove is that a human sees the narrowing in a diff, and that only works
+ * if the file lives with the code and travels with the PR. It is also why the writes are byte-stable:
+ * a ledger that churns on every run is one whose diffs nobody reads.
+ *
+ * Every operation goes through the same file lock the other stores use, because two sessions driving
+ * one project is ordinary and a lost declaration would be silent.
+ */
+const JSON_INDENT = 2;
+export class IntentStore {
+    #fs;
+    #root;
+    #clock;
+    constructor(fs, root, clock) {
+        this.#fs = fs;
+        this.#root = root;
+        this.#clock = clock;
+    }
+    #path() {
+        return reticleDirPaths(this.#root).intent;
+    }
+    /**
+     * Load the ledger, failing soft to empty.
+     *
+     * This is a git-checked file an agent can write and a human can hand-merge, so a malformed one is
+     * genuinely reachable — a conflict marker left in place is the obvious case. Throwing here would
+     * take down the verdict that was only asking what was still open, which trades a small problem for
+     * a large one.
+     */
+    async #load() {
+        try {
+            const raw = await this.#fs.readFile(this.#path());
+            return parseIntentFile(JSON.parse(raw));
+        }
+        catch {
+            return emptyIntentFile();
+        }
+    }
+    /** Byte-stable: 2-space indent, one trailing newline. An unchanged ledger produces no diff. */
+    async #save(file) {
+        await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+        await this.#fs.writeFile(this.#path(), `${JSON.stringify(file, null, JSON_INDENT)}\n`);
+    }
+    /** Every intent, in declaration order. */
+    async read() {
+        return Object.values((await this.#load()).intents);
+    }
+    /** Everything not yet proved — what an agent asking "am I done?" still owes. */
+    async open() {
+        return openIntents(await this.#load());
+    }
+    /**
+     * Declare one or more intents.
+     *
+     * Batched because the marginal cost of the whole mechanism has to stay at one call per feature; an
+     * agent that must make five calls to declare five things will make none.
+     */
+    async declare(entries) {
+        if (0 === entries.length)
+            return [];
+        return withFileLock(this.#path(), async () => {
+            let file = await this.#load();
+            const now = this.#clock.now();
+            const declared = [];
+            for (const entry of entries) {
+                const intent = declareIntent({ ...entry, now });
+                file = upsertIntent(file, intent);
+                const stored = file.intents[intent.id];
+                if (stored !== undefined)
+                    declared.push(stored);
+            }
+            await this.#save(file);
+            return declared;
+        });
+    }
+    /** Attach the predicate that would prove an intent. False when the id names nothing. */
+    async bind(id, binding) {
+        return withFileLock(this.#path(), async () => {
+            const file = await this.#load();
+            const existing = file.intents[id];
+            if (existing === undefined)
+                return false;
+            await this.#save(upsertIntent(file, bindIntent(existing, binding)));
+            return true;
+        });
+    }
+    /**
+     * Record that a verdict proved an intent.
+     *
+     * False rather than a throw on an unknown or unbound id: discharge runs off the back of a verdict,
+     * and must never be the reason one fails to return.
+     */
+    async discharge(id, proof) {
+        return withFileLock(this.#path(), async () => {
+            const file = await this.#load();
+            const existing = file.intents[id];
+            if (existing === undefined)
+                return false;
+            const proved = dischargeIntent(existing, proof);
+            if (proved === existing)
+                return false;
+            await this.#save(upsertIntent(file, proved));
+            return true;
+        });
+    }
+}

package/dist/intent/intent-tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../tools/tool-kit.js';
+export declare const INTENT_TOOLS: ToolDef[];

package/dist/intent/intent-tools.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { IntentStore } from './intent-store.js';
+import { ReticleTool } from '../tools/tool-names.js';
+import { sessionIdShape } from '../tools/tool-kit.js';
+import { sessionRoot } from '../project/session-root.js';
+import { asString } from '../tools/tools-helpers.js';
+/**
+ * Declare what a change was SUPPOSED to make true, while somebody still knows.
+ *
+ * One tool with three actions rather than three tools, because the surface is capped and because an
+ * agent that has to discover three names to use one idea uses none of them.
+ *
+ * There is deliberately no `discharge` action. A verdict discharges an intent by satisfying its
+ * binding, and a discharge an agent has to remember to file would be the same forgetting problem
+ * this exists to solve, moved one layer up.
+ */
+const DECLARE = 'declare';
+const LIST = 'list';
+const BIND = 'bind';
+export const INTENT_TOOLS = [
+    {
+        name: ReticleTool.INTENT,
+        description: 'Record what a change is SUPPOSED to make true, in your own words, while you still know — then verification does not have to re-derive it from the DOM later. { action:"declare", intents:[{ id, statement, surface? }] } takes prose and needs NO predicate: at declare time there is often no route, no ref and no code yet, and a predicate demanded there is just a mechanism. Declare EARLY (as you build) and batch them — one call per feature is the whole budget. { action:"bind", id, binding } attaches the predicate that would prove it once you know how; an intent with no binding is not a failure, it is the most interesting row in the ledger — something meant that nothing can currently prove. { action:"list" } returns what is still open. Stored in .reticle/intent.json, git-checked so a human sees in review if an intent was later narrowed to match what was easy to prove.',
+        example: {
+            action: DECLARE,
+            intents: [
+                { id: 'checkin', statement: 'clicking Send check-in makes the badge read "checked in"' },
+            ],
+        },
+        inputSchema: {
+            action: z.enum([DECLARE, LIST, BIND]),
+            intents: z
+                .array(z.object({
+                id: z.string(),
+                statement: z.string(),
+                surface: z
+                    .object({
+                    route: z.string().optional(),
+                    flow: z.string().optional(),
+                    files: z.array(z.string()).optional(),
+                })
+                    .optional(),
+            }))
+                .optional()
+                .describe('declare only. Batchable — declare every intent for a feature in one call.'),
+            id: z.string().optional().describe('bind only: which intent the predicate proves.'),
+            binding: z
+                .unknown()
+                .optional()
+                .describe("bind only: the predicate that would prove it, in reticle_assert's shape."),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            intents: z
+                .array(z.unknown())
+                .optional()
+                .describe('The intents this call declared, or on `list` everything still open — each { id, statement, state, declaredAt, binding?, surface?, provenBy?, amended? }. `state` is declared (prose only), bound (a predicate exists), or proved (a verdict satisfied it).'),
+            bound: z.boolean().optional().describe('bind only: false when the id names no intent.'),
+            path: z.string().optional().describe('Where the ledger was written.'),
+        },
+        handler: async (deps, args) => {
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            const store = new IntentStore(deps.fs, root, { now: deps.now });
+            const action = asString(args['action']);
+            if (BIND === action) {
+                const id = asString(args['id']) ?? '';
+                return { bound: await store.bind(id, args['binding']) };
+            }
+            if (LIST === action) {
+                return { intents: await store.open() };
+            }
+            const raw = args['intents'];
+            const entries = Array.isArray(raw)
+                ? raw
+                : [];
+            const declared = await store.declare(entries);
+            return { intents: declared, path: root };
+        },
+    },
+];

package/dist/intent/open-intents.d.ts

@@ -0,0 +1,21 @@
+import type { Intent } from '@reticlehq/core';
+import type { ToolDeps } from '../tools/tool-kit.js';
+/**
+ * What this project still owes — the ledger's undischarged intents, for a tool that has `deps` and a
+ * session id rather than a store.
+ *
+ * One helper rather than the same three-line construction at each site: the ROOT resolution is the
+ * part that must not drift. A caller that resolved the daemon's own directory while the declaring
+ * tool wrote to the project's would read an empty ledger and report that nothing was declared, which
+ * is a false accusation rather than an error.
+ */
+export declare function openSessionIntents(deps: ToolDeps, sessionId: string | undefined): Promise<Intent[]>;
+/**
+ * EVERY intent in the ledger, proved ones included — the denominator the open list is a subset of.
+ *
+ * Separate from `openSessionIntents` rather than a flag on it, because the two answer different
+ * questions: "what does this project still owe" drives a verdict's honesty, and "was anything ever
+ * declared" is what decides whether `reticle_intent` is used at all. Same root resolution, for the
+ * same reason it is shared above.
+ */
+export declare function allSessionIntents(deps: ToolDeps, sessionId: string | undefined): Promise<Intent[]>;

package/dist/intent/open-intents.js

@@ -0,0 +1,25 @@
+import { IntentStore } from './intent-store.js';
+import { sessionRoot } from '../project/session-root.js';
+/**
+ * What this project still owes — the ledger's undischarged intents, for a tool that has `deps` and a
+ * session id rather than a store.
+ *
+ * One helper rather than the same three-line construction at each site: the ROOT resolution is the
+ * part that must not drift. A caller that resolved the daemon's own directory while the declaring
+ * tool wrote to the project's would read an empty ledger and report that nothing was declared, which
+ * is a false accusation rather than an error.
+ */
+export async function openSessionIntents(deps, sessionId) {
+    return new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now }).open();
+}
+/**
+ * EVERY intent in the ledger, proved ones included — the denominator the open list is a subset of.
+ *
+ * Separate from `openSessionIntents` rather than a flag on it, because the two answer different
+ * questions: "what does this project still owe" drives a verdict's honesty, and "was anything ever
+ * declared" is what decides whether `reticle_intent` is used at all. Same root resolution, for the
+ * same reason it is shared above.
+ */
+export async function allSessionIntents(deps, sessionId) {
+    return new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now }).read();
+}

package/dist/journal/envelope.d.ts

@@ -8,7 +8,7 @@ import type { SegmentRollup } from './rollups.js';
  * (slower, more errors, more requests) — a segment doing less than expected is not a regression.
  */
 /** Online mean/variance/max for one metric (Welford's algorithm). Immutable: addStat returns a copy. */
-export interface MetricStats {
+interface MetricStats {
     count: number;
     mean: number;
     /** Sum of squared deviations (Welford M2); variance = m2/(count-1). */
@@ -22,7 +22,7 @@ export declare function stddev(stats: MetricStats): number;
 export declare function zScore(stats: MetricStats, x: number): number;
 /** The metrics an envelope tracks per route. */
 declare const ENVELOPE_METRICS: readonly ["durationMs", "net", "netErrors", "consoleErrors"];
-export type EnvelopeMetric = (typeof ENVELOPE_METRICS)[number];
+type EnvelopeMetric = (typeof ENVELOPE_METRICS)[number];
 export interface RouteEnvelope {
     route: string;
     /** Runs that contributed a sample — below MIN_ENVELOPE_SAMPLES the envelope is too green to judge. */
@@ -43,14 +43,14 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }>;
         net: z.ZodObject<{
             count: z.ZodNumber;
@@ -59,14 +59,14 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }>;
         netErrors: z.ZodObject<{
             count: z.ZodNumber;
@@ -75,14 +75,14 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }>;
         consoleErrors: z.ZodObject<{
             count: z.ZodNumber;
@@ -91,64 +91,64 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }, {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         }>;
     }, "strip", z.ZodTypeAny, {
         durationMs: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         net: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         consoleErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         netErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
     }, {
         durationMs: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         net: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         consoleErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         netErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
     }>;
 }, "strip", z.ZodTypeAny, {
@@ -157,27 +157,27 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     stats: {
         durationMs: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         net: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         consoleErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         netErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
     };
 }, {
@@ -186,27 +186,27 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     stats: {
         durationMs: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         net: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         consoleErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
         netErrors: {
             count: number;
-            max: number;
             mean: number;
             m2: number;
+            max: number;
         };
     };
 }>;

package/dist/journal/journal-recorder.d.ts

@@ -7,6 +7,11 @@ export interface JournalSink {
 /** Read side of the durable journal — the fall-through source when the ring buffer has evicted. */
 export interface JournalReader {
     readEvents(): Promise<ReticleEvent[]>;
+    /**
+     * The action ledger. Optional because a test double is a partial reader, and nothing that only
+     * needs events should be forced to grow a second method to satisfy the type.
+     */
+    readActions?(): Promise<JournalAction[]>;
 }
 interface JournalRecorderOptions {
     /** Injected elapsed-ms clock (never read from Date here — the clock-injection rule). */
@@ -32,6 +37,24 @@ export declare class JournalRecorder {
     beginAction(actionId: string, tool: string, args: Record<string, unknown>): void;
     /** Close the active window: persist its buffered events, then the action record. No-op if none active. */
     finishAction(effect?: unknown, settled?: boolean, settledInMs?: number): void;
+    /**
+     * Append one action record for a tool that PROVED something without driving the page.
+     *
+     * `reticle_assert` produces a verdict and moves nothing, so it must never open an attribution
+     * window: while one is open every observed event is stamped with that action's id, and stamping
+     * ambient traffic with an assertion's id would manufacture a causal link that does not exist —
+     * exactly what `EventAttribution.WINDOW` is carefully labelled to avoid claiming. So this writes
+     * the record and leaves `#active` precisely as it found it: an act window open across an assert
+     * keeps attributing to itself, which is the truth of what caused those events.
+     *
+     * `settled` is left unset for the same reason — nothing was dispatched, so there is no settle
+     * outcome to report, and the run fold skips actions that state none rather than inventing one.
+     *
+     * Ordering rides the same chain as `finishAction`: buffered events flush first, so a record is
+     * always persisted after the events that preceded it. Records land in the order verdicts were
+     * REACHED, so an assert taken mid-window is written before the act it interrupted.
+     */
+    recordAction(actionId: string, tool: string, args: Record<string, unknown>, effect?: unknown): void;
     /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
     flush(): Promise<void>;
 }

package/dist/journal/journal-recorder.js

@@ -65,6 +65,41 @@ export class JournalRecorder {
         this.#enqueueFlush();
         this.#chain = this.#chain.then(() => this.#sink.appendAction(action)).catch(() => undefined);
     }
+    /**
+     * Append one action record for a tool that PROVED something without driving the page.
+     *
+     * `reticle_assert` produces a verdict and moves nothing, so it must never open an attribution
+     * window: while one is open every observed event is stamped with that action's id, and stamping
+     * ambient traffic with an assertion's id would manufacture a causal link that does not exist —
+     * exactly what `EventAttribution.WINDOW` is carefully labelled to avoid claiming. So this writes
+     * the record and leaves `#active` precisely as it found it: an act window open across an assert
+     * keeps attributing to itself, which is the truth of what caused those events.
+     *
+     * `settled` is left unset for the same reason — nothing was dispatched, so there is no settle
+     * outcome to report, and the run fold skips actions that state none rather than inventing one.
+     *
+     * Ordering rides the same chain as `finishAction`: buffered events flush first, so a record is
+     * always persisted after the events that preceded it. Records land in the order verdicts were
+     * REACHED, so an assert taken mid-window is written before the act it interrupted.
+     */
+    recordAction(actionId, tool, args, effect) {
+        const at = this.#now();
+        const action = {
+            v: JOURNAL_FILE_VERSION,
+            actionId,
+            tool,
+            args,
+            effect,
+            // No window was opened, so no event carries this id: `seqRange` is omitted rather than
+            // invented, because any range here would claim an attribution that never happened. `tRange` is
+            // required by the schema and the honest value is the instant the verdict was recorded — a span
+            // of zero, which is exactly how much time this action attributed events over.
+            tRange: { from: at, to: at },
+            at,
+        };
+        this.#enqueueFlush();
+        this.#chain = this.#chain.then(() => this.#sink.appendAction(action)).catch(() => undefined);
+    }
     /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
     async flush() {
         this.#enqueueFlush();