xmemory 3.12.0 → 3.14.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
@@ -195,7 +195,7 @@ Every data operation — `read`, `write`, `writeAsync`, `writeStatus`, `extract`
195
195
  record, and `null` when the server has no console configured.
196
196
 
197
197
  Options: `{ extractionLogic?, diffEngine?, scope?, timeoutMs? }` — `extractionLogic`
198
- defaults to `"fast"`; see [Scoped writes](#scoped-writes) for `scope`.
198
+ defaults to `"fast"`; see [Scoped writes](#scoped-writes) for `scope` and its `mode`.
199
199
 
200
200
  Or pass a `WriteMutation[]` for **structured writes** — deterministic, LLM-free
201
201
  create/update/delete mutations applied in array order (later mutations may
@@ -225,7 +225,9 @@ Options for the mutations form: `{ timeoutMs? }` (extraction options don't apply
225
225
 
226
226
  Start an asynchronous write (same text / `WriteMutation[]` dual input and the
227
227
  same options as `inst.write`, `scope` included). Returns a `write_id` for
228
- tracking; a scope violation is reported by `inst.writeStatus` as a failed write.
228
+ tracking; under the default `"reject"` mode a scope violation is reported by
229
+ `inst.writeStatus` as a failed write, while under `"drop"` the write completes
230
+ and `inst.writeStatus` carries what it skipped.
229
231
 
230
232
  ```typescript
231
233
  const { write_id } = await inst.writeAsync("Carol manages the London office.");
@@ -238,8 +240,16 @@ Poll the status of an async write.
238
240
  ```typescript
239
241
  const status = await inst.writeStatus(write_id);
240
242
  console.log(status.write_status); // "queued" | "processing" | "completed" | "failed" | "not_found"
243
+ if (status.write_status === "completed") {
244
+ console.log(status.changes); // the same report inst.write returns inline
245
+ }
241
246
  ```
242
247
 
248
+ A finished write carries `changes`, the async path's only view of what the write
249
+ did — and where a [scoped write](#scoped-writes) in `"drop"` mode reports what it
250
+ left out. A status for a write that has not finished carries none, so the field
251
+ is optional.
252
+
243
253
  ### `inst.read(query, options?)` → `ReadResult`
244
254
 
245
255
  Query the instance.
@@ -249,7 +259,7 @@ const result = await inst.read("Who is on the team?");
249
259
  console.log(result.reader_result);
250
260
  ```
251
261
 
252
- Options: `{ readMode?, scope?, includeRelatedTypes?, relatedTypesDepth?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
262
+ Options: `{ readMode?, scope?, includeRelatedTypes?, relatedTypesDepth?, skipSuggestionCapture?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
253
263
 
254
264
  #### What comes back
255
265
 
@@ -389,12 +399,25 @@ types needs the
389
399
  endpoints need, on top of `data.read`: a key without it gets a 403 whose
390
400
  message names the permission, and the plain read is unaffected.
391
401
 
402
+ #### Keeping a read out of schema suggestions
403
+
404
+ Every read feeds the [suggestion engine](#suggestion-engine-flow-review--decide--apply):
405
+ after answering, the server asks a model whether the schema could fully answer
406
+ the question, and a gap becomes a proposed schema change. For programmatic reads
407
+ — high-volume polling, read-your-write checks — whose question does not reflect
408
+ what a person wants from the memory, pass `skipSuggestionCapture: true`. The
409
+ answer is the same; the read proposes nothing and costs no judge call.
410
+
411
+ ```typescript
412
+ const result = await inst.read("Does invoice INV-42 exist?", { skipSuggestionCapture: true });
413
+ ```
414
+
392
415
  #### Scoped writes
393
416
 
394
417
  A write is normally free to touch anything in the instance: the extractor sees
395
418
  the text alone, and whatever it produces is reconciled against the whole
396
- instance. Pass a `scope` to anchor a text write to a set of concrete existing
397
- objects instead — the same `ScopeObject` shape as a scoped read:
419
+ instance. Pass a `scope` to anchor a text write to a set of concrete objects
420
+ instead — the same `ScopeObject` shape as a scoped read:
398
421
 
399
422
  ```typescript
400
423
  const result = await inst.write(
@@ -403,19 +426,57 @@ const result = await inst.write(
403
426
  );
404
427
  ```
405
428
 
406
- This does two things at once. The scoped objects' **current values** are shown
407
- to the extractor, so the new information is folded into them instead of
408
- producing a near-duplicate record. And the write is then **confined** to the
409
- scope: it may only modify or delete the scoped objects, and create new objects
410
- and relations anchored to them. A write that would touch any other existing
411
- object fails with a validation error rather than applying partially — that
429
+ The write is **confined** to the scope: it may only modify or delete the scoped
430
+ objects, and create new objects and relations anchored to them. That
412
431
  confinement is checked against the resulting plan, so it holds regardless of
413
- what the extractor produced.
432
+ what the extractor produced. Extraction itself is unchanged by a scope — it
433
+ runs on the text alone, so the text still names the objects it means.
414
434
 
415
435
  A write scope takes the same `ScopeObject`s as a read scope, identified the same
416
436
  way. Unlike a read scope there is no `relationsScope`: the relations among the
417
437
  scoped objects always accompany the extraction hint.
418
438
 
439
+ **What becomes of a change that falls outside the scope is the scope's `mode`.**
440
+ By default (`mode: "reject"`) a write that would touch any other existing object
441
+ fails with a validation error rather than applying partially — the write is
442
+ all-or-nothing, and one stray sentence in the text costs you the whole thing.
443
+
444
+ Pass `mode: "drop"` and it applies anyway. The write runs the plan it would have
445
+ run unscoped, minus every out-of-scope change and every change that depended on
446
+ one, and reports what it left out on `changes.skipped_out_of_scope`:
447
+
448
+ ```typescript
449
+ const result = await inst.write(
450
+ "Alice Smith is a surgeon now, and her colleague Bob Lee moved to Rotterdam.",
451
+ {
452
+ scope: {
453
+ objects: [{ type: "Person", key: { full_name: "Alice Smith" } }],
454
+ mode: "drop",
455
+ },
456
+ },
457
+ );
458
+
459
+ for (const skipped of result.changes.skipped_out_of_scope ?? []) {
460
+ console.log(skipped.operation, skipped.object_type_name, skipped.identity, skipped.fields, skipped.count);
461
+ // "update" "Person" "" ["city"] 1
462
+ // ^ empty: the scope never named Bob Lee
463
+ }
464
+ ```
465
+
466
+ Dropping only ever *removes* changes. The write never gains a change it would
467
+ not otherwise have made, and never re-points one at a scoped record instead —
468
+ so `"drop"` narrows a write, it does not redirect it. Each entry stands for
469
+ `count` records of one `operation` (`"create"`, `"update"`, `"delete"`,
470
+ `"merge"`, `"link"` or `"unlink"`) on one type, and `identity` renders the
471
+ record's primary key as `field='value'` **only when the scope itself named that
472
+ record**; otherwise it is empty, meaning "some other record of this type". The
473
+ list is omitted when nothing was skipped, so treat `undefined` and `[]` alike.
474
+
475
+ Because a dropped write succeeds, this is also the mode that makes "create or
476
+ update exactly this record" expressible: under `"drop"` a scoped record need not
477
+ be stored yet, and the write creates it if it is missing. Under `"reject"` every
478
+ scoped record must already exist.
479
+
419
480
  Things to know before reaching for it:
420
481
 
421
482
  - Scope applies to **text writes only**. The `WriteMutation[]` overload takes
@@ -424,13 +485,23 @@ Things to know before reaching for it:
424
485
  anchor to.
425
486
  - Only objects of a type with a **user-defined primary key** can be scoped. A
426
487
  scope names records by that key, so a type declared `primary_key: []` has
427
- nothing to name its records by.
428
- - The server currently accepts a scope with **fast extraction only**, and caps
429
- the number of scoped objects per write. Both are server-side rules, so they
430
- surface as an `XmemoryAPIError`.
431
- - A scoped write additionally requires **read** permission on the instance,
432
- because the scoped objects' current values are shown to the extractor. An API
433
- key with write access alone is refused.
488
+ nothing to name its records by — and `"drop"` never creates a record of such a
489
+ type, for the same reason.
490
+ - `"drop"` is computed by the server's **diff engine**, so asking for it with
491
+ `diffEngine: false` is refused with a 400. `"reject"` has no such requirement.
492
+ - The server caps the number of scoped objects per write, and can have scoped
493
+ writes disabled entirely. Both are server-side rules, so they surface as an
494
+ `XmemoryAPIError`.
495
+ - A scoped write additionally requires **read** permission on the instance: the
496
+ response carries the previous value of every field the write changed,
497
+ resolving a scope answers whether each named object is stored, and a
498
+ drop-mode report says what the skipped changes would have written. An API key
499
+ with write access alone is refused.
500
+ - `mode` is sent only when it changes something: leaving it unset and setting it
501
+ to `"reject"` both put no `mode` on the wire, so naming the default for the
502
+ next reader keeps working against a server that predates the field. A server
503
+ that predates it rejects an unknown body field, so only send `"drop"` to one
504
+ that carries it.
434
505
 
435
506
  ### `inst.extract(text, options?)` → `ExtractResult`
436
507
 
@@ -8,9 +8,9 @@ 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
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
- export type { ScopeObject, ReadScope, WriteScope, RelationsScope } from "./types.js";
11
+ export type { ScopeObject, ReadScope, WriteScope, RelationsScope, WriteScopeMode } 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, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, 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, WriteChanges, SkippedOutOfScope, 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";
@@ -70,26 +70,42 @@ export declare class InstanceHandle {
70
70
  * `values` clears that field). `extractionLogic` / `diffEngine` only apply
71
71
  * to the text form.
72
72
  *
73
- * Pass `scope` — a `WriteScope` of concrete existing objects, each named by
74
- * its user-defined primary key — to anchor a text write to them. Their current
75
- * values are shown to the extractor so the write updates them instead of
76
- * creating duplicates, and the write is then confined to the scope: it may
77
- * only modify or delete the scoped objects and create new objects and
78
- * relations anchored to them. A write that would touch any other existing
79
- * object fails. The server accepts a scope with fast extraction only, and a
80
- * scoped write additionally requires read permission on the instance, because
81
- * the scoped objects' values are shown to the extractor.
73
+ * Pass `scope` — a `WriteScope` of concrete objects, each named by its
74
+ * user-defined primary key — to anchor a text write to them. The write is
75
+ * then confined to the scope: it may only modify or delete the scoped objects
76
+ * and create new objects and relations anchored to them. Extraction is
77
+ * unchanged by a scope — it runs on the text alone, so the text still names
78
+ * the objects it means.
79
+ *
80
+ * What becomes of a change that falls outside is the scope's `mode`. Under
81
+ * `"reject"` (the default) a write that would touch any other existing object
82
+ * fails, and nothing applies. Under `"drop"` that change is skipped — along
83
+ * with anything that depended on it — the rest applies, and what was left out
84
+ * comes back on `result.changes.skipped_out_of_scope`. `"drop"` also lets the
85
+ * write create a scoped record that is not stored yet, and is computed by the
86
+ * diff engine, so passing `diffEngine: false` with it is a 400.
87
+ *
88
+ * A scoped write additionally requires read permission on the instance: the
89
+ * response carries the previous value of every field the write changed,
90
+ * resolving a scope answers whether each named object is stored, and a
91
+ * drop-mode report says what the skipped changes would have written.
82
92
  */
83
93
  write(text: string, options?: WriteOptions): Promise<WriteResult>;
84
94
  write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
85
95
  /**
86
96
  * Submit a write job and return immediately with a `write_id` for polling.
87
97
  * Accepts the same text / `WriteMutation[]` dual input as {@link write}, and
88
- * the same `scope`. A scope violation is reported by {@link writeStatus} as a
89
- * failed write.
98
+ * the same `scope`. Under the default `"reject"` mode a scope violation is
99
+ * reported by {@link writeStatus} as a failed write; under `"drop"` the write
100
+ * completes, and what it skipped rides the completed status as `changes`.
90
101
  */
91
102
  writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
92
103
  writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
104
+ /**
105
+ * Poll a queued write. A finished one carries `changes` — the same report
106
+ * {@link write} returns inline, including what a `"drop"`-mode scope skipped;
107
+ * a status for a write that has not finished carries none.
108
+ */
93
109
  writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
94
110
  extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
95
111
  getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
@@ -36,7 +36,15 @@ function buildWriteBody(input, options) {
36
36
  if (options?.diffEngine != null)
37
37
  body.use_diff_engine = options.diffEngine;
38
38
  if (options?.scope != null) {
39
- body.scope = { objects: serializeScopeObjects(options.scope.objects) };
39
+ const scope = { objects: serializeScopeObjects(options.scope.objects) };
40
+ // Only a mode that changes something is sent. The server omits `mode` at its
41
+ // default, so a scope that does not ask for `"drop"` stays byte-identical for a
42
+ // server that predates the field — a caller who spells the default out for the
43
+ // next reader does not thereby require a newer deployment.
44
+ if (options.scope.mode != null && options.scope.mode !== "reject") {
45
+ scope.mode = options.scope.mode;
46
+ }
47
+ body.scope = scope;
40
48
  }
41
49
  return body;
42
50
  }
@@ -238,6 +246,8 @@ class InstanceHandle {
238
246
  body.include_related_types = options.includeRelatedTypes;
239
247
  if (options?.relatedTypesDepth != null)
240
248
  body.related_types_depth = options.relatedTypesDepth;
249
+ if (options?.skipSuggestionCapture)
250
+ body.skip_suggestion_capture = true;
241
251
  if (options?.traceId != null)
242
252
  body.trace_id = options.traceId;
243
253
  // The wire shape omits `reader_results` on a server without question
@@ -278,6 +288,11 @@ class InstanceHandle {
278
288
  const traceId = own(result, "trace_id");
279
289
  return withConsoleUrl({ ...result, trace_id: typeof traceId === "string" ? traceId : null });
280
290
  }
291
+ /**
292
+ * Poll a queued write. A finished one carries `changes` — the same report
293
+ * {@link write} returns inline, including what a `"drop"`-mode scope skipped;
294
+ * a status for a write that has not finished carries none.
295
+ */
281
296
  async writeStatus(writeId, options) {
282
297
  return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
283
298
  }
@@ -47,15 +47,48 @@ export interface ReadScope {
47
47
  relationsScope?: RelationsScope;
48
48
  }
49
49
  /**
50
- * A write's scope: the concrete existing `objects` the write is anchored to.
51
- * Their current values are shown to the extractor so the write updates them
52
- * instead of creating duplicates, and the write is then confined to them — it
50
+ * What a scoped write does with a change that falls outside its scope.
51
+ *
52
+ * `"reject"` — the server's default — is all-or-nothing: a plan that would
53
+ * touch anything outside the scope fails the whole write, and nothing applies.
54
+ *
55
+ * `"drop"` applies the rest. The write runs the plan it would have run
56
+ * unscoped, minus every out-of-scope change and every change that depended on
57
+ * one, and reports what it left out as
58
+ * {@link WriteChanges.skipped_out_of_scope}. It only ever removes changes: it
59
+ * never adds one and never re-targets one at a scoped record, so `"drop"`
60
+ * narrows a write rather than redirecting it.
61
+ *
62
+ * Two further differences from `"reject"`. A scoped record need not be stored
63
+ * yet — `"drop"` may create a record whose primary key the scope names, which
64
+ * is what makes "create or update exactly this record" expressible, while
65
+ * `"reject"` requires every scoped record to exist already. And a type that
66
+ * declares no user-defined primary key is never created under `"drop"`, since
67
+ * a scope has no way to name such a record. `"drop"` is computed by the
68
+ * server's diff engine, so pairing it with `diffEngine: false` is a 400.
69
+ */
70
+ export type WriteScopeMode = "reject" | "drop";
71
+ /**
72
+ * A write's scope: the concrete `objects` the write is anchored to, and what to
73
+ * do with a change that falls outside them. The write is confined to them — it
53
74
  * may only modify or delete the scoped objects and create new objects and
54
- * relations anchored to them. Unlike `ReadScope` there is no relation policy:
55
- * the relations among the scoped objects always accompany the hint.
75
+ * relations anchored to them. Extraction is unchanged by a scope: it runs on
76
+ * the text alone, so the text still names the objects it means.
77
+ *
78
+ * Unlike `ReadScope`, the second field is not a relation policy: relation
79
+ * changes follow the confinement rule, and there is nothing to choose. It is
80
+ * the out-of-scope `mode`, which decides whether the write fails or reports
81
+ * what it skipped.
56
82
  */
57
83
  export interface WriteScope {
58
84
  objects: ScopeObject[];
85
+ /**
86
+ * `"reject"` by default. Left unset — or set to `"reject"` — nothing is sent,
87
+ * so naming the default for the reader's sake still leaves the request
88
+ * byte-identical for a server that predates the field. See
89
+ * {@link WriteScopeMode}.
90
+ */
91
+ mode?: WriteScopeMode;
59
92
  }
60
93
  export type WriteQueueStatus = "queued" | "processing" | "extracting" | "extracted" | "applying" | "completed" | "failed" | "not_found";
61
94
  export declare class XmemoryAPIError extends Error {
@@ -344,13 +377,66 @@ export interface ReadResult {
344
377
  */
345
378
  readonly related_types: RelatedTypes | null;
346
379
  }
380
+ /**
381
+ * One bundle of changes a `"drop"`-mode scoped write left out instead of
382
+ * applying: one operation on one type, standing for `count` records.
383
+ */
384
+ export interface SkippedOutOfScope {
385
+ /**
386
+ * What the skipped changes would have done. `"link"` / `"unlink"` are
387
+ * relation changes, the rest object ones.
388
+ *
389
+ * Widened with `(string & {})` like the advisory values further down this
390
+ * file, so an operation named by a server newer than this release is still
391
+ * typed rather than rejected. One you do not recognise still means the same
392
+ * thing — something was skipped — so report it rather than dropping the entry.
393
+ */
394
+ readonly operation: "create" | "update" | "delete" | "merge" | "link" | "unlink" | (string & {});
395
+ /** The object type, or the relation type for `"link"` / `"unlink"`. */
396
+ readonly object_type_name: string;
397
+ /**
398
+ * The skipped record's primary key, rendered `field='value'` — and **empty
399
+ * unless the scope itself named that record**. The server identifies a record
400
+ * here only when the caller already knew of it, so an empty string reads as
401
+ * "some other record of this type", not as "a record with no key".
402
+ */
403
+ readonly identity: string;
404
+ /** The field names the skipped changes would have written. */
405
+ readonly fields: readonly string[];
406
+ /** How many records this entry stands for. */
407
+ readonly count: number;
408
+ }
409
+ /**
410
+ * What a write did, grouped into `created` / `updated` / `deleted`, plus what a
411
+ * `"drop"`-mode scope left out.
412
+ *
413
+ * The three groups stay `unknown`: their shape is the server's to evolve and
414
+ * this client has never modelled it. `skipped_out_of_scope` is typed because it
415
+ * is the one part a caller has to branch on — a `"drop"`-mode write succeeds
416
+ * whether or not it skipped anything, so this list is the only report that some
417
+ * of what the text said was not applied.
418
+ */
419
+ export interface WriteChanges {
420
+ readonly created: unknown;
421
+ readonly updated: unknown;
422
+ readonly deleted: unknown;
423
+ /**
424
+ * Omitted by the server when nothing was skipped — which is every write that
425
+ * did not ask for `"drop"` — so `undefined` and `[]` both mean "nothing left
426
+ * out". Branch on whether there are entries, not on whether the key is there.
427
+ */
428
+ readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
429
+ }
347
430
  export interface WriteResult {
348
431
  readonly write_id: string;
349
432
  readonly trace_id: string | null;
350
433
  /** Deep link to this write's trace in the console; `null` if no console is configured. */
351
434
  readonly console_url: string | null;
352
- /** What the write did, grouped into `created` / `updated` / `deleted`. */
353
- readonly changes: unknown;
435
+ /**
436
+ * What the write did, grouped into `created` / `updated` / `deleted`, and —
437
+ * for a scoped write in `"drop"` mode — what it skipped instead of applying.
438
+ */
439
+ readonly changes: WriteChanges;
354
440
  }
355
441
  export interface AsyncWriteResult {
356
442
  readonly write_id: string;
@@ -366,6 +452,17 @@ export interface WriteStatusResult {
366
452
  readonly console_url: string | null;
367
453
  readonly error_detail: string | null;
368
454
  readonly completed_at: string | null;
455
+ /**
456
+ * What the finished write did, in the same shape {@link WriteResult.changes}
457
+ * carries — and the async caller's only view of it, since `writeAsync`
458
+ * returns before the write has done anything. It is therefore where a
459
+ * `"drop"`-mode scope reports what it skipped.
460
+ *
461
+ * Optional because a status is not always about a finished write: a queued,
462
+ * in-progress, failed or unknown `write_id` carries none. Read it once
463
+ * `write_status` is `"completed"`.
464
+ */
465
+ readonly changes?: WriteChanges;
369
466
  }
370
467
  export interface ExtractResult {
371
468
  readonly trace_id: string | null;
@@ -734,6 +831,14 @@ export interface ReadOptions {
734
831
  * serves one level; a value out of range is a 422.
735
832
  */
736
833
  relatedTypesDepth?: number;
834
+ /**
835
+ * `true` keeps this read out of the suggestion engine: the server skips the
836
+ * post-read completeness judge, so the read proposes no schema change and costs
837
+ * no judge model call. Meant for programmatic reads — high-volume polling,
838
+ * read-your-write checks — whose question does not reflect what a person
839
+ * wants from the memory. Left unset, nothing is sent and the read is judged.
840
+ */
841
+ skipSuggestionCapture?: boolean;
737
842
  traceId?: string;
738
843
  timeoutMs?: number;
739
844
  }
@@ -1,2 +1,2 @@
1
1
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
- export declare const VERSION = "3.12.0";
2
+ export declare const VERSION = "3.14.0";
@@ -2,4 +2,4 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
4
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
5
- exports.VERSION = "3.12.0";
5
+ exports.VERSION = "3.14.0";
@@ -8,9 +8,9 @@ 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
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
- export type { ScopeObject, ReadScope, WriteScope, RelationsScope } from "./types.js";
11
+ export type { ScopeObject, ReadScope, WriteScope, RelationsScope, WriteScopeMode } 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, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, 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, WriteChanges, SkippedOutOfScope, 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";
@@ -70,26 +70,42 @@ export declare class InstanceHandle {
70
70
  * `values` clears that field). `extractionLogic` / `diffEngine` only apply
71
71
  * to the text form.
72
72
  *
73
- * Pass `scope` — a `WriteScope` of concrete existing objects, each named by
74
- * its user-defined primary key — to anchor a text write to them. Their current
75
- * values are shown to the extractor so the write updates them instead of
76
- * creating duplicates, and the write is then confined to the scope: it may
77
- * only modify or delete the scoped objects and create new objects and
78
- * relations anchored to them. A write that would touch any other existing
79
- * object fails. The server accepts a scope with fast extraction only, and a
80
- * scoped write additionally requires read permission on the instance, because
81
- * the scoped objects' values are shown to the extractor.
73
+ * Pass `scope` — a `WriteScope` of concrete objects, each named by its
74
+ * user-defined primary key — to anchor a text write to them. The write is
75
+ * then confined to the scope: it may only modify or delete the scoped objects
76
+ * and create new objects and relations anchored to them. Extraction is
77
+ * unchanged by a scope — it runs on the text alone, so the text still names
78
+ * the objects it means.
79
+ *
80
+ * What becomes of a change that falls outside is the scope's `mode`. Under
81
+ * `"reject"` (the default) a write that would touch any other existing object
82
+ * fails, and nothing applies. Under `"drop"` that change is skipped — along
83
+ * with anything that depended on it — the rest applies, and what was left out
84
+ * comes back on `result.changes.skipped_out_of_scope`. `"drop"` also lets the
85
+ * write create a scoped record that is not stored yet, and is computed by the
86
+ * diff engine, so passing `diffEngine: false` with it is a 400.
87
+ *
88
+ * A scoped write additionally requires read permission on the instance: the
89
+ * response carries the previous value of every field the write changed,
90
+ * resolving a scope answers whether each named object is stored, and a
91
+ * drop-mode report says what the skipped changes would have written.
82
92
  */
83
93
  write(text: string, options?: WriteOptions): Promise<WriteResult>;
84
94
  write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
85
95
  /**
86
96
  * Submit a write job and return immediately with a `write_id` for polling.
87
97
  * Accepts the same text / `WriteMutation[]` dual input as {@link write}, and
88
- * the same `scope`. A scope violation is reported by {@link writeStatus} as a
89
- * failed write.
98
+ * the same `scope`. Under the default `"reject"` mode a scope violation is
99
+ * reported by {@link writeStatus} as a failed write; under `"drop"` the write
100
+ * completes, and what it skipped rides the completed status as `changes`.
90
101
  */
91
102
  writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
92
103
  writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
104
+ /**
105
+ * Poll a queued write. A finished one carries `changes` — the same report
106
+ * {@link write} returns inline, including what a `"drop"`-mode scope skipped;
107
+ * a status for a write that has not finished carries none.
108
+ */
93
109
  writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
94
110
  extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
95
111
  getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
@@ -33,7 +33,15 @@ function buildWriteBody(input, options) {
33
33
  if (options?.diffEngine != null)
34
34
  body.use_diff_engine = options.diffEngine;
35
35
  if (options?.scope != null) {
36
- body.scope = { objects: serializeScopeObjects(options.scope.objects) };
36
+ const scope = { objects: serializeScopeObjects(options.scope.objects) };
37
+ // Only a mode that changes something is sent. The server omits `mode` at its
38
+ // default, so a scope that does not ask for `"drop"` stays byte-identical for a
39
+ // server that predates the field — a caller who spells the default out for the
40
+ // next reader does not thereby require a newer deployment.
41
+ if (options.scope.mode != null && options.scope.mode !== "reject") {
42
+ scope.mode = options.scope.mode;
43
+ }
44
+ body.scope = scope;
37
45
  }
38
46
  return body;
39
47
  }
@@ -234,6 +242,8 @@ export class InstanceHandle {
234
242
  body.include_related_types = options.includeRelatedTypes;
235
243
  if (options?.relatedTypesDepth != null)
236
244
  body.related_types_depth = options.relatedTypesDepth;
245
+ if (options?.skipSuggestionCapture)
246
+ body.skip_suggestion_capture = true;
237
247
  if (options?.traceId != null)
238
248
  body.trace_id = options.traceId;
239
249
  // The wire shape omits `reader_results` on a server without question
@@ -274,6 +284,11 @@ export class InstanceHandle {
274
284
  const traceId = own(result, "trace_id");
275
285
  return withConsoleUrl({ ...result, trace_id: typeof traceId === "string" ? traceId : null });
276
286
  }
287
+ /**
288
+ * Poll a queued write. A finished one carries `changes` — the same report
289
+ * {@link write} returns inline, including what a `"drop"`-mode scope skipped;
290
+ * a status for a write that has not finished carries none.
291
+ */
277
292
  async writeStatus(writeId, options) {
278
293
  return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
279
294
  }
@@ -47,15 +47,48 @@ export interface ReadScope {
47
47
  relationsScope?: RelationsScope;
48
48
  }
49
49
  /**
50
- * A write's scope: the concrete existing `objects` the write is anchored to.
51
- * Their current values are shown to the extractor so the write updates them
52
- * instead of creating duplicates, and the write is then confined to them — it
50
+ * What a scoped write does with a change that falls outside its scope.
51
+ *
52
+ * `"reject"` — the server's default — is all-or-nothing: a plan that would
53
+ * touch anything outside the scope fails the whole write, and nothing applies.
54
+ *
55
+ * `"drop"` applies the rest. The write runs the plan it would have run
56
+ * unscoped, minus every out-of-scope change and every change that depended on
57
+ * one, and reports what it left out as
58
+ * {@link WriteChanges.skipped_out_of_scope}. It only ever removes changes: it
59
+ * never adds one and never re-targets one at a scoped record, so `"drop"`
60
+ * narrows a write rather than redirecting it.
61
+ *
62
+ * Two further differences from `"reject"`. A scoped record need not be stored
63
+ * yet — `"drop"` may create a record whose primary key the scope names, which
64
+ * is what makes "create or update exactly this record" expressible, while
65
+ * `"reject"` requires every scoped record to exist already. And a type that
66
+ * declares no user-defined primary key is never created under `"drop"`, since
67
+ * a scope has no way to name such a record. `"drop"` is computed by the
68
+ * server's diff engine, so pairing it with `diffEngine: false` is a 400.
69
+ */
70
+ export type WriteScopeMode = "reject" | "drop";
71
+ /**
72
+ * A write's scope: the concrete `objects` the write is anchored to, and what to
73
+ * do with a change that falls outside them. The write is confined to them — it
53
74
  * may only modify or delete the scoped objects and create new objects and
54
- * relations anchored to them. Unlike `ReadScope` there is no relation policy:
55
- * the relations among the scoped objects always accompany the hint.
75
+ * relations anchored to them. Extraction is unchanged by a scope: it runs on
76
+ * the text alone, so the text still names the objects it means.
77
+ *
78
+ * Unlike `ReadScope`, the second field is not a relation policy: relation
79
+ * changes follow the confinement rule, and there is nothing to choose. It is
80
+ * the out-of-scope `mode`, which decides whether the write fails or reports
81
+ * what it skipped.
56
82
  */
57
83
  export interface WriteScope {
58
84
  objects: ScopeObject[];
85
+ /**
86
+ * `"reject"` by default. Left unset — or set to `"reject"` — nothing is sent,
87
+ * so naming the default for the reader's sake still leaves the request
88
+ * byte-identical for a server that predates the field. See
89
+ * {@link WriteScopeMode}.
90
+ */
91
+ mode?: WriteScopeMode;
59
92
  }
60
93
  export type WriteQueueStatus = "queued" | "processing" | "extracting" | "extracted" | "applying" | "completed" | "failed" | "not_found";
61
94
  export declare class XmemoryAPIError extends Error {
@@ -344,13 +377,66 @@ export interface ReadResult {
344
377
  */
345
378
  readonly related_types: RelatedTypes | null;
346
379
  }
380
+ /**
381
+ * One bundle of changes a `"drop"`-mode scoped write left out instead of
382
+ * applying: one operation on one type, standing for `count` records.
383
+ */
384
+ export interface SkippedOutOfScope {
385
+ /**
386
+ * What the skipped changes would have done. `"link"` / `"unlink"` are
387
+ * relation changes, the rest object ones.
388
+ *
389
+ * Widened with `(string & {})` like the advisory values further down this
390
+ * file, so an operation named by a server newer than this release is still
391
+ * typed rather than rejected. One you do not recognise still means the same
392
+ * thing — something was skipped — so report it rather than dropping the entry.
393
+ */
394
+ readonly operation: "create" | "update" | "delete" | "merge" | "link" | "unlink" | (string & {});
395
+ /** The object type, or the relation type for `"link"` / `"unlink"`. */
396
+ readonly object_type_name: string;
397
+ /**
398
+ * The skipped record's primary key, rendered `field='value'` — and **empty
399
+ * unless the scope itself named that record**. The server identifies a record
400
+ * here only when the caller already knew of it, so an empty string reads as
401
+ * "some other record of this type", not as "a record with no key".
402
+ */
403
+ readonly identity: string;
404
+ /** The field names the skipped changes would have written. */
405
+ readonly fields: readonly string[];
406
+ /** How many records this entry stands for. */
407
+ readonly count: number;
408
+ }
409
+ /**
410
+ * What a write did, grouped into `created` / `updated` / `deleted`, plus what a
411
+ * `"drop"`-mode scope left out.
412
+ *
413
+ * The three groups stay `unknown`: their shape is the server's to evolve and
414
+ * this client has never modelled it. `skipped_out_of_scope` is typed because it
415
+ * is the one part a caller has to branch on — a `"drop"`-mode write succeeds
416
+ * whether or not it skipped anything, so this list is the only report that some
417
+ * of what the text said was not applied.
418
+ */
419
+ export interface WriteChanges {
420
+ readonly created: unknown;
421
+ readonly updated: unknown;
422
+ readonly deleted: unknown;
423
+ /**
424
+ * Omitted by the server when nothing was skipped — which is every write that
425
+ * did not ask for `"drop"` — so `undefined` and `[]` both mean "nothing left
426
+ * out". Branch on whether there are entries, not on whether the key is there.
427
+ */
428
+ readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
429
+ }
347
430
  export interface WriteResult {
348
431
  readonly write_id: string;
349
432
  readonly trace_id: string | null;
350
433
  /** Deep link to this write's trace in the console; `null` if no console is configured. */
351
434
  readonly console_url: string | null;
352
- /** What the write did, grouped into `created` / `updated` / `deleted`. */
353
- readonly changes: unknown;
435
+ /**
436
+ * What the write did, grouped into `created` / `updated` / `deleted`, and —
437
+ * for a scoped write in `"drop"` mode — what it skipped instead of applying.
438
+ */
439
+ readonly changes: WriteChanges;
354
440
  }
355
441
  export interface AsyncWriteResult {
356
442
  readonly write_id: string;
@@ -366,6 +452,17 @@ export interface WriteStatusResult {
366
452
  readonly console_url: string | null;
367
453
  readonly error_detail: string | null;
368
454
  readonly completed_at: string | null;
455
+ /**
456
+ * What the finished write did, in the same shape {@link WriteResult.changes}
457
+ * carries — and the async caller's only view of it, since `writeAsync`
458
+ * returns before the write has done anything. It is therefore where a
459
+ * `"drop"`-mode scope reports what it skipped.
460
+ *
461
+ * Optional because a status is not always about a finished write: a queued,
462
+ * in-progress, failed or unknown `write_id` carries none. Read it once
463
+ * `write_status` is `"completed"`.
464
+ */
465
+ readonly changes?: WriteChanges;
369
466
  }
370
467
  export interface ExtractResult {
371
468
  readonly trace_id: string | null;
@@ -734,6 +831,14 @@ export interface ReadOptions {
734
831
  * serves one level; a value out of range is a 422.
735
832
  */
736
833
  relatedTypesDepth?: number;
834
+ /**
835
+ * `true` keeps this read out of the suggestion engine: the server skips the
836
+ * post-read completeness judge, so the read proposes no schema change and costs
837
+ * no judge model call. Meant for programmatic reads — high-volume polling,
838
+ * read-your-write checks — whose question does not reflect what a person
839
+ * wants from the memory. Left unset, nothing is sent and the read is judged.
840
+ */
841
+ skipSuggestionCapture?: boolean;
737
842
  traceId?: string;
738
843
  timeoutMs?: number;
739
844
  }
@@ -1,2 +1,2 @@
1
1
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
- export declare const VERSION = "3.12.0";
2
+ export declare const VERSION = "3.14.0";
@@ -1,2 +1,2 @@
1
1
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
- export const VERSION = "3.12.0";
2
+ export const VERSION = "3.14.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.12.0",
3
+ "version": "3.14.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"