Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions contract/draught.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
"since": {"schema":{"type":"string"},"description":"For `recent`: a cursor from GET /changes, or an ISO 8601 date and time (as /changes' after). Absent, `recent` is empty. A cursor /changes would answer 409 resync_required answers the same here."},
"budget": {"schema":{"default":50,"maximum":1000,"minimum":1,"type":"integer"},"description":"Items per section: each section is cut to it on its own, never one order across sections. What each drops first: sheet and names the fewest her_links, knowledge, messages and recent the oldest, events the oldest dated then the undated by rank; self, role and work are never cut. `cut` says what each section dropped."},
"depth": {"schema":{"default":1,"enum":[0,1],"type":"integer"},"description":"The sheet's reach: 1 serves what her own element links to, 0 none."},
"lens": {"schema":{"format":"uuid","type":"string"},"description":"A lens id (the lens profile, profiles/lens.md: a Construct with supertype Lens): the packet adds `lenses`, one frame with that lens read for your own view. Its own x_lens carries its reach and limit, so lens beside depth or budget is a 422 (param lens). A lens you cannot see, or an id that is no lens, is the 404. Without lens and with no policy parameter but compact, the packet adds one frame per lens you chose (PUT /api/v2/me/lenses), in your order; none chosen adds nothing."},
"lens": {"schema":{"format":"uuid","type":"string"},"description":"A lens id (the lens profile, profiles/lens.md: a Construct with supertype Lens): the packet adds `lenses`, one frame with that lens read for your own view, on any Character you may read and in either mode. Its own x_lens carries its reach and limit, so lens beside depth or budget is a 422 (param lens). A lens you cannot see, or an id that is no lens, is the 404. Without lens and with no policy parameter but compact, a read of your own Character (GET /api/v2/me's `front_door.my_character`, the same id as its `character`) adds one frame per lens you start with, in your order: the lenses GET /api/v2/me lists, the ones you chose (PUT /api/v2/me/lenses) or, for a seat that never chose, the ones its Titles give it; none adds nothing. A read of any other Character adds none of them, and any policy parameter turns them off, `mode=voice` included; compact does not."},
"compact": {"schema":{"default":false,"type":"boolean"},"description":"`true` leaves out every empty section (an empty array or object) and an empty `cut`; the packet's frame (world, calendar, as_of, now, mode, reader, policy) and each null that is an answer (`character`, `style`, `recent_cursor`: the Draught schema says what each means) stay. It also leaves out every field of an element body that is null, \"\", [] or {}, keeping `id`, `type` and `name` always. Default `false`, the fixed shape, every section present. Announced 2026-11-02: from 2027-05-02 the default becomes `true` (the compact packet); a caller that needs every section present sends `compact=false` from now. Anything but true or false is a 422 (param compact)."},
"world": {"schema":{"format":"uuid","type":"string"},"description":"The id of a world to read without the key that owns it, by one of two readers: keyless, the id of a world its owner opened to the public (only while the public reader is on); or with an account token, the id of a world the account holds. Keyless (the public reader), the read answers what anyone may read there: every element not hidden, with links to hidden elements stripped and its pictures as fields; no files, no roster, no tombstones (a deleted id is the plain 404), and `Cache-Control: no-store`. A world that is not open, and an id that names no world, are the same 404. A keyless request counts against the per-address budget. With a key, `world` may name the key's own world by its id (ignored); any other value, the key's own slug and its id without hyphens included, is a 422 (param world). While the public reader is off, `world` beside a key is no parameter: a list route refuses it as an unknown filter (422, param world) and a get route ignores it. With an account token instead of a key (`Authorization: Bearer ow_a_...`), `world` names the world it reads: the owner reads it whole, a member as its own member key reads, and an account with no access there as the public reads (the same 404 for a world that is not open)."}
},
Expand Down Expand Up @@ -42,7 +42,7 @@
"proposed": "An element carrying x_review_proposed is proposed, not yet reviewed by a keeper; it is left out unless asked for. Every element that reaches her carrying the mark (the review profile, https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/review.md; a mark, an object with something in it, or a doubt, any other value that counts as present, counts here; null, an empty string or one of White_Space alone, [] and {} are no mark) is in this section or nowhere, whatever section would have held it: proposed, not yet reviewed, never what she knows. Each row's element carries its mark as served, except a stub (grade `known_of`), which shows no extension key and is here by its row's mark; `via` is empty for one that reached her only through `recent`. Only when the policy names the component; `cut.proposed` counts the ones left out.",
"recent": "The changes feed under this reader's scope since `since`, cut to the rows about her or by a member who plays her; no bodies. Empty with no since.",
"roster": "Who plays whom: GET /members' rows as this reader is served them. Never in the public reader's packet: the keyless door serves no roster.",
"lenses": "Present only with `lens=` (one frame) or, with no lens and no policy parameter but compact, when you chose lenses (one frame each, in your order). Each lens is read for your own view, never past it."
"lenses": "Present only with `lens=` (one frame) or, on your own Character, the lenses you start with (one frame each, in your order; the `lens` parameter says when). A frame is your own reading, never hers: each lens is read for your own view, never past it, and its mail is your own Character's, in either mode, so it is no part of what her voice may mention."
}
}
}
2 changes: 1 addition & 1 deletion scripts/verify-figures.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -1663,7 +1663,7 @@ if (!/\btime_range_current\b/.test(P.as_of?.description ?? '') || !sets.find((s)
// caption's first sentence is the document's.
const PHRASES = [
'in one read', 'one character', 'as the recorded world holds it', 'only when components names it', 'never cut', 'with since',
'one frame with that lens read for your own view', 'one frame per lens you chose', 'query parameters, all optional', 'every key resolved',
'one frame with that lens read for your own view', 'one frame per lens you start with', 'query parameters, all optional', 'every key resolved',
];
for (const ph of PHRASES) {
if (!src.includes(ph)) bad(`"${ph}" is not on the page's source`);
Expand Down
2 changes: 1 addition & 1 deletion src/components/figures/draught.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ export function draughtWords(data, code = (s) => `\`${s}\``) {
on: `${count(data.on.length)} by default`,
note: (s) => SAYS[s],
keyNote: (k) => `in the packet: ${code(k)}`,
lenses: `${code('lenses')}: with ${code('lens')}, one frame with that lens read for your own view; with no ${code('lens')} and no parameter but ${code('compact')}, one frame per lens you chose`,
lenses: `${code('lenses')}: with ${code('lens')}, one frame with that lens read for your own view; on your own Character, with no ${code('lens')} and no parameter but ${code('compact')}, one frame per lens you start with`,
policy: `${count(n)} query parameters, all optional`,
policyNote: `the packet's ${code('policy')}: every key resolved`,
setting: (s) => NOTES[s.param](code),
Expand Down
1 change: 1 addition & 0 deletions src/content/docs/docs/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ What changed on onlyworlds.com for everyone is on its own [Changelog](https://ww

## 2026-11-17

- **[A Character's context read](/docs/development/api/draught#the-policy) adds your starting lenses only on your own Character.** A lens frame in the packet is your own reading and your own Character's mail, never theirs. The plain read (no parameter, or `compact` alone) added a frame for each lens you start with on any Character you read; it now adds them only on the Character `GET /api/v2/me` names as yours, and none on any other. `lens=<id>` still adds its frame on any Character. If you read someone else's Character with the plain read and used `lenses`, ask for each lens by id. The pages also say that your starting lenses are the ones you chose or, for a seat that never chose, the ones its Titles give it.
- **[A `fields` list with unknown names](/docs/development/api/reads#expansion-and-sparse-fields) is refused once, with all of them named: TypeScript SDK 4.179.0 and [Python](/docs/development/python) 0.134.0.** A read whose `fields` names fields the element type does not have was a `422` that named the first. It is still one `422` with `param` `fields`; its message now lists every unknown name, and the error carries `unknown_fields`, `types_with_field` (for each one another element type has, those types) and `allowed_fields` (the names this type takes). `err.fieldsRefusal` and `ApiError.fields_refusal` return the three as served, and the [errors page](/api/errors/#invalid_request) says so. A list with one unknown name keeps its message.
- **[Unity SDK](/docs/development/unity) v0.44.0** follows serials 132 and 133 and the API's newer answers: each entry of the reading aids and each filled slot of the strand carries its `Type`, `OWFrontDoor.CharterElement` and `CharterSkillElements` give the Charter and its skills as elements, `OWSeat` reads whether a seat may change its Character (`MayChangeCharacter`, `MayChangeCharacterNote`, `FollowsSponsor`), and `OWApiError.IsHostBlocked` names a write the web host refused before the API saw it. A folder it writes names 0.44.0 on its producer line.
<!-- toolkit v5.11.4: no docs change (the workshop pack's online skill says what a page titled Blocked is, which the errors page says, and the pack's Charter line on where a feed starts is reworded; no page here quotes either text, and its links to these docs are the same 18 as at v5.11.3) -->
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/docs/development/api/draught.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Nine query parameters, all optional. The SDKs take the same nine. The MCP tool `
| `budget` | Items per section, 1 to 1000 | `50` |
| `depth` | The sheet's reach: `1` serves what the Character's own element links to, `0` none | `1` |
| `compact` | `true` leaves out every empty section and an empty `cut` ([Compact](#compact)); `false` serves the fixed shape | `false` (`true` from 2027-05-02) |
| `lens` | A [lens](/docs/lenses) id: the packet adds `lenses`, one frame with that lens read for your own view. The lens carries its own reach and limit, so `lens` beside `depth` or `budget` is a 422; a lens you cannot see is the 404. Without it, and with no policy parameter but `compact`, the packet adds one frame per lens you chose (`PUT /api/v2/me/lenses`) | none |
| `lens` | A [lens](/docs/lenses) id: the packet adds `lenses`, one frame with that lens read for your own view, on any Character you may read and in either mode. The lens carries its own reach and limit, so `lens` beside `depth` or `budget` is a 422; a lens you cannot see is the 404. Without it, and with no policy parameter but `compact`, a read of your own Character (the one `GET /api/v2/me` names) adds one frame per lens you start with, in your order: the ones you chose (`PUT /api/v2/me/lenses`) or, for a seat that never chose, the ones its Titles give it. A read of any other Character adds none of them (since 2026-11-17; before, it added yours), and any policy parameter turns them off, `mode=voice` included | none |

**Past the budget,** a section drops items: `sheet` and `names` those with the fewest `her_links`, `knowledge`, `messages` and `recent` the oldest, `events` the oldest dated first, then the undated by rank, `room` and `proposed` the oldest. `self`, `role` and `work` are never cut. `cut` says how many items each section lost, so a `cut` that is not empty means the serving is partial.

Expand All @@ -59,7 +59,7 @@ Nine query parameters, all optional. The SDKs take the same nine. The MCP tool `
{/* shape: Draught partial */}
| Section | Holds |
|:--|:--|
| `character` | The Character's own element, with `self: true` and its `grade`: the voice, where every other section is what that voice may mention. `null` when, read as the Character, their own element is hidden from them. Named `self` in `components` (`components=character` is a 422) |
| `character` | The Character's own element, with `self: true` and its `grade`: the voice, where every other section but `lenses` is what that voice may mention (a lens frame is your own reading and your own Character's mail, never theirs). `null` when, read as the Character, their own element is hidden from them. Named `self` in `components` (`components=character` is a 422) |
| `role` | Titles whose `holders` name them, Collectives whose `characters` name them, and Relations whose `actor` is the Character with supertype `Tenure` or `Membership`; in `voice`, only those the Character's own slice shows: a Title they hold and a Relation they act in are in it (since 2026-11-13), so one is missing only when the owner hid it |
| `work` | Relations with supertype `Work item` and subtype `open` or `taken` that are for the Character: by name (the item's `actor` is the Character) or by a role they hold (the item's `x_packet_for` names a Title whose `holders` name them). Each row adds `packet`, the item's `x_packet_elements` (`[]` when it has none), and `by_role`, the ids of their Titles the item names, each once (`[]` when none does; since 2026-11-17). A row that reached them only through a Title has `via` `["holders"]`. In `voice` a work item reaches them only through a field of its own that names them, so ask with `mode=act` for what is theirs by role |
| `style` | The Construct with supertype `Working style` whose `characters` name them (the most recently edited), or `null` |
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/docs/development/api/lenses.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ On the API, the server reads the same profile as every reader ([Lenses](/docs/le
- `GET /api/v2/world/{world_id}/lenses` lists every lens in the world you can see, templates marked, each with its recipe filled in, the Titles it is the default for, whether you chose it (`chosen`) and whether you start with it through a Title you hold (`from_titles`, never with `chosen`); the owner also gets who chose each lens (`chosen_by`) and, apart, which seats start with it through a Title (`title_seats`, each with those Titles). With `resolve=true` it adds each lens's reading for you: the kept rows, the cut by reason, the mail part. The owner may read as another reader with `read_as` (`guest`, `contributor`, `co-builder`, `public`, or a membership id). Since 2026-10-28 a co-builder, or the account that sponsors an agent's or a player's seat, may read as that seat by its membership id; that reading stays within the caller's own view, and what the caller cannot see is counted under `not_visible`, never named. Read as another reader, a lens that reader cannot see (deleted, or hidden from it) is not read: its row carries `skipped: "not_found"` and `reading: null`, the draught's word for a chosen lens it skips (since 2026-11-01). A member key, the owner's keys or an account token; never keyless. SDK `worldLenses`, Python `world_lenses`.
- `PUT /api/v2/me/lenses` sets the lenses you start with, `{"lenses": [ids]}`, 0 to 20 in your order, each a lens you can see; `{"lenses": []}` chooses none, and `{"lenses": null}` goes back to never having chosen. A member that never chose starts with the lenses whose `titles` name a Title its Character holds and it may see (a Title hidden from a guest or player seat brings it no lens, since 2026-11-13); a list of its own, an empty one included, wins whole, and the owner's lenses are always its own choice. `GET /me` and `GET /members` show each holder's `lenses` and where they come from, `lenses_from`: `chosen` (its own list, empty for none), `titles`, or `none` (it never chose and nothing brings it a lens: no Character, or Titles that name none; since 2026-11-10). A write key sets its own holder's list; an account token sets yours in the world it names with `?world=<id>`. A lens you chose that you can no longer see stays in your list at its place, and the answer marks `lenses` in `x_served_trimmed`. SDK `setMyLenses` (with `null` since 4.99.0), Python `set_my_lenses` (with `None` since 0.81.0).
- `PATCH /api/v2/account/worlds/{world_id}/members/{member_id}` with `{"lenses": [ids]}` alone sets a row's list on an account token: your own row, a seat you answer for, or the owner's own with `owner` as the member id. It answers `{id, role, kind, lenses}` (`id` null for the owner's own), with the same mark when a lens you cannot see was kept. SDK `setMemberLenses`.
- The [draught](/docs/development/api/draught) takes `lens=<id>` and adds `lenses`, one frame with that lens read for your own view. With no lens and no policy parameter but `compact`, it adds one frame per lens you chose, in your order.
- The [draught](/docs/development/api/draught) takes `lens=<id>` and adds `lenses`, one frame with that lens read for your own view. With no lens and no policy parameter but `compact`, a read of your own Character adds one frame per lens you start with, in your order; a read of any other Character adds none (since 2026-11-17).
Loading
Loading