@onlyworlds/sdk 4.40.0 → 4.41.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.32.1-dist.27** (canonical 00.32.01).
+**Current as of**: SDK **4.x** · schema-dist **v0.32.1-dist.28** (canonical 00.32.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.
 
@@ -108,9 +108,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   seat's key is recorded as an agent without the option. Never set it in a tool people use.
 - A guest or player reads what its own Character's sheet links to as a **stub**, marked
   `known_of: true` (`isKnownOf(el)`): only `id`, `type`, `name`, `description`, `supertype`,
-  `subtype`, `image_url` and the timestamps are real; every other field reads unset, and its
-  files are 404. Render it as known of, never merge its empties over a whole copy, and never
-  write it back: `upsert`, `patch`, `create` and `bulk` throw a TypeError on one before sending.
+  `subtype`, `image_url`, the timestamps and the fields its type lists in `PUBLIC_FIELDS` are
+  real; every other field reads unset, and its files are 404. Render it as known of, never
+  merge its empties over a whole copy, and never write it back: `upsert`, `patch`, `create`
+  and `bulk` throw a TypeError on one before sending. keel refuses any write carrying
+  `known_of` with 422 `known_of_not_writable` (`err.isKnownOfNotWritable`).
 - 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

package/CHANGELOG.md

@@ -5,6 +5,26 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.41.0] - 2026-10-20
+
+A known-of stub's public fields (keel PR 117, keel #448), live in production, and schema-dist v0.32.1-dist.28, which publishes them.
+
+### Added
+- **`PUBLIC_FIELDS`** (generated from the distribution's `presentation.json`, `types.<type>.public`): per element type,
+  the fields onlyworlds.com shows on a known-of stub besides the base fields, with their values, as a readonly
+  `as const` array; all 22 types present. A Character's are `physicality`, `height`, `weight`, `species` and
+  `reputation`; every other type's list is empty for now. Platform behaviour, not a default to override. Codegen
+  exits 1 on a tree without the sidecar, a type without the key, or a name that is not a field of its type.
+- **`err.isKnownOfNotWritable`**: keel's named refusal of a write carrying `known_of`, true or false (422
+  `known_of_not_writable`, `param` known_of). This client never sends `known_of` (4.40.0's strip and refusal are
+  unchanged), so it reaches you only through `request()`; `/bulk` puts it in the item's slot.
+
+### Changed
+- Repinned to schema-dist v0.32.1-dist.28: `presentation.json` gains `types.<type>.public` and `_meta.public`; no
+  schema file moved, so the generated interfaces change only their source lines.
+- **A stub's description** on `known_of` (the generated doc comment, `SCHEMA.md` and `AGENTS.md`) says a stub
+  keeps its type's `PUBLIC_FIELDS` with their values too; it said every other field reads unset.
+
 ## [4.40.0] - 2026-10-20
 
 The "known of" stub's client half (keel PR 113, B16; keel #421 §7g), live in production since 2026-10-20 13:47.

package/README.md

@@ -285,6 +285,7 @@ import {
   ELEMENT_LABELS,   // plural display labels
   ELEMENT_SECTIONS, // field grouping and display order
   FIELD_SCHEMA,     // per-field type and link target
+  PUBLIC_FIELDS,    // per type, the fields a known-of stub carries besides the base fields
   elementColor,     // colour by family; the icon carries the type
 } from '@onlyworlds/sdk';
 

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.1-dist.27** — canonical schema **00.32.01**, published 2026-10-20.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.1-dist.28** — canonical schema **00.32.01**, published 2026-10-20.
 
 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.
@@ -8,7 +8,7 @@ Written for both humans and AI agents reading this package locally.
 **The shape rules** (v2 wire dialect): every element carries `id` (UUID), `name`, optional
 `description`/`supertype`/`subtype`/`image_url`, server-managed `type`/`created_at`/`updated_at`/`change_seq`/`created_by`,
 `known_of: true` only on a stub (an element a guest knows of through its Character's sheet:
-its other fields read unset and are not values; never write a stub back),
+its type's `PUBLIC_FIELDS` carry values, its other fields read unset and are not values; never write a stub back),
 and namespaced extension fields (`x_*` etc.) returned verbatim. Link fields use ONE bare
 name in both read and write (no `_ids` suffix). Single links are `UUID | null`; multi links
 are `UUID[]`. **Links are owned one-way**: the type listed below owns the field (e.g.

package/dist/index.d.ts

@@ -31,7 +31,7 @@ interface OwElementBase {
     changed_by?: string | null;
     /** The door of the last write (server-managed, read-only): `seat` (an agent seat), `mcp`, `declared` (a client that sent X-OW-Agent), then `api`, `v1`, `sync`, or `server` (keel's own writes). The first three are agent-made. Null for anything last changed before writes recorded it. */
     changed_via?: 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | null;
-    /** Present, and true, only on a stub (server-managed, read-only): an element a guest or player reaches only through its own Character's sheet. A stub keeps id, type, name, description, supertype, subtype, image_url, created_at, updated_at and change_seq; every other field reads unset ("", null, []), created_by/changed_by/changed_via null, no extension fields, and its files are 404. Its empties are not values and not a deletion: never write a stub back. Absent: the element is whole. See isKnownOf(). */
+    /** Present, and true, only on a stub (server-managed, read-only): an element a guest or player reaches only through its own Character's sheet. A stub keeps id, type, name, description, supertype, subtype, image_url, created_at, updated_at and change_seq, and the fields its type lists in PUBLIC_FIELDS with their values; every other field reads unset ("", null, []), created_by/changed_by/changed_via null, no extension fields, and its files are 404. Its empties are not values and not a deletion: never write a stub back. Absent: the element is whole. See isKnownOf(). */
     known_of?: true;
     /** Namespaced extension fields (atlas_* / shadow_* / x_*), returned verbatim. */
     [ext: string]: unknown;
@@ -50,6 +50,34 @@ type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
 declare const ELEMENT_FAMILIES: Record<ElementType, ElementFamily>;
 /** Material Symbols icon name per type. Source: the distribution's `presentation.json` sidecar. */
 declare const ELEMENT_ICONS: Record<ElementType, string>;
+/** The fields onlyworlds.com shows on a known-of element (`known_of: true`, see isKnownOf)
+ *  besides the base fields, with their values; every other field of a stub reads unset.
+ *  Platform behaviour, not a default to override. Source: the distribution's
+ *  `presentation.json` sidecar, `types.<type>.public` (keel PR 117). */
+declare const PUBLIC_FIELDS: {
+    readonly ability: readonly [];
+    readonly character: readonly ["physicality", "height", "weight", "species", "reputation"];
+    readonly collective: readonly [];
+    readonly construct: readonly [];
+    readonly creature: readonly [];
+    readonly event: readonly [];
+    readonly family: readonly [];
+    readonly institution: readonly [];
+    readonly language: readonly [];
+    readonly law: readonly [];
+    readonly location: readonly [];
+    readonly map: readonly [];
+    readonly marker: readonly [];
+    readonly narrative: readonly [];
+    readonly object: readonly [];
+    readonly phenomenon: readonly [];
+    readonly pin: readonly [];
+    readonly relation: readonly [];
+    readonly species: readonly [];
+    readonly title: readonly [];
+    readonly trait: readonly [];
+    readonly zone: readonly [];
+};
 /** Field grouping for display. DERIVED from the canonical schema's own document
  *  structure (top-level property groups, document order = display order). */
 interface SectionInfo {
@@ -2744,6 +2772,14 @@ declare class OwApiError extends Error {
      * keel's hidden mark is on; until then `viewAs` is an unknown parameter (422).
      */
     get isViewAsOwnerOnly(): boolean;
+    /**
+     * An element write carried `known_of` (422 `known_of_not_writable`, `param` known_of; keel
+     * PR 117), true or false: the key marks a stub and is never written. Drop it and send only
+     * the fields you mean. This client never sends it (`known_of` is stripped, a stub is a
+     * TypeError before sending), so it reaches you only through `request()`. `/bulk` never
+     * throws for it: the item's slot carries the code, and its siblings apply.
+     */
+    get isKnownOfNotWritable(): boolean;
     /**
      * A `patch` or `editLinks` sent with `ifMatch` found the element moved past that
      * `change_seq` (412 `precondition_failed`, keel #210): nothing was written and nothing
@@ -4403,4 +4439,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwDeleteReason, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, OwSignInError, type OwSignInReason, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };
+export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwDeleteReason, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, OwSignInError, type OwSignInReason, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -160,6 +160,16 @@ var OwApiError = class extends Error {
   get isViewAsOwnerOnly() {
     return this.status === 403 && this.code === "view_as_owner_only";
   }
+  /**
+   * An element write carried `known_of` (422 `known_of_not_writable`, `param` known_of; keel
+   * PR 117), true or false: the key marks a stub and is never written. Drop it and send only
+   * the fields you mean. This client never sends it (`known_of` is stripped, a stub is a
+   * TypeError before sending), so it reaches you only through `request()`. `/bulk` never
+   * throws for it: the item's slot carries the code, and its siblings apply.
+   */
+  get isKnownOfNotWritable() {
+    return this.status === 422 && this.code === "known_of_not_writable";
+  }
   /**
    * A `patch` or `editLinks` sent with `ifMatch` found the element moved past that
    * `change_seq` (412 `precondition_failed`, keel #210): nothing was written and nothing
@@ -1386,6 +1396,30 @@ var ELEMENT_ICONS = {
   trait: "flaky",
   zone: "pentagon"
 };
+var PUBLIC_FIELDS = {
+  ability: [],
+  character: ["physicality", "height", "weight", "species", "reputation"],
+  collective: [],
+  construct: [],
+  creature: [],
+  event: [],
+  family: [],
+  institution: [],
+  language: [],
+  law: [],
+  location: [],
+  map: [],
+  marker: [],
+  narrative: [],
+  object: [],
+  phenomenon: [],
+  pin: [],
+  relation: [],
+  species: [],
+  title: [],
+  trait: [],
+  zone: []
+};
 var ELEMENT_SECTIONS = {
   ability: [
     { name: "Mechanics", order: 1, fields: ["activation", "duration", "potency", "range", "effects", "challenges", "talents", "requisites"] },
@@ -3557,6 +3591,7 @@ export {
   OwWorldFileError,
   PHOTO_MAX_BYTES,
   PHOTO_TYPES,
+  PUBLIC_FIELDS,
   SPATIAL_TYPES,
   TokenResource,
   WORLD_FILE_MAX_BYTES,

package/package.json

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