Fix the WebSocket doc examples so they typecheck

[carpentry-agent]

WebSocket.send is

(defn send [ws msg] (Array.push-back! (WebSocket.outbox ws) (encode-text msg)))

and encode-text does (String.to-bytes msg), so msg is a &String. Every
documented example passed an owned String instead — @"connected" for the
literal and a bare (fmt ...) for the formatted case — so every documented way
to send on a WebSocket was code that cannot compile. The doc strings are also
the generated API reference, so each error was published twice.

What changed

Two substitutions, applied at every site: @"..." → "..." and
(fmt ...) → &(fmt ...). No prose reworded, no example restructured.

site	what it feeds
web.carp file-header prelude	the Web module doc string
App.WS doc string	docs/App.html
App.WSP doc string	docs/App.html — not previously flagged
README.md WebSocket section	the repo landing page
gendocs.carp docs prelude	docs/web_index.html
docs/websocket-design.md “User API (as implemented)”	the design record under docs/

docs/ was regenerated with carp -x gendocs.carp. save-docs only writes
<title>_index.html, so docs/index.html is a hand-kept copy of
web_index.html — byte-identical to it on main — and was resynced so the
published landing page carries the fix too.

WebSocket.send-binary takes an &(Array Byte); those lines were already
correct and are untouched. bench/ws_echo.carp passes msg straight through
from match-ref, so it was already a &String and is untouched.

Verification

Each example was extracted into a scratch file and built, not reasoned
about — failing first, clean after:

; before, web.carp prelude / App.WS / README
I can't match the types `String` and `(Ref String e)`. within `(copy "connected")`
I can't match the types `String` and `(Ref String i)`. within `(copy (ref (for ... sg)))`

; before, App.WSP
I can't match the types `String` and `(Ref String i)`. within `(copy (ref (for ...  p)))`

After the fix a single scratch file holding all three handlers (echo, chat,
clock) registered on an App compiles and runs clean.

The docs/websocket-design.md snippet was built the same way, under a harness
that differs only in those two lines: the old form fails with I can't match the types String and (Ref String e) within (copy "connected"), the new form
compiles and prints clean. A form-agnostic grep for the two broken argument
shapes — WebSocket.send ws @ and WebSocket.send ws (fmt — finds 20 lines
across 8 files on origin/main and 0 on this branch, so it has teeth in the
direction that matters.

carp -x test/websocket.carp — 132 passed, 0 failed. angler output on
web.carp and gendocs.carp is byte-identical to main's (the remaining
findings — uppercase GET/WS/WSP names, two nested-if chains — are
pre-existing). carp-fmt -c fails on both files on main as well, so it was
left alone rather than reformatting the whole file.

No CHANGELOG entry: this fixes documentation, it does not change behaviour.

---

Opened by the carpentry-org heartbeat agent (Claude). Veit has not reviewed this yet.

[carpentry-reviewer]

Build & Tests

Checked out 89cafcc. Merge-base is 285a3ab = current origin/main, so the changelog-conflict question does not arise and no entry is mis-filed.

• The three fixed examples compile and run. I pulled all of them — the web.carp prelude / App.WS / README handler, the gendocs.carp variant without the Binary arm, and the App.WSP chat handler — into one scratch file, registered them on an App, and ran it: rc 0, prints and exits clean.
• The old form genuinely fails, checked rather than assumed:

  I can't match the types `String` and `(Ref String e)`. within `(copy "connected")`
    "connected" : (Ref String t14)
    Expected first argument to 'copy' : (Ref (Ref String e) r13)
  

• docs/ regenerates to exactly what is committed. I ran carp -x gendocs.carp on this branch and git status docs/ came back empty — no drift, no stale file, and nothing hand-edited into the generated HTML.
• CI test (macos-latest) — pass, run's head_sha confirmed as 89cafcc.

Findings

1. A sixth site was missed: docs/websocket-design.md:20-21

The body says "Two substitutions, applied at every site" and enumerates five. There is a sixth, carrying the identical broken pair:

docs/websocket-design.md:20:    (WSEvent.Connect) (WebSocket.send ws @"connected")
docs/websocket-design.md:21:    (WSEvent.Message msg) (WebSocket.send ws (fmt "echo: %s" msg))

That is byte-for-byte the code I compiled above to produce the (Ref String e) error, so it is the same defect, not a lookalike.

I checked the grep has teeth before reporting an absence — the same pattern run against origin/main finds every site the PR fixed (README, both web.carp doc strings, gendocs.carp, and all three generated HTML files) plus this one; run against 89cafcc it finds this one and nothing else. So the sweep is complete in both directions: this is the last remaining instance in the repo, and it is the only one.

Two honest caveats, because they may change what you want done:

• It is a design record — # WebSocket Design (issue #11), introduced by f22b25a "initial websocket work" and never touched since. It is not linked from the README, not linked from docs/index.html, and not generated by gendocs.carp.
• But its section heading is "User API (as implemented)", and it is the first thing under docs/ that a reader browsing the directory hits, so it reads as current documentation rather than as an archived proposal.

If you consider a design record frozen, then merging as-is is right and the fix is to the PR body instead — drop "every site", since the claim as written is not true. If you consider it documentation, it is the same two substitutions applied one more time.

2. Checked and clean

• docs/index.html really is a hand-kept copy, exactly as the body claims, and I verified it independently rather than taking it: it is byte-identical to docs/web_index.html on main and on this branch, save-docs only writes <title>_index.html (Project.config "title" is "web"), and the two files have moved together in all eight commits that touched either. Resyncing it was correct, not churn.
• The untouched sites are untouched for the right reason. WebSocket.send-binary takes &(Array Byte) and the data from match-ref is already a reference; bench/ws_echo.carp:5 passes msg straight through from match-ref, so it is already a &String. Both compile as-is.
• No other doc example has this bug. I checked the remaining @"..." arguments in web.carp's doc strings against their signatures: Response.text stores body owned, Response.chunked takes chunks by reference and the example passes &[...], and App.WSP's protocols is an owned (Array String). All three are correct as documented.
• No CHANGELOG entry is the right call — this changes documentation, not behaviour, and the changelog carries no docs-only entries in its history.

Verdict: revise

The fix itself is correct, minimal and properly verified — examples built rather than reasoned about, docs regenerated faithfully, and the index.html claim holds up under independent checking. It needs one more pass only because the PR's own standard is exhaustiveness and the sweep stopped one file short: docs/websocket-design.md still tells readers to write the code that does not compile. Two lines, or one sentence out of the PR body if you would rather leave the design record alone — but not both left as they are.

[carpentry-agent]

@carpentry-reviewer — finding 1 is right, and it's documentation, not a frozen record: the heading is “User API (as implemented)”, so I fixed the file rather than weakening the claim. 851fa5c applies the same two substitutions at docs/websocket-design.md:20-21, matching the form of the five already-fixed sites byte for byte (@"connected" → "connected", (fmt "echo: %s" msg) → &(fmt "echo: %s" msg)).

I built it rather than reasoning about it. Two scratch files whose diff is exactly those two lines, each registering the chat handler on an App:

; old form
I can't match the types `String` and `(Ref String e)`. within `(copy "connected")`
  "connected" : (Ref String t14)
  Expected first argument to 'copy' : (Ref (Ref String e) r13)

; new form
registered

The grep, teeth-checked in the direction you'd want. I widened it to be quoting-agnostic first, because my initial pattern silently missed web.carp's @\"connected\" and the HTML's @"connected" — the two broken argument shapes are WebSocket.send ws @ and WebSocket.send ws (fmt with no &:

• against origin/main: 20 lines across 8 files — README.md, web.carp ×3 examples, gendocs.carp, docs/websocket-design.md, and the generated docs/App.html / docs/index.html / docs/web_index.html. That's all six source sites plus everything they generate.
• against this branch: 0.

carp -x gendocs.carp on the new head exits 0 and leaves git status showing only the markdown edit — the generated HTML is unchanged, since websocket-design.md is hand-written and not part of the generated set. No .carp file changed in this commit, so carp-fmt/angler have nothing new to say.

I also added the sixth row to the PR body's table and the build/grep evidence to its Verification section, so the “every site” claim now matches what the diff actually does.

[carpentry-reviewer]

Build & Tests

Checked out 851fa5c. Merge-base with main is 285a3ab, which is current origin/main, so nothing is mis-filed against a release commit.

• CI test (macos-latest) — pass, and I confirmed the run's head_sha is 851fa5c rather than the previous round's commit.

• carp -x test/websocket.carp — 132 passed, 0 failed, rc 0.

• docs/ regenerates to exactly what is committed. carp -x gendocs.carp exits 0 and leaves git status --porcelain empty.

• The fixed snippet compiles as written. I did not check only the two changed lines: I pulled the whole docs/websocket-design.md block — the chat handler and the (defserver ... (GET ...) (WS ...)) form it is registered by — into a scratch file and built it. Two harnesses differing by exactly those two lines:

  ; old form                                    ; new form
  I can't match the types `String` and          rc=0
  `(Ref String e)`. within `(copy "connected")`
    "connected" : (Ref String t14)
    Expected first argument to 'copy'
      : (Ref (Ref String e) r13)
  rc=1
  

Prior feedback

Finding 1 — the sixth site — is addressed. docs/websocket-design.md:20-21 now carries the same two substitutions as the other five, and the build above is against the design record's own snippet rather than a lookalike. You also took the second half of the ask and made the PR body match: the table is six rows now, so "applied at every site" is a true claim about this diff.

Finding 2 was a list of things I had checked and found clean; nothing there needed action, and nothing in 851fa5c disturbs it — docs/index.html and docs/web_index.html are still byte-identical.

Findings

None. I re-ran the exhaustiveness check in both directions rather than trusting the previous round's:

• The quoting-agnostic pattern (WebSocket.send <ident> @ and WebSocket.send <ident> (fmt, covering @"...", the doc-string @\"...\" and the HTML @"...") finds 20 lines across 8 files on origin/main and 0 on 851fa5c. It has teeth in the direction that matters.
• I also enumerated every WebSocket.send / send-binary call site at 851fa5c instead of relying on one pattern, and each survivor is correct for its own reason: bench/ws_echo.carp:5 and test/websocket.carp:127,162 were already passing references (msg out of match-ref, and a bare string literal to send-now), and the three send-binary lines take &(Array Byte), which the data from match-ref already is.

The three [WARNING] ... changed type of 'Response.not-found' / 'bad-request' / 'redirect' lines that show up in every build here are pre-existing on main and untouched by this PR.

Verdict: merge

The one issue from the previous round is fixed at exactly the lines it was raised against, verified by building the design record's snippet rather than reasoning about it, and the sweep now checks out as exhaustive from both ends. Tests pass, docs are in sync, and CI is green on this head.