clawvault 3.1.0 → 3.2.1

package/dist/chunk-BSJ6RIT7.js

@@ -0,0 +1,447 @@
+// src/lib/fact-extractor.ts
+function normalizeEntity(name) {
+  return name.toLowerCase().replace(/[^a-z0-9\s]/g, "").replace(/\s+/g, " ").trim();
+}
+function factId(entity, relation, value) {
+  const key = `${normalizeEntity(entity)}::${relation.toLowerCase()}::${value.toLowerCase().trim()}`;
+  let hash = 0;
+  for (let i = 0; i < key.length; i++) {
+    const char = key.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(36);
+}
+var PREFERENCE_PATTERNS = [
+  {
+    // "I prefer X" / "I like X" / "I love X" / "I enjoy X"
+    pattern: /\b(?:i|user|they)\s+(?:prefer|like|love|enjoy|want|favor)s?\s+(.+?)(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: "user",
+      relation: "prefers",
+      value: m[1].trim(),
+      category: "preference"
+    })
+  },
+  {
+    // "my favorite X is Y"
+    pattern: /\bmy\s+(?:favorite|favourite|preferred)\s+(\w+)\s+(?:is|are)\s+(.+?)(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: "user",
+      relation: `favorite_${m[1].toLowerCase()}`,
+      value: m[2].trim(),
+      category: "preference"
+    })
+  },
+  {
+    // "I don't like X" / "I hate X" / "I dislike X"
+    pattern: /\b(?:i|user)\s+(?:don'?t\s+like|hate|dislike|avoid)s?\s+(.+?)(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: "user",
+      relation: "dislikes",
+      value: m[1].trim(),
+      category: "preference"
+    })
+  },
+  {
+    // "I'm allergic to X" / "I have an allergy to X"
+    pattern: /\b(?:i'?m|i\s+am|i\s+have)\s+(?:an?\s+)?allerg(?:ic|y)\s+(?:to\s+)?(.+?)(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: "user",
+      relation: "allergic_to",
+      value: m[1].trim(),
+      category: "preference"
+    })
+  }
+];
+var FACT_PATTERNS = [
+  {
+    // "X works at Y" / "X is employed at Y"
+    pattern: /\b(\w+(?:\s+\w+)?)\s+(?:works?\s+(?:at|for)|is\s+employed\s+(?:at|by))\s+(.+?)(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: m[1].trim(),
+      relation: "works_at",
+      value: m[2].trim(),
+      category: "fact"
+    })
+  },
+  {
+    // "X lives in Y" / "X moved to Y"
+    pattern: /\b(\w+(?:\s+\w+)?)\s+(?:live[sd]?\s+in|moved?\s+to|relocated?\s+to)\s+(.+?)(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: m[1].trim(),
+      relation: "lives_in",
+      value: m[2].trim(),
+      category: "fact"
+    })
+  },
+  {
+    // "X is Y years old" / "X's age is Y"
+    pattern: /\b(\w+(?:\s+\w+)?)\s+(?:is|turned)\s+(\d+)\s+years?\s+old/i,
+    extract: (m) => ({
+      entity: m[1].trim(),
+      relation: "age",
+      value: m[2],
+      category: "fact"
+    })
+  },
+  {
+    // "X bought Y" / "X purchased Y"
+    pattern: /\b(\w+(?:\s+\w+)?)\s+(?:bought|purchased|got|acquired)\s+(?:a\s+|an\s+|the\s+)?(.+?)(?:\s+for\s+\$?([\d,.]+))?(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: m[1].trim(),
+      relation: "bought",
+      value: m[3] ? `${m[2].trim()} ($${m[3]})` : m[2].trim(),
+      category: "event"
+    })
+  },
+  {
+    // "X spent $Y on Z"
+    pattern: /\b(\w+(?:\s+\w+)?)\s+spent\s+\$?([\d,.]+)\s+on\s+(.+?)(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: m[1].trim(),
+      relation: "spent_on",
+      value: `$${m[2]} on ${m[3].trim()}`,
+      category: "event"
+    })
+  }
+];
+var DECISION_PATTERNS = [
+  {
+    // "decided to X" / "we decided X"
+    pattern: /\b(?:i|we|user)\s+decided\s+(?:to\s+)?(.+?)(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: "user",
+      relation: "decided",
+      value: m[1].trim(),
+      category: "decision"
+    })
+  },
+  {
+    // "chose X over Y"
+    pattern: /\b(?:i|we|user)\s+chose\s+(.+?)\s+over\s+(.+?)(?:\.|,|$)/i,
+    extract: (m) => ({
+      entity: "user",
+      relation: "chose",
+      value: `${m[1].trim()} (over ${m[2].trim()})`,
+      category: "decision"
+    })
+  }
+];
+var ALL_PATTERNS = [...PREFERENCE_PATTERNS, ...FACT_PATTERNS, ...DECISION_PATTERNS];
+function extractFactsRuleBased(text, source, timestamp) {
+  const facts = [];
+  const now = timestamp || (/* @__PURE__ */ new Date()).toISOString();
+  const sentences = text.split(/[.!?\n]+/).filter((s) => s.trim().length > 5);
+  for (const sentence of sentences) {
+    const trimmed = sentence.trim();
+    for (const rule of ALL_PATTERNS) {
+      const match = trimmed.match(rule.pattern);
+      if (match) {
+        const extracted = rule.extract(match);
+        if (extracted && extracted.value.length > 1 && extracted.value.length < 200) {
+          facts.push({
+            id: factId(extracted.entity, extracted.relation, extracted.value),
+            entity: extracted.entity,
+            entityNorm: normalizeEntity(extracted.entity),
+            relation: extracted.relation,
+            value: extracted.value,
+            validFrom: now,
+            validUntil: null,
+            confidence: 0.7,
+            // Rule-based gets moderate confidence
+            category: extracted.category,
+            source,
+            rawText: trimmed
+          });
+        }
+      }
+    }
+  }
+  return facts;
+}
+var EXTRACTION_PROMPT = `Extract structured facts from the following text. Return ONLY a JSON array of objects with these fields:
+- entity: the subject (person, place, thing, or "user" for the speaker/first person)
+- relation: the relationship type (see examples below)
+- value: the object of the relation
+- category: one of "preference", "fact", "decision", "entity", "event"
+- confidence: 0.0 to 1.0
+
+PREFERENCE EXTRACTION (critical \u2014 extract ALL of these):
+- Likes, dislikes, preferences, favorites: "prefers", "likes", "dislikes", "favorite"
+- Food/dietary: "allergic_to", "dietary_restriction", "favorite_food", "dislikes_food"
+- Habits/routines: "habit", "routine", "schedule"
+- Communication style: "prefers_communication", "timezone", "language"
+- Tools/tech: "uses_tool", "prefers_editor", "prefers_language"
+
+TEMPORAL FACTS (include dates when present):
+- Include specific dates, times, relative references ("last Tuesday" = resolve if possible)
+- Events: "happened_on", "started_on", "ended_on", "deadline"
+- Use ISO format for dates when possible
+
+OTHER RELATIONS:
+- Identity: "works_at", "lives_in", "age", "role", "email", "phone"
+- Actions: "bought", "spent_on", "created", "visited", "completed"
+- Decisions: "decided", "chose", "rejected", "approved"
+- Knowledge: "knows_about", "studied", "expertise"
+
+Examples:
+
+Input: "I really love Thai food, especially pad thai. I'm allergic to shellfish though."
+Output: [
+  {"entity": "user", "relation": "favorite_food", "value": "Thai food, especially pad thai", "category": "preference", "confidence": 0.95},
+  {"entity": "user", "relation": "allergic_to", "value": "shellfish", "category": "preference", "confidence": 0.99}
+]
+
+Input: "We decided on Tuesday to use PostgreSQL for the new project. John will lead the backend team."
+Output: [
+  {"entity": "team", "relation": "decided", "value": "use PostgreSQL for the new project", "category": "decision", "confidence": 0.95},
+  {"entity": "John", "relation": "role", "value": "backend team lead", "category": "fact", "confidence": 0.9}
+]
+
+Input: "My morning routine is: wake up at 6am, coffee, then gym. I prefer working out before work."
+Output: [
+  {"entity": "user", "relation": "routine", "value": "wake up at 6am, coffee, then gym", "category": "preference", "confidence": 0.9},
+  {"entity": "user", "relation": "prefers", "value": "working out before work", "category": "preference", "confidence": 0.9}
+]
+
+Rules:
+- Extract ALL facts, preferences, decisions, and events \u2014 err on the side of extracting more
+- For preferences, use "user" as entity unless a specific person is named
+- For monetary amounts, include the currency symbol
+- Be precise \u2014 only extract what is explicitly stated or strongly implied
+- Return empty array [] if no extractable facts found
+
+Text:
+`;
+async function extractFactsLlm(text, source, timestamp, llmFn) {
+  if (!llmFn) {
+    return extractFactsRuleBased(text, source, timestamp);
+  }
+  const now = timestamp || (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    const response = await llmFn(EXTRACTION_PROMPT + text);
+    const jsonMatch = response.match(/\[[\s\S]*?\]/);
+    if (!jsonMatch) {
+      return extractFactsRuleBased(text, source, timestamp);
+    }
+    const parsed = JSON.parse(jsonMatch[0]);
+    return parsed.map((f) => ({
+      id: factId(f.entity, f.relation, f.value),
+      entity: f.entity,
+      entityNorm: normalizeEntity(f.entity),
+      relation: f.relation,
+      value: f.value,
+      validFrom: now,
+      validUntil: null,
+      confidence: Math.min(1, Math.max(0, f.confidence || 0.8)),
+      category: f.category || "fact",
+      source,
+      rawText: text.substring(0, 500)
+    }));
+  } catch {
+    return extractFactsRuleBased(text, source, timestamp);
+  }
+}
+
+// src/lib/fact-store.ts
+import * as fs from "fs";
+import * as path from "path";
+var FactStore = class {
+  facts = /* @__PURE__ */ new Map();
+  byEntity = /* @__PURE__ */ new Map();
+  byRelation = /* @__PURE__ */ new Map();
+  byCategory = /* @__PURE__ */ new Map();
+  factsPath;
+  dirty = false;
+  constructor(vaultPath) {
+    this.factsPath = path.join(vaultPath, ".clawvault", "facts.jsonl");
+  }
+  /** Load facts from disk */
+  load() {
+    this.facts.clear();
+    this.byEntity.clear();
+    this.byRelation.clear();
+    this.byCategory.clear();
+    if (!fs.existsSync(this.factsPath)) return;
+    const lines = fs.readFileSync(this.factsPath, "utf-8").split("\n").filter((l) => l.trim());
+    for (const line of lines) {
+      try {
+        const fact = JSON.parse(line);
+        this.indexFact(fact);
+      } catch {
+      }
+    }
+  }
+  /** Add facts with conflict resolution. Returns number of conflicts resolved. */
+  addFacts(newFacts) {
+    let conflicts = 0;
+    for (const fact of newFacts) {
+      const existing = this.findConflict(fact);
+      if (existing) {
+        existing.validUntil = fact.validFrom;
+        conflicts++;
+      }
+      this.indexFact(fact);
+      this.dirty = true;
+    }
+    return conflicts;
+  }
+  /** Find an existing fact that conflicts with the new one */
+  findConflict(newFact) {
+    const entityFacts = this.byEntity.get(newFact.entityNorm);
+    if (!entityFacts) return null;
+    for (const id of entityFacts) {
+      const existing = this.facts.get(id);
+      if (!existing || existing.validUntil) continue;
+      if (existing.relation === newFact.relation) {
+        if (this.isSimilarValue(existing.value, newFact.value)) {
+          return existing;
+        }
+        if (this.isExclusiveRelation(newFact.relation)) {
+          return existing;
+        }
+      }
+    }
+    return null;
+  }
+  /** Check if two values are similar enough to be considered the same fact */
+  isSimilarValue(a, b) {
+    const na = a.toLowerCase().trim();
+    const nb = b.toLowerCase().trim();
+    if (na === nb) return true;
+    if (na.includes(nb) || nb.includes(na)) return true;
+    return false;
+  }
+  /** Relations where only one value can be active at a time */
+  isExclusiveRelation(relation) {
+    const exclusive = /* @__PURE__ */ new Set([
+      "lives_in",
+      "works_at",
+      "age",
+      "favorite_color",
+      "favorite_food",
+      "favorite_restaurant",
+      "favorite_movie",
+      "favorite_book",
+      "favorite_music",
+      "favorite_sport",
+      "job_title",
+      "employer",
+      "marital_status",
+      "city",
+      "country"
+    ]);
+    return exclusive.has(relation);
+  }
+  /** Index a fact in all lookup maps */
+  indexFact(fact) {
+    this.facts.set(fact.id, fact);
+    if (!this.byEntity.has(fact.entityNorm)) {
+      this.byEntity.set(fact.entityNorm, /* @__PURE__ */ new Set());
+    }
+    this.byEntity.get(fact.entityNorm).add(fact.id);
+    if (!this.byRelation.has(fact.relation)) {
+      this.byRelation.set(fact.relation, /* @__PURE__ */ new Set());
+    }
+    this.byRelation.get(fact.relation).add(fact.id);
+    if (!this.byCategory.has(fact.category)) {
+      this.byCategory.set(fact.category, /* @__PURE__ */ new Set());
+    }
+    this.byCategory.get(fact.category).add(fact.id);
+  }
+  /** Save facts to disk (full rewrite for consistency) */
+  save() {
+    if (!this.dirty && fs.existsSync(this.factsPath)) return;
+    const dir = path.dirname(this.factsPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    const lines = Array.from(this.facts.values()).map((f) => JSON.stringify(f)).join("\n");
+    fs.writeFileSync(this.factsPath, lines + "\n", "utf-8");
+    this.dirty = false;
+  }
+  /** Append new facts to disk (faster than full rewrite) */
+  append(facts) {
+    const dir = path.dirname(this.factsPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    const lines = facts.map((f) => JSON.stringify(f)).join("\n");
+    fs.appendFileSync(this.factsPath, lines + "\n", "utf-8");
+  }
+  // ─── Query methods ──────────────────────────────────────────────────────
+  /** Get all active facts for an entity */
+  getEntityFacts(entity) {
+    const norm = normalizeEntity(entity);
+    const ids = this.byEntity.get(norm);
+    if (!ids) return [];
+    return Array.from(ids).map((id) => this.facts.get(id)).filter((f) => f && !f.validUntil);
+  }
+  /** Get all active facts for a relation */
+  getRelationFacts(relation) {
+    const ids = this.byRelation.get(relation);
+    if (!ids) return [];
+    return Array.from(ids).map((id) => this.facts.get(id)).filter((f) => f && !f.validUntil);
+  }
+  /** Get all active facts in a category */
+  getCategoryFacts(category) {
+    const ids = this.byCategory.get(category);
+    if (!ids) return [];
+    return Array.from(ids).map((id) => this.facts.get(id)).filter((f) => f && !f.validUntil);
+  }
+  /** Get all active preferences */
+  getPreferences() {
+    return this.getCategoryFacts("preference");
+  }
+  /** Search facts by text query (simple keyword match) */
+  searchFacts(query) {
+    const terms = query.toLowerCase().split(/\s+/);
+    const results = [];
+    for (const fact of this.facts.values()) {
+      if (fact.validUntil) continue;
+      const text = `${fact.entity} ${fact.relation} ${fact.value} ${fact.rawText}`.toLowerCase();
+      const matches = terms.filter((t) => text.includes(t)).length;
+      if (matches >= Math.ceil(terms.length * 0.5)) {
+        results.push(fact);
+      }
+    }
+    return results;
+  }
+  /** Get facts valid at a specific time */
+  getFactsAt(timestamp) {
+    const t = new Date(timestamp).getTime();
+    const results = [];
+    for (const fact of this.facts.values()) {
+      const from = new Date(fact.validFrom).getTime();
+      const until = fact.validUntil ? new Date(fact.validUntil).getTime() : Infinity;
+      if (t >= from && t < until) {
+        results.push(fact);
+      }
+    }
+    return results;
+  }
+  /** Get stats */
+  stats() {
+    const active = Array.from(this.facts.values()).filter((f) => !f.validUntil);
+    return {
+      totalFacts: this.facts.size,
+      activeFacts: active.length,
+      supersededFacts: this.facts.size - active.length,
+      entities: this.byEntity.size,
+      relations: this.byRelation.size
+    };
+  }
+  /** Get all facts (for testing/debugging) */
+  getAllFacts() {
+    return Array.from(this.facts.values());
+  }
+};
+
+export {
+  normalizeEntity,
+  factId,
+  extractFactsRuleBased,
+  extractFactsLlm,
+  FactStore
+};

package/dist/chunk-ECRZL5XR.js

@@ -0,0 +1,50 @@
+import {
+  loadVaultQmdConfig
+} from "./chunk-WIOLLGAD.js";
+import {
+  QmdUnavailableError,
+  hasQmd,
+  qmdEmbed
+} from "./chunk-5PJ4STIC.js";
+import {
+  resolveVaultPath
+} from "./chunk-GNJL4YGR.js";
+
+// src/commands/embed.ts
+async function embedCommand(options = {}) {
+  if (!hasQmd()) {
+    throw new QmdUnavailableError();
+  }
+  const vaultPath = resolveVaultPath({ explicitPath: options.vaultPath });
+  const qmdConfig = loadVaultQmdConfig(vaultPath);
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (!options.quiet) {
+    console.log(
+      `Embedding pending documents for collection "${qmdConfig.qmdCollection}" (root: ${qmdConfig.qmdRoot})...`
+    );
+  }
+  qmdEmbed(qmdConfig.qmdCollection);
+  const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (!options.quiet) {
+    console.log(`\u2713 Embedding complete for "${qmdConfig.qmdCollection}"`);
+  }
+  return {
+    vaultPath,
+    qmdCollection: qmdConfig.qmdCollection,
+    qmdRoot: qmdConfig.qmdRoot,
+    startedAt,
+    finishedAt
+  };
+}
+function registerEmbedCommand(program) {
+  program.command("embed").description("Run qmd embedding for pending vault documents").option("-v, --vault <path>", "Vault path").action(async (rawOptions) => {
+    await embedCommand({
+      vaultPath: rawOptions.vault
+    });
+  });
+}
+
+export {
+  embedCommand,
+  registerEmbedCommand
+};

package/dist/chunk-ERNE2FZ5.js

@@ -0,0 +1,189 @@
+import {
+  create,
+  read,
+  update
+} from "./chunk-HR4KN6S2.js";
+import {
+  append,
+  currentOwner
+} from "./chunk-K7PNYS45.js";
+import {
+  THREAD_STATUS_TRANSITIONS
+} from "./chunk-WMGIIABP.js";
+import {
+  __export
+} from "./chunk-U67V476Y.js";
+
+// src/workgraph/thread.ts
+var thread_exports = {};
+__export(thread_exports, {
+  block: () => block,
+  cancel: () => cancel,
+  claim: () => claim,
+  createThread: () => createThread,
+  decompose: () => decompose,
+  done: () => done,
+  release: () => release,
+  unblock: () => unblock
+});
+function createThread(vaultPath, title, goal, actor, opts = {}) {
+  return create(vaultPath, "thread", {
+    title,
+    goal,
+    status: "open",
+    priority: opts.priority ?? "medium",
+    deps: opts.deps ?? [],
+    parent: opts.parent,
+    context_refs: opts.context_refs ?? [],
+    tags: opts.tags ?? []
+  }, `## Goal
+
+${goal}
+`, actor);
+}
+function claim(vaultPath, threadPath, actor) {
+  const thread = read(vaultPath, threadPath);
+  if (!thread) throw new Error(`Thread not found: ${threadPath}`);
+  const status = thread.fields.status;
+  if (status !== "open") {
+    throw new Error(`Cannot claim thread in "${status}" state. Only "open" threads can be claimed.`);
+  }
+  const owner = currentOwner(vaultPath, threadPath);
+  if (owner) {
+    throw new Error(`Thread already claimed by "${owner}". Wait for release or use a different thread.`);
+  }
+  append(vaultPath, actor, "claim", threadPath, "thread");
+  return update(vaultPath, threadPath, {
+    status: "active",
+    owner: actor
+  }, void 0, actor);
+}
+function release(vaultPath, threadPath, actor, reason) {
+  const thread = read(vaultPath, threadPath);
+  if (!thread) throw new Error(`Thread not found: ${threadPath}`);
+  assertOwner(vaultPath, threadPath, actor);
+  append(
+    vaultPath,
+    actor,
+    "release",
+    threadPath,
+    "thread",
+    reason ? { reason } : void 0
+  );
+  return update(vaultPath, threadPath, {
+    status: "open",
+    owner: null
+  }, void 0, actor);
+}
+function block(vaultPath, threadPath, actor, blockedBy, reason) {
+  const thread = read(vaultPath, threadPath);
+  if (!thread) throw new Error(`Thread not found: ${threadPath}`);
+  assertTransition(thread.fields.status, "blocked");
+  append(vaultPath, actor, "block", threadPath, "thread", {
+    blocked_by: blockedBy,
+    ...reason ? { reason } : {}
+  });
+  const currentDeps = thread.fields.deps ?? [];
+  const updatedDeps = currentDeps.includes(blockedBy) ? currentDeps : [...currentDeps, blockedBy];
+  return update(vaultPath, threadPath, {
+    status: "blocked",
+    deps: updatedDeps
+  }, void 0, actor);
+}
+function unblock(vaultPath, threadPath, actor) {
+  const thread = read(vaultPath, threadPath);
+  if (!thread) throw new Error(`Thread not found: ${threadPath}`);
+  assertTransition(thread.fields.status, "active");
+  append(vaultPath, actor, "unblock", threadPath, "thread");
+  return update(vaultPath, threadPath, {
+    status: "active"
+  }, void 0, actor);
+}
+function done(vaultPath, threadPath, actor, output) {
+  const thread = read(vaultPath, threadPath);
+  if (!thread) throw new Error(`Thread not found: ${threadPath}`);
+  assertTransition(thread.fields.status, "done");
+  assertOwner(vaultPath, threadPath, actor);
+  append(
+    vaultPath,
+    actor,
+    "done",
+    threadPath,
+    "thread",
+    output ? { output } : void 0
+  );
+  const newBody = output ? `${thread.body}
+
+## Output
+
+${output}
+` : thread.body;
+  return update(vaultPath, threadPath, {
+    status: "done"
+  }, newBody, actor);
+}
+function cancel(vaultPath, threadPath, actor, reason) {
+  const thread = read(vaultPath, threadPath);
+  if (!thread) throw new Error(`Thread not found: ${threadPath}`);
+  assertTransition(thread.fields.status, "cancelled");
+  append(
+    vaultPath,
+    actor,
+    "cancel",
+    threadPath,
+    "thread",
+    reason ? { reason } : void 0
+  );
+  return update(vaultPath, threadPath, {
+    status: "cancelled",
+    owner: null
+  }, void 0, actor);
+}
+function decompose(vaultPath, parentPath, subthreads, actor) {
+  const parent = read(vaultPath, parentPath);
+  if (!parent) throw new Error(`Thread not found: ${parentPath}`);
+  const created = [];
+  for (const sub of subthreads) {
+    const inst = createThread(vaultPath, sub.title, sub.goal, actor, {
+      parent: parentPath,
+      deps: sub.deps
+    });
+    created.push(inst);
+  }
+  const childRefs = created.map((c) => `[[${c.path}]]`);
+  const decomposeNote = `
+
+## Sub-threads
+
+${childRefs.map((r) => `- ${r}`).join("\n")}
+`;
+  update(vaultPath, parentPath, {}, parent.body + decomposeNote, actor);
+  append(vaultPath, actor, "decompose", parentPath, "thread", {
+    children: created.map((c) => c.path)
+  });
+  return created;
+}
+function assertTransition(from, to) {
+  const allowed = THREAD_STATUS_TRANSITIONS[from];
+  if (!allowed?.includes(to)) {
+    throw new Error(`Invalid transition: "${from}" \u2192 "${to}". Allowed: ${allowed?.join(", ") ?? "none"}`);
+  }
+}
+function assertOwner(vaultPath, threadPath, actor) {
+  const owner = currentOwner(vaultPath, threadPath);
+  if (owner && owner !== actor) {
+    throw new Error(`Thread is owned by "${owner}", not "${actor}". Only the owner can perform this action.`);
+  }
+}
+
+export {
+  createThread,
+  claim,
+  release,
+  block,
+  unblock,
+  done,
+  cancel,
+  decompose,
+  thread_exports
+};