@jaimevalasek/aioson 1.9.3 → 1.16.0

package/src/operator-memory/decision.js

@@ -0,0 +1,274 @@
+'use strict';
+
+/**
+ * operator-memory — decision CRUD with atomic promote (Phase 2, v1.13.0).
+ *
+ * Atomicity boundary (AC-P2-03): SQLite transaction wraps fs operations.
+ * Crash mid-transaction → rollback. Markdown is source-of-truth (PMD-AN-06);
+ * FTS5 mirror is regenerable. See architecture-operator-memory.md § Phase 2.
+ *
+ * Schema (frontmatter + body):
+ *   ---
+ *   slug: ...
+ *   signal_type: ...
+ *   promoted_at: <ISO>
+ *   last_reinforced: <ISO>
+ *   reinforcement_count: 0
+ *   superseded_by: null
+ *   category: identity | autonomy | tooling | default
+ *   source_agent: ...
+ *   quotes: [...]                       # capped at 5
+ *   version_schema: "1.0"
+ *   deprecated_by: null
+ *   ---
+ *
+ *   # {Title}
+ *
+ *   {Body — short paragraph}
+ *
+ *   ## Trigger quotes
+ *   - "..."
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getStorageRoot, openIndexDb } = require('./storage');
+const { deleteProposal, proposalPath } = require('./proposal');
+
+const SCHEMA_VERSION = '1.0';
+const MAX_BODY_CHARS = 500;
+const VALID_CATEGORIES = ['identity', 'autonomy', 'tooling', 'default'];
+
+const CATEGORY_KEYWORDS = {
+  identity: ['preferencia', 'preference', 'estilo', 'style', 'communication', 'comunicacao', 'linguagem', 'language', 'tom', 'tone'],
+  autonomy: ['commit', 'push', 'publish', 'deploy', 'merge', 'release', 'tag'],
+  tooling: ['cli', 'tool', 'comando', 'command', 'aws', 'gcp', 'kubectl', 'docker', 'npm', 'pip']
+};
+
+function inferCategory(signalType, body) {
+  if (signalType !== 'authorization') return 'default';
+  const text = String(body || '').toLowerCase();
+  for (const cat of ['identity', 'autonomy', 'tooling']) {
+    if (CATEGORY_KEYWORDS[cat].some((kw) => text.includes(kw))) return cat;
+  }
+  return 'default';
+}
+
+function decisionPath(identity, slug) {
+  return path.join(getStorageRoot(identity), 'decisions', `${slug}.md`);
+}
+
+function historyPath(identity, slug, isoStamp) {
+  return path.join(getStorageRoot(identity), 'history', `${isoStamp.replace(/[:.]/g, '-')}-${slug}.md`);
+}
+
+function escapeYamlString(value) {
+  const s = String(value || '');
+  return `'${s.replace(/'/g, "''")}'`;
+}
+
+function quotesToYaml(quotes) {
+  if (!quotes || quotes.length === 0) return '[]';
+  return '\n' + quotes.map((q) => `  - ${escapeYamlString(q)}`).join('\n');
+}
+
+function deriveTitle(proposal) {
+  const text = String(proposal || '').trim();
+  if (!text) return 'Untitled decision';
+  return text.charAt(0).toUpperCase() + text.slice(1, 100);
+}
+
+function serializeDecision(data) {
+  const body = String(data.body || data.proposal || '').slice(0, MAX_BODY_CHARS);
+  const title = deriveTitle(data.title || data.proposal);
+  return [
+    '---',
+    `slug: ${data.slug}`,
+    `signal_type: ${data.signal_type}`,
+    `promoted_at: ${data.promoted_at}`,
+    `last_reinforced: ${data.last_reinforced}`,
+    `reinforcement_count: ${data.reinforcement_count}`,
+    `superseded_by: ${data.superseded_by ?? 'null'}`,
+    `category: ${data.category}`,
+    `source_agent: ${data.source_agent}`,
+    `quotes:${quotesToYaml(data.quotes)}`,
+    `version_schema: "${SCHEMA_VERSION}"`,
+    `deprecated_by: ${data.deprecated_by ?? 'null'}`,
+    '---',
+    '',
+    `# ${title}`,
+    '',
+    body,
+    '',
+    '## Trigger quotes',
+    ...(data.quotes || []).map((q) => `- "${q}"`),
+    ''
+  ].join('\n');
+}
+
+function parseDecisionFile(content) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return null;
+  const body = content.slice(fmMatch[0].length).trim();
+  const out = { body };
+  let inQuotes = false;
+  let quotes = [];
+  for (const rawLine of fmMatch[1].split('\n')) {
+    if (rawLine.startsWith('quotes:')) {
+      const after = rawLine.slice('quotes:'.length).trim();
+      if (after === '[]') { inQuotes = false; out.quotes = []; continue; }
+      if (after === '') { inQuotes = true; quotes = []; continue; }
+      inQuotes = true; quotes = []; continue;
+    }
+    if (inQuotes) {
+      const m = rawLine.match(/^\s+-\s+'?([\s\S]*?)'?\s*$/);
+      if (m) {
+        quotes.push(m[1].replace(/''/g, "'"));
+        continue;
+      } else {
+        inQuotes = false;
+        out.quotes = quotes;
+      }
+    }
+    const fieldMatch = rawLine.match(/^([a-z_]+):\s*(.*)$/);
+    if (fieldMatch) {
+      const [, key, rawValue] = fieldMatch;
+      let value = rawValue.trim();
+      if (value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1).replace(/''/g, "'");
+      if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+      if (value === 'null') value = null;
+      else if (/^\d+$/.test(value)) value = Number(value);
+      out[key] = value;
+    }
+  }
+  if (inQuotes) out.quotes = quotes;
+  if (!out.quotes) out.quotes = [];
+  return out;
+}
+
+function readDecision(identity, slug) {
+  const filePath = decisionPath(identity, slug);
+  if (!fs.existsSync(filePath)) return null;
+  return parseDecisionFile(fs.readFileSync(filePath, 'utf8'));
+}
+
+/**
+ * Atomically promote a proposal to a decision.
+ *
+ * SQLite transaction wraps:
+ *   1. INSERT INTO decisions_fts
+ *   2. write decisions/{slug}.md (atomic via tmp+rename)
+ *   3. delete proposals/{slug}.md
+ *
+ * Returns the decision data on success. Throws on transaction failure.
+ */
+function promoteProposal({ identity, proposal: proposalData }) {
+  const now = new Date().toISOString();
+  const body = String(proposalData.proposal || '').slice(0, MAX_BODY_CHARS);
+  const category = inferCategory(proposalData.signal_type, body);
+  const decision = {
+    slug: proposalData.slug,
+    signal_type: proposalData.signal_type,
+    promoted_at: now,
+    last_reinforced: now,
+    reinforcement_count: 0,
+    superseded_by: null,
+    category,
+    source_agent: proposalData.source_agent || 'unknown',
+    quotes: proposalData.quotes || [],
+    body,
+    title: proposalData.proposal,
+    deprecated_by: null
+  };
+
+  const decFilePath = decisionPath(identity, decision.slug);
+  const decTmpPath = `${decFilePath}.tmp`;
+  const propPath = proposalPath(identity, decision.slug);
+
+  const db = openIndexDb();
+  try {
+    const txn = db.transaction(() => {
+      db.prepare(`
+        INSERT INTO decisions_fts (identity, slug, signal_type, category, body, last_reinforced)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(identity, decision.slug, decision.signal_type, decision.category, decision.body, decision.last_reinforced);
+
+      fs.writeFileSync(decTmpPath, serializeDecision(decision), 'utf8');
+      fs.renameSync(decTmpPath, decFilePath);
+
+      if (fs.existsSync(propPath)) {
+        fs.unlinkSync(propPath);
+      }
+    });
+    txn();
+  } catch (err) {
+    // Cleanup tmp on rollback
+    try { if (fs.existsSync(decTmpPath)) fs.unlinkSync(decTmpPath); } catch { /* ignore */ }
+    throw err;
+  } finally {
+    db.close();
+  }
+
+  // Post-commit: regenerate MEMORY.md index (best-effort, outside transaction
+  // since MEMORY.md is regenerable from decisions/ — markdown source-of-truth).
+  try {
+    const { regenerateIndex } = require('./index-md');
+    regenerateIndex(identity);
+  } catch { /* index regen failure is non-fatal */ }
+
+  return decision;
+}
+
+/**
+ * Soft-delete a decision or proposal to history/.
+ * Returns { mode: 'decision'|'proposal'|'noop', archivedPath: string|null }.
+ */
+function forgetEntry(identity, slug) {
+  const decFilePath = decisionPath(identity, slug);
+  const propFilePath = proposalPath(identity, slug);
+  const now = new Date().toISOString();
+
+  if (fs.existsSync(decFilePath)) {
+    const archived = historyPath(identity, slug, now);
+    const content = fs.readFileSync(decFilePath, 'utf8');
+    fs.writeFileSync(archived, content, 'utf8');
+
+    const db = openIndexDb();
+    try {
+      db.transaction(() => {
+        db.prepare('DELETE FROM decisions_fts WHERE identity = ? AND slug = ?').run(identity, slug);
+        fs.unlinkSync(decFilePath);
+      })();
+    } finally {
+      db.close();
+    }
+    // Post-commit: regenerate MEMORY.md index after decision removed
+    try {
+      const { regenerateIndex } = require('./index-md');
+      regenerateIndex(identity);
+    } catch { /* index regen failure is non-fatal */ }
+    return { mode: 'decision', archivedPath: archived };
+  }
+  if (fs.existsSync(propFilePath)) {
+    const archived = historyPath(identity, slug, now);
+    fs.copyFileSync(propFilePath, archived);
+    deleteProposal(identity, slug);
+    return { mode: 'proposal', archivedPath: archived };
+  }
+  return { mode: 'noop', archivedPath: null };
+}
+
+module.exports = {
+  promoteProposal,
+  forgetEntry,
+  readDecision,
+  decisionPath,
+  historyPath,
+  serializeDecision,
+  parseDecisionFile,
+  inferCategory,
+  CATEGORY_KEYWORDS,
+  MAX_BODY_CHARS,
+  SCHEMA_VERSION,
+  VALID_CATEGORIES
+};

package/src/operator-memory/identity.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * operator-memory — identity resolution (Phase 1, v1.12.0).
+ *
+ * Pure helpers, no I/O side effects. Storage tree creation lives in storage.js.
+ *
+ * Resolution order (PMD-05 + architecture-operator-memory.md § Phase 1):
+ *   1. process.env.AIOSON_OPERATOR_ID — if set + valid → use literal.
+ *   2. git config --get user.email — sha256[0..16]; salt-rehash if reserved-prefix collision.
+ *   3. fallback to reserved identity `_anonymous` with telemetry warning.
+ */
+
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const HASH_PREFIX_BYTES = 16;
+const OVERRIDE_REGEX = /^[a-z0-9][a-z0-9-]{2,31}$/;
+const SALT_V1 = 'aioson-v1';
+const RESERVED_PREFIXES = ['_', 'aioson-'];
+
+function isReservedPrefix(value) {
+  return RESERVED_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
+
+function validateOverride(value) {
+  if (typeof value !== 'string' || value === '') {
+    return { ok: false, reason: 'empty' };
+  }
+  // Check reserved-prefix BEFORE regex so the rejection reason matches the user's
+  // mental model: `_admin` is "reserved-prefix" (even though regex would also reject
+  // a leading `_`); `aioson-system` is "reserved-prefix" (regex passes but PMD-05 bans it).
+  if (isReservedPrefix(value)) {
+    return { ok: false, reason: 'reserved-prefix' };
+  }
+  if (!OVERRIDE_REGEX.test(value)) {
+    return { ok: false, reason: 'regex' };
+  }
+  return { ok: true };
+}
+
+function hashEmail(email) {
+  const normalized = String(email || '').trim();
+  if (normalized === '') return null;
+  const raw = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, HASH_PREFIX_BYTES);
+  if (isReservedPrefix(raw)) {
+    return crypto.createHash('sha256').update(`${SALT_V1}:${normalized}`).digest('hex').slice(0, HASH_PREFIX_BYTES);
+  }
+  return raw;
+}
+
+function readGitEmail() {
+  try {
+    const out = execFileSync('git', ['config', '--get', 'user.email'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+      timeout: 2000
+    });
+    return out.trim();
+  } catch {
+    return '';
+  }
+}
+
+function resolveIdentity({ env = process.env, emailReader = readGitEmail } = {}) {
+  const override = env.AIOSON_OPERATOR_ID;
+  if (override !== undefined && override !== null && override !== '') {
+    const validation = validateOverride(override);
+    if (validation.ok) {
+      return {
+        identity: override,
+        source: 'override',
+        warning: null
+      };
+    }
+    const warning = `AIOSON_OPERATOR_ID '${override}' invalid (reason: ${validation.reason}; expected ${OVERRIDE_REGEX}, no reserved prefix). Falling back to git-email-hash.`;
+    const hashFallback = hashEmail(emailReader());
+    if (hashFallback) {
+      return { identity: hashFallback, source: 'email-hash', warning };
+    }
+    return {
+      identity: '_anonymous',
+      source: 'anonymous-fallback',
+      warning: `${warning} Git email unavailable; using '_anonymous' bucket.`
+    };
+  }
+
+  const email = emailReader();
+  const hash = hashEmail(email);
+  if (hash) {
+    return { identity: hash, source: 'email-hash', warning: null };
+  }
+  return {
+    identity: '_anonymous',
+    source: 'anonymous-fallback',
+    warning: 'git config user.email unavailable; using `_anonymous` bucket. Set git config user.email or AIOSON_OPERATOR_ID to scope memory.'
+  };
+}
+
+module.exports = {
+  resolveIdentity,
+  validateOverride,
+  hashEmail,
+  readGitEmail,
+  HASH_PREFIX_BYTES,
+  OVERRIDE_REGEX,
+  SALT_V1,
+  RESERVED_PREFIXES
+};

package/src/operator-memory/index-md.js

@@ -0,0 +1,170 @@
+'use strict';
+
+/**
+ * operator-memory — MEMORY.md tier-based index reader/writer (Phase 3, v1.14.0).
+ *
+ * Per PMD-AN-02: MEMORY.md = active tier (auto-loaded by preflight directive);
+ * MEMORY-archive.md = archive tier (lazy-loaded only with --include-archived).
+ *
+ * Format (architecture-operator-memory.md § Phase 3):
+ *   ---
+ *   identity_prefix: <first 8 chars of identity>
+ *   decisions_count: N
+ *   archived_count: M
+ *   last_promoted: <ISO>
+ *   schema_version: "1.0"
+ *   ---
+ *
+ *   # Operator Memory — Index
+ *
+ *   ## Active decisions
+ *
+ *   - [Title](decisions/{slug}.md) — {signal_type}, reinforced {date}
+ *   ...
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getStorageRoot } = require('./storage');
+const { readDecision, decisionPath } = require('./decision');
+
+const SCHEMA_VERSION = '1.0';
+
+function indexPath(identity, tier = 'active') {
+  const filename = tier === 'archive' ? 'MEMORY-archive.md' : 'MEMORY.md';
+  return path.join(getStorageRoot(identity), filename);
+}
+
+function listDecisionSlugs(identity) {
+  const root = path.join(getStorageRoot(identity), 'decisions');
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => f.slice(0, -3));
+}
+
+function deriveLineForDecision(decision) {
+  const title = decision.body
+    ? decision.body.slice(0, 80).split('\n')[0].replace(/[#`*\[\]()]/g, '').trim()
+    : decision.slug;
+  const dateOnly = String(decision.last_reinforced || '').slice(0, 10);
+  return `- [${title || decision.slug}](decisions/${decision.slug}.md) — ${decision.signal_type}, reinforced ${dateOnly}`;
+}
+
+function serializeIndex({ identity, decisionsCount, archivedCount, lastPromoted, lines, tier = 'active' }) {
+  const heading = tier === 'archive' ? 'Archived decisions' : 'Active decisions';
+  const frontmatter = [
+    '---',
+    `identity_prefix: ${identity.slice(0, 8)}`,
+    `decisions_count: ${decisionsCount}`,
+    `archived_count: ${archivedCount}`,
+    `last_promoted: ${lastPromoted || 'null'}`,
+    `schema_version: "${SCHEMA_VERSION}"`,
+    '---',
+    ''
+  ].join('\n');
+  const body = [
+    '# Operator Memory — Index',
+    '',
+    `## ${heading}`,
+    '',
+    lines.length === 0 ? '_(empty — no decisions yet)_' : lines.join('\n'),
+    ''
+  ];
+  if (tier === 'active') {
+    body.push('## See also', '');
+    body.push(`- \`MEMORY-archive.md\` — ${archivedCount} archived decisions`);
+    body.push('');
+  }
+  return frontmatter + body.join('\n');
+}
+
+function parseIndexFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const out = {};
+  for (const line of match[1].split('\n')) {
+    const m = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (m) {
+      let v = m[2].trim();
+      if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+      if (/^\d+$/.test(v)) v = Number(v);
+      if (v === 'null') v = null;
+      out[m[1]] = v;
+    }
+  }
+  return out;
+}
+
+function parseIndexLinks(content) {
+  // Match `- [Title](decisions/{slug}.md) — {signal_type}, reinforced {date}`
+  const re = /^- \[(.*?)\]\(decisions\/([a-z0-9-]+)\.md\) — (\w+), reinforced (\S+)/gm;
+  const out = [];
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    out.push({ title: m[1], slug: m[2], signal_type: m[3], last_reinforced: m[4] });
+  }
+  return out;
+}
+
+function loadMemoryIndex(identity, tier = 'active') {
+  const p = indexPath(identity, tier);
+  if (!fs.existsSync(p)) return null;
+  const content = fs.readFileSync(p, 'utf8');
+  return {
+    frontmatter: parseIndexFrontmatter(content),
+    entries: parseIndexLinks(content),
+    raw: content
+  };
+}
+
+/**
+ * Regenerate MEMORY.md from current decisions on disk.
+ *
+ * Phase 3 V1: includes ALL decisions in active tier (no decay yet).
+ * Phase 5 will partition into active vs archive based on category half-life.
+ */
+function regenerateIndex(identity) {
+  const slugs = listDecisionSlugs(identity);
+  const decisions = slugs
+    .map((slug) => {
+      try {
+        const d = readDecision(identity, slug);
+        if (!d) return null;
+        return { slug, ...d };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.last_reinforced || '').localeCompare(String(a.last_reinforced || '')));
+
+  const lines = decisions.map(deriveLineForDecision);
+  const lastPromoted = decisions[0]?.promoted_at || null;
+  const indexContent = serializeIndex({
+    identity,
+    decisionsCount: decisions.length,
+    archivedCount: 0, // Phase 5 will compute from MEMORY-archive.md
+    lastPromoted,
+    lines,
+    tier: 'active'
+  });
+
+  const p = indexPath(identity, 'active');
+  const tmp = `${p}.tmp`;
+  fs.writeFileSync(tmp, indexContent, 'utf8');
+  fs.renameSync(tmp, p);
+  return p;
+}
+
+module.exports = {
+  loadMemoryIndex,
+  regenerateIndex,
+  indexPath,
+  parseIndexFrontmatter,
+  parseIndexLinks,
+  serializeIndex,
+  deriveLineForDecision,
+  listDecisionSlugs,
+  SCHEMA_VERSION
+};

package/src/operator-memory/loader.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * operator-memory — preflight loader + lazy decision matcher (Phase 3, v1.14.0).
+ *
+ * Architecture-operator-memory.md § Phase 3 data flow:
+ *   AIOSON_OPERATOR_MEMORY=true → resolveIdentity → loadMemoryIndex(active)
+ *   → matchDecisions(index, task keywords) → return top-N matched slugs
+ *   → agent lazy-loads decisions/{slug}.md
+ *
+ * V1 match heuristic: substring on title + signal_type tag (AC-P3-10).
+ * V2: FTS5-backed query optimization (deferred).
+ */
+
+const { loadMemoryIndex } = require('./index-md');
+
+const DEFAULT_MAX_MATCHES = 5;
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'of', 'to', 'for', 'in', 'on', 'with', 'is', 'be',
+  'que', 'de', 'em', 'para', 'sem', 'com', 'um', 'uma', 'os', 'as', 'no', 'na'
+]);
+
+function tokenize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w && !STOPWORDS.has(w) && w.length >= 3);
+}
+
+/**
+ * Match decisions by keyword overlap with task description.
+ *
+ * @param {object} memoryIndex — output of loadMemoryIndex(identity, 'active')
+ * @param {string} taskDescription — current task description / user goal
+ * @param {object} options — { maxMatches: number, minOverlap: number }
+ * @returns {Array<{slug: string, title: string, score: number}>}
+ */
+function matchDecisions(memoryIndex, taskDescription, options = {}) {
+  if (!memoryIndex || !memoryIndex.entries || memoryIndex.entries.length === 0) return [];
+  const max = options.maxMatches || DEFAULT_MAX_MATCHES;
+  const minOverlap = options.minOverlap || 1;
+
+  const taskTokens = new Set(tokenize(taskDescription));
+  if (taskTokens.size === 0) return [];
+
+  const scored = memoryIndex.entries.map((entry) => {
+    const entryTokens = new Set(tokenize(`${entry.title} ${entry.signal_type}`));
+    let overlap = 0;
+    for (const t of taskTokens) {
+      if (entryTokens.has(t)) overlap += 1;
+    }
+    return { slug: entry.slug, title: entry.title, signal_type: entry.signal_type, score: overlap };
+  });
+
+  return scored
+    .filter((s) => s.score >= minOverlap)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, max);
+}
+
+/**
+ * Convenience wrapper combining load + match + conflict detection for preflight use.
+ *
+ * @param {string} identity — operator identity hash or override
+ * @param {string} taskDescription — current task / user goal
+ * @param {object} options — { maxMatches, minOverlap, projectRoot, detectConflicts }
+ * @returns {{index, matches, conflicts}} — conflicts is [] when projectRoot absent
+ *   OR when Phase 4 conflict detection is not requested.
+ */
+function preflightLoad(identity, taskDescription, options = {}) {
+  const index = loadMemoryIndex(identity, 'active');
+  if (!index) return { index: null, matches: [], conflicts: [] };
+  const matches = matchDecisions(index, taskDescription, options);
+
+  let conflicts = [];
+  if (options.projectRoot && options.detectConflicts !== false) {
+    try {
+      const { scanProjectRules, detectConflicts, debounceConflicts } = require('./conflict');
+      const { readDecision } = require('./decision');
+      // Resolve full decision data for matched entries so conflict-body checks have content
+      const matchedDecisions = matches
+        .map((m) => {
+          try {
+            const d = readDecision(identity, m.slug);
+            return d ? { slug: m.slug, ...d } : null;
+          } catch { return null; }
+        })
+        .filter(Boolean);
+      const rules = scanProjectRules(options.projectRoot);
+      const detected = detectConflicts(matchedDecisions, rules, options);
+      conflicts = options.skipDebounce ? detected : debounceConflicts(identity, detected, options);
+    } catch { /* conflict detection failure must not crash preflight */ }
+  }
+
+  return { index, matches, conflicts };
+}
+
+module.exports = {
+  preflightLoad,
+  matchDecisions,
+  tokenize,
+  DEFAULT_MAX_MATCHES,
+  STOPWORDS
+};