@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,133 @@
+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';
+/**
+ * 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;
+        });
+    }
+    /**
+     * 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;
+        });
+    }
+    /** 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/memory/intent/intent-subject.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What an intent is ABOUT — the key the store shards on, and the thing that makes it retrievable.
+ *
+ * `.reticle/intent.json` grew without bound 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 every other rule in the project 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. */
+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;
+export {};

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

@@ -0,0 +1,175 @@
+/**
+ * What an intent is ABOUT — the key the store shards on, and the thing that makes it retrievable.
+ *
+ * `.reticle/intent.json` grew without bound 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 every other rule in the project 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, one record each — enough of
+         * them to make 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. The
+ * alternative, a testid's prefix, yields `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/memory/intent/intent-tools.d.ts

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

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

@@ -0,0 +1,157 @@
+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 '@reticlehq/core';
+import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { sessionRoot } from '../project/session-root.js';
+import { asString } from '@reticlehq/core';
+/**
+ * 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';
+/* 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, 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: [
+                { id: 'checkin', statement: 'clicking Send check-in makes the badge read "checked in"' },
+            ],
+        },
+        inputSchema: {
+            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(),
+                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.'),
+            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']) };
+            }
+            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] };
+            }
+            const raw = args['intents'];
+            const entries = Array.isArray(raw)
+                ? raw
+                : [];
+            const declared = await store.declare(entries);
+            return { intents: declared, path: root };
+        },
+    },
+];

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

@@ -0,0 +1,36 @@
+import type { Intent } from '@reticlehq/core/artifacts';
+import type { ToolDeps } from '../../surface/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[]>;
+/** What the ledger still owes once this verdict's own intent is discharged, and how old it is. */
+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;
+}
+export declare function intentDebt(open: readonly Intent[], dischargedId: string | undefined, now: number): IntentDebt;
+export {};

package/dist/memory/intent/open-intents.js

@@ -0,0 +1,58 @@
+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();
+}
+/**
+ * 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".
+ */
+/**
+ * How old an open intent may be and still be THIS run's debt.
+ *
+ * The ledger is project-scoped and outlives every session, so without a horizon a verdict's honesty
+ * block reports the whole standing backlog — weeks of it, on every passing verdict, to say something
+ * the same sentence admitted was "probably not what this run is about".
+ *
+ * A day, matching the age threshold the gap already used to decide a backlog was stale. Anything
+ * older is not silently forgiven: it is exactly what `reticle_context` lists, which is where the
+ * gap's own `fix` sends the reader. The distinction is which QUESTION each answers — "did this run
+ * leave something unproved" is actionable on the result being read, "what does this project owe"
+ * is a separate ask — and collapsing them made the actionable one unreadable.
+ */
+const THIS_RUN_MS = 86_400_000;
+export function intentDebt(open, dischargedId, now) {
+    const stillOpen = open
+        .filter((i) => dischargedId === undefined || i.id !== dischargedId)
+        // `<=` on the age, so a clock corrected backwards (declaredAt in the future) stays counted
+        // rather than being filtered out as ancient — the existing negative-age case.
+        .filter((i) => now - i.declaredAt <= THIS_RUN_MS);
+    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/memory/journal/ambient-store.d.ts

@@ -0,0 +1,13 @@
+import type { FileSystemPort } from '../project/fs/fs-port.js';
+import { type AmbientCounts } from '@reticlehq/engine/window/ambient.js';
+/**
+ * Persists the learned ambient-churn region map at `.reticle/ambient.json`. Local, single-project
+ * memory (stays OSS — OSS-VS-SERVER). Loads never throw: missing/malformed/wrong-version degrades to
+ * an empty map, so a bad file never breaks a drive — the layer just re-learns the ambient regions.
+ */
+export declare class AmbientStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string);
+    load(): Promise<AmbientCounts>;
+    save(counts: AmbientCounts): Promise<void>;
+}