@penpair/core 0.3.6 → 0.4.0

package/dist/design-releases/check.js

@@ -0,0 +1,323 @@
+import { exportShapePng } from "../export.js";
+import { observationHash } from "../journal.js";
+import { projection as validateProjection } from "../map-penpot/projection.js";
+import { validateMapContract, hashMapContract } from "../maps/validation.js";
+import { releaseContractGraph, nativeContractId } from "./contract-graph.js";
+import { readProjection } from "../map-penpot/index.js";
+import { findArtifactReview, validateArtifactReview } from "../maps/review.js";
+import { withPageSession, selectPage } from "../page-session.js";
+import { readArtifact } from "./artifact-paths.js";
+import { compareNativeCopy, decodedPixels, inspectionContentHash, deriveNodeMap, } from "./fidelity.js";
+import { assertSourceUnchanged, captureReleaseScreen, observeRelease, releaseClient, } from "./live.js";
+import { assertReleaseContracts } from "./store.js";
+import { hashDesignRelease, validateDesignRelease } from "./validation.js";
+export function releaseReferences(release) {
+    const references = [
+        ...release.sources.flatMap((source) => [
+            source.inspection,
+            ...(source.render
+                ? [
+                    source.render,
+                ]
+                : []),
+            ...(source.dependencies
+                ? [
+                    source.dependencies,
+                ]
+                : []),
+        ]),
+        ...release.contracts.flatMap((contract) => [
+            {
+                path: contract.path,
+                sha256: contract.sha256,
+            },
+            ...(contract.review?.artifacts ?? []),
+        ]),
+        ...release.receipts.flatMap((receipt) => [
+            receipt.sourceInspection,
+            receipt.targetInspection,
+            receipt.originalRender,
+            receipt.targetRender,
+        ]),
+        ...release.maps.flatMap((map) => [
+            map.projection,
+            map.render,
+        ]),
+        ...(release.overview
+            ? [
+                release.overview.render,
+            ]
+            : []),
+    ];
+    return [
+        ...new Map(references.map((reference) => [
+            `${reference.path}:${reference.sha256}`,
+            reference,
+        ])).values(),
+    ];
+}
+export async function readReleaseBundle(root, release) {
+    if (!release.finalized) {
+        throw new Error("Finalized bundle pointer missing");
+    }
+    const bundle = JSON.parse((await readArtifact(root, release.finalized.bundle)).toString("utf8"));
+    if (bundle.schemaVersion !== 1 ||
+        bundle.kind !== "approved-design-release" ||
+        bundle.designHash !== hashDesignRelease(release) ||
+        hashDesignRelease(bundle.release) !== bundle.designHash ||
+        !Array.isArray(bundle.artifacts) ||
+        bundle.artifacts.length > 2000) {
+        throw new Error("Immutable release bundle does not match its final pointer");
+    }
+    const keys = new Set();
+    for (const item of bundle.artifacts) {
+        if (!item ||
+            !item.original ||
+            !item.snapshot ||
+            item.original.sha256 !== item.snapshot.sha256) {
+            throw new Error("Immutable artifact snapshot differs from its original approved hash");
+        }
+        const key = `${item.original.path}:${item.original.sha256}`;
+        if (keys.has(key)) {
+            throw new Error("Duplicate immutable artifact mapping");
+        }
+        keys.add(key);
+    }
+    for (const reference of releaseReferences(release)) {
+        if (!keys.has(`${reference.path}:${reference.sha256}`)) {
+            throw new Error("Immutable bundle omits required release evidence");
+        }
+    }
+    const review = validateArtifactReview(bundle.review);
+    for (const reference of review.artifacts ?? []) {
+        if (!keys.has(`${reference.path}:${reference.sha256}`)) {
+            throw new Error("Immutable bundle omits owner review evidence");
+        }
+    }
+    if (!findArtifactReview([
+        review,
+    ], "design-release", release.id, bundle.designHash) ||
+        review.hash !== release.finalized?.reviewHash ||
+        release.finalized.markerHash !== release.finalized.bundle.sha256) {
+        throw new Error("Finalized release owner review or marker binding changed");
+    }
+    return bundle;
+}
+export async function checkRelease(client, root, raw, options = {}) {
+    const release = validateDesignRelease(raw);
+    const reasons = [];
+    const designHash = hashDesignRelease(release);
+    let bundle;
+    const artifact = async (reference) => {
+        if (!bundle) {
+            return readArtifact(root, reference, 64 * 1024 * 1024);
+        }
+        const saved = bundle.artifacts.find((item) => item.original.path === reference.path && item.original.sha256 === reference.sha256);
+        if (!saved) {
+            throw new Error("Immutable bundle omits required release evidence");
+        }
+        return readArtifact(root, saved.snapshot, 64 * 1024 * 1024);
+    };
+    try {
+        if (release.status === "final") {
+            bundle = await readReleaseBundle(root, release);
+            for (const item of bundle.artifacts) {
+                await readArtifact(root, item.snapshot, 64 * 1024 * 1024);
+            }
+        }
+        await assertReleaseContracts(root, release.contracts, true, artifact, release.fileId);
+        for (const reference of releaseReferences(release)) {
+            await artifact(reference);
+        }
+        if (!release.fidelity ||
+            !release.overview ||
+            release.maps.length !== release.contracts.length) {
+            reasons.push("Complete verified native screen, map and overview evidence is missing");
+        }
+        const entries = await Promise.all(release.contracts.map(async (reference) => ({
+            reference,
+            map: validateMapContract(JSON.parse((await artifact(reference)).toString("utf8"))),
+        })));
+        const graph = releaseContractGraph(entries, release.fileId);
+        for (const map of release.maps) {
+            const entry = entries.find((candidate) => candidate.map.kind === map.kind && candidate.map.id === map.id);
+            if (!entry || map.contractHash !== hashMapContract(entry.map)) {
+                throw new Error("Release map evidence does not match its exact explicit contract");
+            }
+            const raw = JSON.parse((await artifact(map.projection)).toString("utf8"));
+            const observed = validateProjection({
+                fileId: release.fileId,
+                pageId: release.target.pageId,
+                boardId: map.boardId,
+            }, nativeContractId(entry.map), raw);
+            if (raw.schemaVersion !== 1 ||
+                raw.kind !== "native-map-projection" ||
+                raw.fileId !== release.fileId ||
+                raw.pageId !== release.target.pageId ||
+                raw.boardId !== map.boardId ||
+                raw.mapId !== nativeContractId(entry.map) ||
+                observed.fingerprint !== raw.fingerprint ||
+                observed.contractHash !== map.contractHash ||
+                observed.conflicts.length) {
+                throw new Error("Stored native map projection provenance changed");
+            }
+            const details = graph.details.get(nativeContractId(entry.map)) ?? {};
+            for (const node of entry.map.nodes.filter((node) => node.kind === "detail-link")) {
+                const child = details[node.sourceIds[0]];
+                const target = release.maps.find((candidate) => candidate.kind === child.kind && candidate.id === child.id);
+                if (!target || target.contractHash !== hashMapContract(child)) {
+                    throw new Error("Release detail target lacks an independently pinned child board");
+                }
+                const clickables = observed.shapes.filter((shape) => shape.logicalId === node.id &&
+                    [
+                        "node",
+                        "label",
+                    ].includes(shape.role));
+                if (clickables.length !== 2 ||
+                    clickables.some((shape) => !Array.isArray(shape.interactions) ||
+                        shape.interactions.length !== 1 ||
+                        shape.interactions[0]?.trigger !== "click" ||
+                        shape.interactions[0]?.type !== "navigate-to" ||
+                        shape.interactions[0]?.destinationId !== target.boardId ||
+                        shape.interactions[0]?.destinationPageId !== release.target.pageId ||
+                        shape.interactions[0]?.destinationMapHash !== target.contractHash ||
+                        shape.interactions[0]?.destinationMapId !== nativeContractId(child))) {
+                    throw new Error("Release detail interactions must target the exact reviewed release child board");
+                }
+            }
+        }
+        const completeNodeMap = Object.assign({}, ...release.receipts.map((receipt) => receipt.nodeMap));
+        for (const receipt of release.receipts) {
+            const source = release.sources.find((item) => item.id === receipt.sourceId);
+            const original = JSON.parse((await artifact(receipt.sourceInspection)).toString("utf8"));
+            const copied = JSON.parse((await artifact(receipt.targetInspection)).toString("utf8"));
+            const result = compareNativeCopy(original, copied, completeNodeMap);
+            if (result.sourceHash !== source.contentHash ||
+                result.sourceHash !== receipt.sourceContentHash ||
+                result.targetHash !== receipt.targetContentHash) {
+                throw new Error("Stored receipt native fingerprints changed");
+            }
+            if (observationHash(receipt.nodeMap) !== observationHash(deriveNodeMap(original, copied))) {
+                throw new Error("Stored receipt descendant mapping changed");
+            }
+            if (original.fileId !== release.fileId ||
+                original.pageId !== source.pageId ||
+                original.nodes?.[0]?.id !== source.frameId ||
+                copied.fileId !== release.fileId ||
+                copied.pageId !== release.target.pageId ||
+                copied.nodes?.[0]?.id !== receipt.targetFrameId) {
+                throw new Error("Stored receipt frame provenance changed");
+            }
+            if (!source.render) {
+                throw new Error("Pinned source render missing from release evidence");
+            }
+            const frozen = await decodedPixels(await artifact(source.render));
+            const sourcePixels = await decodedPixels(await artifact(receipt.originalRender));
+            const targetPixels = await decodedPixels(await artifact(receipt.targetRender));
+            if ([
+                frozen,
+                sourcePixels,
+                targetPixels,
+            ].some((pixels) => pixels.hash !== receipt.decodedPixelsHash ||
+                pixels.width !== receipt.width ||
+                pixels.height !== receipt.height)) {
+                throw new Error("Stored exact pixel fidelity evidence differs from its receipt");
+            }
+        }
+        if (!client) {
+            return {
+                valid: reasons.length === 0,
+                finalized: release.status === "final",
+                live: false,
+                designHash,
+                reasons,
+                implementation: release.implementation.status,
+            };
+        }
+        client = releaseClient(client, release);
+        await withPageSession(client, async () => {
+            const observed = await observeRelease(client, release);
+            if (!observed.pageId ||
+                observed.pageId !== release.target.pageId ||
+                observed.overviewFrameId !== release.target.overviewFrameId) {
+                throw new Error("Live release page/overview ownership changed");
+            }
+            if (release.status === "final" &&
+                (observed.marker?.status !== "released" ||
+                    observed.marker.bundleHash !== release.finalized?.bundle.sha256 ||
+                    observed.marker.reviewHash !== release.finalized?.reviewHash)) {
+                throw new Error("Live finalized release marker changed");
+            }
+            if (release.status !== "final") {
+                for (const source of release.sources) {
+                    await assertSourceUnchanged(client, root, release, source);
+                }
+            }
+            for (const receipt of release.receipts) {
+                const original = JSON.parse((await artifact(receipt.sourceInspection)).toString("utf8"));
+                const target = await captureReleaseScreen(client, release.fileId, receipt.targetPageId, receipt.targetFrameId);
+                compareNativeCopy(original, target, completeNodeMap);
+                const image = await exportShapePng(client, receipt.targetFrameId, {
+                    ...options.exportOptions,
+                    stable: true,
+                });
+                const pixels = await decodedPixels(image.png);
+                if (!image.stable ||
+                    pixels.hash !== receipt.decodedPixelsHash ||
+                    pixels.width !== receipt.width ||
+                    pixels.height !== receipt.height) {
+                    throw new Error("Finalized release screen render drifted");
+                }
+            }
+            for (const map of release.maps) {
+                const stored = JSON.parse((await artifact(map.projection)).toString("utf8"));
+                const projection = await readProjection(client, {
+                    fileId: release.fileId,
+                    pageId: release.target.pageId,
+                    boardId: map.boardId,
+                }, `${map.kind}:${map.id}`);
+                if (projection.conflicts.length ||
+                    projection.fingerprint !== stored.fingerprint ||
+                    projection.contractHash !== map.contractHash) {
+                    throw new Error("Release native map drifted from reviewed contract projection");
+                }
+                const image = await exportShapePng(client, map.boardId, {
+                    ...options.exportOptions,
+                    stable: true,
+                });
+                if (!image.stable ||
+                    (await decodedPixels(image.png)).hash !==
+                        (await decodedPixels(await artifact(map.render))).hash) {
+                    throw new Error("Release native map render drifted");
+                }
+            }
+            if (release.overview && release.target.overviewFrameId) {
+                const overview = await captureReleaseScreen(client, release.fileId, release.target.pageId, release.target.overviewFrameId);
+                const image = await exportShapePng(client, release.target.overviewFrameId, {
+                    ...options.exportOptions,
+                    stable: true,
+                });
+                if (inspectionContentHash(overview) !== release.overview.contentHash ||
+                    !image.stable ||
+                    (await decodedPixels(image.png)).hash !== release.overview.decodedPixelsHash) {
+                    throw new Error("Release overview content drifted");
+                }
+            }
+            await selectPage(client, {
+                id: release.target.pageId,
+            });
+        });
+    }
+    catch (error) {
+        reasons.push(options.redact?.(error instanceof Error ? error.message : String(error)) ??
+            (error instanceof Error ? error.message : String(error)));
+    }
+    return {
+        valid: reasons.length === 0,
+        finalized: release.status === "final",
+        live: Boolean(client),
+        designHash,
+        reasons,
+        implementation: release.implementation.status,
+    };
+}

package/dist/design-releases/context.d.ts

@@ -0,0 +1,2 @@
+import type { DesignRelease, ReleaseContext } from "./types.js";
+export declare function releaseContext(root: string, raw: DesignRelease): Promise<ReleaseContext>;

package/dist/design-releases/context.js

@@ -0,0 +1,119 @@
+import { releaseContractContexts } from "./store.js";
+import { observationHash } from "../journal.js";
+import { readArtifact } from "./artifact-paths.js";
+import { checkRelease, readReleaseBundle } from "./check.js";
+import { hashDesignRelease, validateDesignRelease } from "./validation.js";
+export async function releaseContext(root, raw) {
+    const release = validateDesignRelease(raw);
+    const checked = await checkRelease(undefined, root, release);
+    const bundle = release.status === "final" && checked.valid
+        ? await readReleaseBundle(root, release)
+        : undefined;
+    const artifact = async (reference) => {
+        if (!bundle) {
+            return readArtifact(root, reference, 64 * 1024 * 1024);
+        }
+        const frozen = bundle.artifacts.find((item) => item.original.path === reference.path && item.original.sha256 === reference.sha256);
+        if (!frozen) {
+            throw new Error("Approved context is missing frozen evidence");
+        }
+        return readArtifact(root, frozen.snapshot, 64 * 1024 * 1024);
+    };
+    const mapContexts = [];
+    const nextActions = [];
+    if (checked.valid) {
+        mapContexts.push(...(await releaseContractContexts(root, release.contracts, artifact, release.fileId)));
+        for (const map of mapContexts) {
+            for (const finding of map.findings) {
+                if (finding.status === "open") {
+                    nextActions.push(`${map.mapKind}/${map.mapId}: ${finding.message}`);
+                }
+            }
+        }
+    }
+    if (release.implementation.status !== "verified") {
+        nextActions.push(`Implementation verification is ${release.implementation.status}; implement the approved requirements and collect independent implementation evidence.`);
+    }
+    const context = {
+        schemaVersion: 1,
+        kind: "release-context",
+        id: release.id,
+        productVersion: release.productVersion,
+        designHash: hashDesignRelease(release),
+        finalized: release.status === "final",
+        ready: checked.valid &&
+            release.status === "final" &&
+            mapContexts.every((map) => map.ready && !map.truncated),
+        reasons: [
+            ...checked.reasons,
+            ...(release.status !== "final"
+                ? [
+                    "Design release is not finalized",
+                ]
+                : []),
+        ],
+        implementation: release.implementation,
+        mapContexts,
+        mapTargets: release.maps.map((map) => ({
+            kind: map.kind,
+            id: map.id,
+            fileId: release.fileId,
+            pageId: release.target.pageId,
+            frameId: map.boardId,
+            contractHash: map.contractHash,
+        })),
+        nextActions,
+        screens: release.sources.map((source) => ({
+            id: source.id,
+            label: source.label,
+            sourceFrameId: source.frameId,
+            targetFrameId: release.receipts.find((receipt) => receipt.sourceId === source.id)?.targetFrameId ?? null,
+        })),
+        contracts: release.contracts,
+        proposedBaselines: {
+            page: release.target.name,
+            root: `design/releases/${release.productVersion}/baselines`,
+            format: "webp",
+            frames: release.receipts.map((receipt) => ({
+                id: `screen-${observationHash(receipt.sourceId).slice(0, 24)}`,
+                frameId: receipt.targetFrameId,
+            })),
+        },
+        truncated: mapContexts.some((map) => map.truncated),
+    };
+    const collections = [
+        "screens",
+        "contracts",
+        "mapContexts",
+        "mapTargets",
+        "nextActions",
+    ];
+    while (Buffer.byteLength(JSON.stringify(context)) > 127 * 1024) {
+        context.truncated = true;
+        context.ready = false;
+        const largest = collections.reduce((before, key) => JSON.stringify(context[key]).length > JSON.stringify(context[before]).length ? key : before);
+        if (context[largest].length) {
+            context[largest].splice(Math.floor(context[largest].length / 2));
+        }
+        else if (context.proposedBaselines.frames.length) {
+            context.proposedBaselines.frames.splice(Math.floor(context.proposedBaselines.frames.length / 2));
+        }
+        else if (context.implementation.evidence.length) {
+            context.implementation = {
+                status: context.implementation.status,
+                evidence: [],
+            };
+        }
+        else {
+            context.reasons = [
+                "Release context exceeded byte budget; inspect canonical release artifacts",
+            ];
+            break;
+        }
+    }
+    if (context.truncated) {
+        context.ready = false;
+        context.reasons.push("Context omits evidence; canonical release artifacts are required");
+    }
+    return context;
+}

package/dist/design-releases/contract-graph.d.ts

@@ -0,0 +1,13 @@
+import type { MapContract } from "../maps/types.js";
+import type { ReleaseContract } from "./types.js";
+export interface ReleaseContractEntry {
+    reference: ReleaseContract;
+    map: MapContract;
+}
+export interface ReleaseContractGraph {
+    ordered: ReleaseContractEntry[];
+    details: Map<string, Record<string, MapContract>>;
+}
+export declare function nativeContractId(map: MapContract): string;
+/** Detail traversal stays inside the explicit release family; no implicit recursive file loading. */
+export declare function releaseContractGraph(entries: ReleaseContractEntry[], fileId?: string): ReleaseContractGraph;

package/dist/design-releases/contract-graph.js

@@ -0,0 +1,75 @@
+import { validateMapDetail } from "../maps/validation.js";
+export function nativeContractId(map) {
+    return `${map.kind}:${map.id}`;
+}
+/** Detail traversal stays inside the explicit release family; no implicit recursive file loading. */
+export function releaseContractGraph(entries, fileId) {
+    if (entries.length > 100) {
+        throw new Error("Release contract graph exceeds 100 explicit members");
+    }
+    const byId = new Map(entries.map((entry) => [
+        nativeContractId(entry.map),
+        entry,
+    ]));
+    if (byId.size !== entries.length) {
+        throw new Error("Release contract identities must be unique");
+    }
+    const children = new Map();
+    const details = new Map();
+    for (const entry of entries) {
+        const key = nativeContractId(entry.map);
+        const links = entry.map.nodes.filter((node) => node.kind === "detail-link");
+        if (links.length > 64) {
+            throw new Error("Release map exceeds 64 direct detail links");
+        }
+        const resolved = {};
+        const linked = new Set();
+        for (const node of links) {
+            const source = entry.map.sources.find((item) => item.id === node.sourceIds?.[0]);
+            if (!source ||
+                source.kind !== "contract" ||
+                !source.path ||
+                !source.fileId ||
+                !source.pageId ||
+                !source.frameId) {
+                throw new Error("Release detail link is missing its explicit pinned contract target");
+            }
+            if (fileId && source.fileId !== fileId) {
+                throw new Error("Release detail link belongs to another pinned file");
+            }
+            const child = entries.find((candidate) => candidate.reference.path === source.path && candidate.reference.sha256 === source.sha256);
+            if (!child) {
+                throw new Error("Every referenced detail contract must be an explicit exact-hash release member");
+            }
+            resolved[source.id] = validateMapDetail(entry.map, node, child.map);
+            linked.add(nativeContractId(child.map));
+        }
+        details.set(key, resolved);
+        children.set(key, linked);
+    }
+    const visited = new Set();
+    const active = new Set();
+    const ordered = [];
+    const visit = (id) => {
+        if (active.has(id)) {
+            throw new Error("Cyclic detail contracts cannot be assembled or finalized");
+        }
+        if (visited.has(id)) {
+            return;
+        }
+        active.add(id);
+        for (const child of children.get(id) ?? []) {
+            visit(child);
+        }
+        active.delete(id);
+        visited.add(id);
+        ordered.push(byId.get(id));
+    };
+    for (const entry of entries) {
+        visit(nativeContractId(entry.map));
+    }
+    return {
+        ordered,
+        details,
+    };
+}

package/dist/design-releases/fidelity.d.ts

@@ -0,0 +1,23 @@
+import type { InspectionCapture } from "../inspection.js";
+interface NativeTree {
+    root: Record<string, unknown>;
+    ordered: Array<{
+        path: string;
+        node: Record<string, unknown>;
+    }>;
+    paths: Map<string, string>;
+}
+export declare function nativeTree(inspection: InspectionCapture): NativeTree;
+export declare function semanticInspection(inspection: InspectionCapture, remap?: Record<string, string>): unknown;
+export declare function inspectionContentHash(inspection: InspectionCapture): string;
+export declare function deriveNodeMap(source: InspectionCapture, target: InspectionCapture): Record<string, string>;
+export declare function compareNativeCopy(source: InspectionCapture, target: InspectionCapture, fullNodeMap: Record<string, string>): {
+    sourceHash: string;
+    targetHash: string;
+};
+export declare function decodedPixels(png: Buffer): Promise<{
+    hash: string;
+    width: number;
+    height: number;
+}>;
+export {};