@onlyworlds/sdk 4.111.0 → 4.112.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +15 -0
- package/SCHEMA.md +1 -1
- package/dist/index.d.ts +14 -6
- package/dist/index.js +47 -21
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# For AI agents using @onlyworlds/sdk
|
|
2
2
|
|
|
3
|
-
**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.
|
|
3
|
+
**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.93** (canonical 00.33.00).
|
|
4
4
|
This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
|
|
5
5
|
re-read against it, the check fails rather than letting this document rot quietly.
|
|
6
6
|
|
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,21 @@ earlier history lives in git log only.
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [4.112.0] - 2026-10-30
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- **The lens readers follow schema-dist serial 93** (`v0.33.0-dist.93`), whose nineteen new cases replay in `resolveLens` and `worldGraph`. Four readings change for every caller:
|
|
13
|
+
- **A link reaches only an element of its field's target type.** An id naming an element of another type reaches nothing (a data fault, not a hop), draws no edge and takes no place in a reader's served list. A generic pair (a Pin's `element_type` and `element_id`) links only when its type key is exactly one of the 22 slugs as stored, nothing trimmed or folded, and in a graph it is placement, never an edge; the Pin's `map` link is the edge.
|
|
14
|
+
- **An anchor the reader cannot see is counted.** An anchor id that names no element of the world, or an element of another type than its field's, is now counted for the owner as `anchor_not_visible`; it was skipped silently.
|
|
15
|
+
- **A known-of stub keeps its base and public fields, every other field unset.** The stub is made from the body the reader is served: `change_seq` joins the base fields, a public link (a Character's `species`) is kept as trimmed for that reader, every other field of the type it holds is at its unset value (`''`, `null` or `[]`; the who and door fields `null`), and no extension key is kept.
|
|
16
|
+
- **A graph node's name is the stored value**, `null` when absent, and an edge's `index` is the target's place in the list as served, which keeps a proposed id the reader's rung sees.
|
|
17
|
+
- **`draughtText` names the public reader.** The API reads a public draught (keyless, or an account with no access in the world) as the public reader in either mode, and a public `voice` packet's text said "Read as the Character's own view." It now says "Read as the public reader." whenever the packet's `reader` is `public`; every other packet, and one without `reader`, reads by `mode` as before. The shared draughtText fixture gains the case (`public-reader`, 51 cases).
|
|
18
|
+
|
|
19
|
+
### Added
|
|
20
|
+
|
|
21
|
+
- **`reader` on `OwDraught`**: the rung the packet was built through (`public`, `owner`, `co_builder`, `contributor`, `guest`, `seat` or `player`), which the API serves beside `mode` on every draught since 2026-10-30, kept under `compact`; `mode` stays what was asked.
|
|
22
|
+
|
|
8
23
|
## [4.111.0] - 2026-10-30
|
|
9
24
|
|
|
10
25
|
### Changed
|
package/SCHEMA.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# OnlyWorlds Schema Reference
|
|
2
2
|
|
|
3
|
-
**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.
|
|
3
|
+
**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.93** — canonical schema **00.33.00**, published 2026-10-30.
|
|
4
4
|
|
|
5
5
|
GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
|
|
6
6
|
Written for both humans and AI agents reading this package locally.
|
package/dist/index.d.ts
CHANGED
|
@@ -2977,7 +2977,10 @@ interface OwDraught {
|
|
|
2977
2977
|
calendar: Record<string, unknown>;
|
|
2978
2978
|
as_of: number | null;
|
|
2979
2979
|
now: number | null;
|
|
2980
|
+
/** The mode asked for (`voice` or `act`); `reader` says what the packet was read as. */
|
|
2980
2981
|
mode: 'voice' | 'act';
|
|
2982
|
+
/** The rung the packet was built through: `public` reads as itself in either mode; otherwise the owner, a member's role, or a seat. Kept under `compact`. */
|
|
2983
|
+
reader?: 'public' | 'owner' | 'co_builder' | 'contributor' | 'guest' | 'seat' | 'player';
|
|
2981
2984
|
/** The policy served under, every key resolved. */
|
|
2982
2985
|
policy: Record<string, unknown>;
|
|
2983
2986
|
/** {section: items the budget dropped}; empty when whole. `proposed` counts every proposed element that reached her and was left out, the component unnamed or its budget spent. */
|
|
@@ -5177,7 +5180,7 @@ interface OwLensReader {
|
|
|
5177
5180
|
character?: string | null;
|
|
5178
5181
|
/** A guest's whole elements. */
|
|
5179
5182
|
whole?: readonly string[] | null;
|
|
5180
|
-
/** A guest's known-of elements, served as stubs (no links, no date). */
|
|
5183
|
+
/** A guest's known-of elements, served as stubs (the base and public fields, every other field unset: no links, no date). */
|
|
5181
5184
|
known_of?: readonly string[] | null;
|
|
5182
5185
|
/** On an owner: the reader it reads as. The view is that reader's; the owner's two counts stay. */
|
|
5183
5186
|
as?: OwLensReader | null;
|
|
@@ -5283,11 +5286,13 @@ declare function lensesInUse(membership: readonly string[] | null | undefined, x
|
|
|
5283
5286
|
*
|
|
5284
5287
|
* The rules, in short: visibility first (a hidden or proposed element is not there to hop through; a
|
|
5285
5288
|
* known-of stub is kept as served and nothing hops out of it); a hop reaches both ways, and on through
|
|
5286
|
-
* a Relation to its parties
|
|
5289
|
+
* a Relation to its parties, only to an element of the link's target type (a generic pair's type key
|
|
5290
|
+
* compared exact against the 22 slugs); an umbrella enters each child lens once, each child keeping its own budget and mail rule, the rows made by the umbrella's `show`; a hop never crosses a room
|
|
5287
5291
|
* element; a reading aid (the charter, its guide, a domain: `isCharterElement`) a hop reaches is kept, and
|
|
5288
5292
|
* hopped on from, only when `types` names its pair, while one the lens names as an anchor is kept and
|
|
5289
5293
|
* followed; anchors first in link order, then by type in the schema's order, newest first, then by id;
|
|
5290
|
-
* an anchor the reader cannot see
|
|
5294
|
+
* an anchor the reader cannot see (an id naming no element, or one of another type than its field's, too)
|
|
5295
|
+
* is skipped and counted for the owner (`anchor_not_visible`); a template resolves to nothing; the fence is `as_of` on
|
|
5291
5296
|
* each element's own date; `changed_within` cuts what a hop or a filter reaches that changed longer ago
|
|
5292
5297
|
* than that many days before `clock` (`stale`), never an anchor. A value outside the profile's table makes
|
|
5293
5298
|
* the lens unreadable: `unreadable` names the key and nothing is resolved.
|
|
@@ -5396,7 +5401,7 @@ interface OwGraphNode {
|
|
|
5396
5401
|
id: string;
|
|
5397
5402
|
/** The element's type, as its slug (`character`). */
|
|
5398
5403
|
type: string;
|
|
5399
|
-
/** The element's name, or null when it has none. */
|
|
5404
|
+
/** The element's name as stored, or null when it has none; nothing invented. */
|
|
5400
5405
|
name: string | null;
|
|
5401
5406
|
/** The type's colour group, its colour word (`blue`, `green`, `pink` or `amber`), from the distribution's
|
|
5402
5407
|
* presentation defaults: a key for drawing the 22 types, never a classification and never shown as a label. */
|
|
@@ -5442,8 +5447,11 @@ interface OwWorldGraph {
|
|
|
5442
5447
|
*
|
|
5443
5448
|
* Each schema link field, and each extension field a profile declares a link (`x_lens_leads_to`,
|
|
5444
5449
|
* `x_spine_depends_on`), gives one edge per target that is a node, with the target's place in the list as
|
|
5445
|
-
* the reader is served it
|
|
5446
|
-
*
|
|
5450
|
+
* the reader is served it (the owner's list as stored; any other reader's leaves out what it does not see
|
|
5451
|
+
* and keeps a proposed id its rung sees); a link held on both ends is two edges. A Pin's generic pair
|
|
5452
|
+
* (`element_type`, `element_id`) is its placement, never an edge; its `map` link is. A guest's known-of
|
|
5453
|
+
* element has no edges out. A link to an element of another type than its field's target draws no edge and
|
|
5454
|
+
* is not counted. A link to an element that is not a node is counted in `edgesCut` by that element's reason: the
|
|
5447
5455
|
* lens's cut reason, else, with a lens, `outside_lens` for one the reader sees that the lens neither kept
|
|
5448
5456
|
* nor cut (counted for every rung); one of the kinds out by default without a lens; and `not_visible` for one the
|
|
5449
5457
|
* reader does not see. A link to an id that is not in the world is left out and not counted.
|
package/dist/index.js
CHANGED
|
@@ -4255,13 +4255,21 @@ var OWNER_ONLY = /* @__PURE__ */ new Set(["anchor_not_visible", "not_visible"]);
|
|
|
4255
4255
|
var ROOM_KEYS = new Set(ROOM_PAIRS.map((p) => `${fold(p.type)}/${fold(p.supertype)}`));
|
|
4256
4256
|
var MAIL_SECONDS = 30 * 86400;
|
|
4257
4257
|
var MESSAGE_ADDRESSING = ["characters", "narrator"];
|
|
4258
|
-
var STUB_FIELDS = ["id", "type", "name", "description", "supertype", "subtype", "image_url", "created_at", "updated_at"];
|
|
4258
|
+
var STUB_FIELDS = ["id", "type", "name", "description", "supertype", "subtype", "image_url", "created_at", "updated_at", "change_seq"];
|
|
4259
|
+
var STUB_NULLED = ["created_by", "changed_by", "changed_via", "changed_client"];
|
|
4260
|
+
var UNSET = { text: "", integer: null, single_link: null, multi_link: [] };
|
|
4259
4261
|
var LINK_FIELDS = new Map(
|
|
4260
4262
|
Object.entries(FIELD_SCHEMA).map(([type, fields]) => [
|
|
4261
4263
|
type,
|
|
4262
|
-
Object.entries(fields).filter(([, f]) => f.type === "single_link" || f.type === "multi_link").map(([name, f]) => [name, f.type === "multi_link"])
|
|
4264
|
+
Object.entries(fields).filter(([, f]) => f.type === "single_link" || f.type === "multi_link").map(([name, f]) => [name, f.type === "multi_link", f.target ?? "any"])
|
|
4263
4265
|
])
|
|
4264
4266
|
);
|
|
4267
|
+
var ANCHOR_TARGET = new Map((LINK_FIELDS.get("construct") ?? []).map(([f, , t]) => [f, t]));
|
|
4268
|
+
function linkTarget(el, field, target) {
|
|
4269
|
+
if (target !== "any") return target;
|
|
4270
|
+
const key = el[`${field.slice(0, -3)}_type`];
|
|
4271
|
+
return typeof key === "string" && TYPE_RANK.has(key) ? key : "";
|
|
4272
|
+
}
|
|
4265
4273
|
var isBody2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
|
|
4266
4274
|
var own = (v, key) => Object.prototype.hasOwnProperty.call(v, key);
|
|
4267
4275
|
var valueOf = (v, key) => own(v, key) && v[key] !== void 0 ? v[key] : null;
|
|
@@ -4449,14 +4457,19 @@ var Reading = class {
|
|
|
4449
4457
|
}
|
|
4450
4458
|
}
|
|
4451
4459
|
}
|
|
4452
|
-
/**
|
|
4460
|
+
/**
|
|
4461
|
+
* The ids the element's owner-served body links to, in the schema's field order. A link reaches only an
|
|
4462
|
+
* element of its field's target type (an id of another type reaches nothing: a data fault, not a hop), and
|
|
4463
|
+
* a generic pair only an element of the type its key names (`linkTarget`).
|
|
4464
|
+
*/
|
|
4453
4465
|
fullLinks(id) {
|
|
4454
4466
|
const el = this.byId.get(id);
|
|
4455
4467
|
const out = [];
|
|
4456
|
-
for (const [field, many] of LINK_FIELDS.get(this.typeOf.get(id)) ?? []) {
|
|
4468
|
+
for (const [field, many, target] of LINK_FIELDS.get(this.typeOf.get(id)) ?? []) {
|
|
4457
4469
|
const v = el[field];
|
|
4470
|
+
const to = linkTarget(el, field, target);
|
|
4458
4471
|
for (const t of many ? Array.isArray(v) ? v : [] : [v]) {
|
|
4459
|
-
if (typeof t === "string" && t
|
|
4472
|
+
if (typeof t === "string" && this.typeOf.get(t) === to && !out.includes(t)) out.push(t);
|
|
4460
4473
|
}
|
|
4461
4474
|
}
|
|
4462
4475
|
return out;
|
|
@@ -4466,22 +4479,31 @@ var Reading = class {
|
|
|
4466
4479
|
if (this.stubs.has(id)) return [];
|
|
4467
4480
|
return this.fullLinks(id).filter((t) => this.view.has(t));
|
|
4468
4481
|
}
|
|
4469
|
-
/**
|
|
4482
|
+
/**
|
|
4483
|
+
* The body this reader is served: the owner's own view the body as stored; any other reader's with the links
|
|
4484
|
+
* it cannot see left out (`trim`); a known-of element's a stub made from that trimmed body: the base fields
|
|
4485
|
+
* and the type's public fields kept, every other field of the type it holds at its unset value (`UNSET`; the
|
|
4486
|
+
* server's who and door null), no extension key, and `known_of: true`.
|
|
4487
|
+
*/
|
|
4470
4488
|
body(id) {
|
|
4471
4489
|
let b = this.served.get(id);
|
|
4472
4490
|
if (b !== void 0) return b;
|
|
4473
4491
|
const el = this.byId.get(id);
|
|
4474
4492
|
const type = this.typeOf.get(id);
|
|
4493
|
+
b = copy(el);
|
|
4494
|
+
delete b.x_served_trimmed;
|
|
4495
|
+
if (!this.stored) this.trim(type, b);
|
|
4475
4496
|
if (this.stubs.has(id)) {
|
|
4476
|
-
const
|
|
4477
|
-
const keep = /* @__PURE__ */ new Set([...STUB_FIELDS, ...
|
|
4497
|
+
const kinds = FIELD_SCHEMA[type] ?? {};
|
|
4498
|
+
const keep = /* @__PURE__ */ new Set([...STUB_FIELDS, ...PUBLIC_FIELDS[type] ?? []]);
|
|
4499
|
+
const full = b;
|
|
4478
4500
|
b = {};
|
|
4479
|
-
for (const k of Object.keys(
|
|
4501
|
+
for (const k of Object.keys(full)) {
|
|
4502
|
+
if (keep.has(k)) b[k] = full[k];
|
|
4503
|
+
else if (STUB_NULLED.includes(k)) b[k] = null;
|
|
4504
|
+
else if (own(kinds, k) && own(UNSET, kinds[k].type)) b[k] = copy(UNSET[kinds[k].type]);
|
|
4505
|
+
}
|
|
4480
4506
|
b.known_of = true;
|
|
4481
|
-
} else {
|
|
4482
|
-
b = copy(el);
|
|
4483
|
-
delete b.x_served_trimmed;
|
|
4484
|
-
if (!this.stored) this.trim(type, b);
|
|
4485
4507
|
}
|
|
4486
4508
|
this.served.set(id, b);
|
|
4487
4509
|
return b;
|
|
@@ -4660,7 +4682,8 @@ function anchorsOf(lens, r) {
|
|
|
4660
4682
|
for (const id of v) {
|
|
4661
4683
|
if (typeof id !== "string" || id === "" || seen.has(id)) continue;
|
|
4662
4684
|
seen.add(id);
|
|
4663
|
-
if (
|
|
4685
|
+
if (r.typeOf.get(id) !== ANCHOR_TARGET.get(field)) unseen.add(id);
|
|
4686
|
+
else if (field === "constructs" && r.view.has(id) && isLens(r.byId.get(id))) {
|
|
4664
4687
|
if (!r.stubs.has(id)) {
|
|
4665
4688
|
children.push(id);
|
|
4666
4689
|
continue;
|
|
@@ -4684,7 +4707,7 @@ function resolveOne(lens, recipe, r, visited, wall) {
|
|
|
4684
4707
|
let list = [];
|
|
4685
4708
|
const frontier = [];
|
|
4686
4709
|
for (const id of anchors) {
|
|
4687
|
-
if (visited.has(id)
|
|
4710
|
+
if (visited.has(id)) continue;
|
|
4688
4711
|
if (!r.view.has(id) || unseen.has(id)) {
|
|
4689
4712
|
addCut(id, "anchor_not_visible");
|
|
4690
4713
|
continue;
|
|
@@ -4997,7 +5020,7 @@ function worldGraph(world, reader, options) {
|
|
|
4997
5020
|
const node = {
|
|
4998
5021
|
id,
|
|
4999
5022
|
type,
|
|
5000
|
-
name:
|
|
5023
|
+
name: valueOf(el, "name"),
|
|
5001
5024
|
family: ELEMENT_GROUPS[type],
|
|
5002
5025
|
icon: ELEMENT_ICONS[type]
|
|
5003
5026
|
};
|
|
@@ -5020,15 +5043,17 @@ function worldGraph(world, reader, options) {
|
|
|
5020
5043
|
for (const source of ids) {
|
|
5021
5044
|
if (r.stubs.has(source)) continue;
|
|
5022
5045
|
const el = r.byId.get(source);
|
|
5023
|
-
for (const [field, many] of LINK_FIELDS.get(r.typeOf.get(source)) ?? []) {
|
|
5046
|
+
for (const [field, many, target] of LINK_FIELDS.get(r.typeOf.get(source)) ?? []) {
|
|
5047
|
+
if (target === "any") continue;
|
|
5024
5048
|
const v = el[field];
|
|
5049
|
+
const to = linkTarget(el, field, target);
|
|
5025
5050
|
const list = many ? Array.isArray(v) ? v : [] : [v];
|
|
5026
5051
|
let served = 0;
|
|
5027
5052
|
for (let i = 0; i < list.length; i++) {
|
|
5028
5053
|
const t = list[i];
|
|
5029
|
-
const
|
|
5030
|
-
visit(source, field, t, seenOwner ? i : served);
|
|
5031
|
-
if (
|
|
5054
|
+
const typed = typeof t === "string" && r.typeOf.get(t) === to;
|
|
5055
|
+
if (typed) visit(source, field, t, seenOwner ? i : served);
|
|
5056
|
+
if (seenOwner || typed && r.linkable.has(t)) served++;
|
|
5032
5057
|
}
|
|
5033
5058
|
}
|
|
5034
5059
|
for (const field of DECLARED_LINKS) {
|
|
@@ -6120,8 +6145,9 @@ function draughtText(draught) {
|
|
|
6120
6145
|
const asOf = own2(d, "as_of");
|
|
6121
6146
|
const now = own2(d, "now");
|
|
6122
6147
|
const mode = own2(d, "mode");
|
|
6148
|
+
const public_ = own2(d, "reader") === "public";
|
|
6123
6149
|
put(
|
|
6124
|
-
`What the record holds around ${herName}` + (isInt(asOf) ? `, dated up to ${moment(asOf)}` : "") + (isInt(now) ? ` (the world's now: ${moment(now)})` : "") + "." + (mode === "voice" ? " Read as the Character's own view." : mode === "act" ? " Read as the caller's view." : "")
|
|
6150
|
+
`What the record holds around ${herName}` + (isInt(asOf) ? `, dated up to ${moment(asOf)}` : "") + (isInt(now) ? ` (the world's now: ${moment(now)})` : "") + "." + (public_ ? " Read as the public reader." : mode === "voice" ? " Read as the Character's own view." : mode === "act" ? " Read as the caller's view." : "")
|
|
6125
6151
|
);
|
|
6126
6152
|
if (asked) {
|
|
6127
6153
|
out.push("");
|