feat: add deterministic visual-change detection for PRs.

[BillLeoutsakosvl346]

Summary

Add an advisory deterministic designer-notification engine for PRs targeting staging. It reads immutable Git objects and flags supported authored appearance changes and custom styling/layout. Wording, media, additional options, unchanged shared-component reuse, pure movement and uncertainty alone are exempt. Results are grouped, bounded JSON artifacts; operational failures exit nonzero with flagged: null.

An optional SQLite index now reuses parsed file facts, revision bindings/references and on-demand appearance queries. Source reads are lazy and bounded; snapshots are immutable; cache corruption/eviction rebuilds work. Generic nested-property propagation and passive media ownership rules have paired regression coverage. Application code, configuration and plugins are never executed by analysis.

Schema 3.0.0, engine 0.6.0, policy 5.0.0, index schema 1.0.0. Existing design:diff invocation remains valid; add --cache-dir, --no-cache and separate --metrics, plus design:index --ref ... --cache-dir ....

Cloud PR jobs restore an isolated cache copy and never save it. A trusted default-branch workflow refreshes staging every 30 minutes, on main pushes or manual dispatch. Reports/metrics remain artifact-only with seven-day retention. Production activation requires main; its absence on this draft PR is not a pass. Caching remains opt-in (DESIGN_DIFF_INDEX_ENABLED, currently unset), because the median paired speedup is below the 3× target. No Slack, screenshots, AI, PR findings comments/labels or merge-check registration are added.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Other: ___________

Testing

Final head 463fa05: Bun 1.4.1, 574 tests / 37 suites passed. Script discovery, design-diff type checks, Biome, API-validation audit, frozen dependency install and actionlint passed. Tests include cross-process reuse, concurrency, restart recovery, corruption/eviction, aliases/unresolved imports, source failures, matching and non-execution.

Final-head cloud smoke passed separate-job cache save/restore, cached/uncached/repeated byte parity, shared Button shape evidence and resolved consumers, comment exemption and explicit missing-revision failure. Artifacts were downloaded and verified. Its fresh-head comparison took 19.74s cold → 4.82s warm, with a 2.60s repeated comparison.

All 180 frozen comparisons completed with 180/180 byte-identical cached and uncached reports, exact comparison commits/file manifests and no operational failures. Each warm run started with only its merge-base indexed; no completed-report cache or previously processed PR head was used. One process per Blacksmith 2-vCPU Ubuntu runner; same method for each paired measurement.

Development sample	Previous flagged	Indexed engine flagged
Original 120	21/120 (17.5%)	21/120 (17.5%)
Historical holdout 60	10/60 (16.7%)	10/60 (16.7%)
Total	31/180 (17.2%)	31/180 (17.2%)

No changed PR qualifications or flagged source groups. Labels were preserved: 149 need review and 31 are provisional; none are adjudicated. The provisional subset still contains five apparent false positives and one uncertain case. Both cohorts are development data; these results establish cache parity, not unseen accuracy or complete recall.

Measurement	Cold	Baseline warm
Median analysis	18.55s	5.56s
p95 analysis	184.91s	171.49s
Maximum analysis	276.11s	269.21s
Median peak RSS	1.67 GiB	1.03 GiB
Maximum peak RSS	3.93 GiB	4.00 GiB

Median per-comparison speedup: 2.908×; the ratio of aggregate median times is 3.335×. The stricter paired target was not met. Baseline setup: 14.45s median, 17.01s p95, 25.84s maximum, measured separately. Largest report: 1.59 MiB. Times exclude runner provisioning/install; stage timers overlap and must not be summed. Broad functional dependency changes still require substantial value resolution, and a few warm cases are slower.

Benchmark engine: 7f2c2fd. Subsequent commits only declare the already-resolved LRU dependency and reject invalid Git blob metadata before cache reads. All 425 frozen commits / 7,983,868 blob entries satisfy the added guard. Final-head local checks and cloud smoke passed; there was no second full 180-case replay after these follow-ups.

Cloud delivery: initial 136 cases, next 41, last 3. The first two workflows were cancelled after their remaining jobs stalled queued; only unprocessed cases were resubmitted. All 180 unique result artifacts were downloaded and validated. These temporary workflows are isolated on codex/design-index-cloud-smoke; no additional PR was opened.

Latest-head CI: 13 passing, 25 skipped, 1 failing, 0 pending. Helm connection test timed out after five minutes; the chart installed but its test hook did not finish. The log does not establish its root cause. Application build/tests, PostgreSQL integration, desktop checks and chart lint passed. No Helm/database files are changed here.

Remaining limitations: query invalidation conservatively tracks observed files/routing in addition to finer property projections; some broad changes still traverse many candidates. Baseline warming prepares file/revision facts, with appearance queries populated on demand. Static consumers are representative references, not confirmed rendered instances. Unsupported runtime styling can be missed under the uncertainty-exemption policy. A fresh independently labeled dataset is still needed for generalization measurement.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

Not applicable; repository automation only. Reports and execution metrics are JSON artifacts.

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 12, 2026 9:45pm UTC