xmemory 3.8.3 → 3.12.0

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.
package/README.md CHANGED
@@ -249,7 +249,30 @@ const result = await inst.read("Who is on the team?");
249
249
  console.log(result.reader_result);
250
250
  ```
251
251
 
252
- Options: `{ readMode?, scope?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
252
+ Options: `{ readMode?, scope?, includeRelatedTypes?, relatedTypesDepth?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
253
+
254
+ #### What comes back
255
+
256
+ In `"single-answer"` mode `reader_result` is always the prose answer. In
257
+ `"raw-tables"` and `"xresponse"` mode its value says which of four answers the
258
+ read gave:
259
+
260
+ | `reader_result` | Meaning | What to do |
261
+ | --- | --- | --- |
262
+ | rows | Answered. | Use them. |
263
+ | exactly `{ columns: [], rows: [] }` / `{ objects: [], relations: [] }` | The query executed and matched nothing — every table and column it used exists, so the data is absent. | Trust the empty result. |
264
+ | `null` | The schema provably cannot represent the concept. An answer, not a variant of the empty one. | Try a better-matching instance; this memory cannot hold it. |
265
+ | *(throws)* | Every sub-query's SQL failed, so nothing was answered. | Catch `XmemoryAPIError` with `status` 422 and `code` `"INVALID_INPUT"`. It is the same answer for the same input, so do not retry it. |
266
+
267
+ ```typescript
268
+ const result = await inst.read("Which invoices are overdue?", { readMode: "raw-tables" });
269
+ if (result.reader_result === null) {
270
+ // Not a concept this memory holds — try another instance.
271
+ } else {
272
+ const { rows } = result.reader_result as { columns: string[]; rows: unknown[][] };
273
+ // rows.length === 0 means the data is absent, not that the read failed.
274
+ }
275
+ ```
253
276
 
254
277
  #### Composite queries
255
278
 
@@ -269,6 +292,15 @@ for (const part of result.reader_results) {
269
292
  }
270
293
  ```
271
294
 
295
+ Each part's `reader_result` uses the same four answers as above, with one more
296
+ case: a sub-query whose SQL failed carries the empty result *and* a user-safe
297
+ `error`, while the others are answered regardless. Its bytes then equal those
298
+ of a sub-query that matched nothing, so read `error` before `reader_result`, as
299
+ the loop above does. The combined `reader_result` folds the parts: rows if any
300
+ sub-query answered; else the empty result if any executed and matched nothing;
301
+ else `null`. In the tabular modes a read where *every* sub-query failed throws
302
+ the 422 above instead.
303
+
272
304
  #### Scoped reads
273
305
 
274
306
  By default a read may draw on the whole instance. Pass a `scope` to restrict it
@@ -297,6 +329,66 @@ const result = await inst.read("What do we know about these people?", {
297
329
  restricts the read to the listed objects only, while `"all_relations"` also
298
330
  exposes the relations among the in-scope objects.
299
331
 
332
+ #### Related types
333
+
334
+ A read can also say what else the memory could answer about. Pass
335
+ `includeRelatedTypes: "types"` and `related_types` on the result names the
336
+ object types the read touched, each with the fields it did not return and the
337
+ object types a declared relation links it to (the relation, both roles, and its
338
+ cardinality seen from the touched type), plus a catalog that describes every
339
+ named type (description, primary key, field names) and relation once. It is
340
+ derived from the instance schema and the statements the read executed — no
341
+ extra rows, no model call — so an agent can ask a deliberate follow-up instead
342
+ of guessing what the store holds.
343
+
344
+ ```typescript
345
+ const result = await inst.read("Which courses require an English test?", {
346
+ includeRelatedTypes: "types",
347
+ });
348
+ for (const touched of result.related_types?.touched ?? []) {
349
+ console.log(touched.object_type, "did not return", touched.fields_not_returned);
350
+ for (const link of touched.related) {
351
+ const neighbour = result.related_types!.objects[link.object_type];
352
+ console.log(" linked to", link.object_type, "via", link.relation, neighbour.fields);
353
+ }
354
+ }
355
+ ```
356
+
357
+ `related_types` is `null` unless the read asked for it. A requested read that
358
+ executed nothing arrives with `touched: []`. The server caps the payload;
359
+ `truncated` says when it did, and `omitted_touched` and each entry's
360
+ `omitted_related` count what was dropped.
361
+
362
+ To follow the relations further, add `relatedTypesDepth: 2` (up to 3). Every
363
+ entry under `related_types.objects` then carries its `distance` from the touched
364
+ types (0 for a touched type) and, between the touched types and the last level,
365
+ its own `related` edges, so the walk can be continued from the catalog:
366
+
367
+ ```typescript
368
+ const result = await inst.read("Which courses require an English test?", {
369
+ includeRelatedTypes: "types",
370
+ relatedTypesDepth: 2,
371
+ });
372
+ for (const [name, entry] of Object.entries(result.related_types?.objects ?? {})) {
373
+ console.log(name, "at distance", entry.distance);
374
+ for (const link of entry.related) {
375
+ console.log(" linked to", link.object_type, "via", link.relation);
376
+ }
377
+ }
378
+ ```
379
+
380
+ `related_types.depth` echoes the depth asked for. `distance` counts listed edges
381
+ from the nearest touched type, and `omitted_objects` counts the types within that
382
+ many relation levels that the server's budgets kept out of the catalog; `truncated`
383
+ says something was cut. Left unset, nothing is sent and the server serves one
384
+ level in the shape it always had: `depth`, `omitted_objects` and the catalog
385
+ entries' `distance`, `related` and `omitted_related` are then absent. A value
386
+ outside 1 to 3 is a 422 whose `code` is `VALIDATION_ERROR`. Asking for related
387
+ types needs the
388
+ `instance.get_own` permission on the API key, the same one the schema
389
+ endpoints need, on top of `data.read`: a key without it gets a 403 whose
390
+ message names the permission, and the plain read is unaffected.
391
+
300
392
  #### Scoped writes
301
393
 
302
394
  A write is normally free to touch anything in the instance: the extractor sees
@@ -527,6 +619,18 @@ Advisory values — `step.kind`, `fragment.merge`, `format` — are widened to a
527
619
  added to the server after this release, so an additive change does not become a breaking
528
620
  one. A `step.kind` you do not recognise is not something to execute.
529
621
 
622
+ ## Request identification
623
+
624
+ Every request this client issues carries an `X-Xmemory-Client` header naming the package and its
625
+ release, followed by the host — for example `xmemory-node/3.9.0 (node v24.5.0; darwin)`. The
626
+ parenthetical reports `process.version` and `process.platform`, says `unknown` for either one a host
627
+ does not supply, and never carries a hostname. The API uses it to tell its own clients apart.
628
+
629
+ The identity travels in a dedicated header rather than in `User-Agent`, which belongs to the runtime:
630
+ your `User-Agent` is neither read nor written, and every other header on the request is left alone. A
631
+ proxy that strips unknown `X-` headers costs the attribution but not the request — the call still goes
632
+ through, counted as a generic caller.
633
+
530
634
  ## Error handling
531
635
 
532
636
  All errors throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCheckError` (a subclass).
@@ -562,6 +666,8 @@ different things:
562
666
  | ---- | ----------------- | ---------------------------------------------------- | ---------------------------------- |
563
667
  | 402 | `QUOTA_EXCEEDED` | Tenant exhausted its plan/usage allowance (a daily or monthly token quota). | **No.** Wait for the window to reset. |
564
668
  | 429 | `RATE_LIMITED` | Genuine velocity / rate limit. | **Yes**, with backoff. |
669
+ | 422 | `INVALID_INPUT` | A read that answered nothing: in `"raw-tables"` / `"xresponse"` mode every sub-query's SQL failed, or the model provider declined the input. See [What comes back](#what-comes-back). | **No.** Same input, same answer. |
670
+ | 403 | `FORBIDDEN` | The API key lacks a permission the call needs — for a read with `includeRelatedTypes: "types"`, `instance.get_own`; the message names it. See [Related types](#related-types). | **No.** Repeat without the option, or use a key that holds it. |
565
671
 
566
672
  For `QUOTA_EXCEEDED`, `details` carries `kind`
567
673
  (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
@@ -3,6 +3,41 @@
3
3
  */
4
4
  import { InstanceHandle } from "./instance.js";
5
5
  import { type AgentSetupResult, type ClusterInfo, type CreateInstanceOptions, type DryRunMigrationOptions, type DryRunResult, type EnhanceSchemaResult, type GenerateSchemaOptions, type GenerateSchemaResult, type GetMigrationOptions, type InstanceInfo, type InstanceSchemaInfo, type ListMigrationsOptions, type ListMigrationsResult, type MigrationRecord, type PatchInstanceMetadataOptions, type RequestOptions, type SchemaTypeValue, type SetupFormatValue, type UpdateInstanceMetadataOptions, type UpdateInstanceSchemaOptions, type XmemoryClientOptions } from "./types.js";
6
+ /**
7
+ * The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
8
+ * non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
9
+ * `unknown` otherwise.
10
+ * The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
11
+ * missing fields would write the word "undefined" into the header. A control character such as NUL
12
+ * or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
13
+ * converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
14
+ * a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
15
+ * The length cap is there because nothing else bounds what a host may report into a header this
16
+ * sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
17
+ * those substitutions directly.
18
+ */
19
+ export declare function buildClientIdentity(version: string, host: {
20
+ version?: unknown;
21
+ platform?: unknown;
22
+ } | undefined): string;
23
+ /**
24
+ * The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
25
+ * belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
26
+ * treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
27
+ */
28
+ export declare const CLIENT_HEADER = "X-Xmemory-Client";
29
+ /**
30
+ * The headers a request goes out with: everything the caller built, in a new object so the
31
+ * caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
32
+ * header is dropped first — header names are case-insensitive on the wire, so leaving one behind
33
+ * would put two values under one name, and `fetch` joins those into a single comma-separated value
34
+ * whose first token is the one the API reads. `User-Agent` and everything else pass through
35
+ * untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
36
+ * sees what `_headers()` built — so the drop is defensive against a future call site that does, not
37
+ * a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
38
+ * directly.
39
+ */
40
+ export declare function withClientHeader(existing: Record<string, string> | undefined): Record<string, string>;
6
41
  export interface AdminNamespace {
7
42
  listClusters(options?: RequestOptions & {
8
43
  ids?: string[];
@@ -3,10 +3,13 @@
3
3
  * XmemoryClient — main entry point for the xmemory API.
4
4
  */
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.XmemoryClient = void 0;
6
+ exports.XmemoryClient = exports.CLIENT_HEADER = void 0;
7
+ exports.buildClientIdentity = buildClientIdentity;
8
+ exports.withClientHeader = withClientHeader;
7
9
  exports.xmemoryInstance = xmemoryInstance;
8
10
  const instance_js_1 = require("./instance.js");
9
11
  const types_js_1 = require("./types.js");
12
+ const version_js_1 = require("./version.js");
10
13
  const DEFAULT_BASE_URL = "https://api.xmemory.ai";
11
14
  /**
12
15
  * An *own* property of a decoded response, or `undefined`.
@@ -27,6 +30,59 @@ function ownArray(source, key) {
27
30
  return Array.isArray(value) ? value : [];
28
31
  }
29
32
  const DEFAULT_TIMEOUT_MS = 60_000;
33
+ const HOST_FIELD_MAX = 64;
34
+ /** One host detail, reduced to something a header value may safely carry. */
35
+ const hostField = (value) => typeof value === "string" &&
36
+ value.length <= HOST_FIELD_MAX &&
37
+ /^[\x21-\x7e]+$/.test(value) &&
38
+ !/[;()]/.test(value)
39
+ ? value
40
+ : "unknown";
41
+ /**
42
+ * The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
43
+ * non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
44
+ * `unknown` otherwise.
45
+ * The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
46
+ * missing fields would write the word "undefined" into the header. A control character such as NUL
47
+ * or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
48
+ * converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
49
+ * a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
50
+ * The length cap is there because nothing else bounds what a host may report into a header this
51
+ * sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
52
+ * those substitutions directly.
53
+ */
54
+ function buildClientIdentity(version, host) {
55
+ return `xmemory-node/${version} (node ${hostField(host?.version)}; ${hostField(host?.platform)})`;
56
+ }
57
+ /**
58
+ * The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
59
+ * belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
60
+ * treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
61
+ */
62
+ exports.CLIENT_HEADER = "X-Xmemory-Client";
63
+ // `process` is absent in a browser and partial under some bundler shims, so the fields are read
64
+ // defensively and each one falls back to `unknown`.
65
+ const CLIENT_IDENTITY = buildClientIdentity(version_js_1.VERSION, typeof process !== "undefined" ? process : undefined);
66
+ /**
67
+ * The headers a request goes out with: everything the caller built, in a new object so the
68
+ * caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
69
+ * header is dropped first — header names are case-insensitive on the wire, so leaving one behind
70
+ * would put two values under one name, and `fetch` joins those into a single comma-separated value
71
+ * whose first token is the one the API reads. `User-Agent` and everything else pass through
72
+ * untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
73
+ * sees what `_headers()` built — so the drop is defensive against a future call site that does, not
74
+ * a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
75
+ * directly.
76
+ */
77
+ function withClientHeader(existing) {
78
+ const headers = {};
79
+ for (const [name, value] of Object.entries(existing ?? {})) {
80
+ if (name.toLowerCase() !== exports.CLIENT_HEADER.toLowerCase())
81
+ headers[name] = value;
82
+ }
83
+ headers[exports.CLIENT_HEADER] = CLIENT_IDENTITY;
84
+ return headers;
85
+ }
30
86
  const ORANGE = "\x1b[38;5;208m";
31
87
  const RESET = "\x1b[0m";
32
88
  function deprecationWarning(message) {
@@ -142,7 +198,11 @@ class XmemoryClient {
142
198
  const controller = new AbortController();
143
199
  const timer = setTimeout(() => controller.abort(), timeoutMs);
144
200
  try {
145
- return await fetch(url, { ...init, signal: controller.signal });
201
+ return await fetch(url, {
202
+ ...init,
203
+ headers: withClientHeader(init.headers),
204
+ signal: controller.signal,
205
+ });
146
206
  }
147
207
  finally {
148
208
  clearTimeout(timer);
@@ -7,10 +7,10 @@ export { DescribeResult, InstanceHandle } from "./instance.js";
7
7
  export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
8
8
  export { SchemaType } from "./types.js";
9
9
  export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from "./types.js";
10
- export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
10
+ export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, RelatedTypesMode, RelationCardinality, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
11
11
  export type { ScopeObject, ReadScope, WriteScope, RelationsScope } from "./types.js";
12
12
  export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceMetadataOptions, PatchInstanceMetadataOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
13
- export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
13
+ export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
14
14
  export type { WriteMutation, ObjectMutationBody, ObjectCreatePayload, ObjectUpdatePayload, ObjectDeletePayload, RelationMutationBody, RelationCreatePayload, RelationUpdatePayload, RelationDeletePayload, RelationEndpoint, } from "./types.js";
15
15
  export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
16
16
  export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
@@ -234,11 +234,16 @@ class InstanceHandle {
234
234
  relations_scope: options.scope.relationsScope ?? "no_relations",
235
235
  };
236
236
  }
237
+ if (options?.includeRelatedTypes != null)
238
+ body.include_related_types = options.includeRelatedTypes;
239
+ if (options?.relatedTypesDepth != null)
240
+ body.related_types_depth = options.relatedTypesDepth;
237
241
  if (options?.traceId != null)
238
242
  body.trace_id = options.traceId;
239
243
  // The wire shape omits `reader_results` on a server without question
240
- // decomposition, so type it as optional here and normalize to an always-array
241
- // for the public `ReadResult` below.
244
+ // decomposition, and `related_types` unless the read asked for it, so type
245
+ // them as optional here and normalize (always-array, `null`) for the public
246
+ // `ReadResult` below.
242
247
  const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
243
248
  body,
244
249
  timeoutMs: options?.timeoutMs,
@@ -248,10 +253,15 @@ class InstanceHandle {
248
253
  // by `Object.prototype` when the caller reads it.
249
254
  const readerResults = own(result, "reader_results");
250
255
  const traceId = own(result, "trace_id");
256
+ const relatedTypes = own(result, "related_types");
257
+ // `reader_result` is required on the wire and `null` is one of its answers (a
258
+ // refusal, in the tabular modes), so the coalescing only stands in for a field
259
+ // the server omitted; a `null` the server sent arrives as the same `null`.
251
260
  return withConsoleUrl({
252
261
  ...result,
253
262
  reader_result: own(result, "reader_result") ?? null,
254
263
  reader_results: Array.isArray(readerResults) ? readerResults : [],
264
+ related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
255
265
  trace_id: typeof traceId === "string" ? traceId : null,
256
266
  });
257
267
  }
@@ -8,6 +8,23 @@ export declare const SchemaType: {
8
8
  export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
9
9
  export type ExtractionLogic = "fast" | "deep";
10
10
  export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
11
+ /**
12
+ * What a read says about the schema around its answer. `"types"` adds
13
+ * {@link ReadResult.related_types} to the result; `"none"` (the server default)
14
+ * leaves it out. Asking for it needs the `instance.get_own` permission on the
15
+ * API key, the same one the schema endpoints need, on top of `data.read`: a key
16
+ * without it gets a 403 whose message names the permission, and the plain read
17
+ * is unaffected.
18
+ */
19
+ export type RelatedTypesMode = "none" | "types";
20
+ /**
21
+ * Cardinality of a relation seen from the touched type's role, derived from the
22
+ * relation's unique keys: `"one_to_many"` means one touched record links to many
23
+ * neighbours and each neighbour to at most one touched record; `"many_to_one"`
24
+ * is the reverse; `"unconstrained"` means the schema declares no uniqueness rule
25
+ * for the relation.
26
+ */
27
+ export type RelationCardinality = "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" | "unconstrained";
11
28
  /**
12
29
  * One concrete object a scoped read or a scoped write may touch. Identify it by
13
30
  * `type` (PascalCase class name or snake_case table name) plus its user-defined
@@ -155,20 +172,159 @@ export interface InstanceSchemaInfo {
155
172
  * One sub-query and its own answer, in the requested read mode. Appears in
156
173
  * {@link ReadResult.reader_results} when the server decomposed a composite query
157
174
  * into independent sub-queries.
175
+ *
176
+ * `reader_result` gives one of the four answers described on
177
+ * {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
178
+ * failed carries the empty result *and* `error`, while the other sub-queries
179
+ * are answered regardless. Its bytes then equal those of a sub-query that
180
+ * matched nothing, so read `error` before `reader_result`.
158
181
  */
159
182
  export interface TaggedReaderResult {
160
183
  readonly sub_query: string;
161
184
  readonly reader_result: unknown;
162
185
  /**
163
- * A user-safe message set when this sub-query could not be answered while the
164
- * others still were (partial tolerance); `null` otherwise.
186
+ * A user-safe message set when this sub-query's SQL could not be executed;
187
+ * `null` otherwise. In `"raw-tables"` / `"xresponse"` mode a read where every
188
+ * sub-query failed does not return at all: it throws {@link XmemoryAPIError}
189
+ * with `status` 422 and `code` `"INVALID_INPUT"`.
165
190
  */
166
191
  readonly error: string | null;
167
192
  }
193
+ /**
194
+ * One relation edge from the entry's own type to a neighbouring type;
195
+ * {@link RelatedTypes.objects} describes both ends. The entry is a touched type
196
+ * (under `touched`) or, at a `relatedTypesDepth` above 1, a catalog entry
197
+ * (under `objects`); `touched_role` is the role the entry's own type plays
198
+ * either way.
199
+ */
200
+ export interface RelatedTypesLink {
201
+ /** The neighbouring object type, described once under `objects`. */
202
+ readonly object_type: string;
203
+ /** The relation that links the two, described once under `relations`. */
204
+ readonly relation: string;
205
+ /** The relation role the entry's own type plays in this edge. */
206
+ readonly touched_role: string;
207
+ /** The relation role the neighbouring type plays in this edge. */
208
+ readonly related_role: string;
209
+ readonly cardinality: RelationCardinality;
210
+ }
211
+ /** One object type the read touched, with what it withheld and what it is linked to. */
212
+ export interface RelatedTypesTouched {
213
+ /** Object type name as declared in the schema, described under `objects`. */
214
+ readonly object_type: string;
215
+ /**
216
+ * Fields of this type the read did not project. Ask for one by name to see it;
217
+ * an expression the reader could not attribute to a field counts here rather
218
+ * than as returned.
219
+ */
220
+ readonly fields_not_returned: readonly string[];
221
+ /** Relation edges to neighbouring types, sorted by relation then type. A self-relation lists one edge per role. */
222
+ readonly related: readonly RelatedTypesLink[];
223
+ /** Edges dropped from `related` to stay within the server's payload budget. */
224
+ readonly omitted_related: number;
225
+ }
226
+ /** Catalog entry for an object type named in {@link RelatedTypes.touched} or reached through `relatedTypesDepth`. */
227
+ export interface RelatedTypesObjectType {
228
+ /**
229
+ * Listed edges from the nearest touched type: 0 for a touched type, 1 for a
230
+ * type a touched type's listed edge names, and so on up to
231
+ * {@link RelatedTypes.depth}. A route through an edge the server's budget cut
232
+ * is not followed, so this can exceed the schema's own hop count; the cutting
233
+ * entry's `omitted_related` says when. Absent on a one-level read: the server
234
+ * then serves the payload it always did, without the depth keys.
235
+ */
236
+ readonly distance?: number;
237
+ readonly description: string | null;
238
+ /** Declared primary-key fields, in declared order. */
239
+ readonly primary_key: readonly string[];
240
+ /** Every field of the object type, by name. */
241
+ readonly fields: readonly string[];
242
+ /**
243
+ * This type's own relation edges, for an entry whose `distance` is at least 1
244
+ * and below `depth`. Empty for a touched type (its edges are on its `touched`
245
+ * entry), at the last level, and once the server's shared edge budget is spent
246
+ * (then `omitted_related` counts every edge the type has). Absent on a
247
+ * one-level read.
248
+ */
249
+ readonly related?: readonly RelatedTypesLink[];
250
+ /**
251
+ * Edges of this type the server did not list: cut by its per-type cap, by the
252
+ * edge budget shared with the touched entries, or dropped with a level for its
253
+ * byte budget. Absent on a one-level read.
254
+ */
255
+ readonly omitted_related?: number;
256
+ }
257
+ /** Catalog entry for a relation named by any edge. */
258
+ export interface RelatedTypesRelation {
259
+ readonly description: string | null;
260
+ }
261
+ /**
262
+ * What else the memory could answer about, for a read that asked with
263
+ * `includeRelatedTypes: "types"`: the object types the read touched, each with
264
+ * the fields it did not return and its relation edges, plus a catalog that
265
+ * describes every named type and relation exactly once. It is derived from the
266
+ * instance schema and the statements the read executed — no extra rows are
267
+ * read and no model is called — so an agent can phrase a deliberate follow-up
268
+ * read instead of guessing. With a `relatedTypesDepth` above 1 the catalog
269
+ * follows the listed edges further: each entry carries its `distance` from the
270
+ * touched types and, below the last level, its own edges. The server caps the
271
+ * payload; whatever it dropped is counted — an edge on the entry it was dropped
272
+ * from, a type the catalog could not list on `omitted_objects` — and `truncated`
273
+ * says that something was. A one-level read is served in the shape that
274
+ * predates the depth, so `depth`, `omitted_objects` and the catalog entries'
275
+ * depth fields are then absent.
276
+ */
277
+ export interface RelatedTypes {
278
+ /**
279
+ * Relation levels asked for (`relatedTypesDepth`). Never lowered by the server:
280
+ * what its budgets kept the walk from listing is counted on `omitted_objects`
281
+ * and on each entry's `omitted_related`. Absent on a one-level read.
282
+ */
283
+ readonly depth?: number;
284
+ /** Object types the read touched, sorted by name. Empty when the read executed nothing. */
285
+ readonly touched: readonly RelatedTypesTouched[];
286
+ /** Every object type a listed edge names — touched, or reached through the listed edges within `depth` levels — once. */
287
+ readonly objects: Readonly<Record<string, RelatedTypesObjectType>>;
288
+ /** Every relation named by an edge, once. */
289
+ readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
290
+ /** Touched types dropped to stay within the budget. */
291
+ readonly omitted_touched: number;
292
+ /**
293
+ * Object types within `depth` relation levels of the touched types in the
294
+ * schema that the catalog does not list: the route to them ran through an edge
295
+ * the server's budget cut, or their level was dropped for its byte budget.
296
+ * Absent on a one-level read.
297
+ */
298
+ readonly omitted_objects?: number;
299
+ /** `true` when any type, edge or level was dropped for the budget. */
300
+ readonly truncated: boolean;
301
+ }
168
302
  export interface ReadResult {
169
303
  readonly trace_id: string | null;
170
304
  /** Deep link to this read's trace in the console; `null` if no console is configured. */
171
305
  readonly console_url: string | null;
306
+ /**
307
+ * The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
308
+ * prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
309
+ * says which of four answers the read gave:
310
+ *
311
+ * - rows — answered;
312
+ * - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
313
+ * `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
314
+ * matched nothing: every table and column it used exists, so the data is
315
+ * absent;
316
+ * - `null` — the schema provably cannot represent the concept. An answer in
317
+ * its own right, not a variant of the empty one: this memory cannot hold
318
+ * it, so a better-matching instance is worth trying;
319
+ * - no result at all — every sub-query's SQL failed, so nothing was
320
+ * answered. The read throws {@link XmemoryAPIError} with `status` 422 and
321
+ * `code` `"INVALID_INPUT"` rather than reporting an empty result.
322
+ *
323
+ * For a composite query this is the combined answer, folded from the parts:
324
+ * rows if any sub-query answered; else the empty result if any executed and
325
+ * matched nothing; else `null`. `reader_results` carries each part's own
326
+ * answer.
327
+ */
172
328
  readonly reader_result: unknown;
173
329
  /**
174
330
  * Per-sub-query answers when the server decomposed the query into independent
@@ -179,6 +335,14 @@ export interface ReadResult {
179
335
  * so the array is empty regardless of how many questions the query held.
180
336
  */
181
337
  readonly reader_results: readonly TaggedReaderResult[];
338
+ /**
339
+ * The schema around the answer, when the read asked for it with
340
+ * `includeRelatedTypes: "types"`; `null` otherwise. The wire omits the field
341
+ * unless it was requested, and a server that predates the option never sends
342
+ * it; the client normalizes both to `null`, so `null` means "not asked for" and
343
+ * a requested read that executed nothing arrives with `touched: []` instead.
344
+ */
345
+ readonly related_types: RelatedTypes | null;
182
346
  }
183
347
  export interface WriteResult {
184
348
  readonly write_id: string;
@@ -554,6 +718,22 @@ export interface ReadOptions {
554
718
  readMode?: ReadMode;
555
719
  /** Restrict the read to a set of concrete objects (plus optional relation traversal). */
556
720
  scope?: ReadScope;
721
+ /**
722
+ * `"types"` asks for {@link ReadResult.related_types}: the object types the read
723
+ * touched, the fields it did not return, and the object types a declared
724
+ * relation links them to. Left unset, nothing is sent and the server default
725
+ * (`"none"`) applies. Needs `instance.get_own` on the API key; see
726
+ * {@link RelatedTypesMode}.
727
+ */
728
+ includeRelatedTypes?: RelatedTypesMode;
729
+ /**
730
+ * With `includeRelatedTypes: "types"`, how many relation levels the catalog
731
+ * follows out from the touched types, 1 to 3. Every entry under
732
+ * {@link RelatedTypes.objects} then carries its `distance` and, below the last
733
+ * level, its own `related` edges. Left unset, nothing is sent and the server
734
+ * serves one level; a value out of range is a 422.
735
+ */
736
+ relatedTypesDepth?: number;
557
737
  traceId?: string;
558
738
  timeoutMs?: number;
559
739
  }
@@ -0,0 +1,2 @@
1
+ /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
+ export declare const VERSION = "3.12.0";
@@ -0,0 +1,5 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.VERSION = void 0;
4
+ /** Package version. Kept in sync with `package.json` — a test asserts they match. */
5
+ exports.VERSION = "3.12.0";
@@ -3,6 +3,41 @@
3
3
  */
4
4
  import { InstanceHandle } from "./instance.js";
5
5
  import { type AgentSetupResult, type ClusterInfo, type CreateInstanceOptions, type DryRunMigrationOptions, type DryRunResult, type EnhanceSchemaResult, type GenerateSchemaOptions, type GenerateSchemaResult, type GetMigrationOptions, type InstanceInfo, type InstanceSchemaInfo, type ListMigrationsOptions, type ListMigrationsResult, type MigrationRecord, type PatchInstanceMetadataOptions, type RequestOptions, type SchemaTypeValue, type SetupFormatValue, type UpdateInstanceMetadataOptions, type UpdateInstanceSchemaOptions, type XmemoryClientOptions } from "./types.js";
6
+ /**
7
+ * The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
8
+ * non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
9
+ * `unknown` otherwise.
10
+ * The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
11
+ * missing fields would write the word "undefined" into the header. A control character such as NUL
12
+ * or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
13
+ * converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
14
+ * a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
15
+ * The length cap is there because nothing else bounds what a host may report into a header this
16
+ * sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
17
+ * those substitutions directly.
18
+ */
19
+ export declare function buildClientIdentity(version: string, host: {
20
+ version?: unknown;
21
+ platform?: unknown;
22
+ } | undefined): string;
23
+ /**
24
+ * The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
25
+ * belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
26
+ * treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
27
+ */
28
+ export declare const CLIENT_HEADER = "X-Xmemory-Client";
29
+ /**
30
+ * The headers a request goes out with: everything the caller built, in a new object so the
31
+ * caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
32
+ * header is dropped first — header names are case-insensitive on the wire, so leaving one behind
33
+ * would put two values under one name, and `fetch` joins those into a single comma-separated value
34
+ * whose first token is the one the API reads. `User-Agent` and everything else pass through
35
+ * untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
36
+ * sees what `_headers()` built — so the drop is defensive against a future call site that does, not
37
+ * a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
38
+ * directly.
39
+ */
40
+ export declare function withClientHeader(existing: Record<string, string> | undefined): Record<string, string>;
6
41
  export interface AdminNamespace {
7
42
  listClusters(options?: RequestOptions & {
8
43
  ids?: string[];
@@ -3,6 +3,7 @@
3
3
  */
4
4
  import { InstanceHandle } from "./instance.js";
5
5
  import { SetupFormat, XmemoryAPIError, XmemoryHealthCheckError, buildInstanceSchema, } from "./types.js";
6
+ import { VERSION } from "./version.js";
6
7
  const DEFAULT_BASE_URL = "https://api.xmemory.ai";
7
8
  /**
8
9
  * An *own* property of a decoded response, or `undefined`.
@@ -23,6 +24,59 @@ function ownArray(source, key) {
23
24
  return Array.isArray(value) ? value : [];
24
25
  }
25
26
  const DEFAULT_TIMEOUT_MS = 60_000;
27
+ const HOST_FIELD_MAX = 64;
28
+ /** One host detail, reduced to something a header value may safely carry. */
29
+ const hostField = (value) => typeof value === "string" &&
30
+ value.length <= HOST_FIELD_MAX &&
31
+ /^[\x21-\x7e]+$/.test(value) &&
32
+ !/[;()]/.test(value)
33
+ ? value
34
+ : "unknown";
35
+ /**
36
+ * The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
37
+ * non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
38
+ * `unknown` otherwise.
39
+ * The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
40
+ * missing fields would write the word "undefined" into the header. A control character such as NUL
41
+ * or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
42
+ * converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
43
+ * a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
44
+ * The length cap is there because nothing else bounds what a host may report into a header this
45
+ * sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
46
+ * those substitutions directly.
47
+ */
48
+ export function buildClientIdentity(version, host) {
49
+ return `xmemory-node/${version} (node ${hostField(host?.version)}; ${hostField(host?.platform)})`;
50
+ }
51
+ /**
52
+ * The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
53
+ * belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
54
+ * treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
55
+ */
56
+ export const CLIENT_HEADER = "X-Xmemory-Client";
57
+ // `process` is absent in a browser and partial under some bundler shims, so the fields are read
58
+ // defensively and each one falls back to `unknown`.
59
+ const CLIENT_IDENTITY = buildClientIdentity(VERSION, typeof process !== "undefined" ? process : undefined);
60
+ /**
61
+ * The headers a request goes out with: everything the caller built, in a new object so the
62
+ * caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
63
+ * header is dropped first — header names are case-insensitive on the wire, so leaving one behind
64
+ * would put two values under one name, and `fetch` joins those into a single comma-separated value
65
+ * whose first token is the one the API reads. `User-Agent` and everything else pass through
66
+ * untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
67
+ * sees what `_headers()` built — so the drop is defensive against a future call site that does, not
68
+ * a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
69
+ * directly.
70
+ */
71
+ export function withClientHeader(existing) {
72
+ const headers = {};
73
+ for (const [name, value] of Object.entries(existing ?? {})) {
74
+ if (name.toLowerCase() !== CLIENT_HEADER.toLowerCase())
75
+ headers[name] = value;
76
+ }
77
+ headers[CLIENT_HEADER] = CLIENT_IDENTITY;
78
+ return headers;
79
+ }
26
80
  const ORANGE = "\x1b[38;5;208m";
27
81
  const RESET = "\x1b[0m";
28
82
  function deprecationWarning(message) {
@@ -138,7 +192,11 @@ export class XmemoryClient {
138
192
  const controller = new AbortController();
139
193
  const timer = setTimeout(() => controller.abort(), timeoutMs);
140
194
  try {
141
- return await fetch(url, { ...init, signal: controller.signal });
195
+ return await fetch(url, {
196
+ ...init,
197
+ headers: withClientHeader(init.headers),
198
+ signal: controller.signal,
199
+ });
142
200
  }
143
201
  finally {
144
202
  clearTimeout(timer);
@@ -7,10 +7,10 @@ export { DescribeResult, InstanceHandle } from "./instance.js";
7
7
  export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
8
8
  export { SchemaType } from "./types.js";
9
9
  export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from "./types.js";
10
- export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
10
+ export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, RelatedTypesMode, RelationCardinality, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
11
11
  export type { ScopeObject, ReadScope, WriteScope, RelationsScope } from "./types.js";
12
12
  export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceMetadataOptions, PatchInstanceMetadataOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
13
- export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
13
+ export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
14
14
  export type { WriteMutation, ObjectMutationBody, ObjectCreatePayload, ObjectUpdatePayload, ObjectDeletePayload, RelationMutationBody, RelationCreatePayload, RelationUpdatePayload, RelationDeletePayload, RelationEndpoint, } from "./types.js";
15
15
  export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
16
16
  export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
@@ -230,11 +230,16 @@ export class InstanceHandle {
230
230
  relations_scope: options.scope.relationsScope ?? "no_relations",
231
231
  };
232
232
  }
233
+ if (options?.includeRelatedTypes != null)
234
+ body.include_related_types = options.includeRelatedTypes;
235
+ if (options?.relatedTypesDepth != null)
236
+ body.related_types_depth = options.relatedTypesDepth;
233
237
  if (options?.traceId != null)
234
238
  body.trace_id = options.traceId;
235
239
  // The wire shape omits `reader_results` on a server without question
236
- // decomposition, so type it as optional here and normalize to an always-array
237
- // for the public `ReadResult` below.
240
+ // decomposition, and `related_types` unless the read asked for it, so type
241
+ // them as optional here and normalize (always-array, `null`) for the public
242
+ // `ReadResult` below.
238
243
  const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
239
244
  body,
240
245
  timeoutMs: options?.timeoutMs,
@@ -244,10 +249,15 @@ export class InstanceHandle {
244
249
  // by `Object.prototype` when the caller reads it.
245
250
  const readerResults = own(result, "reader_results");
246
251
  const traceId = own(result, "trace_id");
252
+ const relatedTypes = own(result, "related_types");
253
+ // `reader_result` is required on the wire and `null` is one of its answers (a
254
+ // refusal, in the tabular modes), so the coalescing only stands in for a field
255
+ // the server omitted; a `null` the server sent arrives as the same `null`.
247
256
  return withConsoleUrl({
248
257
  ...result,
249
258
  reader_result: own(result, "reader_result") ?? null,
250
259
  reader_results: Array.isArray(readerResults) ? readerResults : [],
260
+ related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
251
261
  trace_id: typeof traceId === "string" ? traceId : null,
252
262
  });
253
263
  }
@@ -8,6 +8,23 @@ export declare const SchemaType: {
8
8
  export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
9
9
  export type ExtractionLogic = "fast" | "deep";
10
10
  export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
11
+ /**
12
+ * What a read says about the schema around its answer. `"types"` adds
13
+ * {@link ReadResult.related_types} to the result; `"none"` (the server default)
14
+ * leaves it out. Asking for it needs the `instance.get_own` permission on the
15
+ * API key, the same one the schema endpoints need, on top of `data.read`: a key
16
+ * without it gets a 403 whose message names the permission, and the plain read
17
+ * is unaffected.
18
+ */
19
+ export type RelatedTypesMode = "none" | "types";
20
+ /**
21
+ * Cardinality of a relation seen from the touched type's role, derived from the
22
+ * relation's unique keys: `"one_to_many"` means one touched record links to many
23
+ * neighbours and each neighbour to at most one touched record; `"many_to_one"`
24
+ * is the reverse; `"unconstrained"` means the schema declares no uniqueness rule
25
+ * for the relation.
26
+ */
27
+ export type RelationCardinality = "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" | "unconstrained";
11
28
  /**
12
29
  * One concrete object a scoped read or a scoped write may touch. Identify it by
13
30
  * `type` (PascalCase class name or snake_case table name) plus its user-defined
@@ -155,20 +172,159 @@ export interface InstanceSchemaInfo {
155
172
  * One sub-query and its own answer, in the requested read mode. Appears in
156
173
  * {@link ReadResult.reader_results} when the server decomposed a composite query
157
174
  * into independent sub-queries.
175
+ *
176
+ * `reader_result` gives one of the four answers described on
177
+ * {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
178
+ * failed carries the empty result *and* `error`, while the other sub-queries
179
+ * are answered regardless. Its bytes then equal those of a sub-query that
180
+ * matched nothing, so read `error` before `reader_result`.
158
181
  */
159
182
  export interface TaggedReaderResult {
160
183
  readonly sub_query: string;
161
184
  readonly reader_result: unknown;
162
185
  /**
163
- * A user-safe message set when this sub-query could not be answered while the
164
- * others still were (partial tolerance); `null` otherwise.
186
+ * A user-safe message set when this sub-query's SQL could not be executed;
187
+ * `null` otherwise. In `"raw-tables"` / `"xresponse"` mode a read where every
188
+ * sub-query failed does not return at all: it throws {@link XmemoryAPIError}
189
+ * with `status` 422 and `code` `"INVALID_INPUT"`.
165
190
  */
166
191
  readonly error: string | null;
167
192
  }
193
+ /**
194
+ * One relation edge from the entry's own type to a neighbouring type;
195
+ * {@link RelatedTypes.objects} describes both ends. The entry is a touched type
196
+ * (under `touched`) or, at a `relatedTypesDepth` above 1, a catalog entry
197
+ * (under `objects`); `touched_role` is the role the entry's own type plays
198
+ * either way.
199
+ */
200
+ export interface RelatedTypesLink {
201
+ /** The neighbouring object type, described once under `objects`. */
202
+ readonly object_type: string;
203
+ /** The relation that links the two, described once under `relations`. */
204
+ readonly relation: string;
205
+ /** The relation role the entry's own type plays in this edge. */
206
+ readonly touched_role: string;
207
+ /** The relation role the neighbouring type plays in this edge. */
208
+ readonly related_role: string;
209
+ readonly cardinality: RelationCardinality;
210
+ }
211
+ /** One object type the read touched, with what it withheld and what it is linked to. */
212
+ export interface RelatedTypesTouched {
213
+ /** Object type name as declared in the schema, described under `objects`. */
214
+ readonly object_type: string;
215
+ /**
216
+ * Fields of this type the read did not project. Ask for one by name to see it;
217
+ * an expression the reader could not attribute to a field counts here rather
218
+ * than as returned.
219
+ */
220
+ readonly fields_not_returned: readonly string[];
221
+ /** Relation edges to neighbouring types, sorted by relation then type. A self-relation lists one edge per role. */
222
+ readonly related: readonly RelatedTypesLink[];
223
+ /** Edges dropped from `related` to stay within the server's payload budget. */
224
+ readonly omitted_related: number;
225
+ }
226
+ /** Catalog entry for an object type named in {@link RelatedTypes.touched} or reached through `relatedTypesDepth`. */
227
+ export interface RelatedTypesObjectType {
228
+ /**
229
+ * Listed edges from the nearest touched type: 0 for a touched type, 1 for a
230
+ * type a touched type's listed edge names, and so on up to
231
+ * {@link RelatedTypes.depth}. A route through an edge the server's budget cut
232
+ * is not followed, so this can exceed the schema's own hop count; the cutting
233
+ * entry's `omitted_related` says when. Absent on a one-level read: the server
234
+ * then serves the payload it always did, without the depth keys.
235
+ */
236
+ readonly distance?: number;
237
+ readonly description: string | null;
238
+ /** Declared primary-key fields, in declared order. */
239
+ readonly primary_key: readonly string[];
240
+ /** Every field of the object type, by name. */
241
+ readonly fields: readonly string[];
242
+ /**
243
+ * This type's own relation edges, for an entry whose `distance` is at least 1
244
+ * and below `depth`. Empty for a touched type (its edges are on its `touched`
245
+ * entry), at the last level, and once the server's shared edge budget is spent
246
+ * (then `omitted_related` counts every edge the type has). Absent on a
247
+ * one-level read.
248
+ */
249
+ readonly related?: readonly RelatedTypesLink[];
250
+ /**
251
+ * Edges of this type the server did not list: cut by its per-type cap, by the
252
+ * edge budget shared with the touched entries, or dropped with a level for its
253
+ * byte budget. Absent on a one-level read.
254
+ */
255
+ readonly omitted_related?: number;
256
+ }
257
+ /** Catalog entry for a relation named by any edge. */
258
+ export interface RelatedTypesRelation {
259
+ readonly description: string | null;
260
+ }
261
+ /**
262
+ * What else the memory could answer about, for a read that asked with
263
+ * `includeRelatedTypes: "types"`: the object types the read touched, each with
264
+ * the fields it did not return and its relation edges, plus a catalog that
265
+ * describes every named type and relation exactly once. It is derived from the
266
+ * instance schema and the statements the read executed — no extra rows are
267
+ * read and no model is called — so an agent can phrase a deliberate follow-up
268
+ * read instead of guessing. With a `relatedTypesDepth` above 1 the catalog
269
+ * follows the listed edges further: each entry carries its `distance` from the
270
+ * touched types and, below the last level, its own edges. The server caps the
271
+ * payload; whatever it dropped is counted — an edge on the entry it was dropped
272
+ * from, a type the catalog could not list on `omitted_objects` — and `truncated`
273
+ * says that something was. A one-level read is served in the shape that
274
+ * predates the depth, so `depth`, `omitted_objects` and the catalog entries'
275
+ * depth fields are then absent.
276
+ */
277
+ export interface RelatedTypes {
278
+ /**
279
+ * Relation levels asked for (`relatedTypesDepth`). Never lowered by the server:
280
+ * what its budgets kept the walk from listing is counted on `omitted_objects`
281
+ * and on each entry's `omitted_related`. Absent on a one-level read.
282
+ */
283
+ readonly depth?: number;
284
+ /** Object types the read touched, sorted by name. Empty when the read executed nothing. */
285
+ readonly touched: readonly RelatedTypesTouched[];
286
+ /** Every object type a listed edge names — touched, or reached through the listed edges within `depth` levels — once. */
287
+ readonly objects: Readonly<Record<string, RelatedTypesObjectType>>;
288
+ /** Every relation named by an edge, once. */
289
+ readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
290
+ /** Touched types dropped to stay within the budget. */
291
+ readonly omitted_touched: number;
292
+ /**
293
+ * Object types within `depth` relation levels of the touched types in the
294
+ * schema that the catalog does not list: the route to them ran through an edge
295
+ * the server's budget cut, or their level was dropped for its byte budget.
296
+ * Absent on a one-level read.
297
+ */
298
+ readonly omitted_objects?: number;
299
+ /** `true` when any type, edge or level was dropped for the budget. */
300
+ readonly truncated: boolean;
301
+ }
168
302
  export interface ReadResult {
169
303
  readonly trace_id: string | null;
170
304
  /** Deep link to this read's trace in the console; `null` if no console is configured. */
171
305
  readonly console_url: string | null;
306
+ /**
307
+ * The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
308
+ * prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
309
+ * says which of four answers the read gave:
310
+ *
311
+ * - rows — answered;
312
+ * - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
313
+ * `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
314
+ * matched nothing: every table and column it used exists, so the data is
315
+ * absent;
316
+ * - `null` — the schema provably cannot represent the concept. An answer in
317
+ * its own right, not a variant of the empty one: this memory cannot hold
318
+ * it, so a better-matching instance is worth trying;
319
+ * - no result at all — every sub-query's SQL failed, so nothing was
320
+ * answered. The read throws {@link XmemoryAPIError} with `status` 422 and
321
+ * `code` `"INVALID_INPUT"` rather than reporting an empty result.
322
+ *
323
+ * For a composite query this is the combined answer, folded from the parts:
324
+ * rows if any sub-query answered; else the empty result if any executed and
325
+ * matched nothing; else `null`. `reader_results` carries each part's own
326
+ * answer.
327
+ */
172
328
  readonly reader_result: unknown;
173
329
  /**
174
330
  * Per-sub-query answers when the server decomposed the query into independent
@@ -179,6 +335,14 @@ export interface ReadResult {
179
335
  * so the array is empty regardless of how many questions the query held.
180
336
  */
181
337
  readonly reader_results: readonly TaggedReaderResult[];
338
+ /**
339
+ * The schema around the answer, when the read asked for it with
340
+ * `includeRelatedTypes: "types"`; `null` otherwise. The wire omits the field
341
+ * unless it was requested, and a server that predates the option never sends
342
+ * it; the client normalizes both to `null`, so `null` means "not asked for" and
343
+ * a requested read that executed nothing arrives with `touched: []` instead.
344
+ */
345
+ readonly related_types: RelatedTypes | null;
182
346
  }
183
347
  export interface WriteResult {
184
348
  readonly write_id: string;
@@ -554,6 +718,22 @@ export interface ReadOptions {
554
718
  readMode?: ReadMode;
555
719
  /** Restrict the read to a set of concrete objects (plus optional relation traversal). */
556
720
  scope?: ReadScope;
721
+ /**
722
+ * `"types"` asks for {@link ReadResult.related_types}: the object types the read
723
+ * touched, the fields it did not return, and the object types a declared
724
+ * relation links them to. Left unset, nothing is sent and the server default
725
+ * (`"none"`) applies. Needs `instance.get_own` on the API key; see
726
+ * {@link RelatedTypesMode}.
727
+ */
728
+ includeRelatedTypes?: RelatedTypesMode;
729
+ /**
730
+ * With `includeRelatedTypes: "types"`, how many relation levels the catalog
731
+ * follows out from the touched types, 1 to 3. Every entry under
732
+ * {@link RelatedTypes.objects} then carries its `distance` and, below the last
733
+ * level, its own `related` edges. Left unset, nothing is sent and the server
734
+ * serves one level; a value out of range is a 422.
735
+ */
736
+ relatedTypesDepth?: number;
557
737
  traceId?: string;
558
738
  timeoutMs?: number;
559
739
  }
@@ -0,0 +1,2 @@
1
+ /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
+ export declare const VERSION = "3.12.0";
@@ -0,0 +1,2 @@
1
+ /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
+ export const VERSION = "3.12.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.8.3",
3
+ "version": "3.12.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"