@ornexus/neocortex 4.60.71 → 4.60.73

package/packages/client/dist/private-execution/ux-source-validation.js

@@ -1 +1,372 @@
-import{parse as H}from"@babel/parser";import{lstatSync as q,readFileSync as G}from"node:fs";import{join as K,posix as V}from"node:path";const Q=1024*1024,ee=1e5,z=/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;function p(){throw new Error("private-execution-ux-source-unverified")}function o(e){return e!==null&&typeof e=="object"&&!Array.isArray(e)}function j(e,t){const r=q(K(e,t));(!r.isFile()||r.isSymbolicLink()||r.size<1||r.size>Q)&&p();const s=new TextDecoder("utf-8",{fatal:!0}).decode(G(K(e,t)));return(!s.trim()||s.includes("\0"))&&p(),s}function I(e,t){const r=H(j(e,t),{sourceType:"module",plugins:["typescript","jsx"],errorRecovery:!1});let s=0;const i=[r];for(;i.length>0;){const l=i.pop();if(o(l)){++s>ee&&p();for(const[n,f]of Object.entries(l))n==="loc"||n==="tokens"||n==="comments"||n==="errors"||(Array.isArray(f)?i.push(...f):o(f)&&i.push(f))}}return r}function E(e){const t=e.program;return(!o(t)||!Array.isArray(t.body))&&p(),t.body.filter(o)}function m(e,t){if(!o(e)||e.type!=="ObjectExpression"||!Array.isArray(e.properties))return;const r=e.properties.filter(s=>o(s)&&s.type==="ObjectProperty"&&s.computed!==!0&&o(s.key)&&(s.key.name===t||s.key.value===t));return r.length===1&&o(r[0])?r[0].value:void 0}function g(e){return o(e)&&e.type==="StringLiteral"&&typeof e.value=="string"?e.value:void 0}function y(e){return o(e)&&e.type==="Identifier"&&typeof e.name=="string"?e.name:void 0}function x(e){return e.type==="VariableDeclaration"&&Array.isArray(e.declarations)?e.declarations.filter(o):[]}function D(e){let t=e;for(let r=0;r<4&&o(t)&&["TSAsExpression","TSSatisfiesExpression","TSTypeAssertion","ParenthesizedExpression"].includes(String(t.type));r++)t=t.expression;return t}function te(e,t){const r=e.flatMap(x).filter(s=>y(s.id)===t);return r.length===1?D(r[0].init):void 0}function R(e,t){for(const r of e){if(r.type!=="ExportNamedDeclaration"||!o(r.declaration))continue;const s=r.declaration;if(s.type==="FunctionDeclaration"&&o(s.id)&&s.id.name===t)return s;const i=x(s).find(l=>o(l.id)&&l.id.name===t);if(i)return D(i.init)}}function A(e,t){const r=[],s=[e];for(;s.length>0;){const i=s.pop();if(o(i)){i.type===t&&r.push(i);for(const[l,n]of Object.entries(i))l==="loc"||l==="comments"||(Array.isArray(n)?s.push(...n):o(n)&&s.push(n))}}return r}function P(e){return e.screenId.toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"").slice(0,64)}function U(e){return e.split(/[^A-Za-z0-9]+/).filter(Boolean).map(t=>`${t.charAt(0).toUpperCase()}${t.slice(1).toLowerCase()}`).join("")}function Z(e,t,r){const s=[];for(const i of e){if(i.type!=="ImportDeclaration"||i.importKind==="type"||!o(i.source)||typeof i.source.value!="string"||!i.source.value.startsWith("./")&&!i.source.value.startsWith("../"))continue;const l=V.normalize(V.join(V.dirname(t),i.source.value));if(!(l!==r.screenViewPath&&l!==r.screenViewPath.replace(/\.tsx$/,"")))for(const n of Array.isArray(i.specifiers)?i.specifiers:[])o(n)&&n.type==="ImportSpecifier"&&o(n.imported)&&n.imported.name===r.screenViewExport&&n.importKind!=="type"&&o(n.local)&&typeof n.local.name=="string"&&s.push(n.local.name)}return s.length!==1&&p(),s[0]}function re(e,t){return A(e,"JSXOpeningElement").some(r=>o(r.name)&&r.name.name===t)}function w(e,t,r){const s=e.filter(i=>i.type==="ImportDeclaration"&&o(i.source)&&i.source.value===t).flatMap(i=>Array.isArray(i.specifiers)?i.specifiers:[]).filter(i=>o(i)&&i.type==="ImportSpecifier"&&o(i.imported)&&i.imported.name===r&&o(i.local)&&typeof i.local.name=="string").map(i=>i.local);return s.length===1?s[0].name:void 0}function Y(e,t,r){return o(e)&&e.type==="CallExpression"&&o(e.callee)&&e.callee.type==="MemberExpression"&&e.callee.computed!==!0&&y(e.callee.object)===t&&y(e.callee.property)===r}function ne(e,t){const r=w(t,"storybook/test","within"),s=w(t,"storybook/test","userEvent"),i=w(t,"storybook/test","expect");if(!r||!s||!i||!Array.isArray(e.params)||!o(e.params[0])||e.params[0].type!=="ObjectPattern"||!Array.isArray(e.params[0].properties)||!e.params[0].properties.some(a=>o(a)&&o(a.key)&&a.key.name==="canvasElement"&&o(a.value)&&a.value.name==="canvasElement"))return!1;const l=A(e.body,"VariableDeclarator"),n=l.filter(a=>o(a.init)&&a.init.type==="CallExpression"&&y(a.init.callee)===r&&Array.isArray(a.init.arguments)&&a.init.arguments.length===1&&y(a.init.arguments[0])==="canvasElement").map(a=>y(a.id)).filter(a=>!!a),f=l.filter(a=>n.some(k=>Y(a.init,k,"getByRole")&&Array.isArray(a.init.arguments)&&g(a.init.arguments[0])==="button"&&typeof g(m(a.init.arguments[1],"name"))=="string"&&!!g(m(a.init.arguments[1],"name"))?.trim())).map(a=>y(a.id)).filter(a=>!!a);if(f.length===0)return!1;const u=A(e.body,"AwaitExpression").map(a=>a.argument),$=u.some(a=>Y(a,s,"tab")&&Array.isArray(a.arguments)&&a.arguments.length===0),h=u.some(a=>o(a)&&a.type==="CallExpression"&&o(a.callee)&&a.callee.type==="MemberExpression"&&y(a.callee.property)==="toHaveFocus"&&o(a.callee.object)&&a.callee.object.type==="CallExpression"&&y(a.callee.object.callee)===i&&Array.isArray(a.callee.object.arguments)&&f.includes(y(a.callee.object.arguments[0])??""));return $&&h}function se(e,t,r){const s=`src/screens/${P(t)}/${P(t)}`,i=I(e,t.screenViewPath),l=R(E(i),t.screenViewExport);(!l||A(l,"JSXElement").length+A(l,"JSXFragment").length===0)&&p();const n=I(e,t.appRoutePath),f=Z(E(n),t.appRoutePath,t);re(n,f)||p();const u=`${s}.stories.tsx`,$=I(e,u),h=E($),a=r==="storybook-react-vite"?"@storybook/react-vite":"@storybook/nextjs-vite";(!w(h,a,"Meta")||!w(h,a,"StoryObj"))&&p();const k=Z(h,u,t),C=h.filter(c=>c.type==="ExportDefaultDeclaration");C.length!==1&&p();const O=D(C[0].declaration),T=y(O)?te(h,y(O)):O;(y(m(T,"component"))!==k||g(m(T,"title"))!==`Screens/${t.screenId}`)&&p();const v=new Set;for(const c of t.states)for(const d of t.viewports){const L=`${U(c)}${U(d)}`;v.add(L);const b=R(h,L);if((!o(b)||b.type!=="ObjectExpression"||g(m(m(b,"args"),"state"))!==c||g(m(m(m(b,"parameters"),"viewport"),"defaultViewport"))!==d)&&p(),t.critical&&(c==="success"||c==="recovery")){const N=m(b,"play");(!o(N)||!["ArrowFunctionExpression","FunctionExpression"].includes(String(N.type))||!ne(N,h))&&p()}}const F=h.filter(c=>c.type==="ExportNamedDeclaration");F.some(c=>!o(c.declaration)||x(c.declaration).length!==1||Array.isArray(c.specifiers)&&c.specifiers.length>0)&&p();const X=F.flatMap(c=>x(c.declaration)).map(c=>y(c.id)).filter(c=>!!c);(X.length!==v.size||X.some(c=>!v.has(c)))&&p();const W=I(e,`${s}.fixtures.ts`);E(W).filter(c=>c.type==="ExportNamedDeclaration").flatMap(c=>o(c.declaration)?x(c.declaration):[]).some(c=>{const d=m(c.init,"synthetic");return o(d)&&d.type==="BooleanLiteral"&&d.value===!0&&m(c.init,"data")!==void 0})||p();const _=I(e,`${s}.handlers.ts`),B=E(_);(!B.some(c=>c.type==="ImportDeclaration"&&o(c.source)&&c.source.value==="msw"&&Array.isArray(c.specifiers)&&c.specifiers.some(d=>o(d)&&o(d.imported)&&d.imported.name==="http"))||!B.some(c=>c.type==="ExportNamedDeclaration"&&o(c.declaration)&&x(c.declaration).some(d=>o(d.init)&&d.init.type==="ArrayExpression"&&Array.isArray(d.init.elements)&&d.init.elements.length>0))||!A(_,"CallExpression").some(c=>o(c.callee)&&c.callee.type==="MemberExpression"&&o(c.callee.object)&&c.callee.object.name==="http"))&&p();const M=j(e,`${s}.mdx`),J=new RegExp(`import\\s+\\*\\s+as\\s+([A-Za-z_$][\\w$]*)\\s+from\\s+['"]\\./${P(t)}\\.stories(?:\\.tsx)?['"];?\\r?\\n(?:[ \\t]*\\r?\\n)+`).exec(M);(!/import\s+\{\s*Meta\s*\}\s+from\s+['"]@storybook\/addon-docs\/blocks['"]/.test(M)||!J||!M.includes(`<Meta of={${J[1]}} />`))&&p()}function S(e){return Array.isArray(e)?`[${e.map(S).join(",")}]`:e&&typeof e=="object"?`{${Object.entries(e).sort(([t],[r])=>t.localeCompare(r)).map(([t,r])=>`${JSON.stringify(t)}:${S(r)}`).join(",")}}`:JSON.stringify(e)??"null"}function oe(e){const t=S(e);let r=2166136261;for(let s=0;s<t.length;s++)r^=t.charCodeAt(s),r=Math.imul(r,16777619);return`uxm-${(r>>>0).toString(16).padStart(8,"0")}`}function ie(e,t){let r;try{r=JSON.parse(j(e,"docs/architecture/ux-coverage-manifest.json"))}catch{p()}(!o(r)||r.schemaVersion!==1||r.manifestId!=="P201-UX-MANIFEST-01"||!Array.isArray(r.entries)||typeof r.fingerprint!="string"||Object.keys(r).sort().join(",")!=="entries,fingerprint,manifestId,schemaVersion"||r.fingerprint!==oe(r.entries))&&p();const s=new Map;for(const n of t.screens)for(const f of n.states)for(const u of n.viewports)s.set(`Screens/${n.screenId}/${f}/${u}`,{screen:n,state:f,viewport:u});r.entries.length!==s.size&&p();const i=new Set;let l="";for(const n of r.entries){(!o(n)||typeof n.storyId!="string"||i.has(n.storyId))&&p(),l&&l.localeCompare(n.storyId)>=0&&p(),l=n.storyId,Object.keys(n).sort().join(",")!=="approvalEvidenceIds,fixtureId,handlerIds,journeyIds,screenId,screenViewPath,state,storyId,viewport"&&p(),i.add(n.storyId);const f=s.get(n.storyId);(!f||n.screenId!==f.screen.screenId||n.state!==f.state||n.viewport!==f.viewport||n.screenViewPath!==f.screen.screenViewPath||!Array.isArray(n.approvalEvidenceIds)||S([...n.approvalEvidenceIds].sort())!==S([...f.screen.approvalEvidenceIds].sort())||!Array.isArray(n.journeyIds)||n.journeyIds.length<1||n.journeyIds.some(u=>typeof u!="string"||!z.test(u))||new Set(n.journeyIds).size!==n.journeyIds.length||typeof n.fixtureId!="string"||!z.test(n.fixtureId)||!Array.isArray(n.handlerIds)||n.handlerIds.length<1||n.handlerIds.some(u=>typeof u!="string"||!z.test(u))||new Set(n.handlerIds).size!==n.handlerIds.length)&&p()}}function fe(e,t){try{for(const[r,s]of[["docs/architecture/ux-design.md","P201-UX-STORYBOOK-01"],["docs/architecture/storybook-ux-contract.md","P201-UX-STORYBOOK-01"]])j(e,r).includes(s)||p();for(const r of t.screens)se(e,r,t.adapterId);ie(e,t)}catch{p()}}export{fe as validateUxCandidateSource};
+/**
+ * Static, non-executing A08 admission screen. Passing this check admits a
+ * candidate patch only; schema validation, Storybook, play and a11y execution
+ * still require separate root-owned evidence before A08 can complete.
+ */
+import { parse } from '@babel/parser';
+import { lstatSync, readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_AST_NODES = 100_000;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function fail() { throw new Error('private-execution-ux-source-unverified'); }
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function source(root, path) {
+    const stat = lstatSync(join(root, path));
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size < 1 || stat.size > MAX_FILE_BYTES)
+        fail();
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(join(root, path)));
+    if (!text.trim() || text.includes('\0'))
+        fail();
+    return text;
+}
+function ast(root, path) {
+    const parsed = parse(source(root, path), { sourceType: 'module',
+        plugins: ['typescript', 'jsx'], errorRecovery: false });
+    let count = 0;
+    const pending = [parsed];
+    while (pending.length > 0) {
+        const value = pending.pop();
+        if (!object(value))
+            continue;
+        if (++count > MAX_AST_NODES)
+            fail();
+        for (const [key, child] of Object.entries(value)) {
+            if (key === 'loc' || key === 'tokens' || key === 'comments' || key === 'errors')
+                continue;
+            if (Array.isArray(child))
+                pending.push(...child);
+            else if (object(child))
+                pending.push(child);
+        }
+    }
+    return parsed;
+}
+function body(tree) {
+    const program = tree.program;
+    if (!object(program) || !Array.isArray(program.body))
+        fail();
+    return program.body.filter(object);
+}
+function prop(value, name) {
+    if (!object(value) || value.type !== 'ObjectExpression' || !Array.isArray(value.properties))
+        return undefined;
+    const matches = value.properties.filter((entry) => object(entry)
+        && entry.type === 'ObjectProperty' && entry.computed !== true && object(entry.key)
+        && (entry.key.name === name || entry.key.value === name));
+    return matches.length === 1 && object(matches[0]) ? matches[0].value : undefined;
+}
+function literal(value) {
+    return object(value) && value.type === 'StringLiteral' && typeof value.value === 'string'
+        ? value.value : undefined;
+}
+function identifier(value) {
+    return object(value) && value.type === 'Identifier' && typeof value.name === 'string'
+        ? value.name : undefined;
+}
+function declarations(node) {
+    return node.type === 'VariableDeclaration' && Array.isArray(node.declarations)
+        ? node.declarations.filter(object) : [];
+}
+function unwrap(value) {
+    let current = value;
+    for (let index = 0; index < 4 && object(current)
+        && ['TSAsExpression', 'TSSatisfiesExpression', 'TSTypeAssertion', 'ParenthesizedExpression']
+            .includes(String(current.type)); index++)
+        current = current.expression;
+    return current;
+}
+function localVariable(statements, name) {
+    const matches = statements.flatMap(declarations)
+        .filter((item) => identifier(item.id) === name);
+    return matches.length === 1 ? unwrap(matches[0].init) : undefined;
+}
+function exported(root, name) {
+    for (const statement of root) {
+        if (statement.type !== 'ExportNamedDeclaration' || !object(statement.declaration))
+            continue;
+        const declaration = statement.declaration;
+        if (declaration.type === 'FunctionDeclaration' && object(declaration.id)
+            && declaration.id.name === name)
+            return declaration;
+        const variable = declarations(declaration).find((item) => object(item.id) && item.id.name === name);
+        if (variable)
+            return unwrap(variable.init);
+    }
+    return undefined;
+}
+function nodes(value, type) {
+    const found = [];
+    const pending = [value];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (!object(current))
+            continue;
+        if (current.type === type)
+            found.push(current);
+        for (const [key, child] of Object.entries(current)) {
+            if (key === 'loc' || key === 'comments')
+                continue;
+            if (Array.isArray(child))
+                pending.push(...child);
+            else if (object(child))
+                pending.push(child);
+        }
+    }
+    return found;
+}
+function stem(screen) {
+    return screen.screenId.toLowerCase().replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '').slice(0, 64);
+}
+function pascal(value) {
+    return value.split(/[^A-Za-z0-9]+/).filter(Boolean)
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1).toLowerCase()}`).join('');
+}
+function importsView(statements, fromPath, screen) {
+    const matched = [];
+    for (const statement of statements) {
+        if (statement.type !== 'ImportDeclaration' || statement.importKind === 'type'
+            || !object(statement.source) || typeof statement.source.value !== 'string'
+            || !statement.source.value.startsWith('./') && !statement.source.value.startsWith('../'))
+            continue;
+        const resolved = posix.normalize(posix.join(posix.dirname(fromPath), statement.source.value));
+        if (resolved !== screen.screenViewPath && resolved !== screen.screenViewPath.replace(/\.tsx$/, ''))
+            continue;
+        for (const specifier of Array.isArray(statement.specifiers) ? statement.specifiers : []) {
+            if (object(specifier) && specifier.type === 'ImportSpecifier'
+                && object(specifier.imported) && specifier.imported.name === screen.screenViewExport
+                && specifier.importKind !== 'type' && object(specifier.local)
+                && typeof specifier.local.name === 'string')
+                matched.push(specifier.local.name);
+        }
+    }
+    if (matched.length !== 1)
+        fail();
+    return matched[0];
+}
+function hasJsx(tree, name) {
+    return nodes(tree, 'JSXOpeningElement').some((item) => object(item.name) && item.name.name === name);
+}
+function importedName(statements, module, name) {
+    const matches = statements.filter((item) => item.type === 'ImportDeclaration'
+        && object(item.source) && item.source.value === module)
+        .flatMap((item) => Array.isArray(item.specifiers) ? item.specifiers : [])
+        .filter((item) => object(item) && item.type === 'ImportSpecifier'
+        && object(item.imported) && item.imported.name === name && object(item.local)
+        && typeof item.local.name === 'string')
+        .map((item) => item.local);
+    return matches.length === 1 ? matches[0].name : undefined;
+}
+function calledMember(value, objectName, memberName) {
+    return object(value) && value.type === 'CallExpression' && object(value.callee)
+        && value.callee.type === 'MemberExpression' && value.callee.computed !== true
+        && identifier(value.callee.object) === objectName
+        && identifier(value.callee.property) === memberName;
+}
+/** A syntactic interaction contract, never a substitute for executing Storybook play. */
+function hasCanvasKeyboardAssertion(play, statements) {
+    const withinName = importedName(statements, 'storybook/test', 'within');
+    const userEventName = importedName(statements, 'storybook/test', 'userEvent');
+    const expectName = importedName(statements, 'storybook/test', 'expect');
+    if (!withinName || !userEventName || !expectName || !Array.isArray(play.params)
+        || !object(play.params[0]) || play.params[0].type !== 'ObjectPattern'
+        || !Array.isArray(play.params[0].properties)
+        || !play.params[0].properties.some((item) => object(item)
+            && object(item.key) && item.key.name === 'canvasElement'
+            && object(item.value) && item.value.name === 'canvasElement'))
+        return false;
+    const variables = nodes(play.body, 'VariableDeclarator');
+    const canvasNames = variables.filter((item) => object(item.init)
+        && item.init.type === 'CallExpression' && identifier(item.init.callee) === withinName
+        && Array.isArray(item.init.arguments) && item.init.arguments.length === 1
+        && identifier(item.init.arguments[0]) === 'canvasElement')
+        .map((item) => identifier(item.id)).filter((name) => !!name);
+    const actionNames = variables.filter((item) => canvasNames.some((name) => calledMember(item.init, name, 'getByRole') && Array.isArray(item.init.arguments)
+        && literal(item.init.arguments[0]) === 'button'
+        && typeof literal(prop(item.init.arguments[1], 'name')) === 'string'
+        && !!literal(prop(item.init.arguments[1], 'name'))?.trim()))
+        .map((item) => identifier(item.id)).filter((name) => !!name);
+    if (actionNames.length === 0)
+        return false;
+    const awaited = nodes(play.body, 'AwaitExpression').map((item) => item.argument);
+    const tabbed = awaited.some((value) => calledMember(value, userEventName, 'tab')
+        && Array.isArray(value.arguments) && value.arguments.length === 0);
+    const focused = awaited.some((value) => object(value) && value.type === 'CallExpression'
+        && object(value.callee) && value.callee.type === 'MemberExpression'
+        && identifier(value.callee.property) === 'toHaveFocus'
+        && object(value.callee.object) && value.callee.object.type === 'CallExpression'
+        && identifier(value.callee.object.callee) === expectName
+        && Array.isArray(value.callee.object.arguments)
+        && actionNames.includes(identifier(value.callee.object.arguments[0]) ?? ''));
+    return tabbed && focused;
+}
+function verifyScreen(root, screen, adapterId) {
+    const base = `src/screens/${stem(screen)}/${stem(screen)}`;
+    const view = ast(root, screen.screenViewPath);
+    const component = exported(body(view), screen.screenViewExport);
+    if (!component || nodes(component, 'JSXElement').length + nodes(component, 'JSXFragment').length === 0)
+        fail();
+    const route = ast(root, screen.appRoutePath);
+    const routeName = importsView(body(route), screen.appRoutePath, screen);
+    if (!hasJsx(route, routeName))
+        fail();
+    const storiesPath = `${base}.stories.tsx`;
+    const stories = ast(root, storiesPath);
+    const storyStatements = body(stories);
+    const adapterModule = adapterId === 'storybook-react-vite'
+        ? '@storybook/react-vite' : '@storybook/nextjs-vite';
+    if (!importedName(storyStatements, adapterModule, 'Meta')
+        || !importedName(storyStatements, adapterModule, 'StoryObj'))
+        fail();
+    const storyViewName = importsView(storyStatements, storiesPath, screen);
+    const defaults = storyStatements.filter((item) => item.type === 'ExportDefaultDeclaration');
+    if (defaults.length !== 1)
+        fail();
+    const defaultValue = unwrap(defaults[0].declaration);
+    const meta = identifier(defaultValue) ? localVariable(storyStatements, identifier(defaultValue))
+        : defaultValue;
+    if (identifier(prop(meta, 'component')) !== storyViewName
+        || literal(prop(meta, 'title')) !== `Screens/${screen.screenId}`)
+        fail();
+    const expected = new Set();
+    for (const state of screen.states)
+        for (const viewport of screen.viewports) {
+            const name = `${pascal(state)}${pascal(viewport)}`;
+            expected.add(name);
+            const story = exported(storyStatements, name);
+            if (!object(story) || story.type !== 'ObjectExpression'
+                || literal(prop(prop(story, 'args'), 'state')) !== state
+                || literal(prop(prop(prop(story, 'parameters'), 'viewport'), 'defaultViewport')) !== viewport)
+                fail();
+            if (screen.critical && (state === 'success' || state === 'recovery')) {
+                const play = prop(story, 'play');
+                if (!object(play) || !['ArrowFunctionExpression', 'FunctionExpression'].includes(String(play.type))
+                    || !hasCanvasKeyboardAssertion(play, storyStatements))
+                    fail();
+            }
+        }
+    const namedExports = storyStatements.filter((item) => item.type === 'ExportNamedDeclaration');
+    if (namedExports.some((item) => !object(item.declaration)
+        || declarations(item.declaration).length !== 1
+        || Array.isArray(item.specifiers) && item.specifiers.length > 0))
+        fail();
+    const actual = namedExports.flatMap((item) => declarations(item.declaration))
+        .map((item) => identifier(item.id)).filter((name) => !!name);
+    if (actual.length !== expected.size || actual.some((name) => !expected.has(name)))
+        fail();
+    const fixture = ast(root, `${base}.fixtures.ts`);
+    const fixtures = body(fixture).filter((item) => item.type === 'ExportNamedDeclaration')
+        .flatMap((item) => object(item.declaration) ? declarations(item.declaration) : []);
+    if (!fixtures.some((item) => {
+        const synthetic = prop(item.init, 'synthetic');
+        return object(synthetic) && synthetic.type === 'BooleanLiteral'
+            && synthetic.value === true && prop(item.init, 'data') !== undefined;
+    }))
+        fail();
+    const handlers = ast(root, `${base}.handlers.ts`);
+    const handlerBody = body(handlers);
+    if (!handlerBody.some((item) => item.type === 'ImportDeclaration'
+        && object(item.source) && item.source.value === 'msw'
+        && Array.isArray(item.specifiers) && item.specifiers.some((specifier) => object(specifier)
+        && object(specifier.imported) && specifier.imported.name === 'http'))
+        || !handlerBody.some((item) => item.type === 'ExportNamedDeclaration'
+            && object(item.declaration) && declarations(item.declaration).some((decl) => object(decl.init)
+            && decl.init.type === 'ArrayExpression' && Array.isArray(decl.init.elements)
+            && decl.init.elements.length > 0))
+        || !nodes(handlers, 'CallExpression').some((call) => object(call.callee)
+            && call.callee.type === 'MemberExpression' && object(call.callee.object)
+            && call.callee.object.name === 'http'))
+        fail();
+    const mdx = source(root, `${base}.mdx`);
+    const mdxStoryImport = new RegExp(`import\\s+\\*\\s+as\\s+([A-Za-z_$][\\w$]*)\\s+from\\s+['"]\\./${stem(screen)}\\.stories(?:\\.tsx)?['"];?\\r?\\n(?:[ \\t]*\\r?\\n)+`)
+        .exec(mdx);
+    if (!/import\s+\{\s*Meta\s*\}\s+from\s+['"]@storybook\/addon-docs\/blocks['"]/.test(mdx)
+        || !mdxStoryImport || !mdx.includes(`<Meta of={${mdxStoryImport[1]}} />`))
+        fail();
+}
+function stableSerialize(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableSerialize).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, nested]) => `${JSON.stringify(key)}:${stableSerialize(nested)}`).join(',')}}`;
+    return JSON.stringify(value) ?? 'null';
+}
+function fingerprint(entries) {
+    const serialized = stableSerialize(entries);
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < serialized.length; index++) {
+        hash ^= serialized.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `uxm-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+function verifyManifest(root, writeSet) {
+    let manifest;
+    try {
+        manifest = JSON.parse(source(root, 'docs/architecture/ux-coverage-manifest.json'));
+    }
+    catch {
+        fail();
+    }
+    if (!object(manifest) || manifest.schemaVersion !== 1
+        || manifest.manifestId !== 'P201-UX-MANIFEST-01'
+        || !Array.isArray(manifest.entries) || typeof manifest.fingerprint !== 'string'
+        || Object.keys(manifest).sort().join(',') !== 'entries,fingerprint,manifestId,schemaVersion'
+        || manifest.fingerprint !== fingerprint(manifest.entries))
+        fail();
+    const expected = new Map();
+    for (const screen of writeSet.screens)
+        for (const state of screen.states)
+            for (const viewport of screen.viewports) {
+                expected.set(`Screens/${screen.screenId}/${state}/${viewport}`, { screen, state, viewport });
+            }
+    if (manifest.entries.length !== expected.size)
+        fail();
+    const seen = new Set();
+    let prior = '';
+    for (const row of manifest.entries) {
+        if (!object(row) || typeof row.storyId !== 'string' || seen.has(row.storyId))
+            fail();
+        if (prior && prior.localeCompare(row.storyId) >= 0)
+            fail();
+        prior = row.storyId;
+        if (Object.keys(row).sort().join(',') !== 'approvalEvidenceIds,fixtureId,handlerIds,journeyIds,screenId,screenViewPath,state,storyId,viewport')
+            fail();
+        seen.add(row.storyId);
+        const match = expected.get(row.storyId);
+        if (!match || row.screenId !== match.screen.screenId || row.state !== match.state
+            || row.viewport !== match.viewport || row.screenViewPath !== match.screen.screenViewPath
+            || !Array.isArray(row.approvalEvidenceIds)
+            || stableSerialize([...row.approvalEvidenceIds].sort())
+                !== stableSerialize([...match.screen.approvalEvidenceIds].sort())
+            || !Array.isArray(row.journeyIds) || row.journeyIds.length < 1
+            || row.journeyIds.some((id) => typeof id !== 'string' || !SAFE_ID.test(id))
+            || new Set(row.journeyIds).size !== row.journeyIds.length
+            || typeof row.fixtureId !== 'string' || !SAFE_ID.test(row.fixtureId)
+            || !Array.isArray(row.handlerIds) || row.handlerIds.length < 1
+            || row.handlerIds.some((id) => typeof id !== 'string' || !SAFE_ID.test(id))
+            || new Set(row.handlerIds).size !== row.handlerIds.length)
+            fail();
+    }
+}
+export function validateUxCandidateSource(projectRoot, writeSet) {
+    try {
+        for (const [path, marker] of [
+            ['docs/architecture/ux-design.md', 'P201-UX-STORYBOOK-01'],
+            ['docs/architecture/storybook-ux-contract.md', 'P201-UX-STORYBOOK-01'],
+        ])
+            if (!source(projectRoot, path).includes(marker))
+                fail();
+        for (const screen of writeSet.screens)
+            verifyScreen(projectRoot, screen, writeSet.adapterId);
+        verifyManifest(projectRoot, writeSet);
+    }
+    catch {
+        fail();
+    }
+}

package/packages/client/dist/private-execution/ux-write-set.js

@@ -1,2 +1,191 @@
-import{execFileSync as I}from"node:child_process";import{createHash as D}from"node:crypto";import{lstatSync as w,readFileSync as b,realpathSync as H}from"node:fs";import{join as h,resolve as k}from"node:path";const d="docs/architecture/ux-execution-authority.json",C=256*1024,x=16*1024*1024,N=48,O=["loading","empty","error","success","permission","recovery"],A=["mobile","tablet","desktop"],v=/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/,W=/^[A-Za-z0-9._@/-]{1,240}$/;function c(){throw new Error("private-execution-ux-write-set-unverified")}function l(t){return D("sha256").update(t).digest("hex")}function z(t){return t!==null&&typeof t=="object"&&!Array.isArray(t)&&Object.getPrototypeOf(t)===Object.prototype}function P(t,r){return Object.keys(t).length===r.length&&r.every(n=>Object.hasOwn(t,n))}function $(t){return typeof t=="string"&&W.test(t)&&t.split("/").every(r=>r!==""&&r!=="."&&r!==".."&&r!==".git")}function j(t,r){return $(t)&&t.endsWith(".tsx")&&(r?/^(?:src\/(?:routes|app|pages)\/|app\/|pages\/)/.test(t):t.startsWith("src/")||t.startsWith("app/"))}function _(t,r){return Array.isArray(t)&&t.length===r.length&&t.every(n=>typeof n=="string")&&new Set(t).size===r.length&&r.every(n=>t.includes(n))}function R(t,r){return Array.isArray(t)&&t.length>0&&t.length<=r.length&&t.every(n=>typeof n=="string"&&r.includes(n))&&new Set(t).size===t.length}function T(t,r){let n=t;const s=r.split("/");for(let a=0;a<s.length;a++){n=h(n,s[a]);try{const p=w(n);if((p.isSymbolicLink()||(a===s.length-1?!p.isFile()||p.size>x:!p.isDirectory()))&&c(),a===s.length-1)return!0}catch(p){if(p.code==="ENOENT")return!1;c()}}return!1}function V(t,r){try{const n=I("git",["ls-tree","HEAD","--",r],{cwd:t,encoding:"utf8",timeout:1e4,maxBuffer:1024});if(!n)return null;const s=/^([0-7]{6}) blob [a-f0-9]{40,64}\t(.+)\n$/.exec(n);return(!s||s[1]!=="100644"&&s[1]!=="100755"||s[2]!==r)&&c(),I("git",["show",`HEAD:${r}`],{cwd:t,timeout:1e4,maxBuffer:x+1})}catch{c()}}function U(t,r,n){/^P[1-9][0-9]{0,11}$/.test(r)||c();const s=k(t);try{(H(s)!==s||!w(s).isDirectory()||!T(s,d))&&c()}catch{c()}const a=b(h(s,d)),p=V(s,d);(!p||a.length<1||a.length>C||!a.equals(p))&&c();let i;try{i=JSON.parse(new TextDecoder("utf-8",{fatal:!0}).decode(a)),`${JSON.stringify(i,null,2)}
-`!==a.toString("utf8")&&c()}catch{c()}(!z(i)||!P(i,["schemaVersion","contractId","targetEpicId","adapterId","screens"])||i.schemaVersion!==1||i.contractId!=="P201-UX-STORYBOOK-01"||i.targetEpicId!==r||!["storybook-react-vite","storybook-nextjs-vite"].includes(String(i.adapterId))||!Array.isArray(i.screens)||i.screens.length<1||i.screens.length>N)&&c();const u=["docs/architecture/ux-design.md","docs/architecture/storybook-ux-contract.md","docs/architecture/ux-coverage-manifest.json"],y=new Set,g=new Set,S=[];for(const e of i.screens){(!z(e)||!P(e,["screenId","critical","route","appRoutePath","screenViewPath","screenViewExport","approvalStatus","approvalEvidenceIds","states","viewports"])||typeof e.screenId!="string"||!v.test(e.screenId)||typeof e.critical!="boolean"||typeof e.route!="string"||!/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$/.test(e.route)||!j(e.appRoutePath,!0)||!j(e.screenViewPath,!1)||typeof e.screenViewExport!="string"||!/^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/.test(e.screenViewExport)||e.approvalStatus!=="approved"||!Array.isArray(e.approvalEvidenceIds)||e.approvalEvidenceIds.length<1||e.approvalEvidenceIds.length>16||e.approvalEvidenceIds.some(f=>typeof f!="string"||!v.test(f))||new Set(e.approvalEvidenceIds).size!==e.approvalEvidenceIds.length||!(e.critical?_(e.states,O):R(e.states,O))||!(e.critical?_(e.viewports,A):R(e.viewports,A))||g.has(e.screenId)||y.has(e.route))&&c(),g.add(e.screenId),y.add(e.route);const o=e.screenId.toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"").slice(0,64);o||c(),S.push(Object.freeze({screenId:e.screenId,critical:e.critical,route:e.route,appRoutePath:e.appRoutePath,screenViewPath:e.screenViewPath,screenViewExport:e.screenViewExport,approvalEvidenceIds:Object.freeze([...e.approvalEvidenceIds]),states:Object.freeze([...e.states]),viewports:Object.freeze([...e.viewports])})),u.push(e.screenViewPath,e.appRoutePath,`src/screens/${o}/${o}.fixtures.ts`,`src/screens/${o}/${o}.handlers.ts`,`src/screens/${o}/${o}.stories.tsx`,`src/screens/${o}/${o}.mdx`)}(u.some(e=>!$(e))||new Set(u.map(e=>e.toLowerCase())).size!==u.length)&&c(),u.sort();const E=Object.create(null);for(const e of u){const o=V(s,e),f=T(s,e);!n&&f!==(o!==null)&&c();const m=f?b(h(s,e)):null;!n&&m&&(!o||!m.equals(o))&&c(),E[e]=o?l(o):null}return Object.freeze({schemaVersion:1,authorityPath:d,targetEpicId:r,adapterId:i.adapterId,authoritySha256:l(a),pathsSha256:l(JSON.stringify(u)),screenCount:i.screens.length,pathCount:u.length,paths:Object.freeze(u),screens:Object.freeze(S),baselineSha256:Object.freeze(E)})}function F(t,r){return U(t,r,!1)}function J(t,r){return U(t,r,!0)}export{d as UX_WRITE_AUTHORITY_PATH,J as deriveUxCandidateWriteSet,F as deriveUxWriteSet};
+/**
+ * P222.26 A08: root-only derivation of an exact UX execution write set.
+ * This is path authority, not semantic A08 acceptance or an agent grant.
+ * The source must be an immutable, tracked approval contract at HEAD; the
+ * private child cannot add screens or paths after its lease is issued.
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export const UX_WRITE_AUTHORITY_PATH = 'docs/architecture/ux-execution-authority.json';
+const MAX_AUTHORITY_BYTES = 256 * 1024;
+const MAX_SOURCE_BYTES = 16 * 1024 * 1024;
+const MAX_SCREENS = 48;
+const REQUIRED_STATES = ['loading', 'empty', 'error', 'success', 'permission', 'recovery'];
+const REQUIRED_VIEWPORTS = ['mobile', 'tablet', 'desktop'];
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const REPO_PATH = /^[A-Za-z0-9._@/-]{1,240}$/;
+function fail() { throw new Error('private-execution-ux-write-set-unverified'); }
+function digest(bytes) { return createHash('sha256').update(bytes).digest('hex'); }
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && Object.getPrototypeOf(value) === Object.prototype;
+}
+function keys(value, expected) {
+    return Object.keys(value).length === expected.length
+        && expected.every((key) => Object.hasOwn(value, key));
+}
+function safePath(value) {
+    return typeof value === 'string' && REPO_PATH.test(value)
+        && value.split('/').every((part) => part !== '' && part !== '.' && part !== '..' && part !== '.git');
+}
+function sourcePath(value, route) {
+    return safePath(value) && value.endsWith('.tsx')
+        && (route ? /^(?:src\/(?:routes|app|pages)\/|app\/|pages\/)/.test(value)
+            : value.startsWith('src/') || value.startsWith('app/'));
+}
+function exactSet(value, expected) {
+    return Array.isArray(value) && value.length === expected.length
+        && value.every((item) => typeof item === 'string')
+        && new Set(value).size === expected.length
+        && expected.every((item) => value.includes(item));
+}
+function subset(value, allowed) {
+    return Array.isArray(value) && value.length > 0 && value.length <= allowed.length
+        && value.every((item) => typeof item === 'string' && allowed.includes(item))
+        && new Set(value).size === value.length;
+}
+function regularOrAbsent(root, path) {
+    let cursor = root;
+    const parts = path.split('/');
+    for (let index = 0; index < parts.length; index++) {
+        cursor = join(cursor, parts[index]);
+        try {
+            const entry = lstatSync(cursor);
+            if (entry.isSymbolicLink() || (index === parts.length - 1
+                ? !entry.isFile() || entry.size > MAX_SOURCE_BYTES : !entry.isDirectory()))
+                fail();
+            if (index === parts.length - 1)
+                return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            fail();
+        }
+    }
+    return false;
+}
+function headFile(root, path) {
+    try {
+        const mode = execFileSync('git', ['ls-tree', 'HEAD', '--', path], {
+            cwd: root, encoding: 'utf8', timeout: 10_000, maxBuffer: 1024,
+        });
+        if (!mode)
+            return null;
+        const match = /^([0-7]{6}) blob [a-f0-9]{40,64}\t(.+)\n$/.exec(mode);
+        if (!match || match[1] !== '100644' && match[1] !== '100755' || match[2] !== path)
+            fail();
+        return execFileSync('git', ['show', `HEAD:${path}`], {
+            cwd: root, timeout: 10_000, maxBuffer: MAX_SOURCE_BYTES + 1,
+        });
+    }
+    catch {
+        fail();
+    }
+}
+/** No filesystem mutation. A missing/uncommitted/changed approval file fails closed. */
+function derive(projectRoot, targetEpicId, candidate) {
+    if (!/^P[1-9][0-9]{0,11}$/.test(targetEpicId))
+        fail();
+    const root = resolve(projectRoot);
+    try {
+        if (realpathSync(root) !== root || !lstatSync(root).isDirectory()
+            || !regularOrAbsent(root, UX_WRITE_AUTHORITY_PATH))
+            fail();
+    }
+    catch {
+        fail();
+    }
+    const source = readFileSync(join(root, UX_WRITE_AUTHORITY_PATH));
+    const atHead = headFile(root, UX_WRITE_AUTHORITY_PATH);
+    if (!atHead || source.length < 1 || source.length > MAX_AUTHORITY_BYTES || !source.equals(atHead))
+        fail();
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(source));
+        if (`${JSON.stringify(parsed, null, 2)}\n` !== source.toString('utf8'))
+            fail();
+    }
+    catch {
+        fail();
+    }
+    if (!object(parsed) || !keys(parsed, ['schemaVersion', 'contractId', 'targetEpicId', 'adapterId', 'screens'])
+        || parsed.schemaVersion !== 1 || parsed.contractId !== 'P201-UX-STORYBOOK-01'
+        || parsed.targetEpicId !== targetEpicId
+        || !['storybook-react-vite', 'storybook-nextjs-vite'].includes(String(parsed.adapterId))
+        || !Array.isArray(parsed.screens) || parsed.screens.length < 1 || parsed.screens.length > MAX_SCREENS)
+        fail();
+    const paths = ['docs/architecture/ux-design.md', 'docs/architecture/storybook-ux-contract.md',
+        'docs/architecture/ux-coverage-manifest.json'];
+    const routeNames = new Set();
+    const screenIds = new Set();
+    const screens = [];
+    for (const screen of parsed.screens) {
+        if (!object(screen) || !keys(screen, ['screenId', 'critical', 'route', 'appRoutePath', 'screenViewPath',
+            'screenViewExport', 'approvalStatus', 'approvalEvidenceIds', 'states', 'viewports'])
+            || typeof screen.screenId !== 'string' || !ID.test(screen.screenId)
+            || typeof screen.critical !== 'boolean'
+            || typeof screen.route !== 'string'
+            || !/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$/.test(screen.route)
+            || !sourcePath(screen.appRoutePath, true) || !sourcePath(screen.screenViewPath, false)
+            || typeof screen.screenViewExport !== 'string'
+            || !/^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/.test(screen.screenViewExport)
+            || screen.approvalStatus !== 'approved'
+            || !Array.isArray(screen.approvalEvidenceIds) || screen.approvalEvidenceIds.length < 1
+            || screen.approvalEvidenceIds.length > 16
+            || screen.approvalEvidenceIds.some((id) => typeof id !== 'string' || !ID.test(id))
+            || new Set(screen.approvalEvidenceIds).size !== screen.approvalEvidenceIds.length
+            || !(screen.critical ? exactSet(screen.states, REQUIRED_STATES)
+                : subset(screen.states, REQUIRED_STATES))
+            || !(screen.critical ? exactSet(screen.viewports, REQUIRED_VIEWPORTS)
+                : subset(screen.viewports, REQUIRED_VIEWPORTS))
+            || screenIds.has(screen.screenId) || routeNames.has(screen.route))
+            fail();
+        screenIds.add(screen.screenId);
+        routeNames.add(screen.route);
+        const stem = screen.screenId.toLowerCase().replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '').slice(0, 64);
+        if (!stem)
+            fail();
+        screens.push(Object.freeze({ screenId: screen.screenId,
+            critical: screen.critical, route: screen.route,
+            appRoutePath: screen.appRoutePath,
+            screenViewPath: screen.screenViewPath,
+            screenViewExport: screen.screenViewExport,
+            approvalEvidenceIds: Object.freeze([...screen.approvalEvidenceIds]),
+            states: Object.freeze([...screen.states]),
+            viewports: Object.freeze([...screen.viewports]),
+        }));
+        paths.push(screen.screenViewPath, screen.appRoutePath, `src/screens/${stem}/${stem}.fixtures.ts`, `src/screens/${stem}/${stem}.handlers.ts`, `src/screens/${stem}/${stem}.stories.tsx`, `src/screens/${stem}/${stem}.mdx`);
+    }
+    if (paths.some((path) => !safePath(path))
+        || new Set(paths.map((path) => path.toLowerCase())).size !== paths.length)
+        fail();
+    paths.sort();
+    const baselineSha256 = Object.create(null);
+    for (const path of paths) {
+        const committed = headFile(root, path);
+        const exists = regularOrAbsent(root, path);
+        if (!candidate && exists !== (committed !== null))
+            fail();
+        const current = exists ? readFileSync(join(root, path)) : null;
+        if (!candidate && current && (!committed || !current.equals(committed)))
+            fail();
+        baselineSha256[path] = committed ? digest(committed) : null;
+    }
+    return Object.freeze({ schemaVersion: 1, authorityPath: UX_WRITE_AUTHORITY_PATH,
+        targetEpicId, adapterId: parsed.adapterId,
+        authoritySha256: digest(source), pathsSha256: digest(JSON.stringify(paths)),
+        screenCount: parsed.screens.length, pathCount: paths.length,
+        paths: Object.freeze(paths), screens: Object.freeze(screens),
+        baselineSha256: Object.freeze(baselineSha256) });
+}
+export function deriveUxWriteSet(projectRoot, targetEpicId) {
+    return derive(projectRoot, targetEpicId, false);
+}
+/** Clone-only projection; admission still verifies every effect before applying it to root. */
+export function deriveUxCandidateWriteSet(projectRoot, targetEpicId) {
+    return derive(projectRoot, targetEpicId, true);
+}