@onlyworlds/sdk 4.0.1 → 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,118 @@
 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
+piece of long-standing speculation is retired by measurement.
+
+⚑ **4.0.2 was tagged in git and superseded before it reached npm.** Everything in it ships
+here — the tag stays as a record rather than being moved or deleted.
+
+### Deprecated
+- **`FieldType.integer_max` and `FieldInfo.max`** — removal scheduled for **5.0.0**. No
+  `FIELD_SCHEMA` entry has ever carried either, in this repository's entire history. They
+  existed to surface the schema's `maximum:` constraint, and that constraint is **advisory**:
+  keel declares no `MaxValueValidator`, and a `charisma: 9999` write against a `maximum: 100`
+  field returns 201 and stores it verbatim. The canonical schema walk therefore stays silent
+  on bounds permanently. There is no source to wire them to and no promise they could keep —
+  and a public type member meaning "hint the wire ignores" is one consumers read as
+  validation. Deprecating now rather than at the major so the signal arrives early; the
+  `@deprecated` tags surface in editors via the shipped `.d.ts`.
+
+### Changed
+- **`TokenResource` is confirmed staying.** RFC-001 §5 asked the platform owner whether the
+  token routes were carried long-term or deprecated wire-side, and the question was never
+  answered in writing — so this package's own barrel carried "wire fate under review; may be
+  removed in a later 4.x" for months, on nobody's authority. Probed against production:
+  `GET /api/v2/tokens/status/` and `/tokens/encryption-info/` both return **200**, with a 404
+  control on a nonexistent route proving the check meant something. The wire carries it. The
+  speculation is retired and the comment now records the evidence instead.
+
+## [4.0.2] — 2026-07-29
+
+Re-pinned to `v0.30.1-dist.13` (canonical **00.30.01**). No field shape changed and no
+`FIELD_SCHEMA` entry changed — the schema walk is byte-identical between the two pins, so
+nothing about decoding moved. Three things changed and nothing else.
+
+### Fixed
+- **`construct.relations` and `event.languages` shipped with no description at all** — in
+  `types.generated.ts` and in `SCHEMA.md`. Their descriptions were nested one level too deep
+  inside `items:` in the canonical YAML, which made them invisible to every consumer that reads
+  field descriptions, this package included. `SCHEMA.md` is the package's AI-legibility artifact,
+  so the gap landed where it did the most harm.
+- **Five description typos** corrected in published JSDoc and `SCHEMA.md`: `beapplied`,
+  `phyiscal`, `relating the`, `object grant`, `eventuated`. The rendered docs site had already
+  fixed all five by hand — the downstream copy was the correct one, and nobody noticed because
+  the fix went where it was visible rather than where it was true.
+
+### Changed
+- `ONLYWORLDS_VERSION` `'00.30.00'` → `'00.30.01'`. It is a public `as const`, so its **literal
+  type** changes. Depending on that literal is pathological, but it is a type-level change and
+  should not be discovered rather than announced.
+- The pin now carries canonical's numeric-bounds correction: the `maximum: 0` sentinel is gone
+  from 26 fields, 8 fields gained `minimum: 0`, and `rulings.yaml` carries the numeric-bounds
+  row. Nothing in this package consumes bounds — `maximum:` is **advisory** (keel does not
+  enforce it; a `charisma: 9999` write returns 201 and stores verbatim) and the walk stays
+  silent on bounds permanently. `integer_max` / `max` therefore remain declared no-ops here.
+
 ## [4.0.1] — 2026-07-29
 
 **Metadata correction release.** No wire-path change: the client's reads and writes never

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.
 
@@ -149,7 +151,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `phenomena` (multi link → phenomenon) — Phenomena relevant to the construct
 - `languages` (multi link → language) — Languages relevant to the construct
 - `families` (multi link → family) — Families relevant to the construct
-- `relations` (multi link → relation)
+- `relations` (multi link → relation) — Relations relevant to the construct
 - `titles` (multi link → title) — Titles relevant to the construct
 - `constructs` (multi link → construct) — Other constructs relevant to the construct
 - `events` (multi link → event) — Events relevant to the construct
@@ -200,7 +202,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `consequences` (text) — Outcomes and impacts resulting from the event
 - `start_date` (integer) — Date on which the event began
 - `end_date` (integer) — Date on which the event concluded
-- `triggers` (multi link → event) — Events that eventuated the event
+- `triggers` (multi link → event) — Events that precipitated this event
 
 ### Involves
 
@@ -215,7 +217,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `zones` (multi link → zone) — Zones relevant to the event
 - `abilities` (multi link → ability) — Abilities relevant to the event
 - `phenomena` (multi link → phenomenon) — Natural or supernatural phenomena relevant to the event
-- `languages` (multi link → language)
+- `languages` (multi link → language) — Languages relevant to the event
 - `families` (multi link → family) — Families relevant to the event
 - `relations` (multi link → relation) — Interpersonal or political relations relevant to the event
 - `titles` (multi link → title) — Titles relevant to the event
@@ -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
@@ -294,7 +296,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `purpose` (text) — The intent, motivation, or justification for the law's creation
 - `date` (integer) — Date the law was formally established, in world TIME units
 - `parent_law` (single link → law) — A law that this law derives from, modifies, or enhances
-- `penalties` (multi link → construct) — Consequences intended to beapplied when the law is contravened
+- `penalties` (multi link → construct) — Consequences intended to be applied when the law is contravened
 
 ### World
 
@@ -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
@@ -436,14 +438,14 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `weight` (integer) — Approximate or exact mass of the object, defined by world MASS units
 - `amount` (integer) — The number of identical units in this object entry
 - `parent_object` (single link → object) — Larger object that this one is part of or contained within
-- `materials` (multi link → construct) — The phyiscal matter that constitutes the object
-- `technology` (multi link → construct) — Mechanisms relating the object's design or operation
+- `materials` (multi link → construct) — The physical matter that constitutes the object
+- `technology` (multi link → construct) — Mechanisms relating to the object's design or operation
 
 ### Function
 
 - `utility` (text) — Intended purpose or primary use of the object
 - `effects` (multi link → phenomenon) — Phenomena potentially triggered or emitted on object use
-- `abilities` (multi link → ability) — Abilities that the object grant or enables
+- `abilities` (multi link → ability) — Abilities that the object grants or enables
 - `consumes` (multi link → construct) — What might be used or depleted on object use
 
 ### World

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 /** Every element carries these. The extension index signature admits namespaced
- *  pass-through fields (atlas_* / shadow_* / x_*) returned verbatim by the server. */
+ *  pass-through fields (atlas_* / shadow_* / x_*) returned verbatim by the server.
+ *  Derived from base_properties.yaml: `World` is dropped (the API rejects it in
+ *  bodies -- the key determines the world) and the four server-managed fields are
+ *  added, since they ride every wire body and appear in no element YAML. */
 interface OwElementBase {
     /** Element type slug (server-managed, read-only). */
     type: string;
-    /** Unique identifier, uuidv7 format. */
+    /** Unique identifier for the element, uuidv7 format. */
     id: string;
     /** Name of the element. */
     name: string;
@@ -28,7 +31,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.00";
+declare const ONLYWORLDS_VERSION: "00.30.01";
 /** 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
@@ -47,11 +50,24 @@ interface SectionInfo {
 }
 declare const ELEMENT_SECTIONS: Record<ElementType, SectionInfo[]>;
 /** Field type definitions for OnlyWorlds elements. */
-type FieldType = 'text' | 'integer' | 'integer_max' | 'single_link' | 'multi_link';
+type FieldType = 'text' | 'integer'
+/**
+ * @deprecated Emitted by nothing, and scheduled for removal in 5.0.0.
+ *
+ * No `FIELD_SCHEMA` entry has ever carried this type, in the entire history of
+ * this repository. It was meant to surface the schema's `maximum:` constraint,
+ * and that constraint is **advisory**: keel declares no `MaxValueValidator` and
+ * the wire stores `charisma: 9999` against a `maximum: 100` field (201, verbatim).
+ * The canonical schema walk therefore stays silent on bounds permanently, so
+ * there is no source to wire this to and no promise it could keep. A public type
+ * member meaning "hint the wire ignores" is one consumers read as validation.
+ */
+ | 'integer_max' | 'single_link' | 'multi_link';
 /** Field metadata structure. */
 interface FieldInfo {
     type: FieldType;
     target?: string;
+    /** @deprecated Never populated; removed in 5.0.0. See `FieldType.integer_max`. */
     max?: number;
     required?: boolean;
 }
@@ -1942,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>;
 }
@@ -2083,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.
      */
@@ -2207,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));
@@ -314,7 +320,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.00";
+var ONLYWORLDS_VERSION = "00.30.01";
 var ELEMENT_FAMILIES = {
   ability: "abstract",
   character: "agents",
@@ -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.0.1",
+  "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",