xmemory 3.8.3 → 3.10.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?, 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,39 @@ 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!.types[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. Asking for it needs the
361
+ `instance.get_own` permission on the API key, the same one the schema
362
+ endpoints need, on top of `data.read`: a key without it gets a 403 whose
363
+ message names the permission, and the plain read is unaffected.
364
+
300
365
  #### Scoped writes
301
366
 
302
367
  A write is normally free to touch anything in the instance: the extractor sees
@@ -527,6 +592,18 @@ Advisory values — `step.kind`, `fragment.merge`, `format` — are widened to a
527
592
  added to the server after this release, so an additive change does not become a breaking
528
593
  one. A `step.kind` you do not recognise is not something to execute.
529
594
 
595
+ ## Request identification
596
+
597
+ Every request this client issues carries an `X-Xmemory-Client` header naming the package and its
598
+ release, followed by the host — for example `xmemory-node/3.9.0 (node v24.5.0; darwin)`. The
599
+ parenthetical reports `process.version` and `process.platform`, says `unknown` for either one a host
600
+ does not supply, and never carries a hostname. The API uses it to tell its own clients apart.
601
+
602
+ The identity travels in a dedicated header rather than in `User-Agent`, which belongs to the runtime:
603
+ your `User-Agent` is neither read nor written, and every other header on the request is left alone. A
604
+ proxy that strips unknown `X-` headers costs the attribution but not the request — the call still goes
605
+ through, counted as a generic caller.
606
+
530
607
  ## Error handling
531
608
 
532
609
  All errors throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCheckError` (a subclass).
@@ -562,6 +639,8 @@ different things:
562
639
  | ---- | ----------------- | ---------------------------------------------------- | ---------------------------------- |
563
640
  | 402 | `QUOTA_EXCEEDED` | Tenant exhausted its plan/usage allowance (a daily or monthly token quota). | **No.** Wait for the window to reset. |
564
641
  | 429 | `RATE_LIMITED` | Genuine velocity / rate limit. | **Yes**, with backoff. |
642
+ | 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. |
643
+ | 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
644
 
566
645
  For `QUOTA_EXCEEDED`, `details` carries `kind`
567
646
  (`"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,14 @@ 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;
237
239
  if (options?.traceId != null)
238
240
  body.trace_id = options.traceId;
239
241
  // 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.
242
+ // decomposition, and `related_types` unless the read asked for it, so type
243
+ // them as optional here and normalize (always-array, `null`) for the public
244
+ // `ReadResult` below.
242
245
  const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
243
246
  body,
244
247
  timeoutMs: options?.timeoutMs,
@@ -248,10 +251,15 @@ class InstanceHandle {
248
251
  // by `Object.prototype` when the caller reads it.
249
252
  const readerResults = own(result, "reader_results");
250
253
  const traceId = own(result, "trace_id");
254
+ const relatedTypes = own(result, "related_types");
255
+ // `reader_result` is required on the wire and `null` is one of its answers (a
256
+ // refusal, in the tabular modes), so the coalescing only stands in for a field
257
+ // the server omitted; a `null` the server sent arrives as the same `null`.
251
258
  return withConsoleUrl({
252
259
  ...result,
253
260
  reader_result: own(result, "reader_result") ?? null,
254
261
  reader_results: Array.isArray(readerResults) ? readerResults : [],
262
+ related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
255
263
  trace_id: typeof traceId === "string" ? traceId : null,
256
264
  });
257
265
  }
@@ -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,112 @@ 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
+ /** One relation edge from a touched type to a neighbouring type; {@link RelatedTypes.types} describes both ends. */
194
+ export interface RelatedTypesLink {
195
+ /** The neighbouring object type, described once under `types`. */
196
+ readonly object_type: string;
197
+ /** The relation that links the two, described once under `relations`. */
198
+ readonly relation: string;
199
+ /** The relation role the touched type plays in this edge. */
200
+ readonly touched_role: string;
201
+ /** The relation role the neighbouring type plays in this edge. */
202
+ readonly related_role: string;
203
+ readonly cardinality: RelationCardinality;
204
+ }
205
+ /** One object type the read touched, with what it withheld and what it is linked to. */
206
+ export interface RelatedTypesTouched {
207
+ /** Object type name as declared in the schema, described under `types`. */
208
+ readonly object_type: string;
209
+ /**
210
+ * Fields of this type the read did not project. Ask for one by name to see it;
211
+ * an expression the reader could not attribute to a field counts here rather
212
+ * than as returned.
213
+ */
214
+ readonly fields_not_returned: readonly string[];
215
+ /** Relation edges to neighbouring types, sorted by relation then type. A self-relation lists one edge per role. */
216
+ readonly related: readonly RelatedTypesLink[];
217
+ /** Edges dropped from `related` to stay within the server's payload budget. */
218
+ readonly omitted_related: number;
219
+ }
220
+ /** Catalog entry for an object type named anywhere in {@link RelatedTypes.touched}. */
221
+ export interface RelatedTypesObjectType {
222
+ readonly description: string | null;
223
+ /** Declared primary-key fields, in declared order. */
224
+ readonly primary_key: readonly string[];
225
+ /** Every field of the object type, by name. */
226
+ readonly fields: readonly string[];
227
+ }
228
+ /** Catalog entry for a relation named by any edge. */
229
+ export interface RelatedTypesRelation {
230
+ readonly description: string | null;
231
+ }
232
+ /**
233
+ * What else the memory could answer about, for a read that asked with
234
+ * `includeRelatedTypes: "types"`: the object types the read touched, each with
235
+ * the fields it did not return and its relation edges, plus a catalog that
236
+ * describes every named type and relation exactly once. It is derived from the
237
+ * instance schema and the statements the read executed — no extra rows are
238
+ * read and no model is called — so an agent can phrase a deliberate follow-up
239
+ * read instead of guessing. The server caps the payload; whatever it dropped is
240
+ * counted on the entry it was dropped from, and `truncated` says that something
241
+ * was.
242
+ */
243
+ export interface RelatedTypes {
244
+ /** Object types the read touched, sorted by name. Empty when the read executed nothing. */
245
+ readonly touched: readonly RelatedTypesTouched[];
246
+ /** Every object type named in `touched`, touched or neighbouring, once. */
247
+ readonly types: Readonly<Record<string, RelatedTypesObjectType>>;
248
+ /** Every relation named by an edge, once. */
249
+ readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
250
+ /** Touched types dropped to stay within the budget. */
251
+ readonly omitted_touched: number;
252
+ /** `true` when any type or edge was dropped for the budget. */
253
+ readonly truncated: boolean;
254
+ }
168
255
  export interface ReadResult {
169
256
  readonly trace_id: string | null;
170
257
  /** Deep link to this read's trace in the console; `null` if no console is configured. */
171
258
  readonly console_url: string | null;
259
+ /**
260
+ * The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
261
+ * prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
262
+ * says which of four answers the read gave:
263
+ *
264
+ * - rows — answered;
265
+ * - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
266
+ * `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
267
+ * matched nothing: every table and column it used exists, so the data is
268
+ * absent;
269
+ * - `null` — the schema provably cannot represent the concept. An answer in
270
+ * its own right, not a variant of the empty one: this memory cannot hold
271
+ * it, so a better-matching instance is worth trying;
272
+ * - no result at all — every sub-query's SQL failed, so nothing was
273
+ * answered. The read throws {@link XmemoryAPIError} with `status` 422 and
274
+ * `code` `"INVALID_INPUT"` rather than reporting an empty result.
275
+ *
276
+ * For a composite query this is the combined answer, folded from the parts:
277
+ * rows if any sub-query answered; else the empty result if any executed and
278
+ * matched nothing; else `null`. `reader_results` carries each part's own
279
+ * answer.
280
+ */
172
281
  readonly reader_result: unknown;
173
282
  /**
174
283
  * Per-sub-query answers when the server decomposed the query into independent
@@ -179,6 +288,14 @@ export interface ReadResult {
179
288
  * so the array is empty regardless of how many questions the query held.
180
289
  */
181
290
  readonly reader_results: readonly TaggedReaderResult[];
291
+ /**
292
+ * The schema around the answer, when the read asked for it with
293
+ * `includeRelatedTypes: "types"`; `null` otherwise. The wire omits the field
294
+ * unless it was requested, and a server that predates the option never sends
295
+ * it; the client normalizes both to `null`, so `null` means "not asked for" and
296
+ * a requested read that executed nothing arrives with `touched: []` instead.
297
+ */
298
+ readonly related_types: RelatedTypes | null;
182
299
  }
183
300
  export interface WriteResult {
184
301
  readonly write_id: string;
@@ -554,6 +671,14 @@ export interface ReadOptions {
554
671
  readMode?: ReadMode;
555
672
  /** Restrict the read to a set of concrete objects (plus optional relation traversal). */
556
673
  scope?: ReadScope;
674
+ /**
675
+ * `"types"` asks for {@link ReadResult.related_types}: the object types the read
676
+ * touched, the fields it did not return, and the object types a declared
677
+ * relation links them to. Left unset, nothing is sent and the server default
678
+ * (`"none"`) applies. Needs `instance.get_own` on the API key; see
679
+ * {@link RelatedTypesMode}.
680
+ */
681
+ includeRelatedTypes?: RelatedTypesMode;
557
682
  traceId?: string;
558
683
  timeoutMs?: number;
559
684
  }
@@ -0,0 +1,2 @@
1
+ /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
+ export declare const VERSION = "3.10.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.10.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,14 @@ 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;
233
235
  if (options?.traceId != null)
234
236
  body.trace_id = options.traceId;
235
237
  // 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.
238
+ // decomposition, and `related_types` unless the read asked for it, so type
239
+ // them as optional here and normalize (always-array, `null`) for the public
240
+ // `ReadResult` below.
238
241
  const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
239
242
  body,
240
243
  timeoutMs: options?.timeoutMs,
@@ -244,10 +247,15 @@ export class InstanceHandle {
244
247
  // by `Object.prototype` when the caller reads it.
245
248
  const readerResults = own(result, "reader_results");
246
249
  const traceId = own(result, "trace_id");
250
+ const relatedTypes = own(result, "related_types");
251
+ // `reader_result` is required on the wire and `null` is one of its answers (a
252
+ // refusal, in the tabular modes), so the coalescing only stands in for a field
253
+ // the server omitted; a `null` the server sent arrives as the same `null`.
247
254
  return withConsoleUrl({
248
255
  ...result,
249
256
  reader_result: own(result, "reader_result") ?? null,
250
257
  reader_results: Array.isArray(readerResults) ? readerResults : [],
258
+ related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
251
259
  trace_id: typeof traceId === "string" ? traceId : null,
252
260
  });
253
261
  }
@@ -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,112 @@ 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
+ /** One relation edge from a touched type to a neighbouring type; {@link RelatedTypes.types} describes both ends. */
194
+ export interface RelatedTypesLink {
195
+ /** The neighbouring object type, described once under `types`. */
196
+ readonly object_type: string;
197
+ /** The relation that links the two, described once under `relations`. */
198
+ readonly relation: string;
199
+ /** The relation role the touched type plays in this edge. */
200
+ readonly touched_role: string;
201
+ /** The relation role the neighbouring type plays in this edge. */
202
+ readonly related_role: string;
203
+ readonly cardinality: RelationCardinality;
204
+ }
205
+ /** One object type the read touched, with what it withheld and what it is linked to. */
206
+ export interface RelatedTypesTouched {
207
+ /** Object type name as declared in the schema, described under `types`. */
208
+ readonly object_type: string;
209
+ /**
210
+ * Fields of this type the read did not project. Ask for one by name to see it;
211
+ * an expression the reader could not attribute to a field counts here rather
212
+ * than as returned.
213
+ */
214
+ readonly fields_not_returned: readonly string[];
215
+ /** Relation edges to neighbouring types, sorted by relation then type. A self-relation lists one edge per role. */
216
+ readonly related: readonly RelatedTypesLink[];
217
+ /** Edges dropped from `related` to stay within the server's payload budget. */
218
+ readonly omitted_related: number;
219
+ }
220
+ /** Catalog entry for an object type named anywhere in {@link RelatedTypes.touched}. */
221
+ export interface RelatedTypesObjectType {
222
+ readonly description: string | null;
223
+ /** Declared primary-key fields, in declared order. */
224
+ readonly primary_key: readonly string[];
225
+ /** Every field of the object type, by name. */
226
+ readonly fields: readonly string[];
227
+ }
228
+ /** Catalog entry for a relation named by any edge. */
229
+ export interface RelatedTypesRelation {
230
+ readonly description: string | null;
231
+ }
232
+ /**
233
+ * What else the memory could answer about, for a read that asked with
234
+ * `includeRelatedTypes: "types"`: the object types the read touched, each with
235
+ * the fields it did not return and its relation edges, plus a catalog that
236
+ * describes every named type and relation exactly once. It is derived from the
237
+ * instance schema and the statements the read executed — no extra rows are
238
+ * read and no model is called — so an agent can phrase a deliberate follow-up
239
+ * read instead of guessing. The server caps the payload; whatever it dropped is
240
+ * counted on the entry it was dropped from, and `truncated` says that something
241
+ * was.
242
+ */
243
+ export interface RelatedTypes {
244
+ /** Object types the read touched, sorted by name. Empty when the read executed nothing. */
245
+ readonly touched: readonly RelatedTypesTouched[];
246
+ /** Every object type named in `touched`, touched or neighbouring, once. */
247
+ readonly types: Readonly<Record<string, RelatedTypesObjectType>>;
248
+ /** Every relation named by an edge, once. */
249
+ readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
250
+ /** Touched types dropped to stay within the budget. */
251
+ readonly omitted_touched: number;
252
+ /** `true` when any type or edge was dropped for the budget. */
253
+ readonly truncated: boolean;
254
+ }
168
255
  export interface ReadResult {
169
256
  readonly trace_id: string | null;
170
257
  /** Deep link to this read's trace in the console; `null` if no console is configured. */
171
258
  readonly console_url: string | null;
259
+ /**
260
+ * The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
261
+ * prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
262
+ * says which of four answers the read gave:
263
+ *
264
+ * - rows — answered;
265
+ * - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
266
+ * `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
267
+ * matched nothing: every table and column it used exists, so the data is
268
+ * absent;
269
+ * - `null` — the schema provably cannot represent the concept. An answer in
270
+ * its own right, not a variant of the empty one: this memory cannot hold
271
+ * it, so a better-matching instance is worth trying;
272
+ * - no result at all — every sub-query's SQL failed, so nothing was
273
+ * answered. The read throws {@link XmemoryAPIError} with `status` 422 and
274
+ * `code` `"INVALID_INPUT"` rather than reporting an empty result.
275
+ *
276
+ * For a composite query this is the combined answer, folded from the parts:
277
+ * rows if any sub-query answered; else the empty result if any executed and
278
+ * matched nothing; else `null`. `reader_results` carries each part's own
279
+ * answer.
280
+ */
172
281
  readonly reader_result: unknown;
173
282
  /**
174
283
  * Per-sub-query answers when the server decomposed the query into independent
@@ -179,6 +288,14 @@ export interface ReadResult {
179
288
  * so the array is empty regardless of how many questions the query held.
180
289
  */
181
290
  readonly reader_results: readonly TaggedReaderResult[];
291
+ /**
292
+ * The schema around the answer, when the read asked for it with
293
+ * `includeRelatedTypes: "types"`; `null` otherwise. The wire omits the field
294
+ * unless it was requested, and a server that predates the option never sends
295
+ * it; the client normalizes both to `null`, so `null` means "not asked for" and
296
+ * a requested read that executed nothing arrives with `touched: []` instead.
297
+ */
298
+ readonly related_types: RelatedTypes | null;
182
299
  }
183
300
  export interface WriteResult {
184
301
  readonly write_id: string;
@@ -554,6 +671,14 @@ export interface ReadOptions {
554
671
  readMode?: ReadMode;
555
672
  /** Restrict the read to a set of concrete objects (plus optional relation traversal). */
556
673
  scope?: ReadScope;
674
+ /**
675
+ * `"types"` asks for {@link ReadResult.related_types}: the object types the read
676
+ * touched, the fields it did not return, and the object types a declared
677
+ * relation links them to. Left unset, nothing is sent and the server default
678
+ * (`"none"`) applies. Needs `instance.get_own` on the API key; see
679
+ * {@link RelatedTypesMode}.
680
+ */
681
+ includeRelatedTypes?: RelatedTypesMode;
557
682
  traceId?: string;
558
683
  timeoutMs?: number;
559
684
  }
@@ -0,0 +1,2 @@
1
+ /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
+ export declare const VERSION = "3.10.0";
@@ -0,0 +1,2 @@
1
+ /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
+ export const VERSION = "3.10.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.8.3",
3
+ "version": "3.10.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"