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

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

@@ -0,0 +1,100 @@
+/**
+ * Edge ends and the named to-one relations of a Class (S2), grouped once per Schema (D3).
+ */
+import type { HandleMembers } from './conditions.js';
+import type { Cls, EdgesOf, Index, KeyOf, NodeRoot, OriginOf, PropNamesOf, Satisfies, Single } from './domain.js';
+import type { RelSet } from './handles.js';
+/** An Edge's two ends; an undirected Edge's are its two incident ends, in declared order. */
+type EndsOf<E> = E extends {
+    readonly definition: {
+        readonly endpoints: infer P;
+    };
+} ? P extends readonly [infer A, infer B] ? {
+    readonly source: A;
+    readonly target: B;
+} : P : never;
+type SourceOf<E> = EndsOf<E> extends {
+    readonly source: infer End;
+} ? End : never;
+type TargetOf<E> = EndsOf<E> extends {
+    readonly target: infer End;
+} ? End : never;
+export type RoleOf<End> = End extends {
+    readonly role: infer R extends string;
+} ? R : never;
+type RefKey<A> = A extends {
+    readonly origin: infer O extends string;
+    readonly name: infer N extends string;
+} ? `${O}:class.${N}` : never;
+type AcceptKeys<End> = End extends {
+    readonly accepts: readonly (infer A)[];
+} ? RefKey<A> : never;
+type CountOf<End> = End extends {
+    readonly outgoing: infer N;
+} ? N : End extends {
+    readonly incoming: infer N;
+} ? N : End extends {
+    readonly incident: infer N;
+} ? N : never;
+type Touches<Sat, End> = [Extract<Sat, AcceptKeys<End>>] extends [never] ? false : true;
+/** An end names its relation only if it accepts specific Classes (S2). */
+type Generic = NodeRoot | 'kernel.astrale.ai:class.Identity';
+type Specific<End> = [Extract<AcceptKeys<End>, Generic>] extends [never] ? true : false;
+/** The Class keys an Edge's source accepts, and its role. */
+export type SourceKeys<S, E> = AcceptKeys<SourceOf<Cls<S, E>>> & keyof Index<S>;
+export type TargetKeys<S, E> = AcceptKeys<TargetOf<Cls<S, E>>> & keyof Index<S>;
+export type SourceRole<S, E> = RoleOf<SourceOf<Cls<S, E>>>;
+export type TargetRole<S, E> = RoleOf<TargetOf<Cls<S, E>>>;
+interface Candidate<N extends string, E extends string, Own extends boolean, Far extends string> {
+    readonly name: N;
+    readonly edge: E;
+    readonly own: Own;
+    readonly far: Far;
+}
+type IsOwn<S, E> = KeyOf<E> extends `${OriginOf<S>}:${string}` ? true : false;
+type ToOne = '0..1' | '1';
+/** One to-one end: the Class key it accepts, and the relation it names from there. */
+interface EndEntry<At extends string, C> {
+    readonly at: At;
+    readonly candidate: C;
+}
+type EntriesAt<At, C> = At extends string ? EndEntry<At, C> : never;
+type ToOneEnds<S> = EdgesOf<S> extends infer E ? E extends unknown ? (CountOf<SourceOf<E>> extends ToOne ? Specific<TargetOf<E>> extends true ? EntriesAt<AcceptKeys<SourceOf<E>>, Candidate<RoleOf<TargetOf<E>>, KeyOf<E>, IsOwn<S, E>, AcceptKeys<TargetOf<E>>>> : never : never) | (CountOf<TargetOf<E>> extends ToOne ? Specific<SourceOf<E>> extends true ? EntriesAt<AcceptKeys<TargetOf<E>>, Candidate<RoleOf<SourceOf<E>>, KeyOf<E>, IsOwn<S, E>, AcceptKeys<SourceOf<E>>>> : never : never) : never : never;
+/** Every to-one end of the Domain, grouped by the Class key it accepts: computed once per Schema. */
+type EndsByClass<S> = {
+    readonly [P in ToOneEnds<S> as P['at']]: P['candidate'];
+};
+/** The to-one relations a Class may name: one per end it reaches from a to-one end. */
+type CandidatesOf<S, Sat> = EndsByClass<S>[Sat & keyof EndsByClass<S>];
+type NameOf<C> = C extends {
+    readonly name: infer N extends string;
+} ? N : never;
+/** The Domain's own relations shadow its dependencies' (S2). */
+type Shadowed<Cs> = Extract<Cs, {
+    readonly own: true;
+}> | Exclude<Extract<Cs, {
+    readonly own: false;
+}>, {
+    readonly name: NameOf<Extract<Cs, {
+        readonly own: true;
+    }>>;
+}>;
+/**
+ * The named to-one relations of one Class (S2), clashing with nothing on the Class. A name two
+ * ends claim names neither: its member is a message that says so.
+ */
+export type RelationsOf<S, K> = Shadowed<CandidatesOf<S, Satisfies<S, K>>> extends infer Cs ? {
+    readonly [C in Cs as Exclude<NameOf<C>, PropNamesOf<Cls<S, K>> | HandleMembers>]: Single<C> extends true ? C extends Candidate<string, infer E, boolean, infer Far> ? RelSet<S, Far & keyof Index<S>, E, {}, 'value', false> : never : `✗ "${NameOf<C>}" names several relations of this Class: use .via(d.<Edge>)`;
+} : never;
+export interface ViaOptions {
+    readonly direction?: 'outgoing' | 'incoming' | 'incident';
+}
+type DirectionOf<S, K, E, O> = O extends {
+    readonly direction: infer D;
+} ? D extends 'outgoing' ? Touches<Satisfies<S, K>, SourceOf<Cls<S, E>>> extends true ? D : 'not the source' : D extends 'incoming' ? Touches<Satisfies<S, K>, TargetOf<Cls<S, E>>> extends true ? D : 'not the target' : D : Touches<Satisfies<S, K>, SourceOf<Cls<S, E>>> extends true ? Touches<Satisfies<S, K>, TargetOf<Cls<S, E>>> extends true ? 'ambiguous' : 'outgoing' : Touches<Satisfies<S, K>, TargetOf<Cls<S, E>>> extends true ? 'incoming' : 'none';
+type FarKeys<S, E, Dir> = E extends unknown ? Dir extends 'outgoing' ? AcceptKeys<TargetOf<Cls<S, E>>> : Dir extends 'incoming' ? AcceptKeys<SourceOf<Cls<S, E>>> : AcceptKeys<TargetOf<Cls<S, E>>> | AcceptKeys<SourceOf<Cls<S, E>>> : never;
+/** The Class keys a `.via` reaches. */
+export type Far<S, K, E, O> = FarKeys<S, E, DirectionOf<S, K, E, O>> & keyof Index<S>;
+/** A `.via` whose Edge has no end for this Class, or two, or reaches only foreign Classes. */
+export type ViaCheck<S, K, E, O> = E extends unknown ? DirectionOf<S, K, E, O> extends 'none' ? `✗ ${E & string} has no end that accepts this Class: read it from a Class one of its ends accepts` : DirectionOf<S, K, E, O> extends `not the ${infer End}` ? `✗ this Class is not the ${End} of ${E & string}: check the direction` : DirectionOf<S, K, E, O> extends 'ambiguous' ? `✗ both ends of ${E & string} accept this Class: pass { direction }` : [Far<S, K, E, O>] extends [never] ? `✗ ${E & string} reaches only Classes this Domain does not declare or depend on: depend on the Domain that declares them` : unknown : never;
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,94 @@
+/**
+ * What a read answers: rows, pages and counts. Rows are portable JSON: `$class` is typed as the
+ * Class or any subclass the Domain can name (D6), and a Property whose name is taken goes under
+ * `$prop` (F6).
+ */
+import type { NodeId } from '../../../platform/graph/node/index.js';
+import type { ClassOf, Cls, Layout, LayoutOf, PropNamesOf, RequiredEntry, SdkKeys, ValueOfEntry } from './domain.js';
+import type { SourceKeys, SourceRole, TargetKeys, TargetRole } from './relations.js';
+/**
+ * Names a row owns (`ROW_KEYS`): `id` and the SDK's keys. A Property named `id` goes under `$prop`
+ * (F6); no Property name starts with `$`. Frozen, as `ROW_KEYS` is.
+ */
+export type RowKeys = 'id' | SdkKeys;
+/** An optional Property may be absent from a row (not delivered); `null` is a stored null. */
+type Slot<P> = RequiredEntry<P> extends true ? ValueOfEntry<P> : ValueOfEntry<P> | undefined;
+type ValuesOfLayout<L> = L extends Layout<infer Flat, infer Groups> ? {
+    readonly [N in keyof Flat]: Slot<Flat[N]>;
+} & {
+    readonly [G in keyof Groups]: {
+        readonly [N in keyof Groups[G]]: Slot<Groups[G][N]>;
+    };
+} : never;
+type ValuesOf<S, K, Taken> = ValuesOfLayout<LayoutOf<Cls<S, K>, Taken>>;
+/** A Node row: `id`, `$class` and every Property by name. One member per Class of a union. */
+export type Row<S, K> = K extends unknown ? {
+    readonly id: NodeId;
+    readonly $class: ClassOf<S, K>;
+} & ValuesOf<S, K, RowKeys> : never;
+/** A reference row (`.pick()`): `id` and `$class`. */
+export type Ref<S, K> = K extends unknown ? {
+    readonly id: NodeId;
+    readonly $class: ClassOf<S, K>;
+} : never;
+/** A row the reader may not read (`.includeWithheld()`): the names of the values withheld. */
+export type WithheldRow<S, K> = K extends unknown ? {
+    readonly id: NodeId;
+    readonly $class: ClassOf<S, K>;
+    readonly $withheld: readonly PropNamesOf<Cls<S, K>>[];
+} : never;
+/**
+ * An Edge's identity: its Class and both ends. An object type, not an interface: a recipe's
+ * exported declaration then spells it out.
+ */
+type EdgeIdentity<E> = {
+    readonly $class: E;
+    readonly $source: NodeId;
+    readonly $target: NodeId;
+};
+/** An Edge row: its Class, both ends' ids and its Properties. */
+export type EdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & ValuesOf<S, E, never> : never;
+/** What `.withEdge()` adds to a row under `$edge`: the Edge's Class and its Properties. */
+export type EdgeValues<S, E> = E extends unknown ? {
+    readonly $class: ClassOf<S, E>;
+} & ValuesOf<S, E, never> : never;
+type Roles<S, E> = SourceRole<S, E> | TargetRole<S, E>;
+/** An Edge row at the root: its values, and both ends' rows by role. */
+export type EdgeRootRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & ValuesOf<S, E, Roles<S, E>> & {
+    readonly [R in SourceRole<S, E>]: Row<S, SourceKeys<S, E>>;
+} & {
+    readonly [R in TargetRole<S, E>]: Row<S, TargetKeys<S, E>>;
+} : never;
+/** An Edge reference row at the root (`.pick()`): both ends as references. */
+export type EdgeRootRef<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & {
+    readonly [R in SourceRole<S, E>]: Ref<S, SourceKeys<S, E>>;
+} & {
+    readonly [R in TargetRole<S, E>]: Ref<S, TargetKeys<S, E>>;
+} : never;
+/** An Edge the reader may not read (`.includeWithheld()`). */
+export type WithheldEdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & {
+    readonly $withheld: readonly PropNamesOf<Cls<S, E>>[];
+} : never;
+/** An Edge's identity, as a Mutation or a guard names it. */
+export interface EdgeKey<E extends string = string> {
+    readonly source: NodeId;
+    readonly target: NodeId;
+    readonly class: E;
+}
+/** The identity of an Edge row. */
+export declare function edgeKey<E extends string>(row: {
+    readonly $class: E;
+    readonly $source: NodeId;
+    readonly $target: NodeId;
+}): EdgeKey<E>;
+/** One page of rows; `next` continues it. */
+export interface Page<T> {
+    readonly rows: readonly T[];
+    readonly next?: string;
+}
+/** A bounded count: `more` says the count reached its bound. */
+export interface Count {
+    readonly count: number;
+    readonly more: boolean;
+}
+export {};

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

@@ -0,0 +1,4 @@
+/** The identity of an Edge row. */
+export function edgeKey(row) {
+    return { source: row.$source, target: row.$target, class: row.$class };
+}

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

@@ -0,0 +1,103 @@
+/** A condition of the canonical JSON, tagged by `op`. */
+export type Where = {
+    readonly op: string;
+} & {
+    readonly [field: string]: unknown;
+};
+/** What a condition or an order key is written on: one handle, by identity. */
+export interface Scope {
+    readonly label: string;
+}
+export declare function scope(label: string): Scope;
+/** Where an order key reads: the item, a relation's Edge, or an Edge root's end. */
+export type KeyTarget = 'item' | 'edge' | 'source' | 'target';
+/** The context a handle writes in: its scope, how its conditions wrap, and its keys' target. */
+export interface Context {
+    readonly scope: Scope;
+    readonly on: KeyTarget;
+    readonly wrap?: (where: Where) => Where;
+}
+/** One conjunct of a condition, on one scope. */
+export interface Conjunct {
+    readonly scope: Scope;
+    readonly where: Where;
+}
+/** A condition: its conjuncts, or `null` for NEVER. No conjunct at all is ALWAYS. */
+export declare class Condition {
+    readonly conjuncts: readonly Conjunct[] | null;
+    /** The Class keys a single-argument `is` or `isExactly` narrows to (S3). */
+    readonly narrows?: readonly string[] | undefined;
+    /** Its conjuncts as written: `conjuncts`, unless the input folds it. */
+    readonly written: readonly Conjunct[] | null;
+    readonly '~cond' = true;
+    constructor(conjuncts: readonly Conjunct[] | null, 
+    /** The Class keys a single-argument `is` or `isExactly` narrows to (S3). */
+    narrows?: readonly string[] | undefined, 
+    /** Its conjuncts as written: `conjuncts`, unless the input folds it. */
+    written?: readonly Conjunct[] | null);
+    static readonly ALWAYS: Condition;
+    static readonly NEVER: Condition;
+    get never(): boolean;
+    get always(): boolean;
+    /** The input folds it: as written, it is `asWritten`. */
+    get folded(): boolean;
+    get asWritten(): Condition;
+    and(...conditions: readonly unknown[]): Condition;
+    or(...conditions: readonly unknown[]): Condition;
+    not(): Condition;
+}
+/** A condition the input folds to `to`, which is `written` as written. */
+export declare function foldedTo(to: Condition, written: Condition): Condition;
+/** What `build` makes of some conditions, and as written, what it makes of them as written. */
+export declare function folding(conditions: readonly Condition[], build: (conditions: readonly Condition[]) => Condition): Condition;
+/** One condition from several conjuncts: NEVER if any is. */
+export declare function and(conditions: readonly Condition[]): Condition;
+/** The canonical condition of some conjuncts: one, or their `and`. */
+export declare function whereOf(conjuncts: readonly Conjunct[]): Where;
+/**
+ * The conditions a `where` callback returned: a condition, a falsy entry it skips (S6), or a list
+ * of those.
+ */
+export declare function kept(conditions: unknown, where?: string): Condition[];
+/** Conditions on a scope: their conjuncts must be written on one of `scopes`. */
+export declare function within(conditions: readonly Condition[], scopes: readonly Scope[]): void;
+export declare function describe(value: unknown): string;
+/** A condition on a handle's scope, wrapped as its context says. */
+export declare function atom(context: Context, where: Where): Condition;
+/** An order key; where it reads is written when its read is lowered. */
+export declare class OrderKey {
+    readonly scope: Scope;
+    readonly property: string;
+    readonly direction: 'asc' | 'desc';
+    readonly missing: 'first' | 'last';
+    readonly target: KeyTarget;
+    readonly '~key' = true;
+    constructor(scope: Scope, property: string, direction: 'asc' | 'desc', missing: 'first' | 'last', target: KeyTarget);
+}
+/** The order keys an `orderBy` callback returned, each on one of `scopes`. */
+export declare function orderKeys(ordering: unknown, scopes: readonly Scope[]): OrderKey[];
+/** A value in its spelling: a scalar as itself, an object or an array as `{literal}` (R1). */
+export declare function spell(value: unknown): unknown;
+/**
+ * The handle of a Property: one key, or several on a union whose Classes each declare the name
+ * (a condition matches any of them; an order key needs one, F7).
+ */
+export declare function propertyHandle(keys: readonly string[], context: Context): object;
+/** A Core node handle (`d.core.<node>`): its key, and the path it lowers to (F10). */
+export declare class CoreNode {
+    readonly path: string;
+    readonly '~core': string;
+    constructor(key: string, path: string);
+}
+/**
+ * Whether text is written as a NodePath: it starts with `/` (a Domain anchor) or `@` (a Node's id
+ * as its anchor). A NodeId holds neither, so the two never meet.
+ */
+export declare function isPathText(value: unknown): value is string;
+/**
+ * The condition a list of targets gives: ids by `id`, an `@<id>` path by its id, so a long list
+ * splits as ids do; any other path, and a Core node, by `path`.
+ */
+export declare function targetCondition(context: Context, targets: readonly unknown[]): Condition;
+/** A target as an error names it: its id or its path. */
+export declare function targetLabel(target: unknown): string;

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

@@ -0,0 +1,282 @@
+export function scope(label) {
+    return Object.freeze({ label });
+}
+/** A condition: its conjuncts, or `null` for NEVER. No conjunct at all is ALWAYS. */
+export class Condition {
+    conjuncts;
+    narrows;
+    written;
+    '~cond' = true;
+    constructor(conjuncts, 
+    /** The Class keys a single-argument `is` or `isExactly` narrows to (S3). */
+    narrows, 
+    /** Its conjuncts as written: `conjuncts`, unless the input folds it. */
+    written = conjuncts) {
+        this.conjuncts = conjuncts;
+        this.narrows = narrows;
+        this.written = written;
+    }
+    static ALWAYS = new Condition([]);
+    static NEVER = new Condition(null);
+    get never() {
+        return this.conjuncts === null;
+    }
+    get always() {
+        return this.conjuncts !== null && this.conjuncts.length === 0;
+    }
+    /** The input folds it: as written, it is `asWritten`. */
+    get folded() {
+        return this.written !== this.conjuncts;
+    }
+    get asWritten() {
+        return this.folded ? new Condition(this.written, this.narrows) : this;
+    }
+    and(...conditions) {
+        return and([this, ...kept(conditions, 'and')]);
+    }
+    or(...conditions) {
+        return or([this, ...kept(conditions, 'or')]);
+    }
+    not() {
+        return folding([this], ([c]) => {
+            if (c.conjuncts === null)
+                return Condition.ALWAYS;
+            if (c.conjuncts.length === 0)
+                return Condition.NEVER;
+            const scope = only(c, 'a `not`');
+            return new Condition([{ scope, where: negated(whereOf(c.conjuncts)) }]);
+        });
+    }
+}
+/** A condition the input folds to `to`, which is `written` as written. */
+export function foldedTo(to, written) {
+    return new Condition(to.conjuncts, written.narrows, written.written);
+}
+/** What `build` makes of some conditions, and as written, what it makes of them as written. */
+export function folding(conditions, build) {
+    const made = build(conditions);
+    if (!conditions.some((c) => c.folded))
+        return made;
+    return foldedTo(made, build(conditions.map((c) => c.asWritten)));
+}
+/** One condition from several conjuncts: NEVER if any is. */
+export function and(conditions) {
+    return folding(conditions, (operands) => {
+        const conjuncts = [];
+        for (const c of operands) {
+            if (c.conjuncts === null)
+                return Condition.NEVER;
+            conjuncts.push(...c.conjuncts);
+        }
+        return conjuncts.length === 0 ? Condition.ALWAYS : new Condition(conjuncts);
+    });
+}
+function or(conditions) {
+    return folding(conditions, (all) => {
+        const operands = all.filter((c) => !c.never);
+        if (operands.length === 0)
+            return Condition.NEVER;
+        if (operands.some((c) => c.always))
+            return Condition.ALWAYS;
+        if (operands.length === 1)
+            return operands[0];
+        const scopes = new Set(operands.map((c) => only(c, 'an `or`')));
+        if (scopes.size > 1)
+            throw new TypeError('An `or` across the node and its Edge is not in Query v7: write one `or` per side.');
+        const [scope] = scopes;
+        return new Condition([
+            { scope: scope, where: { op: 'or', operands: operands.map((c) => whereOf(c.conjuncts)) } },
+        ]);
+    });
+}
+/** The one scope of a condition that is neither NEVER nor ALWAYS. */
+function only(c, what) {
+    const scopes = new Set(c.conjuncts.map((x) => x.scope));
+    if (scopes.size > 1)
+        throw new TypeError(`${what} across the node and its Edge is not in Query v7: write it per side.`);
+    return c.conjuncts[0].scope;
+}
+/** The canonical condition of some conjuncts: one, or their `and`. */
+export function whereOf(conjuncts) {
+    return conjuncts.length === 1
+        ? conjuncts[0].where
+        : { op: 'and', operands: conjuncts.map((c) => c.where) };
+}
+/** `not`, folding a double negation and a presence. */
+function negated(where) {
+    if (where.op === 'not')
+        return where.operand;
+    if (where.op === 'present')
+        return { ...where, present: !where.present };
+    return { op: 'not', operand: where };
+}
+const isFalsy = (value) => !value;
+/**
+ * The conditions a `where` callback returned: a condition, a falsy entry it skips (S6), or a list
+ * of those.
+ */
+export function kept(conditions, where = 'where') {
+    const list = Array.isArray(conditions) ? conditions.flat() : [conditions];
+    const out = [];
+    for (const entry of list) {
+        if (entry instanceof Condition)
+            out.push(entry);
+        else if (!isFalsy(entry))
+            throw new TypeError(`${where} takes conditions, falsy entries it skips, or a list of them; got ${describe(entry)}.`);
+    }
+    return out;
+}
+/** Conditions on a scope: their conjuncts must be written on one of `scopes`. */
+export function within(conditions, scopes) {
+    for (const c of conditions)
+        for (const x of c.written ?? [])
+            if (!scopes.includes(x.scope))
+                throw new TypeError(`A condition on ${x.scope.label} is not in Query v7 here: a condition reads only the handles its callback receives.`);
+}
+export function describe(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value);
+    if (typeof value === 'object' && value !== null)
+        return value.constructor?.name ?? 'an object';
+    return String(value);
+}
+/** A condition on a handle's scope, wrapped as its context says. */
+export function atom(context, where) {
+    return new Condition([
+        { scope: context.scope, where: context.wrap ? context.wrap(where) : where },
+    ]);
+}
+// ─── Order keys ────────────────────────────────────────────────────────────────────────────────
+/** An order key; where it reads is written when its read is lowered. */
+export class OrderKey {
+    scope;
+    property;
+    direction;
+    missing;
+    target;
+    '~key' = true;
+    constructor(scope, property, direction, missing, target) {
+        this.scope = scope;
+        this.property = property;
+        this.direction = direction;
+        this.missing = missing;
+        this.target = target;
+    }
+}
+/** The order keys an `orderBy` callback returned, each on one of `scopes`. */
+export function orderKeys(ordering, scopes) {
+    const list = Array.isArray(ordering) ? ordering : [ordering];
+    return list.map((key) => {
+        if (!(key instanceof OrderKey))
+            throw new TypeError(`orderBy takes order keys from asc() and desc(); got ${describe(key)}.`);
+        if (!scopes.includes(key.scope))
+            throw new TypeError(`An order key on ${key.scope.label} is not in Query v7 here: a read orders only by the handles its callback receives.`);
+        return key;
+    });
+}
+// ─── Values and Properties ─────────────────────────────────────────────────────────────────────
+/** A value in its spelling: a scalar as itself, an object or an array as `{literal}` (R1). */
+export function spell(value) {
+    return value !== null && typeof value === 'object' ? { literal: value } : value;
+}
+/**
+ * The handle of a Property: one key, or several on a union whose Classes each declare the name
+ * (a condition matches any of them; an order key needs one, F7).
+ */
+export function propertyHandle(keys, context) {
+    // A union's name matches if any of its keys does, and is missing only if every key is.
+    const condition = (build, op = 'or') => {
+        const atoms = keys.map(build);
+        return atom(context, atoms.length === 1 ? atoms[0] : { op, operands: atoms });
+    };
+    const range = (bounds) => {
+        for (const bound of Object.values(bounds))
+            if (typeof bound !== 'string' && typeof bound !== 'number')
+                throw new TypeError(`A range bound is text or a number; got ${describe(bound)}.`);
+        return condition((property) => ({ op: 'range', property, ...bounds }));
+    };
+    const key = (direction, options) => {
+        if (keys.length !== 1)
+            throw new TypeError('This name is a different Property on each Class of this union: order by a Property of one Class.');
+        return new OrderKey(context.scope, keys[0], direction, options?.missing ?? 'last', context.on);
+    };
+    return Object.freeze({
+        eq: (value) => condition((property) => ({ op: 'eq', property, value: spell(value) })),
+        in: (values) => {
+            if (!Array.isArray(values))
+                throw new TypeError(`in takes a list of values; got ${describe(values)}.`);
+            if (values.length === 0)
+                return foldedTo(Condition.NEVER, condition((property) => ({ op: 'in', property, values: [] })));
+            // The Kernel matches a Boolean by eq alone: `in` over booleans is one eq per value.
+            if (values.every((value) => typeof value === 'boolean' || value === null))
+                return or([...new Set(values)].map((value) => condition((property) => ({ op: 'eq', property, value }))));
+            return condition((property) => ({ op: 'in', property, values: values.map(spell) }));
+        },
+        gt: (value) => range({ gt: value }),
+        gte: (value) => range({ gte: value }),
+        lt: (value) => range({ lt: value }),
+        lte: (value) => range({ lte: value }),
+        between: (lower, upper) => range({ gte: lower, lt: upper }),
+        startsWith: (prefix) => {
+            if (typeof prefix !== 'string')
+                throw new TypeError(`startsWith takes text; got ${describe(prefix)}.`);
+            return condition((property) => ({ op: 'startsWith', property, prefix }));
+        },
+        isSet: () => condition((property) => ({ op: 'present', property, present: true })),
+        isMissing: () => condition((property) => ({ op: 'present', property, present: false }), 'and'),
+        asc: (options) => key('asc', options),
+        desc: (options) => key('desc', options),
+    });
+}
+// ─── Targets ───────────────────────────────────────────────────────────────────────────────────
+/** A Core node handle (`d.core.<node>`): its key, and the path it lowers to (F10). */
+export class CoreNode {
+    path;
+    '~core';
+    constructor(key, path) {
+        this.path = path;
+        this['~core'] = key;
+        Object.freeze(this);
+    }
+}
+/**
+ * Whether text is written as a NodePath: it starts with `/` (a Domain anchor) or `@` (a Node's id
+ * as its anchor). A NodeId holds neither, so the two never meet.
+ */
+export function isPathText(value) {
+    return typeof value === 'string' && (value.startsWith('/') || value.startsWith('@'));
+}
+/** A NodePath that is a Node's id and no step: `@<id>`, a NodeId being 1 to 255 of `A-Za-z0-9._-`. */
+const ID_PATH = /^@([A-Za-z0-9._-]{1,255})$/;
+/**
+ * The condition a list of targets gives: ids by `id`, an `@<id>` path by its id, so a long list
+ * splits as ids do; any other path, and a Core node, by `path`.
+ */
+export function targetCondition(context, targets) {
+    if (targets.length === 0)
+        return foldedTo(Condition.NEVER, atom(context, { op: 'id', ids: [] }));
+    const ids = [];
+    const paths = [];
+    for (const target of targets) {
+        if (target instanceof CoreNode)
+            paths.push(target.path);
+        else if (isPathText(target)) {
+            const id = ID_PATH.exec(target)?.[1];
+            if (id === undefined)
+                paths.push(target);
+            else
+                ids.push(id);
+        }
+        else if (typeof target === 'string' && target.length > 0)
+            ids.push(target);
+        else
+            throw new TypeError(`A target is a NodeId, a NodePath or a Core node; got ${describe(target)}.`);
+    }
+    const id = ids.length > 0 ? { op: 'id', ids } : undefined;
+    const path = paths.length > 0 ? { op: 'path', paths } : undefined;
+    return atom(context, id && path ? { op: 'or', operands: [id, path] } : (id ?? path));
+}
+/** A target as an error names it: its id or its path. */
+export function targetLabel(target) {
+    return target instanceof CoreNode ? target.path : String(target);
+}

package/dist/application/query/index.d.ts

@@ -1,10 +1,13 @@
-export { defineCollectionQuery, defineCompositeQuery, defineQuery, realizeQuery } from './define.js';
-export type { CollectionQuerySpec } from './collection/metadata.js';
+export { defineCompositeQuery, realizeQuery } from './define.js';
 export { executeQuery, type QueryClient, type QueryExecutor } from './execution/index.js';
 export { QueryPaginationError, QueryValueMismatchError, type QueryFailure, type QueryPaginationErrorCode, } from './failure.js';
-export type { CollectionQueryDefinition, CollectionValue, CompositeQueryDefinition, QueryAstOf, QueryDefinition, QueryInputOf, QueryOutputOf, SingleQueryDefinition, } from './query.js';
-export { queryResult } from './single/index.js';
-export type { CompleteQueryProjectionContext, PaginatedQuery, ProjectedQuery, QueryPages, QueryPagination, QueryProjectionContext, RawQuery, SingleQuery, } from './single/index.js';
+export type { CompositeQueryDefinition, QueryDefinition, QueryInputOf, QueryOutputOf, QueryPagination, } from './query.js';
 export type { CompositeQuery, ProjectedCompositeQuery, QueryComposition, QueryPlan, QueryPlanInput, QueryPlanOutput, QueryPlanValue, RawCompositeQuery, } from './composite/index.js';
-/** Canonical Query language and authoring values accept DSL ResolvedClass directly. */
-export * from '@astrale-os/kernel-core/graph/query';
+export { defineQuery } from './recipe/define.js';
+export { edgeKey, type Count, type EdgeKey, type EdgeRow, type Page, type Ref, type Row, } from './handles/rows.js';
+export type { Handles } from './handles/handles.js';
+export type { InputOf, OutputOf, Recipe } from './recipe/recipe.js';
+export { isQueryError, QueryError, type QueryErrorCode, type QueryErrorDetails, } from './execution/error.js';
+export { runQueryRecipe, type RecipeCallOptions, type RecipeClient, type RecipeOptions, type RecipeQueryOptions, } from './execution/recipe.js';
+export { defineCollectionQuery, queryResult, type CollectionQueryDefinition, type CollectionQuerySpec, type CollectionValue, type CompleteQueryProjectionContext, type PaginatedQuery, type ProjectedQuery, type QueryAstOf, type QueryPages, type QueryProjectionContext, type RawQuery, type SingleQuery, type SingleQueryDefinition, } from './legacy/v6/index.js';
+export * from './legacy/v6/kernel.js';

package/dist/application/query/index.js

@@ -1,6 +1,11 @@
-export { defineCollectionQuery, defineCompositeQuery, defineQuery, realizeQuery } from './define.js';
+export { defineCompositeQuery, realizeQuery } from './define.js';
 export { executeQuery } from './execution/index.js';
 export { QueryPaginationError, QueryValueMismatchError, } from './failure.js';
-export { queryResult } from './single/index.js';
-/** Canonical Query language and authoring values accept DSL ResolvedClass directly. */
-export * from '@astrale-os/kernel-core/graph/query';
+// Query v7: recipes. `defineQuery` defines a recipe from a string id, and a V6 Query from a function.
+export { defineQuery } from './recipe/define.js';
+export { edgeKey, } from './handles/rows.js';
+export { isQueryError, QueryError, } from './execution/error.js';
+export { runQueryRecipe, } from './execution/recipe.js';
+// Query V6.
+export { defineCollectionQuery, queryResult, } from './legacy/v6/index.js';
+export * from './legacy/v6/kernel.js';

package/dist/application/query/language/index.d.ts

@@ -0,0 +1,2 @@
+/** The Query v7 language: the static type of a Query's canonical JSON, over one Domain. */
+export { QUERY, type AnyQuery, type Query, type QueryBounds, type QueryBranch, type QueryClassKey, type QueryCondition, type QueryDomainOf, type QueryEdgeClassKey, type QueryNodeClassKey, type QueryOperatorOf, type QueryOrderKey, type QueryPropertyKey, type QueryPropertyValue, type QueryPropertyValues, type QueryRange, type QueryRendering, type QueryRoot, type QueryTraversal, type Refused, type SizedList, type SizedQuery, type TraversalDirection, type UnsizedList, } from './query.js';

package/dist/application/query/language/index.js

@@ -0,0 +1,2 @@
+/** The Query v7 language: the static type of a Query's canonical JSON, over one Domain. */
+export { QUERY, } from './query.js';