fabi/Sylpheed
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ppc-manual): quote Canary and our own decoder, not the retired xenia-rs #42

Merged
fabi merged 1 commits from docs/ppc-manual-canary into main 2026-09-16 18:55:42 +00:00
Conversation 0 Commits 1 Files Changed 358 +13828 -13520
fabi commented 2026-09-16 18:34:59 +00:00
Owner
Copy Link

Rebuilds the PPC manual generator on the two sources we keep: Xenia Canary for semantics, and
crates/sylpheed-ppc — Sylpheed's own decoder — for decode references. It also regenerates all
350 pages. The retired xenia-rs is no longer quoted anywhere in the generated content.

Why it needed rebuilding, not just re-running

The generator hasn't been able to run correctly since the manual moved into tools/. It
computed the repository root as HERE.parent.parent, which now names tools/. The XML, Canary's
emitters and xenia-rs all stopped resolving — silently, because both scrapers skipped anything
they couldn't find. Every page linked to paths that existed nowhere.

What xenia-rs actually contributed

section on main now
Operation (pseudocode) 251 pages of boilerplate: "derives from the xenia-rs interpreter" (99 real seeds) honest text pointing at the Canary snapshot; the seeds are unchanged
C translation 337 pages of boilerplate mapping ctx.gpr idioms a mapping of Canary's real HIR calls, checked against ppc_hir_builder.h
semantic snapshot 336 pages, the xenia-rs interpreter arm 349 pages, the Canary emitter at a pinned commit, plus the helper for 128 pure delegations
references links into xenia-rs + Canary (all dead) Canary XML and emitter, pinned; sylpheed-ppc opcode and decoder

Pinned to upstream canary_experimental @ f21ebd49e9, not our checkout. Our checkout carries
instrumentation and lacked upstream's mcrf fix ("copy the CR field instead of comparing it against
zero"). Quoting it would have published probes, and a wrong mcrf, as "Canary semantics".

Verified

check result
generator consistency checks 455 XML entries · 350 families · 598 index keys
hand-written sections 386 / 386 byte-identical after regeneration
xenia-rs in generated regions 0
in-repo decoder links 910 / 910 resolve to a line holding the identifier
emitter boundaries brace counter == column-0 } on 521 / 521; preprocessor model unit-tested
idempotency re-run → 0 pages updated, 0 working-tree changes

memory/dcbi.md is the one page without a snapshot, because Canary has no InstrEmit_dcbi at all.
It had no xenia-rs snapshot either.

⚠️ Hand-written notes: links fixed, claims deliberately not rewritten

  • 110 dead links into ../../xenia-rs/… now point at the file in the archived repository
    (git.mc02.dev/fabi/xenia-rs @ 8401d4d). Line anchors were dropped: the notes predate that commit
    (0 of 441 old line ranges match it), and a precise-looking wrong anchor is worse than none. The
    link text, which carries the author's line numbers, is unchanged.
  • 140 prose claims about xenia-rs's behaviour remain. 23 are verified to hold for Canary too
    (32-bit CR0 truncation, OE left unimplemented). The other 114 need checking one by one, and some
    invert    : divdx notes a correct 64-bit CR0 update in xenia-rs, where Canary's UpdateCR
    truncates. A blind "xenia-rs → Canary" swap would publish false claims, so that's left for a
    deliberate pass.

🤖 Generated with Claude Code

Rebuilds the PPC manual generator on the two sources we keep: **Xenia Canary** for semantics, and **`crates/sylpheed-ppc`** — Sylpheed's own decoder — for decode references. It also regenerates all 350 pages. The retired `xenia-rs` is no longer quoted anywhere in the generated content. ## Why it needed rebuilding, not just re-running **The generator hasn't been able to run correctly since the manual moved into `tools/`.** It computed the repository root as `HERE.parent.parent`, which now names `tools/`. The XML, Canary's emitters and `xenia-rs` all stopped resolving — **silently**, because both scrapers skipped anything they couldn't find. Every page linked to paths that existed nowhere. ## What `xenia-rs` actually contributed | section | on `main` | now | |---|---|---| | Operation (pseudocode) | **251** pages of boilerplate: *"derives from the xenia-rs interpreter"* (99 real seeds) | honest text pointing at the Canary snapshot; the seeds are unchanged | | C translation | **337** pages of boilerplate mapping `ctx.gpr` idioms | a mapping of Canary's **real** HIR calls, checked against `ppc_hir_builder.h` | | semantic snapshot | **336** pages, the `xenia-rs` interpreter arm | **349** pages, the Canary emitter at a pinned commit, plus the helper for 128 pure delegations | | references | links into `xenia-rs` + Canary (all dead) | Canary XML and emitter, **pinned**; `sylpheed-ppc` opcode and decoder | **Pinned to upstream `canary_experimental` @ `f21ebd49e9`, not our checkout.** Our checkout carries instrumentation and lacked upstream's `mcrf` fix (*"copy the CR field instead of comparing it against zero"*). Quoting it would have published probes, and a wrong `mcrf`, as "Canary semantics". ## Verified | check | result | |---|---| | generator consistency checks | 455 XML entries · 350 families · 598 index keys | | hand-written sections | **386 / 386 byte-identical** after regeneration | | `xenia-rs` in generated regions | **0** | | in-repo decoder links | **910 / 910** resolve to a line holding the identifier | | emitter boundaries | brace counter == column-0 `}` on **521 / 521**; preprocessor model unit-tested | | idempotency | re-run → 0 pages updated, 0 working-tree changes | `memory/dcbi.md` is the one page without a snapshot, because Canary has no `InstrEmit_dcbi` at all. It had no `xenia-rs` snapshot either. ## ⚠️ Hand-written notes: links fixed, claims deliberately not rewritten - **110 dead links** into `../../xenia-rs/…` now point at the file in the **archived repository** (`git.mc02.dev/fabi/xenia-rs` @ `8401d4d`). Line anchors were dropped: the notes predate that commit (0 of 441 old line ranges match it), and a precise-looking wrong anchor is worse than none. The link text, which carries the author's line numbers, is unchanged. - **140 prose claims about `xenia-rs`'s behaviour remain.** 23 are verified to hold for Canary too (32-bit CR0 truncation, `OE` left unimplemented). The other **114 need checking one by one, and some invert**: `divdx` notes a correct 64-bit CR0 update in `xenia-rs`, where Canary's `UpdateCR` truncates. A blind "xenia-rs → Canary" swap would publish false claims, so that's left for a deliberate pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
fabi added 1 commit 2026-09-16 18:35:00 +00:00
docs(ppc-manual): quote Canary and our own decoder, not the retired xenia-rs
All checks were successful
CI / Native — linux (pull_request) Successful in 2h2m37s
Details
CI / WASM — Web (pull_request) Successful in 30m13s
Details
CI / Formatting (pull_request) Successful in 1m23s
Details
7f8a81b8f8 
The generator had not been able to run correctly since the manual moved into
`tools/ppc-manual/`: it computed the repository root as `HERE.parent.parent`,
which now names `tools/`, so the XML, Canary's emitters and xenia-rs all stopped
resolving — silently, because both scrapers skipped what they could not find.
Every page's references had been pointing at paths that exist nowhere.

What each source contributed, measured on the 350 pages before this change:

  Operation (pseudocode)  251 pages: fixed boilerplate "derives from the xenia-rs
                          interpreter"; 99 carry real hand-written seeds
  C translation           337 pages: the same kind of boilerplate
  xenia-rs snapshot       336 pages: the interpreter arm, pasted in — the only
                          per-instruction semantics on unseeded pages
  links                   xenia-rs opcode/decoder/interpreter + Canary emitter

Now:

  * semantics come from **Xenia Canary**, the reference emulator, read through
    `git show` at a pinned upstream commit (`origin/canary_experimental`,
    f21ebd49e9). Not our checkout: it carries instrumentation and lacked
    upstream's `mcrf` fix, so it would have published probes and a wrong `mcrf`.
    Each page embeds the emitter (`InstrEmit_<mnem>`), and for the 128 pure
    one-line delegations also the helper that holds the semantics.
  * decode references point at `crates/sylpheed-ppc` — the decoder that
    produces `sylpheed.db` — as in-repo relative links.
  * the boilerplate now says what is true, and the C translation guide maps
    Canary's actual HIR calls, checked against `ppc_hir_builder.h` (including
    that `UpdateCR(n, v)` truncates to 32 bits).
  * `rust_scraper.py` -> `decoder_scraper.py` (interpreter half dropped);
    missing sources are now errors, not empty results.

Verified:

  consistency checks        455 XML entries, 350 families, 598 index keys
  hand-written tails        386/386 byte-identical after regeneration
  xenia-rs in generated     0
  pages with a snapshot     349/350 (was 336) — `dcbi` has no Canary emitter at all
  in-repo decoder links     910/910 resolve to a line holding the identifier
  emitter boundaries        brace counter == column-0 `}` rule on 521/521;
                            preprocessor model unit-tested (#if 0/#else/#elif)
  idempotency               re-run: 0 pages updated, 0 working-tree changes

Hand-written notes (outside the generated regions) are not rewritten here:

  * 110 links into `../../xenia-rs/...` were dead; they now point at the file in
    the archived repository (git.mc02.dev/fabi/xenia-rs @ 8401d4d). Line anchors
    were dropped because the notes predate that commit — 0 of 441 old line
    ranges match it — and a precise-looking wrong anchor is worse than none. The
    link text, which carries the author's line numbers, is unchanged.
  * 140 prose claims about xenia-rs's behaviour remain. 23 are verified to hold
    for Canary too (the 32-bit CR0 truncation, OE left unimplemented); the other
    114 need checking one by one, and some invert — e.g. `divdx` notes a correct
    64-bit CR0 update in xenia-rs where Canary's `UpdateCR` truncates. Left for
    a deliberate pass rather than a blind substitution.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
fabi merged commit 2b68f17b5d into main 2026-09-16 18:55:42 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
agent/decoder
Owned by the Decoder (disc to meaning; runs the emulator)
 agent/port
Owned by the Port (disc to playable; no RE)
 kind/ask
One agent asking the other for something it cannot answer in role
 kind/bundle
A bundle the human defined; agents decompose it into items
 kind/defect
Found by a play-test or a check
 kind/item
One unit of work, small enough to finish in a single session
 state/approved
Human approved the shape; an agent may start
 state/blocked
Waiting on another item; use the Depends-On field, not prose
 state/in-progress
An agent is working it now
 state/needs-human
Done as far as an agent can tell -- a person must look. The body says what to look at
 state/proposed
Agent proposed this item; awaiting the human's approval to start
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
sylph-decoder sylph-pi sylph-port fabi
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: fabi/Sylpheed#42
Delete Branch "docs/ppc-manual-canary"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?