shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
writeonce/docs/00-link-audit.md
shoney.arickathil 771180fd28 feat: iterations 19 + 17 — Float/Bytes scalars (.wob v5), library kind + internal/ 
- Float full stack: literals (fraction/exponent; `0..10` still a range), f64
  opcodes 34-41, @table column, WAL bit-exact replay, json fractions in and
  shortest-round-trip out. IEEE-quiet — FDIV never traps where DIV does.
- Bytes: a wo_str with its own class id, so alloc/free/copy are shared but no
  Text builtin accepts one; len/at/slice/eq/concat, base64 both ways, json
  boundary as base64; TEXT_COPY preserves the kind.
- No implicit Int/Float mixing (WO-E201 in the typechecker, not the emitter,
  which picks the opcode from one side and would misread the other).
- One IEEE deviation: float_cmp total order (NaN last, -0.0 == +0.0) for
  indexes and order-by, keys canonicalized to match. `?Float` nil is a
  reserved quiet NaN — the zero word is +0.0, WO_NIL_SCALAR's bits are -2.0.
- Renderer prefers fixed over exponential in 1e-6..1e21: pure shortest makes
  a price of 900.0 read `9e+02`. One renderer for interp/json/float_to_text.
- Fixed en route: lexer double-counted the leading digit; is_scalar_shaped
  took Float/Bytes as Int-shaped; Bytes ownership needed a shared heap-scalar
  predicate or temps never dropped; order-by bit-compared negatives backwards.
- Iteration 17: `kind = "library"` (absent = program; bad value = WO-E109),
  entry-less check mode retiring the `--emit` workaround, Go's `internal/` as
  WO-E108 at the consumer's `use`. Driver-only; VM/.wob/GC untouched.
- Framework reorg: internal/{parse,serve}.wo; http/form.wo split out to keep
  media_type/form_values public (parse.wo had grown public surface).
- Docs: link audit (97 -> 88 broken, conflict markers resolved, 2 duplicate
  stories removed), 00-code-review verified 26/27, iterations re-sequenced.
- Also carries the pre-staged pub(read)/using/#if work from the index.
- Gates: corpus 103/0, test_wal 156/0, web-app 26/0, oop-accept ALL MET.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-20 19:24:15 +02:00

8.3 KiB
Raw Blame History

Markdown link audit — 2026-08-20

Scope: every *.md in the repo (.git excluded). External URLs were not fetched (no network verification performed).

files relative links broken paths bad anchors
first scan 207 574 97 0
after section A fixes 206 569 88 0

Section A is repaired and verified. Sections B–F are pre-existing rot and still open — every one of the remaining 88 lives there.

Re-check with just linkcheck.

Tool: linkcheck.py — walks the tree, strips fenced/inline code, extracts inline links and reference definitions, resolves each relative target, and validates #fragment against GitHub-style heading slugs of the target file.

A. Regressions from the in-flight renumber — FIXED 2026-08-20

All nine broke because files moved in the working tree; each had a known successor. Repaired:

Source Was Now
docs/00-status.md:167 stories/language-runtime-database/05-language-surface.md …/done/05-language-surface.md
docs/00-status.md:187 stories/language-runtime-database/18-memory-db-features.md …/hold/18-memory-db-features.md
docs/stories/language-runtime-database/00-story.md:60 05-language-surface.md done/05-language-surface.md
docs/stories/language-runtime-database/00-story.md:69 18-memory-db-features.md hold/18-memory-db-features.md
docs/stories/language-runtime-database/25-http-service.md:4 ../00-story.md 00-story.md
docs/stories/language-runtime-database/26-blue-green-deploy.md:4 ../00-story.md 00-story.md
.../refine/08-shard-actor-runtime.md:98 ../hold/09e-durability-throughput-scale.md 22-durability-throughput-scale.md
.../refine/08-shard-actor-runtime.md:100 09f-io-uring-commit.md 23-io-uring-commit.md
.../refine/20-cross-program-tables.md:143 ../hold/09d-keypair-attach-auth.md 21-keypair-attach-auth.md

The 25/26 pair used ../00-story.md while 00-story.md is a sibling — the refine/-relative form pasted into files one level up.

Link labels were renumbered with their targets, since the old IDs contradicted the new paths: 9e→22 and 9f→23 in refine/08 (both the "Gated by the benchmark" note and settled decision 4, "Order: 22 → the 8+11 arc → 23").

B. Dead era: the old flat docs/plan/NN-*.md numbering (48 links)

docs/plan/ now holds only compiler/, exploration/, oop-vm/, discarded.md, learnings.md. Every flat-numbered plan doc is gone, and no successor path was recorded. Missing targets, by inbound count:

  • 09-concurrency-scaleout.md — 12
  • 11-wal-and-recovery.md — 9
  • 12-engine-disk-cutover.md — 8
  • 10-storage-foundations.md — 8
  • done/02-event-loop-epoll.md — 4
  • 13-class-model-live-pricing.md — 3
  • 07-inotify-content-watcher.md — 3
  • 08-sendfile-static-assets.md — 2
  • 15-mcp-streamable-http.md, 16-postgres-mirror.md, done/03-hand-rolled-http.md, done/04-cutover-remove-tokio-axum.md — 1 each

Inbound from: all of docs/plan/exploration/{linux,postgresql,c-runtime,assembly}/, plus docs/00-principles.md:57,77,78, runtime/README.md:47, .dev/reference/README.md:55,56,58.

Decision needed — these exploration docs still cite a plan structure that no longer exists. Either map each to its story successor (e.g. concurrency-scaleout → stories/.../refine/08-shard-actor-runtime.md, wal/storage → refine/22-durability-throughput-scale.md, io_uring → refine/23-io-uring-commit.md) or strip the links and keep prose.

C. Dead era: the docs/runtime/database/ tree (7 links)

docs/runtime/ does not exist. Missing targets:

  • 03-inmemory-engine.md — 5 (incl. one #recovery anchor)
  • 02-wo-language.md — 2 (incl. one #concurrency-model anchor)
  • 07-wo-seg-migration.md — 1

Inbound from docs/plan/exploration/linux/{07-io_uring,08-mmap,11-memfd_create}.md, docs/plan/exploration/{assembly/02-writeonce-stance,c-runtime/02-single-binary}.md, runtime/README.md:43, .dev/reference/README.md:31.

D. Never-created / removed siblings (5 links)

Source Target Note
docs/plan/exploration/linux/06-sendfile.md:10 ./07-splice.md slot 07 is 07-io_uring.md; no splice doc was written
docs/plan/exploration/assembly/00-overview.md:19 ../../../.dev/reference/go/src/runtime/atomic_amd64.s wrong depth and file absent from the vendored Go tree
docs/00-principles.md:87 examples/blog/README.md docs/examples/blog/ never existed
.dev/reference/rest/README.md:76 ../../docs/examples/blog/README.md same missing example
.dev/reference/README.md:41,59 ../docs/plan/exploration/colibri/00-colibri-and-mixtral.md exploration/colibri/ absent (2 links)

E. prototypes/ tree gone (4 links)

prototypes/ is not in the repo. Referenced as prototypes/wo-db/ from docs/plan/exploration/c-runtime/00-plan.md:88, 02-single-binary.md:83, runtime/README.md:5, and prototypes/llama-moe-stream from .dev/reference/README.md:59.

F. Vendored skill copies — not ours to fix (13 links)

.dev/skills/ holds flattened copies of plugin skills. The originals ship as directories with sibling reference files; flattening dropped them.

  • .dev/skills/context-mode/context-mode.md:297-300 → ./references/{patterns-javascript,patterns-python,patterns-shell,anti-patterns}.md
  • .dev/skills/superpowers/requesting-code-review.md:34,95 → code-reviewer.md
  • .dev/skills/superpowers/subagent-driven-development.md:232,300,345,400,410 → implementer-prompt.md, task-reviewer-prompt.md, re-review-prompt.md (×2), ../requesting-code-review/code-reviewer.md
  • .dev/skills/superpowers/test-driven-development.md:206 → writing-good-tests.md
  • .dev/skills/superpowers/writing-skills.md:12,587 → ../using-superpowers/references/{codex,gemini}-tools.md, testing-skills-with-subagents.md

Leave as-is, or re-vendor the skills with their references/ subdirectories.

Structural problems found alongside the links

  1. Iteration 19 was double-booked — RESOLVED. refine/19-chat-websocket-workload.md and refine/24-chat-websocket-workload.md were the same document, differing only in the # Iteration NN heading, while 19-missing-scalar-types.md also claimed 19. 00-story.md's mapping line (24←19(chat)) and table row 20 make 24 canonical, so the 19 copy was deleted. refine/11-fibers.md:13 had been pointing at the 19 copy — repointed to 24 first, so the delete broke nothing. Prose in refine/08 that named "iteration 19" for chat now says 24 (4 places).

  2. 08-shard-actor-runtime.md existed twice — RESOLVED. 58 lines at the stories root vs 110 in refine/. The refine/ copy supersedes it outright: same acceptance criteria plus the 2026-08-20 settled decisions, the inferred-GC restatement (7b retired @gc, which the root copy still required), and the corrected substrate path (the root copy cited runtime/wo-rt.c, removed with the Rust runtime). Root copy deleted; the one inbound link, docs/00-status.md:171, now points at refine/. Six other referrers already did.

  3. Unresolved merge-conflict markers were committed into refine/20-cross-program-tables.md:139-145 — `<<<<<<<< HEAD:… / ======== /

    language-surface-strictness:…/hold/09c-cross-program-tables.md, from a rename-conflicted merge. This is what produced that file's broken 09dlink: the stale side was still in the file. Resolved in favour of HEAD (the renumbered21text).grepconfirms no other conflict markers underdocs/`.

Still open

  • Sections B–F above: 88 broken links, all pre-existing.
  • docs/plan/discarded.md and docs/plan/learnings.md are the only survivors of the old flat plan layout, which is why B and C have no successor map. A rename table in one of them would let the exploration docs be repaired mechanically rather than by guesswork.
  • docs/00-status.md:171 still shows iteration 8 as ⬜ while 00-story.md:68 records arc stages 1+2 as landed 2026-08-20. Not a link problem — a status disagreement between the two index docs. Left alone.
  • refine/23-io-uring-commit.md:26 still quotes the old order as "9e → 8+11 → 9f" in a dated note. No link involved; left as historical record.