@warmhub/sdk-ts 0.139.0 → 0.140.0

package/CHANGELOG.md

@@ -2,6 +2,465 @@
 
 <!-- warmhub-changelog-artifact:v1 -->
 
+## 0.140.0
+
+### Changed
+
+A resumed repository export now sends the `formatVersion` of the header the download opened with, and the server refuses a resume whose format is not the one it writes: HTTP 412 `client-incompatible` with the message "Restart the export; a resume must use the format it started with." A download started before a server upgrade that changes the export format can no longer be silently finished under its old header; the resume fails and the export must be restarted.
+
+A resume of a file that holds only the header (interrupted before the first row) sends no cursor, so the server cannot check it; the session now compares the new header's format to the saved one and raises `RepositoryExportError` (`header_invalid`) with the same restart message rather than appending new-format rows under the old header.
+
+**Upgrade with the server.** An older SDK sends no `formatVersion` on a resume, so a server with this change refuses every resume from it, not only cross-format ones. Upgrade the SDK in the same release as the server.
+
+### Added
+
+`isAllStreamOperationsFailedError(error)` reports whether a thrown value is an all-failed stream error. Unlike `error instanceof AllStreamOperationsFailedError`, it also recognizes the error after `toWarmHubError` normalization and when a different copy of the SDK threw it.
+
+### Breaking
+
+#### `NAME_TAKEN` names the holder by durable id only and offers no replacement name
+
+**What it was.** A `name_taken` error's `details.takenBy` was `{ shape, durableId }`, `details.suggestedName` could carry a replacement name, and the message said `by a <Shape> Thing` and `for example "<name>"`.
+
+**What it is now.** `details.takenBy` is `{ durableId }`; `shape` is removed. `details.suggestedName` is removed and no example name appears in the message or hint. The message names no Shape: `Name "acme" is already taken in this repository by another Thing; choose another name`. A caller who cannot read the holder still gets no `takenBy` and no `by another Thing`. The `name_taken` decoder in the streaming submission protocol requires only `takenBy.durableId`.
+
+**Why it breaks.** This is a client-visible breaking change, accepted. Released sdk-ts 0.135.0 to 0.139.0 decode `takenBy` with `shape` required, so they refuse a `name_taken` result from a server that carries this change. It lands before the v2 floor release (0.140.0), so no v2 client sees `shape`.
+
+**Migration.** Read the holder's Shapes with `get` on `details.takenBy.durableId`; a Thing can have several Shapes or none. Choose the replacement name yourself.
+
+```ts
+// Before
+const { takenBy, suggestedName } = details
+console.log(takenBy?.shape, suggestedName)
+
+// After
+const holder = details.takenBy && (await client.thing.get(org, repo, details.takenBy.durableId))
+```
+
+### Added
+
+The `restore` operation and `OperationBuilder.restore()` make a retracted Thing active again, by its durable ID. Pass `newName` to restore it under another name.
+
+In these notes, "old grammar" means the reference form used before this release (`Deal/acme`, operations with `kind`), and "new grammar" the form this release introduces (`acme`, operations with `shapes`).
+
+### Breaking
+
+#### Write operations take `name` and `shapes`
+
+**What it was.** Operations carried `kind`, an add name spelled
+`Shape/name`, a top-level `about`, or collection `type`/`members`, and the
+SDK converted them.
+
+**What it is now.** `Operation`, `AddOperation`, `ReviseOperation`,
+`RetractOperation`, `ReaffirmOperation` and `RenameOperation` keep their
+names but have the new shape. An add or revise requires `name`, `shapes`
+and `data`. `kind` and `shape` are typed `never`. The new `WriteOperation`
+type is one operation of that form.
+
+- A Shape is the Thing `hub/shapes/X` (`shapeName('X')`), written with
+  `shapes: []`.
+- An assertion is a Thing one of whose declared Shapes composes `Assertion`,
+  with its target in `data.about`.
+- A collection is a Thing of its collection Shape:
+  `{ shapes: ['Set'], data: { members } }`.
+
+**Migration.**
+
+```ts
+// Before
+await client.commit.apply('acme', 'world', 'seed', [
+  { operation: 'add', kind: 'thing', name: 'Deal/acme', data: { company: 'Acme' } },
+])
+
+// After
+await client.commit.apply('acme', 'world', 'seed', [
+  { operation: 'add', name: 'acme', shapes: ['Deal'], data: { company: 'Acme' } },
+])
+```
+
+#### Old-grammar operations are refused before any request
+
+**What it was.** The SDK converted old-grammar operations.
+
+**What it is now.** An operation with `kind`, `shape`, `wref`,
+`declaredShapes`, `about`, collection `type` or `members`, or with no
+`operation`, is refused with a `WriteOperationError` before anything is
+sent. The message shows a suggested new form, with data values replaced by
+`"..."`. Names and `about` targets are copied as written, so check them: a
+suggested `name: 'Deal/acme'` would address a Thing literally named
+`Deal/acme`. An add or revise with no `shapes` is refused with a message
+that it states no Shapes.
+
+Old-grammar input no longer type-checks, so it reaches this refusal only
+through a cast.
+
+**Migration.**
+
+```ts
+// Before: converted and sent
+await client.commit.apply('acme', 'world', 'rate', [
+  { operation: 'add', kind: 'assertion', name: 'Rating/r1', about: 'Deal/acme', data: { score: 5 } },
+])
+
+// After
+await client.commit.apply('acme', 'world', 'rate', [
+  { operation: 'add', name: 'r1', shapes: ['Rating'], data: { about: 'acme', score: 5 } },
+])
+```
+
+Other operations refused locally:
+
+- a pinned Shape in `shapes` (`Deal@v2`), or an entry that is not a bare
+  Shape name (`hub/shapes/Deal`, anything with `/`);
+- `shapeless` on a raw operation (spell it `shapes: []`);
+- non-empty `shapes` on a `hub/shapes/X` name;
+- an add or revise without `data`, and `keepShapes` on an add;
+- `affirmedTargets` on a shapeless write;
+- `expectedVersion` on an add, and `active` on a revise;
+- renaming a Shape to a non-Shape name, or the reverse;
+- `+` in an added or renamed-to name;
+- an added or renamed-to name under the reserved `hub` root
+  (`RESERVED_NAME`);
+- the same name added twice in one submission (`ILLEGAL_OP_SEQUENCE`);
+- errors found by the local Shape-definition checks.
+
+#### `OperationBuilder` methods take the name first
+
+**What it was.** `add({ name, data })`, `revise({ name, data })`,
+`retract(target)`, `reaffirm({ name, kind, ... })`; no `rename`.
+
+**What it is now.**
+
+| Method | After |
+|---|---|
+| `add` | `add(name, { shapes \| shapeless, data, ... })` |
+| `revise` | `revise(name, { shapes \| shapeless \| keepShapes, data, ... })` |
+| `retract` | `retract(name, { reason? })` |
+| `reaffirm` | `reaffirm(name, { add?, remove? })` |
+| `rename` | `rename(name, newName)` (new) |
+
+Each add and revise states its Shapes in exactly one way: `shapes: [...]`,
+`shapeless: true`, or (revise only) `keepShapes: true`. The builder refuses
+zero ways or more than one, `keepShapes` on an add, `shapeless` on a
+`hub/shapes/X` name, and `shapes: []` on a non-Shape name (spell that
+`shapeless: true`).
+
+**Migration.**
+
+```ts
+// Before
+import { OperationBuilder } from '@warmhub/sdk-ts'
+const ob = new OperationBuilder()
+ob.add({ name: 'Deal/acme', data: { company: 'Acme' } })
+ob.retract('Deal/old')
+await ob.commit({ client, orgName: 'acme', repoName: 'world', message: 'seed' })
+
+// After
+import { createOperationEventRequestId } from '@warmhub/sdk-ts'
+
+await client.shape.create('acme', 'world', 'Deal', { company: 'string' }, {
+  eventRequestId: createOperationEventRequestId(),
+})
+
+await client.commit.apply(
+  'acme',
+  'world',
+  'seed',
+  client
+    .ops()
+    .add('acme', { shapes: ['Deal'], data: { company: 'Acme' } })
+    .add('scratch', { shapeless: true, data: { note: 'free' } })
+    .rename('scratch', 'scratch-2')
+    .retract('old'),
+)
+
+// A later submission: keepShapes revises a Thing that already exists
+await client.commit.apply(
+  'acme',
+  'world',
+  'update',
+  client.ops().revise('acme', { keepShapes: true, data: { company: 'Acme 2' } }),
+)
+```
+
+A `keepShapes` revise of a Thing added or renamed earlier in the same
+submission is refused; state `shapes` instead.
+
+#### Builder errors are `WriteOperationError`, raised when an operation is queued
+
+**What it was.** Some refusals surfaced only at commit.
+
+**What it is now.** A per-operation refusal throws at the `.add(...)` or
+`.revise(...)` call. Whole-batch refusals ("already submitted", "in flight")
+have `operationIndex: undefined`. The code is usually `VALIDATION_ERROR`;
+it can also be `RESERVED_NAME`, `ILLEGAL_OP_SEQUENCE`, a Shape-name check
+code, or (for `keepShapes`, at submit) `NOT_FOUND`.
+
+**Migration.**
+
+```ts
+import { WriteOperationError, type AddInput } from '@warmhub/sdk-ts'
+
+try {
+  client.ops().add('acme', { data: {} } as AddInput) // no Shapes stated
+} catch (e) {
+  if (e instanceof WriteOperationError) console.log(e.code, e.operationIndex) // VALIDATION_ERROR 0
+}
+```
+
+#### Every reference argument uses the new grammar
+
+**What it was.** Read and write calls took `Deal/acme`, and a Shape was
+`Deal`.
+
+**What it is now.** Pass the Thing name (`acme`) and `hub/shapes/Deal` for a
+Shape where any Thing can appear. An old spelling is looked up literally: a
+single read gets `NOT_FOUND`, and `thing.getMany` lists it in `missing`.
+Globs (`match`) match Thing names, and `*` does not cross `/`.
+
+**Migration.**
+
+```ts
+// Before
+await client.thing.get('acme', 'world', 'Deal/acme')
+// After
+await client.thing.get('acme', 'world', 'acme')
+```
+
+#### `thing.rename` takes full names
+
+**What it was.** `rename(org, repo, shapeName, oldName, newName, opts)`.
+
+**What it is now.** `rename(org, repo, name, newName, opts)`. A call in the
+old argument order is refused locally with `VALIDATION_ERROR`.
+
+**Migration.**
+
+```ts
+// Before
+await client.thing.rename('acme', 'world', 'Deal', 'acme', 'acme-corp', { eventRequestId })
+// After
+await client.thing.rename('acme', 'world', 'acme', 'acme-corp', { eventRequestId })
+```
+
+#### Read results drop `shape`, `shapeName` and `validatedShape`
+
+**What it was.** Results carried a single Shape.
+
+**What it is now.** Use `declaredShapes` (the Shapes the version states)
+and `validatedShapes` (the Shapes it satisfies, including composed ones).
+Both hold version-pinned names such as `Deal@v3`. The removal covers
+`ThingDetail`, `ThingItem`, `thing.getMany` items, `thing.getWithLease`,
+history versions and history's `thing`, refs items, component owned Things
+and `view.evaluate` items. `SynthesizedRepoContent.shape` becomes
+`declaredShapes` / `validatedShapes`.
+
+`ThingDetail` allows extra keys, so `detail.shapeName` still compiles; it is
+`undefined` at run time. Search your code for these field names.
+
+`shape` as an input filter (`thing.head(org, repo, { shape: 'Deal' })`) is
+unchanged.
+
+**Migration.**
+
+```ts
+// Before
+const shape = detail.shapeName
+// After
+const shapes = (detail.declaredShapes ?? []).map((w) => w.replace(/@v\d+$/, ''))
+```
+
+#### Token scopes use `grants`, on input and output
+
+**What it was.** A scope entry carried `allowedMatches` and `allowedShapes`.
+
+**What it is now.** Restrictions are a list of (paths, Shapes) pairs in
+`grants`.
+
+- Input (`token.create`): the entry-level fields are still typed `unknown`,
+  so old code compiles, but the server refuses them with "allowedMatches and
+  allowedShapes are no longer scope-entry fields: give each (paths, Shapes)
+  pair in grants…".
+- Output (`TokenCreateResult`, token metadata, whoami scopes): the
+  entry-level fields are removed, and reading them is a compile error. Read
+  `grants`.
+- `org.setMemberScopes` takes entries with `resource` and `permissions`
+  only; restrictions on member scopes are refused.
+- A pair must carry a non-empty `allowedMatches`, or an `allowedShapes`
+  with at least one key. `grants: []`, `{}` and `{ allowedShapes: {} }` are
+  refused.
+- `shapeless: true` in a clause is not a restriction of its own: it lets
+  Things with no Shape through. Alone it admits every Thing the pair's paths
+  match, shaped or shapeless; beside `shapes` it adds shapeless Things to
+  the Things the clause covers. No clause restricts a pair to shapeless
+  Things only.
+
+**Migration.**
+
+```ts
+// Before
+await client.token.create({ name: 'ci', scopes: [
+  { resource: 'acme/world', permissions: ['read'], allowedMatches: ['Deal/**'] },
+] })
+// After
+await client.token.create({ name: 'ci', scopes: [
+  { resource: 'acme/world', permissions: ['read'],
+    grants: [{ allowedMatches: ['**'], allowedShapes: { shapes: ['Deal'] } }] },
+] })
+```
+
+#### Repository exports are format 6, and the delta fold needs formats
+
+**What it was.** Exports were format 5, and
+`applyRepositoryExportDelta(base, delta)` returned rows keyed by durable id.
+
+**What it is now.**
+
+- The server writes format 6. This SDK reads 5 and 6; older SDKs read only
+  5, so they cannot read exports made after this release reaches
+  production.
+- Format 6 uses new-grammar references, has one row per Shape version, and
+  may carry `retracted: true` on Shape rows. A Shape tombstone in format 6
+  is rejected as `row_invalid`.
+- `applyRepositoryExportDelta` takes a third argument, the formats. Mixing
+  format 5 and format 6 throws `RepositoryExportError` with reason
+  `format_mismatch`.
+- In the returned map, format 6 Shape rows are keyed `durableId@vN`, not
+  `durableId`. Code that looks a Shape up by durable id, or keys its own map
+  by durable id, must account for versions.
+
+**Migration.**
+
+```ts
+// Before
+const current = applyRepositoryExportDelta(base, delta)
+// After
+const current = applyRepositoryExportDelta(base, delta, {
+  base: baseSession.header!.formatVersion,
+  delta: deltaSession.header!.formatVersion,
+})
+```
+
+#### `stream.append` takes new-grammar operations only
+
+**What it was.** `stream.append` took the old operation form.
+
+**What it is now.** It takes new-grammar operations and does not accept
+`keepShapes` (use `createKeepShapesResolver`). Its only local check is a
+pinned Shape; everything else is checked by the server.
+
+**Migration.** Send `{ operation, name, shapes, data }` operations.
+
+#### Writes need a server running this release
+
+**What it was.** The SDK wrote to any current server.
+
+**What it is now.** Against an older server, writes fail the compatibility
+check with "@warmhub/sdk-ts requires write contract 3, but the backend
+provides 2."
+
+**Migration.** Upgrade the SDK after the server.
+
+### Added
+
+- **`client.ops(options?)`** — returns a new `OperationBuilder`.
+- **`shapeName(bare)`** — `'Deal'` to `'hub/shapes/Deal'`; idempotent.
+- **`isShapeReference(value)`** — true for a bare, unpinned Shape name.
+- **`WriteOperationError`** (extends `WarmHubError`) — with
+  `operationIndex`; its message starts `Invalid operation at index N:`.
+- **Types** — `WriteOperation`, `KeepShapesRevise`, `AddInput`,
+  `ReviseInput`, `RetractInput`, `ReaffirmInput`, `ShapesChoice`,
+  `CommitValidateOperations`, `RepositoryExportDeltaFormats`,
+  `ThingShapesReader`.
+- **`keepShapes: true` on a revise** — at submit the SDK reads the Thing's
+  current Shapes and version and sends both, the version as
+  `expectedVersion` (a supplied `expectedVersion` wins). Shapes are sent
+  bare, so the revise is checked against each Shape's current version. A
+  missing Thing is refused with `NOT_FOUND`. A Thing added, or renamed to or
+  from, earlier in the same submission is refused. A Thing revised earlier in
+  the same submission reuses that revise's Shapes and sends no version.
+  Because the version is pinned, resubmitting the same `submissionId` from
+  another process can conflict; explicit `shapes` is the retry-safe form.
+  ```ts
+  await client.commit.apply('acme', 'world', 'm',
+    client.ops().revise('acme', { keepShapes: true, data: { company: 'Acme 2' } }))
+  ```
+- **`createKeepShapesResolver(read)`** — resolves `keepShapes` revises for
+  `stream.append`. It keeps state across calls, so use one resolver per
+  submission.
+  ```ts
+  const resolve = createKeepShapesResolver((names) => client.thing.getMany('acme', 'world', names))
+  await client.stream.append({ /* ... */ operations: await resolve([
+    { operation: 'revise', name: 'acme', keepShapes: true, data: {} },
+  ]) })
+  ```
+- **Builders everywhere** — `commit.validate`, `commit.apply` and
+  `commit.applyStreaming` accept an `OperationBuilder` as well as an array.
+- **`shapeless: true` read filter** — on `thing.head`, `thing.query`,
+  `thing.count` and `live.thingHead`: only Things with no Shape. It
+  cannot be combined with `shape`, `declaredShape`, `match`, a token
+  restricted by paths, or `sinceRepoSeq`, and is not available on search or
+  the changes feeds.
+  ```ts
+  await client.thing.head('acme', 'world', { shapeless: true })
+  ```
+- **`warnings.shapeless?: true`** — on per-operation write results.
+- **`ThingGetManyResult.missingHints`** — for a missing reference that is an
+  old `Shape/name` spelling of a Thing you can read, the text naming its new
+  form.
+- **`declaredShapes` on refs items and history's `thing`** (history also
+  gains `validatedShapes`).
+- **`redactedResource: true`** — may appear on `TokenCreateResult` scopes.
+- **`details.reason` values** — `'legacy-wrefs-window-ended'` (from the
+  server) and `'legacy-wrefs-sdk'` (local).
+- **`DEPENDENCY_FAILED`** — exported as a constant.
+- **`LEGACY_WREFS_REFUSAL` and `WarmHubClient.clientFlags`**.
+- **Export** — `RepositoryExportErrorReason` gains `'format_mismatch'`;
+  `RepositoryExportSession.lastShapeVersion`; an `onRow` option on
+  `restoreRepositoryExportSession`. A resume that breaks between two versions
+  of one Shape continues from the right version.
+
+### Behavior worth knowing
+
+- **`clientFlags: ['legacy-wrefs']` refuses every call.** The SDK does not
+  send old-grammar requests. With the flag set, reads, writes, streaming,
+  export and the compatibility check all throw `WarmHubError` with code
+  `CLIENT_INCOMPATIBLE`, `details.reason: 'legacy-wrefs-sdk'`, and the
+  message "`legacy-wrefs` is set; the SDKs are v2-only. Unset it, or use the
+  `wh` CLI for v1." Use the CLI to submit old-grammar files during the
+  compatibility window.
+
+### Changed
+
+- **Local checks before sending.** `commit.apply`, `commit.validate` and
+  the builder check every operation before sending when given an array or a
+  builder. An iterable, an async iterable, or `commit.applyStreaming` is
+  checked chunk by chunk, so a bad operation late in the source is refused
+  after earlier chunks were committed (`PartialStreamSubmissionError`).
+  `stream.append` checks only pinned Shapes.
+- **Content-limit error labels.**
+  ```text
+  Before: Field "Content/Readme.content" is N bytes; WarmHub content fields are limited to 65536 bytes. ...
+  After:  Field "Readme.content" is N bytes; WarmHub content fields are limited to 65536 bytes. ...
+  ```
+  `Agents.content` changes the same way.
+
+### Removed
+
+- **`AddOp`, `ReviseOp`, `RetractOp`, `CollectionAddOp`,
+  `CollectionAddType`, `OperationBuilderAddInput`** — use `WriteOperation`
+  and the builder input types.
+  ```ts
+  // Before
+  const op: AddOp = { name: 'Deal/acme', data: {} }
+  // After
+  const op: WriteOperation = { operation: 'add', name: 'acme', shapes: ['Deal'], data: {} }
+  ```
+- **Automatic old-grammar conversion** (`kind`, `about`, `type`/`members`,
+  `Shape/name` splitting).
+- **The local "Selector-backed revise requires a Set/<name> target wref"
+  check in `collection.revise`.** The server decides.
+
 ## 0.139.0
 
 No new release notes.

package/README.md

@@ -65,20 +65,23 @@ const client = new WarmHubClient({
 // One-time setup. Skip these three calls (or catch CONFLICT) on re-runs.
 await client.org.create('acme')
 await client.repo.create('acme', 'world', 'Game world')
-await client.shape.create('acme', 'world', 'Location', {
-  x: 'number',
-  y: 'number',
-  label: 'string',
-})
+await client.shape.create(
+  'acme',
+  'world',
+  'Location',
+  { x: 'number', y: 'number', label: 'string' },
+  { eventRequestId: crypto.randomUUID() },
+)
 
-await client.commit.apply('acme', 'world', 'seed cave', [
-  {
-    operation: 'add',
-    kind: 'thing',
-    name: 'Location/cave',
+await client.commit.apply(
+  'acme',
+  'world',
+  'seed cave',
+  client.ops().add('cave', {
+    shapes: ['Location'],
     data: { x: 0, y: 0, label: 'Dark Cave' },
-  },
-])
+  }),
+)
 
 const head = await client.thing.head('acme', 'world', { shape: 'Location' })
 ```
@@ -99,7 +102,7 @@ const client = new WarmHubClient({
 
 ## Entrypoints
 
-- `@warmhub/sdk-ts`: core client, types, errors, `OperationBuilder`
+- `@warmhub/sdk-ts`: core client, types, errors, `OperationBuilder` (`client.ops()`)
 
 ## Error Handling
 
@@ -119,24 +122,67 @@ try {
 }
 ```
 
-## OperationBuilder
+## Writing
 
-`OperationBuilder` is single-use: after a successful `commit()`, the builder
-is sealed and cannot be modified or reused.
+A write names a Thing by its full name (taken literally, `/` included) and
+states its Shapes. Build writes with `client.ops()`; every add and revise
+states its Shapes in exactly one way, or the builder throws a
+`WriteOperationError` (`VALIDATION_ERROR`, with `operationIndex`) before any
+request:
 
 ```ts
-import { OperationBuilder } from '@warmhub/sdk-ts'
-
-const ob = new OperationBuilder()
-ob.add({ name: 'Location/cave', data: { x: 0, y: 0 } })
-const result = await ob.commit({
-  client,
-  orgName: 'acme',
-  repoName: 'world',
-  message: 'seed cave',
-})
+import { shapeName } from '@warmhub/sdk-ts'
+
+const ops = client
+  .ops()
+  .add('acme', { shapes: ['Deal'], data: { company: 'Acme' } })
+  .add('scratch', { shapeless: true, data: { note: 'free' } })
+  .revise('acme', { shapes: ['Deal'], data: { company: 'Acme 2' } })
+  .add('r1', { shapes: ['Rating'], data: { about: 'acme', score: 5 } })
+  .add('crew', { shapes: ['Set'], data: { members: ['acme'] } })
+  .rename('scratch', 'scratch-2')
+  .retract('crew', { reason: 'disbanded' })
+  // A Shape is the Thing hub/shapes/X, written with shapes: [].
+  .add(shapeName('Deal'), { shapes: [], data: { fields: { company: 'string' } } })
+
+await client.commit.apply('acme', 'world', 'seed', ops)
 ```
 
+`commit.apply`, `commit.validate` and `commit.applyStreaming` also take plain
+`WriteOperation[]` (`{ operation: 'add', name, shapes, data }`). A v1-shaped
+operation (`kind`, `Shape/name` adds, top-level `about`, collection
+`type`/`members`) is refused, and the error shows its v2 form. Raw v1 input
+from typed TypeScript needs a cast: the v1 types are gone.
+
+- An assertion (`r1` above) is a Thing one of whose declared Shapes composes
+  `Assertion`, with its target in `data.about`.
+- `shapes: ['Deal', 'Contactable']`: bare Shape names. A pin (`Deal@v2`) is
+  refused: a write always certifies under each Shape's head version.
+- `shapeless: true` (builder option): no Shape; the data is stored but not
+  validated, and the operation result carries `warnings.shapeless`. A raw
+  operation spells it `shapes: []`. A Shape (`hub/shapes/X`) is written with
+  `shapes: []`, never `shapeless`.
+- `keepShapes: true` (revise only): the SDK reads the Thing's current Shapes
+  and version and sends both, the version as `expectedVersion` (a supplied
+  `expectedVersion` wins). A Thing revised earlier in the same submission
+  carries that revise's Shapes and no version; one added, or renamed to or
+  from, earlier in the same submission is refused before anything is sent
+  (submit it in a later request, or pass `shapes`). **keepShapes pins the version
+  it read; a cross-process resubmit of the same submissionId can conflict;
+  explicit shapes is the retry-safe form.** The Shapes are sent bare, so the
+  revise re-certifies under each Shape's head version.
+
+A builder can also submit itself with `ops.commit({ client, orgName,
+repoName })`. Either way it is single-use: once submitted it is sealed. Every
+local refusal, per operation or for the whole batch ("already submitted",
+"in flight"), is a `WriteOperationError` with code `VALIDATION_ERROR`
+unless it names another; `operationIndex` is unset for a whole-batch one.
+
+**`legacy-wrefs`:** the SDK is v2-only. With `clientFlags: ['legacy-wrefs']`
+it refuses every call, read or write, before any request (the compatibility
+probe included) with `LEGACY_WREFS_REFUSAL`. To write v1 during the
+compatibility window, use the `wh` CLI.
+
 ## API Docs
 
 Generated API reference is published at [docs.warmhub.ai/sdk-reference/readme/](https://docs.warmhub.ai/sdk-reference/readme/) — the landing page lists every public class, interface, type alias, variable, and function exported from the main `@warmhub/sdk-ts` entrypoint.

package/changelog.json

@@ -150,6 +150,32 @@
       "version": "0.139.0",
       "sourceSha": "01575d928d1214ed8556301179ef2a4509c28383",
       "notes": []
+    },
+    {
+      "version": "0.140.0",
+      "sourceSha": "6d99197d6e84edc1e7842634e0f5e4b810c80824",
+      "notes": [
+        {
+          "id": "export-resume-format-guard",
+          "body": "### Changed\n\nA resumed repository export now sends the `formatVersion` of the header the download opened with, and the server refuses a resume whose format is not the one it writes: HTTP 412 `client-incompatible` with the message \"Restart the export; a resume must use the format it started with.\" A download started before a server upgrade that changes the export format can no longer be silently finished under its old header; the resume fails and the export must be restarted.\n\nA resume of a file that holds only the header (interrupted before the first row) sends no cursor, so the server cannot check it; the session now compares the new header's format to the saved one and raises `RepositoryExportError` (`header_invalid`) with the same restart message rather than appending new-format rows under the old header.\n\n**Upgrade with the server.** An older SDK sends no `formatVersion` on a resume, so a server with this change refuses every resume from it, not only cross-format ones. Upgrade the SDK in the same release as the server."
+        },
+        {
+          "id": "is-all-stream-operations-failed-error",
+          "body": "### Added\n\n`isAllStreamOperationsFailedError(error)` reports whether a thrown value is an all-failed stream error. Unlike `error instanceof AllStreamOperationsFailedError`, it also recognizes the error after `toWarmHubError` normalization and when a different copy of the SDK threw it."
+        },
+        {
+          "id": "name-taken-durable-id-only",
+          "body": "### Breaking\n\n#### `NAME_TAKEN` names the holder by durable id only and offers no replacement name\n\n**What it was.** A `name_taken` error's `details.takenBy` was `{ shape, durableId }`, `details.suggestedName` could carry a replacement name, and the message said `by a <Shape> Thing` and `for example \"<name>\"`.\n\n**What it is now.** `details.takenBy` is `{ durableId }`; `shape` is removed. `details.suggestedName` is removed and no example name appears in the message or hint. The message names no Shape: `Name \"acme\" is already taken in this repository by another Thing; choose another name`. A caller who cannot read the holder still gets no `takenBy` and no `by another Thing`. The `name_taken` decoder in the streaming submission protocol requires only `takenBy.durableId`.\n\n**Why it breaks.** This is a client-visible breaking change, accepted. Released sdk-ts 0.135.0 to 0.139.0 decode `takenBy` with `shape` required, so they refuse a `name_taken` result from a server that carries this change. It lands before the v2 floor release (0.140.0), so no v2 client sees `shape`.\n\n**Migration.** Read the holder's Shapes with `get` on `details.takenBy.durableId`; a Thing can have several Shapes or none. Choose the replacement name yourself.\n\n```ts\n// Before\nconst { takenBy, suggestedName } = details\nconsole.log(takenBy?.shape, suggestedName)\n\n// After\nconst holder = details.takenBy && (await client.thing.get(org, repo, details.takenBy.durableId))\n```"
+        },
+        {
+          "id": "restore-operation",
+          "body": "### Added\n\nThe `restore` operation and `OperationBuilder.restore()` make a retracted Thing active again, by its durable ID. Pass `newName` to restore it under another name."
+        },
+        {
+          "id": "v2-write-form",
+          "body": "In these notes, \"old grammar\" means the reference form used before this release (`Deal/acme`, operations with `kind`), and \"new grammar\" the form this release introduces (`acme`, operations with `shapes`).\n\n### Breaking\n\n#### Write operations take `name` and `shapes`\n\n**What it was.** Operations carried `kind`, an add name spelled\n`Shape/name`, a top-level `about`, or collection `type`/`members`, and the\nSDK converted them.\n\n**What it is now.** `Operation`, `AddOperation`, `ReviseOperation`,\n`RetractOperation`, `ReaffirmOperation` and `RenameOperation` keep their\nnames but have the new shape. An add or revise requires `name`, `shapes`\nand `data`. `kind` and `shape` are typed `never`. The new `WriteOperation`\ntype is one operation of that form.\n\n- A Shape is the Thing `hub/shapes/X` (`shapeName('X')`), written with\n  `shapes: []`.\n- An assertion is a Thing one of whose declared Shapes composes `Assertion`,\n  with its target in `data.about`.\n- A collection is a Thing of its collection Shape:\n  `{ shapes: ['Set'], data: { members } }`.\n\n**Migration.**\n\n```ts\n// Before\nawait client.commit.apply('acme', 'world', 'seed', [\n  { operation: 'add', kind: 'thing', name: 'Deal/acme', data: { company: 'Acme' } },\n])\n\n// After\nawait client.commit.apply('acme', 'world', 'seed', [\n  { operation: 'add', name: 'acme', shapes: ['Deal'], data: { company: 'Acme' } },\n])\n```\n\n#### Old-grammar operations are refused before any request\n\n**What it was.** The SDK converted old-grammar operations.\n\n**What it is now.** An operation with `kind`, `shape`, `wref`,\n`declaredShapes`, `about`, collection `type` or `members`, or with no\n`operation`, is refused with a `WriteOperationError` before anything is\nsent. The message shows a suggested new form, with data values replaced by\n`\"...\"`. Names and `about` targets are copied as written, so check them: a\nsuggested `name: 'Deal/acme'` would address a Thing literally named\n`Deal/acme`. An add or revise with no `shapes` is refused with a message\nthat it states no Shapes.\n\nOld-grammar input no longer type-checks, so it reaches this refusal only\nthrough a cast.\n\n**Migration.**\n\n```ts\n// Before: converted and sent\nawait client.commit.apply('acme', 'world', 'rate', [\n  { operation: 'add', kind: 'assertion', name: 'Rating/r1', about: 'Deal/acme', data: { score: 5 } },\n])\n\n// After\nawait client.commit.apply('acme', 'world', 'rate', [\n  { operation: 'add', name: 'r1', shapes: ['Rating'], data: { about: 'acme', score: 5 } },\n])\n```\n\nOther operations refused locally:\n\n- a pinned Shape in `shapes` (`Deal@v2`), or an entry that is not a bare\n  Shape name (`hub/shapes/Deal`, anything with `/`);\n- `shapeless` on a raw operation (spell it `shapes: []`);\n- non-empty `shapes` on a `hub/shapes/X` name;\n- an add or revise without `data`, and `keepShapes` on an add;\n- `affirmedTargets` on a shapeless write;\n- `expectedVersion` on an add, and `active` on a revise;\n- renaming a Shape to a non-Shape name, or the reverse;\n- `+` in an added or renamed-to name;\n- an added or renamed-to name under the reserved `hub` root\n  (`RESERVED_NAME`);\n- the same name added twice in one submission (`ILLEGAL_OP_SEQUENCE`);\n- errors found by the local Shape-definition checks.\n\n#### `OperationBuilder` methods take the name first\n\n**What it was.** `add({ name, data })`, `revise({ name, data })`,\n`retract(target)`, `reaffirm({ name, kind, ... })`; no `rename`.\n\n**What it is now.**\n\n| Method | After |\n|---|---|\n| `add` | `add(name, { shapes \\| shapeless, data, ... })` |\n| `revise` | `revise(name, { shapes \\| shapeless \\| keepShapes, data, ... })` |\n| `retract` | `retract(name, { reason? })` |\n| `reaffirm` | `reaffirm(name, { add?, remove? })` |\n| `rename` | `rename(name, newName)` (new) |\n\nEach add and revise states its Shapes in exactly one way: `shapes: [...]`,\n`shapeless: true`, or (revise only) `keepShapes: true`. The builder refuses\nzero ways or more than one, `keepShapes` on an add, `shapeless` on a\n`hub/shapes/X` name, and `shapes: []` on a non-Shape name (spell that\n`shapeless: true`).\n\n**Migration.**\n\n```ts\n// Before\nimport { OperationBuilder } from '@warmhub/sdk-ts'\nconst ob = new OperationBuilder()\nob.add({ name: 'Deal/acme', data: { company: 'Acme' } })\nob.retract('Deal/old')\nawait ob.commit({ client, orgName: 'acme', repoName: 'world', message: 'seed' })\n\n// After\nimport { createOperationEventRequestId } from '@warmhub/sdk-ts'\n\nawait client.shape.create('acme', 'world', 'Deal', { company: 'string' }, {\n  eventRequestId: createOperationEventRequestId(),\n})\n\nawait client.commit.apply(\n  'acme',\n  'world',\n  'seed',\n  client\n    .ops()\n    .add('acme', { shapes: ['Deal'], data: { company: 'Acme' } })\n    .add('scratch', { shapeless: true, data: { note: 'free' } })\n    .rename('scratch', 'scratch-2')\n    .retract('old'),\n)\n\n// A later submission: keepShapes revises a Thing that already exists\nawait client.commit.apply(\n  'acme',\n  'world',\n  'update',\n  client.ops().revise('acme', { keepShapes: true, data: { company: 'Acme 2' } }),\n)\n```\n\nA `keepShapes` revise of a Thing added or renamed earlier in the same\nsubmission is refused; state `shapes` instead.\n\n#### Builder errors are `WriteOperationError`, raised when an operation is queued\n\n**What it was.** Some refusals surfaced only at commit.\n\n**What it is now.** A per-operation refusal throws at the `.add(...)` or\n`.revise(...)` call. Whole-batch refusals (\"already submitted\", \"in flight\")\nhave `operationIndex: undefined`. The code is usually `VALIDATION_ERROR`;\nit can also be `RESERVED_NAME`, `ILLEGAL_OP_SEQUENCE`, a Shape-name check\ncode, or (for `keepShapes`, at submit) `NOT_FOUND`.\n\n**Migration.**\n\n```ts\nimport { WriteOperationError, type AddInput } from '@warmhub/sdk-ts'\n\ntry {\n  client.ops().add('acme', { data: {} } as AddInput) // no Shapes stated\n} catch (e) {\n  if (e instanceof WriteOperationError) console.log(e.code, e.operationIndex) // VALIDATION_ERROR 0\n}\n```\n\n#### Every reference argument uses the new grammar\n\n**What it was.** Read and write calls took `Deal/acme`, and a Shape was\n`Deal`.\n\n**What it is now.** Pass the Thing name (`acme`) and `hub/shapes/Deal` for a\nShape where any Thing can appear. An old spelling is looked up literally: a\nsingle read gets `NOT_FOUND`, and `thing.getMany` lists it in `missing`.\nGlobs (`match`) match Thing names, and `*` does not cross `/`.\n\n**Migration.**\n\n```ts\n// Before\nawait client.thing.get('acme', 'world', 'Deal/acme')\n// After\nawait client.thing.get('acme', 'world', 'acme')\n```\n\n#### `thing.rename` takes full names\n\n**What it was.** `rename(org, repo, shapeName, oldName, newName, opts)`.\n\n**What it is now.** `rename(org, repo, name, newName, opts)`. A call in the\nold argument order is refused locally with `VALIDATION_ERROR`.\n\n**Migration.**\n\n```ts\n// Before\nawait client.thing.rename('acme', 'world', 'Deal', 'acme', 'acme-corp', { eventRequestId })\n// After\nawait client.thing.rename('acme', 'world', 'acme', 'acme-corp', { eventRequestId })\n```\n\n#### Read results drop `shape`, `shapeName` and `validatedShape`\n\n**What it was.** Results carried a single Shape.\n\n**What it is now.** Use `declaredShapes` (the Shapes the version states)\nand `validatedShapes` (the Shapes it satisfies, including composed ones).\nBoth hold version-pinned names such as `Deal@v3`. The removal covers\n`ThingDetail`, `ThingItem`, `thing.getMany` items, `thing.getWithLease`,\nhistory versions and history's `thing`, refs items, component owned Things\nand `view.evaluate` items. `SynthesizedRepoContent.shape` becomes\n`declaredShapes` / `validatedShapes`.\n\n`ThingDetail` allows extra keys, so `detail.shapeName` still compiles; it is\n`undefined` at run time. Search your code for these field names.\n\n`shape` as an input filter (`thing.head(org, repo, { shape: 'Deal' })`) is\nunchanged.\n\n**Migration.**\n\n```ts\n// Before\nconst shape = detail.shapeName\n// After\nconst shapes = (detail.declaredShapes ?? []).map((w) => w.replace(/@v\\d+$/, ''))\n```\n\n#### Token scopes use `grants`, on input and output\n\n**What it was.** A scope entry carried `allowedMatches` and `allowedShapes`.\n\n**What it is now.** Restrictions are a list of (paths, Shapes) pairs in\n`grants`.\n\n- Input (`token.create`): the entry-level fields are still typed `unknown`,\n  so old code compiles, but the server refuses them with \"allowedMatches and\n  allowedShapes are no longer scope-entry fields: give each (paths, Shapes)\n  pair in grants…\".\n- Output (`TokenCreateResult`, token metadata, whoami scopes): the\n  entry-level fields are removed, and reading them is a compile error. Read\n  `grants`.\n- `org.setMemberScopes` takes entries with `resource` and `permissions`\n  only; restrictions on member scopes are refused.\n- A pair must carry a non-empty `allowedMatches`, or an `allowedShapes`\n  with at least one key. `grants: []`, `{}` and `{ allowedShapes: {} }` are\n  refused.\n- `shapeless: true` in a clause is not a restriction of its own: it lets\n  Things with no Shape through. Alone it admits every Thing the pair's paths\n  match, shaped or shapeless; beside `shapes` it adds shapeless Things to\n  the Things the clause covers. No clause restricts a pair to shapeless\n  Things only.\n\n**Migration.**\n\n```ts\n// Before\nawait client.token.create({ name: 'ci', scopes: [\n  { resource: 'acme/world', permissions: ['read'], allowedMatches: ['Deal/**'] },\n] })\n// After\nawait client.token.create({ name: 'ci', scopes: [\n  { resource: 'acme/world', permissions: ['read'],\n    grants: [{ allowedMatches: ['**'], allowedShapes: { shapes: ['Deal'] } }] },\n] })\n```\n\n#### Repository exports are format 6, and the delta fold needs formats\n\n**What it was.** Exports were format 5, and\n`applyRepositoryExportDelta(base, delta)` returned rows keyed by durable id.\n\n**What it is now.**\n\n- The server writes format 6. This SDK reads 5 and 6; older SDKs read only\n  5, so they cannot read exports made after this release reaches\n  production.\n- Format 6 uses new-grammar references, has one row per Shape version, and\n  may carry `retracted: true` on Shape rows. A Shape tombstone in format 6\n  is rejected as `row_invalid`.\n- `applyRepositoryExportDelta` takes a third argument, the formats. Mixing\n  format 5 and format 6 throws `RepositoryExportError` with reason\n  `format_mismatch`.\n- In the returned map, format 6 Shape rows are keyed `durableId@vN`, not\n  `durableId`. Code that looks a Shape up by durable id, or keys its own map\n  by durable id, must account for versions.\n\n**Migration.**\n\n```ts\n// Before\nconst current = applyRepositoryExportDelta(base, delta)\n// After\nconst current = applyRepositoryExportDelta(base, delta, {\n  base: baseSession.header!.formatVersion,\n  delta: deltaSession.header!.formatVersion,\n})\n```\n\n#### `stream.append` takes new-grammar operations only\n\n**What it was.** `stream.append` took the old operation form.\n\n**What it is now.** It takes new-grammar operations and does not accept\n`keepShapes` (use `createKeepShapesResolver`). Its only local check is a\npinned Shape; everything else is checked by the server.\n\n**Migration.** Send `{ operation, name, shapes, data }` operations.\n\n#### Writes need a server running this release\n\n**What it was.** The SDK wrote to any current server.\n\n**What it is now.** Against an older server, writes fail the compatibility\ncheck with \"@warmhub/sdk-ts requires write contract 3, but the backend\nprovides 2.\"\n\n**Migration.** Upgrade the SDK after the server.\n\n### Added\n\n- **`client.ops(options?)`** — returns a new `OperationBuilder`.\n- **`shapeName(bare)`** — `'Deal'` to `'hub/shapes/Deal'`; idempotent.\n- **`isShapeReference(value)`** — true for a bare, unpinned Shape name.\n- **`WriteOperationError`** (extends `WarmHubError`) — with\n  `operationIndex`; its message starts `Invalid operation at index N:`.\n- **Types** — `WriteOperation`, `KeepShapesRevise`, `AddInput`,\n  `ReviseInput`, `RetractInput`, `ReaffirmInput`, `ShapesChoice`,\n  `CommitValidateOperations`, `RepositoryExportDeltaFormats`,\n  `ThingShapesReader`.\n- **`keepShapes: true` on a revise** — at submit the SDK reads the Thing's\n  current Shapes and version and sends both, the version as\n  `expectedVersion` (a supplied `expectedVersion` wins). Shapes are sent\n  bare, so the revise is checked against each Shape's current version. A\n  missing Thing is refused with `NOT_FOUND`. A Thing added, or renamed to or\n  from, earlier in the same submission is refused. A Thing revised earlier in\n  the same submission reuses that revise's Shapes and sends no version.\n  Because the version is pinned, resubmitting the same `submissionId` from\n  another process can conflict; explicit `shapes` is the retry-safe form.\n  ```ts\n  await client.commit.apply('acme', 'world', 'm',\n    client.ops().revise('acme', { keepShapes: true, data: { company: 'Acme 2' } }))\n  ```\n- **`createKeepShapesResolver(read)`** — resolves `keepShapes` revises for\n  `stream.append`. It keeps state across calls, so use one resolver per\n  submission.\n  ```ts\n  const resolve = createKeepShapesResolver((names) => client.thing.getMany('acme', 'world', names))\n  await client.stream.append({ /* ... */ operations: await resolve([\n    { operation: 'revise', name: 'acme', keepShapes: true, data: {} },\n  ]) })\n  ```\n- **Builders everywhere** — `commit.validate`, `commit.apply` and\n  `commit.applyStreaming` accept an `OperationBuilder` as well as an array.\n- **`shapeless: true` read filter** — on `thing.head`, `thing.query`,\n  `thing.count` and `live.thingHead`: only Things with no Shape. It\n  cannot be combined with `shape`, `declaredShape`, `match`, a token\n  restricted by paths, or `sinceRepoSeq`, and is not available on search or\n  the changes feeds.\n  ```ts\n  await client.thing.head('acme', 'world', { shapeless: true })\n  ```\n- **`warnings.shapeless?: true`** — on per-operation write results.\n- **`ThingGetManyResult.missingHints`** — for a missing reference that is an\n  old `Shape/name` spelling of a Thing you can read, the text naming its new\n  form.\n- **`declaredShapes` on refs items and history's `thing`** (history also\n  gains `validatedShapes`).\n- **`redactedResource: true`** — may appear on `TokenCreateResult` scopes.\n- **`details.reason` values** — `'legacy-wrefs-window-ended'` (from the\n  server) and `'legacy-wrefs-sdk'` (local).\n- **`DEPENDENCY_FAILED`** — exported as a constant.\n- **`LEGACY_WREFS_REFUSAL` and `WarmHubClient.clientFlags`**.\n- **Export** — `RepositoryExportErrorReason` gains `'format_mismatch'`;\n  `RepositoryExportSession.lastShapeVersion`; an `onRow` option on\n  `restoreRepositoryExportSession`. A resume that breaks between two versions\n  of one Shape continues from the right version.\n\n### Behavior worth knowing\n\n- **`clientFlags: ['legacy-wrefs']` refuses every call.** The SDK does not\n  send old-grammar requests. With the flag set, reads, writes, streaming,\n  export and the compatibility check all throw `WarmHubError` with code\n  `CLIENT_INCOMPATIBLE`, `details.reason: 'legacy-wrefs-sdk'`, and the\n  message \"`legacy-wrefs` is set; the SDKs are v2-only. Unset it, or use the\n  `wh` CLI for v1.\" Use the CLI to submit old-grammar files during the\n  compatibility window.\n\n### Changed\n\n- **Local checks before sending.** `commit.apply`, `commit.validate` and\n  the builder check every operation before sending when given an array or a\n  builder. An iterable, an async iterable, or `commit.applyStreaming` is\n  checked chunk by chunk, so a bad operation late in the source is refused\n  after earlier chunks were committed (`PartialStreamSubmissionError`).\n  `stream.append` checks only pinned Shapes.\n- **Content-limit error labels.**\n  ```text\n  Before: Field \"Content/Readme.content\" is N bytes; WarmHub content fields are limited to 65536 bytes. ...\n  After:  Field \"Readme.content\" is N bytes; WarmHub content fields are limited to 65536 bytes. ...\n  ```\n  `Agents.content` changes the same way.\n\n### Removed\n\n- **`AddOp`, `ReviseOp`, `RetractOp`, `CollectionAddOp`,\n  `CollectionAddType`, `OperationBuilderAddInput`** — use `WriteOperation`\n  and the builder input types.\n  ```ts\n  // Before\n  const op: AddOp = { name: 'Deal/acme', data: {} }\n  // After\n  const op: WriteOperation = { operation: 'add', name: 'acme', shapes: ['Deal'], data: {} }\n  ```\n- **Automatic old-grammar conversion** (`kind`, `about`, `type`/`members`,\n  `Shape/name` splitting).\n- **The local \"Selector-backed revise requires a Set/<name> target wref\"\n  check in `collection.revise`.** The server decides.\n"
+        }
+      ]
     }
   ]
 }