@warmhub/sdk-ts 0.139.0 → 0.141.0

package/CHANGELOG.md

@@ -2,6 +2,469 @@
 
 <!-- warmhub-changelog-artifact:v1 -->
 
+## 0.141.0
+
+No new release notes.
+
+## 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.