refactor: enforce explicit build and runtime contracts

[vsxd]

Summary

Make ownership, completion and failure explicit across the photo build and runtime pipelines. Cancelled media work no longer starts queued decoding, failed conversions are not cached as successful results, and stalled downloads and DOM decode errors settle through a consistent error path.

• Separate Builder requests, plugin options and captured build plans; pass the same execution policy to worker and cluster processing and reconcile the actual plugin-adjusted task list.
• Publish deeply readonly photo snapshots with structural sharing and atomic shard hydration. Subscribe React to the snapshot itself so React Compiler cannot retain an outdated getPhotos() result.
• Replace the raw JavaScript Worker and function serialization with a TypeScript module Worker, a shared bidirectional protocol and a separate WebWorker type-check. Preserve late-bitmap cleanup and transferable ownership.
• Remove the logger/context cycle; enforce source dependency boundaries and Web test types; document the contracts and update stale engineering guidance.
• Correct TIFF grayscale/alpha handling, shared conversion cancellation, runtime disposal, download idle timeouts and DOM error reporting. Pre-optimize lazy map dependencies to avoid a first-navigation development reload.

Risk and compatibility

• User-visible behavior: existing features and interface remain; loading failures now report consistently and hydrated details update after the initial summary renders.
• Manifest/config/cache compatibility: Builder manifest v2 and Web delivery v3 remain unchanged. No dependency or lockfile changes. AppRuntime.dispose() now returns a promise for decoder drainage while cancelling and releasing owned resources synchronously.
• Plugin compatibility: invalidation hints remain accepted on BuilderPluginOptions; internally calculated keys are no longer written back into options. Plugins observing effective work must use lifecycle tasks / beforeProcessTasks.processorOptions, rather than deprecated options.plannedKeys. Official plugin and transaction tests pass.
• Privacy, accessibility, performance, or security impact: validation uses synthetic photos. Immutable snapshots share unchanged nodes; active non-interruptible codecs retain their concurrency slot until they finish. Architecture and secret checks protect the submitted sources.

Verification

Checks below passed locally. Contracts, formatting, lint and Vitest were run through the installed tool entrypoints; workspace type-checking and the real static build used the project's cached pnpm 10.19.0. No check thresholds were lowered.

• pnpm contracts — equivalent installed entrypoint; includes source architecture guards.
• pnpm format:check — equivalent installed entrypoint; git diff --check also passes.
• pnpm lint — equivalent installed entrypoint; commit hooks also run formatting and ESLint.
• pnpm type-check — tools/E2E, all workspaces, Web unit tests and the Worker environment.
• pnpm test — coverage run: 196 files, 1,268 tests passed. Global and all four partition thresholds passed (statements/lines 76.25%, branches 79.99%, functions 85.03%).
• pnpm build — exercised through the real build-static.sh deployment smoke with an isolated local-photo fixture and output validation.
• Relevant E2E/deployment smoke checks — 10 production, 10 desktop/touch, and 2 WebKit/iPhone tests passed; four platform-inapplicable cases skipped by existing configuration. Production checks require a real Worker asset and painted canvas, and delay detail hydration to cover snapshot updates.
• Synthetic fixture regeneration: not applicable; fixture data and the manifest wire schema are unchanged.
• Tests and documentation cover new behavior and configuration.
• CHANGELOG.md updated for notable Project Code changes.
• No secrets, private manifests, personal filenames, or exact GPS data are included; repository secret scan passed.

Notes

See docs/engineering-contracts.md for API and ownership rules and docs/engineering-refactor-plan.md for the completed seven-stage plan and validation details. Real S3, large-library stress, physical mobile GPU testing and deployment are outside this verification.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
afilmory	Ready	Preview	Sep 8, 2026 5:46am UTC

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-08T05:53:48.224294Z	84d8b9b	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.