diff --git a/docs/merge-reliability.md b/docs/merge-reliability.md index d4489f21..05c64aec 100644 --- a/docs/merge-reliability.md +++ b/docs/merge-reliability.md @@ -25,7 +25,7 @@ when there is a test or document that exercises the specific merge invariant. | 6. Branch birth always captures merge bases | `crates/forkpress-storage/src/lib.rs` requires branch birth metadata for branch reuse/merge and blocks pending reset states. `tests/cow/git_server.php` covers Git-created branch DB/file base, ID-band, row identity, and cleanup/rollback paths. `tests/cow/e2e.sh` covers public create retry after interrupted birth metadata and public reset retry after interrupted reset publication. | Keep every new creation/reuse/reset path under the same invariant and add regressions whenever a new branch publication path is introduced. | | 7. ID-band enforcement beyond happy paths | `tests/cow/merge.php` covers AUTOINCREMENT allocation, rollback, reset below old bands, independent branch IDs, explicit out-of-band source IDs, child rows behind held explicit post/term/user IDs, inserted and updated scalar/serialized/theme/widget `wp_options`, `wp_posts`, `wp_postmeta`, `wp_comments`, `wp_commentmeta`, `wp_usermeta`, `wp_termmeta`, `wp_term_taxonomy`, `wp_term_relationships`, post-author, taxonomy menu-item, reusable/media/avatar/navigation/query block `post_content`, and comment-user references behind held explicit post/term/user IDs, JSON/serialized references that keep branch IDs distinct, plugin validator review for no-FK child rows behind held explicit plugin AUTOINCREMENT parents, and non-AUTOINCREMENT `INTEGER PRIMARY KEY` plugin graph collisions as review-held. `tests/cow/e2e.sh` verifies runtime branch post IDs fall inside branch bands. | Expand explicit-ID/import handling beyond currently covered AUTOINCREMENT row-insert/rewrite cases and enforce review for more plugin/custom logical identities that are not safely bandable. | | 8. Better stale-audit workflow | `docs/stale-audit-workflow.md` describes the revalidation model. `scripts/cow/merge.php` implements `revalidate-reviews`, `merge-audit --revalidate`, `merge-resolve --after-revalidate`, revalidation classes, source/target drift checks, plugin validator replacement evidence, and plugin replacement conflict links. `tests/cow/merge.php` covers stale row/cell/file drift, source drift, deleted targets, no-PK rowid replacement, supported WordPress semantic fingerprints, guarded resolution, idempotent carried notes, plugin validator rerun evidence through direct and `merge-audit --revalidate` paths, duplicate identical validator rerun handling, and replacement validator conflict ids. | Add broader plugin/schema source-drift evidence, more custom logical-identity classifiers, and guarded plugin/schema-specific resolution flows where appropriate. | -| 9. Release gate issue | `scripts/build-dist.sh` and release preflight tests fail earlier when static-PHP prerequisites are missing, avoid macOS bash empty-array expansion under `set -u` while wrapping Apple Silicon `spc` commands in `arch -arm64`, and `docs/merge-reliability.md` tracks aarch64 macOS as a release gate. | Keep aarch64 macOS release and APFS sparsebundle E2E green before treating Mac artifacts as trustworthy. | +| 9. Release gate issue | The historical PR #45 `build aarch64-apple-darwin` release failure was in `static-php-cli doctor --auto-fix`: Homebrew rejected stale formula metadata with "Potential MITM attempt detected. Please run `brew update`." The current release workflow runs `brew update` and installs the full macOS static-PHP prerequisite set before `scripts/build-dist.sh`; PR #46 release run `25923952364` then built `aarch64-apple-darwin` successfully in job `76200033640`. `scripts/build-dist.sh` still fails earlier when static-PHP prerequisites are missing, avoids macOS bash empty-array expansion under `set -u`, wraps Apple Silicon `spc` commands in `arch -arm64` when needed, and keeps `static-php-cli` pinned. | Keep aarch64 macOS release and APFS sparsebundle E2E green before treating Mac artifacts as trustworthy; treat new release failures as release-infrastructure blockers even when merge tests pass. | ## Current Guarantees @@ -56,7 +56,7 @@ when there is a test or document that exercises the specific merge invariant. | Branch birth | CLI and Git-created branches allocate ID bands and capture merge base metadata. Git-created branches finalize birth metadata before publishing the branch tree, so a pre-metadata crash cannot expose a branch without ID bands or row identities. Existing branches reused by automation must still have a database, DB merge base, filesystem merge base, and required birth metadata before reuse. The WordPress admin branch create/merge UI is covered as a thin wrapper over the same CLI paths, including validation, CLI failure surfacing, and real runtime E2E create/merge requests. | Keep branch create, Git ref create, reset, and UI creation on one invariant: DB base, file base, ID bands, and metadata must exist before user writes. | | ID bands | AUTOINCREMENT bands protect common WordPress and plugin tables. Reset below old bands gets fresh bands. Explicit source IDs outside the reserved branch band are review-held instead of applied automatically for core WordPress and plugin AUTOINCREMENT tables, paired source deletes in the same AUTOINCREMENT table are also held when an out-of-band explicit insert is held, and source child `wp_posts`, owner/reference `wp_postmeta` including inserted and updated type-aware nav menu object refs, inserted or updated scalar/serialized/theme/widget `wp_options` references, inserted or updated `wp_comments`, `wp_commentmeta`, inserted or updated `wp_termmeta`, hierarchical and updated `wp_term_taxonomy`, inserted or primary-key-rewritten `wp_term_relationships`, inserted or updated `wp_usermeta`, inserted or updated post authors, inserted or updated reusable/media/avatar/navigation/query block `post_content` refs, inserted or updated taxonomy menu-item object refs, or inserted or updated comment user refs pointing at held explicit post/term/user IDs are review-held instead of leaving orphan WordPress child rows. Non-AUTOINCREMENT `INTEGER PRIMARY KEY` plugin graph collisions are review-held and auditable as non-bandable tables. | Enforce bands before every write path, expand explicit-ID/import handling beyond covered AUTOINCREMENT row-insert cases, and reject/review unsafe reuse. | | Stale audits | Resolution fails if target no longer matches the audited payload. `forkpress branch revalidate-reviews` and `forkpress branch merge-audit --revalidate` carry stale reviewed conflicts back into `needs-action` while preserving prior reviewer intent, avoiding duplicate carried notes, recording revalidated payloads, linking plugin replacement validator conflicts, and storing a conservative revalidation classifier such as `compatible-target-drift`, `compatible-source-drift`, `missing`, no-primary-key rowid-reuse `incompatible`, supported WordPress primary-key semantic `incompatible`, or plugin `replacement-evidence`. `forkpress branch merge-resolve conflict --after-revalidate` can apply reviewed stale database row/cell and filesystem conflicts only when the current source/target payloads still match the latest revalidation record, the latest classifier is not `incompatible`, and the original logical row still exists. Plugin validator conflicts now return to `needs-action` when a validator rerun records changed evidence for the same plugin object, but remain outside generic guarded resolution; schema conflicts still need schema-specific evidence/planning. `docs/stale-audit-workflow.md` maps the current flow and the remaining richer classifier model. | Add broader source-drift coverage for plugin/schema-specific evidence, broader incompatible classifiers for more primary-key/higher-level semantic identities, and guarded revalidation resolution for plugin and schema conflicts. | -| Release gates | Linux, Windows, and x86_64 macOS release artifacts built in the last checked run. macOS and Linux release workflows install static PHP build prerequisites up front, `scripts/build-dist.sh` now fails before cloning/building PHP if those tools are missing instead of letting `static-php-cli` mutate package-manager state during the release bundle step, avoids macOS bash empty-array expansion under `set -u` while wrapping Apple Silicon `spc` commands in `arch -arm64`, and the default `static-php-cli` checkout is pinned to a known upstream commit with an explicit override for deliberate upgrades. | Keep aarch64 macOS release and APFS sparsebundle E2E green; those gates are required before trusting an M1-ready artifact. | +| Release gates | Linux, Windows, x86_64 macOS, and aarch64 macOS release artifacts built in the last checked release run for PR #46. The older PR #45 aarch64 macOS release failure was caused by stale Homebrew metadata during `static-php-cli doctor --auto-fix`, not by merge logic; the release workflow now runs `brew update` and installs static PHP build prerequisites before `scripts/build-dist.sh`. `scripts/build-dist.sh` fails before cloning/building PHP if those tools are missing instead of letting `static-php-cli` mutate package-manager state during the release bundle step, avoids macOS bash empty-array expansion under `set -u` while wrapping Apple Silicon `spc` commands in `arch -arm64`, and the default `static-php-cli` checkout is pinned to a known upstream commit with an explicit override for deliberate upgrades. | Keep aarch64 macOS release and APFS sparsebundle E2E green; those gates are required before trusting an M1-ready artifact. | ## Test Direction