@oscharko-dev/keiko 0.2.0-beta.3 → 0.2.0-beta.5

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaRenderPort.js

@@ -10,20 +10,69 @@
 // Figma auth header (the ephemeral url is pre-signed), but the seam still forwards whatever
 // headers the caller supplies so the proxy adapter can add transport headers. The token is
 // never materialised here and never logged.
+//
+// redirect: "manual" is set so any auth header supplied by the caller cannot follow a
+// cross-origin redirect. A 3xx response surfaces as a non-2xx status; the connector
+// layer treats non-2xx as upstream error.
 import { classifyFigmaTransportError, FigmaConnectorError } from "./figmaConnectorErrors.js";
 import { gatewayFetch, } from "@oscharko-dev/keiko-model-gateway/internal/http";
+/** Default request timeout in milliseconds for Figma render downloads. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Default maximum render response body size (32 MiB). */
+const DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
+/**
+ * Read a streaming response body up to `maxBytes`, accumulating into a Uint8Array.
+ * Throws a {@link FigmaConnectorError} with `FIGMA_RESPONSE_TOO_LARGE` if the cap is exceeded.
+ */
+const readBytesCapped = async (response, maxBytes) => {
+    if (response.body === null) {
+        const buffer = await response.arrayBuffer();
+        return new Uint8Array(buffer);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new FigmaConnectorError("FIGMA_RESPONSE_TOO_LARGE");
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+};
 /**
  * Thin default adapter over the platform `fetch`. This is the ONLY place in the render path
  * `fetch` is named. It forwards the caller-built headers verbatim and reads the body as raw
- * bytes; it does not log, retry, or inspect any token. Resilience/backoff is out of scope here
- * (#759); the proxy/custom-CA transport is the platform prerequisite (#802) that replaces this.
+ * bytes with an explicit byte cap; it does not log, retry, or inspect any token. Resilience/
+ * backoff is out of scope here (#759); the proxy/custom-CA transport is the platform
+ * prerequisite (#802) that replaces this.
+ *
+ * `redirect: "manual"` prevents any caller-supplied auth header from following a cross-origin
+ * redirect. A 3xx response surfaces as a non-2xx port result; the connector treats it as
+ * upstream error.
  */
-export const createDefaultFigmaRenderPort = (egress, fetchImpl) => {
+export const createDefaultFigmaRenderPort = (egress, fetchImpl, options) => {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxResponseBytes = options?.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
     return async (request) => {
+        const signal = AbortSignal.timeout(timeoutMs);
         try {
             const response = await gatewayFetch(request.url, {
                 method: "GET",
                 headers: { ...request.headers },
+                redirect: "manual",
+                signal,
                 ...(egress !== undefined ? { egress } : {}),
                 ...(fetchImpl !== undefined ? { fetchImpl } : {}),
             });
@@ -31,8 +80,8 @@ export const createDefaultFigmaRenderPort = (egress, fetchImpl) => {
             response.headers.forEach((value, name) => {
                 headers[name] = value;
             });
-            const buffer = await response.arrayBuffer();
-            return { status: response.status, bytes: new Uint8Array(buffer), headers };
+            const bytes = await readBytesCapped(response, maxResponseBytes);
+            return { status: response.status, bytes, headers };
         }
         catch (err) {
             if (err instanceof FigmaConnectorError)

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaSnapshotBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotBuilder.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotBuilder.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAGV,aAAa,EAEd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAWzF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,wBAAwB,CAAC,cAAc,CAAC;IACrD,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AA+GD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,uBAAuB,KAC7B,OAAO,CAAC,aAAa,CA6BvB,CAAC"}
+{"version":3,"file":"figmaSnapshotBuilder.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotBuilder.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAGV,aAAa,EAEd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAWzF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,wBAAwB,CAAC,cAAc,CAAC;IACrD,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAwLD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,uBAAuB,KAC7B,OAAO,CAAC,aAAa,CA6BvB,CAAC"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaSnapshotBuilder.js

@@ -29,6 +29,37 @@ const chunk = (items, size) => {
         out.push(items.slice(i, i + size));
     return out;
 };
+// Returns true when the hostname is an IP literal or a local/loopback name that must be blocked.
+const isBlockedHostname = (h) => h.length === 0 ||
+    /^\d+\.\d+\.\d+\.\d+$/.test(h) ||
+    h.startsWith("[") ||
+    h === "localhost" ||
+    h.endsWith(".localhost") ||
+    h.endsWith(".local");
+// Validates that a render URL returned by the Figma API is safe to follow. Blocks http:
+// (plaintext) and IP-literal hostnames (RFC-1918, loopback, link-local) to prevent SSRF via
+// a compromised or MITM'd API response. A broad IP-block is preferred over a tight CDN
+// allowlist because Figma's pre-signed render URLs span multiple AWS S3 regions/CDN fronts.
+const isRenderUrlSafe = (raw) => {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "https:")
+        return false;
+    // Normalise: lowercase + strip exactly one trailing dot so "localhost." == "localhost".
+    const h = url.hostname.toLowerCase().replace(/\.$/, "");
+    if (isBlockedHostname(h))
+        return false;
+    // Only allow the default HTTPS port (443 or implicit) — non-standard ports indicate an
+    // internal service, not a CDN. url.port is "" when the port is the scheme default.
+    if (url.port !== "" && url.port !== "443")
+        return false;
+    return true;
+};
 const buildImagesUrl = (fileKey, ids, version) => {
     const url = new URL(`${FIGMA_API_ORIGIN}/v1/images/${encodeURIComponent(fileKey)}`);
     url.searchParams.set("ids", ids.join(","));
@@ -79,24 +110,65 @@ const requestRenderUrls = async (input, screenIds) => {
 const skip = (screenId, reason) => ({
     skipped: { screenId, reason },
 });
-// Downloads one screen's render bytes and classifies the result into a kept screen or a skip. The
-// pre-signed byte download is wrapped in the same deterministic 429 backoff; a single screen still
-// failing after retries degrades to a skip (partial render), never aborting the whole build.
+// Classifies a finished render download into a skip reason, or null when the bytes are usable.
+const renderSkipReason = (response, maxBytes) => {
+    if (response === null)
+        return "render-fetch-failed";
+    if (response.status < 200 || response.status >= 300)
+        return "render-fetch-failed";
+    if (response.bytes.length === 0)
+        return "render-empty";
+    if (response.bytes.length > maxBytes)
+        return "render-oversized";
+    return null;
+};
+// Hard-egress codes for the render-byte download host (S3/CDN — a DIFFERENT host than
+// api.figma.com). If the render port throws a FigmaConnectorError in this family, it means
+// TLS or proxy is misconfigured for the render CDN; swallowing it would yield a "successful"
+// snapshot with every screen skipped while hiding the root cause. Re-throw to abort the build,
+// consistent with the DEEP_FETCH_ABORT_CODES discipline in figmaScopedPagination.ts.
+// Using ReadonlySet<string> so this set is forward-compatible with the new codes
+// (FIGMA_PROXY_AUTH_REQUIRED, FIGMA_PROXY_BLOCKED_BY_POLICY) landing in a parallel change to
+// figmaConnectorErrors.ts without requiring a re-touch of this file.
+const RENDER_EGRESS_ABORT_CODES = new Set([
+    "FIGMA_TLS_CA_FAILURE",
+    "FIGMA_PROXY_UNREACHABLE",
+    "FIGMA_PROXY_EGRESS_FAILED",
+    "FIGMA_PROXY_AUTH_REQUIRED",
+    "FIGMA_PROXY_BLOCKED_BY_POLICY",
+]);
+// Classifies a render-port throw into a re-throw (hard egress abort) or a coded skip outcome.
+// Hard-egress errors abort the whole build — they affect every screen on the same host so
+// swallowing them would silently produce an empty snapshot.
+const classifyRenderError = (screenId, err) => {
+    if (err instanceof FigmaConnectorError) {
+        if (RENDER_EGRESS_ABORT_CODES.has(err.code))
+            throw err;
+        return skip(screenId, `render-fetch-failed:${err.code}`);
+    }
+    return skip(screenId, "render-fetch-failed");
+};
+// Downloads one screen's render bytes and classifies the result into a kept screen or a skip.
+// A single screen failing after retries degrades to a skip (partial render), never aborting.
+// Exception: hard egress errors (TLS/proxy misconfiguration) abort via classifyRenderError.
 const resolveScreen = async (input, ir, renderUrl) => {
     if (renderUrl === null)
         return skip(ir.id, "render-url-missing");
+    if (!isRenderUrlSafe(renderUrl))
+        return skip(ir.id, "render-url-blocked");
     const maxBytes = input.maxImageBytes ?? DEFAULT_MAX_IMAGE_BYTES;
     const policy = input.retryPolicy ?? DEFAULT_FIGMA_RETRY_POLICY;
     const sleep = input.sleep ?? realFigmaRetrySleep;
-    const response = await fetchWithBackoff(() => input.renderPort({ url: renderUrl, headers: {} }), policy, sleep).catch(() => null);
-    if (response === null)
-        return skip(ir.id, "render-fetch-failed");
-    if (response.status < 200 || response.status >= 300)
-        return skip(ir.id, "render-fetch-failed");
-    if (response.bytes.length === 0)
-        return skip(ir.id, "render-empty");
-    if (response.bytes.length > maxBytes)
-        return skip(ir.id, "render-oversized");
+    let response;
+    try {
+        response = await fetchWithBackoff(() => input.renderPort({ url: renderUrl, headers: {} }), policy, sleep);
+    }
+    catch (err) {
+        return classifyRenderError(ir.id, err);
+    }
+    const reason = renderSkipReason(response, maxBytes);
+    if (reason !== null)
+        return skip(ir.id, reason);
     const sha256 = hashBytes(response.bytes);
     const screen = {
         screenId: ir.id,

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaSnapshotHash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotHash.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotHash.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAEzF,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAyClD,kFAAkF;AAClF,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,EAAE,IAAI,QAAQ,EAAE,aAAa,MAAM,KAAG,MACV,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,uBAAuB,MAAM,EAC7B,SAAS,MAAM,GAAG,SAAS,EAC3B,WAAW,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAAE,KAClF,MAKF,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,OAAO,UAAU,KAAG,MACI,CAAC"}
+{"version":3,"file":"figmaSnapshotHash.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotHash.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAEzF,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAwDlD,kFAAkF;AAClF,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,EAAE,IAAI,QAAQ,EAAE,aAAa,MAAM,KAAG,MACV,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,uBAAuB,MAAM,EAC7B,SAAS,MAAM,GAAG,SAAS,EAC3B,WAAW,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAAE,KAClF,MAKF,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,OAAO,UAAU,KAAG,MACI,CAAC"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaSnapshotHash.js

@@ -23,18 +23,26 @@ const canonical = (value) => {
         .map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`);
     return `{${entries.join(",")}}`;
 };
-const stripA11yColors = (node) => {
-    const projected = {
-        ...node,
-        children: node.children.map(stripA11yColors),
+// Keys excluded from the integrity hash. Using a static Set + Object.entries filter avoids both
+// dynamic-delete (no-dynamic-delete) and unused-var issues while keeping the whitelist explicit.
+const HASH_NEUTRAL_KEYS = new Set([
+    "textColor",
+    "backgroundColor",
+    "layout",
+    "sizing",
+    "cornerRadius",
+    "typography",
+]);
+const stripHashNeutralFields = (node) => {
+    const entries = Object.entries(node).filter(([key]) => key !== "children" && !HASH_NEUTRAL_KEYS.has(key));
+    return {
+        ...Object.fromEntries(entries),
+        children: node.children.map(stripHashNeutralFields),
     };
-    delete projected.textColor;
-    delete projected.backgroundColor;
-    return projected;
 };
 const hashStableIr = (ir) => ({
     ...ir,
-    root: stripA11yColors(ir.root),
+    root: stripHashNeutralFields(ir.root),
 });
 /** sha256 over the canonical per-screen identity: {screenId, ir, imageSha256}. */
 export const hashScreen = (screenId, ir, imageSha256) => sha256Hex(canonical({ imageSha256, ir: hashStableIr(ir), screenId }));

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaSnapshotTypes.d.ts

@@ -16,8 +16,12 @@ export interface FigmaSnapshotScreen {
     /** sha256 over the canonical {screenId, ir, imageSha256} body — the per-screen drift identity. */
     readonly integrityHash: string;
 }
-/** Why a detected screen produced no render and was excluded from `screens` (partial-render). */
-export type FigmaSkippedScreenReason = "render-url-missing" | "render-fetch-failed" | "render-empty" | "render-oversized";
+/** Why a detected screen produced no render and was excluded from `screens` (partial-render).
+ * The `render-fetch-failed` member also appears as `render-fetch-failed:<CODE>` when the fetch
+ * threw a FigmaConnectorError — the code suffix lets metrics distinguish an egress
+ * misconfiguration (e.g. `FIGMA_EGRESS_TIMEOUT`) from an unclassified network flake.
+ */
+export type FigmaSkippedScreenReason = "render-url-missing" | "render-url-blocked" | "render-fetch-failed" | `render-fetch-failed:${string}` | "render-empty" | "render-oversized";
 export interface FigmaSkippedScreen {
     readonly screenId: string;
     readonly reason: FigmaSkippedScreenReason;

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaSnapshotTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotTypes.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotTypes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAElD,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,iGAAiG;AACjG,MAAM,MAAM,wBAAwB,GAChC,oBAAoB,GACpB,qBAAqB,GACrB,cAAc,GACd,kBAAkB,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,cAAc,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACvD;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,wBAAwB,CAAC,eAAe,EAAE,CAAC;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}
+{"version":3,"file":"figmaSnapshotTypes.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotTypes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAElD,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,oBAAoB,GACpB,oBAAoB,GACpB,qBAAqB,GACrB,uBAAuB,MAAM,EAAE,GAC/B,cAAc,GACd,kBAAkB,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,cAAc,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACvD;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,wBAAwB,CAAC,eAAe,EAAE,CAAC;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figmaSnapshotAdapter.d.ts

@@ -2,11 +2,23 @@ import { type FigmaSnapshotRecord } from "@oscharko-dev/keiko-evidence";
 import type { UiHandlerDeps } from "../deps.js";
 /** Loads an immutable Figma Snapshot evidence record by runId. Returns `undefined` when not found. */
 export type FigmaSnapshotLoader = (snapshotRunId: string) => FigmaSnapshotRecord | undefined;
+export interface FigmaSnapshotLoaderOptions {
+    /**
+     * Drift seam (#735): a figma-snapshot source pins a write-once, content-addressed runId, so its
+     * content can never change under its identity — re-checking the pinned record would always
+     * report "fresh" even after the board changed and was re-snapshotted. When this flag is set the
+     * loader resolves the LATEST snapshot recorded for the same board scope (fileKey + nodeId) and
+     * returns it instead of the pinned record whenever its integrity hash differs. Screen atom ids
+     * are board-stable (screenId-derived), so compareStaleness sees changed atoms, not orphans.
+     * Used by re-check and regenerate-stale ONLY — the generate path keeps exact pinning.
+     */
+    readonly resolveLatestByScope?: boolean;
+}
 /**
  * Build the snapshot loader. Returns `undefined` when `deps.evidenceDir` is not configured so the
  * ingestion layer maps an attempted figma-snapshot source to QI_FIGMA_SNAPSHOT_UNAVAILABLE.
  */
-export declare function makeFigmaSnapshotLoader(deps: UiHandlerDeps): FigmaSnapshotLoader | undefined;
+export declare function makeFigmaSnapshotLoader(deps: UiHandlerDeps, options?: FigmaSnapshotLoaderOptions): FigmaSnapshotLoader | undefined;
 /** The image-derived semantics a multimodal model recovered for one screen, as additive hints. */
 export interface FigmaVisionScreenRequest {
     readonly screenId: string;

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figmaSnapshotAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotAdapter.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotAdapter.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,sGAAsG;AACtG,MAAM,MAAM,mBAAmB,GAAG,CAAC,aAAa,EAAE,MAAM,KAAK,mBAAmB,GAAG,SAAS,CAAC;AAE7F;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,aAAa,GAAG,mBAAmB,GAAG,SAAS,CAY5F;AAED,kGAAkG;AAClG,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,wBAAwB,KAAK,SAAS,MAAM,EAAE,CAAC;AAE/F;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,MAAM,KACZ,SAAS,MAAM,EAAE,CAAC;AAOvB;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,aAAa,EACnB,UAAU,CAAC,EAAE,eAAe,GAC3B,uBAAuB,CAazB"}
+{"version":3,"file":"figmaSnapshotAdapter.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotAdapter.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,sGAAsG;AACtG,MAAM,MAAM,mBAAmB,GAAG,CAAC,aAAa,EAAE,MAAM,KAAK,mBAAmB,GAAG,SAAS,CAAC;AAE7F,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,aAAa,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,mBAAmB,GAAG,SAAS,CA0BjC;AAED,kGAAkG;AAClG,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,wBAAwB,KAAK,SAAS,MAAM,EAAE,CAAC;AAE/F;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,MAAM,KACZ,SAAS,MAAM,EAAE,CAAC;AAOvB;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,aAAa,EACnB,UAAU,CAAC,EAAE,eAAe,GAC3B,uBAAuB,CAazB"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figmaSnapshotAdapter.js

@@ -20,14 +20,27 @@ import { resolveQiMultimodalSelection } from "./modelSelection.js";
  * Build the snapshot loader. Returns `undefined` when `deps.evidenceDir` is not configured so the
  * ingestion layer maps an attempted figma-snapshot source to QI_FIGMA_SNAPSHOT_UNAVAILABLE.
  */
-export function makeFigmaSnapshotLoader(deps) {
+export function makeFigmaSnapshotLoader(deps, options) {
     const evidenceDir = deps.evidenceDir;
     if (evidenceDir === undefined || evidenceDir.length === 0)
         return undefined;
     const store = createNodeFigmaSnapshotStore(evidenceDir);
+    const resolveLatest = options?.resolveLatestByScope === true;
     return (snapshotRunId) => {
         try {
-            return store.load(snapshotRunId);
+            const pinned = store.load(snapshotRunId);
+            if (pinned === undefined || !resolveLatest)
+                return pinned;
+            const entries = store.listByScope(pinned.provenance.fileKey, pinned.provenance.nodeId);
+            const newest = entries[0];
+            if (newest === undefined ||
+                newest.runId === pinned.runId ||
+                newest.integrityHash === pinned.integrityHash) {
+                return pinned;
+            }
+            // Fall back to the pinned record when the newest record fails to load — drift detection
+            // must degrade to "fresh", never crash the re-check.
+            return store.load(newest.runId) ?? pinned;
         }
         catch {
             // A malformed / unreadable record is treated as "not found"; the caller emits a coded error.

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figmaSnapshotOrchestration.d.ts

@@ -14,6 +14,15 @@ export interface GovernedSnapshotDeps {
     readonly pagination?: Partial<ScopedPaginationLimits>;
     /** Shared enterprise egress settings for Figma API + render downloads (#802). */
     readonly egress?: OutboundHttpEgressConfig | undefined;
+    /**
+     * Creation-time overrides forwarded to the default HTTP and render ports when no explicit
+     * httpPort/renderPort is injected. Currently only `timeoutMs` (maps to
+     * KEIKO_FIGMA_REQUEST_TIMEOUT_MS). Ignored when httpPort/renderPort are injected directly
+     * (route tests supply fakes that honour their own timeouts).
+     */
+    readonly portOptions?: {
+        readonly timeoutMs?: number;
+    };
     readonly httpPort?: FigmaHttpPort;
     readonly renderPort?: FigmaRenderPort;
     readonly keychainAccess?: FigmaKeychainAccess;

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figmaSnapshotOrchestration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotOrchestration.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotOrchestration.ts"],"names":[],"mappings":"AAeA,OAAO,EAOL,qBAAqB,EAQrB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iDAAiD,CAAC;AAKhG,KAAK,cAAc,GAAG,wBAAwB,CAAC,cAAc,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACtD,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;IAEvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC;CAC/C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC;AAMD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,oBAAoB,KAAG,MAAM,GAAG,SAWzE,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,GAC7B,MAAM,IAAI,CAAC,oBAAoB,EAAE,KAAK,GAAG,aAAa,GAAG,gBAAgB,CAAC,KACzE,UAAU,CAAC,OAAO,qBAAqB,CAOzC,CAAC;AAqDF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,MAAM,EACjB,MAAM,oBAAoB,EAC1B,sBAAoB,KACnB,OAAO,CAAC,sBAAsB,CAiDhC,CAAC"}
+{"version":3,"file":"figmaSnapshotOrchestration.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotOrchestration.ts"],"names":[],"mappings":"AAeA,OAAO,EAOL,qBAAqB,EAQrB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iDAAiD,CAAC;AAKhG,KAAK,cAAc,GAAG,wBAAwB,CAAC,cAAc,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACtD,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC;CAC/C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC;AAMD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,oBAAoB,KAAG,MAAM,GAAG,SAWzE,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,GAC7B,MAAM,IAAI,CAAC,oBAAoB,EAAE,KAAK,GAAG,aAAa,GAAG,gBAAgB,CAAC,KACzE,UAAU,CAAC,OAAO,qBAAqB,CAOzC,CAAC;AAqDF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,MAAM,EACjB,MAAM,oBAAoB,EAC1B,sBAAoB,KACnB,OAAO,CAAC,sBAAsB,CAmDhC,CAAC"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figmaSnapshotOrchestration.js

@@ -91,8 +91,8 @@ export const governedSnapshotBuild = async (boardLink, deps, isResnapshot = fals
     if (target === null)
         throw new FigmaConnectorError("FIGMA_MALFORMED_URL");
     const scopeRef = deriveFigmaScopeRef(target.fileKey, target.nodeId);
-    const httpPort = deps.httpPort ?? createDefaultFigmaHttpPort(deps.egress);
-    const renderPort = deps.renderPort ?? createDefaultFigmaRenderPort(deps.egress);
+    const httpPort = deps.httpPort ?? createDefaultFigmaHttpPort(deps.egress, undefined, deps.portOptions);
+    const renderPort = deps.renderPort ?? createDefaultFigmaRenderPort(deps.egress, undefined, deps.portOptions);
     const vaultToken = readFigmaVaultToken(deps);
     gateConsent(deps, scopeRef);
     // Render-token (vault > config > env). Throws FIGMA_TOKEN_MISSING when nothing is configured.

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figmaSnapshotRoutes.d.ts

@@ -51,7 +51,15 @@ export interface FigmaScreenSummary {
     /** Byte size of the rendered PNG. */
     readonly imageByteLength: number;
 }
-export declare function handleFigmaTriggerSnapshot(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+interface CoalescedBuildEntry {
+    readonly promise: Promise<RouteResult>;
+}
+/** Injectable for tests — returns the module-level map by default. */
+export declare function makeInFlightMap(): Map<string, CoalescedBuildEntry>;
+/** Reset the module-level coalescing map. Used by tests to ensure isolation. */
+export declare function resetInFlightMap(): void;
+export declare function handleFigmaTriggerSnapshot(ctx: RouteContext, deps: UiHandlerDeps, inFlight?: Map<string, CoalescedBuildEntry>): Promise<RouteResult>;
 export declare function handleFigmaRevokeToken(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
 export declare function handleFigmaLoadSnapshot(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export {};
 //# sourceMappingURL=figmaSnapshotRoutes.d.ts.map

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figmaSnapshotRoutes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotRoutes.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EAOL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EAExB,MAAM,kBAAkB,CAAC;AAgH1B,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAmMD,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAkCtB;AAID,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CA4B1F;AAID,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAwB3F"}
+{"version":3,"file":"figmaSnapshotRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotRoutes.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EAOL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EAExB,MAAM,kBAAkB,CAAC;AAoI1B,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAgOD,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CACxC;AAMD,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAElE;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAmED,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,EACnB,QAAQ,GAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAsB,GAC9D,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAID,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CA4B1F;AAID,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAwB3F"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figmaSnapshotRoutes.js

@@ -19,6 +19,28 @@
 //
 // Both routes honour the existing QI error-envelope convention:
 //   { error: { code: string; message: string } }
+//
+// In-flight coalescing (item 2):
+//   Concurrent POSTs for the same scope (fileKey:nodeId) share ONE build promise. The FIRST
+//   caller starts the governed build, mints the runId ONCE, persists ONCE (inside the build
+//   chain so a deadline-expired-but-completed build still persists and is recoverable via an
+//   immediate retry POST). Subsequent callers await the same promise and receive the same
+//   runId/response. The entry is removed on settle (finally). Failures propagate to all
+//   waiters with the same coded error.
+//
+// Build deadline (item 3):
+//   KEIKO_FIGMA_BUILD_DEADLINE_MS (default 600 000 ms). The awaiting handler races the
+//   coalesced build promise against a deadline rejection. On deadline the handler responds
+//   504 FIGMA_BUILD_TIMEOUT WITHOUT a runId. The coalesced build itself continues (other
+//   waiters may exist); persist is INSIDE the build chain, so if/when the build completes
+//   a subsequent POST for the same scope finds the map empty and re-coalesces cheaply.
+//   The underlying build is bounded by per-fetch timeouts and pagination budgets.
+//
+// Client disconnect (item 4):
+//   The handler listens for the 'close' event on ctx.req. On disconnect the per-waiter
+//   race resolves promptly (504 FIGMA_BUILD_TIMEOUT body never sent over the wire).
+//   The coalesced build continues — other waiters (if any) are unaffected and will
+//   receive the result when the build settles.
 import { randomUUID } from "node:crypto";
 import { currentGatewayEgressConfig } from "../deps.js";
 import { parseFigmaTarget, deriveFigmaScopeRef, observeFigmaRevoke, EXPECTED_FIGMA_SCOPES, FigmaConnectorError, } from "./figma/index.js";
@@ -35,9 +57,16 @@ const FIGMA_ROUTE_ERROR_MESSAGES = {
     FIGMA_UPSTREAM_UNAVAILABLE: "Figma API is temporarily unavailable. Please try again.",
     FIGMA_PROXY_EGRESS_FAILED: "The forward proxy rejected the Figma egress request. Check proxy configuration.",
     FIGMA_PROXY_UNREACHABLE: "The configured forward proxy is unreachable. Check proxy host and port settings.",
+    FIGMA_PROXY_AUTH_REQUIRED: "The forward proxy requires authentication. Configure proxy credentials or an allow rule.",
+    FIGMA_PROXY_BLOCKED_BY_POLICY: "The forward proxy blocked the Figma egress request. Ask the proxy operator to allow api.figma.com.",
     FIGMA_TLS_CA_FAILURE: "The Figma egress TLS certificate could not be verified. Check the configured CA bundle.",
     FIGMA_RATE_LIMITED: "Figma rate-limited the snapshot-build. Please wait a moment and try again.",
     FIGMA_OVERSIZED_SCOPE: "The selected Figma board section is too large. Select a smaller section (frame or page).",
+    FIGMA_RESPONSE_TOO_LARGE: "The Figma API response exceeded the size limit. Select a smaller section.",
+    FIGMA_NETWORK_UNREACHABLE: "The outbound request to Figma failed. Check network connectivity and egress policy.",
+    FIGMA_EGRESS_TIMEOUT: "The Figma request timed out. Retry or raise KEIKO_FIGMA_REQUEST_TIMEOUT_MS.",
+    FIGMA_EGRESS_FAILED: "The outbound request to Figma failed before a response was received.",
+    FIGMA_BUILD_TIMEOUT: "The snapshot build exceeded the configured deadline. No partial snapshot was stored.",
     FIGMA_INTERNAL: "An unexpected error occurred during the snapshot-build.",
     FIGMA_BAD_LINK: "The board link is not a valid Figma URL, or it is missing a node-id " +
         "(section/frame anchor required).",
@@ -55,7 +84,7 @@ function figmaErrorBody(code) {
     // board reference — only the static scope strings.
     return code === "FIGMA_CONSENT_REQUIRED" ? { ...base, scopes: EXPECTED_FIGMA_SCOPES } : base;
 }
-// Codes that map to 502 (upstream/auth problems, not client errors).
+// Codes that map to 502 (upstream/auth/egress problems, not client errors).
 const FIGMA_502_CODES = new Set([
     "FIGMA_TOKEN_MISSING",
     "FIGMA_TOKEN_INVALID",
@@ -64,8 +93,14 @@ const FIGMA_502_CODES = new Set([
     "FIGMA_INSUFFICIENT_SCOPE",
     "FIGMA_PROXY_EGRESS_FAILED",
     "FIGMA_PROXY_UNREACHABLE",
+    "FIGMA_PROXY_AUTH_REQUIRED",
+    "FIGMA_PROXY_BLOCKED_BY_POLICY",
     "FIGMA_TLS_CA_FAILURE",
     "FIGMA_UPSTREAM_UNAVAILABLE",
+    "FIGMA_NETWORK_UNREACHABLE",
+    "FIGMA_EGRESS_TIMEOUT",
+    "FIGMA_EGRESS_FAILED",
+    "FIGMA_RESPONSE_TOO_LARGE",
 ]);
 function figmaStatusForCode(code) {
     if (FIGMA_502_CODES.has(code))
@@ -79,6 +114,8 @@ function figmaStatusForCode(code) {
     // Precondition Required: the operator must acknowledge the read-only scope before the build (#760).
     if (code === "FIGMA_CONSENT_REQUIRED")
         return 428;
+    if (code === "FIGMA_BUILD_TIMEOUT")
+        return 504;
     return 500;
 }
 // ─── Body reader ───────────────────────────────────────────────────────────────
@@ -245,6 +282,25 @@ function figmaPaginationFromEnv(env) {
     apply("fetchConcurrency", "KEIKO_FIGMA_FETCH_CONCURRENCY");
     return overrides;
 }
+/** Default total snapshot-build deadline in milliseconds (10 minutes). */
+const DEFAULT_BUILD_DEADLINE_MS = 600_000;
+/** Default per-fetch request timeout in milliseconds (1 minute). */
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+// Parses a positive-integer env var, returning the default when the value is absent or invalid.
+function readPositiveIntEnv(raw, defaultValue) {
+    if (raw === undefined)
+        return defaultValue;
+    const value = Number(raw);
+    return Number.isInteger(value) && value > 0 ? value : defaultValue;
+}
+/** KEIKO_FIGMA_BUILD_DEADLINE_MS — total build deadline used by the coalesced promise race. */
+function figmaBuildDeadlineMsFromEnv(env) {
+    return readPositiveIntEnv(env.KEIKO_FIGMA_BUILD_DEADLINE_MS, DEFAULT_BUILD_DEADLINE_MS);
+}
+/** KEIKO_FIGMA_REQUEST_TIMEOUT_MS — per-fetch timeout threaded into the transport ports. */
+function figmaRequestTimeoutMsFromEnv(env) {
+    return readPositiveIntEnv(env.KEIKO_FIGMA_REQUEST_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS);
+}
 // Map a thrown error from the governed build to a coded route result: a coded connector error maps to
 // its status (consent-required → 428, auth → 502, rate-limit → 429, …); anything else is a safe 500.
 function figmaErrorResult(err) {
@@ -287,8 +343,69 @@ function persistSnapshot(evidenceDir, runId, result) {
         return { status: 500, body: figmaErrorBody("FIGMA_INTERNAL") };
     return record;
 }
+// The map is module-level so it is shared across concurrent requests on the same server instance.
+// It is exposed via makeInFlightMap so tests can inject a fresh map (isolation without mocking).
+let defaultInFlightMap = new Map();
+/** Injectable for tests — returns the module-level map by default. */
+export function makeInFlightMap() {
+    return defaultInFlightMap;
+}
+/** Reset the module-level coalescing map. Used by tests to ensure isolation. */
+export function resetInFlightMap() {
+    defaultInFlightMap = new Map();
+}
+/** Derive the scope key (fileKey:nodeId) for the in-flight map. */
+function scopeKeyFor(boardLink) {
+    const target = parseFigmaTarget(boardLink);
+    if (target === null)
+        return undefined;
+    return `${target.fileKey}:${target.nodeId}`;
+}
+// Starts the governed build + persist and removes the map entry on settle.
+// Persist is INSIDE this chain: if a caller's deadline fires but the build later completes,
+// the record is stored and an immediate retry POST coalesces or finds it via the GET route.
+function startCoalescedBuild(scopeKey, inFlight, boardLink, body, evidenceDir, deps) {
+    const buildAndPersist = async () => {
+        let result;
+        try {
+            // The governed build resolves the vault>config>env PAT (#758), gates on recorded read-only
+            // consent before any egress + audits the action + computes metrics (#760), and deep-fetches +
+            // renders within the snapshot boundary (#837/#759). Errors (incl. consent-required) are coded.
+            result = await governedSnapshotBuild(boardLink, {
+                evidenceDir,
+                env: deps.env,
+                now: new Date().toISOString(),
+                acknowledgeReadOnly: body.acknowledgeReadOnly,
+                pagination: figmaPaginationFromEnv(deps.env),
+                egress: currentGatewayEgressConfig(deps),
+                portOptions: { timeoutMs: figmaRequestTimeoutMsFromEnv(deps.env) },
+            }, body.isResnapshot);
+        }
+        catch (err) {
+            return figmaErrorResult(err);
+        }
+        const runId = `fs-${randomUUID()}`;
+        const stored = persistSnapshot(evidenceDir, runId, result);
+        if ("status" in stored)
+            return stored;
+        return { status: 201, body: recordToSummary(stored, result.coverage, result.metrics) };
+    };
+    const promise = buildAndPersist().finally(() => {
+        inFlight.delete(scopeKey);
+    });
+    inFlight.set(scopeKey, { promise });
+    return promise;
+}
+// Returns a promise that rejects with a FIGMA_BUILD_TIMEOUT error after `ms` milliseconds.
+function deadlineRejection(ms) {
+    return new Promise((_resolve, reject) => {
+        setTimeout(() => {
+            reject(new FigmaConnectorError("FIGMA_BUILD_TIMEOUT"));
+        }, ms);
+    });
+}
 // ─── POST /api/figma/snapshots ─────────────────────────────────────────────────
-export async function handleFigmaTriggerSnapshot(ctx, deps) {
+export async function handleFigmaTriggerSnapshot(ctx, deps, inFlight = defaultInFlightMap) {
     const evidenceDir = deps.evidenceDir;
     if (evidenceDir === undefined || evidenceDir.length === 0) {
         return { status: 503, body: figmaErrorBody("FIGMA_NO_EVIDENCE_DIR") };
@@ -297,28 +414,30 @@ export async function handleFigmaTriggerSnapshot(ctx, deps) {
     if ("status" in bodyResult)
         return bodyResult;
     const body = bodyResult;
-    let result;
+    const scopeKey = scopeKeyFor(body.boardLink);
+    if (scopeKey === undefined) {
+        // parseTriggerBody already validates the board link; this is a belt-and-suspenders guard.
+        return { status: 400, body: figmaErrorBody("FIGMA_BAD_LINK") };
+    }
+    // Coalesce: join an existing build for this scope, or start a new one.
+    const existing = inFlight.get(scopeKey);
+    const buildPromise = existing !== undefined
+        ? existing.promise
+        : startCoalescedBuild(scopeKey, inFlight, body.boardLink, body, evidenceDir, deps);
+    const deadlineMs = figmaBuildDeadlineMsFromEnv(deps.env);
+    // Per-waiter race: deadline + client-disconnect both resolve this waiter promptly while the
+    // coalesced build (and its persist) continues uninterrupted for other waiters.
+    const disconnectPromise = new Promise((_resolve, reject) => {
+        ctx.req.once("close", () => {
+            reject(new FigmaConnectorError("FIGMA_BUILD_TIMEOUT"));
+        });
+    });
     try {
-        // The governed build resolves the vault>config>env PAT (#758), gates on recorded read-only
-        // consent before any egress + audits the action + computes metrics (#760), and deep-fetches +
-        // renders within the snapshot boundary (#837/#759). Errors (incl. consent-required) are coded.
-        result = await governedSnapshotBuild(body.boardLink, {
-            evidenceDir,
-            env: deps.env,
-            now: new Date().toISOString(),
-            acknowledgeReadOnly: body.acknowledgeReadOnly,
-            pagination: figmaPaginationFromEnv(deps.env),
-            egress: currentGatewayEgressConfig(deps),
-        }, body.isResnapshot);
+        return await Promise.race([buildPromise, deadlineRejection(deadlineMs), disconnectPromise]);
     }
     catch (err) {
         return figmaErrorResult(err);
     }
-    const runId = `fs-${randomUUID()}`;
-    const stored = persistSnapshot(evidenceDir, runId, result);
-    if ("status" in stored)
-        return stored;
-    return { status: 201, body: recordToSummary(stored, result.coverage, result.metrics) };
 }
 // ─── DELETE /api/figma/token — revoke the stored PAT (#758 rotation/revocation, #760 audit) ───
 export function handleFigmaRevokeToken(ctx, deps) {