@notis_ai/cli 0.2.0-beta.191.1 → 0.2.0-beta.197.1

package/src/runtime/space-source.js

@@ -0,0 +1,281 @@
+/** Selected, reproducible source slices; never archive a sibling by tree position. */
+import { createRequire } from 'node:module';
+import { realpathSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { collectSourceFiles, loadAppConfig } from './app-platform.js';
+import { usageError } from './errors.js';
+import { VIEW_DEFINITION_FIELDS, viewManifestFields } from './space-view-manifest.js';
+
+const CONFIG_FIELDS = new Set(['name', 'description', 'icon', 'accent', 'entry', 'layout', 'readableContext', 'resources', 'actions', 'navigation', 'viewerReads', 'cloudComputer', 'collection', 'sourceIncludes', 'verificationFixtures', ...VIEW_DEFINITION_FIELDS]);
+/** Reads with each signed-in viewer's own authority (never an issuer grant); see docs/notis-apps-platform.md. */
+export const VIEWER_READ_FAMILIES = Object.freeze(['databases', 'skills']);
+const WORKSPACE_INDEXES = new Set(['notis.config.ts', 'notis.config.js', 'notis.config.mjs']);
+const ROOT_CONFIGS = ['package.json', 'package-lock.json', 'tsconfig.json', 'vite.config.ts', 'vite.config.js', 'vite.config.mjs',
+  'postcss.config.js', 'postcss.config.cjs', 'postcss.config.mjs', 'tailwind.config.ts', 'tailwind.config.js', 'tailwind.config.cjs', 'tailwind.config.mjs'];
+
+function sourceCompiler(projectDir, files) {
+  const require = createRequire(join(projectDir, 'package.json'));
+  let ts;
+  try { ts = require('typescript'); }
+  catch { throw usageError('Install this workspace\'s TypeScript dependency before packaging Space source.'); }
+  const codeFiles = Object.keys(files).filter(path => /\.[cm]?[jt]sx?$/.test(path)).map(path => join(projectDir, path));
+  let source, checker, syntax, close = () => {};
+  if (typeof ts.createProgram === 'function') {
+    let options = { moduleResolution: ts.ModuleResolutionKind.Bundler, allowJs: true };
+    if (files['tsconfig.json']) {
+      const config = ts.readConfigFile(join(projectDir, 'tsconfig.json'), ts.sys.readFile);
+      if (config.error) throw usageError('Fix tsconfig.json before building this Space.');
+      options = { ...options, ...ts.parseJsonConfigFileContent(config.config, ts.sys, projectDir).options, allowJs: true };
+    }
+    const program = ts.createProgram(codeFiles, options), projectChecker = program.getTypeChecker();
+    source = file => program.getSourceFile(join(projectDir, file));
+    checker = () => projectChecker;
+    syntax = ts.SyntaxKind;
+  } else {
+    // TypeScript 7 ships the native compiler and moves JS APIs under unstable/.
+    // Keep one scoped API process, rather than falling back to regex parsing or
+    // assuming the old typescript package exports a parser.
+    const { API } = require('typescript/unstable/sync');
+    syntax = require('typescript/unstable/ast').SyntaxKind;
+    const api = new API({ cwd: projectDir });
+    try {
+      const snapshot = api.updateSnapshot({ openFiles: codeFiles });
+      const project = file => snapshot.getDefaultProjectForFile(join(projectDir, file));
+      source = file => project(file)?.program.getSourceFile(join(projectDir, file));
+      checker = file => project(file)?.checker;
+      close = () => { try { snapshot.dispose(); } finally { api.close(); } };
+    } catch (error) { api.close(); throw error; }
+  }
+  return {
+    close,
+    inspect(file) {
+      const tree = source(file);
+      if (!tree) throw usageError(`The compiler could not inspect ${file}. Include it in this project's TypeScript configuration.`);
+      let dynamic = false;
+      const assets = [];
+      const visit = node => {
+        if (node.kind === syntax.CallExpression && node.expression.kind === syntax.ImportKeyword
+          && ![syntax.StringLiteral, syntax.NoSubstitutionTemplateLiteral].includes(node.arguments[0]?.kind)) dynamic = true;
+        if (node.kind === syntax.NewExpression && node.expression.getText() === 'URL' && node.arguments?.[1]?.getText() === 'import.meta.url') {
+          if ([syntax.StringLiteral, syntax.NoSubstitutionTemplateLiteral].includes(node.arguments[0]?.kind)) assets.push(node.arguments[0].text);
+          else dynamic = true;
+        }
+        if (node.kind === syntax.CallExpression && node.expression.getText().startsWith('import.meta.glob')) dynamic = true;
+        node.forEachChild(visit);
+      };
+      visit(tree);
+      return { dynamic, assets, references: (tree.referencedFiles || []).map(item => item.fileName),
+        imports: (tree.imports || []).map(node => {
+          const symbol = checker(file)?.getSymbolAtLocation(node);
+          const declaration = symbol?.declarations?.[0];
+          const resolved = declaration?.resolve ? declaration.resolve() : declaration;
+          return { specifier: node.text, resolved: resolved?.getSourceFile().fileName };
+        }) };
+    },
+  };
+}
+
+function key(value, label) {
+  if (typeof value !== 'string' || !/^[a-z][a-z0-9_-]{0,99}$/.test(value)) throw usageError(`${label} must be a stable lowercase source key.`);
+  return value;
+}
+
+function localPath(value) {
+  if (typeof value !== 'string' || !value || value.includes('\\') || value.startsWith('/') || value.includes('\0')
+    || value.split('/').some(part => part === '..') || value.startsWith('.notis/') || value.startsWith('.env')) {
+    throw usageError('Use a source path inside this workspace, without private profile state.');
+  }
+  return value.replace(/^\.\//, '').replace(/\/$/, '');
+}
+
+export async function loadSelectedSpace(projectDir, selectedKey) {
+  projectDir = realpathSync(projectDir);
+  selectedKey = key(selectedKey, 'Space');
+  const workspace = await loadAppConfig(projectDir);
+  if (!workspace || typeof workspace !== 'object' || Array.isArray(workspace) || !workspace.spaces
+    || typeof workspace.spaces !== 'object' || Object.keys(workspace).some(name => !['spaces', 'resources', 'defaultSpace'].includes(name))) {
+    throw usageError('Use defineSpaces with an explicit workspace Space index.');
+  }
+  if (!Object.hasOwn(workspace.spaces, selectedKey)) throw usageError('Choose a Space declared in this source workspace.');
+  const reference = workspace.spaces[selectedKey];
+  if (!reference || typeof reference !== 'object' || Object.keys(reference).some(name => !['definition', 'parent', 'defaultChild'].includes(name))) {
+    throw usageError('A workspace Space entry declares a definition file and optional composition.');
+  }
+  const definitionPath = localPath(reference.definition);
+  const definition = await loadAppConfig(projectDir, { file: definitionPath });
+  if (!definition || typeof definition !== 'object' || Array.isArray(definition) || Object.keys(definition).some(name => !CONFIG_FIELDS.has(name))
+    || typeof definition.name !== 'string' || !definition.name.trim() || definition.name.length > 200) {
+    throw usageError('Use a named Space definition with explicit entry, resources and actions.');
+  }
+  const resolveDefinitionPath = value => {
+    if (typeof value !== 'string' || !value || value.startsWith('/') || value.includes('\\') || value.includes('\0')) throw usageError('Use a workspace-relative source path.');
+    return localPath(relative(projectDir, resolve(projectDir, dirname(definitionPath), value)).split(sep).join('/'));
+  };
+  const entry = definition.entry ? resolveDefinitionPath(definition.entry) : null;
+  const layout = definition.layout ? resolveDefinitionPath(definition.layout) : null;
+  if (!entry && layout) throw usageError('A container has no executable layout.');
+  const resources = definition.resources || {};
+  if (definition.navigation != null && (typeof definition.navigation !== 'object' || Array.isArray(definition.navigation))) {
+    throw usageError('Declare portable named Space destinations.');
+  }
+  for (const [alias, target] of Object.entries(definition.navigation || {})) {
+    key(alias, 'Navigation alias');
+    if (!target || typeof target !== 'object' || Object.keys(target).join(',') !== 'key') throw usageError('A navigation reference needs one portable key.');
+    key(target.key, 'Navigation target');
+  }
+  for (const [alias, resource] of Object.entries(resources)) {
+    key(alias, 'Resource alias');
+    if (resource?.kind === 'database' && resource.create != null) {
+      const value = resource.create;
+      if (Object.keys(resource).some(name => !['kind', 'create'].includes(name))
+        || !value || typeof value !== 'object' || Array.isArray(value)
+        || Object.keys(value).some(name => !['name', 'schema', 'starterRows'].includes(name))
+        || typeof value.name !== 'string' || !value.name.trim() || value.name.length > 200
+        || !value.schema || typeof value.schema !== 'object' || Array.isArray(value.schema)
+        || (value.starterRows !== undefined && (!Array.isArray(value.starterRows) || value.starterRows.length > 100
+          || value.starterRows.some(row => !row || typeof row !== 'object' || Array.isArray(row))))) {
+        throw usageError(`Database ${alias} needs create:{name,schema,starterRows?}, without an existing key.`);
+      }
+      if (!Object.values(definition.params || {}).some(param => param?.type === 'record' && param.database === alias && param.main === true)) {
+        throw usageError(`New database ${alias} needs a record param marked main in this view.`);
+      }
+      continue;
+    }
+    if (!resource || !['database', 'document', 'skill', 'automation'].includes(resource.kind) || typeof resource.key !== 'string'
+      || Object.keys(resource).some(name => !['kind', 'key'].includes(name))) throw usageError(`Invalid resource reference: ${alias}`);
+  }
+  if (definition.viewerReads != null && (!Array.isArray(definition.viewerReads)
+    || definition.viewerReads.some(family => !VIEWER_READ_FAMILIES.includes(family))
+    || new Set(definition.viewerReads).size !== definition.viewerReads.length)) {
+    throw usageError("viewerReads lists 'databases' and/or 'skills' once each: the page reads what each signed-in viewer can open.");
+  }
+  if (definition.viewerReads?.length && !entry) throw usageError('A container has no page, so it cannot declare viewerReads.');
+  if (definition.cloudComputer != null && !['read', 'shell'].includes(definition.cloudComputer)) {
+    throw usageError("cloudComputer is 'read' or 'shell': the page uses each signed-in viewer's own cloud computer once that viewer allows it.");
+  }
+  if (definition.cloudComputer != null && !entry) throw usageError('A container has no page, so it cannot use the cloud computer.');
+  if (definition.collection && (resources[definition.collection.database]?.kind !== 'database' || !definition.collection.titleProperty)) {
+    throw usageError('A collection needs a declared database binding and title property.');
+  }
+  for (const [actionId, template] of Object.entries(definition.actions || {})) {
+    key(actionId, 'Action');
+    if (!template || typeof template.tool !== 'string' || !template.tool || Object.keys(template).sort().join(',') !== 'arguments,inputs,tool'
+      || template.inputs?.type !== 'object' || template.inputs?.additionalProperties !== false || !template.arguments || Array.isArray(template.arguments)) {
+      throw usageError(`Action ${actionId} needs the canonical closed inputs/tool/arguments template.`);
+    }
+    const scan = value => {
+      if (Array.isArray(value)) { value.forEach(scan); return; }
+      if (!value || typeof value !== 'object' || Object.hasOwn(value, '$literal')) return;
+      if (Object.hasOwn(value, '$asset') && !Object.hasOwn(resources, value.$asset)) throw usageError(`Action ${actionId} uses an undeclared resource alias.`);
+      Object.values(value).forEach(scan);
+    };
+    scan(template.arguments);
+  }
+  // V4 view manifest (path, params, shows, memory, chrome, markdown); required with specVersion 2.
+  viewManifestFields(definition, { entry, resources });
+  const markdown = definition.markdown ? resolveDefinitionPath(definition.markdown) : null;
+  const fixturePath = definition.verificationFixtures ? resolveDefinitionPath(definition.verificationFixtures) : null;
+  return { key: selectedKey, workspace, definition, definitionPath, entry, layout, markdown, fixturePath, resolveDefinitionPath };
+}
+
+
+/** Include type-only/local declarations too; bundle chunks alone omit them. */
+export function collectSelectedSpaceSource(projectDir, selection, { buildInputs = [] } = {}) {
+  projectDir = realpathSync(projectDir);
+  const files = collectSourceFiles(projectDir), selected = new Set(), queued = [];
+  const compiler = sourceCompiler(projectDir, files);
+  try {
+  function add(path) {
+    path = localPath(path);
+    if (path === 'resources.json' || path === 'skills' || path.startsWith('skills/')) {
+      throw usageError('Resource lists and Skill folders use native Space transport, not sourceIncludes or view imports.');
+    }
+    // This is a synthesized input in the frozen workspace. Its original imports
+    // describe unrelated composition, not dependencies of the selected Space.
+    if (WORKSPACE_INDEXES.has(path)) return;
+    if (!Object.hasOwn(files, path)) throw usageError(`Source dependency is missing, private or linked: ${path}`);
+    if (!selected.has(path)) { selected.add(path); queued.push(path); }
+  }
+  function dependency(specifier, importer, resolved) {
+    if (typeof specifier !== 'string' || specifier.startsWith('node:')) return;
+    if (resolved) {
+      const path = relative(projectDir, resolved).split(sep).join('/');
+      const external = path.includes('/node_modules/') || path.startsWith('node_modules/');
+      if (!external) { add(path); return; }
+      // A relative import is always project source. An ambient declaration such as
+      // vite/client's `*.css` module can claim it depending on the working directory.
+      if (!specifier.startsWith('.')) return;
+    }
+    const raw = specifier.split(/[?#]/, 1)[0];
+    const path = relative(projectDir, resolve(dirname(join(projectDir, importer)), raw)).split(sep).join('/');
+    const candidate = [path, ...['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.d.ts', '/index.ts', '/index.tsx', '/index.js'].map(suffix => path + suffix)]
+      .find(name => Object.hasOwn(files, name));
+    if (candidate) { add(candidate); return; }
+    if (specifier.startsWith('.') || specifier.startsWith('@/') || specifier.startsWith('#')) throw usageError(`Unresolved source dependency ${specifier} in ${importer}.`);
+  }
+  ROOT_CONFIGS.filter(path => Object.hasOwn(files, path)).forEach(add);
+  const projectPackage = JSON.parse(Buffer.from(files['package.json'] || '', 'base64').toString('utf8'));
+  for (const dependency of Object.values({ ...projectPackage.dependencies, ...projectPackage.devDependencies })) {
+    if (typeof dependency !== 'string' || !dependency.startsWith('file:')) continue;
+    const directory = localPath(dependency.slice(5));
+    add(`${directory}/package.json`);
+    const metadata = JSON.parse(Buffer.from(files[`${directory}/package.json`], 'base64').toString('utf8'));
+    const declared = value => {
+      if (typeof value === 'string' && value.startsWith('./')) add(`${directory}/${value.slice(2)}`);
+      else if (value && typeof value === 'object') Object.values(value).forEach(declared);
+    };
+    declared(metadata.exports);
+    for (const value of [metadata.main, metadata.module, metadata.types]) if (typeof value === 'string') add(`${directory}/${value.replace(/^\.\//, '')}`);
+  }
+  add(selection.definitionPath);
+  if (selection.entry) add(selection.entry);
+  if (selection.layout) add(selection.layout);
+  if (selection.markdown) add(selection.markdown);
+  if (selection.fixturePath) add(selection.fixturePath);
+  for (const include of selection.definition.sourceIncludes || []) {
+    const path = selection.resolveDefinitionPath(include);
+    const matches = Object.keys(files).filter(name => name === path || name.startsWith(path + '/'));
+    if (!matches.length) throw usageError(`No source files match explicit inclusion ${path}.`);
+    matches.forEach(add);
+  }
+  for (const reference of Object.values(selection.definition.resources || {})) {
+    if (reference.create || reference.kind === 'skill') continue;
+    const resource = selection.workspace.resources?.[reference.key];
+    if (resource) {
+      if (resource.kind !== reference.kind) throw usageError(`Resource kind changed for ${reference.key}.`);
+      const path = localPath(resource.source);
+      const matches = Object.keys(files).filter(name => name === path || name.startsWith(path + '/'));
+      if (!matches.length) throw usageError(`Missing declared resource source ${path}.`);
+      matches.forEach(add);
+    }
+  }
+  for (const input of buildInputs) {
+    const path = relative(projectDir, input.split(/[?#]/, 1)[0]).split(sep).join('/');
+    if (path.startsWith('.notis/') || path.includes('/node_modules/') || path.startsWith('node_modules/')) continue;
+    add(path);
+  }
+  while (queued.length) {
+    const file = queued.shift(), source = Buffer.from(files[file], 'base64').toString('utf8');
+    if (/\.[cm]?[jt]sx?$/.test(file)) {
+      const parsed = compiler.inspect(file);
+      for (const entry of parsed.imports) dependency(entry.specifier, file, entry.resolved);
+      for (const reference of parsed.references) dependency(reference, file);
+      for (const asset of parsed.assets) dependency(asset, file);
+      if (parsed.dynamic && !(selection.definition.sourceIncludes || []).length) throw usageError(`Declare sourceIncludes for dynamic source dependencies in ${file}.`);
+    } else if (extname(file) === '.css') {
+      for (const match of source.matchAll(/@(import|config)\s+(?:url\(\s*)?['"]([^'"]+)['"]/g)) {
+        if (match[2].startsWith('.')) dependency(match[2], file);
+      }
+      for (const match of source.matchAll(/url\(\s*['"]?(\.[^'"\s)]+)['"]?\s*\)/g)) dependency(match[1], file);
+    }
+  }
+  const result = Object.fromEntries([...selected].sort().map(path => [path, files[path]]));
+  // The exported index describes this target only. Composition is not a source
+  // permission and publishing one definition never applies siblings or parents.
+  for (const path of WORKSPACE_INDEXES) delete result[path];
+  const resourceKeys = new Set(Object.values(selection.definition.resources || {}).map(resource => resource.key));
+  const resources = Object.fromEntries(Object.entries(selection.workspace.resources || {}).filter(([name]) => resourceKeys.has(name)));
+  result['notis.config.ts'] = Buffer.from(`import { defineSpaces } from '@notis/sdk/config';\nexport default defineSpaces(${JSON.stringify({ spaces: { [selection.key]: { definition: selection.definitionPath } }, resources, defaultSpace: selection.key }, null, 2)});\n`).toString('base64');
+  return result;
+  } finally { compiler.close(); }
+}

package/src/runtime/space-test-server.js

@@ -0,0 +1,327 @@
+/** Offline, frozen Space fixtures. No credentials or provider transport exist here. */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { dirname, join, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { appFilesDigest } from './app-platform.js';
+import { usageError } from './errors.js';
+
+const ROOT=resolve(dirname(fileURLToPath(import.meta.url)),'../..');
+// Credentialless worker + non-forwarding proxy own the offline boundary.
+// Source shares the Shadow host realm and may call only this fixture origin.
+const HOST_POLICY="default-src 'none'; script-src 'self' blob: data:; style-src 'self' 'unsafe-inline'; img-src data: blob:; font-src data:; connect-src 'self'; frame-src 'none'; frame-ancestors 'self'; form-action 'none'; base-uri 'none'";
+
+function object(value) { return value && typeof value==='object' && !Array.isArray(value); }
+/** The declared params a list's filter reads (server shown_list_params); `{record}` reads the first record param. */
+function shownListParams(where, params) {
+  const declared=object(params) ? params : {};
+  const single=Object.entries(declared).find(([,item])=>object(item) && item.type==='record')?.[0] ?? null;
+  const names=new Set();
+  const walk=node=>{
+    if(!object(node)) return;
+    for(const group of ['and','or']) if(Array.isArray(node[group])) { node[group].forEach(walk); return; }
+    for(const value of Array.isArray(node.value)?node.value:[node.value]) {
+      const match=typeof value==='string' ? /^\{([a-z][A-Za-z0-9_]{0,63})(?:\.([^{}.\s][^{}]{0,199}))?\}$/.exec(value) : null;
+      const name=match?.[1]==='record' ? single : match?.[1];
+      if(name && Object.hasOwn(declared,name)) names.add(name);
+    }
+  };
+  walk(where);
+  return [...names].sort();
+}
+/** Public runtime declarations (server declared_view_runtime): params, list names and chrome, never filters. */
+function viewDeclarations(manifest) {
+  const shows=Object.fromEntries(Object.entries(manifest.shows || {}).map(([name,value])=>[name,Object.hasOwn(value,'where')
+    ? {database:value.database,...(value.open?{open:value.open}:{}),params:shownListParams(value.where,manifest.params)} : {about:value.about,...(value.services?.length?{services:value.services}:{})}]));
+  return {...(manifest.params && Object.keys(manifest.params).length?{params:structuredClone(manifest.params)}:{}),
+    ...(Object.keys(shows).length?{shows}:{}),...(['portal','hidden'].includes(manifest.chrome)?{chrome:manifest.chrome}:{})};
+}
+const VIEWER_READS={list_databases:'databases',get_database:'databases',query_database:'databases',list_skills:'skills',get_skill:'skills'};
+
+export function createSpaceFixtureEngine(release) {
+  const bodyTemplates=structuredClone(release.manifest.actions || {});
+  const bodyResources=structuredClone(release.manifest.resources || {});
+  let fixtures={actions:{}};
+  if(release.fixturePath) {
+    const encoded=release.sourceFiles[release.fixturePath];
+    if(typeof encoded!=='string') throw usageError('The selected verification fixtures are missing from the frozen source.');
+    try { fixtures=JSON.parse(Buffer.from(encoded,'base64').toString('utf8')); }
+    catch { throw usageError('Verification fixtures must be finite JSON objects.'); }
+  }
+  if(!object(fixtures) || Object.keys(fixtures).some(key=>!['actions','context','documentBodies','viewerReads','shown','recordViews'].includes(key)) || !object(fixtures.actions)
+    || (fixtures.context!==undefined && !object(fixtures.context))) throw usageError('Verification fixtures declare actions and optional synthetic context.');
+  // Viewer reads have no grant: fixtures stand in for what a signed-in viewer could open.
+  const declaredReads=release.manifest.viewer_reads || [];
+  // V4: a declared list is served from fixtures per exact params, like a signed-in Editor's read.
+  const declaredLists=Object.fromEntries(Object.entries(release.manifest.shows || {}).filter(([,value])=>object(value) && Object.hasOwn(value,'where')));
+  const shownCases=fixtures.shown ?? {};
+  if(!object(shownCases)) throw usageError('Declare shown fixtures by list name.');
+  for(const [name,cases] of Object.entries(shownCases)) {
+    if(!Object.hasOwn(declaredLists,name) || !Array.isArray(cases) || !cases.length || cases.length>100) {
+      throw usageError(`Declare shown fixtures only for lists this view declares with a filter (${name}).`);
+    }
+    const previous=[];
+    for(const entry of cases) {
+      if(!object(entry) || Object.keys(entry).some(key=>!['params','result'].includes(key)) || !object(entry.params) || !object(entry.result)) {
+        throw usageError(`Declare each ${name} fixture as params and a result.`);
+      }
+      if(previous.some(params=>isDeepStrictEqual(params,entry.params))) throw usageError(`Ambiguous shown fixture for ${name}.`);
+      previous.push(entry.params);
+    }
+  }
+  const readCases=fixtures.viewerReads ?? {};
+  if(!object(readCases)) throw usageError('Declare viewerReads fixtures by read operation.');
+  for(const [operation,cases] of Object.entries(readCases)) {
+    if(!Object.hasOwn(VIEWER_READS,operation) || !declaredReads.includes(VIEWER_READS[operation]) || !Array.isArray(cases) || !cases.length || cases.length>100) {
+      throw usageError(`Declare explicit viewer read fixtures only for reads this Space declares (${operation}).`);
+    }
+    const previous=[];
+    for(const entry of cases) {
+      if(!object(entry) || Object.keys(entry).some(key=>!['input','result'].includes(key)) || !Object.hasOwn(entry,'result') || !object(entry.input)) {
+        throw usageError(`Declare each ${operation} fixture as an input object and a result.`);
+      }
+      if(previous.some(input=>isDeepStrictEqual(input,entry.input))) throw usageError(`Ambiguous viewer read fixture for ${operation}.`);
+      previous.push(entry.input);
+    }
+  }
+  const ajv=new Ajv2020({strict:false,strictNumbers:true,allErrors:true,coerceTypes:false,useDefaults:false,removeAdditional:false});
+  addFormats(ajv);
+  const validators=new Map();
+  for(const [name,template] of Object.entries(release.manifest.actions || {})) {
+    let validate;
+    try { validate=ajv.compile(template.inputs); }
+    catch { throw usageError(`Cannot validate the declared inputs for ${name}.`); }
+    validators.set(name,validate);
+  }
+  for(const [name,cases] of Object.entries(fixtures.actions)) {
+    const validate=validators.get(name);
+    if(!validate || !Array.isArray(cases) || !cases.length || cases.length>100) throw usageError(`Declare explicit fixture cases for the known action ${name}.`);
+    const previous=[];
+    for(const entry of cases) {
+      if(!object(entry) || Object.keys(entry).some(key=>!['inputs','result'].includes(key)) || !Object.hasOwn(entry,'result')
+        || !object(entry.inputs) || !validate(entry.inputs)) throw usageError(`Fixture inputs do not match the declared action ${name}.`);
+      if(previous.some(inputs=>isDeepStrictEqual(inputs,entry.inputs))) throw usageError(`Ambiguous fixture inputs for ${name}.`);
+      previous.push(entry.inputs);
+    }
+  }
+  const bodies=fixtures.documentBodies || [];
+  if(!Array.isArray(bodies) || bodies.length>100) throw usageError('Declare bounded synthetic documentBodies fixtures.');
+  function bodyRequest(request) {
+    if(!object(request) || Object.keys(request).sort().join(',')!=='binding,operation,readAction,recordKey'
+      || request.operation!=='read' || typeof request.recordKey!=='string' || !/^[a-f0-9-]{36}$/i.test(request.recordKey)) {
+      throw usageError('Verification supports exact synthetic document body reads only.');
+    }
+    const template=bodyTemplates[request.readAction];
+    if(bodyResources[request.binding]?.kind!=='database' || template?.tool!=='LOCAL_NOTIS_DATABASE_QUERY'
+      || !isDeepStrictEqual(template.arguments,{database_id:{$asset:request.binding},request:{$input:'request'}})) {
+      throw usageError('Choose a declared canonical query action for this document binding.');
+    }
+    const inputs={request:{filter:{field:{column:'record_key'},op:'equals',value:request.recordKey},page_size:1,include_content:true}};
+    if(!validators.get(request.readAction)?.(inputs)) throw usageError('The body read inputs do not match this action declaration.');
+  }
+  const previousBodies=[];
+  for(const entry of bodies) {
+    if(!object(entry) || Object.keys(entry).some(key=>!['request','result'].includes(key))) throw usageError('Declare a document body request and result.');
+    bodyRequest(entry.request);
+    const result=entry.result;
+    if(!object(result) || Object.keys(result).some(key=>!['record_key','title','revision','schema_revision','content_markdown'].includes(key))
+      || result.record_key!==entry.request.recordKey || typeof result.content_markdown!=='string'
+      || !Number.isSafeInteger(result.revision) || result.revision<1 || !Number.isSafeInteger(result.schema_revision) || result.schema_revision<0
+      || (result.title!==null && typeof result.title!=='string')) throw usageError('Declare a complete synthetic document body result.');
+    if(previousBodies.some(request=>isDeepStrictEqual(request,entry.request))) throw usageError('Ambiguous document body fixture.');
+    previousBodies.push(entry.request);
+  }
+  // First-party record components use explicit readonly fixtures. They never
+  // need a collaboration token, upload path, property writer or database key.
+  const recordViews=fixtures.recordViews ?? [];
+  if(!Array.isArray(recordViews) || recordViews.length>100) throw usageError('Declare bounded synthetic recordViews fixtures.');
+  const recordDeclarations=Object.values(release.manifest.params || {}).filter(value=>value?.type==='record');
+  const previousViews=new Set();
+  for(const entry of recordViews) {
+    if(!object(entry) || Object.keys(entry).sort().join(',')!=='operation,record_key,result'
+      || !['record','html','report'].includes(entry.operation) || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(entry.record_key)
+      || !object(entry.result) || !recordDeclarations.length
+      || !recordDeclarations.every(value=>bodyResources[value.database]?.kind==='database')) throw usageError('Declare readonly recordViews only for a declared native record param.');
+    const identity=entry.operation+':'+entry.record_key;
+    if(previousViews.has(identity)) throw usageError('Ambiguous record view fixture.');
+    previousViews.add(identity);
+    const value=entry.result;
+    if(entry.operation==='record' && (value.record_key!==entry.record_key || !object(value.document) || !object(value.schema)
+      || value.writable!==false || Object.hasOwn(value,'target') || value.document.record_key!==entry.record_key)) throw usageError('Record fixtures must be readonly snapshots without authoring targets.');
+    if(entry.operation==='html' && (typeof value.html!=='string' || value.record_key!==entry.record_key)) throw usageError('HTML fixtures contain a record key and HTML.');
+    if(entry.operation==='report' && (typeof value.source!=='string' || typeof value.export_name!=='string')) throw usageError('Report fixtures contain an explicit readonly source and export.');
+  }
+  return { context:fixtures.context || {}, digest:createHash('sha256').update(JSON.stringify(fixtures)).digest('hex'),
+    executeRecordView(operation,key) {
+      const match=recordViews.find(value=>value.operation===operation && value.record_key===key);
+      if(!match) throw usageError('Add an explicit synthetic record view fixture.');
+      return structuredClone(match.result);
+    },
+    executeBody(request) {
+      bodyRequest(request);
+      const matched=bodies.find(entry=>isDeepStrictEqual(entry.request,request));
+      if(!matched) throw usageError('Add an explicit synthetic document body fixture.');
+      return structuredClone(matched.result);
+    },
+    executeShown(name,params) {
+      if(!Object.hasOwn(declaredLists,name)) throw usageError('This view does not declare that list.');
+      if(!object(params)) throw usageError('List params must be an object.');
+      const matched=shownCases[name]?.find(entry=>isDeepStrictEqual(entry.params,params));
+      if(!matched) throw usageError(`Add an explicit synthetic shown fixture for ${name} and these params.`);
+      return structuredClone(matched.result);
+    },
+    executeViewerRead(operation,input) {
+      if(!Object.hasOwn(VIEWER_READS,operation) || !declaredReads.includes(VIEWER_READS[operation])) throw usageError('This Space does not declare that viewer read.');
+      if(!object(input)) throw usageError('Viewer read inputs must be an object.');
+      const matched=readCases[operation]?.find(entry=>isDeepStrictEqual(entry.input,input));
+      if(!matched) throw usageError(`Add an explicit synthetic viewer read fixture for ${operation} and this input.`);
+      return structuredClone(matched.result);
+    },
+    execute(name,inputs) {
+      const validate=validators.get(name);
+      if(!validate || !object(inputs) || !validate(inputs)) throw usageError('The action inputs do not match this Space declaration.');
+      const matched=fixtures.actions[name]?.find(entry=>isDeepStrictEqual(entry.inputs,inputs));
+      if(!matched) throw usageError(`Add an explicit synthetic fixture for action ${name} and these inputs.`);
+      return structuredClone(matched.result);
+    } };
+}
+
+export function spaceHarnessSnapshot(release,capabilities,engine,{authorizationMode='authorize_missing',unavailableActions=[]}={}) {
+  if(release.manifest.kind!=='presentation') throw usageError('Containers do not have an executable preview.');
+  const manifest=release.manifest;
+  const names=Object.keys(manifest.actions || {}).sort();
+  if(!object(capabilities?.actions) || !object(capabilities?.bindings)
+    || !['authorize_missing','reuse_only'].includes(authorizationMode) || !Array.isArray(unavailableActions)
+    || unavailableActions.some(name=>typeof name!=='string') || new Set(unavailableActions).size!==unavailableActions.length) {
+    throw usageError('Verify current action authorizations before rendering this Space.');
+  }
+  const available=Object.keys(capabilities.actions).sort();
+  const missing=names.filter(name=>!Object.hasOwn(capabilities.actions,name));
+  if(available.some(name=>!names.includes(name))
+    || (authorizationMode==='authorize_missing' && (missing.length || unavailableActions.length))
+    || (authorizationMode==='reuse_only' && !isDeepStrictEqual([...unavailableActions].sort(),missing))) {
+    throw usageError(authorizationMode==='authorize_missing'
+      ? 'Verify current action authorizations before rendering this Space.'
+      : 'Verify the exact unavailable action declarations before rendering this Space.');
+  }
+  const actions=Object.fromEntries(available.map(name=>{
+    const descriptor=capabilities.actions[name];
+    if(typeof descriptor.readOnly!=='boolean' || !isDeepStrictEqual(descriptor.inputSchema,manifest.actions[name].inputs)) {
+      throw usageError('The verified action descriptor changed. Verify this build again.');
+    }
+    return [name,{id:name,inputSchema:descriptor.inputSchema,readOnly:descriptor.readOnly}];
+  }));
+  const bindings=Object.fromEntries(Object.entries(capabilities.bindings).map(([name,value])=>
+    [name,{kind:value.kind,...(value.operations?{operations:value.operations}:{})}]));
+  if(authorizationMode==='reuse_only' && Object.values(bindings).some(binding=>
+    Object.values(binding.operations || {}).some(name=>!Object.hasOwn(actions,name)))) {
+    throw usageError('An unavailable action cannot become a fixture binding operation.');
+  }
+  const navigation=Object.keys(manifest.navigation || {}).sort();
+  if(!isDeepStrictEqual([...(capabilities.navigation || [])].sort(),navigation)) throw usageError('The verified navigation declaration changed. Verify this build again.');
+  const viewerReads=[...(manifest.viewer_reads || [])];
+  if(!isDeepStrictEqual([...(capabilities.viewerReads || [])],viewerReads)) throw usageError('The verified viewer reads changed. Verify this build again.');
+  const identity=`verification:${manifest.local_key}`;
+  const artifact=appFilesDigest(release.files);
+  const js=manifest.bundle?.js,css=manifest.bundle?.css;
+  if(!js || !release.files[js] || (css && typeof release.files[css]!=='string')) throw usageError('The selected presentation bundle or stylesheet is missing.');
+  return { source:Buffer.from(release.files[js],'base64').toString('utf8'),
+    css:css?Buffer.from(release.files[css],'base64').toString('utf8'):'',
+    cacheKey:`${artifact}:${engine.digest}`,exportCandidates:['SpaceView'],
+    descriptor:{resource:{kind:'space',id:identity,revision:1},
+      space:{id:identity,revision:1,cacheScope:`stub:${artifact}:${engine.digest}`,actions,bindings,...(navigation.length?{navigation}:{}),
+        ...(viewerReads.length?{viewerReads}:{}),...viewDeclarations(manifest)},
+      app:{id:identity,name:manifest.name},route:{slug:'view',path:'/',name:manifest.name},context:engine.context} };
+}
+
+/** Existing CLI theme only; the legacy executable/JWT HTML is never served. */
+function themeCss() {
+  const template=readFileSync(join(ROOT,'template/.harness/index.html.tmpl'),'utf8');
+  const css=template.match(/<style>([\s\S]*?)<\/style>/)?.[1];
+  if(!css) throw usageError('The verification theme is missing. Rebuild the CLI package.');
+  return css;
+}
+
+export async function startSpaceTestServer({release,capabilities,port=0,authorizationMode='authorize_missing',unavailableActions=[]}) {
+  const engine=createSpaceFixtureEngine(release),snapshot=spaceHarnessSnapshot(release,capabilities,engine,{authorizationMode,unavailableActions});
+  const assets={host:readFileSync(join(ROOT,'dist/space-harness/host.js')),css:themeCss()};
+  const server=createServer(async(req,res)=>{
+    const response=(status,body,type='application/json')=>{
+      res.writeHead(status,{'Content-Type':type,'Cache-Control':'no-store','X-Content-Type-Options':'nosniff',
+        'Referrer-Policy':'no-referrer','Content-Security-Policy':HOST_POLICY,
+        'Cross-Origin-Resource-Policy':'same-origin'});
+      res.end(req.method==='HEAD'?undefined:body);
+    };
+    try {
+      const origin=`http://127.0.0.1:${server.address().port}`;
+      const target=new URL(req.url || '/',origin);
+      // Also serve as the verification browser's non-forwarding proxy. An
+      // executable cannot escape to another localhost port by navigating.
+      if(target.origin!==origin || req.headers.host!==new URL(origin).host) return response(403,'{}');
+      const path=target.pathname;
+      if(req.headers.origin && req.headers.origin!==origin) return response(403,'{}');
+      if(req.method==='GET' || req.method==='HEAD') {
+        if(path==='/') return response(200,'<!doctype html><meta charset="utf-8"><title>Space verification</title><link rel="stylesheet" href="/theme.css"><script defer src="/host.js"></script>','text/html; charset=utf-8');
+        if(path==='/host.js') return response(200,assets.host,'text/javascript');
+        if(path==='/theme.css') return response(200,assets.css,'text/css');
+        if(path==='/snapshot') return response(200,JSON.stringify(snapshot));
+      }
+      if(req.method==='POST' && path==='/fixture' && req.headers['content-type']?.split(';')[0]==='application/json') {
+        const chunks=[];let length=0;
+        for await(const chunk of req) {
+          length+=chunk.length;
+          if(length>1_000_000) {response(413,'{}');req.destroy();return;}
+          chunks.push(chunk);
+        }
+        const input=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if(object(input) && Object.keys(input).length===1 && Object.hasOwn(input,'shown')) {
+          const list=input.shown;
+          if(!object(list) || Object.keys(list).sort().join(',')!=='name,params') return response(400,'{}');
+          try {return response(200,JSON.stringify({result:engine.executeShown(list.name,list.params)}));}
+          catch(error) {return response(400,JSON.stringify({message:error.message}));}
+        }
+        if(object(input) && Object.keys(input).length===1 && Object.hasOwn(input,'viewer_read')) {
+          const read=input.viewer_read;
+          if(!object(read) || Object.keys(read).sort().join(',')!=='input,operation') return response(400,'{}');
+          try {return response(200,JSON.stringify({result:engine.executeViewerRead(read.operation,read.input)}));}
+          catch(error) {return response(400,JSON.stringify({message:error.message}));}
+        }
+        if(object(input) && Object.keys(input).length===1 && Object.hasOwn(input,'document_body')) {
+          if(snapshot.descriptor.space.actions[input.document_body?.readAction]?.readOnly!==true) return response(403,'{}');
+          try {return response(200,JSON.stringify({result:engine.executeBody(input.document_body)}));}
+          catch(error) {return response(400,JSON.stringify({message:error.message}));}
+        }
+        if(!object(input) || Object.keys(input).some(key=>!['action_id','inputs'].includes(key))) return response(400,'{}');
+        if(snapshot.descriptor.space.actions[input.action_id]?.readOnly!==true) return response(403,'{}');
+        try { return response(200,JSON.stringify({result:engine.execute(input.action_id,input.inputs)})); }
+        catch(error) {return response(400,JSON.stringify({message:error.message}));}
+      }
+      response(404,'{}');
+    } catch {response(400,JSON.stringify({message:'Invalid verification request.'}));}
+  });
+  // This is an asset/fixture server, never a CONNECT or WebSocket proxy.
+  // These events hand the raw socket to us, outside HTTP's usual lifecycle.
+  // A browser resetting a denied tunnel must close only that connection, not
+  // become an unhandled Socket error that kills every fixture presentation.
+  const deniedSockets=new Set();
+  const denyTunnel=(_req,socket)=>{
+    deniedSockets.add(socket);
+    socket.on('error',()=>socket.destroy());
+    socket.once('close',()=>deniedSockets.delete(socket));
+    socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n',()=>socket.destroy());
+  };
+  server.on('connect',denyTunnel);
+  server.on('upgrade',denyTunnel);
+  await new Promise((accept,reject)=>{server.once('error',reject);server.listen(port,'127.0.0.1',()=>{server.off('error',reject);accept();});});
+  let closing;
+  const rendererDigest=createHash('sha256').update(assets.host).update(assets.css).digest('hex');
+  return {url:`http://127.0.0.1:${server.address().port}`,fixtureDigest:engine.digest,rendererDigest,
+    close(){return closing ||= new Promise(accept=>{
+      server.close(accept);server.closeAllConnections?.();
+      for(const socket of deniedSockets) socket.destroy();
+    });}};
+}