@ornexus/neocortex 4.60.72 → 4.60.73

package/packages/client/dist/migrations/project-identity-capability.js

@@ -1 +1,50 @@
-import{PROJECT_IDENTITY_MIGRATION_CAPABILITY as u}from"../../../shared/dist/invocation/index.js";const l=16*1024;async function f(p,t=globalThis.fetch){if(!t)return{supported:!1,reason:"fetch-unavailable",publicSafe:!0};const a=new AbortController,s=setTimeout(()=>a.abort(),5e3);s.unref?.();try{const o=await t(`${p.replace(/\/+$/,"")}/api/v1/config`,{method:"GET",headers:{accept:"application/json"},signal:a.signal});if(!o.ok)return{supported:!1,reason:"http-rejected",publicSafe:!0};const i=await o.text();if(Buffer.byteLength(i,"utf8")>l)return{supported:!1,reason:"response-too-large",publicSafe:!0};let e;try{e=JSON.parse(i)}catch{return{supported:!1,reason:"response-invalid",publicSafe:!0}}if(!e||typeof e!="object"||Array.isArray(e))return{supported:!1,reason:"response-invalid",publicSafe:!0};const r=e.capabilities;return!Array.isArray(r)||r.some(n=>typeof n!="string"||n.length>80)?{supported:!1,reason:"response-invalid",publicSafe:!0}:r.includes(u)?{supported:!0,reason:"supported",publicSafe:!0}:{supported:!1,reason:"capability-missing",publicSafe:!0}}catch{return{supported:!1,reason:"request-failed",publicSafe:!0}}finally{clearTimeout(s)}}export{f as probeProjectIdentityMigrationCapability};
+import { PROJECT_IDENTITY_MIGRATION_CAPABILITY } from '../../../shared/dist/invocation/index.js';
+const MAX_CAPABILITY_RESPONSE_BYTES = 16 * 1024;
+/**
+ * Fail-closed, non-mutating rollout probe. An older server cannot cause the
+ * client to persist a local project ID that has no remote floor authority.
+ */
+export async function probeProjectIdentityMigrationCapability(serverUrl, fetcher = globalThis.fetch) {
+    if (!fetcher)
+        return { supported: false, reason: 'fetch-unavailable', publicSafe: true };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5_000);
+    timeout.unref?.();
+    try {
+        const response = await fetcher(`${serverUrl.replace(/\/+$/, '')}/api/v1/config`, {
+            method: 'GET',
+            headers: { accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return { supported: false, reason: 'http-rejected', publicSafe: true };
+        const raw = await response.text();
+        if (Buffer.byteLength(raw, 'utf8') > MAX_CAPABILITY_RESPONSE_BYTES) {
+            return { supported: false, reason: 'response-too-large', publicSafe: true };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return { supported: false, reason: 'response-invalid', publicSafe: true };
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { supported: false, reason: 'response-invalid', publicSafe: true };
+        }
+        const capabilities = parsed.capabilities;
+        if (!Array.isArray(capabilities)
+            || capabilities.some((value) => typeof value !== 'string' || value.length > 80)) {
+            return { supported: false, reason: 'response-invalid', publicSafe: true };
+        }
+        return capabilities.includes(PROJECT_IDENTITY_MIGRATION_CAPABILITY)
+            ? { supported: true, reason: 'supported', publicSafe: true }
+            : { supported: false, reason: 'capability-missing', publicSafe: true };
+    }
+    catch {
+        return { supported: false, reason: 'request-failed', publicSafe: true };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/packages/client/dist/migrations/project-identity.js

@@ -1,7 +1,493 @@
-import{createHash as tt,randomUUID as M}from"node:crypto";import{existsSync as I,linkSync as et,lstatSync as R,mkdirSync as rt,readFileSync as T,realpathSync as nt,statSync as ot,unlinkSync as w}from"node:fs";import{dirname as f,join as a,relative as V,resolve as it}from"node:path";import{assertProjectIdentityMigrationReceiptV1 as Y,PROJECT_ID_PATTERN as z}from"../../../shared/dist/invocation/index.js";import{atomicReplaceUtf8 as d,durableCreateUtf8 as b,fsyncDirectoryBestEffort as l,recoverAtomicReplaceUtf8 as q}from"../fs/atomic-state-replace.js";const Ot=1,E=a(".neocortex","state.json"),u=a(".neocortex","project-identity-migration.json"),ct=a(".neocortex","project-identity-migration.lock"),at=/^\.neocortex[\\/]state\.json\.project-identity-backup-(?:\d{8}T\d{9}Z-)?mig_[a-f0-9]{32}$/;class o extends Error{code;constructor(r,t=r){super(t),this.code=r,this.name="ProjectIdentityMigrationError"}}const p=n=>tt("sha256").update(n).digest("hex");function st(){return`prj_${M().replaceAll("-","")}`}function H(){return`mig_${M().replaceAll("-","")}`}function Q(n){return n.toISOString().replace(/[-:.]/g,"")}function O(n){const r=it(n);let t;try{t=nt(r)}catch{throw new o("PROJECT_IDENTITY_ROOT_INVALID")}if(!ot(t).isDirectory())throw new o("PROJECT_IDENTITY_ROOT_INVALID");const e=a(t,".neocortex");if(I(e)&&R(e).isSymbolicLink())throw new o("PROJECT_IDENTITY_SYMLINK_REJECTED");const i=a(t,E);if(I(i)){const s=R(i);if(s.isSymbolicLink()||!s.isFile())throw new o("PROJECT_IDENTITY_SYMLINK_REJECTED")}const c=a(t,u);if(I(c)){const s=R(c);if(s.isSymbolicLink()||!s.isFile())throw new o("PROJECT_IDENTITY_SYMLINK_REJECTED")}return t}function S(n,r){const t=a(n,ct);rt(f(t),{recursive:!0,mode:448});const e=()=>{const i=`${t}.${process.pid}.${M()}.owner`;b(i,`${process.pid}
-`);try{et(i,t),l(f(t))}finally{try{w(i)}catch{}l(f(t))}};try{e()}catch(i){if(i.code!=="EEXIST")throw new o("PROJECT_IDENTITY_MIGRATION_LOCKED");const c=R(t);if(c.isSymbolicLink()||!c.isFile())throw new o("PROJECT_IDENTITY_SYMLINK_REJECTED");const s=T(t,"utf8");if(!/^[1-9][0-9]*\n$/.test(s)||s.length>24)throw new o("PROJECT_IDENTITY_MIGRATION_LOCK_CORRUPT");const _=Number(s.trim());let C=!0;try{process.kill(_,0)}catch(g){C=g.code!=="ESRCH"}if(C)throw new o("PROJECT_IDENTITY_MIGRATION_LOCKED");try{w(t),l(f(t)),e()}catch{throw new o("PROJECT_IDENTITY_MIGRATION_LOCKED")}}try{return r()}finally{try{w(t),l(f(t))}catch{}}}function y(n){let r;try{r=JSON.parse(n)}catch{throw new o("PROJECT_IDENTITY_STATE_CORRUPT")}if(!r||typeof r!="object"||Array.isArray(r))throw new o("PROJECT_IDENTITY_STATE_CORRUPT");return r}function A(n){const r=a(n,u);try{q(r),q(a(n,E))}catch{throw new o("PROJECT_IDENTITY_ATOMIC_RECOVERY_FAILED")}if(!I(r))return null;let t;try{t=JSON.parse(T(r,"utf8"))}catch{throw new o("PROJECT_IDENTITY_MIGRATION_STATE_CORRUPT")}if(!t||typeof t!="object"||Array.isArray(t))throw new o("PROJECT_IDENTITY_MIGRATION_STATE_CORRUPT");const e=t;if(e.schemaVersion!==1||typeof e.operationId!="string"||!/^mig_[a-f0-9]{32}$/.test(e.operationId)||typeof e.projectId!="string"||!z.test(e.projectId)||!["prepared","remote-acknowledged","finalized"].includes(String(e.phase))||!Number.isSafeInteger(e.legacyEpicFloor)||(e.legacyEpicFloor??-1)<0||typeof e.originalStateExists!="boolean"||typeof e.originalStateDigest!="string"||!/^[a-f0-9]{64}$/.test(e.originalStateDigest)||typeof e.preparedStateDigest!="string"||!/^[a-f0-9]{64}$/.test(e.preparedStateDigest)||e.backupPath!==null&&(typeof e.backupPath!="string"||!at.test(e.backupPath))||typeof e.createdAt!="string"||typeof e.updatedAt!="string")throw new o("PROJECT_IDENTITY_MIGRATION_STATE_CORRUPT");e.receipt!==void 0&&Y(e.receipt);const i=e.phase==="remote-acknowledged"||e.phase==="finalized";if(e.phase==="prepared"&&e.receipt!==void 0||i&&e.receipt===void 0||e.receipt!==void 0&&(e.receipt.operationId!==e.operationId||e.receipt.projectId!==e.projectId||e.receipt.acceptedLegacyFloor<e.legacyEpicFloor))throw new o("PROJECT_IDENTITY_MIGRATION_STATE_CORRUPT");return e}function It(n){const r=[];n.epics&&typeof n.epics=="object"&&!Array.isArray(n.epics)&&r.push(...Object.keys(n.epics));const t=n.epic_id_ledger;if(t&&typeof t=="object"&&!Array.isArray(t)){const e=t.reserved_ids;Array.isArray(e)&&r.push(...e.filter(i=>typeof i=="string"))}return r.reduce((e,i)=>{const c=i.match(/^P?(\d+)$/i);if(!c)return e;const s=Number(c[1]);return Number.isSafeInteger(s)?Math.max(e,s):e},0)}function N(n){return{version:1,operationId:n.operationId,projectId:n.projectId,localStateDigest:n.preparedStateDigest,legacyEpicFloor:n.legacyEpicFloor,phase:"seed"}}function k(n,r){const t=y(n),e=G(t),i=t[e]??{};return t[e]={...i,project_id:r},t.schema_version===void 0&&(t.schema_version=1),(!t.stories||typeof t.stories!="object"||Array.isArray(t.stories))&&(t.stories={}),(!t.epics||typeof t.epics!="object"||Array.isArray(t.epics))&&(t.epics={}),{raw:`${JSON.stringify(t,null,2)}
-`,state:t}}function G(n){return n.config&&typeof n.config=="object"&&!Array.isArray(n.config)?"config":n.project&&typeof n.project=="object"&&!Array.isArray(n.project)?"project":"config"}function x(n){const r=n[G(n)];return r&&typeof r=="object"&&!Array.isArray(r)?r.project_id:void 0}function W(n,r){if(!I(n))throw new o("PROJECT_IDENTITY_MIGRATION_STATE_DRIFT");const t=y(T(n,"utf8"));if(x(t)!==r.projectId)throw new o("PROJECT_IDENTITY_MIGRATION_STATE_DRIFT")}function Tt(n,r,t,e){const i=y(t),c=x(i);if(c===e.projectId)return;if(c!==void 0)throw new o("PROJECT_IDENTITY_MIGRATION_STATE_DRIFT");const _=a(n,".neocortex",`state.json.project-identity-reconcile-backup-${Q(new Date)}-${H()}`);b(_,t),d(r,k(t,e.projectId).raw)}function X(){return`${JSON.stringify({schema_version:1,config:{project_name:"neocortex-project",default_branch:"main",language:"pt-BR"},stories:{},epics:{}},null,2)}
-`}function pt(n,r){if(!r.originalStateExists)return;if(!r.backupPath)throw new o("PROJECT_IDENTITY_MIGRATION_BACKUP_MISSING");const t=a(n,r.backupPath);if(!I(t))throw new o("PROJECT_IDENTITY_MIGRATION_BACKUP_MISSING");const e=R(t);if(e.isSymbolicLink()||!e.isFile())throw new o("PROJECT_IDENTITY_SYMLINK_REJECTED");if(p(T(t))!==r.originalStateDigest)throw new o("PROJECT_IDENTITY_MIGRATION_BACKUP_CORRUPT")}function gt(n){const r=O(n);return S(r,()=>{const t=A(r);if(t){const h=a(r,E);pt(r,t);const D=I(h),P=D?T(h,"utf8"):null,v=P===null?null:p(P);if(v===t.preparedStateDigest)return{changed:!1,document:t,request:N(t)};if(t.phase==="finalized"&&P!==null)return x(y(P))===t.projectId?{changed:!1,document:t,request:N(t)}:(Tt(r,h,P,t),{changed:!0,document:t,request:N(t)});if(!(t.phase==="prepared"&&(D&&v===t.originalStateDigest||!D&&!t.originalStateExists)))throw new o("PROJECT_IDENTITY_MIGRATION_STATE_DRIFT");const Z=D?T(h,"utf8"):X(),B=k(Z,t.projectId).raw;if(p(B)!==t.preparedStateDigest)throw new o("PROJECT_IDENTITY_MIGRATION_STATE_DRIFT");return d(h,B),{changed:!0,document:t,request:N(t)}}const e=a(r,E),i=I(e),c=i?T(e,"utf8"):X(),s=y(c),_=G(s),g=(s[_]??{}).project_id,F=typeof g=="string"&&z.test(g)?g:st(),L=k(c,F),j=L.raw,K=H(),U=new Date,m=i?a(".neocortex",`state.json.project-identity-backup-${Q(U)}-${K}`):null;m&&b(a(r,m),c);const $=U.toISOString(),J={schemaVersion:1,operationId:K,projectId:F,phase:"prepared",legacyEpicFloor:It(L.state),originalStateExists:i,originalStateDigest:p(c),preparedStateDigest:p(j),backupPath:m,createdAt:$,updatedAt:$};return d(a(r,u),`${JSON.stringify(J,null,2)}
-`),d(e,j),{changed:j!==c,document:J,request:N(J)}})}function ht(n,r){Y(r);const t=O(n);return S(t,()=>{const e=A(t);if(!e)throw new o("PROJECT_IDENTITY_MIGRATION_NOT_PREPARED");if(e.operationId!==r.operationId||e.projectId!==r.projectId)throw new o("PROJECT_IDENTITY_MIGRATION_RECEIPT_CONFLICT");const i=a(t,E);if(e.phase==="finalized"){if(!e.receipt||e.receipt.receiptDigest!==r.receiptDigest)throw new o("PROJECT_IDENTITY_MIGRATION_ACK_REQUIRED");return W(i,e),e}if(!I(i)||p(T(i))!==e.preparedStateDigest)throw new o("PROJECT_IDENTITY_MIGRATION_STATE_DRIFT");if(e.phase==="prepared"||!e.receipt||e.receipt.receiptDigest!==r.receiptDigest)throw new o("PROJECT_IDENTITY_MIGRATION_ACK_REQUIRED");const c={...e,phase:"finalized",updatedAt:new Date().toISOString(),receipt:r};return d(a(t,u),`${JSON.stringify(c,null,2)}
-`),c})}function Pt(n,r){Y(r);const t=O(n);return S(t,()=>{const e=A(t);if(!e)throw new o("PROJECT_IDENTITY_MIGRATION_NOT_PREPARED");if(e.operationId!==r.operationId||e.projectId!==r.projectId)throw new o("PROJECT_IDENTITY_MIGRATION_RECEIPT_CONFLICT");if(e.receipt&&e.receipt.receiptDigest!==r.receiptDigest)throw new o("PROJECT_IDENTITY_MIGRATION_RECEIPT_CONFLICT");const i=a(t,E);if(e.phase==="finalized")return W(i,e),e;if(!I(i)||p(T(i))!==e.preparedStateDigest)throw new o("PROJECT_IDENTITY_MIGRATION_STATE_DRIFT");if(e.phase==="remote-acknowledged")return e;const c={...e,phase:"remote-acknowledged",updatedAt:new Date().toISOString(),receipt:r};return d(a(t,u),`${JSON.stringify(c,null,2)}
-`),c})}function wt(n){const r=O(n);S(r,()=>{const t=A(r);if(!t)return;if(t.phase!=="prepared"||t.receipt)throw new o("PROJECT_IDENTITY_MIGRATION_ROLLBACK_AFTER_ACK_DENIED");const e=a(r,E);if(!I(e)||p(T(e))!==t.preparedStateDigest)throw new o("PROJECT_IDENTITY_MIGRATION_STATE_DRIFT");if(t.originalStateExists){if(!t.backupPath)throw new o("PROJECT_IDENTITY_MIGRATION_BACKUP_MISSING");const c=a(r,t.backupPath);if(!I(c))throw new o("PROJECT_IDENTITY_MIGRATION_BACKUP_MISSING");const s=R(c);if(s.isSymbolicLink()||!s.isFile())throw new o("PROJECT_IDENTITY_SYMLINK_REJECTED");const _=T(c,"utf8");if(p(_)!==t.originalStateDigest)throw new o("PROJECT_IDENTITY_MIGRATION_BACKUP_CORRUPT");d(e,_)}else w(e),l(f(e));const i=a(r,u);w(i),l(f(i))})}function yt(n){const r=O(n);return A(r)?.phase??null}function At(n){const r=O(n);return{state:V(r,a(r,E)),migration:V(r,a(r,u))}}export{o as ProjectIdentityMigrationError,Pt as acknowledgeProjectIdentityMigration,ht as finalizeProjectIdentityMigration,gt as prepareProjectIdentityMigration,At as projectIdentityMigrationRelativePaths,yt as readProjectIdentityMigrationPhase,wt as rollbackPreparedProjectIdentityMigration};
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync, } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { assertProjectIdentityMigrationReceiptV1, PROJECT_ID_PATTERN, } from '../../../shared/dist/invocation/index.js';
+import { atomicReplaceUtf8, durableCreateUtf8, fsyncDirectoryBestEffort, recoverAtomicReplaceUtf8, } from '../fs/atomic-state-replace.js';
+const MIGRATION_SCHEMA_VERSION = 1;
+const STATE_RELATIVE_PATH = join('.neocortex', 'state.json');
+const MIGRATION_RELATIVE_PATH = join('.neocortex', 'project-identity-migration.json');
+const LOCK_RELATIVE_PATH = join('.neocortex', 'project-identity-migration.lock');
+const BACKUP_PATH_PATTERN = /^\.neocortex[\\/]state\.json\.project-identity-backup-(?:\d{8}T\d{9}Z-)?mig_[a-f0-9]{32}$/;
+export class ProjectIdentityMigrationError extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+        this.name = 'ProjectIdentityMigrationError';
+    }
+}
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+function projectId() {
+    return `prj_${randomUUID().replaceAll('-', '')}`;
+}
+function operationId() {
+    return `mig_${randomUUID().replaceAll('-', '')}`;
+}
+function backupTimestamp(date) {
+    return date.toISOString().replace(/[-:.]/g, '');
+}
+function assertSafeProjectRoot(projectRoot) {
+    const resolved = resolve(projectRoot);
+    let canonical;
+    try {
+        canonical = realpathSync(resolved);
+    }
+    catch {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_ROOT_INVALID');
+    }
+    if (!statSync(canonical).isDirectory()) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_ROOT_INVALID');
+    }
+    const ncPath = join(canonical, '.neocortex');
+    if (existsSync(ncPath) && lstatSync(ncPath).isSymbolicLink()) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_SYMLINK_REJECTED');
+    }
+    const statePath = join(canonical, STATE_RELATIVE_PATH);
+    if (existsSync(statePath)) {
+        const stateStat = lstatSync(statePath);
+        if (stateStat.isSymbolicLink() || !stateStat.isFile()) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_SYMLINK_REJECTED');
+        }
+    }
+    const migrationPath = join(canonical, MIGRATION_RELATIVE_PATH);
+    if (existsSync(migrationPath)) {
+        const migrationStat = lstatSync(migrationPath);
+        if (migrationStat.isSymbolicLink() || !migrationStat.isFile()) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_SYMLINK_REJECTED');
+        }
+    }
+    return canonical;
+}
+function withMigrationLock(root, operation) {
+    const lockPath = join(root, LOCK_RELATIVE_PATH);
+    mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+    const claimLock = () => {
+        const ownerPath = `${lockPath}.${process.pid}.${randomUUID()}.owner`;
+        durableCreateUtf8(ownerPath, `${process.pid}\n`);
+        try {
+            // The hard link is an atomic no-overwrite claim. Because its source was
+            // fsynced first, a canonical lock can never exist with empty metadata.
+            linkSync(ownerPath, lockPath);
+            fsyncDirectoryBestEffort(dirname(lockPath));
+        }
+        finally {
+            try {
+                unlinkSync(ownerPath);
+            }
+            catch { /* orphan owner files do not grant the lock */ }
+            fsyncDirectoryBestEffort(dirname(lockPath));
+        }
+    };
+    try {
+        claimLock();
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST') {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_LOCKED');
+        }
+        const lockStat = lstatSync(lockPath);
+        if (lockStat.isSymbolicLink() || !lockStat.isFile()) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_SYMLINK_REJECTED');
+        }
+        const rawOwner = readFileSync(lockPath, 'utf8');
+        if (!/^[1-9][0-9]*\n$/.test(rawOwner) || rawOwner.length > 24) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_LOCK_CORRUPT');
+        }
+        const ownerPid = Number(rawOwner.trim());
+        let ownerAlive = true;
+        try {
+            process.kill(ownerPid, 0);
+        }
+        catch (probeError) {
+            ownerAlive = probeError.code !== 'ESRCH';
+        }
+        if (ownerAlive)
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_LOCKED');
+        try {
+            unlinkSync(lockPath);
+            fsyncDirectoryBestEffort(dirname(lockPath));
+            claimLock();
+        }
+        catch {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_LOCKED');
+        }
+    }
+    try {
+        return operation();
+    }
+    finally {
+        try {
+            unlinkSync(lockPath);
+            fsyncDirectoryBestEffort(dirname(lockPath));
+        }
+        catch { /* lock cleanup is best effort */ }
+    }
+}
+function parseState(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_STATE_CORRUPT');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_STATE_CORRUPT');
+    }
+    return parsed;
+}
+function readDocument(root) {
+    const path = join(root, MIGRATION_RELATIVE_PATH);
+    try {
+        recoverAtomicReplaceUtf8(path);
+        recoverAtomicReplaceUtf8(join(root, STATE_RELATIVE_PATH));
+    }
+    catch {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_ATOMIC_RECOVERY_FAILED');
+    }
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_CORRUPT');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_CORRUPT');
+    }
+    const document = parsed;
+    if (document.schemaVersion !== 1
+        || typeof document.operationId !== 'string'
+        || !/^mig_[a-f0-9]{32}$/.test(document.operationId)
+        || typeof document.projectId !== 'string'
+        || !PROJECT_ID_PATTERN.test(document.projectId)
+        || !['prepared', 'remote-acknowledged', 'finalized'].includes(String(document.phase))
+        || !Number.isSafeInteger(document.legacyEpicFloor)
+        || (document.legacyEpicFloor ?? -1) < 0
+        || typeof document.originalStateExists !== 'boolean'
+        || typeof document.originalStateDigest !== 'string'
+        || !/^[a-f0-9]{64}$/.test(document.originalStateDigest)
+        || typeof document.preparedStateDigest !== 'string'
+        || !/^[a-f0-9]{64}$/.test(document.preparedStateDigest)
+        || (document.backupPath !== null
+            && (typeof document.backupPath !== 'string' || !BACKUP_PATH_PATTERN.test(document.backupPath)))
+        || typeof document.createdAt !== 'string'
+        || typeof document.updatedAt !== 'string') {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_CORRUPT');
+    }
+    if (document.receipt !== undefined)
+        assertProjectIdentityMigrationReceiptV1(document.receipt);
+    const phaseRequiresReceipt = document.phase === 'remote-acknowledged' || document.phase === 'finalized';
+    if ((document.phase === 'prepared' && document.receipt !== undefined)
+        || (phaseRequiresReceipt && document.receipt === undefined)
+        || (document.receipt !== undefined
+            && (document.receipt.operationId !== document.operationId
+                || document.receipt.projectId !== document.projectId
+                || document.receipt.acceptedLegacyFloor < document.legacyEpicFloor))) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_CORRUPT');
+    }
+    return document;
+}
+function legacyEpicFloor(state) {
+    const candidates = [];
+    if (state.epics && typeof state.epics === 'object' && !Array.isArray(state.epics)) {
+        candidates.push(...Object.keys(state.epics));
+    }
+    const ledger = state.epic_id_ledger;
+    if (ledger && typeof ledger === 'object' && !Array.isArray(ledger)) {
+        const ids = ledger.reserved_ids;
+        if (Array.isArray(ids))
+            candidates.push(...ids.filter((value) => typeof value === 'string'));
+    }
+    return candidates.reduce((floor, candidate) => {
+        const match = candidate.match(/^P?(\d+)$/i);
+        if (!match)
+            return floor;
+        const value = Number(match[1]);
+        return Number.isSafeInteger(value) ? Math.max(floor, value) : floor;
+    }, 0);
+}
+function requestFor(document) {
+    return {
+        version: 1,
+        operationId: document.operationId,
+        projectId: document.projectId,
+        localStateDigest: document.preparedStateDigest,
+        legacyEpicFloor: document.legacyEpicFloor,
+        phase: 'seed',
+    };
+}
+function stateWithProjectIdentity(raw, identity) {
+    const state = parseState(raw);
+    const configKey = projectIdentityContainerKey(state);
+    const config = (state[configKey] ?? {});
+    state[configKey] = { ...config, project_id: identity };
+    if (state.schema_version === undefined)
+        state.schema_version = 1;
+    if (!state.stories || typeof state.stories !== 'object' || Array.isArray(state.stories))
+        state.stories = {};
+    if (!state.epics || typeof state.epics !== 'object' || Array.isArray(state.epics))
+        state.epics = {};
+    return { raw: `${JSON.stringify(state, null, 2)}\n`, state };
+}
+function projectIdentityContainerKey(state) {
+    return state.config && typeof state.config === 'object' && !Array.isArray(state.config)
+        ? 'config'
+        : state.project && typeof state.project === 'object' && !Array.isArray(state.project)
+            ? 'project'
+            : 'config';
+}
+function projectIdentityFromState(state) {
+    const container = state[projectIdentityContainerKey(state)];
+    return container && typeof container === 'object' && !Array.isArray(container)
+        ? container.project_id
+        : undefined;
+}
+function assertFinalizedStateIdentity(statePath, document) {
+    if (!existsSync(statePath)) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_DRIFT');
+    }
+    const state = parseState(readFileSync(statePath, 'utf8'));
+    if (projectIdentityFromState(state) !== document.projectId) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_DRIFT');
+    }
+}
+function reconcileFinalizedStateIdentity(root, statePath, currentRaw, document) {
+    const state = parseState(currentRaw);
+    const currentProjectId = projectIdentityFromState(state);
+    if (currentProjectId === document.projectId)
+        return;
+    if (currentProjectId !== undefined) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_DRIFT');
+    }
+    const now = new Date();
+    const recoveryBackup = join(root, '.neocortex', `state.json.project-identity-reconcile-backup-${backupTimestamp(now)}-${operationId()}`);
+    durableCreateUtf8(recoveryBackup, currentRaw);
+    atomicReplaceUtf8(statePath, stateWithProjectIdentity(currentRaw, document.projectId).raw);
+}
+function defaultStateRaw() {
+    return `${JSON.stringify({
+        schema_version: 1,
+        config: { project_name: 'neocortex-project', default_branch: 'main', language: 'pt-BR' },
+        stories: {},
+        epics: {},
+    }, null, 2)}\n`;
+}
+function verifyBackup(root, document) {
+    if (!document.originalStateExists)
+        return;
+    if (!document.backupPath) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_BACKUP_MISSING');
+    }
+    const backup = join(root, document.backupPath);
+    if (!existsSync(backup)) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_BACKUP_MISSING');
+    }
+    const backupStat = lstatSync(backup);
+    if (backupStat.isSymbolicLink() || !backupStat.isFile()) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_SYMLINK_REJECTED');
+    }
+    if (sha256(readFileSync(backup)) !== document.originalStateDigest) {
+        throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_BACKUP_CORRUPT');
+    }
+}
+export function prepareProjectIdentityMigration(projectRoot) {
+    const root = assertSafeProjectRoot(projectRoot);
+    return withMigrationLock(root, () => {
+        const existingDocument = readDocument(root);
+        if (existingDocument) {
+            const statePath = join(root, STATE_RELATIVE_PATH);
+            verifyBackup(root, existingDocument);
+            const stateExists = existsSync(statePath);
+            const currentRaw = stateExists ? readFileSync(statePath, 'utf8') : null;
+            const currentDigest = currentRaw === null ? null : sha256(currentRaw);
+            if (currentDigest === existingDocument.preparedStateDigest) {
+                return { changed: false, document: existingDocument, request: requestFor(existingDocument) };
+            }
+            if (existingDocument.phase === 'finalized' && currentRaw !== null) {
+                const currentProjectId = projectIdentityFromState(parseState(currentRaw));
+                if (currentProjectId === existingDocument.projectId) {
+                    return { changed: false, document: existingDocument, request: requestFor(existingDocument) };
+                }
+                reconcileFinalizedStateIdentity(root, statePath, currentRaw, existingDocument);
+                return { changed: true, document: existingDocument, request: requestFor(existingDocument) };
+            }
+            const mayResumePrepare = existingDocument.phase === 'prepared'
+                && ((stateExists && currentDigest === existingDocument.originalStateDigest)
+                    || (!stateExists && !existingDocument.originalStateExists));
+            if (!mayResumePrepare) {
+                throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_DRIFT');
+            }
+            const originalRaw = stateExists ? readFileSync(statePath, 'utf8') : defaultStateRaw();
+            const recovered = stateWithProjectIdentity(originalRaw, existingDocument.projectId).raw;
+            if (sha256(recovered) !== existingDocument.preparedStateDigest) {
+                throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_DRIFT');
+            }
+            atomicReplaceUtf8(statePath, recovered);
+            return { changed: true, document: existingDocument, request: requestFor(existingDocument) };
+        }
+        const statePath = join(root, STATE_RELATIVE_PATH);
+        const originalStateExists = existsSync(statePath);
+        const originalRaw = originalStateExists ? readFileSync(statePath, 'utf8') : defaultStateRaw();
+        const state = parseState(originalRaw);
+        const configKey = projectIdentityContainerKey(state);
+        const config = (state[configKey] ?? {});
+        const currentProjectId = config.project_id;
+        const nextProjectId = typeof currentProjectId === 'string' && PROJECT_ID_PATTERN.test(currentProjectId)
+            ? currentProjectId
+            : projectId();
+        const preparedState = stateWithProjectIdentity(originalRaw, nextProjectId);
+        const nextRaw = preparedState.raw;
+        const nextOperationId = operationId();
+        const nowDate = new Date();
+        const backupPath = originalStateExists
+            ? join('.neocortex', `state.json.project-identity-backup-${backupTimestamp(nowDate)}-${nextOperationId}`)
+            : null;
+        if (backupPath) {
+            durableCreateUtf8(join(root, backupPath), originalRaw);
+        }
+        const now = nowDate.toISOString();
+        const document = {
+            schemaVersion: 1,
+            operationId: nextOperationId,
+            projectId: nextProjectId,
+            phase: 'prepared',
+            legacyEpicFloor: legacyEpicFloor(preparedState.state),
+            originalStateExists,
+            originalStateDigest: sha256(originalRaw),
+            preparedStateDigest: sha256(nextRaw),
+            backupPath,
+            createdAt: now,
+            updatedAt: now,
+        };
+        // Persist the recovery manifest before replacing state. If the process dies
+        // in this window, the next prepare deterministically applies the same ID.
+        atomicReplaceUtf8(join(root, MIGRATION_RELATIVE_PATH), `${JSON.stringify(document, null, 2)}\n`);
+        atomicReplaceUtf8(statePath, nextRaw);
+        return { changed: nextRaw !== originalRaw, document, request: requestFor(document) };
+    });
+}
+export function finalizeProjectIdentityMigration(projectRoot, receipt) {
+    assertProjectIdentityMigrationReceiptV1(receipt);
+    const root = assertSafeProjectRoot(projectRoot);
+    return withMigrationLock(root, () => {
+        const document = readDocument(root);
+        if (!document)
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_NOT_PREPARED');
+        if (document.operationId !== receipt.operationId || document.projectId !== receipt.projectId) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_RECEIPT_CONFLICT');
+        }
+        const statePath = join(root, STATE_RELATIVE_PATH);
+        if (document.phase === 'finalized') {
+            if (!document.receipt || document.receipt.receiptDigest !== receipt.receiptDigest) {
+                throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_ACK_REQUIRED');
+            }
+            assertFinalizedStateIdentity(statePath, document);
+            return document;
+        }
+        if (!existsSync(statePath) || sha256(readFileSync(statePath)) !== document.preparedStateDigest) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_DRIFT');
+        }
+        if (document.phase === 'prepared' || !document.receipt
+            || document.receipt.receiptDigest !== receipt.receiptDigest) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_ACK_REQUIRED');
+        }
+        const next = {
+            ...document,
+            phase: 'finalized',
+            updatedAt: new Date().toISOString(),
+            receipt,
+        };
+        atomicReplaceUtf8(join(root, MIGRATION_RELATIVE_PATH), `${JSON.stringify(next, null, 2)}\n`);
+        return next;
+    });
+}
+/** Persist the authenticated ACK before local finalization so a crash is reconcilable. */
+export function acknowledgeProjectIdentityMigration(projectRoot, receipt) {
+    assertProjectIdentityMigrationReceiptV1(receipt);
+    const root = assertSafeProjectRoot(projectRoot);
+    return withMigrationLock(root, () => {
+        const document = readDocument(root);
+        if (!document)
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_NOT_PREPARED');
+        if (document.operationId !== receipt.operationId || document.projectId !== receipt.projectId) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_RECEIPT_CONFLICT');
+        }
+        if (document.receipt && document.receipt.receiptDigest !== receipt.receiptDigest) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_RECEIPT_CONFLICT');
+        }
+        const statePath = join(root, STATE_RELATIVE_PATH);
+        if (document.phase === 'finalized') {
+            assertFinalizedStateIdentity(statePath, document);
+            return document;
+        }
+        if (!existsSync(statePath) || sha256(readFileSync(statePath)) !== document.preparedStateDigest) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_DRIFT');
+        }
+        if (document.phase === 'remote-acknowledged')
+            return document;
+        const next = {
+            ...document,
+            phase: 'remote-acknowledged',
+            updatedAt: new Date().toISOString(),
+            receipt,
+        };
+        atomicReplaceUtf8(join(root, MIGRATION_RELATIVE_PATH), `${JSON.stringify(next, null, 2)}\n`);
+        return next;
+    });
+}
+export function rollbackPreparedProjectIdentityMigration(projectRoot) {
+    const root = assertSafeProjectRoot(projectRoot);
+    withMigrationLock(root, () => {
+        const document = readDocument(root);
+        if (!document)
+            return;
+        if (document.phase !== 'prepared' || document.receipt) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_ROLLBACK_AFTER_ACK_DENIED');
+        }
+        const statePath = join(root, STATE_RELATIVE_PATH);
+        if (!existsSync(statePath) || sha256(readFileSync(statePath)) !== document.preparedStateDigest) {
+            throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_STATE_DRIFT');
+        }
+        if (document.originalStateExists) {
+            if (!document.backupPath)
+                throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_BACKUP_MISSING');
+            const backup = join(root, document.backupPath);
+            if (!existsSync(backup))
+                throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_BACKUP_MISSING');
+            const backupStat = lstatSync(backup);
+            if (backupStat.isSymbolicLink() || !backupStat.isFile()) {
+                throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_SYMLINK_REJECTED');
+            }
+            const originalRaw = readFileSync(backup, 'utf8');
+            if (sha256(originalRaw) !== document.originalStateDigest) {
+                throw new ProjectIdentityMigrationError('PROJECT_IDENTITY_MIGRATION_BACKUP_CORRUPT');
+            }
+            atomicReplaceUtf8(statePath, originalRaw);
+        }
+        else {
+            unlinkSync(statePath);
+            fsyncDirectoryBestEffort(dirname(statePath));
+        }
+        const migrationPath = join(root, MIGRATION_RELATIVE_PATH);
+        unlinkSync(migrationPath);
+        fsyncDirectoryBestEffort(dirname(migrationPath));
+    });
+}
+/**
+ * Read-only admission check used to prevent create-epic from observing the
+ * locally prepared project ID before its remote floor has been acknowledged.
+ */
+export function readProjectIdentityMigrationPhase(projectRoot) {
+    const root = assertSafeProjectRoot(projectRoot);
+    return readDocument(root)?.phase ?? null;
+}
+export function projectIdentityMigrationRelativePaths(projectRoot) {
+    const root = assertSafeProjectRoot(projectRoot);
+    return {
+        state: relative(root, join(root, STATE_RELATIVE_PATH)),
+        migration: relative(root, join(root, MIGRATION_RELATIVE_PATH)),
+    };
+}

package/packages/client/dist/migrations/state-json.d.ts

@@ -18,6 +18,13 @@ export interface StateMigrationAuthorityV1 {
     readonly plan: Omit<StateMigrationPlanV1, 'targetState'> | null;
     readonly publicSafe: true;
 }
+/** Private, complete source used by the P224 brownfield planner. */
+export interface StateMigrationSourceSnapshotV1 {
+    readonly state: Readonly<Record<string, unknown>>;
+    readonly raw: string;
+    readonly byteDigest: string;
+    readonly byteLength: number;
+}
 export declare class StateMigrationApplyError extends Error {
     readonly reasonCode: string;
     readonly receipt?: StateMigrationReceiptV1 | undefined;
@@ -29,6 +36,21 @@ export interface StateMigrationApplyHooks {
     readonly afterReplace?: (statePath: string) => void;
 }
 export declare function collectStateMigrationAuthority(projectRoot: string): StateMigrationAuthorityV1;
+export declare function readStateMigrationSourceSnapshot(projectRoot: string): StateMigrationSourceSnapshotV1;
+/**
+ * Restore one migration preimage only while both current postimage and backup
+ * bytes remain exact. This is intentionally narrower than a general reset and
+ * never removes the backup or migration history.
+ */
+export declare function restoreStateMigrationPreimage(input: {
+    readonly projectRoot: string;
+    readonly operationId: string;
+    readonly expectedCurrentDigest: string;
+    readonly expectedBackupDigest: string;
+}): {
+    readonly restoredDigest: string;
+    readonly backupPreserved: true;
+};
 export declare function previewStateMigration(projectRoot: string): StateMigrationPlanV1 | null;
 /** Apply one shared plan under a client-owned lock, byte CAS and durable backup. */
 export declare function applyStateMigration(projectRoot: string, expectedPlan?: Pick<StateMigrationPlanV1, 'operationId' | 'sourceCanonicalHash' | 'targetCanonicalHash'> & {