xmemory 2.1.2 → 2.3.0

package/README.md

@@ -152,7 +152,34 @@ const result = await inst.read("Who is on the team?");
 console.log(result.reader_result);
 ```
 
-Options: `{ readMode?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
+Options: `{ readMode?, scope?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
+
+#### Scoped reads
+
+By default a read may draw on the whole instance. Pass a `scope` to restrict it
+to a set of concrete objects — useful for grounding an answer in exactly the
+records you care about, or for keeping a per-user / per-entity read from leaking
+into unrelated data.
+
+Each object in the scope is identified by its `type` (the PascalCase class name
+or snake_case table name) plus its user-defined primary `key` (a mapping of
+primary-key field name to value):
+
+```typescript
+const result = await inst.read("What do we know about these people?", {
+  scope: {
+    objects: [
+      { type: "Person", key: { full_name: "Alice Smith" } },
+      { type: "Person", key: { full_name: "Bob Jones" } },
+    ],
+    relationsScope: "all_relations", // default: "no_relations"
+  },
+});
+```
+
+`relationsScope` controls relation traversal: `"no_relations"` (the default)
+restricts the read to the listed objects only, while `"all_relations"` also
+exposes the relations among the in-scope objects.
 
 ### `inst.extract(text, options?)` → `ExtractResult`
 
@@ -183,6 +210,109 @@ const tools = desc.asOpenaiTools();      // OpenAI function-calling format
 
 Results are cached for 5 minutes. Call `inst.clearDescribeCache()` to force a refresh.
 
+## Schema evolution
+
+Schemas can change after creation. xmemory supports **safe, data-preserving
+migrations** (rename / remove / type change) driven by structured migration
+ops, plus a **suggestion engine** that proposes improvements from real read
+traffic. This is purely additive — existing methods are unchanged.
+
+See the [Schema evolution section of the API reference](https://xmemory.ai/api/#schema-evolution)
+for the conceptual model, and the [TypeScript guide](https://xmemory.ai/typescript/)
+for full walkthroughs.
+
+### Suggestion-engine flow (review → decide → apply)
+
+The engine surfaces a single rolling proposal per instance. The minimum flow is
+three calls — review, decide (in bulk), apply:
+
+```typescript
+import { XmemoryClient, type DecisionInput } from "xmemory";
+
+const xm = new XmemoryClient({ apiKey: "..." });
+const inst = xm.instance("<instance-id>");
+
+// 1. Review — get the proposal + its concurrency token.
+const review = await inst.reviewSuggestions();
+if (review.status === "evolution_in_progress") {
+  console.log(`A migration is in flight; retry in ${review.retry_after_seconds}s`);
+} else if (review.proposal) {
+  const proposal = review.proposal;
+  for (const item of proposal.items) {
+    console.log(item.item_fingerprint, item.rationale, item.op);
+  }
+
+  // 2. Decide — accept / reject / defer per item, in one batch.
+  const decisions: DecisionInput[] = proposal.items.map((item) => ({
+    item_fingerprint: item.item_fingerprint,
+    decision: "accept",
+  }));
+  const decided = await inst.decideSuggestions(proposal.proposal_version, decisions);
+
+  // 3. Apply — commit accepted decisions as one migration.
+  const applied = await inst.applyPendingDecisions(decided.next_proposal_version);
+  console.log(applied.status, applied.summary); // e.g. "ok" "added 1 field"
+}
+```
+
+When `status === "evolution_in_progress"`, back off for `retry_after_seconds`
+and retry instead of blocking.
+
+### Direct migration flow (enhance → dry-run → update)
+
+Drive a migration yourself — ask the server to *enhance* the current schema,
+preview the DDL, then apply it:
+
+```typescript
+import { XmemoryClient, SchemaType } from "xmemory";
+import yaml from "js-yaml";
+
+const xm = new XmemoryClient({ apiKey: "..." });
+const current = (await xm.admin.getInstanceSchema("<instance-id>")).data_schema;
+
+// 1. Enhance — new schema + an executor-ready migration plan.
+const enhanced = await xm.admin.enhanceSchema(
+  "<cluster-id>",
+  "Rename Person.mail to Person.email.",
+  yaml.dump(current),
+);
+console.log(enhanced.summary, enhanced.migration_plan?.ops);
+
+const newYaml = yaml.dump(enhanced.data_schema);
+
+// 2. Dry-run — preview the DDL without applying anything.
+const preview = await xm.admin.dryRunMigration("<instance-id>", newYaml, SchemaType.YML, {
+  migrationPlan: enhanced.migration_plan ?? undefined,
+});
+console.log(preview.statements);
+
+// 3. Update — apply. confirmDestructive is required for ops that drop data.
+const info = await xm.admin.updateInstanceSchema("<instance-id>", newYaml, SchemaType.YML, {
+  migrationPlan: enhanced.migration_plan ?? undefined,
+  confirmDestructive: false,
+});
+console.log(info.migration_id, info.prior_version, "->", info.new_version);
+```
+
+### Migration history
+
+```typescript
+const page = await xm.admin.listMigrations("<instance-id>", { limit: 20 });
+for (const record of page.items) {
+  console.log(record.id, record.source, record.prior_version, "->", record.new_version);
+}
+
+const detail = await xm.admin.getMigration("<instance-id>", "<migration-id>", { includeYaml: true });
+console.log(detail.yaml_before, detail.yaml_after);
+```
+
+Migration ops are exported as discriminated-union types (`MigrationPlan`,
+`MigrationOp`, `AddField`, `RenameField`, `RemoveObject`, …) keyed on `op_type`.
+`ProposalItem.op` and `MigrationRecord.ops` are raw dicts for forward
+compatibility — narrow them to `MigrationOp` when needed.
+
+Runnable end-to-end examples live in [`examples/`](examples/).
+
 ## Error handling
 
 All errors throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCheckError` (a subclass).
@@ -207,6 +337,23 @@ try {
 }
 ```
 
+`XmemoryAPIError` carries `status` (HTTP status), `code` (structured error code,
+when the server returned one), and `details`. The schema-evolution endpoints
+return codes you can pattern match on via `.code` — for example
+`stale_proposal_version`, `dependency_closure_failed`,
+`destructive_confirmation_required`, `non_additive_change_requires_plan`,
+`stale_schema_version`, `migration_not_found`, `instance_not_initialised`:
+
+```typescript
+try {
+  await inst.applyPendingDecisions(token);
+} catch (e) {
+  if (e instanceof XmemoryAPIError && e.code === "stale_proposal_version") {
+    const review = await inst.reviewSuggestions(); // re-review and retry
+  }
+}
+```
+
 ## All timeouts are per-request
 
 Every method accepts an optional `timeoutMs` in its options bag, overriding the client default.

package/dist/client.d.ts

@@ -2,7 +2,7 @@
  * XmemoryClient — main entry point for the xmemory API.
  */
 import { InstanceHandle } from "./instance.js";
-import { type ClusterInfo, type CreateInstanceOptions, type GenerateSchemaOptions, type GenerateSchemaResult, type InstanceInfo, type InstanceSchemaInfo, type RequestOptions, type SchemaTypeValue, type XmemoryClientOptions } from "./types.js";
+import { 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 RequestOptions, type SchemaTypeValue, type UpdateInstanceSchemaOptions, type XmemoryClientOptions } from "./types.js";
 export interface AdminNamespace {
     listClusters(options?: RequestOptions & {
         ids?: string[];
@@ -15,9 +15,13 @@ export interface AdminNamespace {
     getInstance(instanceId: string, options?: RequestOptions): Promise<InstanceInfo>;
     deleteInstance(instanceId: string, options?: RequestOptions): Promise<string[]>;
     getInstanceSchema(instanceId: string, options?: RequestOptions): Promise<InstanceSchemaInfo>;
-    updateInstanceSchema(instanceId: string, schemaText: string, schemaType: SchemaTypeValue, options?: RequestOptions): Promise<InstanceInfo>;
+    updateInstanceSchema(instanceId: string, schemaText: string, schemaType: SchemaTypeValue, options?: UpdateInstanceSchemaOptions): Promise<InstanceInfo>;
     updateInstanceMetadata(instanceId: string, name: string, description: string, options?: RequestOptions): Promise<InstanceInfo>;
     generateSchema(clusterId: string, schemaDescription: string, options?: GenerateSchemaOptions): Promise<GenerateSchemaResult>;
+    enhanceSchema(clusterId: string, schemaDescription: string, currentYmlSchema: string, options?: RequestOptions): Promise<EnhanceSchemaResult>;
+    dryRunMigration(instanceId: string, schemaText: string, schemaType: SchemaTypeValue, options?: DryRunMigrationOptions): Promise<DryRunResult>;
+    listMigrations(instanceId: string, options?: ListMigrationsOptions): Promise<ListMigrationsResult>;
+    getMigration(instanceId: string, migrationId: string, options?: GetMigrationOptions): Promise<MigrationRecord>;
 }
 export declare class XmemoryClient {
     private readonly _baseUrl;

package/dist/client.js

@@ -10,6 +10,33 @@ const RESET = "\x1b[0m";
 function deprecationWarning(message) {
     console.warn(`${ORANGE}[xmemory] DEPRECATION: ${message}${RESET}`);
 }
+/**
+ * Pull a structured error out of an error body. Handles the schema-evolution
+ * shape (`{status: "error", error_type, error_message, details}`, where
+ * `error_type` is the code) and the standard `{errors: [{code, message}]}`
+ * envelope.
+ */
+function extractStructuredError(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return {};
+    const p = payload;
+    if (p.status === "error" && typeof p.error_type === "string") {
+        return {
+            code: p.error_type,
+            message: typeof p.error_message === "string" ? p.error_message : undefined,
+            details: (p.details ?? null),
+        };
+    }
+    const errors = p.errors;
+    if (Array.isArray(errors) && errors.length > 0 && typeof errors[0] === "object" && errors[0] !== null) {
+        const first = errors[0];
+        return {
+            code: typeof first.code === "string" ? first.code : undefined,
+            message: typeof first.message === "string" ? first.message : undefined,
+        };
+    }
+    return {};
+}
 // ---------------------------------------------------------------------------
 // Client
 // ---------------------------------------------------------------------------
@@ -122,15 +149,17 @@ export class XmemoryClient {
             throw new XmemoryAPIError(`Invalid JSON from server (${res.status}): ${raw.slice(0, 200)}`, res.status);
         }
         if (!res.ok) {
-            const msg = typeof payload === "object" && payload !== null && "message" in payload
-                ? String(payload.message)
-                : raw.slice(0, 200);
-            throw new XmemoryAPIError(`HTTP ${res.status}: ${msg}`, res.status);
+            const structured = extractStructuredError(payload);
+            const msg = structured.message ??
+                (typeof payload === "object" && payload !== null && "message" in payload
+                    ? String(payload.message)
+                    : raw.slice(0, 200));
+            throw new XmemoryAPIError(`HTTP ${res.status}: ${msg}`, res.status, structured.code, structured.details);
         }
         const response = payload;
         if (response.errors?.length) {
             const first = response.errors[0];
-            throw new XmemoryAPIError(`API error: ${first.message} (${first.code})`, res.status);
+            throw new XmemoryAPIError(`API error: ${first.message} (${first.code})`, res.status, first.code);
         }
         return response;
     }
@@ -202,8 +231,15 @@ export class XmemoryClient {
                 });
             },
             updateInstanceSchema: async (instanceId, schemaText, schemaType, options) => {
+                const body = {
+                    instance_schema: buildInstanceSchema(schemaText, schemaType),
+                };
+                if (options?.migrationPlan != null)
+                    body.migration_plan = options.migrationPlan;
+                if (options?.confirmDestructive != null)
+                    body.confirm_destructive = options.confirmDestructive;
                 return this._requestOne("PUT", `/instances/${instanceId}/schema`, {
-                    body: { instance_schema: buildInstanceSchema(schemaText, schemaType) },
+                    body,
                     timeoutMs: options?.timeoutMs,
                 });
             },
@@ -219,6 +255,41 @@ export class XmemoryClient {
                     body.current_yml_schema = options.currentYmlSchema;
                 return this._requestOne("POST", `/clusters/${clusterId}/instances/generate_schema`, { body, timeoutMs: options?.timeoutMs });
             },
+            enhanceSchema: async (clusterId, schemaDescription, currentYmlSchema, options) => {
+                return this._requestOne("POST", `/clusters/${clusterId}/instances/generate_schema`, {
+                    body: { schema_description: schemaDescription, current_yml_schema: currentYmlSchema },
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            dryRunMigration: async (instanceId, schemaText, schemaType, options) => {
+                const body = {
+                    instance_schema: buildInstanceSchema(schemaText, schemaType),
+                };
+                if (options?.migrationPlan != null)
+                    body.migration_plan = options.migrationPlan;
+                if (options?.confirmDestructive != null)
+                    body.confirm_destructive = options.confirmDestructive;
+                return this._requestOne("POST", `/instances/${instanceId}/migrations/dry_run`, {
+                    body,
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            listMigrations: async (instanceId, options) => {
+                const params = {
+                    limit: String(options?.limit ?? 50),
+                    include_yaml: String(options?.includeYaml ?? false),
+                };
+                if (options?.beforeId != null)
+                    params.before_id = options.beforeId;
+                return this._requestOne("GET", `/instances/${instanceId}/migrations`, {
+                    params,
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            getMigration: async (instanceId, migrationId, options) => {
+                const result = await this._requestOne("GET", `/instances/${instanceId}/migrations/${migrationId}`, { params: { include_yaml: String(options?.includeYaml ?? false) }, timeoutMs: options?.timeoutMs });
+                return result.record;
+            },
         };
     }
 }

package/dist/index.d.ts

@@ -6,6 +6,9 @@ export type { AdminNamespace } from "./client.js";
 export { DescribeResult, InstanceHandle } from "./instance.js";
 export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
 export { SchemaType } from "./types.js";
-export type { SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus } from "./types.js";
-export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, } from "./types.js";
+export type { SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
+export type { ScopeObject, ReadScope, RelationsScope } from "./types.js";
+export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
 export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
+export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
+export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";

package/dist/instance.d.ts

@@ -1,7 +1,7 @@
 /**
  * InstanceHandle — scoped data operations on a single xmemory instance.
  */
-import type { AsyncWriteResult, ExtractOptions, ExtractResult, InstanceSchemaInfo, RawDescribeResult, ReadOptions, ReadResult, RequestOneFn, RequestOptions, ToolDescription, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
+import type { ApplyPendingDecisionsResult, AsyncWriteResult, DecideSuggestionsResult, DecisionInput, ExtractOptions, ExtractResult, InstanceSchemaInfo, RawDescribeResult, ReadOptions, ReadResult, RequestOneFn, RequestOptions, ReviewSuggestionsResult, SuggestionRequestOptions, ToolDescription, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
 export declare class DescribeResult {
     readonly instanceId: string;
     readonly instanceName: string;
@@ -36,6 +36,32 @@ export declare class InstanceHandle {
     writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
     extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
     getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
+    /**
+     * Return the current consolidated schema-improvement proposal (step 1).
+     *
+     * The result's `proposal.proposal_version` is the optimistic-concurrency
+     * token you pass to `decideSuggestions` / `applyPendingDecisions`. When
+     * `status === "evolution_in_progress"`, back off for `retry_after_seconds`
+     * and retry instead of blocking on the in-flight migration.
+     */
+    reviewSuggestions(options?: SuggestionRequestOptions): Promise<ReviewSuggestionsResult>;
+    /**
+     * Record accept/reject/defer decisions for proposal items, in bulk (step 2).
+     *
+     * `proposalVersion` must be the token from the latest `reviewSuggestions`; a
+     * stale token throws `XmemoryAPIError` with `code === "stale_proposal_version"`.
+     * The result's `next_proposal_version` can be passed straight to
+     * `applyPendingDecisions`.
+     */
+    decideSuggestions(proposalVersion: string, decisions: DecisionInput[], options?: SuggestionRequestOptions): Promise<DecideSuggestionsResult>;
+    /**
+     * Commit accepted decisions as a single migration (step 3).
+     *
+     * `status === "nothing_to_apply"` means no accepted items were left. A stale
+     * `proposalVersion` or an unmet dependency throws `XmemoryAPIError`
+     * (`code === "stale_proposal_version"` / `"dependency_closure_failed"`).
+     */
+    applyPendingDecisions(proposalVersion: string, options?: SuggestionRequestOptions): Promise<ApplyPendingDecisionsResult>;
     /**
      * Return agent-facing tool descriptions enriched with the instance schema.
      *

package/dist/instance.js

@@ -109,6 +109,17 @@ export class InstanceHandle {
             query,
             mode: options?.readMode ?? "single-answer",
         };
+        if (options?.scope != null) {
+            // Serialize to the API's identity wire shape: each object is
+            // `{type, key: {key: {...}}}` (by user-defined primary key), plus `relations_scope`.
+            body.scope = {
+                objects: options.scope.objects.map((o) => ({
+                    type: o.type,
+                    key: { key: o.key },
+                })),
+                relations_scope: options.scope.relationsScope ?? "no_relations",
+            };
+        }
         if (options?.traceId != null)
             body.trace_id = options.traceId;
         return this._requestOne("POST", `/instances/${this.id}/read`, {
@@ -161,6 +172,57 @@ export class InstanceHandle {
             timeoutMs: options?.timeoutMs,
         });
     }
+    // -- Schema evolution (suggestion engine) ---------------------------------
+    /**
+     * Return the current consolidated schema-improvement proposal (step 1).
+     *
+     * The result's `proposal.proposal_version` is the optimistic-concurrency
+     * token you pass to `decideSuggestions` / `applyPendingDecisions`. When
+     * `status === "evolution_in_progress"`, back off for `retry_after_seconds`
+     * and retry instead of blocking on the in-flight migration.
+     */
+    async reviewSuggestions(options) {
+        const body = {};
+        if (options?.sessionId != null)
+            body.session_id = options.sessionId;
+        return this._requestOne("POST", `/instances/${this.id}/suggestions/review`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    /**
+     * Record accept/reject/defer decisions for proposal items, in bulk (step 2).
+     *
+     * `proposalVersion` must be the token from the latest `reviewSuggestions`; a
+     * stale token throws `XmemoryAPIError` with `code === "stale_proposal_version"`.
+     * The result's `next_proposal_version` can be passed straight to
+     * `applyPendingDecisions`.
+     */
+    async decideSuggestions(proposalVersion, decisions, options) {
+        const body = { proposal_version: proposalVersion, decisions };
+        if (options?.sessionId != null)
+            body.session_id = options.sessionId;
+        return this._requestOne("POST", `/instances/${this.id}/suggestions/decide`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    /**
+     * Commit accepted decisions as a single migration (step 3).
+     *
+     * `status === "nothing_to_apply"` means no accepted items were left. A stale
+     * `proposalVersion` or an unmet dependency throws `XmemoryAPIError`
+     * (`code === "stale_proposal_version"` / `"dependency_closure_failed"`).
+     */
+    async applyPendingDecisions(proposalVersion, options) {
+        const body = { proposal_version: proposalVersion };
+        if (options?.sessionId != null)
+            body.session_id = options.sessionId;
+        return this._requestOne("POST", `/instances/${this.id}/suggestions/apply`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
     /**
      * Return agent-facing tool descriptions enriched with the instance schema.
      *

package/dist/types.d.ts

@@ -8,10 +8,48 @@ export declare const SchemaType: {
 export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
 export type ExtractionLogic = "fast" | "regular" | "deep";
 export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
-export type WriteQueueStatus = "queued" | "processing" | "completed" | "failed" | "not_found";
+/**
+ * One concrete object a scoped read may touch. Identify it by `type` (PascalCase
+ * class name or snake_case table name) plus its user-defined primary `key`
+ * (a mapping of primary-key field name to value).
+ */
+export interface ScopeObject {
+    type: string;
+    key: Record<string, string | number | boolean>;
+}
+/** Which relations a scoped read may traverse. */
+export type RelationsScope = "no_relations" | "all_relations";
+/**
+ * A read's scope: the concrete `objects` it may touch, plus relation policy.
+ * `relationsScope` is `no_relations` (objects only) by default; `all_relations`
+ * also exposes the relations among the in-scope `objects`.
+ */
+export interface ReadScope {
+    objects: ScopeObject[];
+    relationsScope?: RelationsScope;
+}
+export type WriteQueueStatus = "queued" | "processing" | "extracting" | "extracted" | "applying" | "completed" | "failed" | "not_found";
 export declare class XmemoryAPIError extends Error {
     readonly status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
+    /**
+     * Structured error code when the server returned one. For the
+     * schema-evolution endpoints this is the `error_type` discriminator
+     * (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
+     * Pattern match on this instead of parsing the message.
+     */
+    readonly code?: string | undefined;
+    /** Optional structured `details` payload attached to some errors. */
+    readonly details?: (Record<string, unknown> | null) | undefined;
+    constructor(message: string, status?: number | undefined, 
+    /**
+     * Structured error code when the server returned one. For the
+     * schema-evolution endpoints this is the `error_type` discriminator
+     * (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
+     * Pattern match on this instead of parsing the message.
+     */
+    code?: string | undefined, 
+    /** Optional structured `details` payload attached to some errors. */
+    details?: (Record<string, unknown> | null) | undefined);
 }
 export declare class XmemoryHealthCheckError extends XmemoryAPIError {
     constructor(message: string, status?: number);
@@ -28,6 +66,10 @@ export interface InstanceInfo {
     readonly name: string;
     readonly description: string | null;
     readonly data_schema: Record<string, unknown> | null;
+    readonly migration_id?: string | null;
+    readonly prior_version?: number | null;
+    readonly new_version?: number | null;
+    readonly migration_warnings?: string[] | null;
 }
 export interface InstanceSchemaInfo {
     readonly data_schema: Record<string, unknown>;
@@ -40,7 +82,6 @@ export interface WriteResult {
     readonly write_id: string;
     readonly trace_id: string | null;
     readonly cleaned_objects: unknown;
-    readonly diff_plan: unknown;
 }
 export interface AsyncWriteResult {
     readonly write_id: string;
@@ -58,6 +99,214 @@ export interface ExtractResult {
 export interface GenerateSchemaResult {
     readonly data_schema: Record<string, unknown>;
 }
+export type FieldType = "str" | "string" | "int" | "integer" | "float" | "bool" | "boolean";
+export type OnDelete = "nullify" | "cascade";
+export type CastStrategy = "safe_implicit" | "explicit_using" | "lossy";
+export type DecisionKind = "accept" | "reject" | "defer";
+export type MigrationSource = "direct" | "suggestion_engine";
+export type DefaultValue = string | number | boolean | null;
+export type EnumValues = Array<string | number | boolean> | null;
+export interface FieldSpec {
+    name: string;
+    type: FieldType;
+    required?: boolean;
+    description?: string | null;
+    default?: DefaultValue;
+    enum?: EnumValues;
+}
+export interface AddObject {
+    op_type: "add_object";
+    name: string;
+    description?: string | null;
+    primary_key: string[];
+    fields: FieldSpec[];
+    should_backfill?: boolean;
+}
+export interface RemoveObject {
+    op_type: "remove_object";
+    name: string;
+}
+export interface RenameObject {
+    op_type: "rename_object";
+    old_name: string;
+    new_name: string;
+}
+export interface ChangeObject {
+    op_type: "change_object";
+    name: string;
+    new_primary_key?: string[] | null;
+    new_description?: string | null;
+}
+export interface AddField {
+    op_type: "add_field";
+    object_name: string;
+    field_name: string;
+    field_type: FieldType;
+    required?: boolean;
+    description?: string | null;
+    default?: DefaultValue;
+    enum?: EnumValues;
+    should_backfill?: boolean;
+}
+export interface RemoveField {
+    op_type: "remove_field";
+    object_name: string;
+    field_name: string;
+}
+export interface RenameField {
+    op_type: "rename_field";
+    object_name: string;
+    old_name: string;
+    new_name: string;
+}
+export interface ChangeField {
+    op_type: "change_field";
+    object_name: string;
+    field_name: string;
+    new_type?: FieldType | null;
+    new_required?: boolean | null;
+    new_description?: string | null;
+    new_default?: DefaultValue;
+    new_enum?: EnumValues;
+    clear_default?: boolean;
+    clear_enum?: boolean;
+    cast_strategy?: CastStrategy | null;
+    using_expression?: string | null;
+    confirm_data_loss?: boolean;
+}
+export interface AddRelation {
+    op_type: "add_relation";
+    name: string;
+    description?: string | null;
+    objects: Record<string, string>;
+    keys?: Record<string, string[]> | null;
+    on_delete?: Record<string, OnDelete> | null;
+    should_backfill?: boolean;
+}
+export interface RemoveRelation {
+    op_type: "remove_relation";
+    name: string;
+}
+export interface RenameRelation {
+    op_type: "rename_relation";
+    old_name: string;
+    new_name: string;
+}
+export interface ChangeRelation {
+    op_type: "change_relation";
+    name: string;
+    new_keys?: Record<string, string[]> | null;
+    new_on_delete?: Record<string, OnDelete> | null;
+    new_description?: string | null;
+}
+export type MigrationOp = AddObject | RemoveObject | RenameObject | ChangeObject | AddField | RemoveField | RenameField | ChangeField | AddRelation | RemoveRelation | RenameRelation | ChangeRelation;
+export interface MigrationPlan {
+    ops: MigrationOp[];
+}
+export interface EnhanceSchemaResult {
+    readonly data_schema: Record<string, unknown>;
+    readonly migration_plan: MigrationPlan | null;
+    readonly summary: string | null;
+    readonly warnings: Record<string, unknown>[];
+    readonly repair_log: Record<string, unknown>[];
+}
+export interface PlanSummary {
+    readonly count_by_op_type: Record<string, number>;
+    readonly total: number;
+}
+export interface DryRunResult {
+    readonly status: "ok";
+    readonly instance_id: string;
+    readonly current_version: number;
+    readonly statements: string[];
+    readonly warnings: string[];
+    readonly plan_summary: PlanSummary;
+    readonly requires_metadata_sync: boolean;
+}
+export interface MigrationRecord {
+    readonly id: string;
+    readonly applied_at: string;
+    readonly source: MigrationSource;
+    readonly decided_by: string | null;
+    readonly prior_version: number;
+    readonly new_version: number;
+    readonly ops: Record<string, unknown>[];
+    readonly ops_summary: PlanSummary;
+    readonly notes: string | null;
+    readonly yaml_before: string | null;
+    readonly yaml_after: string | null;
+}
+export interface ListMigrationsResult {
+    readonly status: "ok";
+    readonly instance_id: string;
+    readonly items: MigrationRecord[];
+    readonly next_before_id: string | null;
+    readonly has_more: boolean;
+}
+export interface GetMigrationResult {
+    readonly status: "ok";
+    readonly instance_id: string;
+    readonly record: MigrationRecord;
+}
+export interface ProposalItem {
+    readonly item_fingerprint: string;
+    /** Raw op dict (forward-compatible). Cast to `MigrationOp` when needed. */
+    readonly op: Record<string, unknown>;
+    readonly evidence_feedback_ids: string[];
+    readonly evidence_query_samples: string[];
+    readonly frequency: number;
+    readonly depends_on: string[];
+    readonly current_decision: string | null;
+    readonly rationale: string;
+}
+export interface ConsolidatedProposal {
+    readonly instance_id: string;
+    readonly proposal_version: string;
+    readonly schema_version: number;
+    readonly items: ProposalItem[];
+    readonly generated_at: string;
+    readonly notes: string[];
+}
+export interface ReviewSuggestionsResult {
+    readonly status: "ok" | "evolution_in_progress";
+    readonly instance_id: string;
+    readonly proposal: ConsolidatedProposal | null;
+    readonly retry_after_seconds: number | null;
+}
+export interface DecisionInput {
+    item_fingerprint: string;
+    decision: DecisionKind;
+    edits?: Record<string, unknown> | null;
+}
+export interface RecordedDecision {
+    readonly item_fingerprint: string;
+    readonly decision_id: string;
+}
+export interface DependencyWarning {
+    readonly kind: string;
+    readonly item_fingerprint: string;
+    readonly related_fingerprints: string[];
+    readonly related_summaries: string[];
+    readonly guidance: string;
+}
+export interface DecideSuggestionsResult {
+    readonly status: "ok";
+    readonly instance_id: string;
+    readonly decisions_recorded: RecordedDecision[];
+    readonly warnings: DependencyWarning[];
+    readonly next_proposal_version: string;
+}
+export interface ApplyPendingDecisionsResult {
+    readonly status: "ok" | "nothing_to_apply";
+    readonly instance_id: string;
+    readonly migration_id: string | null;
+    readonly prior_version: number;
+    readonly new_version: number;
+    readonly applied_items: string[];
+    readonly summary: string;
+    readonly warnings: string[];
+    readonly notes: string[];
+}
 export interface ToolParameterDescription {
     readonly name: string;
     readonly type: string;
@@ -92,6 +341,8 @@ export interface RequestOptions {
 }
 export interface ReadOptions {
     readMode?: ReadMode;
+    /** Restrict the read to a set of concrete objects (plus optional relation traversal). */
+    scope?: ReadScope;
     traceId?: string;
     timeoutMs?: number;
 }
@@ -113,6 +364,33 @@ export interface GenerateSchemaOptions {
     currentYmlSchema?: string;
     timeoutMs?: number;
 }
+export interface UpdateInstanceSchemaOptions {
+    /** Serialized migration plan from `enhanceSchema`; required for non-additive changes. */
+    migrationPlan?: MigrationPlan | Record<string, unknown>;
+    /** Authorise ops that drop data (remove object/field, lossy type cast). */
+    confirmDestructive?: boolean;
+    timeoutMs?: number;
+}
+export interface DryRunMigrationOptions {
+    migrationPlan?: MigrationPlan | Record<string, unknown>;
+    confirmDestructive?: boolean;
+    timeoutMs?: number;
+}
+export interface ListMigrationsOptions {
+    limit?: number;
+    beforeId?: string;
+    includeYaml?: boolean;
+    timeoutMs?: number;
+}
+export interface GetMigrationOptions {
+    includeYaml?: boolean;
+    timeoutMs?: number;
+}
+export interface SuggestionRequestOptions {
+    /** Optional free-form session ID for end-to-end tracing. */
+    sessionId?: string;
+    timeoutMs?: number;
+}
 export interface ApiError {
     readonly code: string;
     readonly message: string;

package/dist/types.js

@@ -10,9 +10,22 @@ export const SchemaType = { YML: 0, JSON: 1 };
 // ---------------------------------------------------------------------------
 export class XmemoryAPIError extends Error {
     status;
-    constructor(message, status) {
+    code;
+    details;
+    constructor(message, status, 
+    /**
+     * Structured error code when the server returned one. For the
+     * schema-evolution endpoints this is the `error_type` discriminator
+     * (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
+     * Pattern match on this instead of parsing the message.
+     */
+    code, 
+    /** Optional structured `details` payload attached to some errors. */
+    details) {
         super(message);
         this.status = status;
+        this.code = code;
+        this.details = details;
         this.name = "XmemoryAPIError";
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xmemory",
-  "version": "2.1.2",
+  "version": "2.3.0",
   "description": "xmemory",
   "keywords": [
     "xmemory"