ci(v2): real-install command harness — run the read-only safe surface live (closes Track V)#59
Merged
Merged
Conversation
…e (closes Track V)
actools-pl
force-pushed
the
phaseV/V2-command-harness
branch
from
0192aa5 to
83b964e
Compare
actools-pl
added a commit
that referenced
this pull request
Jun 30, 2026
…ack E) (#61) ## What modules/backup/ carries the live daily backup generator (cron.sh) plus a ten-file PITR/encrypted draft cluster, and across them a backup artifact is named, located, time-stamped, encrypted, and checksummed three incompatible ways. Wiring the encrypted backup (E2) and binlog/PITR (E3) would cement those three dialects unless one contract is fixed first. E1 fixes it — behavior-free: a doc + a guard + the ledger. New docs/backup-format-contract.md — the canonical source of truth for backup-artifact shape. It transcribes the live (A) format exactly from cron.sh and the restore arm (cli/actools:241): ${INSTALL_DIR}/backups/<env>_db_<YYYY-MM-DD>.sql.gz (+ .sha256), content gzip(mariadb-dump --single-transaction --quick actools_<env>), flat directory, daily timestamp, 7-day retention, integrity-or-delete, and the umask-077 --defaults-extra-file password shape. It then defines the canonical scheme X (naming grammar <env>_<kind>_<timestamp>.<ext>[.age][.sha256]; Age encryption with the .sha256 taken over the ciphertext; the PITR nested layout rooted under ${INSTALL_DIR}/backups/; the secure password shape mandatory for every producer) and a divergence ledger recording, per dialect, where the encrypted (B) and PITR (C) drafts diverge from X and what E2/E3 must do to conform. B and C are marked TARGET / NOT YET LIVE throughout. New tests/guards/backup_format_contract_guard_test.bats — pins ONLY the live (A) producer<->consumer agreement at this baseline, mirroring the discipline of cron_security_shape_guard_test.bats. It renders the live cron through the existing tests/helpers/capture_backup_cron.sh and asserts the producer DB pattern (<env>_db_<…>.sql.gz under a backups/ root), the .sha256 integrity sidecar + sha256sum -c, the restore consumer's default glob agreeing on the same root/stem/extension, and the consumer checksum convention. Two permanent non-vacuity arms doctor the producer stem (_db_ -> _database_) and the restore glob on OFF-TREE scratch copies and assert the agreement oracle FAILS ("CONTRACT DRIFT: producer writes '…' but the restore consumer globs '…'"); the repo is never modified. Discovered by the recursive bats job (lint.yml: bats -r tests/) — no workflow edit. ## Gate Behavior-free — no producer, consumer, draft, module, or golden is touched; nothing executable changes, so no branch e2e is required (like C1/D1b/D2/V1). Runtime-authority-changes: none (cli/actools, cron.sh, all modules byte-identical). ## Scope / verification - Scope = 3 files: docs/backup-format-contract.md (new), tests/guards/backup_format_contract_guard_test.bats (new), and docs/runbooks/PHASE0_LEDGER.md (Entry 031 + ratify Entry 030). - bats -r tests/: 241 -> 247 (+6 new arms, all green); the 12 pre-existing jq-dependent secrets/state failures are environmental and unchanged (no regression). - cron.sh, cli/actools, the 10 draft files, tests/fixtures/golden/backup-cron/*, capture_backup_cron.sh, and modules/host/age.sh are byte-identical to baseline c17197f. - Author actools-pl <feezixmp@gmail.com>; no Co-authored-by. Ledger: add Entry 031 (E1, Pending); ratify Entry 030 (V2, c17197f/#59, closes Track V), original Pending text preserved verbatim. Entries 029..001 byte-identical. REVIEW (guard non-vacuity + doc-vs-code spot checks) then DOC-CHECK (the contract doc is the primary deliverable) follow. The coding window does not self-approve.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Turns the V1 matrix's documented command contracts into executed ones. Extends the
real-install e2e (
.github/workflows/e2e.yml) — which ran onlyaudit+doctor(2 of 30) — to run the read-only safe surface against the live VM after install,
asserting each command's matrix signature/exit. Three steps appended after "Run
doctor (smoke)"; the working provision/deploy/audit/doctor steps untouched.
status,log-dir,dry-run,migrate,help,storage-info,redis-info,slow-log,pdf-test,each asserting a stable header/token;
worker-statusasserting exit 0), plustls-statusandoom.logs,stats,worker-logs) under a remotetimeout; exit 124 ≡ clean stream;statsassertsCONTAINER.audit --ci, asserting CI mode (banner suppressed +PASS=summary),additively — the existing
audit cigate andaudit.share untouched.CI-coverage rises 2 → 17 of 30. The 13 skipped: 7 mutating (incl.
tunnel),2 interactive, 1 destructive, 3 read-only with an unmet external dependency.
Verified live
Branch e2e green on the read-only surface — including
worker-status, which nowbootstraps because the worker image carries phpredis (WR, #60, landed first). This
entry ratifies WR.
tls-status/oomexercised green.Finding recorded (not re-wired)
audit ci≠audit --ci: the existing gate invokesaudit ci→ default mode →grep PASS≥10sound;audit --ciis the CI-mode path, now pinned by Step C.Verification
output.sh:26/report.sh:14; env facts verified from the deploy step.tunnelskip-class harmonized to mutating (matrix summary + ledger).e2e.yml,live-verification-matrix.md,PHASE0_LEDGER.md);product/audit code byte-identical; author
actools-pl <feezixmp@gmail.com>.