@penpair/core 0.3.7 → 0.4.1

package/dist/maps/render.js

@@ -0,0 +1,331 @@
+import { designDataBlock } from "../project-input.js";
+import { mapAnnotationLayout } from "./annotation-layout.js";
+import { mapDrawingGeometryProblems, mapEdgeLabelWidth, mapLabelHeight, mapNodeLayers, routeMapEdges, } from "./layout.js";
+import { hashMapContract, validateMapContract, validateMapDetail } from "./validation.js";
+function mermaidLabel(value) {
+    return Array.from(value)
+        .map((character) => /^[a-zA-Z0-9 .,_-]$/.test(character) ? character : `#${character.codePointAt(0)};`)
+        .join("");
+}
+function tableText(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("|", "&#124;")
+        .replace(/[\\`*_[\]#!~]/g, (character) => `\\${character}`)
+        .replace(/[\r\n]+/g, " / ")
+        .replace(/[\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function reviewTables(contract) {
+    const nodes = [
+        "## Regions and responsibilities",
+        "",
+        "| ID | Kind | Origin | Title | Summary | Description | Icon | Requirements |",
+        "| --- | --- | --- | --- | --- | --- | --- | --- |",
+        ...contract.nodes.map((node) => `| ${tableText(node.id)} | ${tableText(node.kind)} | ${node.origin} | ${tableText(node.label)} | ${tableText(node.summary ?? "")} | ${tableText(node.description ?? "")} | ${node.icon ?? ""} | ${tableText((node.requirementIds ?? []).join(", "))} |`),
+    ];
+    const requirements = [
+        "## Requirements",
+        "",
+        "| ID | Origin | Declared requirement |",
+        "| --- | --- | --- |",
+        ...contract.requirements.map((requirement) => `| ${tableText(requirement.id)} | ${requirement.origin} | ${tableText(requirement.text)} |`),
+    ];
+    const findings = [
+        "## Findings and decisions",
+        "",
+        "| ID | Severity | Status | Finding | Resolution |",
+        "| --- | --- | --- | --- | --- |",
+        ...contract.findings.map((finding) => `| ${tableText(finding.id)} | ${finding.severity} | ${finding.status} | ${tableText(finding.message)} | ${tableText(finding.resolution ?? "Pending")} |`),
+    ];
+    const detailRows = contract.nodes
+        .filter((node) => node.kind === "detail-link")
+        .map((node) => {
+        const source = contract.sources.find((entry) => entry.id === node.sourceIds[0]);
+        const target = `./${source
+            .path.split("/")
+            .map((segment) => encodeURIComponent(segment).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`))
+            .join("/")}`;
+        return `| ${tableText(node.id)} | [${tableText(source.path)}](<${target}>) | ${tableText(source.pageId)} / ${tableText(source.frameId)} | ${tableText(node.requirementIds.join(", "))} | Separate artifact review required |`;
+    });
+    const details = detailRows.length
+        ? [
+            "## Linked detail contracts",
+            "",
+            "Links are project-relative. Each detail is published and reviewed independently; its contents are not inlined here.",
+            "",
+            "| Region | Contract | Native page / board | Requirements | Review |",
+            "| --- | --- | --- | --- | --- |",
+            ...detailRows,
+            "",
+            "",
+        ].join("\n")
+        : "";
+    return `${nodes.join("\n")}\n\n${requirements.join("\n")}\n\n${findings.join("\n")}\n\n${details}`;
+}
+export function renderMapMermaid(raw) {
+    const contract = validateMapContract(raw);
+    const aliases = new Map(contract.nodes.map((node, index) => [
+        node.id,
+        `node${index}`,
+    ]));
+    const lines = [
+        "flowchart LR",
+        `  %% title: ${mermaidLabel(contract.title)}`,
+        `  %% goal: ${mermaidLabel(contract.goal)}`,
+    ];
+    if (contract.summary !== undefined) {
+        lines.push(`  %% summary: ${mermaidLabel(contract.summary)}`);
+    }
+    if (contract.description !== undefined) {
+        lines.push(`  %% description: ${mermaidLabel(contract.description)}`);
+    }
+    for (const node of contract.nodes) {
+        lines.push(`  ${aliases.get(node.id)}["${mermaidLabel((node.kind === "detail-link" ? "Details: " : "") + node.label + (node.summary ? ` / ${node.summary}` : ""))}"]`);
+        if (node.description !== undefined) {
+            lines.push(`  %% ${aliases.get(node.id)} description: ${mermaidLabel(node.description)}`);
+        }
+        if (node.icon !== undefined) {
+            lines.push(`  %% ${aliases.get(node.id)} icon: ${node.icon}`);
+        }
+    }
+    for (const edge of contract.edges) {
+        lines.push(`  ${aliases.get(edge.from)} -->|"${mermaidLabel(edge.label)}"| ${aliases.get(edge.to)}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function renderMapMarkdown(raw) {
+    const contract = validateMapContract(raw);
+    const hash = hashMapContract(contract);
+    return (`# ${contract.kind === "journey-map" ? "Journey map" : "Integration map"}\n\n` +
+        `Contract hash: ${hash}\n\n` +
+        `Title: ${tableText(contract.title)}\n\nGoal: ${tableText(contract.goal)}\n\n` +
+        (contract.summary === undefined ? "" : `Summary: ${tableText(contract.summary)}\n\n`) +
+        (contract.description === undefined
+            ? ""
+            : `Description: ${tableText(contract.description)}\n\n`) +
+        "Proposed and observed design data; review records are separate. Appearance does not establish behavior, accessibility or implementation verification.\n\n" +
+        `\`\`\`mermaid\n${renderMapMermaid(contract)}\`\`\`\n\n` +
+        reviewTables(contract) +
+        designDataBlock(contract));
+}
+export function buildMapDrawingPlan(raw, detailMaps = {}) {
+    const contract = validateMapContract(raw);
+    const detailReasons = [];
+    const layers = mapNodeLayers(contract);
+    const columns = Math.max(...layers.values()) + 1;
+    const sameColumn = contract.edges.some((edge) => layers.get(edge.from) === layers.get(edge.to));
+    const columnXs = [
+        sameColumn ? 400 : 96,
+    ];
+    for (let column = 0; column < columns - 1; column++) {
+        const crossing = contract.edges.filter((edge) => layers.get(edge.from) === column && layers.get(edge.to) === column + 1);
+        const gap = Math.max(160, ...crossing.map((edge) => mapEdgeLabelWidth(edge.label) + 64 + crossing.length * 8));
+        columnXs.push(columnXs[column] + 240 + gap);
+    }
+    const titleBox = {
+        x: 32,
+        y: 24,
+        width: 1120,
+        height: mapLabelHeight(contract.title, 700) + 8,
+    };
+    const headerSummary = contract.summary ?? (contract.goal.length <= 240 ? contract.goal : undefined);
+    const summaryBox = headerSummary === undefined
+        ? undefined
+        : {
+            x: 32,
+            y: titleBox.y + titleBox.height + 12,
+            width: 1120,
+            height: mapLabelHeight(headerSummary, 1120),
+        };
+    const legendY = (summaryBox ? summaryBox.y + summaryBox.height : titleBox.y + titleBox.height) + 16;
+    const header = {
+        titleBox,
+        ...(summaryBox
+            ? {
+                summaryBox,
+            }
+            : {}),
+        legendY,
+        height: legendY + 48,
+    };
+    const compact = (text, limit) => text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+    const columnEnds = Array.from({
+        length: columns,
+    }, () => Math.max(180, header.height + 32));
+    const nodes = contract.nodes.map((node) => {
+        const column = layers.get(node.id);
+        const y = columnEnds[column];
+        const height = 144;
+        columnEnds[column] = y + height + 160;
+        let detail;
+        if (node.kind === "detail-link") {
+            const source = contract.sources.find((entry) => entry.id === node.sourceIds[0]);
+            const child = detailMaps[source.id];
+            if (!child) {
+                detailReasons.push(`Resolve the independently reviewed detail contract before native publication: ${source.id}`);
+            }
+            else {
+                const target = validateMapDetail(contract, node, child);
+                detail = {
+                    sourceId: source.id,
+                    path: source.path,
+                    sha256: source.sha256,
+                    fileId: source.fileId,
+                    pageId: source.pageId,
+                    frameId: source.frameId,
+                    mapId: `${target.kind}:${target.id}`,
+                    contractHash: hashMapContract(target),
+                };
+            }
+        }
+        return {
+            ...node,
+            cardTitle: compact(node.label, 24),
+            ...(node.summary === undefined
+                ? {}
+                : {
+                    cardSummary: compact(node.summary, 42),
+                }),
+            ...(node.label.length > 24 ||
+                (node.summary?.length ?? 0) > 42 ||
+                node.description !== undefined
+                ? {
+                    annotationId: `node:${node.id}`,
+                }
+                : {}),
+            ...(detail
+                ? {
+                    detail,
+                }
+                : {}),
+            x: columnXs[column],
+            y,
+            width: 240,
+            height,
+        };
+    });
+    const edges = routeMapEdges(nodes, contract.edges);
+    const width = Math.max(titleBox.x + titleBox.width, ...nodes.map((node) => node.x + node.width), ...edges.map((edge) => edge.labelBox.x + edge.labelBox.width)) + 80;
+    const flowHeight = Math.max(...nodes.map((node) => node.y + node.height), ...edges.map((edge) => edge.labelBox.y + edge.labelBox.height + 48), ...edges.flatMap((edge) => edge.points.map((point) => point.y))) + 80;
+    const annotations = [];
+    let annotationY = flowHeight + 32;
+    const noteWidth = 1120;
+    const noteGap = 24;
+    const noteColumnWidth = (noteWidth - noteGap) / 2;
+    let columnY = [
+        annotationY,
+        annotationY,
+    ];
+    const annotate = (annotation) => {
+        const width = annotation.nodeId ? noteColumnWidth : noteWidth;
+        const height = mapAnnotationLayout({
+            ...annotation,
+            width,
+        }).height;
+        const column = columnY[0] <= columnY[1] ? 0 : 1;
+        const y = annotation.nodeId ? columnY[column] : annotationY;
+        annotations.push({
+            ...annotation,
+            x: 32 + (annotation.nodeId ? column * (noteColumnWidth + noteGap) : 0),
+            y,
+            width,
+            height,
+        });
+        if (annotation.nodeId) {
+            columnY[column] = y + height + noteGap;
+        }
+        else {
+            annotationY = y + height + noteGap;
+            columnY = [
+                annotationY,
+                annotationY,
+            ];
+        }
+    };
+    if (contract.summary !== undefined ||
+        contract.goal.length > 240 ||
+        contract.description !== undefined) {
+        annotate({
+            id: "map:details",
+            title: contract.title,
+            goal: contract.goal,
+            ...(contract.summary === undefined
+                ? {}
+                : {
+                    summary: contract.summary,
+                }),
+            ...(contract.description === undefined
+                ? {}
+                : {
+                    description: contract.description,
+                }),
+        });
+    }
+    for (const node of nodes) {
+        if (node.annotationId) {
+            annotate({
+                id: node.annotationId,
+                nodeId: node.id,
+                title: node.label,
+                ...(node.summary === undefined
+                    ? {}
+                    : {
+                        summary: node.summary,
+                    }),
+                ...(node.description === undefined
+                    ? {}
+                    : {
+                        description: node.description,
+                    }),
+            });
+        }
+    }
+    const height = annotations.length ? Math.max(...columnY) + 32 : flowHeight;
+    const reasons = [
+        ...detailReasons,
+        ...mapDrawingGeometryProblems(nodes, edges),
+    ];
+    if (width > 16384 || height > 16384) {
+        reasons.push("Layered diagram exceeds 16384 px per axis; use linked detail boards before native publication");
+    }
+    const plan = {
+        schemaVersion: 1,
+        kind: "map-drawing-plan",
+        mapKind: contract.kind,
+        mapId: contract.id,
+        mapHash: hashMapContract(contract),
+        title: contract.title,
+        goal: contract.goal,
+        ...(contract.summary === undefined
+            ? {}
+            : {
+                summary: contract.summary,
+            }),
+        ...(contract.description === undefined
+            ? {}
+            : {
+                description: contract.description,
+            }),
+        ...(headerSummary === undefined
+            ? {}
+            : {
+                headerSummary,
+            }),
+        header,
+        annotations,
+        fontFamily: contract.presentation?.fontFamily ?? "Inter",
+        width,
+        height,
+        nodes,
+        edges,
+        complete: reasons.length === 0,
+        reasons,
+    };
+    if (Buffer.byteLength(JSON.stringify(plan)) > 64 * 1024) {
+        plan.complete = false;
+        plan.reasons.push("Drawing plan exceeds 64 KiB; use linked detail boards to reserve the plugin snippet budget");
+    }
+    return plan;
+}

package/dist/maps/review.d.ts

@@ -0,0 +1,16 @@
+import type { ArtifactReview } from "./types.js";
+export interface ArtifactReviewInput {
+    artifactKind: ArtifactReview["artifactKind"];
+    artifactId: string;
+    artifactHash: string;
+    by: string;
+    note: string;
+    artifacts?: Array<{
+        path: string;
+        sha256: string;
+    }>;
+}
+export declare function validateArtifactReview(raw: unknown): ArtifactReview;
+/** Records supplied owner words; content hashes cannot authenticate identity or consent. */
+export declare function createArtifactReview(input: ArtifactReviewInput): ArtifactReview;
+export declare function findArtifactReview(reviews: ArtifactReview[], artifactKind: ArtifactReview["artifactKind"], artifactId: string, artifactHash: string): ArtifactReview | undefined;

package/dist/maps/review.js

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+import { observationHash } from "../journal.js";
+import { mapHash, mapId, mapObject, mapPath, mapText } from "./validation.js";
+export function validateArtifactReview(raw) {
+    const review = mapObject(raw, "Artifact review", [
+        "schemaVersion",
+        "kind",
+        "id",
+        "artifactKind",
+        "artifactId",
+        "artifactHash",
+        "by",
+        "note",
+        "recordedAt",
+        "artifacts",
+        "hash",
+    ]);
+    if (review.schemaVersion !== 1 ||
+        review.kind !== "artifact-review" ||
+        typeof review.artifactKind !== "string" ||
+        ![
+            "journey-map",
+            "integration-map",
+            "design-release",
+            "design-evidence",
+        ].includes(review.artifactKind)) {
+        throw new Error("Unsupported artifact review schema or kind");
+    }
+    const recordedAt = mapText(review.recordedAt, "Review time", 100);
+    if (!Number.isFinite(Date.parse(recordedAt))) {
+        throw new Error("Review requires a valid recording time");
+    }
+    const result = {
+        schemaVersion: 1,
+        kind: "artifact-review",
+        id: mapId(review.id, "Review ID"),
+        artifactKind: review.artifactKind,
+        artifactId: mapId(review.artifactId, "Reviewed artifact ID"),
+        artifactHash: mapHash(review.artifactHash, "Reviewed artifact hash"),
+        by: mapText(review.by, "Owner identity", 200),
+        note: mapText(review.note, "Owner words", 4000),
+        recordedAt,
+        hash: mapHash(review.hash, "Review record hash"),
+    };
+    if (review.artifacts !== undefined) {
+        if (!Array.isArray(review.artifacts) || review.artifacts.length > 1000) {
+            throw new Error("Review artifacts must contain at most 1000 explicit references");
+        }
+        result.artifacts = review.artifacts.map((rawArtifact) => {
+            const artifact = mapObject(rawArtifact, "Review artifact", [
+                "path",
+                "sha256",
+            ]);
+            return {
+                path: mapPath(artifact.path, "Review artifact path"),
+                sha256: mapHash(artifact.sha256, "Review artifact hash"),
+            };
+        });
+        if (new Set(result.artifacts.map((artifact) => artifact.path)).size !== result.artifacts.length) {
+            throw new Error("Duplicate review artifact path");
+        }
+    }
+    const { hash, ...body } = result;
+    if (hash !== observationHash(body)) {
+        throw new Error("Artifact review evidence hash mismatch");
+    }
+    return result;
+}
+/** Records supplied owner words; content hashes cannot authenticate identity or consent. */
+export function createArtifactReview(input) {
+    const body = {
+        schemaVersion: 1,
+        kind: "artifact-review",
+        id: randomUUID(),
+        ...input,
+        recordedAt: new Date().toISOString(),
+    };
+    return validateArtifactReview({
+        ...body,
+        hash: observationHash(body),
+    });
+}
+export function findArtifactReview(reviews, artifactKind, artifactId, artifactHash) {
+    return reviews
+        .map(validateArtifactReview)
+        .reverse()
+        .find((review) => review.artifactKind === artifactKind &&
+        review.artifactId === artifactId &&
+        review.artifactHash === artifactHash);
+}

package/dist/maps/store.d.ts

@@ -0,0 +1,21 @@
+import type { ArtifactReview, MapContract, MapProposal } from "./types.js";
+export interface MapWriteOptions {
+    replace?: boolean;
+    expectedHash?: string;
+    redact?: (text: string) => string;
+}
+export declare function readMapContract(root: string, file: string): Promise<MapContract>;
+export declare function writeMapContract(root: string, file: string, raw: MapContract, options?: MapWriteOptions): Promise<void>;
+export declare function readMapProposal(root: string, file: string): Promise<MapProposal>;
+export declare function writeMapProposal(root: string, file: string, proposal: MapProposal, options?: MapWriteOptions): Promise<void>;
+export declare function readArtifactReviews(root: string, file: string): Promise<ArtifactReview[]>;
+export declare function verifyArtifactReviewEvidence(root: string, raw: ArtifactReview): Promise<boolean>;
+export declare function writeArtifactReview(root: string, file: string, raw: ArtifactReview, options?: MapWriteOptions): Promise<ArtifactReview>;
+export interface MapSourceObservation {
+    sourceHashes: Record<string, string>;
+    journeyHash?: string;
+    journeyRequirementIds?: string[];
+    detailMaps: Record<string, MapContract>;
+}
+/** Only explicitly referenced project files are read; a hash does not prove live design freshness. */
+export declare function observeMapSources(root: string, raw: MapContract): Promise<MapSourceObservation>;

package/dist/maps/store.js

@@ -0,0 +1,222 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, unlink } from "node:fs/promises";
+import path from "node:path";
+import { atomicWriteFile } from "../atomic-output.js";
+import { readProjectBytes } from "../bounded-file.js";
+import { resolveProjectOutput } from "../project-input.js";
+import { validateMapProposal } from "./proposal.js";
+import { validateArtifactReview } from "./review.js";
+import { hashMapContract, mapObject, maxMapBytes, validateMapContract, validateMapDetail, } from "./validation.js";
+async function readBoundedBytes(root, file) {
+    return readProjectBytes(root, file, maxMapBytes);
+}
+async function readMapJson(root, file) {
+    const bytes = await readBoundedBytes(root, file);
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("Map artifact is not valid JSON; inspect the explicitly referenced file privately");
+    }
+}
+function encodeMapArtifact(value, redact) {
+    const encoded = `${JSON.stringify(value, null, 2)}\n`;
+    if (Buffer.byteLength(encoded) > maxMapBytes) {
+        throw new Error("Map artifact exceeds the 16 MiB byte budget");
+    }
+    if (redact && redact(encoded) !== encoded) {
+        throw new Error("Map artifact requires credential redaction; previous evidence preserved");
+    }
+    return encoded;
+}
+async function withArtifactLock(root, file, work) {
+    const target = await resolveProjectOutput(root, file);
+    await mkdir(path.dirname(target), {
+        recursive: true,
+    });
+    const lock = await open(`${target}.lock`, "wx", 0o600);
+    try {
+        return await work(target);
+    }
+    finally {
+        await lock.close();
+        await unlink(`${target}.lock`);
+    }
+}
+export async function readMapContract(root, file) {
+    return validateMapContract(await readMapJson(root, file));
+}
+export async function writeMapContract(root, file, raw, options = {}) {
+    const contract = validateMapContract(raw);
+    const encoded = encodeMapArtifact(contract, options.redact);
+    await withArtifactLock(root, file, async (target) => {
+        if (options.expectedHash !== undefined &&
+            hashMapContract(await readMapContract(root, file)) !== options.expectedHash) {
+            throw new Error("Canonical map changed before publication; inspect the current revision");
+        }
+        await atomicWriteFile(target, encoded, {
+            replace: options.replace ?? false,
+        });
+    });
+}
+export async function readMapProposal(root, file) {
+    return validateMapProposal(await readMapJson(root, file));
+}
+export async function writeMapProposal(root, file, proposal, options = {}) {
+    const encoded = encodeMapArtifact(validateMapProposal(proposal), options.redact);
+    await withArtifactLock(root, file, async (target) => atomicWriteFile(target, encoded, {
+        replace: options.replace ?? false,
+    }));
+}
+export async function readArtifactReviews(root, file) {
+    let raw;
+    try {
+        raw = await readMapJson(root, file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const document = mapObject(raw, "Artifact reviews", [
+        "schemaVersion",
+        "kind",
+        "records",
+    ]);
+    if (document.schemaVersion !== 1 ||
+        document.kind !== "artifact-reviews" ||
+        !Array.isArray(document.records) ||
+        document.records.length > 10000) {
+        throw new Error("Unsupported artifact reviews document");
+    }
+    const reviews = document.records.map(validateArtifactReview);
+    if (new Set(reviews.map((review) => review.id)).size !== reviews.length) {
+        throw new Error("Duplicate artifact review ID");
+    }
+    return reviews;
+}
+export async function verifyArtifactReviewEvidence(root, raw) {
+    const review = validateArtifactReview(raw);
+    for (const artifact of review.artifacts ?? []) {
+        let bytes;
+        try {
+            bytes = await readProjectBytes(root, artifact.path, 64 * 1024 * 1024);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
+        }
+        if (createHash("sha256").update(bytes).digest("hex") !== artifact.sha256) {
+            return false;
+        }
+    }
+    return true;
+}
+export async function writeArtifactReview(root, file, raw, options = {}) {
+    const review = validateArtifactReview(raw);
+    if (!(await verifyArtifactReviewEvidence(root, review))) {
+        throw new Error("Reviewed artifact bytes changed; no review was recorded");
+    }
+    await withArtifactLock(root, file, async (target) => {
+        const previous = await readArtifactReviews(root, file);
+        const duplicate = previous.find((entry) => entry.id === review.id);
+        if (duplicate) {
+            if (duplicate.hash !== review.hash) {
+                throw new Error("A different review already uses this record ID");
+            }
+            return;
+        }
+        if (previous.length >= 10000) {
+            throw new Error("Artifact review record limit reached");
+        }
+        const encoded = encodeMapArtifact({
+            schemaVersion: 1,
+            kind: "artifact-reviews",
+            records: [
+                ...previous,
+                review,
+            ],
+        }, options.redact);
+        await atomicWriteFile(target, encoded, {
+            replace: true,
+        });
+    });
+    return review;
+}
+/** Only explicitly referenced project files are read; a hash does not prove live design freshness. */
+export async function observeMapSources(root, raw) {
+    const contract = validateMapContract(raw);
+    const sourceHashes = Object.create(null);
+    const detailMaps = Object.create(null);
+    const detailSourceIds = new Set(contract.nodes
+        .filter((node) => node.kind === "detail-link")
+        .flatMap((node) => node.sourceIds ?? []));
+    let detailBytes = 0;
+    for (const source of contract.sources) {
+        if (!source.path) {
+            continue;
+        }
+        try {
+            const bytes = await readBoundedBytes(root, source.path);
+            sourceHashes[source.id] = createHash("sha256").update(bytes).digest("hex");
+            if (detailSourceIds.has(source.id) && sourceHashes[source.id] === source.sha256) {
+                detailBytes += bytes.length;
+                if (detailBytes > 128 * 1024 * 1024) {
+                    throw new Error("Direct detail contracts exceed the 128 MiB total input budget");
+                }
+                let rawDetail;
+                try {
+                    rawDetail = JSON.parse(bytes.toString("utf8"));
+                }
+                catch {
+                    throw new Error("Linked detail contract is not valid JSON; no source text was included");
+                }
+                let detail;
+                for (const node of contract.nodes.filter((entry) => entry.kind === "detail-link" && entry.sourceIds?.[0] === source.id)) {
+                    detail = validateMapDetail(contract, node, rawDetail);
+                }
+                detailMaps[source.id] = detail;
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                sourceHashes[source.id] = "missing";
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    if (!contract.journey) {
+        return {
+            sourceHashes,
+            detailMaps,
+        };
+    }
+    let journey;
+    try {
+        journey = await readMapContract(root, contract.journey.path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {
+                sourceHashes,
+                detailMaps,
+                journeyHash: "missing",
+            };
+        }
+        throw error;
+    }
+    if (journey.kind !== "journey-map") {
+        throw new Error("Integration journey reference must resolve to a journey map");
+    }
+    return {
+        sourceHashes,
+        detailMaps,
+        journeyHash: hashMapContract(journey),
+        journeyRequirementIds: journey.requirements.map((requirement) => requirement.id),
+    };
+}