[Agentic Preview delivery slice] Preserve first raster writes across recovery checkpoints

[Flow-Fly]

Parent

#534 — Public site tools

Sources of truth

• #619 — confirmed fresh-copy first-raster failure and diagnosis
• #523 — approved Agentic Preview specification
• #553 — delivered public Site Tool Facade and PR #617
• #519 — adjacent Shape index-coherence defect, used only to constrain snapshot policy

Authorization and exact dispatch boundary

After the completed #553 production-build playtest reported #619 and proposed “fix #619, then future deployed-client validation,” the owner replied, “Okay, allons-y” on 2026-09-10. Director interpretation: this authorizes the bounded #619 correction through a fresh finalizer-approved, green integration into develop. It does not authorize deployment, promotion to main, or the later deployed-client validation itself.

• Repository: Flow-Fly/pixel-forge
• Branch: dev-619-stable-raster-checkpoint
• Target: develop
• Original starting/red-evidence base: d6d4042bddba54a050442534c32e97da9d8a8c07 (historical evidence only)
• Current immediate integration and quality/Fallow comparison base: ea1352ab7387aed9c052d5a7e8e47ed102ee4068
• Implementation: one Astra Medium delivery-worker
• Review: one fresh Astra High finalizer after the complete draft head is green; follow the repository's fresh-pass rule after any finalizer fix

Exact-base reconciliation — 2026-09-10

Merged PR #616 advanced origin/develop to ea1352ab7387aed9c052d5a7e8e47ed102ee4068. Its changed paths are quality scripts/configuration, workflow and agent documentation, lint/Fallow configuration, and focused quality tests; it has no product-source overlap with #620. Existing draft PR #621 at 212b0993a07cfae6024ae7275e3bede73fecf8e4 is mergeable but behind. Prior candidate certification is stale.

The owner authorization already recorded for #620 covers this routine integration recovery. Merge origin/develop@ea1352ab7387aed9c052d5a7e8e47ed102ee4068 into the existing dev-619-stable-raster-checkpoint branch; a merge commit is preferred so the original red baseline and focused implementation commits remain explicit. Resolve only integration conflicts within the already approved slice. Do not reimplement or alter #616. Any further movement of origin/develop, product-source conflict, or scope change requires a new Director reconciliation.

After the merge, all earlier head-specific evidence and review remain historical. Produce one new exact candidate head, run the new quality workflow against ea1352ab7387aed9c052d5a7e8e47ed102ee4068, obtain green PR checks, and only then dispatch a fresh finalizer.

Linked task issues

• First raster write on a fresh safe copy conflicts with its recovery checkpoint #619 — First raster write on a fresh safe copy conflicts with its recovery checkpoint

Task order: #619 is the sole task and should be one focused implementation commit where practical.

Outcome

The first raster transaction on a newly approved blank safe copy crosses the real pre-write recovery checkpoint once and commits once. Checkpoint capture remains a read-only boundary with respect to the live revision/digest contract, while the detached checkpoint remains a coherent, restorable project snapshot. Ordinary default save/reload preserves a legitimately absent live and serialized index buffer; a pre-existing index buffer is still rebuilt when stale.

Diagnosis retained as the implementation constraint

At the delivered baseline, raster observation at revision 0 digests the blank cel as RGBA. checkpointBeforeFirstWrite() then calls the real recovery target's default saveProject(), which rebuilds the live index buffer without advancing the Project Revision. Raster preflight correctly sees a different representation/digest and refuses the formerly current observation as revision_conflict.

The repair must make checkpoint capture stable and coherent. Blindly using rebuildIndexBuffers: false is insufficient because #519 proves that a live canvas can already contain newer RGBA pixels than its index buffer. The serialized checkpoint must derive or otherwise contain index data coherent with its raster bytes without silently changing the live project beneath the observation/write guard.

Director disposition — live versus serialized indices

Existing tests/browser/symbol-grid.test.ts coverage establishes that raster patch, Undo, and Redo preserve an originally absent live index buffer. This slice therefore preserves that live command representation. A detached recovery checkpoint derives coherent matching index data without mutating live project state. Ordinary default save/reload preserves absent indexData when the live index buffer is legitimately absent; when a live index buffer exists but is stale, default save still rebuilds it under the existing palette growth, color-matching, and shared-canvas identity policy. No raster-command behavior changes are authorized.

Compatibility evidence

With the snapshot-only repair, the first raster write commits, but actual Reject still enters recovery-required at revision 2 in the current WIP; the untouched Golden public journey also detects “mid-journey reload changed public project content” at src/editor/golden-automation-journey.ts:499-508: it observes raster before saveRevision / captureDocument, then ordinary default save silently materializes previously absent indices and reload changes the public digest. The earlier checkpoint side effect masked this. The Golden journey and fixture remain unchanged as an acceptance signal; the smallest default serialization correction is part of this same ProjectStore/animation seam and does not create a second capability.

Acceptance criteria

• A red-before/green-after real Chromium test enters through the normal app, approves a fresh blank safe copy through the shipped local dialogs, performs structure/palette/raster observation at revision 0, starts the run, and submits a one-pixel raster-patch as the first transaction through the public Site Tool facade and actual recovery checkpoint. It commits exactly once at revision 1 with the exact RGBA pixel while preserving the fresh project’s originally absent live index-buffer representation. The detached recovery checkpoint contains a coherent index projection, while ordinary default save/reload keeps legitimately absent serialized indexData absent; the run does not enter recovery-required.
• The regression invokes the public facade/fallback normal-entry path. Existing transport conformance remains green; native execution is exercised only when the supported browser API is available and is not a develop acceptance dependency.
• Checkpoint capture does not mutate the live project's raster/index representation, history, change events, or Project Revision. The observed digest remains valid until a real project or concurrent change occurs.
• The existing digest, expected-revision, target, idempotency, and write-turn/concurrency guards remain intact. A genuinely stale digest or revision is still refused atomically with no partial raster change.
• The detached checkpoint file itself has coherent PNG/raster bytes and palette indices, including a focused pre-existing stale-index fixture equivalent to Shape gestures leave RGBA and palette indices temporarily inconsistent #519's canvas-newer-than-index state. This criterion constrains checkpoint serialization only; it does not require ordinary save to materialize a legitimately absent index buffer and does not repair Shape gestures.
• After the successful first raster commit, genuine Reject completes in the terminal rejected phase rather than recovery-required, with the exact blank checkpoint raster bytes restored. Checkpoint rewind/restore is likewise exact, the edited result remains in the required recovery copy, and the original source project stays untouched. Merely creating or opening a Recovery Copy is not sufficient proof.
• Undo and Redo around the committed raster transaction preserve one history operation, revision semantics, exact RGBA pixels, and the originally absent live index-buffer representation. Detached checkpoint serialization contains coherent matching indices. Ordinary default save/reload preserves absent indices when absent and rebuilds pre-existing stale indices when present; package preparation and reload preserve the same public pixels/digest and continue to satisfy existing artifact checks.
• The already successful [Agentic Preview delivery slice] Expose the public Site Tool Facade and WebMCP fallback #553 lifecycle path remains green, including fresh observation after authority loss, a later raster write, Pause, package checksums, recovery-copy access, renewed approval, and local Accept.

Non-goals

• Repairing Rectangle, Ellipse, Line, or any other Shape gesture tracked by Shape gestures leave RGBA and palette indices temporarily inconsistent #519.
• Changing the public Site Tool facade, JSON Schemas, catalogue, wire format, command IDs, raster digest framing, or Project Revision contract.
• Weakening or removing digest comparison, optimistic concurrency, idempotency, recovery safety, or safe-copy preservation.
• Redesigning project serialization, changing the persisted .pf format, adding a migration, changing palette policy, or broadly refactoring animation/project stores.
• Adding dependencies, backend/provider work, production telemetry, deployment, live-host/model-client acceptance, or promotion to main.

Write boundaries

Production edits are limited to the existing recovery checkpoint capture and project snapshot serialization seams:

• src/editor/creative-run-recovery-boundaries.ts
• src/stores/project-store.ts
• src/stores/animation/store.ts and src/stores/animation/index-buffer.ts only if the smallest coherent non-mutating snapshot projection belongs there

Focused evidence may edit:

• tests/browser/site-tools.test.ts
• tests/editor/site-tool-host.test.ts
• tests/editor/creative-run-recovery.test.ts
• tests/stores/project-serialization.test.ts
• tests/editor/timeline-cel-unlink.test.ts
• tests/browser/creative-run-panel.test.ts
• the smallest existing raster/serialization browser test only if the public normal-entry test cannot directly prove byte/index coherence

The timeline cel-unlink test may update only its old default-save expectation: it must assert that absent live and serialized indices plus shared-canvas identity survive save, while retaining the existing Undo/Redo proof. The Creative Run panel Rewind test may replace its ordinary-save equality assumption with a digest comparison between the stored checkpoint and the actual createProjectRecoveryTarget(...).captureProject() result; it must retain the terminal outcome and revision assertions and should also assert that ordinary save leaves absent indices absent. These changes strengthen compatibility coverage for the approved serialization distinction and do not expand production scope or permit weakening other assertions.

Do not edit Site Tool contracts/transports, command/digest implementations, UI product behavior, shared/, server/, dependency manifests, telemetry, or unrelated documentation. Stop and return to the Director if the repair cannot fit these seams.

Contract and runtime surfaces

• Producer: ProjectStore.saveProject() and any existing animation/index serialization projection it uses, distinguishing ordinary default save from the detached coherent recovery-checkpoint projection.
• Checkpoint caller: createProjectRecoveryTarget().captureProject().
• Guarded write path: CreativeRunController pre-write checkpoint followed by project.raster.patch digest/revision validation.
• Durable recovery consumer: CreativeRunRecoveryCoordinator checkpoint digest, copy, reject, rewind, restore, and reload paths.
• Public proof: normal-entry window.pixelForgeSiteTools.invoke lifecycle and the existing WebMCP/fallback conformance boundary.
• Persisted contract: current ProjectFile; its schema/version and externally visible digest semantics remain unchanged.

Decision and safety gates

The product decision is complete: recovery capture must preserve both a valid current observation and a coherent restorable snapshot. The same bounded seam may make the smallest default-save adjustment needed to preserve legitimately absent live and serialized indices through ordinary save/reload, while continuing to rebuild a pre-existing stale index buffer under the current palette and identity policy. Implementation may choose the smallest pure checkpoint/index projection and ordinary-save adjustment inside the named seam. Stop for Director review if a safe fix requires a file-format/API/schema/digest change, migration, weaker concurrency checks, changed recovery meaning, Shape repair, new telemetry, dependency, backend work, or scope outside one PR.

The original selected project and the fresh safe copy must remain distinct. No recovery path may overwrite unpreserved user work. Automated browser evidence is the acceptance path for this correction; deployed-client validation remains a later owner-controlled #524 gate.

Observability

Decision: none. The failure is deterministic local client state with a direct regression test and existing factual recovery records. Production telemetry would not answer an unresolved operational question and could expose private project state. Tests may retain content-free local command results and screenshots; no new logging or event is added.

Verification

Before resuming implementation, fetch and confirm origin/develop is exactly ea1352ab7387aed9c052d5a7e8e47ed102ee4068, #619 remains ready and unblocked, and PR #621 is the sole delivery PR. Merge that exact develop commit into the existing branch as authorized above. If origin/develop moves again or the merge exposes product overlap, stop for another exact-base handoff.

Retain the independent red baseline from the production build at the original d6d4042bddba54a050442534c32e97da9d8a8c07 commit: qa/baseline-first-pixel.json, .png, and .log in the delivery artifact root. It is historical bug evidence and is not a new-candidate certification. It records revision_conflict, recovery-required, revision 0, and zero committed transactions.

Run the smallest focused unit/browser tests needed to prove every criterion above, including the normal-entry first-raster regression, real recovery restoration, and ordinary save/reload stability. Keep the existing Golden journey and fixture unchanged and make that public lifecycle green through the serialization repair. Then run:

npx tsc --noEmit
npm run lint
npm run quality:verify -- --base ea1352ab7387aed9c052d5a7e8e47ed102ee4068
npm run quality:check -- --base ea1352ab7387aed9c052d5a7e8e47ed102ee4068 --head <exact-candidate-sha>
npm run build
git diff --check

quality:verify is the required producer for the five separate root, Chromium, shared, server, and Worker profiles plus shared Node smoke, runtime-import checks, boundaries, and the policy-aware Fallow comparison. Do not substitute the old bare test:run, test:browser, or fallow:audit summaries for this certification. Record the bundle path, manifest and certification digests, exact profile scopes, commands, inputs, exclusions, and results. Confirm the checkout stays clean at the exact candidate and the comparison base is ea1352ab7387aed9c052d5a7e8e47ed102ee4068.

After CI is green for that exact head, retain its Actions quality artifact ID, digest, and expiry. In a clean finalizer checkout, accept the downloaded bundle read-only with npm run quality:check -- --base ea1352ab7387aed9c052d5a7e8e47ed102ee4068 --head <exact-candidate-sha> --bundle <downloaded-directory>. CI checkout/head provenance, checks, and server-container must all identify the same candidate.

PR #621 remains the sole draft PR targeting develop; keep its canonical Linked task issues list current. Only a fresh exact head with successful focused checks, local quality certification, build, whitespace check, green CI, and downloaded-bundle acceptance may be handed to a fresh finalizer.

Dependencies and later work

Native blocked by: none. #553/PR #617 are merged prerequisites and stay closed as their historical delivery record. #519 is adjacent evidence, carries its own human gate, and is neither linked nor blocked by this slice. After this correction is reviewed green and integrated, deployed-client/live-host validation remains future owner-controlled work under #524; it is not part of this PR.

Delivery record — #619 / PR #621

Delivered through PR #621. Finalizer pass 1 approved candidate 186b6916201e2cf18910393e98665e3188d0c745 without edits or blockers; integration commit aa679c699875765309942f05a24e01fc4785e844 preserves exact base/head parents. Candidate CI 34469433987 and post-merge CI 34474412151 passed. Post-merge quality artifact 10151076640 has digest sha256:3e8a0f4668cafc03da8d588819e0e66c8f6e9da1c42bb21326e87b3c59bf5a5a; its exact clean-checkout bundle acceptance passed with no blockers or advisories.

Fresh local production-build QA passed all six required scenarios in Chrome 152 fallback and Canary 155 native WebMCP, including exact first raster, genuine Rewind and Reject restoration, and complete lifecycle acceptance. The original d6d4042 failure and superseded d945d27 CI attempts remain historical evidence. Deployed pixel-forge.app, external-agent validation, #519 Shape repair, main, and deployment remain outside this slice.

[Flow-Fly]

Director evidence disposition — the snapshot-only repair makes the first raster write commit, but actual Reject still enters recovery-required at revision 2 in the current WIP; the untouched Golden public journey also fails at src/editor/golden-automation-journey.ts:499-508 because ordinary default save materializes a legitimately absent index buffer and changes the public digest after reload. The approved narrow correction is to preserve absent live and serialized indices through ordinary save/reload, continue rebuilding a pre-existing stale index buffer under current palette growth, color-matching, and shared-canvas identity rules, and keep detached recovery checkpoints coherently indexed without mutating live state. This stays inside the existing ProjectStore/animation serialization boundary. The Golden journey and fixture remain untouched acceptance signals; raster commands, #519 Shape repair, digests, wire/schema, and public guards remain unchanged.

[Flow-Fly]

Director test-boundary disposition — full gates exposed two assertions for the superseded serialization assumption. tests/editor/timeline-cel-unlink.test.ts may assert absent live and serialized indices plus shared-canvas identity through ordinary save while retaining Undo/Redo. tests/browser/creative-run-panel.test.ts may compare the stored Rewind checkpoint digest with the real createProjectRecoveryTarget(...).captureProject() result while retaining terminal outcome/revision and preferably proving ordinary save keeps absent indices absent. These are the only newly authorized test files. They cover the already approved ordinary-save versus detached-checkpoint distinction; they do not change production scope, weaken public guards, alter the Golden fixture, or convert interim Reject/Golden failures into success claims.

[Flow-Fly]

Exact-base reconciliation — merged PR #616 advanced origin/develop to ea1352ab7387aed9c052d5a7e8e47ed102ee4068 with quality workflow/configuration changes and no #620 product-source overlap. The existing owner mandate authorizes merging that exact commit into dev-619-stable-raster-checkpoint; merge commit is preferred to preserve the original d6d4042bddba54a050442534c32e97da9d8a8c07 RED baseline and focused repair commits. The worker reports a conflict-free integration at interim head d945d278acc684db30ff2053655d2fee84efbc18, with 77 focused unit tests and 17 focused Chromium tests passing plus one native-API skip. This is not final certification. All evidence tied to pre-integration head 212b0993a07cfae6024ae7275e3bede73fecf8e4 is stale. New acceptance requires an exact clean candidate, quality:verify and quality:check against base ea1352ab7387aed9c052d5a7e8e47ed102ee4068, build and whitespace checks, green CI, downloaded CI-bundle acceptance, then a fresh finalizer on that unchanged head. The original d6d4042 browser RED artifacts remain historical bug evidence only.

[Flow-Fly]

Candidate status — exact head d945d278acc684db30ff2053655d2fee84efbc18 against base ea1352ab7387aed9c052d5a7e8e47ed102ee4068 passes focused tests, typecheck, lint, build, whitespace, and local exact-base quality collection/check. The certified five profiles report 989 root tests, 130 Chromium tests plus one unsupported-native skip, 35 shared tests, 79 server tests, and 13 Worker tests; review.json has blockers: [] and advisories: []. A clean independent checkout accepted the worker bundle. Independent production QA also passes six scenarios through Chrome 152 fallback and Canary 155 native WebMCP: exact first pixel and diamond, genuine Rewind (paused, blank revision 2), genuine Reject (rejected, blank revision 2), and both 12-assertion lifecycles through terminal Accept. Evidence is retained in qa/REPORT.md and qa/production-verification.json. CI run 34466396802 attempt 1 failed five 15-second Chromium cases and the one-second site-tool consent poll before product mutation; local durations were 19–478 ms for the five cases, and the cause is not conclusively established. worker/ci-attempt-1-diagnosis.json supports one unchanged-head failed-job retry without timeout, assertion, fixture, or configuration edits. Attempt 2 reproduced the same six browser failures on the unchanged head. No third blind retry is authorized. Baseline ea1352ab7387aed9c052d5a7e8e47ed102ee4068 CI run 34465718704 is green; its bundle is being used only to compare environment and test durations. The worker is performing bounded diagnosis within the approved serializer seam, including the hypothesis that the five timeouts and safe-copy approval delay share the new PNG decode path after absent indices are preserved. No source edit or scope change is approved by this status record. Keep PR #621 draft and #619 open; do not dispatch finalizer, mark ready, close, or merge until the exact candidate passes CI and its downloaded quality bundle is accepted. After any correction, all affected exact-head evidence and a fresh finalizer are required.

[Flow-Fly]

Director disposition — causal CI ordering repair at 186b691

The repeated Site Tools CI failure now has bounded causal evidence. worker/ci-order-diagnosis.json (SHA-256 ec697f576ad7698f74cde3a6947e5b7d4fcf6ecfeb6c407d4e53e18e4b1ce1e6) maps the failed-run coverage to site-tool-host.ts:154: the first approval returned through the missing/disposed-target guard before any save or copy. The regression test had selected the startup context before asynchronous workspace restoration completed; the existing Golden public journey already waits for drop-handler readiness.

The approved correction at exact PR head 186b6916201e2cf18910393e98665e3188d0c745 adds 15 test lines in the already allowed tests/browser/site-tools.test.ts boundary: wait on the existing readiness barrier, create a fresh project through File → New Project → Create, await its new active-project ID, then capture the original source and run the existing first-raster path. Production code, product assertions, test deadlines, and quality configuration are unchanged. Focused evidence is two passing cases with one supported-API skip.

d945d278acc684db30ff2053655d2fee84efbc18 and its local quality, production QA, and failed two-attempt CI records remain historical evidence for that head only. Full quality verification and new CI are still running on 186b691; the five secondary timeout failures remain unclassified until that run completes. PR #621 stays draft and is not eligible for finalizer, ready state, issue closeout, or merge.

[Flow-Fly]

Exact-head verification accepted; finalizer in progress

PR #621 remains draft at exact head 186b6916201e2cf18910393e98665e3188d0c745 over comparison/quality base ea1352ab7387aed9c052d5a7e8e47ed102ee4068.

• CI run 34469433987 passed on attempt 1: checks in 6m08s and server-container in 1m09s. All six browser failures seen twice at d945d27 disappeared after the bounded startup-order test repair; production code, deadlines, and quality configuration did not change.
• CI quality artifact 10149079318, digest sha256:df03a65de981e73780ca291f29fd00910a8353abba44b6508144039236084dc1, expires 2026-09-24. A clean review checkout accepted the downloaded bundle against exact base/head; evidence is review-ci-quality-check-186b691.log (SHA-256 781b225533a9ec64c3a0429e95d80ff99b19249f9e7b91bafc55b93e4d5fc4f8).
• The exact-head local quality bundle also passed clean acceptance with blockers: [] and advisories: []. Local manifest SHA-256 is 7546221c1d78fbb1af74ff4ea04682bdaa48364a21558de7f44405eebe79aa67.
• Fresh production-build QA passed all six required scenarios at this exact head. qa/REPORT.md SHA-256 is 52e7f31974224158553311100ddca2555f543e0be518364b904ee92f6582bf4b; qa/production-verification.json SHA-256 is f74609ebf50560d54ab5eef48f39b4c9f3f40a1bca1b1b5c77a162403316a4ef. The prior d945d27 QA is archived as historical evidence.

A fresh Astra High finalizer is reviewing this complete unchanged draft head now. PR #621 is not yet eligible for ready state, issue closeout, or merge; eligibility requires an APPROVE verdict on the same head followed by live head/base/check/comment reconciliation.

[Flow-Fly]

Integrated into develop; post-merge gate running

Following finalizer pass 1 APPROVE on unchanged green head 186b6916201e2cf18910393e98665e3188d0c745, the director re-read the live PR state: base ea1352ab7387aed9c052d5a7e8e47ed102ee4068, MERGEABLE/CLEAN, checks and server-container successful, zero unresolved review threads, and no task stop label. The PR body now records the exact-head evidence and the three accepted non-blocking Standards dispositions.

PR #621 was marked ready and merged with exact-head protection. Integration commit: aa679c699875765309942f05a24e01fc4785e844; parents: ea1352ab7387aed9c052d5a7e8e47ed102ee4068 and 186b6916201e2cf18910393e98665e3188d0c745; tree: 688b8f848ba598a96be398b3167b31c5318b076a.

Post-merge CI run 34474412151 is running on the integration commit. #619, #620, and reopened capability #534 remain open until that exact integration run and downloaded quality bundle are accepted. No main promotion, deployment, or next slice is part of this closeout.

[Flow-Fly]

Delivery complete through PR #621, candidate 186b6916201e2cf18910393e98665e3188d0c745, integration aa679c699875765309942f05a24e01fc4785e844. Finalizer pass 1 approved without edits; candidate and post-merge CI passed; post-merge artifact 10151076640 passed clean exact-head acceptance with no Fallow blockers or advisories. All acceptance criteria are checked in the slice body. Deployed-host/external-agent validation, #519, main, and deployment remain excluded.