@astrale-os/sdk 0.6.0-beta.41 → 0.6.0-beta.43

package/dist/application/query/execution/rows.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A read's answer as rows (spec § Semantics): each item rendered by the layout of the Class the
+ * plan reads it as, each verb's rule applied (`get` exactly one, `find` at most one, `all` at most
+ * `max`), and a fact the reader may not read left out, kept by `.includeWithheld()`, or an error
+ * where `get` and `find` meet one. Rows and lists are frozen portable JSON.
+ */
+import type { NodeId } from '../../../platform/graph/node/index.js';
+import type { QueryListAnswer } from '../answer/answer.js';
+import type { Model } from '../handles/model.js';
+import type { EdgeRootPlan, NodeRootPlan, Pattern, ReadPlan } from '../handles/plan.js';
+import type { EdgeKey } from '../handles/rows.js';
+type Json = Readonly<Record<string, unknown>>;
+type FactId = NodeId | EdgeKey;
+/** One delivered item; a Kernel with K-C gives each Node item its Class. */
+interface Item {
+    readonly fact: FactId;
+    readonly class?: string;
+    readonly edge?: EdgeKey;
+    readonly source?: Item;
+    readonly target?: Item;
+    readonly branches: Readonly<Record<string, unknown>>;
+}
+/** What renders one answer: the recipe it errs for, the Domain's Classes, the answer's facts. */
+export declare class Renderer {
+    #private;
+    readonly recipe: string;
+    readonly model: Model;
+    constructor(recipe: string, model: Model, answer: QueryListAnswer<unknown, unknown>);
+    /** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
+    node(item: Item, pattern: Pattern): Json | undefined;
+    /** An Edge root row: its identity, its values and both ends by role. */
+    edge(item: Item, plan: EdgeRootPlan): Json | undefined;
+    /** The rows of a root list, Node or Edge, leaving out what the reader may not read. */
+    rootRows(items: readonly Item[], root: NodeRootPlan | EdgeRootPlan): readonly Json[];
+    /** The one root row `get` or `find` gives. */
+    rootOne(item: Item, root: NodeRootPlan | EdgeRootPlan): Json;
+}
+/** The answer of a root read with nothing to read: its verb's empty answer. */
+export declare function emptyResult(recipe: string, plan: ReadPlan): unknown;
+/** A root read's result from its answer, by its verb. */
+export declare function rootResult(recipe: string, model: Model, plan: ReadPlan, answer: unknown): unknown;
+export {};

package/dist/application/query/execution/rows.js

@@ -0,0 +1,308 @@
+import { factKey, factsOf } from '../answer/facts.js';
+import { ROW_KEYS } from '../handles/model.js';
+import { QueryError } from './error.js';
+const NO_TAKEN = new Set();
+const freeze = (value) => Object.freeze(value);
+/** What renders one answer: the recipe it errs for, the Domain's Classes, the answer's facts. */
+export class Renderer {
+    recipe;
+    model;
+    #facts;
+    constructor(recipe, model, answer) {
+        this.recipe = recipe;
+        this.model = model;
+        this.#facts = factsOf(answer);
+    }
+    #fact(fact) {
+        return this.#facts.get(factKey(fact));
+    }
+    /** Until per-property read rights exist, a fact that withholds a key is one the reader may not read. */
+    #withheld(fact) {
+        return (this.#fact(fact)?.withheld.length ?? 0) > 0;
+    }
+    #class(item) {
+        if (item.class === undefined)
+            throw new QueryError('UNSUPPORTED', this.recipe, { feature: 'classes' });
+        return item.class;
+    }
+    /**
+     * The Class an item renders as: of the plan's, the most derived its own Class satisfies, or the
+     * first in the plan's order when none derives from all the others (`Record.union(Owned)` for an
+     * Issue that is both).
+     */
+    #layoutClass(key, classes) {
+        let own;
+        try {
+            own = this.model.classOf(key);
+        }
+        catch {
+            // A Class this Domain cannot name (a newer Schema): one plan Class is the only reading.
+            return classes.length === 1 ? this.model.classOf(classes[0]) : undefined;
+        }
+        if (classes.length === 0)
+            return own;
+        const satisfied = this.model.satisfies(own);
+        const candidates = classes.filter((k) => satisfied.has(k)).map((k) => this.model.classOf(k));
+        return (candidates.find((c) => candidates.every((o) => this.model.satisfies(c).has(o.key))) ??
+            candidates[0]);
+    }
+    /** The values of a fact by the layout of a Class: flat names, then groups (F6). */
+    #values(fact, c, taken) {
+        if (c === undefined)
+            return {};
+        const values = (this.#fact(fact)?.values ?? {});
+        const { flat, groups } = this.model.layout(c, taken);
+        const row = {};
+        for (const [name, key] of flat)
+            if (values[key] !== undefined)
+                row[name] = values[key];
+        for (const [group, members] of groups) {
+            const grouped = {};
+            for (const [name, key] of members)
+                if (values[key] !== undefined)
+                    grouped[name] = values[key];
+            row[group] = freeze(grouped);
+        }
+        return row;
+    }
+    #names(c) {
+        return freeze(c === undefined ? [] : [...this.model.propertyNames(c)]);
+    }
+    /** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
+    node(item, pattern) {
+        const cls = this.#class(item);
+        const id = item.fact;
+        const layout = this.#layoutClass(cls, pattern.classes);
+        if (this.#withheld(id)) {
+            if (!pattern.withheld)
+                return undefined;
+            return freeze({ id, $class: cls, $withheld: this.#names(layout) });
+        }
+        const row = { id, $class: cls };
+        if (pattern.select === 'value')
+            Object.assign(row, this.#values(id, layout, ROW_KEYS));
+        for (const branch of pattern.branches)
+            row[branch.key] = this.#relation(item, branch);
+        if ('edge' in pattern && pattern.edge && item.edge !== undefined)
+            row.$edge = this.#edgeValues(item.edge);
+        return freeze(row);
+    }
+    /** What `.withEdge()` adds: the Edge's Class and values, or the names it withholds. */
+    #edgeValues(edge) {
+        const c = this.#known(edge.class);
+        if (this.#withheld(edge))
+            return freeze({ $class: edge.class, $withheld: this.#names(c) });
+        return freeze({ $class: edge.class, ...this.#values(edge, c, NO_TAKEN) });
+    }
+    #known(key) {
+        try {
+            return this.model.classOf(key);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** An Edge root row: its identity, its values and both ends by role. */
+    edge(item, plan) {
+        const key = item.fact;
+        const identity = { $class: key.class, $source: key.source, $target: key.target };
+        const c = this.#known(key.class);
+        if (this.#withheld(key)) {
+            if (!plan.withheld)
+                return undefined;
+            return freeze({ ...identity, $withheld: this.#names(c) });
+        }
+        const roles = new Set([plan.source.role, plan.target.role]);
+        const row = { ...identity };
+        if (plan.select === 'value')
+            Object.assign(row, this.#values(key, c, roles));
+        const end = (rendered, classes) => {
+            if (rendered === undefined)
+                return undefined;
+            const pattern = { classes, select: plan.select, withheld: true, branches: [] };
+            return this.node(rendered, pattern);
+        };
+        row[plan.source.role] = end(item.source, plan.source.classes);
+        row[plan.target.role] = end(item.target, plan.target.classes);
+        return freeze(row);
+    }
+    /** A relation's answer for one parent, by its verb. */
+    #relation(parent, plan) {
+        if (plan.empty)
+            return this.#emptyRelation(parent, plan);
+        const answer = parent.branches[plan.name];
+        if (plan.verb === 'count' || plan.verb === 'exists') {
+            const { count, more } = answer;
+            return plan.verb === 'exists' ? count > 0 : freeze({ count, more });
+        }
+        const { items } = answer;
+        const relation = { relation: plan.relation, parent: parent.fact };
+        switch (plan.verb) {
+            case 'get':
+            case 'find': {
+                if (items.length > 1)
+                    throw this.#integrity(relation, 2);
+                const [item] = items;
+                if (item === undefined) {
+                    if (plan.verb === 'get')
+                        throw this.#integrity(relation, 0);
+                    return undefined;
+                }
+                return this.#one(item, plan);
+            }
+            case 'first':
+                return items[0] === undefined ? undefined : this.node(items[0], plan);
+            case 'all':
+                if (items.length > plan.bound)
+                    throw new QueryError('TOO_MANY', this.recipe, { limit: 'max', bound: plan.bound });
+                return this.#rows(items, plan);
+            default:
+                return this.#rows(items, plan);
+        }
+    }
+    #emptyRelation(parent, plan) {
+        switch (plan.verb) {
+            case 'get':
+                throw this.#integrity({ relation: plan.relation, parent: parent.fact }, 0);
+            case 'exists':
+                return false;
+            case 'count':
+                return freeze({ count: 0, more: false });
+            case 'firstN':
+            case 'all':
+                return freeze([]);
+            default:
+                return undefined;
+        }
+    }
+    #integrity(at, found) {
+        return new QueryError('INTEGRITY', this.recipe, { ...at, found });
+    }
+    /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
+    #one(item, pattern) {
+        if (this.#withheld(item.fact))
+            throw new QueryError('NOT_READABLE', this.recipe, { class: this.#class(item), id: item.fact });
+        return this.node(item, pattern);
+    }
+    #rows(items, pattern) {
+        return freeze(items.flatMap((item) => this.node(item, pattern) ?? []));
+    }
+    /** The rows of a root list, Node or Edge, leaving out what the reader may not read. */
+    rootRows(items, root) {
+        return freeze(items.flatMap((item) => (root.kind === 'nodes' ? this.node(item, root) : this.edge(item, root)) ?? []));
+    }
+    /** The one root row `get` or `find` gives. */
+    rootOne(item, root) {
+        if (this.#withheld(item.fact)) {
+            const fact = item.fact;
+            throw new QueryError('NOT_READABLE', this.recipe, {
+                class: typeof fact === 'string' ? this.#class(item) : fact.class,
+                id: fact,
+            });
+        }
+        return (root.kind === 'nodes' ? this.node(item, root) : this.edge(item, root));
+    }
+}
+/** The root Classes a root error names. */
+function classLabel(plan) {
+    return plan.root?.classes.join(' | ') ?? '';
+}
+/** The answer of a root read with nothing to read: its verb's empty answer. */
+export function emptyResult(recipe, plan) {
+    switch (plan.verb) {
+        case 'get':
+            throw new QueryError('NOT_FOUND', recipe, {
+                class: classLabel(plan),
+                ...(plan.target === undefined ? {} : { target: plan.target }),
+            });
+        case 'firstN':
+        case 'all':
+            return freeze([]);
+        case 'firstMore':
+            return freeze({ rows: freeze([]), more: false });
+        case 'page':
+            return freeze({ rows: freeze([]) });
+        case 'exists':
+            return false;
+        case 'count':
+            return freeze({ count: 0, more: false });
+        default:
+            return undefined;
+    }
+}
+/** A root read's result from its answer, by its verb. */
+export function rootResult(recipe, model, plan, answer) {
+    const json = answer;
+    if ('exists' in json)
+        return json.exists === true;
+    if ('count' in json)
+        return freeze({ count: json.count, more: json.more === true });
+    const listAnswer = answer;
+    const renderer = new Renderer(recipe, model, listAnswer);
+    const { items, complete, cursor } = listAnswer.list;
+    const root = plan.root ?? documentRoot(plan);
+    switch (plan.verb) {
+        case 'get':
+        case 'find': {
+            if (items.length > 1)
+                throw new QueryError('INTEGRITY', recipe, { relation: classLabel(plan), found: 2 });
+            const [item] = items;
+            if (item === undefined)
+                return emptyResult(recipe, plan);
+            return renderer.rootOne(item, root);
+        }
+        case 'first':
+            return items[0] === undefined ? undefined : renderer.rootRows(items.slice(0, 1), root)[0];
+        case 'firstMore': {
+            const n = plan.bound;
+            return freeze({ rows: renderer.rootRows(items.slice(0, n), root), more: items.length > n });
+        }
+        case 'page':
+            return freeze({
+                rows: renderer.rootRows(items, root),
+                ...(complete || cursor === undefined ? {} : { next: cursor }),
+            });
+        case 'all':
+            if (items.length > plan.bound)
+                throw new QueryError('TOO_MANY', recipe, { limit: 'max', bound: plan.bound });
+            return renderer.rootRows(items, root);
+        default:
+            return renderer.rootRows(items, root);
+    }
+}
+/**
+ * The plan of a document read (D23): its rows rendered like any read, each by its own Class, its
+ * Branches by name, a list as rows and a count as a count.
+ */
+function documentRoot(plan) {
+    const list = plan.document.list;
+    const branches = (pattern) => (pattern.with ?? []).map((b) => ({
+        key: b.name,
+        name: b.name,
+        relation: b.name,
+        verb: b.mode === 'count' ? 'count' : 'firstN',
+        empty: false,
+        edge: b.selectEdge !== undefined,
+        classes: [],
+        select: b.select === 'value' ? 'value' : 'reference',
+        withheld: false,
+        branches: branches(b),
+    }));
+    if ('nodes' in list)
+        return {
+            kind: 'nodes',
+            classes: [],
+            select: list.select === 'value' ? 'value' : 'reference',
+            withheld: false,
+            branches: branches(list),
+        };
+    const select = (list.select ?? {});
+    return {
+        kind: 'edges',
+        classes: [],
+        select: select.edge === 'value' ? 'value' : 'reference',
+        withheld: false,
+        source: { role: 'source', classes: [] },
+        target: { role: 'target', classes: [] },
+    };
+}

package/dist/application/query/execution/split.d.ts

@@ -0,0 +1,24 @@
+import type { QueryCountAnswer, QueryExistsAnswer, QueryListAnswer } from '../answer/answer.js';
+import type { AnyQuery } from '../language/query.js';
+/** The Kernel's set members per v7 document: ids and value-set points, guards included. */
+export declare const MAXIMUM_MEMBERS = 32768;
+type ListAnswer = QueryListAnswer<unknown, unknown>;
+type Answer = ListAnswer | QueryExistsAnswer | QueryCountAnswer;
+/**
+ * The members a document counts against the Kernel's limit: each id, each value of an `in`, one
+ * for each other value atom. The Kernel may count fewer (it merges sets), never more.
+ */
+export declare function membersOf(value: unknown): number;
+/**
+ * The documents a read is sent as: itself, or one per slice of its root id list when it is past
+ * the members limit, each id in one slice only. `values` asks each slice for its root's values, so
+ * an ordered read can merge. A document whose members lie elsewhere is sent whole, and the Kernel
+ * names the limit.
+ */
+export declare function split(document: AnyQuery, values: boolean): readonly AnyQuery[];
+/**
+ * The answers of a split read as one: a list merged in the document's order and cut to its limit,
+ * `exists` if any slice has one, a count summed up to its bound.
+ */
+export declare function merge(document: AnyQuery, answers: readonly Answer[]): Answer;
+export {};

package/dist/application/query/execution/split.js

@@ -0,0 +1,190 @@
+/**
+ * Long id lists (spec § Recipes: the contract, § Semantics): a document past the Kernel's set
+ * members is sent as several, its root id list split, and their answers merged back in the
+ * Kernel's order and cut to the read's limit. Only a Node root's id list splits, and only for a
+ * read that is not a page: a page's cursor continues one document.
+ */
+import { compareQueryText } from '@astrale-os/kernel-core/graph/query';
+import { compareNodeIds } from '../../../platform/graph/node/index.js';
+import { factKey } from '../answer/facts.js';
+/** The Kernel's set members per v7 document: ids and value-set points, guards included. */
+export const MAXIMUM_MEMBERS = 32_768;
+const familyOf = (document) => 'list' in document ? 'list' : 'exists' in document ? 'exists' : 'count';
+/**
+ * The members a document counts against the Kernel's limit: each id, each value of an `in`, one
+ * for each other value atom. The Kernel may count fewer (it merges sets), never more.
+ */
+export function membersOf(value) {
+    if (Array.isArray(value))
+        return value.reduce((total, v) => total + membersOf(v), 0);
+    if (value === null || typeof value !== 'object')
+        return 0;
+    const record = value;
+    switch (record.op) {
+        case 'id':
+            return record.ids.length;
+        case 'in':
+            return record.values.length;
+        case 'eq':
+        case 'range':
+        case 'startsWith':
+            return 1;
+        case 'present':
+        case 'path':
+        case 'is':
+            return 0;
+    }
+    return Object.values(record).reduce((total, v) => total + membersOf(v), 0);
+}
+/** Where a Node root's id list is: its root, and the `id` atom with the most ids. */
+function idList(document) {
+    const root = document[familyOf(document)];
+    if (!('nodes' in root))
+        return undefined;
+    const where = root.where;
+    if (where?.op === 'id')
+        return { root };
+    if (where?.op !== 'and')
+        return undefined;
+    let at;
+    let most = 0;
+    for (const [index, operand] of where.operands.entries()) {
+        const ids = operand.op === 'id' ? operand.ids.length : 0;
+        if (ids > most)
+            [at, most] = [index, ids];
+    }
+    return at === undefined ? undefined : { root, at };
+}
+/**
+ * The documents a read is sent as: itself, or one per slice of its root id list when it is past
+ * the members limit, each id in one slice only. `values` asks each slice for its root's values, so
+ * an ordered read can merge. A document whose members lie elsewhere is sent whole, and the Kernel
+ * names the limit.
+ */
+export function split(document, values) {
+    const members = membersOf(document);
+    if (members <= MAXIMUM_MEMBERS)
+        return [document];
+    const found = idList(document);
+    if (found === undefined)
+        return [document];
+    const where = found.root.where;
+    const atom = found.at === undefined ? where : where.operands[found.at];
+    const listed = atom.ids;
+    const room = MAXIMUM_MEMBERS - (members - listed.length);
+    const ids = [...new Set(listed)];
+    if (room < 1)
+        return [document];
+    const family = familyOf(document);
+    const slices = [];
+    for (let start = 0; start < ids.length; start += room) {
+        const sliced = { op: 'id', ids: ids.slice(start, start + room) };
+        const operands = found.at === undefined ? undefined : [...where.operands];
+        if (operands !== undefined)
+            operands[found.at] = sliced;
+        const root = {
+            ...found.root,
+            where: operands === undefined ? sliced : { ...where, operands },
+            ...(values && family === 'list' ? { select: 'value' } : {}),
+        };
+        slices.push({ ...document, [family]: root });
+    }
+    return slices;
+}
+function rank(fact, property) {
+    if (fact === undefined || fact.withheld.includes(property))
+        return 'closed';
+    const value = fact.values[property];
+    if (value === undefined || value === null || typeof value === 'object')
+        return 'missing';
+    return { value: value };
+}
+function compareValues(left, right) {
+    if (typeof left === 'string' && typeof right === 'string')
+        return compareQueryText(left, right);
+    return Math.sign(Number(left) - Number(right));
+}
+/** Missing values sit first or last, closed ones after both; identity breaks every tie. */
+function comparator(keys, facts) {
+    const bucket = (r, key) => r === 'closed'
+        ? 2
+        : r === 'missing'
+            ? key.missing === 'first'
+                ? 0
+                : 1
+            : key.missing === 'first'
+                ? 1
+                : 0;
+    return (left, right) => {
+        for (const key of keys) {
+            const a = rank(facts.get(factKey(left.fact)), key.property);
+            const b = rank(facts.get(factKey(right.fact)), key.property);
+            const buckets = bucket(a, key) - bucket(b, key);
+            if (buckets !== 0)
+                return buckets;
+            if (typeof a === 'object' && typeof b === 'object') {
+                const compared = compareValues(a.value, b.value);
+                if (compared !== 0)
+                    return key.direction === 'asc' ? compared : -compared;
+            }
+        }
+        return compareNodeIds(left.fact, right.fact);
+    };
+}
+function undecidedOf(reported) {
+    const known = reported.filter((u) => u !== undefined);
+    if (known.length === 0)
+        return undefined;
+    return {
+        count: known.reduce((total, u) => total + u.count, 0),
+        more: known.some((u) => u.more),
+    };
+}
+/**
+ * The answers of a split read as one: a list merged in the document's order and cut to its limit,
+ * `exists` if any slice has one, a count summed up to its bound.
+ */
+export function merge(document, answers) {
+    if (answers.length === 1)
+        return answers[0];
+    const json = document;
+    if ('exists' in json) {
+        const all = answers;
+        const undecided = all.some((a) => a.undecided === true);
+        return { exists: all.some((a) => a.exists), ...(undecided ? { undecided } : {}) };
+    }
+    if ('count' in json) {
+        const all = answers;
+        const upTo = json.upTo;
+        const sum = all.reduce((total, a) => total + a.count, 0);
+        const undecided = undecidedOf(all.map((a) => a.undecided));
+        return {
+            count: Math.min(sum, upTo),
+            more: sum > upTo || all.some((a) => a.more),
+            ...(undecided === undefined ? {} : { undecided }),
+        };
+    }
+    const lists = answers;
+    const root = json.list;
+    const facts = new Map();
+    for (const answer of lists)
+        for (const fact of answer.facts)
+            facts.set(factKey(fact.fact), fact);
+    const limit = root.limit;
+    const items = lists
+        .flatMap((answer) => answer.list.items)
+        .sort(comparator((root.orderBy ?? []), facts));
+    const undecided = undecidedOf(lists.map((a) => a.list.undecided));
+    const last = lists[lists.length - 1];
+    const revised = lists.some((a) => a.revised === true || a.revision !== lists[0].revision);
+    return {
+        list: {
+            items: items.slice(0, limit),
+            complete: items.length <= limit && lists.every((a) => a.list.complete),
+            ...(undecided === undefined ? {} : { undecided }),
+        },
+        facts: [...facts.values()],
+        revision: last.revision,
+        ...(revised ? { revised: true } : {}),
+    };
+}

package/dist/application/query/handles/build.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The handles a recipe's `build` receives (S1), built once per resolved Domain: its own Classes,
+ * each dependency under its alias, the Kernel's Classes under `kernel`, its Core nodes under
+ * `core`, `origin`, and `document`, the escape hatch (D23). The fixed names win over a Class or
+ * an alias of the same name.
+ */
+import type { Domain } from '../../../platform/schema/index.js';
+import type { Handles } from './handles.js';
+/** The handles of a resolved Domain, built once. */
+export declare function handlesOf<Schema>(domain: Domain): Handles<Schema>;

package/dist/application/query/handles/build.js

@@ -0,0 +1,53 @@
+import { Path } from '../../../platform/graph/path/index.js';
+import { QUERY } from '../language/query.js';
+import { kernelClasses, modelOf } from './model.js';
+import { RootRead } from './plan.js';
+import { EdgeSet, NodeSet } from './reads.js';
+import { CoreNode, describe } from './terms.js';
+const FIXED = new Set(['kernel', 'core', 'origin', 'document']);
+function classHandles(model, classes) {
+    const out = {};
+    for (const [name, c] of Object.entries(classes)) {
+        if (FIXED.has(name))
+            continue;
+        out[name] = c.kind === 'edge' ? EdgeSet.of(model, c) : NodeSet.of(model, c);
+    }
+    return Object.freeze(out);
+}
+/** One canonical document, its rows unknown (D23): the read checks only its version. */
+function document(query) {
+    if (typeof query !== 'object' ||
+        query === null ||
+        query.query !== QUERY)
+        throw new TypeError(`d.document takes one canonical ${QUERY} document; got ${describe(query)}.`);
+    return new RootRead({
+        verb: 'document',
+        empty: false,
+        document: query,
+    });
+}
+const built = new WeakMap();
+/** The handles of a resolved Domain, built once. */
+export function handlesOf(domain) {
+    let handles = built.get(domain);
+    if (handles === undefined) {
+        const model = modelOf(domain);
+        const aliases = {};
+        for (const [alias, dependency] of Object.entries(domain.dependencies))
+            if (!FIXED.has(alias))
+                aliases[alias] = classHandles(model, dependency.classes);
+        const core = {};
+        for (const [name, node] of Object.entries(domain.core.nodes))
+            core[name] = new CoreNode(node.key, Path.project(node.ref).raw);
+        handles = Object.freeze({
+            ...aliases,
+            ...classHandles(model, domain.classes),
+            kernel: classHandles(model, kernelClasses()),
+            core: Object.freeze(core),
+            origin: domain.origin,
+            document,
+        });
+        built.set(domain, handles);
+    }
+    return handles;
+}