@onlyworlds/sdk 4.71.0 → 4.72.1

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.57** (canonical 00.33.00).
+**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.59** (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.
 
@@ -56,6 +56,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   account's daily token rating (`tokens_remaining`, `token_rating`; `remaining` counts answers of
   this size still in it); used up → `err.isQuotaExceeded`. `isAskUnavailable`, `isAskFailed`
   count nothing. Custom fields (`x_*`) are in the lookup and the context; `atlas_*` is not.
+  Since 4.72.0 `buildAskContext` leaves proposed (`x_review_proposed` not absent or null), hidden
+  (`hidden` not absent, null or false) and room elements out unless asked
+  (`{ includeProposed, includeHidden, includeRoom }`), lists their ids in `leftOut.proposed`,
+  `.hidden`, `.room` (hidden and proposed: under `hidden` only), and labels a proposed element it
+  sends `[proposed, not yet reviewed]` on its first line; say how many were held back.
 - Sort (since 4.18.0, account token): `account.sort({ worldId, notes, slice })` turns unsorted
   notes (text, or a picture already uploaded into the world) into rows to review: `make`,
   `add_to`, `link`, `ask`, plus `not_proposed` with reasons. Ids come only from your `slice`

package/CHANGELOG.md

@@ -5,6 +5,30 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.72.1] - 2026-10-24
+
+### Fixed
+
+- **`readWorldFile` refuses a deflate stream that ends before its entry's declared compressed size** (folder spec §4.7, OW-14, its size bullet; ruled 2026-10-24, published at schema-dist serial 58). The size bullet speaks of every size an entry declares, the compressed one too. fflate stopped at the stream's end and ignored the bytes after it, so an entry whose stream ended four bytes early, those bytes junk and its sizes and CRC honest, was read (`fail-OW-14-deflate-early-end`); it is now `not_openable`. fflate never says where a stream ended, so each deflated entry is inflated twice: once whole, as before, then again short of its last byte (in 64 KiB chunks past that size, the output dropped), where a stream that ends at its declared size runs out and fflate refuses it, and one that ends sooner still inflates. A stream that never ends (`fail-OW-14-deflate-no-end`) was already refused, as `not_openable`. A world file whose streams end where their entries say reads as before.
+- Tests: the whole `.owworld` set, 96 cases, through the reader, the count floor 96; built streams with 1 and 4 junk bytes after their end, short and past 64 KiB, refused, and the same streams with nothing after them read. The three zips the fix was tested on before the serial was vendored (`test/fixtures/owworld-next/`) are gone: the set carries them.
+
+### Changed
+
+- **Schema repinned to schema-dist `v0.33.0-dist.59`** (commit a40a5f3; same canonical 00.33.00; no schema file moved, `schema.json` and `presentation.json` unchanged, no generated type changed, `ONLYWORLDS_VERSION` still `'00.33.00'`; generated output moves only its source header and SCHEMA.md's line). Serials 58 and 59 together bring what follows; 59's own change is text only (the set's generator and verdicts regenerated with the same 96 zips byte for byte, and the profile pages, the checks fixture's note and the folder lint say when a rule was ruled). The `.owworld` set at 96 zips: the two deflate cases above, and `pass-OW-18-nfc-unassigned`, U+11383 beside U+11382 U+113C9, two names at Unicode 15.1, which 4.71.0's `nfc` already keeps apart; none of the earlier 93 zips moved. The spine profile's serial-58 sentences: `x_spine_owner` the keeping seat's name, the projection's World mark `x_spine_projection`, the audit's one Seat and folded-name uniqueness, the Retirement Event's typed link. The dist's README, LICENSE and SECURITY.md, written by its publisher.
+
+## [4.72.0] - 2026-10-24
+
+### Changed
+
+- **`buildAskContext` now leaves proposed, hidden and room elements out of the context unless asked.** A caller that passes such elements gets fewer items in `context` and `kept` than before: an element whose `x_review_proposed` is anything but absent or null (the review profile, rules 1 and 4: a value that is not a proper mark is a doubt and counts as proposed), one whose `hidden` is anything but absent, null or false (folder format §4.8, the same test as `writeWorldFile`'s `includeHidden`), and a room element (`isRoomElement`, the room profile, rules 1 and 4) are not sent. Their ids come back in the new `leftOut: { proposed, hidden, room }`, in the order given, so a tool can say how many it held back. An element carrying more than one mark is listed once, in the first of hidden, proposed, room whose option is off: a hidden proposed element is under `hidden`, so `includeProposed` alone never sends it. A sent element's link to an element a mark leaves out, anywhere in the index, reads as "not present in the world data", never by its name. `dropped` keeps its meaning (the 8 items and the 12,000 characters), counted over what remains. Until now the SDK relied on the caller (Lantern) to filter first; the rules bind the exported function itself.
+
+### Added
+
+- **`buildAskContext(items, index, { includeProposed, includeHidden, includeRoom })`**, each default false: true sends that kind again. A proposed element sent carries the review profile's label on its first line, `[proposed, not yet reviewed] Name (type)`, where the AI reading the text sees it. An option that is not a boolean is a TypeError, and an unknown key is refused by name (the options fence, `test/options.test.mjs`). Types `OwAskContextOptions` and `OwAskLeftOut`.
+- **`REVIEW_PROPOSED_LABEL`** (`'proposed, not yet reviewed'`), generated into `types.generated.ts` from rule 1's own sentence in the vendored `profiles/review.md` ("labels each one it keeps **"…"**"); codegen exits 1 if the sentence is missing or occurs twice.
+- **`minted_by: string | null` on `OwWorldLink` and `OwCreatedWorldLink`** (keel PR 215): the membership (its id in GET /api/v2/members) of the co-builder who minted the link over POST /api/v2/links; null for a link the owner made. Served by `createWorldLink` and `listWorldLinks`. No client for `/api/v2/links` itself yet.
+- Tests: each mark left out by default and listed; `hidden` as §4.8 reads it (`"true"` and 1 out, false and null in); a doubt (`"yes"`, `{}`) treated as proposed and labelled when asked, a cleared `null` settled; each `include*` bringing back its own kind only; the label on the first line; a hidden proposed element counted once, under hidden; a kept element's links to a hidden element and from a room element read without their names; the limits over what remains; the fence and the boolean check. Ten mutants, each red on its own test: no proposed filter, no hidden filter, no room filter, no label, a doubt not proposed, proposed checked before hidden, left-out elements counted toward the total, no link view, no option fence, no boolean check.
+
 ## [4.71.0] - 2026-10-24
 
 ### Added

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024-2025 OnlyWorlds
+Copyright (c) 2021-2026 Titus Oosting
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,6 +5,8 @@
 
 OnlyWorlds is an open standard for worldbuilding data: 22 element types (characters, locations, events, laws and the rest) that any tool can read and write. This is a typed client for its API, with the schema's constants (element types, icons, colour families, field metadata) generated from the published [schema distribution](https://github.com/OnlyWorlds/schema-dist). It runs in Node 18+ and in the browser through a bundler (ESM only).
 
+**Who writes this repository.** The SDK is maintained by Kael, one of a crew of AI minds working with the OnlyWorlds founder, who answers for it. Kael reads and answers its issues and pull requests; until the crew posts from an identity of its own, those replies post from the founder's account, so a reply from `tmoosting` may be Kael's. `CHANGELOG.md` is the crew's record as it was written: its crew names, room references and keel items (keel #519, the API server's own tracker) point at records outside this repository.
+
 ## Install
 
 ```bash
@@ -247,11 +249,13 @@ To have an answer written from what you found, OnlyWorlds runs a small AI proxy
 
 ```typescript
 const shown = hits.slice(0, 8);                          // what your screen lists
-const { context, kept } = buildAskContext(shown, index); // within the proxy's limits; kept = what was sent
+const { context, kept, leftOut } = buildAskContext(shown, index); // within the proxy's limits; kept = what was sent
 const reply = await account.ask({ worldId, question, context }); // account: a client with an ow_a_ token
 reply.answer;                                            // from those elements only, or "The world doesn't say."
 ```
 
+`buildAskContext` hands world elements to an AI, so it leaves three kinds out unless you ask (since 4.72.0): elements marked proposed (`x_review_proposed` anything but absent or null), elements marked hidden (`hidden` anything but absent, null or false) and room elements (`isRoomElement`). Their ids come back in `leftOut.proposed`, `leftOut.hidden` and `leftOut.room`, so you can say how many were held back; an element both hidden and proposed is listed under `hidden` only. Pass `{ includeProposed: true }`, `{ includeHidden: true }` or `{ includeRoom: true }` to send them; a proposed element sent carries `[proposed, not yet reviewed]` (`REVIEW_PROPOSED_LABEL`) on its first line. A sent element's link to one left out reads as not present, never by its name. `dropped` stays the proxy's limits: past the 8th, or past the 12,000 characters, counted over what remains.
+
 The same proxy sorts loose notes into changes for the user to review. Send the elements your own lookup found for them as the `slice`; every id in a row comes from it, and nothing is written until your app applies what the user accepts.
 
 ```typescript
@@ -398,6 +402,6 @@ Use this SDK for known operations in your own code (CRUD, sync, bulk). To let an
 
 [Docs](https://onlyworlds.github.io/docs/development/typescript) · [Games](https://onlyworlds.github.io/docs/development/games) · [API reference](https://www.onlyworlds.com/api/docs) · [Issues](https://github.com/OnlyWorlds/sdk/issues) · [Changelog](CHANGELOG.md)
 
-## License
+## Licence and contributions
 
-MIT
+The code is MIT (`LICENSE`). Issues are welcome: a bug, a wrong word, a thing you could not do. Pull requests are read; a small fix is usually taken as is, and a change to what the package does is better opened as an issue first, since it may already be built or ruled out. A reply can take a few days. A vulnerability goes privately, never in an issue: `SECURITY.md`.

package/SCHEMA.md

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

@@ -102,6 +102,12 @@ declare const ROOM_PAIRS: ReadonlyArray<{
     readonly type: ElementType;
     readonly supertype: string;
 }>;
+/** The review profile's label (schema-dist `profiles/review.md`, rule 1): the words a reader that
+ *  hands a world on (a context for an AI, a pack, a share) puts on each proposed element it keeps,
+ *  one whose `x_review_proposed` is anything but absent or null (a doubt, rule 4, included).
+ *  buildAskContext writes it on the element's first line. Source: rule 1's own sentence, read at
+ *  codegen. */
+declare const REVIEW_PROPOSED_LABEL: "proposed, not yet reviewed";
 /** Field type definitions for OnlyWorlds elements. */
 type FieldType = 'text' | 'integer'
 /**
@@ -2635,6 +2641,8 @@ interface OwWorldLink {
     uses: number;
     /** A table is `pending` while `uses < max_uses` (and neither revoked nor expired), `used` once full. */
     status: 'pending' | 'used' | 'revoked' | 'expired';
+    /** The membership (its id in GET /api/v2/members) of the co-builder who minted the link over POST /api/v2/links; null for a link the owner made (keel PR 215). */
+    minted_by: string | null;
     /** Whether the link shows the world's name and picture when it is pasted into a chat (keel #422): then the link is `/join/<world_id>#<code>`, else `/join#<code>`. Never on an agent link. */
     preview?: boolean;
     /** A player link only: the Character the player reads as; null while a link for a fresh Character is unused, and always null on a table. `name` is null if that Character was deleted (the redeem then makes a fresh one). */
@@ -4285,7 +4293,7 @@ declare class OwV2Client {
     /**
      * POST /account/ask -- a question about a world the account owns or is in, answered by
      * keel's AI proxy from `context` only (build it with buildAskContext from the elements
-     * the user sees). The answer is "The world doesn't say." when the context does not hold
+     * the user sees; it leaves proposed, hidden and room elements out unless asked). The answer is "The world doesn't say." when the context does not hold
      * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
      * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's token rating used up for the day;
      * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
@@ -4814,11 +4822,20 @@ declare function renderElement<T extends OwLookupElement>(element: T, index: OwW
  * the answer's sources are what the user saw, never a second lookup's.
  *
  *   const hits = lookupWorld(index, question).slice(0, 8);   // what the screen lists
- *   const { context, kept } = buildAskContext(hits, index);
+ *   const { context, kept, leftOut } = buildAskContext(hits, index);
  *   const reply = await account.ask({ worldId, question, context });
  *
+ * It is a reader that hands a world on, so three published rules hold here, not only in
+ * the caller: an element marked proposed (the review profile, rules 1 and 4: any
+ * `x_review_proposed` but absent or null, a doubt included), one marked hidden (folder
+ * format §4.8: a `hidden` but absent, null or false) and a room element (the room
+ * profile, rules 1 and 4: `isRoomElement`) are left out unless asked for, and listed in
+ * `leftOut`. A kept proposed element carries REVIEW_PROPOSED_LABEL on its first line. A
+ * kept element's link to one left out reads as not present, never by its name.
+ *
  * The limits are keel's (accounts/ask.py), counted the way keel counts (characters,
- * not UTF-16 units): at most 8 items, 2,000 characters each, 12,000 in all.
+ * not UTF-16 units): at most 8 items, 2,000 characters each, 12,000 in all. They apply
+ * to what remains after the three rules.
  */
 
 /** keel's limits on one ask. */
@@ -4828,23 +4845,56 @@ declare const ASK_LIMITS: {
     readonly itemMax: 2000;
     readonly totalMax: 12000;
 };
+interface OwAskContextOptions {
+    /**
+     * Send proposed elements: those whose `x_review_proposed` is anything but absent or null
+     * (the review profile; a value that is not a proper mark is a doubt, rule 4, and counts as
+     * proposed). Each one sent carries REVIEW_PROPOSED_LABEL on its first line. Default false:
+     * left out and listed in `leftOut.proposed`.
+     */
+    includeProposed?: boolean;
+    /**
+     * Send elements marked hidden: a `hidden` that is anything but absent, null or false (folder
+     * format §4.8, the same test as writeWorldFile's `includeHidden`). Default false: left out and
+     * listed in `leftOut.hidden`.
+     */
+    includeHidden?: boolean;
+    /** Send room elements (`isRoomElement`, the room profile). Default false: left out and listed in `leftOut.room`. */
+    includeRoom?: boolean;
+}
+/** Ids left out by a mark, in the order given. An element carrying several marks is listed once, in the first of hidden, proposed, room whose `include*` is off. */
+interface OwAskLeftOut {
+    proposed: string[];
+    hidden: string[];
+    room: string[];
+}
 interface OwAskContext {
     /** The texts to send as `context`, in the order given. */
     context: string[];
     /** Ids of the elements sent, in order (one per `context` item). */
     kept: string[];
-    /** Ids of the elements left out: past the 8th, or from the first one the 12,000 total could not hold. */
+    /** Ids of the elements the limits left out: past the 8th, or from the first one the 12,000 total could not hold. Never an element `leftOut` holds. */
     dropped: string[];
     /** Ids among `kept` whose text was cut to 2,000 characters. */
     truncated: string[];
+    /** Ids of the elements a mark left out (proposed, hidden, room), before the limits were counted. */
+    leftOut: OwAskLeftOut;
 }
 /**
  * Turn the elements on screen into the proxy's `context`. Takes lookup hits or plain
- * elements, keeps their order, renders each with `renderElement`, cuts a text over
- * 2,000 characters, and stops at the 8th or at the first one the 12,000 total cannot
- * hold, so what is sent is always the top of the list as shown.
+ * elements and keeps their order. First the three marks: an element marked hidden
+ * (§4.8), proposed (the review profile, a doubt included) or a room element (the room
+ * profile) is left out unless its `include*` option is true, and its id goes to
+ * `leftOut` (one bucket each, in the order hidden, proposed, room: a hidden proposed
+ * element is listed under `hidden` only, since the owner's hide is the stronger
+ * withholding and `includeProposed` alone never sends it). Then each remaining element
+ * is rendered with `renderElement` (a proposed one with REVIEW_PROPOSED_LABEL on its
+ * first line; a link to an element a mark leaves out, anywhere in the index, reads as
+ * not present), a text over 2,000 characters is cut, and the list stops at the 8th or
+ * at the first the 12,000 total cannot hold, so what is sent is always the top of the
+ * list as shown. An unknown option, or one that is not a boolean, is a TypeError.
  */
-declare function buildAskContext<T extends OwLookupElement>(items: Array<OwLookupHit<T> | T>, index: OwWorldIndex<T>): OwAskContext;
+declare function buildAskContext<T extends OwLookupElement>(items: Array<OwLookupHit<T> | T>, index: OwWorldIndex<T>, opts?: OwAskContextOptions): OwAskContext;
 
 /**
  * Photo preparation: make a picture from a phone's camera or files ready for
@@ -5483,4 +5533,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 OwCreateAccountWorldInput, type OwCreatedAccountWorld, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtCompact, 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 OwProposedNewElement, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwReviewInput, type OwReviewed, 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 OwWorldOrigin, type OwWorldProducer, type OwWorldProposalList, type OwWorldProposalQuery, type OwWorldProposalRow, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, type OwWriteWorldFileReport, 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, nfc, 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 OwAskContextOptions, type OwAskLeftOut, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreateAccountWorldInput, type OwCreatedAccountWorld, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtCompact, 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 OwProposedNewElement, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwReviewInput, type OwReviewed, 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 OwWorldOrigin, type OwWorldProducer, type OwWorldProposalList, type OwWorldProposalQuery, type OwWorldProposalRow, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, type OwWriteWorldFileReport, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, REVIEW_PROPOSED_LABEL, 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, nfc, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -1746,7 +1746,7 @@ var OwV2Client = class {
   /**
    * POST /account/ask -- a question about a world the account owns or is in, answered by
    * keel's AI proxy from `context` only (build it with buildAskContext from the elements
-   * the user sees). The answer is "The world doesn't say." when the context does not hold
+   * the user sees; it leaves proposed, hidden and room elements out unless asked). The answer is "The world doesn't say." when the context does not hold
    * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
    * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's token rating used up for the day;
    * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
@@ -2244,6 +2244,7 @@ var ROOM_PAIRS = [
   { type: "character", supertype: "Member" }
 ];
 var ROOM_MARK = "x_room_of";
+var REVIEW_PROPOSED_LABEL = "proposed, not yet reviewed";
 var FIELD_SCHEMA = {
   ability: {
     // Base fields (shared by all elements)
@@ -3277,6 +3278,24 @@ function crc32(data) {
   return (c ^ -1) >>> 0;
 }
 var CHUNK = 64 * 1024;
+function endsEarly(payload) {
+  const short = payload.subarray(0, payload.length - 1);
+  try {
+    if (short.length <= CHUNK) {
+      inflateSync(short);
+    } else {
+      const inf = new Inflate(() => {
+      });
+      for (let i = 0; i < short.length; i += CHUNK) {
+        const stop = Math.min(i + CHUNK, short.length);
+        inf.push(short.subarray(i, stop), stop === short.length);
+      }
+    }
+  } catch {
+    return false;
+  }
+  return true;
+}
 function inflateEntry(bytes, e) {
   const off = e.offset;
   if (off + 30 > bytes.length || u32(bytes, off) !== SIG_LOCAL) refuse("not_openable", `${e.name}: no local header at its offset.`);
@@ -3315,6 +3334,9 @@ function inflateEntry(bytes, e) {
   }
   if (data.length > e.usize) refuse("too_big", `${e.name} holds more than the ${e.usize} bytes it declares.`);
   if (data.length !== e.usize) refuse("not_openable", `${e.name} holds ${data.length} bytes and declares ${e.usize}.`);
+  if (e.method !== 0 && payload.length > 0 && endsEarly(payload)) {
+    refuse("not_openable", `${e.name}: its deflate stream ends before its declared compressed size.`);
+  }
   if (crc32(data) !== e.crc) refuse("not_openable", `${e.name} fails its CRC.`);
   return e.method === 0 ? data.slice() : data;
 }
@@ -4118,19 +4140,60 @@ function renderElement(element, index, opts = {}) {
 
 // src/ask.ts
 var ASK_LIMITS = { questionMax: 500, itemsMax: 8, itemMax: 2e3, totalMax: 12e3 };
+var ASK_OPTION_KEYS = ["includeProposed", "includeHidden", "includeRoom"];
 var chars = (s) => [...s].length;
 var cut = (s, n) => [...s].slice(0, n).join("");
-function buildAskContext(items, index) {
-  const out = { context: [], kept: [], dropped: [], truncated: [] };
+var isHidden = (el) => el.hidden !== void 0 && el.hidden !== null && el.hidden !== false;
+var isProposed = (el) => el.x_review_proposed !== void 0 && el.x_review_proposed !== null;
+function readOptions(opts) {
+  refuseUnknownOptions("buildAskContext", opts, ASK_OPTION_KEYS);
+  const o = opts ?? {};
+  for (const k of ASK_OPTION_KEYS) {
+    if (o[k] !== void 0 && typeof o[k] !== "boolean") {
+      throw new TypeError(`buildAskContext: ${k} must be a boolean; got ${JSON.stringify(o[k]) ?? String(o[k])}.`);
+    }
+  }
+  return { includeProposed: o.includeProposed === true, includeHidden: o.includeHidden === true, includeRoom: o.includeRoom === true };
+}
+function buildAskContext(items, index, opts = {}) {
+  const o = readOptions(opts);
+  const markOf = (el) => {
+    if (!o.includeHidden && isHidden(el)) return "hidden";
+    if (!o.includeProposed && isProposed(el)) return "proposed";
+    if (!o.includeRoom && isRoomElement(el)) return "room";
+    return null;
+  };
+  const withheld = (id) => {
+    const el = index.byId.get(id);
+    return el !== void 0 && markOf(el) !== null;
+  };
+  const viewFor = (el) => {
+    const out2 = index.out.get(el.id) ?? [];
+    const gone = out2.filter((l) => withheld(l.id));
+    if (!gone.length && !(index.inn.get(el.id) ?? []).some((l) => withheld(l.id))) return index;
+    return {
+      ...index,
+      out: /* @__PURE__ */ new Map([[el.id, out2.filter((l) => !withheld(l.id))]]),
+      inn: /* @__PURE__ */ new Map([[el.id, (index.inn.get(el.id) ?? []).filter((l) => !withheld(l.id))]]),
+      unresolved: /* @__PURE__ */ new Map([[el.id, [...index.unresolved.get(el.id) ?? [], ...gone]]])
+    };
+  };
+  const out = { context: [], kept: [], dropped: [], truncated: [], leftOut: { proposed: [], hidden: [], room: [] } };
   let total = 0;
   let full = false;
   for (const item of items) {
     const el = item && typeof item === "object" && "element" in item ? item.element : item;
+    const mark = markOf(el);
+    if (mark) {
+      out.leftOut[mark].push(el.id);
+      continue;
+    }
     if (full || out.context.length >= ASK_LIMITS.itemsMax) {
       out.dropped.push(el.id);
       continue;
     }
-    let text = renderElement(el, index);
+    let text = renderElement(el, viewFor(el));
+    if (isProposed(el)) text = `[${REVIEW_PROPOSED_LABEL}] ${text}`;
     if (chars(text) > ASK_LIMITS.itemMax) {
       text = cut(text, ASK_LIMITS.itemMax);
       out.truncated.push(el.id);
@@ -4889,6 +4952,7 @@ export {
   PHOTO_MAX_BYTES,
   PHOTO_TYPES,
   PUBLIC_FIELDS,
+  REVIEW_PROPOSED_LABEL,
   ROOM_PAIRS,
   SPATIAL_TYPES,
   TokenResource,

package/package.json

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