@onlyworlds/sdk 4.39.0 → 4.40.0

package/AGENTS.md

@@ -106,6 +106,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   `mcp`, `declared`, `api`, `v1`, `sync`, `server`), and a `/changes` delete carries
   `deleted_by` and `deleted_via`; `isAgentDoor(door)` is true for the first three. An agent
   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.
 - 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,25 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [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.
+
+### Added
+- **`known_of?: true`** on `OwElementBase` (generated; `SCHEMA.md` says it too): present, and true, only on a
+  stub, an element a guest or player reaches only through its own Character's sheet, one step out. 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` and
+  `changed_via` are null, it has no extension fields, and its files are 404. For Lantern and Atlas, which
+  render stubs (Temper).
+- **`isKnownOf(el)`**: true only for `known_of: true`; absent or anything else is a whole element.
+
+### Changed
+- **A stub is never written**: `upsert`, `patch`, `create` and `bulk` throw a `TypeError` before sending a
+  body with `known_of: true` (`bulk` names the item, and sends none of the batch). Stripping the marker would
+  turn keel's 422 into a write that blanks the element for any key that may write it (an owner pushing a
+  player's copy). `known_of` joins the strip list, so any other value of it is never sent.
+
 ## [4.39.0] - 2026-10-20
 
 The party link (keel #422 PR 2, keel PR 110), live in production since 2026-10-20 13:15.

package/SCHEMA.md

@@ -7,6 +7,8 @@ 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),
 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

@@ -2,7 +2,8 @@
  *  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 seven server-managed fields are
- *  added, since they ride every wire body and appear in no element YAML. */
+ *  added, since they ride every wire body and appear in no element YAML; `known_of`
+ *  rides only a stub. */
 interface OwElementBase {
     /** Element type slug (server-managed, read-only). */
     type: string;
@@ -30,6 +31,8 @@ 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(). */
+    known_of?: true;
     /** Namespaced extension fields (atlas_* / shadow_* / x_*), returned verbatim. */
     [ext: string]: unknown;
 }
@@ -1955,6 +1958,19 @@ type OwWriteDoor = NonNullable<OwElementBase['changed_via']>;
 declare const AGENT_DOORS: readonly OwWriteDoor[];
 /** Whether a write came through an agent's door (`changed_via` or `deleted_via`); false for null. */
 declare function isAgentDoor(door: OwWriteDoor | null | undefined): boolean;
+/**
+ * Whether an element body is a stub the reader only knows of (keel PR 113, B16; keel #421
+ * §7g): a guest or player reaches it only through its own Character's sheet, one step out.
+ * 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` and `changed_via` are null, it carries no extension
+ * fields, and its files answer 404. Those empties are not the element's values and not a
+ * deletion: never merge them over a whole copy, and never write a stub back (this client
+ * refuses to). True only for `known_of: true`; absent or anything else is a whole element.
+ */
+declare function isKnownOf(element: {
+    known_of?: unknown;
+} | null | undefined): boolean;
 /**
  * /changes response. Wire shape verified in keel source (core/changes.py) and
  * pinned here: {cursor, changes, has_more, head}.
@@ -2941,7 +2957,11 @@ declare class OwV2Client {
     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. */
+    /**
+     * PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. A known-of
+     * stub (`known_of: true`, see isKnownOf) is a TypeError before sending, here and on every
+     * element write: a PUT of one would blank every field it does not keep.
+     */
     upsert(type: ElementType | string, id: string, element: OwElement | Record<string, unknown>): Promise<OwElement>;
     /**
      * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
@@ -4383,4 +4403,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, 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, 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

@@ -429,6 +429,7 @@ var OwV2Client = class {
    * `null` are accepted and stored as `''` (nameless Markers exist).
    */
   async create(type, element, opts = {}) {
+    refuseKnownOf(element, "create");
     const body = sanitizePayload(element);
     if (body.id === void 0 || body.id === null || body.id === "") {
       body.id = opts.idempotencyKey ? keyedId(opts.idempotencyKey, 0) : mintUuid();
@@ -439,8 +440,13 @@ var OwV2Client = class {
       idempotencyKey: opts.idempotencyKey
     });
   }
-  /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
+  /**
+   * PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. A known-of
+   * stub (`known_of: true`, see isKnownOf) is a TypeError before sending, here and on every
+   * element write: a PUT of one would blank every field it does not keep.
+   */
   async upsert(type, id, element) {
+    refuseKnownOf(element, "upsert");
     return this.request("PUT", `/${type}/${id}/`, { write: true, body: sanitizePayload(element) });
   }
   /**
@@ -454,6 +460,7 @@ var OwV2Client = class {
    * it for today's unconditional write.
    */
   async patch(type, id, partial, opts = {}) {
+    refuseKnownOf(partial, "patch");
     return this.request("PATCH", `/${type}/${id}/`, { write: true, body: sanitizePayload(partial), ifMatch: opts.ifMatch });
   }
   /**
@@ -492,6 +499,7 @@ var OwV2Client = class {
    * fresh UUIDv7. Ids you supply are kept.
    */
   async bulk(items, opts = {}) {
+    items.forEach((it, index) => refuseKnownOf(it.element, `bulk: items[${index}]`));
     const body = {
       items: items.map((it, index) => {
         const element = sanitizePayload(it.element);
@@ -1191,13 +1199,20 @@ var OwV2Client = class {
     return parsed;
   }
 };
-var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq"];
+var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq", "known_of"];
 function sanitizePayload(payload) {
   if (!payload || typeof payload !== "object") return payload;
   const rest = { ...payload };
   for (const field of READ_ONLY_FIELDS) delete rest[field];
   return rest;
 }
+function refuseKnownOf(payload, where) {
+  if (payload && typeof payload === "object" && payload.known_of === true) {
+    throw new TypeError(
+      `${where}: this body is a known-of stub (known_of: true), not the element: its empty fields are not its values, and writing it would blank them. Write from a whole copy, or send only the fields you mean to change.`
+    );
+  }
+}
 async function endAuthSession(fetchImpl, auth, session) {
   const abort = new AbortController();
   const timer = setTimeout(() => abort.abort(), 5e3);
@@ -2072,6 +2087,9 @@ var AGENT_DOORS = ["seat", "mcp", "declared"];
 function isAgentDoor(door) {
   return door != null && AGENT_DOORS.includes(door);
 }
+function isKnownOf(element) {
+  return element != null && element.known_of === true;
+}
 
 // src/v2/palette.ts
 var FAMILY_COLORS = {
@@ -3567,6 +3585,7 @@ export {
   getElementLabel,
   isAgentDoor,
   isDemoKey,
+  isKnownOf,
   isLeapYear,
   isParseError,
   kindCanWrite,

package/package.json

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