mewkit 1.14.1 → 1.16.0

package/dist/visual-plan/domain/schemas.d.ts.map

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

package/dist/visual-plan/domain/schemas.js

@@ -0,0 +1,166 @@
+/**
+ * `visual-plan/v1` canonical artifact schema (shape + bounded sizes only).
+ *
+ * This module validates STRUCTURE. Cross-reference integrity (dangling refs,
+ * duplicate ids), coverage closure, HTML safety, and source-hash freshness are
+ * separate deterministic passes (`cross-refs.ts`, `coverage.ts`, the sanitizer,
+ * `hashing.ts`) so each can emit an exact JSON path and a stable code.
+ *
+ * `.passthrough()` is used on the top-level object so a future additive field
+ * survives a read→write round-trip; every nested object stays strict.
+ *
+ * Bounds (red-team: agent-native precedent caps depth/count/size) protect the
+ * validator and the Phase-4 renderer from pathological artifacts.
+ */
+import { z } from "zod";
+import { ENTITY_ID_RE } from "./ids.js";
+/** Concrete caps. Generous for real plans, hard ceilings against abuse. */
+export const CAPS = {
+    FRAMES: 200,
+    CONNECTORS: 400,
+    ANNOTATIONS: 200,
+    LANES: 40,
+    DOCUMENT_BLOCKS: 100,
+    SURFACES: 50,
+    STATES_PER_SURFACE: 100,
+    SOURCE_REFS: 500,
+    HTML_BYTES: 20_000,
+};
+const EntityId = z.string().regex(ENTITY_ID_RE, "invalid id (charset [A-Za-z0-9_-], max 128)");
+export const SURFACE_KINDS = ["browser", "desktop", "mobile", "popover", "panel", "dialog"];
+export const CHANGE_MODES = ["current", "target", "unchanged-context"];
+export const OMISSION_REASONS = [
+    "equivalent-layout",
+    "out-of-scope",
+    "unreachable-after-change",
+    "non-visual-only",
+    "requires-runtime-data",
+    "accepted-risk",
+];
+export const REVIEW_STATUSES = ["draft", "feedback-pending", "approved", "stale"];
+const SourceRefSchema = z
+    .object({
+    id: EntityId,
+    kind: z.enum(["code", "plan-requirement"]),
+    ref: z.string().min(1),
+    note: z.string().optional(),
+})
+    .strict();
+const OmissionSchema = z
+    .object({
+    reason: z.enum(OMISSION_REASONS),
+    representedBy: EntityId.optional(),
+    riskId: z.string().min(1).optional(),
+    note: z.string().optional(),
+})
+    .strict();
+const CoverageStateSchema = z
+    .object({
+    id: EntityId,
+    label: z.string().optional(),
+    frameIds: z.array(EntityId).max(CAPS.FRAMES).default([]),
+    sourceRefIds: z.array(EntityId).max(CAPS.SOURCE_REFS).default([]),
+    omitted: OmissionSchema.optional(),
+})
+    .strict();
+const CoverageSurfaceSchema = z
+    .object({
+    id: EntityId,
+    label: z.string().optional(),
+    states: z.array(CoverageStateSchema).max(CAPS.STATES_PER_SURFACE),
+})
+    .strict();
+const CoverageSummarySchema = z
+    .object({
+    total: z.number().int().nonnegative(),
+    resolved: z.number().int().nonnegative(),
+    planned: z.number().int().nonnegative(),
+    omitted: z.number().int().nonnegative(),
+    unresolved: z.number().int().nonnegative(),
+})
+    .strict();
+const UiCoverageSchema = z
+    .object({
+    surfaces: z.array(CoverageSurfaceSchema).max(CAPS.SURFACES),
+    /** Author totals are IGNORED — always recomputed from states. Optional here. */
+    summary: CoverageSummarySchema.optional(),
+})
+    .strict();
+const WireframeSchema = z
+    .object({
+    format: z.literal("semantic-html"),
+    html: z.string().max(CAPS.HTML_BYTES, `wireframe HTML exceeds ${CAPS.HTML_BYTES} bytes`),
+})
+    .strict();
+const LaneSchema = z
+    .object({ id: EntityId, label: z.string().optional(), kind: z.string().optional() })
+    .strict();
+const FrameSchema = z
+    .object({
+    id: EntityId,
+    label: z.string().min(1),
+    surface: z.enum(SURFACE_KINDS),
+    laneId: EntityId,
+    order: z.number().int(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    stateKind: z.string().optional(),
+    changeMode: z.enum(CHANGE_MODES),
+    coverageStateIds: z.array(EntityId).max(CAPS.STATES_PER_SURFACE).default([]),
+    sourceRefIds: z.array(EntityId).max(CAPS.SOURCE_REFS).default([]),
+    wireframe: WireframeSchema,
+})
+    .strict();
+const ConnectorSchema = z
+    .object({ id: EntityId, from: EntityId, to: EntityId, label: z.string().optional() })
+    .strict();
+export const AnnotationSchema = z
+    .object({
+    id: EntityId,
+    kind: z.enum(["note", "markup"]),
+    text: z.string().min(1),
+    targetId: EntityId.optional(),
+    placement: z.enum(["top", "right", "bottom", "left"]).optional(),
+    points: z.array(z.object({ x: z.number(), y: z.number() }).strict()).optional(),
+})
+    .strict();
+const CanvasSchema = z
+    .object({
+    lanes: z.array(LaneSchema).max(CAPS.LANES),
+    frames: z.array(FrameSchema).max(CAPS.FRAMES),
+    connectors: z.array(ConnectorSchema).max(CAPS.CONNECTORS),
+    annotations: z.array(AnnotationSchema).max(CAPS.ANNOTATIONS),
+})
+    .strict();
+const DocumentBlockSchema = z
+    .object({ id: EntityId, title: z.string().optional(), body: z.string() })
+    .strict();
+const SourceSchema = z
+    .object({
+    planPath: z.string().min(1),
+    planHash: z.string(),
+    phaseHashes: z.record(z.string(), z.string()),
+})
+    .strict();
+const ReviewSchema = z
+    .object({
+    status: z.enum(REVIEW_STATUSES),
+    approvedRevision: z.number().int().nonnegative().nullable().default(null),
+    approvedAt: z.string().nullable().default(null),
+    pendingFeedbackBatchIds: z.array(z.string()).default([]),
+})
+    .strict();
+export const VisualPlanSchema = z
+    .object({
+    schemaVersion: z.literal("visual-plan/v1"),
+    id: EntityId,
+    revision: z.number().int().nonnegative(),
+    source: SourceSchema,
+    uiCoverage: UiCoverageSchema,
+    canvas: CanvasSchema,
+    documentBlocks: z.array(DocumentBlockSchema).max(CAPS.DOCUMENT_BLOCKS).default([]),
+    sourceRefs: z.array(SourceRefSchema).max(CAPS.SOURCE_REFS).default([]),
+    review: ReviewSchema,
+})
+    .passthrough();
+//# sourceMappingURL=schemas.js.map

package/dist/visual-plan/domain/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/visual-plan/domain/schemas.ts"],"names":[],"mappings":"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"}

package/dist/visual-plan/infrastructure/atomic-write.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Crash-safe same-directory atomic write (Phase-1 inline copy).
+ *
+ * Same-dir tmp + renameSync (atomic on POSIX because tmp and target share a
+ * filesystem). A self-contained copy local to the visual-plan module; the
+ * shared `local-web/atomic-write.ts` is the general-purpose primitive. The tmp
+ * prefix keeps orphaned temps from ever matching the `phase-NN-*.md` glob.
+ */
+/** Write `content` to `targetPath` atomically via a same-directory temp file. */
+export declare function atomicWriteFileSync(targetPath: string, content: string): void;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/visual-plan/infrastructure/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/atomic-write.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAyB7E"}

package/dist/visual-plan/infrastructure/atomic-write.js

@@ -0,0 +1,44 @@
+/**
+ * Crash-safe same-directory atomic write (Phase-1 inline copy).
+ *
+ * Same-dir tmp + renameSync (atomic on POSIX because tmp and target share a
+ * filesystem). A self-contained copy local to the visual-plan module; the
+ * shared `local-web/atomic-write.ts` is the general-purpose primitive. The tmp
+ * prefix keeps orphaned temps from ever matching the `phase-NN-*.md` glob.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const TMP_PREFIX = ".visual-plan-tmp-";
+/** Write `content` to `targetPath` atomically via a same-directory temp file. */
+export function atomicWriteFileSync(targetPath, content) {
+    const dir = path.dirname(targetPath);
+    const tmpPath = path.join(dir, `${TMP_PREFIX}${crypto.randomBytes(6).toString("hex")}`);
+    fs.writeFileSync(tmpPath, content, "utf-8");
+    try {
+        try {
+            fs.renameSync(tmpPath, targetPath);
+        }
+        catch (error) {
+            const e = error;
+            if (e.code === "EPERM") {
+                // Windows: target may be briefly locked by another process. Single retry.
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+                fs.renameSync(tmpPath, targetPath);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            // best-effort cleanup; surface the original error
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/visual-plan/infrastructure/atomic-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/atomic-write.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAEvC,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,UAAkB,EAAE,OAAe;IACtE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxF,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC;QACJ,IAAI,CAAC;YACJ,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,CAAC,GAAG,KAA8B,CAAC;YACzC,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACxB,0EAA0E;gBAC1E,OAAO,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;gBACjE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACP,MAAM,KAAK,CAAC;YACb,CAAC;QACF,CAAC;IACF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC;YACJ,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACR,kDAAkD;QACnD,CAAC;QACD,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC"}

package/dist/visual-plan/infrastructure/feedback-repository.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Immutable feedback-batch storage under `<plan-dir>/visual-plan/feedback/`.
+ *
+ * A batch file is write-once: `writeBatch` refuses to overwrite an existing id
+ * (immutability is the misapplication guard). The batch id is validated against
+ * the strict `feedback-<ts>-<slug>` pattern BEFORE any path join (red-team M8),
+ * so a traversal/absolute/null-byte id can never escape the feedback dir.
+ * Batches are committed to git by default (Validation Session 1) — they are
+ * review evidence, like the plan files.
+ */
+import { type FeedbackBatch } from "../domain/feedback-schemas.js";
+/** Persist a batch write-once. Returns false if a batch with this id already exists. */
+export declare function writeBatch(planDir: string, batch: FeedbackBatch): boolean;
+/** Read + validate a batch by id, or null when absent/invalid. Throws on a malformed id. */
+export declare function readBatch(planDir: string, id: string): FeedbackBatch | null;
+/** List batch ids present in the feedback dir (for `status` / orphan detection). */
+export declare function listBatchIds(planDir: string): string[];
+//# sourceMappingURL=feedback-repository.d.ts.map

package/dist/visual-plan/infrastructure/feedback-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-repository.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/feedback-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAWxF,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAMzE;AAED,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAU3E;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAWtD"}

package/dist/visual-plan/infrastructure/feedback-repository.js

@@ -0,0 +1,59 @@
+/**
+ * Immutable feedback-batch storage under `<plan-dir>/visual-plan/feedback/`.
+ *
+ * A batch file is write-once: `writeBatch` refuses to overwrite an existing id
+ * (immutability is the misapplication guard). The batch id is validated against
+ * the strict `feedback-<ts>-<slug>` pattern BEFORE any path join (red-team M8),
+ * so a traversal/absolute/null-byte id can never escape the feedback dir.
+ * Batches are committed to git by default (Validation Session 1) — they are
+ * review evidence, like the plan files.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isValidFeedbackBatchId } from "../domain/ids.js";
+import { FeedbackBatchSchema } from "../domain/feedback-schemas.js";
+import { atomicWriteFileSync } from "./atomic-write.js";
+const FEEDBACK_DIR = path.join("visual-plan", "feedback");
+/** Absolute path to a batch file, validating the id BEFORE the join. Throws on a bad id. */
+function batchPath(planDir, id) {
+    if (!isValidFeedbackBatchId(id))
+        throw new Error(`invalid feedback batch id: ${JSON.stringify(id)}`);
+    return path.join(planDir, FEEDBACK_DIR, `${id}.json`);
+}
+/** Persist a batch write-once. Returns false if a batch with this id already exists. */
+export function writeBatch(planDir, batch) {
+    const file = batchPath(planDir, batch.id);
+    if (fs.existsSync(file))
+        return false; // immutable — never overwrite
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWriteFileSync(file, `${JSON.stringify(batch, null, 2)}\n`);
+    return true;
+}
+/** Read + validate a batch by id, or null when absent/invalid. Throws on a malformed id. */
+export function readBatch(planDir, id) {
+    const file = batchPath(planDir, id);
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const parsed = FeedbackBatchSchema.safeParse(JSON.parse(text));
+    return parsed.success ? parsed.data : null;
+}
+/** List batch ids present in the feedback dir (for `status` / orphan detection). */
+export function listBatchIds(planDir) {
+    try {
+        return fs
+            .readdirSync(path.join(planDir, FEEDBACK_DIR))
+            .filter((n) => n.endsWith(".json"))
+            .map((n) => n.slice(0, -5))
+            .filter(isValidFeedbackBatchId)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=feedback-repository.js.map

package/dist/visual-plan/infrastructure/feedback-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-repository.js","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/feedback-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAsB,MAAM,+BAA+B,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;AAE1D,4FAA4F;AAC5F,SAAS,SAAS,CAAC,OAAe,EAAE,EAAU;IAC7C,IAAI,CAAC,sBAAsB,CAAC,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACrG,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AACvD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,KAAoB;IAC/D,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IAC1C,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,8BAA8B;IACrE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,mBAAmB,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC;AACb,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,EAAU;IACpD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACpC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACJ,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC,CAAC;IAC1E,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5C,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC3C,IAAI,CAAC;QACJ,OAAO,EAAE;aACP,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;aAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;aAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;aAC1B,MAAM,CAAC,sBAAsB,CAAC;aAC9B,IAAI,EAAE,CAAC;IACV,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AACF,CAAC"}

package/dist/visual-plan/infrastructure/hashing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Source-hash computation + stale detection for the visual artifact.
+ *
+ * The artifact pins the SHA-256 of the Markdown plan it was generated from
+ * (`source.planHash`) and of every phase file (`source.phaseHashes`). If a
+ * human edits `plan.md`/`phase-*.md` after generation, the recomputed hash
+ * diverges and validation reports STALE_SOURCE_HASH — the artifact must be
+ * regenerated or re-hashed (`rehash`) before it can be approved (red-team M1).
+ *
+ * `artifactHash` (SHA-256 of the plan.json bytes) is the pointer cached in
+ * `.plan-state.json.visual.hash`; it detects artifact drift, not source drift.
+ */
+import { type ValidationError } from "../domain/errors.js";
+import type { VisualPlan } from "../domain/schemas.js";
+/** SHA-256 of a UTF-8 string, `sha256:`-prefixed lowercase hex. */
+export declare function sha256(content: string): string;
+/** SHA-256 of a file's bytes, or `null` if it cannot be read. */
+export declare function hashFile(filePath: string): string | null;
+/** SHA-256 of the artifact's on-disk bytes (the `.plan-state.json` pointer). */
+export declare function artifactHash(planDir: string, artifactRelPath: string): string | null;
+export interface SourceHashes {
+    planHash: string;
+    phaseHashes: Record<string, string>;
+}
+/**
+ * Recompute source hashes from disk. `planPath` is resolved relative to
+ * `planDir`; phase files are discovered by the `phase-NN-*.md` convention in
+ * the plan directory. Missing plan file → empty planHash (validation catches it).
+ */
+export declare function computeSourceHashes(planDir: string, planPath: string): SourceHashes;
+/**
+ * Compare the artifact's pinned source hashes against freshly-computed ones.
+ * Any divergence (plan bytes changed, a phase added/removed/edited) is a
+ * STALE_SOURCE_HASH error with the exact JSON path.
+ */
+export declare function checkSourceFreshness(plan: VisualPlan, planDir: string): ValidationError[];
+//# sourceMappingURL=hashing.d.ts.map

package/dist/visual-plan/infrastructure/hashing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashing.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/hashing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAKvD,mEAAmE;AACnE,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpF;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAiBnF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CAazF"}

package/dist/visual-plan/infrastructure/hashing.js

@@ -0,0 +1,81 @@
+/**
+ * Source-hash computation + stale detection for the visual artifact.
+ *
+ * The artifact pins the SHA-256 of the Markdown plan it was generated from
+ * (`source.planHash`) and of every phase file (`source.phaseHashes`). If a
+ * human edits `plan.md`/`phase-*.md` after generation, the recomputed hash
+ * diverges and validation reports STALE_SOURCE_HASH — the artifact must be
+ * regenerated or re-hashed (`rehash`) before it can be approved (red-team M1).
+ *
+ * `artifactHash` (SHA-256 of the plan.json bytes) is the pointer cached in
+ * `.plan-state.json.visual.hash`; it detects artifact drift, not source drift.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { err, ErrorCode } from "../domain/errors.js";
+/** Match `phase-NN-*.md`; capture the (possibly zero-padded) phase number. */
+const PHASE_FILE_RE = /^phase-(\d+)-.*\.md$/i;
+/** SHA-256 of a UTF-8 string, `sha256:`-prefixed lowercase hex. */
+export function sha256(content) {
+    return `sha256:${crypto.createHash("sha256").update(content, "utf-8").digest("hex")}`;
+}
+/** SHA-256 of a file's bytes, or `null` if it cannot be read. */
+export function hashFile(filePath) {
+    try {
+        return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** SHA-256 of the artifact's on-disk bytes (the `.plan-state.json` pointer). */
+export function artifactHash(planDir, artifactRelPath) {
+    return hashFile(path.join(planDir, artifactRelPath));
+}
+/**
+ * Recompute source hashes from disk. `planPath` is resolved relative to
+ * `planDir`; phase files are discovered by the `phase-NN-*.md` convention in
+ * the plan directory. Missing plan file → empty planHash (validation catches it).
+ */
+export function computeSourceHashes(planDir, planPath) {
+    const planHash = hashFile(path.join(planDir, planPath)) ?? "";
+    const phaseHashes = {};
+    let entries = [];
+    try {
+        entries = fs.readdirSync(planDir);
+    }
+    catch {
+        entries = [];
+    }
+    for (const name of entries.sort()) {
+        const m = name.match(PHASE_FILE_RE);
+        if (!m)
+            continue;
+        const key = String(parseInt(m[1], 10));
+        const h = hashFile(path.join(planDir, name));
+        if (h)
+            phaseHashes[key] = h;
+    }
+    return { planHash, phaseHashes };
+}
+/**
+ * Compare the artifact's pinned source hashes against freshly-computed ones.
+ * Any divergence (plan bytes changed, a phase added/removed/edited) is a
+ * STALE_SOURCE_HASH error with the exact JSON path.
+ */
+export function checkSourceFreshness(plan, planDir) {
+    const errors = [];
+    const fresh = computeSourceHashes(planDir, plan.source.planPath);
+    if (fresh.planHash !== plan.source.planHash) {
+        errors.push(err("source.planHash", ErrorCode.STALE_SOURCE_HASH, `plan.md hash diverged (expected ${plan.source.planHash || "<empty>"}, on disk ${fresh.planHash || "<missing>"})`));
+    }
+    const keys = new Set([...Object.keys(plan.source.phaseHashes), ...Object.keys(fresh.phaseHashes)]);
+    for (const k of keys) {
+        if (plan.source.phaseHashes[k] !== fresh.phaseHashes[k]) {
+            errors.push(err(`source.phaseHashes.${k}`, ErrorCode.STALE_SOURCE_HASH, `phase ${k} hash diverged`));
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=hashing.js.map

package/dist/visual-plan/infrastructure/hashing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashing.js","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/hashing.ts"],"names":[],"mappings":"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"}

package/dist/visual-plan/infrastructure/plan-state.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `.plan-state.json` schema-1.3 additive `visual` block reader/writer.
+ *
+ * Verified reality: NO CLI code parses `.plan-state.json` today — schema "1.2"
+ * lives in an agent-authored skill doc, and the file is agent-written. So this
+ * module owns ONLY the `visual` block: it does a read-modify-write that
+ * preserves every field it does not own (`phases`, `handoff`, and any unknown
+ * key). It never invents the rest of the file; if the file is absent it writes
+ * a minimal object carrying just the `visual` block (the schema-1.3 doc itself
+ * lands in Phase 3).
+ */
+import type { VisualPlan } from "../domain/schemas.js";
+/** The additive `visual` pointer block (schema 1.3). Snake_case matches the file's style. */
+export interface VisualBlock {
+    schema: "visual-plan/v1";
+    path: string;
+    revision: number;
+    hash: string;
+    source_plan_hash: string;
+    review_status: string;
+    pending_feedback: string[];
+}
+/** Derive the `visual` block from the artifact + its on-disk hash. */
+export declare function buildVisualBlock(plan: VisualPlan, planDir: string): VisualBlock;
+/** Read the whole `.plan-state.json` as an object, or `null` when absent/unparseable. */
+export declare function readPlanState(planDir: string): Record<string, unknown> | null;
+/**
+ * Write the `visual` block into `.plan-state.json`, preserving every other
+ * field (read-modify-write). Creates a minimal file if none exists.
+ */
+export declare function writeVisualBlock(planDir: string, visual: VisualBlock): void;
+//# sourceMappingURL=plan-state.d.ts.map

package/dist/visual-plan/infrastructure/plan-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-state.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/plan-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAMvD,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAU/E;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAc7E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAI3E"}

package/dist/visual-plan/infrastructure/plan-state.js

@@ -0,0 +1,58 @@
+/**
+ * `.plan-state.json` schema-1.3 additive `visual` block reader/writer.
+ *
+ * Verified reality: NO CLI code parses `.plan-state.json` today — schema "1.2"
+ * lives in an agent-authored skill doc, and the file is agent-written. So this
+ * module owns ONLY the `visual` block: it does a read-modify-write that
+ * preserves every field it does not own (`phases`, `handoff`, and any unknown
+ * key). It never invents the rest of the file; if the file is absent it writes
+ * a minimal object carrying just the `visual` block (the schema-1.3 doc itself
+ * lands in Phase 3).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFileSync } from "./atomic-write.js";
+import { artifactHash } from "./hashing.js";
+const PLAN_STATE_FILE = ".plan-state.json";
+/** POSIX-style pointer stored in the artifact + plan-state (stable across OSes). */
+const ARTIFACT_POINTER = "visual-plan/plan.json";
+/** Derive the `visual` block from the artifact + its on-disk hash. */
+export function buildVisualBlock(plan, planDir) {
+    return {
+        schema: "visual-plan/v1",
+        path: ARTIFACT_POINTER,
+        revision: plan.revision,
+        hash: artifactHash(planDir, ARTIFACT_POINTER) ?? "",
+        source_plan_hash: plan.source.planHash,
+        review_status: plan.review.status,
+        pending_feedback: [...plan.review.pendingFeedbackBatchIds],
+    };
+}
+/** Read the whole `.plan-state.json` as an object, or `null` when absent/unparseable. */
+export function readPlanState(planDir) {
+    const full = path.join(planDir, PLAN_STATE_FILE);
+    let text;
+    try {
+        text = fs.readFileSync(full, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return parsed !== null && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the `visual` block into `.plan-state.json`, preserving every other
+ * field (read-modify-write). Creates a minimal file if none exists.
+ */
+export function writeVisualBlock(planDir, visual) {
+    const existing = readPlanState(planDir) ?? {};
+    existing.visual = visual;
+    atomicWriteFileSync(path.join(planDir, PLAN_STATE_FILE), `${JSON.stringify(existing, null, 2)}\n`);
+}
+//# sourceMappingURL=plan-state.js.map

package/dist/visual-plan/infrastructure/plan-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-state.js","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/plan-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAC3C,oFAAoF;AACpF,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAajD,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,IAAgB,EAAE,OAAe;IACjE,OAAO;QACN,MAAM,EAAE,gBAAgB;QACxB,IAAI,EAAE,gBAAgB;QACtB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,YAAY,CAAC,OAAO,EAAE,gBAAgB,CAAC,IAAI,EAAE;QACnD,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;QACtC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;QACjC,gBAAgB,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,uBAAuB,CAAC;KAC1D,CAAC;AACH,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,aAAa,CAAC,OAAe;IAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IACjD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACJ,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;IACD,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;QAC3C,OAAO,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAkC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnG,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,MAAmB;IACpE,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAC9C,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AACpG,CAAC"}

package/dist/visual-plan/infrastructure/receipt-repository.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolution-receipt storage under `<plan-dir>/visual-plan/resolutions/`.
+ *
+ * A receipt records the per-operation outcome of applying a feedback batch
+ * (applied | rejected | unresolved). Receipt EXISTENCE is the "batch resolved"
+ * marker — the batch file itself stays byte-immutable. `writeReceipt` is
+ * write-once (a second apply of the same batch is refused). The batch/receipt id
+ * is validated against the strict pattern BEFORE any path join (red-team M8).
+ */
+import { type ResolutionReceipt } from "../domain/feedback-schemas.js";
+/** True when a resolution receipt already exists for this batch (⇒ already applied). */
+export declare function receiptExists(planDir: string, batchId: string): boolean;
+/** Persist a receipt write-once. Returns false if a receipt for this batch already exists. */
+export declare function writeReceipt(planDir: string, receipt: ResolutionReceipt): boolean;
+/** Read + validate every receipt in the plan (for approve's unresolved-check). */
+export declare function listReceipts(planDir: string): ResolutionReceipt[];
+//# sourceMappingURL=receipt-repository.d.ts.map

package/dist/visual-plan/infrastructure/receipt-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt-repository.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/infrastructure/receipt-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAWhG,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAMjF;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAkBjE"}