@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/context-file-serializer.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `serializeContextFileWrite` — daemon-wide per-absolute-path promise-chain
+ * mutex. The single source of truth for "this read-modify-write block on
+ * `<abs>` does not interleave with any other writer to the same path",
+ * across BOTH the HTTP context routes and the in-process daemon-direct
+ * writers (today-direct-writer, agent-journal-appender, roadmap-maintenance,
+ * dispatcher-scheduled-tasks' weekly-interests journal appender).
+ *
+ * Why this exists
+ * ---------------
+ * Before this module landed, the HTTP route's in-router `withWriteLock`
+ * serialized only HTTP-vs-HTTP writes within a single router instance.
+ * Daemon-direct writers (which fire from cron ticks and scheduled-task
+ * pre-hooks) ran their own `readFileSync` → mutate → `writeFileAtomically`
+ * sequence with no shared coordination, so a concurrent HTTP `PATCH` and
+ * a hourly_check `appendAgentLogLine` could both read the same pre-state,
+ * each compute their own "next", and the second `rename` would silently
+ * drop the first writer's bullet.
+ *
+ * The named cross-session locks (`morningRoutineLock`, `roadmapWriteLock`)
+ * are NOT a substitute: they're a fast-fail X-Lock-Id gate for cross-session
+ * coordination (HTTP returns 409 when held by another session), not an
+ * await-the-current-writer mutex. Direct writers gracefully `acquire() →
+ * skip` when the lock is held; that is acceptable for "best-effort log
+ * line" callers but loses morning-routine journal entries and roadmap
+ * maintenance traces when it fires.
+ *
+ * Contract
+ * --------
+ * - `fn` is invoked at most once per call, after every previously-enqueued
+ *   `fn` for the same absolute path has settled.
+ * - Errors thrown by `fn` propagate to the caller AND release the queue —
+ *   a poisoning `fn` does not block successors.
+ * - The map entry is dropped when this call is the tail of the chain, so
+ *   the map's footprint tracks "paths with currently-pending writers"
+ *   rather than the unbounded history.
+ *
+ * Multi-path acquisitions
+ * -----------------------
+ * Callers that need to atomically read one path and write another (e.g.
+ * `POST /api/context/archive-today` rotating today.md → yesterday.md)
+ * must acquire BOTH serializers, nested with a deterministic order.
+ * Convention: acquire in **alphabetical order by absolute path**. The
+ * fixed order prevents AB/BA deadlock against any other multi-path
+ * caller that follows the same rule. Pattern:
+ *
+ *   return serializeContextFileWrite(pathA, () =>
+ *     serializeContextFileWrite(pathB, () => { ... }));
+ *
+ * where `pathA < pathB` lexicographically.
+ *
+ * Convention for new writers
+ * --------------------------
+ * **Every new writer that targets a context file must go through this
+ * helper.** "Context file" = any `.md` file under the configured
+ * `contextDir` (see `core/context-paths.ts`). The bug class this fence
+ * prevents (HTTP PATCH and a daemon-direct writer reading the same
+ * pre-state and clobbering each other) re-emerges silently the moment
+ * a new writer skips it. There is no compile-time enforcement — the
+ * grep for `writeFileAtomically` followed by a `contextDir`-anchored
+ * path is the audit signal. When adding a writer, wrap the entire
+ * read-modify-write block (not just the write) so the read sees the
+ * post-state of any previously-enqueued writer.
+ *
+ * Out of scope
+ * ------------
+ * - Cross-process coordination (multiple daemon processes touching the
+ *   same context dir). The daemon is single-process by design; running
+ *   two on one DATA_DIR is unsupported elsewhere too.
+ * - Read serialization. Reads are not gated. A reader can observe an
+ *   intermediate post-rename state, which is the same guarantee
+ *   `writeFileAtomically` already gives.
+ *
+ * Resetting state in tests
+ * ------------------------
+ * `_resetContextFileSerializerForTesting()` clears the in-flight map so
+ * a test that exercises the queue can start from a known state in the
+ * next test. Production code MUST NOT call it.
+ */
+export declare function serializeContextFileWrite<T>(absolutePath: string, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Test-only reset. Production callers MUST NOT invoke this — clearing
+ * the map mid-flight would let two writers run concurrently against the
+ * same path, which is the exact bug this module exists to prevent.
+ */
+export declare function _resetContextFileSerializerForTesting(): void;
+/**
+ * Test-only inspector. Returns the number of paths with at least one
+ * pending writer. Exposed so tests can assert the map shrinks back to
+ * zero after the chain drains, catching map-leak regressions.
+ */
+export declare function _pendingPathCountForTesting(): number;

package/dist/core/context-file-serializer.js

@@ -0,0 +1,126 @@
+/**
+ * `serializeContextFileWrite` — daemon-wide per-absolute-path promise-chain
+ * mutex. The single source of truth for "this read-modify-write block on
+ * `<abs>` does not interleave with any other writer to the same path",
+ * across BOTH the HTTP context routes and the in-process daemon-direct
+ * writers (today-direct-writer, agent-journal-appender, roadmap-maintenance,
+ * dispatcher-scheduled-tasks' weekly-interests journal appender).
+ *
+ * Why this exists
+ * ---------------
+ * Before this module landed, the HTTP route's in-router `withWriteLock`
+ * serialized only HTTP-vs-HTTP writes within a single router instance.
+ * Daemon-direct writers (which fire from cron ticks and scheduled-task
+ * pre-hooks) ran their own `readFileSync` → mutate → `writeFileAtomically`
+ * sequence with no shared coordination, so a concurrent HTTP `PATCH` and
+ * a hourly_check `appendAgentLogLine` could both read the same pre-state,
+ * each compute their own "next", and the second `rename` would silently
+ * drop the first writer's bullet.
+ *
+ * The named cross-session locks (`morningRoutineLock`, `roadmapWriteLock`)
+ * are NOT a substitute: they're a fast-fail X-Lock-Id gate for cross-session
+ * coordination (HTTP returns 409 when held by another session), not an
+ * await-the-current-writer mutex. Direct writers gracefully `acquire() →
+ * skip` when the lock is held; that is acceptable for "best-effort log
+ * line" callers but loses morning-routine journal entries and roadmap
+ * maintenance traces when it fires.
+ *
+ * Contract
+ * --------
+ * - `fn` is invoked at most once per call, after every previously-enqueued
+ *   `fn` for the same absolute path has settled.
+ * - Errors thrown by `fn` propagate to the caller AND release the queue —
+ *   a poisoning `fn` does not block successors.
+ * - The map entry is dropped when this call is the tail of the chain, so
+ *   the map's footprint tracks "paths with currently-pending writers"
+ *   rather than the unbounded history.
+ *
+ * Multi-path acquisitions
+ * -----------------------
+ * Callers that need to atomically read one path and write another (e.g.
+ * `POST /api/context/archive-today` rotating today.md → yesterday.md)
+ * must acquire BOTH serializers, nested with a deterministic order.
+ * Convention: acquire in **alphabetical order by absolute path**. The
+ * fixed order prevents AB/BA deadlock against any other multi-path
+ * caller that follows the same rule. Pattern:
+ *
+ *   return serializeContextFileWrite(pathA, () =>
+ *     serializeContextFileWrite(pathB, () => { ... }));
+ *
+ * where `pathA < pathB` lexicographically.
+ *
+ * Convention for new writers
+ * --------------------------
+ * **Every new writer that targets a context file must go through this
+ * helper.** "Context file" = any `.md` file under the configured
+ * `contextDir` (see `core/context-paths.ts`). The bug class this fence
+ * prevents (HTTP PATCH and a daemon-direct writer reading the same
+ * pre-state and clobbering each other) re-emerges silently the moment
+ * a new writer skips it. There is no compile-time enforcement — the
+ * grep for `writeFileAtomically` followed by a `contextDir`-anchored
+ * path is the audit signal. When adding a writer, wrap the entire
+ * read-modify-write block (not just the write) so the read sees the
+ * post-state of any previously-enqueued writer.
+ *
+ * Out of scope
+ * ------------
+ * - Cross-process coordination (multiple daemon processes touching the
+ *   same context dir). The daemon is single-process by design; running
+ *   two on one DATA_DIR is unsupported elsewhere too.
+ * - Read serialization. Reads are not gated. A reader can observe an
+ *   intermediate post-rename state, which is the same guarantee
+ *   `writeFileAtomically` already gives.
+ *
+ * Resetting state in tests
+ * ------------------------
+ * `_resetContextFileSerializerForTesting()` clears the in-flight map so
+ * a test that exercises the queue can start from a known state in the
+ * next test. Production code MUST NOT call it.
+ */
+const pendingWrites = new Map();
+export async function serializeContextFileWrite(absolutePath, fn) {
+    const previous = pendingWrites.get(absolutePath) ?? Promise.resolve();
+    // The chain pattern: each caller awaits its predecessor (swallowing
+    // the predecessor's error so a poisoning fn does not block successors)
+    // and then runs its own `fn`. The map stores the "outer" Promise that
+    // resolves only after this call's `fn` settles, so the next caller
+    // chains onto it.
+    let resolveSelf;
+    const self = new Promise((resolve) => {
+        resolveSelf = resolve;
+    });
+    pendingWrites.set(absolutePath, self);
+    try {
+        await previous.catch(() => {
+            // Predecessor errors are surfaced to the predecessor's caller —
+            // we deliberately do not propagate them here, so a single
+            // poisoning fn does not cascade through the queue.
+        });
+        return await fn();
+    }
+    finally {
+        resolveSelf();
+        // Drop the map entry when we're the tail. If a later caller has
+        // already chained on, `pendingWrites.get(absolutePath)` !== `self`
+        // and we leave the map alone.
+        if (pendingWrites.get(absolutePath) === self) {
+            pendingWrites.delete(absolutePath);
+        }
+    }
+}
+/**
+ * Test-only reset. Production callers MUST NOT invoke this — clearing
+ * the map mid-flight would let two writers run concurrently against the
+ * same path, which is the exact bug this module exists to prevent.
+ */
+export function _resetContextFileSerializerForTesting() {
+    pendingWrites.clear();
+}
+/**
+ * Test-only inspector. Returns the number of paths with at least one
+ * pending writer. Exposed so tests can assert the map shrinks back to
+ * zero after the chain drains, catching map-leak regressions.
+ */
+export function _pendingPathCountForTesting() {
+    return pendingWrites.size;
+}

package/dist/core/context-frontmatter-extract.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared YAML-frontmatter extractor used by both the legacy strict
+ * validator (`context-frontmatter.ts`) and the new vault-contract parser
+ * (`context-validation/frontmatter.ts`). Extracting this into its own
+ * module is the prerequisite for keeping the two parsers in lock-step on
+ * what they consider "frontmatter" while letting each interpret the
+ * resulting key/value map under its own rules.
+ *
+ * The parser is intentionally minimal — it covers the line-scalar shapes
+ * Aitne's frontmatter actually uses today (single-line strings, quoted or
+ * unquoted, with `#`-anchored inline comments). YAML block scalars (`|`,
+ * `>`) and nested mappings remain unsupported by design: every Aitne
+ * frontmatter field is a single scalar today, and accepting richer YAML
+ * here would silently parse multi-line `origin:` blocks as the literal
+ * `"|"` value while losing the actual content — exactly the regression
+ * the policy-file validator guards against.
+ */
+export interface ExtractedFrontmatter {
+    values: Record<string, string>;
+    body: string;
+}
+/**
+ * Extract the YAML frontmatter from a Markdown file. Returns `null` if
+ * the file does not start with `---\n` or never closes the block.
+ */
+export declare function extractContextFrontmatter(content: string): ExtractedFrontmatter | null;
+/**
+ * Convenience wrapper — returns just the parsed scalar map (or `null` if
+ * no frontmatter is present). Callers that only need to look up a field
+ * value avoid the body-slice cost via this entry point.
+ */
+export declare function readContextFrontmatterValues(content: string): Record<string, string> | null;

package/dist/core/context-frontmatter-extract.js

@@ -0,0 +1,98 @@
+/**
+ * Shared YAML-frontmatter extractor used by both the legacy strict
+ * validator (`context-frontmatter.ts`) and the new vault-contract parser
+ * (`context-validation/frontmatter.ts`). Extracting this into its own
+ * module is the prerequisite for keeping the two parsers in lock-step on
+ * what they consider "frontmatter" while letting each interpret the
+ * resulting key/value map under its own rules.
+ *
+ * The parser is intentionally minimal — it covers the line-scalar shapes
+ * Aitne's frontmatter actually uses today (single-line strings, quoted or
+ * unquoted, with `#`-anchored inline comments). YAML block scalars (`|`,
+ * `>`) and nested mappings remain unsupported by design: every Aitne
+ * frontmatter field is a single scalar today, and accepting richer YAML
+ * here would silently parse multi-line `origin:` blocks as the literal
+ * `"|"` value while losing the actual content — exactly the regression
+ * the policy-file validator guards against.
+ */
+/**
+ * Extract the YAML frontmatter from a Markdown file. Returns `null` if
+ * the file does not start with `---\n` or never closes the block.
+ */
+export function extractContextFrontmatter(content) {
+    const lines = content.split(/\r?\n/);
+    if (lines[0].trim() !== "---")
+        return null;
+    const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (end < 0)
+        return null;
+    const values = {};
+    for (const rawLine of lines.slice(1, end)) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const match = /^([A-Za-z0-9_-]+)\s*:\s*(.*?)\s*$/.exec(line);
+        /* c8 ignore start — non-matching lines slip through as documentation;
+           defensive guard for malformed YAML scalars. */
+        if (!match)
+            continue;
+        /* c8 ignore stop */
+        values[match[1]] = parseYamlScalar(match[2]);
+    }
+    return {
+        values,
+        body: lines.slice(end + 1).join("\n"),
+    };
+}
+/**
+ * Convenience wrapper — returns just the parsed scalar map (or `null` if
+ * no frontmatter is present). Callers that only need to look up a field
+ * value avoid the body-slice cost via this entry point.
+ */
+export function readContextFrontmatterValues(content) {
+    const extracted = extractContextFrontmatter(content);
+    return extracted === null ? null : extracted.values;
+}
+function parseYamlScalar(value) {
+    return stripYamlQuotes(stripYamlInlineComment(value).trim());
+}
+function stripYamlInlineComment(value) {
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        if (quote === '"') {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === "\\") {
+                escaped = true;
+            }
+            else if (char === '"') {
+                quote = null;
+            }
+            continue;
+        }
+        if (quote === "'") {
+            if (char === "'")
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === "#" && (i === 0 || /\s/.test(value[i - 1]))) {
+            return value.slice(0, i).trimEnd();
+        }
+    }
+    return value;
+}
+function stripYamlQuotes(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}

package/dist/core/context-frontmatter.d.ts

@@ -7,7 +7,20 @@ export interface ExpectedContextFrontmatter {
     type: string;
     owners: readonly string[];
 }
+/**
+ * Path-prefix predicate consumed by the write chokepoint to decide
+ * whether the strict frontmatter validator should fire. After the
+ * vault restructure (CONTEXT_VAULT_REDESIGN_PLAN.md §3) the prefixes
+ * are the new class-prefixed paths. Legacy prefixes are normalised by
+ * the API alias resolver upstream, so the matcher only ever sees
+ * canonical paths.
+ */
 export declare function shouldValidateContextFileFrontmatter(relativePath: string): boolean;
 export declare function validateContextFileFrontmatter(content: string, relativePath: string): ContextFrontmatterValidationError | null;
+export interface DailySkeletonFrontmatterDriftError {
+    field: string;
+    received: string | null;
+    expected: string;
+}
+export declare function validateDailySkeletonFrontmatter(content: string, relativePath: string): DailySkeletonFrontmatterDriftError[];
 export declare function expectedFrontmatterForPath(relativePath: string): ExpectedContextFrontmatter | null;
-//# sourceMappingURL=context-frontmatter.d.ts.map