enigma-memory 0.1.0

package/scripts/validate-tenant-policy-approval.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const TENANT_POLICY_APPROVAL_SCHEMA = 'enigma.tenant_policy_approval.v1';
+export const TENANT_POLICY_APPROVAL_RESULT_SCHEMA = 'enigma.tenant_policy_approval_result.v1';
+
+const ENTERPRISE_POLICY_SCHEMA = 'enigma.enterprise_policy.v1';
+const ACCEPTED_STATUSES = new Set(['approved', 'accepted', 'go', 'verified']);
+const SHA256_PREFIXED_DIGEST = /^sha256:[0-9a-f]{64}$/;
+const SECRET_VALUE_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|https?:\/\/[^\s/@]+:[^\s/@]+@|raw memory|private prompt|full transcript|decrypted capsule|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16})/iu;
+const SECRET_KEY_RE = /(?:password|passwd|pwd|token|api[_-]?key|private[_-]?key|secret|raw[_-]?memory|plaintext|plain[_-]?text|prompt|completion|transcript|embedding|provider[_-]?response)/iu;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function positiveInteger(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
+function isoLike(value) {
+  return nonEmptyString(value) && !Number.isNaN(Date.parse(value));
+}
+
+function blocker(message, path) {
+  return { message, path };
+}
+
+function assertNoSecrets(value, path = 'tenant_policy') {
+  if (typeof value === 'string') {
+    if (!/\.claim_boundary\[\d+\]$/.test(path) && SECRET_VALUE_RE.test(value)) throw new Error(`${path} contains secret or raw-memory-looking data`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoSecrets(item, `${path}[${index}]`));
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (SECRET_KEY_RE.test(key)) throw new Error(`${path}.${key} uses a forbidden field name`);
+    assertNoSecrets(child, `${path}.${key}`);
+  }
+}
+
+function statusAccepted(value) {
+  return typeof value === 'string' && ACCEPTED_STATUSES.has(value.trim().toLowerCase());
+}
+
+function nonEmptyStringArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(nonEmptyString);
+}
+
+function validateMetadata(metadata, blockers) {
+  if (!isPlainObject(metadata)) {
+    blockers.push(blocker('metadata is required', 'metadata'));
+    return;
+  }
+  for (const field of ['approval_id', 'environment', 'tenant', 'owner', 'approved_at', 'approval_ref', 'status']) {
+    if (!nonEmptyString(metadata[field])) blockers.push(blocker(`metadata.${field} is required`, `metadata.${field}`));
+  }
+  if (!statusAccepted(metadata.status)) blockers.push(blocker('metadata.status must be approved/accepted/go/verified', 'metadata.status'));
+  if (!isoLike(metadata.approved_at)) blockers.push(blocker('metadata.approved_at must be ISO time', 'metadata.approved_at'));
+}
+
+function validateEnterprisePolicy(policy, blockers) {
+  if (!isPlainObject(policy)) {
+    blockers.push(blocker('enterprise_policy object is required', 'enterprise_policy'));
+    return false;
+  }
+  if (policy.schema !== ENTERPRISE_POLICY_SCHEMA) blockers.push(blocker('enterprise_policy.schema must be enigma.enterprise_policy.v1', 'enterprise_policy.schema'));
+  for (const field of ['policy_id', 'tenant_id', 'mode', 'created_at', 'updated_at', 'policy_hash']) {
+    if (!nonEmptyString(policy[field])) blockers.push(blocker(`enterprise_policy.${field} is required`, `enterprise_policy.${field}`));
+  }
+  if (!SHA256_PREFIXED_DIGEST.test(String(policy.policy_hash ?? ''))) blockers.push(blocker('enterprise_policy.policy_hash must be sha256-prefixed digest', 'enterprise_policy.policy_hash'));
+  if (policy.default_action !== 'deny_unknown') blockers.push(blocker('enterprise_policy.default_action must be deny_unknown', 'enterprise_policy.default_action'));
+  if (policy.provider_native_memory !== 'cache_only') blockers.push(blocker('enterprise_policy.provider_native_memory must be cache_only', 'enterprise_policy.provider_native_memory'));
+  if (policy.public_proof !== 'hash_only') blockers.push(blocker('enterprise_policy.public_proof must be hash_only', 'enterprise_policy.public_proof'));
+  if (!positiveInteger(policy.retention_days)) blockers.push(blocker('enterprise_policy.retention_days must be positive integer', 'enterprise_policy.retention_days'));
+  for (const field of ['allowed_operations', 'allowed_providers', 'allowed_models', 'allowed_regions', 'allowed_purposes', 'denied_sensitivities']) {
+    if (!nonEmptyStringArray(policy[field])) blockers.push(blocker(`enterprise_policy.${field} must be non-empty string array`, `enterprise_policy.${field}`));
+  }
+  if (!Array.isArray(policy.legal_holds)) blockers.push(blocker('enterprise_policy.legal_holds must be an array', 'enterprise_policy.legal_holds'));
+  return true;
+}
+
+function validateApproval(approval, blockers) {
+  if (!isPlainObject(approval)) {
+    blockers.push(blocker('approval object is required', 'approval'));
+    return false;
+  }
+  for (const field of ['policy_owner', 'approver', 'approval_ref', 'approved_at', 'rollback_policy_hash', 'rollback_ref', 'status']) {
+    if (!nonEmptyString(approval[field])) blockers.push(blocker(`approval.${field} is required`, `approval.${field}`));
+  }
+  if (!statusAccepted(approval.status)) blockers.push(blocker('approval.status must be approved/accepted/go/verified', 'approval.status'));
+  if (!isoLike(approval.approved_at)) blockers.push(blocker('approval.approved_at must be ISO time', 'approval.approved_at'));
+  if (!SHA256_PREFIXED_DIGEST.test(String(approval.rollback_policy_hash ?? ''))) blockers.push(blocker('approval.rollback_policy_hash must be sha256-prefixed digest', 'approval.rollback_policy_hash'));
+  return true;
+}
+
+function validateRetentionDeletion(retention, policy, blockers) {
+  if (!isPlainObject(retention)) {
+    blockers.push(blocker('retention_deletion object is required', 'retention_deletion'));
+    return false;
+  }
+  for (const field of ['tombstone_receipt_ref', 'legal_hold_policy_ref', 'audit_route_ref', 'retention_policy_ref']) {
+    if (!nonEmptyString(retention[field])) blockers.push(blocker(`retention_deletion.${field} is required`, `retention_deletion.${field}`));
+  }
+  if (!positiveInteger(retention.retention_days)) blockers.push(blocker('retention_deletion.retention_days must be positive integer', 'retention_deletion.retention_days'));
+  if (isPlainObject(policy) && positiveInteger(policy.retention_days) && retention.retention_days !== policy.retention_days) blockers.push(blocker('retention_deletion.retention_days must match enterprise_policy.retention_days', 'retention_deletion.retention_days'));
+  if (retention.tombstone_receipt_required !== true) blockers.push(blocker('retention_deletion.tombstone_receipt_required must be true', 'retention_deletion.tombstone_receipt_required'));
+  if (retention.legal_hold_delete_blocks !== true) blockers.push(blocker('retention_deletion.legal_hold_delete_blocks must be true', 'retention_deletion.legal_hold_delete_blocks'));
+  if (retention.provider_deletion_claimed !== false) blockers.push(blocker('retention_deletion.provider_deletion_claimed must be false', 'retention_deletion.provider_deletion_claimed'));
+  return true;
+}
+
+function validateAuditControls(audit, blockers) {
+  if (!isPlainObject(audit)) {
+    blockers.push(blocker('audit_controls object is required', 'audit_controls'));
+    return false;
+  }
+  for (const field of ['gateway_decision_ref', 'siem_event_ref', 'evidence_retention_ref', 'review_ref']) {
+    if (!nonEmptyString(audit[field])) blockers.push(blocker(`audit_controls.${field} is required`, `audit_controls.${field}`));
+  }
+  if (audit.gateway_decision_required !== true) blockers.push(blocker('audit_controls.gateway_decision_required must be true', 'audit_controls.gateway_decision_required'));
+  if (audit.siem_event_required !== true) blockers.push(blocker('audit_controls.siem_event_required must be true', 'audit_controls.siem_event_required'));
+  if (audit.minimized_events_only !== true) blockers.push(blocker('audit_controls.minimized_events_only must be true', 'audit_controls.minimized_events_only'));
+  return true;
+}
+
+function validateChangeControl(change, blockers) {
+  if (!isPlainObject(change)) {
+    blockers.push(blocker('change_control object is required', 'change_control'));
+    return false;
+  }
+  for (const field of ['change_ticket_ref', 'canary_ref', 'rollback_ref', 'emergency_freeze_ref', 'owner']) {
+    if (!nonEmptyString(change[field])) blockers.push(blocker(`change_control.${field} is required`, `change_control.${field}`));
+  }
+  if (change.force_push_allowed !== false) blockers.push(blocker('change_control.force_push_allowed must be false', 'change_control.force_push_allowed'));
+  return true;
+}
+
+export function validateTenantPolicyApproval(packet, options = {}) {
+  if (!isPlainObject(packet)) throw new Error('tenant policy approval must be an object');
+  assertNoSecrets(packet);
+  const blockers = [];
+  if (packet.schema !== TENANT_POLICY_APPROVAL_SCHEMA) blockers.push(blocker('schema mismatch', 'schema'));
+  validateMetadata(packet.metadata, blockers);
+  const policyOk = validateEnterprisePolicy(packet.enterprise_policy, blockers);
+  const approvalOk = validateApproval(packet.approval, blockers);
+  const retentionOk = validateRetentionDeletion(packet.retention_deletion, packet.enterprise_policy, blockers);
+  const auditOk = validateAuditControls(packet.audit_controls, blockers);
+  const changeOk = validateChangeControl(packet.change_control, blockers);
+
+  const result = {
+    schema: TENANT_POLICY_APPROVAL_RESULT_SCHEMA,
+    generated_at: options.generated_at ?? options.generatedAt ?? new Date(0).toISOString(),
+    ok: blockers.length === 0,
+    status: blockers.length === 0 ? 'accepted' : 'blocked',
+    blockers,
+    checked: {
+      enterprise_policy: policyOk,
+      approval: approvalOk,
+      retention_deletion: retentionOk,
+      audit_controls: auditOk,
+      change_control: changeOk,
+      policy_hash: isPlainObject(packet.enterprise_policy) ? packet.enterprise_policy.policy_hash ?? null : null,
+    },
+    claim_boundary: [
+      'Tenant policy approval validation checks declared policy approval shape only; it does not deploy policy, mutate tenant state, or prove hosted readiness.',
+      'Provider-native memory must remain cache_only and provider deletion must not be claimed by tenant policy evidence.',
+      'Secrets, raw memory, prompts, transcripts, provider responses, decrypted content, credentials, and private key material must remain outside tenant policy artifacts.',
+    ],
+  };
+  assertNoSecrets(result, 'result');
+  return result;
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const flags = new Map();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) continue;
+    const eq = arg.indexOf('=');
+    if (eq !== -1) flags.set(arg.slice(2, eq), arg.slice(eq + 1));
+    else if (!argv[index + 1] || argv[index + 1].startsWith('--')) flags.set(arg.slice(2), true);
+    else {
+      flags.set(arg.slice(2), argv[index + 1]);
+      index += 1;
+    }
+  }
+  return flags;
+}
+
+function getFlag(flags, names) {
+  for (const name of names) if (flags.has(name)) return flags.get(name);
+  return undefined;
+}
+
+async function main() {
+  const flags = parseArgs();
+  const policyPath = getFlag(flags, ['approval', 'policy', 'in']);
+  if (!nonEmptyString(policyPath)) throw new Error('--approval <path> is required');
+  const packet = JSON.parse(await readFile(resolve(String(policyPath)), 'utf8'));
+  const result = validateTenantPolicyApproval(packet, { generated_at: new Date().toISOString() });
+  const out = getFlag(flags, ['out']);
+  const text = `${JSON.stringify(result, null, 2)}\n`;
+  if (out && out !== true) {
+    const outPath = resolve(String(out));
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, text, 'utf8');
+  }
+  process.stdout.write(text);
+  process.exitCode = result.ok ? 0 : 1;
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : '';
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.name ?? 'Error'}: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/validate-usage-metering.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  USAGE_AGGREGATE_SCHEMA,
+  USAGE_EVENT_SCHEMA,
+  aggregateUsageEvents,
+} from '../packages/metering/src/index.js';
+
+export const USAGE_METERING_RESULT_SCHEMA = 'enigma.usage_metering_result.v1';
+
+const SECRET_VALUE_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|https?:\/\/[^\s/@]+:[^\s/@]+@|raw memory|private prompt|full transcript|decrypted capsule|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16})/iu;
+const FORBIDDEN_KEY_RE = /(?:^|_)(?:raw|plaintext|plain_text|prompt|prompts|message|messages|text|content|document|documents|transcript|response|responses|provider_response|response_body|credential|credentials|api_key|secret|password|private_key|seed|mnemonic)(?:$|_)/iu;
+const SAFE_METRIC_KEYS = new Set([
+  'prompt_tokens',
+  'completion_tokens',
+  'memory_baseline_tokens',
+  'memory_optimized_tokens',
+  'memory_savings_tokens',
+  'billable_prompt_tokens',
+  'billable_completion_tokens',
+  'total_prompt_tokens',
+  'total_completion_tokens',
+  'total_memory_baseline_tokens',
+  'total_memory_optimized_tokens',
+  'total_memory_savings_tokens',
+]);
+const HASH_RE = /^sha256:[0-9a-f]{64}$/;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function blocker(message, path) {
+  return { message, path };
+}
+
+function assertNoSensitivePayload(value, path = 'usage_metering') {
+  if (typeof value === 'string') {
+    if (!/\.(claim_boundary\[\d+\]|product_thesis|blockers\[\d+\]\.message)$/.test(path) && SECRET_VALUE_RE.test(value)) throw new Error(`${path} contains secret-looking data`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoSensitivePayload(item, `${path}[${index}]`));
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${path}.${key}`;
+    if (FORBIDDEN_KEY_RE.test(key) && !SAFE_METRIC_KEYS.has(key) && !/^result\.blockers\[\d+\]\.message$/.test(childPath)) throw new Error(`${childPath} is not allowed in usage metering artifacts`);
+    assertNoSensitivePayload(child, childPath);
+  }
+}
+
+function finiteNonNegative(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+function validUsageEvent(event, blockers, path) {
+  if (!isPlainObject(event)) {
+    blockers.push(blocker('usage event must be an object', path));
+    return false;
+  }
+  if (event.schema !== USAGE_EVENT_SCHEMA) blockers.push(blocker('usage event schema mismatch', `${path}.schema`));
+  if (!HASH_RE.test(String(event.event_hash ?? ''))) blockers.push(blocker('usage event hash must be sha256', `${path}.event_hash`));
+  if (!/^uevt_[a-f0-9]{32}$/.test(String(event.event_id ?? ''))) blockers.push(blocker('usage event id must be deterministic uevt hash id', `${path}.event_id`));
+  const usage = event.usage;
+  if (!isPlainObject(usage)) blockers.push(blocker('usage event usage object is required', `${path}.usage`));
+  else {
+    for (const field of ['prompt_tokens', 'completion_tokens', 'memory_baseline_tokens', 'memory_optimized_tokens', 'memory_savings_tokens', 'billable_prompt_tokens', 'billable_completion_tokens']) {
+      if (!finiteNonNegative(usage[field])) blockers.push(blocker(`${path}.usage.${field} must be non-negative number`, `${path}.usage.${field}`));
+    }
+    if (finiteNonNegative(usage.memory_baseline_tokens) && finiteNonNegative(usage.memory_optimized_tokens)) {
+      if (usage.memory_optimized_tokens > usage.memory_baseline_tokens) blockers.push(blocker('memory_optimized_tokens exceeds baseline', `${path}.usage.memory_optimized_tokens`));
+      if (usage.memory_savings_tokens !== usage.memory_baseline_tokens - usage.memory_optimized_tokens) blockers.push(blocker('memory_savings_tokens must equal baseline minus optimized', `${path}.usage.memory_savings_tokens`));
+      if (usage.billable_prompt_tokens !== usage.memory_optimized_tokens) blockers.push(blocker('billable_prompt_tokens must equal memory_optimized_tokens', `${path}.usage.billable_prompt_tokens`));
+    }
+  }
+  const settlement = event.settlement_boundary;
+  if (!isPlainObject(settlement)) blockers.push(blocker('settlement_boundary is required', `${path}.settlement_boundary`));
+  else {
+    for (const field of ['token_roi_claim', 'provider_invoice_savings_claim', 'decentralized_inference_claim']) {
+      if (settlement[field] !== false) blockers.push(blocker(`${path}.settlement_boundary.${field} must be false`, `${path}.settlement_boundary.${field}`));
+    }
+    if (settlement.permissionless_access !== true) blockers.push(blocker(`${path}.settlement_boundary.permissionless_access must be true`, `${path}.settlement_boundary.permissionless_access`));
+  }
+  return true;
+}
+
+function validAggregate(aggregate, blockers, path) {
+  if (!isPlainObject(aggregate)) {
+    blockers.push(blocker('usage aggregate must be an object', path));
+    return false;
+  }
+  if (aggregate.schema !== USAGE_AGGREGATE_SCHEMA) blockers.push(blocker('usage aggregate schema mismatch', `${path}.schema`));
+  if (!HASH_RE.test(String(aggregate.aggregate_hash ?? ''))) blockers.push(blocker('usage aggregate hash must be sha256', `${path}.aggregate_hash`));
+  if (!/^uagg_[a-f0-9]{32}$/.test(String(aggregate.aggregate_id ?? ''))) blockers.push(blocker('usage aggregate id must be deterministic uagg hash id', `${path}.aggregate_id`));
+  if (!Number.isSafeInteger(aggregate.event_count) || aggregate.event_count <= 0) blockers.push(blocker('usage aggregate event_count must be positive integer', `${path}.event_count`));
+  if (!Array.isArray(aggregate.event_hashes) || aggregate.event_hashes.length !== aggregate.event_count || aggregate.event_hashes.some((hash) => !HASH_RE.test(String(hash)))) {
+    blockers.push(blocker('usage aggregate event_hashes must match event_count and contain sha256 hashes', `${path}.event_hashes`));
+  }
+  const totals = aggregate.totals;
+  if (!isPlainObject(totals)) blockers.push(blocker('usage aggregate totals object is required', `${path}.totals`));
+  else {
+    for (const field of ['prompt_tokens', 'completion_tokens', 'memory_baseline_tokens', 'memory_optimized_tokens', 'memory_savings_tokens', 'cost_before_memory', 'cost_after_memory', 'estimated_memory_credit']) {
+      if (!finiteNonNegative(totals[field])) blockers.push(blocker(`${path}.totals.${field} must be non-negative number`, `${path}.totals.${field}`));
+    }
+    if (finiteNonNegative(totals.memory_baseline_tokens) && finiteNonNegative(totals.memory_optimized_tokens)) {
+      if (totals.memory_optimized_tokens > totals.memory_baseline_tokens) blockers.push(blocker('aggregate optimized tokens exceed baseline', `${path}.totals.memory_optimized_tokens`));
+      if (totals.memory_savings_tokens !== totals.memory_baseline_tokens - totals.memory_optimized_tokens) blockers.push(blocker('aggregate memory_savings_tokens must equal baseline minus optimized', `${path}.totals.memory_savings_tokens`));
+    }
+  }
+  if (!Array.isArray(aggregate.claim_boundary) || aggregate.claim_boundary.length === 0) blockers.push(blocker('usage aggregate claim_boundary is required', `${path}.claim_boundary`));
+  return true;
+}
+
+function normalizeInput(input) {
+  if (Array.isArray(input)) return { events: input };
+  if (isPlainObject(input) && Array.isArray(input.events)) return { events: input.events, tenant_id: input.tenant_id, meter_id: input.meter_id, generated_at: input.generated_at };
+  return { artifact: input };
+}
+
+export function validateUsageMetering(input, options = {}) {
+  assertNoSensitivePayload(input);
+  const normalized = normalizeInput(input);
+  const blockers = [];
+  let artifact = normalized.artifact;
+  let mode = 'artifact';
+  let checkedEvents = 0;
+  if (normalized.events) {
+    mode = 'events';
+    normalized.events.forEach((event, index) => validUsageEvent(event, blockers, `events[${index}]`));
+    checkedEvents = normalized.events.length;
+    if (blockers.length === 0) {
+      try {
+        artifact = aggregateUsageEvents({
+          events: normalized.events,
+          tenant_id: normalized.tenant_id,
+          meter_id: normalized.meter_id,
+          generated_at: normalized.generated_at,
+        });
+      } catch (error) {
+        blockers.push(blocker(error.message, 'events'));
+      }
+    }
+  }
+  if (artifact?.schema === USAGE_EVENT_SCHEMA) {
+    validUsageEvent(artifact, blockers, 'artifact');
+    checkedEvents = Math.max(checkedEvents, 1);
+  } else if (artifact?.schema === USAGE_AGGREGATE_SCHEMA) {
+    validAggregate(artifact, blockers, 'artifact');
+  } else if (!normalized.events) {
+    blockers.push(blocker('artifact must be usage event, usage aggregate, or events array', 'artifact.schema'));
+  }
+  const result = {
+    schema: USAGE_METERING_RESULT_SCHEMA,
+    generated_at: options.generated_at ?? options.generatedAt ?? new Date(0).toISOString(),
+    ok: blockers.length === 0,
+    status: blockers.length === 0 ? 'accepted' : 'blocked',
+    mode,
+    blockers,
+    checked: {
+      events: checkedEvents,
+      aggregate_schema: artifact?.schema === USAGE_AGGREGATE_SCHEMA ? artifact.schema : null,
+      event_schema: artifact?.schema === USAGE_EVENT_SCHEMA ? artifact.schema : null,
+      memory_savings_tokens: artifact?.usage?.memory_savings_tokens ?? artifact?.totals?.memory_savings_tokens ?? null,
+      event_count: artifact?.event_count ?? (artifact?.schema === USAGE_EVENT_SCHEMA ? 1 : 0),
+    },
+    claim_boundary: [
+      'Usage metering validation checks content-minimized Enigma usage math only; it is not a provider invoice guarantee.',
+      'A pass result does not claim token ROI, token profit, decentralized inference, provider deletion, model forgetting, or compliance status.',
+      'Raw prompts, completions, provider responses, transcripts, decrypted memory, credentials, keys, and seed phrases are forbidden in usage metering artifacts.',
+    ],
+  };
+  assertNoSensitivePayload(result, 'result');
+  return result;
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const flags = new Map();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) continue;
+    const eq = arg.indexOf('=');
+    if (eq !== -1) flags.set(arg.slice(2, eq), arg.slice(eq + 1));
+    else if (!argv[index + 1] || argv[index + 1].startsWith('--')) flags.set(arg.slice(2), true);
+    else {
+      flags.set(arg.slice(2), argv[index + 1]);
+      index += 1;
+    }
+  }
+  return flags;
+}
+
+function getFlag(flags, names) {
+  for (const name of names) if (flags.has(name)) return flags.get(name);
+  return undefined;
+}
+
+async function main() {
+  const flags = parseArgs();
+  const meteringPath = getFlag(flags, ['metering', 'usage', 'in']);
+  if (typeof meteringPath !== 'string' || meteringPath.trim() === '') throw new Error('--metering <path> is required');
+  const input = JSON.parse(await readFile(resolve(meteringPath), 'utf8'));
+  const result = validateUsageMetering(input, { generated_at: new Date().toISOString() });
+  const out = getFlag(flags, ['out']);
+  const text = `${JSON.stringify(result, null, 2)}\n`;
+  if (out && out !== true) {
+    const outPath = resolve(String(out));
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, text, 'utf8');
+  }
+  process.stdout.write(text);
+  process.exitCode = result.ok ? 0 : 1;
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : '';
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.name ?? 'Error'}: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/validate-whitepaper-claims.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const WHITEPAPER_CLAIMS_RESULT_SCHEMA = 'enigma.whitepaper_claims_result.v1';
+
+const REQUIRED_HEADINGS = Object.freeze([
+  '# Enigma Memory technical whitepaper',
+  '## Abstract',
+  '## 2. System model',
+  '## 3. Commitment and receipt chain',
+  '## 4. Context selection and optimization',
+  '## 5. How Enigma differs from adjacent systems',
+  '### 5.6 Memory-layer evaluation framework',
+  '## 6. Privacy and leakage model',
+  '## 7. Production readiness boundary',
+  '## 8. Claim boundary',
+]);
+
+const REQUIRED_TERMS = Object.freeze([
+  'provider-neutral memory custody',
+  'local/BYOC',
+  'active_set_root',
+  'T_{base}',
+  'T_{opt}',
+  'D_E(X)',
+  'RawMemory \\notin PublicEvidence',
+  'hosted_live_ready',
+  'npm run memory:benchmark',
+]);
+
+const ABSOLUTE_CLAIM_RE = /(?:\$\s*100\s*billion|100\s*billion|best\s+in\s+the\s+world|guaranteed|guarantee|universal\s+(?:invoice\s+)?savings|provider[-\s]?side\s+deletion|model\s+forgetting|token\s+ROI|compliance\s+certification|tamper-proof|live\s+hosted\s+backend\s+readiness)/iu;
+const DENY_CONTEXT_RE = /(?:does\s+\W*not\s+\W*claim|must\s+\W*not\s+\W*claim|must\s+not\s+infer|not\s+a|not\s+provider|not\s+hosted|not\s+ready|without\s+separate\s+evidence|before\s+production\s+dependencies|is\s+not\s+a|should\s+not)/iu;
+const SECRET_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|sk-[A-Za-z0-9_-]{16,}|https?:\/\/[^\s/@]+:[^\s/@]+@)/iu;
+const LOCAL_PATH_RE = /(?:[A-Z]:\\Users\\|\/Users\/|\/home\/)/u;
+
+function countRegex(text, regex) {
+  return [...text.matchAll(regex)].length;
+}
+
+function lineNumberedFindings(text, regex, allowedContext) {
+  const findings = [];
+  const lines = text.split(/\r?\n/u);
+  let denyBlock = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const normalizedLine = line.replace(/[*_`]/gu, '');
+    const normalizedWindow = [lines[index - 2] ?? '', lines[index - 1] ?? '', line]
+      .join(' ')
+      .replace(/[*_`]/gu, '');
+    if (/^##\s+/u.test(line) && !/claim boundary/iu.test(line)) denyBlock = false;
+    if (allowedContext?.test(normalizedWindow)) denyBlock = true;
+    if (!regex.test(line)) continue;
+    if (allowedContext?.test(normalizedLine) || allowedContext?.test(normalizedWindow) || denyBlock) continue;
+    findings.push({ line: index + 1, text: line.trim().slice(0, 160) });
+  }
+  return findings;
+}
+
+export function validateWhitepaperClaims(markdown, options = {}) {
+  if (typeof markdown !== 'string' || markdown.trim().length === 0) throw new Error('whitepaper markdown is required');
+  const blockers = [];
+  const warnings = [];
+  const headingMissing = REQUIRED_HEADINGS.filter((heading) => !markdown.includes(heading));
+  const termMissing = REQUIRED_TERMS.filter((term) => !markdown.includes(term));
+  for (const heading of headingMissing) blockers.push(`missing heading: ${heading}`);
+  for (const term of termMissing) blockers.push(`missing required technical term: ${term}`);
+
+  const equationBlockCount = countRegex(markdown, /^\$\$/gmu) / 2;
+  const mermaidCount = countRegex(markdown, /```mermaid/gmu);
+  const mathSymbolCount = countRegex(markdown, /(?:T_\{base\}|T_\{opt\}|\Delta_\{|D_E\(X\)|MerkleSetRoot|PublicEvidence|RawMemory)/gu);
+  if (equationBlockCount < 10) blockers.push(`expected at least 10 displayed equation blocks; found ${equationBlockCount}`);
+  if (mermaidCount < 4) blockers.push(`expected at least 4 Mermaid diagrams; found ${mermaidCount}`);
+  if (mathSymbolCount < 8) blockers.push(`expected at least 8 math/evaluation symbols; found ${mathSymbolCount}`);
+
+  const absoluteFindings = lineNumberedFindings(markdown, ABSOLUTE_CLAIM_RE, DENY_CONTEXT_RE);
+  for (const finding of absoluteFindings) blockers.push(`unsupported absolute claim on line ${finding.line}: ${finding.text}`);
+  const secretFindings = lineNumberedFindings(markdown, SECRET_RE);
+  for (const finding of secretFindings) blockers.push(`secret-looking content on line ${finding.line}`);
+  const pathFindings = lineNumberedFindings(markdown, LOCAL_PATH_RE);
+  for (const finding of pathFindings) blockers.push(`local path content on line ${finding.line}`);
+
+  if (!/This is an evaluation framework, not a theorem of universal superiority\./u.test(markdown)) blockers.push('missing explicit evaluation-framework claim boundary');
+  if (!/This is deliberately not a provider invoice guarantee\./u.test(markdown)) blockers.push('missing provider-invoice savings boundary');
+  if (!/A hosted deployment is not ready because code exists\./u.test(markdown)) blockers.push('missing hosted readiness boundary');
+  if (!/Raw memory is excluded:/u.test(markdown)) blockers.push('missing raw-memory public evidence exclusion');
+  if (/better than anything else out there/iu.test(markdown)) warnings.push('marketing superlative phrase should stay out of technical whitepaper');
+
+  return {
+    schema: WHITEPAPER_CLAIMS_RESULT_SCHEMA,
+    generated_at: options.generated_at ?? options.generatedAt ?? new Date(0).toISOString(),
+    ok: blockers.length === 0,
+    status: blockers.length === 0 ? 'accepted' : 'blocked',
+    path: options.path ?? null,
+    counts: {
+      headings_required: REQUIRED_HEADINGS.length,
+      headings_missing: headingMissing.length,
+      required_terms: REQUIRED_TERMS.length,
+      required_terms_missing: termMissing.length,
+      displayed_equation_blocks: equationBlockCount,
+      mermaid_diagrams: mermaidCount,
+      math_symbol_mentions: mathSymbolCount,
+      unsupported_absolute_claims: absoluteFindings.length,
+      secret_findings: secretFindings.length,
+      local_path_findings: pathFindings.length,
+    },
+    warnings,
+    blockers,
+    claim_boundary: [
+      'This validator checks that the whitepaper contains math, diagrams, and explicit claim boundaries; it does not prove market leadership or $100B value.',
+      'Passing validation means the document is evidence-bounded and structurally complete, not that hosted infrastructure is live.',
+    ],
+  };
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const out = { file: 'docs/enigma-memory-technical-whitepaper.md', out: null, help: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--help' || token === '-h') {
+      out.help = true;
+      continue;
+    }
+    const readValue = () => {
+      const value = argv[index + 1];
+      if (typeof value !== 'string' || value.length === 0 || value.startsWith('--')) throw new Error(`${token} requires a value`);
+      index += 1;
+      return value;
+    };
+    if (token === '--file') out.file = readValue();
+    else if (token === '--out') out.out = readValue();
+    else throw new Error(`unknown option ${token}`);
+  }
+  return out;
+}
+
+function usage() {
+  return 'Usage: node scripts/validate-whitepaper-claims.mjs [--file docs/enigma-memory-technical-whitepaper.md] [--out <file>]\n\nValidates math/diagram coverage and claim boundaries for the Enigma Memory technical whitepaper.\n';
+}
+
+async function runCli(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help) return { text: usage(), code: 0 };
+  const file = resolve(args.file);
+  const markdown = await readFile(file, 'utf8');
+  const result = validateWhitepaperClaims(markdown, { path: args.file, generated_at: new Date().toISOString() });
+  const json = `${JSON.stringify(result, null, 2)}\n`;
+  if (args.out) {
+    const outPath = resolve(args.out);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, json, 'utf8');
+  }
+  return { text: json, code: result.ok ? 0 : 1 };
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  try {
+    const { text, code } = await runCli();
+    process.stdout.write(text);
+    process.exitCode = code;
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 2;
+  }
+}

package/specs/boundary-manifest-v1.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.enigma.ai/boundary-manifest-v1.schema.json",
+  "title": "Enigma Boundary Manifest v1",
+  "type": "object",
+  "required": ["schema", "manifest_id", "system_id", "created_at", "paths", "default_action"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "enigma.boundary_manifest.v1" },
+    "manifest_id": { "type": "string", "minLength": 8 },
+    "system_id": { "type": "string", "minLength": 1 },
+    "created_at": { "type": "string", "format": "date-time" },
+    "default_action": { "const": "fail_unknown" },
+    "paths": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["path_id", "surface", "classification"],
+        "additionalProperties": false,
+        "properties": {
+          "path_id": { "type": "string", "minLength": 1 },
+          "surface": {
+            "type": "string",
+            "enum": ["model_input", "model_output", "tool_args", "tool_result", "scratchpad", "memory_write", "memory_read", "rag_ingest", "rag_retrieve", "file_write", "log", "telemetry", "browser_dom", "mcp_resource", "network", "inter_agent", "cache", "human_approval"]
+          },
+          "classification": { "type": "string", "enum": ["committed", "blocked", "declared_out_of_scope", "broken"] },
+          "adapter": { "type": "string" },
+          "reason": { "type": "string" },
+          "coverage_receipt_required": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}