@onlyworlds/sdk 4.62.0 → 4.64.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.48** (canonical 00.33.00).
+**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.49** (canonical 00.33.00).
 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.
 
@@ -88,6 +88,8 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   §4.7 (`.owworld`): the reader checks the central directory before inflating
   and ignores files beside the world's folder; the writer's output is byte-stable (marker
   first, UTF-8 name order, 1980 stamps) and holds only `world.json` and the folder's parts.
+  Producers marked `"private": true` in `records/RECORDS.json` are left out whole unless
+  `writeWorldFile(files, topDir, { includePrivateRecords: true })` (since 4.63.0; OW-8).
 - World calendars (since 4.20.0): `worldCalendars(elements)` finds the elements carrying
   `atlas_calendar` (Atlas owns the field: read it, never write it); `resolveCalendarLens` picks
   one; `formatStep(config, step)` names a point on the world's integer time line, `parseDate`

package/CHANGELOG.md

@@ -5,6 +5,25 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.64.0] - 2026-10-23
+
+### Changed
+
+- **Every options object in the package now refuses an unknown key**, not only the client's typed methods (4.51.0 to 4.53.0): `readWorldFile`, `parseDate`, `resolveCalendarLens`, `lookupWorld`, `renderElement`, `planPhoto`, `preparePhoto`, the client's `request()` escape hatch, `listAll` (with its own keys: a `cursor` it was handed was overwritten unread), the deprecated `tokens.consume` and `new OwSignInError`'s third argument throw a `TypeError` naming the function, the key and the keys it takes, before anything is read, decoded, parsed or sent. A dropped key was never harmless: `readWorldFile(bytes, { maxbytes: 1e6 })` read with the 2 GiB budget, `parseDate(cfg, input, { Now: 12 })` parsed as if the world had no now, and W11's `list('character', { name__icontains })` read every Character and a cleanup script deleted 99 of them (2026-10-22). A plain-JavaScript caller passing a misspelt key will now see a `TypeError` where the call used to run with the default; TypeScript callers were already refused at compile time. `writeWorldFile` and `typeWord` keep their refusals on the same shared check; `typeWord`'s message now reads like the others (`typeWord: unknown option 'plural'. The keys are supertype, many.`).
+- Tests: one test calls every options parameter of the exported surface with `{ __unknown__: 1 }` and asserts a `TypeError` naming the key, nothing sent; a second reads `src/index.ts` with the TypeScript checker and fails on any exported object parameter that is neither in that list nor named as data (a calendar config, a world index, an element), so a new options object cannot ship unfenced. Watched failing on mutants of the `readWorldFile`, `parseDate`, `preparePhoto` and `request()` fences, and on an exported options function added without one.
+
+## [4.63.0] - 2026-10-23
+
+### Added
+
+- **`writeWorldFile(files, topDir, { includePrivateRecords })`**, OW-8's private clause (folder format spec v0.3.15, §4.5 rule 11 and §4.7). By default the writer now leaves out, whole, every `records/<producer>/` directory whose entry in `records/RECORDS.json` says `"private": true`, so a tool's own notes do not travel the first time a world is shared. `RECORDS.json` itself travels byte-exact, its private entries kept, so a reader can see a producer was left out. Only the boolean `true` marks a directory private (`"true"`, a string, does not). A producer's name matches its directory by the archive's one fold (NFC, then simple case folding), so a manifest's `Fold` leaves out `records/fold/` on a disk that ignores case. With `includePrivateRecords: true` every record travels as before and the manifest is not read. No manifest, nothing is private. Type `OwWriteWorldFileOptions`.
+- **A manifest the writer cannot read is refused, not guessed at**: a `RECORDS.json` that is not JSON, not an array, holds an entry that is not an object, or marks an entry private without a producer name throws a `TypeError` naming the file and the option, having written nothing, unless `includePrivateRecords: true` is passed. A world whose manifest is in an older shape now needs the option to be written. The options object refuses an unknown key, and an `includePrivateRecords` that is not a boolean, with a `TypeError`, before anything else.
+- Tests: the conformance set's four private cases, written from its `sources.private` world (each source file checked by its sha256): the default side equals `pass-OW-8-private-left-out` and the asked side `pass-OW-8-private-asked`, entry for entry, and neither is `fail-OW-8-private-partial` or `fail-OW-8-private-manifest-rewritten`. Also the string `"true"`, a producer whose name is a prefix of another's, no manifest, each unreadable manifest refused and carried when asked, and the options. Each behaviour watched failing on its own mutant.
+
+### Changed
+
+- **Schema repinned to schema-dist `v0.33.0-dist.49`** (same canonical 00.33.00; no schema file moved, no generated type changed, `ONLYWORLDS_VERSION` still `'00.33.00'`). The `.owworld` conformance set grows to 85 zips with the four OW-8 private-records writer cases on `sources.private`; none of the earlier 81 moved.
+
 ## [4.62.0] - 2026-10-22
 
 ### Added

package/README.md

@@ -285,6 +285,8 @@ Files beside the world's folder and archive junk (`__MACOSX`, `.DS_Store`) are i
 
 The writer gives the same bytes for the same files: the `mimetype` marker first, then every entry in the UTF-8 order of its name, stamped 1980-01-01 00:00. It writes `world.json`, `elements/`, `spatial/`, `media/` and `records/`, and leaves any other file out. A tool's dot-folder you hand it travels too, which makes the file a private copy rather than a portable `.owworld`.
 
+`records/` travels byte for byte, except a producer's directory that `records/RECORDS.json` marks `"private": true`: that one is left out whole, and `RECORDS.json` itself travels unchanged, so the reader can see a producer was left out. Pass `writeWorldFile(files, topDir, { includePrivateRecords: true })` to carry private records too. A `RECORDS.json` that is not a JSON array of objects is refused with a `TypeError` unless you pass that option, since the writer cannot tell which records are private.
+
 ## World calendars
 
 A world's time is an integer line (`time_range_current` is a point on it, and so is an Event's `start_date`). A calendar names its points: months, days, eras. Atlas keeps a calendar on an element (a Construct by convention) in its `atlas_calendar` field, and the SDK reads it with Atlas's own calendar code (since 4.20.0). Atlas owns that field and is its only writer; read it, never write it.

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.48** — canonical schema **00.33.00**, published 2026-10-22.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.49** — canonical schema **00.33.00**, published 2026-10-22.
 
 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.

package/dist/index.d.ts

@@ -4324,7 +4324,9 @@ declare function typeWord(world: object | null | undefined, type: string, opts?:
  * THE WRITER emits a portable copy (OW-7, OW-12, OW-13): the `mimetype` marker
  * first and stored, then only the folder's parts, every entry stamped
  * 1980-01-01 00:00, in the UTF-8 byte order of its name, JSON deflated and
- * everything else stored.
+ * everything else stored. `records/` travels whole and byte-exact, except the
+ * producers `records/RECORDS.json` marks private, left out whole unless the
+ * caller asks (OW-8, §4.5 rule 11).
  *
  * A tool's own `.<tool>/` folder is the tool's (spec §4): the reader returns
  * it like any file (a caller leaves files out with `skip`), and the writer
@@ -4369,9 +4371,17 @@ interface OwReadWorldFileOptions {
 declare function simpleCaseFold(text: string): string;
 /**
  * Read a world file. Throws `OwWorldFileError` saying why, having returned
- * nothing; the caller writes only what this returns.
+ * nothing; the caller writes only what this returns. An unknown option is a
+ * `TypeError` before the bytes are looked at.
  */
 declare function readWorldFile(bytes: Uint8Array, opts?: OwReadWorldFileOptions): OwReadWorldFile;
+interface OwWriteWorldFileOptions {
+    /**
+     * Carry the producers marked private in `records/RECORDS.json` (spec §4.5
+     * rule 11, OW-8). Left out or false, their directories are left out whole.
+     */
+    includePrivateRecords?: boolean;
+}
 /**
  * Write a world file under one top-level folder `topDir`: the `mimetype`
  * marker first and stored, then `world.json` (without `api`) and the folder's
@@ -4379,12 +4389,26 @@ declare function readWorldFile(bytes: Uint8Array, opts?: OwReadWorldFileOptions)
  * deflated and everything else stored (spec §4.7, OW-6, OW-7, OW-12, OW-13).
  * Any other file is left out. A tool's dot-folder in `files` travels, and
  * makes the result a private copy, not a portable `.owworld` (OW-7): leave it
- * out of `files` for a portable one. Refuses (`OwWorldFileError`) an unsafe
- * path or `topDir`, a duplicate path, a name some disk cannot hold, two names
- * that fold to one, and a world.json that is missing, will not parse (it may
- * hold a key, so it is never zipped raw) or has no `id`.
+ * out of `files` for a portable one.
+ *
+ * `records/` travels byte-exact, except private records (OW-8, spec §4.5 rule
+ * 11): every `records/<producer>/` whose entry in `records/RECORDS.json` says
+ * `"private": true` (the boolean; `"true"` is not private; the name matched by
+ * OW-18's fold, so `Fold` names `records/fold/`) is left out whole,
+ * and `RECORDS.json` itself travels byte-exact, its private entries kept, so a
+ * reader learns a producer was left out. Pass `{ includePrivateRecords: true }`
+ * to carry them; then the manifest is not read and every record travels. No
+ * manifest, nothing is private.
+ *
+ * Throws a `TypeError`, having written nothing, for an unknown option, an
+ * `includePrivateRecords` that is not a boolean, and (unless private records
+ * are asked for) a `RECORDS.json` that is not a JSON array of objects or that
+ * marks an entry private without a producer name. Refuses (`OwWorldFileError`)
+ * an unsafe path or `topDir`, a duplicate path, a name some disk cannot hold,
+ * two names that fold to one, and a world.json that is missing, will not parse
+ * (it may hold a key, so it is never zipped raw) or has no `id`.
  */
-declare function writeWorldFile(files: OwWorldFileEntry[], topDir: string): Uint8Array;
+declare function writeWorldFile(files: OwWorldFileEntry[], topDir: string, opts?: OwWriteWorldFileOptions): Uint8Array;
 
 /**
  * World lookup: find the elements a plain-language question is about, in a
@@ -4512,13 +4536,13 @@ declare function buildWorldIndex<T extends OwLookupElement>(elements: Iterable<T
  * elements whose other text holds the question's words. An empty question
  * returns no hits.
  */
-declare function lookupWorld<T extends OwLookupElement>(index: OwWorldIndex<T>, question: string, { limit }?: OwLookupOptions): OwLookupHit<T>[];
+declare function lookupWorld<T extends OwLookupElement>(index: OwWorldIndex<T>, question: string, opts?: OwLookupOptions): OwLookupHit<T>[];
 /**
  * A compact text card for one element, for a person or a model: name, type,
  * kind, description, its fields, its links by name (or how many point outside
  * the data), and what links to it.
  */
-declare function renderElement<T extends OwLookupElement>(element: T, index: OwWorldIndex<T>, { descMax, linkMax, incomingMax }?: OwRenderOptions): string;
+declare function renderElement<T extends OwLookupElement>(element: T, index: OwWorldIndex<T>, opts?: OwRenderOptions): string;
 
 /**
  * Context for keel's AI proxy (POST /api/v2/account/ask, Keel #159): the elements a
@@ -4618,9 +4642,9 @@ declare function planPhoto(source: {
     type: string;
 }, opts?: OwPhotoOptions): OwPhotoPlan;
 /**
- * Shrink and convert a picture for upload. Throws `TypeError` outside a
- * browser, for a file the browser cannot decode, or when the result is still
- * over `maxBytes`.
+ * Shrink and convert a picture for upload. Throws `TypeError` for an unknown
+ * option (before anything is decoded), outside a browser, for a file the
+ * browser cannot decode, or when the result is still over `maxBytes`.
  */
 declare function preparePhoto(input: Blob, opts?: OwPhotoOptions): Promise<OwPreparedPhoto>;
 
@@ -4885,7 +4909,8 @@ declare function worldCalendars(elements: Iterable<OwCalendarElement>): WorldCal
  *
  * `fallbackToOnly`: when no calendar was ever chosen (`activeId` is `undefined`, not
  * `null`) and the world holds exactly one, use it. `null` is an explicit "no calendar" and
- * stays null. With several calendars and no choice, nothing is guessed.
+ * stays null. With several calendars and no choice, nothing is guessed. An unknown option is a
+ * TypeError (the caller's bug, not the world's data).
  */
 declare function resolveCalendarLens(elements: Iterable<OwCalendarElement>, activeId: string | null | undefined, opts?: {
     fallbackToOnly?: boolean;
@@ -5195,4 +5220,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 OwAccountWorld, 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 OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwHiddenRow, 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, type OwMintedKey, type OwNamesMap, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldProposalQuery, type OwWorldPublicPage, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, 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, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, 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 OwAccountWorld, 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 OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwHiddenRow, 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, type OwMintedKey, type OwNamesMap, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldProposalQuery, type OwWorldPublicPage, type OwWriteDoor, type OwWriteWorldFileOptions, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, 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, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -56,6 +56,19 @@ function keyedId(idempotencyKey, index) {
 ${index}`);
 }
 
+// src/options.ts
+function unknownKey(opts, keys) {
+  if (!opts || typeof opts !== "object") return void 0;
+  for (const k of Object.keys(opts)) if (!keys.includes(k)) return k;
+  return void 0;
+}
+function refuseUnknownOptions(fn, opts, keys, after = "") {
+  const k = unknownKey(opts, keys);
+  if (k !== void 0) {
+    throw new TypeError(`${fn}: unknown option '${k}'. The keys are ${keys.join(", ")}.${after ? ` ${after}` : ""}`);
+  }
+}
+
 // src/v2/errors.ts
 var OwApiError = class extends Error {
   constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
@@ -342,6 +355,7 @@ var OwNetworkError = class extends Error {
 };
 var OwSignInError = class extends Error {
   constructor(reason, message, opts = {}) {
+    refuseUnknownOptions("OwSignInError", opts, ["status", "code", "retryAfter"]);
     super(message);
     this.name = "OwSignInError";
     this.reason = reason;
@@ -652,7 +666,7 @@ var OwV2Client = class {
   // -- Element CRUD --------------------------------------------------------
   /** GET /{type}/ -- one cursor page. */
   async list(type, params = {}) {
-    only("list", params, LIST_PARAM_KEYS, "A wire filter (name, name__icontains, supertype, subtype, characters) goes under filter: { ... }.");
+    only("list", params, LIST_PARAM_KEYS, LIST_FILTER_HINT);
     const query = buildQuery({
       limit: params.limit ?? this.pageSize,
       cursor: params.cursor,
@@ -691,6 +705,7 @@ var OwV2Client = class {
   }
   /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
   async *listAll(type, params = {}) {
+    only("listAll", params, LIST_ALL_PARAM_KEYS, LIST_FILTER_HINT);
     let cursor;
     do {
       const page = await this.list(type, { ...params, cursor });
@@ -1718,6 +1733,7 @@ var OwV2Client = class {
    * sanitizePayload — callers own their body shape.
    */
   async request(method, path, opts = {}) {
+    only("request", opts, REQUEST_OPTION_KEYS);
     if (opts.ifMatch !== void 0 && !(Number.isInteger(opts.ifMatch) && opts.ifMatch >= 0)) {
       throw new TypeError(`ifMatch must be a whole number (an element's change_seq), got ${String(opts.ifMatch)}`);
     }
@@ -1930,12 +1946,26 @@ function objectKey(keyOrUrl) {
   return decodeURIComponent(new URL(keyOrUrl).pathname.replace(/^\/+/, ""));
 }
 var LIST_PARAM_KEYS = ["limit", "cursor", "ids", "createdBy", "expand", "fields", "filter", "viewAs"];
+var LIST_ALL_PARAM_KEYS = LIST_PARAM_KEYS.filter((k) => k !== "cursor");
+var LIST_FILTER_HINT = "A wire filter (name, name__icontains, supertype, subtype, characters) goes under filter: { ... }.";
+var REQUEST_OPTION_KEYS = [
+  "query",
+  "body",
+  "idempotencyKey",
+  "auth",
+  "allowEmpty",
+  "replayAware",
+  "write",
+  "elementWrite",
+  "proposable",
+  "ifMatch",
+  "ifNoneMatch",
+  "onEtag"
+];
 function only(method, obj, keys, hint = "") {
-  if (!obj || typeof obj !== "object") return;
-  for (const k of Object.keys(obj)) {
-    if (!keys.includes(k)) {
-      throw new TypeError(`${method}: unknown parameter '${k}'. ${hint ? hint + " " : ""}The keys are ${keys.join(", ")}. Nothing was sent.`);
-    }
+  const k = unknownKey(obj, keys);
+  if (k !== void 0) {
+    throw new TypeError(`${method}: unknown parameter '${k}'. ${hint ? hint + " " : ""}The keys are ${keys.join(", ")}. Nothing was sent.`);
   }
 }
 var CLIENT_CONFIG_KEYS = ["apiKey", "apiPin", "baseUrl", "pageSize", "changesPageSize", "fetch", "agent", "client"];
@@ -2884,6 +2914,7 @@ var OwWorldFileError = class extends Error {
     this.reason = reason;
   }
 };
+var READ_OPTION_KEYS = ["maxBytes", "maxEntries", "skip"];
 var refuse = (reason, message) => {
   throw new OwWorldFileError(reason, message);
 };
@@ -3163,6 +3194,7 @@ function checkFileAndFolder(files) {
   }
 }
 function readWorldFile(bytes, opts = {}) {
+  refuseUnknownOptions("readWorldFile", opts, READ_OPTION_KEYS, "Nothing was read.");
   const maxBytes = opts.maxBytes ?? WORLD_FILE_MAX_BYTES;
   const maxEntries = opts.maxEntries ?? WORLD_FILE_MAX_ENTRIES;
   const entries = centralDirectory(bytes);
@@ -3249,7 +3281,43 @@ function carried(path) {
   return !segs.some((s) => s.startsWith(".")) && !path.endsWith(".meta");
 }
 var STAMP = new Date(1980, 0, 1, 0, 0, 0);
-function writeWorldFile(files, topDir) {
+var WRITE_OPTION_KEYS = ["includePrivateRecords"];
+var RECORDS_MANIFEST = "records/RECORDS.json";
+function asksPrivate(opts) {
+  if (opts === void 0 || opts === null) return false;
+  if (typeof opts !== "object") throw new TypeError(`writeWorldFile: options must be an object, such as { includePrivateRecords: true }. Nothing was written.`);
+  refuseUnknownOptions("writeWorldFile", opts, WRITE_OPTION_KEYS, "Nothing was written.");
+  const asked = opts.includePrivateRecords;
+  if (asked !== void 0 && typeof asked !== "boolean") {
+    throw new TypeError(`writeWorldFile: includePrivateRecords must be true or false; got ${JSON.stringify(asked) ?? String(asked)}. Nothing was written.`);
+  }
+  return asked === true;
+}
+function privateProducers(files) {
+  const manifest = files.find((f) => f.path === RECORDS_MANIFEST);
+  if (!manifest) return [];
+  const unreadable = (why) => {
+    throw new TypeError(`writeWorldFile: ${RECORDS_MANIFEST} ${why}, so which records are private cannot be read and none is left out by guess (spec \xA74.7, OW-8). Fix the manifest, or pass { includePrivateRecords: true } to carry every record. Nothing was written.`);
+  };
+  let doc;
+  try {
+    doc = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(manifest.data));
+  } catch {
+    unreadable("is not JSON");
+  }
+  if (!Array.isArray(doc)) unreadable("is not a JSON array of entries");
+  const out = [];
+  for (const entry of doc) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) unreadable("holds an entry that is not an object");
+    const { producer, private: isPrivate } = entry;
+    if (isPrivate !== true) continue;
+    if (typeof producer !== "string" || producer === "") unreadable("marks an entry private without a producer name");
+    out.push(producer);
+  }
+  return out;
+}
+function writeWorldFile(files, topDir, opts = {}) {
+  const includePrivate = asksPrivate(opts);
   if (pathFault(topDir) || topDir.includes("/")) throw new OwWorldFileError("unsafe_path");
   const seen = /* @__PURE__ */ new Set();
   for (const f of files) {
@@ -3257,7 +3325,12 @@ function writeWorldFile(files, topDir) {
     if (seen.has(f.path)) throw new OwWorldFileError("unsafe_path", `The path ${f.path} is listed twice.`);
     seen.add(f.path);
   }
-  const kept = files.filter((f) => carried(f.path));
+  const left = new Set(includePrivate ? [] : privateProducers(files).map(foldName));
+  const inPrivate = (path) => {
+    const segs = path.split("/");
+    return segs.length > 2 && segs[0] === "records" && left.has(foldName(segs[1]));
+  };
+  const kept = files.filter((f) => carried(f.path) && !inPrivate(f.path));
   if (!kept.some((f) => f.path === WORLD_FILE)) throw new OwWorldFileError("not_a_world");
   const keys = kept.map((f) => `${topDir}/${f.path}`);
   for (const key of keys) {
@@ -3324,7 +3397,7 @@ function isRoomElement(el) {
 
 // src/names.ts
 var SLUGS = new Set(ELEMENT_TYPES);
-var OPTION_KEYS = /* @__PURE__ */ new Set(["supertype", "many"]);
+var OPTION_KEYS = ["supertype", "many"];
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function word(pair, many) {
   if (!isObject(pair) || typeof pair.one !== "string") return null;
@@ -3335,9 +3408,7 @@ function word(pair, many) {
   return plural === "" ? one : plural;
 }
 function typeWord(world, type, opts = {}) {
-  for (const key of Object.keys(opts ?? {})) {
-    if (!OPTION_KEYS.has(key)) throw new TypeError(`typeWord: unknown option "${key}" (known: supertype, many)`);
-  }
+  refuseUnknownOptions("typeWord", opts, OPTION_KEYS);
   const map = world?.x_names;
   if (!isObject(map) || map.version !== 1) return null;
   const { types, supertypes } = map;
@@ -3360,6 +3431,8 @@ function typeWord(world, type, opts = {}) {
 }
 
 // src/lookup.ts
+var LOOKUP_OPTION_KEYS = ["limit"];
+var RENDER_OPTION_KEYS = ["descMax", "linkMax", "incomingMax"];
 var STOP = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -3663,7 +3736,9 @@ function similarWords(w, vocab) {
   }
   return res;
 }
-function lookupWorld(index, question, { limit = 8 } = {}) {
+function lookupWorld(index, question, opts = {}) {
+  refuseUnknownOptions("lookupWorld", opts, LOOKUP_OPTION_KEYS);
+  const { limit = 8 } = opts;
   const seeds = 12;
   const q = words(normalize(question));
   const qSet = new Set(q);
@@ -3780,7 +3855,9 @@ function lookupWorld(index, question, { limit = 8 } = {}) {
   for (const [id, c] of cand) if (SPATIAL.has(index.byId.get(id).type)) c.score *= 0.85;
   return [...cand.entries()].map(([id, c]) => ({ element: index.byId.get(id), score: Math.round(c.score * 10) / 10, reasons: c.reasons })).sort((a, b) => b.score - a.score || String(a.element.name).length - String(b.element.name).length || (a.element.id < b.element.id ? -1 : 1)).slice(0, limit);
 }
-function renderElement(element, index, { descMax = 500, linkMax = 12, incomingMax = 10 } = {}) {
+function renderElement(element, index, opts = {}) {
+  refuseUnknownOptions("renderElement", opts, RENDER_OPTION_KEYS);
+  const { descMax = 500, linkMax = 12, incomingMax = 10 } = opts;
   const el = element;
   const name = (id) => index.byId.get(id)?.name ?? "?";
   const kind = [el.supertype, el.subtype].filter((x) => x && x !== "undefined").join(" / ");
@@ -3864,7 +3941,9 @@ function buildAskContext(items, index) {
 // src/photo.ts
 var PHOTO_TYPES = ["image/webp", "image/png", "image/jpeg", "image/avif"];
 var PHOTO_MAX_BYTES = 15 * 1024 * 1024;
+var PHOTO_OPTION_KEYS = ["maxSide", "quality", "maxBytes"];
 function planPhoto(source, opts = {}) {
+  refuseUnknownOptions("planPhoto", opts, PHOTO_OPTION_KEYS);
   const maxSide = opts.maxSide ?? 2048;
   if (!(maxSide > 0)) throw new TypeError("preparePhoto: maxSide must be a positive number");
   if (!(source.width > 0 && source.height > 0)) throw new TypeError("preparePhoto: the picture has no size");
@@ -3889,6 +3968,7 @@ function makeCanvas(width, height) {
   throw new TypeError("preparePhoto needs a browser: no canvas here");
 }
 async function preparePhoto(input, opts = {}) {
+  refuseUnknownOptions("preparePhoto", opts, PHOTO_OPTION_KEYS);
   const quality = opts.quality ?? 0.82;
   const maxBytes = opts.maxBytes ?? PHOTO_MAX_BYTES;
   const decode = globalThis.createImageBitmap;
@@ -4227,6 +4307,7 @@ function formatMidLabel(cfg, step) {
   if (b.monthName != null && b.day != null) return `${b.day} ${b.monthName} ${b.year}`;
   return formatYearLabel(cfg, step);
 }
+var PARSE_OPTION_KEYS = ["now"];
 function absYearForEraYear(cfg, era, Y) {
   if (era.restart === false) return Y;
   const base = era.year_base ?? 1;
@@ -4245,6 +4326,7 @@ function defaultEra(cfg, now) {
   return [...pool].sort((a, b) => b.start - a.start)[0];
 }
 function parseDate(cfg, input, opts = {}) {
+  refuseUnknownOptions("parseDate", opts, PARSE_OPTION_KEYS);
   const raw = input.trim();
   if (raw === "") return { error: "empty date" };
   if (/^-?\d+$/.test(raw)) return { step: parseInt(raw, 10) };
@@ -4375,6 +4457,7 @@ function worldCalendars(elements) {
   return out;
 }
 function resolveCalendarLens(elements, activeId, opts) {
+  refuseUnknownOptions("resolveCalendarLens", opts, ["fallbackToOnly"]);
   if (activeId === void 0 && opts?.fallbackToOnly) {
     const all = worldCalendars(elements);
     return all.length === 1 ? all[0] : null;
@@ -4454,6 +4537,7 @@ var TokenResource = class {
    * ```
    */
   async consume(params) {
+    refuseUnknownOptions("consume", params, ["amount", "service", "sessionId", "metadata"], "Nothing was sent.");
     return this.req("POST", "/tokens/consume/", {
       body: {
         amount: params.amount,

package/package.json

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