tegwick
250f9a525c
HOH-WP-0002 T01–T03. Public slug is frontmatter id. Rendering lives in hall-render. T04 still needs the operator corpus call. Assistant: grok Assistant-Session: 01a09dc1-b21e-77e1-919e-fcad2f82b267
61 lines
2.3 KiB
Markdown
61 lines
2.3 KiB
Markdown
# ADR 0001 — Hall URI identifier, service shape, and renderer trust
|
|
|
|
Status: accepted
|
|
Date: 2026-09-14
|
|
Workplan: HOH-WP-0002-T01, T02, T03
|
|
|
|
## T01 — URI identifier
|
|
|
|
The public path is:
|
|
|
|
```
|
|
https://helix.coulomb.social/hall-of-helix/<id>
|
|
```
|
|
|
|
`<id>` is the seat frontmatter `id` **verbatim** (example:
|
|
`hall-worker-codex-statehub-snapshot-and-signature`). Uniqueness is already
|
|
enforced by `make check`. The filename is not the URI and may be renamed.
|
|
|
|
The `hall-worker-` prefix stays. Stripping it would require a second
|
|
uniqueness domain; an opaque extra id would be a third name to keep.
|
|
|
|
`id` is URL-safe `[A-Za-z0-9-]+` (mixed case is allowed; several existing
|
|
Claude session ids use it). Once `status` is not `draft`, `id` is frozen.
|
|
Corrections edit the body, not the identifier.
|
|
|
|
`?renderer=` is optional; omitting it equals `renderer=default`.
|
|
|
|
## T02 — Where the service lives
|
|
|
|
This repo stays a **publication** corpus. Rendering is a sibling tooling
|
|
repo, conventionally `hall-render`. Do not execute renderer code from this
|
|
repository.
|
|
|
|
First delivery is **static generation**: `hall-render` reads this repo at a
|
|
pinned commit and emits HTML. The renderer set is known at build time.
|
|
Dynamic on-request execution is declined for v1 (publication classification
|
|
plus XSS surface).
|
|
|
|
Deployment target: reef-railiance k3s, private/static objects behind the
|
|
existing Traefik ingress. DNS `helix.coulomb.social` is a railiance-infra /
|
|
railiance-cluster record, not owned by this publication repo. No live
|
|
publish until T04 (operator corpus disposition).
|
|
|
|
## T03 — Renderer contract and trust
|
|
|
|
`renderer` is user-controlled input that selects code. Rules:
|
|
|
|
1. Resolve only through a **fixed allowlist** in `hall-render`. Never treat
|
|
the parameter as a path, module, package, or URL.
|
|
2. Unknown values return 404 (static: missing artifact). Do not fetch or
|
|
import.
|
|
3. A renderer receives parsed Markdown plus frontmatter and returns markup.
|
|
No credentials, filesystem, or network.
|
|
4. Output is sanitised before it is a page. HTML from a renderer is an XSS
|
|
sink.
|
|
|
|
Registration is an in-repo allowlist in `hall-render`, not reuse-surface
|
|
(that catalog is capability discovery, not a safe code-execution index).
|
|
|
|
Input: `{frontmatter, markdown, entry_id}`. Output: `{html}`. Default
|
|
renderer is named `default` and is the only one in the first allowlist.
|