@maadb/core 0.0.1 → 0.7.9

package/dist/engine/indexing.js

@@ -0,0 +1,225 @@
+// ============================================================================
+// Indexing — indexAll, indexFile, processDocument, reindex
+// ============================================================================
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { ok, err, singleErr } from '../errors.js';
+import { docId as toDocId, docType as toDocType, filePath as toFilePath, } from '../types.js';
+import { parseDocument } from '../parser/index.js';
+import { validateFrontmatter } from '../schema/index.js';
+import { extract } from '../extractor/index.js';
+import { collectMarkdownFiles, computeNumericValue } from './helpers.js';
+// 0.7.4 (fup-2026-093) — Per-type schema fingerprint covering the indexed
+// field set. When a schema edit flips a field's `index: false → true` (or
+// adds/removes an indexed field), the fingerprint changes; indexAll detects
+// that and force-rebuilds docs of the affected type even when their file
+// hashes are unchanged. Closes the silent "indexed: 0, skipped: N" footgun.
+//
+// Fingerprint covers: indexed field names + their types (so a type-change
+// on an indexed field also triggers rebuild). Sorted+joined+hashed; first
+// 16 hex chars are plenty of collision resistance for this use.
+function computeIndexedFieldFingerprint(schema) {
+    const parts = [];
+    for (const [name, def] of schema.fields) {
+        if (def.index)
+            parts.push(`${name}:${def.type}`);
+    }
+    parts.sort();
+    return createHash('sha256').update(parts.join('|')).digest('hex').slice(0, 16);
+}
+const SCHEMA_FP_KEY_PREFIX = 'schema_index_fp:';
+export async function indexAll(ctx, opts) {
+    const force = opts?.force ?? false;
+    const result = { scanned: 0, indexed: 0, skipped: 0, errors: [] };
+    // 0.7.4 — Detect schema-index changes per type. Types whose fingerprint
+    // changed (or was never recorded) join `dirtyTypes`, which overrides the
+    // file-hash skip path below so docs of those types reindex even if their
+    // markdown is byte-for-byte unchanged.
+    const dirtyTypes = new Set();
+    const currentFingerprints = new Map();
+    for (const [typeName] of ctx.registry.types) {
+        const schema = ctx.schemaStore.getSchemaForType(typeName);
+        if (!schema)
+            continue;
+        const fp = computeIndexedFieldFingerprint(schema);
+        currentFingerprints.set(typeName, fp);
+        if (force) {
+            dirtyTypes.add(typeName);
+            continue;
+        }
+        const stored = ctx.backend.getMeta(`${SCHEMA_FP_KEY_PREFIX}${typeName}`);
+        if (stored !== fp)
+            dirtyTypes.add(typeName);
+    }
+    const storedHashes = force ? new Map() : ctx.backend.getAllFileHashes();
+    const filesOnDisk = new Set();
+    for (const [typeName, regType] of ctx.registry.types) {
+        const isTypeDirty = dirtyTypes.has(typeName);
+        const dirPath = path.join(ctx.projectRoot, regType.path);
+        if (!existsSync(dirPath))
+            continue;
+        const files = await collectMarkdownFiles(dirPath);
+        for (const file of files) {
+            result.scanned++;
+            const fp = toFilePath(path.relative(ctx.projectRoot, file));
+            const absPath = toFilePath(file);
+            filesOnDisk.add(fp);
+            // Skip-by-hash only applies when neither --force nor a schema-fingerprint
+            // change is in play. Otherwise we rebuild even if disk content matches.
+            if (!force && !isTypeDirty) {
+                const raw = await readFile(file, 'utf-8');
+                const currentHash = createHash('sha256').update(raw).digest('hex');
+                const storedHash = storedHashes.get(fp);
+                if (storedHash === currentHash) {
+                    result.skipped++;
+                    continue;
+                }
+            }
+            const indexResult = await indexFile(ctx, absPath);
+            if (indexResult.ok) {
+                result.indexed++;
+            }
+            else {
+                result.errors.push(...indexResult.errors);
+            }
+        }
+    }
+    // Remove stale backend records
+    const allStoredPaths = ctx.backend.getAllFileHashes();
+    for (const [storedPath] of allStoredPaths) {
+        if (!filesOnDisk.has(storedPath)) {
+            const doc = ctx.backend.getDocumentByPath(storedPath);
+            if (doc) {
+                ctx.backend.removeDocument(doc.docId);
+            }
+        }
+    }
+    // 0.7.4 — Persist current fingerprints AFTER successful rebuild so a
+    // crash mid-reindex leaves the prior fingerprint in place; next run sees
+    // the diff again and retries.
+    for (const [typeName, fp] of currentFingerprints) {
+        ctx.backend.setMeta(`${SCHEMA_FP_KEY_PREFIX}${typeName}`, fp);
+    }
+    if (dirtyTypes.size > 0) {
+        result.rebuiltTypes = [...dirtyTypes].sort();
+    }
+    return result;
+}
+export async function indexFile(ctx, absolutePath) {
+    const parsed = await parseDocument(absolutePath, ctx.registry.subtypeMap);
+    if (!parsed.ok)
+        return parsed;
+    return processDocument(ctx, parsed.value);
+}
+export function processDocument(ctx, parsed) {
+    const fmDocType = parsed.frontmatter['doc_type'];
+    if (typeof fmDocType !== 'string') {
+        return singleErr('UNKNOWN_TYPE', `Document has no doc_type in frontmatter: ${parsed.filePath}`);
+    }
+    const dt = toDocType(fmDocType);
+    const schema = ctx.schemaStore.getSchemaForType(dt);
+    if (!schema) {
+        return singleErr('UNKNOWN_TYPE', `No schema found for doc_type "${fmDocType}"`);
+    }
+    const fmDocId = parsed.frontmatter['doc_id'];
+    if (typeof fmDocId !== 'string') {
+        return singleErr('INVALID_DOC_ID', `Document has no doc_id in frontmatter: ${parsed.filePath}`);
+    }
+    const regType = ctx.registry.types.get(dt);
+    if (!regType) {
+        return singleErr('UNKNOWN_TYPE', `Type "${fmDocType}" not in registry`);
+    }
+    // Index mode: structural validation only. Precision enforcement is write-
+    // time only — historical records on disk must stay indexable regardless
+    // of current schema precision declarations.
+    const validation = validateFrontmatter(parsed.frontmatter, schema, ctx.registry, parsed.filePath, { mode: 'index' });
+    const validatedFields = {};
+    for (const [fieldName, fieldDef] of schema.fields) {
+        const value = parsed.frontmatter[fieldName];
+        if (value !== undefined && value !== null) {
+            validatedFields[fieldName] = {
+                name: fieldName,
+                value,
+                fieldType: fieldDef.type,
+                role: fieldDef.role,
+                indexed: fieldDef.index,
+            };
+        }
+    }
+    const bound = {
+        parsed,
+        docId: toDocId(fmDocId),
+        docType: dt,
+        schemaRef: regType.schemaRef,
+        validatedFields,
+        validationResult: validation,
+    };
+    const extraction = extract(bound, schema, ctx.registry);
+    const relativePath = path.relative(ctx.projectRoot, parsed.filePath);
+    const existing = ctx.backend.getDocument(bound.docId);
+    // Only bump version when file content actually changed — reindex of unchanged files preserves version
+    const contentChanged = !existing || existing.fileHash !== parsed.fileHash;
+    const version = existing
+        ? (contentChanged ? existing.version + 1 : existing.version)
+        : 1;
+    const now = new Date().toISOString();
+    const docRecord = {
+        docId: bound.docId,
+        docType: bound.docType,
+        schemaRef: bound.schemaRef,
+        filePath: toFilePath(relativePath),
+        fileHash: parsed.fileHash,
+        version,
+        deleted: false,
+        indexedAt: now,
+        updatedAt: contentChanged ? now : (existing?.updatedAt ?? now),
+    };
+    const fieldIndex = [];
+    for (const [name, field] of Object.entries(validatedFields)) {
+        if (field.indexed) {
+            // List fields: one row per item so filters match individual values
+            if (field.fieldType === 'list' && Array.isArray(field.value)) {
+                for (const item of field.value) {
+                    const itemValue = item instanceof Date
+                        ? item.toISOString()
+                        : String(item);
+                    fieldIndex.push({
+                        name,
+                        value: itemValue,
+                        numericValue: computeNumericValue(item, 'string'),
+                        type: field.fieldType,
+                    });
+                }
+            }
+            else {
+                const fieldValue = field.value instanceof Date
+                    ? field.value.toISOString()
+                    : String(field.value);
+                fieldIndex.push({
+                    name,
+                    value: fieldValue,
+                    numericValue: computeNumericValue(field.value, field.fieldType),
+                    type: field.fieldType,
+                });
+            }
+        }
+    }
+    ctx.backend.materializeDocument(docRecord, extraction.objects, extraction.relationships, parsed.blocks, fieldIndex);
+    return ok(extraction);
+}
+export async function reindex(ctx, opts) {
+    if (opts?.docId) {
+        const doc = ctx.backend.getDocument(opts.docId);
+        if (!doc)
+            return singleErr('FILE_NOT_FOUND', `Document "${opts.docId}" not found`);
+        const absPath = path.join(ctx.projectRoot, doc.filePath);
+        const result = await indexFile(ctx, toFilePath(absPath));
+        if (!result.ok)
+            return err(result.errors);
+        return ok({ scanned: 1, indexed: 1, skipped: 0, errors: [] });
+    }
+    return ok(await indexAll(ctx, { force: opts?.force ?? false }));
+}
+//# sourceMappingURL=indexing.js.map

package/dist/engine/indexing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexing.js","sourceRoot":"","sources":["../../src/engine/indexing.ts"],"names":[],"mappings":"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"}

package/dist/engine/journal.d.ts

@@ -0,0 +1,32 @@
+export interface JournalEntry {
+    id: string;
+    op: 'create' | 'update' | 'delete';
+    docId: string;
+    filePath: string;
+    tempPath?: string | undefined;
+    timestamp: string;
+    status: 'pending' | 'file_written' | 'indexed' | 'committed';
+}
+export declare class OperationJournal {
+    private journalPath;
+    private entries;
+    constructor(backendDir: string);
+    private load;
+    private save;
+    begin(op: JournalEntry['op'], docId: string, filePath: string, tempPath?: string): string;
+    advance(id: string, status: JournalEntry['status']): void;
+    complete(id: string): void;
+    getPending(): JournalEntry[];
+    /**
+     * Reconcile incomplete operations on startup.
+     * Returns a list of recovery actions taken.
+     */
+    reconcile(): string[];
+}
+/**
+ * Atomic file write: write to temp path, then rename.
+ * On failure, temp file is cleaned up.
+ */
+export declare function atomicWriteSync(targetPath: string, content: string): string;
+export declare function atomicWrite(targetPath: string, content: string): Promise<string>;
+//# sourceMappingURL=journal.d.ts.map

package/dist/engine/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/engine/journal.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,GAAG,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;CAC9D;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAsB;gBAEzB,UAAU,EAAE,MAAM;IAK9B,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,IAAI;IAIZ,KAAK,CAAC,EAAE,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IAezF,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,IAAI;IAQzD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAK1B,UAAU,IAAI,YAAY,EAAE;IAI5B;;;OAGG;IACH,SAAS,IAAI,MAAM,EAAE;CAgCtB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOtF"}

package/dist/engine/journal.js

@@ -0,0 +1,111 @@
+// ============================================================================
+// Operation Journal — tracks pending writes for crash recovery
+// Stored in _backend/journal.json. Reconciled on engine startup.
+// ============================================================================
+import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'node:fs';
+import path from 'node:path';
+export class OperationJournal {
+    journalPath;
+    entries = [];
+    constructor(backendDir) {
+        this.journalPath = path.join(backendDir, 'journal.json');
+        this.load();
+    }
+    load() {
+        if (existsSync(this.journalPath)) {
+            try {
+                const raw = readFileSync(this.journalPath, 'utf-8');
+                this.entries = JSON.parse(raw);
+            }
+            catch {
+                this.entries = [];
+            }
+        }
+    }
+    save() {
+        writeFileSync(this.journalPath, JSON.stringify(this.entries, null, 2), 'utf-8');
+    }
+    begin(op, docId, filePath, tempPath) {
+        const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.entries.push({
+            id,
+            op,
+            docId,
+            filePath,
+            tempPath,
+            timestamp: new Date().toISOString(),
+            status: 'pending',
+        });
+        this.save();
+        return id;
+    }
+    advance(id, status) {
+        const entry = this.entries.find(e => e.id === id);
+        if (entry) {
+            entry.status = status;
+            this.save();
+        }
+    }
+    complete(id) {
+        this.entries = this.entries.filter(e => e.id !== id);
+        this.save();
+    }
+    getPending() {
+        return this.entries.filter(e => e.status !== 'committed');
+    }
+    /**
+     * Reconcile incomplete operations on startup.
+     * Returns a list of recovery actions taken.
+     */
+    reconcile() {
+        const actions = [];
+        const pending = this.getPending();
+        for (const entry of pending) {
+            if (entry.status === 'pending' && entry.tempPath) {
+                // Write never completed — clean up temp file
+                if (existsSync(entry.tempPath)) {
+                    try {
+                        unlinkSync(entry.tempPath);
+                        actions.push(`Cleaned up incomplete temp file: ${entry.tempPath}`);
+                    }
+                    catch {
+                        actions.push(`Failed to clean temp file: ${entry.tempPath}`);
+                    }
+                }
+            }
+            else if (entry.status === 'file_written') {
+                // File written but not indexed — mark for reindex
+                actions.push(`File written but not indexed: ${entry.filePath} (doc: ${entry.docId}). Run reindex to recover.`);
+            }
+            else if (entry.status === 'indexed') {
+                // Indexed but git commit failed — non-critical, just note it
+                actions.push(`Indexed but git commit skipped: ${entry.filePath} (doc: ${entry.docId}).`);
+            }
+        }
+        // Clear all pending entries after reconciliation
+        if (pending.length > 0) {
+            this.entries = [];
+            this.save();
+        }
+        return actions;
+    }
+}
+/**
+ * Atomic file write: write to temp path, then rename.
+ * On failure, temp file is cleaned up.
+ */
+export function atomicWriteSync(targetPath, content) {
+    const tempPath = targetPath + '.maad-tmp';
+    writeFileSync(tempPath, content, 'utf-8');
+    renameSync(tempPath, targetPath);
+    return targetPath;
+}
+export async function atomicWrite(targetPath, content) {
+    const { writeFile: fsWriteFile } = await import('node:fs/promises');
+    const { rename } = await import('node:fs/promises');
+    const tempPath = targetPath + '.maad-tmp';
+    await fsWriteFile(tempPath, content, 'utf-8');
+    await rename(tempPath, targetPath);
+    return targetPath;
+}
+//# sourceMappingURL=journal.js.map

package/dist/engine/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../src/engine/journal.ts"],"names":[],"mappings":"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"}

package/dist/engine/logger.d.ts

@@ -0,0 +1,19 @@
+export type Severity = 'fatal' | 'error' | 'degraded' | 'best_effort' | 'info';
+export interface LogEntry {
+    severity: Severity;
+    category: string;
+    operation: string;
+    message: string;
+    details?: Record<string, unknown> | undefined;
+}
+export type LogHandler = (entry: LogEntry) => void;
+export declare function setLogHandler(h: LogHandler): void;
+export declare function log(severity: Severity, category: string, operation: string, message: string, details?: Record<string, unknown>): void;
+export declare const logger: {
+    fatal: (cat: string, op: string, msg: string, details?: Record<string, unknown>) => void;
+    error: (cat: string, op: string, msg: string, details?: Record<string, unknown>) => void;
+    degraded: (cat: string, op: string, msg: string, details?: Record<string, unknown>) => void;
+    bestEffort: (cat: string, op: string, msg: string, details?: Record<string, unknown>) => void;
+    info: (cat: string, op: string, msg: string, details?: Record<string, unknown>) => void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/engine/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/engine/logger.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,aAAa,GAAG,MAAM,CAAC;AAE/E,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC/C;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;AAwBnD,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAEjD;AAED,wBAAgB,GAAG,CACjB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAEN;AAGD,eAAO,MAAM,MAAM;iBACJ,MAAM,MAAM,MAAM,OAAO,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;iBAClE,MAAM,MAAM,MAAM,OAAO,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;oBAC/D,MAAM,MAAM,MAAM,OAAO,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;sBAChE,MAAM,MAAM,MAAM,OAAO,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBACxE,MAAM,MAAM,MAAM,OAAO,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAC/E,CAAC"}

package/dist/engine/logger.js

@@ -0,0 +1,40 @@
+// ============================================================================
+// Engine Logger — structured error/event logging with severity policy
+// All engine operations log through this instead of console.warn/silent catch.
+// Emits via the pino ops logger from src/logging.ts so output is JSON.
+// ============================================================================
+import { getOpsLog } from '../logging.js';
+const severityToLevel = {
+    fatal: 'fatal',
+    error: 'error',
+    degraded: 'warn',
+    best_effort: 'warn',
+    info: 'info',
+};
+const defaultHandler = (entry) => {
+    const level = severityToLevel[entry.severity];
+    const log = getOpsLog();
+    const payload = {
+        event: 'engine',
+        category: entry.category,
+        operation: entry.operation,
+        ...(entry.details ?? {}),
+    };
+    log[level](payload, entry.message);
+};
+let handler = defaultHandler;
+export function setLogHandler(h) {
+    handler = h;
+}
+export function log(severity, category, operation, message, details) {
+    handler({ severity, category, operation, message, details });
+}
+// Convenience shortcuts
+export const logger = {
+    fatal: (cat, op, msg, details) => log('fatal', cat, op, msg, details),
+    error: (cat, op, msg, details) => log('error', cat, op, msg, details),
+    degraded: (cat, op, msg, details) => log('degraded', cat, op, msg, details),
+    bestEffort: (cat, op, msg, details) => log('best_effort', cat, op, msg, details),
+    info: (cat, op, msg, details) => log('info', cat, op, msg, details),
+};
+//# sourceMappingURL=logger.js.map

package/dist/engine/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/engine/logger.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,sEAAsE;AACtE,+EAA+E;AAC/E,uEAAuE;AACvE,+EAA+E;AAE/E,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAc1C,MAAM,eAAe,GAA0D;IAC7E,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,MAAM;IAChB,WAAW,EAAE,MAAM;IACnB,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,MAAM,cAAc,GAAe,CAAC,KAAK,EAAE,EAAE;IAC3C,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IACxB,MAAM,OAAO,GAAG;QACd,KAAK,EAAE,QAAQ;QACf,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;KACzB,CAAC;IACD,GAAG,CAAC,KAAK,CAAsC,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;AAC3E,CAAC,CAAC;AAEF,IAAI,OAAO,GAAe,cAAc,CAAC;AAEzC,MAAM,UAAU,aAAa,CAAC,CAAa;IACzC,OAAO,GAAG,CAAC,CAAC;AACd,CAAC;AAED,MAAM,UAAU,GAAG,CACjB,QAAkB,EAClB,QAAgB,EAChB,SAAiB,EACjB,OAAe,EACf,OAAiC;IAEjC,OAAO,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,wBAAwB;AACxB,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,GAAW,EAAE,EAAU,EAAE,GAAW,EAAE,OAAiC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC;IACvH,KAAK,EAAE,CAAC,GAAW,EAAE,EAAU,EAAE,GAAW,EAAE,OAAiC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC;IACvH,QAAQ,EAAE,CAAC,GAAW,EAAE,EAAU,EAAE,GAAW,EAAE,OAAiC,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC;IAC7H,UAAU,EAAE,CAAC,GAAW,EAAE,EAAU,EAAE,GAAW,EAAE,OAAiC,EAAE,EAAE,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC;IAClI,IAAI,EAAE,CAAC,GAAW,EAAE,EAAU,EAAE,GAAW,EAAE,OAAiC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC;CACtH,CAAC"}

package/dist/engine/maintenance.d.ts

@@ -0,0 +1,15 @@
+import { type Result } from '../errors.js';
+import type { DocId } from '../types.js';
+import type { EngineContext } from './context.js';
+import type { ValidationReport } from './types.js';
+export interface ValidateOptions {
+    /**
+     * 0.6.7 — opt in to scanning every date field with a declared
+     * store_precision and reporting any historical records whose stored value
+     * is coarser than the contract. Informational; never changes
+     * `valid`/`invalid` counts.
+     */
+    includePrecision?: boolean;
+}
+export declare function validate(ctx: EngineContext, docId?: DocId | undefined, options?: ValidateOptions): Promise<Result<ValidationReport>>;
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/engine/maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../src/engine/maintenance.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,aAAa,EAClB,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAwDnC"}

package/dist/engine/maintenance.js

@@ -0,0 +1,87 @@
+// ============================================================================
+// Maintenance — validate
+// ============================================================================
+import { ok, singleErr } from '../errors.js';
+import { validateFrontmatter } from '../schema/index.js';
+import { detectPrecision, isCoarserThan } from '../schema/precision.js';
+import { readFrontmatter } from './helpers.js';
+export async function validate(ctx, docId, options) {
+    const includePrecision = options?.includePrecision ?? false;
+    if (docId) {
+        const doc = ctx.backend.getDocument(docId);
+        if (!doc)
+            return singleErr('FILE_NOT_FOUND', `Document "${docId}" not found`);
+        const schema = ctx.schemaStore.getSchemaForType(doc.docType);
+        if (!schema)
+            return singleErr('SCHEMA_NOT_FOUND', `No schema for type "${doc.docType}"`);
+        const frontmatter = await readFrontmatter(ctx.projectRoot, doc);
+        const result = validateFrontmatter(frontmatter, schema, ctx.registry, undefined, { mode: 'audit' });
+        const report = {
+            total: 1,
+            valid: result.valid ? 1 : 0,
+            invalid: result.valid ? 0 : 1,
+            errors: result.valid ? [] : [{ docId, errors: result.errors.map(e => ({ field: e.field, message: e.message })) }],
+        };
+        if (includePrecision) {
+            report.precisionDrift = collectPrecisionDrift(docId, frontmatter, schema);
+        }
+        return ok(report);
+    }
+    const allDocs = ctx.backend.findDocuments({ limit: 100000 });
+    const report = { total: 0, valid: 0, invalid: 0, errors: [] };
+    const drift = includePrecision ? [] : undefined;
+    for (const match of allDocs) {
+        report.total++;
+        const doc = ctx.backend.getDocument(match.docId);
+        if (!doc)
+            continue;
+        const schema = ctx.schemaStore.getSchemaForType(doc.docType);
+        if (!schema) {
+            report.invalid++;
+            report.errors.push({ docId: doc.docId, errors: [{ field: 'doc_type', message: 'No schema found' }] });
+            continue;
+        }
+        const frontmatter = await readFrontmatter(ctx.projectRoot, doc);
+        const result = validateFrontmatter(frontmatter, schema, ctx.registry, undefined, { mode: 'audit' });
+        if (result.valid) {
+            report.valid++;
+        }
+        else {
+            report.invalid++;
+            report.errors.push({ docId: doc.docId, errors: result.errors.map(e => ({ field: e.field, message: e.message })) });
+        }
+        if (drift) {
+            drift.push(...collectPrecisionDrift(doc.docId, frontmatter, schema));
+        }
+    }
+    if (drift)
+        report.precisionDrift = drift;
+    return ok(report);
+}
+function collectPrecisionDrift(docId, frontmatter, schema) {
+    const out = [];
+    for (const [fieldName, fieldDef] of schema.fields) {
+        if (fieldDef.type !== 'date' || fieldDef.storePrecision === null)
+            continue;
+        const value = frontmatter[fieldName];
+        if (value === undefined || value === null)
+            continue;
+        const actual = value instanceof Date
+            ? 'millisecond'
+            : typeof value === 'string'
+                ? detectPrecision(value)
+                : null;
+        if (actual === null)
+            continue; // malformed — structural handler's concern
+        if (!isCoarserThan(actual, fieldDef.storePrecision))
+            continue;
+        out.push({
+            docId,
+            field: fieldName,
+            declared: fieldDef.storePrecision,
+            actual,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=maintenance.js.map

package/dist/engine/maintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.js","sourceRoot":"","sources":["../../src/engine/maintenance.ts"],"names":[],"mappings":"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"}

package/dist/engine/mutex.d.ts

@@ -0,0 +1,24 @@
+export type Release = () => void;
+export declare class AsyncFifoMutex {
+    private queue;
+    private held;
+    /**
+     * Acquire the lock. Returns a release function. Callers MUST call release()
+     * in a finally block to avoid leaks.
+     *
+     * Ordering is FIFO: the first caller to await acquire() is the first to be
+     * granted the lock when it becomes available.
+     */
+    acquire(): Promise<Release>;
+    private release;
+    /**
+     * Current pressure on the lock: 1 if held and no waiters, >1 if waiters are
+     * queued, 0 if idle. Used for health reporting and drain loops.
+     */
+    depth(): number;
+    /**
+     * True if the lock is currently held by a caller.
+     */
+    isHeld(): boolean;
+}
+//# sourceMappingURL=mutex.d.ts.map

package/dist/engine/mutex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../src/engine/mutex.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC;AAEjC,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,IAAI,CAAS;IAErB;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAc3B,OAAO,CAAC,OAAO;IAMf;;;OAGG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,MAAM,IAAI,OAAO;CAGlB"}