enigma-memory 0.1.0

package/scripts/install-enigma-local.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve as resolvePath } from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+export const INSTALLER_SCHEMA = 'enigma.local_installer.v1';
+export const REQUIRED_NODE_MAJOR = 24;
+export const DEFAULT_BUNDLE_PATH = '.enigma/bundle.json';
+
+const execFileAsync = promisify(execFile);
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const DEFAULT_PACKAGE_DIR = resolvePath(dirname(SCRIPT_PATH), '..');
+const SAFE_COMMAND_RE = /^[A-Za-z0-9._-]+$/u;
+
+function readRequiredValue(argv, index, flag) {
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${flag}.`);
+  return value;
+}
+
+export function usage() {
+  return `Usage: node scripts/install-enigma-local.mjs [--dry-run|--execute] [--init-vault] [--bundle <path>]\n\nDry-run is the default. Execute mode runs npm install -g . from the local checkout.\nNo network download command is generated, and vault initialization runs only when --init-vault is present.\n`;
+}
+
+export function parseInstallerArgs(argv = process.argv.slice(2)) {
+  const options = {
+    dryRun: true,
+    execute: false,
+    initVault: false,
+    bundlePath: DEFAULT_BUNDLE_PATH,
+    packageDir: DEFAULT_PACKAGE_DIR,
+    subject: 'local-user',
+    displayName: 'Local user',
+  };
+  let sawDryRun = false;
+  let sawExecute = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--dry-run') {
+      sawDryRun = true;
+      options.dryRun = true;
+      options.execute = false;
+    } else if (arg === '--execute') {
+      sawExecute = true;
+      options.dryRun = false;
+      options.execute = true;
+    } else if (arg === '--init-vault') {
+      options.initVault = true;
+    } else if (arg === '--no-init-vault') {
+      options.initVault = false;
+    } else if (arg === '--bundle') {
+      options.bundlePath = readRequiredValue(argv, index, arg);
+      index += 1;
+    } else if (arg === '--package-dir') {
+      options.packageDir = readRequiredValue(argv, index, arg);
+      index += 1;
+    } else if (arg === '--subject') {
+      options.subject = readRequiredValue(argv, index, arg);
+      index += 1;
+    } else if (arg === '--display-name') {
+      options.displayName = readRequiredValue(argv, index, arg);
+      index += 1;
+    } else {
+      throw new Error('Unknown argument.');
+    }
+  }
+
+  if (sawDryRun && sawExecute) throw new Error('Use either --dry-run or --execute, not both.');
+  return options;
+}
+
+export function nodeMajor(version) {
+  const match = String(version ?? '').trim().match(/^v?(\d+)(?:\.\d+){0,2}(?:[-+].*)?$/u);
+  if (!match) throw new Error('Invalid Node version override.');
+  return Number(match[1]);
+}
+
+export function validateNodeVersion(version = process.versions.node, requiredMajor = REQUIRED_NODE_MAJOR) {
+  const major = nodeMajor(version);
+  if (!Number.isSafeInteger(major) || major < requiredMajor) {
+    throw new Error(`Node >=${requiredMajor} is required for the local Enigma installer.`);
+  }
+  return { ok: true, required: `>=${requiredMajor}`, current_major: major };
+}
+
+function commandForPlatform(base, platform) {
+  return platform === 'win32' ? `${base}.cmd` : base;
+}
+
+function rejectUnsafeArg(arg, label) {
+  const value = String(arg ?? '');
+  if (value.length === 0) throw new Error(`${label} must not be empty.`);
+  if (value.includes('\0') || value.includes('\n') || value.includes('\r')) throw new Error(`${label} contains an invalid control character.`);
+}
+
+export function validateCommandSpec(spec) {
+  if (!spec || typeof spec !== 'object' || Array.isArray(spec)) throw new Error('Installer command spec must be an object.');
+  const command = String(spec.command ?? '');
+  if (!SAFE_COMMAND_RE.test(command)) throw new Error('Installer command name is not safe.');
+  const args = Array.isArray(spec.args) ? spec.args.map(String) : [];
+  for (const [index, arg] of args.entries()) rejectUnsafeArg(arg, `Installer command argument ${index}`);
+
+  if (command === 'npm' || command === 'npm.cmd') {
+    if (args.length !== 3 || args[0] !== 'install' || args[1] !== '-g' || args[2] !== '.') {
+      throw new Error('Installer npm command must be exactly npm install -g .');
+    }
+    return true;
+  }
+
+  if (command === 'enigma' || command === 'enigma.cmd') {
+    const bundleIndex = args.indexOf('--bundle');
+    if (args[0] !== 'init' || bundleIndex === -1 || bundleIndex + 1 >= args.length) {
+      throw new Error('Installer Enigma command must initialize a bundle with --bundle.');
+    }
+    return true;
+  }
+
+  throw new Error('Installer command is not allowlisted.');
+}
+
+function publicCommand(command) {
+  if (command.step === 'install_package') return { command: 'npm', args: ['install', '-g', '.'] };
+  return { command: 'enigma', args: ['init', '--bundle', '<bundle-path>', '--subject', '<subject>', '--display-name', '<display-name>'] };
+}
+
+export function buildInstallerPlan(options = {}, runtime = {}) {
+  const platform = runtime.platform ?? process.platform;
+  const cwd = runtime.cwd ?? process.cwd();
+  const requestedPackageDir = String(options.packageDir ?? DEFAULT_PACKAGE_DIR);
+  rejectUnsafeArg(requestedPackageDir, 'Package directory');
+  const packageDir = resolvePath(requestedPackageDir);
+  const requestedBundlePath = String(options.bundlePath ?? DEFAULT_BUNDLE_PATH);
+  rejectUnsafeArg(requestedBundlePath, 'Bundle path');
+  const bundlePath = isAbsolute(requestedBundlePath) ? resolvePath(requestedBundlePath) : resolvePath(cwd, requestedBundlePath);
+
+  const commands = [
+    {
+      step: 'install_package',
+      command: commandForPlatform('npm', platform),
+      args: ['install', '-g', '.'],
+      cwd: packageDir,
+      mutates_global_state: true,
+    },
+  ];
+
+  if (options.initVault === true) {
+    commands.push({
+      step: 'initialize_vault',
+      command: commandForPlatform('enigma', platform),
+      args: ['init', '--bundle', bundlePath, '--subject', String(options.subject ?? 'local-user'), '--display-name', String(options.displayName ?? 'Local user')],
+      cwd: packageDir,
+      mutates_local_filesystem: true,
+    });
+  }
+
+  for (const command of commands) validateCommandSpec(command);
+
+  return {
+    dryRun: options.execute === true ? false : true,
+    execute: options.execute === true,
+    packageDir,
+    bundlePath,
+    bundlePathKind: requestedBundlePath === DEFAULT_BUNDLE_PATH ? 'default' : (isAbsolute(requestedBundlePath) ? 'absolute' : 'relative'),
+    initVault: options.initVault === true,
+    commands,
+  };
+}
+
+function publicCommandRecords(plan, resultByStep = new Map()) {
+  return plan.commands.map((command) => {
+    const publicSpec = publicCommand(command);
+    const runResult = resultByStep.get(command.step);
+    return {
+      step: command.step,
+      command: publicSpec.command,
+      args: publicSpec.args,
+      status: plan.execute ? (runResult?.ok ? 'executed' : 'pending') : 'preview',
+      mutates: command.mutates_global_state === true ? 'global_npm_install' : 'local_bundle_file',
+    };
+  });
+}
+
+function publicOutput(plan, node, commandResults = []) {
+  const resultByStep = new Map(commandResults.map((result) => [result.step, result]));
+  const commands = publicCommandRecords(plan, resultByStep);
+  return {
+    schema: INSTALLER_SCHEMA,
+    ok: commandResults.every((result) => result.ok !== false),
+    mode: plan.execute ? 'execute' : 'dry-run',
+    dry_run: plan.dryRun,
+    execute: plan.execute,
+    public_safe: true,
+    node,
+    package_source: {
+      kind: 'local_checkout',
+      install_boundary: 'Runs npm install -g . against the checked-out package only; it does not download Enigma from a registry.',
+    },
+    bundle: {
+      path: '<bundle-path>',
+      path_kind: plan.bundlePathKind,
+      initialize_requested: plan.initVault,
+      initialized: plan.execute && plan.initVault && resultByStep.get('initialize_vault')?.ok === true,
+    },
+    commands,
+    preview: {
+      commands,
+    },
+    safety: {
+      default_dry_run: true,
+      requires_execute_for_mutation: true,
+      shell: false,
+      network_download_command: false,
+      prints_local_absolute_paths: false,
+      prints_secrets: false,
+    },
+  };
+}
+
+async function runCommand(command, execFileImpl) {
+  try {
+    await execFileImpl(command.command, command.args, { cwd: command.cwd, windowsHide: true });
+    return { step: command.step, ok: true };
+  } catch {
+    throw new Error(`Installer command failed at ${command.step}.`);
+  }
+}
+
+export async function runInstallEnigmaLocal(argv = process.argv.slice(2), runtime = {}) {
+  const options = Array.isArray(argv) ? parseInstallerArgs(argv) : { ...argv };
+  const node = validateNodeVersion(options.nodeVersion ?? runtime.nodeVersion ?? process.versions.node);
+  const plan = buildInstallerPlan(options, runtime);
+  if (plan.dryRun) return publicOutput(plan, node);
+
+  const mkdirImpl = runtime.mkdirImpl ?? mkdir;
+  if (options.initVault === true) await mkdirImpl(dirname(plan.bundlePath), { recursive: true });
+  const execFileImpl = runtime.execFileImpl ?? execFileAsync;
+  const commandResults = [];
+  for (const command of plan.commands) {
+    commandResults.push(await runCommand(command, execFileImpl));
+  }
+  return publicOutput(plan, node, commandResults);
+}
+
+function safeErrorMessage(error) {
+  const message = String(error?.message ?? error);
+  if (/^(Missing value|Unknown argument|Use either|Invalid Node version|Node >=|Installer command)/u.test(message)) return message;
+  return 'Local Enigma installer failed.';
+}
+
+async function main() {
+  const args = parseInstallerArgs();
+  if (args.help) {
+    process.stdout.write(usage());
+    return;
+  }
+  const output = await runInstallEnigmaLocal(args);
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {
+  main().catch((error) => {
+    process.stdout.write(`${JSON.stringify({ schema: INSTALLER_SCHEMA, ok: false, public_safe: true, error: { code: 'LOCAL_INSTALLER_FAILED', message: safeErrorMessage(error) } }, null, 2)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/memory-optimization-benchmark.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+import { writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir } from 'node:fs/promises';
+import {
+  createMemoryAccessReceipt,
+  createMemoryOptimizationPlan,
+  estimateTextTokens,
+} from '../packages/optimizer/src/index.js';
+
+export const MEMORY_OPTIMIZATION_BENCHMARK_SCHEMA = 'enigma.memory_optimization_benchmark.v1';
+
+const DEFAULT_PRICE_PER_MILLION_TOKENS = 2.5;
+
+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, fallback = undefined) {
+  for (const name of names) if (flags.has(name)) return flags.get(name);
+  return fallback;
+}
+
+function sha256Like(label) {
+  let hash = 0;
+  for (let index = 0; index < label.length; index += 1) hash = (hash * 31 + label.charCodeAt(index)) >>> 0;
+  return `sha256:${String(hash.toString(16)).padStart(64, '0').slice(0, 64)}`;
+}
+
+function fixtureCandidates() {
+  const rows = [
+    ['mem_auth_policy', 'Project policy: admin routes stay private; public routes expose only readyz and livez.', 0.92],
+    ['mem_auth_policy_duplicate', 'Project policy: admin routes stay private; public routes expose only readyz and livez.', 0.7],
+    ['mem_cost_boundary', 'Cost claims must be estimate-bound: no universal discount, benchmark lead, or invoice claim without commands and results.', 0.86],
+    ['mem_chain_boundary', 'Blockchain is for access, settlement, and proof anchoring only; raw memory never goes on-chain.', 0.82],
+    ['mem_support_note', 'Support escalation uses observed facts only and does not claim provider deletion or model forgetting.', 0.58],
+    ['mem_old_context', 'Old context can stay proof-only when the task does not need full text.', 0.18],
+  ];
+  return rows.map(([address, content, importance], index) => ({
+    address,
+    content,
+    importance,
+    last_accessed_at: `2026-06-23T12:0${Math.min(index, 5)}:00.000Z`,
+    metadata: {
+      fixture: 'optimizer-benchmark',
+      order: index,
+      content_commitment: sha256Like(`${address}:${content.length}`),
+    },
+  }));
+}
+
+function publicItem(item) {
+  const out = { ...item };
+  if (out.content_hash !== undefined) {
+    delete out.content_hash;
+    out.content_hash_redacted = true;
+  }
+  return out;
+}
+
+function publicPlan(plan) {
+  const tiers = {};
+  for (const [tier, items] of Object.entries(plan.tiers ?? {})) tiers[tier] = items.map(publicItem);
+  return {
+    ...plan,
+    tiers,
+    items: plan.items.map(publicItem),
+  };
+}
+
+function publicReceipt(receipt) {
+  const out = { ...receipt };
+  if (out.content_hash !== undefined) {
+    delete out.content_hash;
+    out.content_hash_redacted = true;
+  }
+  return out;
+}
+
+
+function comparativeBaselines(plan, candidates, pricing) {
+  const seen = new Set();
+  let dedupedFullContextTokens = 0;
+  let duplicateCandidatesRemoved = 0;
+  for (const candidate of candidates) {
+    const content = String(candidate.content ?? '');
+    if (seen.has(content)) {
+      duplicateCandidatesRemoved += 1;
+      continue;
+    }
+    seen.add(content);
+    dedupedFullContextTokens += estimateTextTokens(content);
+  }
+  const optimizedTokens = plan.optimized_prompt_tokens;
+  const baselineTokens = plan.baseline_prompt_tokens;
+  return {
+    schema: 'enigma.memory_strategy_comparison.v1',
+    strategies: [
+      {
+        id: 'full_context_unverified',
+        prompt_tokens: baselineTokens,
+        estimated_cost: (baselineTokens / 1_000_000) * pricing.price_per_million_tokens,
+        duplicate_candidates_removed: 0,
+        access_receipts: false,
+        proof_boundary: false,
+        public_candidate_text_included: false,
+      },
+      {
+        id: 'deduped_full_context_unreceipted',
+        prompt_tokens: dedupedFullContextTokens,
+        estimated_cost: (dedupedFullContextTokens / 1_000_000) * pricing.price_per_million_tokens,
+        duplicate_candidates_removed: duplicateCandidatesRemoved,
+        access_receipts: false,
+        proof_boundary: false,
+        public_candidate_text_included: false,
+      },
+      {
+        id: 'enigma_receipted_plan',
+        prompt_tokens: optimizedTokens,
+        estimated_cost: (optimizedTokens / 1_000_000) * pricing.price_per_million_tokens,
+        duplicate_candidates_removed: plan.totals.duplicates_removed,
+        access_receipts: true,
+        proof_boundary: true,
+        public_candidate_text_included: false,
+      },
+    ],
+    enigma_vs_full_context: {
+      prompt_token_delta: baselineTokens - optimizedTokens,
+      prompt_token_reduction_pct: baselineTokens === 0 ? 0 : Number((((baselineTokens - optimizedTokens) / baselineTokens) * 100).toFixed(6)),
+      access_receipts_added: true,
+      raw_text_publication_removed: true,
+      provider_invoice_savings_claim: false,
+      universal_discount_claim: false,
+    },
+    claim_boundary: [
+      'Strategy comparison is computed on a repository fixture only.',
+      'Lower prompt_tokens is a local estimator result, not a provider invoice or universal discount claim.',
+      'Unreceipted strategies may use fewer tokens but do not provide Enigma receipt/proof boundaries.',
+    ],
+  };
+}
+export function runMemoryOptimizationBenchmark(options = {}) {
+  const generatedAt = options.generated_at ?? options.generatedAt ?? new Date().toISOString();
+  const pricing = {
+    currency: options.currency ?? 'USD',
+    price_per_million_tokens: Number(options.price_per_million_tokens ?? options.pricePerMillionTokens ?? DEFAULT_PRICE_PER_MILLION_TOKENS),
+  };
+  if (!Number.isFinite(pricing.price_per_million_tokens) || pricing.price_per_million_tokens < 0) {
+    throw new Error('price_per_million_tokens must be a non-negative number');
+  }
+  const plan = createMemoryOptimizationPlan({
+    candidates: fixtureCandidates(),
+    prompt: 'Prepare the production memory-layer launch answer with security and claim boundaries.',
+    pricing,
+    now: '2026-06-23T12:06:00.000Z',
+  });
+  const receipts = plan.items.map((item, index) => createMemoryAccessReceipt({
+    item,
+    plan,
+    timestamp: generatedAt,
+    sequence: index,
+    pricing,
+  }));
+  const report = {
+    schema: MEMORY_OPTIMIZATION_BENCHMARK_SCHEMA,
+    generated_at: generatedAt,
+    corpus: {
+      name: 'enigma.optimizer.fixture.v1',
+      private_candidate_count: fixtureCandidates().length,
+      public_candidate_text_included: false,
+    },
+    strategy_comparison: comparativeBaselines(plan, fixtureCandidates(), pricing),
+    method: {
+      tokenizer: 'estimateTextTokens deterministic local estimator',
+      planner: 'createMemoryOptimizationPlan',
+      pricing_input: pricing,
+      claim_boundary: [
+        'This is a fixture benchmark for repository behavior only.',
+        'savings_pct is estimated prompt-token reduction for these inputs, not provider invoice savings.',
+        'No external-deletion, external-forgetting, crypto-return, compliance, or universal-discount claim is made.',
+      ],
+    },
+    result: {
+      baseline_prompt_tokens: plan.baseline_prompt_tokens,
+      optimized_prompt_tokens: plan.optimized_prompt_tokens,
+      savings_pct: plan.savings_pct,
+      baseline_cost: plan.baseline_cost,
+      optimized_cost: plan.optimized_cost,
+      duplicate_candidates_removed: plan.totals.duplicates_removed,
+      deduped_candidates: plan.totals.deduped_candidates,
+      tiers: Object.fromEntries(Object.entries(plan.tiers).map(([tier, items]) => [tier, items.length])),
+    },
+    optimization_plan: publicPlan(plan),
+    optimization_receipts: receipts.map(publicReceipt),
+  };
+  const serialized = JSON.stringify(report);
+  if (/Project policy|Cost claims|Blockchain is|Support escalation|Old context/i.test(serialized)) {
+    throw new Error('benchmark report leaked private fixture text');
+  }
+  return report;
+}
+
+async function main() {
+  const flags = parseArgs();
+  const report = runMemoryOptimizationBenchmark({
+    price_per_million_tokens: getFlag(flags, ['price-per-million-tokens', 'pricePerMillionTokens'], DEFAULT_PRICE_PER_MILLION_TOKENS),
+    currency: getFlag(flags, ['currency'], 'USD'),
+  });
+  const out = getFlag(flags, ['out']);
+  if (out && out !== true) {
+    const path = resolve(String(out));
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    process.stdout.write(`${JSON.stringify({ ok: true, schema: report.schema, out: path, result: report.result }, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : '';
+const modulePath = fileURLToPath(import.meta.url);
+if (invokedPath === modulePath) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}