@gregiteen/ssss-cli 0.8.0 → 0.9.0

package/src/primitive.mjs

@@ -0,0 +1,227 @@
+/**
+ * SSSS primitive-definition API (spec 0.9).
+ *
+ * Human-facing names and descriptions may be authored in any language. Stable
+ * primitive/field/action/capability identifiers are symbolic controls and are
+ * generated or validated here rather than translated by presentation layers.
+ */
+import crypto from 'node:crypto';
+import { isPrimitiveTypeName } from './registry.mjs';
+
+export const PRIMITIVE_MUTATIONS = ['replace', 'append'];
+export const PRIMITIVE_PORTABILITY = ['structural', 'tenant_private', 'resource_bound'];
+export const PRIMITIVE_SCOPES = ['system', 'account', 'workspace', 'user'];
+export const FIELD_KINDS = [
+  'string', 'text', 'number', 'integer', 'boolean', 'datetime', 'date',
+  'enum', 'object', 'array', 'reference', 'secret_reference', 'resource_reference',
+];
+
+const NAMESPACE_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+const SYMBOL_RE = /^[a-z][a-z0-9_-]{0,127}$/;
+const LANGUAGE_RE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
+const CAPABILITY_RE = /^[a-z][a-z0-9_.-]{0,63}:[a-z][a-z0-9_.-]{0,127}$/;
+
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(field, message) {
+  return { field, issue: message };
+}
+
+function uniqueStrings(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string' && item) &&
+    new Set(value).size === value.length;
+}
+
+/** Generate a stable opaque local ID from an authored name in any language. */
+export function generatePrimitiveId({ namespace, name, salt = '' }) {
+  if (!NAMESPACE_RE.test(namespace || '')) throw new Error('namespace must be a safe lowercase identifier.');
+  if (typeof name !== 'string' || !name.trim()) throw new Error('name must be non-empty.');
+  const digest = crypto.createHash('sha256')
+    .update(`${namespace}\0${name.normalize('NFKC')}\0${salt}`)
+    .digest('hex')
+    .slice(0, 20);
+  return `${namespace}:p_${digest}`;
+}
+
+export function validatePrimitiveDefinition(definition) {
+  const errors = [];
+  if (!isRecord(definition)) return { valid: false, errors: [issue('(root)', 'Primitive definition must be an object.')] };
+  const required = ['primitive_id', 'namespace', 'version', 'name', 'mutation', 'portability', 'scopes', 'fields'];
+  for (const field of required) {
+    const value = definition[field];
+    if (value === undefined || value === null || value === '' || (Array.isArray(value) && !value.length)) {
+      errors.push(issue(field, `Missing required field '${field}'.`));
+    }
+  }
+  if (!NAMESPACE_RE.test(definition.namespace || '')) {
+    errors.push(issue('namespace', 'Use a lowercase namespace containing letters, numbers, underscore, or hyphen.'));
+  }
+  if (!isPrimitiveTypeName(definition.primitive_id) ||
+      !definition.primitive_id?.startsWith(`${definition.namespace}:`)) {
+    errors.push(issue('primitive_id', 'Use a qualified identifier whose prefix matches namespace.'));
+  }
+  if (!Number.isInteger(definition.version) || definition.version < 1) {
+    errors.push(issue('version', 'Version must be a positive integer.'));
+  }
+  if (definition.revision !== undefined && (!Number.isInteger(definition.revision) || definition.revision < 1)) {
+    errors.push(issue('revision', 'Revision must be a positive integer.'));
+  }
+  if (typeof definition.name !== 'string' || !definition.name.trim()) {
+    errors.push(issue('name', 'Name may use any language but must not be empty.'));
+  }
+  if (definition.language !== undefined && !LANGUAGE_RE.test(definition.language)) {
+    errors.push(issue('language', 'Use a BCP-47-style language tag.'));
+  }
+  if (!PRIMITIVE_MUTATIONS.includes(definition.mutation)) {
+    errors.push(issue('mutation', `Use one of: ${PRIMITIVE_MUTATIONS.join(', ')}.`));
+  }
+  if (!PRIMITIVE_PORTABILITY.includes(definition.portability)) {
+    errors.push(issue('portability', `Use one of: ${PRIMITIVE_PORTABILITY.join(', ')}.`));
+  }
+  if (!uniqueStrings(definition.scopes) ||
+      definition.scopes.some((scope) => !PRIMITIVE_SCOPES.includes(scope))) {
+    errors.push(issue('scopes', `Provide a unique non-empty subset of: ${PRIMITIVE_SCOPES.join(', ')}.`));
+  }
+  if (!Array.isArray(definition.fields)) {
+    errors.push(issue('fields', 'Fields must be an array.'));
+  } else {
+    const ids = new Set();
+    for (const [index, field] of definition.fields.entries()) {
+      const prefix = `fields[${index}]`;
+      if (!isRecord(field)) {
+        errors.push(issue(prefix, 'Field definition must be an object.'));
+        continue;
+      }
+      if (!SYMBOL_RE.test(field.id || '')) errors.push(issue(`${prefix}.id`, 'Use a stable lowercase symbolic field ID.'));
+      else if (ids.has(field.id)) errors.push(issue(`${prefix}.id`, `Duplicate field ID '${field.id}'.`));
+      else ids.add(field.id);
+      if (typeof field.name !== 'string' || !field.name.trim()) {
+        errors.push(issue(`${prefix}.name`, 'Field name may use any language but must not be empty.'));
+      }
+      if (!FIELD_KINDS.includes(field.kind)) {
+        errors.push(issue(`${prefix}.kind`, `Use one of: ${FIELD_KINDS.join(', ')}.`));
+      }
+      if (field.kind === 'enum' && !uniqueStrings(field.values)) {
+        errors.push(issue(`${prefix}.values`, 'Enum fields require unique non-empty symbolic values.'));
+      }
+      if (field.pattern !== undefined) {
+        try { new RegExp(field.pattern, 'u'); }
+        catch (error) { errors.push(issue(`${prefix}.pattern`, `Invalid regular expression: ${error.message}`)); }
+      }
+    }
+  }
+  if (definition.capabilities !== undefined) {
+    if (!isRecord(definition.capabilities)) errors.push(issue('capabilities', 'Capabilities must be an action-to-list object.'));
+    else for (const [action, values] of Object.entries(definition.capabilities)) {
+      if (!SYMBOL_RE.test(action) || !uniqueStrings(values) || values.some((value) => !CAPABILITY_RE.test(value))) {
+        errors.push(issue(`capabilities.${action}`, 'Use unique qualified capability IDs.'));
+      }
+    }
+  }
+  if (definition.projections !== undefined && !Array.isArray(definition.projections)) {
+    errors.push(issue('projections', 'Projections must be an array.'));
+  }
+  if (definition.aliases !== undefined && (!uniqueStrings(definition.aliases) ||
+      definition.aliases.some((alias) => !isPrimitiveTypeName(alias)))) {
+    errors.push(issue('aliases', 'Aliases must be unique safe primitive identifiers.'));
+  }
+  if (definition.migrations !== undefined && !Array.isArray(definition.migrations)) {
+    errors.push(issue('migrations', 'Migrations must be an array.'));
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Normalize a user/repo-authored definition and generate missing symbolic IDs.
+ */
+export function definePrimitive(input, options = {}) {
+  if (!isRecord(input)) throw new Error('Primitive input must be an object.');
+  const namespace = input.namespace || options.namespace;
+  const primitive_id = input.primitive_id || generatePrimitiveId({ namespace, name: input.name, salt: options.salt });
+  const fields = (input.fields || []).map((field, index) => ({
+    ...field,
+    id: field.id || `field_${crypto.createHash('sha256')
+      .update(`${primitive_id}\0${field.name || index}`)
+      .digest('hex').slice(0, 12)}`,
+  }));
+  const definition = {
+    type: 'ssss:primitive',
+    version: 1,
+    revision: 1,
+    mutation: 'replace',
+    portability: 'structural',
+    scopes: ['workspace'],
+    ...input,
+    namespace,
+    primitive_id,
+    fields,
+  };
+  const result = validatePrimitiveDefinition(definition);
+  if (!result.valid) {
+    const error = new Error(result.errors.map((entry) => `${entry.field}: ${entry.issue}`).join('; '));
+    error.field_errors = result.errors;
+    throw error;
+  }
+  return definition;
+}
+
+/** Convert a rich primitive definition into the executable registry schema. */
+export function primitiveDefinitionToRegistryEntry(definition) {
+  const result = validatePrimitiveDefinition(definition);
+  if (!result.valid) throw new Error(result.errors.map((entry) => `${entry.field}: ${entry.issue}`).join('; '));
+  const required_fields = ['type'];
+  const optional_fields = [];
+  const enums = {};
+  const patterns = {};
+  const references = {};
+  for (const field of definition.fields) {
+    (field.required ? required_fields : optional_fields).push(field.id);
+    if (field.kind === 'enum') enums[field.id] = field.values;
+    if (field.pattern) patterns[field.id] = field.pattern;
+    if (field.kind === 'reference') references[field.id] = {
+      must_exist: field.must_exist !== false,
+      ...(field.allowed_types ? { allowed_types: field.allowed_types } : {}),
+      ...(field.allowed_portability ? { allowed_portability: field.allowed_portability } : {}),
+    };
+  }
+  return {
+    family: definition.family || 'extension',
+    canonical_path: definition.path_template || null,
+    append_only: definition.mutation === 'append',
+    portability: definition.portability,
+    required_fields,
+    optional_fields,
+    ...(Object.keys(enums).length ? { enums } : {}),
+    ...(Object.keys(patterns).length ? { patterns } : {}),
+    ...(Object.keys(references).length ? { references } : {}),
+    scopes: definition.scopes,
+    capabilities: definition.capabilities || {},
+    events: definition.events || [],
+    projections: definition.projections || [],
+    ui: definition.ui || {},
+    aliases: definition.aliases || [],
+    migrations: definition.migrations || [],
+    primitive_version: definition.version,
+    primitive_revision: definition.revision || 1,
+    authored_language: definition.language || null,
+  };
+}
+
+/** Package one or more definitions as an extension registry object. */
+export function definitionsToExtensionRegistry(namespace, definitions, options = {}) {
+  if (!NAMESPACE_RE.test(namespace || '')) throw new Error('Invalid namespace.');
+  const document_primitives = {};
+  for (const definition of definitions) {
+    if (definition.namespace !== namespace) throw new Error(`Definition '${definition.primitive_id}' belongs to another namespace.`);
+    document_primitives[definition.primitive_id] = primitiveDefinitionToRegistryEntry(definition);
+  }
+  return {
+    registry: namespace,
+    extends: 'ssss',
+    version: options.version || '1.0.0',
+    requires: options.requires || {},
+    document_primitives,
+  };
+}

package/src/projections.mjs

@@ -0,0 +1,62 @@
+/** Replayable, cursor-aware SSSS projection coordinator. */
+import crypto from 'node:crypto';
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+  return value;
+}
+
+export function projectionHash(value) {
+  return `sha256:${crypto.createHash('sha256').update(JSON.stringify(stable(value))).digest('hex')}`;
+}
+
+export class ProjectionCoordinator {
+  constructor({ eventStore, cursorStore = new Map() } = {}) {
+    if (!eventStore) throw new Error('ProjectionCoordinator requires an eventStore.');
+    this.eventStore = eventStore;
+    this.cursorStore = cursorStore;
+    this.projections = new Map();
+  }
+  register(definition) {
+    if (!definition?.id || typeof definition.apply !== 'function') throw new Error('Projection id and apply(event, context) are required.');
+    if (this.projections.has(definition.id)) throw new Error(`Duplicate projection '${definition.id}'.`);
+    this.projections.set(definition.id, definition);
+  }
+  async replay(id, options = {}) {
+    const projection = this.projections.get(id);
+    if (!projection) throw new Error(`Unknown projection '${id}'.`);
+    let cursor = options.rebuild ? 0 : (this.cursorStore.get(id) || 0);
+    if (options.rebuild && projection.reset) await projection.reset();
+    let applied = 0;
+    for await (const item of this.eventStore.replay({ cursor, workspaceId: options.workspaceId })) {
+      if (!projection.filter || projection.filter(item.event)) {
+        await projection.apply(item.event, { replay: true, cursor: item.cursor });
+        applied++;
+      }
+      cursor = item.cursor;
+      this.cursorStore.set(id, cursor);
+    }
+    const state = projection.snapshot ? await projection.snapshot() : null;
+    return { id, cursor, applied, output_hash: state === null ? null : projectionHash(state) };
+  }
+  async dispatch(event) {
+    const results = [];
+    for (const projection of this.projections.values()) {
+      if (projection.filter && !projection.filter(event)) continue;
+      try {
+        await projection.apply(event, { replay: false });
+        results.push({ id: projection.id, success: true });
+      } catch (error) {
+        results.push({ id: projection.id, success: false, error: error.message });
+      }
+    }
+    return results;
+  }
+  async detectDrift(id, expectedHash) {
+    const projection = this.projections.get(id);
+    if (!projection?.snapshot) throw new Error(`Projection '${id}' does not expose snapshot().`);
+    const actualHash = projectionHash(await projection.snapshot());
+    return { drift: actualHash !== expectedHash, expected_hash: expectedHash, actual_hash: actualHash };
+  }
+}

package/src/registry.mjs

@@ -18,7 +18,7 @@ const DEFAULT_REGISTRY_DIR = path.resolve(__dirname, '..', 'registry');
 
 const APPEND_TYPES = new Set(['conversation', 'run']);
 const SAFE_REGISTRY_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
-const SAFE_TYPE_NAME = /^[a-z][a-z0-9_-]{0,127}$/;
+const SAFE_TYPE_NAME = /^(?:[a-z][a-z0-9_-]{0,63}:)?[a-z][a-z0-9_-]{0,127}$/;
 const SAFE_FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 
 function isRecord(value) {
@@ -109,58 +109,124 @@ function validatePrimitiveDefinition(name, def, source, portabilityClasses) {
   }
 }
 
+/** Return true when a primitive identifier is a safe local or qualified name. */
+export function isPrimitiveTypeName(value) {
+  return typeof value === 'string' && SAFE_TYPE_NAME.test(value);
+}
+
+function normalizeExtensionInput(item, index) {
+  if (item?.document_primitives) return { source: item.source || `extension[${index}]`, value: item };
+  if (item?.registry?.document_primitives) {
+    return { source: item.source || `extension[${index}]`, value: item.registry };
+  }
+  throw new Error(`extension[${index}] must be an extension registry object.`);
+}
+
+function semverSatisfies(version, range) {
+  if (range === '*' || range === undefined) return true;
+  if (version === range) return true;
+  const current = String(version || '').match(/^(\d+)\.(\d+)\.(\d+)/);
+  const wanted = String(range).match(/^([~^])(\d+)\.(\d+)\.(\d+)$/);
+  if (!current || !wanted) return false;
+  const [, operator, major, minor, patch] = wanted;
+  const [cm, cn, cp] = current.slice(1).map(Number);
+  const [wm, wn, wp] = [major, minor, patch].map(Number);
+  if (operator === '^') return cm === wm && (cn > wn || (cn === wn && cp >= wp));
+  return cm === wm && cn === wn && cp >= wp;
+}
+
 /**
- * Load the core registry and merge extension registries.
- * @param {string} [registryDir] - directory containing core.json + extensions/
- * @returns {{ types: Map<string, object>, contractTypes: Set<string>, portabilityClasses: string[], core: object, extensions: Set<string> }}
+ * Compose the package core with extension/repository/workspace registry objects.
+ * This is the runtime composition path; hosts do not copy core.json into their repos.
  */
-export function loadRegistries(registryDir = DEFAULT_REGISTRY_DIR) {
-  const corePath = path.join(registryDir, 'core.json');
-  const core = JSON.parse(fs.readFileSync(corePath, 'utf8'));
+export function composeRegistries({ core, extensions: extensionInputs = [] } = {}) {
+  if (!isRecord(core)) throw new Error('core registry must be an object.');
   const portabilityClasses = Object.keys(core.portability?.classes || {});
-  if (!portabilityClasses.length) throw new Error('core.json: portability.classes must not be empty.');
-  const extensions = new Set();
+  if (!portabilityClasses.length) throw new Error('core registry: portability.classes must not be empty.');
 
+  const extensions = new Set();
+  const extensionVersions = new Map();
+  const extensionRequirements = [];
   const types = new Map();
+  const aliases = new Map();
+
   for (const [name, def] of Object.entries(core.document_primitives || {})) {
-    validatePrimitiveDefinition(name, def, 'core.json', portabilityClasses);
-    types.set(name, { ...def, type: name, registry: 'core' });
+    validatePrimitiveDefinition(name, def, 'core registry', portabilityClasses);
+    const value = { ...def, type: name, qualified_type: `ssss:${name}`, registry: 'core' };
+    types.set(name, value);
+    aliases.set(`ssss:${name}`, name);
   }
 
-  const extDir = path.join(registryDir, 'extensions');
-  if (fs.existsSync(extDir)) {
-    for (const file of fs.readdirSync(extDir).filter((f) => f.endsWith('.json')).sort()) {
-      const extPath = path.join(extDir, file);
-      if (fs.lstatSync(extPath).isSymbolicLink()) {
-        throw new Error(`extensions/${file}: symlinked registries are not allowed.`);
-      }
-      const ext = JSON.parse(fs.readFileSync(extPath, 'utf8'));
-      if (!SAFE_REGISTRY_NAME.test(ext.registry || '')) {
-        throw new Error(`extensions/${file}: registry must be a safe identifier.`);
+  for (const [index, item] of extensionInputs.entries()) {
+    const { source, value: ext } = normalizeExtensionInput(item, index);
+    if (!SAFE_REGISTRY_NAME.test(ext.registry || '')) {
+      throw new Error(`${source}: registry must be a safe identifier.`);
+    }
+    if (ext.registry === 'core' || ext.registry === 'ssss' || extensions.has(ext.registry)) {
+      throw new Error(`${source}: duplicate or reserved registry name '${ext.registry}'.`);
+    }
+    if (ext.extends !== undefined && ext.extends !== 'core' && ext.extends !== 'ssss') {
+      throw new Error(`${source}: extends must be 'core' or 'ssss'.`);
+    }
+    if (ext.version !== undefined &&
+        (typeof ext.version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(ext.version))) {
+      throw new Error(`${source}: version must be a semantic version string.`);
+    }
+    assertRecord(ext.requires, `${source}: requires`);
+    extensions.add(ext.registry);
+    extensionVersions.set(ext.registry, ext.version || '0.0.0');
+    extensionRequirements.push({ source, registry: ext.registry, requires: ext.requires || {} });
+
+    for (const [name, def] of Object.entries(ext.document_primitives || {})) {
+      validatePrimitiveDefinition(name, def, source, portabilityClasses);
+      const qualified = name.includes(':') ? name : `${ext.registry}:${name}`;
+      if (name.includes(':') && !name.startsWith(`${ext.registry}:`)) {
+        throw new Error(`${source}: primitive '${name}' must use registry namespace '${ext.registry}'.`);
       }
-      if (ext.registry === 'core' || extensions.has(ext.registry)) {
-        throw new Error(`extensions/${file}: duplicate or reserved registry name '${ext.registry}'.`);
+      if (types.has(name) || aliases.has(name) || types.has(qualified) || aliases.has(qualified)) {
+        const existing = types.get(name) || types.get(aliases.get(name)) ||
+          types.get(qualified) || types.get(aliases.get(qualified));
+        throw new Error(
+          `${source}: primitive '${name}' collides with registry '${existing?.registry || 'unknown'}'.`
+        );
       }
-      if (ext.extends !== undefined && ext.extends !== 'core') {
-        throw new Error(`extensions/${file}: extends must be 'core'.`);
+      const value = { ...def, type: name, qualified_type: qualified, registry: ext.registry };
+      types.set(name, value);
+      if (qualified !== name) aliases.set(qualified, name);
+      for (const alias of def.aliases || []) {
+        if (!isPrimitiveTypeName(alias)) throw new Error(`${source}: primitive '${name}' has unsafe alias '${alias}'.`);
+        if (types.has(alias) || aliases.has(alias)) throw new Error(`${source}: primitive alias '${alias}' collides with an existing primitive.`);
+        aliases.set(alias, name);
       }
-      extensions.add(ext.registry);
-      for (const [name, def] of Object.entries(ext.document_primitives || {})) {
-        validatePrimitiveDefinition(name, def, `extensions/${file}`, portabilityClasses);
-        if (types.has(name)) {
-          throw new Error(
-            `extensions/${file}: primitive '${name}' collides with registry '${types.get(name).registry}'.`
-          );
-        }
-        types.set(name, { ...def, type: name, registry: ext.registry });
+    }
+  }
+
+  for (const requirement of extensionRequirements) {
+    for (const [dependency, range] of Object.entries(requirement.requires)) {
+      if (!extensionVersions.has(dependency)) throw new Error(`${requirement.source}: missing required extension '${dependency}'.`);
+      if (typeof range !== 'string' || !semverSatisfies(extensionVersions.get(dependency), range)) {
+        throw new Error(`${requirement.source}: extension '${dependency}' version '${extensionVersions.get(dependency)}' does not satisfy '${range}'.`);
       }
     }
   }
 
+  const registrySet = {
+    types,
+    aliases,
+    contractTypes: new Set(Object.keys(core.contract_primitives || {})),
+    portabilityClasses,
+    core,
+    extensions,
+    extensionVersions,
+  };
+  // Backward-compatible Map surface used by the existing engine/bundle APIs.
+  // The alias table lets shared validators resolve qualified 0.9 identifiers.
+  types.aliases = aliases;
+
   for (const def of types.values()) {
     for (const [field, constraint] of Object.entries(def.references || {})) {
       for (const target of [...(constraint.allowed_types || []), ...(constraint.disallowed_types || [])]) {
-        if (!SAFE_TYPE_NAME.test(target) || !types.has(target)) {
+        if (!isPrimitiveTypeName(target) || !resolvePrimitiveDefinition(registrySet, target)) {
           throw new Error(
             `registry '${def.registry}' primitive '${def.type}' reference '${field}' names unknown type '${target}'.`
           );
@@ -169,8 +235,91 @@ export function loadRegistries(registryDir = DEFAULT_REGISTRY_DIR) {
     }
   }
 
-  const contractTypes = new Set(Object.keys(core.contract_primitives || {}));
-  return { types, contractTypes, portabilityClasses, core, extensions };
+  return registrySet;
+}
+
+/** Compose named ownership layers without giving lower scopes override semantics. */
+export function composeRegistryLayers({ core, installed = [], repository = [], workspace = [], user = [], policyFloors = {} } = {}) {
+  const extensions = [
+    ...installed.map((registry) => ({ source: 'installed', registry })),
+    ...repository.map((registry) => ({ source: 'repository', registry })),
+    ...workspace.map((registry) => ({ source: 'workspace', registry })),
+    ...user.map((registry) => ({ source: 'user', registry })),
+  ];
+  const registrySet = composeRegistries({ core, extensions });
+  for (const [type, actions] of Object.entries(policyFloors)) {
+    const definition = resolvePrimitiveDefinition(registrySet, type);
+    if (!definition) throw new Error(`Policy floor names unknown primitive '${type}'.`);
+    for (const [action, required] of Object.entries(actions || {})) {
+      assertStringArray(required, `policy floor '${type}.${action}'`);
+      const declared = new Set(definition.capabilities?.[action] || []);
+      const missing = required.filter((capability) => !declared.has(capability));
+      if (missing.length) throw new Error(`Primitive '${type}' weakens policy floor for '${action}': ${missing.join(', ')}.`);
+    }
+  }
+  return registrySet;
+}
+
+function stableObject(value) {
+  if (Array.isArray(value)) return value.map(stableObject);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableObject(value[key])]));
+  return value;
+}
+
+export function createRegistryLock(registrySet) {
+  const primitives = [...registrySet.types.values()]
+    .map((definition) => ({ ...definition }))
+    .sort((a, b) => a.qualified_type.localeCompare(b.qualified_type));
+  const payload = {
+    version: 1,
+    core_spec_version: registrySet.core.spec_version,
+    extensions: Object.fromEntries([...registrySet.extensionVersions.entries()].sort()),
+    primitives,
+  };
+  return { ...payload, integrity: `sha256:${crypto.createHash('sha256').update(JSON.stringify(stableObject(payload))).digest('hex')}` };
+}
+
+export function verifyRegistryLock(registrySet, lock) {
+  const expected = createRegistryLock(registrySet);
+  return {
+    valid: !!lock && lock.integrity === expected.integrity,
+    expected_integrity: expected.integrity,
+    actual_integrity: lock?.integrity || null,
+  };
+}
+
+/** Resolve local, qualified, or explicit migration-alias primitive identifiers. */
+export function resolvePrimitiveDefinition(registrySet, type) {
+  if (!registrySet || typeof type !== 'string') return null;
+  const direct = registrySet.types?.get(type);
+  if (direct) return direct;
+  const local = registrySet.aliases?.get(type);
+  return local ? registrySet.types.get(local) || null : null;
+}
+
+/**
+ * Load the core registry and merge extension registries.
+ * @param {string} [registryDir] - directory containing core.json + extensions/
+ * @returns {{ types: Map<string, object>, contractTypes: Set<string>, portabilityClasses: string[], core: object, extensions: Set<string> }}
+ */
+export function loadRegistries(registryDir = DEFAULT_REGISTRY_DIR) {
+  const corePath = path.join(registryDir, 'core.json');
+  const core = JSON.parse(fs.readFileSync(corePath, 'utf8'));
+  const extensionInputs = [];
+  const extDir = path.join(registryDir, 'extensions');
+  if (fs.existsSync(extDir)) {
+    for (const file of fs.readdirSync(extDir).filter((f) => f.endsWith('.json')).sort()) {
+      const extPath = path.join(extDir, file);
+      if (fs.lstatSync(extPath).isSymbolicLink()) {
+        throw new Error(`extensions/${file}: symlinked registries are not allowed.`);
+      }
+      extensionInputs.push({
+        source: `extensions/${file}`,
+        registry: JSON.parse(fs.readFileSync(extPath, 'utf8')),
+      });
+    }
+  }
+  return composeRegistries({ core, extensions: extensionInputs });
 }
 
 /** Is this document type append-only (events appended, never rewritten)? */
@@ -258,6 +407,8 @@ export function validateDataConstraints(typeDef, data, universalRequired = []) {
  */
 export function validateReferenceConstraints(typeDef, data, resolveReference, types) {
   const issues = [];
+  const lookupType = (name) => types.get(name) ||
+    (types.aliases?.get(name) ? types.get(types.aliases.get(name)) : null);
   for (const [field, constraint] of Object.entries(typeDef?.references || {})) {
     const referencePath = data[field];
     if (referencePath === undefined || referencePath === null || referencePath === '') continue;
@@ -278,7 +429,7 @@ export function validateReferenceConstraints(typeDef, data, resolveReference, ty
       continue;
     }
     const referencedType = referenced.data?.type;
-    if (!types.has(referencedType)) {
+    if (!lookupType(referencedType)) {
       issues.push({ field, issue: `Referenced document declares unknown type '${referencedType || '(missing)'}'.` });
       continue;
     }
@@ -288,7 +439,7 @@ export function validateReferenceConstraints(typeDef, data, resolveReference, ty
     if (constraint.disallowed_types?.includes(referencedType)) {
       issues.push({ field, issue: `Referenced type '${referencedType}' is forbidden.` });
     }
-    const referencedPortability = resolvePortability(types.get(referencedType), referenced.data);
+    const referencedPortability = resolvePortability(lookupType(referencedType), referenced.data);
     if (constraint.allowed_portability && !constraint.allowed_portability.includes(referencedPortability)) {
       issues.push({
         field,