xmemcli 1.4.0__tar.gz → 1.5.1__tar.gz

{xmemcli-1.4.0 → xmemcli-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xmemcli
-Version: 1.4.0
+Version: 1.5.1
 Summary: Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools.
 Keywords: api,cli,llm,memory,xmemory
 Requires-Python: <4,>=3.12
@@ -20,6 +20,8 @@ xmemcli auth logout
 xmemcli auth status
 xmemcli read <query>
 xmemcli write <text>
+xmemcli write (--mutations-file PATH | --mutations-stdin) [--delete TYPE:ID]…
+xmemcli write --delete TYPE:ID [--delete TYPE:ID]…
 xmemcli write-status <write_id> [<id> …]
 xmemcli quota
 xmemcli instance templates
@@ -48,6 +50,9 @@ Two local files, same discovery rule, different jobs: `.xmemrc.json` holds the c
 | `xmemcli write --extraction fast` (default) | `extraction_logic: "fast"` |
 | `xmemcli write --extraction deep` | `extraction_logic: "deep"` |
 | `xmemcli write --no-wait` | async write; poll with `write-status` |
+| `xmemcli write --mutations-file m.json` / `--mutations-stdin` | `structured_mutations` — the JSON array as given; no `text`, no `extraction_logic` |
+| `xmemcli write --scope Pet:name=Luna --scope-mode drop` | `scope: {objects: [...], mode: "drop"}` — out-of-scope changes are skipped and reported; `reject` is not sent |
+| `xmemcli write --delete Person:name=Ada` | appends `{"object_mutation": {"object_type": "Person", "delete": {"key": {"name": "Ada"}}}}` (`Person:<xuid>` sends `{"xuid": …}` as the key) |
 | `xmemcli read --read-mode single` (default) | `mode: "single-answer"` |
 | `xmemcli read --read-mode raw` | `mode: "raw-tables"` |
 | `xmemcli read --read-mode xresponse` | `mode: "xresponse"` |
@@ -58,7 +63,7 @@ Two local files, same discovery rule, different jobs: `.xmemrc.json` holds the c
 
 ## Curated output
 
-The CLI does not echo raw API payloads. Server internals (`sql`, `diff_plan`, extraction trees) are never emitted. Read responses keep `pending_suggestions` (schema-evolution hint). `--verbose` adds `trace_id` and `console_url` when present.
+The CLI does not echo raw API payloads. Server internals (`sql`, `diff_plan`, extraction trees) are never emitted. Read responses keep `pending_suggestions` (schema-evolution hint). A text write keeps a compact `extracted` summary (`Type(identifier)` tags); a structured write runs no extraction and has none. `write` and `write-status` keep the server's `changes` block (created / updated with old → new / deleted, bulk summaries, advisory records) when the write changed something. `--verbose` adds `trace_id` and `console_url` when present.
 
 **`trace …` is the one deliberate exception.** Those commands return the Console's own operation documents — the paged operations list, the Inspect search, and the per-operation detail — **verbatim**, because the Console already curates them per caller (a super admin sees LLM calls and raw token counts; everyone else does not). They are JSON on every stream and carry every internal id the Console does: `trace_id`, `instance_id`, `session_id`, `user_id`, `api_key_id`, and on detail documents `source_id`, `migration_id`, `llm_call_id`, `gateway_request_id`, …
 
@@ -138,7 +143,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **1.4.0**.
+Version: **1.5.1**.
 
 
 ---
@@ -238,7 +243,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `1.4.0` (see `xmemcli version`)
+**Version:** `1.5.1` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
@@ -256,12 +261,23 @@ Every command below has dedicated help — see [Help](#help).
 
 | Command | Description |
 |---------|-------------|
-| **`write`** `<text>` | Sync write (`POST …/write`). `--extraction fast\|deep` (default `fast`). `--no-wait` queues async write, returns `write_id`. `--scope TYPE:ID` (repeatable) anchors the write to existing objects: only they may be modified/deleted, new objects and links to them are allowed, anything else fails; works with either extraction mode. |
-| **`write-status`** `<write_id>` … | Poll async writes until terminal or `--timeout` (default 60s). Accepts multiple ids. |
+| **`write`** `[text]` | Sync write (`POST …/write`). `--extraction fast\|deep` (default `fast`). `--no-wait` queues async write, returns `write_id`. `--scope TYPE:ID` (repeatable) anchors the write to existing objects: only they may be modified/deleted; by default new objects and links to them are allowed and anything else fails, and under `--scope-mode drop` only the objects a `--scope` names may be created and everything else is skipped; works with either extraction mode. `--scope-mode drop` (needs `--scope`) skips out-of-scope changes instead of failing and lists them under `changes.skipped_out_of_scope`; it creates only records a `--scope` names by primary key, and such a record need not be stored yet — create-or-update exactly the named record. `reject` is the server default and is not sent. Instead of text, a **structured write** sends `structured_mutations` — deterministic creates, updates and deletes with no extraction: `--mutations-file PATH` or `--mutations-stdin` (one JSON array, same shape as the API's `structured_mutations`; see [Structured writes](#structured-writes)) and/or `--delete TYPE:ID` (repeatable, `--scope` syntax: `Person:<xuid>` or `Person:name=Ada`; appended after the file's entries). Text and mutations are exclusive, as are the file and stdin forms; mutations refuse `--scope` and `--extraction deep`; empty or whitespace-only text is refused (exit **2**, before anything is read or sent). A text write's output lists what it extracted as `Type(identifier)` tags (`extracted`); a structured write's does not. Both carry the server's `changes` block (`created` / `updated` with per-field `old_value` → `new_value` / `deleted`, and any other bucket such as `created_keyless_objects`) whenever the write changed something, and on a drop-mode write that skipped everything, where the block carries `skipped_out_of_scope` alone. A `--no-wait` answer carries only the `write_id`; `write-status` reports the `changes` once the write completes. |
+| **`write-status`** `<write_id>` … | Poll async writes until terminal or `--timeout` (default 60s). Accepts multiple ids. A completed write's non-empty `changes` block is kept, as on `write`. |
 | **`read`** `<query>` | Read from active instance. `--read-mode single\|raw\|xresponse`, `--scope TYPE:ID` (repeatable), `--scope-relations`, `--related-types` (also return `related_types`: per object type the read touched, the fields it did not return and the object types a declared relation links it to; needs `instance.get_own` on the key), `--related-types-depth N` (1, 2 or 3, refused as a usage error otherwise; follow the relations N levels out, each catalog entry saying its distance; implies `--related-types`). |
 
 Requires **`--instance-id`** or **`$XMEM_INSTANCE_ID`** for read/write (or auto-pick when exactly one instance is visible — see [Global flags](#global-flags--environment)).
 
+#### Structured writes
+
+`--mutations-file PATH` / `--mutations-stdin` send one JSON array as the API's `structured_mutations`, as given. The server takes at most **100** entries per write, `--delete` entries included; the CLI refuses more with exit **2** before sending anything. `--mutations-stdin` needs a pipe or a file on stdin and refuses a terminal. Each entry is one of:
+
+- **`object_mutation`** — `{"object_mutation": {"object_type": "Person", "create": {"key": {"name": "Ada"}, "values": {"age": 36}}}}`. `update` takes the same `key` + `values` (the key may be `{"xuid": "…"}`; a null value clears a field); `delete` takes `{"key": {…}}` alone.
+- **`relation_mutation`** — `{"relation_mutation": {"relation_type": "works_at", "create": {"endpoints": [{"object_name": "person", "key": {"name": "Ada"}}, {"object_name": "company", "key": {"name": "ACME"}}]}}}`. `create` lists every participant role, each keyed by primary key or `{"xuid": "…"}`, with no `key` and no `values`. `delete` takes either `endpoints` (a subset may be given) or a top-level `"key": {"xuid": "…"}` — never both — and `"allow_bulk_delete": true` to remove every matched link (without it, a delete matching more than one link is refused). Relation `update` is always refused: re-link by deleting and creating.
+
+`--delete TYPE:ID` appends the object `delete` above; each key field may appear once and none may be empty. A delete that matches no record is a no-op, not an error: exit **0** and no `deleted` line — in a terminal the write reads `write <id> ok · nothing matched or changed`.
+
+A deployment that has not enabled structured writes answers **400** `Structured writes are not enabled on this deployment.`; a server that predates structured writes answers **422** with two errors, both reported: `Field required (field: text); Extra inputs are not permitted (field: structured_mutations)`. Both exit **3** with `stage: "request"`.
+
 ---
 
 ### Org inventory
@@ -648,6 +664,10 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, `not
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 
+**New in 1.5.1:** `write --scope-mode drop` asks for a scoped write that skips and reports changes outside its scope instead of failing, and that creates only the records its `--scope` names — which may not be stored yet. The report is `changes.skipped_out_of_scope`: one terminal line per operation, type and set of fields, carrying `count=N`, the number of records it stands for, and naming a record's key only when the `--scope` named that record. A drop-mode write that skipped everything still returns a `changes` block, holding that report alone. A server that predates drop mode refuses `mode` in the scope (exit **3**), which is a clean failure; a deployment part-way through rolling it out is not, so publish 1.5.1 only after the server side is fully deployed — see [Releasing `xmemcli`](../docs/cli/XMEMCLI-RELEASE.md). `--scope-mode reject` is never sent, so plain scoped writes work against any server.
+
+**New in 1.5.1:** `write` and `write-status` keep the server's `changes` block — what the write created, updated (field by field, old → new) and deleted, plus bulk summaries and advisory records — verbatim in `--json` output. In a terminal each change is one indented line: a bulk delete or update reads `deleted 3 × Ticket where status='open'`, one the server refused reads `not deleted Ticket: refused — <reason>`, the advisory `overwritten_field_values` / `merged_field_conflicts` records follow as `note:` lines, and past 50 lines the rest is counted in one closing line (`--json` is never truncated); `write-status` with several ids prints a status line per write, each followed by its changes. `changes` is omitted when the write changed nothing, so that output keeps its earlier shape; a drop-mode write that only skipped is the one write that changed nothing and still carries the block. `write` also takes structured mutations (`--mutations-file`, `--mutations-stdin`, `--delete TYPE:ID`) in place of text; the text positional is now optional, and a write with neither text nor mutations, or whose text is empty or only whitespace, is a usage error (exit **2**, `stage: "usage"`). Before 1.5.1 `write ""` reached the server, whose 400 exited **3** with `stage: "request"`, and whitespace-only text was sent and accepted. A structured write's output carries no `extracted`, since it runs no extraction; on a text write the tags now read `Type(identifier)` (`Person(name='Ada')`), as documented, where they read `?(Type)`. A malformed `--scope` (on `write` and `read`) or `--delete` — now including a key field given twice or an empty value — reports `stage: "usage"`, still exit **2**; `--scope` reported `"request"`. `--mutations-stdin` and `--schema-stdin` refuse a terminal instead of waiting on it, and every input file and piped input is read by one reader and decoded as strict UTF-8, so an input that is not UTF-8 (`--mutations-file`, `--schema-file`, `--migration-plan`, `schema suggestions decide --file`, the `xmd validate` / `convert` / `enhance` schema file, or the same bytes piped to `--mutations-stdin` / `--schema-stdin`) is a usage error at exit **2** instead of a traceback at exit **1** — or, piped, a garbled write at exit **0** — and a leading UTF-8 byte-order mark is accepted. Wherever an HTTP error from the API is reported as `HTTP <status>: …`, a body in the API's error envelope now gives the server's own message (`HTTP 400: <message>`, plus the request `field` when the server names one) instead of the first 200 characters of the raw body.
+
 **New in 1.3.0:** exit **8** with `stage: "processing"` for a `write` whose server-side wait window expired while the write kept running. In `--json` mode that document also carries a `write_id` field (omitted when the server sent no handle), so a script polls with it directly instead of parsing the message. Additive — no previously documented mapping changed — but a script that reads “non-zero, and not a code I recognise” as failed-and-retryable will now retry a write that has **not** failed, starting a second one the account pays for. Branch on **8** (or on `stage`) and poll `xmemcli write-status <write_id>` until it settles.
 
 **New in 1.2.0:** `instance templates` lists the ready-made instance shapes the service ships, with the prose to choose between them, and `instance create --template <id>` builds one from a pinned schema the server already holds. No schema is generated on that path: no description to compose, no `xmd generate` hop, and the instance comes out identical to the one the console would have made from the same template. (Creating an instance still generates its agent brief afterwards, on this path as on any other.)

{xmemcli-1.4.0 → xmemcli-1.5.1}/README.md

@@ -12,6 +12,8 @@ xmemcli auth logout
 xmemcli auth status
 xmemcli read <query>
 xmemcli write <text>
+xmemcli write (--mutations-file PATH | --mutations-stdin) [--delete TYPE:ID]…
+xmemcli write --delete TYPE:ID [--delete TYPE:ID]…
 xmemcli write-status <write_id> [<id> …]
 xmemcli quota
 xmemcli instance templates
@@ -40,6 +42,9 @@ Two local files, same discovery rule, different jobs: `.xmemrc.json` holds the c
 | `xmemcli write --extraction fast` (default) | `extraction_logic: "fast"` |
 | `xmemcli write --extraction deep` | `extraction_logic: "deep"` |
 | `xmemcli write --no-wait` | async write; poll with `write-status` |
+| `xmemcli write --mutations-file m.json` / `--mutations-stdin` | `structured_mutations` — the JSON array as given; no `text`, no `extraction_logic` |
+| `xmemcli write --scope Pet:name=Luna --scope-mode drop` | `scope: {objects: [...], mode: "drop"}` — out-of-scope changes are skipped and reported; `reject` is not sent |
+| `xmemcli write --delete Person:name=Ada` | appends `{"object_mutation": {"object_type": "Person", "delete": {"key": {"name": "Ada"}}}}` (`Person:<xuid>` sends `{"xuid": …}` as the key) |
 | `xmemcli read --read-mode single` (default) | `mode: "single-answer"` |
 | `xmemcli read --read-mode raw` | `mode: "raw-tables"` |
 | `xmemcli read --read-mode xresponse` | `mode: "xresponse"` |
@@ -50,7 +55,7 @@ Two local files, same discovery rule, different jobs: `.xmemrc.json` holds the c
 
 ## Curated output
 
-The CLI does not echo raw API payloads. Server internals (`sql`, `diff_plan`, extraction trees) are never emitted. Read responses keep `pending_suggestions` (schema-evolution hint). `--verbose` adds `trace_id` and `console_url` when present.
+The CLI does not echo raw API payloads. Server internals (`sql`, `diff_plan`, extraction trees) are never emitted. Read responses keep `pending_suggestions` (schema-evolution hint). A text write keeps a compact `extracted` summary (`Type(identifier)` tags); a structured write runs no extraction and has none. `write` and `write-status` keep the server's `changes` block (created / updated with old → new / deleted, bulk summaries, advisory records) when the write changed something. `--verbose` adds `trace_id` and `console_url` when present.
 
 **`trace …` is the one deliberate exception.** Those commands return the Console's own operation documents — the paged operations list, the Inspect search, and the per-operation detail — **verbatim**, because the Console already curates them per caller (a super admin sees LLM calls and raw token counts; everyone else does not). They are JSON on every stream and carry every internal id the Console does: `trace_id`, `instance_id`, `session_id`, `user_id`, `api_key_id`, and on detail documents `source_id`, `migration_id`, `llm_call_id`, `gateway_request_id`, …
 
@@ -130,7 +135,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **1.4.0**.
+Version: **1.5.1**.
 
 
 ---
@@ -230,7 +235,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `1.4.0` (see `xmemcli version`)
+**Version:** `1.5.1` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
@@ -248,12 +253,23 @@ Every command below has dedicated help — see [Help](#help).
 
 | Command | Description |
 |---------|-------------|
-| **`write`** `<text>` | Sync write (`POST …/write`). `--extraction fast\|deep` (default `fast`). `--no-wait` queues async write, returns `write_id`. `--scope TYPE:ID` (repeatable) anchors the write to existing objects: only they may be modified/deleted, new objects and links to them are allowed, anything else fails; works with either extraction mode. |
-| **`write-status`** `<write_id>` … | Poll async writes until terminal or `--timeout` (default 60s). Accepts multiple ids. |
+| **`write`** `[text]` | Sync write (`POST …/write`). `--extraction fast\|deep` (default `fast`). `--no-wait` queues async write, returns `write_id`. `--scope TYPE:ID` (repeatable) anchors the write to existing objects: only they may be modified/deleted; by default new objects and links to them are allowed and anything else fails, and under `--scope-mode drop` only the objects a `--scope` names may be created and everything else is skipped; works with either extraction mode. `--scope-mode drop` (needs `--scope`) skips out-of-scope changes instead of failing and lists them under `changes.skipped_out_of_scope`; it creates only records a `--scope` names by primary key, and such a record need not be stored yet — create-or-update exactly the named record. `reject` is the server default and is not sent. Instead of text, a **structured write** sends `structured_mutations` — deterministic creates, updates and deletes with no extraction: `--mutations-file PATH` or `--mutations-stdin` (one JSON array, same shape as the API's `structured_mutations`; see [Structured writes](#structured-writes)) and/or `--delete TYPE:ID` (repeatable, `--scope` syntax: `Person:<xuid>` or `Person:name=Ada`; appended after the file's entries). Text and mutations are exclusive, as are the file and stdin forms; mutations refuse `--scope` and `--extraction deep`; empty or whitespace-only text is refused (exit **2**, before anything is read or sent). A text write's output lists what it extracted as `Type(identifier)` tags (`extracted`); a structured write's does not. Both carry the server's `changes` block (`created` / `updated` with per-field `old_value` → `new_value` / `deleted`, and any other bucket such as `created_keyless_objects`) whenever the write changed something, and on a drop-mode write that skipped everything, where the block carries `skipped_out_of_scope` alone. A `--no-wait` answer carries only the `write_id`; `write-status` reports the `changes` once the write completes. |
+| **`write-status`** `<write_id>` … | Poll async writes until terminal or `--timeout` (default 60s). Accepts multiple ids. A completed write's non-empty `changes` block is kept, as on `write`. |
 | **`read`** `<query>` | Read from active instance. `--read-mode single\|raw\|xresponse`, `--scope TYPE:ID` (repeatable), `--scope-relations`, `--related-types` (also return `related_types`: per object type the read touched, the fields it did not return and the object types a declared relation links it to; needs `instance.get_own` on the key), `--related-types-depth N` (1, 2 or 3, refused as a usage error otherwise; follow the relations N levels out, each catalog entry saying its distance; implies `--related-types`). |
 
 Requires **`--instance-id`** or **`$XMEM_INSTANCE_ID`** for read/write (or auto-pick when exactly one instance is visible — see [Global flags](#global-flags--environment)).
 
+#### Structured writes
+
+`--mutations-file PATH` / `--mutations-stdin` send one JSON array as the API's `structured_mutations`, as given. The server takes at most **100** entries per write, `--delete` entries included; the CLI refuses more with exit **2** before sending anything. `--mutations-stdin` needs a pipe or a file on stdin and refuses a terminal. Each entry is one of:
+
+- **`object_mutation`** — `{"object_mutation": {"object_type": "Person", "create": {"key": {"name": "Ada"}, "values": {"age": 36}}}}`. `update` takes the same `key` + `values` (the key may be `{"xuid": "…"}`; a null value clears a field); `delete` takes `{"key": {…}}` alone.
+- **`relation_mutation`** — `{"relation_mutation": {"relation_type": "works_at", "create": {"endpoints": [{"object_name": "person", "key": {"name": "Ada"}}, {"object_name": "company", "key": {"name": "ACME"}}]}}}`. `create` lists every participant role, each keyed by primary key or `{"xuid": "…"}`, with no `key` and no `values`. `delete` takes either `endpoints` (a subset may be given) or a top-level `"key": {"xuid": "…"}` — never both — and `"allow_bulk_delete": true` to remove every matched link (without it, a delete matching more than one link is refused). Relation `update` is always refused: re-link by deleting and creating.
+
+`--delete TYPE:ID` appends the object `delete` above; each key field may appear once and none may be empty. A delete that matches no record is a no-op, not an error: exit **0** and no `deleted` line — in a terminal the write reads `write <id> ok · nothing matched or changed`.
+
+A deployment that has not enabled structured writes answers **400** `Structured writes are not enabled on this deployment.`; a server that predates structured writes answers **422** with two errors, both reported: `Field required (field: text); Extra inputs are not permitted (field: structured_mutations)`. Both exit **3** with `stage: "request"`.
+
 ---
 
 ### Org inventory
@@ -640,6 +656,10 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, `not
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 
+**New in 1.5.1:** `write --scope-mode drop` asks for a scoped write that skips and reports changes outside its scope instead of failing, and that creates only the records its `--scope` names — which may not be stored yet. The report is `changes.skipped_out_of_scope`: one terminal line per operation, type and set of fields, carrying `count=N`, the number of records it stands for, and naming a record's key only when the `--scope` named that record. A drop-mode write that skipped everything still returns a `changes` block, holding that report alone. A server that predates drop mode refuses `mode` in the scope (exit **3**), which is a clean failure; a deployment part-way through rolling it out is not, so publish 1.5.1 only after the server side is fully deployed — see [Releasing `xmemcli`](../docs/cli/XMEMCLI-RELEASE.md). `--scope-mode reject` is never sent, so plain scoped writes work against any server.
+
+**New in 1.5.1:** `write` and `write-status` keep the server's `changes` block — what the write created, updated (field by field, old → new) and deleted, plus bulk summaries and advisory records — verbatim in `--json` output. In a terminal each change is one indented line: a bulk delete or update reads `deleted 3 × Ticket where status='open'`, one the server refused reads `not deleted Ticket: refused — <reason>`, the advisory `overwritten_field_values` / `merged_field_conflicts` records follow as `note:` lines, and past 50 lines the rest is counted in one closing line (`--json` is never truncated); `write-status` with several ids prints a status line per write, each followed by its changes. `changes` is omitted when the write changed nothing, so that output keeps its earlier shape; a drop-mode write that only skipped is the one write that changed nothing and still carries the block. `write` also takes structured mutations (`--mutations-file`, `--mutations-stdin`, `--delete TYPE:ID`) in place of text; the text positional is now optional, and a write with neither text nor mutations, or whose text is empty or only whitespace, is a usage error (exit **2**, `stage: "usage"`). Before 1.5.1 `write ""` reached the server, whose 400 exited **3** with `stage: "request"`, and whitespace-only text was sent and accepted. A structured write's output carries no `extracted`, since it runs no extraction; on a text write the tags now read `Type(identifier)` (`Person(name='Ada')`), as documented, where they read `?(Type)`. A malformed `--scope` (on `write` and `read`) or `--delete` — now including a key field given twice or an empty value — reports `stage: "usage"`, still exit **2**; `--scope` reported `"request"`. `--mutations-stdin` and `--schema-stdin` refuse a terminal instead of waiting on it, and every input file and piped input is read by one reader and decoded as strict UTF-8, so an input that is not UTF-8 (`--mutations-file`, `--schema-file`, `--migration-plan`, `schema suggestions decide --file`, the `xmd validate` / `convert` / `enhance` schema file, or the same bytes piped to `--mutations-stdin` / `--schema-stdin`) is a usage error at exit **2** instead of a traceback at exit **1** — or, piped, a garbled write at exit **0** — and a leading UTF-8 byte-order mark is accepted. Wherever an HTTP error from the API is reported as `HTTP <status>: …`, a body in the API's error envelope now gives the server's own message (`HTTP 400: <message>`, plus the request `field` when the server names one) instead of the first 200 characters of the raw body.
+
 **New in 1.3.0:** exit **8** with `stage: "processing"` for a `write` whose server-side wait window expired while the write kept running. In `--json` mode that document also carries a `write_id` field (omitted when the server sent no handle), so a script polls with it directly instead of parsing the message. Additive — no previously documented mapping changed — but a script that reads “non-zero, and not a code I recognise” as failed-and-retryable will now retry a write that has **not** failed, starting a second one the account pays for. Branch on **8** (or on `stage`) and poll `xmemcli write-status <write_id>` until it settles.
 
 **New in 1.2.0:** `instance templates` lists the ready-made instance shapes the service ships, with the prose to choose between them, and `instance create --template <id>` builds one from a pinned schema the server already holds. No schema is generated on that path: no description to compose, no `xmd generate` hop, and the instance comes out identical to the one the console would have made from the same template. (Creating an instance still generates its agent brief afterwards, on this path as on any other.)

{xmemcli-1.4.0 → xmemcli-1.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "1.4.0"
+version = "1.5.1"
 description = "Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools."
 readme = "README.md"
 requires-python = ">=3.12,<4"

{xmemcli-1.4.0 → xmemcli-1.5.1}/xmemcli/__init__.py

@@ -1,3 +1,3 @@
 """Standalone xmemcli package (``xmemcli`` console script)."""
 
-__version__ = "1.4.0"
+__version__ = "1.5.1"

{xmemcli-1.4.0 → xmemcli-1.5.1}/xmemcli/_help.py

@@ -105,7 +105,7 @@ _OVERVIEW_SECTIONS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
     (
         "Data",
         (
-            ("write", "Write a fact to the active instance"),
+            ("write", "Write text, or create, update and delete records by key"),
             ("write-status", "Poll async writes until they complete (one or more write_ids)"),
             ("read", "Read from the active instance"),
         ),

{xmemcli-1.4.0 → xmemcli-1.5.1}/xmemcli/_instance_schema.py

@@ -163,10 +163,9 @@ def _read_schema_mutation_payload(
 ) -> tuple[dict[str, Any] | None, tuple[CliOutput, int] | None]:
     if not args.schema_file:
         return None, (make_error("--schema-file is required", stage="usage"), xmem_module().EXIT_USAGE)
-    try:
-        schema_text = Path(args.schema_file).read_text(encoding="utf-8")
-    except OSError as exc:
-        return None, (make_error(f"cannot read {args.schema_file}: {exc}", stage="usage"), xmem_module().EXIT_USAGE)
+    schema_text, err = xmem_module()._read_input_text(args.schema_file)
+    if err is not None:
+        return None, err
     schema_type = _infer_schema_type(args.schema_file, getattr(args, "schema_type", None))
     payload: dict[str, Any] = {
         "instance_schema": _build_instance_schema_payload(schema_text, schema_type),
@@ -174,10 +173,11 @@ def _read_schema_mutation_payload(
     }
     migration_plan = getattr(args, "migration_plan", None)
     if migration_plan:
-        try:
-            payload["migration_plan"] = json.loads(Path(migration_plan).read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            return None, (make_error(f"cannot read migration_plan: {exc}", stage="usage"), xmem_module().EXIT_USAGE)
+        # The shared input reader, like every other input file: a non-UTF-8 plan escaped as a traceback at exit 1.
+        plan, err = xmem_module()._read_json_input(migration_plan)
+        if err is not None:
+            return None, err
+        payload["migration_plan"] = plan
     return payload, None
 
 
@@ -776,17 +776,14 @@ def cmd_instance_create(args: argparse.Namespace) -> tuple[CliOutput, int]:
         # The id is the whole input: no file to read, nothing to parse, and
         # nothing generated. The server holds the shape.
         payload["template_id"] = template_id
-    elif args.schema_stdin:
-        payload["instance_schema"] = _build_instance_schema_payload(
-            sys.stdin.read(), _infer_schema_type(None, args.schema_type)
+    elif args.schema_stdin or args.schema_file:
+        schema_text, err = m._read_input_text(
+            args.schema_file, use_stdin=args.schema_stdin, stdin_flag="--schema-stdin", file_flag="--schema-file"
         )
-    elif args.schema_file:
-        try:
-            schema_text = Path(args.schema_file).read_text(encoding="utf-8")
-        except OSError as exc:
-            return (make_error(f"cannot read {args.schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+        if err is not None:
+            return err
         payload["instance_schema"] = _build_instance_schema_payload(
-            schema_text, _infer_schema_type(args.schema_file, args.schema_type)
+            schema_text, _infer_schema_type(None if args.schema_stdin else args.schema_file, args.schema_type)
         )
     else:
         return (
@@ -934,10 +931,9 @@ def cmd_xmd_enhance(args: argparse.Namespace) -> tuple[CliOutput, int]:
             return (make_error("instance has no live schema to enhance", stage="usage"), m.EXIT_USAGE)
         current_yaml = _yaml_dump_or_json(schema)
     elif schema_file:
-        try:
-            current_yaml = Path(schema_file).read_text(encoding="utf-8")
-        except OSError as exc:
-            return (make_error(f"cannot read {schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+        current_yaml, err = m._read_input_text(schema_file)
+        if err is not None:
+            return err
     else:
         return (
             make_error(
@@ -988,10 +984,9 @@ def _xmd_validate_impl(
         return cluster_err
     if not cluster_id:
         return (make_error("could not resolve cluster_id", stage="usage"), m.EXIT_USAGE)
-    try:
-        text = Path(args.schema_file).read_text(encoding="utf-8")
-    except OSError as exc:
-        return (make_error(f"cannot read {args.schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+    text, err = m._read_input_text(args.schema_file)
+    if err is not None:
+        return err
 
     use_json = format_hint == "json" or (format_hint is None and Path(args.schema_file).suffix.lower() == ".json")
     if use_json:
@@ -1038,12 +1033,9 @@ def cmd_xmd_convert(args: argparse.Namespace) -> tuple[CliOutput, int]:
     input_file = Path(args.schema_file)
     if not input_file.is_file():
         return (make_error(f"cannot read {args.schema_file}: file not found", stage="usage"), m.EXIT_USAGE)
-    try:
-        json_schema = json.loads(input_file.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        return (make_error(f"invalid JSON in {args.schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
-    except OSError as exc:
-        return (make_error(f"cannot read {args.schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+    json_schema, err = m._read_json_input(args.schema_file)
+    if err is not None:
+        return err
 
     root_object = getattr(args, "root_object", None) or "MainObject"
     body: dict[str, Any] = {"json_schema": json_schema, "root_object_name": root_object}
@@ -1419,13 +1411,10 @@ def _curate_suggestions_apply(item: dict[str, Any], *, verbose: bool) -> dict[st
 def _read_decisions_file(path: str) -> tuple[list[dict[str, Any]] | None, tuple[CliOutput, int] | None]:
     """Parse a decisions JSON file into wire rows; any malformed row is a usage error."""
     m = xmem_module()
-    try:
-        raw = json.loads(Path(path).read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        return None, (
-            make_error(f"cannot read decisions file: {exc}", stage="usage"),
-            m.EXIT_USAGE,
-        )
+    # The shared input reader, like every other input file: a non-UTF-8 file escaped as a traceback at exit 1.
+    raw, err = m._read_json_input(path)
+    if err is not None:
+        return None, err
     if isinstance(raw, dict) and isinstance(raw.get("decisions"), list):
         raw = raw["decisions"]
     if not isinstance(raw, list):

{xmemcli-1.4.0 → xmemcli-1.5.1}/xmemcli/_output.py

@@ -79,12 +79,13 @@ class OutputKind(StrEnum):
     server payload, and that's fine.
     """
 
-    #: Synchronous write that completed (``POST …/write``). Curated payload:
-    #: ``write_id`` + ``extracted`` (compact ``Type(name)`` tags).
+    #: Synchronous write that completed (``POST …/write``). Curated payload: ``write_id``, ``extracted`` (compact
+    #: ``Type(identifier)`` tags) on a text write only — a structured write runs no extraction — and the server's
+    #: ``changes`` block verbatim when any of its buckets is non-empty.
     WRITE_SYNC = "write_sync"
 
-    #: Asynchronous write that was queued (``POST …/write_async``). Curated
-    #: payload: ``write_id``; the caller must poll.
+    #: Asynchronous write that was queued (``POST …/write_async``). Curated payload: ``write_id``; the caller must poll.
+    #: ``changes`` is curated as on `WRITE_SYNC`, but the queued answer carries none: it arrives on `WRITE_STATUS`.
     WRITE_ASYNC = "write_async"
 
     #: Result of an ``async_write_status`` poll. Curated payload: ``write_id`` + ``write_status``
@@ -92,7 +93,7 @@ class OutputKind(StrEnum):
     #: ``"error"`` / ``"unknown"`` fallbacks — whichever of ``submitted_at`` / ``started_at`` /
     #: ``completed_at`` is set, ``restart_count`` once non-zero (``--verbose`` keeps a zero count and
     #: drops only the null an unknown ``write_id`` reports), and ``error_detail`` / ``error``
-    #: / ``http_status`` / ``timed_out`` when applicable.
+    #: / ``http_status`` / ``timed_out`` when applicable, and ``changes`` as on `WRITE_SYNC`.
     WRITE_STATUS = "write_status"
 
     #: Read in ``mode=single-answer``. Curated payload: ``answer`` (falls