xmemory 3.17.0 → 3.20.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
@@ -247,8 +247,8 @@ if (status.write_status === "completed") {
247
247
 
248
248
  A finished write carries `changes`, the async path's only view of what the write
249
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.
250
+ left out, and a [field merge](#mergeable-text-fields) what it chose between. A
251
+ status for a write that has not finished carries none, so the field is optional.
252
252
 
253
253
  ### Write ordering
254
254
 
@@ -283,6 +283,57 @@ await inst.write([
283
283
  ]);
284
284
  ```
285
285
 
286
+ ### Mergeable text fields
287
+
288
+ By default a write replaces a field's stored value. A `str` field that is not
289
+ part of the primary key can instead declare a `merge` in the schema, so a later
290
+ text write merges its value into the text already stored. A server from before
291
+ field merges keeps the block but ignores it, and replaces the value as before:
292
+
293
+ ```yaml
294
+ next_steps:
295
+ type: str
296
+ description: what is still to be done on the project, one step per line
297
+ merge:
298
+ rules:
299
+ - Keep every step that is still open.
300
+ - Drop a step the text says is done.
301
+ max_length: 400
302
+ ```
303
+
304
+ - `max_length` is required, a whole number from 1 to 20,000: the length the
305
+ merge keeps the text within. `rules` is optional: up to 50 non-empty lines of
306
+ at most 1,000 characters each. `merge` takes no other key, and a schema that
307
+ breaks any of this is refused.
308
+ - With `rules`, the server merges the new value into the stored one by those
309
+ rules, within the cap.
310
+ - Without `rules`, the new value is appended on its own line, leaving out lines
311
+ whose facts are already stated; past the cap, the text is shortened, keeping
312
+ every fact.
313
+ - If a merge cannot be made, the new value is appended, even past the cap, and
314
+ nothing stored is cut.
315
+ - Only text writes merge, through the server's diff engine. A text write that
316
+ runs without it on such a schema — `diffEngine: false`, or a connection whose
317
+ default is off — is refused with a 400 `VALIDATION_ERROR`; through
318
+ `writeAsync` it is queued and fails, which `writeStatus` reports.
319
+ `WriteMutation[]` writes replace the value as given.
320
+ - Adding, changing or removing a `merge` is a metadata-only schema change.
321
+
322
+ Where a merge that changed the field found the new value contradicting the
323
+ stored one, `changes.merge_contradictions` says what each said and which one it
324
+ kept (`FieldMergeContradiction`):
325
+
326
+ ```typescript
327
+ const result = await inst.write("The Harbour Wall survey moved to 10 March.");
328
+ for (const c of result.changes.merge_contradictions ?? []) {
329
+ console.log(c.object_type_name, c.identity, c.field, c.stored, "->", c.new, "kept:", c.kept);
330
+ }
331
+ ```
332
+
333
+ The key is omitted when there is no such entry. An absent key does not prove the
334
+ texts agreed: a merge that failed, fell back to appending, or left the stored
335
+ text unchanged reports none.
336
+
286
337
  ### `inst.read(query, options?)` → `ReadResult`
287
338
 
288
339
  Query the instance.
@@ -667,8 +718,8 @@ const xm = new XmemoryClient({ apiKey: "..." });
667
718
  const current = (await xm.admin.getInstanceSchema("<instance-id>")).data_schema;
668
719
 
669
720
  // 1. Enhance — new schema + an executor-ready migration plan.
670
- const enhanced = await xm.admin.enhanceSchema(
671
- "<cluster-id>",
721
+ const enhanced = await xm.admin.enhanceInstanceSchema(
722
+ "<instance-id>",
672
723
  "Rename Person.mail to Person.email.",
673
724
  yaml.dump(current),
674
725
  );
@@ -690,6 +741,11 @@ const info = await xm.admin.updateInstanceSchema("<instance-id>", newYaml, Schem
690
741
  console.log(info.migration_id, info.prior_version, "->", info.new_version);
691
742
  ```
692
743
 
744
+ `enhanceInstanceSchema` runs on the model the instance is configured to use. To
745
+ enhance a schema not tied to an instance, call
746
+ `xm.admin.enhanceSchema("<cluster-id>", description, currentYaml)`, which runs
747
+ on the cluster's model.
748
+
693
749
  ### Migration history
694
750
 
695
751
  ```typescript
@@ -77,7 +77,21 @@ export interface AdminNamespace {
77
77
  */
78
78
  patchInstanceMetadata(instanceId: string, options?: PatchInstanceMetadataOptions): Promise<InstanceInfo>;
79
79
  generateSchema(clusterId: string, schemaDescription: string, options?: GenerateSchemaOptions): Promise<GenerateSchemaResult>;
80
+ /**
81
+ * Evolve a schema not tied to an instance, on the cluster's model. To evolve
82
+ * an instance's schema, use `enhanceInstanceSchema`.
83
+ */
80
84
  enhanceSchema(clusterId: string, schemaDescription: string, currentYmlSchema: string, options?: RequestOptions): Promise<EnhanceSchemaResult>;
85
+ /**
86
+ * Evolve an instance's schema, returning the new schema and a migration plan.
87
+ *
88
+ * Pass the instance's current YAML schema plus a description of the change
89
+ * you want; nothing is applied. It runs on the model the instance is
90
+ * configured to use. The result's `migration_plan` is executor-ready: hand it
91
+ * to `dryRunMigration` to preview the DDL, then to `updateInstanceSchema` to
92
+ * apply it.
93
+ */
94
+ enhanceInstanceSchema(instanceId: string, schemaDescription: string, currentYmlSchema: string, options?: RequestOptions): Promise<EnhanceSchemaResult>;
81
95
  dryRunMigration(instanceId: string, schemaText: string, schemaType: SchemaTypeValue, options?: DryRunMigrationOptions): Promise<DryRunResult>;
82
96
  listMigrations(instanceId: string, options?: ListMigrationsOptions): Promise<ListMigrationsResult>;
83
97
  getMigration(instanceId: string, migrationId: string, options?: GetMigrationOptions): Promise<MigrationRecord>;
@@ -425,6 +425,12 @@ class XmemoryClient {
425
425
  timeoutMs: options?.timeoutMs,
426
426
  });
427
427
  },
428
+ enhanceInstanceSchema: async (instanceId, schemaDescription, currentYmlSchema, options) => {
429
+ return this._requestOne("POST", `/instances/${instanceId}/schema/enhance`, {
430
+ body: { schema_description: schemaDescription, current_yml_schema: currentYmlSchema },
431
+ timeoutMs: options?.timeoutMs,
432
+ });
433
+ },
428
434
  dryRunMigration: async (instanceId, schemaText, schemaType, options) => {
429
435
  const body = {
430
436
  instance_schema: (0, types_js_1.buildInstanceSchema)(schemaText, schemaType),
@@ -10,7 +10,7 @@ export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from
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
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, WriteChanges, SkippedOutOfScope, 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, FieldMergeContradiction, 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";
@@ -85,6 +85,11 @@ export declare class InstanceHandle {
85
85
  * write create a scoped record that is not stored yet, and is computed by the
86
86
  * diff engine, so passing `diffEngine: false` with it is a 400.
87
87
  *
88
+ * A text write on a schema with a `merge` field also needs the diff engine:
89
+ * with the engine off, by `diffEngine: false` or by the connection's default,
90
+ * it is refused with a 400 `VALIDATION_ERROR`; a {@link writeAsync} one is
91
+ * queued and fails, which {@link writeStatus} reports.
92
+ *
88
93
  * A scoped write additionally requires read permission on the instance: the
89
94
  * response carries the previous value of every field the write changed,
90
95
  * resolving a scope answers whether each named object is stored, and a
@@ -114,8 +119,9 @@ export declare class InstanceHandle {
114
119
  writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
115
120
  /**
116
121
  * Poll a queued write. A finished one carries `changes` — the same report
117
- * {@link write} returns inline, including what a `"drop"`-mode scope skipped;
118
- * a status for a write that has not finished carries none.
122
+ * {@link write} returns inline, including what a `"drop"`-mode scope skipped
123
+ * and what a field merge chose between; a status for a write that has not
124
+ * finished carries none.
119
125
  */
120
126
  writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
121
127
  extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
@@ -298,8 +298,9 @@ class InstanceHandle {
298
298
  }
299
299
  /**
300
300
  * Poll a queued write. A finished one carries `changes` — the same report
301
- * {@link write} returns inline, including what a `"drop"`-mode scope skipped;
302
- * a status for a write that has not finished carries none.
301
+ * {@link write} returns inline, including what a `"drop"`-mode scope skipped
302
+ * and what a field merge chose between; a status for a write that has not
303
+ * finished carries none.
303
304
  */
304
305
  async writeStatus(writeId, options) {
305
306
  return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
@@ -455,15 +455,49 @@ export interface SkippedOutOfScope {
455
455
  */
456
456
  readonly folded?: boolean;
457
457
  }
458
+ /**
459
+ * One contradiction a text field's merge resolved: what the stored value said,
460
+ * what the write's value said, and which of the two the merged value keeps.
461
+ *
462
+ * Only a `str` field whose schema declares a `merge` produces these. A later
463
+ * text write merges its value into the stored text instead of replacing it,
464
+ * and where the two disagreed about the same thing, the merge kept one.
465
+ */
466
+ export interface FieldMergeContradiction {
467
+ /** The object type of the record whose field merged. */
468
+ readonly object_type_name: string;
469
+ /**
470
+ * The record's primary key, rendered `field='value'` (a composite key's parts
471
+ * comma-separated); empty for a record that has no key or is missing part of
472
+ * it.
473
+ */
474
+ readonly identity: string;
475
+ /** The field that merged. */
476
+ readonly field: string;
477
+ /** What the stored value said, as the merge quoted it, cut to 300 characters. */
478
+ readonly stored: string;
479
+ /**
480
+ * What the write's value said (or that of a record the write merged into
481
+ * this one), as the merge quoted it, cut to 300 characters.
482
+ */
483
+ readonly new: string;
484
+ /**
485
+ * Which of the two the merged value keeps. Widened with `(string & {})` like
486
+ * {@link SkippedOutOfScope.operation}, so a value named by a server newer
487
+ * than this release is still typed rather than rejected.
488
+ */
489
+ readonly kept: "stored" | "new" | (string & {});
490
+ }
458
491
  /**
459
492
  * What a write did, grouped into `created` / `updated` / `deleted`, plus what a
460
- * `"drop"`-mode scope left out.
493
+ * `"drop"`-mode scope left out and the contradictions a field merge resolved.
461
494
  *
462
495
  * The three groups stay `unknown`: their shape is the server's to evolve and
463
496
  * this client has never modelled it. `skipped_out_of_scope` is typed because it
464
497
  * is the one part a caller has to branch on — a `"drop"`-mode write succeeds
465
498
  * whether or not it skipped anything, so this list is the only report that some
466
- * of what the text said was not applied.
499
+ * of what the text said was not applied. `merge_contradictions` is typed because
500
+ * it is the only report of what a merge chose between.
467
501
  */
468
502
  export interface WriteChanges {
469
503
  readonly created: unknown;
@@ -478,6 +512,14 @@ export interface WriteChanges {
478
512
  * {@link SkippedOutOfScope.folded}).
479
513
  */
480
514
  readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
515
+ /**
516
+ * The contradictions a merge reported for a field the write changed.
517
+ * Advisory: the write landed either way. Omitted by the server when there is
518
+ * none, and by a server that predates field merges, so `undefined` and `[]`
519
+ * both mean "none reported" — not that the texts agreed: a merge that failed,
520
+ * appended, or left the stored text unchanged reports none.
521
+ */
522
+ readonly merge_contradictions?: readonly FieldMergeContradiction[];
481
523
  }
482
524
  export interface WriteResult {
483
525
  readonly write_id: string;
@@ -485,8 +527,9 @@ export interface WriteResult {
485
527
  /** Deep link to this write's trace in the console; `null` if no console is configured. */
486
528
  readonly console_url: string | null;
487
529
  /**
488
- * What the write did, grouped into `created` / `updated` / `deleted`, and —
489
- * for a scoped write in `"drop"` mode — what it skipped instead of applying.
530
+ * What the write did, grouped into `created` / `updated` / `deleted`; for a
531
+ * scoped write in `"drop"` mode, what it skipped instead of applying; and
532
+ * what a field merge chose between (`merge_contradictions`).
490
533
  */
491
534
  readonly changes: WriteChanges;
492
535
  }
@@ -508,7 +551,8 @@ export interface WriteStatusResult {
508
551
  * What the finished write did, in the same shape {@link WriteResult.changes}
509
552
  * carries — and the async caller's only view of it, since `writeAsync`
510
553
  * returns before the write has done anything. It is therefore where a
511
- * `"drop"`-mode scope reports what it skipped.
554
+ * `"drop"`-mode scope reports what it skipped, and a field merge what it chose
555
+ * between.
512
556
  *
513
557
  * Optional because a status is not always about a finished write: a queued,
514
558
  * in-progress, failed or unknown `write_id` carries none. Read it once
@@ -980,7 +1024,7 @@ export interface PatchInstanceMetadataOptions {
980
1024
  timeoutMs?: number;
981
1025
  }
982
1026
  export interface UpdateInstanceSchemaOptions {
983
- /** Serialized migration plan from `enhanceSchema`; required for non-additive changes. */
1027
+ /** Serialized migration plan from `enhanceInstanceSchema` or `enhanceSchema`; required for non-additive changes. */
984
1028
  migrationPlan?: MigrationPlan | Record<string, unknown>;
985
1029
  /** Authorise ops that drop data (remove object/field, lossy type cast). */
986
1030
  confirmDestructive?: boolean;
@@ -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.17.0";
2
+ export declare const VERSION = "3.20.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.17.0";
5
+ exports.VERSION = "3.20.0";
@@ -77,7 +77,21 @@ export interface AdminNamespace {
77
77
  */
78
78
  patchInstanceMetadata(instanceId: string, options?: PatchInstanceMetadataOptions): Promise<InstanceInfo>;
79
79
  generateSchema(clusterId: string, schemaDescription: string, options?: GenerateSchemaOptions): Promise<GenerateSchemaResult>;
80
+ /**
81
+ * Evolve a schema not tied to an instance, on the cluster's model. To evolve
82
+ * an instance's schema, use `enhanceInstanceSchema`.
83
+ */
80
84
  enhanceSchema(clusterId: string, schemaDescription: string, currentYmlSchema: string, options?: RequestOptions): Promise<EnhanceSchemaResult>;
85
+ /**
86
+ * Evolve an instance's schema, returning the new schema and a migration plan.
87
+ *
88
+ * Pass the instance's current YAML schema plus a description of the change
89
+ * you want; nothing is applied. It runs on the model the instance is
90
+ * configured to use. The result's `migration_plan` is executor-ready: hand it
91
+ * to `dryRunMigration` to preview the DDL, then to `updateInstanceSchema` to
92
+ * apply it.
93
+ */
94
+ enhanceInstanceSchema(instanceId: string, schemaDescription: string, currentYmlSchema: string, options?: RequestOptions): Promise<EnhanceSchemaResult>;
81
95
  dryRunMigration(instanceId: string, schemaText: string, schemaType: SchemaTypeValue, options?: DryRunMigrationOptions): Promise<DryRunResult>;
82
96
  listMigrations(instanceId: string, options?: ListMigrationsOptions): Promise<ListMigrationsResult>;
83
97
  getMigration(instanceId: string, migrationId: string, options?: GetMigrationOptions): Promise<MigrationRecord>;
@@ -419,6 +419,12 @@ export class XmemoryClient {
419
419
  timeoutMs: options?.timeoutMs,
420
420
  });
421
421
  },
422
+ enhanceInstanceSchema: async (instanceId, schemaDescription, currentYmlSchema, options) => {
423
+ return this._requestOne("POST", `/instances/${instanceId}/schema/enhance`, {
424
+ body: { schema_description: schemaDescription, current_yml_schema: currentYmlSchema },
425
+ timeoutMs: options?.timeoutMs,
426
+ });
427
+ },
422
428
  dryRunMigration: async (instanceId, schemaText, schemaType, options) => {
423
429
  const body = {
424
430
  instance_schema: buildInstanceSchema(schemaText, schemaType),
@@ -10,7 +10,7 @@ export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from
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
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, WriteChanges, SkippedOutOfScope, 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, FieldMergeContradiction, 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";
@@ -85,6 +85,11 @@ export declare class InstanceHandle {
85
85
  * write create a scoped record that is not stored yet, and is computed by the
86
86
  * diff engine, so passing `diffEngine: false` with it is a 400.
87
87
  *
88
+ * A text write on a schema with a `merge` field also needs the diff engine:
89
+ * with the engine off, by `diffEngine: false` or by the connection's default,
90
+ * it is refused with a 400 `VALIDATION_ERROR`; a {@link writeAsync} one is
91
+ * queued and fails, which {@link writeStatus} reports.
92
+ *
88
93
  * A scoped write additionally requires read permission on the instance: the
89
94
  * response carries the previous value of every field the write changed,
90
95
  * resolving a scope answers whether each named object is stored, and a
@@ -114,8 +119,9 @@ export declare class InstanceHandle {
114
119
  writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
115
120
  /**
116
121
  * Poll a queued write. A finished one carries `changes` — the same report
117
- * {@link write} returns inline, including what a `"drop"`-mode scope skipped;
118
- * a status for a write that has not finished carries none.
122
+ * {@link write} returns inline, including what a `"drop"`-mode scope skipped
123
+ * and what a field merge chose between; a status for a write that has not
124
+ * finished carries none.
119
125
  */
120
126
  writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
121
127
  extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
@@ -294,8 +294,9 @@ export class InstanceHandle {
294
294
  }
295
295
  /**
296
296
  * Poll a queued write. A finished one carries `changes` — the same report
297
- * {@link write} returns inline, including what a `"drop"`-mode scope skipped;
298
- * a status for a write that has not finished carries none.
297
+ * {@link write} returns inline, including what a `"drop"`-mode scope skipped
298
+ * and what a field merge chose between; a status for a write that has not
299
+ * finished carries none.
299
300
  */
300
301
  async writeStatus(writeId, options) {
301
302
  return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
@@ -455,15 +455,49 @@ export interface SkippedOutOfScope {
455
455
  */
456
456
  readonly folded?: boolean;
457
457
  }
458
+ /**
459
+ * One contradiction a text field's merge resolved: what the stored value said,
460
+ * what the write's value said, and which of the two the merged value keeps.
461
+ *
462
+ * Only a `str` field whose schema declares a `merge` produces these. A later
463
+ * text write merges its value into the stored text instead of replacing it,
464
+ * and where the two disagreed about the same thing, the merge kept one.
465
+ */
466
+ export interface FieldMergeContradiction {
467
+ /** The object type of the record whose field merged. */
468
+ readonly object_type_name: string;
469
+ /**
470
+ * The record's primary key, rendered `field='value'` (a composite key's parts
471
+ * comma-separated); empty for a record that has no key or is missing part of
472
+ * it.
473
+ */
474
+ readonly identity: string;
475
+ /** The field that merged. */
476
+ readonly field: string;
477
+ /** What the stored value said, as the merge quoted it, cut to 300 characters. */
478
+ readonly stored: string;
479
+ /**
480
+ * What the write's value said (or that of a record the write merged into
481
+ * this one), as the merge quoted it, cut to 300 characters.
482
+ */
483
+ readonly new: string;
484
+ /**
485
+ * Which of the two the merged value keeps. Widened with `(string & {})` like
486
+ * {@link SkippedOutOfScope.operation}, so a value named by a server newer
487
+ * than this release is still typed rather than rejected.
488
+ */
489
+ readonly kept: "stored" | "new" | (string & {});
490
+ }
458
491
  /**
459
492
  * What a write did, grouped into `created` / `updated` / `deleted`, plus what a
460
- * `"drop"`-mode scope left out.
493
+ * `"drop"`-mode scope left out and the contradictions a field merge resolved.
461
494
  *
462
495
  * The three groups stay `unknown`: their shape is the server's to evolve and
463
496
  * this client has never modelled it. `skipped_out_of_scope` is typed because it
464
497
  * is the one part a caller has to branch on — a `"drop"`-mode write succeeds
465
498
  * whether or not it skipped anything, so this list is the only report that some
466
- * of what the text said was not applied.
499
+ * of what the text said was not applied. `merge_contradictions` is typed because
500
+ * it is the only report of what a merge chose between.
467
501
  */
468
502
  export interface WriteChanges {
469
503
  readonly created: unknown;
@@ -478,6 +512,14 @@ export interface WriteChanges {
478
512
  * {@link SkippedOutOfScope.folded}).
479
513
  */
480
514
  readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
515
+ /**
516
+ * The contradictions a merge reported for a field the write changed.
517
+ * Advisory: the write landed either way. Omitted by the server when there is
518
+ * none, and by a server that predates field merges, so `undefined` and `[]`
519
+ * both mean "none reported" — not that the texts agreed: a merge that failed,
520
+ * appended, or left the stored text unchanged reports none.
521
+ */
522
+ readonly merge_contradictions?: readonly FieldMergeContradiction[];
481
523
  }
482
524
  export interface WriteResult {
483
525
  readonly write_id: string;
@@ -485,8 +527,9 @@ export interface WriteResult {
485
527
  /** Deep link to this write's trace in the console; `null` if no console is configured. */
486
528
  readonly console_url: string | null;
487
529
  /**
488
- * What the write did, grouped into `created` / `updated` / `deleted`, and —
489
- * for a scoped write in `"drop"` mode — what it skipped instead of applying.
530
+ * What the write did, grouped into `created` / `updated` / `deleted`; for a
531
+ * scoped write in `"drop"` mode, what it skipped instead of applying; and
532
+ * what a field merge chose between (`merge_contradictions`).
490
533
  */
491
534
  readonly changes: WriteChanges;
492
535
  }
@@ -508,7 +551,8 @@ export interface WriteStatusResult {
508
551
  * What the finished write did, in the same shape {@link WriteResult.changes}
509
552
  * carries — and the async caller's only view of it, since `writeAsync`
510
553
  * returns before the write has done anything. It is therefore where a
511
- * `"drop"`-mode scope reports what it skipped.
554
+ * `"drop"`-mode scope reports what it skipped, and a field merge what it chose
555
+ * between.
512
556
  *
513
557
  * Optional because a status is not always about a finished write: a queued,
514
558
  * in-progress, failed or unknown `write_id` carries none. Read it once
@@ -980,7 +1024,7 @@ export interface PatchInstanceMetadataOptions {
980
1024
  timeoutMs?: number;
981
1025
  }
982
1026
  export interface UpdateInstanceSchemaOptions {
983
- /** Serialized migration plan from `enhanceSchema`; required for non-additive changes. */
1027
+ /** Serialized migration plan from `enhanceInstanceSchema` or `enhanceSchema`; required for non-additive changes. */
984
1028
  migrationPlan?: MigrationPlan | Record<string, unknown>;
985
1029
  /** Authorise ops that drop data (remove object/field, lossy type cast). */
986
1030
  confirmDestructive?: boolean;
@@ -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.17.0";
2
+ export declare const VERSION = "3.20.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.17.0";
2
+ export const VERSION = "3.20.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.17.0",
3
+ "version": "3.20.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"