@onlyworlds/sdk 4.1.0 → 4.2.0

package/AGENTS.md

@@ -1,34 +1,48 @@
-# For AI agents using @onlyworlds/sdk
-
-**Start with [SCHEMA.md](SCHEMA.md)** (in this package): the full generated schema reference —
-every type, every field with its meaning, link directions, families, icons, display sections.
-It is generated from the same canonical YAML as the types, so it cannot drift.
-
-**What this package is**: the canonical typed TypeScript client for the OnlyWorlds v2 API,
-plus the canonical constants (element types, icons, colour families, field schema).
-OnlyWorlds is an open standard for portable world data — 22 element types, UUID-linked.
-
-**Use the v2 surface.** `OwV2Client` + the `V2ElementType` slug union + the generated
-interfaces in `types.generated.ts` (emitted from the canonical schema YAML, validated
-against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum) is frozen
-legacy — do not build new work on it.
-
-**SDK vs MCP server — pick correctly**:
-- 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).
-
-**Wire facts that bite** (full details in README):
-- Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).
-- v2 link fields use ONE name both directions (no `_ids` suffix — that is v1 dialect only).
-- PATCH is destructive on sent fields; use `editLinks` (atomic add/remove) for relationships.
-- World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
-- Extension fields: `x_<toolname>_*` is the sanctioned namespace for tool-specific state;
-  unknown unprefixed fields 422.
-- Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon
-  (`ELEMENT_ICONS`) carries the TYPE. Icon + label are required alongside colour, not optional.
-
-**Auth**: prefixed keys — `ow_w_` (read+write), `ow_r_` (read-only, no PIN — the share
-primitive), `ow_a_` (account Bearer). Demo keys `0000000000`–`0000000009` are read-only
-test credentials against real data.
+# For AI agents using @onlyworlds/sdk
+
+**Current as of**: SDK **4.x** · schema-dist **v0.30.1-dist.15** (canonical 00.30.01).
+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.
+
+**Start with [SCHEMA.md](SCHEMA.md)** (in this package): the full generated schema reference —
+every type, every field with its meaning, link directions, families, icons, display sections.
+It is generated from the same canonical YAML as the types, so it cannot drift.
+
+**What this package is**: the canonical typed TypeScript client for the OnlyWorlds v2 API,
+plus the canonical constants (element types, icons, colour families, field schema).
+OnlyWorlds is an open standard for portable world data — 22 element types, UUID-linked.
+
+**Use the v2 surface.** `OwV2Client` + the `V2ElementType` slug union + the generated
+interfaces in `types.generated.ts` (emitted from the canonical schema YAML, validated
+against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum) is not in
+4.x — it was removed at 4.0.0 and lives only in 3.x. Do not build new work on it.
+
+**SDK vs MCP server — pick correctly**:
+- 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).
+
+**Wire facts that bite** (full details in README):
+- Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).
+- v2 link fields use ONE name both directions (no `_ids` suffix — that is v1 dialect only).
+- PATCH is destructive on sent fields; use `editLinks` (atomic add/remove) for relationships.
+- World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
+- Extension fields: `x_<toolname>_*` is the sanctioned namespace for tool-specific state;
+  unknown unprefixed fields 422. Extensions are capped at **64 KB per element** (422,
+  `param: extensions`).
+- List filters: only `name__icontains`, `supertype` and `subtype` are built. Any other
+  filter key — and `?ordering=` — returns 422 naming it. Filter or sort client-side.
+- Ids: the client mints **UUIDv7** on an id-less `create` (since 4.2.0; keel mints v7 too).
+  A v4 or v7 id you supply is accepted. **Never sort elements by id**: worlds mix v7, v4
+  and legacy `06x…` ids (nibble 7 too, but seconds-first). For creation order use
+  `created_at`; `change_seq` is last-write order, not creation.
+  A PUT or bulk item whose id belongs to **another world** returns 409 `id_conflict`.
+- A string holding an unpaired surrogate (text cut mid-emoji) is a 422 naming the field.
+  Slice strings by code point, not by UTF-16 unit.
+- Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon
+  (`ELEMENT_ICONS`) carries the TYPE. Icon + label are required alongside colour, not optional.
+
+**Auth**: prefixed keys — `ow_w_` (read+write), `ow_r_` (read-only, no PIN — the share
+primitive), `ow_a_` (account Bearer). Demo keys `0000000000`–`0000000009` are read-only
+test credentials against real data.

package/CHANGELOG.md

@@ -3,6 +3,63 @@
 All notable changes to `@onlyworlds/sdk`. Maintained from 3.1.0 onward (Kael, Assembly);
 earlier history lives in git log only.
 
+## [Unreleased]
+
+## [4.2.0] — staged 2026-09-28, not yet published
+
+Ids, honest filter docs, and the schema repin. Nothing is removed; no call needs to change.
+
+### Changed
+- **`create()` now mints an RFC 9562 UUIDv7** when the element has no id (was v4). The first
+  48 bits are the creation millisecond, so ids this client mints a millisecond or more apart
+  sort by creation (while the clock does not step backwards), which gives databases better
+  index locality. **This holds within one client only**: worlds also hold v4 ids and legacy
+  v1-server ids (`06x…`, which also carry version nibble 7 but put seconds first), so never
+  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,
+  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`
+  fallback (asserting `Math.random` is actually used). Five injected defects (v4 nibble,
+  32-bit truncation, a dropped random fill, a dropped variant mask, an unfloored clock)
+  each fail the suite on every run, on Node 20 and 22. An independent reviewer's decoder agreed on 20,000 random timestamps and the 48-bit
+  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
+  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
+  its occurrences (the count was 41; since 00.30.01 it is 15). The question was ruled on
+  2026-07-29.
+- **`ListParams.filter` JSDoc names what the server actually accepts**: `name__icontains`,
+  `supertype`, `subtype`. It used to list `__in`, `__gte`, `__lte` and `__isnull`, copied
+  from keel's spec, which described them but never built them. Probed live 2026-09-28: the
+  three accepted keys answer 200; every other one, and `?ordering=`, answers 422.
+- **Schema repinned `v0.30.1-dist.13` → `v0.30.1-dist.15`** (canonical unchanged, 00.30.01).
+  Two generated values move: `ELEMENT_ICONS.institution` `business` → `account_balance`,
+  `ELEMENT_ICONS.marker` `place` → `location_on` (both Material Symbols names). dist.15
+  also adds `minimum: 0` to `ability.potency`; the walk does not surface bounds, so nothing
+  generated changes for it. 31/31 file hashes recomputed from a fresh download.
+- **`AGENTS.md` re-read against the new pin** (its gate fired on the repin, as designed).
+  It still called the v1 client "frozen legacy" in this package; v1 was removed at 4.0.0.
+  It now also names the wire behaviours keel deployed on 2026-09-28 (keel D70): the 64 KB
+  extension cap, the three built filters and the `?ordering=` 422, 409 `id_conflict` for a
+  PUT or bulk id that belongs to another world, and the 422 for unpaired surrogates. None of
+  them needs client code.
+
+### Also in this release (staged earlier)
+- **`SCHEMA.md` now opens with its own provenance** (dist tag, canonical version, publish
+  date — rendered from `schema-pin.json`, never the wall clock). It ships in the tarball
+  and is read cold by agents outside this repo, where the pin file is not present; a
+  generated reference that cannot name its source was the one remaining self-dating gap.
+- **`AGENTS.md` carries a "Current as of" line, asserted by `codegen:check`** — the tag it
+  names must match the pin or CI fails. A hand-maintained agent doc with an ungated date
+  is how this repo's previous agent doc went a major version stale. Gate watched firing
+  (tampered tag → exit 1, restored → 0).
+
 ## [4.1.0] — 2026-07-29
 
 Public-surface hygiene. Nothing breaks; one member is now marked for removal, and one

package/SCHEMA.md

@@ -1,5 +1,7 @@
 # OnlyWorlds Schema Reference
 
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.30.1-dist.15** — canonical schema **00.30.01**, published 2026-09-18.
+
 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.
 
@@ -244,7 +246,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `creatures` (multi link → creature) — Creatures owned, bonded to, or representing the family
 
 
-## institution  ·  family: agents  ·  icon: business
+## institution  ·  family: agents  ·  icon: account_balance
 
 
 ### Foundation
@@ -376,7 +378,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `location` (single link → location) — Location element that this map represents
 
 
-## marker  ·  family: world  ·  icon: place
+## marker  ·  family: world  ·  icon: location_on
 
 
 ### Details

package/dist/index.d.ts

@@ -1958,9 +1958,10 @@ interface ListParams {
     /** Sparse include-set of field names. */
     fields?: string[];
     /**
-     * Blessed Django-style filters: __icontains, __in, __gte, __lte, __isnull,
-     * supertype/subtype equality. Unknown params 422 loudly server-side -- the
-     * client passes them through and lets the platform name the typo.
+     * Accepted: `name__icontains`, `supertype`, `subtype`. Any other key 422s
+     * server-side, which names the typo -- the client passes keys through
+     * unchecked and lets the platform say so. (`__in`, `__gte`, `__lte` and
+     * `__isnull` are designed in keel's spec but not built; `ordering` 422s too.)
      */
     filter?: Record<string, string | number | boolean>;
 }
@@ -2099,7 +2100,7 @@ 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-4122 UUID for element.id when the
+     * 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.
      */
@@ -2223,6 +2224,13 @@ declare function familyOf(type: ElementType): ElementFamily;
  * Name matches the live atlas/council implementations so their SDK swap is a
  * re-export, not a rename. Defaults to `dark` (both current consumers are
  * dark-surface).
+ *
+ * An unknown type throws a TypeError naming it (since 4.2.0; before, it crashed
+ * with "Cannot read properties of undefined"). This is the one place a swap from
+ * atlas's own copy is NOT a pure re-export: atlas falls back to the `world`
+ * family for an unknown type. A caller that wants a fallback catches, or checks
+ * `type in ELEMENT_FAMILIES` first; which fallback, if any, is a design call
+ * this package does not make for its consumers.
  */
 declare function elementColor(type: ElementType, mode?: 'light' | 'dark'): string;
 /** All four families, in ruling order (the order IS the CVD-safety mechanism of the source palette). */

package/dist/index.js

@@ -143,7 +143,7 @@ var OwV2Client = class {
     return this.request("GET", `/${type}/${id}/`, { query });
   }
   /**
-   * POST /{type}/ -- create. Mints an RFC-4122 UUID for element.id when the
+   * 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.
    */
@@ -289,16 +289,22 @@ function readReplayHeader(headers) {
   const v = headers.get("Idempotent-Replay");
   return v != null && v.toLowerCase() === "true";
 }
-function mintUuid() {
+function mintUuid(now = Date.now()) {
   const c = globalThis.crypto;
-  if (c && typeof c.randomUUID === "function") return c.randomUUID();
   const bytes = new Uint8Array(16);
   if (c && typeof c.getRandomValues === "function") {
     c.getRandomValues(bytes);
   } else {
     for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
   }
-  bytes[6] = bytes[6] & 15 | 64;
+  const ms = Math.floor(now);
+  bytes[0] = Math.floor(ms / 2 ** 40) & 255;
+  bytes[1] = Math.floor(ms / 2 ** 32) & 255;
+  bytes[2] = ms >>> 24 & 255;
+  bytes[3] = ms >>> 16 & 255;
+  bytes[4] = ms >>> 8 & 255;
+  bytes[5] = ms & 255;
+  bytes[6] = bytes[6] & 15 | 112;
   bytes[8] = bytes[8] & 63 | 128;
   const hex = [];
   for (let i = 0; i < 256; i++) hex.push((i + 256).toString(16).slice(1));
@@ -347,12 +353,12 @@ var ELEMENT_ICONS = {
   creature: "bug_report",
   event: "saved_search",
   family: "supervisor_account",
-  institution: "business",
+  institution: "account_balance",
   language: "edit_road",
   law: "gpp_bad",
   location: "castle",
   map: "map",
-  marker: "place",
+  marker: "location_on",
   narrative: "menu_book",
   object: "webhook",
   phenomenon: "thunderstorm",
@@ -1072,7 +1078,9 @@ function familyOf(type) {
   return ELEMENT_FAMILIES[type];
 }
 function elementColor(type, mode = "dark") {
-  return FAMILY_COLORS[ELEMENT_FAMILIES[type]][mode];
+  const family = ELEMENT_FAMILIES[type];
+  if (family === void 0) throw new TypeError(`elementColor: unknown element type "${String(type)}"`);
+  return FAMILY_COLORS[family][mode];
 }
 var FAMILY_ORDER = ["agents", "world", "abstract", "temporal"];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {
@@ -28,7 +28,8 @@
     "codegen:check": "python codegen/generate_types.py --check",
     "schema:verify": "python codegen/verify_dist.py",
     "schema:check": "npm run schema:verify && npm run codegen:check",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "release:verify": "node codegen/verify_release.mjs"
   },
   "keywords": [
     "onlyworlds",