stageflow 0.25.0 → 0.30.0

package/dist/ui/index.html

@@ -13,8 +13,8 @@
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&display=swap" />
     <link rel="icon" type="image/svg+xml" href="/stageflow-icon.svg" />
     <title>Stageflow</title>
-    <script type="module" crossorigin src="/assets/index-Da5EHU6M.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CSsDued1.css">
+    <script type="module" crossorigin src="/assets/index-CntB4bZR.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Bv4p1aPK.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/workshop/autosave.d.ts

@@ -0,0 +1,58 @@
+import type { DraftPackage } from "../config/draftPackage.js";
+export declare const WORKSHOP_UNTITLED_AUTOSAVE_KEY = "__untitled__";
+export type WorkshopAutosaveChatMessage = {
+    id: string;
+    role: "assistant" | "user" | "system";
+    text: string;
+    artifacts?: unknown;
+};
+export type WorkshopAutosaveDestination = {
+    directory: string;
+    pipelineFilename?: string;
+};
+export type WorkshopAutosaveRecord = {
+    version: 1;
+    key: string;
+    updatedAt: string;
+    draft: DraftPackage;
+    messages: WorkshopAutosaveChatMessage[];
+    autoApply: boolean;
+    sessionModelOverride?: string | null;
+    destination?: WorkshopAutosaveDestination | null;
+    savedPath?: string | null;
+    savedTaskPath?: string | null;
+    diskFingerprints?: Record<string, string>;
+};
+export declare function workshopAutosaveSlotKey(pipelinePath: string | null | undefined): string;
+export declare function resolveWorkshopAutosaveStoreRoot(options: {
+    projectRoot?: string | null;
+    isGitProject?: boolean;
+}): string;
+export declare function workshopAutosaveDir(storeRoot: string): string;
+export declare function workshopAutosaveFilePath(storeRoot: string, key: string): string;
+export declare function parseWorkshopAutosaveRecord(value: unknown): WorkshopAutosaveRecord | null;
+export declare function readWorkshopAutosave(storeRoot: string, key: string): WorkshopAutosaveRecord | null;
+export declare function writeWorkshopAutosave(storeRoot: string, record: WorkshopAutosaveRecord): WorkshopAutosaveRecord;
+export declare function clearWorkshopAutosave(storeRoot: string, key: string): boolean;
+export declare function fingerprintPath(filePath: string): string | null;
+export declare function draftPackageDiskRelativePaths(input: {
+    pipelinePath: string;
+    draft: DraftPackage;
+    taskPath?: string | null;
+}): string[];
+export declare function fingerprintPackageFiles(projectRoot: string, relativePaths: readonly string[]): Record<string, string>;
+export declare function detectDiskChange(input: {
+    baseline?: Record<string, string> | null;
+    current: Record<string, string>;
+}): {
+    changed: boolean;
+    changedPaths: string[];
+};
+export type DiskChangeDecision = "reload" | "keep";
+export declare function applyDiskChangeDecision(input: {
+    decision: DiskChangeDecision;
+    currentFingerprints: Record<string, string>;
+}): {
+    clearAutosave: boolean;
+    nextFingerprints: Record<string, string>;
+};

package/dist/workshop/autosave.js

@@ -0,0 +1,222 @@
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { storeRootFor } from "../runstore/paths.js";
+export const WORKSHOP_UNTITLED_AUTOSAVE_KEY = "__untitled__";
+export function workshopAutosaveSlotKey(pipelinePath) {
+    const trimmed = pipelinePath?.trim();
+    if (!trimmed)
+        return WORKSHOP_UNTITLED_AUTOSAVE_KEY;
+    return trimmed.replace(/\\/g, "/");
+}
+export function resolveWorkshopAutosaveStoreRoot(options) {
+    const root = options.projectRoot?.trim();
+    if (root && options.isGitProject !== false) {
+        return storeRootFor(path.resolve(root));
+    }
+    return globalStageflowHome();
+}
+export function workshopAutosaveDir(storeRoot) {
+    return path.join(storeRoot, "workshop", "autosave");
+}
+export function workshopAutosaveFilePath(storeRoot, key) {
+    const safe = Buffer.from(workshopAutosaveSlotKey(key), "utf8").toString("base64url");
+    return path.join(workshopAutosaveDir(storeRoot), `${safe}.json`);
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseChatMessage(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (typeof value.id !== "string" || !value.id)
+        return null;
+    if (value.role !== "assistant" &&
+        value.role !== "user" &&
+        value.role !== "system") {
+        return null;
+    }
+    if (typeof value.text !== "string")
+        return null;
+    const msg = {
+        id: value.id,
+        role: value.role,
+        text: value.text,
+    };
+    if (value.artifacts !== undefined) {
+        msg.artifacts = value.artifacts;
+    }
+    return msg;
+}
+export function parseWorkshopAutosaveRecord(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (value.version !== 1)
+        return null;
+    if (typeof value.key !== "string" || !value.key)
+        return null;
+    if (typeof value.updatedAt !== "string" || !value.updatedAt)
+        return null;
+    if (!isPlainObject(value.draft))
+        return null;
+    if (!isPlainObject(value.draft.pipeline))
+        return null;
+    if (!Array.isArray(value.messages))
+        return null;
+    if (typeof value.autoApply !== "boolean")
+        return null;
+    const messages = [];
+    for (const entry of value.messages) {
+        const msg = parseChatMessage(entry);
+        if (!msg)
+            return null;
+        messages.push(msg);
+    }
+    const record = {
+        version: 1,
+        key: value.key,
+        updatedAt: value.updatedAt,
+        draft: value.draft,
+        messages,
+        autoApply: value.autoApply,
+    };
+    if (value.sessionModelOverride === null ||
+        typeof value.sessionModelOverride === "string") {
+        record.sessionModelOverride = value.sessionModelOverride;
+    }
+    if (value.destination === null) {
+        record.destination = null;
+    }
+    else if (isPlainObject(value.destination)) {
+        if (typeof value.destination.directory !== "string")
+            return null;
+        record.destination = {
+            directory: value.destination.directory,
+            ...(typeof value.destination.pipelineFilename === "string"
+                ? { pipelineFilename: value.destination.pipelineFilename }
+                : {}),
+        };
+    }
+    if (value.savedPath === null || typeof value.savedPath === "string") {
+        record.savedPath = value.savedPath;
+    }
+    if (value.savedTaskPath === null || typeof value.savedTaskPath === "string") {
+        record.savedTaskPath = value.savedTaskPath;
+    }
+    if (value.diskFingerprints !== undefined) {
+        if (!isPlainObject(value.diskFingerprints))
+            return null;
+        const fps = {};
+        for (const [k, v] of Object.entries(value.diskFingerprints)) {
+            if (typeof v !== "string")
+                return null;
+            fps[k] = v;
+        }
+        record.diskFingerprints = fps;
+    }
+    return record;
+}
+export function readWorkshopAutosave(storeRoot, key) {
+    const filePath = workshopAutosaveFilePath(storeRoot, key);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        const parsed = parseWorkshopAutosaveRecord(raw);
+        if (!parsed)
+            return null;
+        if (parsed.key !== workshopAutosaveSlotKey(key))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeWorkshopAutosave(storeRoot, record) {
+    const key = workshopAutosaveSlotKey(record.key);
+    const next = {
+        ...record,
+        version: 1,
+        key,
+        updatedAt: record.updatedAt || new Date().toISOString(),
+    };
+    const dir = workshopAutosaveDir(storeRoot);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(workshopAutosaveFilePath(storeRoot, key), `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return next;
+}
+export function clearWorkshopAutosave(storeRoot, key) {
+    const filePath = workshopAutosaveFilePath(storeRoot, key);
+    if (!existsSync(filePath))
+        return false;
+    unlinkSync(filePath);
+    return true;
+}
+export function fingerprintPath(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    const st = statSync(filePath);
+    return `${st.size}:${Math.trunc(st.mtimeMs)}`;
+}
+export function draftPackageDiskRelativePaths(input) {
+    const pipelinePath = input.pipelinePath.trim().replace(/\\/g, "/");
+    const paths = [pipelinePath];
+    const packageDir = path.posix.dirname(pipelinePath);
+    for (const stage of input.draft.stages ?? []) {
+        if (typeof stage.path !== "string" || !stage.path.trim())
+            continue;
+        const joined = path.posix
+            .normalize(path.posix.join(packageDir, stage.path.trim().replace(/\\/g, "/")))
+            .replace(/^\.\//, "");
+        paths.push(joined);
+    }
+    if (input.taskPath?.trim()) {
+        paths.push(input.taskPath.trim().replace(/\\/g, "/"));
+    }
+    return [...new Set(paths)];
+}
+export function fingerprintPackageFiles(projectRoot, relativePaths) {
+    const out = {};
+    const root = path.resolve(projectRoot);
+    for (const rel of relativePaths) {
+        const abs = path.resolve(root, rel);
+        const relToRoot = path.relative(root, abs);
+        if (relToRoot.startsWith("..") || path.isAbsolute(relToRoot)) {
+            out[rel] = "escaped";
+            continue;
+        }
+        out[rel] = fingerprintPath(abs) ?? "missing";
+    }
+    return out;
+}
+export function detectDiskChange(input) {
+    const baseline = input.baseline;
+    if (!baseline || Object.keys(baseline).length === 0) {
+        return { changed: false, changedPaths: [] };
+    }
+    const keys = new Set([
+        ...Object.keys(baseline),
+        ...Object.keys(input.current),
+    ]);
+    const changedPaths = [];
+    for (const key of keys) {
+        if ((baseline[key] ?? "missing") !== (input.current[key] ?? "missing")) {
+            changedPaths.push(key);
+        }
+    }
+    changedPaths.sort();
+    return { changed: changedPaths.length > 0, changedPaths };
+}
+export function applyDiskChangeDecision(input) {
+    if (input.decision === "reload") {
+        return {
+            clearAutosave: true,
+            nextFingerprints: input.currentFingerprints,
+        };
+    }
+    return {
+        clearAutosave: false,
+        nextFingerprints: input.currentFingerprints,
+    };
+}

package/dist/workshop/buildStore.d.ts

@@ -0,0 +1,79 @@
+import { type DraftPackage } from "../config/draftPackage.js";
+export type WorkshopBuildRecord = {
+    version: 1;
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    draft: DraftPackage;
+    projectRoot: string | null;
+    relativePath: string | null;
+};
+export type WorkshopBuildSummary = {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    projectRoot: string | null;
+    relativePath: string | null;
+};
+export type WorkshopBuildCreateInput = {
+    draft: DraftPackage;
+    id?: string;
+    now?: Date;
+    projectRoot?: string | null;
+    relativePath?: string | null;
+};
+export type WorkshopBuildUpdate = {
+    draft?: DraftPackage;
+    projectRoot?: string | null;
+    relativePath?: string | null;
+};
+export type WorkshopBuildStoreErrorCode = "workshop_build_not_found";
+export declare class WorkshopBuildStoreError extends Error {
+    readonly code: WorkshopBuildStoreErrorCode;
+    readonly buildId?: string;
+    constructor(message: string, code: WorkshopBuildStoreErrorCode, buildId?: string);
+}
+export declare function resolveWorkshopBuildStoreRoot(): string;
+export declare function workshopBuildsDir(storeRoot: string): string;
+export declare function workshopBuildFilePath(storeRoot: string, buildId: string): string;
+export declare function parseWorkshopBuildRecord(value: unknown): WorkshopBuildRecord | null;
+export declare function readWorkshopBuild(storeRoot: string, buildId: string): WorkshopBuildRecord | null;
+export declare function createWorkshopBuild(storeRoot: string, input: WorkshopBuildCreateInput): WorkshopBuildRecord;
+export declare function getWorkshopBuild(storeRoot: string, buildId: string): WorkshopBuildRecord;
+export declare function listWorkshopBuilds(storeRoot: string): WorkshopBuildSummary[];
+export type WorkshopPickerCatalogPipeline = {
+    project_root: string;
+    path: string;
+    id: string;
+};
+export declare function resolvePickerCatalogPipelines(items: readonly WorkshopPickerCatalogPipeline[], roots: readonly {
+    project_root: string;
+    path: string;
+}[]): WorkshopPickerCatalogPipeline[];
+export type WorkshopPickerRow = {
+    id: string | null;
+    name: string;
+    projectRoot: string | null;
+    relativePath: string | null;
+};
+export type FocusUnboundWorkshopBuildInput = {
+    projectRoot: string;
+    relativePath: string;
+};
+export type FocusUnboundWorkshopBuildResult = {
+    ok: true;
+    created: boolean;
+    build: WorkshopBuildRecord;
+} | {
+    ok: false;
+    status: 400 | 404;
+    error: string;
+};
+export declare function listWorkshopPickerRows(storeRoot: string, pipelines: ReadonlyArray<WorkshopPickerCatalogPipeline>, roots?: readonly {
+    project_root: string;
+    path: string;
+}[]): WorkshopPickerRow[];
+export declare function focusUnboundWorkshopBuild(storeRoot: string, input: FocusUnboundWorkshopBuildInput): Promise<FocusUnboundWorkshopBuildResult>;
+export declare function updateWorkshopBuild(storeRoot: string, buildId: string, patch: WorkshopBuildUpdate, options?: {
+    now?: Date;
+}): WorkshopBuildRecord;

package/dist/workshop/buildStore.js

@@ -0,0 +1,326 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { loadDraftPackage, parseDraftPackageBody, } from "../config/draftPackage.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+export class WorkshopBuildStoreError extends Error {
+    code;
+    buildId;
+    constructor(message, code, buildId) {
+        super(message);
+        this.name = "WorkshopBuildStoreError";
+        this.code = code;
+        if (buildId !== undefined)
+            this.buildId = buildId;
+    }
+}
+export function resolveWorkshopBuildStoreRoot() {
+    return globalStageflowHome();
+}
+export function workshopBuildsDir(storeRoot) {
+    return path.join(storeRoot, "workshop", "builds");
+}
+export function workshopBuildFilePath(storeRoot, buildId) {
+    return path.join(workshopBuildsDir(storeRoot), `${guardBuildId(buildId)}.json`);
+}
+function guardBuildId(buildId) {
+    const trimmed = buildId.trim();
+    if (!trimmed ||
+        trimmed.includes("/") ||
+        trimmed.includes("\\") ||
+        trimmed.includes("..") ||
+        trimmed === ".") {
+        throw new Error(`invalid workshop build id: ${buildId}`);
+    }
+    return trimmed;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeTie(value) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+function parseTieField(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string")
+        return undefined;
+    return normalizeTie(value);
+}
+function parseStoredDraft(value) {
+    const parsed = parseDraftPackageBody(value);
+    if ("ok" in parsed)
+        return null;
+    return parsed;
+}
+export function parseWorkshopBuildRecord(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (value.version !== 1)
+        return null;
+    if (typeof value.id !== "string" || !value.id)
+        return null;
+    if (typeof value.createdAt !== "string" || !value.createdAt)
+        return null;
+    if (typeof value.updatedAt !== "string" || !value.updatedAt)
+        return null;
+    const draft = parseStoredDraft(value.draft);
+    if (!draft)
+        return null;
+    const projectRoot = parseTieField(value.projectRoot);
+    if (projectRoot === undefined)
+        return null;
+    const relativePath = parseTieField(value.relativePath);
+    if (relativePath === undefined)
+        return null;
+    return {
+        version: 1,
+        id: value.id,
+        createdAt: value.createdAt,
+        updatedAt: value.updatedAt,
+        draft,
+        projectRoot,
+        relativePath,
+    };
+}
+function writeBuild(storeRoot, record) {
+    const dir = workshopBuildsDir(storeRoot);
+    mkdirSync(dir, { recursive: true });
+    const payload = {
+        version: 1,
+        id: record.id,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        draft: record.draft,
+        projectRoot: record.projectRoot,
+        relativePath: record.relativePath,
+    };
+    writeFileSync(workshopBuildFilePath(storeRoot, record.id), `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+export function readWorkshopBuild(storeRoot, buildId) {
+    let id;
+    try {
+        id = guardBuildId(buildId);
+    }
+    catch {
+        return null;
+    }
+    const filePath = workshopBuildFilePath(storeRoot, id);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        const parsed = parseWorkshopBuildRecord(raw);
+        if (!parsed || parsed.id !== id)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function createWorkshopBuild(storeRoot, input) {
+    const draft = parseStoredDraft(input.draft);
+    if (!draft) {
+        throw new Error("draft.pipeline is required");
+    }
+    const id = input.id?.trim() || randomUUID();
+    guardBuildId(id);
+    if (readWorkshopBuild(storeRoot, id)) {
+        throw new Error(`workshop build already exists: ${id}`);
+    }
+    const now = (input.now ?? new Date()).toISOString();
+    const record = {
+        version: 1,
+        id,
+        createdAt: now,
+        updatedAt: now,
+        draft,
+        projectRoot: normalizeTie(input.projectRoot),
+        relativePath: normalizeTie(input.relativePath),
+    };
+    writeBuild(storeRoot, record);
+    return record;
+}
+export function getWorkshopBuild(storeRoot, buildId) {
+    const record = readWorkshopBuild(storeRoot, buildId);
+    if (!record) {
+        throw new WorkshopBuildStoreError(`workshop_build_not_found: ${buildId}`, "workshop_build_not_found", buildId);
+    }
+    return record;
+}
+function listWorkshopBuildRecords(storeRoot) {
+    const dir = workshopBuildsDir(storeRoot);
+    if (!existsSync(dir))
+        return [];
+    const records = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const id = entry.name.slice(0, -".json".length);
+        const record = readWorkshopBuild(storeRoot, id);
+        if (!record)
+            continue;
+        records.push(record);
+    }
+    records.sort((a, b) => {
+        if (a.updatedAt !== b.updatedAt) {
+            return a.updatedAt < b.updatedAt ? 1 : -1;
+        }
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+    return records;
+}
+export function listWorkshopBuilds(storeRoot) {
+    return listWorkshopBuildRecords(storeRoot).map((record) => ({
+        id: record.id,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        projectRoot: record.projectRoot,
+        relativePath: record.relativePath,
+    }));
+}
+export function resolvePickerCatalogPipelines(items, roots) {
+    const byWire = new Map(roots.map((root) => [root.project_root, root.path]));
+    return items.map((item) => {
+        const resolved = byWire.get(item.project_root);
+        return resolved ? { ...item, project_root: resolved } : item;
+    });
+}
+function normalizeProjectRoot(value) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    if (path.isAbsolute(trimmed))
+        return path.resolve(trimmed);
+    return trimmed.replace(/\\/g, "/");
+}
+function normalizeRelativePath(value) {
+    if (value == null)
+        return null;
+    let trimmed = value.trim().replace(/\\/g, "/");
+    if (!trimmed)
+        return null;
+    while (trimmed.startsWith("./"))
+        trimmed = trimmed.slice(2);
+    return trimmed || null;
+}
+function tieKey(projectRoot, relativePath) {
+    if (!projectRoot || !relativePath)
+        return null;
+    return `${projectRoot}\0${relativePath}`;
+}
+function pickerName(id) {
+    const trimmed = id?.trim() ?? "";
+    return trimmed ? trimmed : "Untitled";
+}
+function findTiedBuild(storeRoot, projectRoot, relativePath) {
+    const key = tieKey(projectRoot, relativePath);
+    if (!key)
+        return null;
+    for (const record of listWorkshopBuildRecords(storeRoot)) {
+        const recordKey = tieKey(normalizeProjectRoot(record.projectRoot), normalizeRelativePath(record.relativePath));
+        if (recordKey === key)
+            return record;
+    }
+    return null;
+}
+export function listWorkshopPickerRows(storeRoot, pipelines, roots = []) {
+    const byWire = new Map(roots.map((root) => [root.project_root, root.path]));
+    const canonicalRoot = (value) => {
+        const normalized = normalizeProjectRoot(value);
+        if (!normalized)
+            return null;
+        return byWire.get(normalized) ?? normalized;
+    };
+    const rows = [];
+    const tied = new Set();
+    for (const record of listWorkshopBuildRecords(storeRoot)) {
+        const projectRoot = canonicalRoot(record.projectRoot);
+        const key = tieKey(projectRoot, normalizeRelativePath(record.relativePath));
+        if (key)
+            tied.add(key);
+        rows.push({
+            id: record.id,
+            name: pickerName(record.draft.pipeline.id),
+            projectRoot,
+            relativePath: record.relativePath,
+        });
+    }
+    for (const pipeline of pipelines) {
+        const projectRoot = canonicalRoot(pipeline.project_root);
+        const relativePath = normalizeRelativePath(pipeline.path);
+        if (!projectRoot || !relativePath)
+            continue;
+        const key = tieKey(projectRoot, relativePath);
+        if (key && tied.has(key))
+            continue;
+        rows.push({
+            id: null,
+            name: pickerName(pipeline.id),
+            projectRoot,
+            relativePath,
+        });
+    }
+    return rows;
+}
+export async function focusUnboundWorkshopBuild(storeRoot, input) {
+    const projectRoot = normalizeProjectRoot(input.projectRoot);
+    const relativePath = normalizeRelativePath(input.relativePath);
+    if (!projectRoot || !relativePath) {
+        return {
+            ok: false,
+            status: 400,
+            error: "project root and path are required",
+        };
+    }
+    const existing = findTiedBuild(storeRoot, projectRoot, relativePath);
+    if (existing) {
+        return { ok: true, created: false, build: existing };
+    }
+    const loaded = await loadDraftPackage(projectRoot, relativePath);
+    if (!loaded.ok) {
+        return { ok: false, status: loaded.status, error: loaded.error };
+    }
+    const again = findTiedBuild(storeRoot, projectRoot, relativePath);
+    if (again) {
+        return { ok: true, created: false, build: again };
+    }
+    const build = createWorkshopBuild(storeRoot, {
+        draft: loaded.draft,
+        projectRoot,
+        relativePath,
+    });
+    return { ok: true, created: true, build };
+}
+export function updateWorkshopBuild(storeRoot, buildId, patch, options) {
+    const record = getWorkshopBuild(storeRoot, buildId);
+    let draft = record.draft;
+    if (patch.draft !== undefined) {
+        const parsed = parseStoredDraft(patch.draft);
+        if (!parsed) {
+            throw new Error("draft.pipeline is required");
+        }
+        draft = parsed;
+    }
+    const next = {
+        ...record,
+        id: record.id,
+        version: 1,
+        updatedAt: (options?.now ?? new Date()).toISOString(),
+        draft,
+        projectRoot: patch.projectRoot === undefined
+            ? record.projectRoot
+            : normalizeTie(patch.projectRoot),
+        relativePath: patch.relativePath === undefined
+            ? record.relativePath
+            : normalizeTie(patch.relativePath),
+    };
+    writeBuild(storeRoot, next);
+    return next;
+}