marcopan
c7338969d7
prepare records an immutable manifest of every regular backend/dist file (path/size/sha256/dev/ino) in the owned root and binds its record identity in ownership; serve revalidates record and every file before spawn, passes the manifest to the child on fd 4, and the immutable preload hash-verifies all files at startup and serves only cached verified bytes for any import below backend/dist, so imported dependency replacement is refused before RUNNING or never executes. The render command validates the commit snapshot.json manifest, binds snapshot bytes to the manifest digest and the installed Git blob, and passes the expected digest to the renderer, which revalidates head/files digest with bounded no-follow reads and renders only verified bytes with lease release on refusal.
108 lines
8.1 KiB
Markdown
108 lines
8.1 KiB
Markdown
# P1 manual configuration acceptance
|
|
|
|
This walkthrough is an independent human gate for the P1 workspace configuration process. The
|
|
reviewer—not the helper—performs the HTTP, Git, export, rendering, and `tht` checks and judges the
|
|
result. Automation never creates `VERDICT.md`, never records PASS, and never consumes or copies
|
|
`.artifacts/p1-integration`.
|
|
|
|
## Prerequisites
|
|
|
|
From a clean repository checkout, Task 8 must already be implemented. Install Node/npm, `python3`,
|
|
and Git, `curl`, `unzip`/`zipinfo`, `lsof`, and the harness development environment so
|
|
`harness/.venv/bin/tht` is executable.
|
|
Ports `127.0.0.1:8791` and `127.0.0.1:8792` must be free. The helper builds and serves only the
|
|
production backend; it does not start Docker or the frontend.
|
|
|
|
## Lifecycle
|
|
|
|
Run these commands from the repository root:
|
|
|
|
```bash
|
|
./scripts/p1-manual-acceptance.sh prepare
|
|
./scripts/p1-manual-acceptance.sh serve
|
|
./scripts/p1-manual-acceptance.sh stop
|
|
./scripts/p1-manual-acceptance.sh cleanup
|
|
```
|
|
|
|
All four actions serialize on the stable repository-root
|
|
`.p1-manual-acceptance.lifecycle.lock`; the helper retains and revalidates repository, artifact,
|
|
manual-parent, and owned-root identities throughout each transaction. `prepare` acquires that lock
|
|
before prerequisite checks and the backend build, exclusively creates
|
|
`.artifacts/manual-acceptance/p1/`, and immediately publishes a `PREPARING` ownership record before
|
|
populating the lab. That ownership-first record makes an interrupted population cleanable. A
|
|
successful prepare atomically advances it to `READY` after creating fresh Git history, fixtures,
|
|
secret files, concrete request/inspection commands, `GUIDE.md`, and the single regular
|
|
`logs/backend.log` with mode `0600`. It records the log identity and the production entrypoint's
|
|
path/device/inode/size/SHA-256, creates no supervisor or readiness-status file, leaves status
|
|
`PENDING` and the server stopped, and refuses an existing root. Use guarded `stop` and `cleanup`
|
|
rather than deleting or reusing state manually.
|
|
|
|
`serve` revalidates the bound `backend/dist/server.js` identity and bytes, the immutable
|
|
post-build manifest of every regular `backend/dist` file (path, size, SHA-256, device, inode),
|
|
every owned root/runtime/log ancestor, the absence of a legacy supervisor, and the original log
|
|
identity before spawning. The log, the production entrypoint, and the distribution manifest are
|
|
opened with no-follow semantics; the entrypoint and manifest descriptors are passed directly to the
|
|
child, and an immutable preload makes Node load the already verified entrypoint bytes and the
|
|
complete verified `backend/dist` module graph rather than a later pathname replacement. At startup
|
|
the preload hash-verifies every manifest file and serves only those cached verified bytes for any
|
|
import below `backend/dist`, so a same-path regular replacement is refused (before or during
|
|
serving) and can never execute. The child remains the production Node entrypoint itself:
|
|
`node --import data:text/javascript;base64,<immutable-preload> backend/dist/server.js` followed by
|
|
six ownership, control, and entrypoint-identity arguments (plus the manifest descriptor on fd 4).
|
|
The preload owns the authenticated fixed `127.0.0.1:8792` control channel and bounded watchdog, and
|
|
tracks the HTTP server that this same process successfully binds to `127.0.0.1:8791`. Before publishing the
|
|
`RUNNING` PID record, the parent requires exact nonce-bound control acknowledgements that identify
|
|
that owned listener, a 2xx `GET /health`, stable listener generation and entrypoint identity, and a
|
|
final authenticated status check. A foreign health listener cannot satisfy readiness. A startup or
|
|
non-2xx failure requests nonce-authenticated STOP (or lets the watchdog self-exit) and leaves no PID
|
|
record after the child exits.
|
|
|
|
`stop` revalidates the exact executable, immutable preload, bound production entrypoint identity and
|
|
bytes, arguments, repository cwd/root, and process start identity, then requests STOP over the
|
|
nonce-authenticated cooperative channel and requires the exact acknowledgement. The controlled
|
|
process closes its owned listener and exits itself; the tool never sends a numeric terminating
|
|
signal. Ambiguous, stale, or starting records remain for operator inspection. `cleanup` uses opened,
|
|
no-follow directory identities to rename and remove only the exact stopped owned fixed root. Foreign
|
|
siblings and automated integration artifacts are outside its cleanup boundary.
|
|
|
|
After `prepare`, follow the 14 ordered steps in the generated absolute-path `GUIDE.md`. Personally run each generated `http-01` through `http-14` curl script in numeric order; they save the exact status, three validation, three sequential publication, pull, three read responses, and three ZIP exports. Each publication derives its current base commit with a bounded parser from the preceding saved API response, with no placeholder base. Run the five numbered negative validation scripts separately at checklist step 10. The render commands validate the bounded saved read response,
|
|
its commit-addressed owned snapshot path, the saved publish commit, the installed Git HEAD, and the
|
|
bounded `snapshot.json` manifest of that commit: they bind the snapshot bytes to the manifest digest,
|
|
the saved revision blob to the manifest revision, and the manifest blob to the installed Git commit
|
|
(`git rev-parse <commit>:workspaces/<id>.yaml` plus `git hash-object` of the snapshot bytes) before
|
|
calling the acceptance-only production renderer with the expected `--snapshot-sha256`. The renderer
|
|
revalidates the bounded `snapshot.json` (`head`, `files[<id>.yaml]`) and reads the snapshot exactly
|
|
once with no-follow semantics, rendering only the digest-verified bytes. It imports the built
|
|
`ThtRunner`, resolves bindings from environment paths, copies one lease with mode `0600` through an
|
|
opened no-follow `rendered` directory descriptor, rejects an output-parent identity swap, and
|
|
releases the lease in `finally`. For each exported ZIP, invoke the generated extractor with the exact expected workspace ID
|
|
(`p1-filesystem`, `p1-http`, or `p1-s3`); its `python3` helper opens the source once, stages and
|
|
revalidates its SHA-256, anchors every extraction and cleanup operation to an opened no-follow
|
|
`exports/extracted` directory descriptor, and binds both the manifest and parsed descriptor identity
|
|
to that expected ID. It verifies exactly four regular entries and publishes only their exact checked
|
|
bytes. The generated secret scan reads bounded filesystem content and name/path bytes outside the
|
|
direct `fixture-secrets` payload directory, discovers every bounded `.git` repository under the lab
|
|
(plus the owned bare remote), and enumerates every reachable or unreachable object. It
|
|
scans raw blob, commit, tree, and tag bytes plus loose-ref names. Findings and operational diagnostics
|
|
redact canary-bearing paths and values. The absence gate rejects directories as well as files,
|
|
including the canonical `artifacts/evidence` tree and preprocessing, materialization, embedding,
|
|
Qdrant, ACTIVE, or retention names. Do not inspect or print raw secret-file contents; only inspect
|
|
ownership/mode/path metadata and canary absence outside `fixture-secrets`.
|
|
|
|
## Failures and verdict
|
|
|
|
On failure, run `stop` if the owned server is running and preserve the entire fixed root for review.
|
|
Do not run `cleanup` until evidence is no longer needed. A reviewer creates `VERDICT.md` only after the
|
|
walkthrough, containing:
|
|
|
|
- reviewer identity;
|
|
- UTC timestamp;
|
|
- an explicit result for every one of the 14 generated checklist steps;
|
|
- observations and failure evidence;
|
|
- exactly `manual acceptance: PASS` or `manual acceptance: FAIL`.
|
|
|
|
Passing `bash scripts/test-p1-manual-acceptance.sh` proves only that the tooling guards work. It does
|
|
not perform or approve manual acceptance and leaves the project-level manual status PENDING.
|
|
|
|
Expected safe outcomes are one production Node PID owning both listeners on `127.0.0.1:8791` and the authenticated control port `127.0.0.1:8792`; 2xx positive responses; non-2xx negative validations without Git or snapshot mutation; an empty render diff; two successful `tht config check` calls; no manifest, Evidence/export, secret, or out-of-scope-artifact finding; and no PID or listener on either port after `stop`.
|