@ornexus/neocortex 4.60.71 → 4.60.73

package/packages/client/dist/git/epic-operational-state.js

@@ -0,0 +1,672 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, fsyncSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { GIT_LIFECYCLE_RUNTIME_DIRECTORY, mutateGitLifecycleRuntime, readGitLifecycleRuntime, readGitLifecycleRuntimeSync, } from './git-lifecycle-store.js';
+export const EPIC_OPERATIONAL_SOURCE_LIMIT_BYTES = 4 * 1024 * 1024;
+export const EPIC_OPERATIONAL_PAYLOAD_LIMIT_BYTES = 1024 * 1024;
+export const EPIC_OPERATIONAL_RECEIPT_CAP = 64;
+export const EPIC_OPERATIONAL_IDENTITY_CAP = 2_048;
+const HASH = /^[a-f0-9]{64}$/;
+const ID = /^P[1-9][0-9]*(?:\.[0-9]+)*$/;
+const SAFE_TOKEN = /^[A-Za-z0-9._:/#\-[\]]{1,240}$/;
+export function epicOperationalCanonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(epicOperationalCanonicalJson).join(',')}]`;
+    return `{${Object.entries(value)
+        .filter(([, child]) => child !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => `${JSON.stringify(key)}:${epicOperationalCanonicalJson(child)}`)
+        .join(',')}}`;
+}
+export function epicOperationalHash(domain, value) {
+    return createHash('sha256').update(`${domain}\0${epicOperationalCanonicalJson(value)}`).digest('hex');
+}
+export function deriveEpicOperationalRepositoryFingerprint(projectRoot) {
+    const canonicalRoot = realpathSync(resolve(projectRoot));
+    const raw = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+        cwd: canonicalRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const absolute = isAbsolute(raw) ? resolve(raw) : resolve(canonicalRoot, raw);
+    const commonDir = realpathSync(absolute);
+    if (commonDir !== absolute)
+        throw new Error('epic-operational-path-unsafe');
+    const info = lstatSync(commonDir);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error('epic-operational-path-unsafe');
+    return epicOperationalHash('p224-epic-operational-repository-v1', {
+        commonDir,
+        dev: Number(info.dev),
+        ino: Number(info.ino),
+    });
+}
+export function createEpicOperationalIdentity(projectRoot, input) {
+    const repositoryFingerprint = deriveEpicOperationalRepositoryFingerprint(projectRoot);
+    const base = {
+        schemaVersion: 'EpicOperationalIdentity/1.0',
+        epicId: input.epicId,
+        executionBranch: input.executionBranch,
+        graphRevision: input.graphRevision,
+        originBindingDigest: input.originBindingDigest,
+        repositoryFingerprint,
+    };
+    const identity = Object.freeze({
+        ...base,
+        identityHash: epicOperationalHash('p224-epic-operational-identity-v1', base),
+    });
+    assertEpicOperationalIdentity(identity);
+    return identity;
+}
+export function createInitialEpicOperationalState(input) {
+    const value = {
+        schemaVersion: 'EpicOperationalState/1.0',
+        repositoryFingerprint: input.identity.repositoryFingerprint,
+        writerEpoch: 1,
+        capabilities: ['epic-operational-state-v1', 'epic-lifecycle-backfill-v1'],
+        identities: { [input.identity.identityHash]: input.identity },
+        yoloop: { schemaVersion: 'CommonYoloopAuthority/1.0', ...input.yoloop },
+        projectionBindings: {
+            schemaVersion: 'EpicOperationalProjectionBindings/1.0',
+            trackedState: {
+                status: 'bound',
+                sourceDigest: input.trackedStateDigest,
+                authorityRevision: 0,
+                reasonCodes: ['epic-operational-tracked-state-bound'],
+            },
+            sqlite: {
+                status: input.sqliteStatus ?? 'unbound',
+                sourceDigest: null,
+                authorityRevision: 0,
+                reasonCodes: input.sqliteReasonCodes ?? ['epic-operational-projection-unbound'],
+            },
+        },
+        activeJournal: null,
+        backfillReceipts: [],
+        reconciliationReceipts: [],
+        rollbackReceipts: [],
+    };
+    assertEpicOperationalState(value);
+    return Object.freeze(value);
+}
+export function assertEpicOperationalState(value) {
+    const item = record(value);
+    if (!item)
+        throw new Error('epic-operational-store-corrupt');
+    exact(item, [
+        'schemaVersion', 'repositoryFingerprint', 'writerEpoch', 'capabilities',
+        'identities', 'yoloop', 'projectionBindings', 'activeJournal',
+        'backfillReceipts', 'reconciliationReceipts', 'rollbackReceipts',
+    ]);
+    const identities = record(item.identities);
+    const yoloop = record(item.yoloop);
+    const bindings = record(item.projectionBindings);
+    if (item.schemaVersion !== 'EpicOperationalState/1.0' || !hash(item.repositoryFingerprint)
+        || !Number.isSafeInteger(item.writerEpoch) || Number(item.writerEpoch) < 1
+        || !Array.isArray(item.capabilities)
+        || !sameStringSet(item.capabilities, ['epic-operational-state-v1', 'epic-lifecycle-backfill-v1'])
+        || !identities || Object.keys(identities).length > EPIC_OPERATIONAL_IDENTITY_CAP
+        || !yoloop || !hasExactKeys(yoloop, ['schemaVersion', 'lock', 'state', 'capabilities'])
+        || yoloop.schemaVersion !== 'CommonYoloopAuthority/1.0'
+        || !record(yoloop.state) || !(yoloop.lock === null || record(yoloop.lock))
+        || !Array.isArray(yoloop.capabilities) || yoloop.capabilities.length > 16
+        || new Set(yoloop.capabilities).size !== yoloop.capabilities.length
+        || yoloop.capabilities.some((capability) => ![
+            'rollover-session-v1', 'successor-transition-v1', 'continuation-replan-v1',
+            'cross-epic-continuation-reconcile-v1',
+        ].includes(String(capability)))
+        || !bindings || !hasExactKeys(bindings, ['schemaVersion', 'trackedState', 'sqlite'])
+        || bindings.schemaVersion !== 'EpicOperationalProjectionBindings/1.0'
+        || !validProjectionBinding(bindings.trackedState) || !validProjectionBinding(bindings.sqlite)
+        || !(item.activeJournal === null || validJournal(item.activeJournal))
+        || !boundedReceipts(item.backfillReceipts, 'EpicLifecycleBackfillReceipt/1.0')
+        || !boundedReceipts(item.reconciliationReceipts, 'YoloopCrossEpicReconciliationReceipt/1.0')
+        || !boundedReceipts(item.rollbackReceipts, 'EpicOperationalRollbackReceipt/1.0')) {
+        throw new Error('epic-operational-store-corrupt');
+    }
+    for (const [identityHash, identity] of Object.entries(identities)) {
+        assertEpicOperationalIdentity(identity);
+        if (identityHash !== identity.identityHash || identity.repositoryFingerprint !== item.repositoryFingerprint) {
+            throw new Error('epic-operational-identity-mismatch');
+        }
+    }
+    if (Buffer.byteLength(epicOperationalCanonicalJson(item), 'utf8') > EPIC_OPERATIONAL_SOURCE_LIMIT_BYTES) {
+        throw new Error('epic-operational-source-oversized');
+    }
+}
+export function readEpicOperationalState(projectRoot, context) {
+    const document = readGitLifecycleRuntimeSync(projectRoot, { required: true });
+    if (document.schemaVersion !== 2 || document.operational === undefined) {
+        throw new Error('epic-operational-store-missing');
+    }
+    assertEpicOperationalState(document.operational);
+    assertOperationalContext(document, document.operational, context);
+    return { document, operational: document.operational };
+}
+export async function mutateEpicOperationalState(projectRoot, context, mutate) {
+    try {
+        return await mutateGitLifecycleRuntime(projectRoot, (document) => {
+            if (document.schemaVersion !== 2 || document.operational === undefined) {
+                throw new Error('epic-operational-store-missing');
+            }
+            assertEpicOperationalState(document.operational);
+            assertOperationalContext(document, document.operational, context);
+            return mutate(document.operational, document);
+        }, { expectedRevision: context.expectedRevision });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'git-lifecycle-runtime-revision-conflict') {
+            throw new Error('epic-operational-revision-conflict');
+        }
+        throw error;
+    }
+}
+export function projectEpicOperationalState(document, identityHash) {
+    if (document.schemaVersion !== 2 || document.operational === undefined) {
+        throw new Error('epic-operational-store-missing');
+    }
+    assertEpicOperationalState(document.operational);
+    const state = document.operational;
+    const identity = state.identities[identityHash];
+    if (!identity)
+        throw new Error('epic-operational-identity-mismatch');
+    const run = record(state.yoloop.state.runControl);
+    const pending = state.yoloop.state.pendingContinuationAuthorities ?? [];
+    return Object.freeze({
+        schemaVersion: 'EpicOperationalPublicProjection/1.0',
+        repositoryFingerprint: state.repositoryFingerprint,
+        identityHash,
+        epicId: identity.epicId,
+        executionBranch: identity.executionBranch,
+        graphRevision: identity.graphRevision,
+        storeRevision: document.revision,
+        writerEpoch: state.writerEpoch,
+        runId: typeof run?.runId === 'string' ? run.runId : null,
+        runStatus: typeof run?.status === 'string' ? run.status : null,
+        runRevision: Number.isSafeInteger(run?.revision) ? Number(run.revision) : null,
+        snapshotHash: run?.latestSnapshotHash === null || hash(run?.latestSnapshotHash)
+            ? run?.latestSnapshotHash : null,
+        continuationSessionHash: epicOperationalHash('p224-common-continuation-session-v1', state.yoloop.state.continuationSession ?? null),
+        pendingAuthorityHash: epicOperationalHash('p224-common-pending-authorities-v1', pending),
+        pendingAuthorityCount: pending.length,
+        lockActive: state.yoloop.lock !== null,
+        currentSessionActive: state.yoloop.state.currentSession !== null,
+        journalActive: state.activeJournal !== null,
+        reasonCodes: ['epic-operational-projection-bounded'],
+        publicSafe: true,
+    });
+}
+export function classifyCrossEpicContinuationReconciliation(input) {
+    let projection;
+    try {
+        projection = projectEpicOperationalState(input.document, input.targetIdentityHash);
+    }
+    catch (error) {
+        return { kind: 'blocked', reasonCodes: [publicOperationalReason(error)] };
+    }
+    const operational = input.document.operational;
+    const targetIdentity = operational.identities[input.targetIdentityHash];
+    const session = record(operational.yoloop.state.continuationSession);
+    if (!session)
+        return { kind: 'not-applicable', reasonCodes: ['yoloop-cross-epic-session-missing'] };
+    const sourceEpicId = typeof session.epicId === 'string' ? session.epicId : '';
+    const sourceGraphRevision = typeof session.graphFingerprint === 'string' ? session.graphFingerprint : '';
+    if (sourceEpicId === input.targetEpicId && sourceGraphRevision === input.targetGraphRevision) {
+        return { kind: 'not-applicable', reasonCodes: ['yoloop-cross-epic-target-unchanged'] };
+    }
+    const reasons = [];
+    const run = record(operational.yoloop.state.runControl);
+    const pending = operational.yoloop.state.pendingContinuationAuthorities ?? [];
+    if (!targetIdentity || targetIdentity.epicId !== input.targetEpicId
+        || targetIdentity.graphRevision !== input.targetGraphRevision)
+        reasons.push('epic-operational-identity-mismatch');
+    if (!operational.yoloop.capabilities.includes('cross-epic-continuation-reconcile-v1'))
+        reasons.push('yoloop-cross-epic-capability-missing');
+    if (!run || !['success', 'exhausted'].includes(String(run.status)))
+        reasons.push('yoloop-cross-epic-predecessor-active');
+    if (operational.yoloop.lock !== null || operational.yoloop.state.currentSession !== null
+        || input.legacyActivity !== 'inactive')
+        reasons.push('yoloop-cross-epic-lock-active');
+    if (operational.activeJournal !== null)
+        reasons.push('epic-operational-journal-conflict');
+    if (operational.reconciliationReceipts.length >= EPIC_OPERATIONAL_RECEIPT_CAP)
+        reasons.push('yoloop-cross-epic-receipt-capacity');
+    if (pending.length > 1)
+        reasons.push('yoloop-cross-epic-authority-ambiguous');
+    if (pending.length === 1) {
+        const authority = record(pending[0]);
+        const certificate = record(authority?.certificate);
+        if (!authority || !certificate || authority.sessionId !== session.sessionId
+            || certificate.sessionId !== session.sessionId)
+            reasons.push('yoloop-cross-epic-authority-ambiguous');
+        else if (authority.delegated !== false)
+            reasons.push('yoloop-cross-epic-authority-delegated');
+    }
+    if (!hash(sourceGraphRevision) || !hash(session.sessionId)
+        || projection.runId === null || projection.runRevision === null)
+        reasons.push('yoloop-cross-epic-state-corrupt');
+    if (reasons.length > 0)
+        return { kind: 'blocked', reasonCodes: [...new Set(reasons)] };
+    return {
+        kind: 'eligible',
+        evidence: Object.freeze({
+            ...projection,
+            schemaVersion: 'YoloopCrossEpicReconciliationEvidence/1.0',
+            sourceEpicId,
+            sourceGraphRevision,
+            targetEpicId: input.targetEpicId,
+            targetGraphRevision: input.targetGraphRevision,
+            decision: 'eligible',
+        }),
+    };
+}
+export function buildCrossEpicContinuationPayloadHash(payload) {
+    return epicOperationalHash('p224-cross-epic-continuation-reconcile-v1', payload);
+}
+export async function applyCrossEpicContinuationReconciliation(projectRoot, operation) {
+    validateCrossEpicOperation(operation);
+    let current = await readGitLifecycleRuntime(projectRoot, { required: true });
+    if (current.schemaVersion !== 2 || current.operational === undefined)
+        throw new Error('epic-operational-store-missing');
+    assertEpicOperationalState(current.operational);
+    let operational = current.operational;
+    const expectedReceipt = crossEpicReceipt(operation);
+    const replay = operational.reconciliationReceipts.find((receipt) => receipt.operationId === operation.operationId || receipt.idempotencyKey === operation.idempotencyKey);
+    if (replay) {
+        if (epicOperationalCanonicalJson(replay) !== epicOperationalCanonicalJson(expectedReceipt)
+            || epicOperationalHash('p224-common-continuation-session-v1', operational.yoloop.state.continuationSession ?? null)
+                !== operation.nextSessionHash
+            || (operational.yoloop.state.pendingContinuationAuthorities?.length ?? 0) !== 0) {
+            throw new Error('yoloop-cross-epic-replay-conflict');
+        }
+        return { applied: false, replay: true, receipt: replay };
+    }
+    if (operational.reconciliationReceipts.length >= EPIC_OPERATIONAL_RECEIPT_CAP) {
+        throw new Error('yoloop-cross-epic-receipt-capacity');
+    }
+    const existingJournal = operational.activeJournal;
+    if (existingJournal && (existingJournal.operationId !== operation.operationId
+        || existingJournal.idempotencyKey !== operation.idempotencyKey
+        || existingJournal.payloadHash !== operation.payloadHash)) {
+        throw new Error('epic-operational-journal-conflict');
+    }
+    if (!existingJournal)
+        assertCrossEpicPreimage(current, operational, operation);
+    const backup = existingJournal
+        ? verifyOperationalBackup(projectRoot, existingJournal.backupManifestRef, existingJournal.preimageDigest)
+        : persistOperationalBackup(projectRoot, operation.operationId, operational);
+    if (!existingJournal) {
+        const journal = crossEpicJournal(operation, backup.digest, backup.ref, 'prepared');
+        const result = await mutateEpicOperationalState(projectRoot, {
+            identityHash: operation.expectedIdentityHash,
+            expectedRevision: current.revision,
+            expectedWriterEpoch: operation.expectedWriterEpoch,
+        }, (state) => {
+            state.activeJournal = journal;
+        });
+        current = result.document;
+        operational = current.operational;
+    }
+    if (operational.activeJournal?.phase === 'prepared') {
+        assertCrossEpicPreimage(current, operational, operation, true);
+        const nextState = {
+            ...operational.yoloop.state,
+            continuationSession: operation.nextSession,
+            pendingContinuationAuthorities: [],
+        };
+        const result = await mutateEpicOperationalState(projectRoot, {
+            identityHash: operation.expectedIdentityHash,
+            expectedRevision: current.revision,
+            expectedWriterEpoch: operation.expectedWriterEpoch,
+        }, (state) => {
+            state.yoloop = { ...state.yoloop, state: nextState };
+            state.activeJournal = {
+                ...state.activeJournal, phase: 'authority-applied',
+            };
+        });
+        current = result.document;
+        operational = current.operational;
+    }
+    if (operational.activeJournal?.phase === 'authority-applied') {
+        const result = await mutateEpicOperationalState(projectRoot, {
+            identityHash: operation.expectedIdentityHash,
+            expectedRevision: current.revision,
+            expectedWriterEpoch: operation.expectedWriterEpoch,
+        }, (state) => {
+            state.activeJournal = {
+                ...state.activeJournal, phase: 'projections-applied',
+                projectionStatuses: { trackedState: 'not-applicable', sqlite: 'not-applicable' },
+            };
+        });
+        current = result.document;
+        operational = current.operational;
+    }
+    if (operational.activeJournal?.phase !== 'projections-applied') {
+        throw new Error('epic-operational-journal-corrupt');
+    }
+    const result = await mutateEpicOperationalState(projectRoot, {
+        identityHash: operation.expectedIdentityHash,
+        expectedRevision: current.revision,
+        expectedWriterEpoch: operation.expectedWriterEpoch,
+    }, (state) => {
+        if (state.reconciliationReceipts.length >= EPIC_OPERATIONAL_RECEIPT_CAP) {
+            throw new Error('yoloop-cross-epic-receipt-capacity');
+        }
+        state.reconciliationReceipts = [
+            ...state.reconciliationReceipts,
+            expectedReceipt,
+        ];
+        state.activeJournal = null;
+    });
+    assertEpicOperationalState(result.document.operational);
+    return { applied: true, replay: false, receipt: expectedReceipt };
+}
+function assertCrossEpicPreimage(document, state, operation, allowPrepared = false) {
+    const run = record(state.yoloop.state.runControl);
+    const pending = state.yoloop.state.pendingContinuationAuthorities ?? [];
+    const identity = state.identities[operation.expectedIdentityHash];
+    const session = record(state.yoloop.state.continuationSession);
+    if ((document.revision !== operation.expectedCommonRevision && !allowPrepared)
+        || state.writerEpoch !== operation.expectedWriterEpoch
+        || !identity || identity.epicId !== operation.targetEpicId
+        || identity.graphRevision !== operation.targetGraphRevision
+        || !state.yoloop.capabilities.includes('cross-epic-continuation-reconcile-v1')
+        || state.yoloop.lock !== null || state.yoloop.state.currentSession !== null
+        || !run || run.runId !== operation.expectedRunId || run.status !== operation.expectedRunStatus
+        || run.revision !== operation.expectedRunRevision
+        || (run.latestSnapshotHash ?? null) !== operation.expectedSnapshotHash
+        || !session || session.epicId !== operation.sourceEpicId
+        || session.graphFingerprint !== operation.sourceGraphRevision
+        || session.sessionId !== operation.sourceSessionId
+        || epicOperationalHash('p224-common-continuation-session-v1', state.yoloop.state.continuationSession ?? null)
+            !== operation.expectedSessionHash
+        || epicOperationalHash('p224-common-pending-authorities-v1', pending) !== operation.expectedPendingHash
+        || pending.length !== operation.expectedPendingCount) {
+        throw new Error('yoloop-cross-epic-revision-conflict');
+    }
+    if (pending.length > 1 || pending.some((entry) => {
+        const authority = record(entry);
+        const certificate = record(authority?.certificate);
+        return !authority || authority.delegated !== false || !certificate
+            || authority.sessionId !== operation.sourceSessionId
+            || certificate.sessionId !== operation.sourceSessionId;
+    }))
+        throw new Error('yoloop-cross-epic-authority-ambiguous');
+}
+function crossEpicReceipt(operation) {
+    return Object.freeze({
+        schemaVersion: 'YoloopCrossEpicReconciliationReceipt/1.0',
+        operationId: operation.operationId,
+        idempotencyKey: operation.idempotencyKey,
+        payloadHash: operation.payloadHash,
+        sourceEpicId: operation.sourceEpicId,
+        sourceGraphRevision: operation.sourceGraphRevision,
+        targetEpicId: operation.targetEpicId,
+        targetGraphRevision: operation.targetGraphRevision,
+        runId: operation.expectedRunId,
+        previousSessionHash: operation.expectedSessionHash,
+        nextSessionHash: operation.nextSessionHash,
+        retiredAuthorityHash: operation.expectedPendingHash,
+        retiredAuthorityCount: operation.expectedPendingCount,
+        outcome: 'cross-epic-reconciled',
+        publicSafe: true,
+    });
+}
+function crossEpicJournal(operation, preimageDigest, backupManifestRef, phase) {
+    return {
+        schemaVersion: 'EpicOperationalJournal/1.0',
+        kind: 'cross-epic-reconcile',
+        operationId: operation.operationId,
+        idempotencyKey: operation.idempotencyKey,
+        payloadHash: operation.payloadHash,
+        identityHash: operation.expectedIdentityHash,
+        expectedRevision: operation.expectedCommonRevision,
+        expectedWriterEpoch: operation.expectedWriterEpoch,
+        preimageDigest,
+        backupManifestRef,
+        phase,
+        projectionStatuses: { trackedState: 'not-applicable', sqlite: 'not-applicable' },
+        reasonCodes: ['epic-operational-backup-verified'],
+    };
+}
+function validateCrossEpicOperation(operation) {
+    const { type: _type, payloadHash: _payloadHash, receipt: _receipt, ...payload } = operation;
+    const nextSession = record(operation.nextSession);
+    if (!safeOperationId(operation.operationId) || !safeOperationId(operation.idempotencyKey)
+        || buildCrossEpicContinuationPayloadHash(payload) !== operation.payloadHash
+        || Buffer.byteLength(epicOperationalCanonicalJson(payload), 'utf8') > EPIC_OPERATIONAL_PAYLOAD_LIMIT_BYTES
+        || operation.expectedPendingCount < 0 || operation.expectedPendingCount > 1
+        || !nextSession || nextSession.epicId !== operation.targetEpicId
+        || nextSession.graphFingerprint !== operation.targetGraphRevision
+        || !hash(nextSession.sessionId)
+        || operation.nextSessionHash !== epicOperationalHash('p224-common-continuation-session-v1', operation.nextSession)
+        || epicOperationalCanonicalJson(operation.receipt) !== epicOperationalCanonicalJson(crossEpicReceipt(operation))) {
+        throw new Error('yoloop-cross-epic-replay-conflict');
+    }
+}
+function persistOperationalBackup(projectRoot, operationId, operational) {
+    if (!safeOperationId(operationId))
+        throw new Error('epic-operational-backup-failed');
+    const canonicalRoot = realpathSync(resolve(projectRoot));
+    const rawCommon = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: canonicalRoot, encoding: 'utf8' }).trim();
+    const commonDir = realpathSync(isAbsolute(rawCommon) ? resolve(rawCommon) : resolve(canonicalRoot, rawCommon));
+    const runtimeDir = join(commonDir, GIT_LIFECYCLE_RUNTIME_DIRECTORY);
+    const backupsDir = join(runtimeDir, 'backups');
+    assertPrivateDirectory(runtimeDir, commonDir);
+    if (!existsSync(backupsDir))
+        mkdirSync(backupsDir, { mode: 0o700 });
+    assertPrivateDirectory(backupsDir, runtimeDir);
+    const name = `${operationId}.operational.json`;
+    const path = join(backupsDir, name);
+    const raw = `${JSON.stringify(operational, null, 2)}\n`;
+    const digest = createHash('sha256').update(raw).digest('hex');
+    if (existsSync(path)) {
+        const info = lstatSync(path);
+        if (!info.isFile() || info.isSymbolicLink()
+            || createHash('sha256').update(readFileSync(path)).digest('hex') !== digest) {
+            throw new Error('epic-operational-backup-failed');
+        }
+    }
+    else {
+        const fd = openSync(path, 'wx', 0o600);
+        try {
+            writeFileSync(fd, raw);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        const directoryFd = openSync(backupsDir, 'r');
+        try {
+            fsyncSync(directoryFd);
+        }
+        finally {
+            closeSync(directoryFd);
+        }
+    }
+    return { ref: `backups/${name}`, digest };
+}
+function verifyOperationalBackup(projectRoot, backupRef, expectedDigest) {
+    if (!/^backups\/[A-Za-z0-9._-]{1,240}$/.test(backupRef) || !hash(expectedDigest)) {
+        throw new Error('epic-operational-backup-failed');
+    }
+    const canonicalRoot = realpathSync(resolve(projectRoot));
+    const rawCommon = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+        cwd: canonicalRoot,
+        encoding: 'utf8',
+    }).trim();
+    const commonDir = realpathSync(isAbsolute(rawCommon) ? resolve(rawCommon) : resolve(canonicalRoot, rawCommon));
+    const runtimeDir = join(commonDir, GIT_LIFECYCLE_RUNTIME_DIRECTORY);
+    const path = join(runtimeDir, backupRef);
+    assertPrivateDirectory(runtimeDir, commonDir);
+    const info = lstatSync(path);
+    if (!info.isFile() || info.isSymbolicLink()
+        || createHash('sha256').update(readFileSync(path)).digest('hex') !== expectedDigest) {
+        throw new Error('epic-operational-backup-failed');
+    }
+    return { ref: backupRef, digest: expectedDigest };
+}
+function assertPrivateDirectory(path, parent) {
+    const canonicalParent = realpathSync(parent);
+    if (relative(canonicalParent, resolve(path)).startsWith('..'))
+        throw new Error('epic-operational-path-unsafe');
+    const info = lstatSync(path);
+    if (!info.isDirectory() || info.isSymbolicLink() || realpathSync(path) !== resolve(path)
+        || (typeof process.getuid === 'function' && (info.uid !== process.getuid() || (info.mode & 0o077) !== 0))) {
+        throw new Error('epic-operational-path-unsafe');
+    }
+}
+function assertOperationalContext(document, state, context) {
+    if (context?.expectedRevision !== undefined && document.revision !== context.expectedRevision) {
+        throw new Error('epic-operational-revision-conflict');
+    }
+    if (context?.expectedWriterEpoch !== undefined && state.writerEpoch !== context.expectedWriterEpoch) {
+        throw new Error('epic-operational-epoch-conflict');
+    }
+    if (context?.identityHash !== undefined && !state.identities[context.identityHash]) {
+        throw new Error('epic-operational-identity-mismatch');
+    }
+}
+function assertEpicOperationalIdentity(value) {
+    const item = record(value);
+    if (!item)
+        throw new Error('epic-operational-identity-mismatch');
+    exact(item, [
+        'schemaVersion', 'epicId', 'executionBranch', 'graphRevision',
+        'originBindingDigest', 'repositoryFingerprint', 'identityHash',
+    ]);
+    const { identityHash, ...base } = item;
+    if (item.schemaVersion !== 'EpicOperationalIdentity/1.0' || !ID.test(String(item.epicId))
+        || !safeGitRef(item.executionBranch) || !hash(item.graphRevision)
+        || !hash(item.originBindingDigest) || !hash(item.repositoryFingerprint)
+        || identityHash !== epicOperationalHash('p224-epic-operational-identity-v1', base)) {
+        throw new Error('epic-operational-identity-mismatch');
+    }
+}
+function validProjectionBinding(value) {
+    const item = record(value);
+    return Boolean(item && hasExactKeys(item, ['status', 'sourceDigest', 'authorityRevision', 'reasonCodes'])
+        && ['bound', 'unbound', 'unavailable'].includes(String(item.status))
+        && (item.sourceDigest === null || hash(item.sourceDigest))
+        && Number.isSafeInteger(item.authorityRevision) && Number(item.authorityRevision) >= 0
+        && Array.isArray(item.reasonCodes) && item.reasonCodes.length <= 16
+        && item.reasonCodes.every(safeReasonCode));
+}
+function validJournal(value) {
+    const item = record(value);
+    const statuses = record(item?.projectionStatuses);
+    return Boolean(item && hasExactKeys(item, [
+        'schemaVersion', 'kind', 'operationId', 'idempotencyKey', 'payloadHash',
+        'identityHash', 'expectedRevision', 'expectedWriterEpoch', 'preimageDigest',
+        'backupManifestRef', 'phase', 'projectionStatuses', 'reasonCodes',
+    ]) && item.schemaVersion === 'EpicOperationalJournal/1.0'
+        && ['backfill', 'cross-epic-reconcile', 'rollback'].includes(String(item.kind))
+        && safeToken(item.operationId) && safeToken(item.idempotencyKey) && hash(item.payloadHash)
+        && hash(item.identityHash) && Number.isSafeInteger(item.expectedRevision)
+        && Number.isSafeInteger(item.expectedWriterEpoch) && hash(item.preimageDigest)
+        && typeof item.backupManifestRef === 'string' && item.backupManifestRef.length <= 1_024
+        && !isAbsolute(item.backupManifestRef) && !item.backupManifestRef.includes('..')
+        && ['prepared', 'authority-applied', 'projections-applied', 'committed', 'aborted-before-authority'].includes(String(item.phase))
+        && statuses && hasExactKeys(statuses, ['trackedState', 'sqlite'])
+        && ['pending', 'applied', 'not-applicable'].includes(String(statuses.trackedState))
+        && ['pending', 'applied', 'unavailable', 'not-applicable'].includes(String(statuses.sqlite))
+        && Array.isArray(item.reasonCodes) && item.reasonCodes.length <= 16
+        && item.reasonCodes.every(safeReasonCode));
+}
+function boundedReceipts(value, schema) {
+    return Array.isArray(value) && value.length <= EPIC_OPERATIONAL_RECEIPT_CAP
+        && value.every((entry) => schema === 'EpicLifecycleBackfillReceipt/1.0'
+            ? validBackfillReceipt(entry)
+            : schema === 'YoloopCrossEpicReconciliationReceipt/1.0'
+                ? validReconciliationReceipt(entry)
+                : validRollbackReceipt(entry));
+}
+function validBackfillReceipt(value) {
+    const item = record(value);
+    return Boolean(item && hasExactKeys(item, [
+        'schemaVersion', 'operationId', 'idempotencyKey', 'payloadHash', 'planDigest',
+        'sourceInventoryDigest', 'preimageDigest', 'postimageDigest',
+        'authorityPostimageDigest', 'backupManifestDigest', 'identityHash',
+        'appliedRevision', 'writerEpoch', 'stateMigrationOperationId', 'outcome',
+        'reasonCodes', 'publicSafe',
+    ]) && item.schemaVersion === 'EpicLifecycleBackfillReceipt/1.0'
+        && safeOperationId(item.operationId) && safeOperationId(item.idempotencyKey)
+        && item.operationId === item.idempotencyKey
+        && [item.payloadHash, item.planDigest, item.sourceInventoryDigest, item.preimageDigest,
+            item.postimageDigest, item.authorityPostimageDigest, item.backupManifestDigest,
+            item.identityHash].every(hash)
+        && Number.isSafeInteger(item.appliedRevision) && Number(item.appliedRevision) >= 1
+        && Number.isSafeInteger(item.writerEpoch) && Number(item.writerEpoch) >= 1
+        && (item.stateMigrationOperationId === null || safeOperationId(item.stateMigrationOperationId))
+        && ['applied', 'already-applied'].includes(String(item.outcome))
+        && validReasonCodes(item.reasonCodes) && item.publicSafe === true);
+}
+function validReconciliationReceipt(value) {
+    const item = record(value);
+    return Boolean(item && hasExactKeys(item, [
+        'schemaVersion', 'operationId', 'idempotencyKey', 'payloadHash', 'sourceEpicId',
+        'sourceGraphRevision', 'targetEpicId', 'targetGraphRevision', 'runId',
+        'previousSessionHash', 'nextSessionHash', 'retiredAuthorityHash',
+        'retiredAuthorityCount', 'outcome', 'publicSafe',
+    ]) && item.schemaVersion === 'YoloopCrossEpicReconciliationReceipt/1.0'
+        && safeOperationId(item.operationId) && safeOperationId(item.idempotencyKey)
+        && hash(item.payloadHash) && ID.test(String(item.sourceEpicId)) && ID.test(String(item.targetEpicId))
+        && hash(item.sourceGraphRevision) && hash(item.targetGraphRevision)
+        && safeOperationId(item.runId) && hash(item.previousSessionHash) && hash(item.nextSessionHash)
+        && hash(item.retiredAuthorityHash) && [0, 1].includes(Number(item.retiredAuthorityCount))
+        && item.outcome === 'cross-epic-reconciled' && item.publicSafe === true);
+}
+function validRollbackReceipt(value) {
+    const item = record(value);
+    return Boolean(item && hasExactKeys(item, [
+        'schemaVersion', 'operationId', 'targetOperationId', 'expectedPostimageDigest',
+        'restoredPreimageDigest', 'reasonCodes', 'publicSafe',
+    ]) && item.schemaVersion === 'EpicOperationalRollbackReceipt/1.0'
+        && safeOperationId(item.operationId) && safeOperationId(item.targetOperationId)
+        && hash(item.expectedPostimageDigest) && hash(item.restoredPreimageDigest)
+        && validReasonCodes(item.reasonCodes) && item.publicSafe === true);
+}
+function validReasonCodes(value) {
+    return Array.isArray(value) && value.length <= 16 && value.every(safeReasonCode);
+}
+function sameStringSet(value, expected) {
+    return value.length === expected.length && expected.every((item) => value.includes(item));
+}
+function exact(item, keys) {
+    const allowed = new Set(keys);
+    if (Object.keys(item).some((key) => !allowed.has(key)))
+        throw new Error('epic-operational-store-corrupt');
+}
+function hasExactKeys(item, keys) {
+    const actual = Object.keys(item).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value : undefined;
+}
+function hash(value) {
+    return typeof value === 'string' && HASH.test(value);
+}
+function safeToken(value) {
+    return typeof value === 'string' && SAFE_TOKEN.test(value) && !value.includes('..');
+}
+function safeOperationId(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9._:-]{1,128}$/.test(value);
+}
+function safeReasonCode(value) {
+    return typeof value === 'string' && /^[a-z0-9][a-z0-9-]{0,79}$/.test(value);
+}
+function safeGitRef(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._/-]{0,239}$/.test(value)
+        && !value.includes('..') && !value.includes('//') && !value.includes('@{')
+        && !value.endsWith('/') && !value.endsWith('.');
+}
+function publicOperationalReason(error) {
+    const reason = error instanceof Error ? error.message : '';
+    return safeReasonCode(reason) ? reason : 'epic-operational-store-corrupt';
+}