@gregiteen/ssss-cli 0.8.0 → 0.9.0

package/skills/ssss/references/contract-reference.md

@@ -11,7 +11,7 @@ This is an operational map. The normative source is the current
 | `registry/extensions/*.json` | Host/application types that cannot redefine core primitives. |
 | `src/engine.mjs` | Operation Contract, validation, authorization, leases, idempotency, atomic commit, audit. |
 | `src/runtime.mjs` | Workflow trigger planning and deterministic event/task/run envelopes. |
-| `src/semantic.mjs` | Deterministic semantic records/edges, localized search, and safe materialization. |
+| `src/semantic.mjs` | Deterministic records/edges, multilingual embeddings, hybrid retrieval, and invariant rendering. |
 | `src/bundle.mjs` | Export, validate, provision, import, portability filtering, link/hash integrity. |
 | `src/registry.mjs` | Registry loading and type/portability resolution. |
 | `src/frontmatter.mjs` | Dependency-free parse/serialize with unknown-field preservation. |
@@ -35,8 +35,7 @@ document types.
 Current core document families include knowledge (`memory`), capability
 (`skill`, `page`), governance (`rule`, `security_role`), work (`task`,
 `workflow`), actors/catalog (`assistant`, `model`), transcripts (`conversation`,
-`run`), localization (`translation`), and lifecycle/meta (`conflict`, `migration`,
-`release`).
+`run`), and lifecycle/meta (`conflict`, `migration`, `release`, `primitive`).
 
 The contract primitives are `operation`, `patch`, `event`, `delete`, and
 `lease`.
@@ -77,15 +76,15 @@ For a bundle:
 7. Internal links resolve after remapping.
 8. Re-import replays without new commits.
 
-For a semantic/localization projection:
+For a multilingual semantic projection:
 
 1. Records and index hashes are deterministic for identical inputs.
 2. Stable identity, tokens, content hashes, portability, and graph edges are retained.
 3. Private and resource-bound documents are excluded unless explicitly authorized.
-4. A translation targets one structural, non-translation source by safe relative path.
-5. The source hash is exact and only natural-language surface fields change.
-6. Duplicate, stale, traversing, symlinked, or recursive overlays fail closed.
-7. Materialization occurs outside the source vault and remains rebuildable.
+4. Embedding records retain model identity and vector dimensions.
+5. Lexical and semantic evidence remain separately inspectable.
+6. Runtime rendering preserves all symbolic control fields.
+7. Language selection never widens authorization or portability scope.
 
 ## Drift checklist
 

package/skills/ssss/scripts/validate-schema.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const FALLBACK_UNIVERSAL = ['type', 'title', 'description', 'timestamp'];
@@ -20,7 +19,7 @@ const FALLBACK_REQUIRED = {
   page: ['slug', 'name', 'sandbox_entry'],
   migration: ['migration_id', 'from_version', 'to_version', 'status'],
   release: ['release_id', 'version', 'schema_version', 'summary', 'released_at'],
-  translation: ['translation_id', 'source_path', 'source_hash', 'locale', 'status', 'translated_fields'],
+  primitive: ['primitive_id', 'namespace', 'version', 'name', 'mutation', 'portability', 'scopes', 'fields'],
 };
 const CONTRACT_TYPES = new Set(['operation', 'patch', 'event', 'delete', 'lease']);
 const APPEND_TYPES = new Set(['conversation', 'run']);
@@ -120,46 +119,6 @@ function isSafeReferencePath(value) {
     value.split('/').every((segment) => segment && segment !== '.' && segment !== '..');
 }
 
-function inferVaultRoot(target) {
-  let cursor = path.dirname(target);
-  while (path.dirname(cursor) !== cursor) {
-    if (path.basename(cursor) === 'translations') return path.dirname(cursor);
-    cursor = path.dirname(cursor);
-  }
-  return null;
-}
-
-async function validateTranslationReference(target, data, registry, kernelRoot, errors, warnings) {
-  if (data.type !== 'translation' || isEmpty(data.source_path)) return;
-  if (!isSafeReferencePath(data.source_path)) {
-    errors.push(`Field 'source_path' must be a safe vault-relative Markdown path.`);
-    return;
-  }
-  const vaultRoot = inferVaultRoot(target);
-  if (!vaultRoot) {
-    warnings.push("Cannot resolve translation source outside the canonical translations/<locale>/ layout.");
-    return;
-  }
-  const source = path.resolve(vaultRoot, data.source_path);
-  const relative = path.relative(vaultRoot, source);
-  if (relative.startsWith('..') || path.isAbsolute(relative)) {
-    errors.push("Translation source_path escapes the vault.");
-    return;
-  }
-  if (!fs.existsSync(source) || !fs.statSync(source).isFile() || fs.lstatSync(source).isSymbolicLink()) {
-    errors.push(`Translation source does not exist as a regular non-symlinked file: ${data.source_path}.`);
-    return;
-  }
-  const raw = fs.readFileSync(source, 'utf8');
-  const parsed = await parseDocument(raw, kernelRoot);
-  if (parsed.data.type === 'translation') errors.push('Translations may not target another translation.');
-  const sourceDefinition = registry?.document_primitives?.[parsed.data.type];
-  const portability = parsed.data.x_portability || sourceDefinition?.portability;
-  if (portability !== 'structural') errors.push('Translations may target structural documents only.');
-  const hash = `sha256:${crypto.createHash('sha256').update(raw).digest('hex')}`;
-  if (data.source_hash !== hash) errors.push(`Translation source_hash is stale; expected '${hash}'.`);
-}
-
 export async function validateNode(filePath) {
   const target = path.resolve(filePath);
   const kernelRoot = findKernelRoot(path.dirname(target)) || findKernelRoot(process.cwd());
@@ -210,8 +169,6 @@ export async function validateNode(filePath) {
     }
   }
 
-  await validateTranslationReference(target, data, registry, kernelRoot, errors, warnings);
-
   if (APPEND_TYPES.has(data.type) && body.trim() === '') {
     warnings.push(`Append-only primitive '${data.type}' has an empty body.`);
   }

package/src/authorization.mjs

@@ -0,0 +1,61 @@
+/** Verified identity and fail-closed capability authorization contracts. */
+const PRINCIPAL_KINDS = new Set(['human', 'agent', 'service', 'system']);
+const ACTIONS = new Set(['create', 'replace', 'patch', 'append', 'event', 'delete', 'define', 'migrate']);
+const ASSURANCE = { unverified: 0, verified: 1, elevated: 2, hardware: 3 };
+
+export function validateVerifiedPrincipal(principal) {
+  const errors = [];
+  if (!principal || typeof principal !== 'object') errors.push('Verified principal is required.');
+  else {
+    if (typeof principal.id !== 'string' || !principal.id) errors.push('Principal id is required.');
+    if (!PRINCIPAL_KINDS.has(principal.kind)) errors.push(`Principal kind must be one of: ${[...PRINCIPAL_KINDS].join(', ')}.`);
+    if (!Array.isArray(principal.workspaceIds)) errors.push('Principal workspaceIds must be an array.');
+    if (!principal.authentication || typeof principal.authentication.provider !== 'string') {
+      errors.push('Authentication provenance is required.');
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function requiredCapabilities(definition, action) {
+  if (!ACTIONS.has(action)) throw new Error(`Unknown authorization action '${action}'.`);
+  const declared = definition?.capabilities?.[action];
+  if (Array.isArray(declared) && declared.length) return declared;
+  const primitive = definition?.qualified_type || definition?.type || 'unknown';
+  return [`${primitive}:${action}`];
+}
+
+export function createCapabilityAuthorizer(options = {}) {
+  const policyFloors = options.policyFloors || {};
+  return async function authorize({ principal, workspaceId, definition, action, context = {} }) {
+    const principalValidation = validateVerifiedPrincipal(principal);
+    if (!principalValidation.valid) return { allowed: false, reason: principalValidation.errors.join(' ') };
+    if (principal.kind !== 'system' && !principal.workspaceIds.includes(workspaceId)) {
+      return { allowed: false, reason: `Principal '${principal.id}' is not scoped to workspace '${workspaceId}'.` };
+    }
+    const required = new Set([
+      ...requiredCapabilities(definition, action),
+      ...(policyFloors[definition?.qualified_type || definition?.type]?.[action] || []),
+      ...(context.policyFloor || []),
+    ]);
+    const granted = new Set(principal.capabilities || []);
+    if (principal.kind === 'system' && options.systemBypass !== false) return { allowed: true, required: [...required] };
+    const missing = [...required].filter((capability) =>
+      !granted.has(capability) && !granted.has('*:*') && !granted.has(`${capability.split(':')[0]}:*`));
+    if (missing.length) return { allowed: false, required: [...required], missing, reason: `Missing capabilities: ${missing.join(', ')}.` };
+    if (context.requiresHumanConfirmation && principal.kind !== 'human') {
+      return { allowed: false, required: [...required], reason: 'A verified human confirmation is required.' };
+    }
+    if (context.requiresHumanConfirmation && context.humanConfirmation !== true) {
+      return { allowed: false, required: [...required], reason: 'Explicit human confirmation is required.' };
+    }
+    if (context.requiredAssurance) {
+      const actual = ASSURANCE[principal.authentication.assurance] ?? -1;
+      const requiredAssurance = ASSURANCE[context.requiredAssurance] ?? Number.POSITIVE_INFINITY;
+      if (actual < requiredAssurance) {
+        return { allowed: false, required: [...required], reason: `Authentication step-up to '${context.requiredAssurance}' is required.` };
+      }
+    }
+    return { allowed: true, required: [...required] };
+  };
+}

package/src/bundle.mjs

@@ -429,7 +429,7 @@ export function provisionBundle(bundle, opts = {}) {
  * import(plan, target) → replay (§17.1). Runs each envelope through the engine
  * (§6.3). Idempotent: each envelope's idempotency_key makes a re-run a no-op.
  */
-export function importBundle(plan, vaultRoot, engine) {
+export async function importBundle(plan, vaultRoot, engine) {
   const dryRunFlags = new Set(plan.map((envelope) => !!envelope.dry_run));
   if (dryRunFlags.size > 1) {
     return {
@@ -457,7 +457,7 @@ export function importBundle(plan, vaultRoot, engine) {
   // Two-phase import: validate the complete plan with in-plan references first.
   // A single invalid document prevents every commit, eliminating partial bundle
   // installation and allowing dry-run to validate cross-file constraints.
-  const preflight = plan.map((envelope) => {
+  const preflight = await Promise.all(plan.map((envelope) => {
     const preflightKey = 'preflight-' + crypto.createHash('sha256')
       .update(`${envelope.workspace_id}:${envelope.idempotency_key}:${envelope.path}`)
       .digest('hex')
@@ -467,7 +467,7 @@ export function importBundle(plan, vaultRoot, engine) {
       vaultRoot,
       operationOptions
     );
-  });
+  }));
   if (!preflight.every((result) => result.success)) {
     return { ok: false, committed: 0, wouldCommit: 0, results: preflight };
   }
@@ -480,7 +480,7 @@ export function importBundle(plan, vaultRoot, engine) {
     };
   }
   const results = [];
-  for (const env of plan) results.push(engine.processOperation(env, vaultRoot, operationOptions));
+  for (const env of plan) results.push(await engine.processOperation(env, vaultRoot, operationOptions));
   const committed = results.filter((r) => r.success && !r.replay && !r.dry_run).length;
   return { ok: results.every((r) => r.success), committed, wouldCommit: 0, results };
 }