@kontourai/flow-agents 0.4.0 → 1.0.0

package/kits/knowledge/adapters/flow-runner/index.js

@@ -35,6 +35,12 @@
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { KnowledgeTelemetry } from "./telemetry.js";
+import {
+  defaultEntityExtractor,
+  normalizeName,
+  isExactMatch,
+  isPossibleDuplicate,
+} from "./entity-extractor.js";
 
 // ---------------------------------------------------------------------------
 // Error helpers
@@ -1383,12 +1389,325 @@ export class KnowledgeFlowRunner {
     };
   }
 
+
+  // -------------------------------------------------------------------------
+  // knowledge.compile — entity extraction step (R2)
+  //
+  // Called after compile() to extract person mentions from the compiled record,
+  // resolve/create person cards, and write bidirectional links:
+  //   - Person card → raw + compiled (kind: appears-in)
+  //   - Compiled record → person cards (kind: person)
+  //
+  // EntityExtractor interface (same pattern as SimilarityDetector — R3):
+  //   async (record: Record) => PersonMention[]
+  //   PersonMention: { name: string, role?: string, org?: string }
+  // -------------------------------------------------------------------------
+
+  /**
+   * Extract person entities from a compiled record and its source raws, then
+   * create or update person cards with bidirectional links.
+   *
+   * @param {string} compiledId   - ID of the compiled record to process
+   * @param {object} [options]
+   *   - entityExtractor: fn   — pluggable extractor (default: defaultEntityExtractor)
+   *   - agent: string         — override agent name
+   * @returns {Promise<{
+   *   compiledId: string,
+   *   personCards: Array<{ cardId, name, created, duplicate }>,
+   *   linkCount: number
+   * }>}
+   */
+  async extractEntities(compiledId, options = {}) {
+    const agent = options.agent || this._agent;
+    const extractor = options.entityExtractor || defaultEntityExtractor;
+
+    const compiled = await this._store.get(compiledId);
+    if (!compiled) throw new Error(`extractEntities: compiled record not found: ${compiledId}`);
+
+    // Gather mentions from the compiled record
+    const mentions = await extractor(compiled);
+
+    // Also gather mentions from all source raw records
+    const sourceLinks = (compiled.links || []).filter((l) => l.kind === "source");
+    const seenNames = new Set(mentions.map((m) => normalizeName(m.name)));
+    for (const link of sourceLinks) {
+      const raw = await this._store.get(link.target_id);
+      if (!raw) continue;
+      const rawMentions = await extractor(raw);
+      for (const m of rawMentions) {
+        const norm = normalizeName(m.name);
+        if (!seenNames.has(norm)) {
+          seenNames.add(norm);
+          mentions.push(m);
+        }
+      }
+    }
+
+    const personCardResults = [];
+    const category = compiled.category || "people";
+
+    for (const mention of mentions) {
+      // Resolve or create the person card
+      const result = await resolvePersonCard(this._store, mention, category, agent);
+      const { cardId, created, duplicate } = result;
+
+      // Build link sets for both sides
+      const cardRecord = await this._store.get(cardId);
+      const compiledRecord = await this._store.get(compiledId);
+
+      // Person card → compiled (appears-in) — skip if already linked
+      const cardLinks = cardRecord.links || [];
+      const hasCompiledLink = cardLinks.some(
+        (l) => l.target_id === compiledId && l.kind === "appears-in"
+      );
+      if (!hasCompiledLink) {
+        await this._store.link(
+          cardId,
+          [{ target_id: compiledId, kind: "appears-in" }],
+          { agent, note: `Person appears in compiled record` }
+        );
+      }
+
+      // Person card → each source raw (appears-in) — skip if already linked
+      for (const link of sourceLinks) {
+        const updatedCard = await this._store.get(cardId);
+        const hasRawLink = (updatedCard.links || []).some(
+          (l) => l.target_id === link.target_id && l.kind === "appears-in"
+        );
+        if (!hasRawLink) {
+          await this._store.link(
+            cardId,
+            [{ target_id: link.target_id, kind: "appears-in" }],
+            { agent, note: `Person appears in raw source` }
+          );
+        }
+      }
+
+      // Compiled record → person card (person link) — skip if already linked
+      const compLinks = compiledRecord.links || [];
+      const hasPersonLink = compLinks.some(
+        (l) => l.target_id === cardId && l.kind === "person"
+      );
+      if (!hasPersonLink) {
+        await this._store.link(
+          compiledId,
+          [{ target_id: cardId, kind: "person" }],
+          { agent, note: `Compiled record references person card` }
+        );
+      }
+
+      personCardResults.push({ cardId, name: mention.name, created, duplicate });
+    }
+
+    return {
+      compiledId,
+      personCards: personCardResults,
+      linkCount: personCardResults.length,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // knowledge.merge-person flow (R3 / AC3)
+  //   Merge two person cards via the existing propose→apply/reject gate.
+  //   On apply: union aliases + links → supersede the duplicate (archive).
+  //   On reject: both cards remain byte-identical.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Merge a duplicate person card into a primary card via gated propose/apply.
+   *
+   * On apply:
+   *   1. Primary card body updated with unioned role text.
+   *   2. Aliases from the duplicate appended to primary's tags as "alias:Name".
+   *   3. All appears-in links from the duplicate are added to the primary.
+   *   4. The duplicate is superseded (archived) via store.supersede().
+   *
+   * On reject:
+   *   Both cards remain byte-identical (AC3).
+   *
+   * @param {string} primaryId    - ID of the primary person card to keep
+   * @param {string} duplicateId  - ID of the card being merged in
+   * @param {object} [options]
+   *   - decision: "apply"|"reject"  (default "apply")
+   *   - rationale: string           (required for apply)
+   *   - rejectReason: string        (required for reject)
+   *   - agent: string
+   * @returns {Promise<{ primaryId, duplicateId, decision }>}
+   */
+  async mergePerson(primaryId, duplicateId, options = {}) {
+    const agent = options.agent || this._agent;
+    const decision = options.decision || "apply";
+
+    const primary = await this._store.get(primaryId);
+    if (!primary) throw new Error(`mergePerson: primary card not found: ${primaryId}`);
+    if (primary.type !== "person") throw new Error(`mergePerson: primaryId must be a person record`);
+
+    const duplicate = await this._store.get(duplicateId);
+    if (!duplicate) throw new Error(`mergePerson: duplicate card not found: ${duplicateId}`);
+    if (duplicate.type !== "person") throw new Error(`mergePerson: duplicateId must be a person record`);
+
+    // propose: duplicate proposes a change to primary
+    await this._store.propose(primaryId, duplicateId, {
+      agent,
+      proposal: `Merge duplicate person card "${duplicate.title}" into "${primary.title}"`,
+    });
+
+    if (decision === "apply") {
+      if (!options.rationale || !options.rationale.trim()) {
+        throw new Error("mergePerson: options.rationale is required when decision=apply");
+      }
+
+      // Compute merged body: union role text
+      const mergedBodyLines = [];
+      if (primary.body && primary.body.trim()) mergedBodyLines.push(primary.body.trim());
+      if (duplicate.body && duplicate.body.trim() && duplicate.body.trim() !== primary.body.trim()) {
+        mergedBodyLines.push(duplicate.body.trim());
+      }
+      const mergedBody = mergedBodyLines.join("\n") || primary.title;
+
+      // Apply: update primary body
+      await this._store.apply(primaryId, duplicateId, {
+        agent,
+        new_body: mergedBody,
+        rationale: options.rationale,
+      });
+
+      // Add duplicate title as alias on primary
+      const primaryAfterApply = await this._store.get(primaryId);
+      const existingTags = primaryAfterApply.tags || [];
+      const aliasTag = `alias:${duplicate.title}`;
+      if (!existingTags.includes(aliasTag)) {
+        await this._store.update(primaryId, { tags: [...existingTags, aliasTag] }, {
+          agent,
+          note: `Added alias from merged duplicate: ${duplicate.title}`,
+        });
+      }
+
+      // Union appears-in links from duplicate to primary
+      const dupLinks = (duplicate.links || []).filter((l) => l.kind === "appears-in");
+      const primaryLinks = await this._store.getLinks(primaryId);
+      for (const link of dupLinks) {
+        const hasLink = primaryLinks.forward.some(
+          (l) => l.target_id === link.target_id && l.kind === "appears-in"
+        );
+        if (!hasLink) {
+          await this._store.link(primaryId, [{ target_id: link.target_id, kind: "appears-in" }], {
+            agent,
+            note: `Unioned from merged duplicate ${duplicateId}`,
+          });
+        }
+      }
+
+      // Supersede the duplicate (archives it — supersede-not-delete invariant)
+      await this._store.supersede(primaryId, [duplicateId], {
+        agent,
+        rationale: options.rationale,
+        note: `Merged duplicate person card into ${primaryId}`,
+      });
+    } else if (decision === "reject") {
+      if (!options.rejectReason || !options.rejectReason.trim()) {
+        throw new Error("mergePerson: options.rejectReason is required when decision=reject");
+      }
+      // Reject: both cards remain byte-identical
+      await this._store.reject(primaryId, duplicateId, {
+        agent,
+        reason: options.rejectReason,
+      });
+    } else {
+      throw new Error(`mergePerson: decision must be "apply" or "reject"; got: ${decision}`);
+    }
+
+    return { primaryId, duplicateId, decision };
+  }
+
 }
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolve or create a person card for a given mention.
+ *
+ * Resolution rules (R3):
+ *  1. Exact normalised-name match (or alias match) → update existing card.
+ *  2. Possible duplicate (same surname + initial) → create new card + related
+ *     link of kind "related" with a possible-duplicate tag.
+ *  3. No match → create new card.
+ *
+ * @param {object} store       - KnowledgeStoreAdapter
+ * @param {object} mention     - { name, role? }
+ * @param {string} category    - category for new card
+ * @param {string} agent       - agent name
+ * @returns {Promise<{ cardId: string, created: boolean, duplicate: boolean }>}
+ */
+async function resolvePersonCard(store, mention, category, agent) {
+  const existing = await store.listByType("person");
+
+  // 1. Exact match (name or alias)
+  for (const card of existing) {
+    if (isExactMatch(card.title, mention.name)) {
+      return { cardId: card.id, created: false, duplicate: false };
+    }
+    // Check aliases tag: "alias:Some Name"
+    const aliases = (card.tags || [])
+      .filter((t) => t.startsWith("alias:"))
+      .map((t) => t.slice("alias:".length));
+    for (const alias of aliases) {
+      if (isExactMatch(alias, mention.name)) {
+        return { cardId: card.id, created: false, duplicate: false };
+      }
+    }
+  }
+
+  // 2. Possible duplicate check
+  let possibleDupId = null;
+  for (const card of existing) {
+    if (isPossibleDuplicate(mention.name, card.title)) {
+      possibleDupId = card.id;
+      break;
+    }
+    const aliases = (card.tags || [])
+      .filter((t) => t.startsWith("alias:"))
+      .map((t) => t.slice("alias:".length));
+    for (const alias of aliases) {
+      if (isPossibleDuplicate(mention.name, alias)) {
+        possibleDupId = card.id;
+        break;
+      }
+    }
+    if (possibleDupId) break;
+  }
+
+  // Build body: role/org as structured prose
+  const bodyLines = [];
+  if (mention.role) {
+    bodyLines.push(`**Role/Org:** ${mention.role}`);
+  }
+  const body = bodyLines.length > 0 ? bodyLines.join("\n") : mention.name;
+
+  // Create new person card
+  const cardId = await store.create({
+    type: "person",
+    title: mention.name,
+    body,
+    category,
+    tags: [],
+    provenance: { agent, note: `Auto-created from entity extraction` },
+  });
+
+  // If possible duplicate: add related link from new card to existing card
+  if (possibleDupId) {
+    await store.link(
+      cardId,
+      [{ target_id: possibleDupId, kind: "related", label: "possible-duplicate" }],
+      { agent, note: "Possible duplicate — same surname+initial; verify manually" }
+    );
+  }
+
+  return { cardId, created: true, duplicate: possibleDupId !== null };
+}
+
 function mostCommonCategory(records) {
   const counts = {};
   for (const r of records) {
@@ -1467,3 +1786,33 @@ export async function retire(
 }
 
 export default KnowledgeFlowRunner;
+
+/**
+ * Module-level extractEntities: creates an ephemeral runner using the provided store.
+ *
+ * @param {string} compiledId
+ * @param {object} options  (merged into extractEntities options + runner options)
+ */
+export async function extractEntities(
+  compiledId,
+  { store, workspace, agent, sessionId, ...extractOpts } = {}
+) {
+  const runner = new KnowledgeFlowRunner({ store, workspace, agent, sessionId });
+  return runner.extractEntities(compiledId, extractOpts);
+}
+
+/**
+ * Module-level mergePerson: creates an ephemeral runner using the provided store.
+ *
+ * @param {string} primaryId
+ * @param {string} duplicateId
+ * @param {object} options
+ */
+export async function mergePerson(
+  primaryId,
+  duplicateId,
+  { store, workspace, agent, sessionId, ...mergeOpts } = {}
+) {
+  const runner = new KnowledgeFlowRunner({ store, workspace, agent, sessionId });
+  return runner.mergePerson(primaryId, duplicateId, mergeOpts);
+}

package/kits/knowledge/adapters/obsidian-store/README.md

@@ -0,0 +1,141 @@
+# Knowledge Kit — Obsidian Store Adapter
+
+Spike verdict: **RATIFY**
+
+The "file is the record" thesis holds. Each Knowledge Kit record maps to exactly
+one Obsidian-native markdown note. Frontmatter carries the full contract payload;
+the markdown body is human-readable Obsidian rendering. The adapter passes the
+full 48-test contract suite without modifications.
+
+---
+
+## The File-Is-the-Record Thesis
+
+A Knowledge Kit record has a canonical identity (`id`), a structured payload
+(type, category, provenance, links, mutation_log), and a human-facing body.
+The Obsidian store places ALL of this in a single `.md` file:
+
+- YAML frontmatter holds every contract field including `body`.
+- The markdown section below `---` is rendered for Obsidian readability only —
+  it is decorative and not read back on load.
+- The file IS the record. No separate database. No shadow index for content.
+
+This is the core claim of the spike: **a single Obsidian note can faithfully
+represent a Knowledge Kit record** with zero fidelity loss.
+
+---
+
+## File Shape
+
+```
+---
+id: <uuid>
+type: raw | compiled | concept | snapshot
+title: <string>
+category: eng.decisions
+tags: [tag-a, tag-b]
+status: active | implemented | retired
+created_at: <ISO8601>
+updated_at: <ISO8601>
+provenance:
+  agent: <string>
+  session_id: <optional>
+  source_ids: [<optional uuid list>]
+links:
+  - target_id: <uuid>
+    kind: related | source | proposes | supersedes | refines
+    label: <optional>
+mutation_log:
+  - op: update
+    at: <ISO8601>
+    agent: <string>
+    evidence:
+      fields: [title, body]
+body: "The full contract body text stored here for round-trip fidelity."
+---
+
+<!-- Obsidian-readable section below — decorative, not parsed on load -->
+
+> [!note]- Raw Notes          ← raw type: collapsed callout
+> Original capture text here.
+
+## Sources                     ← compiled/concept/snapshot: wikilinks to sources
+
+[[source-slug|Source Note]]
+
+## Related
+
+[[related-slug]]
+```
+
+---
+
+## Storage Layout
+
+```
+<storeRoot>/
+  <category/as/path>/<title-slug>.md     active records
+  archive/<category/as/path>/<slug>.md   superseded records (moved, not deleted)
+  graph-index.json                       link graph (suite §13 requirement)
+  .graph-index.json                      path index (id → {path, archived})
+```
+
+- Category dots map to directory segments: `eng.decisions` → `eng/decisions/`.
+- Title is slugified for the filename: `My Decision` → `my-decision.md`.
+- Filename collisions (same slug, different id) get a suffix: `my-decision-2.md`.
+- When a record is superseded, its file MOVES to `archive/` (supersede-not-delete
+  invariant). The record remains fully queryable via `get(id)`.
+
+---
+
+## Spike Gaps Found
+
+1. **Multi-file wikilink resolution**: Obsidian resolves `[[slug]]` links by
+   filename across the entire vault, regardless of folder. The adapter renders
+   wikilinks using the filename slug for human readability, but the canonical
+   link data (stored as UUIDs in frontmatter) is what the contract uses. If a
+   user clicks a wikilink in Obsidian, it navigates by slug — not by UUID —
+   which may not match if slugs collide across categories.
+
+2. **Vault-level wikilink display**: Obsidian flattens `[[slug]]` resolution.
+   Two records in different categories that happen to share a slug
+   (`eng/api/deploy.md` and `ops/api/deploy.md`) would cause Obsidian link
+   ambiguity. The contract itself is unaffected (UUIDs in frontmatter win),
+   but the human-readable `## Related` section would be ambiguous in Obsidian.
+   Mitigation: use category-prefixed slugs in the Obsidian body rendering.
+
+3. **Frontmatter `body` YAML quoting for complex content**: Bodies containing
+   Obsidian callout syntax (`> [!note]`) or multi-paragraph content serialize
+   correctly via the shared codec's `yamlScalar` quoting, but the result can be
+   a long single-line quoted string in frontmatter. Obsidian displays this fine,
+   but it is less human-editable than a literal block scalar. A future YAML block
+   scalar (`|`) serializer would improve ergonomics.
+
+4. **Obsidian sync conflicts**: If two agents write to the same record
+   concurrently, Obsidian Sync may create conflict copies. The adapter uses no
+   file locking. This is acceptable for a spike but would need attention in
+   production use with live sync.
+
+5. **Archive folder visibility**: The `archive/` subdirectory will appear in the
+   Obsidian vault file explorer. This is intentional (superseded records remain
+   inspectable) but users may want to exclude it via `.obsidianignore` or a
+   dedicated vault folder setting.
+
+---
+
+## Spike Verdict: RATIFY
+
+The adapter proves:
+
+- A single Obsidian note is a sufficient and non-lossy representation of a
+  Knowledge Kit record, including all Addendum A (snapshot/supersede) and
+  Addendum B (status/retire) contract extensions.
+- The category hierarchy maps naturally to Obsidian folder organization.
+- Supersede-not-delete is expressible as an archive move within the vault.
+- Human readability (callouts, Sources/Related wikilink sections) coexists with
+  machine-readable frontmatter without duplication errors.
+- The contract suite (48/48) passes without modification.
+
+**Recommendation**: Proceed with the Obsidian store adapter as a supported adapter
+alongside the default store. Address gap #2 (slug ambiguity) before marking the
+adapter production-ready for multi-category vaults.

package/kits/knowledge/adapters/obsidian-store/demo.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * Knowledge Kit — Obsidian Store Demo
+ *
+ * Generates a small set of realistic sample notes in a temporary vault,
+ * then prints the snapshot note verbatim to demonstrate the file-is-the-record
+ * thesis.
+ *
+ * Run:
+ *   node kits/knowledge/adapters/obsidian-store/demo.js
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const adapterPath = path.join(__dirname, "index.js");
+const { ObsidianKnowledgeStore } = await import(adapterPath);
+
+// ---------------------------------------------------------------------------
+// Setup: ephemeral vault
+// ---------------------------------------------------------------------------
+
+const vaultRoot = fs.mkdtempSync(path.join(os.tmpdir(), "obsidian-demo-"));
+const store = new ObsidianKnowledgeStore({ storeRoot: vaultRoot });
+
+console.log(`\nDemo vault: ${vaultRoot}\n`);
+console.log("─".repeat(70));
+
+// ---------------------------------------------------------------------------
+// 1. Raw capture: meeting transcript
+// ---------------------------------------------------------------------------
+
+const rawId = await store.create({
+  type: "raw",
+  title: "Q2 Planning Meeting — Transcript",
+  body: `Discussed moving deploy pipeline to GitHub Actions.
+Ben: we should retire the Jenkins instance, it's costing us $300/mo.
+Alice: agreed, but we need the secrets migration plan first.
+Action items: Alice to draft secrets migration doc by Friday.`,
+  category: "eng.decisions",
+  tags: ["meeting", "infra", "q2"],
+  provenance: {
+    agent: "demo-agent",
+    session_id: "demo-sess-001",
+    note: "Captured from Zoom transcript",
+  },
+});
+
+console.log(`\n[1/4] Created raw capture: ${rawId}`);
+
+// ---------------------------------------------------------------------------
+// 2. Compiled: distilled from the raw
+// ---------------------------------------------------------------------------
+
+const compiledId = await store.create({
+  type: "compiled",
+  title: "Jenkins Retirement Decision",
+  body: `Team agreed to retire the Jenkins CI instance in Q2.
+Prerequisite: secrets migration plan must be completed first (owner: Alice).
+Cost savings: ~$300/month after retirement.`,
+  category: "eng.decisions",
+  tags: ["infra", "ci", "cost"],
+  links: [{ target_id: rawId, kind: "source" }],
+  provenance: {
+    agent: "demo-agent",
+    source_ids: [rawId],
+    note: "Compiled from Q2 planning meeting transcript",
+  },
+});
+
+console.log(`[2/4] Created compiled note: ${compiledId}`);
+
+// ---------------------------------------------------------------------------
+// 3. Placeholder snapshot (to be superseded)
+// ---------------------------------------------------------------------------
+
+const placeholderSnapshotId = await store.create({
+  type: "snapshot",
+  title: "CI Strategy Snapshot — Draft",
+  body: "Placeholder: CI strategy under discussion. No final decision yet.",
+  category: "eng.decisions",
+  tags: ["ci", "strategy", "draft"],
+  provenance: {
+    agent: "demo-agent",
+    note: "Placeholder snapshot pending planning meeting outcome",
+  },
+});
+
+console.log(`[3/4] Created placeholder snapshot: ${placeholderSnapshotId}`);
+
+// ---------------------------------------------------------------------------
+// 4. Final snapshot that supersedes the placeholder
+// ---------------------------------------------------------------------------
+
+const finalSnapshotId = await store.create({
+  type: "snapshot",
+  title: "CI Strategy Snapshot — Q2 2026",
+  body: `Decision: Migrate from Jenkins to GitHub Actions in Q2 2026.
+
+Key constraints:
+- Secrets migration must complete before Jenkins decommission.
+- Target: Jenkins instance retired by end of June 2026.
+- Owner: Platform team (Alice lead).
+
+Cost impact: -$300/month after retirement.`,
+  category: "eng.decisions",
+  tags: ["ci", "strategy", "q2-2026"],
+  links: [
+    { target_id: compiledId, kind: "source" },
+  ],
+  provenance: {
+    agent: "demo-agent",
+    source_ids: [compiledId],
+    note: "Final Q2 snapshot after planning meeting",
+  },
+});
+
+// Supersede the placeholder
+await store.supersede(finalSnapshotId, [placeholderSnapshotId], {
+  agent: "demo-agent",
+  rationale: "Q2 planning meeting resolved the CI strategy; placeholder superseded by final snapshot.",
+});
+
+console.log(`[4/4] Created final snapshot ${finalSnapshotId} (supersedes ${placeholderSnapshotId})\n`);
+console.log("─".repeat(70));
+
+// ---------------------------------------------------------------------------
+// Print the final snapshot note verbatim
+// ---------------------------------------------------------------------------
+
+// Find the file via the path index
+const pathIndexRaw = fs.readFileSync(path.join(vaultRoot, ".graph-index.json"), "utf8");
+const pathIndex = JSON.parse(pathIndexRaw);
+const snapshotEntry = pathIndex.by_id[finalSnapshotId];
+const snapshotPath = path.join(vaultRoot, snapshotEntry.path);
+
+console.log(`\nFinal snapshot note on disk: ${snapshotPath}\n`);
+console.log("═".repeat(70));
+console.log(fs.readFileSync(snapshotPath, "utf8"));
+console.log("═".repeat(70));
+
+// ---------------------------------------------------------------------------
+// Show the archived placeholder
+// ---------------------------------------------------------------------------
+
+const archivedEntry = pathIndex.by_id[placeholderSnapshotId];
+console.log(`\nSuperseded placeholder archived at: ${archivedEntry.path}`);
+console.log(`(archived: ${archivedEntry.archived})`);
+
+// Confirm it's still queryable
+const archived = await store.get(placeholderSnapshotId);
+console.log(`\nArchived record still queryable via get(): title = "${archived.title}"`);
+console.log(`Mutation log has ${archived.mutation_log.length} entr${archived.mutation_log.length === 1 ? "y" : "ies"}.`);
+const sbEntry = archived.mutation_log.find((e) => e.op === "superseded-by");
+if (sbEntry) {
+  console.log(`  - superseded-by: new_id = ${sbEntry.new_id}`);
+}
+
+// ---------------------------------------------------------------------------
+// Vault structure
+// ---------------------------------------------------------------------------
+
+console.log("\nVault layout:");
+function printTree(dir, prefix = "") {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const isLast = entry === entries[entries.length - 1];
+    console.log(`${prefix}${isLast ? "└── " : "├── "}${entry.name}`);
+    if (entry.isDirectory()) {
+      printTree(path.join(dir, entry.name), prefix + (isLast ? "    " : "│   "));
+    }
+  }
+}
+printTree(vaultRoot);
+
+// Cleanup
+fs.rmSync(vaultRoot, { recursive: true, force: true });
+console.log(`\nDemo vault cleaned up.\n`);