@gregiteen/ssss-cli 0.8.0 → 0.9.0

package/src/semantic.mjs

@@ -1,33 +1,24 @@
 /**
- * Deterministic semantic projection and non-destructive localization helpers
- * (spec §11.9). No database, network, embedding provider, or YAML dependency.
+ * Semantic projection, multilingual embedding, retrieval, and runtime rendering.
+ * Canonical documents remain authored once; translations are never stored here.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { parseDocument, serializeDocument } from './frontmatter.mjs';
-import {
-  documentHash,
-  isSafeDocumentPath,
-  loadRegistries,
-  resolvePortability,
-  validateDataConstraints,
-  validateReferenceConstraints,
-} from './registry.mjs';
+import { parseDocument } from './frontmatter.mjs';
+import { createValidator } from './validator.mjs';
+import { isSafeDocumentPath, resolvePortability, resolvePrimitiveDefinition, documentHash } from './registry.mjs';
 
-const DEFAULT_LOCALE_PATTERN = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/u;
-const TRANSLATABLE_FIELDS = new Set(['title', 'description', 'body']);
-const APPROVED_STATUSES = new Set(['approved']);
+const LANGUAGE_RE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/u;
+const RENDER_FIELDS = new Set(['title', 'description', 'body']);
 
 function asStrings(value) {
   if (Array.isArray(value)) return value.filter((item) => typeof item === 'string' && item);
   return typeof value === 'string' && value ? [value] : [];
 }
 
-export function normalizeLocale(value, pattern = DEFAULT_LOCALE_PATTERN) {
-  if (typeof value !== 'string' || !pattern.test(value)) {
-    throw new Error(`Invalid locale '${value}'. Use a BCP47-style tag such as en, es-MX, or zh-Hant.`);
-  }
+export function normalizeLanguage(value) {
+  if (typeof value !== 'string' || !LANGUAGE_RE.test(value)) throw new Error(`Invalid language tag '${value}'.`);
   return value.split('-').map((part, index) => {
     if (index === 0) return part.toLowerCase();
     if (part.length === 2 || /^\d{3}$/.test(part)) return part.toUpperCase();
@@ -36,153 +27,40 @@ export function normalizeLocale(value, pattern = DEFAULT_LOCALE_PATTERN) {
   }).join('-');
 }
 
+function tokenize(value) {
+  return [...new Set(String(value || '').normalize('NFKC').toLocaleLowerCase().match(/[\p{L}\p{N}]+/gu) || [])].sort();
+}
+
 function walkDocuments(vaultRoot) {
-  const root = path.resolve(vaultRoot);
-  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
-    throw new Error(`Vault directory does not exist: ${root}`);
-  }
+  const root = fs.realpathSync(path.resolve(vaultRoot));
   const documents = [];
   const stack = [root];
   while (stack.length) {
     const dir = stack.pop();
-    const entries = fs.readdirSync(dir, { withFileTypes: true })
-      .sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
       if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
       const absolute = path.join(dir, entry.name);
       const relative = path.relative(root, absolute).split(path.sep).join('/');
-      if (entry.isSymbolicLink()) {
-        throw new Error(`Refusing symlinked vault entry: ${relative}`);
-      }
+      if (entry.isSymbolicLink()) throw new Error(`Refusing symlinked vault entry: ${relative}`);
       if (entry.isDirectory()) stack.push(absolute);
-      else if (entry.isFile() && entry.name.endsWith('.md') &&
-               entry.name !== 'index.md' && entry.name !== 'log.md') {
+      else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'index.md' && entry.name !== 'log.md') {
         if (!isSafeDocumentPath(relative)) throw new Error(`Unsafe vault path: ${relative}`);
         const content = fs.readFileSync(absolute, 'utf8');
         const parsed = parseDocument(content);
-        if (!parsed.data.type) continue;
-        documents.push({ path: relative, absolute, content, ...parsed });
+        if (parsed.data.type) documents.push({ path: relative, content, ...parsed });
       }
     }
   }
   return documents.sort((a, b) => a.path.localeCompare(b.path));
 }
 
-function documentMap(documents) {
-  return new Map(documents.map((document) => [document.path, document]));
-}
-
-function validateReferences(document, documents, types) {
-  const definition = types.get(document.data.type);
-  return validateReferenceConstraints(
-    definition,
-    document.data,
-    (referencePath) => documents.get(referencePath) || null,
-    types
-  );
-}
-
-function translationMap(documents, locale, types, { includeDrafts = false } = {}) {
-  const wanted = normalizeLocale(locale);
-  const bySource = new Map();
-  for (const document of documents.values()) {
-    if (document.data.type !== 'translation') continue;
-    const normalized = normalizeLocale(document.data.locale);
-    if (normalized !== wanted) continue;
-    if (!includeDrafts && !APPROVED_STATUSES.has(document.data.status)) continue;
-    const key = document.data.source_path;
-    if (bySource.has(key)) {
-      throw new Error(
-        `Duplicate translation overlays for '${key}' and locale '${wanted}': ` +
-        `${bySource.get(key).path}, ${document.path}`
-      );
-    }
-    const issues = validateReferences(document, documents, types);
-    if (issues.length) {
-      throw new Error(`${document.path}: ${issues.map((issue) => `${issue.field}: ${issue.issue}`).join('; ')}`);
-    }
-    bySource.set(key, document);
-  }
-  return bySource;
-}
-
-export function applyTranslationOverlay(sourceContent, translationContent, options = {}) {
-  const { types, core } = loadRegistries(options.registryDir);
-  const source = parseDocument(sourceContent);
-  const overlay = parseDocument(translationContent);
-  if (overlay.data.type !== 'translation') throw new Error('Overlay must declare type: translation.');
-  if (source.data.type === 'translation') throw new Error('Translations may not target another translation.');
-  const sourcePath = options.sourcePath || overlay.data.source_path;
-  if (!isSafeDocumentPath(sourcePath) || overlay.data.source_path !== sourcePath) {
-    throw new Error(`Translation source_path '${overlay.data.source_path}' does not match '${sourcePath}'.`);
-  }
-  if (resolvePortability(types.get(source.data.type), source.data) !== 'structural') {
-    throw new Error('Translation overlays may target structural documents only.');
-  }
-  const expectedHash = documentHash(sourceContent);
-  if (overlay.data.source_hash !== expectedHash) {
-    throw new Error(`Stale translation for '${sourcePath}'; expected source_hash '${expectedHash}'.`);
-  }
-  const localePattern = new RegExp(core.semantic?.locale_pattern || DEFAULT_LOCALE_PATTERN.source, 'u');
-  const locale = normalizeLocale(overlay.data.locale, localePattern);
-  const translatedFields = [...new Set(asStrings(overlay.data.translated_fields))];
-  if (!translatedFields.length) throw new Error('translated_fields must not be empty.');
-  for (const field of translatedFields) {
-    if (!TRANSLATABLE_FIELDS.has(field)) {
-      throw new Error(`Field '${field}' is a symbolic control field and may not be translated.`);
-    }
-  }
-
-  const data = { ...source.data };
-  let body = source.body;
-  if (translatedFields.includes('title')) {
-    if (!overlay.data.translated_title) throw new Error('translated_title is required when translating title.');
-    data.title = overlay.data.translated_title;
-  }
-  if (translatedFields.includes('description')) {
-    if (!overlay.data.translated_description) {
-      throw new Error('translated_description is required when translating description.');
-    }
-    data.description = overlay.data.translated_description;
-  }
-  if (translatedFields.includes('body')) {
-    if (!overlay.body.trim()) throw new Error('Translation body must not be empty when translating body.');
-    body = overlay.body;
-  }
-  data.locale = locale;
-  data.translation_of = sourcePath;
-  data.translation_source_hash = expectedHash;
-
-  return {
-    content: serializeDocument(data, body),
-    data,
-    body,
-    locale,
-    status: overlay.data.status,
-    translated_fields: translatedFields,
-  };
-}
-
-function tokenize(value) {
-  const normalized = String(value || '').normalize('NFKC').toLocaleLowerCase();
-  return [...new Set(normalized.match(/[\p{L}\p{N}]+/gu) || [])].sort();
-}
-
 function extractEdges(documentPath, data, body) {
   const edges = [];
-  for (const match of body.matchAll(/\[\[([^\]]+)\]\]/g)) {
-    edges.push({ source: documentPath, relation: 'mentions', target: match[1].trim() });
-  }
-  for (const match of body.matchAll(/\[[^\]]*\]\((\/[^)]+\.md)\)/g)) {
-    edges.push({ source: documentPath, relation: 'links_to', target: match[1].slice(1) });
-  }
+  for (const match of body.matchAll(/\[\[([^\]]+)\]\]/g)) edges.push({ source: documentPath, relation: 'mentions', target: match[1].trim() });
+  for (const match of body.matchAll(/\[[^\]]*\]\((\/[^)]+\.md)\)/g)) edges.push({ source: documentPath, relation: 'links_to', target: match[1].slice(1) });
   for (const relation of Array.isArray(data.relations) ? data.relations : []) {
     if (relation && typeof relation === 'object' && relation.target) {
-      edges.push({
-        source: documentPath,
-        relation: String(relation.relation || relation.type || 'related_to'),
-        target: String(relation.target),
-      });
+      edges.push({ source: documentPath, relation: String(relation.relation || relation.type || 'related_to'), target: String(relation.target) });
     }
   }
   return edges;
@@ -192,211 +70,141 @@ function canonicalHash(value) {
   return `sha256:${crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
 }
 
-function localizedDocuments(vaultRoot, options = {}) {
-  const { types, core } = loadRegistries(options.registryDir);
-  const all = walkDocuments(vaultRoot);
-  const documents = documentMap(all);
-  for (const document of all) {
-    const definition = types.get(document.data.type);
-    if (!definition) throw new Error(`${document.path}: unknown type '${document.data.type}'.`);
-    const issues = [
-      ...validateDataConstraints(
-        definition,
-        document.data,
-        core.universal_frontmatter?.required || ['type']
-      ),
-      ...(document.data.type === 'translation' ? [] : validateReferences(document, documents, types)),
-    ];
-    if (issues.length) {
-      throw new Error(`${document.path}: ${issues.map((issue) => `${issue.field}: ${issue.issue}`).join('; ')}`);
-    }
-  }
-  const overlays = options.locale
-    ? translationMap(documents, options.locale, types, options)
-    : new Map();
-  const output = [];
-  let excluded = 0;
-
-  for (const source of all) {
-    if (source.data.type === 'translation') continue;
-    const portability = resolvePortability(types.get(source.data.type), source.data);
-    if (!options.includePrivate && portability !== 'structural') {
-      excluded++;
-      continue;
-    }
-    const overlay = overlays.get(source.path);
-    const localized = overlay
-      ? applyTranslationOverlay(source.content, overlay.content, {
-          sourcePath: source.path,
-          registryDir: options.registryDir,
-        })
-      : { content: source.content, data: source.data, body: source.body, locale: source.data.locale || null };
-    output.push({
-      path: source.path,
-      source,
-      overlay: overlay || null,
-      portability,
-      ...localized,
-    });
-  }
-  return { documents: output, excluded };
+function semanticText(record) {
+  return [record.title, record.description, record.surface?.body, record.aliases?.join(' '), record.tags?.join(' ')].filter(Boolean).join('\n');
 }
 
 export function buildSemanticIndex(vaultRoot, options = {}) {
-  const locale = options.locale ? normalizeLocale(options.locale) : null;
-  const localized = localizedDocuments(vaultRoot, { ...options, locale });
+  const validator = options.validator || createValidator(options);
   const records = [];
   const edges = [];
-
-  for (const document of localized.documents) {
-    const data = document.data;
-    const identity = data.semantic_id || data.resource || `${data.type}:${document.path}`;
-    const labels = [data.title, data.description, data.name, data.slug, ...asStrings(data.aliases)];
-    const tags = asStrings(data.tags);
+  let excluded = 0;
+  for (const document of walkDocuments(vaultRoot)) {
+    const validation = validator.validateDocument(document.content);
+    if (!validation.valid) throw new Error(`${document.path}: ${validation.errors.join('; ')}`);
+    const definition = resolvePrimitiveDefinition(validator.registry, validation.declared_type);
+    const portability = resolvePortability(definition, document.data);
+    if (!options.includePrivate && portability !== 'structural') { excluded++; continue; }
+    const identity = document.data.semantic_id || document.data.resource || `${definition.qualified_type}:${document.path}`;
+    const labels = [document.data.title, document.data.description, document.data.name, document.data.slug, ...asStrings(document.data.aliases)];
+    const tags = asStrings(document.data.tags);
     const record = {
       semantic_id: identity,
       path: document.path,
-      type: data.type,
-      portability: document.portability,
-      locale: document.locale || null,
-      title: data.title || null,
-      description: data.description || null,
-      resource: data.resource || null,
-      aliases: asStrings(data.aliases),
+      type: definition.qualified_type,
+      primitive_version: definition.primitive_version || 1,
+      portability,
+      authored_language: document.data.language || document.data.locale || null,
+      title: document.data.title || null,
+      description: document.data.description || null,
+      resource: document.data.resource || null,
+      aliases: asStrings(document.data.aliases),
       tags,
+      relations: Array.isArray(document.data.relations) ? document.data.relations : [],
       content_hash: documentHash(document.content),
-      translation: document.overlay ? {
-        path: document.overlay.path,
-        status: document.overlay.data.status,
-        source_hash: document.overlay.data.source_hash,
-      } : null,
+      surface: { title: document.data.title || null, description: document.data.description || null, body: document.body || '' },
       search: {
-        identity: tokenize([identity, data.resource, data.type, document.path].filter(Boolean).join(' ')),
+        identity: tokenize([identity, document.data.resource, definition.qualified_type, document.path].filter(Boolean).join(' ')),
         labels: tokenize(labels.filter(Boolean).join(' ')),
         tags: tokenize(tags.join(' ')),
-        text: tokenize(`${data.description || ''}\n${document.body || ''}`),
+        text: tokenize(`${document.data.description || ''}\n${document.body || ''}`),
       },
     };
     records.push(record);
-    edges.push(...extractEdges(document.path, data, document.body));
+    edges.push(...extractEdges(document.path, document.data, document.body));
   }
-  records.sort((a, b) => a.path.localeCompare(b.path));
-  edges.sort((a, b) =>
-    a.source.localeCompare(b.source) || a.relation.localeCompare(b.relation) || a.target.localeCompare(b.target)
-  );
-  const payload = {
-    version: 1,
-    locale,
-    include_private: !!options.includePrivate,
-    excluded_documents: localized.excluded,
-    documents: records,
-    edges,
-  };
+  edges.sort((a, b) => a.source.localeCompare(b.source) || a.relation.localeCompare(b.relation) || a.target.localeCompare(b.target));
+  const payload = { version: 2, include_private: !!options.includePrivate, excluded_documents: excluded, embedding: null, documents: records, edges };
+  return { ...payload, index_hash: canonicalHash(payload) };
+}
+
+function validateVectors(vectors, expectedLength) {
+  if (!Array.isArray(vectors) || vectors.length !== expectedLength) throw new Error(`Embedding adapter returned ${vectors?.length || 0} vectors; expected ${expectedLength}.`);
+  const dimension = vectors[0]?.length;
+  if (!Number.isInteger(dimension) || dimension < 1) throw new Error('Embedding vectors must be non-empty arrays.');
+  for (const vector of vectors) {
+    if (!Array.isArray(vector) || vector.length !== dimension || vector.some((value) => typeof value !== 'number' || !Number.isFinite(value))) {
+      throw new Error('Embedding vectors must have one finite numeric dimension.');
+    }
+  }
+  return dimension;
+}
+
+export async function enrichSemanticIndex(index, { embed, model }) {
+  if (typeof embed !== 'function') throw new Error('A multilingual embed(texts, context) adapter is required.');
+  if (typeof model !== 'string' || !model) throw new Error('Embedding model identity is required.');
+  const vectors = await embed(index.documents.map(semanticText), { model, purpose: 'document' });
+  const dimension = validateVectors(vectors, index.documents.length);
+  const documents = index.documents.map((record, indexNumber) => ({ ...record, embedding: vectors[indexNumber] }));
+  const payload = { ...index, embedding: { model, dimension, multilingual: true }, documents };
+  delete payload.index_hash;
   return { ...payload, index_hash: canonicalHash(payload) };
 }
 
+function cosine(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return 0;
+  let dot = 0; let aa = 0; let bb = 0;
+  for (let index = 0; index < a.length; index++) { dot += a[index] * b[index]; aa += a[index] ** 2; bb += b[index] ** 2; }
+  return aa && bb ? dot / (Math.sqrt(aa) * Math.sqrt(bb)) : 0;
+}
+
 export function searchSemanticIndex(index, query, options = {}) {
-  const queryTokens = tokenize(query);
-  if (!queryTokens.length) return [];
-  const allowedTypes = options.types ? new Set(options.types) : null;
+  const tokens = tokenize(query);
+  if (!tokens.length) return [];
   const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 10;
+  const allowedTypes = options.types ? new Set(options.types) : null;
   const results = [];
   for (const document of index.documents || []) {
     if (allowedTypes && !allowedTypes.has(document.type)) continue;
-    const buckets = [
-      [document.search?.identity || [], 12],
-      [document.search?.labels || [], 7],
-      [document.search?.tags || [], 5],
-      [document.search?.text || [], 1],
-    ];
-    let score = 0;
+    const buckets = [[document.search?.identity || [], 12], [document.search?.labels || [], 7], [document.search?.tags || [], 5], [document.search?.text || [], 1]];
+    let lexical = 0;
     const matched = new Set();
-    for (const token of queryTokens) {
-      for (const [values, weight] of buckets) {
-        if (values.includes(token)) {
-          score += weight;
-          matched.add(token);
-          break;
-        }
-      }
+    for (const token of tokens) for (const [values, weight] of buckets) if (values.includes(token)) { lexical += weight; matched.add(token); break; }
+    const semantic = options.queryVector && document.embedding ? cosine(options.queryVector, document.embedding) : 0;
+    if (lexical > 0 || semantic > 0) {
+      results.push({ score: lexical + Math.max(0, semantic) * 20, evidence: { lexical, semantic, matched: [...matched].sort() }, document });
     }
-    if (score > 0) results.push({ score, matched: [...matched].sort(), document });
   }
-  return results
-    .sort((a, b) => b.score - a.score || a.document.path.localeCompare(b.document.path))
-    .slice(0, limit);
+  return results.sort((a, b) => b.score - a.score || a.document.path.localeCompare(b.document.path)).slice(0, limit);
 }
 
-function atomicWrite(target, content) {
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  const temp = path.join(path.dirname(target), `.${path.basename(target)}.${crypto.randomUUID()}.tmp`);
-  fs.writeFileSync(temp, content);
-  fs.renameSync(temp, target);
+export async function searchSemanticIndexWithAdapter(index, query, { embed, model = index.embedding?.model, ...options }) {
+  if (!index.embedding) throw new Error('Semantic index has no embeddings; enrich it first.');
+  if (model !== index.embedding.model) throw new Error(`Embedding model mismatch: index uses '${index.embedding.model}', query requested '${model}'.`);
+  const vectors = await embed([query], { model, purpose: 'query' });
+  validateVectors(vectors, 1);
+  if (vectors[0].length !== index.embedding.dimension) throw new Error('Query embedding dimension does not match the index.');
+  return searchSemanticIndex(index, query, { ...options, queryVector: vectors[0] });
 }
 
-function resolvePhysicalTarget(value) {
-  const requested = path.resolve(value);
-  let cursor = requested;
-  const suffix = [];
-  while (!fs.existsSync(cursor)) {
-    suffix.unshift(path.basename(cursor));
-    const parent = path.dirname(cursor);
-    if (parent === cursor) break;
-    cursor = parent;
-  }
-  const physical = fs.realpathSync(cursor);
-  return path.join(physical, ...suffix);
+export function prepareRenderRequest(record, options = {}) {
+  const language = normalizeLanguage(options.language);
+  return {
+    target_language: language,
+    instruction: 'Render only the natural-language presentation fields in target_language. Never alter invariant controls or invent authority.',
+    invariant: {
+      semantic_id: record.semantic_id,
+      path: record.path,
+      type: record.type,
+      primitive_version: record.primitive_version,
+      resource: record.resource,
+      portability: record.portability,
+      tags: record.tags,
+      relations: record.relations,
+      content_hash: record.content_hash,
+      available_actions: options.availableActions || [],
+    },
+    surface: { ...record.surface },
+    context: options.context || null,
+  };
 }
 
-export function materializeLocale(vaultRoot, locale, outputDir, options = {}) {
-  const sourceRoot = fs.realpathSync(path.resolve(vaultRoot));
-  const targetRoot = resolvePhysicalTarget(outputDir);
-  const normalizedLocale = normalizeLocale(locale);
-  if (targetRoot === sourceRoot || targetRoot.startsWith(sourceRoot + path.sep)) {
-    throw new Error('Localization output must be outside the source vault.');
-  }
-  if (fs.existsSync(targetRoot)) {
-    const targetStat = fs.lstatSync(targetRoot);
-    if (targetStat.isSymbolicLink() || !targetStat.isDirectory()) {
-      throw new Error(`Localization output must be a real directory: ${targetRoot}`);
-    }
-    if (fs.readdirSync(targetRoot).length > 0) {
-      throw new Error(`Localization output directory must be empty: ${targetRoot}`);
-    }
-  }
-  const localized = localizedDocuments(sourceRoot, { ...options, locale: normalizedLocale });
-  const parent = path.dirname(targetRoot);
-  fs.mkdirSync(parent, { recursive: true });
-  const stageRoot = path.join(parent, `.${path.basename(targetRoot)}.${crypto.randomUUID()}.stage`);
-  const inventory = [];
-  let targetWasEmpty = fs.existsSync(targetRoot);
-  try {
-    fs.mkdirSync(stageRoot);
-    for (const document of localized.documents) {
-      if (!isSafeDocumentPath(document.path)) throw new Error(`Unsafe projection path: ${document.path}`);
-      const target = path.resolve(stageRoot, document.path);
-      if (!target.startsWith(stageRoot + path.sep)) throw new Error(`Projection path escaped output: ${document.path}`);
-      atomicWrite(target, document.content);
-      inventory.push({ path: document.path, content_hash: documentHash(document.content) });
-    }
-    inventory.sort((a, b) => a.path.localeCompare(b.path));
-    const manifest = {
-      type: 'ssss_localization_projection',
-      version: 1,
-      locale: normalizedLocale,
-      include_private: !!options.includePrivate,
-      document_count: inventory.length,
-      excluded_documents: localized.excluded,
-      source_hash: canonicalHash(inventory),
-      documents: inventory,
-    };
-    atomicWrite(path.join(stageRoot, '.ssss-projection.json'), JSON.stringify(manifest, null, 2) + '\n');
-    if (targetWasEmpty) fs.rmdirSync(targetRoot);
-    fs.renameSync(stageRoot, targetRoot);
-    return manifest;
-  } catch (error) {
-    fs.rmSync(stageRoot, { recursive: true, force: true });
-    if (targetWasEmpty && !fs.existsSync(targetRoot)) fs.mkdirSync(targetRoot);
-    throw error;
-  }
+export async function renderSemanticRecord(record, { language, render, ...options }) {
+  if (typeof render !== 'function') throw new Error('An LLM render(request) adapter is required.');
+  const request = prepareRenderRequest(record, { ...options, language });
+  const rendered = await render(request);
+  if (!rendered || typeof rendered !== 'object' || Array.isArray(rendered)) throw new Error('Render adapter must return an object.');
+  for (const key of Object.keys(rendered)) if (!RENDER_FIELDS.has(key)) throw new Error(`Render adapter returned forbidden field '${key}'.`);
+  for (const [key, value] of Object.entries(rendered)) if (typeof value !== 'string') throw new Error(`Rendered field '${key}' must be a string.`);
+  return { record, presentation: { language: request.target_language, ...rendered }, invariant: request.invariant };
 }

package/src/ui.mjs

@@ -0,0 +1,100 @@
+/** Typed, capability-bound generative UI projection contract. */
+import crypto from 'node:crypto';
+
+const SAFE_ID = /^[a-z][a-z0-9_.-]{0,127}$/;
+const LAYOUTS = new Set(['form', 'table', 'detail', 'detail-with-actions', 'dashboard', 'wizard']);
+
+function isRecord(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
+
+export class UiRegistry {
+  constructor() { this.components = new Map(); this.actions = new Map(); }
+  registerComponent(definition) {
+    if (!SAFE_ID.test(definition?.id || '') || typeof definition.validateProps !== 'function') throw new Error('Component id and validateProps are required.');
+    if (this.components.has(definition.id)) throw new Error(`Duplicate UI component '${definition.id}'.`);
+    this.components.set(definition.id, { ...definition });
+  }
+  registerAction(definition) {
+    if (!SAFE_ID.test(definition?.id || '') || !definition.capability || !definition.command) throw new Error('Action id, capability, and command are required.');
+    if (this.actions.has(definition.id)) throw new Error(`Duplicate UI action '${definition.id}'.`);
+    this.actions.set(definition.id, { ...definition });
+  }
+}
+
+export function validateUiManifest(manifest, { registry, visibleFields = [], grantedCapabilities = [], maxComponents = 100 } = {}) {
+  const errors = [];
+  if (!isRecord(manifest)) return { valid: false, errors: [{ field: '(root)', issue: 'UI manifest must be an object.' }] };
+  if (manifest.type !== 'ssss:ui_projection') errors.push({ field: 'type', issue: 'Expected ssss:ui_projection.' });
+  if (!LAYOUTS.has(manifest.layout)) errors.push({ field: 'layout', issue: `Use one of: ${[...LAYOUTS].join(', ')}.` });
+  if (!Array.isArray(manifest.components)) errors.push({ field: 'components', issue: 'Components must be an array.' });
+  else if (manifest.components.length > maxComponents) errors.push({ field: 'components', issue: `At most ${maxComponents} components are allowed.` });
+  const allowedFields = new Set(visibleFields);
+  const capabilities = new Set(grantedCapabilities);
+  for (const [index, component] of (manifest.components || []).entries()) {
+    const prefix = `components[${index}]`;
+    if (!isRecord(component)) { errors.push({ field: prefix, issue: 'Component must be an object.' }); continue; }
+    const definition = registry?.components.get(component.component);
+    if (!definition) { errors.push({ field: `${prefix}.component`, issue: `Unregistered component '${component.component}'.` }); continue; }
+    if (component.bind && !allowedFields.has(component.bind)) errors.push({ field: `${prefix}.bind`, issue: `Field '${component.bind}' is hidden or unknown.` });
+    if (!isRecord(component.props) || typeof component.props.label !== 'string' || !component.props.label.trim()) {
+      errors.push({ field: `${prefix}.props.label`, issue: 'An accessible label is required.' });
+    }
+    if (component.action) {
+      const action = registry.actions.get(component.action);
+      if (!action) errors.push({ field: `${prefix}.action`, issue: `Unregistered action '${component.action}'.` });
+      else if (!capabilities.has(action.capability) && !capabilities.has('*:*')) errors.push({ field: `${prefix}.action`, issue: `Missing capability '${action.capability}'.` });
+    }
+    const propIssues = definition.validateProps(component.props || {});
+    for (const issue of propIssues || []) errors.push({ field: `${prefix}.props.${issue.field || '(root)'}`, issue: issue.issue || String(issue) });
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function createDeterministicUi(definition, options = {}) {
+  const fields = (options.visibleFields || definition.fields || []).map((field) => typeof field === 'string' ? { id: field, name: field, kind: 'string' } : field);
+  return {
+    type: 'ssss:ui_projection',
+    projection_id: `ui_${crypto.createHash('sha256').update(`${definition.primitive_id || definition.qualified_type}\0${options.mode || 'form'}`).digest('hex').slice(0, 16)}`,
+    primitive: definition.primitive_id || definition.qualified_type,
+    layout: options.mode || 'form',
+    title: definition.name || definition.qualified_type,
+    components: fields.map((field) => ({
+      component: field.kind === 'enum' ? 'select-field' : field.kind === 'boolean' ? 'boolean-field' : 'data-field',
+      bind: field.id,
+      props: { label: field.name || field.id, required: !!field.required, values: field.values || undefined },
+    })),
+  };
+}
+
+export async function planUi({ definition, data, principal, language, planner, registry, visibleFields, grantedCapabilities }) {
+  const fallback = createDeterministicUi(definition, { visibleFields });
+  if (typeof planner !== 'function') return { manifest: fallback, generated: false, fallback_reason: 'planner unavailable' };
+  const safeData = Object.fromEntries(Object.entries(data || {}).filter(([key]) => visibleFields.includes(key)));
+  let candidate;
+  try {
+    candidate = await planner({
+      instruction: 'Compose a UI manifest using only registered components, visible fields, and actions. Do not emit executable code.',
+      primitive: {
+        primitive_id: definition.primitive_id,
+        qualified_type: definition.qualified_type,
+        name: definition.name,
+        fields: (definition.fields || []).filter((field) => visibleFields.includes(field.id)),
+      },
+      data: safeData,
+      principal: { id: principal.id, kind: principal.kind },
+      language,
+      components: [...registry.components.keys()],
+      actions: [...registry.actions.values()].filter((action) => grantedCapabilities.includes(action.capability)).map((action) => action.id),
+    });
+  } catch (error) {
+    return { manifest: fallback, generated: false, fallback_reason: error.message };
+  }
+  const validation = validateUiManifest(candidate, { registry, visibleFields, grantedCapabilities });
+  if (!validation.valid) return { manifest: fallback, generated: false, fallback_reason: 'generated manifest rejected', errors: validation.errors };
+  return { manifest: candidate, generated: true };
+}
+
+export function actionToEnvelope(manifestComponent, registry, input = {}) {
+  const action = registry.actions.get(manifestComponent.action);
+  if (!action) throw new Error(`Unknown UI action '${manifestComponent.action}'.`);
+  return typeof action.command === 'function' ? action.command(input) : structuredClone(action.command);
+}