@astrale-os/sdk 0.6.0-beta.40 → 0.6.0-beta.42

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

@@ -0,0 +1,839 @@
+var _a, _b, _c;
+import { QUERY } from '../language/query.js';
+import { HANDLE_MEMBERS, ROW_KEYS } from './model.js';
+import { RelationRead, RootRead } from './plan.js';
+import { and, atom, Condition, describe, foldedTo, folding, kept, orderKeys, propertyHandle, scope, targetCondition, targetLabel, whereOf, within, } from './terms.js';
+const defined = (fields) => Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+const nonEmpty = (items) => items.length > 0 ? items : undefined;
+const keysOf = (classes) => classes.map((c) => c.key);
+/**
+ * A canonical document, from its family's fields. The lowering writes the grammar by construction;
+ * the lowering checks hold it to `SizedQuery<Schema>` per construct.
+ */
+const documentOf = (family) => ({ query: QUERY, ...family });
+const optional = (condition) => condition.always || condition.never ? undefined : whereOf(condition.conjuncts);
+/**
+ * A part of a document, from its conditions and its Branches: as sent, absent when a condition is
+ * NEVER, and as written when the input folds one of them (absent when it is the part as sent).
+ */
+function lowered(conditions, branches, write) {
+    const part = (cs, withs) => cs.some((c) => c.never) ? undefined : write(cs, withs);
+    const sent = part(conditions, branches.flatMap((b) => (b.branch === undefined ? [] : [b.branch])));
+    if (!conditions.some((c) => c.folded) && branches.every((b) => b.written === undefined))
+        return { sent };
+    const written = part(conditions.map((c) => c.asWritten), branches.flatMap((b) => {
+        const branch = b.written ?? b.branch;
+        return branch === undefined ? [] : [branch];
+    }));
+    return { sent, written };
+}
+/** A root read: its plan, and its document as `lowered` writes it from its condition. */
+function rootRead(plan, where, branches, write) {
+    const { sent, written } = lowered([where], branches, ([w], withs) => write(w, withs));
+    return new RootRead({
+        ...plan,
+        empty: sent === undefined,
+        ...(sent === undefined ? {} : { document: sent }),
+        ...(written === undefined ? {} : { written }),
+    });
+}
+/**
+ * A whole number of at least `min`, as a verb or a condition takes it. A verb bound past the
+ * Kernel's page is the call's `TOO_MANY`, since it may come from the input (S11).
+ */
+function integer(value, what, min) {
+    if (!Number.isSafeInteger(value) || value < min)
+        throw new TypeError(`${what} takes an integer of at least ${min}; got ${describe(value)}.`);
+    return value;
+}
+function callback(value, what) {
+    if (typeof value !== 'function')
+        throw new TypeError(`${what} takes a callback; got ${describe(value)}.`);
+    return value;
+}
+function options(value, what) {
+    if (typeof value !== 'object' || value === null)
+        throw new TypeError(`${what} takes an options object; got ${describe(value)}.`);
+    return value;
+}
+// ─── Handles ───────────────────────────────────────────────────────────────────────────────────
+/**
+ * The Property handles of some Classes by name: each Class's flat Properties, and on one Class
+ * its groups (F6). On a union, a name every Class keeps flat, by its keys (F7).
+ */
+function propertyHandles(model, classes, taken, context) {
+    const layouts = classes.map((c) => model.layout(c, taken));
+    const out = new Map();
+    for (const name of layouts[0]?.flat.keys() ?? []) {
+        const keys = layouts.map((layout) => layout.flat.get(name));
+        if (keys.every((key) => key !== undefined))
+            out.set(name, propertyHandle([...new Set(keys)], context));
+    }
+    if (layouts.length === 1)
+        for (const [group, members] of layouts[0].groups) {
+            const handles = Object.create(null);
+            for (const [name, key] of members)
+                handles[name] = propertyHandle([key], context);
+            out.set(group, Object.freeze(handles));
+        }
+    return out;
+}
+/** A handle with fixed members first, then names resolved once on first read. */
+function handle(fixed, resolve) {
+    const target = Object.freeze(Object.assign(Object.create(null), fixed));
+    const resolved = new Map();
+    return new Proxy(target, {
+        get(t, name) {
+            if (typeof name !== 'string')
+                return undefined;
+            if (Object.hasOwn(t, name))
+                return t[name];
+            if (!resolved.has(name))
+                resolved.set(name, resolve(name));
+            return resolved.get(name);
+        },
+    });
+}
+/** The Classes a Class handle names: a set of Nodes no method was called on. */
+function classesOf(value, what) {
+    if (value instanceof NodeSet && value.pristine)
+        return value.classes;
+    throw new TypeError(`${what} takes a Class handle (d.<Class>) on which no method was called.`);
+}
+/** The Edge Class an Edge handle names. */
+function edgeOf(value) {
+    if (value instanceof EdgeSet && value.pristine)
+        return value.edge;
+    throw new TypeError('via takes an Edge Class handle (d.<Edge>), or a list of them, on which no method was called.');
+}
+/**
+ * The one Class a Class handle names, as a write takes it: `d.<Class>`, on which no method was
+ * called. `undefined` for a value that is no set of roots.
+ */
+export function handleClass(value) {
+    if (value instanceof NodeSet) {
+        if (value.pristine && value.classes.length === 1)
+            return value.classes[0];
+    }
+    else if (value instanceof EdgeSet) {
+        if (value.pristine)
+            return value.edge;
+    }
+    else
+        return undefined;
+    throw new TypeError('A write names one Class by its handle, `d.<Class>`, on which no method was called.');
+}
+/**
+ * A guard's range (S7), the roots of a Class handle after `where`, `union` and `orderBy`, as a
+ * read: of whether one exists, or, `ordered`, of them in their order. `undefined` for a value that
+ * is no set of roots; a set whose rows render (`with`, `pick`, `includeWithheld`) is refused.
+ */
+export function rangeRead(value, ordered) {
+    if (value instanceof NodeSet)
+        return NodeSet.range(value, ordered);
+    if (value instanceof EdgeSet)
+        return EdgeSet.range(value, ordered);
+    return undefined;
+}
+function renderedRange() {
+    throw new TypeError("A guard reads its range's roots alone: `.with`, `.pick` and `.includeWithheld` render rows, which a guard never reads.");
+}
+const DIRECTIONS = new Set(['outgoing', 'incoming', 'incident']);
+/** The direction from `classes` along `edge`, written or derived from the end that accepts them. */
+function directionOf(model, classes, edge, written) {
+    const { source, target } = model.ends(edge);
+    const s = model.touches(classes, source);
+    const t = model.touches(classes, target);
+    if (written !== undefined) {
+        if (!DIRECTIONS.has(written))
+            throw new TypeError(`direction is outgoing, incoming or incident; got ${describe(written)}.`);
+        if ((written === 'outgoing' && !s) || (written === 'incoming' && !t) || (!s && !t))
+            throw new TypeError(`This Class is not the ${written === 'outgoing' ? 'source' : written === 'incoming' ? 'target' : 'end'} of ${edge.key}: check the direction.`);
+        return written;
+    }
+    if (s && t)
+        throw new TypeError(`Both ends of ${edge.key} accept this Class: pass { direction }.`);
+    if (!s && !t)
+        throw new TypeError(`${edge.key} has no end that accepts this Class: read it from a Class one of its ends accepts.`);
+    return s ? 'outgoing' : 'incoming';
+}
+/** A Node handle: its Properties, its named to-one relations, and the methods every Node has. */
+export function nodeHandle(model, classes, context) {
+    const properties = propertyHandles(model, classes, HANDLE_MEMBERS, context);
+    const classCondition = (op, of) => {
+        const atoms = of.map((c) => ({ op, class: c.key }));
+        const where = atoms.length === 1 ? atoms[0] : { op: 'or', operands: atoms };
+        return new Condition(atom(context, where).conjuncts, keysOf(of));
+    };
+    const fixed = {
+        id: Object.freeze({
+            eq: (target) => targetCondition(context, [target]),
+            in: (targets) => {
+                if (!Array.isArray(targets))
+                    throw new TypeError(`id.in takes a list; got ${describe(targets)}.`);
+                return targetCondition(context, targets);
+            },
+        }),
+        path: Object.freeze({
+            eq: (path) => pathCondition(context, [path]),
+            in: (paths) => {
+                if (!Array.isArray(paths))
+                    throw new TypeError(`path.in takes a list; got ${describe(paths)}.`);
+                return pathCondition(context, paths);
+            },
+        }),
+        is: (cls, conditions) => {
+            const narrowed = classesOf(cls, 'is');
+            const is = classCondition('is', narrowed);
+            if (conditions === undefined)
+                return is;
+            const inner = nodeHandle(model, narrowed, context);
+            const listed = kept(callback(conditions, 'is')(inner));
+            within(listed, [context.scope]);
+            return and([is, ...listed]);
+        },
+        isExactly: (cls) => classCondition('isExactly', classesOf(cls, 'isExactly')),
+        via: (edge, written) => {
+            const edges = (Array.isArray(edge) ? edge : [edge]).map(edgeOf);
+            if (edges.length === 0)
+                throw new TypeError('via takes at least one Edge Class handle.');
+            const asked = written === undefined
+                ? undefined
+                : options(written, 'via').direction;
+            const directions = new Set(edges.map((e) => directionOf(model, classes, e, asked)));
+            if (directions.size > 1)
+                throw new TypeError('These Edges leave this Class in different directions: pass { direction }.');
+            const [direction] = directions;
+            const far = model.reached(edges, direction);
+            if (far.length === 0)
+                throw new TypeError(`${keysOf(edges).join(', ')} reaches only Classes this Domain does not declare or depend on: depend on the Domain that declares them.`);
+            return Relation.of(model, `via(${keysOf(edges).join(', ')})`, edges, direction, far, context);
+        },
+    };
+    return handle(fixed, (name) => {
+        const property = properties.get(name);
+        if (property !== undefined)
+            return property;
+        return relationNamed(model, classes, name, context);
+    });
+}
+function pathCondition(context, paths) {
+    if (paths.length === 0)
+        return foldedTo(Condition.NEVER, atom(context, { op: 'path', paths: [] }));
+    for (const path of paths)
+        if (typeof path !== 'string' || !path.startsWith('/'))
+            throw new TypeError(`A path starts with "/"; got ${describe(path)}.`);
+    return atom(context, { op: 'path', paths });
+}
+/** The named to-one relation of a handle's Classes: on a union, one every Class names alike. */
+function relationNamed(model, classes, name, context) {
+    const named = classes.map((c) => model.relations(c).get(name));
+    if (named.some((r) => r !== undefined && 'ambiguous' in r))
+        throw new TypeError(`"${name}" names several relations of this Class: use .via(d.<Edge>).`);
+    const relations = named;
+    if (relations.length === 0 || relations.some((r) => r === undefined))
+        return undefined;
+    const directions = new Set(relations.map((r) => r.direction));
+    if (directions.size > 1)
+        return undefined;
+    const edges = [...new Set(relations.map((r) => r.edge))];
+    const far = [...new Set(relations.flatMap((r) => r.far))];
+    return Relation.of(model, name, edges, relations[0].direction, far, context);
+}
+/** An Edge handle in a `(node, edge) =>` callback: the Properties its Edges share. */
+function edgeHandle(model, edges, context) {
+    const properties = propertyHandles(model, edges, new Set(), context);
+    return handle({}, (name) => properties.get(name));
+}
+// ─── Branches ──────────────────────────────────────────────────────────────────────────────────
+const BRANCH_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+/**
+ * The Branches of a pattern, named after their `.with` keys: a key that is a valid Branch name
+ * keeps it, any other gets `w<index>`, made unique among its siblings.
+ */
+function lowerWiths(withs) {
+    const names = new Set();
+    const kept = withs.map(([key]) => {
+        if (!BRANCH_NAME.test(key) || names.has(key))
+            return undefined;
+        names.add(key);
+        return key;
+    });
+    return withs.map(([key, read], index) => {
+        let name = kept[index];
+        if (name === undefined) {
+            name = `w${index}`;
+            for (let n = 1; names.has(name); n += 1)
+                name = `w${index}_${n}`;
+            names.add(name);
+        }
+        return read.lower(key, name);
+    });
+}
+/** The relation reads a `.with` callback returned, by name, checked against the row's names. */
+function withsOf(value, handleScope, taken, earlier) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new TypeError(`with takes a callback that returns an object of relation reads; got ${describe(value)}.`);
+    const names = new Set(earlier.map(([name]) => name));
+    return Object.entries(value).map(([name, entry]) => {
+        if (taken.has(name) || ROW_KEYS.has(name) || names.has(name) || name.startsWith('$'))
+            throw new TypeError(`"${name}" is already a row key of this Class: give the .with another name.`);
+        const read = entry instanceof Exists ? entry.read : entry;
+        if (read instanceof RootRead)
+            throw new TypeError(`"${name}" reads another root: read it as a facet of the recipe.`);
+        if (!(read instanceof RelationRead))
+            throw new TypeError(`"${name}" is not a relation read: end the relation with a verb (find, first, all, count, exists).`);
+        if (read.scope !== handleScope)
+            throw new TypeError(`"${name}" reads a relation of another handle: a .with reads the handle it receives.`);
+        return [name, read];
+    });
+}
+const DISTINCT_EDGE = 'A distinct relation renders its Nodes only: its rows have no single Edge, so no withEdge.';
+function keyJson(key, distinct) {
+    let on;
+    if (key.target === 'item')
+        on = distinct ? undefined : 'node';
+    else if (key.target === 'edge') {
+        if (distinct)
+            throw new TypeError('A distinct relation orders by its Nodes only: its rows have no single Edge.');
+        on = 'edge';
+    }
+    else
+        on = key.target;
+    return defined({ property: key.property, direction: key.direction, missing: key.missing, on });
+}
+function rootKeyJson(key) {
+    return defined({
+        property: key.property,
+        direction: key.direction,
+        missing: key.missing,
+        on: key.target === 'source' || key.target === 'target' ? key.target : undefined,
+    });
+}
+/** A condition that is also a relation read: `exists()` is a boolean in `.with`. */
+class Exists extends Condition {
+    read;
+    constructor(condition, read) {
+        super(condition.conjuncts, undefined, condition.written);
+        this.read = read;
+    }
+}
+/** A relation from a Node: the Nodes at the far end of its Edges. */
+export class Relation {
+    #s;
+    constructor(state) {
+        this.#s = state;
+    }
+    static of(model, name, edges, direction, far, context) {
+        return new _a({
+            model,
+            name,
+            edges,
+            direction,
+            far,
+            context,
+            node: Condition.ALWAYS,
+            edge: Condition.ALWAYS,
+            orderBy: [],
+            with: [],
+            select: 'value',
+            withheld: false,
+            selectEdge: false,
+            distinct: false,
+        });
+    }
+    #next(patch) {
+        return new _a({ ...this.#s, ...patch });
+    }
+    /** Fresh handles for a `(node, edge) =>` callback, each on its own scope. */
+    #handles() {
+        const nodeScope = scope(`the Nodes of ${this.#s.name}`);
+        const edgeScope = scope(`the Edges of ${this.#s.name}`);
+        return {
+            node: nodeHandle(this.#s.model, this.#s.far, { scope: nodeScope, on: 'item' }),
+            edge: edgeHandle(this.#s.model, this.#s.edges, { scope: edgeScope, on: 'edge' }),
+            scopes: [nodeScope, edgeScope],
+        };
+    }
+    /** A `(node, edge) =>` callback's conditions, split into the node's and the Edge's. */
+    #split(conditions, what) {
+        if (conditions === undefined)
+            return { node: Condition.ALWAYS, edge: Condition.ALWAYS };
+        const { node, edge, scopes } = this.#handles();
+        const listed = kept(callback(conditions, what)(node, edge));
+        within(listed, scopes);
+        const narrows = [...new Set(listed.flatMap((c) => c.narrows ?? []))];
+        const side = (on) => folding(listed, (cs) => and(cs.map((c) => c.never ? Condition.NEVER : new Condition(c.conjuncts.filter((x) => x.scope === on)))));
+        return {
+            node: side(scopes[0]),
+            edge: side(scopes[1]),
+            ...(narrows.length > 0 ? { narrows } : {}),
+        };
+    }
+    where(conditions) {
+        const split = this.#split(callback(conditions, 'where'), 'where');
+        return this.#next({
+            node: and([this.#s.node, split.node]),
+            edge: and([this.#s.edge, split.edge]),
+            far: split.narrows ? split.narrows.map((key) => this.#s.model.classOf(key)) : this.#s.far,
+        });
+    }
+    orderBy(keys) {
+        const { node, edge, scopes } = this.#handles();
+        const ordering = callback(keys, 'orderBy')(node, edge);
+        return this.#next({ orderBy: [...this.#s.orderBy, ...orderKeys(ordering, scopes)] });
+    }
+    with(relations) {
+        const handleScope = scope(`the Nodes of ${this.#s.name}`);
+        const node = nodeHandle(this.#s.model, this.#s.far, { scope: handleScope, on: 'item' });
+        const value = callback(relations, 'with')(node);
+        const taken = new Set(this.#s.far.flatMap((c) => [...this.#s.model.propertyNames(c)]));
+        return this.#next({
+            with: [...this.#s.with, ...withsOf(value, handleScope, taken, this.#s.with)],
+        });
+    }
+    withEdge() {
+        if (this.#s.distinct)
+            throw new TypeError(DISTINCT_EDGE);
+        return this.#next({ selectEdge: true });
+    }
+    pick() {
+        return this.#next({ select: 'reference' });
+    }
+    includeWithheld() {
+        return this.#next({ withheld: true });
+    }
+    distinct() {
+        if (this.#s.selectEdge)
+            throw new TypeError(DISTINCT_EDGE);
+        return this.#next({ distinct: true });
+    }
+    #traversal(node, edge) {
+        return defined({
+            via: keysOf(this.#s.edges),
+            direction: this.#s.direction,
+            distinct: this.#s.distinct ? true : undefined,
+            edge: optional(edge),
+            node: optional(node),
+        });
+    }
+    #read(verb, limit, bound) {
+        const s = this.#s;
+        return new RelationRead(s.context.scope, (key, name) => {
+            const counted = verb === 'count' || verb === 'exists';
+            const branches = counted ? [] : lowerWiths(s.with);
+            const { sent, written } = lowered([s.node, s.edge], branches, ([node, edge], withs) => {
+                const traversal = this.#traversal(node, edge);
+                if (counted)
+                    return { name, ...traversal, mode: 'count', upTo: limit };
+                const orderBy = s.orderBy.map((k) => keyJson(k, s.distinct));
+                return defined({
+                    name,
+                    ...traversal,
+                    mode: 'optional',
+                    orderBy: nonEmpty(orderBy),
+                    select: s.select === 'value' ? 'value' : undefined,
+                    selectEdge: s.selectEdge ? 'value' : undefined,
+                    with: nonEmpty(withs),
+                    limit,
+                });
+            });
+            const plan = {
+                key,
+                name,
+                relation: s.name,
+                verb,
+                ...(bound === undefined ? {} : { bound }),
+                empty: sent === undefined,
+                edge: s.selectEdge,
+                classes: keysOf(s.far),
+                select: s.select,
+                withheld: s.withheld,
+                branches: branches.map((b) => b.plan),
+            };
+            return {
+                plan,
+                ...(sent === undefined ? {} : { branch: sent }),
+                ...(written === undefined ? {} : { written }),
+            };
+        });
+    }
+    /** Exactly one per parent: two rows, to see a second. */
+    get() {
+        return this.#read('get', 2);
+    }
+    find() {
+        return this.#read('find', 2);
+    }
+    first(n) {
+        if (n === undefined)
+            return this.#read('first', 1);
+        const bound = integer(n, 'first', 1);
+        return this.#read('firstN', bound, bound);
+    }
+    all(written) {
+        const max = integer(options(written, 'all').max, 'all({ max })', 1);
+        return this.#read('all', max + 1, max);
+    }
+    count(written) {
+        const upTo = integer(options(written, 'count').upTo, 'count({ upTo })', 1);
+        return this.#read('count', upTo, upTo);
+    }
+    /** At least `atLeast` Edges of the relation meet the extra conditions. */
+    #exists(extra, atLeast = 1) {
+        const sides = [and([this.#s.node, extra.node]), and([this.#s.edge, extra.edge])];
+        return folding(sides, ([node, edge]) => node.never || edge.never
+            ? Condition.NEVER
+            : atom(this.#s.context, {
+                op: 'exists',
+                ...this.#traversal(node, edge),
+                ...(atLeast > 1 ? { atLeast } : {}),
+            }));
+    }
+    /** A boolean per parent in a `.with`; a condition in a `where`. */
+    exists() {
+        return new Exists(this.#exists({ node: Condition.ALWAYS, edge: Condition.ALWAYS }), this.#read('exists', 1));
+    }
+    /** The relation reaches this Node. */
+    is(target) {
+        const node = targetCondition({ scope: scope(`the Nodes of ${this.#s.name}`), on: 'item' }, [
+            target,
+        ]);
+        return this.#exists({ node, edge: Condition.ALWAYS });
+    }
+    some(conditions) {
+        return this.#exists(this.#split(conditions, 'some'));
+    }
+    none(conditions) {
+        return this.#exists(this.#split(conditions, 'none')).not();
+    }
+    atLeast(n, conditions) {
+        const bound = integer(n, 'atLeast', 0);
+        const some = this.#exists(this.#split(conditions, 'atLeast'), Math.max(bound, 1));
+        // At least none is ALWAYS; as written, it still reads the relation.
+        return bound === 0 ? foldedTo(Condition.ALWAYS, some) : some;
+    }
+    atMost(n, conditions) {
+        const bound = integer(n, 'atMost', 0);
+        return this.#exists(this.#split(conditions, 'atMost'), bound + 1).not();
+    }
+    exactly(n, conditions) {
+        const bound = integer(n, 'exactly', 0);
+        const split = this.#split(conditions, 'exactly');
+        const more = this.#exists(split, bound + 1).not();
+        return bound === 0 ? more : and([this.#exists(split, bound), more]);
+    }
+    /** No Edge of the relation fails the conditions: `none` of their negation, on one side. */
+    every(conditions) {
+        const split = this.#split(callback(conditions, 'every'), 'every');
+        return folding([split.node, split.edge], ([node, edge]) => {
+            if (node.never || edge.never)
+                return this.none();
+            if (!node.always && !edge.always)
+                throw new TypeError('`every` over both the node and its Edge is not in Query v7: write one `every` per side.');
+            if (node.always && edge.always)
+                return Condition.ALWAYS;
+            const failing = node.always
+                ? { node: Condition.ALWAYS, edge: edge.not() }
+                : { node: node.not(), edge: Condition.ALWAYS };
+            return this.#exists(failing).not();
+        });
+    }
+}
+_a = Relation;
+/** The Nodes of a Class, or of a union of Classes, at the root of a read. */
+export class NodeSet {
+    #s;
+    constructor(state) {
+        this.#s = state;
+    }
+    static of(model, cls) {
+        const classes = [cls];
+        return new _b({
+            model,
+            roots: classes,
+            classes,
+            where: Condition.ALWAYS,
+            orderBy: [],
+            with: [],
+            select: 'value',
+            withheld: false,
+        });
+    }
+    /** Its Classes, after narrowing. */
+    get classes() {
+        return this.#s.classes;
+    }
+    /** No method was called on it but `union`: a Class handle, as `is` and `union` take one. */
+    get pristine() {
+        const s = this.#s;
+        return (s.where.always &&
+            s.orderBy.length === 0 &&
+            s.with.length === 0 &&
+            s.select === 'value' &&
+            !s.withheld &&
+            s.roots === s.classes);
+    }
+    /** The range a guard reads (S7); a set whose rows render is none. */
+    static range(set, ordered) {
+        const s = set.#s;
+        if (s.with.length > 0 || s.select !== 'value' || s.withheld)
+            renderedRange();
+        return ordered ? set.#list('first', 1) : set.#range('exists');
+    }
+    #next(patch) {
+        return new _b({ ...this.#s, ...patch });
+    }
+    #handle() {
+        const handleScope = scope(`the Nodes of ${keysOf(this.#s.classes).join(' | ')}`);
+        return {
+            node: nodeHandle(this.#s.model, this.#s.classes, { scope: handleScope, on: 'item' }),
+            scope: handleScope,
+        };
+    }
+    where(conditions) {
+        const { node, scope: handleScope } = this.#handle();
+        const listed = kept(callback(conditions, 'where')(node));
+        within(listed, [handleScope]);
+        const narrows = [...new Set(listed.flatMap((c) => c.narrows ?? []))];
+        return this.#next({
+            where: and([this.#s.where, ...listed]),
+            classes: narrows.length > 0 ? narrows.map((key) => this.#s.model.classOf(key)) : this.#s.classes,
+        });
+    }
+    orderBy(keys) {
+        const { node, scope: handleScope } = this.#handle();
+        const ordering = callback(keys, 'orderBy')(node);
+        return this.#next({ orderBy: [...this.#s.orderBy, ...orderKeys(ordering, [handleScope])] });
+    }
+    with(relations) {
+        const { node, scope: handleScope } = this.#handle();
+        const value = callback(relations, 'with')(node);
+        const taken = new Set(this.#s.classes.flatMap((c) => [...this.#s.model.propertyNames(c)]));
+        return this.#next({
+            with: [...this.#s.with, ...withsOf(value, handleScope, taken, this.#s.with)],
+        });
+    }
+    pick() {
+        return this.#next({ select: 'reference' });
+    }
+    includeWithheld() {
+        return this.#next({ withheld: true });
+    }
+    union(other) {
+        const s = this.#s;
+        if (!s.where.always || s.orderBy.length > 0 || s.with.length > 0 || s.roots !== s.classes)
+            throw new TypeError('Call union before where, orderBy and with: they read the union.');
+        const classes = [...new Set([...s.roots, ...classesOf(other, 'union')])];
+        return this.#next({ roots: classes, classes });
+    }
+    #root(branches) {
+        return {
+            kind: 'nodes',
+            classes: keysOf(this.#s.classes),
+            select: this.#s.select,
+            withheld: this.#s.withheld,
+            branches: branches.map((b) => b.plan),
+        };
+    }
+    #where(id) {
+        if (id === undefined)
+            return this.#s.where;
+        return and([this.#s.where, targetCondition({ scope: scope('the root'), on: 'item' }, [id])]);
+    }
+    #list(verb, limit, bound, id) {
+        const s = this.#s;
+        const where = this.#where(id);
+        const branches = lowerWiths(s.with);
+        const plan = {
+            verb,
+            ...(bound === undefined ? {} : { bound }),
+            ...(id === undefined ? {} : { target: targetLabel(id) }),
+            root: this.#root(branches),
+        };
+        return rootRead(plan, where, branches, (where, withs) => documentOf({
+            list: defined({
+                nodes: keysOf(s.roots),
+                where: optional(where),
+                orderBy: nonEmpty(s.orderBy.map(rootKeyJson)),
+                select: s.select === 'value' ? 'value' : undefined,
+                with: nonEmpty(withs),
+                limit,
+            }),
+        }));
+    }
+    #range(verb, id, upTo) {
+        const where = this.#where(id);
+        const plan = {
+            verb,
+            ...(upTo === undefined ? {} : { bound: upTo }),
+            ...(id === undefined ? {} : { target: targetLabel(id) }),
+            root: this.#root([]),
+        };
+        return rootRead(plan, where, [], (where) => {
+            const range = defined({ nodes: keysOf(this.#s.roots), where: optional(where) });
+            return documentOf(verb === 'exists' ? { exists: range } : { count: range, upTo });
+        });
+    }
+    /** Exactly one: two rows, to see a second. */
+    get(id) {
+        return this.#list('get', 2, undefined, id);
+    }
+    find(id) {
+        return this.#list('find', 2, undefined, id);
+    }
+    first(n, written) {
+        if (n === undefined)
+            return this.#list('first', 1);
+        const bound = integer(n, 'first', 1);
+        if (written !== undefined &&
+            options(written, 'first').more === true)
+            return this.#list('firstMore', bound + 1, bound);
+        return this.#list('firstN', bound, bound);
+    }
+    page(written) {
+        const max = integer(options(written, 'page').max, 'page({ max })', 1);
+        return this.#list('page', max, max);
+    }
+    all(written) {
+        const max = integer(options(written, 'all').max, 'all({ max })', 1);
+        return this.#list('all', max + 1, max);
+    }
+    exists(id) {
+        return this.#range('exists', id);
+    }
+    count(written) {
+        const upTo = integer(options(written, 'count').upTo, 'count({ upTo })', 1);
+        return this.#range('count', undefined, upTo);
+    }
+}
+_b = NodeSet;
+/** The Edges of a Class at the root of a read: its Properties, and both ends by role. */
+export class EdgeSet {
+    #s;
+    constructor(state) {
+        this.#s = state;
+    }
+    static of(model, edge) {
+        return new _c({
+            model,
+            edge,
+            where: Condition.ALWAYS,
+            orderBy: [],
+            select: 'value',
+            withheld: false,
+        });
+    }
+    get edge() {
+        return this.#s.edge;
+    }
+    get pristine() {
+        const s = this.#s;
+        return s.where.always && s.orderBy.length === 0 && s.select === 'value' && !s.withheld;
+    }
+    /** The range a guard reads (S7); a set whose rows render is none. */
+    static range(set, ordered) {
+        const s = set.#s;
+        if (s.select !== 'value' || s.withheld)
+            renderedRange();
+        return ordered ? set.#list('first', 1) : set.#range('exists');
+    }
+    #next(patch) {
+        return new _c({ ...this.#s, ...patch });
+    }
+    #handle() {
+        const { model, edge } = this.#s;
+        const handleScope = scope(`the Edges of ${edge.key}`);
+        const { source, target } = model.ends(edge);
+        const end = (e, on) => nodeHandle(model, model.far(e), {
+            scope: handleScope,
+            on,
+            wrap: (where) => ({ op: on, operand: where }),
+        });
+        const roles = new Set([source.role, target.role]);
+        const properties = propertyHandles(model, [edge], roles, { scope: handleScope, on: 'item' });
+        const ends = { [source.role]: end(source, 'source'), [target.role]: end(target, 'target') };
+        return { edge: handle(ends, (name) => properties.get(name)), scope: handleScope };
+    }
+    where(conditions) {
+        const { edge, scope: handleScope } = this.#handle();
+        const listed = kept(callback(conditions, 'where')(edge));
+        within(listed, [handleScope]);
+        return this.#next({ where: and([this.#s.where, ...listed]) });
+    }
+    orderBy(keys) {
+        const { edge, scope: handleScope } = this.#handle();
+        const ordering = callback(keys, 'orderBy')(edge);
+        return this.#next({ orderBy: [...this.#s.orderBy, ...orderKeys(ordering, [handleScope])] });
+    }
+    pick() {
+        return this.#next({ select: 'reference' });
+    }
+    includeWithheld() {
+        return this.#next({ withheld: true });
+    }
+    #root() {
+        const { model, edge } = this.#s;
+        const { source, target } = model.ends(edge);
+        return {
+            kind: 'edges',
+            classes: [edge.key],
+            select: this.#s.select,
+            withheld: this.#s.withheld,
+            source: { role: source.role, classes: keysOf(model.far(source)) },
+            target: { role: target.role, classes: keysOf(model.far(target)) },
+        };
+    }
+    #list(verb, limit, bound) {
+        const s = this.#s;
+        const plan = { verb, ...(bound === undefined ? {} : { bound }), root: this.#root() };
+        return rootRead(plan, s.where, [], (where) => documentOf({
+            list: defined({
+                edges: [s.edge.key],
+                where: optional(where),
+                orderBy: nonEmpty(s.orderBy.map(rootKeyJson)),
+                // Both ends, so each carries its Class; a reference Edge is the canonical default.
+                select: s.select === 'value'
+                    ? { edge: 'value', source: 'value', target: 'value' }
+                    : { source: 'reference', target: 'reference' },
+                limit,
+            }),
+        }));
+    }
+    #range(verb, upTo) {
+        const s = this.#s;
+        const plan = { verb, ...(upTo === undefined ? {} : { bound: upTo }), root: this.#root() };
+        return rootRead(plan, s.where, [], (where) => {
+            const range = defined({ edges: [s.edge.key], where: optional(where) });
+            return documentOf(verb === 'exists' ? { exists: range } : { count: range, upTo });
+        });
+    }
+    get() {
+        return this.#list('get', 2);
+    }
+    find() {
+        return this.#list('find', 2);
+    }
+    first(n) {
+        if (n === undefined)
+            return this.#list('first', 1);
+        const bound = integer(n, 'first', 1);
+        return this.#list('firstN', bound, bound);
+    }
+    page(written) {
+        const max = integer(options(written, 'page').max, 'page({ max })', 1);
+        return this.#list('page', max, max);
+    }
+    all(written) {
+        const max = integer(options(written, 'all').max, 'all({ max })', 1);
+        return this.#list('all', max + 1, max);
+    }
+    exists() {
+        return this.#range('exists');
+    }
+    count(written) {
+        const upTo = integer(options(written, 'count').upTo, 'count({ upTo })', 1);
+        return this.#range('count', upTo);
+    }
+}
+_c = EdgeSet;