@mindrian_os/install 1.13.0-beta.11

package/lib/memory/aaak-compress.cjs

@@ -0,0 +1,403 @@
+'use strict';
+
+/**
+ * MindrianOS Plugin -- AAAK Compression (v1.10.1)
+ *
+ * AAAK = Assertion -> Assumption -> Action -> Knowledge
+ *
+ * Compresses a reasoning document (MINTO.md, meeting notes, problem analysis)
+ * into a 4-field cross-session memory record. The AAAK record is small enough
+ * (typically 150-300 tokens) that many of them can load at once for cross-room
+ * recall without blowing the context window.
+ *
+ * This is the canonical compression format for MindrianOS cross-session memory.
+ * Every MINTO.md generated by /mos:reason appends an AAAK footer. Every meeting
+ * filed by /mos:file-meeting optionally gets an AAAK record. The global AAAK
+ * index at ~/MindrianRooms/.aaak-index.db (Phase 82) queries across all records
+ * regardless of which room they live in.
+ *
+ * The AAAK format was introduced by MemPalace (https://mempalace.tech, MIT
+ * licensed, Python + ChromaDB). MindrianOS independently implements the same
+ * format in CJS + SQLite per Decision #8 (Tier 0 fully functional, no
+ * dependencies). We learn the concept, not borrow the code. See
+ * docs/research/MEMPALACE-EVALUATION.md for the architectural comparison.
+ *
+ * Design principles:
+ * - Pure function: input text, output AAAK object. No I/O, no side effects.
+ * - Tier-0 heuristics: works without Brain MCP, embeddings, or any external
+ *   service. Brain enrichment is a future optional enhancement (Phase 82).
+ * - Deterministic: same input -> same output. Unit-testable.
+ * - Markdown-friendly: renderAaakFooter() produces idiomatic markdown that
+ *   round-trips through existing file I/O.
+ * - No em-dashes in output (hard user rule, Decision #17).
+ *
+ * @module lib/memory/aaak-compress
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Maximum token budget (approximate) for a full AAAK record. */
+const MAX_TOKENS_PER_RECORD = 300;
+
+/** Rough chars per token (conservative). */
+const CHARS_PER_TOKEN = 4;
+
+/** Per-field char budgets derived from MAX_TOKENS_PER_RECORD. */
+const FIELD_BUDGETS = {
+  assertion: 250,  // the main claim
+  assumption: 250, // what must be true for the assertion
+  action: 250,     // what we are going to do about it
+  knowledge: 250,  // canonical evidence or provenance
+};
+
+/**
+ * Heuristic cue phrases used for field extraction when the input lacks
+ * explicit AAAK structure. Ordered by specificity (most specific first).
+ */
+const CUES = {
+  assertion: [
+    /^(?:the|our)\s+(?:core\s+)?(?:problem|claim|thesis|assertion|conclusion|finding)\s+is[:\s]/i,
+    /^(?:we\s+(?:claim|argue|believe|assert))/i,
+    /^(?:the\s+governing\s+thought)/i,
+  ],
+  assumption: [
+    /\b(?:assumes?|assuming|assumption|presuppos|predicates?\s+on|depends?\s+on|requires?\s+that|must\s+be\s+true|if\s+.+\s+then)\b/i,
+    /^(?:this\s+(?:only\s+)?(?:works|holds|applies)\s+if)/i,
+  ],
+  action: [
+    /^(?:we\s+(?:will|should|must|are\s+going\s+to|plan\s+to|need\s+to))\b/i,
+    /^(?:next\s+(?:step|action)|action\s+item|decision)[:\s]/i,
+    /^(?:build|ship|write|add|remove|refactor|deploy|test|document|investigate)\b/i,
+  ],
+  knowledge: [
+    /\b(?:canonical\s+evidence|source:|per\s+the\s+|according\s+to|as\s+observed\s+in|witnessed\s+in|documented\s+in|see\s+\[)/i,
+    /\b(?:van\s+clief|simon|rittel|tetlock|hughes|ashby|knight|christensen)\b/i,
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compress a reasoning document into an AAAK record.
+ *
+ * @param {string} text - The source text (typically a MINTO.md body)
+ * @param {object} [opts] - Optional compression parameters
+ * @param {string} [opts.section] - Section name for contextual hints
+ * @param {string} [opts.room] - Room name for contextual hints
+ * @param {number} [opts.maxTokens=300] - Approximate token budget
+ * @returns {{assertion: string, assumption: string, action: string, knowledge: string, metadata: object}}
+ */
+function compressToAaak(text, opts = {}) {
+  if (typeof text !== 'string') {
+    throw new TypeError('compressToAaak: text must be a string');
+  }
+  const section = opts.section || 'unknown';
+  const room = opts.room || 'unknown';
+  const maxTokens = opts.maxTokens || MAX_TOKENS_PER_RECORD;
+
+  const body = stripFrontmatter(text);
+  const sentences = splitSentences(body);
+
+  const bucketed = bucketSentences(sentences);
+  const assertion = pickAssertion(bucketed, sentences, section, room);
+  const assumption = pickAssumption(bucketed, sentences);
+  const action = pickAction(bucketed, sentences);
+  const knowledge = pickKnowledge(bucketed, sentences, section, room);
+
+  const record = {
+    assertion: truncate(cleanField(assertion), FIELD_BUDGETS.assertion),
+    assumption: truncate(cleanField(assumption), FIELD_BUDGETS.assumption),
+    action: truncate(cleanField(action), FIELD_BUDGETS.action),
+    knowledge: truncate(cleanField(knowledge), FIELD_BUDGETS.knowledge),
+    metadata: {
+      source_tokens: Math.ceil(text.length / CHARS_PER_TOKEN),
+      compressed_tokens: null,  // filled below
+      compression_ratio: null,  // filled below
+      section,
+      room,
+      method: 'tier-0-heuristic',
+      format_version: '1.0',
+    },
+  };
+
+  const compressedText = [
+    record.assertion,
+    record.assumption,
+    record.action,
+    record.knowledge,
+  ].join(' ');
+  record.metadata.compressed_tokens = Math.ceil(
+    compressedText.length / CHARS_PER_TOKEN
+  );
+  record.metadata.compression_ratio =
+    record.metadata.source_tokens > 0
+      ? +(
+          record.metadata.source_tokens / record.metadata.compressed_tokens
+        ).toFixed(1)
+      : 0;
+
+  if (record.metadata.compressed_tokens > maxTokens) {
+    // Over budget: trim action + knowledge first (lowest priority fields)
+    record.knowledge = truncate(record.knowledge, Math.floor(FIELD_BUDGETS.knowledge / 2));
+    record.action = truncate(record.action, Math.floor(FIELD_BUDGETS.action / 2));
+  }
+
+  return record;
+}
+
+/**
+ * Render an AAAK record as a Markdown footer block suitable for appending
+ * to a MINTO.md file.
+ *
+ * @param {object} aaak - AAAK record from compressToAaak()
+ * @returns {string} Markdown block
+ */
+function renderAaakFooter(aaak) {
+  if (!aaak || typeof aaak !== 'object') {
+    throw new TypeError('renderAaakFooter: aaak must be an object');
+  }
+  const m = aaak.metadata || {};
+  const lines = [
+    '## AAAK Compressed (for cross-session retrieval)',
+    '',
+    '> [!summary] AAAK Record',
+    '> **Format:** Assertion -> Assumption -> Action -> Knowledge',
+    `> **Compression ratio:** ${m.compression_ratio || '?'}x`,
+    `> **Tokens:** ${m.compressed_tokens || '?'} compressed from ${m.source_tokens || '?'} source`,
+    `> **Method:** ${m.method || 'tier-0-heuristic'}`,
+    '',
+    '### Assertion',
+    aaak.assertion || '*(no assertion extracted)*',
+    '',
+    '### Assumption',
+    aaak.assumption || '*(no assumption extracted)*',
+    '',
+    '### Action',
+    aaak.action || '*(no action extracted)*',
+    '',
+    '### Knowledge',
+    aaak.knowledge || '*(no knowledge extracted)*',
+    '',
+    '<!-- aaak-end -->',
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * Parse an AAAK footer block back into a structured record. Inverse of
+ * renderAaakFooter(). Used by the (future) AAAK index builder to extract
+ * records from existing MINTO.md files without recompressing.
+ *
+ * @param {string} markdown - MINTO.md body or full file
+ * @returns {object|null} AAAK record or null if no footer found
+ */
+function parseAaakFooter(markdown) {
+  if (typeof markdown !== 'string') {
+    return null;
+  }
+  const footerStart = markdown.indexOf('## AAAK Compressed');
+  if (footerStart === -1) return null;
+  const footerEnd = markdown.indexOf('<!-- aaak-end -->', footerStart);
+  const footer =
+    footerEnd === -1 ? markdown.slice(footerStart) : markdown.slice(footerStart, footerEnd);
+
+  const fields = {
+    assertion: extractSection(footer, '### Assertion'),
+    assumption: extractSection(footer, '### Assumption'),
+    action: extractSection(footer, '### Action'),
+    knowledge: extractSection(footer, '### Knowledge'),
+  };
+
+  const ratioMatch = footer.match(/\*\*Compression ratio:\*\*\s+(\d+(?:\.\d+)?)x/);
+  const tokMatch = footer.match(
+    /\*\*Tokens:\*\*\s+(\d+)\s+compressed\s+from\s+(\d+)\s+source/
+  );
+
+  return {
+    ...fields,
+    metadata: {
+      compression_ratio: ratioMatch ? parseFloat(ratioMatch[1]) : null,
+      compressed_tokens: tokMatch ? parseInt(tokMatch[1], 10) : null,
+      source_tokens: tokMatch ? parseInt(tokMatch[2], 10) : null,
+      format_version: '1.0',
+    },
+  };
+}
+
+/**
+ * Append or replace an AAAK footer in an existing MINTO.md body.
+ * Idempotent: if a footer already exists, it is replaced, not duplicated.
+ *
+ * @param {string} mintoBody - Full MINTO.md text
+ * @param {object} aaak - AAAK record to render as footer
+ * @returns {string} Updated MINTO.md text
+ */
+function attachAaakFooter(mintoBody, aaak) {
+  const footer = renderAaakFooter(aaak);
+  const existing = mintoBody.indexOf('## AAAK Compressed');
+  if (existing === -1) {
+    // Append at the end, before any trailing filing signature
+    const sigMatch = mintoBody.match(/\n\*Filed by MindrianOS[^\n]*\n?$/);
+    if (sigMatch) {
+      const sigStart = sigMatch.index;
+      return (
+        mintoBody.slice(0, sigStart).replace(/\s*$/, '') +
+        '\n\n' +
+        footer +
+        '\n' +
+        mintoBody.slice(sigStart)
+      );
+    }
+    return mintoBody.replace(/\s*$/, '') + '\n\n' + footer + '\n';
+  }
+  // Replace existing footer
+  const endMarker = mintoBody.indexOf('<!-- aaak-end -->', existing);
+  if (endMarker === -1) {
+    // No end marker -- replace everything from '## AAAK Compressed' to EOF
+    return mintoBody.slice(0, existing).replace(/\s*$/, '') + '\n\n' + footer + '\n';
+  }
+  const after = mintoBody.slice(endMarker + '<!-- aaak-end -->'.length);
+  return (
+    mintoBody.slice(0, existing).replace(/\s*$/, '') +
+    '\n\n' +
+    footer +
+    after
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function stripFrontmatter(text) {
+  if (!text.startsWith('---')) return text;
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) return text;
+  return text.slice(end + 4);
+}
+
+function splitSentences(body) {
+  // Strip markdown structural markers, callout prefixes, and headings noise
+  const cleaned = body
+    .replace(/^#{1,6}\s+.*$/gm, '')
+    .replace(/^>\s*\[!\w+\][^\n]*$/gm, '')
+    .replace(/^>\s?/gm, '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g, '$1');
+  // Split on sentence terminators (keep the terminator)
+  const raw = cleaned
+    .split(/(?<=[.!?])\s+(?=[A-Z*_\[(`'"-])/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 15);
+  return raw;
+}
+
+function bucketSentences(sentences) {
+  const buckets = {
+    assertion: [],
+    assumption: [],
+    action: [],
+    knowledge: [],
+    other: [],
+  };
+  for (const s of sentences) {
+    let matched = false;
+    for (const field of ['assertion', 'assumption', 'action', 'knowledge']) {
+      for (const rx of CUES[field]) {
+        if (rx.test(s)) {
+          buckets[field].push(s);
+          matched = true;
+          break;
+        }
+      }
+      if (matched) break;
+    }
+    if (!matched) buckets.other.push(s);
+  }
+  return buckets;
+}
+
+function pickAssertion(buckets, sentences, section, room) {
+  if (buckets.assertion.length > 0) return buckets.assertion[0];
+  // Fall back to the first substantive non-other sentence
+  const first = sentences.find((s) => s.length > 30 && !/^\s*\*/.test(s));
+  if (first) return first;
+  return `Reasoning for section ${section} in room ${room}.`;
+}
+
+function pickAssumption(buckets, sentences) {
+  if (buckets.assumption.length > 0) return buckets.assumption[0];
+  // Look for conditional/hedge language in any sentence
+  const conditional = sentences.find((s) =>
+    /\b(?:if|unless|provided|assuming|when)\b/i.test(s)
+  );
+  if (conditional) return conditional;
+  return 'Implicit: no explicit assumption surfaced in source.';
+}
+
+function pickAction(buckets, sentences) {
+  if (buckets.action.length > 0) return buckets.action[0];
+  // Look for imperatives or "next" language
+  const next = sentences.find((s) =>
+    /\b(?:next|then|upcoming|todo|open|gap|missing)\b/i.test(s)
+  );
+  if (next) return next;
+  return 'No explicit action surfaced. Run /mos:reason to propose one.';
+}
+
+function pickKnowledge(buckets, sentences, section, room) {
+  if (buckets.knowledge.length > 0) return buckets.knowledge[0];
+  // Pick the longest substantive sentence as fallback -- it often contains
+  // the most factual content
+  const longest = sentences
+    .filter((s) => s.length > 40)
+    .sort((a, b) => b.length - a.length)[0];
+  if (longest) return longest;
+  return `Canonical source: ${room}/${section}`;
+}
+
+function cleanField(s) {
+  if (!s) return '';
+  return s
+    .replace(/\s+/g, ' ')
+    .replace(/\u2014/g, '-')  // em-dash to hyphen (hard rule)
+    .replace(/^\s*[-*]\s*/, '')
+    .trim();
+}
+
+function truncate(s, maxChars) {
+  if (!s) return s;
+  if (s.length <= maxChars) return s;
+  return s.slice(0, maxChars - 3) + '...';
+}
+
+function extractSection(text, heading) {
+  const start = text.indexOf(heading);
+  if (start === -1) return '';
+  const afterHeading = text.slice(start + heading.length);
+  const nextHeading = afterHeading.search(/\n###\s|\n<!--\s*aaak-end/);
+  const body = nextHeading === -1 ? afterHeading : afterHeading.slice(0, nextHeading);
+  return body.trim().replace(/\s+/g, ' ');
+}
+
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  compressToAaak,
+  renderAaakFooter,
+  parseAaakFooter,
+  attachAaakFooter,
+  // Exported for tests
+  _internals: {
+    stripFrontmatter,
+    splitSentences,
+    bucketSentences,
+    cleanField,
+    truncate,
+    extractSection,
+  },
+};

package/lib/memory/aaak-compress.test.cjs

@@ -0,0 +1,288 @@
+'use strict';
+
+/**
+ * Unit tests for lib/memory/aaak-compress.cjs
+ *
+ * Run: node lib/memory/aaak-compress.test.cjs
+ */
+
+const assert = require('node:assert/strict');
+const {
+  compressToAaak,
+  renderAaakFooter,
+  parseAaakFooter,
+  attachAaakFooter,
+  _internals,
+} = require('./aaak-compress.cjs');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    process.stdout.write('  ok  ' + name + '\n');
+    passed++;
+  } catch (err) {
+    process.stdout.write('  FAIL  ' + name + '\n');
+    process.stdout.write('        ' + (err.message || err) + '\n');
+    failed++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const SAMPLE_MINTO = `---
+type: section-minto
+section: problem-definition
+created: 2026-04-13
+room: mindrianos-product
+---
+
+# Problem Definition -- Minto Reasoning
+
+> [!abstract] Governing Thought
+> The core problem is that MindrianOS does not activate for new users without Jonathan physically present. The Dror Barak session is the canonical evidence that the installation flow requires verbal coaching to reach a filed artifact.
+
+## Argument Structure
+
+> [!info] Pyramid Logic
+> This section argues that the activation gap is a structural invariant problem, not a documentation problem.
+
+## Key Claims
+
+### Claim 1: Dror activation required Jonathan
+The session only succeeded because Jonathan was sitting next to Dror. This assumes that a stranger cannot replicate the activation without live guidance. We will build a session-start hook that enforces a conversion event on every state transition.
+
+### Claim 2: Patches have failed
+Each patch addressed a specific symptom but not the structural invariant. This only holds if the user does not work around the patch. Next action: write a structural invariant that protects future state transitions by default.
+
+## Source Artifacts
+
+- [[dror-barak-session|Dror Barak Session Notes]]
+`;
+
+const SAMPLE_MINTO_NO_AAAK_STRUCTURE = `# Random Notes
+
+Some random content without clear MINTO structure.
+We did a thing. It worked.
+Next time we should do more.
+The end.
+`;
+
+// ---------------------------------------------------------------------------
+// compressToAaak()
+// ---------------------------------------------------------------------------
+
+test('compressToAaak returns all 4 fields + metadata', () => {
+  const result = compressToAaak(SAMPLE_MINTO, {
+    section: 'problem-definition',
+    room: 'mindrianos-product',
+  });
+  assert.ok(result.assertion, 'assertion should be non-empty');
+  assert.ok(result.assumption, 'assumption should be non-empty');
+  assert.ok(result.action, 'action should be non-empty');
+  assert.ok(result.knowledge, 'knowledge should be non-empty');
+  assert.ok(result.metadata, 'metadata should exist');
+  assert.equal(result.metadata.section, 'problem-definition');
+  assert.equal(result.metadata.room, 'mindrianos-product');
+  assert.equal(result.metadata.format_version, '1.0');
+});
+
+test('compressToAaak extracts assertion from governing thought', () => {
+  const result = compressToAaak(SAMPLE_MINTO);
+  assert.match(
+    result.assertion,
+    /activat|MindrianOS|Jonathan|Dror/i,
+    'assertion should reference the core problem'
+  );
+});
+
+test('compressToAaak extracts action from imperative sentences', () => {
+  const result = compressToAaak(SAMPLE_MINTO);
+  assert.match(
+    result.action,
+    /(build|write|ship|next)/i,
+    'action should use imperative or next-action language'
+  );
+});
+
+test('compressToAaak computes compression ratio >= 1', () => {
+  const result = compressToAaak(SAMPLE_MINTO);
+  assert.ok(
+    result.metadata.compression_ratio >= 1,
+    `compression_ratio should be >= 1, got ${result.metadata.compression_ratio}`
+  );
+});
+
+test('compressToAaak respects maxTokens budget', () => {
+  const result = compressToAaak(SAMPLE_MINTO, { maxTokens: 100 });
+  assert.ok(
+    result.metadata.compressed_tokens <= 150,
+    `over-budget input should be trimmed, got ${result.metadata.compressed_tokens}`
+  );
+});
+
+test('compressToAaak handles degenerate input without crashing', () => {
+  const result = compressToAaak(SAMPLE_MINTO_NO_AAAK_STRUCTURE, {
+    section: 'unknown',
+    room: 'unknown',
+  });
+  assert.ok(result.assertion);
+  assert.ok(result.assumption);
+  assert.ok(result.action);
+  assert.ok(result.knowledge);
+});
+
+test('compressToAaak rejects non-string input', () => {
+  assert.throws(() => compressToAaak(42), /text must be a string/);
+  assert.throws(() => compressToAaak(null), /text must be a string/);
+});
+
+test('compressToAaak output has no em-dashes (hard rule)', () => {
+  const result = compressToAaak(SAMPLE_MINTO);
+  const combined = [
+    result.assertion,
+    result.assumption,
+    result.action,
+    result.knowledge,
+  ].join(' ');
+  assert.equal(
+    combined.indexOf('\u2014'),
+    -1,
+    'AAAK output must contain zero em-dashes'
+  );
+});
+
+// ---------------------------------------------------------------------------
+// renderAaakFooter()
+// ---------------------------------------------------------------------------
+
+test('renderAaakFooter produces well-formed markdown', () => {
+  const aaak = compressToAaak(SAMPLE_MINTO);
+  const md = renderAaakFooter(aaak);
+  assert.match(md, /^## AAAK Compressed/m, 'must have AAAK heading');
+  assert.match(md, /^### Assertion$/m, 'must have Assertion subsection');
+  assert.match(md, /^### Assumption$/m, 'must have Assumption subsection');
+  assert.match(md, /^### Action$/m, 'must have Action subsection');
+  assert.match(md, /^### Knowledge$/m, 'must have Knowledge subsection');
+  assert.match(md, /<!-- aaak-end -->/, 'must have end marker');
+});
+
+test('renderAaakFooter includes metadata', () => {
+  const aaak = compressToAaak(SAMPLE_MINTO);
+  const md = renderAaakFooter(aaak);
+  assert.match(md, /Compression ratio:/);
+  assert.match(md, /Tokens:/);
+  assert.match(md, /Method:/);
+});
+
+test('renderAaakFooter has no em-dashes', () => {
+  const aaak = compressToAaak(SAMPLE_MINTO);
+  const md = renderAaakFooter(aaak);
+  assert.equal(md.indexOf('\u2014'), -1);
+});
+
+test('renderAaakFooter rejects invalid input', () => {
+  assert.throws(() => renderAaakFooter(null), /aaak must be an object/);
+  assert.throws(() => renderAaakFooter('string'), /aaak must be an object/);
+});
+
+// ---------------------------------------------------------------------------
+// parseAaakFooter()
+// ---------------------------------------------------------------------------
+
+test('parseAaakFooter round-trips a rendered footer', () => {
+  const original = compressToAaak(SAMPLE_MINTO);
+  const md = renderAaakFooter(original);
+  const parsed = parseAaakFooter(md);
+
+  assert.ok(parsed, 'parse should succeed');
+  // Round-trip: assertion text should survive (modulo whitespace normalization)
+  assert.match(
+    parsed.assertion,
+    new RegExp(original.assertion.slice(0, 30).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+  );
+  assert.equal(
+    parsed.metadata.compression_ratio,
+    original.metadata.compression_ratio
+  );
+});
+
+test('parseAaakFooter returns null when no footer present', () => {
+  assert.equal(parseAaakFooter('# Random document\n\nno aaak here'), null);
+  assert.equal(parseAaakFooter(null), null);
+  assert.equal(parseAaakFooter(42), null);
+});
+
+// ---------------------------------------------------------------------------
+// attachAaakFooter()
+// ---------------------------------------------------------------------------
+
+test('attachAaakFooter appends to MINTO without existing footer', () => {
+  const aaak = compressToAaak(SAMPLE_MINTO);
+  const updated = attachAaakFooter(SAMPLE_MINTO, aaak);
+  assert.match(updated, /## AAAK Compressed/);
+  assert.match(updated, /<!-- aaak-end -->/);
+  // Original content must still be present
+  assert.match(updated, /Problem Definition -- Minto Reasoning/);
+  assert.match(updated, /Key Claims/);
+});
+
+test('attachAaakFooter is idempotent (replace, not duplicate)', () => {
+  const aaak = compressToAaak(SAMPLE_MINTO);
+  const once = attachAaakFooter(SAMPLE_MINTO, aaak);
+  const twice = attachAaakFooter(once, aaak);
+  // Count occurrences of the AAAK heading
+  const matches = twice.match(/## AAAK Compressed/g) || [];
+  assert.equal(matches.length, 1, 'must have exactly one AAAK footer after second attach');
+});
+
+test('attachAaakFooter preserves filing signature trailer', () => {
+  const withSig =
+    SAMPLE_MINTO + '\n\n---\n*Filed by MindrianOS -- Section MINTO -- 2026-04-13*\n';
+  const aaak = compressToAaak(withSig);
+  const updated = attachAaakFooter(withSig, aaak);
+  assert.match(updated, /\*Filed by MindrianOS/);
+  // Signature should come AFTER the AAAK footer
+  const aaakIdx = updated.indexOf('## AAAK Compressed');
+  const sigIdx = updated.indexOf('*Filed by MindrianOS');
+  assert.ok(aaakIdx < sigIdx, 'AAAK footer must precede filing signature');
+});
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+test('_internals.stripFrontmatter removes YAML block', () => {
+  const withFm = '---\nkey: value\n---\n\nbody text';
+  assert.equal(_internals.stripFrontmatter(withFm).trim(), 'body text');
+  assert.equal(_internals.stripFrontmatter('no frontmatter'), 'no frontmatter');
+});
+
+test('_internals.cleanField strips markdown bullet prefixes', () => {
+  assert.equal(_internals.cleanField('- hello'), 'hello');
+  assert.equal(_internals.cleanField('* world'), 'world');
+  assert.equal(_internals.cleanField('  spaced  '), 'spaced');
+});
+
+test('_internals.cleanField converts em-dashes to hyphens', () => {
+  assert.equal(_internals.cleanField('a \u2014 b'), 'a - b');
+});
+
+test('_internals.truncate adds ellipsis only when over limit', () => {
+  assert.equal(_internals.truncate('short', 100), 'short');
+  assert.equal(_internals.truncate('1234567890', 8), '12345...');
+});
+
+// ---------------------------------------------------------------------------
+
+process.stdout.write('\n');
+process.stdout.write(`${passed} passed, ${failed} failed\n`);
+if (failed > 0) {
+  process.stdout.write('FAIL\n');
+  process.exit(1);
+}
+process.stdout.write('PASS\n');