openplanr 1.13.2 → 1.14.0

package/dist/services/operate/pipeline-handoff.js

@@ -0,0 +1,175 @@
+import { access, readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { canonicalDigest } from './canonical.js';
+import { resolveOperatingPipelineRoot } from './protocol.js';
+import { OperateError } from './types.js';
+import { resolveContainedPath } from './workspace.js';
+async function loadPortablePipelineModule() {
+    const root = resolveOperatingPipelineRoot();
+    if (!root) {
+        throw new OperateError('E_PIPELINE_NOT_INSTALLED', 'Operating Board routing requires the full planr-pipeline package.');
+    }
+    return import(pathToFileURL(path.join(root, 'lib', 'pipeline', 'index.mjs')).href);
+}
+export async function loadPipelinePoBridge() {
+    const module = (await loadPortablePipelineModule());
+    if (typeof module.preparePlan !== 'function' || typeof module.completePlan !== 'function') {
+        throw new OperateError('E_PIPELINE_NOT_INSTALLED', 'The installed pipeline does not expose the required PLAN engine API.');
+    }
+    return module;
+}
+export async function loadOperatingGeneratorBridge() {
+    const module = (await loadPortablePipelineModule());
+    if (typeof module.prepareOperatingArtifactGeneration !== 'function' ||
+        typeof module.renderOperatingArtifactTemplate !== 'function' ||
+        typeof module.startOperatingArtifactGeneration !== 'function' ||
+        typeof module.validateOperatingArtifactOutput !== 'function' ||
+        typeof module.commitOperatingArtifactGeneration !== 'function' ||
+        typeof module.failOperatingArtifactGeneration !== 'function' ||
+        typeof module.resumeOperatingArtifactGeneration !== 'function') {
+        throw new OperateError('E_PIPELINE_NOT_INSTALLED', 'The installed pipeline does not expose the Protocol v1.2 operating artifact generator.');
+    }
+    return module;
+}
+async function walkFiles(root, maximum = 2_000) {
+    const files = [];
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const entry of await readdir(current, { withFileTypes: true }).catch(() => [])) {
+            if (files.length >= maximum) {
+                throw new OperateError('E_OPERATE_PLANNER_CONFLICT', 'Planning producer inspection exceeded its bounded file count.');
+            }
+            const candidate = path.join(current, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new OperateError('E_OPERATE_PATH_ESCAPE', 'Planning targets cannot contain symlinks.');
+            }
+            if (entry.isDirectory())
+                queue.push(candidate);
+            else if (entry.isFile())
+                files.push(candidate);
+        }
+    }
+    return files.sort();
+}
+export async function inspectPlanningProducer(input) {
+    const target = await resolveContainedPath(input.projectRoot, input.targetPath);
+    const present = await access(target).then(() => true, () => false);
+    const files = present
+        ? (await stat(target)).isDirectory()
+            ? await walkFiles(target)
+            : [target]
+        : [];
+    const relativeFiles = files.map((file) => path.relative(input.projectRoot, file).split(path.sep).join('/'));
+    const planningFiles = relativeFiles.filter((file) => /(?:^|\/)(?:stories|tasks)\/.+\.(?:md|feature)$/i.test(file));
+    const producers = new Set();
+    const provenancePath = path.join(input.projectRoot, '.planr', 'provenance.jsonl');
+    const provenance = await readFile(provenancePath, 'utf8').catch(() => '');
+    for (const line of provenance.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event.artifact_path &&
+                (event.artifact_path === input.targetPath ||
+                    event.artifact_path.startsWith(`${input.targetPath.replace(/\/$/, '')}/`))) {
+                if (event.producer?.product === 'planr-pipeline' && event.producer.phase === 'po') {
+                    producers.add('pipeline-po');
+                }
+                else if (event.producer?.product === 'openplanr') {
+                    producers.add('openplanr');
+                }
+            }
+        }
+        catch {
+            // Invalid provenance is diagnosed elsewhere; it cannot prove producer ownership.
+        }
+    }
+    if (producers.size > 1) {
+        throw new OperateError('E_OPERATE_PLANNER_CONFLICT', 'The target contains provenance from more than one planning producer.', { producers: [...producers].sort(), files: relativeFiles });
+    }
+    const producer = [...producers][0];
+    return {
+        populated: planningFiles.length > 0,
+        ...(producer ? { producer } : {}),
+        files: relativeFiles,
+    };
+}
+export async function hasPipelinePoCompletionProvenance(input) {
+    const normalizedTarget = input.targetPath.replace(/\/$/, '');
+    const provenancePath = path.join(input.projectRoot, '.planr', 'provenance.jsonl');
+    const provenance = await readFile(provenancePath, 'utf8').catch(() => '');
+    for (const line of provenance.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const event = JSON.parse(line);
+            const artifactPath = typeof event.artifact_path === 'string' ? event.artifact_path : '';
+            if (event.run_id === input.runId &&
+                event.operation === 'decomposed' &&
+                event.producer?.product === 'planr-pipeline' &&
+                event.producer.phase === 'po' &&
+                (artifactPath === normalizedTarget || artifactPath.startsWith(`${normalizedTarget}/`))) {
+                return true;
+            }
+        }
+        catch {
+            // Invalid provenance cannot prove completion.
+        }
+    }
+    return false;
+}
+export async function assertPlanningProducer(input) {
+    const inspection = await inspectPlanningProducer(input);
+    if (inspection.populated && (!inspection.producer || inspection.producer !== input.selected)) {
+        throw new OperateError('E_OPERATE_PLANNER_CONFLICT', 'The target already contains planning artifacts from another or unknown producer.', {
+            selected: input.selected,
+            existing: inspection.producer ?? 'unknown',
+            files: inspection.files,
+        });
+    }
+}
+export async function preparePipelinePoHandoff(input) {
+    await assertPlanningProducer({
+        projectRoot: input.projectRoot,
+        targetPath: input.targetPath,
+        selected: 'pipeline-po',
+    });
+    const prepared = await input.bridge.preparePlan({
+        projectRoot: input.projectRoot,
+        feature: input.feature,
+        scaffold: false,
+        createStackTemplate: false,
+    });
+    return {
+        planningEngine: 'pipeline-po',
+        feature: input.feature,
+        runId: input.runId,
+        preparedDigest: canonicalDigest(prepared),
+        prepared,
+        invocation: `planr pipeline plan ${JSON.stringify(input.feature)} --runtime ${input.runtime}`,
+        state: 'awaiting-native-plan',
+        shipInvoked: false,
+    };
+}
+export async function completePipelinePoHandoff(input) {
+    if (input.nativePlanCompleted !== true ||
+        canonicalDigest(input.handoff.prepared) !== input.handoff.preparedDigest) {
+        throw new OperateError('E_OPERATE_PLANNER_CONFLICT', 'Pipeline PO completion requires the unchanged prepared handoff and explicit PLAN completion.');
+    }
+    const result = await input.bridge.completePlan({
+        projectRoot: input.projectRoot,
+        feature: input.handoff.feature,
+        runtime: input.runtime,
+        runId: input.handoff.runId,
+    });
+    return {
+        planningEngine: 'pipeline-po',
+        runId: input.handoff.runId,
+        state: 'plan-completed',
+        result,
+        shipInvoked: false,
+    };
+}
+//# sourceMappingURL=pipeline-handoff.js.map

package/dist/services/operate/pipeline-handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-handoff.js","sourceRoot":"","sources":["../../../src/services/operate/pipeline-handoff.ts"],"names":[],"mappings":"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"}

package/dist/services/operate/projection-persistence.d.ts

@@ -0,0 +1,55 @@
+import { type OperatingEventHead, type OperatingState } from './types.js';
+export type OperatingProjectionDriftStatus = 'absent' | 'current' | 'drift';
+export interface OperatingProjectionDrift {
+    path: string;
+    status: OperatingProjectionDriftStatus;
+    expectedDigest: `sha256:${string}`;
+    actualDigest: `sha256:${string}` | null;
+    reason?: string;
+}
+export interface OperatingProjectionFile {
+    relativePath: string;
+    content: string;
+    markerName?: string;
+    managedContent?: string;
+}
+export interface OperatingProjectionPreview {
+    stateDigest: `sha256:${string}`;
+    eventHead: OperatingEventHead;
+    previewDigest: `sha256:${string}`;
+    files: OperatingProjectionFile[];
+    changedPaths: string[];
+    drift: OperatingProjectionDrift[];
+}
+export interface PersistOperatingProjectionResult extends OperatingProjectionPreview {
+    transactionId: string | null;
+}
+export declare function renderOperatingProjectionFiles(state: OperatingState): OperatingProjectionFile[];
+export declare function inspectOperatingProjectionDrift(input: {
+    projectRoot: string;
+    state: OperatingState;
+}): Promise<OperatingProjectionDrift[]>;
+export declare function assertOperatingProjectionsCurrent(input: {
+    projectRoot: string;
+    state: OperatingState;
+}): Promise<void>;
+export declare function prepareOperatingProjectionPersistence(input: {
+    projectRoot: string;
+    state: OperatingState;
+}): Promise<OperatingProjectionPreview>;
+export declare function persistOperatingProjections(input: {
+    projectRoot: string;
+    state: OperatingState;
+    localRoot?: string;
+    transactionId?: string;
+    now?: string;
+    revalidateEventHead?: () => Promise<OperatingEventHead>;
+}): Promise<PersistOperatingProjectionResult>;
+export declare const OPERATING_PROJECTION_PATHS: {
+    readonly state: ".planr/operate/projections/state.json";
+    readonly register: ".planr/operate/projections/register.md";
+    readonly decisions: ".planr/operate/projections/decisions.md";
+    readonly dataGaps: ".planr/operate/projections/data-gaps.md";
+    readonly backlog: ".planr/operate/projections/backlog.md";
+};
+//# sourceMappingURL=projection-persistence.d.ts.map

package/dist/services/operate/projection-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection-persistence.d.ts","sourceRoot":"","sources":["../../../src/services/operate/projection-persistence.ts"],"names":[],"mappings":"AAWA,OAAO,EAAgB,KAAK,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AA4BxF,MAAM,MAAM,8BAA8B,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5E,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,8BAA8B,CAAC;IACvC,cAAc,EAAE,UAAU,MAAM,EAAE,CAAC;IACnC,YAAY,EAAE,UAAU,MAAM,EAAE,GAAG,IAAI,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,UAAU,MAAM,EAAE,CAAC;IAChC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,aAAa,EAAE,UAAU,MAAM,EAAE,CAAC;IAClC,KAAK,EAAE,uBAAuB,EAAE,CAAC;IACjC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,wBAAwB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,gCAAiC,SAAQ,0BAA0B;IAClF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAwQD,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,cAAc,GAAG,uBAAuB,EAAE,CAY/F;AAkED,wBAAsB,+BAA+B,CAAC,KAAK,EAAE;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,CAAC;CACvB,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAItC;AAED,wBAAsB,iCAAiC,CAAC,KAAK,EAAE;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED,wBAAsB,qCAAqC,CAAC,KAAK,EAAE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,CAAC;CACvB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAsDtC;AAED,wBAAsB,2BAA2B,CAAC,KAAK,EAAE;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACzD,GAAG,OAAO,CAAC,gCAAgC,CAAC,CA6B5C;AAED,eAAO,MAAM,0BAA0B;;;;;;CAM7B,CAAC"}

package/dist/services/operate/projection-persistence.js

@@ -0,0 +1,393 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalDigest, canonicalize, sha256Digest } from './canonical.js';
+import { applyJournalTransaction, prepareJournalTransaction, } from './journal.js';
+import { renderOperatingBrief, selectCycleState } from './projection.js';
+import { assertOperatingArtifact } from './protocol.js';
+import { operatingStalledItems } from './stalled-item-service.js';
+import { OperateError } from './types.js';
+const PROJECTION_ROOT = '.planr/operate/projections';
+const STATE_PATH = `${PROJECTION_ROOT}/state.json`;
+const MARKDOWN_PROJECTIONS = [
+    {
+        relativePath: `${PROJECTION_ROOT}/register.md`,
+        markerName: 'operate-findings-register',
+        render: renderFindingRegister,
+    },
+    {
+        relativePath: `${PROJECTION_ROOT}/decisions.md`,
+        markerName: 'operate-decisions-register',
+        render: renderDecisionRegister,
+    },
+    {
+        relativePath: `${PROJECTION_ROOT}/data-gaps.md`,
+        markerName: 'operate-data-gaps-register',
+        render: renderDataGapRegister,
+    },
+    {
+        relativePath: `${PROJECTION_ROOT}/backlog.md`,
+        markerName: 'operate-backlog-register',
+        render: renderBacklogRegister,
+    },
+];
+const CYCLE_BRIEF_MARKER = 'operate-cycle-brief';
+function value(record, key, fallback = '') {
+    const candidate = record[key];
+    if (typeof candidate === 'string' && candidate.trim()) {
+        return candidate.replace(/\s+/g, ' ').trim();
+    }
+    if (typeof candidate === 'number' || typeof candidate === 'boolean') {
+        return String(candidate);
+    }
+    return fallback;
+}
+function markdownCell(candidate, fallback = '—') {
+    const rendered = typeof candidate === 'string' || typeof candidate === 'number' || typeof candidate === 'boolean'
+        ? String(candidate)
+        : fallback;
+    const withoutControls = [...rendered]
+        .filter((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return (codePoint === 9 ||
+            codePoint === 10 ||
+            codePoint === 13 ||
+            (codePoint >= 32 && codePoint !== 127));
+    })
+        .join('');
+    const normalized = withoutControls.replace(/\s+/g, ' ').trim();
+    return (normalized || fallback).replaceAll('\\', '\\\\').replaceAll('|', '\\|');
+}
+function evidenceRefs(record) {
+    if (!Array.isArray(record.evidenceRefs))
+        return '—';
+    const refs = [
+        ...new Set(record.evidenceRefs.filter((entry) => typeof entry === 'string')),
+    ].sort();
+    return refs.length > 0 ? refs.map((entry) => `\`${markdownCell(entry)}\``).join(', ') : '—';
+}
+function generatedHeader(state, title) {
+    return [
+        `# ${title}`,
+        '',
+        '> Generated by `planr operate` from canonical events. Edit operating state through the CLI.',
+        `> Event head: ${state.eventHead.sequence} / ${state.eventHead.hash ?? 'genesis'}`,
+        `> Projection time: ${state.generatedAt}`,
+        '',
+    ];
+}
+function renderFindingRegister(state) {
+    const findings = [...state.findings].sort((left, right) => left.id.localeCompare(right.id));
+    const stalledById = new Map(operatingStalledItems(state).map((item) => [item.id, item.stalledCycles]));
+    return [
+        ...generatedHeader(state, 'Operating Findings Register'),
+        '| Finding | Status | Lane | Owner | Severity | Score | Stalled cycles | Title | Evidence |',
+        '|---|---|---|---|---|---:|---:|---|---|',
+        ...(findings.length > 0
+            ? findings.map((finding) => `| ${markdownCell(finding.id)} | ${markdownCell(finding.status)} | ${markdownCell(finding.lane)} | ${markdownCell(finding.owner)} | ${markdownCell(finding.severity)} | ${markdownCell(finding.score, '0')} | ${markdownCell(stalledById.get(finding.id) ?? 0, '0')} | ${markdownCell(finding.title)} | ${evidenceRefs(finding)} |`)
+            : ['| — | — | — | — | — | 0 | 0 | No findings recorded. | — |']),
+    ].join('\n');
+}
+function renderDecisionRegister(state) {
+    const stalledById = new Map(operatingStalledItems(state).map((item) => [item.id, item.stalledCycles]));
+    const decisions = [...state.decisions].sort((left, right) => {
+        const deadlineDelta = value(left, 'deadline').localeCompare(value(right, 'deadline'));
+        return deadlineDelta || left.id.localeCompare(right.id);
+    });
+    return [
+        ...generatedHeader(state, 'Operating Decisions'),
+        '| Decision | Status | Owner | Deadline | Stalled cycles | Reversibility | Question | Recommendation |',
+        '|---|---|---|---|---:|---|---|---|',
+        ...(decisions.length > 0
+            ? decisions.map((decision) => `| ${markdownCell(decision.id)} | ${markdownCell(decision.status)} | ${markdownCell(decision.owner)} | ${markdownCell(decision.deadline)} | ${markdownCell(stalledById.get(decision.id) ?? 0, '0')} | ${markdownCell(decision.reversibility)} | ${markdownCell(decision.question)} | ${markdownCell(decision.recommendation)} |`)
+            : ['| — | — | — | — | 0 | — | No decisions recorded. | — |']),
+    ].join('\n');
+}
+function renderDataGapRegister(state) {
+    const gaps = [...state.dataGaps].sort((left, right) => left.id.localeCompare(right.id));
+    return [
+        ...generatedHeader(state, 'Operating Data Gaps'),
+        '| Gap | Status | Owner | Question | Reason | Unblocks |',
+        '|---|---|---|---|---|---|',
+        ...(gaps.length > 0
+            ? gaps.map((gap) => {
+                const unblocks = Array.isArray(gap.unblocks)
+                    ? gap.unblocks
+                        .filter((entry) => typeof entry === 'string')
+                        .sort()
+                        .join(', ')
+                    : '';
+                return `| ${markdownCell(gap.id)} | ${markdownCell(gap.status)} | ${markdownCell(gap.owner)} | ${markdownCell(gap.question)} | ${markdownCell(gap.reason)} | ${markdownCell(unblocks)} |`;
+            })
+            : ['| — | — | — | No data gaps recorded. | — | — |']),
+    ].join('\n');
+}
+function renderBacklogRegister(state) {
+    const parked = state.findings
+        .filter((finding) => finding.parked === true)
+        .sort((left, right) => {
+        const scoreDelta = Number(right.score ?? 0) - Number(left.score ?? 0);
+        return scoreDelta || left.id.localeCompare(right.id);
+    });
+    return [
+        ...generatedHeader(state, 'Operating Backlog'),
+        '| Finding | Status | Owner | Score | Title | Parked reason | Evidence |',
+        '|---|---|---|---:|---|---|---|',
+        ...(parked.length > 0
+            ? parked.map((finding) => `| ${markdownCell(finding.id)} | ${markdownCell(finding.status)} | ${markdownCell(finding.owner)} | ${markdownCell(finding.score, '0')} | ${markdownCell(finding.title)} | ${markdownCell(finding.problem ?? finding.proposal, 'Deprioritized by the current attention cap.')} | ${evidenceRefs(finding)} |`)
+            : ['| — | — | — | 0 | No parked findings. | — | — |']),
+    ].join('\n');
+}
+function renderCycleBrief(state, cycleId) {
+    const selected = selectCycleState(state, cycleId);
+    const brief = renderOperatingBrief(selected);
+    const words = brief.split(/\s+/).filter(Boolean);
+    if (words.length > 900) {
+        throw new OperateError('E_OPERATE_PROJECTION_DRIFT', `Cycle brief ${cycleId} exceeds the 900-word projection limit.`, { cycleId, words: words.length });
+    }
+    return brief;
+}
+function markerExpression(markerName, edge) {
+    const escaped = markerName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return edge === 'begin'
+        ? new RegExp(`^<!--\\s*##planr-${escaped}:begin##[^>]*-->[\\t ]*(?:\\r?\\n|$)`, 'gm')
+        : new RegExp(`^<!--\\s*##planr-${escaped}:end##\\s*-->[\\t ]*`, 'gm');
+}
+function managedSection(content, markerName) {
+    const beginMatches = [...content.matchAll(markerExpression(markerName, 'begin'))];
+    const endMatches = [...content.matchAll(markerExpression(markerName, 'end'))];
+    if (beginMatches.length === 0 && endMatches.length === 0)
+        return null;
+    if (beginMatches.length !== 1 || endMatches.length !== 1) {
+        return { content: '', malformed: true };
+    }
+    const begin = beginMatches[0];
+    const end = endMatches[0];
+    const beginEnd = (begin.index ?? 0) + begin[0].length;
+    const endStart = end.index ?? 0;
+    if (endStart < beginEnd)
+        return { content: '', malformed: true };
+    return {
+        content: content.slice(beginEnd, endStart).trimEnd(),
+        malformed: false,
+    };
+}
+function beginMarker(markerName) {
+    return `<!-- ##planr-${markerName}:begin## (managed by planr CLI; preserve hand-edits outside this block) -->`;
+}
+function endMarker(markerName) {
+    return `<!-- ##planr-${markerName}:end## -->`;
+}
+function spliceProjectionBlock(existing, markerName, managedContent) {
+    const beginMatches = [...existing.matchAll(markerExpression(markerName, 'begin'))];
+    const endMatches = [...existing.matchAll(markerExpression(markerName, 'end'))];
+    const block = [beginMarker(markerName), managedContent.trimEnd(), endMarker(markerName)].join('\n');
+    if (beginMatches.length === 0 && endMatches.length === 0) {
+        if (existing.length === 0)
+            return `${block}\n`;
+        const separator = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+        return `${existing}${separator}${block}\n`;
+    }
+    if (beginMatches.length !== 1 || endMatches.length !== 1) {
+        throw new OperateError('E_OPERATE_PROJECTION_DRIFT', `Projection markers for ${markerName} are malformed or duplicated.`, { markerName });
+    }
+    const begin = beginMatches[0];
+    const end = endMatches[0];
+    const beginStart = begin.index ?? 0;
+    const endStart = end.index ?? 0;
+    if (endStart < beginStart + begin[0].length) {
+        throw new OperateError('E_OPERATE_PROJECTION_DRIFT', `Projection markers for ${markerName} are out of order.`, { markerName });
+    }
+    const afterStart = endStart + end[0].length;
+    return `${existing.slice(0, beginStart)}${block}${existing.slice(afterStart)}`;
+}
+function markdownProjectionSpecs(state) {
+    const registers = MARKDOWN_PROJECTIONS.map((projection) => ({
+        relativePath: projection.relativePath,
+        markerName: projection.markerName,
+        managedContent: projection.render(state),
+    }));
+    const briefs = [...state.cycles]
+        .filter((cycle) => cycle.state === 'reviewable' || cycle.state === 'closed')
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map((cycle) => ({
+        relativePath: `.planr/operate/cycles/${cycle.id}/brief.md`,
+        markerName: CYCLE_BRIEF_MARKER,
+        managedContent: renderCycleBrief(state, cycle.id),
+    }));
+    return [...registers, ...briefs];
+}
+export function renderOperatingProjectionFiles(state) {
+    const stateFile = {
+        relativePath: STATE_PATH,
+        content: `${canonicalize(state)}\n`,
+    };
+    const markdownFiles = markdownProjectionSpecs(state).map((projection) => ({
+        relativePath: projection.relativePath,
+        markerName: projection.markerName,
+        managedContent: projection.managedContent,
+        content: spliceProjectionBlock('', projection.markerName, projection.managedContent),
+    }));
+    return [stateFile, ...markdownFiles];
+}
+async function inspectProjectionFile(projectRoot, expected) {
+    const expectedBytes = expected.markerName ? (expected.managedContent ?? '') : expected.content;
+    const expectedDigest = sha256Digest(expectedBytes);
+    const current = await readFile(path.join(projectRoot, expected.relativePath), 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (current === null) {
+        return {
+            path: expected.relativePath,
+            status: 'absent',
+            expectedDigest,
+            actualDigest: null,
+            reason: 'Projection has not been generated.',
+        };
+    }
+    if (!expected.markerName) {
+        const actualDigest = sha256Digest(current);
+        return actualDigest === expectedDigest
+            ? { path: expected.relativePath, status: 'current', expectedDigest, actualDigest }
+            : {
+                path: expected.relativePath,
+                status: 'drift',
+                expectedDigest,
+                actualDigest,
+                reason: 'Canonical JSON bytes differ from event replay.',
+            };
+    }
+    const section = managedSection(current, expected.markerName);
+    if (!section) {
+        return {
+            path: expected.relativePath,
+            status: 'drift',
+            expectedDigest,
+            actualDigest: sha256Digest(current),
+            reason: 'Managed projection markers are missing.',
+        };
+    }
+    if (section.malformed) {
+        return {
+            path: expected.relativePath,
+            status: 'drift',
+            expectedDigest,
+            actualDigest: sha256Digest(current),
+            reason: 'Managed projection markers are malformed or duplicated.',
+        };
+    }
+    const actualDigest = sha256Digest(section.content);
+    return actualDigest === expectedDigest
+        ? { path: expected.relativePath, status: 'current', expectedDigest, actualDigest }
+        : {
+            path: expected.relativePath,
+            status: 'drift',
+            expectedDigest,
+            actualDigest,
+            reason: 'Generated projection rows differ from event replay.',
+        };
+}
+export async function inspectOperatingProjectionDrift(input) {
+    await assertOperatingArtifact('operating-state', input.state);
+    const expected = renderOperatingProjectionFiles(input.state);
+    return Promise.all(expected.map((file) => inspectProjectionFile(input.projectRoot, file)));
+}
+export async function assertOperatingProjectionsCurrent(input) {
+    const drift = await inspectOperatingProjectionDrift(input);
+    const mismatches = drift.filter((entry) => entry.status !== 'current');
+    if (mismatches.length > 0) {
+        throw new OperateError('E_OPERATE_PROJECTION_DRIFT', `${mismatches.length} Operating Board projection(s) differ from event replay.`, { projections: mismatches });
+    }
+}
+export async function prepareOperatingProjectionPersistence(input) {
+    await assertOperatingArtifact('operating-state', input.state);
+    const rendered = renderOperatingProjectionFiles(input.state);
+    const files = [];
+    for (const file of rendered) {
+        if (!file.markerName) {
+            files.push(file);
+            continue;
+        }
+        const current = await readFile(path.join(input.projectRoot, file.relativePath), 'utf8').catch((error) => {
+            if (error.code === 'ENOENT')
+                return '';
+            throw error;
+        });
+        files.push({
+            ...file,
+            content: spliceProjectionBlock(current, file.markerName, file.managedContent ?? ''),
+        });
+    }
+    const changedPaths = [];
+    for (const file of files) {
+        const current = await readFile(path.join(input.projectRoot, file.relativePath)).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (current === null || sha256Digest(current) !== sha256Digest(file.content)) {
+            changedPaths.push(file.relativePath);
+        }
+    }
+    const drift = await inspectOperatingProjectionDrift(input);
+    const stateDigest = canonicalDigest(input.state);
+    const previewDigest = canonicalDigest({
+        kind: 'operating-projection-preview',
+        stateDigest,
+        eventHead: input.state.eventHead,
+        writes: files
+            .filter((file) => changedPaths.includes(file.relativePath))
+            .map((file) => ({
+            path: file.relativePath,
+            digest: sha256Digest(file.content),
+        }))
+            .sort((left, right) => left.path.localeCompare(right.path)),
+    });
+    return {
+        stateDigest,
+        eventHead: structuredClone(input.state.eventHead),
+        previewDigest,
+        files,
+        changedPaths,
+        drift,
+    };
+}
+export async function persistOperatingProjections(input) {
+    const preview = await prepareOperatingProjectionPersistence(input);
+    if (preview.changedPaths.length === 0) {
+        return { ...preview, transactionId: null };
+    }
+    const changed = new Set(preview.changedPaths);
+    const writes = preview.files
+        .filter((file) => changed.has(file.relativePath))
+        .map((file) => ({
+        relativePath: file.relativePath,
+        content: file.content,
+        mode: '0600',
+    }));
+    const transaction = await prepareJournalTransaction(input.projectRoot, {
+        writes,
+        eventHead: preview.eventHead,
+        previewDigest: preview.previewDigest,
+        localRoot: input.localRoot,
+        transactionId: input.transactionId,
+        now: input.now,
+    });
+    await applyJournalTransaction(input.projectRoot, transaction, {
+        currentEventHead: preview.eventHead,
+        revalidateEventHead: input.revalidateEventHead,
+    });
+    return {
+        ...preview,
+        transactionId: transaction.record.transactionId,
+    };
+}
+export const OPERATING_PROJECTION_PATHS = {
+    state: STATE_PATH,
+    register: `${PROJECTION_ROOT}/register.md`,
+    decisions: `${PROJECTION_ROOT}/decisions.md`,
+    dataGaps: `${PROJECTION_ROOT}/data-gaps.md`,
+    backlog: `${PROJECTION_ROOT}/backlog.md`,
+};
+//# sourceMappingURL=projection-persistence.js.map