Design notes

Tracked, citeable design records: the model behind a mechanism, the options weighed, and the decisions taken. Nothing here is normative -- a note binds no implementation, and points at the spec for the normative rows rather than restating them. A note opens with a status line stating where its subject stands, from a direction still open to a decision taken and built.

Index

Note	Status
abort-marker-retryable-class.md	Design only, not built; waits on an observed base rate. The classless default is final.
agent-hooks-and-scripts.md	Decided and built; the rationale and stated limits behind the agent hooks and session scripts whose headers state only their contract.
app-shell-service-worker.md	Decided and built.
backup-import-per-exchange-guard.md	Decided on the maintainer's ruling and built.
bound-transformed-value.md	Decided and built, by a 3-panelist design panel.
broker-runtime-closure.md	Decided and built.
browser-sftp-proxy.md	Design only, not built; the product scope and seven other choices are left open.
cascade-fan-out.md	Directed; the spec has landed, the realization is pending.
claude-md-spawn-cost.md	Decided and built; what each spawn type receives, the orchestrator-only share under two partitions, and the split taken against it.
cli-webrtc-attempt-cycle.md	Decided on the maintainer's ruling and built, after a real-broker measurement.
cli-webrtc-stack.md	Decided and built.
cloudflare-turn-sizing.md	Measured; cost per GB unmeasured, and nothing decided or built.
column-name-display.md	Decided and built; why the operator's own column names are isolated rather than escaped, and what isolation leaves open.
comment-history-narration-check.md	Decided and built; the corpus measurement and the false-positive rate behind the check's phrase list.
connect-timeout-prior-art.md	Decided and built; what curl and OpenSSH bound, measured, and the three decisions taken on it.
connection-error-kind-taxonomy.md	Decided and built; each classification records the condition that would reopen it.
connection-per-poll-sftp.md	Shipped.
console-announce-and-focus.md	Decided and built, by a 3-panelist design panel deciding 2-1.
console-signing-identity-custody.md	Decided on the maintainer's ruling; the refusal is built, the identity-location option is not.
core-dist-cache-buildinfo.md	Decided and built; supersedes an earlier cache-side decision.
cosign-keyless-signing.md	Decided and built.
cross-workspace-test-material.md	Decided and built.
deduplicate-matching-semantics.md	Specified, and run end to end: the one-sided cardinalities under both linkage strategies, the both-sided one under cascade.
default-linkage-rule-set.md	Decided and built.
failure-cause-catalog.md	Decided and built.
fan-out-matching-resolution.md	Built under single-pass; the cascade realization stays open work.
fips-provider-surface.md	Measurement, plus two decisions taken on it; whether to pursue a FIPS claim at all remains open.
fips-variant-image.md	Decided, built, and published.
folded-column-name-lookup.md	Decided on the maintainer's ruling and built; the options weighed and what the fold changes for a configuration with no metadata block.
hash-keyed-value-lookup.md	Decided and built; the three lookup keys measured at 2^24 and why the hash was taken.
hosted-environment-opentofu.md	Decided and applied; the resources it held no longer exist.
key-establishment-fips-boundary.md	Decided and implemented; the post-quantum hybrid and dual signing wait on three runtimes, measured 2026-10-28.
linkage-rule-catalog.md	Proposed; bands the shipped keys and proposes the rest, each rule with its precision band and evidence.
linkage-rule-grounding.md	Proposal, pending adoption -- nothing here is adopted or shipped.
lockless-rendezvous-barrier.md	Weighed and set aside; the shipped symmetric barrier stands.
managed-exchange-design.md	Decided and built; the grace window is proposed in rotation-hardening.md and not built.
one-sided-disclosure.md	Resolved - shipped as the opt-in single-pass linkage strategy (the cascade stays the default).
one-sided-fuzzy-expansion.md	Decided, built, and applied.
operator-message-control-characters.md	Decided and built.
output-directory-removal-lock.md	Measurement backing the retry's wall-clock budget.
payload-as-agreed-terms.md	Decided on the maintainer's ruling, after a 3-panelist design panel; not built.
portable-configuration-readers.md	Rule decided and specified, the unread-key refusal built; the audit of each reader and the two gaps it leaves open.
prebuild-provenance.md	Decided, built, and armed against a fork that attests.
psi-c-count-only.md	Directed by the maintainer's rulings; the spec has landed, the rebuild is pending, and the shipped build is the earlier one-key construction. Missing-field conditions and single-pass are admitted; candidate sets stay refused as an interim limit.
rebase-reattestation.md	Decided on the maintainer's ruling and built; the fourth mechanical re-attestation path and the limits it accepts.
receipt-run-binding.md	Resolved - built.
receipt-signing-fips-boundary.md	Decided.
record-durability-point.md	Resolved - built.
rename-to-alcove.md	Decided on the maintainer's rulings and built.
repo-check-scripts.md	Decided and built; the rationale and stated limits behind the repository check scripts whose headers state only their contract.
reported-failure-cause.md	Decided on the maintainer's ruling and built; the two shapes declined, and what the block holds apart that escaping does not.
rotation-hardening.md	Design only, not built; proposed for ratification, with two choices left open.
rule-set-citation-verdict.md	Resolved - built, then withdrawn on the maintainer's ruling removing the citation.
sftp-adapter-state-machine.md	Shipped.
shared-consent-summary.md	Shipped.
signing-identity-custody.md	Decided and built, by a 3-panelist design panel converging 3-0.
standing-relay-delivery.md	Decided, the reference is written, and the first deployment has driven a relayed exchange through it.
turn-provisioning-governance.md	Surveyed, with a recommendation per profile; nothing decided or built, and the configuration shape left to separate work.
wasm-parallel-evaluation.md	Both arms measured, and the browser direction decided: Web Worker sharding, with the pthreads/SIMD build declined; the web exchange runs the worker pool for the party creating the request, one worker for the party answering it and on macOS.
web-server-runtime-role.md	End state reached for the public deployment: a static site, with the framework's server half removed; the console keeps its server.
web-websocket-transport.md	Design only, not built; the WebSocket relay for networks that stop TURN recommended first, the browser SFTP forks re-answered for the public web application, and seven choices left open.
webrtc-frame-structure-envelope.md	Decided and built, by a 3-panelist design panel converging 3-0 on the retirement and 2-1 on the ceiling.
webrtc-memory-measurements.md	Measurement history; the current figures are in the spec.
webrtc-outbound-packer.md	Decided and built, by a 3-panelist design panel deciding 2-1; the measured ceiling it removes and the one it leaves.
webrtc-relay-deployment.md	Measured, with a recommendation and a proposed epic; the recommendation is now deployed and verified against the standing relay.

Each note states its full status at its own top; this table is a pointer, not a restatement.

The maturity ladder:

• scratch/ (gitignored) - personal, throwaway thinking, no audience.
• docs/notes/ (here) - tracked, citeable design records; non-normative.
• docs/ proper - the formal, living documentation, in two tiers:
  • docs/ (overview) - conceptual and operational documents for program officers, security reviewers, compliance officers, IT staff, and new contributors.
  • docs/spec/ - the technical specification tier: wire formats, byte encodings, protocol internals, and implementation-level design, written for implementors and auditors. See docs/spec/README.md for the index and routing guide.

Naming: notes use lowercase-kebab filenames to distinguish them at a glance from the SCREAMING_CASE formal specs in docs/ and docs/spec/.