@aitne/daemon 0.1.0

package/dist/core/context/domain-index-runner.js

@@ -0,0 +1,223 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DOMAINS } from "@aitne/shared";
+import { localDateStr } from "@aitne/shared";
+import { writeRuntimeState, getDegradedMode } from "../../db/runtime-state.js";
+import { writeFileAtomically } from "../atomic-write.js";
+import { createLogger } from "../../logging.js";
+import { bucketByDomain, relativeDomainIndexPath, renderDomainIndex, } from "./domain-index-reconciler.js";
+const logger = createLogger("domain-index-reconciler");
+/** Runtime-state key for the domain-index reconciler's last run record. */
+export const DOMAIN_INDEX_RECONCILER_LAST_RUN_KEY = "reconciler.domain_index.last_run";
+/**
+ * Per-process mutex. The runner does not need to coordinate with other
+ * reconcilers' write paths — each rebuilds an isolated set of files —
+ * but two concurrent driver invocations could race on the same domain
+ * file. Mirrors `policy-index-runner.ts` exactly.
+ */
+let runnerMutex = Promise.resolve();
+/**
+ * Drive one pass of the domain-index reconciler:
+ *
+ *   1. Early-exit when degraded mode is active.
+ *   2. Read the `entities` table + `entity_source_keys` sidecar to build
+ *      the per-domain bucket snapshot.
+ *   3. Render each domain's `_index.md` body deterministically.
+ *   4. Compare against on-disk content; skip the write when bytes match.
+ *   5. Atomic write + agent-write-tracker mark + snapshot the prior
+ *      contents into `md_file_snapshots`.
+ *   6. Persist a single `runtime_state` row regardless of outcome.
+ *
+ * The numeric slots in `ReconcilerRunRecord` are repurposed:
+ *   - `added`           → number of files the runner wrote this pass
+ *   - `removed`         → 0 (domain index files are never removed)
+ *   - `refreshedMtime`  → number of files that already matched on disk
+ */
+export async function runDomainIndexReconciler(opts) {
+    const prev = runnerMutex;
+    let releaseMutex;
+    runnerMutex = new Promise((resolve) => {
+        releaseMutex = resolve;
+    });
+    try {
+        await prev;
+        return await runOnce(opts);
+    }
+    finally {
+        releaseMutex();
+    }
+}
+async function runOnce(opts) {
+    const now = opts.now ? opts.now() : new Date();
+    const today = localDateStr(now, opts.timezone || undefined);
+    const updated = now.toISOString();
+    const recordBase = {
+        at: now.toISOString(),
+        trigger: opts.trigger,
+        added: 0,
+        removed: 0,
+        refreshedMtime: 0,
+    };
+    const degraded = getDegradedMode(opts.db);
+    if (degraded) {
+        const record = {
+            ...recordBase,
+            result: "noop",
+            error: `degraded_mode:${degraded.reason}`,
+        };
+        persistRunRecord(opts.db, record);
+        return record;
+    }
+    try {
+        const entities = loadEntitiesForDomainIndex(opts.db);
+        const buckets = bucketByDomain(entities);
+        let written = 0;
+        let unchanged = 0;
+        for (const domain of DOMAINS) {
+            const list = buckets.byDomain.get(domain) ?? [];
+            // Skip rendering when the domain is empty AND no file exists yet.
+            // Forcing an empty placeholder file on day one creates noise; we
+            // wait for the first entity to be created before materialising
+            // the index.
+            const relativePath = relativeDomainIndexPath(domain);
+            const absolutePath = join(opts.contextDir, relativePath);
+            const previous = readIfExists(absolutePath);
+            if (list.length === 0 && previous === null)
+                continue;
+            const body = renderDomainIndex(domain, list, updated);
+            // Compare the body excluding the `last_built:` line so two
+            // wall-clock-different runs with identical data don't churn the
+            // file. Without this, every cron / fs-event chain rewrites every
+            // domain index, growing `md_file_snapshots` and firing
+            // `onPromptContextChanged` for nothing.
+            if (previous !== null && stripLastBuilt(previous) === stripLastBuilt(body)) {
+                unchanged += 1;
+                continue;
+            }
+            writeWithSnapshot(opts, absolutePath, relativePath, body, previous);
+            opts.onPromptContextChanged?.(relativePath, "domain_index_reconciler", "quiet", { tierReason: "derived_domain_index" });
+            written += 1;
+        }
+        const record = {
+            ...recordBase,
+            result: written === 0 ? "noop" : "applied",
+            error: null,
+            added: written,
+            removed: 0,
+            refreshedMtime: unchanged,
+        };
+        persistRunRecord(opts.db, record);
+        if (written > 0) {
+            logger.info({ trigger: opts.trigger, written, unchanged, today }, "Domain-index reconciler applied");
+        }
+        return record;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const record = {
+            ...recordBase,
+            result: "error",
+            error: message.slice(0, 200),
+        };
+        persistRunRecord(opts.db, record);
+        logger.error({ err, trigger: opts.trigger }, "Domain-index reconciler run failed");
+        return record;
+    }
+}
+/**
+ * Load every mirror row joined with its sidecar source-key set. The
+ * `group_concat` returns NULL when no source keys exist; the caller
+ * normalises to an empty array. Sorted at the SQL level so the bucket
+ * order is reproducible across calls.
+ */
+function loadEntitiesForDomainIndex(db) {
+    const rows = db
+        .prepare(`SELECT e.path, e.domain, e.type, e.title, e.status, e.date,
+              e.last_synced_at AS lastSyncedAt,
+              (SELECT group_concat(k.source_key, ',')
+                 FROM (SELECT source_key
+                         FROM entity_source_keys
+                        WHERE path = e.path
+                     ORDER BY source_key ASC) k) AS sourceKeys
+         FROM entities e
+        ORDER BY e.path ASC`)
+        .all();
+    const out = [];
+    for (const row of rows) {
+        if (!isKnownDomain(row.domain))
+            continue;
+        if (!isKnownType(row.type))
+            continue;
+        const sourceKeys = row.sourceKeys
+            ? row.sourceKeys.split(",").filter((k) => k.length > 0)
+            : [];
+        out.push({
+            path: row.path,
+            domain: row.domain,
+            type: row.type,
+            title: row.title,
+            status: row.status,
+            date: row.date,
+            lastSyncedAt: row.lastSyncedAt,
+            sourceKeys,
+        });
+    }
+    return out;
+}
+function isKnownDomain(value) {
+    return DOMAINS.includes(value);
+}
+const KNOWN_TYPES = new Set([
+    "meeting",
+    "trip",
+    "receipt",
+    "project",
+    "book",
+    "note",
+]);
+function isKnownType(value) {
+    return KNOWN_TYPES.has(value);
+}
+/**
+ * Replace the `last_built: <iso>` line with a stable sentinel so two
+ * renders with identical data but different wall-clocks compare equal.
+ * The renderer's other output is byte-deterministic for a given
+ * snapshot, so this is the only varying line.
+ */
+function stripLastBuilt(content) {
+    return content.replace(/^last_built: .*$/m, "last_built: <stable>");
+}
+function readIfExists(absolutePath) {
+    if (!existsSync(absolutePath))
+        return null;
+    try {
+        return readFileSync(absolutePath, "utf-8");
+    }
+    catch (err) {
+        logger.warn({ err, file: absolutePath }, "Reconciler could not read file");
+        return null;
+    }
+}
+function writeWithSnapshot(opts, absolutePath, relativePath, content, previousContent) {
+    if (previousContent !== null) {
+        try {
+            opts.db
+                .prepare("INSERT INTO md_file_snapshots (file_path, content, trigger, session_id) VALUES (?, ?, ?, ?)")
+                .run(relativePath, previousContent, "domain_index_reconciled", null);
+        }
+        catch (err) {
+            logger.warn({ err, file: relativePath }, "Failed to snapshot prior content before domain-index write");
+        }
+    }
+    writeFileAtomically(absolutePath, content);
+    opts.writeTracker?.markWriting(absolutePath, content);
+}
+function persistRunRecord(db, record) {
+    try {
+        writeRuntimeState(db, DOMAIN_INDEX_RECONCILER_LAST_RUN_KEY, record);
+    }
+    catch (err) {
+        logger.warn({ err, record }, "Domain-index reconciler run record persistence failed");
+    }
+}
+//# sourceMappingURL=domain-index-runner.js.map

package/dist/core/context/domain-index-runner.js.map

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

package/dist/core/context/entity-mirror.d.ts

@@ -0,0 +1,227 @@
+import type Database from "better-sqlite3";
+import { type Domain, type EntityType } from "@aitne/shared";
+import type { AgentWriteTracker } from "../../safety/agent-write-tracker.js";
+/**
+ * Parsed entity-file frontmatter. The mirror only consumes a subset of
+ * the §9.3 schema — the fields it indexes — so the parser is permissive
+ * about unknown keys. Validation that the frontmatter conforms to the
+ * full schema lives in `/api/context/...` PATCH handlers.
+ */
+export interface ParsedEntityFrontmatter {
+    domain: Domain;
+    type: EntityType;
+    slug: string;
+    title: string;
+    status: string | null;
+    date: string | null;
+    lastSyncedAt: string | null;
+    /** Verbatim sources record (JSON) keyed by user-typed app label. */
+    sources: Record<string, Record<string, unknown>>;
+}
+/**
+ * Parse an entity-file body into a mirror-ready record. Returns `null`
+ * when the file is structurally invalid for the mirror's purposes:
+ *
+ *   - no frontmatter,
+ *   - frontmatter does not close with `---`,
+ *   - missing `domain` / `type` / `slug` / `title`,
+ *   - `domain` is not a member of the §9.4 enum,
+ *   - `type` is not a member of the §9.3 enum.
+ *
+ * The L2 path-derived overrides are layered in by the caller (the file
+ * path is the strongest signal — the directory layout cannot lie about
+ * domain or type the way frontmatter can).
+ */
+export declare function parseEntityFromBody(body: string): ParsedEntityFrontmatter | null;
+export interface MirrorSnapshotRow {
+    path: string;
+    domain: Domain;
+    type: EntityType;
+    slug: string;
+    title: string;
+    status: string | null;
+    date: string | null;
+    lastSyncedAt: string | null;
+    /**
+     * Stable JSON serialization of the parsed `sources` record, sorted by
+     * key so identical inputs produce identical strings (the diff compares
+     * stored vs new with a string equality check).
+     */
+    sourcesJson: string;
+    /** Lex-sorted list of source keys for the `entity_source_keys` sidecar. */
+    sourceKeys: string[];
+}
+export interface MirrorCurrentRow {
+    path: string;
+    domain: string;
+    type: string;
+    slug: string;
+    title: string;
+    status: string | null;
+    date: string | null;
+    lastSyncedAt: string | null;
+    sourcesJson: string;
+}
+export interface MirrorDiff {
+    /** Rows present in the snapshot AND either absent from current or changed. */
+    upserts: MirrorSnapshotRow[];
+    /** Paths that exist in the current table but not in the snapshot. */
+    deletes: string[];
+    /** True when no upserts and no deletes — caller skips the SQL roundtrip. */
+    noOp: boolean;
+}
+/**
+ * Diff a directory snapshot against the current `entities` table state.
+ * Returns the upsert + delete plan with deterministic ordering so a
+ * single fixture's expected output is reproducible across runs.
+ */
+export declare function computeMirrorDiff(snapshot: MirrorSnapshotRow[], current: MirrorCurrentRow[]): MirrorDiff;
+/**
+ * Stable JSON serializer. Each top-level key (the source label) is
+ * emitted in sorted order; nested fields under each source are likewise
+ * sorted. Two parses producing identical content map to byte-identical
+ * strings — that's the contract `computeMirrorDiff` relies on.
+ */
+export declare function serializeSourcesJson(sources: Record<string, Record<string, unknown>>): string;
+/**
+ * Build a mirror snapshot row from an entity file body + relative path.
+ * The relative path supplies the canonical (domain, type, slug) triple
+ * — the directory layout cannot misrepresent these the way frontmatter
+ * can — and a frontmatter mismatch is logged but does not abort the
+ * mirror entry.
+ */
+export declare function buildSnapshotRow(relativePath: string, body: string): MirrorSnapshotRow | null;
+/**
+ * Enumerate `<contextDir>/<domain>/<type-plural>/*.md` paths. Skips
+ * hidden directories (`.git`, `.obsidian`, `.DS_Store`) and any file
+ * that is not under one of the §9.4 / §9.3 enums.
+ *
+ * Returns relative paths (forward-slashed) so the caller can hand
+ * them to {@link parseEntityPath} without further normalisation.
+ */
+export declare function enumerateEntityFiles(contextDir: string): string[];
+/**
+ * Read + parse an L2 file from disk into a snapshot row. Returns `null`
+ * when the file is unreadable, has no parseable frontmatter, or the
+ * relative path is not a valid `<domain>/<type-plural>/<slug>.md`.
+ */
+export declare function readSnapshotRow(contextDir: string, relativePath: string): MirrorSnapshotRow | null;
+/**
+ * Build the full snapshot of L2 entity files for a context directory.
+ * Used by both the boot reconciler and the watcher's incremental
+ * single-file refresh path.
+ */
+export declare function buildFullSnapshot(contextDir: string): MirrorSnapshotRow[];
+/**
+ * Read the current `entities` rows for the boot diff. Includes
+ * `sources_json` so the diff's equality check matches `MirrorSnapshotRow.
+ * sourcesJson` (both produced by `serializeSourcesJson`).
+ */
+export declare function readCurrentMirror(db: Database.Database): MirrorCurrentRow[];
+/**
+ * Apply a single row's upsert: replace the entity row + replace the
+ * sidecar source-key set. Wrapped in `db.transaction` so a partial
+ * failure (entity inserted, source-keys not) is impossible.
+ */
+export declare function upsertMirrorRow(db: Database.Database, row: MirrorSnapshotRow): void;
+/**
+ * Hard-delete a mirror row. The FK ON DELETE CASCADE removes matching
+ * `entity_source_keys` rows automatically.
+ */
+export declare function deleteMirrorRow(db: Database.Database, path: string): void;
+export interface BootstrapEntityMirrorOptions {
+    db: Database.Database;
+    contextDir: string;
+}
+export interface BootstrapEntityMirrorResult {
+    scanned: number;
+    upserted: number;
+    deleted: number;
+    /** Wall-clock millis of the full pass — surfaces in metrics + tests. */
+    durationMs: number;
+}
+/**
+ * Boot-time pass — walks the L2 tree, diffs against the current mirror,
+ * applies upserts and deletes. Idempotent: a second call with no
+ * filesystem changes is a no-op (`upserted === 0 && deleted === 0`).
+ */
+export declare function bootstrapEntityMirror(opts: BootstrapEntityMirrorOptions): BootstrapEntityMirrorResult;
+export type SingleRefreshResult = {
+    kind: "noop";
+} | {
+    kind: "self-write";
+} | {
+    kind: "ignored";
+    reason: "not-l2" | "is-index" | "unparseable";
+} | {
+    kind: "upserted";
+    path: string;
+} | {
+    kind: "deleted";
+    path: string;
+};
+export interface RefreshOneOptions {
+    db: Database.Database;
+    contextDir: string;
+    /** Absolute path the watcher emitted. */
+    absolutePath: string;
+    /** Optional self-write tracker — when present, marked paths short-circuit. */
+    writeTracker?: AgentWriteTracker;
+}
+/**
+ * Apply a single-path delta to the mirror. The watcher calls this on
+ * `add`, `change`, and `unlink` events. The function classifies the
+ * path, reads the file (if present), and writes the row delta. Returns
+ * a discriminated outcome so the caller can record metrics + tests can
+ * assert behavior without poking SQLite directly.
+ */
+export declare function refreshEntityMirrorForPath(opts: RefreshOneOptions): SingleRefreshResult;
+/**
+ * Map an absolute path under `contextDir` back to its forward-slashed
+ * relative form. Returns `null` when the absolute path is outside the
+ * context directory (defense in depth — chokidar should never emit
+ * out-of-tree events, but a misconfigured ignore list could).
+ */
+export declare function toRelativePath(contextDir: string, absolutePath: string): string | null;
+/**
+ * True when the given relative path matches the L2 layout
+ * `<domain>/<type-plural>/<slug>.md`. Does NOT validate the slug — that
+ * is the parser's job — only the directory shape.
+ */
+export declare function isL2EntityRelativePath(relativePath: string): boolean;
+export interface EntityMirrorWatcherOptions {
+    db: Database.Database;
+    contextDir: string;
+    writeTracker?: AgentWriteTracker;
+    /**
+     * Invoked after every applied entity-mirror delta (upsert or delete).
+     * The daemon wires this to the context-index reconciler observer's
+     * `requestReconcile("fs_event")` so the §7.2 chain (domain-index +
+     * activity-view) re-renders when an L2 file changes — without it,
+     * those views only refreshed on the nightly cron + 30 s startup pass
+     * because `shouldIndexPath` filters L2 paths out of the context-
+     * index's own watcher (followups item 7).
+     *
+     * No fan-out risk: the reconciler outputs (`<domain>/_index.md`,
+     * `_activity/<source>.md`) live outside the entity-mirror watcher's
+     * `<contextDir>/<domain>/<plural>/*.md` patterns and `_*.md` is
+     * explicitly ignored, so the chain cannot loop back through this
+     * observer.
+     */
+    onEntityChanged?: () => void;
+    /**
+     * Test seam — override the watcher factory so unit tests can drive
+     * the watcher end-to-end without booting chokidar.
+     */
+    watcherFactory?: (contextDir: string) => EntityFileWatcher;
+}
+export interface EntityFileWatcher {
+    onChange(handler: (absolutePath: string) => void): void;
+    onUnlink(handler: (absolutePath: string) => void): void;
+    close(): Promise<void>;
+}
+export interface EntityMirrorWatcherHandle {
+    stop(): Promise<void>;
+}
+export declare function startEntityMirrorWatcher(opts: EntityMirrorWatcherOptions): EntityMirrorWatcherHandle;
+//# sourceMappingURL=entity-mirror.d.ts.map

package/dist/core/context/entity-mirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-mirror.d.ts","sourceRoot":"","sources":["../../../src/core/context/entity-mirror.ts"],"names":[],"mappings":"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"}