Skip to content

Commit bb35f13

Browse files
tmoostingclaude
andcommitted
0.66.0: the review profile's readers, onlyworlds.review (proposed_mark_of, hands_on_as_proposed); pack.is_proposed reads the same function
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 5f1a30d commit bb35f13

6 files changed

Lines changed: 197 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ The package version runs on its own semver; the schema it is generated from is `
44

55
## Unreleased
66

7+
## 0.66.0 (2026-10-26)
8+
9+
- **The review profile's readers: `onlyworlds.review`** with `proposed_mark_of`, `hands_on_as_proposed`, `PROPOSED_MARK` and `ProposedMark`, exported from the package. `proposed_mark_of(element, today=None)` gives the mark as a reader that shows a world shows it, `{"by", "expires", "lapsed"}`, or None for a settled element (absent, None, or a value that is not an object); `by` and `expires` are trimmed of Unicode White_Space as the room profile trims, `expires` is read only as a day (YYYY-MM-DD, ASCII digits), and `lapsed` is true from that day on, in UTC as keel reads it (a `today` that is not a day is a TypeError). `hands_on_as_proposed(element)` is what a reader that hands a world on leaves out: `x_review_proposed` with any value but absent or None, so a malformed value (a doubt) is left out too (rule 4). `pack.is_proposed` now calls it. The profile has no fixture yet; `tests/test_review.py` holds the npm SDK's 17 cases, including one per language default that would read differently (a byte order mark, U+001C, Arabic-Indic digits).
10+
711
## 0.65.1 (2026-10-26)
812

913
- **`draught()`'s docstring follows keel's 2026-10-26 change.** With `compact=True` every element body in the packet leaves out each field whose value is null, "", [] or {} (`id`, `type` and `name` always stay; 0 and False are values and stay), so read a missing field as empty; and a Message without the room mark is placed as any Narrative unless `messages` is named, when it is in `messages` and no other section. The client already returned the packet as keel sent it; no code changed.

‎src/onlyworlds/__init__.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@
6666
)
6767
from .names import type_word
6868
from .push import Patch, PushPlan, PushResult, plan_push, push, verify_level
69+
from .review import PROPOSED_MARK, ProposedMark, hands_on_as_proposed, proposed_mark_of
6970
from .room import is_room_element
7071
from .spine import SPINE_KINDS, SpineRead, read_spine_element
7172
from .worldfile import (
@@ -86,6 +87,7 @@
8687
"FORMAT_VERSION",
8788
"KNOWN_OF_KEEPS",
8889
"MESSAGE_PAIR",
90+
"PROPOSED_MARK",
8991
"PUBLIC_FIELDS",
9092
"READ_MARK_PAIR",
9193
"READ_ONLY_FIELDS",
@@ -105,6 +107,7 @@
105107
"Patch",
106108
"PreconditionFailed",
107109
"ProposedError",
110+
"ProposedMark",
108111
"PushPlan",
109112
"PushResult",
110113
"Response",
@@ -124,6 +127,7 @@
124127
"check_kinds",
125128
"element_filename",
126129
"export_world",
130+
"hands_on_as_proposed",
127131
"is_addressed_to",
128132
"is_hidden",
129133
"is_known_of",
@@ -133,6 +137,7 @@
133137
"is_to_everyone",
134138
"parse_retry_after",
135139
"plan_push",
140+
"proposed_mark_of",
136141
"push",
137142
"read_folder",
138143
"read_mark_of",

‎src/onlyworlds/_version.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
__version__ = "0.65.1"
1+
__version__ = "0.66.0"

‎src/onlyworlds/pack.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,7 @@
105105
from .http import API_BASE, Client
106106
from .names import type_word
107107
from .push import NOT_SENT
108+
from .review import hands_on_as_proposed
108109
from .room import is_room_element
109110

110111
__all__ = [
@@ -171,8 +172,8 @@ def hidden_line(left_out: int, kept: int) -> str | None:
171172
def is_proposed(body: Mapping[str, Any]) -> bool:
172173
"""True when the element carries ``x_review_proposed`` with any value but null. A
173174
null mark is a settled one (an accept writes null); a malformed value still counts as marked,
174-
so a doubt leaves the element out rather than handing it on as canon."""
175-
return body.get(PROPOSED_MARK) is not None
175+
so a doubt leaves the element out rather than handing it on as canon (``review.hands_on_as_proposed``)."""
176+
return hands_on_as_proposed(body)
176177

177178

178179
def proposed_line(left_out: int, kept: int) -> str | None:

‎src/onlyworlds/review.py‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
"""The review profile's proposed mark (schema-dist ``profiles/review.md``): an element written as proposed.
2+
3+
An element whose ``x_review_proposed`` is an object was written as proposed (an AI seat's new element on a
4+
world whose keeper reviews them) and is not canon until a keeper settles it: accept writes the mark null,
5+
decline deletes the element.
6+
7+
Two readings, as the profile's rule 1 and rule 4 give them. A reader that shows a world to its people shows
8+
the mark when it is an object (``proposed_mark_of``); any other value is not a mark and is reported by a
9+
lint, never repaired. A reader that hands a world on leaves out every element whose ``x_review_proposed``
10+
is anything but absent or null (``hands_on_as_proposed``), so a doubt never reaches an AI as canon. The npm
11+
SDK's ``proposedMarkOf`` and ``handsOnAsProposed`` are the same readers, and ``tests/test_review.py`` holds
12+
the same cases as its ``test/review.test.mjs``.
13+
"""
14+
15+
from __future__ import annotations
16+
17+
import re
18+
from datetime import UTC, datetime
19+
from typing import Any, TypedDict
20+
21+
from .room import _WHITE_SPACE
22+
23+
PROPOSED_MARK = "x_review_proposed"
24+
25+
_DAY = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}$")
26+
27+
28+
class ProposedMark(TypedDict):
29+
"""A proposed element's mark as a reader shows it."""
30+
31+
#: The membership or seat that proposed it, trimmed of Unicode White_Space as the room profile trims,
32+
#: when the mark names one.
33+
by: str | None
34+
#: The day it lapses (YYYY-MM-DD), trimmed, when the mark gives one in that shape.
35+
expires: str | None
36+
#: ``expires`` has come (on or before ``today``): shown as lapsed, never deleted on its own (rule 2).
37+
lapsed: bool
38+
39+
40+
def _today() -> str:
41+
"""Today as the profile writes a day, in UTC: keel reads a proposal as lapsed from midnight UTC of its day."""
42+
return datetime.now(UTC).strftime("%Y-%m-%d")
43+
44+
45+
def proposed_mark_of(element: Any, today: str | None = None) -> ProposedMark | None:
46+
"""The proposed mark of an element as a reader that shows a world shows it, or None for a settled
47+
element: ``x_review_proposed`` absent, None, or a value that is not an object (a list included).
48+
``today`` is a day as the profile writes one (YYYY-MM-DD), by default today in UTC; anything else is
49+
a TypeError."""
50+
if today is not None and not (isinstance(today, str) and _DAY.match(today)):
51+
raise TypeError(f"proposed_mark_of: today is a day as YYYY-MM-DD; got {today!r}.")
52+
if not isinstance(element, dict):
53+
return None
54+
v = element.get(PROPOSED_MARK)
55+
if not isinstance(v, dict):
56+
return None
57+
raw_by = v.get("by")
58+
by = raw_by.strip(_WHITE_SPACE) if isinstance(raw_by, str) and raw_by.strip(_WHITE_SPACE) else None
59+
raw_exp = v.get("expires")
60+
expires = (
61+
raw_exp.strip(_WHITE_SPACE) if isinstance(raw_exp, str) and _DAY.match(raw_exp.strip(_WHITE_SPACE)) else None
62+
)
63+
lapsed = expires is not None and expires <= (today or _today())
64+
return {"by": by, "expires": expires, "lapsed": lapsed}
65+
66+
67+
def hands_on_as_proposed(element: Any) -> bool:
68+
"""Whether a reader that hands a world on (a pack, a context packet, an AI's context) leaves this
69+
element out as proposed: ``x_review_proposed`` with any value but absent or None, a value that is not a
70+
proper mark included (a doubt, counted with the proposed)."""
71+
return isinstance(element, dict) and element.get(PROPOSED_MARK) is not None

‎tests/test_review.py‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
"""The review profile (schema-dist ``profiles/review.md``): ``proposed_mark_of`` (the mark as a reader that shows
2+
a world shows it, rules 1, 2 and 4) and ``hands_on_as_proposed`` (what a reader that hands a world on leaves out,
3+
rules 1 and 4). The profile has no fixture yet; these cases are the npm SDK's too (``test/review.test.mjs``),
4+
case for case."""
5+
6+
from __future__ import annotations
7+
8+
from typing import Any
9+
10+
import pytest
11+
12+
from onlyworlds import PROPOSED_MARK, hands_on_as_proposed, proposed_mark_of
13+
from onlyworlds.pack import is_proposed
14+
15+
TODAY = "2026-10-26"
16+
_NO_KEY = object()
17+
18+
FS = chr(0x1C)
19+
BOM = chr(0xFEFF)
20+
ARABIC_DAY = "".join(chr(c) for c in (0x662, 0x660, 0x662, 0x666)) + "-10-01"
21+
22+
# (what, the mark (_NO_KEY: no key), proposed_mark_of's answer, hands_on_as_proposed's answer)
23+
CASES: list[tuple[str, Any, Any, bool]] = [
24+
("no key", _NO_KEY, None, False),
25+
("null: settled", None, None, False),
26+
("a string: not a mark, a doubt", "yes", None, True),
27+
("an array: not a mark, a doubt", [], None, True),
28+
("false: a value, a doubt", False, None, True),
29+
("zero: a value, a doubt", 0, None, True),
30+
("an empty object", {}, {"by": None, "expires": None, "lapsed": False}, True),
31+
(
32+
"a whole mark, open",
33+
{"by": "m1", "evidence": "seen", "expires": "2026-11-01"},
34+
{"by": "m1", "expires": "2026-11-01", "lapsed": False},
35+
True,
36+
),
37+
(
38+
"trimmed by and expires",
39+
{"by": " m1 ", "expires": " 2026-11-01 "},
40+
{"by": "m1", "expires": "2026-11-01", "lapsed": False},
41+
True,
42+
),
43+
("lapses on its own day", {"by": "m1", "expires": TODAY}, {"by": "m1", "expires": TODAY, "lapsed": True}, True),
44+
(
45+
"lapsed before today",
46+
{"by": "m1", "expires": "2026-10-01"},
47+
{"by": "m1", "expires": "2026-10-01", "lapsed": True},
48+
True,
49+
),
50+
(
51+
"an expires not shaped as a day",
52+
{"by": "m1", "expires": "2026-1-1"},
53+
{"by": "m1", "expires": None, "lapsed": False},
54+
True,
55+
),
56+
("a blank or non-string by", {"by": " ", "expires": 7}, {"by": None, "expires": None, "lapsed": False}, True),
57+
# The two languages' own defaults disagree here (see the npm test): both trim by White_Space and read ASCII digits.
58+
(
59+
"a by wrapped in U+001C keeps it",
60+
{"by": f"{FS}m1{FS}"},
61+
{"by": f"{FS}m1{FS}", "expires": None, "lapsed": False},
62+
True,
63+
),
64+
(
65+
"a by wrapped in a byte order mark keeps it",
66+
{"by": f"{BOM}m1"},
67+
{"by": f"{BOM}m1", "expires": None, "lapsed": False},
68+
True,
69+
),
70+
(
71+
"an expires in Arabic-Indic digits is no day",
72+
{"by": "m1", "expires": ARABIC_DAY},
73+
{"by": "m1", "expires": None, "lapsed": False},
74+
True,
75+
),
76+
(
77+
"an expires wrapped in a no-break space is trimmed",
78+
{"expires": chr(0xA0) + "2026-10-01"},
79+
{"by": None, "expires": "2026-10-01", "lapsed": True},
80+
True,
81+
),
82+
]
83+
84+
85+
def _el(mark: Any) -> dict[str, Any]:
86+
return {"id": "a", "name": "A"} if mark is _NO_KEY else {"id": "a", "name": "A", PROPOSED_MARK: mark}
87+
88+
89+
def test_the_mark_key_is_the_profiles() -> None:
90+
assert PROPOSED_MARK == "x_review_proposed"
91+
92+
93+
@pytest.mark.parametrize(("what", "mark", "shown", "handed_on"), CASES, ids=[c[0] for c in CASES])
94+
def test_review_case(what: str, mark: Any, shown: Any, handed_on: bool) -> None:
95+
assert proposed_mark_of(_el(mark), TODAY) == shown
96+
assert hands_on_as_proposed(_el(mark)) is handed_on
97+
assert is_proposed(_el(mark)) is handed_on # the pack's reader is the same rule
98+
99+
100+
def test_not_an_element_reads_as_settled() -> None:
101+
for v in (None, "x", 3, ["a"]):
102+
assert proposed_mark_of(v, TODAY) is None
103+
assert hands_on_as_proposed(v) is False
104+
105+
106+
def test_today_must_be_a_day() -> None:
107+
with pytest.raises(TypeError):
108+
proposed_mark_of(_el({}), "26-10-2026")
109+
with pytest.raises(TypeError):
110+
proposed_mark_of(_el({}), 20261026) # type: ignore[arg-type]
111+
with pytest.raises(TypeError):
112+
proposed_mark_of(_el({}), ARABIC_DAY)
113+
assert proposed_mark_of(_el({})) is not None # today in UTC by default

0 commit comments

Comments
 (0)