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

package/node_modules/@oscharko-dev/keiko-evidence/dist/qualityIntelligence/companionStore.js

@@ -12,7 +12,7 @@
 import { randomUUID } from "node:crypto";
 import { chmodSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join, resolve } from "node:path";
-import { assertContainedRealPath, resolveWithinWorkspace, } from "@oscharko-dev/keiko-workspace";
+import { 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";
@@ -37,11 +37,27 @@ function realBaseForRead(baseDir, fs) {
         throw new EvidenceReadError(`cannot read QI companion directory: ${error instanceof Error ? error.message : "unknown"}`);
     }
 }
-function containedPath(runId, suffix, realBase, fs) {
+function lexicalArtifactPath(runId, suffix, realBase) {
     assertValidRunId(runId);
     const name = `${runId}${suffix}`;
-    const lexical = resolveWithinWorkspace(realBase, name);
-    return assertContainedRealPath(fs, realBase, lexical, name);
+    return resolveWithinWorkspace(realBase, name);
+}
+function isSingleLinkRegularFile(path, fs) {
+    try {
+        const stat = fs.stat(path);
+        return stat.isFile && (stat.hardLinkCount ?? 1) <= 1;
+    }
+    catch (error) {
+        throw new EvidenceReadError(`cannot inspect QI companion: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function assertWritableArtifactEntry(target, fs) {
+    const entry = lstatSync(target, { throwIfNoEntry: false });
+    if (entry === undefined)
+        return;
+    if (!entry.isFile() || !isSingleLinkRegularFile(target, fs)) {
+        throw new EvidenceWriteError("cannot overwrite a non-ledger QI companion artifact");
+    }
 }
 function atomicWrite(target, json, randomSuffix) {
     const temp = `${target}.${randomSuffix()}.tmp`;
@@ -68,6 +84,8 @@ function readArtifactFile(baseDir, fs, suffix, parse, runId) {
     const target = join(realBase, `${runId}${suffix}`);
     if (lstatSync(target, { throwIfNoEntry: false })?.isFile() !== true)
         return undefined;
+    if (!isSingleLinkRegularFile(target, fs))
+        return undefined;
     let parsed;
     try {
         parsed = JSON.parse(readFileSync(target, "utf8"));
@@ -82,9 +100,11 @@ function deleteArtifactFile(baseDir, fs, suffix, runId) {
     const realBase = realBaseForRead(baseDir, fs);
     if (realBase === undefined)
         return false;
-    const target = containedPath(runId, suffix, realBase, fs);
+    const target = lexicalArtifactPath(runId, suffix, realBase);
     if (lstatSync(target, { throwIfNoEntry: false })?.isFile() !== true)
         return false;
+    if (!isSingleLinkRegularFile(target, fs))
+        return false;
     rmSync(target, { force: true });
     return true;
 }
@@ -101,8 +121,8 @@ export function createNodeContainedJsonArtifactStore(evidenceDir, suffix, option
         record: (runId, value) => {
             assertValidRunId(runId);
             const realBase = realBaseForWrite(baseDir, fs);
-            const target = containedPath(runId, suffix, realBase, fs);
-            rmSync(target, { force: true });
+            const target = lexicalArtifactPath(runId, suffix, realBase);
+            assertWritableArtifactEntry(target, fs);
             atomicWrite(target, JSON.stringify(value), randomSuffix);
             return target;
         },
@@ -113,7 +133,7 @@ export function createNodeContainedJsonArtifactStore(evidenceDir, suffix, option
             const realBase = realBaseForRead(baseDir, fs);
             return realBase === undefined
                 ? join(resolve(baseDir), `${runId}${suffix}`)
-                : containedPath(runId, suffix, realBase, fs);
+                : lexicalArtifactPath(runId, suffix, realBase);
         },
     };
 }
@@ -124,9 +144,9 @@ export function createNodeContainedJsonArtifactStore(evidenceDir, suffix, option
  * that live alongside the run manifest. EXACT-suffix matching is mandatory: a non-leading `.` is a
  * legal runId character (`assertValidRunId`), so `run-1` and `run-1.2` can coexist and a prefix
  * (`startsWith`) sweep would let deleting `run-1` destroy `run-1.2`'s companion. By deriving the
- * full `${runId}${suffix}` name and resolving it through `assertContainedRealPath`, the delete is
- * collision-free, realpath-contained, and symlink-refusing (`deleteArtifactFile` lstat-gates
- * `isFile`, which is false for a symlink). Returns true iff a regular file was removed.
+ * full `${runId}${suffix}` name from the validated run id, the delete is collision-free,
+ * realpath-contained at the base, and symlink-refusing (`deleteArtifactFile` lstat-gates `isFile`,
+ * which is false for a symlink). Returns true iff a regular single-link file was removed.
  *
  * Intentionally NOT re-exported from the package barrel — it is an internal seam consumed only by
  * the deletion path, so the published surface stays unchanged.

package/node_modules/@oscharko-dev/keiko-evidence/dist/qualityIntelligence/figmaSnapshot/schema.d.ts

@@ -11,7 +11,7 @@ export interface FigmaSnapshotImageRef {
  * the FigmaConnectorErrorCode suffix when the download threw a coded error, letting retention
  * and metrics distinguish misconfigured egress from an unclassified network flake.
  */
-export type FigmaSnapshotSkipReason = "render-url-missing" | "render-url-blocked" | "render-fetch-failed" | `render-fetch-failed:${string}` | "render-empty" | "render-oversized";
+export type FigmaSnapshotSkipReason = "render-url-missing" | "render-url-blocked" | "render-screen-cap-exceeded" | "render-fetch-failed" | `render-fetch-failed:${string}` | "render-empty" | "render-oversized";
 export interface FigmaSnapshotSkippedScreenRow {
     readonly screenId: string;
     readonly reason: FigmaSnapshotSkipReason;
@@ -28,7 +28,7 @@ export interface FigmaSnapshotScreenRow {
  * a record without `links` (e.g. an older snapshot) is still valid and the navigation derivation
  * degrades to zero nav items. NOT part of any integrity hash — `links` is non-identity design
  * metadata, so adding it does not change the drift hash (#735). Node ids + trigger are design content
- * (already redaction-safe); no token, secret, or url ever reaches this shape.
+ * (already redaction-safe); no token, secret, or outbound URL ever reaches this shape.
  */
 export interface FigmaSnapshotLinkRow {
     readonly sourceNodeId: string;
@@ -47,6 +47,34 @@ export interface FigmaSnapshotRedactionSummary {
     readonly stringsRedacted: number;
     readonly patternsMatched: Readonly<Record<string, number>>;
 }
+/** Tamper-evidence for optional #752 artifacts that are hash-neutral for drift identity. */
+export interface FigmaSnapshotArtifactHashes {
+    readonly links?: string;
+    readonly tokens?: string;
+    readonly metrics?: string;
+}
+export interface FigmaSnapshotAugmentationMetrics {
+    readonly deterministic: number;
+    readonly modelAugmented: number;
+    readonly modelAugmentedShare: number;
+}
+export interface FigmaSnapshotNavGraphMetrics {
+    readonly screens: number;
+    readonly transitions: number;
+}
+export interface FigmaSnapshotA11yMetrics {
+    readonly findings: number;
+}
+/** Numeric-only operational metrics from Issue #760. No ids, names, links, text, or token. */
+export interface FigmaSnapshotMetrics {
+    readonly reductionRatio: number;
+    readonly screenCount: number;
+    readonly renderCount: number;
+    readonly designTokenCount: number;
+    readonly augmentation: FigmaSnapshotAugmentationMetrics;
+    readonly navGraph?: FigmaSnapshotNavGraphMetrics;
+    readonly a11y?: FigmaSnapshotA11yMetrics;
+}
 export interface FigmaSnapshotRecord {
     readonly figmaSnapshotSchemaVersion: typeof FIGMA_SNAPSHOT_SCHEMA_VERSION;
     readonly runId: string;
@@ -62,9 +90,13 @@ export interface FigmaSnapshotRecord {
      * fields they come from are pruned out of the lean per-screen IR). OPTIONAL + additive: a record
      * without `tokens` (an older snapshot) is still valid and code-gen emits an empty token table. NOT
      * part of any integrity hash — design tokens are non-identity design metadata, so adding them does
-     * not change the drift hash (#735). Design content (no token/secret/url ever reaches this shape).
+     * not change the drift hash (#735). Design content (no token/secret/outbound URL reaches this shape).
      */
     readonly tokens?: unknown;
+    /** Durable numeric operational metrics (#760), safe to expose and reload with the snapshot. */
+    readonly metrics?: FigmaSnapshotMetrics;
+    /** Separate integrity hashes for optional hash-neutral artifacts (`links`/`tokens`) when present. */
+    readonly artifactHashes?: FigmaSnapshotArtifactHashes;
     readonly integrityHash: string;
     readonly redactionSummary: FigmaSnapshotRedactionSummary;
 }

package/node_modules/@oscharko-dev/keiko-evidence/dist/qualityIntelligence/figmaSnapshot/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figmaSnapshot/schema.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,6BAA6B,EAAG,CAAU,CAAC;AAExD,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAC/B,oBAAoB,GACpB,oBAAoB,GACpB,qBAAqB,GACrB,uBAAuB,MAAM,EAAE,GAC/B,cAAc,GACd,kBAAkB,CAAC;AAEvB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;CAC1C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,8FAA8F;AAC9F,MAAM,WAAW,0BAA0B;IACzC,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;CAC5B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,0BAA0B,EAAE,OAAO,6BAA6B,CAAC;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACpD,QAAQ,CAAC,cAAc,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAClE,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,6BAA6B,CAAC;CAC1D;AAcD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAID,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,6BAA6B,CAoBzF"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figmaSnapshot/schema.ts"],"names":[],"mappings":"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"}

package/node_modules/@oscharko-dev/keiko-evidence/dist/qualityIntelligence/figmaSnapshot/schema.js

@@ -3,12 +3,15 @@
 // The immutable, redaction-safe on-disk shape of a Figma Snapshot. It mirrors the QI evidence
 // manifest posture: a breaking change introduces a NEW `figmaSnapshotSchemaVersion` literal rather
 // than mutating this one; every string leaf has passed through redaction before persist; NO token,
-// NO secret, NO outbound url, NO header reaches this shape.
+// NO secret, NO outbound Figma/render URL, NO header reaches this shape.
 //
 // The rendered PNG bytes do NOT live inline — they are written as binary side-files and referenced
 // here by relative path + sha256 (the same tamper-evidence pattern as ADR-0017 side-files). The
-// integrity hashes are computed by the server builder over the in-memory Snapshot BEFORE persist
-// and are reproduced here verbatim, so a loaded record can be drift-checked against #735.
+// integrity hashes follow the server builder's deterministic hash projection but are recomputed by
+// the evidence store after redaction so they describe the exact persisted artifact. A loaded record
+// can then be drift-checked against #735. Optional #752 metadata (`links`, `tokens`) keeps separate
+// artifact hashes: they are not drift identity, but downstream consumers must not trust a tampered
+// artifact under an otherwise-valid drift hash.
 //
 // `irJson` is the structural Screen-IR (#752) serialised as an opaque JSON value. It is design
 // CONTENT — the artifact's purpose — and is kept (not redacted away); only secrets are stripped.
@@ -21,9 +24,104 @@ const ALLOWED_TOP_LEVEL_KEYS = new Set([
     "skippedScreens",
     "links",
     "tokens",
+    "metrics",
+    "artifactHashes",
     "integrityHash",
     "redactionSummary",
 ]);
+const ALLOWED_ARTIFACT_HASH_KEYS = new Set([
+    "links",
+    "tokens",
+    "metrics",
+]);
+const ALLOWED_METRICS_KEYS = new Set([
+    "reductionRatio",
+    "screenCount",
+    "renderCount",
+    "designTokenCount",
+    "augmentation",
+    "navGraph",
+    "a11y",
+]);
+const ALLOWED_AUGMENTATION_KEYS = new Set([
+    "deterministic",
+    "modelAugmented",
+    "modelAugmentedShare",
+]);
+const ALLOWED_NAV_GRAPH_KEYS = new Set(["screens", "transitions"]);
+const ALLOWED_A11Y_KEYS = new Set(["findings"]);
+const REQUIRED_METRIC_KEYS = [
+    "reductionRatio",
+    "screenCount",
+    "renderCount",
+    "designTokenCount",
+];
+function validateArtifactHashes(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, reason: "artifactHashes must be an object" };
+    }
+    for (const key of Object.keys(value)) {
+        if (!ALLOWED_ARTIFACT_HASH_KEYS.has(key)) {
+            return { ok: false, reason: `unknown artifactHashes key: ${key}` };
+        }
+    }
+    return undefined;
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function keysAllowed(value, allowed) {
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function validateObjectNumbers(value, allowed, required, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, reason: `${label} must be an object` };
+    }
+    const record = value;
+    if (!keysAllowed(record, allowed)) {
+        return { ok: false, reason: `${label} has unknown keys` };
+    }
+    for (const key of required) {
+        if (!finiteNumber(record[key]))
+            return { ok: false, reason: `${label}.${key} must be a number` };
+    }
+    return undefined;
+}
+function validateRequiredNumbers(record, keys, label) {
+    for (const key of keys) {
+        if (!finiteNumber(record[key]))
+            return { ok: false, reason: `${label}.${key} must be a number` };
+    }
+    return undefined;
+}
+function validateOptionalNumberObject(record, key, allowed, required) {
+    if (record[key] === undefined)
+        return undefined;
+    return validateObjectNumbers(record[key], allowed, required, `metrics.${key}`);
+}
+function validateMetrics(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, reason: "metrics must be an object" };
+    }
+    const metrics = value;
+    if (!keysAllowed(metrics, ALLOWED_METRICS_KEYS)) {
+        return { ok: false, reason: "metrics has unknown keys" };
+    }
+    const required = validateRequiredNumbers(metrics, REQUIRED_METRIC_KEYS, "metrics");
+    if (required !== undefined)
+        return required;
+    const aug = validateObjectNumbers(metrics.augmentation, ALLOWED_AUGMENTATION_KEYS, ["deterministic", "modelAugmented", "modelAugmentedShare"], "metrics.augmentation");
+    if (aug !== undefined)
+        return aug;
+    return (validateOptionalNumberObject(metrics, "navGraph", ALLOWED_NAV_GRAPH_KEYS, [
+        "screens",
+        "transitions",
+    ]) ?? validateOptionalNumberObject(metrics, "a11y", ALLOWED_A11Y_KEYS, ["findings"]));
+}
 // Strict-schema gate for a deserialised snapshot record: schema-version literal + closed key set.
 // Structural correctness of the integrity hashes is the builder's responsibility, not this gate's.
 export function validateFigmaSnapshotRecord(value) {
@@ -45,5 +143,11 @@ export function validateFigmaSnapshotRecord(value) {
     if (!Array.isArray(record.screens) || !Array.isArray(record.skippedScreens)) {
         return { ok: false, reason: "screens and skippedScreens must be arrays" };
     }
+    const artifactHashesValidation = validateArtifactHashes(record.artifactHashes);
+    if (artifactHashesValidation !== undefined)
+        return artifactHashesValidation;
+    const metricsValidation = validateMetrics(record.metrics);
+    if (metricsValidation !== undefined)
+        return metricsValidation;
     return { ok: true, reason: undefined };
 }

package/node_modules/@oscharko-dev/keiko-evidence/dist/qualityIntelligence/figmaSnapshot/store.d.ts

@@ -1,5 +1,5 @@
 import { type WorkspaceFs } from "@oscharko-dev/keiko-workspace";
-import { type FigmaSnapshotLinkRow, type FigmaSnapshotRecord } from "./schema.js";
+import { type FigmaSnapshotImageRef, type FigmaSnapshotLinkRow, type FigmaSnapshotMetrics, type FigmaSnapshotRecord } from "./schema.js";
 export interface RecordFigmaSnapshotScreenInput {
     readonly screenId: string;
     readonly irJson: unknown;
@@ -27,6 +27,8 @@ export interface RecordFigmaSnapshotInput {
     readonly links?: readonly FigmaSnapshotLinkRow[];
     /** Deterministic design-tokens artifact (#752), opaque, for design-to-code (#755). Optional. */
     readonly tokens?: unknown;
+    /** Numeric operational metrics (#760). Optional for older snapshots. */
+    readonly metrics?: FigmaSnapshotMetrics;
 }
 export interface RecordFigmaSnapshotResult {
     readonly recordPath: string;
@@ -38,9 +40,21 @@ export interface FigmaSnapshotScopeEntry {
     readonly fetchedAt: string;
     readonly integrityHash: string;
 }
+export interface FigmaSnapshotImageBytes {
+    readonly mimeType: "image/png";
+    readonly bytes: Uint8Array;
+    readonly sha256: string;
+    readonly byteLength: number;
+}
 export interface FigmaSnapshotStore {
     readonly record: (input: RecordFigmaSnapshotInput) => RecordFigmaSnapshotResult;
     readonly load: (runId: string) => FigmaSnapshotRecord | undefined;
+    /**
+     * Loads and verifies the JSON snapshot record and hash graph without reading every image side-file.
+     * Callers that stream one image must then verify that requested side-file with loadImage().
+     */
+    readonly loadMetadata: (runId: string) => FigmaSnapshotRecord | undefined;
+    readonly loadImage: (runId: string, image: FigmaSnapshotImageRef) => FigmaSnapshotImageBytes;
     readonly location: (runId: string) => string;
     /**
      * List all snapshot records for a specific Figma scope, sorted by `fetchedAt` descending

package/node_modules/@oscharko-dev/keiko-evidence/dist/qualityIntelligence/figmaSnapshot/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figmaSnapshot/store.ts"],"names":[],"mappings":"AAyCA,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAOvC,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAGzB,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC;CAChF;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,8BAA8B,EAAE,CAAC;IAI5D,QAAQ,CAAC,cAAc,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3F,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD,gGAAgG;IAChG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,wEAAwE;AACxE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,yBAAyB,CAAC;IAChF,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,mBAAmB,GAAG,SAAS,CAAC;IAClE,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,SAAS,uBAAuB,EAAE,CAAC;CAC/F;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;CACtC;AAwND,MAAM,WAAW,6BAA6B;IAC5C,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,6BAA6B,GACrC,IAAI,CAkCN;AAiGD,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CA2BpB"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figmaSnapshot/store.ts"],"names":[],"mappings":"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"}