@quereus/quereus 3.3.0 → 4.1.0

package/dist/src/schema/lens-ack.js

@@ -0,0 +1,361 @@
+import { ACKNOWLEDGEABLE_ADVISORY_CODES } from './lens-prover.js';
+import { getReservedTag, getReservedTagByTemplate } from './reserved-tags.js';
+import { fnv1aHash, toBase64Url } from '../util/hash.js';
+/**
+ * Lens advisory acknowledgment & escalation governance — the anti-fatigue half
+ * of the lens capstone (`docs/lens.md` § Acknowledging advisories).
+ *
+ * Sits **atop** the advisory list the prover (`lens-prover.ts`) produces: that
+ * module proves write-soundness and emits coded, sited, fingerprint-bearing
+ * advisories; this module lets a developer consciously accept those advisories
+ * in source (the reserved `quereus.lens.ack.<code>` tag), **re-surfaces** them
+ * when the underlying facts change (fingerprint mismatch), and lets a project
+ * escalate specific codes to hard requirements (`error-on` / `require-ack`).
+ * No new enforcement semantics — pure governance over the advisory channel.
+ *
+ * The three mechanics the doc locks (and this module realizes):
+ *  - **Coded + sited + targeted.** An ack `quereus.lens.ack.<code>[:<target>]`
+ *    on the logical table or a constraint suppresses exactly the advisory whose
+ *    `(code, site[, target])` it names — never a class by accident.
+ *  - **Fingerprinted (anti-fatigue).** Each ack records the coarse facts behind
+ *    its advisory ({@link FingerprintInputs}, banded so ordinary churn is
+ *    invisible). When the recorded fingerprint no longer matches the freshly
+ *    computed one, the advisory re-surfaces flagged "previously acknowledged;
+ *    situation changed." A first-write ack with no recorded fingerprint is
+ *    honored *unconditionally* (record-on-first-sight; the author opted out of
+ *    re-surfacing).
+ *  - **Escalation policy.** `error-on: [code]` makes the code a hard error an ack
+ *    cannot suppress; `require-ack: [code]` makes an *un*-acknowledged instance a
+ *    hard error a valid ack clears. Default-empty (projects opt in).
+ */
+/**
+ * Advisory codes are spelled `lens.<x>` ({@link LensCheckCode}); the ack tag
+ * `quereus.lens.ack.<code>` carries only the `<x>` remainder (the `quereus.lens.`
+ * literal already encodes the `lens.` prefix). So `lens.no-backing-index` is
+ * acknowledged by `quereus.lens.ack.no-backing-index`.
+ */
+const ADVISORY_CODE_PREFIX = 'lens.';
+const ACK_TEMPLATE = 'quereus.lens.ack.<code>';
+/**
+ * In-DDL fingerprint storage (resolved-lean): the recorded fingerprint rides the
+ * ack tag *value* as a trailing `#fp=<hash>` token, so it survives schema export
+ * round-trip, is version-controlled, and shows up in review alongside the
+ * rationale (the same reason the lens doc keeps acks in source). This is the
+ * least-noisy shape that round-trips through `reserved-tags.ts` validation: the
+ * value is still a single non-empty TEXT rationale (validation unchanged), and no
+ * sibling key collides with the `quereus.lens.ack.<code>` template. The anchored
+ * suffix keeps an ordinary rationale (which may contain `#`) unambiguous.
+ */
+const FINGERPRINT_SUFFIX_RE = /\s*#fp=([A-Za-z0-9_-]+)\s*$/;
+/** The default policy: nothing escalated (out of the box). */
+export const EMPTY_ESCALATION_POLICY = {
+    errorOn: new Set(),
+    requireAck: new Set(),
+};
+/**
+ * Resolves the escalation policy for one logical table from its reserved policy
+ * tags (`quereus.lens.policy.error-on` / `quereus.lens.policy.require-ack`, each a
+ * CSV of advisory codes). Default-empty when neither tag is present — out of the
+ * box no code is escalated; a project opts in per logical table. (A schema-wide
+ * policy is expressed by tagging each table; see `docs/lens.md` § Escalation
+ * policy.)
+ */
+export function resolveEscalationPolicy(logicalTable) {
+    return {
+        errorOn: parseCodeCsv(getReservedTag(logicalTable.tags, 'quereus.lens.policy.error-on')),
+        requireAck: parseCodeCsv(getReservedTag(logicalTable.tags, 'quereus.lens.policy.require-ack')),
+    };
+}
+/**
+ * Parses a CSV of advisory codes into a set of **code bases** (empty when
+ * absent). Each entry is normalized through {@link advisoryCodeBase}, so a policy
+ * may name a code either fully (`lens.no-backing-index`) or bare
+ * (`no-backing-index`, mirroring the ack tag remainder) — both resolve to the
+ * same base the governance compares against. Without this, the bare form would
+ * silently no-op the escalation.
+ */
+function parseCodeCsv(value) {
+    const set = new Set();
+    if (!value)
+        return set;
+    for (const part of value.split(',')) {
+        const code = part.trim().toLowerCase();
+        if (code.length > 0)
+            set.add(advisoryCodeBase(code));
+    }
+    return set;
+}
+// ---------------------------------------------------------------------------
+// Fingerprint
+// ---------------------------------------------------------------------------
+/**
+ * Computes the stable fingerprint of an advisory from the coarse facts behind it
+ * ({@link FingerprintInputs}) plus its code + site. Canonicalized (columns
+ * lowercased + sorted, cardinality already **banded** by the prover) so ordinary
+ * row-count drift within a band does not churn the hash — only a band crossing,
+ * a covering-structure change, or a constraint-column change moves it. The result
+ * is a short base64url FNV-1a digest, suitable for embedding in the ack tag value.
+ *
+ * **Cardinality bands** (`lens-prover.ts:cardinalityBand`): `empty` (0 rows),
+ * `small` (<1e3), `medium` (<1e6), `large` (≥1e6), `unknown` (no estimate). An
+ * ack survives any row-count change that stays within one band; crossing a band
+ * boundary re-surfaces it.
+ */
+export function computeAdvisoryFingerprint(code, site, inputs) {
+    const canonical = JSON.stringify({
+        code,
+        table: site.table.toLowerCase(),
+        constraint: site.constraint?.toLowerCase() ?? null,
+        column: site.column?.toLowerCase() ?? null,
+        cols: inputs?.constraintColumns
+            ? [...inputs.constraintColumns].map(c => c.toLowerCase()).sort()
+            : null,
+        cover: inputs?.hasCoveringStructure ?? null,
+        band: inputs?.cardinalityBand ?? null,
+        basis: inputs?.basisRelation ?? null,
+        // Conditionally serialized: advisories carrying no domain (every code
+        // before `lens.getput-lossy`) keep their pre-existing hashes, while a
+        // CHECK `in (...)` list change moves a round-trip advisory's fingerprint
+        // and re-surfaces its acknowledgment.
+        ...(inputs?.domainValues ? { domain: [...inputs.domainValues].sort() } : {}),
+        // Conditionally serialized (same as `domain`): only `lens.over-restrictive-basis-key`
+        // carries a governing basis key, so every other advisory keeps its existing hash. A
+        // basis-key change (tightened to match the logical key, or loosened) moves the hash
+        // and re-surfaces the acknowledgment.
+        ...(inputs?.basisKeyColumns ? { basisKey: [...inputs.basisKeyColumns].map(c => c.toLowerCase()).sort() } : {}),
+    });
+    return toBase64Url(fnv1aHash(canonical)).slice(0, 12);
+}
+/** Splits an ack tag value into `{ rationale, recordedFingerprint }`. */
+function parseAckValue(value) {
+    const m = FINGERPRINT_SUFFIX_RE.exec(value);
+    if (!m)
+        return { rationale: value.trim() };
+    return { rationale: value.slice(0, m.index).trim(), recordedFingerprint: m[1] };
+}
+/** Splits an ack template segment `<code>[:<target>]` into its parts. */
+function splitAckSegment(segment) {
+    const colon = segment.indexOf(':');
+    if (colon < 0)
+        return { codeBase: segment.toLowerCase() };
+    return { codeBase: segment.slice(0, colon).toLowerCase(), target: segment.slice(colon + 1).toLowerCase() };
+}
+/** Collects every ack on the logical table's tags. */
+function collectTableAcks(tags) {
+    return getReservedTagByTemplate(tags, ACK_TEMPLATE).map(inst => {
+        const { codeBase, target } = splitAckSegment(inst.segment);
+        const { rationale, recordedFingerprint } = parseAckValue(inst.value);
+        return { codeBase, target, rationale, recordedFingerprint, emptyRationale: rationale.length === 0, scope: 'table' };
+    });
+}
+/** Collects every ack on one constraint's tags (scoped to that constraint's columns). */
+function collectConstraintAcks(constraint, columnNames) {
+    if (constraint.kind === 'primaryKey')
+        return []; // a PK carries no tag surface
+    const tags = constraint.constraint.tags;
+    const cols = constraintColumns(constraint, columnNames);
+    return getReservedTagByTemplate(tags, ACK_TEMPLATE).map(inst => {
+        const { codeBase, target } = splitAckSegment(inst.segment);
+        const { rationale, recordedFingerprint } = parseAckValue(inst.value);
+        return {
+            codeBase, target, rationale, recordedFingerprint,
+            emptyRationale: rationale.length === 0, scope: 'constraint', constraintColumns: cols,
+        };
+    });
+}
+/** The lowercased column names a constraint covers (best-effort by kind). */
+function constraintColumns(constraint, columnNames) {
+    const idx = (i) => (columnNames.get(i) ?? `#${i}`).toLowerCase();
+    switch (constraint.kind) {
+        case 'primaryKey': return constraint.columns.map(c => idx(c.index));
+        case 'unique': return constraint.constraint.columns.map(idx);
+        case 'foreignKey': return constraint.constraint.columns.map(idx);
+        case 'check': return [];
+    }
+}
+/** Reads every ack on a slot (table tags + each constraint's tags). */
+function collectAcks(slot) {
+    const columnNames = new Map();
+    slot.logicalTable.columns.forEach((c, i) => columnNames.set(i, c.name));
+    const acks = collectTableAcks(slot.logicalTable.tags);
+    for (const c of slot.attachedConstraints)
+        acks.push(...collectConstraintAcks(c, columnNames));
+    return acks;
+}
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+/** The advisory-code base an ack must name to suppress this advisory. */
+function advisoryCodeBase(code) {
+    return code.startsWith(ADVISORY_CODE_PREFIX) ? code.slice(ADVISORY_CODE_PREFIX.length) : code;
+}
+/** Does `target` (an ack refinement) name this advisory's constraint / column / one of its columns? */
+function targetMatches(target, advisory) {
+    const cols = advisory.fingerprintInputs?.constraintColumns ?? [];
+    return target === advisory.site.constraint?.toLowerCase()
+        || target === advisory.site.column?.toLowerCase()
+        || cols.some(c => c.toLowerCase() === target);
+}
+/** Do an ack's constraint columns (set) equal the advisory's constraint columns (set)? */
+function constraintColumnsMatch(ackColumns, advisory) {
+    const advCols = advisory.fingerprintInputs?.constraintColumns;
+    if (!ackColumns || !advCols || ackColumns.length !== advCols.length)
+        return false;
+    const advSet = new Set(advCols.map(c => c.toLowerCase()));
+    return ackColumns.every(c => advSet.has(c.toLowerCase()));
+}
+/** Finds the ack (if any) that suppresses `advisory`. See § Coded + sited + targeted. */
+function matchAck(advisory, acks) {
+    const base = advisoryCodeBase(advisory.code);
+    for (const ack of acks) {
+        if (ack.codeBase !== base)
+            continue;
+        if (ack.target !== undefined) {
+            if (targetMatches(ack.target, advisory))
+                return ack;
+            continue;
+        }
+        // Untargeted: a table ack suppresses the class for that table; a
+        // constraint ack only its own constraint (matched by its column set).
+        if (ack.scope === 'table')
+            return ack;
+        if (constraintColumnsMatch(ack.constraintColumns, advisory))
+            return ack;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Governance
+// ---------------------------------------------------------------------------
+/**
+ * The recognized escalation-policy code bases — every advisory code that can flow
+ * through governance, normalized through {@link advisoryCodeBase} so it compares
+ * against a policy's bare/`lens.`-prefixed forms exactly as the resolved policy set
+ * stores them. A policy entry whose base is absent here names no real advisory and
+ * would silently fail open, so {@link applyAckGovernance} rejects it.
+ */
+const RECOGNIZED_ADVISORY_BASES = new Set([...ACKNOWLEDGEABLE_ADVISORY_CODES].map(advisoryCodeBase));
+/** The recognized advisory codes (full `lens.<base>` form), for diagnostics. */
+const RECOGNIZED_ADVISORY_CODES_DISPLAY = [...ACKNOWLEDGEABLE_ADVISORY_CODES].join(', ');
+/**
+ * Emits one error {@link LensDiagnostic} for each policy code that names no real
+ * advisory — a typo'd or stale escalation entry that would otherwise silently fail
+ * open (the deploy stays advisory while the author believes they hardened it). The
+ * resolved policy holds normalized bases; the full `lens.<base>` form is
+ * reconstructed for the message. Validated against the *vocabulary*, independent of
+ * whether any advisory currently fires (pre-empting a not-yet-triggered but
+ * recognized code is valid and must NOT error).
+ */
+function validatePolicyCodes(slot, policy) {
+    const errors = [];
+    const check = (bases, tag) => {
+        for (const base of bases) {
+            if (RECOGNIZED_ADVISORY_BASES.has(base))
+                continue;
+            errors.push(unknownPolicyCodeError(slot, tag, base));
+        }
+    };
+    check(policy.errorOn, 'error-on');
+    check(policy.requireAck, 'require-ack');
+    return errors;
+}
+/** The deploy-blocking diagnostic for an unrecognized escalation policy code. */
+function unknownPolicyCodeError(slot, tag, base) {
+    const table = slot.logicalTable.name;
+    return {
+        code: 'lens.unknown-policy-code',
+        severity: 'error',
+        site: { table },
+        message: `lens: escalation policy tag 'quereus.lens.policy.${tag}' on '${table}' references unknown advisory code '${ADVISORY_CODE_PREFIX}${base}' — it will never match and the escalation silently does nothing; recognized codes: ${RECOGNIZED_ADVISORY_CODES_DISPLAY}`,
+        resurfaced: false,
+    };
+}
+/**
+ * Applies ack-suppression, fingerprint re-surfacing, and the escalation policy to
+ * one slot's prover warnings. Pure analysis — does not mutate the slot or report.
+ *
+ * First validates the policy codes against the advisory vocabulary
+ * ({@link validatePolicyCodes}) — an unrecognized code is a deploy-blocking error,
+ * never a silent no-op. Then, order per advisory:
+ *  1. **error-on** wins first — the code is a hard error regardless of any ack.
+ *  2. Otherwise match an ack. No ack ⇒ the advisory stays in the default report.
+ *  3. A matched ack with a recorded fingerprint that *mismatches* the freshly
+ *     computed one ⇒ the advisory **re-surfaces** (flagged), counted as
+ *     un-acknowledged. A matching (or first-sight, unconditional) fingerprint ⇒
+ *     acknowledged + suppressed. An empty rationale additionally surfaces a
+ *     meta-warning (the ack still suppresses).
+ *  4. **require-ack**: an advisory of a require-ack code that is not validly
+ *     acknowledged (no ack, or re-surfaced) becomes a hard error.
+ */
+export function applyAckGovernance(slot, warnings, policy) {
+    const acks = collectAcks(slot);
+    const outWarnings = [];
+    const acknowledged = [];
+    // Up front: reject policy entries naming no real advisory code (a typo/stale
+    // code that would silently fail open). Validated against the vocabulary,
+    // independent of whether any advisory below actually fires.
+    const errors = validatePolicyCodes(slot, policy);
+    for (const w of warnings) {
+        const codeBase = advisoryCodeBase(w.code);
+        if (policy.errorOn.has(codeBase)) {
+            errors.push(escalationError(w, 'error-on'));
+            continue; // an ack cannot suppress an error-on code
+        }
+        const ack = matchAck(w, acks);
+        let validlyAcked = false;
+        if (ack) {
+            const currentFp = computeAdvisoryFingerprint(w.code, w.site, w.fingerprintInputs);
+            if (ack.emptyRationale)
+                outWarnings.push(emptyRationaleWarning(w));
+            if (ack.recordedFingerprint !== undefined && ack.recordedFingerprint !== currentFp) {
+                outWarnings.push(resurface(w, ack.recordedFingerprint, currentFp));
+            }
+            else {
+                acknowledged.push({
+                    code: w.code,
+                    site: w.site,
+                    message: w.message,
+                    rationale: ack.rationale,
+                    target: ack.target,
+                    currentFingerprint: currentFp,
+                    recordedFingerprint: ack.recordedFingerprint,
+                    unconditional: ack.recordedFingerprint === undefined,
+                });
+                validlyAcked = true;
+            }
+        }
+        else {
+            outWarnings.push(w);
+        }
+        if (policy.requireAck.has(codeBase) && !validlyAcked) {
+            errors.push(escalationError(w, 'require-ack'));
+        }
+    }
+    return { warnings: outWarnings, acknowledged, errors };
+}
+/** Flags a re-surfaced advisory: kept in the report, message annotated. */
+function resurface(w, recorded, current) {
+    return {
+        ...w,
+        resurfaced: true,
+        message: `${w.message} [previously acknowledged; situation changed — recorded fingerprint '${recorded}' no longer matches '${current}'; re-acknowledge to suppress again]`,
+    };
+}
+/** The meta-warning for an ack whose rationale is empty (docs/lens.md:211). */
+function emptyRationaleWarning(w) {
+    return {
+        code: w.code,
+        severity: 'warning',
+        site: w.site,
+        message: `lens: acknowledgment of '${w.code}' on '${w.site.table}' has an empty rationale — every suppression should carry its justification (set the ack tag value to a non-empty reason)`,
+        resurfaced: false,
+    };
+}
+/** Promotes an advisory to a blocking error under the named escalation policy. */
+function escalationError(w, kind) {
+    const detail = kind === 'error-on'
+        ? `escalated to a hard error by the 'error-on' policy (an ack cannot suppress it)`
+        : `un-acknowledged but required by the 'require-ack' policy (add a 'quereus.lens.ack.${advisoryCodeBase(w.code)}' tag with a rationale to clear it)`;
+    return { ...w, severity: 'error', message: `${w.message} [${detail}]` };
+}
+//# sourceMappingURL=lens-ack.js.map

package/dist/src/schema/lens-ack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens-ack.js","sourceRoot":"","sources":["../../../src/schema/lens-ack.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,OAAO,CAAC;AACrC,MAAM,YAAY,GAAG,yBAAyB,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,qBAAqB,GAAG,6BAA6B,CAAC;AAU5D,8DAA8D;AAC9D,MAAM,CAAC,MAAM,uBAAuB,GAAqB;IACxD,OAAO,EAAE,IAAI,GAAG,EAAU;IAC1B,UAAU,EAAE,IAAI,GAAG,EAAU;CAC7B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,YAAyB;IAChE,OAAO;QACN,OAAO,EAAE,YAAY,CAAC,cAAc,CAAC,YAAY,CAAC,IAAI,EAAE,8BAA8B,CAAC,CAAC;QACxF,UAAU,EAAE,YAAY,CAAC,cAAc,CAAC,YAAY,CAAC,IAAI,EAAE,iCAAiC,CAAC,CAAC;KAC9F,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,KAAyB;IAC9C,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,GAAG,CAAC;IACvB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAwCD,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CACzC,IAAY,EACZ,IAAwB,EACxB,MAAqC;IAErC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI;QACJ,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;QAC/B,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE,IAAI,IAAI;QAClD,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,IAAI;QAC1C,IAAI,EAAE,MAAM,EAAE,iBAAiB;YAC9B,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE;YAChE,CAAC,CAAC,IAAI;QACP,KAAK,EAAE,MAAM,EAAE,oBAAoB,IAAI,IAAI;QAC3C,IAAI,EAAE,MAAM,EAAE,eAAe,IAAI,IAAI;QACrC,KAAK,EAAE,MAAM,EAAE,aAAa,IAAI,IAAI;QACpC,sEAAsE;QACtE,sEAAsE;QACtE,yEAAyE;QACzE,sCAAsC;QACtC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,sFAAsF;QACtF,oFAAoF;QACpF,oFAAoF;QACpF,sCAAsC;QACtC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9G,CAAC,CAAC;IACH,OAAO,WAAW,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACvD,CAAC;AAwBD,yEAAyE;AACzE,SAAS,aAAa,CAAC,KAAa;IACnC,MAAM,CAAC,GAAG,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;IAC3C,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,yEAAyE;AACzE,SAAS,eAAe,CAAC,OAAe;IACvC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;IAC1D,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;AAC5G,CAAC;AAED,sDAAsD;AACtD,SAAS,gBAAgB,CAAC,IAA0C;IACnE,OAAO,wBAAwB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QAC9D,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3D,MAAM,EAAE,SAAS,EAAE,mBAAmB,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,mBAAmB,EAAE,cAAc,EAAE,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,KAAK,EAAE,OAAgB,EAAE,CAAC;IAC9H,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,SAAS,qBAAqB,CAAC,UAA6B,EAAE,WAAwC;IACrG,IAAI,UAAU,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,EAAE,CAAC,CAAC,8BAA8B;IAC/E,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC;IACxC,MAAM,IAAI,GAAG,iBAAiB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IACxD,OAAO,wBAAwB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QAC9D,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3D,MAAM,EAAE,SAAS,EAAE,mBAAmB,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrE,OAAO;YACN,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,mBAAmB;YAChD,cAAc,EAAE,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,KAAK,EAAE,YAAqB,EAAE,iBAAiB,EAAE,IAAI;SAC7F,CAAC;IACH,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,SAAS,iBAAiB,CAAC,UAA6B,EAAE,WAAwC;IACjG,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACjF,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACzB,KAAK,YAAY,CAAC,CAAC,OAAO,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QACpE,KAAK,QAAQ,CAAC,CAAC,OAAO,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7D,KAAK,YAAY,CAAC,CAAC,OAAO,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjE,KAAK,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;AACF,CAAC;AAED,uEAAuE;AACvE,SAAS,WAAW,CAAC,IAAc;IAClC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC9C,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACxE,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,mBAAmB;QAAE,IAAI,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC;IAC9F,OAAO,IAAI,CAAC;AACb,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,yEAAyE;AACzE,SAAS,gBAAgB,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/F,CAAC;AAED,uGAAuG;AACvG,SAAS,aAAa,CAAC,MAAc,EAAE,QAAwB;IAC9D,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,IAAI,EAAE,CAAC;IACjE,OAAO,MAAM,KAAK,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE;WACrD,MAAM,KAAK,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE;WAC9C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,0FAA0F;AAC1F,SAAS,sBAAsB,CAAC,UAAyC,EAAE,QAAwB;IAClG,MAAM,OAAO,GAAG,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IAC9D,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,IAAI,UAAU,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAClF,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC1D,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,yFAAyF;AACzF,SAAS,QAAQ,CAAC,QAAwB,EAAE,IAA0B;IACrE,MAAM,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI;YAAE,SAAS;QACpC,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC;gBAAE,OAAO,GAAG,CAAC;YACpD,SAAS;QACV,CAAC;QACD,iEAAiE;QACjE,sEAAsE;QACtE,IAAI,GAAG,CAAC,KAAK,KAAK,OAAO;YAAE,OAAO,GAAG,CAAC;QACtC,IAAI,sBAAsB,CAAC,GAAG,CAAC,iBAAiB,EAAE,QAAQ,CAAC;YAAE,OAAO,GAAG,CAAC;IACzE,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,yBAAyB,GAC9B,IAAI,GAAG,CAAC,CAAC,GAAG,8BAA8B,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAEpE,gFAAgF;AAChF,MAAM,iCAAiC,GAAG,CAAC,GAAG,8BAA8B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEzF;;;;;;;;GAQG;AACH,SAAS,mBAAmB,CAAC,IAAc,EAAE,MAAwB;IACpE,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,CAAC,KAA0B,EAAE,GAA+B,EAAQ,EAAE;QACnF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,IAAI,yBAAyB,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YAClD,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QACtD,CAAC;IACF,CAAC,CAAC;IACF,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAClC,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC;AACf,CAAC;AAED,iFAAiF;AACjF,SAAS,sBAAsB,CAAC,IAAc,EAAE,GAA+B,EAAE,IAAY;IAC5F,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;IACrC,OAAO;QACN,IAAI,EAAE,0BAA0B;QAChC,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,EAAE,KAAK,EAAE;QACf,OAAO,EAAE,oDAAoD,GAAG,SAAS,KAAK,uCAAuC,oBAAoB,GAAG,IAAI,uFAAuF,iCAAiC,EAAE;QAC1Q,UAAU,EAAE,KAAK;KACjB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CACjC,IAAc,EACd,QAAmC,EACnC,MAAwB;IAExB,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,MAAM,YAAY,GAA2B,EAAE,CAAC;IAChD,6EAA6E;IAC7E,yEAAyE;IACzE,4DAA4D;IAC5D,MAAM,MAAM,GAAqB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAEnE,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;YAC5C,SAAS,CAAC,0CAA0C;QACrD,CAAC;QAED,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC9B,IAAI,YAAY,GAAG,KAAK,CAAC;QACzB,IAAI,GAAG,EAAE,CAAC;YACT,MAAM,SAAS,GAAG,0BAA0B,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,iBAAiB,CAAC,CAAC;YAClF,IAAI,GAAG,CAAC,cAAc;gBAAE,WAAW,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;YACnE,IAAI,GAAG,CAAC,mBAAmB,KAAK,SAAS,IAAI,GAAG,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;gBACpF,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC,CAAC;YACpE,CAAC;iBAAM,CAAC;gBACP,YAAY,CAAC,IAAI,CAAC;oBACjB,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,SAAS,EAAE,GAAG,CAAC,SAAS;oBACxB,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,kBAAkB,EAAE,SAAS;oBAC7B,mBAAmB,EAAE,GAAG,CAAC,mBAAmB;oBAC5C,aAAa,EAAE,GAAG,CAAC,mBAAmB,KAAK,SAAS;iBACpD,CAAC,CAAC;gBACH,YAAY,GAAG,IAAI,CAAC;YACrB,CAAC;QACF,CAAC;aAAM,CAAC;YACP,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;QAED,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACtD,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;QAChD,CAAC;IACF,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;AACxD,CAAC;AAED,2EAA2E;AAC3E,SAAS,SAAS,CAAC,CAAiB,EAAE,QAAgB,EAAE,OAAe;IACtE,OAAO;QACN,GAAG,CAAC;QACJ,UAAU,EAAE,IAAI;QAChB,OAAO,EAAE,GAAG,CAAC,CAAC,OAAO,wEAAwE,QAAQ,wBAAwB,OAAO,sCAAsC;KAC1K,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,SAAS,qBAAqB,CAAC,CAAiB;IAC/C,OAAO;QACN,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,QAAQ,EAAE,SAAS;QACnB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,4BAA4B,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,2HAA2H;QAC3L,UAAU,EAAE,KAAK;KACjB,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,SAAS,eAAe,CAAC,CAAiB,EAAE,IAAgC;IAC3E,MAAM,MAAM,GAAG,IAAI,KAAK,UAAU;QACjC,CAAC,CAAC,gFAAgF;QAClF,CAAC,CAAC,qFAAqF,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,qCAAqC,CAAC;IACtJ,OAAO,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC;AACzE,CAAC"}

package/dist/src/schema/lens-compiler.d.ts

@@ -0,0 +1,62 @@
+import type { Database } from '../core/database.js';
+import type { Schema } from './schema.js';
+import type { SchemaManager } from './manager.js';
+import { type TableSchema } from './table.js';
+import type * as AST from '../parser/ast.js';
+import { type LensDeployReport } from './lens-prover.js';
+/**
+ * Lens compiler — the `apply schema X` step for a **logical** schema.
+ *
+ * For each declared logical table it: builds the logical spec, aligns it against
+ * the basis schema (the default name-based aligner), produces the inlined
+ * effective view body, populates the lens slot, and registers the body as an
+ * ordinary `ViewSchema`. The query processor then sees a view; reads ride the
+ * standard view-resolution path and writes ride view-updateability.
+ *
+ * v1 is **single-source, name-based** (see `docs/lens.md` § The Default Mapper):
+ * a logical table maps to a name-matching basis table, and each logical column
+ * to a name-matching basis column. Type/nullability conformance and the n-way
+ * decomposition shape are deferred to the prover / decomposition tickets.
+ */
+/**
+ * Deploys (or re-deploys) a logical schema's lens slots + compiled view bodies.
+ *
+ * Re-deploy semantics are **clear-and-rebuild**: every existing lens view + slot
+ * in the logical schema is dropped, then rebuilt from the current declaration.
+ * This is how asymmetric removal falls out for free — a logical table dropped
+ * from the declaration is simply not rebuilt (its view + slot vanish), and the
+ * basis is never touched (logical removals never cascade to basis storage; see
+ * `docs/lens.md` § Deployment).
+ */
+export declare function deployLogicalSchema(db: Database, declaredSchema: AST.DeclareSchemaStmt, logicalSchemaName: string): LensDeployReport;
+/**
+ * Rejects every physical construct under a logical declared schema, naming the
+ * offending construct and the logical-schema context. Tags are allowed (they
+ * are engine-facing and survive into the compiled view).
+ */
+export declare function validateLogicalDeclaration(declaredSchema: AST.DeclareSchemaStmt, logicalSchemaName: string): void;
+/**
+ * Infers the default basis for a logical schema (MVP binding — there is no
+ * `declare lens for X over Y` yet). The basis is the single registered
+ * **physical** schema that contains ≥1 table, excluding the logical schema
+ * itself and `temp`. See `docs/lens.md` § Default-basis inference.
+ */
+export declare function inferDefaultBasis(schemaManager: SchemaManager, logicalSchemaName: string): {
+    schema: Schema;
+    schemaName: string;
+};
+/**
+ * The default name-based aligner: produces `select <logical columns> from B.T'`
+ * for one logical table `L.T` over basis schema `B`.
+ *
+ * - The basis table is matched by name (case-insensitive).
+ * - Each logical column is matched to a basis column by name (case-insensitive).
+ * - The projection lists exactly the logical columns, in declaration order, so
+ *   a basis table with extra columns is correctly projected down.
+ *
+ * The empty-key (singleton) case needs no special path: a `primary key ()`
+ * logical table over a `primary key ()` basis table is an ordinary single-source
+ * projection.
+ */
+export declare function compileDefaultBody(logicalTable: TableSchema, logicalSchemaName: string, basisSchema: Schema, basisSchemaName: string): AST.SelectStmt;
+//# sourceMappingURL=lens-compiler.d.ts.map

package/dist/src/schema/lens-compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens-compiler.d.ts","sourceRoot":"","sources":["../../../src/schema/lens-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtE,OAAO,KAAK,KAAK,GAAG,MAAM,kBAAkB,CAAC;AAS7C,OAAO,EAAoC,KAAK,gBAAgB,EAAkD,MAAM,kBAAkB,CAAC;AAU3I;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAClC,EAAE,EAAE,QAAQ,EACZ,cAAc,EAAE,GAAG,CAAC,iBAAiB,EACrC,iBAAiB,EAAE,MAAM,GACvB,gBAAgB,CA+NlB;AAqSD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACzC,cAAc,EAAE,GAAG,CAAC,iBAAiB,EACrC,iBAAiB,EAAE,MAAM,GACvB,IAAI,CA+BN;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAChC,aAAa,EAAE,aAAa,EAC5B,iBAAiB,EAAE,MAAM,GACvB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAyBxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CACjC,YAAY,EAAE,WAAW,EACzB,iBAAiB,EAAE,MAAM,EACzB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,GACrB,GAAG,CAAC,UAAU,CAuChB"}