@penpair/core 0.3.7 → 0.4.1

package/dist/map-penpot/snippets.js

@@ -0,0 +1,164 @@
+import { nativeMapRoles, nativeMapTextEntries } from "./content.js";
+import { nativeMapIcons, defaultMapIcon } from "./icons.js";
+import { mapOriginLabels, mapOriginLegend } from "./status-labels.js";
+import { snippet } from "../snippet.js";
+const inspectSource = `
+if (penpot.currentFile.id !== CFG.target.fileId || penpot.currentPage.id !== CFG.target.pageId) throw new Error("Map file/page identity changed");
+const readMeta = shape => {
+  if (typeof shape.getSharedPluginData !== "function") throw new Error("Map metadata API unavailable");
+  const raw = shape.getSharedPluginData("penpair", "map");
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch { throw new Error("Malformed managed map metadata"); }
+};
+const readInteractions = shape => {
+  if (!Array.isArray(shape.interactions)) return null;
+  return shape.interactions.map(interaction => {
+    const destination = interaction.action?.destination;
+    const destinationId = destination?.id || null;
+    const destinationPageId = destinationId ? penpot.currentFile.pages.find(page => page.getShapeById(destinationId)?.id === destinationId)?.id || null : null;
+    const destinationMeta = destination ? readMeta(destination) : null;
+    return {trigger:interaction.trigger,type:interaction.action?.type || "unknown",destinationId,destinationPageId,destinationMapHash:destinationMeta?.contractHash || null,destinationMapId:destinationMeta?.mapId || null};
+  });
+};
+const all = [], queue = [...penpot.currentPage.root.children], visited = new Set();
+while (queue.length) {
+  const shape = queue.shift();
+  if (visited.has(shape.id)) throw new Error("Cyclic native hierarchy");
+  visited.add(shape.id); all.push(shape);
+  if (all.length > 20000) throw new Error("Page traversal exceeds map inspection limit");
+  if (shape.children) queue.push(...shape.children);
+}
+const boards = all.filter(shape => { const meta = readMeta(shape); return meta && meta.mapId === CFG.mapId && meta.role === "board"; });
+if (boards.length > 1) throw new Error("Duplicate managed map boards");
+const board = boards[0] || null;
+if (CFG.target.boardId && (!board || board.id !== CFG.target.boardId)) throw new Error("Managed map board identity changed");
+const conflicts = [], shapes = [], keys = new Set();
+if (board) {
+  const meta = readMeta(board);
+  if (meta.schemaVersion !== 1 || meta.owner !== "penpair") conflicts.push("Edited board ownership");
+  for (const shape of board.children) {
+    const child = readMeta(shape);
+    if (!child || child.owner !== "penpair" || child.schemaVersion !== 1 || child.mapId !== CFG.mapId) { conflicts.push("Unknown or edited ownership: " + shape.id); continue; }
+    if (!${JSON.stringify(nativeMapRoles)}.includes(child.role) || typeof child.logicalId !== "string" || !child.logicalId) { conflicts.push("Unknown managed role or identity: " + shape.id); continue; }
+    const key = child.role + ":" + child.logicalId;
+    if (keys.has(key)) conflicts.push("Duplicate logical ID: " + key);
+    keys.add(key);
+    if (shape.children && shape.children.length) conflicts.push("Unexpected nested content: " + shape.id);
+    shapes.push({shapeId:shape.id,logicalId:child.logicalId,role:child.role,iconKey:child.iconKey || null,interactions:readInteractions(shape),label:shape.type === "text" ? shape.characters : null,x:shape.x,y:shape.y,width:shape.width,height:shape.height,content:shape.type === "path" ? shape.content : null,appearance:{type:shape.type,name:shape.name,fills:shape.fills || [],strokes:shape.strokes || [],fontId:shape.fontId || null,fontFamily:shape.fontFamily || null,fontVariantId:shape.fontVariantId || null,fontSize:shape.fontSize || null,growType:shape.growType || null,borderRadiusTopLeft:shape.borderRadiusTopLeft ?? shape.borderRadius ?? null,borderRadiusTopRight:shape.borderRadiusTopRight ?? shape.borderRadius ?? null,borderRadiusBottomLeft:shape.borderRadiusBottomLeft ?? shape.borderRadius ?? null,borderRadiusBottomRight:shape.borderRadiusBottomRight ?? shape.borderRadius ?? null,opacity:shape.opacity ?? null,blendMode:shape.blendMode ?? null,blur:shape.blur || null},...(child.from ? {from:child.from,to:child.to} : {})});
+  }
+  const childIds = new Set(board.children.map(shape => shape.id));
+  for (const shape of all) { const child = readMeta(shape); if (shape.id !== board.id && child && child.mapId === CFG.mapId && !childIds.has(shape.id)) conflicts.push("Reparented managed shape: " + shape.id); }
+}
+const observation = {boardId:board ? board.id : null,boardBounds:board ? {x:board.x,y:board.y,width:board.width,height:board.height} : null,contractHash:board ? readMeta(board).contractHash : null,shapes,conflicts};
+`;
+export function inspectMapSnippet(target, mapId) {
+    return snippet("map-projection-inspect", `${inspectSource}\nreturn {ok:true,...observation};`, {
+        target,
+        mapId,
+    }, "read");
+}
+export function publishMapSnippet(target, drawing, expected) {
+    return snippet("map-projection-publish", `${inspectSource}
+if (conflicts.length || JSON.stringify(observation) !== JSON.stringify(CFG.expected)) throw new Error("Map changed after inspection; reconcile before publishing");
+const fontName = CFG.drawing.fontFamily || "Inter";
+const exactFonts = Array.isArray(penpot.fonts.all) ? penpot.fonts.all.filter(font => font.name === fontName) : [];
+if (exactFonts.length !== 1) throw new Error("Map font unavailable or ambiguous: " + fontName);
+const font = exactFonts[0];
+if (typeof font.applyToText !== "function" || !Array.isArray(font.variants)) throw new Error("Map font unavailable");
+const variants = font.variants.filter(variant => String(variant.fontWeight) === "400" && (variant.fontStyle || "normal") === "normal");
+if (variants.length !== 1) throw new Error("Map regular font variant unavailable or ambiguous");
+if (typeof penpot.currentPage.root.setSharedPluginData !== "function" || ["createBoard","createRectangle","createEllipse","createPath","createText"].some(method => typeof penpot[method] !== "function")) throw new Error("Required native map creation/metadata APIs unavailable");
+const detailBoards = new Map();
+for (const node of CFG.drawing.nodes.filter(node => node.detail)) {
+  const detail = node.detail;
+  if (detail.fileId !== CFG.target.fileId) throw new Error("Detail map target must be in the same pinned file");
+  const pages = penpot.currentFile.pages.filter(page => page.id === detail.pageId);
+  if (pages.length !== 1 || typeof pages[0].getShapeById !== "function") throw new Error("Detail map target page is missing or cannot be inspected");
+  const target = pages[0].getShapeById(detail.frameId);
+  const targetMeta = target ? readMeta(target) : null;
+  if (!target || target.type !== "board" || !targetMeta || targetMeta.owner !== "penpair" || targetMeta.role !== "board" || !detail.mapId || targetMeta.mapId !== detail.mapId || !detail.contractHash || targetMeta.contractHash !== detail.contractHash) throw new Error("Detail map target is not the existing pinned owned contract board");
+  if (typeof target.addInteraction !== "function" || typeof target.removeInteraction !== "function") throw new Error("Native detail interaction API is unavailable");
+  detailBoards.set(node.id,target);
+}
+let root = board;
+if (!root) { root = penpot.createBoard(); root.name = CFG.drawing.title; root.fills = [{fillColor:"#F8FAFC",fillOpacity:1}]; root.clipContent = false; root.x = CFG.drawing.origin?.x || 0; root.y = CFG.drawing.origin?.y || 0; root.resize(1600,1200); }
+const metadata = (shape, role, logicalId, extra = {}) => {
+  if (typeof shape.setSharedPluginData !== "function") throw new Error("Map metadata write API unavailable");
+  shape.setSharedPluginData("penpair", "map", JSON.stringify({schemaVersion:1,owner:"penpair",mapId:CFG.mapId,role,logicalId,...extra}));
+};
+metadata(root,"board",CFG.mapId,{contractHash:CFG.drawing.contractHash});
+const previous = new Map(shapes.map(shape => [shape.role + ":" + shape.logicalId,shape]));
+const retained = new Set();
+const get = (role,id,create) => { const prior = previous.get(role + ":" + id); const shape = prior ? penpot.currentPage.getShapeById(prior.shapeId) : create(); root.appendChild(shape); retained.add(shape.id);shape.opacity=1;shape.blendMode="normal"; metadata(shape,role,id); return shape; };
+const strongVariants = font.variants.filter(variant => ["600","700"].includes(String(variant.fontWeight)) && (variant.fontStyle || "normal") === "normal").sort((left,right)=>Number(left.fontWeight)-Number(right.fontWeight));
+const textShape = entry => {
+  const shape = get(entry.role,entry.logicalId,() => penpot.createText(entry.text || " "));
+  shape.characters = entry.text || " ";
+  font.applyToText(shape,entry.strong && strongVariants.length ? strongVariants[0] : variants[0]);
+  shape.fontSize = entry.fontSize; shape.resize(entry.width,entry.height); shape.growType = "auto-height";
+  shape.x=root.x+entry.x; shape.y=root.y+entry.y; shape.fills=[{fillColor:entry.color,fillOpacity:1}];
+  return shape;
+};
+const plannedNodes = CFG.drawing.nodes;
+const nodes = new Map(plannedNodes.map(node => [node.id,node]));
+for (const edge of CFG.drawing.edges) {
+  const from = nodes.get(edge.from), to = nodes.get(edge.to);
+  const shape = get("edge",edge.id,() => penpot.createPath());
+  const points = edge.points.map(point => ({x:root.x+point.x,y:root.y+point.y}));
+  shape.content = points.map((point,index) => (index ? "L" : "M")+point.x+" "+point.y).join(" ");
+  shape.fills=[]; shape.strokes=[{strokeColor:"#98A2B3",strokeWidth:1.25,strokeCapEnd:"line-arrow"}];
+  metadata(shape,"edge",edge.id,{from:edge.from,to:edge.to});
+}
+for (const node of plannedNodes) {
+  const shape = get("node",node.id,() => penpot.createRectangle());
+  shape.name=node.kind+": "+node.label;shape.resize(node.width,node.height);shape.x=root.x+node.x;shape.y=root.y+node.y;
+  shape.fills=[{fillColor:"#FFFFFF",fillOpacity:1}];shape.strokes=[{strokeColor:"#D0D5DD",strokeWidth:1}];shape.borderRadius=12;
+  const well = get("icon-well",node.id,() => penpot.createRectangle());well.resize(32,32);well.x=shape.x+16;well.y=shape.y+16;well.borderRadius=8;well.fills=[{fillColor:"#EEF2FF",fillOpacity:1}];well.strokes=[];
+  const iconKey=node.icon || CFG.iconDefaults[node.id];
+  const glyph=get("icon",node.id,()=>penpot.createPath());
+  glyph.content=CFG.iconPaths[iconKey].replace(/([ML])(-?[0-9.]+) (-?[0-9.]+)/g,(_all,command,x,y)=>command+(shape.x+24+Number(x)*16/24)+" "+(shape.y+24+Number(y)*16/24));
+  glyph.resize(16,16);glyph.x=shape.x+24;glyph.y=shape.y+24;
+  glyph.fills=[];glyph.strokes=[{strokeColor:"#5B5BD6",strokeWidth:1.6,strokeCapStart:"round",strokeCapEnd:"round",strokeJoinStyle:"round"}];metadata(glyph,"icon",node.id,{iconKey});
+  for(const [role,x] of [["port-in",shape.x],["port-out",shape.x+shape.width]]){
+    const port=get(role,node.id,()=>penpot.createEllipse());port.resize(8,8);port.x=x-4;port.y=shape.y+shape.height/2-4;port.fills=[{fillColor:"#FFFFFF",fillOpacity:1}];port.strokes=[{strokeColor:"#98A2B3",strokeWidth:1.25}];
+  }
+}
+for(const annotation of CFG.drawing.annotations || []){
+  const panel=get("annotation-panel",annotation.id,()=>penpot.createRectangle());panel.resize(annotation.width,annotation.height);panel.x=root.x+annotation.x;panel.y=root.y+annotation.y;panel.borderRadius=12;panel.fills=[{fillColor:"#FFFFFF",fillOpacity:1}];panel.strokes=[{strokeColor:"#E4E7EC",strokeWidth:1}];
+}
+for(const entry of CFG.textEntries) textShape(entry);
+for(const node of plannedNodes){
+  const clickableRoles=new Set(["node","label","summary","badge","icon-well","icon","port-in","port-out"]);
+  for(const id of retained){
+    const shape=penpot.currentPage.getShapeById(id);const info=readMeta(shape);
+    if(info.logicalId!==node.id || !clickableRoles.has(info.role))continue;
+    if(Array.isArray(shape.interactions))for(const interaction of [...shape.interactions])shape.removeInteraction(interaction);
+    if(node.detail)shape.addInteraction("click",{type:"navigate-to",destination:detailBoards.get(node.id)});
+  }
+}
+if (typeof penpot.waitForLayoutUpdate === "function") await penpot.waitForLayoutUpdate();
+const right = Math.max(900,...root.children.map(shape => shape.x-root.x+shape.width)) + 64;
+const bottom = Math.max(160,...root.children.map(shape => shape.y-root.y+shape.height)) + 64;
+root.resize(right,bottom);
+for (const prior of shapes) if (!retained.has(prior.shapeId)) penpot.currentPage.getShapeById(prior.shapeId).remove();
+return {ok:true,boardId:root.id};`, {
+        target,
+        mapId: drawing.mapId,
+        drawing,
+        textEntries: nativeMapTextEntries(drawing),
+        iconPaths: nativeMapIcons,
+        iconDefaults: Object.fromEntries(drawing.nodes.map((node) => [
+            node.id,
+            defaultMapIcon(node.kind),
+        ])),
+        originLabels: mapOriginLabels,
+        originLegend: mapOriginLegend,
+        expected: {
+            boardId: expected.boardId,
+            boardBounds: expected.boardBounds,
+            contractHash: expected.contractHash,
+            shapes: expected.shapes,
+            conflicts: expected.conflicts,
+        },
+    }, "write");
+}

package/dist/map-penpot/status-labels.d.ts

@@ -0,0 +1,7 @@
+export declare const mapOriginLabels: {
+    observed: string;
+    proposed: string;
+    "owner-decision": string;
+    unknown: string;
+};
+export declare const mapOriginLegend = "Origin: Observed \u00B7 Proposed \u00B7 Owner decision \u00B7 Unknown. Status labels describe evidence, not implementation acceptance.";

package/dist/map-penpot/status-labels.js

@@ -0,0 +1,7 @@
+export const mapOriginLabels = {
+    observed: "Observed",
+    proposed: "Proposed",
+    "owner-decision": "Owner decision",
+    unknown: "Unknown",
+};
+export const mapOriginLegend = "Origin: Observed · Proposed · Owner decision · Unknown. Status labels describe evidence, not implementation acceptance.";

package/dist/map-penpot/types.d.ts

@@ -0,0 +1,161 @@
+import type { MapIcon, MapDrawingPlan } from "../maps/types.js";
+import type { ExecuteOptions } from "../client.js";
+import type { OperationOptions, OperationReport } from "../operation.js";
+import type { ExportResult } from "../export.js";
+export interface NativeDrawingNode {
+    id: string;
+    label: string;
+    summary?: string;
+    description?: string;
+    icon?: MapIcon;
+    cardTitle?: string;
+    cardSummary?: string;
+    annotationId?: string;
+    kind: string;
+    requirementIds?: string[];
+    detail?: {
+        mapId?: string;
+        contractHash?: string;
+        sourceId: string;
+        path: string;
+        sha256: string;
+        fileId: string;
+        pageId: string;
+        frameId: string;
+    };
+    origin?: "observed" | "proposed" | "owner-decision" | "unknown";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface NativeDrawingEdge {
+    labelBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    points?: {
+        x: number;
+        y: number;
+    }[];
+    id: string;
+    from: string;
+    to: string;
+    label: string;
+}
+export interface MapDrawing {
+    mapId: string;
+    contractHash: string;
+    title: string;
+    goal?: string;
+    summary?: string;
+    description?: string;
+    headerSummary?: string;
+    header?: MapDrawingPlan["header"];
+    annotations?: MapDrawingPlan["annotations"];
+    fontFamily?: string;
+    origin?: {
+        x: number;
+        y: number;
+    };
+    nodes: NativeDrawingNode[];
+    edges: NativeDrawingEdge[];
+}
+export interface MapTarget {
+    fileId: string;
+    pageId: string;
+    boardId?: string;
+}
+export interface ProjectionShape {
+    shapeId: string;
+    logicalId: string;
+    role: "node" | "label" | "edge" | "edge-label" | "title" | "badge" | "legend" | "map-summary" | "map-full-summary" | "map-goal" | "map-description" | "summary" | "full-label" | "full-summary" | "description" | "annotation-panel" | "annotation-id" | "annotation-heading" | "icon-well" | "icon" | "port-in" | "port-out";
+    label: string | null;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    content: string | null;
+    appearance?: unknown;
+    iconKey?: string | null;
+    interactions?: {
+        trigger: string;
+        type: string;
+        destinationId: string | null;
+        destinationPageId?: string | null;
+        destinationMapHash?: string | null;
+        destinationMapId?: string | null;
+    }[] | null;
+    from?: string;
+    to?: string;
+}
+export interface NativeMapProjection {
+    schemaVersion: 1;
+    kind: "native-map-projection";
+    fileId: string;
+    pageId: string;
+    boardId: string | null;
+    boardBounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    mapId: string;
+    contractHash: string | null;
+    fingerprint: string;
+    shapes: ProjectionShape[];
+    conflicts: string[];
+}
+export interface PublishMapOptions extends OperationOptions {
+    /** Required for writes; the standard operation journal persists the pre-write snapshot. */
+    journal?: OperationOptions["journal"];
+    /** Last independently observed projection. Required before replacing an existing map. */
+    expected?: NativeMapProjection;
+    /** Export remains evidence awaiting human/agent visual inspection. */
+    export?: boolean;
+}
+export interface PublishMapResult {
+    report: OperationReport;
+    projection: NativeMapProjection;
+    image?: ExportResult;
+    visualReviewRequired: boolean;
+}
+export interface NativeMapProposal {
+    schemaVersion: 1;
+    kind: "native-map-proposal";
+    baseContractHash: string;
+    observedProjectionHash: string;
+    mapId: string;
+    title?: string;
+    metadataChanges?: {
+        title?: string;
+        goal?: string;
+        summary?: string | null;
+        description?: string | null;
+    };
+    changes: {
+        nodeId: string;
+        label?: string;
+        summary?: string | null;
+        description?: string | null;
+        icon?: MapIcon | null;
+    }[];
+    edgeChanges: {
+        edgeId: string;
+        from: string;
+        to: string;
+        label: string;
+    }[];
+    presentation: {
+        nodeId: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }[];
+    findings: string[];
+}
+export type ProjectionReadOptions = ExecuteOptions;

package/dist/map-penpot/types.js

@@ -0,0 +1 @@
+export {};

package/dist/maps/annotation-layout.d.ts

@@ -0,0 +1,24 @@
+import type { MapDrawingAnnotation } from "./types.js";
+type AnnotationContent = Pick<MapDrawingAnnotation, "nodeId" | "title" | "goal" | "summary" | "description" | "width">;
+export interface MapAnnotationLayout {
+    idBox: {
+        y: number;
+        height: number;
+    };
+    titleBox?: {
+        y: number;
+        height: number;
+    };
+    fields: Array<{
+        field: "goal" | "summary" | "description";
+        headingY: number;
+        headingHeight: number;
+        y: number;
+        height: number;
+    }>;
+    height: number;
+}
+/** Conservative word wrapping for Inter notes; native text uses the same reserved boxes. */
+export declare function mapNoteTextHeight(text: string, width: number, fontSize?: number, lineHeight?: number): number;
+export declare function mapAnnotationLayout(annotation: AnnotationContent): MapAnnotationLayout;
+export {};

package/dist/maps/annotation-layout.js

@@ -0,0 +1,85 @@
+function wordWidth(word, fontSize) {
+    return Array.from(word).reduce((width, character) => {
+        const factor = /\s/.test(character)
+            ? 0.35
+            : /[il.,'!:;]/.test(character)
+                ? 0.35
+                : /[MW@#]/.test(character)
+                    ? 1
+                    : /[A-Z]/.test(character)
+                        ? 0.78
+                        : /[a-z0-9]/.test(character)
+                            ? 0.62
+                            : 1;
+        return width + factor * fontSize;
+    }, 0);
+}
+/** Conservative word wrapping for Inter notes; native text uses the same reserved boxes. */
+export function mapNoteTextHeight(text, width, fontSize = 14, lineHeight = 20) {
+    let lines = 0;
+    for (const paragraph of text.split(/\r?\n/)) {
+        let lineWidth = 0;
+        let paragraphLines = 1;
+        for (const token of paragraph.split(/(\s+)/).filter(Boolean)) {
+            const tokenWidth = wordWidth(token, fontSize);
+            if (lineWidth && lineWidth + tokenWidth > width) {
+                paragraphLines++;
+                lineWidth = 0;
+            }
+            if (!lineWidth && /^\s+$/.test(token)) {
+                continue;
+            }
+            paragraphLines += Math.max(0, Math.ceil(tokenWidth / width) - 1);
+            lineWidth += tokenWidth > width ? tokenWidth % width : tokenWidth;
+        }
+        lines += paragraphLines;
+    }
+    return Math.max(1, lines) * lineHeight;
+}
+export function mapAnnotationLayout(annotation) {
+    const width = annotation.width - 40;
+    const idBox = {
+        y: 20,
+        height: 16,
+    };
+    let y = idBox.y + idBox.height + 8;
+    const titleBox = annotation.nodeId
+        ? {
+            y,
+            height: mapNoteTextHeight(annotation.title, width, 16, 24),
+        }
+        : undefined;
+    if (titleBox) {
+        y += titleBox.height + 12;
+    }
+    const fields = [];
+    for (const field of [
+        "goal",
+        "summary",
+        "description",
+    ]) {
+        const value = annotation[field];
+        if (value === undefined) {
+            continue;
+        }
+        const height = mapNoteTextHeight(value, width);
+        fields.push({
+            field,
+            headingY: y,
+            headingHeight: 16,
+            y: y + 20,
+            height,
+        });
+        y += 20 + height + 14;
+    }
+    return {
+        idBox,
+        ...(titleBox
+            ? {
+                titleBox,
+            }
+            : {}),
+        fields,
+        height: y + 6,
+    };
+}

package/dist/maps/context.d.ts

@@ -0,0 +1,13 @@
+import type { ArtifactReview, MapContext, MapContract } from "./types.js";
+export interface MapContextOptions {
+    reviews?: ArtifactReview[];
+    sourceHashes?: Record<string, string>;
+    journeyHash?: string;
+    journeyRequirementIds?: string[];
+    detailMaps?: Record<string, MapContract>;
+    detailReadiness?: Record<string, boolean>;
+    reviewEvidenceValid?: boolean;
+    maxItems?: number;
+    maxBytes?: number;
+}
+export declare function buildMapContext(raw: MapContract, options?: MapContextOptions): MapContext;

package/dist/maps/context.js

@@ -0,0 +1,207 @@
+import { findArtifactReview } from "./review.js";
+import { hashMapContract, validateMapContract, validateMapDetail } from "./validation.js";
+export function buildMapContext(raw, options = {}) {
+    const contract = validateMapContract(raw);
+    const mapHash = hashMapContract(contract);
+    const maxItems = options.maxItems ?? 100;
+    const maxBytes = options.maxBytes ?? 128 * 1024;
+    if (!Number.isInteger(maxItems) ||
+        maxItems < 1 ||
+        maxItems > 1000 ||
+        !Number.isInteger(maxBytes) ||
+        maxBytes < 4096 ||
+        maxBytes > 1024 * 1024) {
+        throw new Error("Map context requires 1–1000 items and a 4 KiB–1 MiB byte budget");
+    }
+    const reviewed = !!findArtifactReview(options.reviews ?? [], contract.kind, contract.id, mapHash) &&
+        options.reviewEvidenceValid !== false;
+    const staleSources = contract.sources.filter((source) => options.sourceHashes &&
+        Object.hasOwn(options.sourceHashes, source.id) &&
+        options.sourceHashes[source.id] !== source.sha256);
+    const unknownSources = contract.sources.filter((source) => !options.sourceHashes || !Object.hasOwn(options.sourceHashes, source.id));
+    const staleJourney = !!contract.journey &&
+        options.journeyHash !== undefined &&
+        options.journeyHash !== contract.journey.sha256;
+    const missingJourney = contract.kind === "integration-map" && !contract.journey;
+    const unknownJourney = !!contract.journey &&
+        (options.journeyHash === undefined || options.journeyRequirementIds === undefined);
+    const mappedRequirements = new Set([
+        ...contract.nodes,
+        ...contract.edges,
+    ].flatMap((entry) => entry.requirementIds ?? []));
+    const unmappedRequirements = contract.requirements.filter((requirement) => !mappedRequirements.has(requirement.id));
+    const requirementIds = new Set(contract.requirements.map((requirement) => requirement.id));
+    const missingJourneyRequirements = contract.kind === "integration-map"
+        ? (options.journeyRequirementIds ?? []).filter((id) => !requirementIds.has(id))
+        : [];
+    const details = contract.nodes
+        .filter((node) => node.kind === "detail-link")
+        .map((node) => {
+        const source = contract.sources.find((entry) => entry.id === node.sourceIds[0]);
+        const supplied = options.detailMaps?.[source.id];
+        const child = supplied ? validateMapDetail(contract, node, supplied) : undefined;
+        return {
+            nodeId: node.id,
+            sourceId: source.id,
+            path: source.path,
+            sha256: source.sha256,
+            fileId: source.fileId,
+            pageId: source.pageId,
+            frameId: source.frameId,
+            ...(child
+                ? {
+                    mapId: child.id,
+                    mapHash: hashMapContract(child),
+                }
+                : {}),
+            ready: !!child && options.detailReadiness?.[source.id] === true,
+            review: "separate-artifact",
+            contents: "not-inlined",
+        };
+    });
+    const unreadyDetails = details.filter((detail) => !detail.ready);
+    const blockers = contract.findings.filter((finding) => finding.severity === "blocking" && finding.status === "open");
+    const unknowns = [
+        ...contract.nodes,
+        ...contract.edges,
+        ...contract.requirements,
+    ].filter((entry) => entry.origin === "unknown");
+    const freshness = staleSources.length || staleJourney
+        ? "stale"
+        : unknownSources.length || unknownJourney
+            ? "unassessed"
+            : "matches-supplied-inputs";
+    const reasons = [];
+    if (!reviewed) {
+        reasons.push("Exact current contract owner review is missing or its evidence is invalid");
+    }
+    if (staleSources.length) {
+        reasons.push(`${staleSources.length} changed source(s): ${staleSources
+            .slice(0, 5)
+            .map((source) => source.id)
+            .join(", ")}`);
+    }
+    if (unknownSources.length || unknownJourney) {
+        reasons.push("Source freshness is unassessed for one or more declared references");
+    }
+    if (staleJourney || missingJourney) {
+        reasons.push(staleJourney
+            ? "Referenced journey contract changed"
+            : "Integration map requires an explicit journey contract reference");
+    }
+    if (blockers.length) {
+        reasons.push(`${blockers.length} unresolved blocking finding(s): ${blockers
+            .slice(0, 5)
+            .map((finding) => finding.id)
+            .join(", ")}`);
+    }
+    if (unknowns.length) {
+        reasons.push(`${unknowns.length} unresolved unknown semantic element(s)`);
+    }
+    if (unmappedRequirements.length) {
+        reasons.push(`${unmappedRequirements.length} unmapped local requirement(s): ${unmappedRequirements
+            .slice(0, 5)
+            .map((requirement) => requirement.id)
+            .join(", ")}`);
+    }
+    if (missingJourneyRequirements.length) {
+        reasons.push(`${missingJourneyRequirements.length} omitted journey requirement(s): ${missingJourneyRequirements.slice(0, 5).join(", ")}`);
+    }
+    if (unreadyDetails.length) {
+        reasons.push(`${unreadyDetails.length} linked detail contract(s) require separate source/readiness/review checks; contents are not inlined`);
+    }
+    const context = {
+        schemaVersion: 1,
+        kind: "map-context",
+        mapKind: contract.kind,
+        mapId: contract.id,
+        mapHash,
+        title: contract.title,
+        goal: contract.goal,
+        ...(contract.summary === undefined
+            ? {}
+            : {
+                summary: contract.summary,
+            }),
+        ...(contract.description === undefined
+            ? {}
+            : {
+                description: contract.description,
+            }),
+        reviewed,
+        ready: reviewed &&
+            freshness === "matches-supplied-inputs" &&
+            !missingJourney &&
+            !blockers.length &&
+            !unknowns.length &&
+            !unmappedRequirements.length &&
+            !missingJourneyRequirements.length &&
+            !unreadyDetails.length,
+        freshness,
+        reasons,
+        nodes: contract.nodes.slice(0, maxItems),
+        edges: contract.edges.slice(0, maxItems),
+        requirements: contract.requirements.slice(0, maxItems),
+        findings: [
+            ...blockers,
+            ...contract.findings.filter((finding) => !blockers.includes(finding)),
+        ].slice(0, maxItems),
+        sources: contract.sources.slice(0, maxItems),
+        details: details.slice(0, maxItems),
+        truncated: [
+            contract.nodes,
+            contract.edges,
+            contract.requirements,
+            contract.findings,
+            contract.sources,
+            details,
+        ].some((entries) => entries.length > maxItems),
+        implementation: "not-assessed",
+    };
+    const collections = [
+        "nodes",
+        "edges",
+        "requirements",
+        "findings",
+        "sources",
+        "details",
+    ];
+    const markTruncated = () => {
+        context.truncated = true;
+        context.ready = false;
+        const reason = "Context is truncated; inspect the complete contract before deciding readiness";
+        if (!context.reasons.includes(reason)) {
+            context.reasons.push(reason);
+        }
+    };
+    if (context.truncated) {
+        markTruncated();
+    }
+    while (true) {
+        const visibleNodes = new Set(context.nodes.map((node) => node.id));
+        const visibleEdges = context.edges.filter((edge) => visibleNodes.has(edge.from) && visibleNodes.has(edge.to));
+        if (visibleEdges.length !== context.edges.length) {
+            markTruncated();
+            context.edges = visibleEdges;
+        }
+        if (Buffer.byteLength(JSON.stringify(context)) <= maxBytes) {
+            break;
+        }
+        markTruncated();
+        const largest = collections.reduce((previous, key) => JSON.stringify(context[key]).length > JSON.stringify(context[previous]).length
+            ? key
+            : previous);
+        if (!context[largest].length) {
+            const textKey = [
+                "goal",
+                "summary",
+                "description",
+            ].reduce((previous, key) => (context[key]?.length ?? 0) > (context[previous]?.length ?? 0) ? key : previous);
+            context[textKey] = (context[textKey] ?? "").slice(0, Math.floor((context[textKey]?.length ?? 0) / 2));
+        }
+        else {
+            context[largest].splice(Math.floor(context[largest].length / 2));
+        }
+    }
+    return context;
+}