@onlyworlds/sdk 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -3,6 +3,61 @@
 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

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;
@@ -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;
 }

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",

package/package.json

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