Skip to content

Commit 8efe4f7

Browse files
authored
Merge pull request #166 from decipherhub/feat/154-append-only-deploy-evidence
feat(deploy): complete, append-only production evidence (#154)
2 parents a821a13 + 20ba677 commit 8efe4f7

29 files changed

Lines changed: 3223 additions & 177 deletions

‎DECISIONS.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1768,6 +1768,160 @@ Dates and assignees for the four P2 PR slots remain for team confirmation.
17681768
- `docs/compliance/spec-sheets/A-01_sanctions.spec.md`
17691769
- `docs/ROADMAP.md`
17701770

1771+
## D037: Versioned complete production commitments require clean Git for broadcast
1772+
1773+
Date: 2026-11-11. Issue #154. Status: implemented default, team-to-confirm.
1774+
1775+
### Context
1776+
1777+
A manual source list omitted the imported production deployer. HEAD alone could
1778+
not distinguish changed sources or a copied source-only bundle from a clean
1779+
release, and did not commit the compiler/build/orchestration inputs.
1780+
1781+
### Decision
1782+
1783+
Production evidence version 2 uses canonical domain-separated SHA-256 source,
1784+
build and evidence identities. Resolve compiler inputs from the production entry
1785+
point; include the deployer, transitive contracts, exact configuration/remappings,
1786+
orchestration, lockfiles, tool/dependency identities, compiler settings and
1787+
creation/runtime bytecode commitments. Compile a captured isolated workspace,
1788+
exclude inherited build overrides and verify copied bytes before execution.
1789+
1790+
Record HEAD plus explicit clean/dirty/source-only/unavailable provenance, with
1791+
staged, unstaged, untracked and recursive submodule evidence. Dirty, unavailable
1792+
and source-only provenance permits diagnostics but blocks production broadcast.
1793+
Before granting clean provenance, compare captured bytes with HEAD blobs,
1794+
following committed submodule gitlinks independently of index visibility flags.
1795+
Bind canonical configuration, deployment ID, chain and wiring into evidenceId;
1796+
plans, unsigned exports, review evidence and deployment records must agree.
1797+
1798+
### Consequences
1799+
1800+
Offline source hashing requires the pinned Forge/Solc toolchain. Repository,
1801+
package and runtime copies preserve source/build commitments, but a source-only
1802+
package cannot claim clean Git through an upstream commit string. New broadcast
1803+
requires independently reviewed clean Git-backed inputs. Exact tool/runtime
1804+
changes require a new identity and review. Key management, custody and multisig
1805+
expansion remain deferred; the existing local Foundry account needs no vendor.
1806+
1807+
### Related Files
1808+
1809+
- `services/toolkit/src/production-evidence.ts`
1810+
- `services/toolkit/src/production.ts`
1811+
- `services/cli/scripts/prepare-package.mjs`
1812+
- `docs/deployment-production.md`
1813+
1814+
## D038: Production envelopes publish exclusively after validation
1815+
1816+
Date: 2026-11-11. Issue #154. Status: implemented default, team-to-confirm.
1817+
1818+
### Context
1819+
1820+
Overwriting copies could replace reviewed artifacts, and exclusive writes alone
1821+
could expose incomplete files. Interruption after broadcast needs a recovery
1822+
path that preserves evidence without repeating transactions.
1823+
1824+
### Decision
1825+
1826+
Reserve a vacant destination before signing/broadcast. Generate in a unique
1827+
sibling operation directory; the production Solidity script writes only a
1828+
candidate inside its captured workspace. Validate successful canonical receipts,
1829+
receipt-derived addresses, exact transaction inputs/order, reconstructed runtime
1830+
bytecode, ownership/operator/wiring and Safe state before publication.
1831+
1832+
Reservation setup is transactional before the operation is returned to the
1833+
caller. A failure while writing operation pointers, probing hard-link/fsync
1834+
semantics or performing the final vacancy check removes the reservation and
1835+
staging directory. If filesystem cleanup itself fails, the typed error reports
1836+
the exact staging and reservation paths and marks cleanup incomplete; signing or
1837+
broadcast has not started and the incomplete setup is not recoverable as an
1838+
execution journal.
1839+
1840+
Require the staging/output directories and every ancestor to be owned by the
1841+
current uid or root. Reject group/world write permissions on staging/output;
1842+
allow writable ancestors only with the sticky bit, which protects operator-owned
1843+
entries from other users. Reject foreign ownership even on sticky ancestors and
1844+
reject application symlinked ancestry. The existing macOS `/tmp` and `/var`
1845+
system aliases have their `/private` target ancestry checked too. Check existing
1846+
output ancestry before creating directories, then check the output directory
1847+
before reserving anything. Check staging on creation and recheck both paths at
1848+
publication/recovery, naming the offending path on failure.
1849+
1850+
This StrictModes-like precondition is the filesystem trust boundary: publication
1851+
is safe against other local principals, with root trusted. Concurrent operator
1852+
uid processes are out of scope because they already hold the operator's signing
1853+
material. Node has no fd-based `linkat`/`unlinkat`; path checks cannot eliminate
1854+
replacement races against writers within that trust boundary.
1855+
1856+
Publish by exclusive no-follow creation and file fsync, validate through a
1857+
no-follow descriptor held across the no-replacement
1858+
hard link, then verify the final regular file's device, inode and size. On mismatch,
1859+
attempt cleanup only after verifying the output directory/ancestry again and
1860+
rechecking the observed entry's identity. Cleanup and its parent fsync are best
1861+
effort, preserving the original publication error. The separate identity check
1862+
and unlink do not protect against same-uid replacement immediately before unlink.
1863+
Parent fsync, staging-link cleanup and another fsync complete publication. Never
1864+
use a replacing rename; unsupported semantics fail closed. Apply the same
1865+
publisher to signable exports. The raw-byte publisher preserves imported signed
1866+
bytes without reserialization.
1867+
1868+
Persist immutable journal events. Recovery rebuilds and revalidates staged
1869+
commitments, receipts and chain state before publication/cleanup. It never
1870+
signs, automatically rebroadcasts or overwrites an existing final artifact.
1871+
1872+
### Consequences
1873+
1874+
Pre-link failure leaves no final. Post-link interruption may leave a complete
1875+
final, which recovery verifies before cleanup. Failed broadcast/verification
1876+
retains the captured workspace and journal. Missing evidence/RPC access blocks
1877+
recovery. Broadcast uses Foundry --slow to preserve transaction/hash association.
1878+
Local SIGKILL and injected I/O tests do not establish power-loss durability or
1879+
support for untested filesystems.
1880+
1881+
### Related Files
1882+
1883+
- `services/toolkit/src/production-publication.ts`
1884+
- `services/toolkit/src/production-chain.ts`
1885+
- `services/cli/src/commands.ts`
1886+
- `script/DeployProductionCore.s.sol`
1887+
1888+
## D039: Preserve legacy readers and require version 2 for new production releases
1889+
1890+
Date: 2026-11-11. Issue #154. Status: implemented default, team-to-confirm.
1891+
1892+
### Context
1893+
1894+
Existing public-testnet records and consumers must remain usable while stronger
1895+
production evidence becomes mandatory for new deployments.
1896+
1897+
### Decision
1898+
1899+
Keep legacy artifacts and review files in their original schema and readable
1900+
through existing readers. Do not rewrite or upgrade published records. New
1901+
production deployments require evidence version 2. Version 1 review evidence
1902+
cannot authorize a new production deployment.
1903+
1904+
Version 2 verification requires the reviewed evidenceId, rebuilt local
1905+
source/build/configuration commitments and an independently trusted expected
1906+
recordDigest. The record binds the script artifact digest, transaction inputs,
1907+
receipts and evidence identity without circular hashes. A version 2 expectation
1908+
cannot fall back to legacy verification.
1909+
1910+
### Consequences
1911+
1912+
Compatibility tests enumerate existing public records, pin the published Monad
1913+
record hash, read exact files through the CLI and read-only Operator API and
1914+
compare bytes afterward. No live-chain readiness is needed to prove readability.
1915+
Public Monad runtime, deployment infrastructure and deployed contracts remain
1916+
unchanged. Legacy readability does not imply version 2 verification guarantees.
1917+
1918+
### Related Files
1919+
1920+
- `scripts/test-production-legacy-artifacts.mjs`
1921+
- `services/cli/src/commands.ts`
1922+
- `services/toolkit/examples/production-evidence.example.json`
1923+
- `services/toolkit/examples/production-evidence-v2.example.json`
1924+
17711925
## D043: Primary Distributor Authority for EXEC-002
17721926

17731927
### Status

‎FEATURES.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,77 @@
99

1010
동시에 하나의 feature만 `active` 상태로 둔다.
1111

12+
## DEPLOY-004: Complete and Append-Only Production Evidence
13+
14+
### Behavior
15+
16+
- Evidence version 2 binds resolved compiler inputs, the production deployer,
17+
orchestration, exact tool/dependency identities, compiler settings and bytecode
18+
templates through canonical domain-separated SHA-256 commitments.
19+
- Plans, unsigned exports, reviewed evidence and deployment records share one
20+
evidenceId over source/build/provenance, configuration, chain and wiring.
21+
Clean Git provenance is required for broadcast. Dirty, source-only and
22+
unavailable provenance supports diagnostics only.
23+
- Production artifacts and signable exports reserve destinations and publish
24+
complete validated envelopes exclusively through fsync and hard-link creation.
25+
Receipts, reconstructed runtime bytecode, owners/operators and wiring must
26+
verify before deployment publication. Reservation setup rolls back staging and
27+
reservation state on failure; typed errors expose exact paths if rollback also
28+
fails. Recovery revalidates returned operations without rebroadcast.
29+
- Publication requires current-uid/root-owned staging/output directories and
30+
ancestry, without group/world writes except sticky ancestors. Trust is checked
31+
before reservation and again at publication; mismatch cleanup is best effort
32+
inside verified output ancestry. Same-uid concurrency is outside this boundary.
33+
- Version 2 verification requires the independently trusted recordDigest and
34+
reviewed evidence identity. Legacy artifacts/review files remain readable;
35+
legacy review evidence cannot authorize new deployments. Public Monad records,
36+
contracts and demo runtime remain unchanged.
37+
38+
### Verification
39+
40+
- Toolkit/CLI source/build/provenance mutation, package/runtime equivalence,
41+
publication failure/concurrency/SIGKILL/recovery and chain tampering tests.
42+
- Review regressions replace staged entries/parents during linking, reject
43+
unsafe staging ownership/permissions, preserve another writer's final, and
44+
block hidden index-flag edits, submodule edits and missing HEAD blobs.
45+
- Trust-boundary regressions reject writable/foreign-owned ancestry and output
46+
directories before reservation, accept sticky ancestors, recheck before linking
47+
and skip mismatch cleanup in untrusted output directories.
48+
- Reservation fault injection covers operation/reservation/probe writes, file and
49+
directory fsync, hard-link probes, successful rollback and typed cleanup paths.
50+
- Packed clean Git-backed consumer: real production dry-run/fork, export,
51+
deployment and verification with one evidenceId; source-only broadcast denial.
52+
- Existing public artifact listing, pinned hash, CLI/Operator API reads and
53+
exact byte preservation without live-chain readiness checks.
54+
- `scripts/check.sh`, both `scripts/e2e-anvil.sh` profiles,
55+
`scripts/e2e-context-provenance.sh`, `scripts/e2e-identity-evidence.sh`,
56+
whitespace and protected-path comparisons.
57+
58+
### State
59+
60+
passing
61+
62+
### Notes
63+
64+
- Issue #154; D037-D039 defaults adopted, team-to-confirm.
65+
- Publication trust-boundary recheck verified on 2026-11-11: seven new guards
66+
failed before implementation; all 20 publication cases now pass. Toolkit 74/74,
67+
CLI 19/19, legacy 2/2 and the full gate passed, including 50 packed production
68+
assertions and live Anvil deployment/recovery. See the latest PROGRESS entry.
69+
- Review hardening on 2026-11-17 makes `reserve()` transactional before return;
70+
six setup faults leave no reservation/staging state, and failed cleanup returns
71+
a typed error with exact operator cleanup paths.
72+
- Review fixes verified on 2026-11-11: 1,171 Foundry tests, 66 Toolkit/19 CLI
73+
named tests, 50 packed production assertions and two public compatibility
74+
cases. Legacy profiles passed 7/7 each; context 12/12; identity 40/40.
75+
An unrelated RFQ nonce-order assertion failed once; isolated RFQ and the full
76+
rerun passed. See PROGRESS for attempts and logs.
77+
- Plan: `docs/exec-plans/completed/DEPLOY-004-append-only-production-evidence.md`.
78+
- Main remains at 7893021 as of the step 3 sequencing check. Prerequisite PRs
79+
must merge before release; this authorized work proceeds on the supplied stack.
80+
- Key management, custody and multisig expansion remain deferred. No external
81+
vendor, production-chain broadcast or public deployment is part of this work.
82+
1283
## DATA-004: Operator-Accepted Identity Evidence and Topology Guards
1384

1485
### Behavior

0 commit comments

Comments
 (0)