@onlyworlds/sdk 4.6.0 → 4.7.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.30.1-dist.15** (canonical 00.30.01).
+**Current as of**: SDK **4.x** · schema-dist **v0.30.2-dist.16** (canonical 00.30.02).
 This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
 re-read against it, the check fails rather than letting this document rot quietly.
 
@@ -21,7 +21,7 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Known, deterministic operations (CRUD, sync, bulk) → **this SDK**. Typed calls, typed
   responses, far cheaper than tool-schema reasoning.
 - Live exploration of a user's world from a chat/agent context → the **MCP server** at
-  `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 11 tools).
+  `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 12 tools).
 
 **Wire facts that bite** (full details in README):
 - Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).

package/CHANGELOG.md

@@ -1,24 +1,57 @@
 # Changelog
 
-All notable changes to `@onlyworlds/sdk`. Maintained from 3.1.0 onward (Kael, Assembly);
+All notable changes to `@onlyworlds/sdk`. Maintained from 3.1.0 onward;
 earlier history lives in git log only.
 
 ## [Unreleased]
 
-## [4.6.0] — 2026-10-06 (staged, not published)
+## [4.7.1] — 2026-10-08
+
+### Changed
+- **README rewritten**: install, a first run against the public demo world (its output shown,
+  run as written), your own world with an agent seat for writes, then the reference. It no
+  longer calls a `world` field in a payload an error: the API ignores it.
+- Comments, the RFC and pin-file prose no longer name people or internal places.
+- **Schema repinned `v0.30.1-dist.15` → `v0.30.2-dist.16`** (canonical **00.30.02**).
+  `ONLYWORLDS_VERSION` is now `'00.30.02'`. Field descriptions move with the schema: Location's
+  `rivalries` and `partnerships`, Marker's `order`, and Pin's `element` pair. No field shape and
+  no `FIELD_SCHEMA` entry changed: canonical now requires only `name` on every type, which is
+  what `FIELD_SCHEMA` already said, so its hand-made exception for the old Pin and Marker
+  lists is gone. If the schema lists more than `name` again, codegen stops and asks for a
+  ruling instead of dropping the list. 31/31 file hashes recomputed from the tag.
+
+## [4.7.0] — 2026-10-08
+
+### Added
+- **`OwApiError.isResyncRequired`**: 409 `resync_required` from `/changes`. Guests can follow the
+  feed since keel D79; when a guest's view or a key's role changes, its stored cursor is refused. Drop
+  it, walk from zero, and replace the local copy rather than merging.
+
+### Documented
+- `uploadImage` accepts webp, png, jpeg and avif. 4.6.0's JSDoc and README also listed gif, which
+  the edge refuses (415 `unsupported_type`); checked against the Worker's type table.
+- `changes()`: the old rewind rule compared a stored cursor with `head`, which an opaque cursor
+  cannot do; replaced with the reset rule (`isResyncRequired`).
+- The doc comments of `OwClientConfig`, `create` and `uploadImage` are written for users: internal
+  ruling numbers and test-harness notes are gone, and each opens with what the option or method does.
+  The docs site's TypeScript reference is generated from these comments.
+
+## [4.6.0] — 2026-10-06
+
+Published from `e198298` (tag `v4.6.0`); the tarball was checked against a build of that commit.
 
 Includes 4.5.1's documentation fixes: 4.5.1 was staged and never published.
 
 ### Added
-- **`uploadImage(image, { key?, ticket? })`**: upload one image (webp, png, jpeg, avif, gif;
-  never SVG) and get its permanent public URL. Two requests: a ticket from keel
+- **`uploadImage(image, { key?, ticket? })`**: upload one image (webp, png, jpeg, avif;
+  never SVG; 4.6.0's docs also said gif, which the edge refuses with 415) and get its permanent public URL. Two requests: a ticket from keel
   (`POST /media/ticket`), then the bytes straight to the edge at the ticket's `upload_url`
   (keel never sees them). Only the ticket goes to the edge, never the API key or PIN. An image
   larger than the ticket's `max_bytes` throws 413 `too_large` before anything is sent; the edge's
   refusals (`ticket_used`, `ticket_expired`, `bad_key`, `exists`, `unsupported_type`, ...) arrive
   as `OwApiError` with their code. Set the returned `url` as an element's `image_url` yourself.
   Checked live on 2026-10-06: one upload through keel's ticket to the edge (201), and the same
-  ticket again refused with 401 `ticket_used` (Keel #59).
+  ticket again refused with 401 `ticket_used`.
 - **`createMediaTicket()`**: the first step alone, for callers that upload themselves (progress
   bars, say). Types `OwMediaTicket` and `OwUploadedImage`.
 
@@ -33,11 +66,11 @@ Docs only: no code path changes.
 ### Documented
 - **`isOwnerOnly`'s JSDoc in 4.5.0 was wrong about who sees `owner_only`.** It said owners and
   co-builders never see it. A member key, a co-builder's too, gets it on `PATCH /world`; only the
-  owner's key is exempt (keel spec section 9; confirmed from keel's `patch_world` by Skeld,
+  owner's key is exempt (keel spec section 9; confirmed from keel's `patch_world`,
   2026-10-04).
 - **`world_gone` is reserved.** `OwAuthErrorCode` and `isAuthError` still carry it, but keel never
   emits it: a deleted world's keys are deleted with it, so the key answers 401 `invalid_credentials`
-  (Skeld, 2026-10-04; keel spec section 2, T6b). Found by the wire gate reading the SDK's own
+  (2026-10-04; keel spec section 2). Found by the wire gate reading the SDK's own
   built file for the codes it keys on.
 
 ## [4.5.0] — 2026-10-04
@@ -48,7 +81,7 @@ three behaviours the server has always had that no client doc said. Additive; no
 ### Added
 - **`OwApiError.isOwnerOnly`**: 403 `owner_only`, a contributor attempting a world-level change
   (`patchWorld`, publishing a show page). Owners and co-builders never see it. keel's OpenAPI
-  document does not name the code yet (Skeld has that to close); the wire returns it.
+  document does not name the code yet (the schema side has that to close); the wire returns it.
 
 ### Documented
 - **An atomic `/bulk` rollback still returns 201 slots** for the items that would have
@@ -77,10 +110,10 @@ contributor meets on someone else's. Additive; nothing is removed or narrows.
 ### Fixed
 - **`FIELD_SCHEMA` no longer marks `marker.map/zone/x/y/order` and `pin.map/element_type/element_id/x/y`
   as `required: true`.** The wire requires `name` and nothing else (rulings.yaml `nullable-by-default`,
-  Captain 2026-07-28; keel's OpenAPI write schemas say `required: [name]`), but the schema files still
+  ruling 2026-07-28; keel's OpenAPI write schemas say `required: [name]`), but the schema files still
   list those fields and the generator copied the lists, so a form built from the table demanded
   coordinates the server never did. Found by comparing the SDK with keel's OpenAPI document (the
-  new `verify-sdk-wire` gate in Assembly). **If you read `required` from this table, marker and pin
+  new `verify-sdk-wire` gate). **If you read `required` from this table, marker and pin
   fields now read as optional**, which is what the server accepts. The generator notes the lists it
   ignores on every run and says when canonical stops carrying them.
 
@@ -128,7 +161,7 @@ Ids, honest filter docs, and the schema repin. Nothing is removed; no call needs
   order elements by id. For creation order use `created_at`; `change_seq` is last-write
   order. This is a **default, not a
   requirement**: a v4 or v7 id a caller supplies is still accepted as-is, and
-  every id already stored stays valid. Keel mints v7 server-side too (Captain's ruling,
+  every id already stored stays valid. Keel mints v7 server-side too (ruling,
   2026-09-28). Pinned by six tests: version and variant, the big-endian timestamp above
   bit 32, fractional and pre-1970 clocks floored consistently, creation order across 50
   consecutive milliseconds, 1,000 distinct ids inside one millisecond, and the no-`crypto`
@@ -138,7 +171,7 @@ Ids, honest filter docs, and the schema repin. Nothing is removed; no call needs
   edges, and keel's `uuid7()` agrees on timestamp, version and variant for a pinned clock.
 - **`elementColor()` on an unknown type now throws a `TypeError` that names the type.** It
   used to crash with `Cannot read properties of undefined (reading 'dark')`. Found while
-  building the Forge's colour gate: atlas's own copy falls back to the `world` family for an
+  building a colour gate: atlas's own copy falls back to the `world` family for an
   unknown type, so swapping it for this export is not a pure re-export for that input, and the
   docstring now says so. Whether the package should fall back is left to its consumers.
 - The generated field-schema comment no longer calls `maximum:` an open question or counts
@@ -285,7 +318,7 @@ pinned consumers.
 ### Added (post-alpha.0, same night)
 - **`ELEMENT_ICONS` GENERATED** from keel's `icon:` wrapper key (keel `56c124a`).
 - **`ELEMENT_SECTIONS` DERIVED** from the canonical schema's own document structure
-  (Skeld's ruling: sections are the standard tier's property groups; document order is
+  (ruling: sections are the standard tier's property groups; document order is
   display order). Divergence check vs the old hand table found and fixed three fossils:
   creature "Behaviour"→"Behavior", pin's triple-listed generic link → `element`,
   relation "Involves" listing a nonexistent `relations` field. Canonical is truth.
@@ -294,18 +327,18 @@ pinned consumers.
   covered by the codegen drift guard. AGENTS.md points agents at it first.
 - **`OwV2Client.request()` is public** (typed escape hatch; does not sanitize) and
   structurally satisfies `TokenTransport` — `new TokenResource(client)` just works.
-  Token ruling (Skeld): keel keeps `/tokens/*` long-term; ported, not deleted.
+  Token ruling: keel keeps `/tokens/*` long-term; ported, not deleted.
 - README rewritten v2-native (v1 sections, branded types, and the encrypted-key
   walkthrough removed; bulk partial-failure and idempotency-key hygiene promoted).
 
-### alpha.1 — consumer-pin fixes (Temper's atlas review, same night)
+### alpha.1 — consumer-pin fixes (atlas review, same night)
 - **`parseEnvelope` → `parseErrorEnvelope`** (it parses the platform *error* envelope;
   renamed before the 4.0 name freeze to avoid collision with the world-export envelope).
 - The never-whitelist LAW now lives as a comment on `READ_ONLY_FIELDS` itself.
 - Stale v1 example in the shipped d.ts fixed (TokenResource JSDoc).
 
 ### Release gates — ALL GREEN (2026-07-23 night)
-- **Gate 3 (wire-log v1-traffic query, Skeld)**: GREEN — no unknown v1-SDK consumer on
+- **Gate 3 (wire-log v1-traffic query)**: GREEN — no unknown v1-SDK consumer on
   the wire; observed v1 traffic is pinned deployed builds (council proxy, legacy plugin
   walks) that an npm major cannot touch. The v1 API dialect stays served regardless.
 - **`/api/v2/tokens/` live on prod + staging** (keel `e181689`; three-base byte
@@ -313,7 +346,7 @@ pinned consumers.
   "older server", not "no tokens". Requirement noted in the migration guide.
 - **`ONLYWORLDS_VERSION` now GENERATED** from canonical's `VERSION` file (carried
   into keel `schema/` by the refresh script, keel `492168c`) — the last hand-synced
-  constant is dead. Consumer soak: Temper pinned the alpha against atlas's full
+  constant is dead. Consumer soak: the atlas app pinned the alpha against its full
   static surface — strict-clean compile, correct runtime, package shape approved.
 - **No `npm deprecate` on 3.x** (landscape research; 3.x stays plainly supported).
 - 4.x wishlist: account client (list/mint/create — atlas first consumer), world-export
@@ -327,7 +360,7 @@ pinned consumers.
   `ELEMENT_FAMILIES` (type → family), `FAMILY_COLORS` (family → `{light, dark}` hex),
   `familyOf(type)`, `elementColor(type, mode)`, `FAMILY_ORDER`, type `ElementFamily`.
   Four semantic families (agents / world / abstract / temporal) ruled 2026-07-22 after
-  CVD-validated measurement (Orrery `product/schema/element-palette-measurements.md`).
+  CVD-validated measurement.
   Colour carries the FAMILY; `ELEMENT_ICONS` carries the TYPE. Keyed on the v2 slug
   union. First proven live in atlas and council, whose local copies become re-exports.
   **`ELEMENT_FAMILIES` is GENERATED** from the `family:` key in keel's schema YAML
@@ -355,7 +388,7 @@ pinned consumers.
 
 ## [3.0.0] — 2026-07-18
 
-- v2-native client (`OwV2Client`) absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+- v2-native client (`OwV2Client`) absorbed from an earlier v2 client (ow-v2-client v0.9.0),
   wire-corrected against live staging fixtures (S22). Generated element types from the
   canonical keel schema YAML (`src/v2/types.generated.ts`), validated against all 1,086
   live W11 elements. v1 surface unchanged and frozen.

package/README.md

@@ -3,74 +3,79 @@
 [![npm version](https://badge.fury.io/js/@onlyworlds%2Fsdk.svg)](https://www.npmjs.com/package/@onlyworlds/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-The canonical typed client for the [OnlyWorlds](https://onlyworlds.github.io) v2 API, plus the
-canonical constants (element types, icons, colour families, field schema) — generated from the
-canonical OnlyWorlds schema, obtained through the public
-[schema distribution](https://github.com/OnlyWorlds/schema-dist) at a pinned, hash-verified
-tag. The generated files carry that tag and commit in their header, so what these types were
-built from is checkable rather than asserted.
+OnlyWorlds is an open standard for worldbuilding data: 22 element types (characters, locations, events, laws and the rest) that any tool can read and write. This is a typed client for its API, with the schema's constants (element types, icons, colour families, field metadata) generated from the published [schema distribution](https://github.com/OnlyWorlds/schema-dist). It runs in Node 18+ and in the browser through a bundler (ESM only).
 
-**4.x is v2-native and ESM-only (Node 18+).** If you need the legacy v1 API dialect
-(`OnlyWorldsClient`) or CommonJS `require()`, stay on 3.x — it remains published and the v1 API
-remains served. See [docs/migrating-3-to-4.md](docs/migrating-3-to-4.md).
-
-## Installation
+## Install
 
 ```bash
 npm install @onlyworlds/sdk
 ```
 
-## Quick Start
+## First run
+
+Moppetopia is a public demo world. Its read-only key, `0000000001`, needs no account:
 
 ```typescript
 import { OwV2Client } from '@onlyworlds/sdk';
 
-const client = new OwV2Client({ apiKey: 'ow_r_your_key' }); // read-only key: that's all you need
-const page = await client.list('character');                 // { data, has_more, next_cursor }
+const client = new OwV2Client({ apiKey: '0000000001' });
+console.log((await client.getWorld()).name);
+const { data } = await client.list('character', { limit: 3 });
+for (const c of data) console.log(' ', c.name);
+```
+
+```
+Moppetopia
+  Admiral Splashworth
+  Admiral Fluffington
+  Captain Snoot
 ```
 
-Key kinds: `ow_w_` write / `ow_r_` read-only (no PIN — the "give this to your players" key) /
-`ow_a_` account Bearer / 10-digit legacy. Writes on a PIN-protected world also pass `apiPin`.
-Demo keys `0000000000`–`0000000009` read real sample worlds.
+## Your own world
 
-## The full round-trip
+Create a world at [onlyworlds.com](https://www.onlyworlds.com); its keys are on the world's page. A new key is shown once, so copy it then.
+
+- An `ow_r_` key reads, with no PIN. It is the key to give to players or a public site.
+- An `ow_w_` key reads and writes. Writes also send a PIN as `apiPin`.
+- Anyone who loads a web page can read the keys in its code. Ship only an `ow_r_` key to a browser, and keep write keys and seat secrets on a server.
+- For code that writes, give it its own [agent seat](https://onlyworlds.github.io/docs/development/agents), a key for one tool or script. The seat's key and its `ow_s_` secret (sent as `apiPin`) work in one world, and you can remove them without touching your account PIN.
 
 ```typescript
-const writer = new OwV2Client({ apiKey: 'ow_w_your_key', apiPin: '1234' });
+const writer = new OwV2Client({ apiKey: 'ow_w_…', apiPin: 'ow_s_…' });
+```
+
+## Reading and writing
 
-// v2 dialect rules, worth internalizing once:
-// - link fields use ONE bare name both directions (no _ids suffix — that's v1)
-// - NEVER send a "world" field (identity comes from the key; the client strips it anyway)
+```typescript
 const location = await writer.create('location', {
   name: 'Dragon Peak',
-  description: 'A treacherous mountain peak where dragons nest',
-}); // id minted client-side when omitted (retries stay idempotent)
-// name is the one required field, and required means the key is present:
-// '' and null are accepted and stored as '' (nameless Markers exist).
+  description: 'A mountain peak where dragons nest',
+}); // the id is minted client-side when omitted, so a retry creates nothing twice
 
 const dragon = await writer.create('creature', {
   name: 'Vorrath the Ember-Scaled',
-  location: location.id,            // single link: UUID (or null)
+  location: location.id, // a single link: a UUID or null
 });
 
 const fetched = await writer.get('creature', dragon.id);
-// fetched.location === location.id — reads the way it writes
+// fetched.location === location.id: a field reads the way it writes
 
-// PATCH is destructive on sent fields; arrays replace wholesale
+// PATCH replaces the fields it sends; an array is replaced whole
 await writer.patch('location', location.id, { supertype: 'Mountain' });
 
-// For relationships, use the atomic link merge — returns the full updated element
-const fireBreath = await writer.create('ability', { name: 'Ember Breath' });
-await writer.editLinks('creature', dragon.id, 'abilities', { add: [fireBreath.id], remove: [] });
+// For links, the atomic merge; it returns the updated element
+const breath = await writer.create('ability', { name: 'Ember Breath' });
+await writer.editLinks('creature', dragon.id, 'abilities', { add: [breath.id], remove: [] });
 
-// Walk every page of a type
+// Every page of a type
 for await (const character of writer.listAll('character')) { /* ... */ }
 ```
 
-## Bulk writes — always check `errors`
+A link field has one name in both directions (`location`, not `location_id`). Only `name` is required, and an empty name is stored as `''`. A `world` field in a payload is ignored: the key decides the world, and the client strips it anyway.
+
+## Bulk writes
 
-`/bulk` **succeeds partially by default** (HTTP 200 with per-slot statuses). The one mistake to
-never make: treating a 200 as "everything landed."
+`/bulk` answers 200 even when some items fail, so check `errors`:
 
 ```typescript
 const res = await writer.bulk(
@@ -78,87 +83,80 @@ const res = await writer.bulk(
     { type: 'character', element: { name: 'A' } },
     { type: 'event', element: { name: 'B' } },
   ],
-  { idempotencyKey: crypto.randomUUID() }, // mint FRESH per attempt — a failed batch is
-);                                          // cached under its key; never reuse across retries
+  { idempotencyKey: crypto.randomUUID() }, // a new key per attempt: a failed batch is cached under its key
+);
 if (res.errors) {
   for (const slot of res.items.filter((s) => s.status >= 400)) {
     console.warn(slot.error?.code, slot.error?.message, slot.error?.doc_url);
   }
 }
-// Pass { atomic: true } for all-or-nothing instead. res.wasReplay flags idempotent replays.
-// After a failed atomic batch NOTHING was written, but the slots that would have succeeded
-// still say 201 (keel's counterfactual 201s): do not record those ids as created.
 ```
 
+Pass `{ atomic: true }` for all or nothing. After a failed atomic batch nothing was written, but the slots that would have succeeded still read 201: don't record those ids as created. `res.wasReplay` marks an idempotent replay.
+
 ## Images
 
 ```typescript
-const image = await writer.uploadImage(file);             // a Blob, File, ArrayBuffer or Uint8Array
+const image = await writer.uploadImage(file); // a Blob, File, ArrayBuffer or Uint8Array
 await writer.patch('character', id, { image_url: image.url });
 ```
 
-Two requests: a single-use ticket from keel, then the bytes straight to the edge (keel never
-sees them, and the edge never sees your key). webp, png, jpeg, avif or gif, read from the
-bytes; never SVG. Each ticket counts toward the world's daily limit and the account's image
-storage. To upload yourself (for a progress bar), take `createMediaTicket()` and POST the bytes to
-its `upload_url` with `Authorization: Bearer <ticket>`.
+The SDK asks the API for a single-use ticket, then sends the bytes straight to the upload host, which never sees your key. webp, png, jpeg or avif (no SVG or gif), up to 15 MB. Each upload counts toward the world's daily limit and the account's storage. To upload yourself (for a progress bar), call `createMediaTicket()` and POST the bytes to its `upload_url` with `Authorization: Bearer <ticket>`.
 
 ## Sync
 
 ```typescript
-let cursor; // opaque, never expires; persist it
+let cursor; // opaque and never expires: keep it
 for await (const change of client.changesAll(cursor)) {
-  // ops arrive in (change_seq, id) order — apply in order → convergence
+  // changes arrive in order; apply them in order and you converge
 }
-// GOTCHA: world-meta edits (name, calendar, public_read) do NOT enter /changes.
-// Poll client.getWorld() and compare updated_at separately.
 ```
 
+Edits to the world itself (its name, calendar, `public_read`) don't appear in the change feed. Read `client.getWorld()` and compare `updated_at`.
+
 ## Errors
 
-Every non-2xx throws `OwApiError` carrying the platform envelope: `.status`, `.type`, `.code`,
-`.param` (the exact field that failed), and `.docUrl` — surface `docUrl` in your UX. Transport
-failures throw `OwNetworkError`. `err.isValidationError` is the common branch.
+Every non-2xx response throws `OwApiError` with the API's envelope: `.status`, `.type`, `.code`, `.param` (the field that failed) and `.docUrl`, which is worth showing to your users. A transport failure throws `OwNetworkError`. `err.isValidationError` covers the common case.
 
-## Canonical constants (all generated or test-gated from schema)
+## Schema constants
 
 ```typescript
 import {
-  ELEMENT_TYPES,        // the 22 slugs (and the ElementType union)
-  ELEMENT_ICONS,        // Material Symbols icon per type
-  ELEMENT_LABELS,       // plural display labels
-  ELEMENT_SECTIONS,     // canonical field grouping + display order
-  FIELD_SCHEMA,         // per-field type/target metadata
-  elementColor,         // canonical colour: family carries COLOUR, icon carries TYPE
+  ELEMENT_TYPES,    // the 22 type slugs (and the ElementType union)
+  ELEMENT_ICONS,    // a Material Symbols icon per type
+  ELEMENT_LABELS,   // plural display labels
+  ELEMENT_SECTIONS, // field grouping and display order
+  FIELD_SCHEMA,     // per-field type and link target
+  elementColor,     // colour by family; the icon carries the type
 } from '@onlyworlds/sdk';
 
-elementColor('character', 'dark'); // '#3987e5' — four CVD-validated families
-// Always pair colour with icon + label; colour alone is not accessible.
+elementColor('character', 'dark'); // '#3987e5'
 ```
 
-The full schema with per-field meaning lives in [SCHEMA.md](SCHEMA.md) (generated, ships in this
-package). AI agents: read [AGENTS.md](AGENTS.md) first.
+The four colour families (agents, world, abstract, temporal) are checked for colour-blind separation. Show colour with the icon and label, never alone. [SCHEMA.md](SCHEMA.md) (generated, in the package) describes every field; AI agents should read [AGENTS.md](AGENTS.md) first.
+
+## Tokens
 
-## Token rating system
+The account's token allowance and ratings, which some OnlyWorlds tools use.
 
 ```typescript
 import { TokenResource } from '@onlyworlds/sdk';
-const tokens = new TokenResource(writer); // OwV2Client.request() satisfies TokenTransport
+const tokens = new TokenResource(writer);
 const status = await tokens.getStatus();
 ```
 
-## AI access — when to use which
+## SDK or MCP
 
-For **known, deterministic operations** (CRUD, sync, bulk) use this SDK — typed calls, no
-tool-schema overhead. For **live exploration of a user's world from a chat/agent context**, use
-the MCP server at `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 11 tools;
-unaffected by SDK versioning).
+Use this SDK for known operations in your own code (CRUD, sync, bulk). To let an AI assistant that speaks MCP (the Model Context Protocol) explore a world in a chat, connect it to `https://www.onlyworlds.com/mcp` with the same key and PIN as `API-Key` and `API-Pin` headers.
 
-## License
+## Version 3 and the old API
 
-MIT
+4.x speaks the current (v2) API only. The v1 client (`OnlyWorldsClient`) and CommonJS `require()` stay on 3.x, which remains published and supported: see [the migration guide](docs/migrating-3-to-4.md).
 
 ## Links
 
-- [OnlyWorlds](https://www.onlyworlds.com) · [Docs](https://onlyworlds.github.io) · [API reference](https://www.onlyworlds.com/api/docs)
-- [Issues](https://github.com/OnlyWorlds/sdk/issues) · [CHANGELOG](CHANGELOG.md) · [Migration 3→4](docs/migrating-3-to-4.md)
+[Docs](https://onlyworlds.github.io/docs/development/typescript) · [Games](https://onlyworlds.github.io/docs/development/games) · [API reference](https://www.onlyworlds.com/api/docs) · [Issues](https://github.com/OnlyWorlds/sdk/issues) · [Changelog](CHANGELOG.md)
+
+## License
+
+MIT

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.30.1-dist.15** — canonical schema **00.30.01**, published 2026-09-18.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.30.2-dist.16** — canonical schema **00.30.02**, published 2026-10-08.
 
 GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
 Written for both humans and AI agents reading this package locally.
@@ -326,8 +326,8 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `governing_title` (single link → title) — Governing figure assigned by the location's primary power
 - `secondary_powers` (multi link → institution) — Institutions with significant political control
 - `zone` (single link → zone) — Zone of interest that is associated with the location
-- `rival` (single link → location) — Locations with active, traditional, or historical rivalries
-- `partner` (single link → location) — Locations with active, cooperative, or historical ties
+- `rival` (single link → location) — Location with an active, traditional, or historical rivalry with this one
+- `partner` (single link → location) — Location with active, cooperative, or historical ties to this one
 
 ### World
 
@@ -388,7 +388,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `x` (integer) — x coordinate, from bottom left of the map
 - `y` (integer) — y coordinate, from bottom left of the map
 - `z` (integer) — z coordinate, in case of depth
-- `order` (integer) — Sequence position when markers define a polygon or line (0 = first point)
+- `order` (integer) — Sequence position when markers define a polygon or line (0 = first point); without it, markers keep the order they were made in
 
 
 ## narrative  ·  family: temporal  ·  icon: menu_book
@@ -482,7 +482,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 ### Details
 
 - `map` (single link → map) — Map that the pin is placed on
-- `element` (generic link (any element type)) — Link to any Element (managed by ContentType + UUID)
+- `element` (generic link (any element type)) — The element this pin places on the map, of any type
 - `x` (integer) — x coordinate, from bottom left of the map
 - `y` (integer) — y coordinate, from bottom left of the map
 - `z` (integer) — z coordinate, in case of depth (optional)
@@ -517,7 +517,6 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `families` (multi link → family) — Families relevant to the relation
 - `titles` (multi link → title) — Titles relevant to the relation
 - `constructs` (multi link → construct) — Concepts, contracts, or principles relevant to the relation
-- `events` (multi link → event) — Events where the relation is involved or relevant
 - `narratives` (multi link → narrative) — Narratives relevant to the relation
 
 

package/dist/index.d.ts

@@ -33,7 +33,7 @@ type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creat
 declare const ELEMENT_TYPES: ElementType[];
 /** Canonical OnlyWorlds schema version. Source: the `canonical:` value of the pinned
  *  distribution's VERSION file (see the provenance block at the top of this file). */
-declare const ONLYWORLDS_VERSION: "00.30.01";
+declare const ONLYWORLDS_VERSION: "00.30.02";
 /** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
 type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
 /** Per-type semantic family. Source: the distribution's `presentation.json` sidecar
@@ -1844,7 +1844,7 @@ declare const FIELD_SCHEMA: {
 };
 
 /**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * keel v2 engine absorbed from an earlier v2 client (ow-v2-client v0.9.0),
  * wire-corrected against live staging fixtures 2026-07-18.
  *
  * OnlyWorlds v2 (keel) wire types -- the NON-generated, hand-owned wire shapes
@@ -2000,32 +2000,31 @@ interface ListParams {
     filter?: Record<string, string | number | boolean>;
 }
 interface OwClientConfig {
-    /** ow_w_ / ow_r_ / ow_a_ prefixed key, or grandfathered 10-digit legacy key. */
+    /** The key: an ow_w_ (write) or ow_r_ (read) world key, an ow_a_ account token (sent as a Bearer token, for the account routes), or a 10-digit legacy key. */
     apiKey: string;
     /**
-     * Optional. Required for writes when the world has a PIN, and for legacy-key
-     * reads of private worlds. Prefixed keys read PIN-less. String, not number --
-     * '0123' !== 123.
+     * The PIN, needed for writes when the world has one, and for legacy-key reads of private worlds.
+     * Prefixed keys read without a PIN. A string, not a number: '0123' !== 123.
      */
     apiPin?: string;
-    /** Default: https://www.onlyworlds.com/api/v2 */
+    /** The API's base URL, default https://www.onlyworlds.com/api/v2. */
     baseUrl?: string;
     /**
-     * Page size for element lists. Default 100 (server default; max 1000).
-     * Deliberately visible in config: page size is a citizenship property.
+     * Page size for element lists, default 100 (the server's default; at most 1000).
+     * It is in the config on purpose: page size decides the load a client puts on the server.
      */
     pageSize?: number;
     /**
-     * Page size for /changes pulls. Default 100. Live precedents: Obsidian 100,
-     * Atlas 250, MCP 25. /changes is the platform's heaviest route -- be polite.
+     * Page size for /changes pulls, default 100. Tools in use pick 25 to 250; the change feed
+     * is the platform's heaviest route, so keep it modest.
      */
     changesPageSize?: number;
-    /** Injectable for tests / fake-keel harnesses. Defaults to globalThis.fetch. */
+    /** A fetch implementation to use instead of globalThis.fetch (for tests and other runtimes). */
     fetch?: typeof globalThis.fetch;
 }
 
 /**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * keel v2 engine absorbed from an earlier v2 client (ow-v2-client v0.9.0),
  * wire-corrected against live staging fixtures 2026-07-18.
  *
  * keel error envelope handling. The error contract is part of the contract:
@@ -2079,6 +2078,13 @@ declare class OwApiError extends Error {
      * per-item slot `{status: 409, error: {code: 'id_conflict'}}` — check the slot.
      */
     get isIdConflict(): boolean;
+    /**
+     * `/changes` refused the cursor (409 `resync_required`): a guest's view of the world
+     * changed, or the key's role did (a guest's cursor has another shape). Drop the stored
+     * cursor, walk again from the start, and REPLACE the local copy rather than merging into
+     * it: a guest never receives delete ops, so only the replace removes what it no longer sees.
+     */
+    get isResyncRequired(): boolean;
     /** keel's admission control turned the request away (503 `server_busy`); see retryAfter. */
     get isBusy(): boolean;
     /**
@@ -2109,7 +2115,7 @@ declare function parseErrorEnvelope(status: number, body: unknown, retryAfter?:
 declare function errorFromResponse(res: Response): Promise<OwApiError>;
 
 /**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * keel v2 engine absorbed from an earlier v2 client (ow-v2-client v0.9.0),
  * wire-corrected against live staging fixtures 2026-07-18.
  *
  * OnlyWorlds key-kind detection. Prefixes make leaked keys grep-scannable
@@ -2137,7 +2143,7 @@ declare function kindCanWrite(kind: OwKeyKind): boolean;
 declare function pinExpectation(kind: OwKeyKind): 'never' | 'optional' | 'required-for-private-reads';
 
 /**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * keel v2 engine absorbed from an earlier v2 client (ow-v2-client v0.9.0),
  * wire-corrected against live staging fixtures 2026-07-18.
  *
  * OwV2Client -- thin typed fetch client for the keel v2 API.
@@ -2175,11 +2181,11 @@ declare class OwV2Client {
     /** GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields. */
     get(type: ElementType | string, id: string, opts?: Pick<ListParams, 'expand' | 'fields'>): Promise<OwElement>;
     /**
-     * POST /{type}/ -- create. Mints an RFC 9562 UUIDv7 for element.id when the
-     * caller omits one (design ruling D29d) so a retry carrying the same
-     * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
+     * POST /{type}/ -- create one element, minting a UUIDv7 id on the client when you leave id out.
+     * The client-side id makes a retry carrying the same Idempotency-Key safe: it rewrites
+     * the same element instead of creating a second one. You may still supply your own id.
      * `name` is the one required field, and required means the key is present: `''` and
-     * `null` are accepted and stored as `''` (nameless Markers exist; keel ruling 2026-09-28).
+     * `null` are accepted and stored as `''` (nameless Markers exist).
      */
     create(type: ElementType | string, element: OwElement | Record<string, unknown>, opts?: {
         idempotencyKey?: string;
@@ -2223,10 +2229,12 @@ declare class OwV2Client {
     }): Promise<OwBulkResponse>;
     /**
      * GET /changes -- one page of the world's ordered change feed.
-     * Cursor is OPAQUE and never expires: persist verbatim, never parse.
+     * Cursor is OPAQUE: persist verbatim, never parse or build one (a guest's has
+     * another shape than everyone else's).
      * Zero/absent cursor = full export (byte-aligned with the Folder Format).
-     * Rewind rule: if your persisted position is ahead of page.head, the server
-     * was restored -- re-baseline from cursor zero; do not assume caught-up.
+     * Reset rule: a 409 `resync_required` (err.isResyncRequired) means the key's
+     * view changed (a guest's, or its role): drop the cursor, walk from zero, and
+     * replace the local copy rather than merging into it.
      * Citizenship: heaviest route on the platform; default page size is polite.
      */
     changes(opts?: {
@@ -2254,12 +2262,12 @@ declare class OwV2Client {
      */
     createMediaTicket(): Promise<OwMediaTicket>;
     /**
-     * Upload one image and get its permanent public URL: a ticket from keel, then the
-     * bytes straight to the edge (keel never sees them). Pass a ticket from
+     * Upload one image and get its permanent public URL: a ticket from the API, then the
+     * bytes straight to the media edge (the API never sees them). Pass a ticket from
      * createMediaTicket() to use it instead of fetching one. Returns the edge's 201;
      * set `url` as an element's `image_url` yourself (`patch(type, id, { image_url })`).
      *
-     * webp, png, jpeg, avif or gif, read from the bytes (never SVG). `key` names the
+     * webp, png, jpeg or avif, read from the bytes (never SVG or gif). `key` names the
      * object (it must start with the ticket's `prefix`; without it the edge picks one).
      * An image larger than the ticket's `max_bytes` throws 413 `too_large` before any
      * byte is sent. The edge's refusals arrive as OwApiError with its code: 401
@@ -2292,9 +2300,8 @@ declare class OwV2Client {
 /**
  * Canonical element colour palette — four semantic families.
  *
- * Ruled by Captain 2026-07-22 after Skeld's measurement pass (Orrery
- * `product/schema/element-palette-measurements.md`): 22 mutually-separable
- * hues is structurally impossible; four families is the ceiling that passes
+ * Ruled 2026-07-22 after a measurement pass: 22 mutually-separable hues
+ * is structurally impossible; four families is the ceiling that passes
  * all-pairs CVD separation in both modes. **Colour carries the FAMILY; the
  * icon (`ELEMENT_ICONS`) carries the TYPE.** Dark-mode pairs land in the 6–8
  * CVD floor band, so secondary encoding (icon + label) is REQUIRED alongside
@@ -2485,7 +2492,7 @@ declare enum GameTier {
 /**
  * Minimal transport the token resource needs — structurally satisfied by
  * `OwV2Client` (its `request()` is public since 4.0): `new TokenResource(client)`.
- * Wire ruling (Skeld 2026-07-23): keel keeps the /tokens/* economy long-term
+ * Wire ruling (2026-07-23): keel keeps the /tokens/* economy long-term
  * (Tangle ratings write it, Council voting reads it) — port, don't delete.
  */
 interface TokenTransport {

package/dist/index.js

@@ -35,6 +35,15 @@ var OwApiError = class extends Error {
   get isIdConflict() {
     return this.status === 409 && this.code === "id_conflict";
   }
+  /**
+   * `/changes` refused the cursor (409 `resync_required`): a guest's view of the world
+   * changed, or the key's role did (a guest's cursor has another shape). Drop the stored
+   * cursor, walk again from the start, and REPLACE the local copy rather than merging into
+   * it: a guest never receives delete ops, so only the replace removes what it no longer sees.
+   */
+  get isResyncRequired() {
+    return this.status === 409 && this.code === "resync_required";
+  }
   /** keel's admission control turned the request away (503 `server_busy`); see retryAfter. */
   get isBusy() {
     return this.status === 503 && this.code === "server_busy";
@@ -188,11 +197,11 @@ var OwV2Client = class {
     return this.request("GET", `/${type}/${id}/`, { query });
   }
   /**
-   * POST /{type}/ -- create. Mints an RFC 9562 UUIDv7 for element.id when the
-   * caller omits one (design ruling D29d) so a retry carrying the same
-   * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
+   * POST /{type}/ -- create one element, minting a UUIDv7 id on the client when you leave id out.
+   * The client-side id makes a retry carrying the same Idempotency-Key safe: it rewrites
+   * the same element instead of creating a second one. You may still supply your own id.
    * `name` is the one required field, and required means the key is present: `''` and
-   * `null` are accepted and stored as `''` (nameless Markers exist; keel ruling 2026-09-28).
+   * `null` are accepted and stored as `''` (nameless Markers exist).
    */
   async create(type, element, opts = {}) {
     const body = sanitizePayload(element);
@@ -260,10 +269,12 @@ var OwV2Client = class {
   // -- Changes feed --------------------------------------------------------
   /**
    * GET /changes -- one page of the world's ordered change feed.
-   * Cursor is OPAQUE and never expires: persist verbatim, never parse.
+   * Cursor is OPAQUE: persist verbatim, never parse or build one (a guest's has
+   * another shape than everyone else's).
    * Zero/absent cursor = full export (byte-aligned with the Folder Format).
-   * Rewind rule: if your persisted position is ahead of page.head, the server
-   * was restored -- re-baseline from cursor zero; do not assume caught-up.
+   * Reset rule: a 409 `resync_required` (err.isResyncRequired) means the key's
+   * view changed (a guest's, or its role): drop the cursor, walk from zero, and
+   * replace the local copy rather than merging into it.
    * Citizenship: heaviest route on the platform; default page size is polite.
    */
   async changes(opts = {}) {
@@ -300,12 +311,12 @@ var OwV2Client = class {
     return this.request("POST", "/media/ticket");
   }
   /**
-   * Upload one image and get its permanent public URL: a ticket from keel, then the
-   * bytes straight to the edge (keel never sees them). Pass a ticket from
+   * Upload one image and get its permanent public URL: a ticket from the API, then the
+   * bytes straight to the media edge (the API never sees them). Pass a ticket from
    * createMediaTicket() to use it instead of fetching one. Returns the edge's 201;
    * set `url` as an element's `image_url` yourself (`patch(type, id, { image_url })`).
    *
-   * webp, png, jpeg, avif or gif, read from the bytes (never SVG). `key` names the
+   * webp, png, jpeg or avif, read from the bytes (never SVG or gif). `key` names the
    * object (it must start with the ticket's `prefix`; without it the edge picks one).
    * An image larger than the ticket's `max_bytes` throws 413 `too_large` before any
    * byte is sent. The edge's refusals arrive as OwApiError with its code: 401
@@ -422,7 +433,7 @@ function buildQuery(params) {
 
 // src/v2/types.generated.ts
 var ELEMENT_TYPES = ["ability", "character", "collective", "construct", "creature", "event", "family", "institution", "language", "law", "location", "map", "marker", "narrative", "object", "phenomenon", "pin", "relation", "species", "title", "trait", "zone"];
-var ONLYWORLDS_VERSION = "00.30.01";
+var ONLYWORLDS_VERSION = "00.30.02";
 var ELEMENT_FAMILIES = {
   ability: "abstract",
   character: "agents",
@@ -553,7 +564,7 @@ var ELEMENT_SECTIONS = {
   ],
   relation: [
     { name: "Nature", order: 1, fields: ["background", "start_date", "end_date", "intensity", "actor", "events"] },
-    { name: "Involves", order: 2, fields: ["characters", "objects", "locations", "species", "creatures", "institutions", "traits", "collectives", "zones", "abilities", "phenomena", "languages", "families", "titles", "constructs", "events", "narratives"] }
+    { name: "Involves", order: 2, fields: ["characters", "objects", "locations", "species", "creatures", "institutions", "traits", "collectives", "zones", "abilities", "phenomena", "languages", "families", "titles", "constructs", "narratives"] }
   ],
   species: [
     { name: "Biology", order: 1, fields: ["appearance", "life_span", "weight", "nourishment", "reproduction", "adaptations"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.6.0",
+  "version": "4.7.1",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {