@bjornpagen/bumbledb 0.1.0

package/dist/query/lower.d.ts

@@ -0,0 +1,145 @@
+/**
+ * `query()` and the IR lowering (PRD-08). A query is built inside a scope
+ * callback (variable identity is lexical and typed) and is an INERT value:
+ * `Query<Rels, Row, Params>` with `Row` inferred from `select` and
+ * `Params` from every parameter the returned rules (and the predicates
+ * they reach) use. Lowering is a pure function of the query value down to
+ * the bridge's `ProgramIr` (`bumbledb/crates/bumbledb/src/ir.rs`, the
+ * bijection target): relations and predicates by declaration ordinal (the
+ * declaration-order-is-ids law the engine's manifest pins), variables by
+ * dense per-rule first-occurrence ids (rule-scoped, exactly as the IR
+ * scopes them), params by scope declaration order. Lowering is STABLE —
+ * the same query value lowers to deeply-equal IR every time, and two
+ * identically-written queries lower identically (prepared-query caching
+ * upstream keys on this). Construction validates negation safety (typed,
+ * naming the variable — earlier and warmer than the engine's refusal);
+ * everything else (strata, types, aggregates rosters, rule caps) is the
+ * ENGINE's judge, surfacing its typed errors at prepare. No invented
+ * limits: rule counts and predicate counts are never pre-checked here.
+ */
+import { phantom } from "#brand.ts";
+import { type FieldData } from "#fields.ts";
+import type { ProgramIr, TaggedValue } from "#native.ts";
+import type { AnyBodyItem } from "#query/atom.ts";
+import type { ColumnValues, Predicate, PredicateColumnsInput, PredicateParams, PredicateRuleInput, PredicateSelf } from "#query/predicate.ts";
+import type { AnyVar, ItemParams, MaskParam, Param, ParamSet, ParamsRecord, ParamsShape, QueryRegistry, Var } from "#query/scope.ts";
+import type { AggregateData, RowOf, SelectShape } from "#query/select.ts";
+import type { FieldRef } from "#relation.ts";
+import type { Schema, SchemaRelations } from "#schema.ts";
+/**
+ * The scope value the `query()` build callback receives: variable and
+ * parameter declaration plus predicate declaration (engine recursion).
+ */
+interface Scope<Rels extends SchemaRelations> {
+    /**
+     * Declares one query variable, typed by the field it is declared from
+     * — usable in ANY atom position whose field carries the same brand
+     * (the nominal join discipline). Two calls are two variables.
+     */
+    var<V>(field: FieldRef<keyof Rels & string, string, V>): Var<V>;
+    /**
+     * Declares one scalar parameter under a mandatory name literal — the
+     * key of the typed params object `execute` takes.
+     */
+    param<const Name extends string, V>(name: Name, field: FieldRef<keyof Rels & string, string, V>): Param<Name, V>;
+    /**
+     * Declares one set parameter (the IR's `ParamSet`): bound at execution
+     * to a readonly array; a binding position matches on set membership.
+     */
+    paramSet<const Name extends string, V>(name: Name, field: FieldRef<keyof Rels & string, string, V>): ParamSet<Name, V>;
+    /**
+     * Declares one Allen-mask parameter (`MaskTerm::Param`): the temporal
+     * relation as a bind-time 13-bit mask argument.
+     */
+    allenParam<const Name extends string>(name: Name): MaskParam<Name>;
+    /**
+     * Declares one IDB predicate with a named, field-typed head; its rules
+     * are given in the declaration through a callback receiving the
+     * predicate's own reference (self-recursion is `self.match({...})`).
+     * `.match` on the returned value uses it as a body atom elsewhere.
+     */
+    predicate<const Cols extends PredicateColumnsInput, const Rules extends readonly PredicateRuleInput<ColumnValues<Cols>>[]>(name: string, columns: Cols, rules: (self: PredicateSelf<ColumnValues<Cols>>) => Rules): Predicate<ColumnValues<Cols>, PredicateParams<Rules>>;
+}
+/**
+ * What the build callback returns: `rules` is an array of conjunctions
+ * (multiple rules = set union — answers are SETS, no order/limit exists;
+ * the host sorts); `select` is the head record — non-aggregate entries are
+ * the implicit group key.
+ */
+interface QueryBuild {
+    readonly rules: readonly (readonly AnyBodyItem[])[];
+    readonly select: SelectShape;
+}
+/** One classified select column as runtime data. */
+type SelectEntryData = {
+    readonly kind: "var";
+    readonly over: AnyVar;
+} | {
+    readonly kind: "measure";
+    readonly over: AnyVar;
+} | {
+    readonly kind: "aggregate";
+    readonly aggregate: AggregateData;
+};
+/** One answer column: its name (the row object key) and its entry. */
+interface SelectColumn {
+    readonly name: string;
+    readonly entry: SelectEntryData;
+}
+/** A query's runtime description — everything lowering and execution read. */
+interface QueryData {
+    readonly registry: QueryRegistry;
+    readonly rules: readonly (readonly AnyBodyItem[])[];
+    readonly select: readonly SelectColumn[];
+}
+/**
+ * An inert query value. `Row` is the inferred answer-row object type;
+ * `Params` the inferred execute-params object type. Prepare with
+ * `db.prepare(q)`; nothing here touches an engine.
+ */
+interface Query<Rels extends SchemaRelations, Row, Params extends ParamsRecord> {
+    readonly schema: Schema<Rels>;
+    readonly data: QueryData;
+    readonly [phantom]?: {
+        readonly row: Row;
+        readonly params: Params;
+    };
+}
+/** Any query value, whatever its schema and inferred types. */
+type AnyQuery = Query<SchemaRelations, unknown, ParamsRecord>;
+/** Extracts a query value's inferred answer-row type. */
+type QueryRow<Q extends AnyQuery> = Exclude<Q[typeof phantom], undefined>["row"];
+/** Extracts a query value's inferred execute-params type. */
+type QueryParams<Q extends AnyQuery> = Exclude<Q[typeof phantom], undefined>["params"];
+/** The params object type a build result implies (union over every rule item). */
+type BuildParams<R extends QueryBuild> = ParamsShape<ItemParams<R["rules"][number][number]>>;
+/**
+ * Builds a query as a typed value: runs `build` inside a fresh scope,
+ * classifies the select record (written order = answer column order),
+ * validates negation safety across every rule (the predicates' rules
+ * included), and freezes. Rule counts, strata legality, and every deeper
+ * roster stay the engine's judge at prepare.
+ */
+declare function query<Rels extends SchemaRelations, const R extends QueryBuild>(theory: Schema<Rels>, build: ($: Scope<Rels>) => R): Query<Rels, RowOf<R["select"]>, BuildParams<R>>;
+/**
+ * Tags one host literal at a FIELD position (atom bindings): the field's
+ * structural type directs the tag, never a guess. At an interval field a
+ * bigint literal tags as the ELEMENT type — the IR's membership typing
+ * rule (point membership), an interval-shaped literal as the interval
+ * (value equality). A closed-reference literal is its branded id, tagged
+ * u64 after a roster re-verification (queries cross ids, never handle
+ * names).
+ */
+declare function taggedLiteral(context: string, field: FieldData, value: unknown): TaggedValue;
+/**
+ * Lowers a query value to the bridge's `ProgramIr` — pure and stable: the
+ * declared predicates in declaration order (`PredId` = index), the output
+ * predicate (built from `rules` + `select`) appended last. Relations lower
+ * by declaration ordinal, the law the engine's own manifest pins;
+ * `db.prepare` re-verifies the alignment against the live manifest before
+ * sending.
+ */
+declare function lowerQuery(q: AnyQuery): ProgramIr;
+export type { AnyQuery, BuildParams, Query, QueryBuild, QueryData, QueryParams, QueryRow, Scope, SelectColumn, SelectEntryData };
+export { lowerQuery, query, taggedLiteral };
+//# sourceMappingURL=lower.d.ts.map

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

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