create-principles-disciple 1.94.0 → 1.95.0

package/plugin/dist/core/principle-tree-ledger.js

@@ -1,527 +1,42 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { withLock, withLockAsync } from '../utils/file-lock.js';
-import { atomicWriteFileSync } from '../utils/io.js';
-const PRINCIPLE_TRAINING_FILE = 'principle_training_state.json';
-export const TREE_NAMESPACE = '_tree';
-const VALID_EVALUABILITIES = ['deterministic', 'weak_heuristic', 'manual_only'];
-const VALID_INTERNALIZATION_STATUSES = [
-    'prompt_only',
-    'needs_training',
-    'in_training',
-    'deployed_pending_eval',
-    'internalized',
-    'regressed',
-];
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function clampFloat(value, min, max, fallback) {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return fallback;
-    }
-    return Math.max(min, Math.min(max, value));
-}
-function clampInt(value, min, max, fallback) {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return fallback;
-    }
-    return Math.max(min, Math.min(max, Math.round(value)));
-}
-function stringArray(value) {
-    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
-}
-function uniqueStrings(values) {
-    return Array.from(new Set(values));
-}
-function createEmptyTree() {
-    return {
-        principles: {},
-        rules: {},
-        implementations: {},
-        metrics: {},
-        lastUpdated: new Date(0).toISOString(),
-    };
-}
-function parseLegacyTrainingStore(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const result = {};
-    for (const [principleId, candidate] of Object.entries(raw)) {
-        if (principleId === TREE_NAMESPACE || !isRecord(candidate)) {
-            continue;
-        }
-        if (candidate.principleId !== principleId) {
-            continue;
-        }
-        const evaluability = VALID_EVALUABILITIES.includes(candidate.evaluability)
-            ? candidate.evaluability
-            : 'manual_only';
-        const internalizationStatus = VALID_INTERNALIZATION_STATUSES.includes(candidate.internalizationStatus)
-            ? candidate.internalizationStatus
-            : 'prompt_only';
-        const rawLastEvalScore = candidate.lastEvalScore;
-        result[principleId] = {
-            principleId,
-            evaluability,
-            applicableOpportunityCount: clampInt(candidate.applicableOpportunityCount, 0, Number.POSITIVE_INFINITY, 0),
-            observedViolationCount: clampInt(candidate.observedViolationCount, 0, Number.POSITIVE_INFINITY, 0),
-            complianceRate: clampFloat(candidate.complianceRate, 0, 1, 0),
-            violationTrend: clampFloat(candidate.violationTrend, -1, 1, 0),
-            generatedSampleCount: clampInt(candidate.generatedSampleCount, 0, Number.POSITIVE_INFINITY, 0),
-            approvedSampleCount: clampInt(candidate.approvedSampleCount, 0, Number.POSITIVE_INFINITY, 0),
-            includedTrainRunIds: stringArray(candidate.includedTrainRunIds),
-            deployedCheckpointIds: stringArray(candidate.deployedCheckpointIds),
-            lastEvalScore: typeof rawLastEvalScore === 'number' && Number.isFinite(rawLastEvalScore)
-                ? clampFloat(rawLastEvalScore, 0, 1, 0)
-                : undefined,
-            internalizationStatus,
-        };
-    }
-    return result;
-}
-function parsePrinciples(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const principles = {};
-    for (const [id, value] of Object.entries(raw)) {
-        if (!isRecord(value)) {
-            continue;
-        }
-        const suggestedRules = stringArray(value.suggestedRules);
-        principles[id] = {
-            ...value,
-            id,
-            ruleIds: stringArray(value.ruleIds),
-            conflictsWithPrincipleIds: stringArray(value.conflictsWithPrincipleIds),
-            derivedFromPainIds: stringArray(value.derivedFromPainIds),
-            ...(Object.prototype.hasOwnProperty.call(value, 'suggestedRules') ? { suggestedRules } : {}),
-        };
-    }
-    return principles;
-}
-function parseRules(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const rules = {};
-    for (const [id, value] of Object.entries(raw)) {
-        if (!isRecord(value)) {
-            continue;
-        }
-        rules[id] = {
-            ...value,
-            id,
-            principleId: typeof value.principleId === 'string' ? value.principleId : '',
-            implementationIds: stringArray(value.implementationIds),
-        };
-    }
-    return rules;
-}
-function parseImplementations(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const implementations = {};
-    for (const [id, value] of Object.entries(raw)) {
-        if (!isRecord(value) || typeof value.ruleId !== 'string') {
-            continue;
-        }
-        implementations[id] = {
-            ...value,
-            id,
-            ruleId: value.ruleId,
-        };
-    }
-    return implementations;
-}
-function parseMetrics(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const metrics = {};
-    for (const [id, value] of Object.entries(raw)) {
-        if (!isRecord(value)) {
-            continue;
-        }
-        metrics[id] = {
-            ...value,
-            principleId: typeof value.principleId === 'string' ? value.principleId : id,
-        };
-    }
-    return metrics;
-}
-function parseTree(raw) {
-    if (!isRecord(raw)) {
-        return createEmptyTree();
-    }
-    return {
-        principles: parsePrinciples(raw.principles),
-        rules: parseRules(raw.rules),
-        implementations: parseImplementations(raw.implementations),
-        metrics: parseMetrics(raw.metrics),
-        lastUpdated: typeof raw.lastUpdated === 'string' ? raw.lastUpdated : new Date(0).toISOString(),
-    };
-}
-function serializeLedger(store) {
-    return JSON.stringify({
-        ...store.trainingStore,
-        [TREE_NAMESPACE]: {
-            ...store.tree,
-            lastUpdated: new Date().toISOString(),
-        },
-    }, null, 2);
-}
-function ensureParentDir(filePath) {
-    const dir = path.dirname(filePath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-}
-function readLedgerFromFile(filePath) {
-    if (!fs.existsSync(filePath)) {
-        return {
-            trainingStore: {},
-            tree: createEmptyTree(),
-        };
-    }
-    try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        if (!content || content.trim() === '') {
-            return { trainingStore: {}, tree: createEmptyTree() };
-        }
-        const parsed = JSON.parse(content);
-        const raw = isRecord(parsed) ? parsed : {};
-        // #219: Handle both formats:
-        // - New format: { trainingStore: {...}, tree: {...} }
-        // - Legacy format: { P_xxx: {...}, _tree: {...} }
-        const trainingStoreRaw = raw.trainingStore ?? raw;
-        const treeRaw = raw[TREE_NAMESPACE] ?? raw.tree;
-        return {
-            trainingStore: parseLegacyTrainingStore(trainingStoreRaw),
-            tree: parseTree(treeRaw),
-        };
-    }
-    catch (err) {
-        console.error(`[principle-tree-ledger] Failed to load ledger from ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
-        return { trainingStore: {}, tree: createEmptyTree() };
-    }
-}
-function writeLedgerUnlocked(filePath, store) {
-    ensureParentDir(filePath);
-    atomicWriteFileSync(filePath, serializeLedger(store));
-}
-function mutateLedger(stateDir, mutate) {
-    const filePath = getLedgerFilePath(stateDir);
-    return withLock(filePath, () => {
-        const store = readLedgerFromFile(filePath);
-        const result = mutate(store);
-        writeLedgerUnlocked(filePath, store);
-        return result;
-    });
-}
-async function mutateLedgerAsync(stateDir, mutate) {
-    const filePath = getLedgerFilePath(stateDir);
-    return withLockAsync(filePath, async () => {
-        const store = readLedgerFromFile(filePath);
-        const result = await mutate(store);
-        writeLedgerUnlocked(filePath, store);
-        return result;
-    });
-}
-export function getLedgerFilePath(stateDir) {
-    return path.join(stateDir, PRINCIPLE_TRAINING_FILE);
-}
-export function loadLedger(stateDir) {
-    return readLedgerFromFile(getLedgerFilePath(stateDir));
-}
-export function saveLedger(stateDir, store) {
-    mutateLedger(stateDir, (current) => {
-        current.trainingStore = store.trainingStore;
-        current.tree = store.tree;
-    });
-}
-export async function saveLedgerAsync(stateDir, store) {
-    await mutateLedgerAsync(stateDir, async (current) => {
-        current.trainingStore = store.trainingStore;
-        current.tree = store.tree;
-    });
-}
-export function updateTrainingStore(stateDir, mutate) {
-    mutateLedger(stateDir, (store) => {
-        mutate(store.trainingStore);
-    });
-}
 /**
- * Add a new principle directly to the ledger tree.
- * This is the companion to updatePrinciple() — use this when creating a NEW
- * principle so the compiler can find it in tree.principles.
+ * Principle Tree Ledger — plugin adapter (re-export) over @principles/core.
  *
- * Idempotent: if the principle already exists, overwrites (update semantics).
- */
-export function addPrincipleToLedger(stateDir, principle) {
-    return mutateLedger(stateDir, (store) => {
-        store.tree.principles[principle.id] = principle;
-        store.tree.lastUpdated = new Date().toISOString();
-        return principle;
-    });
-}
-export function createRule(stateDir, rule) {
-    return mutateLedger(stateDir, (store) => {
-        const principle = store.tree.principles[rule.principleId];
-        if (!principle) {
-            throw new Error(`Cannot create rule "${rule.id}" for missing principle "${rule.principleId}".`);
-        }
-        const nextRule = {
-            ...rule,
-            implementationIds: uniqueStrings(rule.implementationIds),
-        };
-        store.tree.rules[nextRule.id] = nextRule;
-        principle.ruleIds = uniqueStrings([...principle.ruleIds, nextRule.id]);
-        return nextRule;
-    });
-}
-export function createImplementation(stateDir, implementation) {
-    return mutateLedger(stateDir, (store) => {
-        const rule = store.tree.rules[implementation.ruleId];
-        if (!rule) {
-            throw new Error(`Cannot create implementation "${implementation.id}" for missing rule "${implementation.ruleId}".`);
-        }
-        store.tree.implementations[implementation.id] = implementation;
-        rule.implementationIds = uniqueStrings([...rule.implementationIds, implementation.id]);
-        return implementation;
-    });
-}
-export function updatePrinciple(stateDir, principleId, updates) {
-    return mutateLedger(stateDir, (store) => {
-        const existingPrinciple = store.tree.principles[principleId];
-        if (!existingPrinciple) {
-            throw new Error(`Cannot update missing principle "${principleId}".`);
-        }
-        const nextPrinciple = {
-            ...existingPrinciple,
-            ...updates,
-            id: principleId,
-            ruleIds: updates.ruleIds ? uniqueStrings(updates.ruleIds) : existingPrinciple.ruleIds,
-            conflictsWithPrincipleIds: updates.conflictsWithPrincipleIds
-                ? uniqueStrings(updates.conflictsWithPrincipleIds)
-                : existingPrinciple.conflictsWithPrincipleIds,
-            derivedFromPainIds: updates.derivedFromPainIds
-                ? uniqueStrings(updates.derivedFromPainIds)
-                : existingPrinciple.derivedFromPainIds,
-            ...(Object.prototype.hasOwnProperty.call(updates, 'suggestedRules')
-                ? { suggestedRules: uniqueStrings(updates.suggestedRules ?? []) }
-                : Object.prototype.hasOwnProperty.call(existingPrinciple, 'suggestedRules')
-                    ? { suggestedRules: existingPrinciple.suggestedRules }
-                    : {}),
-        };
-        store.tree.principles[principleId] = nextPrinciple;
-        return nextPrinciple;
-    });
-}
-export function updateRule(stateDir, ruleId, updates) {
-    return mutateLedger(stateDir, (store) => {
-        const existingRule = store.tree.rules[ruleId];
-        if (!existingRule) {
-            throw new Error(`Cannot update missing rule "${ruleId}".`);
-        }
-        const nextPrincipleId = updates.principleId ?? existingRule.principleId;
-        const nextPrinciple = store.tree.principles[nextPrincipleId];
-        if (!nextPrinciple) {
-            throw new Error(`Cannot move rule "${ruleId}" to missing principle "${nextPrincipleId}".`);
-        }
-        const nextRule = {
-            ...existingRule,
-            ...updates,
-            id: ruleId,
-            principleId: nextPrincipleId,
-            implementationIds: updates.implementationIds
-                ? uniqueStrings(updates.implementationIds)
-                : existingRule.implementationIds,
-        };
-        if (existingRule.principleId !== nextPrincipleId) {
-            const previousPrinciple = store.tree.principles[existingRule.principleId];
-            if (previousPrinciple) {
-                previousPrinciple.ruleIds = previousPrinciple.ruleIds.filter((candidateId) => candidateId !== ruleId);
-            }
-            nextPrinciple.ruleIds = uniqueStrings([...nextPrinciple.ruleIds, ruleId]);
-        }
-        store.tree.rules[ruleId] = nextRule;
-        return nextRule;
-    });
-}
-export function deleteRule(stateDir, ruleId) {
-    return mutateLedger(stateDir, (store) => {
-        const existingRule = store.tree.rules[ruleId];
-        if (!existingRule) {
-            return undefined;
-        }
-        const parentPrinciple = store.tree.principles[existingRule.principleId];
-        if (parentPrinciple) {
-            parentPrinciple.ruleIds = parentPrinciple.ruleIds.filter((candidateId) => candidateId !== ruleId);
-        }
-        const implementationIds = uniqueStrings([
-            ...existingRule.implementationIds,
-            ...Object.values(store.tree.implementations)
-                .filter((implementation) => implementation.ruleId === ruleId)
-                .map((implementation) => implementation.id),
-        ]);
-        for (const implementationId of implementationIds) {
-            delete store.tree.implementations[implementationId];
-        }
-        delete store.tree.rules[ruleId];
-        return existingRule;
-    });
-}
-export function updateImplementation(stateDir, implementationId, updates) {
-    return mutateLedger(stateDir, (store) => {
-        const existingImplementation = store.tree.implementations[implementationId];
-        if (!existingImplementation) {
-            throw new Error(`Cannot update missing implementation "${implementationId}".`);
-        }
-        const nextRuleId = updates.ruleId ?? existingImplementation.ruleId;
-        const nextRule = store.tree.rules[nextRuleId];
-        if (!nextRule) {
-            throw new Error(`Cannot move implementation "${implementationId}" to missing rule "${nextRuleId}".`);
-        }
-        const nextImplementation = {
-            ...existingImplementation,
-            ...updates,
-            id: implementationId,
-            ruleId: nextRuleId,
-        };
-        if (existingImplementation.ruleId !== nextRuleId) {
-            const previousRule = store.tree.rules[existingImplementation.ruleId];
-            if (previousRule) {
-                previousRule.implementationIds = previousRule.implementationIds.filter((candidateId) => candidateId !== implementationId);
-            }
-            nextRule.implementationIds = uniqueStrings([...nextRule.implementationIds, implementationId]);
-        }
-        store.tree.implementations[implementationId] = nextImplementation;
-        return nextImplementation;
-    });
-}
-export function deleteImplementation(stateDir, implementationId) {
-    return mutateLedger(stateDir, (store) => {
-        const existingImplementation = store.tree.implementations[implementationId];
-        if (!existingImplementation) {
-            return undefined;
-        }
-        const parentRule = store.tree.rules[existingImplementation.ruleId];
-        if (parentRule) {
-            parentRule.implementationIds = parentRule.implementationIds.filter((candidateId) => candidateId !== implementationId);
-        }
-        delete store.tree.implementations[implementationId];
-        return existingImplementation;
-    });
-}
-export function listImplementationsForRule(stateDir, ruleId) {
-    const ledger = loadLedger(stateDir);
-    const rule = ledger.tree.rules[ruleId];
-    if (!rule) {
-        return [];
-    }
-    return rule.implementationIds
-        .map((implementationId) => ledger.tree.implementations[implementationId])
-        .filter((implementation) => implementation !== undefined);
-}
-export function getPrincipleSubtree(stateDir, principleId) {
-    const ledger = loadLedger(stateDir);
-    const principle = ledger.tree.principles[principleId];
-    if (!principle) {
-        return undefined;
-    }
-    return {
-        principle,
-        rules: principle.ruleIds
-            .map((ruleId) => ledger.tree.rules[ruleId])
-            .filter((rule) => rule !== undefined)
-            .map((rule) => ({
-            rule,
-            implementations: rule.implementationIds
-                .map((implementationId) => ledger.tree.implementations[implementationId])
-                .filter((implementation) => implementation !== undefined),
-        })),
-    };
-}
-export function updatePrincipleValueMetrics(stateDir, principleId, metrics) {
-    return mutateLedger(stateDir, (store) => {
-        const nextMetrics = {
-            ...metrics,
-            principleId,
-        };
-        store.tree.metrics[principleId] = nextMetrics;
-        return nextMetrics;
-    });
-}
-// ---------------------------------------------------------------------------
-// Implementation Lifecycle State Transitions
-// ---------------------------------------------------------------------------
-/**
- * Valid lifecycle state transitions (per Phase 13 context D-15):
- *   candidate -> active      (promote)
- *   active -> disabled       (disable)
- *   disabled -> active       (re-enable via promote)
- *   disabled -> archived     (permanent disable)
- *   active -> archived       (direct archive)
- *   candidate -> archived    (rejected candidate cleanup)
- */
-const VALID_LIFECYCLE_TRANSITIONS = {
-    candidate: ['active', 'archived'],
-    active: ['disabled', 'archived'],
-    disabled: ['active', 'archived'],
-    archived: [],
-};
-/**
- * Validate a lifecycle state transition.
- * Returns true if the transition is valid, false otherwise.
- */
-export function isValidLifecycleTransition(from, to) {
-    return VALID_LIFECYCLE_TRANSITIONS[from]?.includes(to) ?? false;
-}
-/**
- * Get allowed transitions for a given lifecycle state.
- */
-export function getAllowedTransitions(from) {
-    return VALID_LIFECYCLE_TRANSITIONS[from] ?? [];
-}
-/**
- * Transition an implementation's lifecycle state with validation.
- * Throws on invalid transitions */
-export function transitionImplementationState(stateDir, implementationId, newState) {
-    return mutateLedger(stateDir, (store) => {
-        const impl = store.tree.implementations[implementationId];
-        if (!impl) {
-            throw new Error(`Implementation not found: ${implementationId}`);
-        }
-        const currentState = impl.lifecycleState ?? 'candidate';
-        if (!isValidLifecycleTransition(currentState, newState)) {
-            const allowed = getAllowedTransitions(currentState);
-            throw new Error(`Invalid lifecycle transition: ${currentState} -> ${newState}. ` +
-                `Allowed: ${allowed.length > 0 ? allowed.join(', ') : 'none (terminal state)'}`);
-        }
-        const updated = {
-            ...impl,
-            lifecycleState: newState,
-            updatedAt: new Date().toISOString(),
-        };
-        store.tree.implementations[implementationId] = updated;
-        return updated;
-    });
-}
-/**
- * Get implementations in a specific lifecycle state for a given rule.
- */
-export function listRuleImplementationsByState(stateDir, ruleId, state) {
-    const implementations = listImplementationsForRule(stateDir, ruleId);
-    return implementations.filter((impl) => impl.lifecycleState === state);
-}
-/**
- * Find active implementation for a rule (helper for rule host lookup).
+ * PRI-459: This file WAS a full duplicate implementation of
+ * principle_training_state.json parsing / serialization / mutation (~600
+ * lines of inlined parsers, serializers, mutators, and a parallel codec).
+ * That dual ownership caused two real failure classes:
+ *
+ *   1. Lost updates — core wrote the file UNLOCKED, the plugin wrote it WITH
+ *      a lock, and neither knew the other's lock. Concurrent writers (e.g.
+ *      evolution-worker async + a pd-cli command) could silently drop edits.
+ *   2. Silent field loss — the two codecs parsed the same bytes at different
+ *      strictness; a field one side persisted could be dropped on the next
+ *      load by the other.
+ *
+ * Both are now fixed by converging on a SINGLE source of truth in core:
+ *   - parse/serialize: @principles/core/runtime-v2/principle-tree/ledger-codec
+ *   - mutation (with cross-process file lock): @principles/core/principle-tree-ledger
+ *
+ * This file is now a thin re-export so existing relative imports
+ * (`from './principle-tree-ledger.js'`) keep resolving. Consumers get the
+ * exact same API surface, now backed by the locked core implementation.
+ *
+ * Do NOT reintroduce parsing / serialization / mutation logic here. The
+ * architecture-regression guard "PRI-459: single principle_training_state
+ * ledger implementation" enforces this.
  */
-export function findActiveImplementation(stateDir, ruleId) {
-    const implementations = listImplementationsForRule(stateDir, ruleId);
-    return implementations.find((impl) => impl.lifecycleState === 'active') ?? null;
-}
+export { 
+// Constants
+TREE_NAMESPACE, 
+// Lock
+LockAcquisitionError, 
+// I/O + mutators
+loadLedger, saveLedger, saveLedgerAsync, updateTrainingStore, addPrincipleToLedger, createRule, createImplementation, updatePrinciple, updateRule, deleteRule, updateImplementation, deleteImplementation, listImplementationsForRule, getPrincipleSubtree, updatePrincipleValueMetrics, 
+// Lifecycle
+isValidLifecycleTransition, getAllowedTransitions, transitionImplementationState, listRuleImplementationsByState, findActiveImplementation, } from '@principles/core/principle-tree-ledger';
+// Back-compat alias: the historical plugin module exported `getLedgerFilePath`
+// (core names it `getLedgerFilePathPublic` for the same path). Keep the old
+// name resolvable for any consumer still on it; both compute
+// path.join(stateDir, 'principle_training_state.json').
+import { getLedgerFilePathPublic } from '@principles/core/principle-tree-ledger';
+export const getLedgerFilePath = getLedgerFilePathPublic;

package/plugin/dist/core/reflection/reflection-context.d.ts

@@ -1,7 +1,7 @@
+import { type LedgerPrinciple } from '../principle-tree-ledger.js';
 import type { TrajectoryDatabase } from '../trajectory.js';
-import type { Principle } from '../../types/principle-tree-schema.js';
 export interface ReflectionContext {
-    principle: Principle;
+    principle: LedgerPrinciple;
     painEvents: Array<{
         source: string;
         score: number;

package/plugin/dist/core/trajectory.d.ts

@@ -1,5 +1,21 @@
 import type { CorrectionSampleReviewStatus, CorrectionExportMode, TrajectoryDataStats, TrajectoryAssistantTurnInput, TrajectoryUserTurnInput, TrajectoryToolCallInput, TrajectoryPainEventInput, TrajectoryGateBlockInput, TrajectoryTrustChangeInput, TrajectoryPrincipleEventInput, TrajectoryTaskOutcomeInput, TrajectorySessionInput, EvolutionTaskInput, EvolutionEventInput, EvolutionTaskRecord, EvolutionEventRecord, EvolutionTaskFilters, AssistantTurnRecord, CorrectionSampleRecord, TrajectoryExportResult, TrajectoryDatabaseOptions } from './trajectory-types.js';
 export type { CorrectionSampleReviewStatus, CorrectionExportMode, TrajectoryDataStats, TrajectoryAssistantTurnInput, TrajectoryUserTurnInput, TrajectoryToolCallInput, TrajectoryPainEventInput, TrajectoryGateBlockInput, DailyMetricRow, TrajectoryTrustChangeInput, TrajectoryPrincipleEventInput, TrajectoryTaskOutcomeInput, TrajectorySessionInput, TaskKind, TaskPriority, EvolutionTaskInput, EvolutionEventInput, EvolutionTaskRecord, EvolutionEventRecord, EvolutionTaskFilters, AssistantTurnRecord, CorrectionSampleRecord, TrajectoryExportResult, TrajectoryDatabaseOptions, } from './trajectory-types.js';
+/**
+ * Initialize trajectory.db schema at the given workspace directory.
+ *
+ * Opens trajectory.db in write mode, applies the full schema (tables + indexes + views +
+ * migrations), then closes the DB. Does NOT run importLegacyArtifacts() or
+ * pruneUnreferencedBlobs() — those are runtime side-effects of TrajectoryDatabase
+ * construction and are not needed for pure initialization.
+ *
+ * Idempotent: safe to call on an existing DB; all CREATE statements use IF NOT EXISTS.
+ *
+ * @returns list of created/verified table names and any warnings
+ */
+export declare function initTrajectorySchema(workspaceDir: string): {
+    tables: string[];
+    warnings: string[];
+};
 export declare class TrajectoryDatabase {
     private readonly workspaceDir;
     private readonly stateDir;