@bjornpagen/bumbledb 0.1.0

package/dist/query/predicate.d.ts

@@ -0,0 +1,101 @@
+/**
+ * IDB predicates (PRD-08) — engine recursion as values, mirroring the IR's
+ * cut exactly (`ir::Program`/`PredicateDef`/`AtomSource::Idb`;
+ * `docs/architecture/20-query-ir.md` § engine recursion): `$.predicate`
+ * declares a predicate with a named, field-typed head; its rules are given
+ * IN the declaration (a callback receiving the predicate's own reference,
+ * so self-recursion is writable and the rules are data the type system can
+ * see — the params they use flow into the query's inferred `Params`); and
+ * `.match({...})` uses it as a body atom, bindings addressing head
+ * positions by the declared column names (lowered positionally —
+ * `FieldId(i)` is head position i, exactly as the IR reads it). Strata
+ * legality (no negation/aggregation through a cycle) is the ENGINE's
+ * judge; its typed error surfaces at prepare.
+ */
+import { phantom } from "#brand.ts";
+import { type FieldData } from "#fields.ts";
+import type { AnyBodyItem, BindingsParams, MatchAtom, TermInput } from "#query/atom.ts";
+import type { AnyVar, Flatten, ItemParams, ParamsRecord, ParamsShape, QueryRegistry, Var } from "#query/scope.ts";
+import type { FieldRef } from "#relation.ts";
+/** One declared head column: name plus the field description that types it. */
+interface PredicateColumn {
+    readonly name: string;
+    readonly data: FieldData;
+}
+/** One clause of a predicate: head projections (column order) and the body. */
+interface PredicateRuleData {
+    readonly finds: readonly AnyVar[];
+    readonly body: readonly AnyBodyItem[];
+}
+/** A predicate's runtime description; identity keys the dense `PredId` at lowering. */
+interface PredicateData {
+    readonly name: string;
+    readonly columns: readonly PredicateColumn[];
+    readonly rules: readonly PredicateRuleData[];
+}
+/** Any field reference, whatever its brand — the column-declaration position. */
+type AnyFieldRef = FieldRef<string, string, unknown>;
+/** The columns record `$.predicate` takes: column name to typing field reference. */
+type PredicateColumnsInput = Readonly<Record<string, AnyFieldRef>>;
+/** Extracts a field reference's host value type. */
+type RefValue<T> = T extends {
+    readonly [phantom]?: infer V;
+} ? Exclude<V, undefined> : never;
+/** The head's typed column record, derived from the declaration. */
+type ColumnValues<Cols> = {
+    [K in keyof Cols]: RefValue<Cols[K]>;
+};
+/**
+ * The `.match` bindings of a predicate atom: per head column, a term of
+ * the column's brand; unmentioned columns are wildcards, exactly as
+ * relation atoms.
+ */
+type PredicateBindings<ColsV> = {
+    readonly [K in keyof ColsV]?: TermInput<ColsV[K]>;
+};
+/**
+ * One rule of a predicate as the declaration callback returns it: `finds`
+ * names the projected variable per head column (interior heads project
+ * bound variables only — the creation quarantine; the engine's strata
+ * judge enforces it), `body` is the clause's conjunction.
+ */
+interface PredicateRuleInput<ColsV> {
+    readonly finds: {
+        readonly [K in keyof ColsV]: Var<ColsV[K]>;
+    };
+    readonly body: readonly AnyBodyItem[];
+}
+/**
+ * The predicate's own reference, passed INTO its rules callback — the
+ * fixpoint spelling: `self.match({...})` inside a rule of the same
+ * predicate is the recursive atom.
+ */
+interface PredicateSelf<ColsV> {
+    readonly data: PredicateData;
+    match<const B extends PredicateBindings<ColsV>>(bindings: B): MatchAtom<BindingsParams<B>>;
+}
+/**
+ * A declared predicate. `.match({...})` uses it as a body atom — in
+ * another predicate's rules or in the output rules; the phantom `P`
+ * carries the params its own rules contributed, so a query's `Params`
+ * type sees through predicates it only reaches transitively.
+ */
+interface Predicate<ColsV, P extends ParamsRecord> {
+    readonly data: PredicateData;
+    match<const B extends PredicateBindings<ColsV>>(bindings: B): MatchAtom<Flatten<P & BindingsParams<B>>>;
+}
+/** The params contributed by a predicate's declared rules. */
+type PredicateParams<Rules extends readonly {
+    readonly body: readonly AnyBodyItem[];
+}[]> = ParamsShape<ItemParams<Rules[number]["body"][number]>>;
+/**
+ * Declares one predicate in the scope (the `$.predicate` implementation):
+ * resolves the head columns, runs the rules callback against the
+ * predicate's own reference, verifies every rule projects a declared
+ * scope variable per column, and registers the predicate in declaration
+ * order (= its dense `PredId`).
+ */
+declare function makePredicate<const Cols extends PredicateColumnsInput, const Rules extends readonly PredicateRuleInput<ColumnValues<Cols>>[]>(registry: QueryRegistry, name: string, columns: Cols, rules: (self: PredicateSelf<ColumnValues<Cols>>) => Rules): Predicate<ColumnValues<Cols>, PredicateParams<Rules>>;
+export type { AnyFieldRef, ColumnValues, Predicate, PredicateBindings, PredicateColumn, PredicateColumnsInput, PredicateData, PredicateParams, PredicateRuleData, PredicateRuleInput, PredicateSelf };
+export { makePredicate };
+//# sourceMappingURL=predicate.d.ts.map

package/dist/query/predicate.d.ts.map

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

package/dist/query/predicate.js

@@ -0,0 +1,85 @@
+/**
+ * IDB predicates (PRD-08) — engine recursion as values, mirroring the IR's
+ * cut exactly (`ir::Program`/`PredicateDef`/`AtomSource::Idb`;
+ * `docs/architecture/20-query-ir.md` § engine recursion): `$.predicate`
+ * declares a predicate with a named, field-typed head; its rules are given
+ * IN the declaration (a callback receiving the predicate's own reference,
+ * so self-recursion is writable and the rules are data the type system can
+ * see — the params they use flow into the query's inferred `Params`); and
+ * `.match({...})` uses it as a body atom, bindings addressing head
+ * positions by the declared column names (lowered positionally —
+ * `FieldId(i)` is head position i, exactly as the IR reads it). Strata
+ * legality (no negation/aggregation through a cycle) is the ENGINE's
+ * judge; its typed error surfaces at prepare.
+ */
+import * as errors from "@superbuilders/errors";
+import { phantom } from "#brand.ts";
+import { assertDeclarationOrderKey } from "#fields.ts";
+import { resolveBindings } from "#query/atom.ts";
+import { isTerm, resolveFieldData, term } from "#query/scope.ts";
+/** Builds one predicate atom (shared by `self.match` and `.match`). */
+function predicateAtom(data, bindings) {
+    return Object.freeze({
+        item: "atom",
+        negated: false,
+        source: Object.freeze({ kind: "predicate", pred: data }),
+        bindings: resolveBindings(`predicate ${data.name}`, data.columns.map(function asField(column) {
+            return { name: column.name, field: column.data };
+        }), bindings)
+    });
+}
+/**
+ * Declares one predicate in the scope (the `$.predicate` implementation):
+ * resolves the head columns, runs the rules callback against the
+ * predicate's own reference, verifies every rule projects a declared
+ * scope variable per column, and registers the predicate in declaration
+ * order (= its dense `PredId`).
+ */
+function makePredicate(registry, name, columns, rules) {
+    const ordered = [];
+    for (const [columnName, ref] of Object.entries(columns)) {
+        assertDeclarationOrderKey(`predicate ${name} column`, columnName);
+        ordered.push(Object.freeze({
+            name: columnName,
+            data: resolveFieldData(registry.theory, ref.relation, ref.field)
+        }));
+    }
+    if (ordered.length === 0) {
+        throw errors.new(`predicate ${name}: a predicate head needs at least one column`);
+    }
+    const ruleSlots = [];
+    const data = Object.freeze({
+        name,
+        columns: Object.freeze(ordered),
+        rules: ruleSlots
+    });
+    const self = Object.freeze({
+        data,
+        match(bindings) {
+            return predicateAtom(data, bindings);
+        }
+    });
+    const declared = rules(self);
+    for (const rule of declared) {
+        const finds = [];
+        const record = Object.fromEntries(Object.entries(rule.finds));
+        for (const column of ordered) {
+            const found = record[column.name];
+            if (!isTerm(found) || found[term] !== "var") {
+                throw errors.new(`predicate ${name}: rule finds must project a scope variable for column ${column.name} (interior heads project bound variables only)`);
+            }
+            finds.push(found);
+        }
+        ruleSlots.push(Object.freeze({ finds: Object.freeze(finds), body: Object.freeze([...rule.body]) }));
+    }
+    Object.freeze(ruleSlots);
+    registry.predicates.push(data);
+    return Object.freeze({
+        data,
+        match(bindings) {
+            return predicateAtom(data, bindings);
+        }
+    });
+}
+export { makePredicate };
+//# sourceMappingURL=predicate.js.map

package/dist/query/predicate.js.map

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

package/dist/query/run.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prepared-query marshaling seams (PRD-08), the two rides every execution
+ * takes — the typed params object down to the bridge's positional
+ * `QueryParam[]` (declaration order = dense `ParamId`s, values tagged by
+ * each param's declaring field), and answer rows (positional, head order)
+ * back up to plain objects with branded values (the store is the proof
+ * carrier: the engine computed the answer, so readback asserts the brand,
+ * the same trust direction as fact readback in `#marshal.ts`). Answers are
+ * SETS — no order or limit exists anywhere; hosts sort. The `Prepared`
+ * VALUE itself (no lifecycle, GC-reclaimed plan) lives in `#db.ts`.
+ */
+import type { FactValue, QueryParam } from "#native.ts";
+import type { SelectColumn } from "#query/lower.ts";
+import type { ParamEntry } from "#query/scope.ts";
+/**
+ * Marshals the typed params object to the bridge's positional arguments,
+ * in param declaration order (= the lowering's dense `ParamId`s). A
+ * missing entry is a typed error naming the param; values tag by the
+ * declaring field's structural type; a set param takes a readonly array
+ * (the empty set is legal and matches nothing — the engine's rule).
+ */
+declare function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<string, unknown>>): QueryParam[];
+/**
+ * Decodes positional answer rows (column order = the program's head order
+ * = the select record's written order) to named, branded, frozen row
+ * objects.
+ */
+declare function decodeAnswers<Row>(select: readonly SelectColumn[], rows: FactValue[][]): Row[];
+export { decodeAnswers, wireParams };
+//# sourceMappingURL=run.d.ts.map

package/dist/query/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/query/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAe,MAAM,YAAY,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAajD;;;;;;GAMG;AACH,iBAAS,UAAU,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,UAAU,EAAE,CA0B7G;AAiBD;;;;GAIG;AACH,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,GAAG,GAAG,EAAE,CAmBvF;AAED,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,CAAA"}

package/dist/query/run.js

@@ -0,0 +1,94 @@
+/**
+ * Prepared-query marshaling seams (PRD-08), the two rides every execution
+ * takes — the typed params object down to the bridge's positional
+ * `QueryParam[]` (declaration order = dense `ParamId`s, values tagged by
+ * each param's declaring field), and answer rows (positional, head order)
+ * back up to plain objects with branded values (the store is the proof
+ * carrier: the engine computed the answer, so readback asserts the brand,
+ * the same trust direction as fact readback in `#marshal.ts`). Answers are
+ * SETS — no order or limit exists anywhere; hosts sort. The `Prepared`
+ * VALUE itself (no lifecycle, GC-reclaimed plan) lives in `#db.ts`.
+ */
+import * as errors from "@superbuilders/errors";
+import { taggedLiteral } from "#query/lower.ts";
+/** The 13-bit Allen mask ceiling (`bumbledb/crates/bumbledb/src/allen.rs`: bits above the low 13 are unrepresentable). */
+const ALLEN_ALL_BITS = (1 << 13) - 1;
+/** Tags one supplied mask-param value. */
+function wireMask(name, value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > ALLEN_ALL_BITS) {
+        throw errors.new(`param ${name}: an Allen-mask param binds a 13-bit mask number built from the ALLEN constants`);
+    }
+    return { kind: "allenMask", mask: value };
+}
+/**
+ * Marshals the typed params object to the bridge's positional arguments,
+ * in param declaration order (= the lowering's dense `ParamId`s). A
+ * missing entry is a typed error naming the param; values tag by the
+ * declaring field's structural type; a set param takes a readonly array
+ * (the empty set is legal and matches nothing — the engine's rule).
+ */
+function wireParams(entries, supplied) {
+    return entries.map(function wireOne(entry) {
+        const value = supplied[entry.name];
+        if (value === undefined) {
+            throw errors.new(`execute params object is missing param ${entry.name}`);
+        }
+        if (entry.shape === "mask") {
+            return wireMask(entry.name, value);
+        }
+        if (entry.data === undefined) {
+            throw errors.new(`param ${entry.name}: registry entry carries no declaring field`);
+        }
+        if (entry.shape === "set") {
+            if (!Array.isArray(value)) {
+                throw errors.new(`param ${entry.name}: a set param binds a readonly array of values`);
+            }
+            const data = entry.data;
+            return {
+                kind: "set",
+                values: value.map(function wireElement(element, index) {
+                    return taggedLiteral(`param ${entry.name}[${index}]`, data, element);
+                })
+            };
+        }
+        return taggedLiteral(`param ${entry.name}`, entry.data, value);
+    });
+}
+/**
+ * The read-side trusted seam of answers: a decoded row carrying every
+ * select column IS a `Row` — the engine computed it under the prepared
+ * head, so the brands are asserted, not re-derived (the `#marshal.ts`
+ * trust direction).
+ */
+function isAnswerRow(select, decoded) {
+    return select.every(function present(column) {
+        return decoded[column.name] !== undefined;
+    });
+}
+/**
+ * Decodes positional answer rows (column order = the program's head order
+ * = the select record's written order) to named, branded, frozen row
+ * objects.
+ */
+function decodeAnswers(select, rows) {
+    return rows.map(function decodeRow(row) {
+        if (row.length !== select.length) {
+            throw errors.new(`query answer arity ${row.length} does not match the ${select.length} select columns`);
+        }
+        const decoded = {};
+        select.forEach(function decodeCell(column, ordinal) {
+            const cell = row[ordinal];
+            if (cell === undefined) {
+                throw errors.new(`query answer cell ${ordinal} (${column.name}) is absent`);
+            }
+            decoded[column.name] = cell;
+        });
+        Object.freeze(decoded);
+        if (!isAnswerRow(select, decoded)) {
+            throw errors.new("query answer row is not a complete select record");
+        }
+        return decoded;
+    });
+}
+export { decodeAnswers, wireParams };
+//# sourceMappingURL=run.js.map

package/dist/query/run.js.map

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

package/dist/query/scope.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Query scope terms (PRD-08): typed variables and parameters, declared
+ * inside a `query()` scope callback so identity is lexical. A `Var` is
+ * typed by the field it is declared from and joins are brand-equal by
+ * construction (the nominal join discipline); var identity is OBJECT
+ * identity — two `$.var` calls are two variables even from the same field,
+ * and no name-collision machinery exists. Params are query-global, carry a
+ * mandatory literal name (the key of `execute`'s params object), and lower
+ * to dense positional `ParamId`s in declaration order. This module also
+ * owns the type-level params extraction: every atom and condition value
+ * carries its contributed params object in a phantom, and the query's
+ * `Params` type is the flattened intersection over the returned rules —
+ * inference rides the return value, never a mutable type accumulator.
+ */
+import { phantom } from "#brand.ts";
+import type { FieldData } from "#fields.ts";
+import type { PredicateData } from "#query/predicate.ts";
+import type { AnySchema } from "#schema.ts";
+/**
+ * The runtime discriminant of query term values. Host literals (bigints,
+ * strings, interval objects, `oneOf` sets) never carry it, so "is this
+ * binding a term or a literal" is one property probe, never a guess.
+ */
+declare const term: unique symbol;
+/**
+ * A query variable, typed by the field it was declared from
+ * (`$.var(Holder.fields.id)` → `Var<Brand<bigint, "HolderId">>`). Usable in
+ * any atom position whose field carries the same brand; a brand-mismatched
+ * placement is a TYPE error. Identity is object identity.
+ */
+interface Var<V> {
+    readonly [term]: "var";
+    readonly relation: string;
+    readonly field: string;
+    readonly data: FieldData;
+    readonly [phantom]?: V;
+}
+/**
+ * A scalar query parameter — `$.param("root", Holder.fields.id)`. The name
+ * literal is the key of the typed params object `execute` takes; the value
+ * is marshaled by the declaring field's structural type at bind.
+ */
+interface Param<Name extends string, V> {
+    readonly [term]: "param";
+    readonly name: Name;
+    readonly relation: string;
+    readonly field: string;
+    readonly data: FieldData;
+    readonly [phantom]?: V;
+}
+/**
+ * A set-valued query parameter (the IR's `ParamSet` term): bound at
+ * execution to an ARRAY of values of the declaring field's type; a binding
+ * position matches iff the field value is in the set. Legal in atom
+ * bindings (positive and negated) and as the right side of `is` — nowhere
+ * else, exactly as the IR rules it.
+ */
+interface ParamSet<Name extends string, V> {
+    readonly [term]: "paramSet";
+    readonly name: Name;
+    readonly relation: string;
+    readonly field: string;
+    readonly data: FieldData;
+    readonly [phantom]?: V;
+}
+/**
+ * An Allen-mask parameter (the IR's `MaskTerm::Param`): the temporal
+ * relation as a bind-time argument — one prepared query answers any of the
+ * mask questions per execution. Bound to a 13-bit mask number built from
+ * the `ALLEN` constants.
+ */
+interface MaskParam<Name extends string> {
+    readonly [term]: "maskParam";
+    readonly name: Name;
+}
+/** Any query variable, whatever its brand. */
+type AnyVar = Var<unknown>;
+/** Any parameter term of the scope, whatever its name and brand. */
+type AnyParamTerm = Param<string, unknown> | ParamSet<string, unknown> | MaskParam<string>;
+/** Any scope term value. */
+type AnyTerm = AnyVar | AnyParamTerm;
+/** Narrows an unknown binding value to a scope term (vs a host literal). */
+declare function isTerm(value: unknown): value is AnyTerm;
+/** A params object type — what `execute` takes and the phantoms carry. */
+type ParamsRecord = Readonly<Record<string, unknown>>;
+/** Flattens an intersection into one displayed object type (hover legibility). */
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+};
+/** The standard union-to-intersection fold (distributes over `U`). */
+type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never) extends (member: infer I) => void ? I : never;
+/**
+ * One term's contribution to the query's params object type: a `Param`
+ * contributes its value type under its name, a `ParamSet` the readonly
+ * array of it, a `MaskParam` a mask number; everything else contributes
+ * nothing.
+ */
+type TermContribution<T> = T extends {
+    readonly [term]: "param";
+    readonly name: infer N extends string;
+    readonly [phantom]?: infer V;
+} ? {
+    readonly [K in N]: Exclude<V, undefined>;
+} : T extends {
+    readonly [term]: "paramSet";
+    readonly name: infer N extends string;
+    readonly [phantom]?: infer V;
+} ? {
+    readonly [K in N]: readonly Exclude<V, undefined>[];
+} : T extends {
+    readonly [term]: "maskParam";
+    readonly name: infer N extends string;
+} ? {
+    readonly [K in N]: number;
+} : Record<never, never>;
+/**
+ * Folds a union of per-term/per-item params objects into the one flattened
+ * params record (the query's `Params` type).
+ */
+type ParamsShape<U> = [U] extends [never] ? Record<never, never> : Flatten<UnionToIntersection<U>>;
+/** Reads an atom's/condition's contributed params object off its phantom. */
+type ItemParams<T> = T extends {
+    readonly [phantom]?: infer P;
+} ? Exclude<P, undefined> : Record<never, never>;
+/** One registered parameter: name, wire shape, and the declaring field. */
+interface ParamEntry {
+    readonly name: string;
+    readonly shape: "value" | "set" | "mask";
+    readonly data: FieldData | undefined;
+}
+/**
+ * The mutable build-time registry one `query()` scope owns: declared vars
+ * (membership polices cross-scope smuggling), params in declaration order
+ * (= dense `ParamId`s), and declared predicates in declaration order
+ * (= dense `PredId`s; the output predicate is appended by lowering).
+ */
+interface QueryRegistry {
+    readonly theory: AnySchema;
+    readonly vars: Set<AnyVar>;
+    readonly params: ParamEntry[];
+    readonly paramIndex: Map<AnyTerm, number>;
+    readonly predicates: PredicateData[];
+}
+/** Creates one empty scope registry over the query's theory. */
+declare function createRegistry(theory: AnySchema): QueryRegistry;
+/**
+ * Resolves a field reference's runtime description through the schema —
+ * the seam that types `$.var`/`$.param` declarations at runtime (the type
+ * level already carries the brand; this recovers the structural type the
+ * lowering and the param marshaler direct by).
+ */
+declare function resolveFieldData(theory: AnySchema, relationName: string, fieldName: string): FieldData;
+/** A field reference's runtime half, as the scope factories consume it. */
+interface RefNames {
+    readonly relation: string;
+    readonly field: string;
+}
+/** Declares one variable in the scope (the `$.var` implementation). */
+declare function scopeVar<V>(registry: QueryRegistry, ref: RefNames): Var<V>;
+/** Declares one scalar parameter (the `$.param` implementation). */
+declare function scopeParam<Name extends string, V>(registry: QueryRegistry, name: Name, ref: RefNames): Param<Name, V>;
+/** Declares one set parameter (the `$.paramSet` implementation). */
+declare function scopeParamSet<Name extends string, V>(registry: QueryRegistry, name: Name, ref: RefNames): ParamSet<Name, V>;
+/** Declares one Allen-mask parameter (the `$.allenParam` implementation). */
+declare function scopeAllenParam<Name extends string>(registry: QueryRegistry, name: Name): MaskParam<Name>;
+export type { AnyParamTerm, AnyTerm, AnyVar, Flatten, ItemParams, MaskParam, Param, ParamEntry, ParamSet, ParamsRecord, ParamsShape, QueryRegistry, TermContribution, UnionToIntersection, Var };
+export { createRegistry, isTerm, resolveFieldData, scopeAllenParam, scopeParam, scopeParamSet, scopeVar, term };
+//# sourceMappingURL=scope.d.ts.map

package/dist/query/scope.d.ts.map

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

package/dist/query/scope.js

@@ -0,0 +1,134 @@
+/**
+ * Query scope terms (PRD-08): typed variables and parameters, declared
+ * inside a `query()` scope callback so identity is lexical. A `Var` is
+ * typed by the field it is declared from and joins are brand-equal by
+ * construction (the nominal join discipline); var identity is OBJECT
+ * identity — two `$.var` calls are two variables even from the same field,
+ * and no name-collision machinery exists. Params are query-global, carry a
+ * mandatory literal name (the key of `execute`'s params object), and lower
+ * to dense positional `ParamId`s in declaration order. This module also
+ * owns the type-level params extraction: every atom and condition value
+ * carries its contributed params object in a phantom, and the query's
+ * `Params` type is the flattened intersection over the returned rules —
+ * inference rides the return value, never a mutable type accumulator.
+ */
+import * as errors from "@superbuilders/errors";
+import { phantom } from "#brand.ts";
+/**
+ * The runtime discriminant of query term values. Host literals (bigints,
+ * strings, interval objects, `oneOf` sets) never carry it, so "is this
+ * binding a term or a literal" is one property probe, never a guess.
+ */
+const term = Symbol("bumbledb.query.term");
+/** Narrows an unknown binding value to a scope term (vs a host literal). */
+function isTerm(value) {
+    return typeof value === "object" && value !== null && term in value;
+}
+/** Creates one empty scope registry over the query's theory. */
+function createRegistry(theory) {
+    return {
+        theory,
+        vars: new Set(),
+        params: [],
+        paramIndex: new Map(),
+        predicates: []
+    };
+}
+/**
+ * The relation-kind discriminant: a closed relation's runtime description
+ * carries its handle roster, an ordinary relation's never does.
+ */
+function isClosedMember(member) {
+    return "handles" in member.data;
+}
+/**
+ * Resolves a field reference's runtime description through the schema —
+ * the seam that types `$.var`/`$.param` declarations at runtime (the type
+ * level already carries the brand; this recovers the structural type the
+ * lowering and the param marshaler direct by).
+ */
+function resolveFieldData(theory, relationName, fieldName) {
+    const member = theory.relations[relationName];
+    if (member === undefined) {
+        throw errors.new(`schema ${theory.name} has no relation ${relationName}`);
+    }
+    if (isClosedMember(member)) {
+        if (fieldName === "id") {
+            return member.id.data;
+        }
+        const column = member.data.columns.find(function byName(candidate) {
+            return candidate.name === fieldName;
+        });
+        if (column === undefined) {
+            throw errors.new(`closed relation ${relationName} has no column ${fieldName}`);
+        }
+        return column.field;
+    }
+    const declared = member.data.fields.find(function byName(candidate) {
+        return candidate.name === fieldName;
+    });
+    if (declared === undefined) {
+        throw errors.new(`relation ${relationName} has no field ${fieldName}`);
+    }
+    return declared.field;
+}
+/** Declares one variable in the scope (the `$.var` implementation). */
+function scopeVar(registry, ref) {
+    const value = Object.freeze({
+        [term]: "var",
+        relation: ref.relation,
+        field: ref.field,
+        data: resolveFieldData(registry.theory, ref.relation, ref.field)
+    });
+    registry.vars.add(value);
+    return value;
+}
+/** Rejects a second parameter under an already-taken name. */
+function assertFreshParamName(registry, name) {
+    const taken = registry.params.some(function byName(entry) {
+        return entry.name === name;
+    });
+    if (taken) {
+        throw errors.new(`query scope already declares a param named ${name} — param names key the execute params object, one declaration each`);
+    }
+}
+/** Declares one scalar parameter (the `$.param` implementation). */
+function scopeParam(registry, name, ref) {
+    assertFreshParamName(registry, name);
+    const data = resolveFieldData(registry.theory, ref.relation, ref.field);
+    const value = Object.freeze({
+        [term]: "param",
+        name,
+        relation: ref.relation,
+        field: ref.field,
+        data
+    });
+    registry.paramIndex.set(value, registry.params.length);
+    registry.params.push(Object.freeze({ name, shape: "value", data }));
+    return value;
+}
+/** Declares one set parameter (the `$.paramSet` implementation). */
+function scopeParamSet(registry, name, ref) {
+    assertFreshParamName(registry, name);
+    const data = resolveFieldData(registry.theory, ref.relation, ref.field);
+    const value = Object.freeze({
+        [term]: "paramSet",
+        name,
+        relation: ref.relation,
+        field: ref.field,
+        data
+    });
+    registry.paramIndex.set(value, registry.params.length);
+    registry.params.push(Object.freeze({ name, shape: "set", data }));
+    return value;
+}
+/** Declares one Allen-mask parameter (the `$.allenParam` implementation). */
+function scopeAllenParam(registry, name) {
+    assertFreshParamName(registry, name);
+    const value = Object.freeze({ [term]: "maskParam", name });
+    registry.paramIndex.set(value, registry.params.length);
+    registry.params.push(Object.freeze({ name, shape: "mask", data: undefined }));
+    return value;
+}
+export { createRegistry, isTerm, resolveFieldData, scopeAllenParam, scopeParam, scopeParamSet, scopeVar, term };
+//# sourceMappingURL=scope.js.map