@quereus/quereus 3.3.0 → 4.0.0

package/dist/src/schema/lens-fk-discovery.js.map

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

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

@@ -0,0 +1,336 @@
+import type { Database } from '../core/database.js';
+import type { SchemaManager } from './manager.js';
+import type { TableSchema } from './table.js';
+import type { LensSlot, LogicalConstraint } from './lens.js';
+import type * as AST from '../parser/ast.js';
+import type { FunctionalDependency, RelationalPlanNode } from '../planner/nodes/plan-node.js';
+import { type ResolvedBaseSite } from '../planner/analysis/update-lineage.js';
+import type { AcknowledgedAdvisory } from './lens-ack.js';
+/**
+ * Lens prover — proves each logical table's compiled body realizes its logical
+ * spec, and classifies how every logical constraint becomes real at the lens
+ * boundary. It is the second half of "validate, generate, attach": the foundation
+ * generated the effective body; this proves it sound and decides the obligation
+ * for each constraint.
+ *
+ * The prover is a **consumer** of the shipped inference surface — it applies
+ * `proveEffectiveKeyUnique` (`planner/analysis/coverage-prover.ts`) and the
+ * derived FD/key facts read off the optimized body; it derives no new inference.
+ * What it cannot prove, it reports — it never silently assumes coverage.
+ *
+ * Two outputs per slot ({@link LensProveResult}):
+ *  - **diagnostics** — the deploy-blocking errors (any one blocks the deploy)
+ *    plus the warning-severity diagnostics that flow to the deploy report: the
+ *    pure advisories (no-backing-index / no-answering-structure /
+ *    partial-override / getput-lossy) plus the read-only verdict
+ *    (`pk-not-reconstructible`). See `docs/lens.md` § Coverage checklist.
+ *  - **obligations + readOnly** — per-constraint enforcement classification and
+ *    the writable-or-read-only verdict, recorded on the {@link LensSlot}. The
+ *    *live* per-write enforcement wiring (`lens-constraint-enforcement-wiring`)
+ *    consumes these: the row-local check pipeline, the child-side FK existence
+ *    check, and the set-level commit-time uniqueness scan are shipped
+ *    (`planner/mutation/lens-enforcement.ts` — the `enforced-fk` obligation is a
+ *    deferred basis-term `EXISTS` against the logical parent gated by the
+ *    `foreign_keys` pragma; the `enforced-set-level` `commit-time` obligation is a
+ *    deferred `(select count(*) … ) <= 1` count-subquery CHECK over the logical key,
+ *    detection-only — `or replace`/`or ignore` against such a key is rejected). The
+ *    `enforced-set-level` `row-time` write path (covering structure, conflict-
+ *    resolution-capable) is **delivered** with no dedicated lens code: by this
+ *    classifier's own precondition a row-time key is backed by a matching basis
+ *    `UNIQUE` + non-stale covering MV, and the single-source re-plan reaches that
+ *    basis UC, whose physical enforcement-through-covering-MV path does the
+ *    O(log n) lookup and honors `ABORT`/`IGNORE`/`REPLACE` for free. This module
+ *    proves, classifies, and blocks/advises.
+ *
+ * Soundness over completeness: a false error blocks a sound deploy, so every
+ * check is conservative — when a fact cannot be established (e.g. the body fails
+ * to plan, a multi-source covering lookup), the prover degrades to the
+ * *safe* verdict (no spurious error; default a set-level constraint to the
+ * commit-time scan and warn) rather than guessing.
+ */
+/**
+ * Error-severity diagnostic codes — already hard errors that block the deploy
+ * before ack/escalation governance runs, so they are *not* valid escalation
+ * policy targets (see `docs/lens.md` § Coverage checklist).
+ */
+export type LensErrorCode = 'lens.uncovered-column' | 'lens.type-mismatch' | 'lens.nullability-mismatch' | 'lens.unrealizable-constraint' | 'lens.unenforceable-conflict-action' | 'lens.non-invertible' | 'lens.putget-violation' | 'lens.unknown-policy-code';
+/**
+ * The warning-severity advisory codes that flow through ack/escalation
+ * governance (`lens-ack.ts`). This is the single authoritative source of the
+ * governable vocabulary: a policy (`error-on` / `require-ack`) may legitimately
+ * name any of these, and only these. Keeping the list here means it cannot drift
+ * from what the prover actually emits.
+ */
+declare const ADVISORY_CODE_LIST: readonly ["lens.pk-not-reconstructible", "lens.no-backing-index", "lens.no-answering-structure", "lens.partial-override", "lens.getput-lossy", "lens.over-restrictive-basis-key"];
+/** An advisory (warning-severity) code — see {@link ADVISORY_CODE_LIST}. */
+export type LensAdvisoryCode = typeof ADVISORY_CODE_LIST[number];
+/** The advisory codes a policy may escalate, as a runtime set (drift-locked by a unit test). */
+export declare const ACKNOWLEDGEABLE_ADVISORY_CODES: ReadonlySet<LensAdvisoryCode>;
+/** Stable diagnostic codes (see `docs/lens.md` § Coverage checklist). */
+export type LensCheckCode = LensErrorCode | LensAdvisoryCode;
+/** The logical site a diagnostic concerns (table / constraint / column). */
+export interface LensDiagnosticSite {
+    readonly table: string;
+    readonly constraint?: string;
+    readonly column?: string;
+}
+/**
+ * The coarse facts behind a warning, recorded so the sibling acknowledgment
+ * ticket (`lens-advisory-acknowledgment`) can fingerprint an advisory without
+ * re-deriving it. This ticket *defines and populates* the shape; the sibling
+ * computes the hash and persists it when an ack is written, and re-surfaces the
+ * advisory when the fingerprint no longer matches. Deliberately coarse — a
+ * cardinality *band* rather than a row count — so an ack survives ordinary churn.
+ */
+export interface FingerprintInputs {
+    /** The logical constraint's columns (names, declaration order). */
+    readonly constraintColumns?: readonly string[];
+    /** Whether a basis covering structure answers the constraint at deploy time. */
+    readonly hasCoveringStructure?: boolean;
+    /** Coarse cardinality band of the basis anchor: empty | small | medium | large | unknown. */
+    readonly cardinalityBand?: string;
+    /** The basis relation backing the constraint (lowercased `schema.table`), when resolvable. */
+    readonly basisRelation?: string;
+    /**
+     * The enumerable CHECK `in (...)` domain behind a round-trip advisory
+     * (`lens.getput-lossy`), rendered + sorted — a domain change (the list gains
+     * or loses a value) is a material fact that re-surfaces an acknowledgment.
+     * Serialized into the fingerprint only when present, so advisories without a
+     * domain keep their existing hashes.
+     */
+    readonly domainValues?: readonly string[];
+    /**
+     * The governing basis key's basis-column names behind an over-restriction
+     * advisory (`lens.over-restrictive-basis-key`), rendered + sorted — if the basis
+     * key changes (tightened to match the logical key, or loosened) the advisory's
+     * truth changes, so a prior acknowledgment should re-surface. Serialized into the
+     * fingerprint only when present (mirroring {@link domainValues}), so advisories
+     * without a basis key keep their existing hashes.
+     */
+    readonly basisKeyColumns?: readonly string[];
+}
+/** A sited, coded diagnostic. Errors block the deploy; warnings flow to the report. */
+export interface LensDiagnostic {
+    readonly code: LensCheckCode;
+    readonly severity: 'error' | 'warning';
+    readonly site: LensDiagnosticSite;
+    readonly message: string;
+    readonly fingerprintInputs?: FingerprintInputs;
+    /**
+     * Set by the acknowledgment governance (`lens-ack.ts`) when a previously
+     * acknowledged advisory re-surfaced because its recorded fingerprint no longer
+     * matches the freshly computed one. The message is annotated accordingly.
+     */
+    readonly resurfaced?: boolean;
+}
+/** A reference to the basis covering structure routing a set-level constraint. */
+export interface CoveringStructureRef {
+    readonly kind: 'memory-index' | 'materialized-view';
+    readonly name: string;
+}
+/**
+ * How one logical constraint becomes real at the lens boundary:
+ *  - `proved` — the body intrinsically guarantees it (FD/key); zero runtime cost.
+ *  - `enforced-row-local` — evaluable on the projected row being written (a
+ *    scalar `check` over non-computed columns); the common, free case.
+ *  - `enforced-set-level` — an existence lookup. `row-time` when a covering
+ *    structure answers it (O(log n), conflict-resolution-capable); `commit-time`
+ *    otherwise (O(n) `DeltaExecutor` scan, detection-only).
+ *  - `enforced-fk` — cross-relation existence, realized at the lens boundary as a
+ *    deferred synthesized `EXISTS` against the logical parent (gated by the
+ *    `foreign_keys` pragma, auto-deferred to commit; `planner/mutation/lens-enforcement.ts`).
+ *  - `vacuous` — body + predicate make it trivially satisfied.
+ */
+export type ConstraintObligation = {
+    readonly constraint: LogicalConstraint;
+} & ({
+    readonly kind: 'proved';
+} | {
+    readonly kind: 'enforced-row-local';
+} | {
+    readonly kind: 'enforced-set-level';
+    readonly mode: 'row-time' | 'commit-time';
+    readonly structure?: CoveringStructureRef;
+} | {
+    readonly kind: 'enforced-fk';
+} | {
+    readonly kind: 'vacuous';
+});
+/**
+ * The aggregated result of proving every logical table in one `apply schema X`.
+ * `deployLogicalSchema` returns this; `emitApplySchema` surfaces the warnings as
+ * advisory rows. Errors are thrown atomically (before any catalog mutation), so a
+ * returned report always has `errors: []` — the field is kept for symmetry and so
+ * an in-process caller that wants to inspect-without-throwing can.
+ */
+export interface LensDeployReport {
+    readonly errors: LensDiagnostic[];
+    /**
+     * Advisories shown by default — un-acknowledged ones plus any that re-surfaced
+     * (`resurfaced: true`) plus empty-rationale meta-warnings. Acknowledged
+     * advisories are removed (and tallied in {@link acknowledged}).
+     */
+    readonly warnings: LensDiagnostic[];
+    /**
+     * Advisories an in-source `quereus.lens.ack.<code>` tag suppressed from the
+     * default report. The deploy summary tallies `acknowledged: N` (=
+     * `acknowledged.length`) and the `quereus_lens_advisories` TVF expands them on
+     * demand (`docs/lens.md` § Acknowledging advisories). Produced by `lens-ack.ts`.
+     */
+    readonly acknowledged: AcknowledgedAdvisory[];
+    /** Lowercased logical table name → its constraint obligations. */
+    readonly obligationsByTable: ReadonlyMap<string, ReadonlyArray<ConstraintObligation>>;
+}
+/** The prover's verdict for one lens slot. */
+export interface LensProveResult {
+    /** Any non-empty ⇒ deploy blocks. */
+    readonly errors: LensDiagnostic[];
+    /** Advisory; never blocks. Surfaced in the deploy report. */
+    readonly warnings: LensDiagnostic[];
+    /** Per-constraint enforcement classification. */
+    readonly obligations: ConstraintObligation[];
+    /** Key not reconstructible ⇒ the table is read-only; mutations error at the lens. */
+    readonly readOnly: boolean;
+}
+/**
+ * Proves one lens slot and classifies its constraints. Pure analysis — does not
+ * mutate the slot or the catalog; the caller (`lens-compiler.ts`) records the
+ * `obligations` / `readOnly` on the slot and aggregates the diagnostics into the
+ * deploy report.
+ */
+export declare function proveLens(slot: LensSlot, db: Database): LensProveResult;
+/**
+ * The single basis `table` source of a lens slot's compiled body, or undefined for
+ * a multi-source / opaque FROM — the exported slot-level entry point. Reused by the
+ * lens FK-redundancy detector (`planner/mutation/lens-enforcement.ts`) so it walks
+ * the same single-source `from` the prover does, resolving a bare table name against
+ * the slot's own default basis schema. Reads only the catalog, so it is safe over a
+ * lightweight (un-planned) caller.
+ */
+export declare function resolveSlotBasisSource(slot: LensSlot, schemaManager: SchemaManager): TableSchema | undefined;
+/** The per-output-column round-trip verdict over a planned single-source body. */
+export interface ColumnRoundTrip {
+    readonly attrId: number;
+    /** Body-output column name (the lens spells these as the logical columns). */
+    readonly name: string;
+    /** The lens presents this column as writable (a `base` {@link ResolvedBaseSite}). */
+    readonly writable: boolean;
+    /** A *writable* column whose GetPut/PutGet round-trip is proved faithful. */
+    readonly faithful: boolean;
+    /** Names the obstruction for a writable-but-unfaithful column (else undefined). */
+    readonly obstruction?: string;
+    /**
+     * The authored (`with inverse`) put payload, when the column's write path is
+     * authored. Such a column is writable+faithful *structurally*; its law
+     * treatment is the prover's authored branch ({@link emitAuthoredInverseDiagnostics}) —
+     * PutGet by enumeration, GetPut surrendered into the lossy advisory.
+     */
+    readonly authored?: AuthoredSite;
+    /** The forward `get` expression off the topmost projection (carried for the authored branch's composition). */
+    readonly forward?: AST.Expression;
+}
+/**
+ * The computed per-column GetPut/PutGet verdict over a planned **logical** body —
+ * the deploy-time predicate {@link analyzeRoundTrip} / {@link emitRoundTrip} consume,
+ * exported so the operational round-trip harness (`test/property.spec.ts` § View
+ * Round-Trip Laws) can assert it agrees with the operational law per column.
+ *
+ * Returns `undefined` (the degrade-to-safe signal) for any body the complement
+ * does not characterize: not single-source projection-and-filter (multi-source /
+ * join / aggregate / set-op / VALUES / recursive-CTE / LIMIT / OFFSET / DISTINCT),
+ * `updateLineage` not threaded, or a residual predicate that is not negation-free.
+ * Otherwise one verdict per output column, in attribute order.
+ *
+ * Each writable site is read through {@link resolveBaseSite} — the same n-way
+ * reader the single-source, join, and decomposition put paths share — so the
+ * GetPut hidden-column and PutGet inverse-domain checks already generalize past
+ * single-source when the complement is later defined on the join/decomposition
+ * fragment (`view-write-through-shape-gaps`); only the fragment gate here is
+ * single-source-only.
+ */
+export declare function computeRoundTrip(root: RelationalPlanNode): ColumnRoundTrip[] | undefined;
+/**
+ * PutGet identity probe: is the composed `get ∘ put` the identity on the writable
+ * value? For each probe `w`, lowers it through the `put` inverse to a base value
+ * and re-applies the forward `get`, requiring `get(put(w)) === w`. Sound because a
+ * writable column's `get` and the inverse's `put` are built **only** from the
+ * law-gated invertibility registry's closed vocabulary (column ref, `± k`, no-op
+ * cast, collate), which {@link evalClosed} evaluates exactly; an expression outside
+ * it yields `undefined` and reds (the analysis cannot prove faithfulness).
+ *
+ * Exported as the pure core the operational harness's injected-violation self-test
+ * drives (an unfaithful forward/inverse pair must red), mirroring the harness's
+ * `injected-widening` / `injected-getput` cores.
+ */
+export declare function getPutComposesToIdentity(forward: AST.Expression, inverse: (written: AST.Expression) => AST.Expression): boolean;
+/** The authored put payload off a resolved {@link ResolvedBaseSite}. */
+type AuthoredSite = NonNullable<ResolvedBaseSite['authored']>;
+/**
+ * Maps each authored-inverse logical column (lowercased) to its **forward** `get`
+ * expression (basis terms), when that forward is row-local-enforceable — a
+ * subquery-free scalar over basis column refs of a **single-source** body. This
+ * is the agreement predicate between the prover's CHECK realizability classifier
+ * ({@link classifyCheckConstraint}: a CHECK referencing an authored column is
+ * row-local exactly when this map has the column) and the write-time
+ * logical→basis rewrite (`planner/mutation/lens-enforcement.ts`), which
+ * substitutes the forward — `NEW.`-qualified — for the column ref so the CHECK
+ * evaluates over the basis write row's logical image. The two must accept the
+ * same set, or a deploy-admitted CHECK would crash at write plan time.
+ *
+ * The single-source condition is load-bearing: on a multi-source body the
+ * forward may read a column of a *different member* than the one the put
+ * writes, and the substituted `NEW.<col>` on that member's write row does not
+ * carry the value — the CHECK would pass vacuously (3VL unknown) instead of
+ * enforcing. The clause's put targets are bare column names, so the slot AST
+ * alone cannot prove every forward ref lives on the put member; single-source
+ * is the decidable conservative gate (the same posture as the prover's PutGet
+ * enumeration). A multi-source CHECK over an authored column therefore reds
+ * `lens.unrealizable-constraint` at deploy rather than deploying un-enforced.
+ */
+export declare function authoredForwardMap(slot: LensSlot): Map<string, AST.Expression>;
+/**
+ * The declared logical keys a lens *proves* or *actively enforces*, encoded as
+ * physical functional dependencies in the body's **output**-column-index space,
+ * for the optimizer to consume at the inlined-view boundary
+ * (`planner/nodes/asserted-keys-node.ts`, wired in `planner/building/select.ts`).
+ *
+ * Soundness is gated by the prover's per-constraint {@link ConstraintObligation}
+ * kind — a false key FD is a *correctness* defect (it can make
+ * DISTINCT/join-elimination/order-by-pruning drop real rows), so the gate
+ * under-claims exactly like every other FD-propagation rule:
+ *
+ *  - `proved`   — the body intrinsically guarantees the key (the same FD surface
+ *    the optimizer derives locally); contribute the **unconditional** key FD.
+ *    Redundant-but-harmless when local propagation already surfaces it (`addFd`
+ *    subsumes), load-bearing when the inlining context loses it.
+ *  - `vacuous`  — the empty (singleton) key; contribute `∅ → all_cols` (≤1-row).
+ *  - `enforced-set-level` `row-time` — a covering structure enforces uniqueness
+ *    per row-write, but only over the **non-null** tuples a plain (NULL-skipping)
+ *    UNIQUE governs — SQL UNIQUE permits multiple all-/any-NULL rows, so the key
+ *    is conditionally unique. Contribute a **guarded** FD `key → others
+ *    [guard: key IS NOT NULL]` (the same shape a partial UNIQUE emits), and only
+ *    when the covering structure re-validates against the *current* catalog (it
+ *    can be dropped / go stale out-of-band between deploys) and the backing basis
+ *    UC is non-partial (so NULL-skip is the *entire* uniqueness scope).
+ *  - `enforced-set-level` `commit-time` — **excluded**. Detection-only at commit;
+ *    a duplicate can transiently exist mid-statement (read-own-writes / Halloween),
+ *    so assuming the FD mid-statement is unsound.
+ *  - `enforced-row-local` / `enforced-fk` — not uniqueness facts; excluded.
+ *
+ * Returns the (deduped) FD list, or `[]` when nothing is contributable — the
+ * wiring site inlines no node for an empty list (plain views / MVs / unenforced
+ * keys produce none).
+ */
+export declare function computeLensAssertedKeyFds(slot: LensSlot, db: Database): FunctionalDependency[];
+/**
+ * Collects every `column` reference name in an expression (best-effort reflective walk,
+ * qualifier-stripped — returns each `column` node's `.name`). Shared with the lens write
+ * side (`planner/mutation/lens-enforcement.ts`), which maps these refs through the slot's
+ * logical→basis projection to derive a row-local CHECK's `referencedWriteRowColumns`
+ * metadata — keeping the gate's notion of "write-row column" consistent with the prover's
+ * notion of "row-local" (both use this walk + logical-column membership; see
+ * {@link classifyCheckConstraint}).
+ */
+export declare function collectColumnRefNames(expr: AST.Expression): string[];
+export {};
+//# sourceMappingURL=lens-prover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lens-prover.d.ts","sourceRoot":"","sources":["../../../src/schema/lens-prover.ts"],"names":[],"mappings":"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"}