hafez 1.3.0 → 2.0.0

package/dist/vault.d.ts

@@ -25,13 +25,31 @@ export declare function scanVaultDir(dirPath: string): string[];
 /** Where an entity's overflow session-log entries are archived. */
 export declare function archiveLogPath(vaultPath: string, slug: string): string;
 export declare function resolveFilePath(vaultPath: string, slug: string, kind: VaultKind): string;
+/** The file a slug names, or null — entities are resolved before knowledge,
+ * the one resolution order every operation sees. */
+export declare function findVaultFile(vaultPath: string, slug: string): string | null;
+/** Does this slug name a vault file? An invalid slug definitionally doesn't
+ * exist — reference checks (create parent/related, link targets, validate)
+ * must report "does not exist", not crash. validate() in particular exists to
+ * REPORT malformed refs. */
+export declare function vaultFileExists(vaultPath: string, slug: string): boolean;
 export declare function kindFromPath(filePath: string): 'entity' | 'knowledge';
+/** Fields that must always be arrays when present (may be scalar in
+ * hand-edited YAML). Parsing coerces them here; merge.ts unions them on
+ * conflict — one list, so a new list-valued field cannot be normalized on
+ * read and then overwritten wholesale on merge. */
+export declare const ARRAY_FIELDS: string[];
 /** Full-kind path classification (kindFromPath only distinguishes the
  * indexed kinds — sessions default to knowledge there for compatibility).
  * Session files live directly in sessions/, so only the immediate parent
  * counts — matching anywhere in the path misclassifies every file of a
  * vault that happens to live under a directory named "sessions". */
 export declare function vaultKindFromPath(filePath: string): VaultKind;
+/** Total kind classification for a vault-relative content file (anything
+ * matching VAULT_FILE_RE) — derived from KIND_DIRS, so adding a vault dir
+ * can't silently fall a new kind through to the wrong one. Throws on paths
+ * outside the vault dirs; callers gate on VAULT_FILE_RE first. */
+export declare function vaultKindFromRelPath(relPath: string): VaultKind;
 export declare function parseFilePath(path: string): ParsedVaultFile;
 export declare function parseContent(content: string): {
     frontmatter: Record<string, any>;

package/dist/vault.js

@@ -1,7 +1,7 @@
 // src/vault.ts
 import matter from 'gray-matter';
 import yaml from 'js-yaml';
-import { readFileSync, readdirSync } from 'fs';
+import { readFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { HafezError } from './types.js';
 // Prevent gray-matter from auto-coercing YAML date strings into JS Date objects
@@ -11,7 +11,7 @@ export function slugify(name) {
     // real slug instead of collapsing to ''.
     return name
         .toLowerCase()
-        .replace(/['']/g, '')
+        .replace(/['’]/g, '')
         .replace(/[^\p{L}\p{N}]+/gu, '-')
         .replace(/^-|-$/g, '')
         .replace(/-{2,}/g, '-');
@@ -69,15 +69,50 @@ export function resolveFilePath(vaultPath, slug, kind) {
     }
     return join(vaultPath, KIND_DIRS[kind], `${slug}.md`);
 }
+/** The file a slug names, or null — entities are resolved before knowledge,
+ * the one resolution order every operation sees. */
+export function findVaultFile(vaultPath, slug) {
+    const entity = resolveFilePath(vaultPath, slug, 'entity');
+    if (existsSync(entity))
+        return entity;
+    const knowledge = resolveFilePath(vaultPath, slug, 'knowledge');
+    if (existsSync(knowledge))
+        return knowledge;
+    return null;
+}
+/** Does this slug name a vault file? An invalid slug definitionally doesn't
+ * exist — reference checks (create parent/related, link targets, validate)
+ * must report "does not exist", not crash. validate() in particular exists to
+ * REPORT malformed refs. */
+export function vaultFileExists(vaultPath, slug) {
+    try {
+        return findVaultFile(vaultPath, slug) !== null;
+    }
+    catch {
+        return false;
+    }
+}
 // Separator-agnostic: OS paths use '/' or '\' depending on platform, and a
 // POSIX-only check silently classifies every entity as knowledge on Windows
 // (all updates then fail on kind rules). Exported pure so win32 paths are
 // unit-testable from any platform.
+// The DEEPEST kind-dir occurrence wins: the in-vault dir is always deeper
+// than any ancestor, so a vault living under a directory named 'entities'
+// (e.g. ~/data/entities/myvault) can't shadow its knowledge/ files.
 export function kindFromPath(filePath) {
-    return /[/\\]entities[/\\]/.test(filePath) ? 'entity' : 'knowledge';
+    const lastMatch = (dir) => {
+        let idx = -1;
+        for (const m of filePath.matchAll(new RegExp(`[/\\\\]${dir}[/\\\\]`, 'g')))
+            idx = m.index;
+        return idx;
+    };
+    return lastMatch(KIND_DIRS.entity) > lastMatch(KIND_DIRS.knowledge) ? 'entity' : 'knowledge';
 }
-// Fields that must always be arrays when present (may be scalar in hand-edited YAML)
-const ARRAY_FIELDS = ['related', 'tags', 'domain'];
+/** Fields that must always be arrays when present (may be scalar in
+ * hand-edited YAML). Parsing coerces them here; merge.ts unions them on
+ * conflict — one list, so a new list-valued field cannot be normalized on
+ * read and then overwritten wholesale on merge. */
+export const ARRAY_FIELDS = ['related', 'tags', 'domain'];
 function normalizeFrontmatter(fm) {
     for (const field of ARRAY_FIELDS) {
         if (field in fm && typeof fm[field] === 'string') {
@@ -96,6 +131,17 @@ export function vaultKindFromPath(filePath) {
         return 'session';
     return kindFromPath(filePath);
 }
+/** Total kind classification for a vault-relative content file (anything
+ * matching VAULT_FILE_RE) — derived from KIND_DIRS, so adding a vault dir
+ * can't silently fall a new kind through to the wrong one. Throws on paths
+ * outside the vault dirs; callers gate on VAULT_FILE_RE first. */
+export function vaultKindFromRelPath(relPath) {
+    for (const [kind, dir] of Object.entries(KIND_DIRS)) {
+        if (relPath.startsWith(`${dir}/`))
+            return kind;
+    }
+    throw new HafezError('VALIDATION_FAILED', `Not a vault content path: ${relPath}`);
+}
 export function parseFilePath(path) {
     const content = readFileSync(path, 'utf-8');
     const { data, content: body } = matter(content, MATTER_OPTIONS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hafez",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,8 +18,9 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
-    "install:local": "chmod +x \"$(pwd)/dist/cli.js\" && mkdir -p ~/.local/bin && ln -sf \"$(pwd)/dist/cli.js\" ~/.local/bin/hafez && rm -f ~/.claude/skills/hafez/SKILL.md && mkdir -p ~/.claude/skills/hafez && cp \"$(pwd)/skill/SKILL.md\" ~/.claude/skills/hafez/SKILL.md",
-    "pretest": "npm run build",
+    "install:local": "chmod +x \"$(pwd)/dist/cli.js\" && mkdir -p ~/.local/bin && ln -sf \"$(pwd)/dist/cli.js\" ~/.local/bin/hafez && for d in ~/.claude/skills ~/.agents/skills; do for s in hafez hafez-save; do mkdir -p \"$d/$s\" && cp \"$(pwd)/skill/$s/SKILL.md\" \"$d/$s/SKILL.md\"; done; done",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "pretest": "npm run build && npm run typecheck",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepare": "npm run build"

package/skill/hafez/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: hafez
+description: >
+  Hafez vault: the less common operations and the tool itself. Use when the
+  user asks what is in the vault ("what am I working on?", "what's stale?"),
+  wants to promote, link, unlink, delete, change a status or validate, or
+  wants to update or reconfigure Hafez ("upgrade hafez", "set up hafez").
+  Also the reference to read when no Hafez block is in your instructions.
+hash: 01a30ae1e209
+---
+
+# Hafez
+
+- Update an entity or note: `hafez read <slug>`. The end of its output shows the write command.
+- Create an entity or a knowledge note: the two `hafez create` lines below.
+- Save the session: the `hafez-save` skill. No skill: `hafez schema digest`.
+
+Never ask the user whether to write to the vault. Write, then say so in one line naming the slug and what you did.
+Update only what you have read this session. Not read yet: read it first.
+Open actions on an entity you read are yours: tick what landed, drop what is dead. Lines `read` marks stale are due.
+
+## Create
+
+```
+hafez create entity "<name>" --type <project|entity> --description "<one sentence>" --brief "<where things stand>" --add-action "<next step>"
+hafez create knowledge "<name>" --synthesis "<the insight>" --confidence <observation|pattern|principle> --related <slug>
+```
+
+A plan is `--subtype plan` without `--synthesis`. Cannot tell entity from knowledge: `hafez capture "<name>"`.
+
+## Find
+
+```
+hafez query --filter <active|paused|done|stale|capture>
+hafez search "<terms>" --kind <entity|knowledge>
+hafez stats
+```
+
+## Less common operations
+
+```
+hafez promote <slug> <entity|project|knowledge>
+hafez link <slug> <target> --relation <parent|related>
+hafez unlink <slug> <target> --relation <parent|related>
+hafez update <slug> --status <active|paused|done>
+hafez delete <slug>
+hafez validate
+```
+
+A plan's status is `active|done`. `delete` removes a knowledge or session note only; an entity is retired with `--status done`.
+
+Several writes that must land together go in one batch: a bare array, no wrapper. A slug is the name lowercased, apostrophes dropped, each other run of characters that are not letters or digits turned into one `-` and none left at either end, so a later op can name what an earlier one creates.
+
+```
+hafez batch --data '[
+  {"op":"create","kind":"entity","name":"Token Rotation","fields":{"type":"entity"}},
+  {"op":"link","slug":"token-rotation","target":"auth-refactor","relation":"parent"}
+]'
+```
+
+In the JSON, write each apostrophe as `’` (`isn’t`): a straight `'` ends the quoted argument and the batch fails.
+
+No pipe (PowerShell 5.1): `hafez batch --file ops.json`. Machine-readable shape of any op: `hafez schema <op>`, with `--examples` for a sample.
+
+## The tool itself
+
+- Upgrade: `hafez upgrade`. It checks and prints, it never installs. Show the user the printed steps and run them only after a yes.
+- Set up or reconfigure: `hafez onboard`.

package/skill/hafez-save/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: hafez-save
+description: >
+  Save this session to the Hafez vault. Use when the user invokes hafez-save
+  or says "save", "save the session" or "wrap up". Never run it unprompted.
+hash: 91351681e779
+---
+
+# Save the session
+
+1. List the slugs you read, updated or created this session. Use only those; a slug you did not see in `hafez` output this session does not go in. No slugs: tell the user there is nothing to save and stop.
+2. Run this once, with today's date:
+
+```
+hafez digest --data '{
+  "entities_touched": ["<slug>", "<slug>"],
+  "decisions": ["<a decision made this session>"],
+  "narrative": "<one to three sentences: what happened and how it connects>",
+  "session_date": "<YYYY-MM-DD>"
+}' | hafez batch
+```
+
+In the JSON, write each apostrophe as `’` (`isn’t`): a straight `'` ends the quoted argument and the save fails.
+
+No pipe (PowerShell 5.1): put the JSON in `summary.json`, then `hafez digest --file summary.json > ops.json`, then `hafez batch --file ops.json`.
+
+3. Tell the user in one line: the session note's slug and the entities it logged to.
+
+`decisions` may be an empty array. Each slug in `entities_touched` gets a session log entry and the session note links them all. An unknown slug fails the save and names the slug: fix the list and run it again. A session already saved is skipped, so a second run does no harm.

package/dist/cli/help-agent.d.ts

@@ -1 +0,0 @@
-export declare function renderAgentHelp(): string;

package/dist/cli/help-agent.js

@@ -1,186 +0,0 @@
-// src/cli/help-agent.ts
-//
-// `hafez help --agent` — the prompt-gate. Plain text, no ANSI, no markdown
-// decoration. Designed for an LLM with zero Hafez context to read once per
-// session and then produce valid batch JSON on first try.
-//
-// Hand-written sections: Preamble + Hard rules (prose, free-form).
-// Generated sections (wrapped in <!-- SECTION:name --> markers so tests can
-// parse them): op-catalog, critical-enums, batch-examples, digest.
-//
-// Generated sections derive from the Op Spec table (batch-ops.ts via
-// schema-introspect.ts), so they cannot drift from the Zod schemas. Do NOT
-// enumerate enum values inside the preamble or hard rules — those come from
-// schema-introspect.ts.
-import { listOps, getEnumValues, getOpExample, getOpSchema } from './schema-introspect.js';
-const PREAMBLE = `# Hafez — Agent Prompt Gate
-
-Hafez is your persistent knowledge graph for projects, entities, captures,
-knowledge notes, and session notes. The \`hafez\` CLI is the ONLY supported
-write path into the vault — never edit files under \`entities/\`, \`knowledge/\`,
-or \`sessions/\` by hand. Every mutation goes through the CLI so the git history,
-SQLite index, and link integrity stay in sync.
-
-Mental model:
-
-- An \`entity\` is tracked work with substance — a bug, a feature, a decision.
-  Entities have status, can have children, and carry a session log. The three
-  entity types are \`capture\` (raw inbox), \`entity\` (standalone tracked item),
-  and \`project\` (scoped effort with deliverables, can have child entities).
-- A \`knowledge\` note is an insight or a plan. Insights distil a pattern or
-  principle and mature through added evidence. Plans are structured steps
-  toward a goal. Knowledge is searchable, linkable, and timestamped.
-- A \`session\` note records what happened in a working session and references
-  the entities it touched. Session notes are created via \`create/session\`
-  and are not indexed in SQLite — they are for narrative, not query.
-- \`capture\` is the quick-inbox path: grab a link or thought, no structure.
-  A capture can later be promoted to entity, project, or knowledge.
-- Entities relate to each other through links: \`parent\` (hierarchy) or
-  \`related\` (soft reference). Use \`link\` / \`unlink\` ops to manage them.
-- Every meaningful update should include a session_log entry so the history
-  of the work is preserved. Sessions are how future-you reconstructs why a
-  decision was made.
-
-Single source of truth: the exact field names, enum values, and op signatures
-below are generated at runtime from the live Zod schema. If a field is not
-listed here, it does not exist — do not invent fields.
-
-## Hard rules (read before writing a batch)
-
-- ALWAYS batch 2+ mutations into one \`hafez batch\` call. Many single-op
-  calls fragment git history and clobber the vault index's atomicity guarantee.
-- NEVER invent field names. If a field is not in \`hafez schema <op>\`, it
-  does not exist. Unknown fields are rejected by the validator with a pointer
-  to the right schema.
-- NEVER write to vault files directly. Always go through the CLI.
-- STRONGLY PREFERRED: include a \`session_log\` on update ops that reflect
-  meaningful work. The validator does not enforce this — omitting it is a
-  code smell, not a hard error.
-- When in doubt, run \`hafez schema <op>\` before writing a batch. Cheap,
-  deterministic, no side effects.
-- Use \`hafez batch --dry-run\` to validate a payload without touching the
-  vault. Same validation as a real apply, zero filesystem mutation.
-
-## Slug contract (create-then-link in one batch)
-
-Slugs are deterministic: slug = slugify(name) — lowercase, non-alphanumeric
-runs collapse to single \`-\`, edges trimmed (\`"Auth Refactor!"\` →
-\`auth-refactor\`). A batch executes sequentially, so later ops may reference
-the slugs of earlier creates in the same batch (\`create\` then \`link\`/\`update\`
-works in one payload). Collisions hard-error — a wrong slug prediction can
-never silently hit an existing document. To verify predictions first:
-\`hafez batch --dry-run\` reports the derived slug for every create op.
-`;
-function renderOpCatalog() {
-    const lines = ['<!-- SECTION:op-catalog -->'];
-    lines.push('Ops (run `hafez schema <name>` for the full field list):');
-    for (const op of listOps()) {
-        const desc = op.description ? ` — ${op.description}` : '';
-        lines.push(`  ${op.name}${desc}`);
-        lines.push(`    → hafez schema ${op.name}`);
-    }
-    lines.push('<!-- /SECTION:op-catalog -->');
-    return lines.join('\n');
-}
-function renderCriticalEnums() {
-    const entries = [
-        ['update.fields.status', 'update.fields.status'],
-        ['update.fields.session_log.type', 'update.fields.session_log.type'],
-        ['update.fields.confidence', 'update.fields.confidence'],
-        ['create-entity.fields.type', 'create-entity.fields.type'],
-        ['create-knowledge.fields.subtype', 'create-knowledge.fields.subtype'],
-        ['link.relation', 'link.relation'],
-    ];
-    const lines = ['<!-- SECTION:critical-enums -->'];
-    lines.push('Critical enums (value lists — values are authoritative):');
-    for (const [label, path] of entries) {
-        const values = getEnumValues(path);
-        if (!values)
-            continue;
-        lines.push(`  ${label} = [${values.join(', ')}]`);
-    }
-    lines.push('<!-- /SECTION:critical-enums -->');
-    return lines.join('\n');
-}
-function renderBatchExamples() {
-    const lines = ['<!-- SECTION:batch-examples -->'];
-    lines.push('Batch JSON shape — wrap one or more ops in an array:');
-    lines.push('');
-    lines.push('  echo \'[...]\' | hafez batch          # POSIX shells');
-    lines.push('  hafez batch --file payload.json     # any platform (PowerShell 5.1 cannot pipe stdin)');
-    lines.push('');
-    lines.push('Minimal example per op (canonical field names; aliased keys stripped):');
-    lines.push('');
-    for (const op of listOps()) {
-        const example = getOpExample(op.name);
-        if (!example)
-            continue;
-        lines.push(`# ${op.name}`);
-        lines.push(JSON.stringify(example, null, 2));
-        lines.push('');
-    }
-    lines.push('<!-- /SECTION:batch-examples -->');
-    return lines.join('\n');
-}
-function renderDigestSection() {
-    const lines = ['<!-- SECTION:digest -->'];
-    lines.push('Session digest — turn end-of-session context into a batch payload.');
-    lines.push('NOT a batch op: it reads its own JSON and prints batch JSON.');
-    lines.push('');
-    lines.push("  echo '<digest-json>' | hafez digest | hafez batch");
-    lines.push('  # No stdin pipes (PowerShell 5.1): hafez digest --file summary.json > ops.json,');
-    lines.push('  # then hafez batch --file ops.json');
-    lines.push('');
-    lines.push('Input fields (`hafez schema digest` for the full schema):');
-    const schema = getOpSchema('digest');
-    for (const [name, field] of Object.entries(schema?.fields ?? {})) {
-        const req = field.optional ? 'optional' : 'required';
-        const desc = field.description ? ` — ${field.description}` : '';
-        lines.push(`  ${name} (${req})${desc}`);
-    }
-    lines.push('');
-    lines.push('Example input:');
-    lines.push(JSON.stringify(getOpExample('digest'), null, 2));
-    lines.push('<!-- /SECTION:digest -->');
-    return lines.join('\n');
-}
-const FOOTER = `## Lookup pointers
-
-- \`hafez schema\`                      — list all ops
-- \`hafez schema <op>\`                 — full JSON schema for one op
-- \`hafez schema <op> --examples\`      — working JSON examples per enum value
-- \`hafez batch --dry-run\`             — validate without touching the vault
-`;
-/**
- * Render the full prompt-gate output. Token budget: 1500-3000 tokens when
- * measured as char/3.5. The drift test in tests/cli-help-agent.test.ts
- * enforces the ceiling.
- */
-const EXIT_CODES_SECTION = `## Exit codes
-
-| code | meaning |
-|------|---------|
-| 0 | success |
-| 1 | not found / unknown error |
-| 2 | validation or usage error (bad flags, bad payload, core rejected the write) |
-| 3 | git push failed — the write IS committed locally |
-| 4 | write succeeded but the auto-sync after it failed |
-| 5 | slug already exists |
-| 6 | git commit failed — nothing was written to history |
-| 7 | vault locked by another hafez process — retry when it finishes |`;
-export function renderAgentHelp() {
-    return [
-        PREAMBLE,
-        renderOpCatalog(),
-        '',
-        renderCriticalEnums(),
-        '',
-        renderBatchExamples(),
-        '',
-        renderDigestSection(),
-        '',
-        EXIT_CODES_SECTION,
-        '',
-        FOOTER,
-    ].join('\n');
-}

package/dist/query.d.ts

@@ -1,24 +0,0 @@
-import type { QueryResult, KnowledgeQueryResult, EntityQueryOpts, KnowledgeQueryOpts, UnifiedResult } from './types.js';
-import type { HafezIndex } from './db.js';
-export declare function queryEntities(index: HafezIndex, opts?: EntityQueryOpts): {
-    items: QueryResult[];
-    total: number;
-};
-export declare function queryChildren(index: HafezIndex, parentSlug: string): {
-    items: QueryResult[];
-    total: number;
-};
-export declare function queryRelatedTo(index: HafezIndex, slug: string, relation?: string): {
-    items: UnifiedResult[];
-    total: number;
-};
-export declare function queryKnowledge(index: HafezIndex, opts?: KnowledgeQueryOpts): {
-    items: KnowledgeQueryResult[];
-    total: number;
-};
-export declare function queryUnified(index: HafezIndex, opts?: EntityQueryOpts & {
-    kind?: 'entity' | 'knowledge' | 'all';
-}): {
-    items: UnifiedResult[];
-    total: number;
-};

package/dist/query.js

@@ -1,169 +0,0 @@
-import { HafezError } from './types.js';
-function toQueryResult(slug, row) {
-    return {
-        slug,
-        name: row.name,
-        type: row.type,
-        status: row.status,
-        description: row.description ?? null,
-        resource: row.resource ?? null,
-        domain: row.domain ?? [],
-        last_touched: row.last_touched,
-        next_action: row.next_action ?? null,
-        next_action_count: row.next_action_count ?? 0,
-        parent: row.parent ?? null,
-        related: row.related ?? [],
-        staleness_days: row.staleness_days ?? null,
-        tags: row.tags ?? [],
-        brief: row.brief ?? null,
-        session_log_count: row.session_log_count ?? 0,
-        last_session_date: row.last_session_date ?? null,
-        last_session_type: row.last_session_type ?? null,
-        last_session_summary: row.last_session_summary ?? null,
-    };
-}
-function toKnowledgeResult(slug, row) {
-    return {
-        slug,
-        name: row.name,
-        description: row.description ?? null,
-        domain: row.domain ?? [],
-        confidence: row.confidence ?? 'observation',
-        related: row.related ?? [],
-        reinforcement_count: row.reinforcement_count ?? 0,
-        last_reinforced: row.last_reinforced ?? null,
-        last_touched: row.last_touched ?? null,
-    };
-}
-const STATUS_FILTERS = new Set(['active', 'paused', 'done']);
-const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
-function validateDateOpts(opts) {
-    const fields = ['since', 'before', 'createdSince', 'createdBefore'];
-    for (const f of fields) {
-        if (opts?.[f] !== undefined && !ISO_DATE.test(opts[f])) {
-            throw new HafezError('VALIDATION_FAILED', `Invalid date format for ${f}: "${opts[f]}". Must be YYYY-MM-DD.`);
-        }
-    }
-}
-export function queryEntities(index, opts) {
-    index.syncIfStale();
-    validateDateOpts(opts);
-    const qopts = { kind: 'entity' };
-    if (opts?.filter && STATUS_FILTERS.has(opts.filter))
-        qopts.status = opts.filter;
-    if (opts?.filter === 'stale')
-        qopts.filter = 'stale';
-    if (opts?.filter === 'capture')
-        qopts.filter = 'capture';
-    if (opts?.type)
-        qopts.type = opts.type;
-    if (opts?.parent)
-        qopts.parent = opts.parent;
-    if (opts?.domain)
-        qopts.domain = opts.domain;
-    if (opts?.since)
-        qopts.since = opts.since;
-    if (opts?.before)
-        qopts.before = opts.before;
-    if (opts?.createdSince)
-        qopts.createdSince = opts.createdSince;
-    if (opts?.createdBefore)
-        qopts.createdBefore = opts.createdBefore;
-    if (opts?.tags)
-        qopts.tags = opts.tags;
-    if (opts?.sort_by)
-        qopts.sort_by = opts.sort_by;
-    if (opts?.sort_order)
-        qopts.sort_order = opts.sort_order;
-    if (opts?.limit != null)
-        qopts.limit = opts.limit;
-    if (opts?.offset != null)
-        qopts.offset = opts.offset;
-    const { items, total } = index.queryItems(qopts);
-    return { items: items.map(i => toQueryResult(i.slug, i)), total };
-}
-export function queryChildren(index, parentSlug) {
-    return queryEntities(index, { parent: parentSlug });
-}
-export function queryRelatedTo(index, slug, relation) {
-    index.syncIfStale();
-    const { items, total } = index.queryItems({ relatedTo: slug, relation });
-    return {
-        items: items.map(i => i.kind === 'entity'
-            ? { ...toQueryResult(i.slug, i), kind: 'entity' }
-            : { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' }),
-        total,
-    };
-}
-export function queryKnowledge(index, opts) {
-    index.syncIfStale();
-    const qopts = { kind: 'knowledge' };
-    if (opts?.domain)
-        qopts.domain = opts.domain;
-    if (opts?.confidence)
-        qopts.confidence = opts.confidence;
-    if (opts?.subtype)
-        qopts.subtype = opts.subtype;
-    if (opts?.tags)
-        qopts.tags = opts.tags;
-    if (opts?.sort_by)
-        qopts.sort_by = opts.sort_by;
-    if (opts?.sort_order)
-        qopts.sort_order = opts.sort_order;
-    if (opts?.limit != null)
-        qopts.limit = opts.limit;
-    if (opts?.offset != null)
-        qopts.offset = opts.offset;
-    const { items, total } = index.queryItems(qopts);
-    return { items: items.map(i => toKnowledgeResult(i.slug, i)), total };
-}
-export function queryUnified(index, opts) {
-    index.syncIfStale();
-    validateDateOpts(opts);
-    const qopts = {};
-    if (opts?.kind && opts.kind !== 'all')
-        qopts.kind = opts.kind;
-    // When kind is 'all' or unset, no kind filter — both entities and knowledge are returned
-    if (opts?.filter && STATUS_FILTERS.has(opts.filter))
-        qopts.status = opts.filter;
-    if (opts?.filter === 'stale')
-        qopts.filter = 'stale';
-    if (opts?.filter === 'capture')
-        qopts.filter = 'capture';
-    if (opts?.type)
-        qopts.type = opts.type;
-    if (opts?.parent)
-        qopts.parent = opts.parent;
-    if (opts?.domain)
-        qopts.domain = opts.domain;
-    if (opts?.confidence)
-        qopts.confidence = opts.confidence;
-    if (opts?.since)
-        qopts.since = opts.since;
-    if (opts?.before)
-        qopts.before = opts.before;
-    if (opts?.createdSince)
-        qopts.createdSince = opts.createdSince;
-    if (opts?.createdBefore)
-        qopts.createdBefore = opts.createdBefore;
-    if (opts?.tags)
-        qopts.tags = opts.tags;
-    if (opts?.sort_by)
-        qopts.sort_by = opts.sort_by;
-    if (opts?.sort_order)
-        qopts.sort_order = opts.sort_order;
-    if (opts?.limit !== undefined)
-        qopts.limit = opts.limit;
-    if (opts?.offset !== undefined)
-        qopts.offset = opts.offset;
-    const result = index.queryItems(qopts);
-    const items = result.items.map(i => {
-        if (i.kind === 'entity') {
-            return { ...toQueryResult(i.slug, i), kind: 'entity' };
-        }
-        else {
-            return { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' };
-        }
-    });
-    return { items, total: result.total };
-}