@oscharko-dev/keiko-evidence 0.2.0

package/dist/qualityIntelligence/candidatesArtifact.js

@@ -0,0 +1,258 @@
+// Quality Intelligence generated-candidate artifact (Issue #274/#280, Epic #270, ADR-0023 D8).
+//
+// The run manifest (`<runId>.qi.json`) carries only counts + refs. The reviewable, exportable
+// product — the generated test-case bodies — is persisted here as a companion artifact
+// `<runId>.candidates.json`. Bodies are redacted (every string leaf) BEFORE persist so a candidate
+// that echoed a secret-shaped source string cannot reach disk, preview, or export unredacted
+// (Issue #284). Stored as plain rows (branded IDs collapse to strings on the wire).
+import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+import { createNodeContainedJsonArtifactStore, } from "./companionStore.js";
+import { EvidenceReadError } from "../errors.js";
+export const QUALITY_INTELLIGENCE_CANDIDATES_SCHEMA_VERSION = 1;
+// Exported (but intentionally NOT re-exported from the package barrel) so the run-deletion path
+// can reference the evidence-owned companion suffix without duplicating the literal.
+export const CANDIDATES_SUFFIX = ".candidates.json";
+const cloneQualityVerdict = (verdict) => ({
+    verdict: verdict.verdict,
+    score: verdict.score,
+    dimensions: verdict.dimensions.map((dimension) => ({ ...dimension })),
+    overallRationale: verdict.overallRationale,
+});
+const toRow = (candidate) => {
+    const qualityVerdict = candidate.qualityVerdict;
+    return {
+        id: String(candidate.id),
+        title: candidate.title,
+        preconditions: [...candidate.preconditions],
+        steps: [...candidate.steps],
+        expectedResults: [...candidate.expectedResults],
+        priority: candidate.priority,
+        riskClass: candidate.riskClass,
+        tags: [...candidate.tags],
+        status: candidate.status,
+        derivedFromAtomIds: candidate.derivedFromAtomIds.map(String),
+        ...(qualityVerdict !== undefined
+            ? { qualityVerdict: cloneQualityVerdict(qualityVerdict) }
+            : {}),
+    };
+};
+const PRIORITIES = new Set(QualityIntelligence.QUALITY_INTELLIGENCE_PRIORITIES);
+const RISK_CLASSES = new Set(QualityIntelligence.QUALITY_INTELLIGENCE_RISK_CLASSES);
+const TEST_CASE_STATUSES = new Set(QualityIntelligence.QUALITY_INTELLIGENCE_TEST_CASE_STATUSES);
+const TEST_QUALITY_DIMENSIONS = new Set(QualityIntelligence.TEST_QUALITY_RUBRIC_DIMENSIONS);
+const isObjectRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+const isString = (value) => typeof value === "string";
+const isPriority = (value) => typeof value === "string" && PRIORITIES.has(value);
+const isRiskClass = (value) => typeof value === "string" && RISK_CLASSES.has(value);
+const isTestCaseStatus = (value) => typeof value === "string" && TEST_CASE_STATUSES.has(value);
+const isQualityVerdictValue = (value) => value === "strong" || value === "weak";
+const isScore = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100;
+const isDimensionScore = (value) => isScore(value) && Number.isInteger(value);
+const isRubricDimensionName = (value) => typeof value === "string" && TEST_QUALITY_DIMENSIONS.has(value);
+function isRubricDimension(value) {
+    return (isObjectRecord(value) &&
+        isRubricDimensionName(value.name) &&
+        isDimensionScore(value.score) &&
+        isString(value.rationale));
+}
+function isCandidateQualityVerdict(value) {
+    return (isObjectRecord(value) &&
+        isQualityVerdictValue(value.verdict) &&
+        isScore(value.score) &&
+        Array.isArray(value.dimensions) &&
+        value.dimensions.every(isRubricDimension) &&
+        isString(value.overallRationale));
+}
+const isEditedBy = (value) => value === "human" || value === "api";
+// An edited list field persists as an array of non-blank strings — the edit route rejects blank
+// ("") items before persist (editRoutes.ts isListField). Empty arrays are accepted on read so a
+// legitimately-cleared preconditions/tags list still loads: strict on write, fail-open on read. The
+// route additionally enforces minItems:1 for steps/expectedResults, but that is a write-time domain
+// rule (a body must have at least one step); on read we stay deliberately fail-open for every list
+// field here — this validator only gates the provenance log shape, never the candidate row itself
+// (rows carry the merged effective value, validated separately by isStringArray).
+const isListOfNonBlankStrings = (value) => Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0);
+const EDITABLE_FIELD_VALIDATORS = {
+    title: isNonEmptyString,
+    preconditions: isListOfNonBlankStrings,
+    steps: isListOfNonBlankStrings,
+    expectedResults: isListOfNonBlankStrings,
+    priority: isPriority,
+    riskClass: isRiskClass,
+    tags: isListOfNonBlankStrings,
+};
+function isEditableFields(value) {
+    if (!isObjectRecord(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.every((key) => EDITABLE_FIELD_VALIDATORS[key]?.(value[key]) ?? false);
+}
+const CANDIDATE_ROW_VALIDATORS = [
+    (row) => isNonEmptyString(row.id),
+    (row) => isNonEmptyString(row.title),
+    (row) => isStringArray(row.preconditions),
+    (row) => isStringArray(row.steps),
+    (row) => isStringArray(row.expectedResults),
+    (row) => isPriority(row.priority),
+    (row) => isRiskClass(row.riskClass),
+    (row) => isStringArray(row.tags),
+    (row) => isTestCaseStatus(row.status),
+    (row) => isStringArray(row.derivedFromAtomIds),
+    (row) => row.qualityVerdict === undefined || isCandidateQualityVerdict(row.qualityVerdict),
+];
+function isCandidateRow(value) {
+    return isObjectRecord(value) && CANDIDATE_ROW_VALIDATORS.every((validate) => validate(value));
+}
+function isEditedRevision(value) {
+    if (!isObjectRecord(value))
+        return false;
+    const provenance = value.provenance;
+    return (isNonEmptyString(value.candidateId) &&
+        isObjectRecord(provenance) &&
+        isNonEmptyString(provenance.editedAt) &&
+        isEditedBy(provenance.editedBy) &&
+        isNonEmptyString(provenance.editorLabel) &&
+        isEditableFields(value.editedFields));
+}
+function invalidArtifact(message) {
+    throw new EvidenceReadError(message);
+}
+function readArtifactStringField(record, key, message) {
+    const value = record[key];
+    if (!isNonEmptyString(value))
+        invalidArtifact(message);
+    return value;
+}
+function readArtifactCandidates(record) {
+    const { candidates } = record;
+    if (!Array.isArray(candidates) || !candidates.every(isCandidateRow)) {
+        invalidArtifact("QI candidates companion schema invalid: candidates[] has an invalid row");
+    }
+    return candidates;
+}
+function readArtifactEditedRevisions(record) {
+    const { editedRevisions } = record;
+    if (editedRevisions === undefined)
+        return undefined;
+    if (!Array.isArray(editedRevisions) || !editedRevisions.every(isEditedRevision)) {
+        invalidArtifact("QI candidates companion schema invalid: editedRevisions[] has an invalid revision");
+    }
+    return editedRevisions;
+}
+// Strict-schema gate on read: reject any artifact whose version literal drifts so a stale or
+// tampered file fails closed instead of surfacing a wrong shape to the BFF.
+const parseArtifact = (value) => {
+    if (!isObjectRecord(value)) {
+        invalidArtifact("QI candidates companion schema invalid: expected an object");
+    }
+    const record = value;
+    if (record.qiCandidatesSchemaVersion !== QUALITY_INTELLIGENCE_CANDIDATES_SCHEMA_VERSION) {
+        invalidArtifact("QI candidates companion schema invalid: unsupported schema version");
+    }
+    const runId = readArtifactStringField(record, "runId", "QI candidates companion schema invalid: runId must be a string");
+    const generatedAt = readArtifactStringField(record, "generatedAt", "QI candidates companion schema invalid: generatedAt must be a string");
+    const candidates = readArtifactCandidates(record);
+    const editedRevisions = readArtifactEditedRevisions(record);
+    return {
+        qiCandidatesSchemaVersion: QUALITY_INTELLIGENCE_CANDIDATES_SCHEMA_VERSION,
+        runId,
+        generatedAt,
+        candidates,
+        ...(editedRevisions !== undefined ? { editedRevisions } : {}),
+    };
+};
+const storeFor = (evidenceDir) => createNodeContainedJsonArtifactStore(evidenceDir, CANDIDATES_SUFFIX, { parse: parseArtifact });
+/**
+ * Persist the generated candidate bodies for a run. Redacts every string leaf first, then writes
+ * the companion artifact atomically. Returns the on-disk location.
+ */
+export const recordQualityIntelligenceCandidates = (input) => {
+    const rows = input.candidates.map(toRow);
+    const redactedRows = input.redact(rows);
+    const redactedEditedRevisions = input.editedRevisions === undefined
+        ? undefined
+        : input.redact(input.editedRevisions);
+    const artifact = {
+        qiCandidatesSchemaVersion: QUALITY_INTELLIGENCE_CANDIDATES_SCHEMA_VERSION,
+        runId: input.runId,
+        generatedAt: input.generatedAt,
+        candidates: redactedRows,
+        ...(redactedEditedRevisions !== undefined ? { editedRevisions: redactedEditedRevisions } : {}),
+    };
+    return storeFor(input.evidenceDir).record(input.runId, artifact);
+};
+export const loadQualityIntelligenceCandidates = (runId, options) => storeFor(options.evidenceDir).load(runId);
+export const deleteQualityIntelligenceCandidates = (runId, options) => storeFor(options.evidenceDir).delete(runId);
+const EDITABLE_KEYS = [
+    "title",
+    "preconditions",
+    "steps",
+    "expectedResults",
+    "priority",
+    "riskClass",
+    "tags",
+];
+const hasEditedField = (fields) => EDITABLE_KEYS.some((key) => fields[key] !== undefined);
+const mergeRow = (row, fields) => ({
+    ...row,
+    ...(fields.title !== undefined ? { title: fields.title } : {}),
+    ...(fields.preconditions !== undefined ? { preconditions: [...fields.preconditions] } : {}),
+    ...(fields.steps !== undefined ? { steps: [...fields.steps] } : {}),
+    ...(fields.expectedResults !== undefined ? { expectedResults: [...fields.expectedResults] } : {}),
+    ...(fields.priority !== undefined ? { priority: fields.priority } : {}),
+    ...(fields.riskClass !== undefined ? { riskClass: fields.riskClass } : {}),
+    ...(fields.tags !== undefined ? { tags: [...fields.tags] } : {}),
+});
+const sameStringArray = (left, right) => left.length === right.length && left.every((item, index) => item === right[index]);
+const sameRow = (left, right) => left.id === right.id &&
+    left.title === right.title &&
+    sameStringArray(left.preconditions, right.preconditions) &&
+    sameStringArray(left.steps, right.steps) &&
+    sameStringArray(left.expectedResults, right.expectedResults) &&
+    left.priority === right.priority &&
+    left.riskClass === right.riskClass &&
+    sameStringArray(left.tags, right.tags) &&
+    left.status === right.status &&
+    sameStringArray(left.derivedFromAtomIds, right.derivedFromAtomIds);
+export const applyQualityIntelligenceCandidateEdit = (input) => {
+    if (!hasEditedField(input.editedFields))
+        return { ok: false, reason: "no-edited-fields" };
+    const store = storeFor(input.evidenceDir);
+    const artifact = store.load(input.runId);
+    if (artifact === undefined)
+        return { ok: false, reason: "artifact-not-found" };
+    const existing = artifact.candidates.find((row) => row.id === input.candidateId);
+    if (existing === undefined)
+        return { ok: false, reason: "candidate-not-found" };
+    const redactedFields = input.redact(input.editedFields);
+    const updatedRow = mergeRow(existing, redactedFields);
+    if (sameRow(existing, updatedRow)) {
+        return { ok: true, candidate: existing, changed: false };
+    }
+    const candidates = artifact.candidates.map((row) => row.id === input.candidateId ? updatedRow : row);
+    // Redact the provenance label before persist: `editorLabel` is the one user-controlled free-text
+    // field of the provenance (the edit route derives it from the request body) and is stored as a
+    // string leaf of the candidates artifact — never write an unredacted label to disk. This restores
+    // parity with recordQualityIntelligenceCandidates (which redacts the whole editedRevisions[]) and
+    // upholds the file-level "every string leaf redacted before persist" invariant. Only the label is
+    // routed through the redactor: `editedAt` (machine ISO timestamp) and `editedBy` (closed enum) are
+    // server-set, carry no secret, and must stay byte-exact so the strict read validator still accepts
+    // them. `candidateId` likewise stays the matched row id so the revision keeps referencing its row.
+    const redactedProvenance = {
+        ...input.provenance,
+        editorLabel: input.redact(input.provenance.editorLabel),
+    };
+    const revision = {
+        candidateId: input.candidateId,
+        provenance: redactedProvenance,
+        editedFields: redactedFields,
+    };
+    store.record(input.runId, {
+        ...artifact,
+        candidates,
+        editedRevisions: [...(artifact.editedRevisions ?? []), revision],
+    });
+    return { ok: true, candidate: updatedRow, changed: true };
+};

package/dist/qualityIntelligence/companionStore.d.ts

@@ -0,0 +1,37 @@
+import { type WorkspaceFs } from "@oscharko-dev/keiko-workspace";
+export interface ContainedJsonArtifactStore<T> {
+    readonly record: (runId: string, value: T) => string;
+    readonly load: (runId: string) => T | undefined;
+    readonly delete: (runId: string) => boolean;
+    readonly location: (runId: string) => string;
+}
+export interface ContainedJsonArtifactStoreOptions<T> {
+    readonly fs?: WorkspaceFs;
+    readonly randomSuffix?: () => string;
+    /** Validates + narrows a parsed JSON value; return `undefined` to reject a corrupt artifact. */
+    readonly parse: (value: unknown) => T | undefined;
+}
+/**
+ * Build a node-backed contained JSON artifact store for one `suffix` (e.g. `.candidates.json`).
+ * `record` overwrites in place (companions are mutable, unlike the write-once manifest): it writes
+ * a fresh atomic temp and renames over any existing file.
+ */
+export declare function createNodeContainedJsonArtifactStore<T>(evidenceDir: string, suffix: string, options: ContainedJsonArtifactStoreOptions<T>): ContainedJsonArtifactStore<T>;
+/**
+ * Idempotently delete ONE QI companion artifact `<runId><suffix>` from the contained `qi/` dir.
+ *
+ * Used by the run-deletion path (`deleteQualityIntelligenceRun`) to clean up companion artifacts
+ * 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 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.
+ */
+export declare function deleteQualityIntelligenceCompanionArtifact(evidenceDir: string, runId: string, suffix: string, options?: {
+    readonly fs?: WorkspaceFs;
+}): boolean;
+//# sourceMappingURL=companionStore.d.ts.map

package/dist/qualityIntelligence/companionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companionStore.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/companionStore.ts"],"names":[],"mappings":"AAuBA,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAQzF,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9C;AAED,MAAM,WAAW,iCAAiC,CAAC,CAAC;IAClD,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;IACrC,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,GAAG,SAAS,CAAC;CACnD;AA2GD;;;;GAIG;AACH,wBAAgB,oCAAoC,CAAC,CAAC,EACpD,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iCAAiC,CAAC,CAAC,CAAC,GAC5C,0BAA0B,CAAC,CAAC,CAAC,CAwB/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0CAA0C,CACxD,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAA;CAAO,GAC1C,OAAO,CAIT"}

package/dist/qualityIntelligence/companionStore.js

@@ -0,0 +1,158 @@
+// Quality Intelligence companion-artifact store (Issue #274/#280/#282, Epic #270, ADR-0023 D7+D8).
+//
+// Generic contained JSON artifact store that lives ALONGSIDE the immutable run manifest under
+// `<evidenceDir>/qi/`, keyed by `<runId><suffix>`. The run manifest (`<runId>.qi.json`) stays the
+// integrity-hashed, write-once evidence record; companion artifacts carry the MUTABLE product
+// surfaces the manifest deliberately does not (generated candidate bodies for review/export, and
+// the human review/lifecycle state). Suffix isolation keeps `listQualityIntelligenceRuns` (which
+// only counts `.qi.json`) blind to companions.
+//
+// Same safety discipline as the manifest store: realpath-contained base, validated runId-derived
+// filename, atomic O_EXCL temp + rename, 0o700 dir / 0o600 file intent.
+import { randomUUID } from "node:crypto";
+import { chmodSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+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";
+import { QI_SUBDIR } from "./store.js";
+const QI_DIR_MODE = 0o700;
+function realBaseForWrite(baseDir, fs) {
+    try {
+        mkdirSync(baseDir, { recursive: true, mode: QI_DIR_MODE });
+        return fs.realPath(baseDir);
+    }
+    catch (error) {
+        throw new EvidenceWriteError(`cannot create QI companion 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 QI companion directory: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function lexicalArtifactPath(runId, suffix, realBase) {
+    assertValidRunId(runId);
+    const name = `${runId}${suffix}`;
+    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`;
+    try {
+        writeFileSync(temp, json, { encoding: "utf8", flag: "wx" });
+        try {
+            chmodSync(temp, 0o600);
+        }
+        catch {
+            // non-fatal: not all filesystems support chmod (e.g. Windows)
+        }
+        renameSync(temp, target);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw new EvidenceWriteError(`QI companion write failed: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function readArtifactFile(baseDir, fs, suffix, parse, runId) {
+    assertValidRunId(runId);
+    const realBase = realBaseForRead(baseDir, fs);
+    if (realBase === undefined)
+        return undefined;
+    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"));
+    }
+    catch (error) {
+        throw new EvidenceReadError(`QI companion is not valid JSON: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+    return parse(parsed);
+}
+function deleteArtifactFile(baseDir, fs, suffix, runId) {
+    assertValidRunId(runId);
+    const realBase = realBaseForRead(baseDir, fs);
+    if (realBase === undefined)
+        return false;
+    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;
+}
+/**
+ * Build a node-backed contained JSON artifact store for one `suffix` (e.g. `.candidates.json`).
+ * `record` overwrites in place (companions are mutable, unlike the write-once manifest): it writes
+ * a fresh atomic temp and renames over any existing file.
+ */
+export function createNodeContainedJsonArtifactStore(evidenceDir, suffix, options) {
+    const baseDir = join(evidenceDir, QI_SUBDIR);
+    const fs = options.fs ?? nodeWorkspaceFs;
+    const randomSuffix = options.randomSuffix ?? randomUUID;
+    return {
+        record: (runId, value) => {
+            assertValidRunId(runId);
+            const realBase = realBaseForWrite(baseDir, fs);
+            const target = lexicalArtifactPath(runId, suffix, realBase);
+            assertWritableArtifactEntry(target, fs);
+            atomicWrite(target, JSON.stringify(value), randomSuffix);
+            return target;
+        },
+        load: (runId) => readArtifactFile(baseDir, fs, suffix, options.parse, runId),
+        delete: (runId) => deleteArtifactFile(baseDir, fs, suffix, runId),
+        location: (runId) => {
+            assertValidRunId(runId);
+            const realBase = realBaseForRead(baseDir, fs);
+            return realBase === undefined
+                ? join(resolve(baseDir), `${runId}${suffix}`)
+                : lexicalArtifactPath(runId, suffix, realBase);
+        },
+    };
+}
+/**
+ * Idempotently delete ONE QI companion artifact `<runId><suffix>` from the contained `qi/` dir.
+ *
+ * Used by the run-deletion path (`deleteQualityIntelligenceRun`) to clean up companion artifacts
+ * 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 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.
+ */
+export function deleteQualityIntelligenceCompanionArtifact(evidenceDir, runId, suffix, options = {}) {
+    const baseDir = join(evidenceDir, QI_SUBDIR);
+    const fs = options.fs ?? nodeWorkspaceFs;
+    return deleteArtifactFile(baseDir, fs, suffix, runId);
+}

package/dist/qualityIntelligence/figmaSnapshot/schema.d.ts

@@ -0,0 +1,123 @@
+export declare const FIGMA_SNAPSHOT_SCHEMA_VERSION: 1;
+/** A reference to one rendered screen image written as a binary side-file. */
+export interface FigmaSnapshotImageRef {
+    readonly mimeType: "image/png";
+    /** Path RELATIVE to the per-run side-file subdir. */
+    readonly relativePath: string;
+    readonly sha256: string;
+    readonly byteLength: number;
+}
+/** Why a screen was excluded from the snapshot. The `render-fetch-failed:<CODE>` variant carries
+ * 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-screen-cap-exceeded" | "render-fetch-failed" | `render-fetch-failed:${string}` | "render-empty" | "render-oversized";
+export interface FigmaSnapshotSkippedScreenRow {
+    readonly screenId: string;
+    readonly reason: FigmaSnapshotSkipReason;
+}
+export interface FigmaSnapshotScreenRow {
+    readonly screenId: string;
+    /** Opaque serialised Screen-IR (#752). Design content — kept, not redacted away. */
+    readonly irJson: unknown;
+    readonly image: FigmaSnapshotImageRef;
+    readonly integrityHash: string;
+}
+/** A screen whose structural Screen-IR is persisted but whose PNG render is absent. */
+export interface FigmaSnapshotStructuralScreenRow {
+    readonly screenId: string;
+    /** Why the screen has no render side-file. Mirrors the matching skippedScreens row. */
+    readonly reason: FigmaSnapshotSkipReason;
+    /** Opaque serialised Screen-IR (#752). Design content — kept, not redacted away. */
+    readonly irJson: unknown;
+    readonly integrityHash: string;
+}
+/**
+ * A raw inter-screen transition carried for the navigation/flow graph (#811). OPTIONAL and additive:
+ * 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 outbound URL ever reaches this shape.
+ */
+export interface FigmaSnapshotLinkRow {
+    readonly sourceNodeId: string;
+    readonly trigger: string;
+    readonly targetNodeId: string;
+}
+/** Token-free provenance carried for audit. `fetchedAt` is audit-only and NOT in any hash. */
+export interface FigmaSnapshotProvenanceRow {
+    readonly fileKey: string;
+    readonly nodeId: string;
+    readonly version: string | undefined;
+    readonly fetchedAt: string;
+}
+export interface FigmaSnapshotRedactionSummary {
+    readonly totalStringsScanned: number;
+    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;
+    readonly provenance: FigmaSnapshotProvenanceRow;
+    readonly screens: readonly FigmaSnapshotScreenRow[];
+    readonly skippedScreens: readonly FigmaSnapshotSkippedScreenRow[];
+    /**
+     * Structural IR for screens without a PNG render. Optional for older snapshots. New snapshots
+     * write one row for each skipped screen whose IR was available, so downstream QI can still use
+     * the JSON even when rendering is capped or degraded.
+     */
+    readonly structuralScreens?: readonly FigmaSnapshotStructuralScreenRow[];
+    /** Raw inter-screen transitions for the navigation/flow graph (#811). Optional + additive. */
+    readonly links?: readonly FigmaSnapshotLinkRow[];
+    /**
+     * The deterministic design-tokens artifact (#752) — colours, typography, spacing, radius — kept as
+     * an opaque serialised value (like {@link FigmaSnapshotScreenRow.irJson}) so design-to-code (#755)
+     * can consume the tokens from the STORED snapshot without re-deriving them (the structural style
+     * 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/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;
+}
+export interface FigmaSnapshotValidationResult {
+    readonly ok: boolean;
+    readonly reason: string | undefined;
+}
+export declare function validateFigmaSnapshotRecord(value: unknown): FigmaSnapshotValidationResult;
+//# sourceMappingURL=schema.d.ts.map

package/dist/qualityIntelligence/figmaSnapshot/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figmaSnapshot/schema.ts"],"names":[],"mappings":"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"}