@ornexus/neocortex 4.60.66 → 4.60.68

package/packages/client/dist/migrations/state-json.js

@@ -1,4 +1,344 @@
-import{createHash as q,randomUUID as N}from"node:crypto";import{existsSync as S,linkSync as J,lstatSync as E,mkdirSync as z,readFileSync as h,realpathSync as G,statSync as j,unlinkSync as v}from"node:fs";import{dirname as A,join as d,resolve as K}from"node:path";import{assertStateMigrationPlanV1 as X,assertStateMigrationReceiptV1 as Y,planStateMigration as T,stateMigrationDigest as Q,STATE_MIGRATION_RECEIPT_SCHEMA as W,StateMigrationHardStopError as B}from"../../../shared/dist/state/index.js";import{atomicReplaceUtf8 as M,durableCreateUtf8 as L,fsyncDirectoryBestEffort as O,recoverAtomicReplaceUtf8 as V}from"../fs/atomic-state-replace.js";const D=d(".neocortex","state.json"),R=d(".neocortex","state-migration.json"),Z=d(".neocortex","state-migration.lock"),P=4*1024*1024;class o extends Error{reasonCode;receipt;constructor(e,a=e,t){super(a),this.reasonCode=e,this.receipt=t,this.name="StateMigrationApplyError"}}const _=i=>q("sha256").update(i).digest("hex"),tt=i=>`${JSON.stringify(i,null,2)}
-`;function $(i){let e;try{e=G(K(i))}catch{throw new o("state_migration_root_invalid")}if(!j(e).isDirectory())throw new o("state_migration_root_invalid");for(const a of[".neocortex",D,R]){const t=d(e,a);if(!S(t))continue;const s=E(t);if(s.isSymbolicLink()||a!==".neocortex"&&!s.isFile()||a===".neocortex"&&!s.isDirectory())throw new o("state_migration_symlink_or_type_rejected")}return e}function U(i){try{const e=JSON.parse(i);if(e&&typeof e=="object"&&!Array.isArray(e))return e}catch{}throw new o("state_migration_state_corrupt")}function F(i){const e=d(i,D);if(!S(e))throw new o("state_migration_state_missing");const a=j(e).size;if(a>P)throw new o("state_migration_input_too_large");const t=h(e,"utf8"),s=Buffer.byteLength(t,"utf8");if(s!==a||s>P)throw new o("state_migration_source_changed");return{state:U(t),raw:t,digest:_(t),bytes:s}}function ct(i){const e=F($(i));let a;try{a=T(e.state)}catch(l){throw l instanceof B?new o(l.reasonCode,l.message):l}const t=a.kind==="migrate"?a.plan.targetState:e.state,s=(l,p)=>{const n=l[p];return n&&typeof n=="object"&&!Array.isArray(n)?Object.keys(n).length:0},c=a.kind==="migrate"?(({targetState:l,...p})=>p)(a.plan):null;return Object.freeze({schemaVersion:"StateMigrationAuthority/1.0",sourceByteDigest:e.digest,sourceCanonicalHash:a.kind==="migrate"?a.plan.sourceCanonicalHash:a.sourceCanonicalHash,sourceByteLength:e.bytes,before:{epics:s(e.state,"epics"),stories:s(e.state,"stories")},after:{epics:s(t,"epics"),stories:s(t,"stories")},outcome:a.kind,plan:c,publicSafe:!0})}function et(i){const e=d(i,Z);z(A(e),{recursive:!0,mode:448});const a=N(),t=`${process.pid}:${a}
-`,s=()=>{const c=`${e}.${process.pid}.${N()}.owner`;L(c,t);try{J(c,e)}finally{try{v(c)}catch{}O(A(e))}};try{s()}catch(c){if(c.code!=="EEXIST")throw new o("state_migration_lock_failed");const l=E(e);if(l.isSymbolicLink()||!l.isFile())throw new o("state_migration_lock_corrupt");const p=h(e,"utf8"),n=p.match(/^([1-9][0-9]*):([a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12})\n$/i);if(!n||p.length>64)throw new o("state_migration_lock_corrupt");let f=!0;try{process.kill(Number(n[1]),0)}catch(r){f=r.code!=="ESRCH"}if(f)throw new o("state_migration_locked");try{v(e),s()}catch{throw new o("state_migration_locked")}}return()=>{try{if(h(e,"utf8")!==t)return;v(e),O(A(e))}catch{}}}function rt(i){const e=d(i,R);if(V(e),!S(e))return null;let a;try{a=JSON.parse(h(e,"utf8"))}catch{throw new o("state_migration_manifest_corrupt")}if(!a||typeof a!="object"||Array.isArray(a))throw new o("state_migration_manifest_corrupt");const t=a;if(t.schemaVersion!==1||typeof t.operationId!="string"||!/^smig_[a-f0-9]{32}$/.test(t.operationId)||!["prepared","applied","rolled-back"].includes(String(t.phase))||typeof t.sourceCanonicalHash!="string"||!/^[a-f0-9]{64}$/.test(t.sourceCanonicalHash)||typeof t.sourceByteDigest!="string"||!/^[a-f0-9]{64}$/.test(t.sourceByteDigest)||typeof t.targetCanonicalHash!="string"||!/^[a-f0-9]{64}$/.test(t.targetCanonicalHash)||typeof t.targetByteDigest!="string"||!/^[a-f0-9]{64}$/.test(t.targetByteDigest)||!Number.isSafeInteger(t.migratedEpicCount)||(t.migratedEpicCount??-1)<0||!Number.isSafeInteger(t.migratedStoryCount)||(t.migratedStoryCount??-1)<0||!Number.isSafeInteger(t.preservedUnknownFieldCount)||(t.preservedUnknownFieldCount??-1)<0||typeof t.backupPath!="string"||t.backupPath!==d(".neocortex",`state.json.migration-backup-${t.operationId}`))throw new o("state_migration_manifest_corrupt");return t}function b(i,e){M(d(i,R),`${JSON.stringify(e,null,2)}
-`)}function k(i,e,a,t,s,c,l,p,n,f,r,g){const m={schemaVersion:W,operationId:e,outcome:i,sourceBytesHash:a,targetBytesHash:t,sourceCanonicalHash:s,targetCanonicalHash:c,backupHash:l,rollbackStatus:p,migratedEpicCount:n,migratedStoryCount:f,preservedUnknownFieldCount:r,reasonCodes:g,publicSafe:!0};return Y(m),m}function lt(i){const e=$(i);let a;try{a=T(F(e).state)}catch(t){throw t instanceof B?new o(t.reasonCode,t.message):t}return a.kind==="migrate"?a.plan:null}function pt(i,e,a={}){const t=$(i),s=et(t);try{const c=d(t,D);try{V(c)}catch{throw new o("state_migration_atomic_recovery_failed")}if(!S(c))throw new o("state_migration_state_missing");const l=F(t).raw;if(e?.sourceByteDigest&&_(l)!==e.sourceByteDigest)throw new o("state_migration_expected_bytes_conflict");let p;try{p=T(U(l))}catch(u){throw u instanceof B?new o(u.reasonCode,u.message):u}const n=rt(t),f=_(l);if(p.kind==="unchanged"){if(e&&p.sourceCanonicalHash!==e.targetCanonicalHash)throw new o("state_migration_expected_plan_conflict");if(n&&n.targetCanonicalHash===p.sourceCanonicalHash){if(n.targetByteDigest!==f)throw new o("state_migration_state_drift");if(n.phase==="prepared"&&b(t,{...n,phase:"applied"}),n.phase==="rolled-back")throw new o("state_migration_state_drift");return k("already-applied",n.operationId,n.sourceByteDigest,n.targetByteDigest,n.sourceCanonicalHash,n.targetCanonicalHash,n.sourceByteDigest,"not-required",n.migratedEpicCount,n.migratedStoryCount,n.preservedUnknownFieldCount,["migration_replay_verified"])}if(n)throw new o("state_migration_state_drift");return k("already-applied",e?.operationId??"smig_00000000000000000000000000000000",f,f,p.sourceCanonicalHash,p.sourceCanonicalHash,null,"not-required",0,0,0,["canonical_state_unchanged"])}const r=p.plan;if(X(r),e&&(e.operationId!==r.operationId||e.sourceCanonicalHash!==r.sourceCanonicalHash||e.targetCanonicalHash!==r.targetCanonicalHash))throw new o("state_migration_expected_plan_conflict");if(n&&n.operationId!==r.operationId)throw new o("state_migration_operation_conflict");const g=f,m=tt(r.targetState),w=_(m),x=d(".neocortex",`state.json.migration-backup-${r.operationId}`),y=d(t,x);if(S(y)){const u=E(y);if(u.isSymbolicLink()||!u.isFile()||_(h(y))!==g)throw new o("state_migration_backup_conflict")}else L(y,l);const I={schemaVersion:1,operationId:r.operationId,phase:"prepared",sourceCanonicalHash:r.sourceCanonicalHash,sourceByteDigest:g,targetCanonicalHash:r.targetCanonicalHash,targetByteDigest:w,migratedEpicCount:r.migratedEpicIds.length,migratedStoryCount:r.migratedStoryIds.length,preservedUnknownFieldCount:r.preservedUnknownFieldCount,backupPath:x};if(b(t,I),a.afterPrepared?.(c),_(h(c))!==g)throw new o("state_migration_source_cas_conflict");try{M(c,m),a.afterReplace?.(c);const u=h(c,"utf8"),H=U(u);if(_(u)!==w||Q(H)!==r.targetCanonicalHash)throw new Error("readback-digest-mismatch");b(t,{...I,phase:"applied"})}catch(u){try{const C=h(y,"utf8");if(_(C)!==g)throw new Error("rollback-backup-digest-mismatch");if(M(c,C),_(h(c))!==g)throw new Error("rollback-digest-mismatch");b(t,{...I,phase:"rolled-back"})}catch{const C=k("blocked",r.operationId,g,w,r.sourceCanonicalHash,r.targetCanonicalHash,g,"unverified",r.migratedEpicIds.length,r.migratedStoryIds.length,r.preservedUnknownFieldCount,["apply_failed","rollback_unverified"]);throw new o("state_migration_rollback_failed",String(u),C)}const H=k("blocked",r.operationId,g,w,r.sourceCanonicalHash,r.targetCanonicalHash,g,"restored",r.migratedEpicIds.length,r.migratedStoryIds.length,r.preservedUnknownFieldCount,["apply_failed","rollback_verified"]);throw new o("state_migration_apply_rolled_back",String(u),H)}return k("applied",r.operationId,g,w,r.sourceCanonicalHash,r.targetCanonicalHash,g,"not-required",r.migratedEpicIds.length,r.migratedStoryIds.length,r.preservedUnknownFieldCount,["lock_acquired","source_cas_verified","backup_verified","atomic_replace_verified"])}finally{s()}}export{P as STATE_MIGRATION_INPUT_LIMIT_BYTES,o as StateMigrationApplyError,pt as applyStateMigration,ct as collectStateMigrationAuthority,lt as previewStateMigration};
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync, } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { assertStateMigrationPlanV1, assertStateMigrationReceiptV1, planStateMigration, stateMigrationDigest, STATE_MIGRATION_RECEIPT_SCHEMA, StateMigrationHardStopError, } from '../../../shared/dist/state/index.js';
+import { atomicReplaceUtf8, durableCreateUtf8, fsyncDirectoryBestEffort, recoverAtomicReplaceUtf8, } from '../fs/atomic-state-replace.js';
+const STATE_RELATIVE_PATH = join('.neocortex', 'state.json');
+const MANIFEST_RELATIVE_PATH = join('.neocortex', 'state-migration.json');
+const LOCK_RELATIVE_PATH = join('.neocortex', 'state-migration.lock');
+export const STATE_MIGRATION_INPUT_LIMIT_BYTES = 4 * 1024 * 1024;
+export class StateMigrationApplyError extends Error {
+    reasonCode;
+    receipt;
+    constructor(reasonCode, message = reasonCode, receipt) {
+        super(message);
+        this.reasonCode = reasonCode;
+        this.receipt = receipt;
+        this.name = 'StateMigrationApplyError';
+    }
+}
+const sha256Bytes = (value) => createHash('sha256').update(value).digest('hex');
+const stateRaw = (state) => `${JSON.stringify(state, null, 2)}\n`;
+function safeRoot(projectRoot) {
+    let root;
+    try {
+        root = realpathSync(resolve(projectRoot));
+    }
+    catch {
+        throw new StateMigrationApplyError('state_migration_root_invalid');
+    }
+    if (!statSync(root).isDirectory())
+        throw new StateMigrationApplyError('state_migration_root_invalid');
+    for (const relative of ['.neocortex', STATE_RELATIVE_PATH, MANIFEST_RELATIVE_PATH]) {
+        const path = join(root, relative);
+        if (!existsSync(path))
+            continue;
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink() || (relative !== '.neocortex' && !stat.isFile()) || (relative === '.neocortex' && !stat.isDirectory())) {
+            throw new StateMigrationApplyError('state_migration_symlink_or_type_rejected');
+        }
+    }
+    return root;
+}
+function parseState(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch { /* normalized below */ }
+    throw new StateMigrationApplyError('state_migration_state_corrupt');
+}
+function readBoundedState(root) {
+    const statePath = join(root, STATE_RELATIVE_PATH);
+    if (!existsSync(statePath))
+        throw new StateMigrationApplyError('state_migration_state_missing');
+    const size = statSync(statePath).size;
+    if (size > STATE_MIGRATION_INPUT_LIMIT_BYTES)
+        throw new StateMigrationApplyError('state_migration_input_too_large');
+    const raw = readFileSync(statePath, 'utf8');
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    if (bytes !== size || bytes > STATE_MIGRATION_INPUT_LIMIT_BYTES) {
+        throw new StateMigrationApplyError('state_migration_source_changed');
+    }
+    return { state: parseState(raw), raw, digest: sha256Bytes(raw), bytes };
+}
+export function collectStateMigrationAuthority(projectRoot) {
+    const source = readBoundedState(safeRoot(projectRoot));
+    let decision;
+    try {
+        decision = planStateMigration(source.state);
+    }
+    catch (error) {
+        if (error instanceof StateMigrationHardStopError)
+            throw new StateMigrationApplyError(error.reasonCode, error.message);
+        throw error;
+    }
+    const target = decision.kind === 'migrate' ? decision.plan.targetState : source.state;
+    const count = (record, key) => {
+        const value = record[key];
+        return value && typeof value === 'object' && !Array.isArray(value) ? Object.keys(value).length : 0;
+    };
+    const plan = decision.kind === 'migrate'
+        ? (({ targetState: _privateTargetState, ...publicPlan }) => publicPlan)(decision.plan)
+        : null;
+    return Object.freeze({
+        schemaVersion: 'StateMigrationAuthority/1.0',
+        sourceByteDigest: source.digest,
+        sourceCanonicalHash: decision.kind === 'migrate' ? decision.plan.sourceCanonicalHash : decision.sourceCanonicalHash,
+        sourceByteLength: source.bytes,
+        before: { epics: count(source.state, 'epics'), stories: count(source.state, 'stories') },
+        after: { epics: count(target, 'epics'), stories: count(target, 'stories') },
+        outcome: decision.kind,
+        plan,
+        publicSafe: true,
+    });
+}
+function claimLock(root) {
+    const lockPath = join(root, LOCK_RELATIVE_PATH);
+    mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+    const ownerToken = randomUUID();
+    const ownerContents = `${process.pid}:${ownerToken}\n`;
+    const acquire = () => {
+        const ownerPath = `${lockPath}.${process.pid}.${randomUUID()}.owner`;
+        durableCreateUtf8(ownerPath, ownerContents);
+        try {
+            linkSync(ownerPath, lockPath);
+        }
+        finally {
+            try {
+                unlinkSync(ownerPath);
+            }
+            catch { /* orphan owners have no authority */ }
+            fsyncDirectoryBestEffort(dirname(lockPath));
+        }
+    };
+    try {
+        acquire();
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw new StateMigrationApplyError('state_migration_lock_failed');
+        const stat = lstatSync(lockPath);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            throw new StateMigrationApplyError('state_migration_lock_corrupt');
+        const owner = readFileSync(lockPath, 'utf8');
+        const ownerMatch = owner.match(/^([1-9][0-9]*):([a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12})\n$/i);
+        if (!ownerMatch || owner.length > 64)
+            throw new StateMigrationApplyError('state_migration_lock_corrupt');
+        let alive = true;
+        try {
+            process.kill(Number(ownerMatch[1]), 0);
+        }
+        catch (probe) {
+            alive = probe.code !== 'ESRCH';
+        }
+        if (alive)
+            throw new StateMigrationApplyError('state_migration_locked');
+        try {
+            unlinkSync(lockPath);
+            acquire();
+        }
+        catch {
+            throw new StateMigrationApplyError('state_migration_locked');
+        }
+    }
+    return () => {
+        try {
+            if (readFileSync(lockPath, 'utf8') !== ownerContents)
+                return;
+            unlinkSync(lockPath);
+            fsyncDirectoryBestEffort(dirname(lockPath));
+        }
+        catch { /* cleanup is best effort; never delete an unproven foreign lock */ }
+    };
+}
+function parseManifest(root) {
+    const path = join(root, MANIFEST_RELATIVE_PATH);
+    recoverAtomicReplaceUtf8(path);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new StateMigrationApplyError('state_migration_manifest_corrupt');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new StateMigrationApplyError('state_migration_manifest_corrupt');
+    const value = parsed;
+    if (value.schemaVersion !== 1
+        || typeof value.operationId !== 'string' || !/^smig_[a-f0-9]{32}$/.test(value.operationId)
+        || !['prepared', 'applied', 'rolled-back'].includes(String(value.phase))
+        || typeof value.sourceCanonicalHash !== 'string' || !/^[a-f0-9]{64}$/.test(value.sourceCanonicalHash)
+        || typeof value.sourceByteDigest !== 'string' || !/^[a-f0-9]{64}$/.test(value.sourceByteDigest)
+        || typeof value.targetCanonicalHash !== 'string' || !/^[a-f0-9]{64}$/.test(value.targetCanonicalHash)
+        || typeof value.targetByteDigest !== 'string' || !/^[a-f0-9]{64}$/.test(value.targetByteDigest)
+        || !Number.isSafeInteger(value.migratedEpicCount) || (value.migratedEpicCount ?? -1) < 0
+        || !Number.isSafeInteger(value.migratedStoryCount) || (value.migratedStoryCount ?? -1) < 0
+        || !Number.isSafeInteger(value.preservedUnknownFieldCount) || (value.preservedUnknownFieldCount ?? -1) < 0
+        || typeof value.backupPath !== 'string'
+        || value.backupPath !== join('.neocortex', `state.json.migration-backup-${value.operationId}`)) {
+        throw new StateMigrationApplyError('state_migration_manifest_corrupt');
+    }
+    return value;
+}
+function writeManifest(root, manifest) {
+    atomicReplaceUtf8(join(root, MANIFEST_RELATIVE_PATH), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+function receipt(outcome, operationId, sourceBytesHash, targetBytesHash, sourceCanonicalHash, targetCanonicalHash, backupHash, rollbackStatus, migratedEpicCount, migratedStoryCount, preservedUnknownFieldCount, reasonCodes) {
+    const value = {
+        schemaVersion: STATE_MIGRATION_RECEIPT_SCHEMA,
+        operationId,
+        outcome,
+        sourceBytesHash,
+        targetBytesHash,
+        sourceCanonicalHash,
+        targetCanonicalHash,
+        backupHash,
+        rollbackStatus,
+        migratedEpicCount,
+        migratedStoryCount,
+        preservedUnknownFieldCount,
+        reasonCodes,
+        publicSafe: true,
+    };
+    assertStateMigrationReceiptV1(value);
+    return value;
+}
+export function previewStateMigration(projectRoot) {
+    const root = safeRoot(projectRoot);
+    let decision;
+    try {
+        decision = planStateMigration(readBoundedState(root).state);
+    }
+    catch (error) {
+        if (error instanceof StateMigrationHardStopError)
+            throw new StateMigrationApplyError(error.reasonCode, error.message);
+        throw error;
+    }
+    return decision.kind === 'migrate' ? decision.plan : null;
+}
+/** Apply one shared plan under a client-owned lock, byte CAS and durable backup. */
+export function applyStateMigration(projectRoot, expectedPlan, hooks = {}) {
+    const root = safeRoot(projectRoot);
+    const release = claimLock(root);
+    try {
+        const statePath = join(root, STATE_RELATIVE_PATH);
+        try {
+            recoverAtomicReplaceUtf8(statePath);
+        }
+        catch {
+            throw new StateMigrationApplyError('state_migration_atomic_recovery_failed');
+        }
+        if (!existsSync(statePath))
+            throw new StateMigrationApplyError('state_migration_state_missing');
+        const initialRaw = readBoundedState(root).raw;
+        if (expectedPlan?.sourceByteDigest && sha256Bytes(initialRaw) !== expectedPlan.sourceByteDigest) {
+            throw new StateMigrationApplyError('state_migration_expected_bytes_conflict');
+        }
+        let decision;
+        try {
+            decision = planStateMigration(parseState(initialRaw));
+        }
+        catch (error) {
+            if (error instanceof StateMigrationHardStopError)
+                throw new StateMigrationApplyError(error.reasonCode, error.message);
+            throw error;
+        }
+        const existing = parseManifest(root);
+        const currentBytesHash = sha256Bytes(initialRaw);
+        if (decision.kind === 'unchanged') {
+            if (expectedPlan && decision.sourceCanonicalHash !== expectedPlan.targetCanonicalHash) {
+                throw new StateMigrationApplyError('state_migration_expected_plan_conflict');
+            }
+            if (existing && existing.targetCanonicalHash === decision.sourceCanonicalHash) {
+                if (existing.targetByteDigest !== currentBytesHash) {
+                    throw new StateMigrationApplyError('state_migration_state_drift');
+                }
+                if (existing.phase === 'prepared')
+                    writeManifest(root, { ...existing, phase: 'applied' });
+                if (existing.phase === 'rolled-back')
+                    throw new StateMigrationApplyError('state_migration_state_drift');
+                return receipt('already-applied', existing.operationId, existing.sourceByteDigest, existing.targetByteDigest, existing.sourceCanonicalHash, existing.targetCanonicalHash, existing.sourceByteDigest, 'not-required', existing.migratedEpicCount, existing.migratedStoryCount, existing.preservedUnknownFieldCount, ['migration_replay_verified']);
+            }
+            if (existing)
+                throw new StateMigrationApplyError('state_migration_state_drift');
+            return receipt('already-applied', expectedPlan?.operationId ?? 'smig_00000000000000000000000000000000', currentBytesHash, currentBytesHash, decision.sourceCanonicalHash, decision.sourceCanonicalHash, null, 'not-required', 0, 0, 0, ['canonical_state_unchanged']);
+        }
+        const plan = decision.plan;
+        assertStateMigrationPlanV1(plan);
+        if (expectedPlan && (expectedPlan.operationId !== plan.operationId
+            || expectedPlan.sourceCanonicalHash !== plan.sourceCanonicalHash
+            || expectedPlan.targetCanonicalHash !== plan.targetCanonicalHash)) {
+            throw new StateMigrationApplyError('state_migration_expected_plan_conflict');
+        }
+        if (existing && existing.operationId !== plan.operationId) {
+            throw new StateMigrationApplyError('state_migration_operation_conflict');
+        }
+        const sourceByteDigest = currentBytesHash;
+        const targetRaw = stateRaw(plan.targetState);
+        const targetByteDigest = sha256Bytes(targetRaw);
+        const backupPath = join('.neocortex', `state.json.migration-backup-${plan.operationId}`);
+        const backupAbsolute = join(root, backupPath);
+        if (existsSync(backupAbsolute)) {
+            const backupStat = lstatSync(backupAbsolute);
+            if (backupStat.isSymbolicLink() || !backupStat.isFile() || sha256Bytes(readFileSync(backupAbsolute)) !== sourceByteDigest) {
+                throw new StateMigrationApplyError('state_migration_backup_conflict');
+            }
+        }
+        else {
+            durableCreateUtf8(backupAbsolute, initialRaw);
+        }
+        const manifest = {
+            schemaVersion: 1,
+            operationId: plan.operationId,
+            phase: 'prepared',
+            sourceCanonicalHash: plan.sourceCanonicalHash,
+            sourceByteDigest,
+            targetCanonicalHash: plan.targetCanonicalHash,
+            targetByteDigest,
+            migratedEpicCount: plan.migratedEpicIds.length,
+            migratedStoryCount: plan.migratedStoryIds.length,
+            preservedUnknownFieldCount: plan.preservedUnknownFieldCount,
+            backupPath,
+        };
+        writeManifest(root, manifest);
+        hooks.afterPrepared?.(statePath);
+        if (sha256Bytes(readFileSync(statePath)) !== sourceByteDigest) {
+            throw new StateMigrationApplyError('state_migration_source_cas_conflict');
+        }
+        try {
+            atomicReplaceUtf8(statePath, targetRaw);
+            hooks.afterReplace?.(statePath);
+            const installedRaw = readFileSync(statePath, 'utf8');
+            const installed = parseState(installedRaw);
+            if (sha256Bytes(installedRaw) !== targetByteDigest || stateMigrationDigest(installed) !== plan.targetCanonicalHash) {
+                throw new Error('readback-digest-mismatch');
+            }
+            writeManifest(root, { ...manifest, phase: 'applied' });
+        }
+        catch (error) {
+            try {
+                const backupRaw = readFileSync(backupAbsolute, 'utf8');
+                if (sha256Bytes(backupRaw) !== sourceByteDigest)
+                    throw new Error('rollback-backup-digest-mismatch');
+                atomicReplaceUtf8(statePath, backupRaw);
+                if (sha256Bytes(readFileSync(statePath)) !== sourceByteDigest)
+                    throw new Error('rollback-digest-mismatch');
+                writeManifest(root, { ...manifest, phase: 'rolled-back' });
+            }
+            catch {
+                const unverified = receipt('blocked', plan.operationId, sourceByteDigest, targetByteDigest, plan.sourceCanonicalHash, plan.targetCanonicalHash, sourceByteDigest, 'unverified', plan.migratedEpicIds.length, plan.migratedStoryIds.length, plan.preservedUnknownFieldCount, ['apply_failed', 'rollback_unverified']);
+                throw new StateMigrationApplyError('state_migration_rollback_failed', String(error), unverified);
+            }
+            const rolledBack = receipt('blocked', plan.operationId, sourceByteDigest, targetByteDigest, plan.sourceCanonicalHash, plan.targetCanonicalHash, sourceByteDigest, 'restored', plan.migratedEpicIds.length, plan.migratedStoryIds.length, plan.preservedUnknownFieldCount, ['apply_failed', 'rollback_verified']);
+            throw new StateMigrationApplyError('state_migration_apply_rolled_back', String(error), rolledBack);
+        }
+        return receipt('applied', plan.operationId, sourceByteDigest, targetByteDigest, plan.sourceCanonicalHash, plan.targetCanonicalHash, sourceByteDigest, 'not-required', plan.migratedEpicIds.length, plan.migratedStoryIds.length, plan.preservedUnknownFieldCount, ['lock_acquired', 'source_cas_verified', 'backup_verified', 'atomic_replace_verified']);
+    }
+    finally {
+        release();
+    }
+}

package/packages/client/dist/policy/architecture-policy.js

@@ -1,2 +1,184 @@
-import{readFile as u}from"node:fs/promises";import{join as d}from"node:path";const p=".neocortex/architecture-policy.json",f=Object.freeze(["interactive","yoloop_friendly","fully_automated"]),y=Object.freeze(["aws","gcp","oci","azure","any"]),_=Object.freeze(["REST","GraphQL","tRPC"]),g=Object.freeze(["sync","async","hybrid"]),m=Object.freeze(["mobile-first","desktop-first","responsive"]),O=Object.freeze(["conservative","balanced","aggressive"]),b=Object.freeze(["TDD","test-after","BDD"]),h=new Set(["primary_persona","cloud_provider","api_style","integration_style","ui_priority","refactor_aggressiveness","test_workflow"]);function v(n){const r=[],o=[];if(typeof n!="object"||n===null||Array.isArray(n))return{valid:!1,errors:Object.freeze(["Policy must be a plain object"]),warnings:Object.freeze([])};const t=n;if(t.schema_version!==1&&r.push(`schema_version must be 1, got ${JSON.stringify(t.schema_version)}`),(typeof t.mode!="string"||!f.includes(t.mode))&&r.push(`mode must be one of [${f.join(", ")}], got ${JSON.stringify(t.mode)}`),t.defaults!==void 0&&t.defaults!==null)if(typeof t.defaults!="object"||Array.isArray(t.defaults))r.push("defaults must be an object");else{const e=t.defaults;for(const c of Object.keys(e))h.has(c)||o.push(`defaults.${c}: unknown field (ignored)`);e.primary_persona!==void 0&&e.primary_persona!==null&&typeof e.primary_persona!="string"&&r.push("defaults.primary_persona must be string or null"),i(e,"cloud_provider",y,r),i(e,"api_style",_,r),i(e,"integration_style",g,r),i(e,"ui_priority",m,r),i(e,"refactor_aggressiveness",O,r),i(e,"test_workflow",b,r)}return t.preserved_interactions!==void 0&&t.preserved_interactions!==null&&(!Array.isArray(t.preserved_interactions)||!t.preserved_interactions.every(e=>typeof e=="string"))&&r.push("preserved_interactions must be array of strings"),{valid:r.length===0,errors:Object.freeze(r),warnings:Object.freeze(o)}}async function A(n){const r=d(n,p);let o;try{o=await u(r,"utf8")}catch(s){if(s.code==="ENOENT")return;const l=s.message??String(s);console.warn(`[Neocortex] architecture-policy read failed (${r}): ${l}`);return}const t=o.replace(/^/,"").replace(/\r\n/g,`
-`);let e;try{e=JSON.parse(t)}catch(s){const a=s.message??String(s);console.warn(`[Neocortex] architecture-policy malformed JSON (${r}): ${a}. Proceeding without policy.`);return}const c=v(e);if(!c.valid){console.warn(`[Neocortex] architecture-policy schema invalid (${r}): ${c.errors.join("; ")}. Proceeding without policy.`);return}return e}function i(n,r,o,t){const e=n[r];e!=null&&(typeof e!="string"||!o.includes(e))&&t.push(`defaults.${r} must be one of [${o.join(", ")}] or null, got ${JSON.stringify(e)}`)}export{p as POLICY_FILE_PATH,A as readArchitecturePolicy,v as validatePolicy};
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * Epic P107.02: Client-side Policy Reader
+ *
+ * Reads `.neocortex/architecture-policy.json` from consumer project root,
+ * validates structure against P107.01 wire-format types, and exposes to
+ * `collectStateSnapshot` hook so the server receives it via request body.
+ *
+ * Fail-soft by design -- NEVER throws. File absent / malformed / invalid
+ * schema all return `undefined` (warning to stderr when non-trivial).
+ *
+ * Pattern reference:
+ * - P101.06/07 (client-side file reader + hook pattern)
+ * - P63.01 (UTF-8 BOM defense)
+ * - P103.06 (CRLF normalization)
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Relative path from project root to consumer policy file.
+ * Consumer copies `architecture-policy.template.json` (from repo root) to
+ * this path and edits.
+ */
+export const POLICY_FILE_PATH = '.neocortex/architecture-policy.json';
+// Frozen canonical enum sets mirroring JSON Schema (core/data/architecture-policy-schema.json).
+// Kept in sync with SSoT types in @neocortex/shared/types/architecture-policy.ts.
+const VALID_MODES = Object.freeze([
+    'interactive',
+    'yoloop_friendly',
+    'fully_automated',
+]);
+const VALID_CLOUD_PROVIDERS = Object.freeze(['aws', 'gcp', 'oci', 'azure', 'any']);
+const VALID_API_STYLES = Object.freeze(['REST', 'GraphQL', 'tRPC']);
+const VALID_INTEGRATION_STYLES = Object.freeze(['sync', 'async', 'hybrid']);
+const VALID_UI_PRIORITIES = Object.freeze(['mobile-first', 'desktop-first', 'responsive']);
+const VALID_REFACTOR_AGGRESSIVENESS = Object.freeze(['conservative', 'balanced', 'aggressive']);
+const VALID_TEST_WORKFLOWS = Object.freeze(['TDD', 'test-after', 'BDD']);
+/** Known optional default field names per ArchitectureDefaults interface. */
+const KNOWN_DEFAULT_FIELDS = new Set([
+    'primary_persona',
+    'cloud_provider',
+    'api_style',
+    'integration_style',
+    'ui_priority',
+    'refactor_aggressiveness',
+    'test_workflow',
+]);
+/**
+ * Pure function validator. Zero I/O. Deterministic.
+ *
+ * Returns `ArchitecturePolicyValidationResult` with:
+ * - `valid: true` iff all required fields correct and no hard errors
+ * - `errors`: hard failures (schema version mismatch, bad mode, type errors)
+ * - `warnings`: soft issues (unknown optional fields -- forward-compat)
+ */
+export function validatePolicy(candidate) {
+    const errors = [];
+    const warnings = [];
+    if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate)) {
+        return {
+            valid: false,
+            errors: Object.freeze(['Policy must be a plain object']),
+            warnings: Object.freeze([]),
+        };
+    }
+    const c = candidate;
+    // schema_version: must be literal 1
+    if (c.schema_version !== 1) {
+        errors.push(`schema_version must be 1, got ${JSON.stringify(c.schema_version)}`);
+    }
+    // mode: must be one of 3 valid values
+    if (typeof c.mode !== 'string' || !VALID_MODES.includes(c.mode)) {
+        errors.push(`mode must be one of [${VALID_MODES.join(', ')}], got ${JSON.stringify(c.mode)}`);
+    }
+    // defaults: optional object, each field must match its enum (or null/undefined)
+    if (c.defaults !== undefined && c.defaults !== null) {
+        if (typeof c.defaults !== 'object' || Array.isArray(c.defaults)) {
+            errors.push('defaults must be an object');
+        }
+        else {
+            const defaults = c.defaults;
+            // Unknown-field warnings (forward-compat: future versions may add fields)
+            for (const key of Object.keys(defaults)) {
+                if (!KNOWN_DEFAULT_FIELDS.has(key)) {
+                    warnings.push(`defaults.${key}: unknown field (ignored)`);
+                }
+            }
+            // Per-field value validation (null is allowed -- means "unset", asks human)
+            if (defaults.primary_persona !== undefined &&
+                defaults.primary_persona !== null &&
+                typeof defaults.primary_persona !== 'string') {
+                errors.push(`defaults.primary_persona must be string or null`);
+            }
+            validateEnumField(defaults, 'cloud_provider', VALID_CLOUD_PROVIDERS, errors);
+            validateEnumField(defaults, 'api_style', VALID_API_STYLES, errors);
+            validateEnumField(defaults, 'integration_style', VALID_INTEGRATION_STYLES, errors);
+            validateEnumField(defaults, 'ui_priority', VALID_UI_PRIORITIES, errors);
+            validateEnumField(defaults, 'refactor_aggressiveness', VALID_REFACTOR_AGGRESSIVENESS, errors);
+            validateEnumField(defaults, 'test_workflow', VALID_TEST_WORKFLOWS, errors);
+        }
+    }
+    // preserved_interactions: optional array of strings
+    if (c.preserved_interactions !== undefined && c.preserved_interactions !== null) {
+        if (!Array.isArray(c.preserved_interactions) ||
+            !c.preserved_interactions.every((s) => typeof s === 'string')) {
+            errors.push('preserved_interactions must be array of strings');
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors: Object.freeze(errors),
+        warnings: Object.freeze(warnings),
+    };
+}
+/**
+ * Async reader. NEVER throws.
+ *
+ * Returns `undefined` when:
+ * - file does not exist (ENOENT; silent, expected default)
+ * - permission denied (EACCES; warns stderr)
+ * - malformed JSON (warns stderr with path)
+ * - schema invalid (warns stderr with error list)
+ *
+ * Returns typed `ArchitecturePolicy` on full success.
+ */
+export async function readArchitecturePolicy(projectRoot) {
+    const absPath = join(projectRoot, POLICY_FILE_PATH);
+    let raw;
+    try {
+        raw = await readFile(absPath, 'utf8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            // Silent: file absent is the expected default.
+            return undefined;
+        }
+        const msg = err.message ?? String(err);
+        // Defensive warn -- operational issue (permission, etc).
+        // eslint-disable-next-line no-console
+        console.warn(`[Neocortex] architecture-policy read failed (${absPath}): ${msg}`);
+        return undefined;
+    }
+    // Encoding normalization (P63 BOM + P103 CRLF patterns).
+    // eslint-disable-next-line no-misleading-character-class
+    const normalized = raw.replace(/^/, '').replace(/\r\n/g, '\n');
+    let parsed;
+    try {
+        parsed = JSON.parse(normalized);
+    }
+    catch (err) {
+        const msg = err.message ?? String(err);
+        // eslint-disable-next-line no-console
+        console.warn(`[Neocortex] architecture-policy malformed JSON (${absPath}): ${msg}. Proceeding without policy.`);
+        return undefined;
+    }
+    const result = validatePolicy(parsed);
+    if (!result.valid) {
+        // eslint-disable-next-line no-console
+        console.warn(`[Neocortex] architecture-policy schema invalid (${absPath}): ${result.errors.join('; ')}. Proceeding without policy.`);
+        return undefined;
+    }
+    return parsed;
+}
+// ── Internal helpers ──────────────────────────────────────────────────────
+function validateEnumField(defaults, field, validValues, errors) {
+    const val = defaults[field];
+    if (val === undefined || val === null)
+        return; // unset is OK
+    if (typeof val !== 'string' || !validValues.includes(val)) {
+        errors.push(`defaults.${field} must be one of [${validValues.join(', ')}] or null, got ${JSON.stringify(val)}`);
+    }
+}

package/packages/client/dist/policy/index.js

@@ -1 +1,7 @@
-import{readArchitecturePolicy as c,validatePolicy as i,POLICY_FILE_PATH as o}from"./architecture-policy.js";export{o as POLICY_FILE_PATH,c as readArchitecturePolicy,i as validatePolicy};
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * Barrel export for Epic P107.02 policy reader module.
+ */
+export { readArchitecturePolicy, validatePolicy, POLICY_FILE_PATH, } from './architecture-policy.js';

package/packages/client/dist/policy/shared-policy-types.js

@@ -0,0 +1,38 @@
+/**
+ * P119.02: Inlined byte-identical types from
+ * `@neocortex/shared/types/architecture-policy`.
+ *
+ * SSoT-Shadow pattern (P92.01 server precedent extended by P117.01 to client
+ * checkpoint dist + P117.07 to client yoloop dist). Client tarball is published
+ * standalone via `@ornexus/neocortex` and does NOT include `@neocortex/shared`
+ * as a runtime dependency (workspace package, excluded from tarball per
+ * `.npmignore` + `tsconfig.build.json`). Any non-erased import of
+ * `@neocortex/shared` in `packages/client/dist/**` causes runtime
+ * `ERR_MODULE_NOT_FOUND` on globally installed `@ornexus/neocortex`.
+ *
+ * Pre-P119.02, three files leaked `import type` statements from
+ * `@neocortex/shared` in the published v4.19.1 tarball:
+ *   - dist/policy/architecture-policy.d.ts
+ *   - dist/policy/index.d.ts
+ *   - dist/commands/invoke.d.ts (imported `YoloopPersistedState`)
+ *
+ * Type-only `import type` is erased at runtime (no module resolution attempt),
+ * but produces TS2307 in consumer projects that try to use the types via
+ * globally-installed CLI (`npm install -g @ornexus/neocortex`).
+ *
+ * Sync responsibility: `policy-shared-sync.test.ts` (client-side drift test,
+ * mirror of `checkpoint-shared-sync.test.ts` P117.01). Drift test fails CI
+ * if these diverge from SSoT canonical at
+ * `packages/shared/src/types/architecture-policy.ts`.
+ *
+ * Defense-in-depth: `validate-pre-publish.js` ships
+ * `validateClientNoSharedImport()` (P117.01) scanning client dist for
+ * `@neocortex/shared` runtime references. P119.02 expands its scope to also
+ * walk `dist/policy/` and `dist/commands/` (in addition to checkpoint + yoloop
+ * coverage from P117).
+ *
+ * DO NOT EDIT WITHOUT also editing
+ * `packages/shared/src/types/architecture-policy.ts`.
+ */
+export {};
+// === END P119.02 ===