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

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

@@ -0,0 +1,157 @@
+/**
+ * The Domain a recipe reads, indexed once per Schema (spike designs D1, D3 and D10).
+ *
+ * Every generic is keyed by the Schema type `S` and Class keys, never by resolved Classes:
+ * instantiations are cached per (Schema, key), and messages print the key. The Domain is indexed
+ * once (`Index<S>`, key → resolved Class), and every other lookup is an indexed access into it.
+ */
+import type { schema } from '../../../platform/schema/index.js';
+import type { KernelDomain } from '../../../platform/schema/kernel.js';
+import type { SDK_KEYS } from './model.js';
+export type Values<R> = R[keyof R];
+/**
+ * A Class a degraded Schema types as `any` (D10). `unknown extends T` holds only for `any` (and
+ * `unknown`), and fails at once on a resolved Class; `0 extends 1 & T` would reduce an
+ * intersection with each one, walking its whole type.
+ */
+export type Untyped<T> = unknown extends T ? true : false;
+/** The key of the graph's root Class, which every Node Class satisfies. */
+export type NodeRoot = 'kernel.astrale.ai:class.Node';
+/** The resolved Domain of a Schema. */
+export type Dom<S> = S extends schema.DomainSchema ? schema.DomainOf<S> : never;
+/** A namespace of Classes, without the Classes a degraded Schema types as `any` (D10). */
+type Typed<R> = {
+    readonly [N in keyof R as Untyped<R[N]> extends true ? never : N]: R[N];
+};
+type ClassesOf<D> = D extends {
+    readonly classes: infer Own;
+    readonly dependencies: infer Deps;
+} ? Values<Typed<Own>> | Values<{
+    [A in keyof Deps]: Deps[A] extends {
+        readonly classes: infer C;
+    } ? Values<Typed<C>> : never;
+}> : never;
+export type KeyOf<C> = C extends {
+    readonly key: infer K extends string;
+} ? K : never;
+/**
+ * Every Class a read names, by key: the Domain's own, its direct dependencies' and the Kernel's.
+ */
+export type Index<S> = {
+    readonly [C in ClassesOf<Dom<S>> | Values<KernelDomain['classes']> as KeyOf<C>]: C;
+};
+/** One Class of the index, by key (through `infer`: tsc does not index a remapped type by its keys). */
+export type Cls<S, K> = Index<S> extends infer I ? I[K & keyof I] : never;
+/** The key of every Node Class a read names. */
+export type NodeClassKey<S> = KeyOf<Exclude<Values<Index<S>>, {
+    readonly kind: 'edge';
+}>>;
+/** The Domain's origin, as the Schema declares it: its resolved Domain types it as `string`. */
+export type OriginOf<S> = S extends {
+    readonly origin: infer O extends string;
+} ? O : never;
+/** Every Edge Class of the index, as resolved Classes. */
+export type EdgesOf<S> = Extract<Values<Index<S>>, {
+    readonly kind: 'edge';
+}>;
+/** The keys a Class satisfies: its own and its parents', transitively. */
+type SatKeys<C, Depth extends readonly 0[] = []> = Depth['length'] extends 8 ? never : C extends {
+    readonly key: infer K extends string;
+    readonly extends: infer P extends readonly unknown[];
+} ? `${string}:class.${string}` extends K ? never : K | SatKeys<P[number], [...Depth, 0]> : never;
+/** The keys a Class satisfies, and the graph root for a Node Class. */
+type SatisfiedBy<C> = SatKeys<C> | (C extends {
+    readonly kind: 'edge';
+} ? never : NodeRoot);
+export type Satisfies<S, K> = K extends unknown ? SatisfiedBy<Cls<S, K>> : never;
+interface Sub<At extends string, K extends string> {
+    readonly at: At;
+    readonly sub: K;
+}
+/** One entry per parent link: a Class under each key it satisfies, its own and the root apart. */
+type SubEntries<S> = Values<Index<S>> extends infer C ? C extends unknown ? Exclude<SatKeys<C>, KeyOf<C>> extends infer At ? At extends string ? Sub<At, KeyOf<C>> : never : never : never : never;
+/** The proper subclasses of each Class that has one: computed once per Schema (D3). */
+type SubclassesByClass<S> = {
+    readonly [E in SubEntries<S> as E['at']]: E['sub'];
+};
+/**
+ * A Class key, or the key of any subclass the Domain can name (D6). The graph root's are every
+ * Node Class: only parent links are grouped, so a Schema without inheritance groups nothing.
+ */
+export type ClassOf<S, K> = K extends NodeRoot ? NodeClassKey<S> : K | SubclassesByClass<S>[K & keyof SubclassesByClass<S>];
+type ByKeyOf<C> = C extends {
+    readonly properties: {
+        readonly byKey: infer B;
+    };
+} ? B : never;
+/** The Property entries of a Class, own and inherited. */
+export type EntriesOf<C> = ByKeyOf<C> extends infer B ? B[keyof B] : never;
+export type NameOfEntry<P> = P extends {
+    readonly name: infer N extends string;
+} ? N : never;
+export type ValueOfEntry<P> = P extends {
+    readonly __value?: infer V;
+} ? Exclude<V, undefined> : never;
+export type RequiredEntry<P> = P extends {
+    readonly definition: {
+        readonly required: true;
+    };
+} ? true : false;
+type KeyOfEntry<P> = P extends {
+    readonly key: infer K extends string;
+} ? K : never;
+/** The name of the Class that declares a Property, from its key (distributive: no entry, no owner). */
+type OwnerOfEntry<P> = P extends {
+    readonly key: `${string}:class.${infer O}.property.${string}`;
+} ? O : never;
+/** A name two members claim names neither: members a key-remapped type sends to one name reach its template as one union. */
+export type Single<C, All = C> = C extends unknown ? [Exclude<All, C>] extends [never] ? true : false : never;
+/** The Property entries of a Class by name: a name several entries claim maps to their union. */
+type ByName<C> = {
+    readonly [P in EntriesOf<C> as NameOfEntry<P>]: P;
+};
+/** The entry a name keeps on the Class: the only one, or the Class's own among inherited duplicates. */
+type FlatEntry<C, Es> = Single<Es> extends true ? Es : Extract<Es, {
+    readonly key: `${KeyOf<C>}.property.${string}`;
+}> extends infer Own ? [Own] extends [never] ? never : Single<Own> extends true ? Own : never : never;
+/**
+ * Where each Property of a Class goes on a row or a handle (F6): under its name; under `$prop` when
+ * the name is taken (`Taken`: the row keys, the handle's members or the Edge's roles); under `$`
+ * and its owner's name in lower camel case when it is an inherited duplicate its name does not
+ * keep, and under `$$` and that name when `$` and it is one of the SDK's keys.
+ */
+export interface Layout<Flat, Groups> {
+    readonly flat: Flat;
+    readonly groups: Groups;
+}
+type FlatOf<C, Taken> = ByName<C> extends infer Names ? {
+    readonly [N in keyof Names as N extends Taken ? never : [FlatEntry<C, Names[N]>] extends [never] ? never : N]: FlatEntry<C, Names[N]>;
+} : never;
+/** The entries the taken names keep: they go under `$prop`. */
+type TakenOf<C, Taken> = ByName<C> extends infer Names ? {
+    readonly [N in keyof Names & Taken as [FlatEntry<C, Names[N]>] extends [never] ? never : N]: FlatEntry<C, Names[N]>;
+} : never;
+/** The inherited duplicates a name does not keep (`FlatEntry`). */
+type Duplicates<C> = EntriesOf<C> extends infer P ? P extends unknown ? KeyOfEntry<P> extends KeyOfEntry<FlatEntry<C, ByName<C>[NameOfEntry<P> & keyof ByName<C>]>> ? never : P : never : never;
+/**
+ * The keys the SDK writes on rows besides `id`, all named with `$`: `SDK_KEYS`, the one list. Frozen;
+ * an owner group named as one of them is escaped with one more `$`.
+ */
+export type SdkKeys = (typeof SDK_KEYS)[number];
+/** The group of an owner's duplicates; an owner named `Class` groups under `$$class`. */
+type OwnerGroup<O> = O extends string ? `$${Uncapitalize<O>}` extends SdkKeys ? `$$${Uncapitalize<O>}` : `$${Uncapitalize<O>}` : never;
+/**
+ * The owner groups, and `$prop` when the taken names `T` keep any entry. Written inline: an alias
+ * for the `$prop` part costs about 8% more instantiations on the type budget's fixtures.
+ */
+type GroupsOf<C, T> = {
+    readonly [P in Duplicates<C> as OwnerGroup<OwnerOfEntry<P>>]: {
+        readonly [Q in P as NameOfEntry<Q>]: Q;
+    };
+} & {
+    readonly [G in '$prop' as [keyof TakenOf<C, T>] extends [never] ? never : G]: TakenOf<C, T>;
+};
+export type LayoutOf<C, Taken> = Layout<FlatOf<C, Taken>, GroupsOf<C, Taken>>;
+/** Every Property name of a Class, flat or grouped: a relation or a `.with` name avoids them. */
+export type PropNamesOf<C> = keyof ByName<C>;
+export {};

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

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

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

@@ -0,0 +1,268 @@
+/**
+ * Typed handles over a Domain (spec § Recipes: the read layer): what a recipe's `build` receives,
+ * and the reads it returns. Handles are interfaces with lazy members; the per-Class parts
+ * (Properties, named relations, rows) are mapped types computed once per Class key (D5).
+ */
+import type { NodeId } from '../../../platform/graph/node/index.js';
+import type { NodePath } from '../../../platform/graph/path/index.js';
+import type { KernelDomain } from '../../../platform/schema/kernel.js';
+import type { SizedQuery } from '../language/query.js';
+import type { Cond, Conditions, HandleMembers, IsCond, Ordering, PropOf, PropsOf, Unordered } from './conditions.js';
+import type { Cls, Dom, KeyOf, LayoutOf, OriginOf, PropNamesOf, Satisfies, Single, Untyped, ValueOfEntry } from './domain.js';
+import type { Far, RelationsOf, SourceKeys, SourceRole, TargetKeys, TargetRole, ViaCheck, ViaOptions } from './relations.js';
+import type { Count, EdgeRootRef, EdgeRootRow, EdgeValues, Page, Ref, Row, RowKeys, WithheldEdgeRow, WithheldRow } from './rows.js';
+/** A read: what a verb returns, an opaque description the recipe runs, typed by its answer `T`. */
+export interface Read<out T> {
+    readonly '~read': T;
+}
+/** A read of a relation, per parent row: what a `.with` takes. */
+export interface RelationRead<out T> extends Read<T> {
+    readonly '~relation': true;
+}
+/** One page of a root: only as a recipe's single read (D22). */
+export interface PageRead<out T> {
+    readonly '~page': T;
+}
+/** What a read answers: a page read answers one `Page`. */
+export type ResultOf<R> = R extends Read<infer T> ? T : R extends PageRead<infer T> ? Page<T> : never;
+/** Rows render values, or references (`.pick()`). */
+export type Rendering = 'value' | 'reference';
+/** The answers a `.with` adds to each row, by the names the author picks. */
+type Withs = {
+    readonly [name: string]: Read<unknown>;
+};
+type Answers<X> = {
+    readonly [P in keyof X]: ResultOf<X[P]>;
+};
+/**
+ * A `.with` name a row already carries, or a `.with` that reads another root, fails to compile
+ * at that name.
+ */
+type WithCheck<S, K, W, X> = {
+    readonly [P in keyof X as P extends PropNamesOf<Cls<S, K>> | RowKeys | keyof W | `$${string}` ? P : X[P] extends RelationRead<unknown> ? never : P]: P extends PropNamesOf<Cls<S, K>> | RowKeys | keyof W | `$${string}` ? `✗ "${P & string}" is already a row key of this Class: give the .with another name` : `✗ "${P & string}" reads another root: read it as a facet of the recipe`;
+};
+type RowOf<S, K, W, M extends Rendering, H extends boolean> = ((M extends 'reference' ? Ref<S, K> : Row<S, K>) & W) | (H extends true ? WithheldRow<S, K> : never);
+/** The id of a Node, its path, or a Core node of the Domain. */
+export type Target = NodeId | NodePath | CoreNode<string>;
+/** A Core node of the Domain (`d.core.<node>`). */
+export interface CoreNode<Key extends string> {
+    readonly '~core': Key;
+}
+interface IdProp {
+    eq(id: Target): Cond;
+    /** Any length. */
+    in(ids: readonly Target[]): Cond;
+}
+interface PathProp {
+    eq(path: NodePath): Cond;
+    in(paths: readonly NodePath[]): Cond;
+}
+/** A Class handle, matched by its phantom key alone. */
+interface ClassHandle<K extends string> {
+    readonly '~class': K;
+}
+type IsCheck<S, K, X> = X extends unknown ? [Extract<Satisfies<S, X> | X, K>] extends [never] ? `✗ ${X & string} is not ${K & string} nor one of its subclasses: narrow to a subclass, or read both with .union` : unknown : never;
+/** An Edge Class handle, matched by its phantom key alone. */
+type AnyEdgeSet = {
+    readonly '~edge': string;
+};
+type EdgeKeyOf<X> = X extends {
+    readonly '~edge': infer E extends string;
+} ? E : never;
+type EdgeKeysOf<X> = X extends readonly (infer One)[] ? EdgeKeyOf<One> : EdgeKeyOf<X>;
+/** What every Node handle offers besides its Properties and named relations. */
+export interface NodeMethods<S, K extends string> {
+    readonly id: IdProp;
+    readonly path: PathProp;
+    /** The Node is a `cls`, or one of its subclasses: narrows the handle and the rows. */
+    is<X extends string>(cls: ClassHandle<X> & IsCheck<S, K, X>): IsCond<X>;
+    /** The Node is a `cls` and meets `conditions`, written on a handle narrowed to `cls`. */
+    is<X extends string>(cls: ClassHandle<X> & IsCheck<S, K, X>, conditions: (node: NodeHandle<S, X>) => Conditions): Cond;
+    isExactly<X extends string>(cls: ClassHandle<X> & IsCheck<S, K, X>): IsCond<X>;
+    /** The Edges of one Class (or several) from this Node; the far end's Classes come from the Edge. */
+    via<const X extends AnyEdgeSet | readonly [AnyEdgeSet, ...AnyEdgeSet[]], const O extends ViaOptions = {}>(edge: X & ViaCheck<S, K, EdgeKeysOf<X>, O>, options?: O): RelSet<S, Far<S, K, EdgeKeysOf<X>, O>, EdgeKeysOf<X>, {}, 'value', false>;
+}
+type IsUnion<K, All = K> = K extends unknown ? ([All] extends [K] ? false : true) : never;
+type FlatOf<S, K> = LayoutOf<Cls<S, K>, HandleMembers>['flat'];
+type EntryNamed<S, K, N> = K extends unknown ? FlatOf<S, K>[N & keyof FlatOf<S, K>] : never;
+type KeyOfEntry<P> = P extends {
+    readonly key: infer Key extends string;
+} ? Key : never;
+/**
+ * The Properties a union's Classes share, by name. A name that maps to several Property keys
+ * filters but does not order (F7).
+ */
+type UnionProps<S, K> = {
+    readonly [N in keyof (K extends unknown ? FlatOf<S, K> : never)]: Single<KeyOfEntry<EntryNamed<S, K, N>>> extends true ? PropOf<ValueOfEntry<EntryNamed<S, K, N>>> : Unordered<PropOf<ValueOfEntry<EntryNamed<S, K, N>>>, `✗ "${N & string}" is a different Property on each Class of this union: order by a Property of one Class`>;
+};
+/** A Node handle in a callback: Properties, named to-one relations, and the methods above. */
+export type NodeHandle<S, K extends string> = (true extends IsUnion<K> ? UnionProps<S, K> & (K extends unknown ? RelationsOf<S, K> : never) : PropsOf<Cls<S, K>> & RelationsOf<S, K>) & NodeMethods<S, K>;
+/** An Edge handle in a `(node, edge) =>` callback: its Properties. */
+export type EdgeHandle<S, E extends string> = E extends unknown ? PropsOf<Cls<S, E>, never> : never;
+/** The Classes of the `is` conditions among `C`. */
+type IsOf<C> = C extends IsCond<infer X> ? X : never;
+/** Those of an entry that is always an `is`: a falsy value `where` skips may replace any other. */
+type SureOf<C> = [C] extends [IsCond<string>] ? IsOf<C> : never;
+/** A list narrows to its `is` Classes, and keeps `K` too if a skipped entry may leave none. */
+type Narrowed<K, Any, Sure> = [Any] extends [never] ? K : [Sure] extends [never] ? K | Any : Any;
+/** The Classes a `where` narrows to (S3), for each list it may return. */
+type Narrow<K, R> = R extends readonly unknown[] ? Narrowed<K, IsOf<R[number]>, {
+    readonly [I in keyof R]: SureOf<R[I]>;
+}[number]> : Narrowed<K, IsOf<R>, SureOf<R>>;
+/** The Nodes of a Class (or a union of Classes) at the root of a read. */
+export interface NodeSet<S, K extends string, W, M extends Rendering, H extends boolean> {
+    readonly '~class': K;
+    where<const R extends Conditions>(conditions: (node: NodeHandle<S, K>) => R): NodeSet<S, Narrow<K, R>, W, M, H>;
+    orderBy(keys: (node: NodeHandle<S, K>) => Ordering): NodeSet<S, K, W, M, H>;
+    /** Rows gain each relation's answer under the name given. */
+    with<const X extends Withs>(relations: (node: NodeHandle<S, K>) => X & WithCheck<S, K, W, X>): NodeSet<S, K, W & Answers<X>, M, H>;
+    /** Rows of references: `{ id, $class }`. */
+    pick(): NodeSet<S, K, W, 'reference', H>;
+    /** Rows the reader may not read stay, as `{ id, $class, $withheld }`. */
+    includeWithheld(): NodeSet<S, K, W, M, true>;
+    union<K2 extends string>(other: ClassHandle<K2>): NodeSet<S, K | K2, W, M, H>;
+    /**
+     * Exactly one; none is `NOT_FOUND`, a second is `INTEGRITY`, one the reader may not read
+     * `NOT_READABLE`.
+     */
+    get(id?: Target): Read<RowOf<S, K, W, M, false>>;
+    /** Zero or one; a second is `INTEGRITY`, one the reader may not read `NOT_READABLE`. */
+    find(id?: Target): Read<RowOf<S, K, W, M, false> | undefined>;
+    first(): Read<RowOf<S, K, W, M, H> | undefined>;
+    first(n: number): Read<readonly RowOf<S, K, W, M, H>[]>;
+    /** Reads n + 1 rows to say whether more exist. */
+    first(n: number, options: {
+        readonly more: true;
+    }): Read<{
+        readonly rows: readonly RowOf<S, K, W, M, H>[];
+        readonly more: boolean;
+    }>;
+    /** Only as a recipe's single read: the call sets the size, up to `max`, and continues it. */
+    page(options: {
+        readonly max: number;
+    }): PageRead<RowOf<S, K, W, M, H>>;
+    /** Every row; past `max`, `TOO_MANY`. */
+    all(options: {
+        readonly max: number;
+    }): Read<readonly RowOf<S, K, W, M, H>[]>;
+    exists(id?: Target): Read<boolean>;
+    count(options: {
+        readonly upTo: number;
+    }): Read<Count>;
+}
+/** A relation from a Node: the Nodes at the far end of its Edges. */
+export interface RelSet<S, K extends string, E extends string, W, M extends Rendering, H extends boolean> {
+    /** Its far Classes and Edges: a relation is not a Class handle, so `is` and `union` refuse it. */
+    readonly '~via': readonly [K, E];
+    where<const R extends Conditions>(conditions: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => R): RelSet<S, Narrow<K, R>, E, W, M, H>;
+    orderBy(keys: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Ordering): RelSet<S, K, E, W, M, H>;
+    with<const X extends Withs>(relations: (node: NodeHandle<S, K>) => X & WithCheck<S, K, W, X>): RelSet<S, K, E, W & Answers<X>, M, H>;
+    /** Each row gains `$edge`: the Edge's Class and Properties. */
+    withEdge(): RelSet<S, K, E, W & {
+        readonly $edge: EdgeValues<S, E>;
+    }, M, H>;
+    pick(): RelSet<S, K, E, W, 'reference', H>;
+    includeWithheld(): RelSet<S, K, E, W, M, true>;
+    distinct(): RelSet<S, K, E, W, M, H>;
+    /**
+     * Exactly one per parent; none or a second is `INTEGRITY`, naming the relation; one the reader
+     * may not read is `NOT_READABLE`.
+     */
+    get(): RelationRead<RowOf<S, K, W, M, false>>;
+    find(): RelationRead<RowOf<S, K, W, M, false> | undefined>;
+    first(): RelationRead<RowOf<S, K, W, M, H> | undefined>;
+    first(n: number): RelationRead<readonly RowOf<S, K, W, M, H>[]>;
+    all(options: {
+        readonly max: number;
+    }): RelationRead<readonly RowOf<S, K, W, M, H>[]>;
+    count(options: {
+        readonly upTo: number;
+    }): RelationRead<Count>;
+    /** A boolean per parent in a `.with`; a condition in a `where`. */
+    exists(): RelationRead<boolean> & Cond;
+    /** The relation reaches this Node. */
+    is(target: Target): Cond;
+    some(conditions?: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Conditions): Cond;
+    every(conditions: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Conditions): Cond;
+    none(conditions?: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Conditions): Cond;
+    atLeast(n: number, conditions?: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Conditions): Cond;
+    atMost(n: number, conditions?: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Conditions): Cond;
+    exactly(n: number, conditions?: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Conditions): Cond;
+}
+/** An Edge handle at the root: its Properties, and both ends by role. */
+export type EdgeRootHandle<S, E extends string> = E extends unknown ? PropsOf<Cls<S, E>, SourceRole<S, E> | TargetRole<S, E>> & {
+    readonly [R in SourceRole<S, E>]: NodeHandle<S, SourceKeys<S, E>>;
+} & {
+    readonly [R in TargetRole<S, E>]: NodeHandle<S, TargetKeys<S, E>>;
+} : never;
+type EdgeRowOf<S, E, M extends Rendering, H extends boolean> = (M extends 'reference' ? EdgeRootRef<S, E> : EdgeRootRow<S, E>) | (H extends true ? WithheldEdgeRow<S, E> : never);
+/** The Edges of a Class at the root of a read. */
+export interface EdgeSet<S, E extends string, M extends Rendering, H extends boolean> {
+    readonly '~edge': E;
+    where(conditions: (edge: EdgeRootHandle<S, E>) => Conditions): EdgeSet<S, E, M, H>;
+    orderBy(keys: (edge: EdgeRootHandle<S, E>) => Ordering): EdgeSet<S, E, M, H>;
+    /** Rows of `{ $class, $source, $target }`, with both ends as references. */
+    pick(): EdgeSet<S, E, 'reference', H>;
+    includeWithheld(): EdgeSet<S, E, M, true>;
+    get(): Read<EdgeRowOf<S, E, M, false>>;
+    find(): Read<EdgeRowOf<S, E, M, false> | undefined>;
+    first(): Read<EdgeRowOf<S, E, M, H> | undefined>;
+    first(n: number): Read<readonly EdgeRowOf<S, E, M, H>[]>;
+    page(options: {
+        readonly max: number;
+    }): PageRead<EdgeRowOf<S, E, M, H>>;
+    all(options: {
+        readonly max: number;
+    }): Read<readonly EdgeRowOf<S, E, M, H>[]>;
+    exists(): Read<boolean>;
+    count(options: {
+        readonly upTo: number;
+    }): Read<Count>;
+}
+type HandleOf<S, C> = C extends {
+    readonly kind: 'edge';
+    readonly key: infer K extends string;
+} ? EdgeSet<S, K, 'value', false> : C extends {
+    readonly key: infer K extends string;
+} ? NodeSet<S, K, {}, 'value', false> : never;
+/** The names `d` owns: a Class or an alias of the same name has no handle. */
+type Fixed = 'kernel' | 'core' | 'origin' | 'document';
+type ClassHandles<S, Classes> = {
+    readonly [N in keyof Classes as N extends Fixed ? never : Untyped<Classes[N]> extends true ? never : N]: HandleOf<S, Classes[N]>;
+};
+type CoreHandles<Core> = Core extends {
+    readonly nodes: infer Nodes;
+} ? {
+    readonly [N in keyof Nodes]: CoreNode<KeyOf<Nodes[N]>>;
+} : never;
+/** The escape hatch: one canonical document, its rows typed `unknown` (D23). */
+interface DocumentRead<S> {
+    document(query: Extract<SizedQuery<S>, {
+        readonly list: unknown;
+    }>): Read<readonly unknown[]>;
+    document(query: Extract<SizedQuery<S>, {
+        readonly exists: unknown;
+    }>): Read<boolean>;
+    document(query: Extract<SizedQuery<S>, {
+        readonly count: unknown;
+    }>): Read<Count>;
+}
+/**
+ * The handles a recipe's `build` receives (S1): the Domain's own Classes, each dependency under
+ * its alias, the Kernel's Classes under `d.kernel`, the Domain's Core nodes under `d.core`, and
+ * `d.origin`. A Class the Domain neither declares nor depends on has no handle.
+ */
+export type Handles<S> = Dom<S> extends {
+    readonly classes: infer Own;
+    readonly dependencies: infer Deps;
+    readonly core: infer Core;
+} ? ClassHandles<S, Own> & {
+    readonly [A in keyof Deps as A extends Fixed ? never : A]: Deps[A] extends {
+        readonly classes: infer C;
+    } ? ClassHandles<S, C> : never;
+} & {
+    readonly kernel: ClassHandles<S, KernelDomain['classes']>;
+    readonly core: CoreHandles<Core>;
+    readonly origin: OriginOf<S>;
+} & DocumentRead<S> : never;
+export {};

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

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

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

@@ -0,0 +1,96 @@
+import type { AnyResolvedClass, Domain } from '../../../platform/schema/index.js';
+/** The key of the graph's root Class, which every Node Class satisfies. */
+export declare const NODE_ROOT = "kernel.astrale.ai:class.Node";
+/**
+ * Names a Node handle owns (`HandleMembers`): a Property of the same name goes under `$prop`. The
+ * list is frozen, as `SDK_KEYS` is, so no SDK release moves a Property or an owner group.
+ */
+export declare const HANDLE_MEMBERS: ReadonlySet<string>;
+/** The group of the Properties whose name a handle member, a row key or an Edge role takes. */
+export declare const PROP_GROUP = "$prop";
+/**
+ * The keys the SDK writes on rows besides `id` (`SdkKeys`), all named with `$`: `$class`, `$edge`
+ * on a row read `.withEdge()`, `$source` and `$target` on an Edge root's row, `$withheld` on a row
+ * the reader may not read, and the `$prop` group. Frozen; an owner group named as one of them
+ * goes under `$` and that name (`ownerGroup`).
+ */
+export declare const SDK_KEYS: readonly ['$class', '$edge', '$source', '$target', '$withheld', "$prop"];
+/**
+ * Names a row owns (`RowKeys`): `id` and the SDK's keys. A Property named `id` goes under `$prop`;
+ * no Property name starts with `$`. Frozen as `HANDLE_MEMBERS` is.
+ */
+export declare const ROW_KEYS: ReadonlySet<string>;
+export type Direction = 'outgoing' | 'incoming' | 'incident';
+/** One end of an Edge Class: its role, the Class keys it accepts and how many Edges it holds. */
+export interface End {
+    readonly role: string;
+    readonly accepts: readonly string[];
+    readonly count: string;
+}
+/** An Edge's two ends; an undirected Edge's are its two incident ends, in declared order. */
+export interface Ends {
+    readonly source: End;
+    readonly target: End;
+}
+/** A named to-one relation of a Class (S2). */
+export interface Relation {
+    readonly name: string;
+    readonly edge: AnyResolvedClass;
+    readonly direction: Direction;
+    readonly far: readonly AnyResolvedClass[];
+}
+/** A name several ends claim: it names no relation, and reading it says to use `.via`. */
+export interface Ambiguous {
+    readonly name: string;
+    readonly ambiguous: true;
+}
+/**
+ * Where each Property of a Class goes on a row or a handle (F6), by Property key: under its name
+ * (`flat`), or in a group (`groups`): `$prop` when its name is taken, `$` and its owner's name in
+ * lower camel case when it is an inherited duplicate its name does not keep, and `$$` and that
+ * name when `$` and it is one of the SDK's keys.
+ */
+export interface Layout {
+    readonly flat: ReadonlyMap<string, string>;
+    readonly groups: ReadonlyMap<string, ReadonlyMap<string, string>>;
+}
+/**
+ * The Kernel's Classes, realized once from its compiled Schema reduced to them: a Worker reaches
+ * them without the Kernel's builder or its Functions' value programs.
+ */
+export declare function kernelClasses(): Readonly<Record<string, AnyResolvedClass>>;
+/** The Class model of one resolved Domain. */
+export declare class Model {
+    #private;
+    readonly origin: string;
+    constructor(domain: Domain);
+    /** One Class of the model, by key. */
+    classOf(key: string): AnyResolvedClass;
+    /** The keys a Class satisfies: its own and its parents', transitively, and the graph root. */
+    satisfies(c: AnyResolvedClass): ReadonlySet<string>;
+    /** Both ends of an Edge Class. */
+    ends(edge: AnyResolvedClass): Ends;
+    /** The Classes an end accepts that the Domain can name. */
+    far(end: End): readonly AnyResolvedClass[];
+    /** Whether an end accepts one of `classes`, or one of their parents. */
+    touches(classes: readonly AnyResolvedClass[], end: End): boolean;
+    /** The Classes a traversal of `edges` in `direction` reaches. */
+    reached(edges: readonly AnyResolvedClass[], direction: Direction): readonly AnyResolvedClass[];
+    /** Every Property name of a Class, flat or grouped: a relation or a `.with` name avoids them. */
+    propertyNames(c: AnyResolvedClass): ReadonlySet<string>;
+    /**
+     * The named to-one relations of a Class (S2): one per to-one end that accepts the Class or a
+     * parent, named by the far end's role when that end accepts specific Classes. The Domain's own
+     * relations shadow its dependencies'; a name that clashes with a Property or a handle member
+     * names nothing, and a name several ends claim is ambiguous.
+     */
+    relations(c: AnyResolvedClass): ReadonlyMap<string, Relation | Ambiguous>;
+    /**
+     * Where each Property of a Class goes when `taken` names are a row's or a handle's (F6). A name
+     * keeps its only Property, or the Class's own among inherited duplicates: flat, or under
+     * `$prop` when the name is taken. Each duplicate it does not keep goes under its owner.
+     */
+    layout(c: AnyResolvedClass, taken: ReadonlySet<string>): Layout;
+}
+/** The Class model of a resolved Domain, built once. */
+export declare function modelOf(domain: Domain): Model;