~bigbes/sr-ht-spec

394b6ace — Eugene Blikh 6 hours ago
web: stop promising a scripts seam this layout does not have

The header listed "three seams" and described "scripts" as one nothing used
yet. No such block was ever declared, so the list was one short of the truth
and read as an invitation to use something absent — a page defining "scripts"
renders nothing at all and reports nothing, verified against html/template:
an unreferenced define is dropped and Execute still returns nil.

Not adding the block instead. proposal.html is the only page with a script and
it defines "head" with <script src="/static/diff.js" defer>, which is where a
deferred script belongs: fetched during parsing, executed after parsing and
before DOMContentLoaded, i.e. exactly where an end-of-body script runs, minus
the later fetch. diff.js does not depend on either — it calls init at once
when document.readyState has left "loading" and waits for DOMContentLoaded
otherwise. The seam goes in when a page needs what defer cannot give it.
4726b315 — Eugene Blikh 6 hours ago
make: name the missing tool before deleting the stylesheet it would rebuild

`make css` opened by removing web/static/main.min.*.css and only then reached
for sassc, so a machine without it lost a working stylesheet to learn that:
measured, `PATH=/usr/bin:/bin make css` died on the sassc line and left
check-css reporting no stylesheet and an orphan main.css for go:embed to pick
up. The three checks go in front of the rm for that reason, not for the
message alone — re-measured after, the same failure now leaves the hashed file
untouched and check-css still passes.

The message is worth something too, most of all for the partials. Missing,
sassc says "File to import not found or unreadable: base ... on line 16:1 of
scss/main.scss" and never prints the -I path it searched, so a correct
@import in our own stylesheet reads as the bug. The check prints the ASSETS
path and names core.sr.ht's `make install` as what fills it.

MINIFY joins SASSC as a variable so the guard and the recipe cannot come to
name different tools, and so an install under another path stays buildable.
ecc6db16 — Eugene Blikh 6 hours ago
make: say what the version stamp is, and what it is not

The check-version comment claimed the binary "reports itself from the VCS
revision Go records". It does not. cmd/specsrht declares `const version =
"dev"` and hands it to mcpsrv.Handler, nothing in the tree calls
debug.ReadBuildInfo, so every build introduces itself to an MCP client as
"dev". The stamp is provenance readable with `go version -m`, which is what
this gate is for and all it now claims.

Keep the mechanism rather than adopting the siblings' -ldflags: there is no
symbol to set. `-X` at a const and `-X` at a symbol that does not exist are
both silently ignored on go1.26.5 — exit 0, no diagnostic, the binary still
prints "dev" — so a VERSION here would read like a version and do nothing.
Record what has to change first, and cov.sr.ht's argument for changing it.

Also name the linked-worktree case in the empty-dirt branch, which is how it
was found: built from .worktrees/chore/makefile-preflight with a clean tree,
the binary came out vcs.modified=true because Go had stamped the parent
checkout. Every measurement above was taken in a plain clone for that reason.
7138632e — Eugene Blikh 6 hours ago
cmd: keep the metrics listener on loopback unless asked otherwise

core-go defaults the Prometheus bind to ":0" - a random port on every
interface - while giving pprof "localhost:0", and this daemon inherited the
wrong half of that asymmetry: /metrics is served by core-go's own mux with no
credential in front of it, so anyone who could reach the host read the counters
of an instance whose service port is deliberately on loopback behind nginx.

withMetricsDefault inserts -m localhost:0 immediately after argv[0], so an
operator's own -m is parsed after it and still wins - server.New keeps the last
-m it sees. The vector is built once in run and handed to both bindAddresses and
server.New, so the startup line and the daemon cannot disagree about it.
3d3b1d11 — Eugene Blikh 7 hours ago
cmd: take the listen address from the config the operator already edits

The daemon's only HTTP listener was set by -b alone, with localhost:5091
compiled in as the fallback, so an instance that needs a different address
had to carry it in the unit file or the container entrypoint rather than in
the config.ini it edits for every other setting. phoebe-lab's template says
so in as many words: "the web listener is set with -b in the entrypoint ...
so no bind-address key is needed here", while every containerised sibling
beside it binds 0.0.0.0 through its own key.

[spec.sr.ht] bind-address is that key. The spelling is not invented here:
six siblings already read it under that name -- artifacts, bench, cover,
curator, snip and tokens -- and upstream's own builds.sr.ht worker reads
[builds.sr.ht::worker] bind-address, so it is the name an operator sharing
one config.ini across services already knows.

Precedence is flag > config > default, stated in service.DefaultBindAddress
and in bindAddresses rather than left to be inferred: server.New falls back
to the address it was constructed with only when the vector carries no -b,
so handing it cfg.BindAddress is what produces that order.

The address is validated while the config is read, next to repos and origin,
so a malformed one is refused by a message naming the key instead of by a
bare net error once the database is open and the hook socket is held. Port 0
is refused with the malformed ones -- it is legal to bind and useless behind
a proxy that connects to a fixed port.

bindAddresses reads the vector with core-go's own getopt rather than scanning
for "-b", so the attached form and clustered flags are read the way the real
parse reads them, and the startup line reports the addresses actually bound
rather than the configured one -- which -b had already been making it
misreport.
43eac1df — Eugene Blikh 7 hours ago
web: say in the embed directive that partials are wanted

//go:embed templates/*.html carried _threads.html by accident of a rule
rather than by saying so: embed excludes a name starting with '.' or '_'
when it walks a directory, not when a pattern matches the file directly.
Measured before changing anything — the partial is in the embedded FS
today, and TestEveryTemplateOnDiskIsEmbedded is what keeps it there.

The "all:" prefix states the rule instead of relying on the reader
knowing the distinction, so the line is right under either reading of it
and cannot be shortened into the directory form without the prefix being
deleted first. The glob stays: "all:templates" is the same intention
with no extension to match, and would compile a stray .DS_Store or an
editor swap file into the release binary, which pages.Load would filter
out in silence.

The comment on the neighbouring static directive moves with it, since
the two forms now differ on the page: that tree is served to a browser
by name, so excluding '.' and '_' is what is wanted there. It also
listed two assets where there are three — proposal.html has loaded
/static/diff.js since the prose differ grew a client side.
53803c31 — Eugene Blikh 7 hours ago
web: serve the asset tree for the two methods it answers

r.Mount registers a subtree under every method chi knows, so the routing
table listed all ten against a handler that answers two, and a
same-origin POST to /static/main.min.<sha>.css came back 200 with the
whole 133 KB stylesheet instead of a 405. Nothing was writable and
nothing leaked; the description was wrong, and the table is what chi's
own 405 and anything walking the router read.

chimw.GetHead over the pattern Mount would have appended, so the asset
tree is registered the way every other read route on this surface is.
Nothing of Mount's is lost: its RoutePath shift and its 404/405
inheritance are for a mounted *Mux, and assets.Handler is a plain
handler that reads r.URL.Path and strips the prefix itself.

Measured against a live listener, before and after: the hashed asset
still answers 200 with public, max-age=31536000, immutable and no Vary,
a HEAD still answers the same headers with no body, an
If-None-Match: * still answers 304 carrying the asset policy rather than
the page's private, no-store, and /static, /static/ and a name that is
not there still get this service's own 404 page. POST, PUT, PATCH,
DELETE and OPTIONS now get the rendered 405.

The 405 carries no Allow header, which is chi's limitation rather than
this route's: it hands the list of methods that would have matched only
to its built-in responder, through unexported types, so the custom
handler chimw.RenderRefusals installs cannot emit one. Every 405 on this
surface is missing it, not just this route.
8532809e — Eugene Blikh 7 hours ago
api: tell caches that the write plane answers per credential

Every answer the REST write plane gives is computed from the bearer token on
the request and from nothing else the request line shows: the 201 names a
proposal opened for the agent that presented the credential, the 401 names the
challenge, the 403 says this token may not propose. The mux carried no cache
policy at all, which made it the last credential-varying surface of the service
without one — web/ has it, /mcp has it, and /query got it two commits ago.

The policy is sr-ht-ecore's PrivateCache, the same helper the other three use:
private, no-store with Vary: Cookie, Authorization. Where it goes is a short
question here and was a long one for mountGraphQL, because that Group also holds
api-meta.json and had to keep it publicly cacheable. This mux mounts exactly one
route and it is the credential-varying PUT, so the policy covers the whole mux
and picks up two answers a route-level one would miss: chi's 404 for an address
this surface does not serve, and the resolver middleware's 401, written before
the router has looked at the path.

The honest ranking, which is why this is one line: a PUT is even less cacheable
than the POST /query carries the same policy for, so this is defence in depth
and not a live leak.

The test drives httptest.NewServer and a real client rather than a recorder,
which hands back the live header map and so cannot observe when a header was
set
ff38b522 — Eugene Blikh 7 hours ago
doc: check the href a review link publishes, not the destination it came from

Mutation found the dangerous-URL refusal had grown two guards for one property:
with an archive supplied, the check on the way out caught what the check on the
way in was for, so removing the incoming one turned nothing red. There is one
check now, on the href, which is the thing that reaches the anchor — and
removing it fails four tests in both configurations.

The relative-link test went the same way: a sibling destination resolves through
doc.Archive's space-wide stem fallback as well, so it passed with the linking
document's directory thrown away. It uses a path-qualified destination now,
which has no fallback.
f740ae5c — Eugene Blikh 8 hours ago
web: resolve a proposal's links against the revision under review

An internal link inside a proposed document used to reach the review page as the
destination as typed, so following one landed nowhere. The page now reads the
proposal through ProposalReview and resolves each block against the archive of
the revision that block's text is from: the branch tip for the text under
review, the base for a block the proposal deletes.

Every href is pinned to the revision it was resolved at. A document's site path
names the document and not the revision, so an unpinned link out of a proposed
block would land on the approved head — the text the proposal is changing.

Two things the resolver could not say before and says now: a link to a document
that does not exist is marked, and so is a citation of a section the proposal
has renamed, which is the error a proposal introduces and review is the moment
to catch.
fe0c8a62 — Eugene Blikh 8 hours ago
service: read a proposal's two revisions as archives

ProposalDiff hands over bytes and a path, so nothing above it can turn a
wikilink in a proposed document into a URL. ProposalReview returns the same
documents plus the whole document set of each side as an archive, built from the
tree walks the diff already does.

Two archives and not one because the review page renders two revisions: a block
the proposal deletes belongs to the base, and resolving its links against the
branch tip would answer for it with the very text the proposal is changing.

Each is built once per proposal rather than once per document; LinkPass is a
parse of every document in the revision. ProposalDiff is left as it was, so the
comment POST path and the MCP surface pay for neither.
c336e6e8 — Eugene Blikh 8 hours ago
doc: let the review renderer resolve against a supplied archive

Inline now takes the linking document's directory and the document set to
resolve against, and wraps whatever it is handed in reviewResolver rather than
holding one. The wrapping is the security boundary: doc.Archive applies no
dangerous-destination check, correctly, because the read plane's documents are
approved and render with unsafe on.

web/ still passes nothing, so the review page is unchanged by this commit.
d29b18f8 — Eugene Blikh 9 hours ago
web: describe the selection the composer actually gets

The composer's note explained that the script prefixes a selected line range
onto it and removes that element on Escape. Nothing prefixes anything any more:
the gutter drag is gone and a selection becomes a quotation in the textarea. The
comment now says that, since it is the one place a reader looks to learn what the
composer promises before they type.
e1d733b7 — Eugene Blikh 9 hours ago
scss: stop calling the margin a flex row, which it is not
4052544a — Eugene Blikh 9 hours ago
scss: mark the block being quoted, not the empty half of its cell

The tint that says "this is the block your comment will attach to" was painted
on the whole text cell. On a full-bleed review that cell runs about 500 pixels
past the end of the measure and another 200 past the margin the conversation
sits in, so the mark was mostly a wash of colour over nothing — which reads as
a rendering defect rather than as a mark.

It is on the block's own text now, plus the two number cells, which is what
"this block" means. The conversation beside it is left alone: a thread is not
part of what is being quoted, and this replaces the rule that had to paint the
page's background back over it.
c18c64d8 — Eugene Blikh 9 hours ago
web: pin the placement a stranded conversation falls back to

writeGroup pairs a notes row with the row before it only when the two belong to
the same block, because the other reading — "put this conversation on whatever
row is above it" — files a critique under a paragraph nobody wrote it about.
The pairing holds by construction today, which is exactly why the branch that
does not was untested: nothing on the page reaches it.

It is reached here directly, with a group holding the notes row alone, and what
it has to prove is that the comment is still on the page.
ec8e06d2 — Eugene Blikh 9 hours ago
scss: give a phone its comment back from the gutter

The conversation lives in the block's text cell now, so on a phone it starts
where the text starts — 88px in, behind two number tracks and a sign column.
Measured on a 375px viewport: 257 pixels of comment on a 375 pixel screen.

The full-width notes row this replaced had a rule for exactly that, and it says
why: a review comment is the one thing on the page that has to stay readable at
any width. So the rule moves to where the conversation moved. Below Bootstrap's
sm breakpoint the box is pulled back over the rail, which is empty at that
height — the gutter's number sits at the top of the row and the conversation
hangs off the bottom of it. 345 pixels of the 375 afterwards, and the page
still does not scroll sideways.
e569dcde — Eugene Blikh 9 hours ago
web: quote the text you selected instead of dragging line numbers

Dragging the gutter was how a reviewer said what they were talking about, and
it stopped meaning anything when prose started flowing: a paragraph is one row
with one range in the gutter, so a drag could only ever say "this paragraph",
which is what the composer already says. Selecting the words says which words.
They land in the composer as a `> ` quotation — something the reviewer can
edit, delete or keep, and which survives into the posted comment, where it says
what the critique is about to whoever reads the thread later.

The anchor does not move. A comment is still stored against its block's content
hash, heading path and index, which is why the selection is still CLAMPED to
one block: a quote reaching into the next paragraph would have to be filed
under a paragraph it is not about. The clamp does not argue with the mouse — it
takes the part of the selection lying inside the block the selection began in,
and the quote in the composer is the report of what was taken. Measured: a
701-character selection across two blocks quotes exactly the first block's 163
and opens that block's composer.

A quote is not a draft. `hasDraft` ignores a body that is exactly the quotation
this file inserted, and without that every stray selection would leave a
composer that nothing could ever close — "one composer at a time" would decay
into a box beside every block, which is the state the whole hiding rule exists
to prevent. Type anything beside the quote, or edit the quote itself, and it is
a draft like any other: measured, the second selection closes the quote-only
composer and clears its body, and leaves the one holding words open with the
words in it.

The address bar carries `#b-<digest>` — the block, not a range. That id is
honest across revisions by construction, since the digest covers the block's
content hash, so a link into a block that has since been rewritten resolves to
nothing rather than to its neighbour. What is lost is a shareable sub-block
selection; the quote in the comment body carries those two sentences to the
reader of the thread instead of to the follower of a link. A character range
under the same id would in fact be honest for the same reason, and is written
down at the top of diff.js as the option not taken rather than left to be
rediscovered.

The gutter cells and the sign are stripped out of a quote. That matters in one
narrow case, measured with the filter removed: a drag beginning above the diff
is read from its end, so the clamp opens the range before the block's row and
the quote comes out as `> 15–2015–20Спека даёт боту…`.

Selecting somebody's posted comment does nothing at all, deliberately: quoting
a critique into the box that comments on the paragraph would be an answer to
the wrong thing.
a26f1573 — Eugene Blikh 9 hours ago
web: move a block's conversation into the review page's margin

A thread was a full-width row under its block, so every critique, every reply
and every compose form pushed the two halves of the document apart by its own
height — on a page whose subject is how those paragraphs read together. It now
sits beside the block instead, out in the empty right-hand third of a
full-bleed review.

THE MARGIN IS A CELL AND NOT A COLUMN, which the table forces. The diff has to
be a table (a paragraph is six visual lines and its numbers have to stay on the
first of them), and a table has no column a row can opt into: a rowspanning
fifth column would have to survive a fold cutting a block in half, which it
cannot, and a fifth column on every row would take its width from the text on
a phone. What a table does have is a cell that can hold two things. So the
conversation is written into the block's own text cell and the stylesheet sets
the two side by side.

What that buys is that a row is as tall as its tallest cell: a thread beside a
paragraph now costs the document nothing. What it costs is a conversation
TALLER than its block — a heading with a long critique on it — which still
pushes what follows down, by the difference rather than by the whole.

Two inline-blocks and not a flex row. `display: flex` on a td is the obvious
spelling and it is wrong: the cell stops being a table cell and stops driving
its row's height, and measured in Chrome 151 every commented block painted
over the three rows below it. A code fence keeps its conversation underneath,
because only its last line would make room and one short line in a listing is
a lie about where the scrolling starts.

Below 1200px the two stack and the thread is back under its block, which is
also what it does with JavaScript off. The row model is untouched: writeGroup
folds the notes row into the row before it, the two are adjacent and share a
fold by construction, and a notes row that ever arrived without its block in
front of it still renders as the full-width row it used to be.

The deleted-block strike moved from the cell to the block's own div. It had to:
text-decoration propagates and no descendant can switch it off, so a strike
started on the cell runs through the comments written about the paragraph.
Measured both ways — with the strike back on the cell Chrome 151 leaves the
wide layout alone (an inline-block is an atomic inline and exempt) and strikes
the comment's author, timestamp, anchor and body in the stacked one.

The rule that keeps typed text on the page was ported first. A composer holding
a draft inside a fold that is then shut now keeps the block's whole row drawn
rather than a notes row of its own; measured with the rule removed, the
textarea collapses to 0px with the words still in it.
6ed67a73 — Eugene Blikh 9 hours ago
web: say which of the two guards keeps a comment off the map

Mutation-testing the tick sizes turned up a property with two guards and a
test that cannot tell them apart. mapTicks skips a notes row when it adds up a
block's lines — and deleting that skip changes nothing, because a notes row
carries no gutter number on either side and so already reports zero source
lines through diffRow.sourceLines.

Both the check and its test are kept: what would break the property is a notes
row that grows a number, and then the skip is what holds and the test is what
says so. What is not kept is a comment implying the skip is doing the work.
Next