@vibe-agent-toolkit/cli 0.1.42 → 0.2.0-rc.10

package/dist/utils/projection-lenses.js

@@ -0,0 +1,203 @@
+/**
+ * Which lenses a run evaluates, and when it does NOT — the selection that keeps
+ * the derived relations affordable.
+ *
+ * 🚨 **The selector over-selects on purpose: a FALSE NEGATIVE fails a run that
+ * had an answer.** A lens skipped when its relation is named leaves that
+ * relation ABSENT from the run's database, so the statement is refused with
+ * `no such table` — loud rather than wrong, because the refusal is SQLite's and
+ * does not depend on this scan. The cost that forced the selection, the rules
+ * that keep it fail-safe, and why the registry lives in the CLI rather than in a
+ * population are in
+ * `docs/architecture/zones.md` §2, "A lens is evaluated only when a statement
+ * names one of its relations".
+ */
+import { DERIVED_TABLES } from '@vibe-agent-toolkit/resources';
+import { evaluateClaudeContextLens } from './claude-context-lens.js';
+import { evaluateAuthoredLenses } from './edge-lens-evaluation.js';
+/** The authored-link lens: `lens_contexts`, `edges`, `edge_resolutions`. */
+export const AUTHORED_LINK_LENS = {
+    name: 'authored-link',
+    relations: ['lensContexts', 'edges', 'edgeResolutions'],
+    evaluate: ({ projection }) => evaluateAuthoredLenses(projection),
+};
+/** The always-loaded context lens: `claude_context_chains`, `claude_context_loads`. */
+export const CLAUDE_CONTEXT_LENS = {
+    name: 'claude-context',
+    relations: ['claudeContextChains', 'claudeContextLoads'],
+    evaluate: ({ root, logger, cache }) => evaluateClaudeContextLens({ root, logger, cache }),
+};
+/** Every lens the query lane can evaluate, in evaluation order. */
+export const PROJECTION_LENSES = [
+    AUTHORED_LINK_LENS,
+    CLAUDE_CONTEXT_LENS,
+];
+/**
+ * The SQL names of a lens's relations. Read off `DERIVED_TABLES` rather than
+ * restated: the SQL name and the registry key are deliberately different
+ * vocabularies (`edgeResolutions` is spelled `edge_resolutions`), so a second
+ * copy here would be a rename waiting to be missed.
+ *
+ * @param lens - The lens
+ * @returns Its relations as SQL spells them
+ */
+export function lensRelationNames(lens) {
+    return lens.relations.map((name) => DERIVED_TABLES[name].name);
+}
+/**
+ * The lenses a run has to evaluate, given the statements it declared.
+ *
+ * @param statements - Every statement the run may ask, or `undefined` when the
+ *   caller cannot enumerate them. ⛔ `undefined` selects EVERY lens — see the
+ *   header on why the fail-safe direction is not negotiable
+ * @returns The lenses to evaluate, in {@link PROJECTION_LENSES} order
+ */
+export function lensesNamedBy(statements) {
+    if (statements === undefined)
+        return PROJECTION_LENSES;
+    const readable = statements.map((sql) => wordsIn(withoutCommentsAndLiterals(sql)));
+    return PROJECTION_LENSES.filter((lens) => lensRelationNames(lens).some((relation) => readable.some((words) => namesRelation(words, relation))));
+}
+/**
+ * Evaluate one lens and hand back its rows, refusing any that are not exactly
+ * the relations it declares.
+ *
+ * `LensRows` makes every relation optional, so a lens that forgot one compiles —
+ * and `writeDerived` would leave that relation empty, a table that reads as a
+ * healthy tree. Checked here because this is the one place every lens passes.
+ *
+ * @param lens - The lens
+ * @param input - What it may read
+ * @returns Its rows
+ * @throws Error When the rows omit a declared relation or carry an undeclared one
+ */
+export async function evaluateLens(lens, input) {
+    const rows = await lens.evaluate(input);
+    const declared = lens.relations;
+    const missing = declared.filter((name) => !Object.hasOwn(rows, name));
+    const undeclared = Object.keys(rows).filter((name) => !declared.includes(name));
+    if (missing.length > 0 || undeclared.length > 0) {
+        throw new Error(`Lens "${lens.name}" must produce exactly [${declared.join(', ')}];`
+            + ` missing [${missing.join(', ')}], undeclared [${undeclared.join(', ')}]`);
+    }
+    return rows;
+}
+/**
+ * Blank out the parts of a statement that cannot name a table: line comments,
+ * block comments and single-quoted string literals. Quoted IDENTIFIERS
+ * (`"edges"`, `[edges]`, backticked) are deliberately left alone — those ARE
+ * table references, spelled differently. Replaced with spaces rather than
+ * removed, so a block comment between `FROM` and `edges` cannot let the two run
+ * together.
+ *
+ * @param sql - The statement
+ * @returns The statement with every non-code span blanked
+ */
+function withoutCommentsAndLiterals(sql) {
+    let out = '';
+    let index = 0;
+    while (index < sql.length) {
+        const end = spanEnd(sql, index);
+        if (end === undefined) {
+            out += sql.charAt(index);
+            index += 1;
+            continue;
+        }
+        const span = sql.slice(index, end);
+        out += QUOTED_IDENTIFIER_CLOSERS.has(span.charAt(0)) ? span : ' '.repeat(span.length);
+        index = end;
+    }
+    return out;
+}
+/** The characters that open a quoted identifier, and the one that closes each. */
+const QUOTED_IDENTIFIER_CLOSERS = new Map([['"', '"'], ['[', ']'], ['`', '`']]);
+/** Every quoted span's opener and closer: the identifiers, plus `'` for a literal. */
+const QUOTE_CLOSERS = new Map([...QUOTED_IDENTIFIER_CLOSERS, ["'", "'"]]);
+/**
+ * Where a span starting at `start` ends: a line comment, a block comment, a
+ * single-quoted literal — or a quoted IDENTIFIER, consumed only so it can be
+ * handed back unblanked.
+ *
+ * ⛔ Quoted identifiers MUST be consumed by this same scan even though their
+ * contents stay code, and the reason is the whole of this function. SQLite gives
+ * `'`, `--` and `/*` no meaning inside `"…"`, `[…]` or `` `…` ``. A scanner that
+ * skips those spans lets a character inside one open a literal or a comment that
+ * SQLite never opened, desynchronises, and blanks a span of REAL SQL — taking the
+ * relation name with it. The statement then reads an EMPTY relation and answers 0
+ * instead of being refused, which for a declared check is a silent exit 0: a gate
+ * that cannot fail.
+ *
+ * Scanning left to right is what keeps the spans mutually exclusive: a comment
+ * marker inside a literal is never looked at, nor a quote inside a comment.
+ *
+ * @param sql - The statement
+ * @param start - Where to look
+ * @returns The index just past the span, or undefined when none opens here
+ */
+function spanEnd(sql, start) {
+    const pair = sql.slice(start, start + 2);
+    if (pair === '--') {
+        const newline = sql.indexOf('\n', start);
+        return newline === -1 ? sql.length : newline;
+    }
+    if (pair === '/*') {
+        const close = sql.indexOf('*/', start + 2);
+        return close === -1 ? undefined : close + 2;
+    }
+    const closer = QUOTE_CLOSERS.get(sql.charAt(start));
+    return closer === undefined ? undefined : quotedEnd(sql, start, closer);
+}
+/**
+ * Where a quoted span ends. A doubled closer (`''`, `""`, two backticks) is an
+ * escaped one; `[…]` has no escape. Left unterminated, the span ends at the last
+ * doubled closer instead — what the single pattern this replaced did by
+ * backtracking.
+ *
+ * @param sql - The statement
+ * @param start - The opening quote
+ * @param closer - The character that closes it
+ * @returns The index just past the span, or undefined when it never closes
+ */
+function quotedEnd(sql, start, closer) {
+    let fallback;
+    let from = start + 1;
+    for (;;) {
+        const close = sql.indexOf(closer, from);
+        if (close === -1)
+            return fallback;
+        if (closer === ']' || sql.charAt(close + 1) !== closer)
+            return close + 1;
+        fallback = close + 1;
+        from = close + 2;
+    }
+}
+/**
+ * Every whole word in a statement, lowercased.
+ *
+ * Relation names are `[a-z_]` only and `_` is a word character, so membership in
+ * this set answers exactly what a `\b`-anchored search would: `my_edges`
+ * tokenizes whole and never answers for `edges`. One pass per statement, rather
+ * than one pattern per relation, and no `RegExp` built from a variable.
+ *
+ * @param sql - The statement, already stripped of comments and literals
+ * @returns Its identifier-character runs, lowercased
+ */
+function wordsIn(sql) {
+    return new Set((sql.match(IDENTIFIER_RUNS) ?? []).map((word) => word.toLowerCase()));
+}
+/** Runs of identifier characters — SQL's word boundaries, the `\b` equivalent. */
+const IDENTIFIER_RUNS = /[a-z0-9_]+/gi;
+/**
+ * Does a statement's word set name this relation?
+ *
+ * Case-folds the relation as well as the words: a registry name spelled with an
+ * uppercase letter would otherwise miss every statement silently.
+ *
+ * @param words - The statement's words, from {@link wordsIn}
+ * @param relation - The relation's SQL name
+ * @returns True when the statement could be reading that relation
+ */
+function namesRelation(words, relation) {
+    return words.has(relation.toLowerCase());
+}
+//# sourceMappingURL=projection-lenses.js.map

package/dist/utils/projection-lenses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection-lenses.js","sourceRoot":"","sources":["../../src/utils/projection-lenses.ts"],"names":[],"mappings":"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"}

package/dist/utils/projection-query.d.ts

@@ -0,0 +1,324 @@
+/**
+ * Populating a tree's resource projection and putting it somewhere ASKABLE —
+ * the shared half of every command that runs SQL over it.
+ *
+ * `vat resources query` runs one statement a person typed; `vat resources check`
+ * runs the statements a project wrote down. They differ in what they do with
+ * rows and in nothing else: same population, same store selection, same
+ * ephemeral fallback, same cache tell. This module is that "and in nothing
+ * else", stated once so the two cannot drift into answering about different
+ * corpora.
+ *
+ * ## 🚨 The SQL ALWAYS runs against a per-run in-memory database. Never the store.
+ *
+ * This is a correctness property, not an optimisation choice, and it was learned
+ * the expensive way. The on-disk projection store is **one database per VAT
+ * release, shared by every root on the machine** (`defaultStoreDirectory()` is
+ * `tmpdir/.vat-cache/<version>/projection-<shapeDigest>`), it retains three tree
+ * hashes per root, and its blob tier is never evicted and carries no tree key at
+ * all. `ProjectionStore.readExtent` narrows by `(rootId, treeHash)`; **arbitrary
+ * SQL does not**, and cannot be made to — a `WHERE` clause the caller wrote is
+ * not a key predicate.
+ *
+ * So running a user's statement against the file-backed store answered from
+ * every projection on the machine. Measured on a two-file scratch repository:
+ * `SELECT COUNT(*) FROM resource_realizations` returned **3** with no store and
+ * **5,779** with one, and `WHERE path LIKE 'packages/%'` returned paths from a
+ * different repository entirely. That is a wrong answer and a cross-project
+ * disclosure of link text, heading text and frontmatter — the same material
+ * `store.ts` cites as the reason it chmods the cache `0o700`.
+ *
+ * ⇒ The store's job is to make the POPULATION cheap, and that is all. Whatever
+ * `populate()` returns — served from the store or derived — is written into a
+ * fresh in-memory database that holds this tree and nothing else, and the SQL
+ * runs there. The saving is untouched (it was always in the population: on this
+ * repository {@link ProjectionProvenance.populationMs} reads 1.16-1.18 s derived
+ * against 0.29-0.31 s served), and "one tree, one answer" stops being a claim
+ * about how callers behave and becomes a property of the shape.
+ *
+ * ## The store never reaches a caller
+ *
+ * Work runs against an `ask` closure rather than a store handle. That is
+ * deliberate: `utils/projection-store.ts` is the one module in the toolkit that
+ * knows `@vibe-agent-toolkit/projection-sqlite` exists, and handing commands a
+ * backend-typed object would spread that knowledge to every future verb. A
+ * closure also puts the legible-failure wrapper on the single path that can
+ * throw, so no command can forget it.
+ */
+import { type Projection } from '@vibe-agent-toolkit/resources';
+import type { Logger } from './logger.js';
+/** Where the POPULATION a statement ran against came from. */
+export type PopulationOrigin = 'derived' | 'store';
+/**
+ * What a run's rows are, and where they came from.
+ *
+ * ⚠️ There is deliberately no `engine` field beside these. An earlier version
+ * published one (`sqlite | ephemeral`) to say which database answered the SQL;
+ * it is gone because the answer is now always the same — see the header — and a
+ * field with one possible value tells a reader nothing while implying the other
+ * value is reachable.
+ */
+export interface ProjectionProvenance {
+    /**
+     * 🔑 The cache tell. Reported rather than inferred, because it CANNOT be
+     * inferred: a correct store hit and a correct re-derivation produce identical
+     * rows. A hit short-circuits `populate()` before the builder exists, so no
+     * contributor timing is filed — an empty record list IS the hit.
+     *
+     * It describes the POPULATION, which is the only thing the store now affects.
+     */
+    readonly population: PopulationOrigin;
+    /**
+     * 🔑 What that origin was WORTH. {@link population} says whether the
+     * projection was served or re-derived; this says what the difference cost, so
+     * the tell stops being a bare label a reader has to take on faith.
+     *
+     * Measured as THIS field, by running `vat resources query 'SELECT COUNT(*) AS
+     * n FROM blobs'` against this repository three times per arm with the parse
+     * cache warm: **1.16-1.18 s derived against 0.29-0.31 s served**. With a cold
+     * parse cache the derived arm is 33-35 s, so the pair above is the store's
+     * saving and not the parse cache's.
+     *
+     * The wall time of the SHARED setup and nothing else: everything
+     * {@link withQueriedProjection} does before it hands control to the caller's
+     * work — opening the population cache (which, when a store is selected, is a
+     * `git write-tree` spawn plus the backend's dynamic import and
+     * `openSqliteProjectionStore()`), the git tracker, `buildResourceProjection`,
+     * opening the ephemeral database, and writing the blob tier and the extent
+     * into it.
+     *
+     * ⚠️ The population cache's CLOSE is outside it, necessarily: that runs in
+     * `withPopulationCache`'s `finally`, after the caller's work returns, and a
+     * span that ends before the work begins cannot contain it. It is a handle
+     * release, not population.
+     *
+     * 🪤 **The span's start is load-bearing, and moving it inward is silent.**
+     * This shipped with the clock started on the first line INSIDE
+     * `withPopulationCache`'s callback — which put the population-cache open, the
+     * only part of the setup a store adds, OUTSIDE the measurement, and only on
+     * the arm where a store exists. Measured on a two-file corpus with identical
+     * total wall time on both arms: no store 0.145 of 0.146 s, cold store 0.0475
+     * of 0.161 s. Same work, `populationSecs` three times apart, and a reader
+     * comparing a no-store run to a warm-store run read a 42x saving where the
+     * honest totals differ by 1.75x. The field was added to stop the cache tell
+     * being a label taken on faith and had become the artifact instead. A
+     * measurement that flatters one arm is this repository's most-repeated
+     * defect; the system suite now pins `populationSecs / durationSecs > 0.6` on a
+     * cold run so the next inward move is red rather than quiet.
+     *
+     * ## Why it belongs on shared provenance rather than on one verb
+     *
+     * Both verbs pay it, identically, because it is the half of the run they hold
+     * in common — a `check` that runs forty statements and a `query` that runs one
+     * do the same population first. And a per-statement cost is UNREADABLE without
+     * it: `vat resources check` publishes what each rule's SQL cost, and a reader
+     * handed forty small numbers and a large total has no way to tell an expensive
+     * rule from a setup everybody shares. Absent this field the only arithmetic
+     * available is "total minus the statements", which silently attributes the
+     * shared setup to whichever rule the reader is looking at.
+     *
+     * ⚠️ Measured with `performance.now()`, not `Date.now()`. A warm population
+     * lands well under a millisecond on a small tree, and a millisecond-granularity
+     * clock reports that as `0` — which reads as "not measured" rather than "very
+     * fast", turning the best case the store has into its least credible number.
+     *
+     * ⚠️ Deliberately ONE number, not a breakdown. Splitting it into crawl, parse
+     * and store-load is a real question and it is the lab's: an instrument that
+     * gets reviewed and re-run, rather than a product document that would then owe
+     * every consumer a stable sub-phase vocabulary.
+     */
+    readonly populationMs: number;
+    /**
+     * The lenses this run evaluated, by name, in evaluation order.
+     *
+     * 🔑 **Published because "which lenses ran" became a DECISION, and an
+     * unpublished decision is one nobody can check.** Without it an empty derived
+     * relation is ambiguous — no rows, or no evaluation? This is the tell, in the
+     * same family as {@link population}, and what makes a `lensSecs` of `0`
+     * legible rather than alarming.
+     *
+     * ⚠️ Not the only guard: a relation no evaluated lens produced does not
+     * EXIST in the run's database, so a statement naming it is refused by SQLite
+     * (see {@link withQueriedProjection}). This field explains a cheap run rather
+     * than excusing a blind one.
+     */
+    readonly lensesEvaluated: readonly string[];
+    /**
+     * What EVALUATING THE LENSES cost, separately from populating the tree.
+     *
+     * Separate because the two answer different questions and a reader must be
+     * able to tell them apart. Population is work every verb pays and the store
+     * can make cheap; this is work the *derived relations* cost, and a store hit
+     * does NOT make an authored-link evaluation cheaper — it is a pass over the
+     * served rows just as over derived ones. Folded into `populationMs` it would
+     * look like the store getting worse.
+     *
+     * ⚠️ **Not an unconditional cost.** A run whose statements name no derived
+     * relation evaluates nothing and reports `0`; {@link lensesEvaluated} says
+     * which lenses the number covers.
+     *
+     * ⚠️ **DISJOINT from `populationMs`, and that is enforced by where the
+     * population clock stops, not by convention.** It shipped overlapping: the
+     * population span ended after the lens write, so this value was contained in
+     * that one while all three docstrings said otherwise, and anyone adding the
+     * two over-counted wall time. If you move either clock, keep them disjoint —
+     * a reader comparing a served run against a derived one is the whole reason
+     * they are two fields.
+     *
+     * ⚠️ Published rather than merely measured, because a cost that is invisible
+     * is the one nobody can argue with. It is the evidence the selection above
+     * rests on, and the evidence any future flag would rest on.
+     */
+    readonly lensMs: number;
+}
+/**
+ * How much of the tree the population actually covered.
+ *
+ * ## Why this is not a field on {@link ProjectionProvenance}
+ *
+ * Provenance is a fact both verbs PUBLISH verbatim — "these rows were served or
+ * re-derived" is the same sentence in either document. This is a fact a verb
+ * REASONS with, and only one of them has anything to reason about: `vat
+ * resources query` prints the rows a person selected, so its reader can see the
+ * extent for themselves, while `vat resources check` prints a verdict and a
+ * count of rules. Only the second can pass vacuously, and only the second needs
+ * to know.
+ *
+ * ## 🔑 The failure it exists to make visible
+ *
+ * `vat resources check` reported how many CHECKS ran; nothing said how many ROWS
+ * they ran against. So "four checks passed over eight thousand files" and "four
+ * checks passed over ZERO files" were byte-identical documents, and the second
+ * was a green gate asserting nothing. A broad `.gitignore`, a shallow or sparse
+ * checkout, a root that resolved elsewhere, or an extent source that enumerated
+ * nothing all produce it — and `buildResourceProjection` DECLINES ignored
+ * members rather than flagging them, so an emptied enumeration leaves no trace
+ * in the tables either.
+ */
+export interface PopulationExtent {
+    /**
+     * One per `(extentId, path)` row the population enumerated.
+     *
+     * 🪤 Realizations rather than any other count, because every alternative
+     * fails to reach zero on the case that matters: `roots` always holds exactly
+     * one row (the invariant thrown for below), so a total over all thirteen tables
+     * is never 0; `blobs` is content-keyed and deduped, so it counts parse REACH
+     * and already has its own guard in `onBlobPopulation`; and `resources` counts
+     * identities, which a corpus can legitimately have none of while enumerating
+     * plenty. One row per enumerated path is non-zero exactly when something was
+     * enumerated.
+     */
+    readonly membersEnumerated: number;
+}
+/** One statement a run intends to ask, with the values it will bind to it. */
+export interface PreflightStatement {
+    readonly sql: string;
+    /** Bound in order, one per `?`. Empty for a statement that binds nothing. */
+    readonly parameters: readonly string[];
+}
+/** Run one read-only statement against the populated projection. */
+export type AskProjection = (sql: string, ...parameters: readonly string[]) => readonly Record<string, unknown>[];
+/**
+ * Compile every statement a run intends to ask, against the schema and NO rows,
+ * before anything is populated.
+ *
+ * ## 🔑 What this buys, measured
+ *
+ * SQLite resolves table and column names when a statement is *prepared*, not
+ * when it is stepped — so a typo is knowable before a single row exists. It was
+ * not knowable in practice, because the only place a statement met the schema
+ * was after the projection had been built. On a real adopter tree, `SELECT path,
+ * no_such_column …` cost **8.3 s**, every millisecond of it spent building a
+ * projection the statement could never have read. The same typo now costs the
+ * price of an empty in-memory database — one extra `createSchema` into
+ * `:memory:`, which is the whole overhead this adds on the happy path.
+ *
+ * It also moves the KIND refusals — a second statement, an `ATTACH`, a `PRAGMA`
+ * — in front of the population, so a statement rejected for what it is costs no
+ * more than one rejected for what it names.
+ *
+ * ⚠️ **This is a pre-flight, not a second gate.** `ask` still compiles and runs
+ * the real statement against the real projection, and nothing here is trusted in
+ * place of that. A statement that compiles here can still fail there — SQLite
+ * resolves names against a schema, and this is the same schema, but a run-time
+ * error (a bad cast, an overflow) belongs to stepping and is unreachable from a
+ * prepare.
+ *
+ * ⚠️ It deliberately does not STEP anything. Stepping is where a check's
+ * unbounded cost lives, and a preflight that ran `WITH RECURSIVE …` would hang
+ * before the run it exists to make cheap had begun.
+ *
+ * ⚠️ Each statement comes WITH the values it will be bound to, because the
+ * placeholder count is part of what compiles: a `?` the caller forgot to bind is
+ * SQL NULL at run time, and the statement then selects nothing and reports
+ * success — the same silent class as a typo'd column, and worth the same early
+ * refusal. The backend does the counting; this only has to hand it the values.
+ *
+ * @param statements - Every statement the run will ask, in any order, each with
+ *   the values it will bind
+ * @throws The same legible failure `ask` throws, for the first statement that
+ *   does not compile or does not pair its placeholders with its values
+ */
+export declare function assertQueriesCompile(statements: readonly PreflightStatement[]): Promise<void>;
+/**
+ * Populate the tree, load it into something askable, and hand the caller a way
+ * to ask.
+ *
+ * @param options - The run
+ * @param options.root - Absolute corpus root
+ * @param options.logger - Where blob-stage refusals are reported (stderr, so a
+ *   parseable document on stdout stays parseable)
+ * @param options.preflight - Every statement this run intends to ask, compiled
+ *   against the empty schema BEFORE the population starts. See
+ *   {@link assertQueriesCompile}
+ * @param options.statements - Every statement this run may ask, for LENS
+ *   SELECTION only — never compiled, never bound, and deliberately separate from
+ *   `preflight`. ⛔ Omitting it evaluates EVERY lens, which is the correct answer
+ *   and the expensive one
+ * @param work - Given the asker, where its rows came from, how much of the tree
+ *   they cover, and the ROWS THEMSELVES. The store is open for exactly this call
+ *   and closed however it ends
+ * @returns Whatever `work` returned
+ */
+export declare function withQueriedProjection<T>(options: {
+    root: string;
+    logger: Logger;
+    preflight?: readonly PreflightStatement[];
+    statements?: readonly string[];
+}, work: (ask: AskProjection, provenance: ProjectionProvenance, extent: PopulationExtent, projection: Projection) => Promise<T> | T): Promise<T>;
+/**
+ * Turn a rejected statement into a message that names the surface it missed.
+ *
+ * ## Why this wrapper exists
+ *
+ * VAT ships no schema version, by standing rule — the *cache* is safe across a
+ * shape change because its digest self-invalidates, but submitted SQL is not: it
+ * simply breaks. Pre-1.0 that is acceptable. A raw SQLite error reaching the
+ * user is not, because `no such column: contentHash` says nothing about what the
+ * column is called now. It matters more for a CHECK than for a query: a query's
+ * author is at the keyboard, while a check's author wrote it months ago and the
+ * person reading the failure is someone else.
+ *
+ * ⚠️ **A legibility wrapper, not a validator.** It does not parse SQL and does
+ * not check a statement before running it — it reacts to a failure by listing
+ * what the query COULD have named. When the statement mentions a known table,
+ * that table's columns are listed, which is the case that actually answers "what
+ * moved"; otherwise the table names are, which at least answers "what is there".
+ *
+ * 🪤 **Only a name that was not found gets the listing.** The engine also refuses
+ * a write and this backend refuses a second statement, and neither is answered by
+ * a column list — appending one says the problem is the schema when the problem
+ * is what the caller asked for. A wrapper that decorates every failure identically
+ * teaches the reader to skip the decoration, which costs the case it was written for.
+ *
+ * Matching is a plain lowercase substring test rather than a regex: the input is
+ * user text, and a pattern built from it is both a lint failure here and a
+ * needless hazard.
+ *
+ * @param sql - The statement that was submitted
+ * @param message - What the engine said
+ * @returns The message to surface, with the queryable surface appended when the
+ *   failure was a name this projection does not have
+ */
+export declare function describeQueryFailure(sql: string, message: string): string;
+//# sourceMappingURL=projection-query.d.ts.map

package/dist/utils/projection-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection-query.d.ts","sourceRoot":"","sources":["../../src/utils/projection-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAIH,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAsB1C,8DAA8D;AAC9D,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAE5C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,UAAU,EAAE,SAAS,MAAM,EAAE,KAC7B,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBnG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,OAAO,EAAE;IACP,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC1C,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC,EACD,IAAI,EAAE,CACJ,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,gBAAgB,EAQxB,UAAU,EAAE,UAAU,KACnB,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,CAgIZ;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAsCzE"}