xmemory 2.2.1 → 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`
 

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { DescribeResult, InstanceHandle } from "./instance.js";
 export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
 export { SchemaType } 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";

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`, {

package/dist/types.d.ts

@@ -8,6 +8,26 @@ 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";
+/**
+ * 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;
@@ -321,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;
 }

package/package.json

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