Write Methods

WarmHub has one write path: every mutation lands through the same operation pipeline. The TypeScript SDK gives you two ways to submit operations:

client.commit.apply(...) for call sites that already have operation arrays.
OperationBuilder for call sites that benefit from incremental construction and local validation.

Both submit operations through the same write path and return the same per-operation result shape. client.commit.apply(...) accepts the full Operation union — including RenameOperation — while OperationBuilder exposes helpers for add, revise, and retract only. If you need to submit rename operations, pass them directly via client.commit.apply(...). For the full rename payload shape and rename-specific rules, see Write Operations and the RenameOperation SDK reference.

Choosing an API

Need	Prefer
Submit a small operation array directly	`client.commit.apply(...)`
Build operations across several branches or helper functions	`OperationBuilder`
Run client-side preflight checks before any server call (and shape-data validation when constructed with `{ shapes }`)	`OperationBuilder`
Preserve a raw operation payload from another system	`client.commit.apply(...)`
Chain add, revise, and retract calls fluently	`OperationBuilder`
Submit rename operations	`client.commit.apply(...)`
Tag a caller-managed stream for diagnostics	Either, with advanced stream options

await client.commit.apply('acme', 'world', 'seed cave', [
  {
    operation: 'add',
    name: 'Location/cave',
    data: { x: 0, y: 0 },
  },
])

import { OperationBuilder } from '@warmhub/sdk-ts'

const builder = new OperationBuilder()
builder.add({ name: 'Location/cave', data: { x: 0, y: 0 } })
builder.add({ name: 'Location/forest', data: { x: 5, y: 3 } })

const check = builder.validate()
if (!check.valid) {
  throw new Error(check.errors.map((e) => e.message).join('; '))
}

await builder.commit({
  client,
  orgName: 'acme',
  repoName: 'world',
  message: 'seed locations',
})

The builder has no .build() step and is not itself a promise — await builder does nothing. builder.commit({...}) is the only finalizer; it validates, submits, and seals the builder so calling builder.commit(...) a second time throws.

Typing Operation arrays

Operation is a discriminated union over AddOperation, ReviseOperation, RetractOperation, and RenameOperation, keyed on the operation field. When the array is passed inline to client.commit.apply, the parameter type narrows the literal for you and the call typechecks with no extra ceremony.

When you bind the array to a variable first without a type annotation, TypeScript widens operation: "add" to operation: string, and the variable no longer assigns to the Operation[] parameter. Two equivalent fixes — pick whichever fits the call site:

import type { Operation } from "@warmhub/sdk-ts";

// 1. Annotate the variable — contextually typed by the annotation.
const operations: Operation[] = [
  { operation: "add", kind: "thing", name: "Sensor/temp-1", data: { x: 1 } },
  { operation: "revise", name: "Sensor/temp-1", data: { x: 2 } },
];

// 2. Or `satisfies` — preserves the inferred literal types instead of
//    widening them to `Operation`.
const operations2 = [
  { operation: "add", kind: "thing", name: "Sensor/temp-1", data: { x: 1 } },
  { operation: "revise", name: "Sensor/temp-1", data: { x: 2 } },
] satisfies Operation[];

await client.commit.apply("acme", "world", "seed", operations);

as const works too, at the cost of marking the whole array readonly.

Kind Inference

When kind is omitted, both write surfaces — client.commit.apply and OperationBuilder — infer it with the same shared rule, applied in order:

about present -> assertion
type and members both present -> collection
one-segment name (e.g. game-state) -> thing
two-segment Shape/name -> thing
three or more segments -> assertion

The rule is identical across surfaces; only where an invalid result is rejected differs. OperationBuilder rejects at .add()/.revise() time (a one-segment thing name fails the local-path preflight; an inferred assertion without about fails immediately rather than at commit()). client.commit.apply rejects while normalizing the operation or server-side, since the backend requires an explicit kind on every operation and never infers.

Shape adds always require explicit kind: 'shape' — a bare shape name (e.g. Player) is otherwise inferred as a thing and rejected as a thing-path violation. Use kind: 'thing' for hierarchical thing names such as GameState/round-1/state if you need to keep them on the thing path despite the segment count. Collection adds require both type and members; supplying only one of the two is rejected on both surfaces.

The same name-segmentation rule applies to kind-less revise operations.

The wh CLI shorthand is a separate, explicit-kind surface: it always sends a kind (defaulting to thing, or assertion when --about is supplied), so SDK inference never applies to CLI-built operations. See the write submit deep dive for the CLI’s defaulting rules.

Wref constraints are enforced server-side. An untyped wref accepts shapes and shaped things. A typed constraint uses the target’s resolved type: Player/alice can satisfy wref<Player>, while the Player shape itself has no governing resolved type and cannot. OperationBuilder validates field types and most local constraints, but it cannot prove a target’s resolved type until the operation reaches the server.

Version preconditions

revise and retract accept an optional expectedVersion — the write applies only if the target (thing, shape, assertion, or collection) is still at that version, otherwise it is rejected with a CONFLICT (details.reason: "expected_version_mismatch"). Use it for read-modify-write safety when you don’t need to hold an exclusive lease. See Conditional Operations for an overview of all three conditional write patterns across surfaces.

Read leases

revise and retract operations accept an optional leaseId to write under a read lease acquired with client.thing.getWithLease — a leased read requires write access and is never an anonymous read. The field is per-operation, so the client.commit.apply signature is unchanged; add is never lease-gated (a new thing has no prior version to lease).

const leased = await client.thing.getWithLease("acme", "world", "Player/alice", { ttlMs: 5000 });

await client.commit.apply("acme", "world", "update score", [
  { operation: "revise", name: "Player/alice", data: { score: 2 }, leaseId: leased.lease.id },
]);
// The lease auto-releases on a successful or no-op write. To bail out without writing,
// call client.thing.releaseLease("acme", "world", "Player/alice", leased.lease.id).

A successful (or no-op) write auto-releases the lease. If the lease has already expired, the write runs as an ordinary write — the same path you would take without a lease, following the usual version-conflict rules. But if another caller still holds the lease and your leaseId doesn’t match it, the write is rejected with LEASE_UNAVAILABLE.

Operation Results

Successful submissions return an OperationSubmitResult: the aggregate write result (operationCount, operations[], and partial plus statusCounts when any operation failed) with the ordered exact OperationEventReceiptV1 receipts nested under receipts, one immutable receipt per chunk. Each receipt contains its caller-known request ID, request digest, event or no-event outcome, and the existing ordered operation envelopes.

Repository sequence acknowledgement

An event receipt carries event.repoSeq as decimal text. A no-event receipt has event: null and no sequence.

const result = await client.commit.apply(
  'acme',
  'world',
  'seed cave',
  [{ operation: 'add', name: 'Location/cave', data: { x: 0, y: 0 } }],
)
console.log(result.receipts[0]?.event?.repoSeq) // e.g. "42"

const result = await builder.commit({
  client,
  orgName: 'acme',
  repoName: 'world',
  message: 'seed locations',
})
console.log(result.receipts[0]?.event?.repoSeq)

If a later stream chunk fails after earlier chunks were acknowledged, PartialStreamSubmissionError.completedReceipts preserves their exact repository sequences. Use the pending chunk’s eventRequestId for receipt lookup; do not infer its outcome from the earlier high-water mark. See Transient Retry.

Each per-operation error object may carry an optional details field that, when present, narrows to one of several typed arms depending on the failure. Simple failures such as add-conflicts produce a code and message but no details. When details is present, narrow on details.reason to access the arm-specific fields exposed by the SDK result shape:

`details.reason`	Additional fields	When it appears
`"expected_version_mismatch"`	`expectedVersion: number`; `currentVersion: number`	Version precondition failed
`"lease_held"`	`leaseExpiresAt: string` (ISO 8601)	Another caller holds the lease and the supplied `leaseId` does not match
`"validation_failed"`	`issues: { path: string; message: string }[]`	One or more fields on the submitted operation failed server-side validation; each entry in `issues` identifies the offending path and a human-readable message
`"rate_limit_reset"`	`retryAfterSeconds: number`; `resetAt: string` (ISO 8601)	The operation was rejected because a rate limit was hit; retry after the indicated interval

Check for details before narrowing on details.reason:

for (const receipt of receipts) {
  for (const op of receipt.operations) {
    if (op.status === 'failed' && op.error?.details) {
      const { details } = op.error
      if (details.reason === 'validation_failed') {
        for (const issue of details.issues) {
          console.error(`Validation error at ${issue.path}: ${issue.message}`)
        }
      } else if (details.reason === 'rate_limit_reset') {
        console.warn(`Rate limited — retry after ${details.retryAfterSeconds}s (resets at ${details.resetAt})`)
      }
    }
  }
}

Warnings are informational — a result can still be applied or no-op’d while carrying them. The warnings object is additive and can carry two kinds at once: undeclaredFields (top-level fields in the submitted data that the target shape does not declare) and coalescedWrefs (optional wref? fields whose resolver outcome was thing_absent and was coalesced to null — each entry carries fieldPath, wref, and reason). Missing shapes and every other failure remain hard errors. Each kind reports truncation (undeclaredFieldsTruncated / coalescedWrefsTruncated) with a full count when its list is capped. See Coalesced optional-wref warnings.

There is no commitId field. Version histories are the audit source; use client.thing.history(...) or client.shape.history(...) when you need to inspect what changed over time.