@astrale-os/sdk 0.6.0-beta.64 → 0.6.0-beta.66

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -66,8 +66,9 @@ export interface DomainQuery<DomainValue extends Domain = Domain, As extends Aut
66
66
  <Output>(query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
67
67
  <Input, Output>(query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
68
68
  /**
69
- * Every row of a page Query, page after page; past `max` rows, `TOO_MANY`, as `all({ max })`.
70
- * Each page is a read of its own, at its own snapshot.
69
+ * Every row of a page Query, page after page; past `max` rows answered, `TOO_MANY`. A row a page
70
+ * leaves out does not count, unlike `all({ max })`, which counts every row it reads. Each page is
71
+ * a read of its own, at its own snapshot.
71
72
  */
72
73
  readonly all: <R extends DefinedQuery>(query: R, input: InputOf<R>, options: '~page' extends keyof R ? {
73
74
  readonly as: As;
@@ -1,6 +1,5 @@
1
1
  import type { MutationPropsInput } from '@astrale-os/kernel-core/graph/mutate';
2
2
  import type { PropertyInputOf, ResolvedClass, ResolvedProperty } from '@astrale-os/kernel-dsl/v1';
3
- import { PropertyValues } from '@astrale-os/kernel-dsl/v1/language';
4
3
  import type { schema } from '../../../platform/schema/index.js';
5
4
  import type { StoredPropertyInputOf } from '../../../platform/schema/property-input.js';
6
5
  import type { ReceivedFile } from '../../file/index.js';
@@ -24,11 +23,11 @@ export interface RichPropertyDelta<Class> {
24
23
  }
25
24
  export declare function properties<Class extends ResolvedClass>(selected: Class, input: RichPropertyInput<Class>): MutationPropsInput;
26
25
  export declare function conditions<Class extends ResolvedClass>(selected: Class, input: RichPropertyConditions<Class>): Readonly<{
27
- equals?: PropertyValues | undefined;
26
+ equals?: import("@astrale-os/kernel-dsl/v1").PropertyValues | undefined;
28
27
  absent?: readonly `${string}:class.${string}.property.${string}`[] | undefined;
29
28
  }>;
30
29
  export declare function delta<Class extends ResolvedClass>(selected: Class, input: RichPropertyDelta<Class>): Readonly<{
31
- set: Readonly<Record<`${string}:class.${string}.property.${string}`, import("@astrale-os/kernel-dsl/v1/language").PropertyValue>>;
30
+ set: Readonly<Record<`${string}:class.${string}.property.${string}`, import("../../../platform/schema/index.js").Value>>;
32
31
  unset: readonly `${string}:class.${string}.property.${string}`[];
33
32
  }>;
34
33
  export declare function resolvedProperty<Class extends ResolvedClass>(selected: Class, name: RichPropertyName<Class>): ResolvedProperty;
@@ -1,38 +1,15 @@
1
1
  import { PropertyKey } from '@astrale-os/kernel-dsl/v1/addressing';
2
- import { PropertyValues } from '@astrale-os/kernel-dsl/v1/language';
3
2
  import { isReceivedFile } from '../../file/index.js';
4
3
  export function properties(selected, input) {
5
- const ordinary = Object.create(null);
6
- const receipts = [];
7
- const sources = new Map();
8
- for (const [name, value] of Object.entries(input)) {
9
- const property = resolvedProperty(selected, name);
10
- const previous = sources.get(property.key);
11
- if (previous !== undefined) {
12
- throw new TypeError(`Property ${property.key} is supplied through both ${JSON.stringify(previous)} and ${JSON.stringify(name)}.`);
13
- }
14
- sources.set(property.key, name);
15
- if (isBlobProperty(property)) {
16
- // A received file attaches as its upload receipt.
17
- const receipt = isReceivedFile(value) ? value.receipt : value;
18
- if (typeof receipt !== 'string') {
19
- throw new TypeError(`Blob Property ${property.key} requires an upload receipt or a received file.`);
20
- }
21
- receipts.push([property.key, receipt]);
22
- }
23
- else {
24
- ordinary[name] = value;
25
- }
26
- }
27
- // Blob receipts are admitted by the Kernel executor. A property's ordinary validator expects
28
- // the stored Ref, so run it only for ordinary write values before combining the two sets.
29
- const admitted = selected.properties.from(ordinary);
30
- return receipts.length === 0
31
- ? admitted
32
- : PropertyValues.create([
33
- ...Object.entries(admitted).map(([key, value]) => [PropertyKey(key), value]),
34
- ...receipts,
35
- ]);
4
+ // A received file attaches to a blob Property as its upload receipt, which `from` takes.
5
+ const values = Object.fromEntries(Object.entries(input).map(([name, value]) => [
6
+ name,
7
+ isReceivedFile(value) &&
8
+ isBlobProperty(resolvedProperty(selected, name))
9
+ ? value.receipt
10
+ : value,
11
+ ]));
12
+ return selected.properties.from(values);
36
13
  }
37
14
  export function conditions(selected, input) {
38
15
  return Object.freeze({
@@ -9,10 +9,13 @@
9
9
  * carries no Class, so a value is typed by its key alone; a Node item carries its Class (K-C),
10
10
  * which a Kernel before K-C leaves out.
11
11
  */
12
- import type { EdgeKey } from '../../../platform/graph/edge/index.js';
12
+ import type { EdgeKey, EdgeSlug } from '../../../platform/graph/edge/index.js';
13
13
  import type { NodeId } from '../../../platform/graph/node/index.js';
14
14
  import type { QueryPropertyKey, QueryPropertyValues, QueryRendering } from '../language/query.js';
15
- /** On request (W8): the roots the caller's view cannot decide, up to the fold's bound. */
15
+ /**
16
+ * On request (W8): the roots the caller's view cannot decide, up to the read's bound: a page's
17
+ * size, a count's `upTo`.
18
+ */
16
19
  export interface QueryUndecided {
17
20
  readonly count: number;
18
21
  readonly more: boolean;
@@ -82,9 +85,13 @@ export type QueryRootItem<R> = R extends {
82
85
  };
83
86
  readonly branches: {};
84
87
  };
85
- /** One fact a list renders as values: its readable values and the keys it withholds (R9). */
88
+ /**
89
+ * One fact a list renders as values: its readable values and the keys it withholds (R9), and an
90
+ * Edge's slug when it has one.
91
+ */
86
92
  export interface QueryFact<Source> {
87
93
  readonly fact: NodeId | EdgeKey;
94
+ readonly slug?: EdgeSlug;
88
95
  /** By Property key; a key the Domain does not define may appear (a newer Schema). */
89
96
  readonly values: QueryPropertyValues<Source>;
90
97
  readonly withheld: readonly QueryPropertyKey<Source>[];
@@ -108,7 +115,7 @@ export interface QueryCountAnswer {
108
115
  readonly more: boolean;
109
116
  readonly undecided?: QueryUndecided;
110
117
  }
111
- /** What a Query answers, by its family (the name of its root fold). */
118
+ /** What a Query answers, by its family: `list`, `exists` or `count`. */
112
119
  export type QueryAnswerOf<Source, Q> = Q extends {
113
120
  readonly list: unknown;
114
121
  } ? QueryListAnswer<Source, Q> : Q extends {
@@ -11,7 +11,10 @@ export interface QueryErrorDetails {
11
11
  readonly class: string;
12
12
  readonly target?: string;
13
13
  };
14
- /** `get` or `find` met a fact the reader may not read: a Node, or an Edge read at the root. */
14
+ /**
15
+ * `get` or `find` met a fact the reader may not read: a Node, an Edge read at the root, or the
16
+ * Edge of a row read `.withEdge()`.
17
+ */
15
18
  NOT_READABLE: {
16
19
  readonly class: string;
17
20
  readonly id: NodeId | EdgeKey;
@@ -7,14 +7,17 @@
7
7
  import type { NodeId } from '../../../platform/graph/node/index.js';
8
8
  import type { QueryListAnswer } from '../answer/answer.js';
9
9
  import type { Model } from '../handles/model.js';
10
- import type { EdgeRootPlan, NodeRootPlan, Pattern, ReadPlan } from '../handles/plan.js';
10
+ import type { EdgeRootPlan, Pattern, ReadPlan } from '../handles/plan.js';
11
11
  import type { EdgeKey } from '../handles/rows.js';
12
12
  type Json = Readonly<Record<string, unknown>>;
13
13
  type FactId = NodeId | EdgeKey;
14
- /** One delivered item; a Kernel with K-C gives each Node item its Class. */
15
- interface Item {
14
+ /** A fact a row shows; a Kernel with K-C gives a Node its Class, an Edge's key holds its own. */
15
+ interface Shown {
16
16
  readonly fact: FactId;
17
17
  readonly class?: string;
18
+ }
19
+ /** One delivered item. */
20
+ interface Item extends Shown {
18
21
  readonly edge?: EdgeKey;
19
22
  readonly source?: Item;
20
23
  readonly target?: Item;
@@ -28,12 +31,12 @@ export declare class Renderer {
28
31
  constructor(query: string, model: Model, answer: QueryListAnswer<unknown, unknown>);
29
32
  /** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
30
33
  node(item: Item, pattern: Pattern): Json | undefined;
31
- /** An Edge root row: its identity, its values and both ends by role. */
34
+ /** An Edge root row: its identity, its slug and values when read as values, and both ends. */
32
35
  edge(item: Item, plan: EdgeRootPlan): Json | undefined;
33
- /** The rows of a root list, Node or Edge, leaving out what the reader may not read. */
34
- rootRows(items: readonly Item[], root: NodeRootPlan | EdgeRootPlan): readonly Json[];
35
- /** The one root row `get` or `find` gives. */
36
- rootOne(item: Item, root: NodeRootPlan | EdgeRootPlan): Json;
36
+ /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
37
+ one(item: Item, plan: Pattern | EdgeRootPlan): Json;
38
+ /** The rows of a list, Node or Edge, leaving out what the reader may not read. */
39
+ rows(items: readonly Item[], plan: Pattern | EdgeRootPlan): readonly Json[];
37
40
  }
38
41
  /** The answer of a root read with nothing to read: its verb's empty answer. */
39
42
  export declare function emptyResult(query: string, plan: ReadPlan): unknown;
@@ -77,16 +77,36 @@ export class Renderer {
77
77
  #names(c) {
78
78
  return freeze(c === undefined ? [] : [...this.model.propertyNames(c)]);
79
79
  }
80
+ /**
81
+ * What a row may not show, the one rule of every render path and verb: the first fact it shows
82
+ * that the reader may not read. A row shows its own fact, the Edge it reads as values, and an
83
+ * Edge root's ends read as values; an end read as a reference shows no value.
84
+ */
85
+ #unread(item, plan) {
86
+ const shown = 'source' in plan
87
+ ? [
88
+ item,
89
+ plan.source.select === 'value' ? item.source : undefined,
90
+ plan.target.select === 'value' ? item.target : undefined,
91
+ ]
92
+ : [
93
+ item,
94
+ plan.edge === 'value' && item.edge !== undefined
95
+ ? { fact: item.edge }
96
+ : undefined,
97
+ ];
98
+ return shown.find((one) => one !== undefined && this.#withheld(one.fact));
99
+ }
80
100
  /** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
81
101
  node(item, pattern) {
82
102
  const cls = this.#class(item);
83
103
  const id = item.fact;
84
104
  const layout = this.#layoutClass(cls, pattern.classes);
85
- if (this.#withheld(id)) {
86
- if (!pattern.withheld)
87
- return undefined;
105
+ const unread = this.#unread(item, pattern);
106
+ if (unread !== undefined && !pattern.withheld)
107
+ return undefined;
108
+ if (unread === item)
88
109
  return freeze({ id, $class: cls, $withheld: this.#names(layout) });
89
- }
90
110
  const row = { id, $class: cls };
91
111
  if (pattern.select === 'value')
92
112
  Object.assign(row, this.#values(id, layout, ROW_KEYS));
@@ -97,14 +117,23 @@ export class Renderer {
97
117
  row.$edge = this.#edgeValues(item.edge, edge);
98
118
  return freeze(row);
99
119
  }
100
- /** What `.withEdge()` adds: the Edge's Class, and its values or the names it withholds. */
120
+ /**
121
+ * What `.withEdge()` adds: the Edge's Class, and its slug with its values or, on a row
122
+ * `.includeWithheld()` keeps, the names it withholds.
123
+ */
101
124
  #edgeValues(edge, select) {
102
125
  if (select === 'reference')
103
126
  return freeze({ $class: edge.class });
104
127
  const c = this.#known(edge.class);
128
+ const named = { $class: edge.class, ...this.#slug(edge) };
105
129
  if (this.#withheld(edge))
106
- return freeze({ $class: edge.class, $withheld: this.#names(c) });
107
- return freeze({ $class: edge.class, ...this.#values(edge, c, NO_TAKEN) });
130
+ return freeze({ ...named, $withheld: this.#names(c) });
131
+ return freeze({ ...named, ...this.#values(edge, c, NO_TAKEN) });
132
+ }
133
+ /** The slug the Kernel gives an Edge it renders as values, when the Edge has one. */
134
+ #slug(edge) {
135
+ const slug = this.#fact(edge)?.slug;
136
+ return slug === undefined ? {} : { $slug: slug };
108
137
  }
109
138
  #known(key) {
110
139
  try {
@@ -114,20 +143,27 @@ export class Renderer {
114
143
  return undefined;
115
144
  }
116
145
  }
117
- /** An Edge root row: its identity, its values and both ends by role. */
146
+ /** An Edge root row: its identity, its slug and values when read as values, and both ends. */
118
147
  edge(item, plan) {
119
148
  const key = item.fact;
120
- const identity = { $class: key.class, $source: key.source, $target: key.target };
149
+ const identity = {
150
+ $class: key.class,
151
+ $source: key.source,
152
+ $target: key.target,
153
+ ...(plan.select === 'value' ? this.#slug(key) : {}),
154
+ };
121
155
  const c = this.#known(key.class);
122
- if (this.#withheld(key)) {
123
- if (!plan.withheld)
124
- return undefined;
156
+ const unread = this.#unread(item, plan);
157
+ if (unread !== undefined && !plan.withheld)
158
+ return undefined;
159
+ if (unread === item)
125
160
  return freeze({ ...identity, $withheld: this.#names(c) });
126
- }
127
161
  const roles = new Set([plan.source.role, plan.target.role]);
128
162
  const row = { ...identity };
129
163
  if (plan.select === 'value')
130
164
  Object.assign(row, this.#values(key, c, roles));
165
+ // `#unread` has ruled on the row: an end it let through that the reader may not read, one kept
166
+ // or read as a reference, renders withheld.
131
167
  const end = (rendered, { classes, select }) => {
132
168
  if (rendered === undefined)
133
169
  return undefined;
@@ -159,20 +195,20 @@ export class Renderer {
159
195
  throw this.#integrity(relation, 0);
160
196
  return undefined;
161
197
  }
162
- return this.#one(item, plan);
198
+ return this.one(item, plan);
163
199
  }
164
200
  case 'first':
165
201
  return items[0] === undefined ? undefined : this.node(items[0], plan);
166
202
  case 'firstMore': {
167
203
  const n = plan.bound;
168
- return freeze({ rows: this.#rows(items.slice(0, n), plan), more: items.length > n });
204
+ return freeze({ rows: this.rows(items.slice(0, n), plan), more: items.length > n });
169
205
  }
170
206
  case 'all':
171
207
  if (items.length > plan.bound)
172
208
  throw new QueryError('TOO_MANY', this.query, { limit: 'max', bound: plan.bound });
173
- return this.#rows(items, plan);
209
+ return this.rows(items, plan);
174
210
  default:
175
- return this.#rows(items, plan);
211
+ return this.rows(items, plan);
176
212
  }
177
213
  }
178
214
  #emptyRelation(parent, plan) {
@@ -195,29 +231,22 @@ export class Renderer {
195
231
  #integrity(at, found) {
196
232
  return new QueryError('INTEGRITY', this.query, { ...at, found });
197
233
  }
198
- /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
199
- #one(item, pattern) {
200
- if (this.#withheld(item.fact))
201
- throw new QueryError('NOT_READABLE', this.query, { class: this.#class(item), id: item.fact });
202
- return this.node(item, pattern);
203
- }
204
- #rows(items, pattern) {
205
- return freeze(items.flatMap((item) => this.node(item, pattern) ?? []));
234
+ #row(item, plan) {
235
+ return 'source' in plan ? this.edge(item, plan) : this.node(item, plan);
206
236
  }
207
- /** The rows of a root list, Node or Edge, leaving out what the reader may not read. */
208
- rootRows(items, root) {
209
- return freeze(items.flatMap((item) => (root.kind === 'nodes' ? this.node(item, root) : this.edge(item, root)) ?? []));
210
- }
211
- /** The one root row `get` or `find` gives. */
212
- rootOne(item, root) {
213
- if (this.#withheld(item.fact)) {
214
- const fact = item.fact;
237
+ /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
238
+ one(item, plan) {
239
+ const unread = this.#unread(item, plan);
240
+ if (unread !== undefined)
215
241
  throw new QueryError('NOT_READABLE', this.query, {
216
- class: typeof fact === 'string' ? this.#class(item) : fact.class,
217
- id: fact,
242
+ class: typeof unread.fact === 'string' ? this.#class(unread) : unread.fact.class,
243
+ id: unread.fact,
218
244
  });
219
- }
220
- return (root.kind === 'nodes' ? this.node(item, root) : this.edge(item, root));
245
+ return this.#row(item, plan);
246
+ }
247
+ /** The rows of a list, Node or Edge, leaving out what the reader may not read. */
248
+ rows(items, plan) {
249
+ return freeze(items.flatMap((item) => this.#row(item, plan) ?? []));
221
250
  }
222
251
  }
223
252
  /** The root Classes a root error names. */
@@ -266,25 +295,25 @@ export function rootResult(query, model, plan, answer) {
266
295
  const [item] = items;
267
296
  if (item === undefined)
268
297
  return emptyResult(query, plan);
269
- return renderer.rootOne(item, root);
298
+ return renderer.one(item, root);
270
299
  }
271
300
  case 'first':
272
- return items[0] === undefined ? undefined : renderer.rootRows(items.slice(0, 1), root)[0];
301
+ return items[0] === undefined ? undefined : renderer.rows(items.slice(0, 1), root)[0];
273
302
  case 'firstMore': {
274
303
  const n = plan.bound;
275
- return freeze({ rows: renderer.rootRows(items.slice(0, n), root), more: items.length > n });
304
+ return freeze({ rows: renderer.rows(items.slice(0, n), root), more: items.length > n });
276
305
  }
277
306
  case 'page':
278
307
  return freeze({
279
- rows: renderer.rootRows(items, root),
308
+ rows: renderer.rows(items, root),
280
309
  ...(complete || cursor === undefined ? {} : { next: cursor }),
281
310
  });
282
311
  case 'all':
283
312
  if (items.length > plan.bound)
284
313
  throw new QueryError('TOO_MANY', query, { limit: 'max', bound: plan.bound });
285
- return renderer.rootRows(items, root);
314
+ return renderer.rows(items, root);
286
315
  default:
287
- return renderer.rootRows(items, root);
316
+ return renderer.rows(items, root);
288
317
  }
289
318
  }
290
319
  /**
@@ -72,9 +72,10 @@ export declare function planStep(run: Run, built: unknown, single: boolean, earl
72
72
  */
73
73
  export declare function runQuery<R extends DefinedQuery>(client: QueryClient, domain: Domain, query: R, input: InputOf<R>, call?: QueryPageOptions, declared?: readonly DeclaredClass[]): Promise<OutputOf<R>>;
74
74
  /**
75
- * Every row of a page Query for `input`, page after page: past `max` rows, `TOO_MANY`, as
76
- * `all({ max })`. Each page is a call of its own, with its own bounds (S11) and its own snapshot,
77
- * and asks for at most the rows `max` leaves, plus one: the pages read at most `max + 1` rows.
75
+ * Every row of a page Query for `input`, page after page: past `max` rows answered, `TOO_MANY`. A
76
+ * row a page leaves out does not count, unlike `all({ max })`, which counts every row it reads.
77
+ * Each page is a call of its own, with its own bounds (S11) and its own snapshot, and asks for at
78
+ * most the rows `max` leaves, plus one: the pages read at most `max + 1` rows and those left out.
78
79
  */
79
80
  export declare function runEveryPage<R extends DefinedQuery>(client: QueryClient, domain: Domain, query: R, input: InputOf<R>, max: number, declared?: readonly DeclaredClass[]): Promise<readonly unknown[]>;
80
81
  /**
@@ -327,9 +327,10 @@ export async function runQuery(client, domain, query, input, call = {}, declared
327
327
  return (await answer(new Run(client, domain, query.id, declared), built, call));
328
328
  }
329
329
  /**
330
- * Every row of a page Query for `input`, page after page: past `max` rows, `TOO_MANY`, as
331
- * `all({ max })`. Each page is a call of its own, with its own bounds (S11) and its own snapshot,
332
- * and asks for at most the rows `max` leaves, plus one: the pages read at most `max + 1` rows.
330
+ * Every row of a page Query for `input`, page after page: past `max` rows answered, `TOO_MANY`. A
331
+ * row a page leaves out does not count, unlike `all({ max })`, which counts every row it reads.
332
+ * Each page is a call of its own, with its own bounds (S11) and its own snapshot, and asks for at
333
+ * most the rows `max` leaves, plus one: the pages read at most `max + 1` rows and those left out.
333
334
  */
334
335
  export async function runEveryPage(client, domain, query, input, max, declared) {
335
336
  const built = build(domain, query, input);
@@ -10,7 +10,7 @@ import type { SizedQuery } from '../language/query.js';
10
10
  import type { Cond, Conditions, HandleMembers, IsCond, Ordering, PropOf, PropsOf, Unordered } from './conditions.js';
11
11
  import type { Cls, Dom, KeyOf, LayoutOf, OriginOf, PropNamesOf, Satisfies, Single, Untyped, ValueOfEntry } from './domain.js';
12
12
  import type { Far, RelationsOf, SourceKeys, SourceRole, TargetKeys, TargetRole, ViaCheck, ViaOptions } from './relations.js';
13
- import type { Count, EdgeRootRef, EdgeRootRow, EdgeValues, Page, Ref, Row, RowKeys, WithheldEdgeRow, WithheldRow } from './rows.js';
13
+ import type { Count, EdgeRootRef, EdgeRootRow, EdgeValues, Page, Ref, Row, RowKeys, WithheldEdgeRow, WithheldEdgeValues, WithheldRow } from './rows.js';
14
14
  /** A read: what a verb returns, an opaque description the Query runs, typed by its answer `T`. */
15
15
  export interface Read<out T> {
16
16
  readonly '~read': T;
@@ -152,6 +152,15 @@ export interface NodeSet<S, K extends string, W, M extends Rendering, H extends
152
152
  readonly upTo: number;
153
153
  }): Read<Count>;
154
154
  }
155
+ /**
156
+ * A relation's row: under `.includeWithheld()`, a row read `.withEdge()` may also be one whose
157
+ * Edge the reader may not read.
158
+ */
159
+ type RelRowOf<S, K, E, W, M extends Rendering, H extends boolean> = H extends true ? RowOf<S, K, W, M, true> | (W extends {
160
+ readonly $edge: unknown;
161
+ } ? RowOf<S, K, Omit<W, '$edge'> & {
162
+ readonly $edge: WithheldEdgeValues<S, E>;
163
+ }, M, false> : never) : RowOf<S, K, W, M, false>;
155
164
  /** A relation from a Node: the Nodes at the far end of its Edges. */
156
165
  export interface RelSet<S, K extends string, E extends string, W, M extends Rendering, H extends boolean> {
157
166
  /** Its far Classes and Edges: a relation is not a Class handle, so `is` and `union` refuse it. */
@@ -159,7 +168,11 @@ export interface RelSet<S, K extends string, E extends string, W, M extends Rend
159
168
  where<const R extends Conditions>(conditions: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => R): RelSet<S, Narrow<K, R>, E, W, M, H>;
160
169
  orderBy(keys: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Ordering): RelSet<S, K, E, W, M, H>;
161
170
  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>;
162
- /** Each row gains `$edge`: the Edge's Class and Properties. */
171
+ /**
172
+ * Each row gains `$edge`: the Edge's Class, its slug when it has one, and its Properties. The
173
+ * Edge is a fact the row reads: when the reader may not read it, the row is left out, `get` and
174
+ * `find` raise `NOT_READABLE`, and `.includeWithheld()` keeps the row with `$withheld` in `$edge`.
175
+ */
163
176
  withEdge(): RelSet<S, K, E, W & {
164
177
  readonly $edge: EdgeValues<S, E>;
165
178
  }, M, H>;
@@ -173,18 +186,18 @@ export interface RelSet<S, K extends string, E extends string, W, M extends Rend
173
186
  */
174
187
  get(): RelationRead<RowOf<S, K, W, M, false>>;
175
188
  find(): RelationRead<RowOf<S, K, W, M, false> | undefined>;
176
- first(): RelationRead<RowOf<S, K, W, M, H> | undefined>;
177
- first(n: number): RelationRead<readonly RowOf<S, K, W, M, H>[]>;
189
+ first(): RelationRead<RelRowOf<S, K, E, W, M, H> | undefined>;
190
+ first(n: number): RelationRead<readonly RelRowOf<S, K, E, W, M, H>[]>;
178
191
  /** Reads n + 1 rows per parent to say whether more exist. */
179
192
  first(n: number, options: {
180
193
  readonly more: true;
181
194
  }): RelationRead<{
182
- readonly rows: readonly RowOf<S, K, W, M, H>[];
195
+ readonly rows: readonly RelRowOf<S, K, E, W, M, H>[];
183
196
  readonly more: boolean;
184
197
  }>;
185
198
  all(options: {
186
199
  readonly max: number;
187
- }): RelationRead<readonly RowOf<S, K, W, M, H>[]>;
200
+ }): RelationRead<readonly RelRowOf<S, K, E, W, M, H>[]>;
188
201
  count(options: {
189
202
  readonly upTo: number;
190
203
  }): RelationRead<Count>;
@@ -205,7 +218,7 @@ export type EdgeRootHandle<S, E extends string> = E extends unknown ? PropsOf<Cl
205
218
  } & {
206
219
  readonly [R in TargetRole<S, E>]: NodeHandle<S, TargetKeys<S, E>>;
207
220
  } : never;
208
- 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);
221
+ type EdgeRowOf<S, E, M extends Rendering, H extends boolean> = (M extends 'reference' ? EdgeRootRef<S, E> : EdgeRootRow<S, E, H>) | (H extends true ? WithheldEdgeRow<S, E> : never);
209
222
  /** The Edges of a Class at the root of a read. */
210
223
  export interface EdgeSet<S, E extends string, M extends Rendering, H extends boolean> {
211
224
  readonly '~edge': E;
@@ -213,6 +226,7 @@ export interface EdgeSet<S, E extends string, M extends Rendering, H extends boo
213
226
  orderBy(keys: (edge: EdgeRootHandle<S, E>) => Ordering): EdgeSet<S, E, M, H>;
214
227
  /** Rows of `{ $class, $source, $target }`, with both ends as references. */
215
228
  ref(): EdgeSet<S, E, 'reference', H>;
229
+ /** Keeps in a list a row the reader may not read: its Edge, or an end read as values, withheld. */
216
230
  includeWithheld(): EdgeSet<S, E, M, true>;
217
231
  get(): Read<EdgeRowOf<S, E, M, false>>;
218
232
  find(): Read<EdgeRowOf<S, E, M, false> | undefined>;
@@ -3,18 +3,19 @@ import type { AnyResolvedClass, Domain } from '../../../platform/schema/index.js
3
3
  export declare const NODE_ROOT = "kernel.astrale.ai:class.Node";
4
4
  /**
5
5
  * Names a Node handle owns (`HandleMembers`): a Property of the same name goes under `$prop`. The
6
- * list is frozen, as `SDK_KEYS` is, so no SDK release moves a Property or an owner group.
6
+ * list is frozen, as `SDK_KEYS` is: a name added to either moves the Properties or the owner group
7
+ * of that name, in every Domain that has one.
7
8
  */
8
9
  export declare const HANDLE_MEMBERS: ReadonlySet<string>;
9
10
  /** The group of the Properties whose name a handle member, a row key or an Edge role takes. */
10
11
  export declare const PROP_GROUP = "$prop";
11
12
  /**
12
13
  * The keys the SDK writes on rows besides `id` (`SdkKeys`), all named with `$`: `$class`, `$edge`
13
- * on a row read `.withEdge()`, `$source` and `$target` on an Edge root's row, `$withheld` on a row
14
- * the reader may not read, and the `$prop` group. Frozen; an owner group named as one of them
15
- * goes under `$` and that name (`ownerGroup`).
14
+ * on a row read `.withEdge()`, `$slug` on an Edge read as values that has one, `$source` and
15
+ * `$target` on an Edge root's row, `$withheld` on a row the reader may not read, and the `$prop`
16
+ * group. Frozen; an owner group named as one of them goes under `$` and that name (`ownerGroup`).
16
17
  */
17
- export declare const SDK_KEYS: readonly ['$class', '$edge', '$source', '$target', '$withheld', "$prop"];
18
+ export declare const SDK_KEYS: readonly ['$class', '$edge', '$slug', '$source', '$target', '$withheld', "$prop"];
18
19
  /**
19
20
  * Names a row owns (`RowKeys`): `id` and the SDK's keys. A Property named `id` goes under `$prop`;
20
21
  * no Property name starts with `$`. Frozen as `HANDLE_MEMBERS` is.
@@ -7,18 +7,27 @@ const GENERIC = new Set([NODE_ROOT, 'kernel.astrale.ai:class.Identity']);
7
7
  const TO_ONE = new Set(['0..1', '1']);
8
8
  /**
9
9
  * Names a Node handle owns (`HandleMembers`): a Property of the same name goes under `$prop`. The
10
- * list is frozen, as `SDK_KEYS` is, so no SDK release moves a Property or an owner group.
10
+ * list is frozen, as `SDK_KEYS` is: a name added to either moves the Properties or the owner group
11
+ * of that name, in every Domain that has one.
11
12
  */
12
13
  export const HANDLE_MEMBERS = new Set(['id', 'path', 'is', 'isExactly', 'via']);
13
14
  /** The group of the Properties whose name a handle member, a row key or an Edge role takes. */
14
15
  export const PROP_GROUP = '$prop';
15
16
  /**
16
17
  * The keys the SDK writes on rows besides `id` (`SdkKeys`), all named with `$`: `$class`, `$edge`
17
- * on a row read `.withEdge()`, `$source` and `$target` on an Edge root's row, `$withheld` on a row
18
- * the reader may not read, and the `$prop` group. Frozen; an owner group named as one of them
19
- * goes under `$` and that name (`ownerGroup`).
18
+ * on a row read `.withEdge()`, `$slug` on an Edge read as values that has one, `$source` and
19
+ * `$target` on an Edge root's row, `$withheld` on a row the reader may not read, and the `$prop`
20
+ * group. Frozen; an owner group named as one of them goes under `$` and that name (`ownerGroup`).
20
21
  */
21
- export const SDK_KEYS = ['$class', '$edge', '$source', '$target', '$withheld', PROP_GROUP];
22
+ export const SDK_KEYS = [
23
+ '$class',
24
+ '$edge',
25
+ '$slug',
26
+ '$source',
27
+ '$target',
28
+ '$withheld',
29
+ PROP_GROUP,
30
+ ];
22
31
  /**
23
32
  * Names a row owns (`RowKeys`): `id` and the SDK's keys. A Property named `id` goes under `$prop`;
24
33
  * no Property name starts with `$`. Frozen as `HANDLE_MEMBERS` is.
@@ -3,6 +3,7 @@
3
3
  * Class or any subclass the Domain can name (D6), and a Property whose name is taken goes under
4
4
  * `$prop` (F6).
5
5
  */
6
+ import type { EdgeSlug } from '../../../platform/graph/edge/index.js';
6
7
  import type { NodeId } from '../../../platform/graph/node/index.js';
7
8
  import type { ClassOf, Cls, Layout, LayoutOf, PropNamesOf, RequiredEntry, SdkKeys, ValueOfEntry } from './domain.js';
8
9
  import type { SourceKeys, SourceRole, TargetKeys, TargetRole } from './relations.js';
@@ -48,16 +49,33 @@ type EdgeIdentity<E> = {
48
49
  };
49
50
  /** An Edge row: its Class, both ends' ids and its Properties. */
50
51
  export type EdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & ValuesOf<S, E, never> : never;
51
- /** What `.withEdge()` adds to a row under `$edge`: the Edge's Class and its Properties. */
52
+ /** An Edge read as values: its slug, absent from an Edge without one and on a Host before beta.39. */
53
+ type Slugged = {
54
+ readonly $slug?: EdgeSlug;
55
+ };
56
+ /** What `.withEdge()` adds to a row under `$edge`: the Edge's Class, its slug and its Properties. */
52
57
  export type EdgeValues<S, E> = E extends unknown ? {
53
58
  readonly $class: ClassOf<S, E>;
54
- } & ValuesOf<S, E, never> : never;
59
+ } & Slugged & ValuesOf<S, E, never> : never;
60
+ /** An Edge the reader may not read: its slug, which traversal discloses, and the names withheld. */
61
+ type UnreadEdge<S, E> = Slugged & {
62
+ readonly $withheld: readonly PropNamesOf<Cls<S, E>>[];
63
+ };
64
+ /** `$edge` on a row `.includeWithheld()` keeps though the reader may not read its Edge. */
65
+ export type WithheldEdgeValues<S, E> = E extends unknown ? {
66
+ readonly $class: ClassOf<S, E>;
67
+ } & UnreadEdge<S, E> : never;
55
68
  type Roles<S, E> = SourceRole<S, E> | TargetRole<S, E>;
56
- /** An Edge row at the root: its values, and both ends' rows by role. */
57
- export type EdgeRootRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & ValuesOf<S, E, Roles<S, E>> & {
58
- readonly [R in SourceRole<S, E>]: Row<S, SourceKeys<S, E>>;
69
+ /** An end read as values: one `.includeWithheld()` keeps may be one the reader may not read. */
70
+ type EndRow<S, K, H extends boolean> = Row<S, K> | (H extends true ? WithheldRow<S, K> : never);
71
+ /**
72
+ * An Edge row at the root: its slug, its values, and both ends' rows by role. `H` is
73
+ * `.includeWithheld()`, under which either end may be withheld.
74
+ */
75
+ export type EdgeRootRow<S, E, H extends boolean = false> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & Slugged & ValuesOf<S, E, Roles<S, E>> & {
76
+ readonly [R in SourceRole<S, E>]: EndRow<S, SourceKeys<S, E>, H>;
59
77
  } & {
60
- readonly [R in TargetRole<S, E>]: Row<S, TargetKeys<S, E>>;
78
+ readonly [R in TargetRole<S, E>]: EndRow<S, TargetKeys<S, E>, H>;
61
79
  } : never;
62
80
  /** An Edge reference row at the root (`.ref()`): both ends as references. */
63
81
  export type EdgeRootRef<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & {
@@ -65,10 +83,8 @@ export type EdgeRootRef<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>>
65
83
  } & {
66
84
  readonly [R in TargetRole<S, E>]: Ref<S, TargetKeys<S, E>>;
67
85
  } : never;
68
- /** An Edge the reader may not read (`.includeWithheld()`). */
69
- export type WithheldEdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & {
70
- readonly $withheld: readonly PropNamesOf<Cls<S, E>>[];
71
- } : never;
86
+ /** An Edge row at the root the reader may not read (`.includeWithheld()`). */
87
+ export type WithheldEdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & UnreadEdge<S, E> : never;
72
88
  /** An Edge's identity, as a Mutation or a guard names it. */
73
89
  export interface EdgeKey<E extends string = string> {
74
90
  readonly source: NodeId;
@@ -307,7 +307,7 @@ type QueryOver<D extends Domain, L extends Size> = D extends Domain ? {
307
307
  readonly count: Range<D>;
308
308
  readonly upTo: number;
309
309
  } : never;
310
- /** A Query of the Domain, as its canonical JSON: the root fold names its family. */
310
+ /** A Query of the Domain, as its canonical JSON: its family is `list`, `exists` or `count`. */
311
311
  export type Query<Source> = QueryOver<QueryDomainOf<Source>, UnsizedList>;
312
312
  /** A Query whose every list is sized by `limit`: the document a defined Query reads (W1). */
313
313
  export type SizedQuery<Source> = QueryOver<QueryDomainOf<Source>, SizedList>;
@@ -1,2 +1,2 @@
1
- /** Generated from the Kernel Schema of @astrale-os/kernel-core 1.0.0-beta.40, reduced to its Classes. Regenerate with pnpm sync:kernel-schema. */
1
+ /** Generated from the Kernel Schema of @astrale-os/kernel-core 1.0.0-beta.41, reduced to its Classes. Regenerate with pnpm sync:kernel-schema. */
2
2
  export declare const kernelCompiledSchema: string;