@onlyworlds/sdk 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -3,6 +3,97 @@
 All notable changes to `@onlyworlds/sdk`. Maintained from 3.1.0 onward (Kael, Assembly);
 earlier history lives in git log only.
 
+## [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
+consulted `FIELD_SCHEMA`, and the generated interfaces carried the correct targets throughout.
+The exposure is anything that builds UI or validation by **iterating `FIELD_SCHEMA`**.
+
+⚑ **One way this can surface as a compile error**: `relation.relations` is removed, so
+`FIELD_SCHEMA.relation.relations` is now a TypeScript error rather than a value. That is the
+intended outcome — the field does not exist in the standard and the API rejects it — but it can
+break a build rather than only a behaviour.
+
+### Fixed
+- **`FIELD_SCHEMA.collective.equipment` targeted `construct`; the standard says `object`.**
+  This is the founding case of the schema ruling table
+  (`collective-equipment-target`, ruled 2026-07-23): the v1 implementation used
+  Construct, v1 is decommissioned, and keel serves per YAML. The generated code path
+  in this repo was corrected the same week. The hand-maintained `FIELD_SCHEMA` copy of
+  the same fact, in the same package, kept shipping the decommissioned value on
+  `latest` — the fix went where someone happened to be looking.
+- **`FIELD_SCHEMA.relation.relations` removed** — a `multi_link` to `relation` that does
+  not exist in `relation.yaml`. A phantom field, publicly exported, that consumers
+  building forms from this table would have sent to an API that 422s unknown keys.
+
+### Changed
+- **`FIELD_SCHEMA` is now GENERATED** from the pinned schema distribution and gated by
+  `codegen:check`, joining `ELEMENT_ICONS` / `ELEMENT_SECTIONS` / `ELEMENT_FAMILIES`. It
+  was ~650 hand-maintained lines whose test compared nothing to the schema. Regenerating
+  it changed exactly 2 of 467 entries — the two above. Runtime shape and the deeply
+  readonly public types (`as const`) are unchanged.
+  Two declared deviations from a naive schema read are now stated in the generated file:
+  `pin.element` (a `generic-link`) splits into `element_type` + `element_id`, as the wire
+  serves it; and `integer_max` / `max` remain in the `FieldType` union unused, because
+  the walk does not surface the schema's `maximum:` constraint (41 across 17 types).
+- `codegen/generate_types.py` imports the vendored schema walk instead of carrying its
+  own copy of it. Output byte-identical.
+
 ## [4.0.0] — 2026-07-23
 
 **v2-native only.** See `docs/migrating-3-to-4.md`. 3.x stays published forever for

package/README.md

@@ -5,7 +5,10 @@
 
 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
-same schema source the server runs on.
+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.
 
 **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

package/SCHEMA.md

@@ -149,7 +149,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 +200,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 +215,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
@@ -294,7 +294,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
 
@@ -436,14 +436,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;
@@ -26,15 +29,17 @@ interface OwElementBase {
 }
 type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creature' | 'event' | 'family' | 'institution' | 'language' | 'law' | 'location' | 'map' | 'marker' | 'narrative' | 'object' | 'phenomenon' | 'pin' | 'relation' | 'species' | 'title' | 'trait' | 'zone';
 declare const ELEMENT_TYPES: ElementType[];
-/** Canonical OnlyWorlds schema version. Source: canonical VERSION file, carried into keel schema/ by the refresh script (keel 492168c). */
-declare const ONLYWORLDS_VERSION: "00.30.00";
+/** 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";
 /** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
 type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
-/** Per-type semantic family. Source: keel's PRESENTATION-WRAPPER schema key `family:`
- *  (first-party rendering metadata, keel-only — NOT part of the council-governed
- *  OnlyWorlds standard; see keel/schema-pipeline.md "The wrapper layer"). */
+/** Per-type semantic family. Source: the distribution's `presentation.json` sidecar
+ *  (first-party rendering DEFAULTS — NOT part of the council-governed OnlyWorlds
+ *  standard, and explicitly overridable by any consumer). The colour values are
+ *  NOT in the sidecar: FAMILY_COLORS is hand-authored here in src/v2/palette.ts. */
 declare const ELEMENT_FAMILIES: Record<ElementType, ElementFamily>;
-/** Material Symbols icon name per type. Source: keel's PRESENTATION-WRAPPER key `icon:` (keel 56c124a). */
+/** Material Symbols icon name per type. Source: the distribution's `presentation.json` sidecar. */
 declare const ELEMENT_ICONS: Record<ElementType, string>;
 /** Field grouping for display. DERIVED from the canonical schema's own document
  *  structure (top-level property groups, document order = display order). */
@@ -44,402 +49,28 @@ interface SectionInfo {
     fields: string[];
 }
 declare const ELEMENT_SECTIONS: Record<ElementType, SectionInfo[]>;
-
-/**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
- * wire-corrected against live staging fixtures 2026-07-18.
- *
- * OnlyWorlds v2 (keel) wire types -- the NON-generated, hand-owned wire shapes
- * (envelopes, pages, bulk, changes, config). Per-type element field typing is
- * generated (types.generated.ts). One-shape principle: a field reads the way it
- * writes -- links are UUID arrays (or UUID/null), same name both directions.
- * No `_ids` suffix in v2.
- */
-
-/** An element as read from / written to the v2 API. Loose base + extension keys. */
-type OwElement = OwElementBase;
-/** Spatial types live under spatial/ in the OW Folder Format. */
-declare const SPATIAL_TYPES: readonly ElementType[];
-interface OwWorldMeta {
-    id: string;
-    name: string;
-    updated_at?: string;
-    public_read?: boolean;
-    [field: string]: unknown;
-}
-/** List envelope: cursor-paginated. */
-interface OwPage<T = OwElement> {
-    data: T[];
-    has_more: boolean;
-    next_cursor: string | null;
-}
-/** /changes feed -- discriminated union on `op`. Apply in order -> convergence. */
-type OwChange = {
-    op: 'upsert';
-    id: string;
-    type: string;
-    element: OwElement;
-    updated_at: string;
-    [k: string]: unknown;
-} | {
-    op: 'delete';
-    id: string;
-    type: string;
-    deleted_at: string;
-    [k: string]: unknown;
-};
-/**
- * /changes response. Wire shape verified in keel source (core/changes.py) and
- * pinned here: {cursor, changes, has_more, head}.
- */
-interface OwChangesPage {
-    /** Opaque compound cursor -- persist verbatim, never parse, never expires. */
-    cursor: string;
-    changes: OwChange[];
-    has_more: boolean;
-    /**
-     * World's current change_seq. If a persisted cursor is ever AHEAD of head,
-     * the server rewound (disaster restore) -- re-baseline from cursor zero
-     * instead of assuming caught-up.
-     */
-    head: number;
-}
-interface OwBulkItem {
-    type: ElementType | string;
-    element: OwElement | Record<string, unknown>;
-}
-/**
- * One slot of a /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): `status` is
- * the NUMERIC HTTP status of that slot (201/400/...), success slots echo
- * created_at/updated_at, error slots carry an OwErrorBody under `error`.
- */
-interface OwBulkItemResult {
-    status: number;
-    id?: string;
-    created_at?: string;
-    updated_at?: string;
-    error?: OwErrorBody;
-}
-/** The wire error envelope carried in error slots and thrown errors. */
-interface OwErrorBody {
-    type?: string;
-    code?: string;
-    message?: string;
-    param?: string | null;
-    doc_url?: string;
-}
-/**
- * /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): the array key is `items`,
- * not `results`. `wasReplay` is populated by the client from the (lowercase on
- * the wire) Idempotent-Replay response header (fixture P2b) -- not a wire field.
- */
-interface OwBulkResponse {
-    errors: boolean;
-    items: OwBulkItemResult[];
-    /** Client-derived: true when the server replayed a prior Idempotency-Key. */
-    wasReplay?: boolean;
-    [k: string]: unknown;
-}
-interface OwLinkEdit {
-    add?: string[];
-    remove?: string[];
-}
-interface ListParams {
-    limit?: number;
-    cursor?: string;
-    /** One-level stub expansion, e.g. ['friends', 'location']. */
-    expand?: string[];
-    /** 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.
-     */
-    filter?: Record<string, string | number | boolean>;
-}
-interface OwClientConfig {
-    /** ow_w_ / ow_r_ / ow_a_ prefixed key, or grandfathered 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.
-     */
-    apiPin?: string;
-    /** 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.
-     */
-    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.
-     */
-    changesPageSize?: number;
-    /** Injectable for tests / fake-keel harnesses. Defaults to globalThis.fetch. */
-    fetch?: typeof globalThis.fetch;
-}
-
+/** Field type definitions for OnlyWorlds elements. */
+type FieldType = 'text' | 'integer'
 /**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
- * wire-corrected against live staging fixtures 2026-07-18.
+ * @deprecated Emitted by nothing, and scheduled for removal in 5.0.0.
  *
- * keel error envelope handling. The error contract is part of the contract:
- * envelopes carry a machine `code` and a `doc_url` fragment anchored at
- * onlyworlds.github.io/api/errors -- surface both, always. The live wire
- * envelope also carries `type` and `param` (fixtures P4a/P2c); both are
- * surfaced on the thrown error.
+ * 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.
  */
-/** Auth codes are distinguishable by design; client recovery UX differs per code. */
-type OwAuthErrorCode = 'invalid_credentials' | 'key_revoked' | 'world_gone';
-declare class OwApiError extends Error {
-    readonly status: number;
-    /** Machine error code from the keel envelope, e.g. 'invalid_credentials'. */
-    readonly code: string | null;
-    /** Error family from the envelope, e.g. 'invalid_request', 'not_found'. */
-    readonly type: string | null;
-    /** Offending field/param named by the envelope (422/400), else null. */
-    readonly param: string | null;
-    /** Documentation link from the envelope -- show it to users/logs verbatim. */
-    readonly docUrl: string | null;
-    /** Raw parsed envelope (or body text when the body wasn't JSON). */
-    readonly detail: unknown;
-    constructor(status: number, code: string | null, message: string, docUrl: string | null, detail: unknown, type?: string | null, param?: string | null);
-    get isAuthError(): boolean;
-    /** 422s/400s name the offending param/field -- typos error loudly platform-wide. */
-    get isValidationError(): boolean;
-    /** Same Idempotency-Key replayed with a different payload. */
-    get isIdempotencyConflict(): boolean;
-}
-/** Network-level failure (fetch rejected) -- no envelope to parse. */
-declare class OwNetworkError extends Error {
-    readonly cause2: unknown;
-    constructor(message: string, cause: unknown);
+ | '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;
 }
-/** Parse a wire envelope into OwApiError parts (exported for the error type-tests). */
-/** Parse the platform ERROR envelope into an OwApiError. (Renamed from parseEnvelope in 4.0 —
- *  distinct from the world-export envelope, which is a different artifact entirely.) */
-declare function parseErrorEnvelope(status: number, body: unknown): OwApiError;
-/** Build an OwApiError from a non-2xx response, tolerating non-JSON bodies. */
-declare function errorFromResponse(res: Response): Promise<OwApiError>;
-
-/**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
- * wire-corrected against live staging fixtures 2026-07-18.
- *
- * OnlyWorlds key-kind detection. Prefixes make leaked keys grep-scannable
- * (Stripe/GitHub precedent) -- and tell a client what auth shape to expect.
- */
-type OwKeyKind = 
-/** ow_w_ -- world key, read + write. Writes need the world's PIN if it has one. */
-'write'
-/** ow_r_ -- world key, read-only, works bare (no PIN). The share-with-players primitive. */
- | 'read'
-/** ow_a_ -- account Bearer token for /account/* routes; can mint world keys. */
- | 'account'
-/** Grandfathered 10-digit key. Needs PIN to read private worlds. */
- | 'legacy' | 'unknown';
-/** Demo range 0000000000-0000000009: read-only aliases, safe as live read gates. */
-declare function isDemoKey(key: string): boolean;
-declare function detectKeyKind(key: string): OwKeyKind;
-/** Can this key kind ever perform world writes? (PIN is a separate, per-world question.) */
-declare function kindCanWrite(kind: OwKeyKind): boolean;
-/**
- * Should a credential UI ask for a PIN with this key?
- * Prefixed keys read PIN-less; legacy keys may need it; writes on pinned
- * worlds always need it. 'optional' means: show the field, don't require it.
- */
-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),
- * wire-corrected against live staging fixtures 2026-07-18.
- *
- * OwV2Client -- thin typed fetch client for the keel v2 API.
- *
- * Deliberately thin: no caching, no sync state, no retry policy -- those belong
- * to callers (sync engines, tools, games). What IS encoded here is the wire
- * contract and its safety rails: payload read-only-field stripping, opaque
- * cursors, idempotency headers, doc_url-bearing errors, polite page sizes, and
- * client-side UUID minting so idempotent retries are structurally safe.
- */
-
-declare class OwV2Client {
-    readonly baseUrl: string;
-    readonly keyKind: OwKeyKind;
-    readonly pageSize: number;
-    readonly changesPageSize: number;
-    private readonly apiKey;
-    private readonly apiPin;
-    private readonly fetchImpl;
-    constructor(config: OwClientConfig);
-    /** GET /health -- unauthenticated liveness pulse. */
-    health(): Promise<unknown>;
-    /**
-     * GET /world -- world meta (name, calendar/time fields, public_read).
-     * GOTCHA (by server design): world-meta edits do NOT appear in /changes and
-     * do not bump change_seq. Poll getWorld().updated_at for meta freshness.
-     */
-    getWorld(): Promise<OwWorldMeta>;
-    /** PATCH /world -- partial world-meta update. */
-    patchWorld(partial: Record<string, unknown>): Promise<OwWorldMeta>;
-    /** GET /{type}/ -- one cursor page. */
-    list(type: ElementType | string, params?: ListParams): Promise<OwPage>;
-    /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
-    listAll(type: ElementType | string, params?: Omit<ListParams, 'cursor'>): AsyncGenerator<OwElement>;
-    /** 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
-     * caller omits one (design ruling D29d) so a retry carrying the same
-     * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
-     */
-    create(type: ElementType | string, element: OwElement | Record<string, unknown>, opts?: {
-        idempotencyKey?: string;
-    }): Promise<OwElement>;
-    /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
-    upsert(type: ElementType | string, id: string, element: OwElement | Record<string, unknown>): Promise<OwElement>;
-    /**
-     * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
-     * replace wholesale, omitted fields stay untouched. For link arrays prefer
-     * editLinks() -- atomic server-side merge, no read-before-write.
-     */
-    patch(type: ElementType | string, id: string, partial: Record<string, unknown>): Promise<OwElement>;
-    /**
-     * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
-     * tombstone AND scrubs the id from every other element's links in the same
-     * transaction -- no client-side unlink pass needed, ever.
-     */
-    delete(type: ElementType | string, id: string): Promise<void>;
-    /**
-     * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
-     * Dedupes, tolerates already-present/already-absent ids. Returns the FULL
-     * updated element (fixture P5). Use this for all relationship editing; it
-     * retires the read-merge-PATCH dance.
-     */
-    editLinks(type: ElementType | string, id: string, field: string, edit: OwLinkEdit): Promise<OwElement>;
-    /**
-     * POST /bulk -- up to ~1000 items. Partial success by default (HTTP 200
-     * always; inspect per-slot numeric `status` + top-level `errors` flag);
-     * atomic:true for all-or-nothing. Link validation runs against batch U
-     * database -- send in any order, cycles included; no client topo-sort.
-     * Success slots echo server-authoritative timestamps: set your sync baseline
-     * from this response alone. When an idempotencyKey is replayed, the returned
-     * response carries wasReplay:true (read from the Idempotent-Replay header).
-     */
-    bulk(items: OwBulkItem[], opts?: {
-        atomic?: boolean;
-        idempotencyKey?: string;
-    }): Promise<OwBulkResponse>;
-    /**
-     * GET /changes -- one page of the world's ordered change feed.
-     * Cursor is OPAQUE and never expires: persist verbatim, never parse.
-     * 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.
-     * Citizenship: heaviest route on the platform; default page size is polite.
-     */
-    changes(opts?: {
-        since?: string;
-        limit?: number;
-    }): Promise<OwChangesPage>;
-    /**
-     * Walk the feed from `since` (or from zero = full export) to the current
-     * tail, yielding ops in order. Returns the final cursor via the generator's
-     * return value; persist it for the next incremental pull.
-     */
-    changesAll(since?: string): AsyncGenerator<OwChange, {
-        cursor: string;
-        head: number;
-    }>;
-    /**
-     * Raw authenticated request against this client's baseUrl. Public since 4.0
-     * so auxiliary resources can ride the same transport — it structurally
-     * satisfies `TokenTransport` (`new TokenResource(client)`). Prefer the typed
-     * methods for element CRUD; this is the escape hatch, and it does NOT apply
-     * sanitizePayload — callers own their body shape.
-     */
-    request<T = unknown>(method: string, path: string, opts?: {
-        query?: string;
-        body?: unknown;
-        idempotencyKey?: string;
-        auth?: boolean;
-        allowEmpty?: boolean;
-        replayAware?: boolean;
-    }): Promise<T>;
-}
-
-/**
- * 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
- * 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
- * colour, not optional.
- *
- * The type→family map is GENERATED: `ELEMENT_FAMILIES` is emitted by
- * `codegen/generate_types.py` from the `family:` key in keel's schema YAML
- * (added 2026-07-23, keel c69366b) — a keel PRESENTATION-WRAPPER key
- * (first-party rendering metadata, not part of the council-governed
- * OnlyWorlds standard). It cannot drift from the schema; membership and hex
- * invariants stay test-gated in `test/palette.test.mjs`.
- *
- * The hexes below are design constants, hand-authored beside the generated
- * map. Do not change any value without re-running the CVD validation (every
- * brighter World green collides with Temporal amber for protan viewers — the
- * green is pinned BY the accessibility budget).
- *
- * Provenance: first proven live in atlas (`src/core/element-colors.ts`) and
- * council (`src/cosmos/element-families.ts`) — both become re-exports of this
- * module.
- */
-
-/**
- * Family → validated hex per surface mode. `light` assumes near-white
- * surfaces, `dark` assumes near-black (measured against #0a0a0a).
- * World green is identical in both modes and sits at its low-contrast end
- * deliberately — see module header before "fixing" it.
- */
-declare const FAMILY_COLORS: Record<ElementFamily, {
-    light: string;
-    dark: string;
-}>;
-/** Semantic family for an element type slug. */
-declare function familyOf(type: ElementType): ElementFamily;
-/**
- * The convenience most callers want: canonical colour for an element type.
- * 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).
- */
-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). */
-declare const FAMILY_ORDER: readonly ElementFamily[];
-
-/**
- * Current OnlyWorlds version
- * Synced with https://github.com/OnlyWorlds/OnlyWorlds/blob/main/VERSION
- */
-/**
- * Field type definitions for OnlyWorlds elements
- */
-type FieldType = 'text' | 'integer' | 'integer_max' | 'single_link' | 'multi_link';
-/**
- * Field metadata structure
- */
-interface FieldInfo {
-    type: FieldType;
-    target?: string;
-    max?: number;
-    required?: boolean;
-}
-declare const ELEMENT_LABELS: Record<ElementType, string>;
 declare const FIELD_SCHEMA: {
     readonly ability: {
         readonly name: {
@@ -681,7 +312,7 @@ declare const FIELD_SCHEMA: {
         };
         readonly equipment: {
             readonly type: "multi_link";
-            readonly target: "construct";
+            readonly target: "object";
         };
         readonly activity: {
             readonly type: "text";
@@ -1892,10 +1523,6 @@ declare const FIELD_SCHEMA: {
             readonly type: "multi_link";
             readonly target: "family";
         };
-        readonly relations: {
-            readonly type: "multi_link";
-            readonly target: "relation";
-        };
         readonly titles: {
             readonly type: "multi_link";
             readonly target: "title";
@@ -2223,6 +1850,389 @@ declare const FIELD_SCHEMA: {
         };
     };
 };
+
+/**
+ * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * wire-corrected against live staging fixtures 2026-07-18.
+ *
+ * OnlyWorlds v2 (keel) wire types -- the NON-generated, hand-owned wire shapes
+ * (envelopes, pages, bulk, changes, config). Per-type element field typing is
+ * generated (types.generated.ts). One-shape principle: a field reads the way it
+ * writes -- links are UUID arrays (or UUID/null), same name both directions.
+ * No `_ids` suffix in v2.
+ */
+
+/** An element as read from / written to the v2 API. Loose base + extension keys. */
+type OwElement = OwElementBase;
+/** Spatial types live under spatial/ in the OW Folder Format. */
+declare const SPATIAL_TYPES: readonly ElementType[];
+interface OwWorldMeta {
+    id: string;
+    name: string;
+    updated_at?: string;
+    public_read?: boolean;
+    [field: string]: unknown;
+}
+/** List envelope: cursor-paginated. */
+interface OwPage<T = OwElement> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+/** /changes feed -- discriminated union on `op`. Apply in order -> convergence. */
+type OwChange = {
+    op: 'upsert';
+    id: string;
+    type: string;
+    element: OwElement;
+    updated_at: string;
+    [k: string]: unknown;
+} | {
+    op: 'delete';
+    id: string;
+    type: string;
+    deleted_at: string;
+    [k: string]: unknown;
+};
+/**
+ * /changes response. Wire shape verified in keel source (core/changes.py) and
+ * pinned here: {cursor, changes, has_more, head}.
+ */
+interface OwChangesPage {
+    /** Opaque compound cursor -- persist verbatim, never parse, never expires. */
+    cursor: string;
+    changes: OwChange[];
+    has_more: boolean;
+    /**
+     * World's current change_seq. If a persisted cursor is ever AHEAD of head,
+     * the server rewound (disaster restore) -- re-baseline from cursor zero
+     * instead of assuming caught-up.
+     */
+    head: number;
+}
+interface OwBulkItem {
+    type: ElementType | string;
+    element: OwElement | Record<string, unknown>;
+}
+/**
+ * One slot of a /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): `status` is
+ * the NUMERIC HTTP status of that slot (201/400/...), success slots echo
+ * created_at/updated_at, error slots carry an OwErrorBody under `error`.
+ */
+interface OwBulkItemResult {
+    status: number;
+    id?: string;
+    created_at?: string;
+    updated_at?: string;
+    error?: OwErrorBody;
+}
+/** The wire error envelope carried in error slots and thrown errors. */
+interface OwErrorBody {
+    type?: string;
+    code?: string;
+    message?: string;
+    param?: string | null;
+    doc_url?: string;
+}
+/**
+ * /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): the array key is `items`,
+ * not `results`. `wasReplay` is populated by the client from the (lowercase on
+ * the wire) Idempotent-Replay response header (fixture P2b) -- not a wire field.
+ */
+interface OwBulkResponse {
+    errors: boolean;
+    items: OwBulkItemResult[];
+    /** Client-derived: true when the server replayed a prior Idempotency-Key. */
+    wasReplay?: boolean;
+    [k: string]: unknown;
+}
+interface OwLinkEdit {
+    add?: string[];
+    remove?: string[];
+}
+interface ListParams {
+    limit?: number;
+    cursor?: string;
+    /** One-level stub expansion, e.g. ['friends', 'location']. */
+    expand?: string[];
+    /** 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.
+     */
+    filter?: Record<string, string | number | boolean>;
+}
+interface OwClientConfig {
+    /** ow_w_ / ow_r_ / ow_a_ prefixed key, or grandfathered 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.
+     */
+    apiPin?: string;
+    /** 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.
+     */
+    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.
+     */
+    changesPageSize?: number;
+    /** Injectable for tests / fake-keel harnesses. Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * wire-corrected against live staging fixtures 2026-07-18.
+ *
+ * keel error envelope handling. The error contract is part of the contract:
+ * envelopes carry a machine `code` and a `doc_url` fragment anchored at
+ * onlyworlds.github.io/api/errors -- surface both, always. The live wire
+ * envelope also carries `type` and `param` (fixtures P4a/P2c); both are
+ * surfaced on the thrown error.
+ */
+/** Auth codes are distinguishable by design; client recovery UX differs per code. */
+type OwAuthErrorCode = 'invalid_credentials' | 'key_revoked' | 'world_gone';
+declare class OwApiError extends Error {
+    readonly status: number;
+    /** Machine error code from the keel envelope, e.g. 'invalid_credentials'. */
+    readonly code: string | null;
+    /** Error family from the envelope, e.g. 'invalid_request', 'not_found'. */
+    readonly type: string | null;
+    /** Offending field/param named by the envelope (422/400), else null. */
+    readonly param: string | null;
+    /** Documentation link from the envelope -- show it to users/logs verbatim. */
+    readonly docUrl: string | null;
+    /** Raw parsed envelope (or body text when the body wasn't JSON). */
+    readonly detail: unknown;
+    constructor(status: number, code: string | null, message: string, docUrl: string | null, detail: unknown, type?: string | null, param?: string | null);
+    get isAuthError(): boolean;
+    /** 422s/400s name the offending param/field -- typos error loudly platform-wide. */
+    get isValidationError(): boolean;
+    /** Same Idempotency-Key replayed with a different payload. */
+    get isIdempotencyConflict(): boolean;
+}
+/** Network-level failure (fetch rejected) -- no envelope to parse. */
+declare class OwNetworkError extends Error {
+    readonly cause2: unknown;
+    constructor(message: string, cause: unknown);
+}
+/** Parse a wire envelope into OwApiError parts (exported for the error type-tests). */
+/** Parse the platform ERROR envelope into an OwApiError. (Renamed from parseEnvelope in 4.0 —
+ *  distinct from the world-export envelope, which is a different artifact entirely.) */
+declare function parseErrorEnvelope(status: number, body: unknown): OwApiError;
+/** Build an OwApiError from a non-2xx response, tolerating non-JSON bodies. */
+declare function errorFromResponse(res: Response): Promise<OwApiError>;
+
+/**
+ * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * wire-corrected against live staging fixtures 2026-07-18.
+ *
+ * OnlyWorlds key-kind detection. Prefixes make leaked keys grep-scannable
+ * (Stripe/GitHub precedent) -- and tell a client what auth shape to expect.
+ */
+type OwKeyKind = 
+/** ow_w_ -- world key, read + write. Writes need the world's PIN if it has one. */
+'write'
+/** ow_r_ -- world key, read-only, works bare (no PIN). The share-with-players primitive. */
+ | 'read'
+/** ow_a_ -- account Bearer token for /account/* routes; can mint world keys. */
+ | 'account'
+/** Grandfathered 10-digit key. Needs PIN to read private worlds. */
+ | 'legacy' | 'unknown';
+/** Demo range 0000000000-0000000009: read-only aliases, safe as live read gates. */
+declare function isDemoKey(key: string): boolean;
+declare function detectKeyKind(key: string): OwKeyKind;
+/** Can this key kind ever perform world writes? (PIN is a separate, per-world question.) */
+declare function kindCanWrite(kind: OwKeyKind): boolean;
+/**
+ * Should a credential UI ask for a PIN with this key?
+ * Prefixed keys read PIN-less; legacy keys may need it; writes on pinned
+ * worlds always need it. 'optional' means: show the field, don't require it.
+ */
+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),
+ * wire-corrected against live staging fixtures 2026-07-18.
+ *
+ * OwV2Client -- thin typed fetch client for the keel v2 API.
+ *
+ * Deliberately thin: no caching, no sync state, no retry policy -- those belong
+ * to callers (sync engines, tools, games). What IS encoded here is the wire
+ * contract and its safety rails: payload read-only-field stripping, opaque
+ * cursors, idempotency headers, doc_url-bearing errors, polite page sizes, and
+ * client-side UUID minting so idempotent retries are structurally safe.
+ */
+
+declare class OwV2Client {
+    readonly baseUrl: string;
+    readonly keyKind: OwKeyKind;
+    readonly pageSize: number;
+    readonly changesPageSize: number;
+    private readonly apiKey;
+    private readonly apiPin;
+    private readonly fetchImpl;
+    constructor(config: OwClientConfig);
+    /** GET /health -- unauthenticated liveness pulse. */
+    health(): Promise<unknown>;
+    /**
+     * GET /world -- world meta (name, calendar/time fields, public_read).
+     * GOTCHA (by server design): world-meta edits do NOT appear in /changes and
+     * do not bump change_seq. Poll getWorld().updated_at for meta freshness.
+     */
+    getWorld(): Promise<OwWorldMeta>;
+    /** PATCH /world -- partial world-meta update. */
+    patchWorld(partial: Record<string, unknown>): Promise<OwWorldMeta>;
+    /** GET /{type}/ -- one cursor page. */
+    list(type: ElementType | string, params?: ListParams): Promise<OwPage>;
+    /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
+    listAll(type: ElementType | string, params?: Omit<ListParams, 'cursor'>): AsyncGenerator<OwElement>;
+    /** 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
+     * caller omits one (design ruling D29d) so a retry carrying the same
+     * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
+     */
+    create(type: ElementType | string, element: OwElement | Record<string, unknown>, opts?: {
+        idempotencyKey?: string;
+    }): Promise<OwElement>;
+    /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
+    upsert(type: ElementType | string, id: string, element: OwElement | Record<string, unknown>): Promise<OwElement>;
+    /**
+     * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
+     * replace wholesale, omitted fields stay untouched. For link arrays prefer
+     * editLinks() -- atomic server-side merge, no read-before-write.
+     */
+    patch(type: ElementType | string, id: string, partial: Record<string, unknown>): Promise<OwElement>;
+    /**
+     * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
+     * tombstone AND scrubs the id from every other element's links in the same
+     * transaction -- no client-side unlink pass needed, ever.
+     */
+    delete(type: ElementType | string, id: string): Promise<void>;
+    /**
+     * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
+     * Dedupes, tolerates already-present/already-absent ids. Returns the FULL
+     * updated element (fixture P5). Use this for all relationship editing; it
+     * retires the read-merge-PATCH dance.
+     */
+    editLinks(type: ElementType | string, id: string, field: string, edit: OwLinkEdit): Promise<OwElement>;
+    /**
+     * POST /bulk -- up to ~1000 items. Partial success by default (HTTP 200
+     * always; inspect per-slot numeric `status` + top-level `errors` flag);
+     * atomic:true for all-or-nothing. Link validation runs against batch U
+     * database -- send in any order, cycles included; no client topo-sort.
+     * Success slots echo server-authoritative timestamps: set your sync baseline
+     * from this response alone. When an idempotencyKey is replayed, the returned
+     * response carries wasReplay:true (read from the Idempotent-Replay header).
+     */
+    bulk(items: OwBulkItem[], opts?: {
+        atomic?: boolean;
+        idempotencyKey?: string;
+    }): Promise<OwBulkResponse>;
+    /**
+     * GET /changes -- one page of the world's ordered change feed.
+     * Cursor is OPAQUE and never expires: persist verbatim, never parse.
+     * 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.
+     * Citizenship: heaviest route on the platform; default page size is polite.
+     */
+    changes(opts?: {
+        since?: string;
+        limit?: number;
+    }): Promise<OwChangesPage>;
+    /**
+     * Walk the feed from `since` (or from zero = full export) to the current
+     * tail, yielding ops in order. Returns the final cursor via the generator's
+     * return value; persist it for the next incremental pull.
+     */
+    changesAll(since?: string): AsyncGenerator<OwChange, {
+        cursor: string;
+        head: number;
+    }>;
+    /**
+     * Raw authenticated request against this client's baseUrl. Public since 4.0
+     * so auxiliary resources can ride the same transport — it structurally
+     * satisfies `TokenTransport` (`new TokenResource(client)`). Prefer the typed
+     * methods for element CRUD; this is the escape hatch, and it does NOT apply
+     * sanitizePayload — callers own their body shape.
+     */
+    request<T = unknown>(method: string, path: string, opts?: {
+        query?: string;
+        body?: unknown;
+        idempotencyKey?: string;
+        auth?: boolean;
+        allowEmpty?: boolean;
+        replayAware?: boolean;
+    }): Promise<T>;
+}
+
+/**
+ * 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
+ * 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
+ * colour, not optional.
+ *
+ * The type→family map is GENERATED: `ELEMENT_FAMILIES` is emitted by
+ * `codegen/generate_types.py` from the `family:` key in keel's schema YAML
+ * (added 2026-07-23, keel c69366b) — a keel PRESENTATION-WRAPPER key
+ * (first-party rendering metadata, not part of the council-governed
+ * OnlyWorlds standard). It cannot drift from the schema; membership and hex
+ * invariants stay test-gated in `test/palette.test.mjs`.
+ *
+ * The hexes below are design constants, hand-authored beside the generated
+ * map. Do not change any value without re-running the CVD validation (every
+ * brighter World green collides with Temporal amber for protan viewers — the
+ * green is pinned BY the accessibility budget).
+ *
+ * Provenance: first proven live in atlas (`src/core/element-colors.ts`) and
+ * council (`src/cosmos/element-families.ts`) — both become re-exports of this
+ * module.
+ */
+
+/**
+ * Family → validated hex per surface mode. `light` assumes near-white
+ * surfaces, `dark` assumes near-black (measured against #0a0a0a).
+ * World green is identical in both modes and sits at its low-contrast end
+ * deliberately — see module header before "fixing" it.
+ */
+declare const FAMILY_COLORS: Record<ElementFamily, {
+    light: string;
+    dark: string;
+}>;
+/** Semantic family for an element type slug. */
+declare function familyOf(type: ElementType): ElementFamily;
+/**
+ * The convenience most callers want: canonical colour for an element type.
+ * 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).
+ */
+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). */
+declare const FAMILY_ORDER: readonly ElementFamily[];
+
+/**
+ * Current OnlyWorlds version
+ * Synced with https://github.com/OnlyWorlds/OnlyWorlds/blob/main/VERSION
+ */
+declare const ELEMENT_LABELS: Record<ElementType, string>;
 /**
  * Get Material Design icon name for an element type
  * Accepts multiple formats: 'character', 'characters', 'Character', etc.

package/dist/index.js

@@ -314,7 +314,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",
@@ -466,50 +466,6 @@ var ELEMENT_SECTIONS = {
     { name: "World", order: 2, fields: ["context", "populations", "titles", "principles"] }
   ]
 };
-
-// src/v2/types.ts
-var SPATIAL_TYPES = ["map", "pin", "marker", "zone"];
-
-// src/v2/palette.ts
-var FAMILY_COLORS = {
-  agents: { light: "#2a78d6", dark: "#3987e5" },
-  world: { light: "#008300", dark: "#008300" },
-  abstract: { light: "#e87ba4", dark: "#d55181" },
-  temporal: { light: "#eda100", dark: "#c98500" }
-};
-function familyOf(type) {
-  return ELEMENT_FAMILIES[type];
-}
-function elementColor(type, mode = "dark") {
-  return FAMILY_COLORS[ELEMENT_FAMILIES[type]][mode];
-}
-var FAMILY_ORDER = ["agents", "world", "abstract", "temporal"];
-
-// src/v2/constants.ts
-var ELEMENT_LABELS = {
-  ability: "Abilities",
-  character: "Characters",
-  collective: "Collectives",
-  construct: "Constructs",
-  creature: "Creatures",
-  event: "Events",
-  family: "Families",
-  institution: "Institutions",
-  language: "Languages",
-  law: "Laws",
-  location: "Locations",
-  map: "Maps",
-  marker: "Markers",
-  narrative: "Narratives",
-  object: "Objects",
-  phenomenon: "Phenomena",
-  pin: "Pins",
-  relation: "Relations",
-  species: "Species",
-  title: "Titles",
-  trait: "Traits",
-  zone: "Zones"
-};
 var FIELD_SCHEMA = {
   ability: {
     // Base fields (shared by all elements)
@@ -594,7 +550,7 @@ var FIELD_SCHEMA = {
     count: { type: "integer" },
     formation_date: { type: "integer" },
     operator: { type: "single_link", target: "institution" },
-    equipment: { type: "multi_link", target: "construct" },
+    equipment: { type: "multi_link", target: "object" },
     // Dynamics
     activity: { type: "text" },
     disposition: { type: "text" },
@@ -655,7 +611,7 @@ var FIELD_SCHEMA = {
     weight: { type: "integer" },
     height: { type: "integer" },
     species: { type: "multi_link", target: "species" },
-    // Behaviour
+    // Behavior
     habits: { type: "text" },
     demeanor: { type: "text" },
     traits: { type: "multi_link", target: "trait" },
@@ -957,9 +913,7 @@ var FIELD_SCHEMA = {
     // Details
     map: { type: "single_link", target: "map", required: true },
     element_type: { type: "text", required: true },
-    // ElementType enum value; YAML 'element' generic-link is split into _type + _id
     element_id: { type: "single_link", target: "any", required: true },
-    // Can reference any element
     x: { type: "integer", required: true },
     y: { type: "integer", required: true },
     z: { type: "integer" }
@@ -992,7 +946,6 @@ var FIELD_SCHEMA = {
     phenomena: { type: "multi_link", target: "phenomenon" },
     languages: { type: "multi_link", target: "language" },
     families: { type: "multi_link", target: "family" },
-    relations: { type: "multi_link", target: "relation" },
     titles: { type: "multi_link", target: "title" },
     constructs: { type: "multi_link", target: "construct" },
     narratives: { type: "multi_link", target: "narrative" }
@@ -1104,6 +1057,50 @@ var FIELD_SCHEMA = {
     principles: { type: "multi_link", target: "construct" }
   }
 };
+
+// src/v2/types.ts
+var SPATIAL_TYPES = ["map", "pin", "marker", "zone"];
+
+// src/v2/palette.ts
+var FAMILY_COLORS = {
+  agents: { light: "#2a78d6", dark: "#3987e5" },
+  world: { light: "#008300", dark: "#008300" },
+  abstract: { light: "#e87ba4", dark: "#d55181" },
+  temporal: { light: "#eda100", dark: "#c98500" }
+};
+function familyOf(type) {
+  return ELEMENT_FAMILIES[type];
+}
+function elementColor(type, mode = "dark") {
+  return FAMILY_COLORS[ELEMENT_FAMILIES[type]][mode];
+}
+var FAMILY_ORDER = ["agents", "world", "abstract", "temporal"];
+
+// src/v2/constants.ts
+var ELEMENT_LABELS = {
+  ability: "Abilities",
+  character: "Characters",
+  collective: "Collectives",
+  construct: "Constructs",
+  creature: "Creatures",
+  event: "Events",
+  family: "Families",
+  institution: "Institutions",
+  language: "Languages",
+  law: "Laws",
+  location: "Locations",
+  map: "Maps",
+  marker: "Markers",
+  narrative: "Narratives",
+  object: "Objects",
+  phenomenon: "Phenomena",
+  pin: "Pins",
+  relation: "Relations",
+  species: "Species",
+  title: "Titles",
+  trait: "Traits",
+  zone: "Zones"
+};
 var PLURAL_TO_SINGULAR = {
   abilities: "ability",
   characters: "character",

package/package.json

@@ -1,61 +1,63 @@
-{
-  "name": "@onlyworlds/sdk",
-  "version": "4.0.0",
-  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "types": "dist/index.d.ts",
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "README.md",
-    "AGENTS.md",
-    "CHANGELOG.md",
-    "SCHEMA.md"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
-    "pretest": "npm run build",
-    "test": "node --test \"test/**/*.test.mjs\"",
-    "codegen": "python codegen/generate_types.py",
-    "codegen:check": "python codegen/generate_types.py --check",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "onlyworlds",
-    "worldbuilding",
-    "api",
-    "sdk",
-    "typescript",
-    "rpg",
-    "ttrpg",
-    "game-development"
-  ],
-  "author": "OnlyWorlds",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/OnlyWorlds/sdk.git"
-  },
-  "homepage": "https://onlyworlds.github.io/",
-  "bugs": {
-    "url": "https://github.com/OnlyWorlds/sdk/issues"
-  },
-  "devDependencies": {
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3"
-  },
-  "peerDependencies": {
-    "typescript": ">=4.5.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@onlyworlds/sdk",
+  "version": "4.1.0",
+  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "SCHEMA.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "pretest": "npm run build",
+    "test": "node --test",
+    "codegen": "python codegen/generate_types.py",
+    "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"
+  },
+  "keywords": [
+    "onlyworlds",
+    "worldbuilding",
+    "api",
+    "sdk",
+    "typescript",
+    "rpg",
+    "ttrpg",
+    "game-development"
+  ],
+  "author": "OnlyWorlds",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OnlyWorlds/sdk.git"
+  },
+  "homepage": "https://onlyworlds.github.io/",
+  "bugs": {
+    "url": "https://github.com/OnlyWorlds/sdk/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}