@reticlehq/server 2.11.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

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

package/dist/intent/intent-store.js

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

package/dist/intent/intent-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.d.ts

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