ltcai 10.6.2 → 10.7.0

package/latticeai/core/workspace_runs.py

@@ -434,6 +434,117 @@ class WorkspaceRuns:
             runs = [run for run in runs if run.get("workflow_id") == workflow_id]
         return {"runs": list(reversed(runs[-max(1, min(limit, 300)):]))}
 
+    def list_combined_runs(
+        self,
+        *,
+        limit: int = 20,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Merge agent + workflow runs into one ``started_at``-descending timeline.
+
+        Response shape is the product contract for Act screen 09 and the
+        layout-rebuild activity feed: each row carries ``source``, a human
+        ``title``, stop/resume affordances, and normalized timestamps.
+        """
+        capped = max(1, min(int(limit or 20), 100))
+        state = self.load_state()
+        agent_runs = self._scoped(_listify(state.get("agent_runs")), workspace_id)
+        workflow_runs = self._scoped(_listify(state.get("workflow_runs")), workspace_id)
+        combined: List[Dict[str, Any]] = []
+        for run in agent_runs:
+            combined.append(self.activity_run_row(run, source="agent"))
+        for run in workflow_runs:
+            combined.append(self.activity_run_row(run, source="workflow"))
+        combined.sort(key=lambda row: str(row.get("started_at") or ""), reverse=True)
+        total = len(combined)
+        return {
+            "runs": combined[:capped],
+            "total": total,
+            "truncated": total > capped,
+        }
+
+    @staticmethod
+    def _first_string(*values: Any) -> str:
+        for value in values:
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        return ""
+
+    @classmethod
+    def activity_run_title(cls, run: Dict[str, Any]) -> str:
+        """Public title resolver shared by list_combined_runs and router fallbacks."""
+        direct = cls._first_string(
+            run.get("workflow_name"),
+            run.get("name"),
+            run.get("goal"),
+            run.get("title"),
+            run.get("query"),
+        )
+        if direct:
+            return direct
+        raw_input = run.get("input")
+        if isinstance(raw_input, str) and raw_input.strip():
+            return raw_input.strip()
+        if isinstance(raw_input, dict):
+            nested = cls._first_string(
+                raw_input.get("goal"),
+                raw_input.get("name"),
+                raw_input.get("title"),
+                raw_input.get("query"),
+                raw_input.get("text"),
+                raw_input.get("prompt"),
+            )
+            if nested:
+                return nested
+        return ""
+
+    @classmethod
+    def activity_run_row(cls, run: Dict[str, Any], *, source: str) -> Dict[str, Any]:
+        """Normalize an agent or workflow run into the Act activity-feed row shape.
+
+        Public so API routers (e.g. automation_intelligence fallback) can reuse
+        the same contract without reaching for a private method.
+
+        ``source`` is the product discriminator for the 레시피/목표 badge.
+        Legacy agent runs may lack ``agent_id`` (and both ids may be None) —
+        those rows must still leave this method with ``source="agent"`` so the
+        Act feed does not collapse every goal row into a recipe badge.
+        """
+        status = str(run.get("status") or "")
+        started_at = (
+            run.get("started_at")
+            or run.get("created_at")
+            or run.get("updated_at")
+            or ""
+        )
+        finished_at = (
+            run.get("finished_at")
+            or run.get("completed_at")
+            or run.get("resolved_at")
+            or run.get("interrupted_at")
+        )
+        run_id = run.get("id") or run.get("run_id")
+        normalized_source = str(source or "").strip().lower()
+        if normalized_source not in {"agent", "workflow"}:
+            # Infer only when the caller failed to pin a valid source; prefer
+            # workflow_id when present, otherwise agent (including bare legacy).
+            if run.get("workflow_id"):
+                normalized_source = "workflow"
+            else:
+                normalized_source = "agent"
+        return {
+            "id": run_id,
+            "source": normalized_source,
+            "title": cls.activity_run_title(run),
+            "status": status,
+            "started_at": started_at,
+            "finished_at": finished_at,
+            "can_stop": status in RUN_ACTIVE_STATUSES,
+            "can_resume": status in {"awaiting_approval", "paused", "waiting_approval"},
+            "workflow_id": run.get("workflow_id"),
+            "agent_id": run.get("agent_id"),
+        }
+
     def mark_workflow_run_resolved(
         self, run_id: str, *, resumed_run_id: str, approved: bool,
         workspace_id: Optional[str] = None,

package/latticeai/services/architecture_readiness.py

@@ -16,7 +16,7 @@ from typing import Any, Dict, List
 
 from latticeai.core.legacy_compatibility import legacy_shim_report
 
-ARCHITECTURE_VERSION_TARGET = "10.6.2"
+ARCHITECTURE_VERSION_TARGET = "10.7.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/product_readiness.py

@@ -18,7 +18,7 @@ from typing import Any, Dict, List
 
 from latticeai.services.architecture_readiness import architecture_readiness
 
-PRODUCT_VERSION_TARGET = "10.6.2"
+PRODUCT_VERSION_TARGET = "10.7.0"
 
 
 @dataclass(frozen=True)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "10.6.2",
+  "version": "10.7.0",
   "description": "Lattice AI — local-first Digital Brain that keeps your knowledge durable across any AI model.",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
@@ -24,7 +24,8 @@
     "build:assets": "vite build && node scripts/build_frontend_assets.mjs",
     "build:python": "node scripts/run_python.mjs -m build",
     "check:python": "node scripts/run_python.mjs scripts/check_python.py",
-    "lint": "npm run lint:python && node --check tests/visual/mock_server.cjs && node --check tests/visual/v3.spec.js && npm run lint:frontend && npm run frontend:openapi:check && node scripts/check_i18n_literals.mjs && npm run check:i18n-namespaces && npm run check:bundle && npm run check:legacy-debt && npm run test:browser-extension && npm run test:vscode-extension",
+    "lint": "npm run lint:python && node --check tests/visual/mock_server.cjs && node --check tests/visual/v3.spec.js && npm run lint:frontend && npm run frontend:openapi:check && node scripts/check_i18n_literals.mjs && npm run check:i18n-namespaces && npm run check:bundle && npm run check:legacy-debt && npm run test:browser-extension && npm run test:vscode-extension && node scripts/check_release_evidence_bound.mjs",
+    "check:release-evidence-bound": "node scripts/check_release_evidence_bound.mjs",
     "check:legacy-debt": "node scripts/check_legacy_debt.mjs",
     "lint:python": "node scripts/run_python.mjs -m ruff check . && npm run typecheck:python",
     "lint:frontend": "node scripts/lint_frontend.mjs",
@@ -48,7 +49,8 @@
     "desktop:tauri:check": "cd src-tauri && cargo check",
     "desktop:electron": "electron desktop/electron/main.cjs",
     "package:vsix": "node scripts/build_vsix.mjs",
-    "release:evidence": "node scripts/capture_release_evidence.mjs && node scripts/prune_release_evidence.mjs",
+    "check:screenshot-delta": "node scripts/run_python.mjs scripts/check_screenshot_pixel_delta.py",
+    "release:evidence": "node scripts/capture_release_evidence.mjs && node scripts/prune_release_evidence.mjs && npm run check:screenshot-delta",
     "release:evidence:prune": "node scripts/prune_release_evidence.mjs",
     "release:artifacts": "node scripts/clean_release_artifacts.mjs $npm_package_version && npm run build:assets && npm run build:python && npm pack && npm run package:vsix && npm run desktop:tauri:build",
     "release:validate": "node scripts/run_python.mjs scripts/validate_release_artifacts.py $npm_package_version --require-vsix --require-tgz --require-dmg",

package/scripts/capture_release_evidence.mjs

@@ -1,4 +1,5 @@
 import { chromium } from "playwright";
+import { createHash } from "node:crypto";
 import { execFileSync, spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
@@ -7,10 +8,243 @@ const repoRoot = process.cwd();
 const version = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
 const port = Number(process.env.LTCAI_RELEASE_EVIDENCE_PORT || 4936);
 const baseURL = `http://127.0.0.1:${port}`;
-const root = path.join(repoRoot, "output", "release", `v${version}`);
+// Defaults to the published directory for this version, but can be redirected.
+// This script starts by deleting `root` outright, so anything that wants a
+// preview capture — a reviewer checking whether the UI actually moved before
+// the version is bumped — would otherwise have to overwrite the screenshots of
+// an already-released version to get one.
+const root =
+  process.env.LTCAI_RELEASE_EVIDENCE_DIR ||
+  path.join(repoRoot, "output", "release", `v${version}`);
 const screenshots = path.join(root, "screenshots");
 const videos = path.join(root, "videos");
 const gifs = path.join(root, "gifs");
+const manifestPath = path.join(repoRoot, "static", "app", "asset-manifest.json");
+
+function assetManifestFingerprint() {
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  const body = fs.readFileSync(manifestPath);
+  const stat = fs.statSync(manifestPath);
+  return {
+    sha256: createHash("sha256").update(body).digest("hex"),
+    mtime: stat.mtime.toISOString(),
+    bytes: body.length,
+  };
+}
+
+const mockServerPath = path.join(repoRoot, "tests", "visual", "mock_server.cjs");
+
+function mockServerFingerprint() {
+  if (!fs.existsSync(mockServerPath)) {
+    return null;
+  }
+  const body = fs.readFileSync(mockServerPath);
+  const stat = fs.statSync(mockServerPath);
+  return {
+    sha256: createHash("sha256").update(body).digest("hex"),
+    mtime: stat.mtime.toISOString(),
+    bytes: body.length,
+  };
+}
+
+/**
+ * Refuse to overwrite published release screenshots for an already-tagged version.
+ *
+ * Failure mode this catches: package.json is still 10.6.3, tag v10.6.3 exists
+ * (the shipped release), and capture writes into output/release/v10.6.3/,
+ * silently replacing the public screenshots of a released version with WIP UI.
+ * Preview captures must use LTCAI_RELEASE_EVIDENCE_DIR (any path other than the
+ * default published dir). To land new evidence under output/release/, bump the
+ * package version first so the tag name no longer collides.
+ *
+ * Guard runs *before* wiping `root`, so a tagged release is never deleted by
+ * an unbumped recapture.
+ */
+function assertNotOverwritingTaggedRelease() {
+  const defaultRoot = path.join(repoRoot, "output", "release", `v${version}`);
+  const writingToPublished = path.resolve(root) === path.resolve(defaultRoot);
+  if (!writingToPublished) {
+    // Explicit LTCAI_RELEASE_EVIDENCE_DIR redirect (preview) — allowed even
+    // when the version tag already exists.
+    return;
+  }
+
+  let tagExists = false;
+  try {
+    execFileSync("git", ["rev-parse", "--verify", `refs/tags/v${version}`], {
+      cwd: repoRoot,
+      stdio: "pipe",
+    });
+    tagExists = true;
+  } catch {
+    tagExists = false;
+  }
+  if (!tagExists) {
+    return;
+  }
+
+  console.error(
+    `release evidence: git tag v${version} already exists.\n` +
+      `  Refusing to overwrite ${path.relative(repoRoot, defaultRoot)}/ — that would\n` +
+      `  replace the published screenshots of an already-released version with WIP UI.\n` +
+      `  Bump the package version first (e.g. node scripts/run_python.mjs scripts/bump_version.py),\n` +
+      `  or set LTCAI_RELEASE_EVIDENCE_DIR to a non-published path for a preview capture.`,
+  );
+  process.exit(1);
+}
+
+/**
+ * Refuse to capture when the release lint gate is red.
+ *
+ * Failure mode this catches: lint is failing (e.g. ruff F841) but
+ * capture still runs and writes 12 screenshots + SCREENSHOT_INDEX.md
+ * bound to the asset manifest — evidence that looks green while the
+ * first CI stage would already have stopped. Capture is not proof that
+ * the tree is releasable; lint must pass first.
+ *
+ * Guard runs *before* wiping `root`, so a red lint never deletes the
+ * last good evidence directory.
+ */
+function assertLintClean() {
+  console.log("release evidence: running npm run lint before capture…");
+  try {
+    // Skip the evidence↔build binding gate during intentional recapture:
+    // this run is about to wipe and rebind SCREENSHOT_INDEX.md. Day-to-day
+    // `npm run lint` still hard-fails when screenshots are stale.
+    execFileSync("npm", ["run", "lint"], {
+      cwd: repoRoot,
+      stdio: "inherit",
+      env: { ...process.env, LTCAI_SKIP_RELEASE_EVIDENCE_BOUND: "1" },
+    });
+  } catch (err) {
+    const code = err && typeof err === "object" && "status" in err ? err.status : 1;
+    console.error(
+      "release evidence: npm run lint failed — capture aborted.\n" +
+        "  Fix lint (ruff / frontend / openapi / i18n gates) before release:evidence.\n" +
+        `  exit status: ${code}`,
+    );
+    process.exit(typeof code === "number" && code !== 0 ? code : 1);
+  }
+}
+
+/**
+ * Refuse to capture when static/app is older than frontend/src.
+ *
+ * Failure mode this catches: someone edits frontend/src, skips
+ * `npm run build:assets`, then runs release:evidence. Screenshots look
+ * "fresh" (new mtimes) but still show the previous build. That shipped
+ * stale evidence in 10.6.3 (asset mtime later than screenshot mtime by
+ * 42–50s). Warn-and-continue is useless — exit 1 so CI and humans stop.
+ *
+ * Guard runs *before* wiping `root`, so a stale build never deletes the
+ * last good evidence directory.
+ */
+function assertBuiltAssetsFresh() {
+  const srcRoot = path.join(repoRoot, "frontend", "src");
+  if (!fs.existsSync(manifestPath)) {
+    console.error(
+      "release evidence: static/app/asset-manifest.json 이 없습니다.\n" +
+        "실행 전에 npm run build:assets 를 돌려라.",
+    );
+    process.exit(1);
+  }
+  if (!fs.existsSync(srcRoot)) {
+    console.error(`release evidence: frontend/src 가 없습니다: ${srcRoot}`);
+    process.exit(1);
+  }
+
+  let newestSrcMtime = 0;
+  let newestSrcPath = srcRoot;
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const mtime = fs.statSync(full).mtimeMs;
+      if (mtime > newestSrcMtime) {
+        newestSrcMtime = mtime;
+        newestSrcPath = full;
+      }
+    }
+  };
+  walk(srcRoot);
+
+  const manifestMtime = fs.statSync(manifestPath).mtimeMs;
+  if (newestSrcMtime > manifestMtime) {
+    const rel = path.relative(repoRoot, newestSrcPath);
+    console.error(
+      "release evidence: frontend/src 가 static/app 빌드보다 더 새롭습니다.\n" +
+        `  최신 소스: ${rel}\n` +
+        `  소스 mtime:  ${new Date(newestSrcMtime).toISOString()}\n` +
+        `  빌드 mtime:  ${new Date(manifestMtime).toISOString()} (static/app/asset-manifest.json)\n` +
+        "실행 전에 npm run build:assets 를 돌려라.",
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * Detect evidence that was captured against a *previous* asset build.
+ *
+ * Failure mode: capture runs (screenshots mtime T0), then someone rebuilds
+ * assets (manifest mtime T1 > T0). The pre-guard only compares src vs
+ * manifest, so it still passes — but screenshots no longer show the build
+ * that will ship. Recording the manifest sha256 in SCREENSHOT_INDEX.md at
+ * capture time, then refusing to trust a mismatched index, closes that hole.
+ *
+ * Day-to-day gate: `scripts/check_release_evidence_bound.mjs` (in npm run
+ * lint) hard-fails on sha mismatch. This pre-capture check is different —
+ * when someone deliberately runs release:evidence after build:assets, the
+ * existing index is *expected* to be stale; we continue, wipe, and rebind.
+ * Set LTCAI_RELEASE_EVIDENCE_REQUIRE_BOUND=1 to refuse wipe-and-rebind
+ * (useful in CI that should never recapture from a dirty tree).
+ */
+function assertExistingEvidenceStillBoundToBuild() {
+  const indexPath = path.join(root, "SCREENSHOT_INDEX.md");
+  if (!fs.existsSync(indexPath)) return;
+  const index = fs.readFileSync(indexPath, "utf8");
+  const match = index.match(/asset-manifest\.sha256:\s*`?([0-9a-f]{64})`?/i);
+  if (!match) {
+    // Older captures predate binding — this run will rebind after wipe.
+    console.warn(
+      "release evidence: existing SCREENSHOT_INDEX.md has no asset-manifest.sha256 binding.\n" +
+        "  Recapture will record the current build fingerprint.",
+    );
+    return;
+  }
+  const recorded = match[1].toLowerCase();
+  const current = assetManifestFingerprint();
+  if (!current) return;
+  if (recorded === current.sha256) return;
+
+  const msg =
+    "release evidence: SCREENSHOT_INDEX.md is bound to a different asset build.\n" +
+    `  recorded sha256: ${recorded}\n` +
+    `  current  sha256: ${current.sha256}\n` +
+    `  current  mtime:  ${current.mtime}\n` +
+    "Evidence screenshots are stale relative to static/app.";
+  if (process.env.LTCAI_RELEASE_EVIDENCE_REQUIRE_BOUND === "1") {
+    console.error(
+      `${msg}\n  LTCAI_RELEASE_EVIDENCE_REQUIRE_BOUND=1 — refusing wipe/rebind.\n` +
+        "  Unset the flag and re-run release:evidence to recapture, or restore the matching build.",
+    );
+    process.exit(1);
+  }
+  console.warn(
+    `${msg}\n  Continuing: this run will wipe and rebind evidence to the current build.\n` +
+      "  (Day-to-day lint still fails on stale evidence via check_release_evidence_bound.mjs.)",
+  );
+}
+
+assertNotOverwritingTaggedRelease();
+assertLintClean();
+assertBuiltAssetsFresh();
+assertExistingEvidenceStillBoundToBuild();
 
 // A release capture must be reproducible and must never retain partial videos
 // from an interrupted prior run.
@@ -42,6 +276,59 @@ async function shot(page, name) {
   await page.screenshot({ path: path.join(screenshots, name), fullPage: true });
 }
 
+// The README's hero GIF is this session's screen recording, and 26 of its 79
+// frames were the route-level Suspense fallback ("Brain 작업공간을 여는 중...",
+// App.tsx PageLoader): every screen visited below is a separate lazy chunk, so a
+// cold headless capture pays that chunk's parse cost on first visit and records
+// an empty shell instead of the product. A third of the walkthrough published in
+// the README was therefore a loading screen. Preloading the route chunks once,
+// while the Brain home is already on screen, makes the recording show the
+// screens a person came to see rather than the loader between them.
+//
+// The asset base is read from the module script the page already loaded instead
+// of being hardcoded, so moving the static mount cannot quietly turn this into a
+// no-op — and resolving zero chunks throws rather than shipping a blank GIF.
+async function preloadRouteChunks(page) {
+  const chunks = [
+    ...new Set(fs.readFileSync(manifestPath, "utf8").match(/assets\/[A-Za-z0-9_-]+\.js/g) ?? []),
+  ];
+  if (!chunks.length) {
+    throw new Error(`release evidence: no route chunks found in ${manifestPath}`);
+  }
+  const loaded = await page.evaluate(async (names) => {
+    const entry = document.querySelector('script[type="module"][src]');
+    if (!entry) return 0;
+    const base = new URL(entry.src, location.href).href.replace(/assets\/[^/]+$/, "");
+    let done = 0;
+    await Promise.all(
+      names.map(
+        (name) =>
+          new Promise((resolve) => {
+            const link = document.createElement("link");
+            link.rel = "modulepreload";
+            link.crossOrigin = "anonymous";
+            link.href = base + name;
+            link.onload = () => {
+              done += 1;
+              resolve();
+            };
+            link.onerror = () => resolve();
+            document.head.appendChild(link);
+          }),
+      ),
+    );
+    return done;
+  }, chunks);
+  if (loaded === 0) {
+    throw new Error(
+      `release evidence: preloaded 0 of ${chunks.length} route chunks — the ` +
+        "walkthrough would record the loading fallback instead of the screens",
+    );
+  }
+  await page.waitForTimeout(250);
+  return { loaded, total: chunks.length };
+}
+
 async function main() {
   await waitForServer();
 
@@ -93,6 +380,12 @@ async function main() {
   await page.locator("main[aria-label='Lattice Brain']").waitFor();
   await shot(page, "04-brain-chat-home.png");
 
+  const preload = await preloadRouteChunks(page);
+  console.log(
+    `release evidence: preloaded ${preload.loaded}/${preload.total} route chunks ` +
+      "so the walkthrough records screens, not the loading fallback",
+  );
+
   await page.goto(`${baseURL}/app#/knowledge-graph`, { waitUntil: "networkidle" });
   await page.locator("[data-testid='brain-cytoscape']").waitFor();
   const graphSearch = page.locator(
@@ -176,10 +469,35 @@ async function main() {
     gifTarget,
   ], { stdio: "ignore" });
 
+  const fingerprint = assetManifestFingerprint();
+  if (!fingerprint) {
+    throw new Error("asset-manifest.json missing after capture — cannot bind evidence");
+  }
+  const mockFp = mockServerFingerprint();
+  if (!mockFp) {
+    throw new Error("tests/visual/mock_server.cjs missing after capture — cannot bind evidence");
+  }
+  // Post-capture binding: if a later build:assets changes the manifest hash,
+  // or mock_server.cjs changes the capture payloads, check_release_evidence_bound.mjs
+  // will refuse to trust these screenshots without a recapture.
   const index = `# v${version} Release Evidence
 
 Captured from the built React/Vite app served by the release visual API on ${new Date().toISOString()}.
 
+## Build Binding
+
+Evidence is only trustworthy while this fingerprint matches
+\`static/app/asset-manifest.json\` **and** \`tests/visual/mock_server.cjs\`.
+A later \`build:assets\` or mock-server edit without recapture invalidates the
+screenshots even when their mtimes look fresh.
+
+- asset-manifest.sha256: \`${fingerprint.sha256}\`
+- asset-manifest.mtime: \`${fingerprint.mtime}\`
+- asset-manifest.bytes: ${fingerprint.bytes}
+- mock-server.sha256: \`${mockFp.sha256}\`
+- mock-server.mtime: \`${mockFp.mtime}\`
+- mock-server.bytes: ${mockFp.bytes}
+
 ## Screenshots
 
 | File | Flow |
@@ -203,6 +521,22 @@ Captured from the built React/Vite app served by the release visual API on ${new
 - [v${version}-living-brain-walkthrough.gif](gifs/v${version}-living-brain-walkthrough.gif)
 `;
   fs.writeFileSync(path.join(root, "SCREENSHOT_INDEX.md"), index);
+
+  // Post-hoc: re-hash the manifest *now* and refuse if it drifted mid-run
+  // (e.g. a parallel build:assets while Playwright was shooting).
+  const after = assetManifestFingerprint();
+  if (!after || after.sha256 !== fingerprint.sha256) {
+    console.error(
+      "release evidence: asset-manifest.json changed during capture.\n" +
+        `  bound:    ${fingerprint.sha256}\n` +
+        `  current:  ${after ? after.sha256 : "(missing)"}\n` +
+        "Rebuild was not stable — delete evidence and re-run after a single build:assets.",
+    );
+    process.exit(1);
+  }
+  console.log(
+    `release evidence bound to asset-manifest sha256=${fingerprint.sha256.slice(0, 12)}… mtime=${fingerprint.mtime}`,
+  );
 }
 
 try {

package/scripts/check_current_release_docs.mjs

@@ -6,7 +6,7 @@ const root = process.cwd();
 const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
 const version = pkg.version;
 const releaseDir = `output/release/v${version}`;
-const releaseTheme = "Ask First";
+const releaseTheme = "Plain Surface";
 const title = `${version} — ${releaseTheme}`;
 const escapedVersion = version.replaceAll(".", "\\.");
 

package/scripts/check_release_evidence_bound.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Post-capture evidence ↔ build binding gate.
+ *
+ * Failure mode
+ * ------------
+ * 1. `npm run release:evidence` writes screenshots (mtime T0).
+ * 2. Someone runs `npm run build:assets` again (manifest mtime T1 > T0).
+ * 3. The pre-capture guard only compares frontend/src mtime vs manifest mtime,
+ *    so it still passes — while screenshots show an older UI than the build.
+ *
+ * Also: capture hits tests/visual/mock_server.cjs for API payloads. Changing
+ * the mock after capture (e.g. taller Act panel → 1846px vs committed 1721px)
+ * left asset-manifest.sha256 alone, so this gate used to stay green while
+ * SCREENSHOT_INDEX.md described a UI the tree no longer produces.
+ *
+ * Capture records asset-manifest.sha256 and mock-server.sha256 in
+ * SCREENSHOT_INDEX.md. This script fails (exit 1) when either binding is
+ * missing or does not match the live file. Wired into `npm run lint` so a
+ * green lint cannot ship stale screenshots.
+ *
+ * Exit 0 bound, 1 stale/missing, 2 could not run.
+ *
+ * Escape hatch: LTCAI_SKIP_RELEASE_EVIDENCE_BOUND=1 (used only by
+ * release:evidence while it intentionally wipes and rebinds evidence).
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const repoRoot = process.cwd();
+
+if (process.env.LTCAI_SKIP_RELEASE_EVIDENCE_BOUND === "1") {
+  console.log(
+    "release evidence binding: skipped (LTCAI_SKIP_RELEASE_EVIDENCE_BOUND=1)",
+  );
+  process.exit(0);
+}
+
+const version = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
+const root =
+  process.env.LTCAI_RELEASE_EVIDENCE_DIR ||
+  path.join(repoRoot, "output", "release", `v${version}`);
+const indexPath = path.join(root, "SCREENSHOT_INDEX.md");
+const manifestPath = path.join(repoRoot, "static", "app", "asset-manifest.json");
+const mockServerPath = path.join(repoRoot, "tests", "visual", "mock_server.cjs");
+
+function fail(message, code = 1) {
+  console.error(message);
+  process.exit(code);
+}
+
+function sha256File(filePath) {
+  return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+if (!fs.existsSync(indexPath)) {
+  fail(`release evidence binding: missing ${path.relative(repoRoot, indexPath)}`);
+}
+if (!fs.existsSync(manifestPath)) {
+  fail("release evidence binding: static/app/asset-manifest.json missing", 2);
+}
+if (!fs.existsSync(mockServerPath)) {
+  fail("release evidence binding: tests/visual/mock_server.cjs missing", 2);
+}
+
+const index = fs.readFileSync(indexPath, "utf8");
+const match = index.match(/asset-manifest\.sha256:\s*`?([0-9a-f]{64})`?/i);
+if (!match) {
+  fail(
+    "release evidence binding: SCREENSHOT_INDEX.md has no asset-manifest.sha256.\n" +
+      "  Re-run npm run release:evidence so the index records the build fingerprint.",
+  );
+}
+
+const mockMatch = index.match(/mock-server\.sha256:\s*`?([0-9a-f]{64})`?/i);
+if (!mockMatch) {
+  fail(
+    "release evidence binding: SCREENSHOT_INDEX.md has no mock-server.sha256.\n" +
+      "  Capture data comes from tests/visual/mock_server.cjs; re-run\n" +
+      "  npm run release:evidence so the index records the mock fingerprint.",
+  );
+}
+
+const recorded = match[1].toLowerCase();
+const current = sha256File(manifestPath);
+const mtime = fs.statSync(manifestPath).mtime.toISOString();
+
+if (recorded !== current) {
+  fail(
+    "release evidence binding: screenshots are stale relative to static/app.\n" +
+      `  recorded sha256: ${recorded}\n` +
+      `  current  sha256: ${current}\n` +
+      `  current  mtime:  ${mtime}\n` +
+      "  Rebuild happened after capture. Run: npm run build:assets && npm run release:evidence",
+  );
+}
+
+const recordedMock = mockMatch[1].toLowerCase();
+const currentMock = sha256File(mockServerPath);
+const mockMtime = fs.statSync(mockServerPath).mtime.toISOString();
+
+if (recordedMock !== currentMock) {
+  fail(
+    "release evidence binding: screenshots are stale relative to mock_server.cjs.\n" +
+      `  recorded mock-server.sha256: ${recordedMock}\n` +
+      `  current  mock-server.sha256: ${currentMock}\n` +
+      `  current  mtime:  ${mockMtime}\n` +
+      "  Mock API payloads changed after capture. Run: npm run release:evidence\n" +
+      "  (bump version first if vX.Y.Z is already tagged — see docs/OPERATIONS.md).",
+  );
+}
+
+console.log(
+  `release evidence binding ok: asset=${current.slice(0, 12)}… mock=${currentMock.slice(0, 12)}… mtime=${mtime} dir=${path.relative(repoRoot, root)}`,
+);