@reticlehq/server 3.2.0 → 3.4.0

package/dist/memory/intent/intent-shard.d.ts

@@ -21,7 +21,6 @@
  */
 import { z } from 'zod';
 import { type Intent } from '@reticlehq/core/artifacts';
-import type { FileSystemPort } from '../project/fs/fs-port.js';
 /**
  * How settled a record is.
  *
@@ -311,25 +310,6 @@ export declare const IntentShardSchema: z.ZodObject<{
     }>;
 }>;
 export type IntentShard = z.infer<typeof IntentShardSchema>;
-export declare const summarise: (statement: string) => string;
-/** One line per intent: enough to decide whether to open the shard, and no more. */
-declare const IntentIndexEntrySchema: z.ZodObject<{
-    id: z.ZodString;
-    subject: z.ZodString;
-    statement: z.ZodString;
-    status: z.ZodEnum<["proposed", "agreed", "proved", "stale"]>;
-}, "strip", z.ZodTypeAny, {
-    status: "proved" | "proposed" | "agreed" | "stale";
-    id: string;
-    subject: string;
-    statement: string;
-}, {
-    status: "proved" | "proposed" | "agreed" | "stale";
-    id: string;
-    subject: string;
-    statement: string;
-}>;
-export type IntentIndexEntry = z.infer<typeof IntentIndexEntrySchema>;
 export declare const IntentIndexSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     entries: z.ZodArray<z.ZodObject<{
@@ -367,7 +347,6 @@ export declare const IntentIndexSchema: z.ZodObject<{
 }>;
 export type IntentIndex = z.infer<typeof IntentIndexSchema>;
 export declare const emptyShard: (subject: string) => IntentShard;
-export declare const emptyIndex: () => IntentIndex;
 /** The verification lifecycle a legacy record carried, mapped onto the settledness axis. */
 export declare const statusFromState: (state: Intent["state"]) => IntentStatus;
 /**
@@ -384,6 +363,4 @@ export declare const indexFrom: (shards: readonly IntentShard[]) => IntentIndex;
 export declare const shardsFrom: (records: readonly IntentRecord[]) => IntentShard[];
 /** Serialise byte-stably, with keys sorted so a re-save of unchanged data is a no-op diff. */
 export declare const serialise: (value: unknown) => string;
-/** Read + validate one JSON file, failing soft: a hand-merged file with a conflict marker is real. */
-export declare const readJsonFile: <T>(fs: FileSystemPort, path: string, parse: (raw: unknown) => T, fallback: T) => Promise<T>;
 export {};

package/dist/memory/intent/intent-shard.js

@@ -74,7 +74,7 @@ export const IntentShardSchema = z.object({
  * can do to a file meant to be read every session, which is the reason to keep it.
  */
 const SUMMARY_MAX = 72;
-export const summarise = (statement) => statement.length <= SUMMARY_MAX ? statement : `${statement.slice(0, SUMMARY_MAX - 1).trimEnd()}…`;
+const summarise = (statement) => statement.length <= SUMMARY_MAX ? statement : `${statement.slice(0, SUMMARY_MAX - 1).trimEnd()}…`;
 /** One line per intent: enough to decide whether to open the shard, and no more. */
 const IntentIndexEntrySchema = z.object({
     id: z.string().min(1),
@@ -96,7 +96,6 @@ export const emptyShard = (subject) => ({
     subject,
     intents: {},
 });
-export const emptyIndex = () => ({ version: INTENT_SHARD_VERSION, entries: [] });
 /** The verification lifecycle a legacy record carried, mapped onto the settledness axis. */
 export const statusFromState = (state) => 'proved' === state ? IntentStatus.PROVED : IntentStatus.AGREED;
 /**
@@ -142,12 +141,3 @@ const sortKeys = (value) => {
         return value;
     return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
 };
-/** Read + validate one JSON file, failing soft: a hand-merged file with a conflict marker is real. */
-export const readJsonFile = async (fs, path, parse, fallback) => {
-    try {
-        return parse(JSON.parse(await fs.readFile(path)));
-    }
-    catch {
-        return fallback;
-    }
-};

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

@@ -1,6 +1,14 @@
 import { type Intent, type IntentSurface } from '@reticlehq/core/artifacts';
 import type { FileSystemPort } from '../project/fs/fs-port.js';
 import type { Clock } from '../../machine/clock.js';
+/**
+ * The intent ledger's domain operations: declare, place, bind, discharge.
+ *
+ * Every operation is a PURE transition from core (`redeclareIntent`, `bindIntent`,
+ * `dischargeIntent`) handed to the ledger's atomic upsert. Storage is `IntentShardStore` —
+ * `.reticle/intent/<subject>/intent.json`, a flow's name being its subject — and this class writes no
+ * file of its own, so there is exactly one place an intent can be.
+ */
 export declare class IntentStore {
     #private;
     constructor(fs: FileSystemPort, root: string, clock: Clock);
@@ -12,7 +20,8 @@ export declare class IntentStore {
      * 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.
+     * agent that must make five calls to declare five things will make none. Saying an intent again
+     * does not unsay it: see `redeclareIntent` for what survives.
      */
     declare(entries: readonly {
         id: string;
@@ -22,13 +31,9 @@ export declare class IntentStore {
     /**
      * File a record under where it turned out to be about.
      *
-     * Separate from `declare` because the two happen at different MOMENTS and know different things.
-     * An inline intent is declared BEFORE the action — deliberately, so a verdict can see it open —
-     * and at that instant the agent is still on the page it is leaving. The route that describes what
-     * the intent is ABOUT only exists after the consequence lands.
-     *
-     * Write-once: an existing surface is never overwritten. A record placed by an agent that named its
-     * own subject must not be re-filed by a later run that happened to be somewhere else.
+     * Separate from `declare` because an inline intent is declared BEFORE the action, and the route
+     * that describes it only exists after the consequence lands. Write-once: an existing surface is
+     * never overwritten. A flow named here moves the record into that flow's directory.
      */
     place(id: string, surface: IntentSurface): Promise<boolean>;
     /** Attach the predicate that would prove an intent. False when the id names nothing. */

package/dist/memory/intent/intent-store.js

@@ -1,115 +1,71 @@
-import { bindIntent, declareIntent, dischargeIntent, emptyIntentFile, openIntents, parseIntentFile, upsertIntent, } from '@reticlehq/core/artifacts';
-import { reticleDirPaths } from '../project/dir/reticle-dir.js';
-import { withFileLock } from '../project/file-lock.js';
+import { IntentState, bindIntent, declareIntent, redeclareIntent, dischargeIntent, isActionLabel, } from '@reticlehq/core/artifacts';
+import { IntentShardStore } from './intent-shard-store.js';
+import { IntentStatus } from './intent-shard.js';
 /**
- * The intent ledger on disk — `.reticle/intent.json`, git-checked and meant to be read in review.
+ * The intent ledger's domain operations: declare, place, bind, discharge.
  *
- * 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.
+ * Every operation is a PURE transition from core (`redeclareIntent`, `bindIntent`,
+ * `dischargeIntent`) handed to the ledger's atomic upsert. Storage is `IntentShardStore` —
+ * `.reticle/intent/<subject>/intent.json`, a flow's name being its subject — and this class writes no
+ * file of its own, so there is exactly one place an intent can be.
  */
-const JSON_INDENT = 2;
 export class IntentStore {
-    #fs;
-    #root;
+    #ledger;
     #clock;
     constructor(fs, root, clock) {
-        this.#fs = fs;
-        this.#root = root;
+        this.#ledger = new IntentShardStore(fs, root, clock);
         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);
+        return this.#ledger.all();
     }
     /** Everything not yet proved — what an agent asking "am I done?" still owes. */
     async open() {
-        return openIntents(await this.#load());
+        // Stale is not owed: it is kept as history, not as work.
+        return (await this.#ledger.all()).filter((record) => IntentState.PROVED !== record.state && IntentStatus.STALE !== record.status);
     }
     /**
      * 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.
+     * agent that must make five calls to declare five things will make none. Saying an intent again
+     * does not unsay it: see `redeclareIntent` for what survives.
      */
     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;
-        });
+        const now = this.#clock.now();
+        const declared = [];
+        for (const entry of entries) {
+            // A step label is a log line, not a rule: every route that declares comes through here.
+            if (isActionLabel(entry.statement))
+                continue;
+            const stored = await this.#ledger.upsert(entry.id, (existing) => redeclareIntent(existing, declareIntent({ ...entry, now })));
+            if (stored !== undefined)
+                declared.push(stored);
+        }
+        return declared;
     }
     /**
      * File a record under where it turned out to be about.
      *
-     * Separate from `declare` because the two happen at different MOMENTS and know different things.
-     * An inline intent is declared BEFORE the action — deliberately, so a verdict can see it open —
-     * and at that instant the agent is still on the page it is leaving. The route that describes what
-     * the intent is ABOUT only exists after the consequence lands.
-     *
-     * Write-once: an existing surface is never overwritten. A record placed by an agent that named its
-     * own subject must not be re-filed by a later run that happened to be somewhere else.
+     * Separate from `declare` because an inline intent is declared BEFORE the action, and the route
+     * that describes it only exists after the consequence lands. Write-once: an existing surface is
+     * never overwritten. A flow named here moves the record into that flow's directory.
      */
     async place(id, surface) {
-        return withFileLock(this.#path(), async () => {
-            const file = await this.#load();
-            const existing = file.intents[id];
+        let placed = false;
+        await this.#ledger.upsert(id, (existing) => {
             if (existing === undefined || existing.surface !== undefined)
-                return false;
-            await this.#save(upsertIntent(file, { ...existing, surface }));
-            return true;
+                return undefined;
+            placed = true;
+            return { ...existing, surface };
         });
+        return placed;
     }
     /** 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;
-        });
+        const stored = await this.#ledger.upsert(id, (existing) => existing === undefined ? undefined : bindIntent(existing, binding));
+        return stored !== undefined;
     }
     /**
      * Record that a verdict proved an intent.
@@ -118,16 +74,16 @@ export class IntentStore {
      * 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];
+        let proved = false;
+        await this.#ledger.upsert(id, (existing) => {
             if (existing === undefined)
-                return false;
-            const proved = dischargeIntent(existing, proof);
-            if (proved === existing)
-                return false;
-            await this.#save(upsertIntent(file, proved));
-            return true;
+                return undefined;
+            const next = dischargeIntent(existing, proof);
+            if (next === existing)
+                return undefined;
+            proved = true;
+            return next;
         });
+        return proved;
     }
 }

package/dist/memory/intent/intent-tools.js

@@ -4,8 +4,10 @@ import { IntentShardStore } from './intent-shard-store.js';
 import { IntentStatus } from './intent-shard.js';
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate.js';
 import { sessionRoot } from '../project/session-root.js';
 import { asString } from '@reticlehq/core';
+import { isActionLabel } from '@reticlehq/core/artifacts';
 /**
  * Declare what a change was SUPPOSED to make true, while somebody still knows.
  *
@@ -24,11 +26,13 @@ const INDEX = 'index';
 const SUBJECT = 'subject';
 const GET = 'get';
 const RECORD = 'record';
+/** Why a step label is not stored, in words that say what to write instead. */
+const STEP_LABEL_REFUSAL = 'describes a step that was done, not what must be true. State the rule, e.g. "saving the form shows the new row in the list"';
 const MIGRATE = 'migrate';
 export const INTENT_TOOLS = [
     {
         name: ReticleTool.INTENT,
-        description: 'Record what a change is SUPPOSED to make true, as a durable statement ABOUT THE PRODUCT that a teammate who was not here will understand in six months — name the behaviour, not this run or its step number, and never "renders cleanly", which nothing can check. It is SHARED memory: pooled per project and read back by later agents. Capture it 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.',
+        description: 'Record what a change is SUPPOSED to make true, as a durable statement ABOUT THE PRODUCT that a teammate who was not here will understand in six months — name the behaviour, not this run or its step number, and never "renders cleanly", which nothing can check. It is SHARED memory: pooled per project and read back by later agents. Capture it 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/<subject>/intent.json (a flow name is its subject), 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: [
@@ -56,8 +60,8 @@ export const INTENT_TOOLS = [
                 .describe('record only: how settled it is. Defaults to proposed.'),
             intents: z
                 .array(z.object({
-                id: z.string(),
-                statement: z.string(),
+                id: z.string().min(1),
+                statement: z.string().min(1),
                 surface: z
                     .object({
                     route: z.string().optional(),
@@ -69,10 +73,19 @@ export const INTENT_TOOLS = [
                 .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."),
+            /*
+             * The predicate schema, not `unknown`.
+             *
+             * The description has always said "in reticle_assert's shape" and the type said "anything",
+             * so a client reading the surface to build this call learned the field's name and nothing
+             * else — the same degradation the recursive `until` predicate suffered when it was converted
+             * without the SDK's own options. This one was not a converter bug: it was declared that way.
+             * Caught by `weakest-client-schemas.test.ts`, which is the first thing that ever looked.
+             *
+             * Accepting the real shape also means a malformed binding is refused at the boundary instead
+             * of being written into the ledger and failing later against a verdict it can never satisfy.
+             */
+            binding: PredicateSchema.optional().describe("bind only: the predicate that would prove it, in reticle_assert's shape."),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -81,6 +94,10 @@ export const INTENT_TOOLS = [
                 .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.'),
+            refused: z
+                .array(z.object({ id: z.string(), reason: z.string() }))
+                .optional()
+                .describe('declare only: statements not stored, and why.'),
             path: z.string().optional().describe('Where the ledger was written.'),
             entries: z
                 .array(z.unknown())
@@ -130,28 +147,22 @@ export const INTENT_TOOLS = [
                 return { bound: await store.bind(id, args['binding']) };
             }
             if (LIST === action) {
-                /*
-                 * Both files, one answer.
-                 *
-                 * `declare` writes the flat `.reticle/intent.json`; `record` writes the sharded
-                 * `.reticle/intent/`. Listing only the flat one meant a recorded intent could not be found
-                 * again by the agent that had just written it — and the lesson an agent draws from that is
-                 * "the intent does not exist", not "there are two stores".
-                 *
-                 * Merged HERE rather than inside either store: this tool is the one seam that knows both
-                 * exist, and neither store should have to learn the other's layout to stay honest.
-                 */
-                const flat = await store.open();
-                const seen = new Set(flat.map((intent) => intent.id));
-                const fromShards = (await shards.all()).filter((record) => !seen.has(record.id));
-                return { intents: [...flat, ...fromShards] };
+                // One ledger, so one read. This merged two stores while `declare` and `record` wrote two
+                // different files; kept past that, it would add back every PROVED intent to a list that
+                // promises only what is still open.
+                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 };
+            // Said, not swallowed: an agent that declared something and finds nothing stored would
+            // otherwise conclude the ledger lost it.
+            const refused = entries
+                .filter((entry) => isActionLabel(entry.statement))
+                .map((entry) => ({ id: entry.id, reason: STEP_LABEL_REFUSAL }));
+            return { intents: declared, ...(0 === refused.length ? {} : { refused }), path: root };
         },
     },
 ];

package/dist/memory/journal/ambient-store.js

@@ -1,4 +1,5 @@
 import { dirname } from 'node:path';
+import { writeFileAtomic } from '../project/fs/write-atomic.js';
 import { reticleDirPaths } from '../project/dir/reticle-dir.js';
 import { AmbientFileSchema } from './on-disk/ambient-file.js';
 import { onlyStableAmbient } from '@reticlehq/engine/window/ambient.js';
@@ -45,8 +46,6 @@ export class AmbientStore {
         // numbering, so persisting it teaches the next session to suppress an element it never saw.
         const regions = onlyStableAmbient(counts);
         const body = `${JSON.stringify({ version: AMBIENT_FILE_VERSION, regions }, null, 2)}\n`;
-        const tmp = `${this.#path}.tmp`;
-        await this.#fs.writeFile(tmp, body);
-        await this.#fs.rename(tmp, this.#path);
+        await writeFileAtomic(this.#fs, this.#path, body);
     }
 }

package/dist/memory/journal/deviation-report.js

@@ -1,3 +1,4 @@
+import { routeTemplate } from './route-template.js';
 import { compareSegment, MIN_ENVELOPE_SAMPLES, } from './envelope.js';
 function headlineFor(report) {
     const truncNote = report.truncatedSegments > 0
@@ -31,7 +32,9 @@ export function buildDeviationReport(envelopes, segments, zThreshold) {
             truncated += 1;
             continue;
         }
-        const envelope = envelopes.get(segment.route);
+        // The SAME key the service accumulates under — a lookup on the observed path would miss every
+        // envelope on an app with ids in its URLs, which is the case this templating exists for.
+        const envelope = envelopes.get(routeTemplate(segment.route));
         if (envelope === undefined || envelope.samples < MIN_ENVELOPE_SAMPLES)
             continue;
         judged += 1;

package/dist/memory/journal/deviation-service.js

@@ -1,3 +1,4 @@
+import { routeTemplate } from './route-template.js';
 import { addSegmentToEnvelope, emptyEnvelope } from './envelope.js';
 import { buildDeviationReport } from './deviation-report.js';
 import { withFileLock } from '../project/file-lock.js';
@@ -22,8 +23,15 @@ export async function reportAndAccumulate(store, segments, zThreshold) {
             // Never learn from a truncated sample — its understated counts would poison the baseline.
             if (true === segment.truncated)
                 continue;
-            const current = envelopes.get(segment.route) ?? emptyEnvelope(segment.route);
-            envelopes.set(segment.route, addSegmentToEnvelope(current, segment));
+            /*
+             * Keyed on the route TEMPLATE, not the observed path. Keyed on the path, an app with ids in
+             * its URLs mints one envelope per id, every envelope holds a single sample, and nothing ever
+             * reaches MIN_ENVELOPE_SAMPLES — so the deviation report answers "envelope too new" forever
+             * and the feature never turns on. See route-template.ts.
+             */
+            const key = routeTemplate(segment.route);
+            const current = envelopes.get(key) ?? emptyEnvelope(key);
+            envelopes.set(key, addSegmentToEnvelope(current, segment));
         }
         await store.save(envelopes);
         return report;

package/dist/memory/journal/drive-flow.d.ts

@@ -1,4 +1,4 @@
-import type { FlowExpect, FlowName } from '@reticlehq/core';
+import type { FlowFile, FlowName, Predicate } from '@reticlehq/core';
 /**
  * What this module needs a recorded step to BE, named structurally rather than imported.
  *
@@ -12,9 +12,13 @@ export interface TapeStep {
     tool: string;
     args: Record<string, unknown>;
     stable: boolean;
-    expect?: FlowExpect;
+    expect?: Predicate;
     /** Recorder-internal, and the field journeys are cut on. Never written to the saved flow. */
     route?: string;
+    page?: string;
+    endPage?: string;
+    /** The intent the agent declared on this action. The first one names the journey. */
+    intent?: string;
 }
 /** The compiled shape a flow store accepts. Structural, for the same reason as `TapeStep`. */
 export interface DriveProgram {
@@ -22,6 +26,7 @@ export interface DriveProgram {
     version: number;
     steps: TapeStep[];
     startPath?: string;
+    author?: FlowFile['author'];
 }
 /**
  * What a session drove, saved as a replayable flow — without anybody asking for it.
@@ -36,21 +41,21 @@ export interface DriveProgram {
  */
 /** The one condition on saving, and the reason the whole thing is safe. */
 export declare function carriesAnAssertion(steps: readonly TapeStep[]): boolean;
+/** Every auto-saved flow's name starts here, which is what lets a merge tell them from hand-named ones. */
+export declare const DRIVE_FLOW_PREFIX = "drive-";
 /**
- * A stable name for what this session drove — led by what it proved.
+ * A readable name for a journey, led by WHY it was driven.
  *
- * Two properties, and the name used to have only the second. It has to be STABLE: teardown fires on
- * every socket close and a reconnecting tab keeps its id, so a name that moves leaves one journey
- * scattered across several files, each a partial copy of the others. And it has to be READABLE,
- * because `presenter-controls.ts` renders it straight into the replay button's `textContent` — so
- * the label a person actually sees was `drive-sdc991872-6d66-4adf-8780-f931c62905f9`, twice, for two
- * different journeys. A session id is a fact about the socket, not about the feature.
+ * The agent's own `intent` on the action is the best name there is — it is the sentence a person
+ * would use — so it leads when one was declared. Without one, what the journey proved names it (the
+ * strongest claim first), and the route follows so two journeys stay apart.
  *
- * So the claim leads, the route follows, and a SHORT session discriminator trails: two sessions that
- * prove the same thing on the same route stay separate files rather than overwriting each other,
- * which is the one thing the full id was buying that the claim cannot.
+ * No session id. It used to trail every name so two sessions never overwrote each other, which also
+ * made every session's drive of the same journey its own file. Two DIFFERENT journeys that land on
+ * one name are now told apart at save by their shape, and two copies of the SAME journey merge —
+ * see FlowStore.saveJourney.
  */
-export declare function driveFlowName(sessionId: string, route?: string, steps?: readonly TapeStep[]): FlowName;
+export declare function driveFlowName(route?: string, steps?: readonly TapeStep[]): FlowName;
 export interface DriveFlowOutcome {
     /** The flows that were written — one per journey the session contained. */
     readonly saved?: readonly string[];
@@ -65,7 +70,7 @@ export interface DriveFlowOutcome {
     readonly unprovenSteps?: number;
 }
 /** A flow per journey, so two journeys in one session are two regression tests rather than one. */
-export declare function driveFlowsFrom(sessionId: string, tape: {
+export declare function driveFlowsFrom(tape: {
     steps: readonly TapeStep[];
     startPath?: string;
 } | undefined): {