@anmol-srv/sigil 0.10.3

package/prompts/default-extraction.md

@@ -0,0 +1,35 @@
+You are extracting structured facts from a document in a personal knowledge base. Extract every discrete, atomic fact that would be useful for someone querying this knowledge base later.
+
+## Categories
+
+1. **preference** — Personal likes, dislikes, favorites, preferred tools/foods/methods
+2. **opinion** — Personal views, assessments, evaluations of tools/concepts/approaches
+3. **personal** — Personal facts: birthday, workplace, location, biographical details
+4. **experience** — Personal experiences: projects built, tools used, skills acquired, years of use
+5. **business_rule** — Organizational rules, policies, constraints, requirements
+6. **workflow** — Process flows, state transitions, step-by-step procedures
+7. **architecture** — System design, service interactions, infrastructure decisions
+8. **convention** — Coding patterns, naming rules, team standards, style guidelines
+9. **decision** — Why choices were made, tradeoffs considered, alternatives rejected
+10. **domain_knowledge** — Domain-specific terminology, concepts, definitions
+11. **key_insight** — Important takeaways, notable explanations, lessons learned
+12. **metric** — Quantitative data, measurements, statistics, benchmarks
+13. **issue** — Known problems, bugs, limitations, risks, caveats
+14. **action_item** — Tasks, follow-ups, assignments, deadlines, TODOs
+
+## Rules
+
+- Each fact must be **self-contained** — include enough context (names, identifiers) so the fact makes sense without the source document.
+- Facts should be **atomic** — one idea per fact. Don't combine multiple facts into one.
+- Include **specific details** — numbers, names, identifiers, exact values when available. **Never paraphrase or drop specific terms** (brand names, technical terms, model names, proper nouns). "sodium vapor lamps" must appear as "sodium vapor lamps", not just "lamps".
+- Do NOT extract generic knowledge (widely known programming concepts, common definitions). Only extract facts specific to THIS document and THIS person/organization.
+- Use personal categories (preference, opinion, personal, experience) when the content expresses subjective or biographical information. Use knowledge categories for objective/organizational information.
+- Set confidence to "high" when the fact comes directly from explicit statements. Set to "medium" for facts inferred or summarized. Set to "low" for uncertain or speculative information.
+- Set importance to "vital" if the fact is essential to understanding the topic — core preferences, key decisions, critical constraints. Set to "supplementary" for supporting details, examples, or background context.
+- Aim for 5-20 facts per document depending on length and density. Don't pad with low-value facts, but don't miss important details either.
+
+## Anti-Redundancy Rules
+
+- **No rephrased duplicates.** If you already extracted a fact about a topic, don't extract the same thing in different words.
+- **Combine related items.** If multiple items convey the same point, combine into one fact.
+- **Be specific, not generic.** "I prefer Fastify over Express for Node.js APIs" is good. "The user has framework preferences" is bad.

package/prompts/entity-extraction.md

@@ -0,0 +1,37 @@
+You are extracting topic entities from a set of facts in an organizational knowledge base.
+A "topic" is a distinct concept, technology, system, process, or subject referenced in the facts.
+
+## Rules
+
+- Extract 3-8 topics. Only meaningful, distinct topics.
+- Use canonical names: "normalization" not "database normalization concepts", "React hooks" not "React.js hooks pattern".
+- If two facts mention the same topic with different wording, extract it once with the canonical name.
+- Include a brief description (1 sentence) for context.
+- Do NOT extract generic terms like "programming", "coding", "software". Be specific.
+- Do NOT extract people names or document titles — those are handled separately.
+- Topics should be reusable across documents — "database indexing" not "the indexing discussion in doc 12".
+
+## Rename contexts — ALWAYS extract BOTH names
+
+When the source mentions a rename ("X is now named Y", "X has been renamed to Y", "X used to be called Y", "we renamed X to Y", etc.) — extract **both** the old and new names as separate topic entries. Do not collapse the rename into a single topic. The downstream entity resolver needs both names so it can recognise the rename and merge them into one entity with the old name preserved as an alias. Skipping the old name will cause the system to create a duplicate entity.
+
+## Output Format
+
+Respond with ONLY a JSON array. Each item:
+- "name" (string): canonical topic name, lowercase
+- "description" (string): one-sentence description of what this topic covers in context
+
+Example:
+[
+  { "name": "3NF normalization", "description": "Third normal form and eliminating transitive dependencies in relational databases" },
+  { "name": "foreign key cascades", "description": "CASCADE vs SET NULL behavior when deleting referenced rows" },
+  { "name": "query optimization", "description": "Techniques for improving SQL query performance including indexing and query plans" }
+]
+
+Rename example — note BOTH names are extracted:
+Input: "Smara is now named Sigil"
+Output:
+[
+  { "name": "smara", "description": "the project's previous name (renamed)" },
+  { "name": "sigil", "description": "the project's current name; was previously called Smara" }
+]

package/prompts/input-classifier.md

@@ -0,0 +1,23 @@
+Classify this input for a personal knowledge base. Determine how it should be stored.
+
+## Routes
+
+- **thought**: Short personal statement — preference, opinion, note, personal fact, experience. Extract facts directly. No chunking needed.
+- **knowledge**: Structured information with substance — explanations, rules, procedures, technical content. Needs full extraction pipeline.
+- **noise**: Not worth storing — greetings, incomplete fragments, test input, nonsense. Skip entirely.
+
+## Categories for extracted facts
+
+preference, opinion, personal, experience, business_rule, workflow, architecture, convention, decision, domain_knowledge, key_insight, metric, issue, action_item
+
+## Rules
+
+- If input expresses a preference, opinion, personal fact, or experience, route as "thought"
+- For "thought" route: extract 1-3 atomic facts. Each fact must be self-contained.
+- **Preserve all specific details verbatim** — technical terms, brand names, proper nouns, measurements, model names. Never paraphrase, generalize, or drop specifics. "sodium vapor streetlamps" must stay "sodium vapor streetlamps", not become "streetlamps".
+- If the input mentions multiple specific things (e.g. "amber, sodium vapor, streetlamps"), include all of them in the fact content.
+- For "knowledge" route: set facts to empty array (the pipeline will extract them)
+- For "noise" route: set facts to empty array
+- Always list mentioned entities (people, tools, technologies, places, concepts)
+- Confidence: "high" for explicit statements, "medium" for inferred
+- Importance: "vital" for core preferences/facts, "supplementary" for casual mentions

package/prompts/query-router.md

@@ -0,0 +1,18 @@
+Classify the intent of this search query for a personal knowledge base.
+
+## Intents
+
+- **preference**: Asking about likes, dislikes, preferences, opinions ("which fruit do I like", "what's my favorite tool", "do I prefer X or Y")
+- **factual**: Asking for specific information ("how does X work", "what is the rule for Y", "what BLEU score did the model achieve")
+- **entity_lookup**: Looking up a specific person, tool, system, or concept by name ("tell me about Redis", "what do I know about John")
+- **exploratory**: Broad exploration of a topic ("everything about auth", "what do I know about databases", "summarize my knowledge on X")
+- **temporal**: Time-dependent query ("what changed last month", "what was the status in January")
+
+## Rules
+
+- For preference: set categories to ["preference", "opinion", "personal"]
+- For factual: set categories to [] (search all categories)
+- For entity_lookup: set entities to the entity name(s), categories to []
+- For exploratory: set expand to true, categories to []
+- For temporal: extract the time reference as an ISO date in pointInTime
+- Always list entity names mentioned in the query

package/src/db/migrations/20260310120000_create-cortex-document-table.cjs

@@ -0,0 +1,21 @@
+exports.up = function (knex) {
+  return knex.raw('CREATE EXTENSION IF NOT EXISTS vector').then(() =>
+    knex.schema.createTable('document', (table) => {
+      table.increments('id').primary();
+      table.text('uid').notNullable().unique();
+      table.text('source_path').notNullable();
+      table.text('source_type').notNullable();
+      table.text('title');
+      table.text('content_hash');
+      table.text('namespace').notNullable().index();
+      table.integer('chunk_count').defaultTo(0);
+      table.integer('fact_count').defaultTo(0);
+      table.timestamp('last_ingested_at');
+      table.timestamps(false, true);
+    })
+  );
+};
+
+exports.down = function (knex) {
+  return knex.schema.dropTable('document');
+};

package/src/db/migrations/20260310120001_create-cortex-chunk-table.cjs

@@ -0,0 +1,37 @@
+exports.up = function (knex) {
+  return knex.schema
+    .createTable('chunk', (table) => {
+      table.increments('id').primary();
+      table
+        .integer('document_id')
+        .notNullable()
+        .references('id')
+        .inTable('document')
+        .onDelete('CASCADE');
+      table.integer('chunk_index').notNullable();
+      table.text('content').notNullable();
+      table.text('section_heading');
+      table.text('namespace').notNullable().index();
+      table.specificType('search_vector', 'tsvector');
+      table.timestamps(false, true);
+    })
+    .then(() =>
+      knex.raw(
+        `ALTER TABLE chunk ADD COLUMN embedding vector(768)`
+      )
+    )
+    .then(() =>
+      knex.raw(
+        `CREATE INDEX chunk_embedding_idx ON chunk USING hnsw (embedding vector_cosine_ops)`
+      )
+    )
+    .then(() =>
+      knex.raw(
+        `CREATE INDEX chunk_search_idx ON chunk USING gin (search_vector)`
+      )
+    );
+};
+
+exports.down = function (knex) {
+  return knex.schema.dropTable('chunk');
+};

package/src/db/migrations/20260310120002_create-cortex-fact-table.cjs

@@ -0,0 +1,37 @@
+exports.up = function (knex) {
+  return knex.schema
+    .createTable('fact', (table) => {
+      table.increments('id').primary();
+      table.text('uid').notNullable().unique();
+      table.text('content').notNullable();
+      table.text('category').notNullable().index();
+      table.text('confidence').defaultTo('medium');
+      table.text('namespace').notNullable().index();
+      table.text('status').notNullable().defaultTo('active').index();
+      table.integer('contradicted_by_id').references('id').inTable('fact');
+      table.integer('superseded_by_id').references('id').inTable('fact');
+      table.specificType('source_document_ids', 'integer[]');
+      table.text('source_section');
+      table.specificType('search_vector', 'tsvector');
+      table.timestamps(false, true);
+    })
+    .then(() =>
+      knex.raw(
+        `ALTER TABLE fact ADD COLUMN embedding vector(768)`
+      )
+    )
+    .then(() =>
+      knex.raw(
+        `CREATE INDEX fact_embedding_idx ON fact USING hnsw (embedding vector_cosine_ops)`
+      )
+    )
+    .then(() =>
+      knex.raw(
+        `CREATE INDEX fact_search_idx ON fact USING gin (search_vector)`
+      )
+    );
+};
+
+exports.down = function (knex) {
+  return knex.schema.dropTable('fact');
+};

package/src/db/migrations/20260310120003_create-cortex-entity-table.cjs

@@ -0,0 +1,26 @@
+exports.up = function (knex) {
+  return knex.schema
+    .createTable('entity', (table) => {
+      table.increments('id').primary();
+      table.text('uid').notNullable().unique();
+      table.text('name').notNullable();
+      table.text('entity_type').notNullable().index();
+      table.text('description');
+      table.integer('mention_count').defaultTo(0);
+      table.timestamps(false, true);
+    })
+    .then(() =>
+      knex.raw(
+        `ALTER TABLE entity ADD COLUMN embedding vector(768)`
+      )
+    )
+    .then(() =>
+      knex.raw(
+        `CREATE INDEX entity_embedding_idx ON entity USING hnsw (embedding vector_cosine_ops)`
+      )
+    );
+};
+
+exports.down = function (knex) {
+  return knex.schema.dropTable('entity');
+};

package/src/db/migrations/20260310120004_create-cortex-relation-table.cjs

@@ -0,0 +1,27 @@
+exports.up = function (knex) {
+  return knex.schema.createTable('relation', (table) => {
+    table.increments('id').primary();
+    table
+      .integer('source_id')
+      .notNullable()
+      .references('id')
+      .inTable('entity')
+      .onDelete('CASCADE');
+    table
+      .integer('target_id')
+      .notNullable()
+      .references('id')
+      .inTable('entity')
+      .onDelete('CASCADE');
+    table.text('relation_type').notNullable().index();
+    table.integer('source_fact_id').references('id').inTable('fact');
+    table.integer('mention_count').defaultTo(1);
+    table.timestamp('valid_at');
+    table.timestamp('invalid_at');
+    table.timestamps(false, true);
+  });
+};
+
+exports.down = function (knex) {
+  return knex.schema.dropTable('relation');
+};

package/src/db/migrations/20260310120005_create-cortex-history-table.cjs

@@ -0,0 +1,16 @@
+exports.up = function (knex) {
+  return knex.schema.createTable('history', (table) => {
+    table.increments('id').primary();
+    table.text('target_type').notNullable();
+    table.integer('target_id').notNullable();
+    table.text('event').notNullable();
+    table.text('old_content');
+    table.text('new_content');
+    table.text('triggered_by');
+    table.timestamps(false, true);
+  });
+};
+
+exports.down = function (knex) {
+  return knex.schema.dropTable('history');
+};

package/src/db/migrations/20260311120000_add-entity-namespace-and-relation-indexes.cjs

@@ -0,0 +1,32 @@
+exports.up = function (knex) {
+  return knex.schema
+    .alterTable('entity', (table) => {
+      table.text('namespace').defaultTo('product/lms').index();
+      table.text('external_id');
+      table.unique(['name', 'entity_type', 'namespace']);
+    })
+    .then(() =>
+      knex.raw(`
+        CREATE INDEX relation_source_type_idx
+          ON relation (source_id, relation_type)
+          WHERE invalid_at IS NULL;
+        CREATE INDEX relation_target_type_idx
+          ON relation (target_id, relation_type)
+          WHERE invalid_at IS NULL;
+      `)
+    );
+};
+
+exports.down = function (knex) {
+  return knex.raw(`
+    DROP INDEX IF EXISTS relation_target_type_idx;
+    DROP INDEX IF EXISTS relation_source_type_idx;
+  `)
+    .then(() =>
+      knex.schema.alterTable('entity', (table) => {
+        table.dropUnique(['name', 'entity_type', 'namespace']);
+        table.dropColumn('external_id');
+        table.dropColumn('namespace');
+      })
+    );
+};

package/src/db/migrations/20260312120000_add-fact-entity-linking.cjs

@@ -0,0 +1,22 @@
+exports.up = function (knex) {
+  return knex.schema
+    .createTable('fact_entity', (table) => {
+      table.increments('id').primary();
+      table.integer('fact_id').notNullable().references('id').inTable('fact').onDelete('CASCADE');
+      table.integer('entity_id').notNullable().references('id').inTable('entity').onDelete('CASCADE');
+      table.text('mention_type').defaultTo('content');
+      table.integer('mention_count').defaultTo(1);
+      table.timestamps(false, true);
+    })
+    .then(() =>
+      knex.raw(`
+        CREATE INDEX fact_entity_fact_id_idx ON fact_entity (fact_id);
+        CREATE INDEX fact_entity_entity_id_idx ON fact_entity (entity_id);
+        CREATE UNIQUE INDEX fact_entity_unique_idx ON fact_entity (fact_id, entity_id, mention_type);
+      `)
+    );
+};
+
+exports.down = function (knex) {
+  return knex.schema.dropTable('fact_entity');
+};

package/src/db/migrations/20260313093130_create-api-key-table.cjs

@@ -0,0 +1,15 @@
+exports.up = function (knex) {
+  return knex.schema.createTable('api_key', (table) => {
+    table.increments('id').primary();
+    table.text('key_hash').notNullable().unique();
+    table.text('name').notNullable();
+    table.specificType('namespaces', 'text[]').notNullable().defaultTo('{}');
+    table.text('role').notNullable().defaultTo('reader');
+    table.boolean('active').notNullable().defaultTo(true);
+    table.timestamps(false, true);
+  });
+};
+
+exports.down = function (knex) {
+  return knex.schema.dropTable('api_key');
+};

package/src/db/migrations/20260313120000_add-entity-dedup-support.cjs

@@ -0,0 +1,13 @@
+exports.up = function (knex) {
+  return knex.schema.table('entity', (table) => {
+    table.text('entity_types').nullable();
+    table.integer('merged_with').nullable().references('id').inTable('entity');
+  });
+};
+
+exports.down = function (knex) {
+  return knex.schema.table('entity', (table) => {
+    table.dropColumn('entity_types');
+    table.dropColumn('merged_with');
+  });
+};

package/src/db/migrations/20260313150000_create-connector-tables.cjs

@@ -0,0 +1,46 @@
+exports.up = function (knex) {
+  return knex.schema
+    .createTable('connection', (table) => {
+      table.increments('id').primary();
+      table.text('uid').notNullable().unique();
+      table.text('name').notNullable();
+      table.text('connector_type').notNullable();
+      table.jsonb('config').notNullable().defaultTo('{}');
+      table.binary('credentials_encrypted');
+      table.text('namespace').notNullable();
+      table.text('status').notNullable().defaultTo('pending');
+      table.timestamp('last_check_at');
+      table.timestamps(false, true);
+    })
+    .createTable('sync_run', (table) => {
+      table.increments('id').primary();
+      table.text('uid').notNullable().unique();
+      table.integer('connection_id').notNullable().references('id').inTable('connection').onDelete('CASCADE');
+      table.text('pipeline_type').notNullable();
+      table.text('sync_type').notNullable().defaultTo('full');
+      table.text('status').notNullable().defaultTo('pending');
+      table.jsonb('state_before');
+      table.jsonb('state_after');
+      table.integer('records_read').defaultTo(0);
+      table.integer('records_written').defaultTo(0);
+      table.text('error_message');
+      table.timestamp('started_at');
+      table.timestamp('completed_at');
+      table.timestamps(false, true);
+    })
+    .createTable('sync_schedule', (table) => {
+      table.increments('id').primary();
+      table.integer('connection_id').notNullable().references('id').inTable('connection').onDelete('CASCADE');
+      table.text('cron_expression');
+      table.text('sync_type').notNullable().defaultTo('incremental');
+      table.boolean('enabled').notNullable().defaultTo(true);
+      table.timestamps(false, true);
+    });
+};
+
+exports.down = function (knex) {
+  return knex.schema
+    .dropTableIfExists('sync_schedule')
+    .dropTableIfExists('sync_run')
+    .dropTableIfExists('connection');
+};

package/src/db/migrations/20260318120000_add-contextual-chunk-prefix.cjs

@@ -0,0 +1,11 @@
+exports.up = function (knex) {
+  return knex.schema.alterTable('chunk', (table) => {
+    table.text('contextual_prefix');
+  });
+};
+
+exports.down = function (knex) {
+  return knex.schema.alterTable('chunk', (table) => {
+    table.dropColumn('contextual_prefix');
+  });
+};

package/src/db/migrations/20260318120001_add-fact-temporal-validity.cjs

@@ -0,0 +1,15 @@
+exports.up = function (knex) {
+  return knex.schema
+    .alterTable('fact', (table) => {
+      table.timestamp('valid_from');
+      table.timestamp('valid_until');
+    })
+    .then(() => knex.raw('UPDATE fact SET valid_from = created_at'));
+};
+
+exports.down = function (knex) {
+  return knex.schema.alterTable('fact', (table) => {
+    table.dropColumn('valid_from');
+    table.dropColumn('valid_until');
+  });
+};

package/src/db/migrations/20260318120002_add-fact-importance.cjs

@@ -0,0 +1,11 @@
+exports.up = function (knex) {
+  return knex.schema.alterTable('fact', (table) => {
+    table.text('importance').defaultTo('supplementary');
+  });
+};
+
+exports.down = function (knex) {
+  return knex.schema.alterTable('fact', (table) => {
+    table.dropColumn('importance');
+  });
+};

package/src/db/migrations/20260318120003_add-fact-access-tracking.cjs

@@ -0,0 +1,13 @@
+exports.up = function (knex) {
+  return knex.schema.alterTable('fact', (table) => {
+    table.integer('access_count').defaultTo(0);
+    table.timestamp('last_accessed_at');
+  });
+};
+
+exports.down = function (knex) {
+  return knex.schema.alterTable('fact', (table) => {
+    table.dropColumn('access_count');
+    table.dropColumn('last_accessed_at');
+  });
+};

package/src/db/migrations/20260405120000_add-unique-constraints.cjs

@@ -0,0 +1,58 @@
+exports.up = async function (knex) {
+  // Count duplicates before deleting so the operator knows what was removed
+  const docDupes = await knex.raw(`
+    SELECT COUNT(*) AS cnt FROM document
+    WHERE id NOT IN (SELECT MAX(id) FROM document GROUP BY source_path)
+  `);
+  const docCount = parseInt(docDupes.rows?.[0]?.cnt ?? 0, 10);
+  if (docCount > 0) {
+    console.warn(`[migration] Removing ${docCount} duplicate document rows (keeping latest per source_path)`);
+  }
+
+  await knex.raw(`
+    DELETE FROM document
+    WHERE id NOT IN (
+      SELECT MAX(id) FROM document GROUP BY source_path
+    )
+  `);
+
+  await knex.schema.alterTable('document', (table) => {
+    table.unique('source_path');
+  });
+
+  const relDupes = await knex.raw(`
+    SELECT COUNT(*) AS cnt FROM relation
+    WHERE id NOT IN (
+      SELECT MAX(id) FROM relation
+      WHERE invalid_at IS NULL
+      GROUP BY source_id, target_id, relation_type
+    )
+  `);
+  const relCount = parseInt(relDupes.rows?.[0]?.cnt ?? 0, 10);
+  if (relCount > 0) {
+    console.warn(`[migration] Removing ${relCount} duplicate relation rows (keeping latest per source/target/type)`);
+  }
+
+  await knex.raw(`
+    DELETE FROM relation
+    WHERE id NOT IN (
+      SELECT MAX(id) FROM relation
+      WHERE invalid_at IS NULL
+      GROUP BY source_id, target_id, relation_type
+    )
+  `);
+
+  await knex.schema.alterTable('relation', (table) => {
+    table.unique(['source_id', 'target_id', 'relation_type']);
+  });
+};
+
+exports.down = async function (knex) {
+  await knex.schema.alterTable('relation', (table) => {
+    table.dropUnique(['source_id', 'target_id', 'relation_type']);
+  });
+
+  await knex.schema.alterTable('document', (table) => {
+    table.dropUnique('source_path');
+  });
+};

package/src/db/migrations/20260405140000_create-llm-log-table.cjs

@@ -0,0 +1,21 @@
+exports.up = function (knex) {
+  return knex.schema.createTable('llm_log', (table) => {
+    table.increments('id').primary();
+    table.text('provider').notNullable().index();
+    table.text('model').notNullable().index();
+    table.text('caller').index();
+    table.text('input');
+    table.text('response');
+    table.integer('input_tokens').defaultTo(0);
+    table.integer('output_tokens').defaultTo(0);
+    table.decimal('cost', 10, 6).defaultTo(0);
+    table.integer('duration_ms').defaultTo(0);
+    table.text('status').defaultTo('success').index();
+    table.text('error');
+    table.timestamp('created_at').defaultTo(knex.fn.now());
+  });
+};
+
+exports.down = function (knex) {
+  return knex.schema.dropTable('llm_log');
+};

package/src/db/migrations/20260424120000_split-fact-lifecycle.cjs

@@ -0,0 +1,86 @@
+/**
+ * Split volatile lifecycle state (access_count, last_accessed_at) off the fact row
+ * into a dedicated fact_lifecycle table.
+ *
+ * Reason: Postgres HNSW indexes cannot do HOT updates. When a column on a row with
+ * an HNSW index is UPDATEd — even a column unrelated to the embedding — Postgres
+ * creates a new tuple and rewrites the index entry. At high search volume, this
+ * causes catastrophic HNSW index bloat and autovacuum pressure.
+ *
+ * Fix: keep the fact row read-mostly. Lifecycle state (access_count, last_accessed_at)
+ * lives in fact_lifecycle with a FK and a trigger for auto-insert on new facts.
+ */
+
+exports.up = async function (knex) {
+  await knex.schema.createTable('fact_lifecycle', (table) => {
+    table.bigInteger('fact_id').primary().references('id').inTable('fact').onDelete('CASCADE');
+    table.integer('access_count').notNullable().defaultTo(0);
+    table.timestamp('last_accessed_at');
+    table.string('stage').notNullable().defaultTo('fresh'); // fresh | stable | editing
+    table.timestamp('stage_entered_at').notNullable().defaultTo(knex.fn.now());
+    table.timestamp('created_at').notNullable().defaultTo(knex.fn.now());
+
+    table.index('last_accessed_at');
+    table.index(['stage', 'stage_entered_at']);
+  });
+
+  // Backfill existing facts into fact_lifecycle
+  await knex.raw(`
+    INSERT INTO fact_lifecycle (fact_id, access_count, last_accessed_at, stage, stage_entered_at, created_at)
+    SELECT
+      id,
+      COALESCE(access_count, 0),
+      last_accessed_at,
+      'stable' AS stage,
+      COALESCE(created_at, NOW()) AS stage_entered_at,
+      COALESCE(created_at, NOW()) AS created_at
+    FROM fact
+    ON CONFLICT (fact_id) DO NOTHING
+  `);
+
+  // Trigger to auto-insert a lifecycle row when a new fact is inserted.
+  await knex.raw(`
+    CREATE OR REPLACE FUNCTION fact_init_lifecycle() RETURNS trigger AS $$
+    BEGIN
+      INSERT INTO fact_lifecycle (fact_id, access_count, last_accessed_at, stage, stage_entered_at, created_at)
+      VALUES (NEW.id, 0, NULL, 'fresh', NOW(), NOW())
+      ON CONFLICT (fact_id) DO NOTHING;
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+  `);
+
+  await knex.raw(`
+    DROP TRIGGER IF EXISTS fact_init_lifecycle_trigger ON fact;
+    CREATE TRIGGER fact_init_lifecycle_trigger
+      AFTER INSERT ON fact
+      FOR EACH ROW EXECUTE FUNCTION fact_init_lifecycle();
+  `);
+
+  // Drop the old columns from fact — these have moved to fact_lifecycle.
+  await knex.schema.alterTable('fact', (table) => {
+    table.dropColumn('access_count');
+    table.dropColumn('last_accessed_at');
+  });
+};
+
+exports.down = async function (knex) {
+  // Re-add columns to fact
+  await knex.schema.alterTable('fact', (table) => {
+    table.integer('access_count').defaultTo(0);
+    table.timestamp('last_accessed_at');
+  });
+
+  // Copy data back
+  await knex.raw(`
+    UPDATE fact f
+    SET access_count = fl.access_count,
+        last_accessed_at = fl.last_accessed_at
+    FROM fact_lifecycle fl
+    WHERE f.id = fl.fact_id
+  `);
+
+  await knex.raw('DROP TRIGGER IF EXISTS fact_init_lifecycle_trigger ON fact');
+  await knex.raw('DROP FUNCTION IF EXISTS fact_init_lifecycle()');
+  await knex.schema.dropTable('fact_lifecycle');
+};