docs(readme): document built-in references for cycles, drop legacy (ref X)#28
docs(readme): document built-in references for cycles, drop legacy (ref X)#28
Conversation
Adding .gitkeep for PR creation (default mode). This file will be removed when the task is complete. Issue: #27
…ef X) The encoder in both JS and Python already emits cycles using the built-in links-notation `(self-ref: first-ref second-ref ...)` form — a self- referencing dict is `(obj_0: dict ((str c2VsZg==) obj_0))`, with bare `obj_N` back-references rather than a `(ref obj_N)` marker. Decoders in both languages reject `(ref X)` as an unknown type marker. The per-language READMEs (`js/README.md`, `python/README.md`) still documented the legacy `(ref obj_0)` syntax in their "How It Works" sections, which contradicted the actual emitted format and the main README. This commit makes the per-language docs match reality and links to issue #27. Regression tests in both languages now assert two invariants: 1. cycles encode as bare `obj_N` links inside an `(obj_N: type ...)` self-reference definition (no `(ref ` substring in the output); 2. the legacy `(ref X)` form must fail to decode with "Unknown type marker: ref", so it cannot silently masquerade as a real type. Closes #27.
konard
changed the title
Working session summaryDone. The investigation revealed the encoders in JS and Python already produce the built-in self-reference form requested in issue #27 — PR #28 is updated and marked ready for review: #28 Changes:
All checks pass: JS 146 tests, Python 73 tests, ruff/mypy/prettier clean. This summary was automatically extracted from the AI working session output. |
🤖 Solution Draft LogThis log file contains the complete execution trace of the AI solution draft process. 💰 Cost: $5.112691📊 Context and tokens usage:Claude Opus 4.7: (2 sub-sessions)
Total: (21.1K new + 204.7K cache writes + 5.7M cache reads) input tokens, 36.1K output tokens, $5.112691 cost 🤖 Models used:
📎 Log file uploaded as Gist (2484KB)Now working session is ended, feel free to review and add any feedback on the solution draft. |
✅ Ready to mergeThis pull request is now ready to be merged:
Monitored by hive-mind with --auto-restart-until-mergeable flag |
1 participant
Summary
Closes #27.
The encoder in both JS and Python already emits circular references using
the built-in links-notation self-reference form
(self-ref: first-ref second-ref ...)rather than a(ref obj_N)marker.For example,
{ self: obj }encodes as(obj_0: object ((str c2VsZg==) obj_0))(JS) or(obj_0: dict ((str c2VsZg==) obj_0))(Python). Decoders in both languagesalready reject
(ref X)as an unknown type marker.The per-language READMEs still documented the legacy
(ref obj_0)syntaxin their "How It Works" sections, which contradicted both the emitted
format and the main
README.md(which already documented the new style).This PR makes the per-language docs match reality and adds regression
tests that lock in the format invariant.
Changes
js/README.md,python/README.md: replace the stale(ref obj_0)/(list obj_0 ...)description with the actual(obj_0: dict ...)/(obj_0: list ...)self-reference form, andlink to All our packages should be published, and if that didn't happen, we need clear visible feedback as badges for each package #27 for context.
js/tests/test_circular_references.test.js,python/tests/test_circular_references.py: two new regression testsper language asserting:
obj_Nlinks inside an(obj_N: type ...)self-reference definition (the encoded string contains no
(refsubstring);(ref X)form fails to decode withUnknown type marker: ref, so it cannot silently masquerade as areal type marker.
js/.changeset/issue-27-builtin-references.md: patch changeset(docs + tests, no source changes).
python/changelog.d/20260503_issue_27_builtin_references.md:matching scriv fragment.
.gitkeep: removed (placeholder from PR-init now superseded by realchanges).
Test plan
cd js && npm test— 146 passed (was 144; +2 new regression tests)cd js && npm run lint && npm run format:check— clean (onlypre-existing complexity warnings in
src/codec.jsandsrc/format.js)cd python && pytest tests/ --no-cov— 73 passed (was 71;+2 new regression tests)
cd python && ruff check src tests && ruff format --check src tests && mypy src— all cleanreferences, and shared sub-objects in both JS and Python — all
use
obj_Ndirect references, none use(ref ...).Issue reproduction
The example from the issue:
now produces (and is documented to produce):
— exactly the built-in self-reference form requested in the issue, with
no
refkeyword.