@oscharko-dev/keiko-evidence 0.2.0

package/dist/qualityIntelligence/figmaSnapshot/store.js

@@ -0,0 +1,898 @@
+// Immutable Figma Snapshot evidence store (Epic #750, Issue #753, ADR-0023 "extend, don't fork").
+//
+// Persists an assembled Figma Snapshot as a WRITE-ONCE JSON record `<runId>.figma-snapshot.json`
+// under the evidence `qi/` subdir, with the rendered PNG bytes written as binary side-files under
+// `qi/figma-snapshots/<runId>/`. It reuses the existing keiko-evidence discipline verbatim — the
+// realpath-contained QI dir, the atomic O_EXCL side-file writer, the QI redaction wrapper, and the
+// runId validator — and adds NO new persistence layer.
+//
+// Immutability: unlike the MUTABLE candidate companion, this record is the evidence artifact, so it
+// is write-once. `record` refuses to overwrite an existing snapshot (O_EXCL on the JSON temp +
+// an explicit pre-check) — a re-snapshot is a new run, never a mutation of an old one.
+//
+// Redaction: the whole record (including the design-content IR) is passed through
+// `redactQualityIntelligenceEvidence` before write. The token is never present by construction
+// (the server builder never places it on the in-memory snapshot); redaction is defense-in-depth.
+//
+// Integrity: load() recomputes each persisted screen hash from the stored, redacted IR + image
+// sha256, verifies each PNG side-file against the stored sha256/byteLength, and then recomputes the
+// snapshot integrity hash. Tampered or truncated records are rejected at the read boundary. The
+// optional artifacts (`links`, `tokens`, `metrics`) stay out of the drift hash but carry separate
+// artifact hashes when present; old un-hashed optional artifacts are omitted on load instead of being
+// trusted.
+//
+// Retention: `enforceFigmaSnapshotRetention` deletes snapshot records + their side-file dirs in
+// lock-step with the provided policy. Wiring: call it where the other QI retention enforcement
+// runs (the orchestrator that calls `deleteQualityIntelligenceRun` for each expired run).
+//
+// Orphan cleanup: `sweepOrphanedFigmaSnapshotSideDirs` removes side-file dirs (and stray *.tmp
+// files) that have no matching record. It is lazy/once — the store calls it on first use so stale
+// dirs from a previously interrupted record() are cleaned up without a separate boot step.
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, linkSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join, sep } from "node:path";
+import { assertContainedRealPath, resolveWithinWorkspace, } from "@oscharko-dev/keiko-workspace";
+import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
+import { assertValidRunId } from "@oscharko-dev/keiko-security";
+import { EvidenceReadError, EvidenceWriteError } from "../../errors.js";
+import { writeSideFile } from "../../side-file.js";
+import { redactQualityIntelligenceEvidence } from "../redaction.js";
+import { QI_SUBDIR } from "../store.js";
+import { FIGMA_SNAPSHOT_SCHEMA_VERSION, validateFigmaSnapshotRecord, } from "./schema.js";
+const QI_DIR_MODE = 0o700;
+const SNAPSHOT_SUFFIX = ".figma-snapshot.json";
+const SNAPSHOT_MANAGEMENT_SUFFIX = ".figma-snapshot.management.json";
+const FIGMA_SNAPSHOT_MANAGEMENT_SCHEMA_VERSION = 1;
+const SIDE_FILE_SUBDIR = "figma-snapshots";
+const MAX_SIDE_FILE_NAME_LENGTH = 128;
+const SIDE_FILE_NAME_PATTERN = /^[A-Za-z0-9._-]+$/u;
+const MAX_SNAPSHOT_DISPLAY_NAME_LENGTH = 120;
+/**
+ * Conservative default Figma-snapshot retention cap. Chosen to match the QI `qi:standard-90d`
+ * profile's `maxRunArtifacts` (500) — the least-destructive value that still bounds growth, so
+ * wiring retention on by default does NOT surprise an operator with an aggressive small cap (ADR-0048).
+ * Deployments raise/lower it via `FigmaSnapshotStoreOptions.retention.maxRecords`.
+ */
+export const DEFAULT_FIGMA_SNAPSHOT_MAX_RECORDS = 500;
+// ─── Integrity hash (mirrors figmaSnapshotHash.ts — inlined so keiko-evidence does not depend
+//     on the private keiko-server package). MUST stay bit-identical with the server builder. ────
+const sha256Hex = (input) => createHash("sha256").update(input, "utf8").digest("hex");
+const sha256Bytes = (input) => createHash("sha256").update(input).digest("hex");
+// Stable stringify: keys emitted in sorted order at every depth (mirrors canonical() in hash.ts).
+function canonical(value) {
+    if (value === undefined)
+        return "null";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const record = value;
+    const entries = Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`);
+    return `{${entries.join(",")}}`;
+}
+const hashArtifact = (value) => sha256Hex(canonical(value));
+// Hash-neutral IR projection (mirrors figmaSnapshotHash.ts in keiko-server). The store accepts
+// `irJson` as opaque JSON, so malformed legacy/tampered shapes fall back to the raw JSON projection;
+// valid Screen-IR gets the exact same hash-neutral field pruning as the builder.
+const HASH_NEUTRAL_IR_KEYS = new Set([
+    "textColor",
+    "backgroundColor",
+    "layout",
+    "sizing",
+    "cornerRadius",
+    "typography",
+]);
+const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const stripHashNeutralChild = (child) => isJsonObject(child) ? stripHashNeutralFields(child) : child;
+const stripHashNeutralFields = (node) => {
+    const entries = Object.entries(node).filter(([key]) => key !== "children" && !HASH_NEUTRAL_IR_KEYS.has(key));
+    const rawChildren = node.children;
+    return {
+        ...Object.fromEntries(entries),
+        children: Array.isArray(rawChildren)
+            ? rawChildren.map(stripHashNeutralChild)
+            : [],
+    };
+};
+const hashStableIr = (irJson) => {
+    if (!isJsonObject(irJson) || !isJsonObject(irJson.root))
+        return irJson;
+    return { ...irJson, root: stripHashNeutralFields(irJson.root) };
+};
+const recomputeScreenIntegrityHash = (screen) => sha256Hex(canonical({
+    imageSha256: screen.image.sha256,
+    ir: hashStableIr(screen.irJson),
+    screenId: screen.screenId,
+}));
+const recomputeStructuralScreenIntegrityHash = (screen) => sha256Hex(canonical({
+    ir: hashStableIr(screen.irJson),
+    screenId: screen.screenId,
+    structuralOnly: true,
+}));
+const artifactHashesFor = (record) => {
+    const hashes = {
+        ...(record.links !== undefined ? { links: hashArtifact(record.links) } : {}),
+        ...(record.tokens !== undefined ? { tokens: hashArtifact(record.tokens) } : {}),
+        ...(record.metrics !== undefined ? { metrics: hashArtifact(record.metrics) } : {}),
+    };
+    return hashes.links === undefined && hashes.tokens === undefined && hashes.metrics === undefined
+        ? undefined
+        : hashes;
+};
+// Recompute the snapshot-level integrity hash from a loaded record.
+// This exactly mirrors hashSnapshot() in figmaSnapshotHash.ts:
+//   sha256( canonical({ screens: sorted [{integrityHash,screenId}], snapshotSchemaVersion, version }) )
+// fetchedAt and links/tokens are excluded by design (non-identity metadata).
+function recomputeSnapshotIntegrityHash(record) {
+    const screens = [...record.screens, ...(record.structuralScreens ?? [])]
+        .sort((a, b) => (a.screenId < b.screenId ? -1 : a.screenId > b.screenId ? 1 : 0))
+        .map((s) => ({ integrityHash: s.integrityHash, screenId: s.screenId }));
+    return sha256Hex(canonical({
+        screens,
+        snapshotSchemaVersion: record.figmaSnapshotSchemaVersion,
+        version: record.provenance.version ?? null,
+    }));
+}
+const rehashRecord = (record) => {
+    const screens = record.screens.map((screen) => ({
+        ...screen,
+        integrityHash: recomputeScreenIntegrityHash(screen),
+    }));
+    const structuralScreens = record.structuralScreens?.map((screen) => ({
+        ...screen,
+        integrityHash: recomputeStructuralScreenIntegrityHash(screen),
+    }));
+    const rehashed = {
+        ...record,
+        screens,
+        ...(structuralScreens !== undefined ? { structuralScreens } : {}),
+    };
+    return { ...rehashed, integrityHash: recomputeSnapshotIntegrityHash(rehashed) };
+};
+const EXTERNAL_LINK_TARGET = /^(?:[a-z][a-z0-9+.-]*:\/\/|mailto:|tel:|data:|javascript:)/iu;
+const isExternalLinkTarget = (targetNodeId) => targetNodeId.startsWith("url:") || EXTERNAL_LINK_TARGET.test(targetNodeId);
+const safeLinkRows = (links) => links?.filter((link) => !isExternalLinkTarget(link.targetNodeId));
+const omitUnverifiedArtifacts = (record, omitLinks, omitTokens, omitMetrics) => {
+    if (!omitLinks && !omitTokens && !omitMetrics)
+        return record;
+    const omitted = new Set([
+        ...(omitLinks ? ["links"] : []),
+        ...(omitTokens ? ["tokens"] : []),
+        ...(omitMetrics ? ["metrics"] : []),
+    ]);
+    return Object.fromEntries(Object.entries(record).filter(([key]) => !omitted.has(key)));
+};
+function verifyArtifactHash(kind, value, actualHash, runId) {
+    if (value === undefined) {
+        if (actualHash !== undefined) {
+            throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: ${kind} artifact missing`);
+        }
+        return false;
+    }
+    if (actualHash === undefined)
+        return true;
+    if (actualHash !== hashArtifact(value)) {
+        throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: ${kind} artifact hash mismatch`);
+    }
+    return false;
+}
+function verifyOptionalArtifactHashes(record, runId) {
+    const actual = record.artifactHashes;
+    const omitLinks = verifyArtifactHash("links", record.links, actual?.links, runId);
+    const omitTokens = verifyArtifactHash("tokens", record.tokens, actual?.tokens, runId);
+    const omitMetrics = verifyArtifactHash("metrics", record.metrics, actual?.metrics, runId);
+    // Older records predate artifact hashes. The optional fields remain schema-valid, but we do not
+    // trust them for downstream generation without their own tamper evidence.
+    return omitUnverifiedArtifacts(record, omitLinks, omitTokens, omitMetrics);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────────────────────
+function realBaseForWrite(baseDir, fs) {
+    try {
+        mkdirSync(baseDir, { recursive: true, mode: QI_DIR_MODE });
+        return fs.realPath(baseDir);
+    }
+    catch (error) {
+        throw new EvidenceWriteError(`cannot create Figma snapshot directory: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function realBaseForRead(baseDir, fs) {
+    if (!fs.exists(baseDir))
+        return undefined;
+    try {
+        return fs.realPath(baseDir);
+    }
+    catch (error) {
+        throw new EvidenceReadError(`cannot read Figma snapshot directory: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function containedRecordPath(runId, realBase, fs) {
+    assertValidRunId(runId);
+    const name = `${runId}${SNAPSHOT_SUFFIX}`;
+    const lexical = resolveWithinWorkspace(realBase, name);
+    return assertContainedRealPath(fs, realBase, lexical, name);
+}
+function containedManagementPath(runId, realBase, fs) {
+    assertValidRunId(runId);
+    const name = `${runId}${SNAPSHOT_MANAGEMENT_SUFFIX}`;
+    const lexical = resolveWithinWorkspace(realBase, name);
+    return assertContainedRealPath(fs, realBase, lexical, name);
+}
+function containedSideFileRunDir(ctx, runId) {
+    assertValidRunId(runId);
+    const realQiBase = realBaseForRead(ctx.qiDir, ctx.fs) ?? realBaseForWrite(ctx.qiDir, ctx.fs);
+    const sideBaseLexical = resolveWithinWorkspace(realQiBase, SIDE_FILE_SUBDIR);
+    const realSideBase = assertContainedRealPath(ctx.fs, realQiBase, sideBaseLexical, SIDE_FILE_SUBDIR);
+    const runDirLexical = resolveWithinWorkspace(realSideBase, runId);
+    return assertContainedRealPath(ctx.fs, realSideBase, runDirLexical, runId);
+}
+function assertSnapshotAbsent(target) {
+    if (lstatSync(target, { throwIfNoEntry: false }) !== undefined) {
+        throw new EvidenceWriteError("Figma snapshot already exists for this run (write-once)");
+    }
+}
+function runIdFromSnapshotName(name) {
+    if (!name.endsWith(SNAPSHOT_SUFFIX))
+        return undefined;
+    const runId = name.slice(0, -SNAPSHOT_SUFFIX.length);
+    try {
+        assertValidRunId(runId);
+        return runId;
+    }
+    catch {
+        return undefined;
+    }
+}
+function runIdFromManagementName(name) {
+    if (!name.endsWith(SNAPSHOT_MANAGEMENT_SUFFIX))
+        return undefined;
+    const runId = name.slice(0, -SNAPSHOT_MANAGEMENT_SUFFIX.length);
+    try {
+        assertValidRunId(runId);
+        return runId;
+    }
+    catch {
+        return undefined;
+    }
+}
+function snapshotRecordFiles(baseDir) {
+    let entries;
+    try {
+        entries = readdirSync(baseDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || entry.isSymbolicLink())
+            continue;
+        const runId = runIdFromSnapshotName(entry.name);
+        if (runId === undefined)
+            continue;
+        files.push({ runId, path: join(baseDir, entry.name) });
+    }
+    return files;
+}
+// Write-once: create a temp file, then hard-link it into the final target. `linkSync` is the
+// exclusive commit: it fails with EEXIST if another recorder created the target after the
+// pre-check, unlike `rename`, which would overwrite the winner on POSIX.
+function atomicWriteOnce(target, json, randomSuffix) {
+    assertSnapshotAbsent(target);
+    const temp = `${target}.${randomSuffix()}.tmp`;
+    try {
+        writeFileSync(temp, json, { encoding: "utf8", flag: "wx" });
+        try {
+            chmodSync(temp, 0o600);
+        }
+        catch {
+            // non-fatal: not every filesystem supports chmod (e.g. Windows)
+        }
+        try {
+            linkSync(temp, target);
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                throw new EvidenceWriteError("Figma snapshot already exists for this run (write-once)");
+            }
+            throw error;
+        }
+        rmSync(temp, { force: true });
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        if (error instanceof EvidenceWriteError)
+            throw error;
+        throw new EvidenceWriteError(`Figma snapshot write failed: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function atomicWriteMutable(target, json, randomSuffix) {
+    const temp = `${target}.${randomSuffix()}.tmp`;
+    try {
+        writeFileSync(temp, json, { encoding: "utf8", flag: "wx" });
+        try {
+            chmodSync(temp, 0o600);
+        }
+        catch {
+            // non-fatal: not every filesystem supports chmod (e.g. Windows)
+        }
+        renameSync(temp, target);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw new EvidenceWriteError(`Figma snapshot management metadata write failed: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function normalizeDisplayName(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const trimmed = value.trim().replace(/\s+/gu, " ");
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed.length > MAX_SNAPSHOT_DISPLAY_NAME_LENGTH) {
+        throw new EvidenceWriteError("Figma snapshot display name is too long");
+    }
+    if (hasControlCharacter(trimmed)) {
+        throw new EvidenceWriteError("Figma snapshot display name contains control characters");
+    }
+    return trimmed;
+}
+function hasControlCharacter(value) {
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function userMetadataRecord(value, expectedRunId) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (record.figmaSnapshotManagementSchemaVersion !== FIGMA_SNAPSHOT_MANAGEMENT_SCHEMA_VERSION) {
+        return undefined;
+    }
+    return record.runId === expectedRunId ? record : undefined;
+}
+function metadataUpdatedAt(record) {
+    return typeof record.updatedAt === "string" && record.updatedAt.length > 0
+        ? record.updatedAt
+        : undefined;
+}
+function metadataDisplayName(record) {
+    if (record.displayName === undefined)
+        return undefined;
+    if (typeof record.displayName !== "string")
+        return null;
+    try {
+        return normalizeDisplayName(record.displayName);
+    }
+    catch {
+        return null;
+    }
+}
+function parseUserMetadata(value, expectedRunId) {
+    const record = userMetadataRecord(value, expectedRunId);
+    if (record === undefined)
+        return undefined;
+    const updatedAt = metadataUpdatedAt(record);
+    if (updatedAt === undefined)
+        return undefined;
+    const displayName = metadataDisplayName(record);
+    if (displayName === null)
+        return undefined;
+    return displayName === undefined ? { updatedAt } : { displayName, updatedAt };
+}
+function metadataToJson(runId, metadata) {
+    return JSON.stringify({
+        figmaSnapshotManagementSchemaVersion: FIGMA_SNAPSHOT_MANAGEMENT_SCHEMA_VERSION,
+        runId,
+        ...(metadata.displayName !== undefined ? { displayName: metadata.displayName } : {}),
+        updatedAt: metadata.updatedAt,
+    });
+}
+function writeScreenSideFiles(sideFileBase, runId, screens, fs, randomSuffix) {
+    return screens.map((screen, index) => {
+        const name = `screen-${String(index).padStart(4, "0")}.png`;
+        const written = writeSideFile(sideFileBase, runId, name, Buffer.from(screen.image.bytes), {
+            fs,
+            randomSuffix,
+        });
+        return {
+            screenId: screen.screenId,
+            irJson: screen.irJson,
+            integrityHash: screen.integrityHash,
+            image: {
+                mimeType: "image/png",
+                relativePath: written.relativePath,
+                sha256: written.sha256,
+                byteLength: written.bytes,
+            },
+        };
+    });
+}
+function assembleRecord(input, screenRows) {
+    const links = safeLinkRows(input.links);
+    const draft = {
+        figmaSnapshotSchemaVersion: FIGMA_SNAPSHOT_SCHEMA_VERSION,
+        runId: input.runId,
+        provenance: {
+            fileKey: input.provenance.fileKey,
+            nodeId: input.provenance.nodeId,
+            version: input.provenance.version,
+            fetchedAt: input.provenance.fetchedAt,
+        },
+        screens: screenRows,
+        skippedScreens: input.skippedScreens,
+        ...(input.structuralScreens !== undefined
+            ? {
+                structuralScreens: input.structuralScreens,
+            }
+            : {}),
+        // Omit `links`/`tokens` entirely when absent so an older snapshot stays byte-minimal and the
+        // optional fields never serialise as `undefined` (exactOptionalPropertyTypes-safe).
+        ...(links !== undefined ? { links } : {}),
+        ...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+        ...(input.metrics !== undefined ? { metrics: input.metrics } : {}),
+        integrityHash: input.integrityHash,
+        redactionSummary: { totalStringsScanned: 0, stringsRedacted: 0, patternsMatched: {} },
+    };
+    const { redacted, summary } = redactQualityIntelligenceEvidence(draft);
+    const rehashed = rehashRecord(redacted);
+    const artifactHashes = artifactHashesFor(rehashed);
+    return {
+        ...rehashed,
+        ...(artifactHashes !== undefined ? { artifactHashes } : {}),
+        redactionSummary: summary,
+    };
+}
+function isAllowedSideFileName(name) {
+    if (name.length === 0 || name.length > MAX_SIDE_FILE_NAME_LENGTH)
+        return false;
+    return !name.startsWith(".") && SIDE_FILE_NAME_PATTERN.test(name);
+}
+function verifyScreenIntegrity(screen, runId) {
+    const expected = recomputeScreenIntegrityHash(screen);
+    if (screen.integrityHash !== expected) {
+        throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: screen ${screen.screenId} hash mismatch`);
+    }
+}
+function verifyStructuralScreenIntegrity(screen, runId) {
+    const expected = recomputeStructuralScreenIntegrityHash(screen);
+    if (screen.integrityHash !== expected) {
+        throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: structural screen ${screen.screenId} hash mismatch`);
+    }
+}
+function readVerifiedScreenImageSideFile(ctx, runId, image) {
+    const name = image.relativePath;
+    if (!isAllowedSideFileName(name)) {
+        throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: invalid image side-file path`);
+    }
+    const runDir = join(ctx.sideFileBase, runId);
+    let realRunDir;
+    try {
+        realRunDir = ctx.fs.realPath(runDir);
+    }
+    catch {
+        throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: image side-file directory missing`);
+    }
+    const lexical = resolveWithinWorkspace(realRunDir, name);
+    const absolute = assertContainedRealPath(ctx.fs, realRunDir, lexical, name);
+    const stat = lstatSync(absolute, { throwIfNoEntry: false });
+    if (stat === undefined || !stat.isFile() || stat.isSymbolicLink()) {
+        throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: image side-file missing`);
+    }
+    const bytes = readFileSync(absolute);
+    if (bytes.byteLength !== image.byteLength || sha256Bytes(bytes) !== image.sha256) {
+        throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: image side-file hash mismatch`);
+    }
+    return bytes;
+}
+function verifyScreenImageSideFile(ctx, runId, screen) {
+    readVerifiedScreenImageSideFile(ctx, runId, screen.image);
+}
+function verifyPersistedScreens(ctx, rec, runId) {
+    for (const screen of rec.screens) {
+        verifyScreenIntegrity(screen, runId);
+        verifyScreenImageSideFile(ctx, runId, screen);
+    }
+    for (const screen of rec.structuralScreens ?? [])
+        verifyStructuralScreenIntegrity(screen, runId);
+}
+function verifyPersistedScreenMetadata(rec, runId) {
+    for (const screen of rec.screens)
+        verifyScreenIntegrity(screen, runId);
+    for (const screen of rec.structuralScreens ?? [])
+        verifyStructuralScreenIntegrity(screen, runId);
+}
+// Parse one raw JSON string from a snapshot record file into a scope entry, or null when the
+// file does not belong to the requested scope or cannot be parsed.
+function parseScopeEntry(filePath, fileKey, nodeId) {
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        const prov = parsed.provenance;
+        if (!prov?.fileKey || prov.fileKey !== fileKey || prov.nodeId !== nodeId)
+            return null;
+        const runId = typeof parsed.runId === "string" ? parsed.runId : undefined;
+        if (runId === undefined)
+            return null;
+        const fetchedAt = typeof prov.fetchedAt === "string" ? prov.fetchedAt : "";
+        const integrityHash = typeof parsed.integrityHash === "string" ? parsed.integrityHash : "";
+        return { runId, fetchedAt, integrityHash };
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Orphan sweep ─────────────────────────────────────────────────────────────────────────────
+function snapshotRecordExists(qiDir, runId) {
+    const recordPath = join(qiDir, `${runId}${SNAPSHOT_SUFFIX}`);
+    return lstatSync(recordPath, { throwIfNoEntry: false })?.isFile() === true;
+}
+function sweepSideFileBaseEntry(qiDir, sideFileBase, name) {
+    if (name.endsWith(".tmp")) {
+        rmSync(join(sideFileBase, name), { force: true });
+        return;
+    }
+    if (snapshotRecordExists(qiDir, name))
+        return;
+    const runDir = join(sideFileBase, name);
+    const stat = lstatSync(runDir, { throwIfNoEntry: false });
+    if (stat?.isDirectory() === true)
+        rmSync(runDir, { recursive: true, force: true });
+}
+function sweepSideFileBaseEntries(qiDir, sideFileBase) {
+    const sideBaseStat = lstatSync(sideFileBase, { throwIfNoEntry: false });
+    if (!sideBaseStat?.isDirectory())
+        return;
+    let entries;
+    try {
+        entries = readdirSync(sideFileBase);
+    }
+    catch {
+        return; // non-fatal: best-effort sweep
+    }
+    for (const name of entries)
+        sweepSideFileBaseEntry(qiDir, sideFileBase, name);
+}
+function sweepManagementMetadataFiles(qiDir) {
+    let qiEntries;
+    try {
+        qiEntries = readdirSync(qiDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of qiEntries) {
+        if (!entry.isFile() || entry.isSymbolicLink())
+            continue;
+        const runId = runIdFromManagementName(entry.name);
+        if (runId === undefined)
+            continue;
+        if (!snapshotRecordExists(qiDir, runId))
+            rmSync(join(qiDir, entry.name), { force: true });
+    }
+}
+// Removes side-file dirs, stray *.tmp files, and orphaned mutable management sidecars that have no
+// matching record in qiDir. Called lazily once per store instance to clean up interrupted writes.
+function sweepOrphanedSideDirs(qiDir, sideFileBase) {
+    sweepSideFileBaseEntries(qiDir, sideFileBase);
+    sweepManagementMetadataFiles(qiDir);
+}
+// Read the fetchedAt timestamp from one snapshot file, or undefined when missing/unparseable.
+function readFetchedAt(filePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        const prov = parsed.provenance;
+        if (typeof prov?.fetchedAt !== "string" || prov.fetchedAt.trim() === "") {
+            return undefined;
+        }
+        return Number.isNaN(Date.parse(prov.fetchedAt)) ? undefined : prov.fetchedAt;
+    }
+    catch {
+        return undefined;
+    }
+}
+function listRecentOp(ctx, limit = 12) {
+    ctx.ensureSwept();
+    const realBase = realBaseForRead(ctx.qiDir, ctx.fs);
+    if (realBase === undefined)
+        return [];
+    const boundedLimit = Number.isInteger(limit) && limit > 0 ? limit : 12;
+    const records = [];
+    for (const file of snapshotRecordFiles(realBase)) {
+        const fetchedAt = readFetchedAt(file.path);
+        if (fetchedAt === undefined)
+            continue;
+        records.push({ runId: file.runId, fetchedAt });
+    }
+    records.sort((a, b) => (a.fetchedAt > b.fetchedAt ? -1 : a.fetchedAt < b.fetchedAt ? 1 : 0));
+    return records.slice(0, boundedLimit).map((record) => record.runId);
+}
+function containedPath(path, root) {
+    return path === root || path.startsWith(root + sep);
+}
+function realSideFileBaseForRetention(qiDir, sideFileBase) {
+    const sideStat = lstatSync(sideFileBase, { throwIfNoEntry: false });
+    if (sideStat === undefined) {
+        return undefined;
+    }
+    if (sideStat.isSymbolicLink() || !sideStat.isDirectory()) {
+        throw new EvidenceWriteError("Figma snapshot side-file root is not a real directory");
+    }
+    const realQiDir = realpathSync(qiDir);
+    const realSideFileBase = realpathSync(sideFileBase);
+    if (!containedPath(realSideFileBase, realQiDir)) {
+        throw new EvidenceWriteError("Figma snapshot side-file root escapes the QI evidence directory");
+    }
+    return realSideFileBase;
+}
+function sideDirForRetention(realSideFileBase, runId) {
+    if (realSideFileBase === undefined) {
+        return undefined;
+    }
+    const runDir = join(realSideFileBase, runId);
+    if (!containedPath(runDir, realSideFileBase)) {
+        throw new EvidenceWriteError("Figma snapshot side-file dir escapes retention root");
+    }
+    const stat = lstatSync(runDir, { throwIfNoEntry: false });
+    if (stat?.isSymbolicLink() === true) {
+        throw new EvidenceWriteError("Figma snapshot side-file dir is a symlink");
+    }
+    if (stat !== undefined && !stat.isDirectory()) {
+        throw new EvidenceWriteError("Figma snapshot side-file dir is not a real directory");
+    }
+    return stat === undefined ? undefined : runDir;
+}
+/**
+ * Enforce store-level retention for Figma snapshot records. Deletes the RECORD first, then the
+ * side-file dir, so a partially-retained snapshot is never in a state where the record is gone
+ * but the side-files remain (the side-files are unreachable without the record). A retained
+ * record's side-dir is never touched.
+ *
+ * Wiring: call this alongside `deleteQualityIntelligenceRun` in the QI retention orchestrator
+ * (#274). The profiles are intentionally separate because snapshot retention may differ from
+ * run-manifest retention (snapshots are larger, longer-lived evidence artifacts).
+ */
+export function enforceFigmaSnapshotRetention(evidenceDir, profile) {
+    const qiDir = join(evidenceDir, QI_SUBDIR);
+    const sideFileBase = join(qiDir, SIDE_FILE_SUBDIR);
+    const dirStat = lstatSync(qiDir, { throwIfNoEntry: false });
+    if (!dirStat?.isDirectory())
+        return;
+    const realSideFileBase = realSideFileBaseForRetention(qiDir, sideFileBase);
+    // Scan for snapshot records and sort by fetchedAt ascending so we remove the oldest first.
+    const records = [];
+    for (const file of snapshotRecordFiles(qiDir)) {
+        const fetchedAt = readFetchedAt(file.path);
+        // Unparseable records are skipped — do not evict conservatively.
+        if (fetchedAt !== undefined)
+            records.push({ runId: file.runId, fetchedAt });
+    }
+    // Sort oldest first (ascending fetchedAt) so we evict the oldest beyond the cap.
+    records.sort((a, b) => (a.fetchedAt < b.fetchedAt ? -1 : a.fetchedAt > b.fetchedAt ? 1 : 0));
+    const toEvict = records.slice(0, Math.max(0, records.length - profile.maxRecords));
+    for (const { runId } of toEvict) {
+        const sideDir = sideDirForRetention(realSideFileBase, runId);
+        // After side-dir preflight succeeds, delete the record first — after this the side-dir is
+        // unreachable by any normal path.
+        rmSync(join(qiDir, `${runId}${SNAPSHOT_SUFFIX}`), { force: true });
+        rmSync(join(qiDir, `${runId}${SNAPSHOT_MANAGEMENT_SUFFIX}`), { force: true });
+        // Best-effort: remove the side-file dir; failure is non-fatal for lazy store reads because
+        // ensureSwept catches retention errors and retries on the next store instance.
+        if (sideDir !== undefined) {
+            rmSync(sideDir, { recursive: true, force: true });
+        }
+    }
+}
+function recordOp(ctx, input) {
+    assertValidRunId(input.runId);
+    ctx.ensureSwept();
+    const realBase = realBaseForWrite(ctx.qiDir, ctx.fs);
+    const recordPath = containedRecordPath(input.runId, realBase, ctx.fs);
+    // Write-once pre-check BEFORE any side-file is written so a rejected re-record leaves no
+    // partial render bytes behind. `atomicWriteOnce` re-checks via O_EXCL to close the TOCTOU gap.
+    assertSnapshotAbsent(recordPath);
+    let rows;
+    try {
+        rows = writeScreenSideFiles(ctx.sideFileBase, input.runId, input.screens, ctx.fs, ctx.randomSuffix);
+    }
+    catch (error) {
+        // Side-file write failed: best-effort remove the run's side-dir so it is not orphaned.
+        rmSync(join(ctx.sideFileBase, input.runId), { recursive: true, force: true });
+        throw error;
+    }
+    try {
+        atomicWriteOnce(recordPath, JSON.stringify(assembleRecord(input, rows)), ctx.randomSuffix);
+    }
+    catch (error) {
+        // Record write failed after side-files succeeded: remove side-dir to avoid orphaning.
+        rmSync(join(ctx.sideFileBase, input.runId), { recursive: true, force: true });
+        throw error;
+    }
+    return { recordPath, sideFileDir: join(ctx.sideFileBase, input.runId) };
+}
+function loadOp(ctx, runId) {
+    assertValidRunId(runId);
+    ctx.ensureSwept();
+    const realBase = realBaseForRead(ctx.qiDir, ctx.fs);
+    if (realBase === undefined)
+        return undefined;
+    const target = join(realBase, `${runId}${SNAPSHOT_SUFFIX}`);
+    if (lstatSync(target, { throwIfNoEntry: false })?.isFile() !== true)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(target, "utf8"));
+    }
+    catch (error) {
+        throw new EvidenceReadError(`Figma snapshot is not valid JSON: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+    if (!validateFigmaSnapshotRecord(parsed).ok)
+        return undefined;
+    const rec = parsed;
+    // Integrity check: recompute and reject on mismatch. Screen rows are verified before the
+    // snapshot-level hash so stale/tampered IR or image refs cannot hide behind an old screen hash.
+    verifyPersistedScreens(ctx, rec, runId);
+    const expected = recomputeSnapshotIntegrityHash(rec);
+    if (rec.integrityHash !== expected) {
+        throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: hash mismatch`);
+    }
+    return verifyOptionalArtifactHashes(rec, runId);
+}
+function loadMetadataOp(ctx, runId) {
+    assertValidRunId(runId);
+    ctx.ensureSwept();
+    const realBase = realBaseForRead(ctx.qiDir, ctx.fs);
+    if (realBase === undefined)
+        return undefined;
+    const target = join(realBase, `${runId}${SNAPSHOT_SUFFIX}`);
+    if (lstatSync(target, { throwIfNoEntry: false })?.isFile() !== true)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(target, "utf8"));
+    }
+    catch (error) {
+        throw new EvidenceReadError(`Figma snapshot is not valid JSON: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+    if (!validateFigmaSnapshotRecord(parsed).ok)
+        return undefined;
+    const rec = parsed;
+    verifyPersistedScreenMetadata(rec, runId);
+    const expected = recomputeSnapshotIntegrityHash(rec);
+    if (rec.integrityHash !== expected) {
+        throw new EvidenceReadError(`Figma snapshot integrity check failed for run ${runId}: hash mismatch`);
+    }
+    return verifyOptionalArtifactHashes(rec, runId);
+}
+function loadImageOp(ctx, runId, image) {
+    assertValidRunId(runId);
+    ctx.ensureSwept();
+    const bytes = readVerifiedScreenImageSideFile(ctx, runId, image);
+    return {
+        mimeType: image.mimeType,
+        bytes,
+        sha256: image.sha256,
+        byteLength: image.byteLength,
+    };
+}
+function loadUserMetadataOp(ctx, runId) {
+    assertValidRunId(runId);
+    ctx.ensureSwept();
+    const realBase = realBaseForRead(ctx.qiDir, ctx.fs);
+    if (realBase === undefined)
+        return undefined;
+    const target = containedManagementPath(runId, realBase, ctx.fs);
+    if (lstatSync(target, { throwIfNoEntry: false })?.isFile() !== true)
+        return undefined;
+    try {
+        return parseUserMetadata(JSON.parse(readFileSync(target, "utf8")), runId);
+    }
+    catch {
+        return undefined;
+    }
+}
+function updateUserMetadataOp(ctx, runId, input) {
+    assertValidRunId(runId);
+    const record = loadMetadataOp(ctx, runId);
+    if (record === undefined) {
+        throw new EvidenceWriteError("Figma snapshot does not exist");
+    }
+    const existing = loadUserMetadataOp(ctx, runId);
+    const nextDisplayName = input.displayName === undefined
+        ? existing?.displayName
+        : normalizeDisplayName(input.displayName);
+    const next = {
+        ...(nextDisplayName !== undefined ? { displayName: nextDisplayName } : {}),
+        updatedAt: input.updatedAt ?? new Date().toISOString(),
+    };
+    const realBase = realBaseForWrite(ctx.qiDir, ctx.fs);
+    atomicWriteMutable(containedManagementPath(record.runId, realBase, ctx.fs), metadataToJson(runId, next), ctx.randomSuffix);
+    return next;
+}
+function deleteSnapshotOp(ctx, runId) {
+    assertValidRunId(runId);
+    ctx.ensureSwept();
+    const realBase = realBaseForRead(ctx.qiDir, ctx.fs);
+    if (realBase === undefined) {
+        return { runId, recordDeleted: false, sideFileDirDeleted: false, metadataDeleted: false };
+    }
+    const recordPath = containedRecordPath(runId, realBase, ctx.fs);
+    const metadataPath = containedManagementPath(runId, realBase, ctx.fs);
+    const sideFileDir = containedSideFileRunDir(ctx, runId);
+    const recordDeleted = lstatSync(recordPath, { throwIfNoEntry: false })?.isFile() === true;
+    const metadataDeleted = lstatSync(metadataPath, { throwIfNoEntry: false })?.isFile() === true;
+    const sideStat = lstatSync(sideFileDir, { throwIfNoEntry: false });
+    const sideFileDirDeleted = sideStat !== undefined;
+    rmSync(recordPath, { force: true });
+    rmSync(metadataPath, { force: true });
+    if (sideStat !== undefined)
+        rmSync(sideFileDir, { recursive: true, force: true });
+    return { runId, recordDeleted, sideFileDirDeleted, metadataDeleted };
+}
+function listByScopeOp(ctx, fileKey, nodeId) {
+    ctx.ensureSwept();
+    const realBase = realBaseForRead(ctx.qiDir, ctx.fs);
+    if (realBase === undefined)
+        return [];
+    const results = [];
+    for (const file of snapshotRecordFiles(realBase)) {
+        const entry = parseScopeEntry(file.path, fileKey, nodeId);
+        if (entry !== null)
+            results.push(entry);
+    }
+    results.sort((a, b) => (a.fetchedAt > b.fetchedAt ? -1 : a.fetchedAt < b.fetchedAt ? 1 : 0));
+    return results;
+}
+// ─── Store factory ────────────────────────────────────────────────────────────────────────────
+export function createNodeFigmaSnapshotStore(evidenceDir, options = {}) {
+    const qiDir = join(evidenceDir, QI_SUBDIR);
+    const sideFileBase = join(qiDir, SIDE_FILE_SUBDIR);
+    const maxRecords = options.retention?.maxRecords ?? DEFAULT_FIGMA_SNAPSHOT_MAX_RECORDS;
+    let swept = false;
+    const ctx = {
+        qiDir,
+        sideFileBase,
+        fs: options.fs ?? nodeWorkspaceFs,
+        randomSuffix: options.randomSuffix ?? randomUUID,
+        ensureSwept() {
+            if (swept)
+                return;
+            swept = true;
+            sweepOrphanedSideDirs(qiDir, sideFileBase);
+            // Issue #1323 AC4 — make retention operational. Runs once per store instance (the sweep is
+            // already guarded against concurrent re-entry by `swept`). A non-positive cap disables it so
+            // a deployment can opt out without removing the call site. Best-effort: `ensureSwept` runs at
+            // the head of read ops too, so a transient eviction fault (e.g. rmSync EPERM/EBUSY) must never
+            // surface as a read error; it is swallowed and retried on the next store instance.
+            if (Number.isFinite(maxRecords) && maxRecords > 0) {
+                try {
+                    enforceFigmaSnapshotRetention(evidenceDir, { maxRecords });
+                }
+                catch {
+                    // ignore; retention is best-effort and re-runs once per fresh store instance
+                }
+            }
+        },
+    };
+    return {
+        record: (input) => recordOp(ctx, input),
+        load: (runId) => loadOp(ctx, runId),
+        loadMetadata: (runId) => loadMetadataOp(ctx, runId),
+        loadImage: (runId, image) => loadImageOp(ctx, runId, image),
+        loadUserMetadata: (runId) => loadUserMetadataOp(ctx, runId),
+        updateUserMetadata: (runId, input) => updateUserMetadataOp(ctx, runId, input),
+        deleteSnapshot: (runId) => deleteSnapshotOp(ctx, runId),
+        location: (runId) => {
+            assertValidRunId(runId);
+            const realBase = realBaseForRead(qiDir, ctx.fs);
+            return realBase === undefined
+                ? join(qiDir, `${runId}${SNAPSHOT_SUFFIX}`)
+                : containedRecordPath(runId, realBase, ctx.fs);
+        },
+        listByScope: (fileKey, nodeId) => listByScopeOp(ctx, fileKey, nodeId),
+        listRecent: (limit) => listRecentOp(ctx, limit),
+    };
+}