@reticlehq/server 2.12.0 → 2.13.0

package/dist/intent/intent-shard.js

@@ -0,0 +1,176 @@
+/**
+ * The sharded intent store: one small file per subject, plus an index cheap enough to always load.
+ *
+ * ## Why this exists
+ *
+ * `.reticle/intent.json` was a single object that reached 141 entries and 109KB. Parsing that is
+ * nothing; READING it is the cost, and reading is what this store is for. An agent wanting the two
+ * rules about checkout pulled 139 irrelevant ones through its context to find them, and an agent
+ * changing one rewrote the whole file — which is both slow to review and a lost write whenever two
+ * sessions touch different subjects at once.
+ *
+ * ## The shape
+ *
+ *   .reticle/intent/index.json     every id, its subject and one line of prose
+ *   .reticle/intent/<subject>.json the full records for that subject
+ *
+ * The index is the whole point: it answers "what do we know, and where does it live?" without
+ * opening anything, and detail is then fetched for the one subject in play. Measured on the real
+ * corpus, that is 109KB all-or-nothing becoming an index plus one shard — and the largest shard is
+ * under 10KB once the unsorted bucket is set aside.
+ *
+ * The index is NOT tiny, and measuring beat guessing twice over. With full statements it came to
+ * 36KB for 141 entries; summarising them saved 7%, because the bulk is not the prose but the ids —
+ * `inline:signing-in-with-the-email-password-created-earli-6ca804e9` is 63 characters before the
+ * statement starts. So the honest numbers are: 109KB all-or-nothing becomes a 33KB index plus one
+ * ~10KB shard, and the real win is that a READ and a WRITE are both bounded to one subject rather
+ * than the whole corpus.
+ *
+ * The index is therefore the part that does not scale forever. At ten times this size it needs a
+ * second tier — subjects and counts, with ids fetched per subject — rather than a longer single
+ * read. Recorded here because the next person will hit it, and the shape of the fix is already
+ * visible.
+ *
+ * ## What the records carry that the old ones did not
+ *
+ * The legacy file was written BY verification, AT verification time, in verification's vocabulary: a
+ * statement, a predicate, and whether a verdict discharged it. Of 141 entries, four named a surface.
+ * There was nowhere to put the reason a thing must be true, who decided it, or when — so the
+ * business case somebody states once and then forgets had no home and was never captured.
+ *
+ * `why`, `source` and `subject` are that home. They are optional because a migrated record cannot
+ * invent them, and a store that rejected incomplete records would simply not be written to.
+ */
+import { z } from 'zod';
+import { IntentSchema } from '@reticlehq/core';
+import { subjectFor, UNSORTED_SUBJECT } from './intent-subject.js';
+export const INTENT_SHARD_VERSION = 1;
+/** Byte-stable writes: an unchanged shard produces no diff, so the ones that DID change stand out. */
+const JSON_INDENT = 2;
+/**
+ * How settled a record is.
+ *
+ * Separate from the legacy `state`, which only ever described the VERIFICATION lifecycle
+ * (declared → bound → proved). A rule can be agreed with the customer months before anything can
+ * prove it, and collapsing those two axes is what made the old file an assertion log rather than a
+ * memory.
+ */
+export const IntentStatus = {
+    /** Captured, not yet confirmed by anyone. What an agent writes while building. */
+    PROPOSED: 'proposed',
+    /** Confirmed as something that must hold. May have no way to prove it yet. */
+    AGREED: 'agreed',
+    /** A verdict has actually shown it holds. */
+    PROVED: 'proved',
+    /** Believed out of date — kept, because deleting the record loses the fact it was ever true. */
+    STALE: 'stale',
+};
+export const IntentRecordSchema = IntentSchema.extend({
+    /** Which shard this lives in. Stored as well as implied, so a file read alone is self-describing. */
+    subject: z.string().min(1),
+    status: z.enum([
+        IntentStatus.PROPOSED,
+        IntentStatus.AGREED,
+        IntentStatus.PROVED,
+        IntentStatus.STALE,
+    ]),
+    /** WHY it must be true. The half the old file had no room for. */
+    why: z.string().optional(),
+    /** Where it came from — "the user, in conversation" beats an anonymous assertion in six months. */
+    source: z.string().optional(),
+    /** When it was last touched, so a stale-looking record can be told from an untouched one. */
+    updatedAt: z.number().optional(),
+});
+export const IntentShardSchema = z.object({
+    version: z.literal(INTENT_SHARD_VERSION),
+    subject: z.string().min(1),
+    intents: z.record(z.string(), IntentRecordSchema),
+});
+/**
+ * How much of a statement the index carries.
+ *
+ * The index exists to answer WHICH SHARD, and a clause is enough to decide that; the sentence is one
+ * file away. Ellipsis included so a truncated line is never mistaken for the whole intent.
+ *
+ * Worth 7% on the real corpus rather than the large saving expected — the ids dominate — but it also
+ * bounds the damage a future 500-character statement 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()}…`;
+/** One line per intent: enough to decide whether to open the shard, and no more. */
+export const IntentIndexEntrySchema = z.object({
+    id: z.string().min(1),
+    subject: z.string().min(1),
+    statement: z.string().min(1),
+    status: z.enum([
+        IntentStatus.PROPOSED,
+        IntentStatus.AGREED,
+        IntentStatus.PROVED,
+        IntentStatus.STALE,
+    ]),
+});
+export const IntentIndexSchema = z.object({
+    version: z.literal(INTENT_SHARD_VERSION),
+    entries: z.array(IntentIndexEntrySchema),
+});
+export const emptyShard = (subject) => ({
+    version: INTENT_SHARD_VERSION,
+    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;
+/**
+ * Turn a legacy intent into a record, inferring only what can be inferred.
+ *
+ * `why` and `source` are left ABSENT rather than filled with the statement or a placeholder. A
+ * record that claims to carry a reason it does not have is worse than one that admits the gap: the
+ * gap is a prompt to write the reason down, and a placeholder is a reason to stop looking.
+ */
+export const recordFromIntent = (intent) => ({
+    ...intent,
+    subject: subjectFor({ surface: intent.surface, binding: intent.binding }),
+    status: statusFromState(intent.state),
+});
+/** Build the index from the shards. Derived, never hand-maintained — two sources would disagree. */
+export const indexFrom = (shards) => ({
+    version: INTENT_SHARD_VERSION,
+    entries: shards
+        .flatMap((s) => Object.values(s.intents))
+        .map((r) => ({
+        id: r.id,
+        subject: r.subject,
+        statement: summarise(r.statement),
+        status: r.status,
+    }))
+        .sort((a, b) => a.subject.localeCompare(b.subject) || a.id.localeCompare(b.id)),
+});
+/** Group records into shards by their own subject. */
+export const shardsFrom = (records) => {
+    const bySubject = new Map();
+    for (const r of records) {
+        const subject = '' === r.subject ? UNSORTED_SUBJECT : r.subject;
+        const shard = bySubject.get(subject) ?? emptyShard(subject);
+        shard.intents[r.id] = r;
+        bySubject.set(subject, shard);
+    }
+    return [...bySubject.values()].sort((a, b) => a.subject.localeCompare(b.subject));
+};
+/** Serialise byte-stably, with keys sorted so a re-save of unchanged data is a no-op diff. */
+export const serialise = (value) => `${JSON.stringify(value, (_k, v) => sortKeys(v), JSON_INDENT)}\n`;
+const sortKeys = (value) => {
+    if (Array.isArray(value) || null === value || typeof value !== 'object')
+        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/intent/intent-store.d.ts

@@ -22,6 +22,18 @@ export declare class IntentStore {
         surface?: IntentSurface;
     }[]): Promise<Intent[]>;
     /** Attach the predicate that would prove an intent. False when the id names nothing. */
+    /**
+     * 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.
+     */
+    place(id: string, surface: IntentSurface): Promise<boolean>;
     bind(id: string, binding: unknown): Promise<boolean>;
     /**
      * Record that a verdict proved an intent.

package/dist/intent/intent-store.js

@@ -80,6 +80,27 @@ export class IntentStore {
         });
     }
     /** Attach the predicate that would prove an intent. False when the id names nothing. */
+    /**
+     * 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.
+     */
+    async place(id, surface) {
+        return withFileLock(this.#path(), async () => {
+            const file = await this.#load();
+            const existing = file.intents[id];
+            if (existing === undefined || existing.surface !== undefined)
+                return false;
+            await this.#save(upsertIntent(file, { ...existing, surface }));
+            return true;
+        });
+    }
     async bind(id, binding) {
         return withFileLock(this.#path(), async () => {
             const file = await this.#load();

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

@@ -0,0 +1,45 @@
+/**
+ * What an intent is ABOUT — the key the store shards on, and the thing that makes it retrievable.
+ *
+ * `.reticle/intent.json` reached 141 entries and 109KB as one object. That is not expensive to
+ * parse; it is expensive to READ, which is the operation that matters here. An agent that wants the
+ * two rules about checkout has to pull 139 irrelevant ones through its context to find them, and an
+ * agent that wants to change one has to rewrite the whole file.
+ *
+ * Sharding by subject fixes both, but only if the subject is DERIVABLE. A store that requires every
+ * caller to invent a category is one where everything lands in whatever the first caller typed. So
+ * the subject is inferred from evidence the intent already carries, in falling order of reliability:
+ *
+ *   1. an explicit subject, when the caller knows one
+ *   2. the flow it belongs to — the strongest signal, because a flow IS a feature
+ *   3. the route it touches, which is how the product is navigated and therefore how it is discussed
+ *   4. the feature directory of the FILE its verdict acted on — the grouping the codebase already
+ *      states about itself
+ *   5. the API path its binding asserts on, which names the domain even when the UI does not
+ *   6. failing all of that, a single shared bucket — visibly unsorted rather than silently misfiled
+ *
+ * Nothing here guesses from prose. A statement is a sentence written for a human, and clustering
+ * sentences is exactly the kind of plausible-looking inference that puts "sign-in works" under
+ * `settings` and leaves nobody able to explain why.
+ */
+/** Where an intent goes when nothing about it says where it belongs. Deliberately obvious. */
+export declare const UNSORTED_SUBJECT = "unsorted";
+/** Shape enough of an intent to derive a subject, without importing the whole record. */
+export interface SubjectEvidence {
+    subject?: string | undefined;
+    surface?: {
+        route?: string | undefined;
+        flow?: string | undefined;
+        files?: string[] | undefined;
+    } | undefined;
+    binding?: unknown;
+}
+/** A filesystem- and URL-safe slug. Same rules as a project id, for the same reasons. */
+export declare const slugifySubject: (raw: string) => string;
+/**
+ * The subject for one intent, by the ladder above.
+ *
+ * Total: it always returns something, because a store that can refuse to place a record is a store
+ * that loses records.
+ */
+export declare const subjectFor: (evidence: SubjectEvidence) => string;

package/dist/intent/intent-subject.js

@@ -0,0 +1,177 @@
+/**
+ * What an intent is ABOUT — the key the store shards on, and the thing that makes it retrievable.
+ *
+ * `.reticle/intent.json` reached 141 entries and 109KB as one object. That is not expensive to
+ * parse; it is expensive to READ, which is the operation that matters here. An agent that wants the
+ * two rules about checkout has to pull 139 irrelevant ones through its context to find them, and an
+ * agent that wants to change one has to rewrite the whole file.
+ *
+ * Sharding by subject fixes both, but only if the subject is DERIVABLE. A store that requires every
+ * caller to invent a category is one where everything lands in whatever the first caller typed. So
+ * the subject is inferred from evidence the intent already carries, in falling order of reliability:
+ *
+ *   1. an explicit subject, when the caller knows one
+ *   2. the flow it belongs to — the strongest signal, because a flow IS a feature
+ *   3. the route it touches, which is how the product is navigated and therefore how it is discussed
+ *   4. the feature directory of the FILE its verdict acted on — the grouping the codebase already
+ *      states about itself
+ *   5. the API path its binding asserts on, which names the domain even when the UI does not
+ *   6. failing all of that, a single shared bucket — visibly unsorted rather than silently misfiled
+ *
+ * Nothing here guesses from prose. A statement is a sentence written for a human, and clustering
+ * sentences is exactly the kind of plausible-looking inference that puts "sign-in works" under
+ * `settings` and leaves nobody able to explain why.
+ */
+/** Where an intent goes when nothing about it says where it belongs. Deliberately obvious. */
+export const UNSORTED_SUBJECT = 'unsorted';
+/** The longest a subject may be. It is a filename, and it is read in a directory listing. */
+const MAX_SUBJECT = 40;
+/** A filesystem- and URL-safe slug. Same rules as a project id, for the same reasons. */
+export const slugifySubject = (raw) => {
+    const slug = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, MAX_SUBJECT)
+        .replace(/-+$/g, '');
+    return 0 === slug.length ? UNSORTED_SUBJECT : slug;
+};
+/** The first path segment of a route or URL — `/issues?x=1` and `/v1/issues` both give `issues`. */
+const firstSegment = (path) => {
+    const clean = path.split(/[?#]/)[0] ?? '';
+    for (const part of clean.split('/')) {
+        // Skip empties, the API version prefix, and anything that is plainly an id rather than a name.
+        if ('' === part || /^v\d+$/i.test(part) || /^\d+$/.test(part))
+            continue;
+        /*
+         * A QUERY FRAGMENT is not a path segment.
+         *
+         * A `net` predicate's `urlContains` is frequently a filter rather than a URL —
+         * `category=vulnerability%2Csevere`, `projectId=storefront` — and with no `?` to split on, the
+         * whole thing survived as a "path" and was slugified into a subject. Measured on a real corpus:
+         * six of thirty-four subjects were query values, one record each, and together they made the
+         * coverage map read as a product with two dozen tiny unrelated areas.
+         *
+         * Skipped rather than aborting the walk, so a binding that asserts a filter AND a route still
+         * finds the route.
+         */
+        if (part.includes('=') || part.includes('&'))
+            continue;
+        return part;
+    }
+    return undefined;
+};
+/** Walk a binding predicate tree for the first route or URL it mentions. */
+const fromBinding = (binding) => {
+    if (typeof binding !== 'object' || null === binding)
+        return undefined;
+    const node = binding;
+    const direct = node['pathname'] ?? node['urlContains'] ?? node['path'];
+    if ('string' === typeof direct) {
+        const seg = firstSegment(direct);
+        if (seg !== undefined)
+            return seg;
+    }
+    const nested = node['predicates'] ?? node['of'];
+    if (Array.isArray(nested)) {
+        for (const child of nested) {
+            const found = fromBinding(child);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+};
+/**
+ * Directory names that group CODE rather than name a feature.
+ *
+ * `src/ui/input.tsx` is every screen's shared control; filing knowledge under `ui` would put
+ * sign-in, billing and issues in one bucket named after a folder. Walked past rather than accepted,
+ * and if every directory is generic the file yields nothing — which is honest, because it genuinely
+ * did not say what the record is about.
+ */
+const GENERIC_DIRS = new Set([
+    'src',
+    'app',
+    'apps',
+    'lib',
+    'libs',
+    'packages',
+    'components',
+    'ui',
+    'utils',
+    'util',
+    'helpers',
+    'shared',
+    'common',
+    'core',
+    'pages',
+    'features',
+    'modules',
+    'screens',
+    'views',
+    'test',
+    'tests',
+    '__tests__',
+    'dist',
+    'build',
+    'node_modules',
+]);
+/**
+ * The feature a file belongs to: the deepest directory that names something.
+ *
+ * A codebase already groups itself by feature, and the directory a file sits in is that grouping
+ * stated by the people who wrote it — structural evidence, not an inference from prose. Measured
+ * against the alternative before being written: 29 unsorted records carried a testid, and using the
+ * testid's prefix would have produced `confirm`, `new` and `delete` — verbs rather than areas.
+ */
+const featureOfFile = (file) => {
+    // Windows paths arrive from Windows machines; splitting on `/` alone leaves one long segment.
+    const parts = file.split(/[/\\]/).filter((p) => p !== '');
+    // The last part is the filename, never a feature.
+    for (let i = parts.length - 2; i >= 0; i--) {
+        const dir = parts[i];
+        if (dir === undefined || GENERIC_DIRS.has(dir.toLowerCase()))
+            continue;
+        return dir;
+    }
+    return undefined;
+};
+/**
+ * The subject for one intent, by the ladder above.
+ *
+ * Total: it always returns something, because a store that can refuse to place a record is a store
+ * that loses records.
+ */
+export const subjectFor = (evidence) => {
+    const explicit = evidence.subject;
+    if ('string' === typeof explicit && explicit.trim() !== '')
+        return slugifySubject(explicit);
+    const flow = evidence.surface?.flow;
+    if ('string' === typeof flow && flow.trim() !== '')
+        return slugifySubject(flow);
+    const route = evidence.surface?.route;
+    if ('string' === typeof route) {
+        const seg = firstSegment(route);
+        if (seg !== undefined)
+            return slugifySubject(seg);
+    }
+    /*
+     * The file, before the binding. A path names the feature the code lives in; a binding's API path
+     * names the domain only indirectly, and its element predicates name controls rather than areas.
+     */
+    const files = evidence.surface?.files;
+    if (Array.isArray(files)) {
+        for (const file of files) {
+            if ('string' !== typeof file || '' === file)
+                continue;
+            const feature = featureOfFile(file);
+            if (feature !== undefined)
+                return slugifySubject(feature);
+        }
+    }
+    const bound = fromBinding(evidence.binding);
+    if (bound !== undefined)
+        return slugifySubject(bound);
+    return UNSORTED_SUBJECT;
+};

package/dist/intent/intent-tools.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { IntentStore } from './intent-store.js';
+import { IntentShardStore } from './intent-shard-store.js';
+import { IntentStatus } from './intent-shard.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
 import { sessionRoot } from '../project/session-root.js';
@@ -17,10 +19,16 @@ import { asString } from '../tools/tools-helpers.js';
 const DECLARE = 'declare';
 const LIST = 'list';
 const BIND = 'bind';
+/* The sharded store's surface. Same tool, because a second tool name is a second thing to discover. */
+const INDEX = 'index';
+const SUBJECT = 'subject';
+const GET = 'get';
+const RECORD = 'record';
+const MIGRATE = 'migrate';
 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.',
+        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.',
         example: {
             action: DECLARE,
             intents: [
@@ -28,7 +36,24 @@ export const INTENT_TOOLS = [
             ],
         },
         inputSchema: {
-            action: z.enum([DECLARE, LIST, BIND]),
+            action: z.enum([DECLARE, LIST, BIND, INDEX, SUBJECT, GET, RECORD, MIGRATE]),
+            subject: z
+                .string()
+                .optional()
+                .describe('subject/record: what the intent is ABOUT — the shard it lives in.'),
+            statement: z.string().optional().describe('record only: what must be true, in prose.'),
+            why: z
+                .string()
+                .optional()
+                .describe('record only: WHY it must be true. The thing somebody says once and forgets.'),
+            source: z
+                .string()
+                .optional()
+                .describe('record only: where it came from — a person, a ticket, a conversation.'),
+            status: z
+                .enum([IntentStatus.PROPOSED, IntentStatus.AGREED, IntentStatus.PROVED, IntentStatus.STALE])
+                .optional()
+                .describe('record only: how settled it is. Defaults to proposed.'),
             intents: z
                 .array(z.object({
                 id: z.string(),
@@ -57,11 +82,49 @@ export const INTENT_TOOLS = [
                 .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.'),
+            entries: z
+                .array(z.unknown())
+                .optional()
+                .describe('index only: one line per intent — { id, subject, statement (summarised), status }. The cheap read: enough to decide WHICH subject to open, without loading any of them.'),
+            records: z
+                .array(z.unknown())
+                .optional()
+                .describe('subject only: every full record for that subject.'),
+            record: z.unknown().optional().describe('get/record: the single full record, or null.'),
+            migrated: z
+                .number()
+                .optional()
+                .describe('migrate only: how many flat-file intents were folded into shards.'),
+            subjects: z
+                .array(z.string())
+                .optional()
+                .describe('migrate only: which subjects received them.'),
         },
         handler: async (deps, args) => {
             const root = sessionRoot(deps, asString(args['sessionId']));
             const store = new IntentStore(deps.fs, root, { now: deps.now });
+            const shards = new IntentShardStore(deps.fs, root, { now: deps.now });
             const action = asString(args['action']);
+            if (INDEX === action)
+                return { entries: (await shards.index()).entries, path: root };
+            if (SUBJECT === action)
+                return { records: await shards.subject(asString(args['subject']) ?? ''), path: root };
+            if (GET === action)
+                return { record: await shards.get(asString(args['id']) ?? '') };
+            if (MIGRATE === action)
+                return { ...(await shards.migrate()), path: root };
+            if (RECORD === action) {
+                const written = await shards.record({
+                    id: asString(args['id']) ?? '',
+                    statement: asString(args['statement']) ?? '',
+                    subject: asString(args['subject']),
+                    why: asString(args['why']),
+                    source: asString(args['source']),
+                    status: asString(args['status']),
+                    binding: args['binding'],
+                });
+                return { record: written, path: root };
+            }
             if (BIND === action) {
                 const id = asString(args['id']) ?? '';
                 return { bound: await store.bind(id, args['binding']) };

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

@@ -19,3 +19,24 @@ export declare function openSessionIntents(deps: ToolDeps, sessionId: string | u
  * same reason it is shared above.
  */
 export declare function allSessionIntents(deps: ToolDeps, sessionId: string | undefined): Promise<Intent[]>;
+/** What the ledger still owes once this verdict's own intent is discharged, and how old it is. */
+export interface IntentDebt {
+    openIntentCount: number;
+    /**
+     * Age of the OLDEST open intent, in ms. Absent when nothing is open.
+     *
+     * A count alone cannot tell "declared a minute ago and not proved yet" from "this project has
+     * owed eighteen things since last week", and only the first is actionable on the result being
+     * read. A number that is always large is one people learn to skip, which is how an honest gap
+     * gets filtered out along with the noise.
+     */
+    oldestOpenIntentAgeMs?: number;
+}
+/**
+ * The debt a verdict should report, MINUS the intent it is about to discharge.
+ *
+ * The discharge happens after the gaps are built, so counting the raw ledger would include the
+ * intent this very call proves — measured live: an inline intent was declared, asserted and proved
+ * by one verdict, and the result still said "1 declared intent(s) are still unproved".
+ */
+export declare function intentDebt(open: readonly Intent[], dischargedId: string | undefined, now: number): IntentDebt;

package/dist/intent/open-intents.js

@@ -23,3 +23,18 @@ export async function openSessionIntents(deps, sessionId) {
 export async function allSessionIntents(deps, sessionId) {
     return new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now }).read();
 }
+/**
+ * The debt a verdict should report, MINUS the intent it is about to discharge.
+ *
+ * The discharge happens after the gaps are built, so counting the raw ledger would include the
+ * intent this very call proves — measured live: an inline intent was declared, asserted and proved
+ * by one verdict, and the result still said "1 declared intent(s) are still unproved".
+ */
+export function intentDebt(open, dischargedId, now) {
+    const stillOpen = open.filter((i) => dischargedId === undefined || i.id !== dischargedId);
+    const oldest = stillOpen.reduce((min, i) => (min === undefined || i.declaredAt < min ? i.declaredAt : min), undefined);
+    return {
+        openIntentCount: stillOpen.length,
+        ...(oldest === undefined ? {} : { oldestOpenIntentAgeMs: now - oldest }),
+    };
+}

package/dist/license/license-env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Find an enterprise licence key the customer actually placed, wherever they reasonably placed it.
+ *
+ * The daemon folded in `<cwd>/.env` and nothing else. It is spawned without an explicit `cwd`, so it
+ * inherits whatever directory the editor launched the MCP server from — in a monorepo that is the
+ * workspace root while the key sits in the app's own `.env`, and under some editors it is the user's
+ * home. The key was never read, `describeLicense` reported `missing`, and every event that customer
+ * produced said they had no licence, which is indistinguishable from a customer who has none.
+ *
+ * That is the worst shape a licensing bug can take. A key that fails LOUDLY gets reported by the
+ * customer within the hour. A key that silently fails to register leaves them believing they are
+ * licensed and us believing they are not, and neither side finds out.
+ *
+ * Two directions, because the field hits both: DOWN one level into app directories (the daemon
+ * starts at the workspace root) and UP to the project root (the editor starts inside the app).
+ *
+ * ONLY the licence key is ever taken out of a file found this way, and that restriction is the point
+ * rather than an optimisation. Bulk-importing a `.env` discovered by walking would let a directory
+ * the caller never named rebind the daemon's port, its telemetry gate or its allowed origins — a far
+ * worse bug than the one this fixes. `loadDotEnv` still owns the local file, where importing
+ * everything is what the caller asked for.
+ */
+/**
+ * The key, or undefined. Never throws, never mutates anything the caller did not ask it to.
+ *
+ * A key already present in `env` always wins: that is the operator stating it explicitly, and a file
+ * silently overriding it is the surprise `loadDotEnv` already refuses to cause.
+ */
+export declare function licenseKeyFromEnvFiles(startDir: string, env?: NodeJS.ProcessEnv): string | undefined;