@ornexus/neocortex 4.60.67 → 4.60.68

package/packages/client/dist/commands/qa-scan-discovery.js

@@ -1,3 +1,376 @@
-import{createHash as F}from"node:crypto";import{performance as U}from"node:perf_hooks";import{closeSync as k,constants as S,fstatSync as V,fsyncSync as J,openSync as z,readFileSync as P,writeFileSync as W}from"node:fs";import{dirname as X,join as Y,resolve as E}from"node:path";import{aggregateRootQaScanReviews as G,planRootQaScan as B,rootQaScanEvidenceDirectory as K}from"./qa-scan-review.js";import{routeRootQaScanRequest as Z}from"./qa-scan-browser-route.js";import{launchRootQaBrowser as ee}from"./qa-scan-browser-launch.js";import{launchSyntheticBackendBrowser as re}from"./qa-synthetic-browser.js";import{openSyntheticBackendSession as te}from"./qa-synthetic-backend.js";const T=/^[a-f0-9]{64}$/,R=16,A=1024,C=32768,oe=60*6e4,ae=500,se=2e3,ne=50;function q(r){return F("sha256").update(r).digest("hex")}function ce(r){return r!==null&&typeof r=="object"&&!Array.isArray(r)}function L(r,t){return ce(r)&&Object.keys(r).sort().join("\0")===[...t].sort().join("\0")}function N(r,t,e){if(!T.test(e))throw new Error("qa-scan-discovery-unverified");return Y(K(r),`${t}-${e}.json`)}function j(r,t){const e=Buffer.from(`${JSON.stringify(t)}
-`),o=z(r,S.O_WRONLY|S.O_CREAT|S.O_EXCL|(S.O_NOFOLLOW??0),384);try{W(o,e),J(o)}finally{k(o)}const n=z(X(r),S.O_RDONLY|(S.O_DIRECTORY??0));try{J(n)}finally{k(n)}}function x(r,t){const e=z(r,S.O_RDONLY|(S.O_NOFOLLOW??0));let o,n;try{const s=V(e);if(!s.isFile()||s.uid!==process.getuid?.()||(s.mode&63)!==0||s.size<1||s.size>t)throw new Error("qa-scan-discovery-unverified");n=s.size,o=P(e)}finally{k(e)}if(o.length!==n||o.length>t)throw new Error("qa-scan-discovery-unverified");const a=JSON.parse(new TextDecoder("utf-8",{fatal:!0}).decode(o));if(!o.equals(Buffer.from(`${JSON.stringify(a)}
-`)))throw new Error("qa-scan-discovery-unverified");return a}function I(r,t){return Object.freeze({schemaVersion:2,kind:"root-qa-scan-link-discovery",sourceHead:r.sourceHead,seedSha256:r.seedSha256,discoverySha256:t,targetCount:r.targetUrls.length,inventoryScope:"reachable-rendered-same-origin-links",qaAccepted:!1,workflowContinuationAuthorized:!1,localOnly:!0,publicSafe:!0})}async function ie(r){let t,e=U.now();const o=e+se;for(;U.now()<=o;){const n=await r.locator("a[href]").evaluateAll(s=>s.map(i=>i.href)),a=JSON.stringify(n);if(a!==t)t=a,e=U.now();else if(U.now()-e>=ae)return n;await r.waitForTimeout(ne)}throw new Error("qa-scan-discovery-scope-unverified")}async function Se(r){if(!r.authorizeDiscovery)throw new Error("qa-scan-discovery-authorization-required");const t=E(r.projectRoot),e=B(t,"discovery",r.seedUrl),o=new URL(r.seedUrl);if(Buffer.byteLength(o.href)>A)throw new Error("qa-scan-discovery-scope-too-large");let n;const a=r.syntheticBackend?await te({projectRoot:t,surface:"discovery",targetUrl:r.seedUrl,...r.syntheticBackend}):void 0;try{n=a?await re():await ee()}catch{throw new Error("qa-scan-discovery-browser-unavailable")}try{const s=await n.newContext({serviceWorkers:"block",acceptDownloads:!1,permissions:[],ignoreHTTPSErrors:!1});let i=0,g=0,u=0,d=0;await s.route("**/*",async c=>{let y=!1;try{const f=c.request(),p=new URL(f.url());y=p.protocol==="http:"&&p.origin===o.origin&&(f.method()==="GET"||f.method()==="HEAD")}catch{}if(a)try{if(!y)throw new Error("denied");const f=c.request(),p=await a.request(f.url(),f.method(),f.postData(),await f.allHeaders());await c.fulfill({status:p.status,body:p.body,headers:{"content-type":p.contentType,"cache-control":"no-store"}})}catch{i++,await c.abort("blockedbyclient").catch(()=>{})}else await Z(c,y,()=>{i++})}),await s.routeWebSocket(/.*/,async c=>{i++,await c.close({code:1008,reason:"blocked"})});const l=await s.newPage();s.on("page",c=>{c!==l&&(d++,c.close())}),l.on("framenavigated",c=>{c===l.mainFrame()&&c.url()!=="about:blank"&&u++}),l.on("requestfailed",()=>{g++}),l.on("response",c=>{c.status()>=400&&g++});const m=new Set([o.href]),v=new Set;let H=0;for(;v.size<m.size;){const c=[...m].filter(w=>!v.has(w)).sort((w,h)=>Buffer.from(w).compare(Buffer.from(h)))[0];if(!c||m.size>R)throw new Error("qa-scan-discovery-scope-too-large");let y;try{y=await l.goto(c,{waitUntil:"load",timeout:15e3})}catch{throw new Error("qa-scan-discovery-target-unavailable")}if(!y||y.status()>=400||l.url()!==c||u!==v.size+1||i!==0||g!==0||d!==0)throw new Error("qa-scan-discovery-target-unavailable");const f=await ie(l);if(H+=f.length,H>256)throw new Error("qa-scan-discovery-scope-too-large");for(const w of f){if(typeof w!="string"||Buffer.byteLength(w)>A)throw new Error("qa-scan-discovery-scope-too-large");let h;try{h=new URL(w)}catch{throw new Error("qa-scan-discovery-target-unavailable")}if(!(h.origin!==o.origin||h.protocol!=="http:")){if(h.username||h.password||h.search||h.hash)throw new Error("qa-scan-discovery-target-unavailable");if(m.add(h.href),m.size>R)throw new Error("qa-scan-discovery-scope-too-large")}}const p=await l.locator("a[href]").evaluateAll(w=>w.map(h=>h.href));if(JSON.stringify(p)!==JSON.stringify(f)||l.url()!==c||u!==v.size+1||i!==0||g!==0||d!==0)throw new Error("qa-scan-discovery-scope-unverified");v.add(c)}const _=[...m].sort((c,y)=>Buffer.from(c).compare(Buffer.from(y)));if(_.length<1||_.length>R||v.size!==m.size||u!==v.size||i!==0||g!==0||d!==0)throw new Error("qa-scan-discovery-scope-unverified");const $=B(t,"discovery",r.seedUrl);if(a&&await a.verify(),$.planSha256!==e.planSha256)throw new Error("qa-scan-discovery-source-drift");const O={schemaVersion:2,sourceHead:e.sourceHead,seedUrl:o.href,seedSha256:e.targetSha256,capturedAt:new Date().toISOString(),targetUrls:_,pageCount:v.size},b=q(JSON.stringify(O)),M=N(t,"discovery",b);if(Buffer.byteLength(JSON.stringify({...O,discoverySha256:b}))+1>C)throw new Error("qa-scan-discovery-scope-too-large");return j(M,{...O,discoverySha256:b}),I(O,b)}catch(s){throw s instanceof Error&&s.message.startsWith("qa-scan-discovery-")?s:new Error("qa-scan-discovery-unverified")}finally{await n.close().catch(()=>{})}}function D(r,t){const e=x(N(r,"discovery",t),C);if(!L(e,["schemaVersion","sourceHead","seedUrl","seedSha256","capturedAt","targetUrls","pageCount","discoverySha256"])||e.schemaVersion!==2||e.discoverySha256!==t||typeof e.seedUrl!="string"||typeof e.sourceHead!="string"||typeof e.seedSha256!="string"||Buffer.byteLength(e.seedUrl)>A||!T.test(e.seedSha256)||!Array.isArray(e.targetUrls)||e.targetUrls.length<1||e.targetUrls.length>R||e.pageCount!==e.targetUrls.length||typeof e.capturedAt!="string")throw new Error("qa-scan-discovery-unverified");const o=Date.now()-Date.parse(e.capturedAt);if(!Number.isFinite(o)||new Date(e.capturedAt).toISOString()!==e.capturedAt||o<-5*6e4||o>oe)throw new Error("qa-scan-discovery-unverified");const n=B(r,"discovery",e.seedUrl);if(e.sourceHead!==n.sourceHead||e.seedSha256!==n.targetSha256)throw new Error("qa-scan-discovery-unverified");const a=new URL(e.seedUrl),s=e.targetUrls;if(!s.every(u=>typeof u=="string"&&Buffer.byteLength(u)<=A&&(()=>{try{const d=new URL(u);return d.origin===a.origin&&d.protocol==="http:"&&!d.username&&!d.password&&!d.search&&!d.hash&&d.href===u}catch{return!1}})())||!s.includes(a.href)||JSON.stringify(s)!==JSON.stringify([...new Set(s)].sort((u,d)=>Buffer.from(String(u)).compare(Buffer.from(String(d))))))throw new Error("qa-scan-discovery-unverified");const{discoverySha256:i,...g}=e;if(q(JSON.stringify(g))!==t)throw new Error("qa-scan-discovery-unverified");return g}function me(r,t){try{return I(D(E(r),t),t)}catch{throw new Error("qa-scan-discovery-unverified")}}function qe(r,t){try{return Object.freeze([...D(E(r),t).targetUrls])}catch{throw new Error("qa-scan-discovery-unverified")}}function Q(r,t,e){if(!L(e,["schemaVersion","targets"])||e.schemaVersion!==1||!Array.isArray(e.targets))throw new Error("qa-scan-discovery-phase-unverified");const o=D(r,t),n=e.targets.map(s=>{if(!L(s,["surface","targetUrl"])||typeof s.targetUrl!="string")throw new Error("qa-scan-discovery-phase-unverified");return s.targetUrl}).sort((s,i)=>Buffer.from(s).compare(Buffer.from(i)));if(JSON.stringify(n)!==JSON.stringify(o.targetUrls))throw new Error("qa-scan-discovery-phase-unverified");const a=G(r,e);if(a.sourceHead!==o.sourceHead||a.qaAccepted&&(a.verdict!=="approved"||a.issueCount!==0)||!a.qaAccepted&&(a.verdict!=="issues-found"||a.issueCount<1))throw new Error("qa-scan-discovery-phase-unverified");return Object.freeze({schemaVersion:2,kind:"root-qa-scan-discovered-phase-checkpoint",sourceHead:o.sourceHead,discoverySha256:t,aggregateSha256:a.aggregateSha256,surfaceCount:a.surfaceCount,inventoryScope:"reachable-rendered-same-origin-links",qaAccepted:a.qaAccepted,workflowContinuationAuthorized:!1,localOnly:!0,publicSafe:!0})}function Ee(r,t,e){try{const o=E(r),n=Q(o,t,e),a={receipt:n,checksumSha256:q(`qa-scan-discovered-phase-v2\0${JSON.stringify(n)}`)},s=N(o,"discovered-phase",q(`${t}\0${n.aggregateSha256}`));try{j(s,a)}catch(i){if(i.code!=="EEXIST")throw i}if(JSON.stringify(de(o,t,e))!==JSON.stringify(n))throw new Error("qa-scan-discovery-phase-unverified");return n}catch{throw new Error("qa-scan-discovery-phase-unverified")}}function de(r,t,e){try{const o=E(r),n=Q(o,t,e),a=x(N(o,"discovered-phase",q(`${t}\0${n.aggregateSha256}`)),4096);if(!L(a,["receipt","checksumSha256"])||a.checksumSha256!==q(`qa-scan-discovered-phase-v2\0${JSON.stringify(a.receipt)}`)||JSON.stringify(a.receipt)!==JSON.stringify(n))throw new Error("qa-scan-discovery-phase-unverified");return n}catch{throw new Error("qa-scan-discovery-phase-unverified")}}export{Ee as acceptRootQaScanDiscoveredPhase,Se as discoverRootQaScanLinks,de as readRootQaScanDiscoveredPhase,me as readRootQaScanDiscovery,qe as readRootQaScanDiscoveryTargets};
+/** Root-owned, synthetic-loopback Q01 reachable-link inventory and bound Q01–Q03 evidence. */
+import { createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { closeSync, constants, fstatSync, fsyncSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { aggregateRootQaScanReviews, planRootQaScan, rootQaScanEvidenceDirectory } from './qa-scan-review.js';
+import { routeRootQaScanRequest } from './qa-scan-browser-route.js';
+import { launchRootQaBrowser } from './qa-scan-browser-launch.js';
+import { launchSyntheticBackendBrowser } from './qa-synthetic-browser.js';
+import { openSyntheticBackendSession } from './qa-synthetic-backend.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+const MAX_TARGETS = 16;
+const MAX_URL_BYTES = 1024;
+const MAX_RECORD_BYTES = 32_768;
+const MAX_AGE_MS = 60 * 60_000;
+// A load event can precede SPA hydration. Observe a bounded quiet window
+// before treating rendered links as the Q01 inventory; never claim that an
+// indefinitely changing page has a complete route set.
+const LINK_QUIET_MS = 500;
+const LINK_SETTLE_LIMIT_MS = 2_000;
+const LINK_POLL_MS = 50;
+function sha(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function exact(value, keys) {
+    return object(value) && Object.keys(value).sort().join('\0') === [...keys].sort().join('\0');
+}
+function privateRecord(root, prefix, id) {
+    if (!SHA256.test(id))
+        throw new Error('qa-scan-discovery-unverified');
+    return join(rootQaScanEvidenceDirectory(root), `${prefix}-${id}.json`);
+}
+function saveImmutable(path, value) {
+    const bytes = Buffer.from(`${JSON.stringify(value)}\n`);
+    const handle = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL
+        | (constants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+        writeFileSync(handle, bytes);
+        fsyncSync(handle);
+    }
+    finally {
+        closeSync(handle);
+    }
+    const directoryHandle = openSync(dirname(path), constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+    try {
+        fsyncSync(directoryHandle);
+    }
+    finally {
+        closeSync(directoryHandle);
+    }
+}
+function readImmutable(path, maxBytes) {
+    const handle = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    let raw;
+    let expectedSize;
+    try {
+        const stat = fstatSync(handle);
+        if (!stat.isFile() || stat.uid !== process.getuid?.()
+            || (stat.mode & 0o077) !== 0 || stat.size < 1 || stat.size > maxBytes) {
+            throw new Error('qa-scan-discovery-unverified');
+        }
+        expectedSize = stat.size;
+        raw = readFileSync(handle);
+    }
+    finally {
+        closeSync(handle);
+    }
+    if (raw.length !== expectedSize || raw.length > maxBytes)
+        throw new Error('qa-scan-discovery-unverified');
+    const parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
+    if (!raw.equals(Buffer.from(`${JSON.stringify(parsed)}\n`))) {
+        throw new Error('qa-scan-discovery-unverified');
+    }
+    return parsed;
+}
+function discoveryReceipt(body, discoverySha256) {
+    return Object.freeze({ schemaVersion: 2, kind: 'root-qa-scan-link-discovery',
+        sourceHead: body.sourceHead, seedSha256: body.seedSha256, discoverySha256,
+        targetCount: body.targetUrls.length, inventoryScope: 'reachable-rendered-same-origin-links',
+        qaAccepted: false, workflowContinuationAuthorized: false,
+        localOnly: true, publicSafe: true });
+}
+async function settledRenderedLinks(page) {
+    let previous;
+    let quietSince = performance.now();
+    const deadline = quietSince + LINK_SETTLE_LIMIT_MS;
+    while (performance.now() <= deadline) {
+        const links = await page.locator('a[href]').evaluateAll((anchors) => anchors.map((anchor) => anchor.href));
+        const serialized = JSON.stringify(links);
+        if (serialized !== previous) {
+            previous = serialized;
+            quietSince = performance.now();
+        }
+        else if (performance.now() - quietSince >= LINK_QUIET_MS) {
+            return links;
+        }
+        await page.waitForTimeout(LINK_POLL_MS);
+    }
+    throw new Error('qa-scan-discovery-scope-unverified');
+}
+/** Navigation itself may have application-defined GET effects. Opt in only
+ * for a purpose-built synthetic app; never borrow a browser profile/cookies. */
+export async function discoverRootQaScanLinks(options) {
+    if (!options.authorizeDiscovery)
+        throw new Error('qa-scan-discovery-authorization-required');
+    const root = resolve(options.projectRoot);
+    const plan = planRootQaScan(root, 'discovery', options.seedUrl);
+    const seed = new URL(options.seedUrl);
+    if (Buffer.byteLength(seed.href) > MAX_URL_BYTES) {
+        throw new Error('qa-scan-discovery-scope-too-large');
+    }
+    let browser;
+    const backend = options.syntheticBackend ? await openSyntheticBackendSession({ projectRoot: root,
+        surface: 'discovery', targetUrl: options.seedUrl, ...options.syntheticBackend }) : undefined;
+    try {
+        browser = backend ? await launchSyntheticBackendBrowser() : await launchRootQaBrowser();
+    }
+    catch {
+        throw new Error('qa-scan-discovery-browser-unavailable');
+    }
+    try {
+        const context = await browser.newContext({ serviceWorkers: 'block', acceptDownloads: false,
+            permissions: [], ignoreHTTPSErrors: false });
+        let denied = 0;
+        let failed = 0;
+        let navigations = 0;
+        let popups = 0;
+        await context.route('**/*', async (route) => {
+            let allowed = false;
+            try {
+                const request = route.request();
+                const url = new URL(request.url());
+                allowed = url.protocol === 'http:' && url.origin === seed.origin
+                    && (request.method() === 'GET' || request.method() === 'HEAD');
+            }
+            catch { /* Refuse malformed and opaque browser requests. */ }
+            if (backend) {
+                try {
+                    if (!allowed)
+                        throw new Error('denied');
+                    const request = route.request();
+                    const response = await backend.request(request.url(), request.method(), request.postData(), await request.allHeaders());
+                    await route.fulfill({ status: response.status, body: response.body,
+                        headers: { 'content-type': response.contentType, 'cache-control': 'no-store' } });
+                }
+                catch {
+                    denied++;
+                    await route.abort('blockedbyclient').catch(() => undefined);
+                }
+            }
+            else
+                await routeRootQaScanRequest(route, allowed, () => { denied++; });
+        });
+        await context.routeWebSocket(/.*/, async (socket) => {
+            denied++;
+            await socket.close({ code: 1008, reason: 'blocked' });
+        });
+        const page = await context.newPage();
+        context.on('page', (opened) => { if (opened !== page) {
+            popups++;
+            void opened.close();
+        } });
+        page.on('framenavigated', (frame) => {
+            if (frame === page.mainFrame() && frame.url() !== 'about:blank')
+                navigations++;
+        });
+        page.on('requestfailed', () => { failed++; });
+        page.on('response', (response) => { if (response.status() >= 400)
+            failed++; });
+        const targets = new Set([seed.href]);
+        const visited = new Set();
+        let anchorCount = 0;
+        while (visited.size < targets.size) {
+            const next = [...targets].filter((url) => !visited.has(url))
+                .sort((a, b) => Buffer.from(a).compare(Buffer.from(b)))[0];
+            if (!next || targets.size > MAX_TARGETS)
+                throw new Error('qa-scan-discovery-scope-too-large');
+            let response;
+            try {
+                response = await page.goto(next, { waitUntil: 'load', timeout: 15_000 });
+            }
+            catch {
+                throw new Error('qa-scan-discovery-target-unavailable');
+            }
+            if (!response || response.status() >= 400 || page.url() !== next
+                || navigations !== visited.size + 1 || denied !== 0 || failed !== 0 || popups !== 0) {
+                throw new Error('qa-scan-discovery-target-unavailable');
+            }
+            const hrefs = await settledRenderedLinks(page);
+            anchorCount += hrefs.length;
+            if (anchorCount > 256)
+                throw new Error('qa-scan-discovery-scope-too-large');
+            for (const href of hrefs) {
+                if (typeof href !== 'string' || Buffer.byteLength(href) > MAX_URL_BYTES) {
+                    throw new Error('qa-scan-discovery-scope-too-large');
+                }
+                let url;
+                try {
+                    url = new URL(href);
+                }
+                catch {
+                    throw new Error('qa-scan-discovery-target-unavailable');
+                }
+                if (url.origin !== seed.origin || url.protocol !== 'http:')
+                    continue;
+                if (url.username || url.password || url.search || url.hash) {
+                    throw new Error('qa-scan-discovery-target-unavailable');
+                }
+                targets.add(url.href);
+                if (targets.size > MAX_TARGETS)
+                    throw new Error('qa-scan-discovery-scope-too-large');
+            }
+            const finalHrefs = await page.locator('a[href]').evaluateAll((anchors) => anchors.map((anchor) => anchor.href));
+            if (JSON.stringify(finalHrefs) !== JSON.stringify(hrefs)
+                || page.url() !== next || navigations !== visited.size + 1
+                || denied !== 0 || failed !== 0 || popups !== 0) {
+                throw new Error('qa-scan-discovery-scope-unverified');
+            }
+            visited.add(next);
+        }
+        const targetUrls = [...targets].sort((a, b) => Buffer.from(a).compare(Buffer.from(b)));
+        if (targetUrls.length < 1 || targetUrls.length > MAX_TARGETS
+            || visited.size !== targets.size || navigations !== visited.size
+            || denied !== 0 || failed !== 0 || popups !== 0) {
+            throw new Error('qa-scan-discovery-scope-unverified');
+        }
+        const fresh = planRootQaScan(root, 'discovery', options.seedUrl);
+        if (backend)
+            await backend.verify();
+        if (fresh.planSha256 !== plan.planSha256)
+            throw new Error('qa-scan-discovery-source-drift');
+        const body = { schemaVersion: 2, sourceHead: plan.sourceHead,
+            seedUrl: seed.href, seedSha256: plan.targetSha256,
+            capturedAt: new Date().toISOString(), targetUrls, pageCount: visited.size };
+        const discoverySha256 = sha(JSON.stringify(body));
+        const path = privateRecord(root, 'discovery', discoverySha256);
+        if (Buffer.byteLength(JSON.stringify({ ...body, discoverySha256 })) + 1 > MAX_RECORD_BYTES) {
+            throw new Error('qa-scan-discovery-scope-too-large');
+        }
+        saveImmutable(path, { ...body, discoverySha256 });
+        return discoveryReceipt(body, discoverySha256);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('qa-scan-discovery-'))
+            throw error;
+        throw new Error('qa-scan-discovery-unverified');
+    }
+    finally {
+        await browser.close().catch(() => undefined);
+    }
+}
+function readDiscovery(root, id) {
+    const value = readImmutable(privateRecord(root, 'discovery', id), MAX_RECORD_BYTES);
+    if (!exact(value, ['schemaVersion', 'sourceHead', 'seedUrl', 'seedSha256',
+        'capturedAt', 'targetUrls', 'pageCount', 'discoverySha256']) || value.schemaVersion !== 2
+        || value.discoverySha256 !== id || typeof value.seedUrl !== 'string'
+        || typeof value.sourceHead !== 'string' || typeof value.seedSha256 !== 'string'
+        || Buffer.byteLength(value.seedUrl) > MAX_URL_BYTES
+        || !SHA256.test(value.seedSha256) || !Array.isArray(value.targetUrls)
+        || value.targetUrls.length < 1 || value.targetUrls.length > MAX_TARGETS
+        || value.pageCount !== value.targetUrls.length
+        || typeof value.capturedAt !== 'string')
+        throw new Error('qa-scan-discovery-unverified');
+    const age = Date.now() - Date.parse(value.capturedAt);
+    if (!Number.isFinite(age) || new Date(value.capturedAt).toISOString() !== value.capturedAt
+        || age < -5 * 60_000 || age > MAX_AGE_MS) {
+        throw new Error('qa-scan-discovery-unverified');
+    }
+    const plan = planRootQaScan(root, 'discovery', value.seedUrl);
+    if (value.sourceHead !== plan.sourceHead || value.seedSha256 !== plan.targetSha256) {
+        throw new Error('qa-scan-discovery-unverified');
+    }
+    const seed = new URL(value.seedUrl);
+    const urls = value.targetUrls;
+    if (!urls.every((item) => typeof item === 'string' && Buffer.byteLength(item) <= MAX_URL_BYTES && (() => {
+        try {
+            const url = new URL(item);
+            return url.origin === seed.origin && url.protocol === 'http:'
+                && !url.username && !url.password && !url.search && !url.hash && url.href === item;
+        }
+        catch {
+            return false;
+        }
+    })()) || !urls.includes(seed.href)
+        || JSON.stringify(urls) !== JSON.stringify([...new Set(urls)].sort((a, b) => Buffer.from(String(a)).compare(Buffer.from(String(b)))))) {
+        throw new Error('qa-scan-discovery-unverified');
+    }
+    const { discoverySha256: _digest, ...body } = value;
+    if (sha(JSON.stringify(body)) !== id)
+        throw new Error('qa-scan-discovery-unverified');
+    return body;
+}
+export function readRootQaScanDiscovery(projectRoot, id) {
+    try {
+        return discoveryReceipt(readDiscovery(resolve(projectRoot), id), id);
+    }
+    catch {
+        throw new Error('qa-scan-discovery-unverified');
+    }
+}
+/** Root/worker evidence verification only; reopening validates source and the complete inventory. */
+export function readRootQaScanDiscoveryTargets(projectRoot, id) {
+    try {
+        return Object.freeze([...readDiscovery(resolve(projectRoot), id).targetUrls]);
+    }
+    catch {
+        throw new Error('qa-scan-discovery-unverified');
+    }
+}
+function discoveredPhase(root, id, input) {
+    if (!exact(input, ['schemaVersion', 'targets']) || input.schemaVersion !== 1
+        || !Array.isArray(input.targets))
+        throw new Error('qa-scan-discovery-phase-unverified');
+    const discovery = readDiscovery(root, id);
+    const targetUrls = input.targets.map((target) => {
+        if (!exact(target, ['surface', 'targetUrl']) || typeof target.targetUrl !== 'string') {
+            throw new Error('qa-scan-discovery-phase-unverified');
+        }
+        return target.targetUrl;
+    }).sort((a, b) => Buffer.from(a).compare(Buffer.from(b)));
+    if (JSON.stringify(targetUrls) !== JSON.stringify(discovery.targetUrls)) {
+        throw new Error('qa-scan-discovery-phase-unverified');
+    }
+    const aggregate = aggregateRootQaScanReviews(root, input);
+    if (aggregate.sourceHead !== discovery.sourceHead
+        || (aggregate.qaAccepted && (aggregate.verdict !== 'approved' || aggregate.issueCount !== 0))
+        || (!aggregate.qaAccepted && (aggregate.verdict !== 'issues-found' || aggregate.issueCount < 1))) {
+        throw new Error('qa-scan-discovery-phase-unverified');
+    }
+    return Object.freeze({ schemaVersion: 2, kind: 'root-qa-scan-discovered-phase-checkpoint',
+        sourceHead: discovery.sourceHead, discoverySha256: id,
+        aggregateSha256: aggregate.aggregateSha256, surfaceCount: aggregate.surfaceCount,
+        inventoryScope: 'reachable-rendered-same-origin-links', qaAccepted: aggregate.qaAccepted,
+        workflowContinuationAuthorized: false, localOnly: true, publicSafe: true });
+}
+export function acceptRootQaScanDiscoveredPhase(projectRoot, id, input) {
+    try {
+        const root = resolve(projectRoot);
+        const receipt = discoveredPhase(root, id, input);
+        const record = { receipt, checksumSha256: sha(`qa-scan-discovered-phase-v2\0${JSON.stringify(receipt)}`) };
+        const path = privateRecord(root, 'discovered-phase', sha(`${id}\0${receipt.aggregateSha256}`));
+        try {
+            saveImmutable(path, record);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        if (JSON.stringify(readRootQaScanDiscoveredPhase(root, id, input)) !== JSON.stringify(receipt)) {
+            throw new Error('qa-scan-discovery-phase-unverified');
+        }
+        return receipt;
+    }
+    catch {
+        throw new Error('qa-scan-discovery-phase-unverified');
+    }
+}
+export function readRootQaScanDiscoveredPhase(projectRoot, id, input) {
+    try {
+        const root = resolve(projectRoot);
+        const expected = discoveredPhase(root, id, input);
+        const value = readImmutable(privateRecord(root, 'discovered-phase', sha(`${id}\0${expected.aggregateSha256}`)), 4096);
+        if (!exact(value, ['receipt', 'checksumSha256'])
+            || value.checksumSha256 !== sha(`qa-scan-discovered-phase-v2\0${JSON.stringify(value.receipt)}`)
+            || JSON.stringify(value.receipt) !== JSON.stringify(expected)) {
+            throw new Error('qa-scan-discovery-phase-unverified');
+        }
+        return expected;
+    }
+    catch {
+        throw new Error('qa-scan-discovery-phase-unverified');
+    }
+}