@aitne/daemon 0.1.6 → 0.1.8

package/dist/core/context-validation/routine-rulebook.js

@@ -0,0 +1,156 @@
+/**
+ * Pure validators for routine rulebooks and `.base` YAML files.
+ *
+ * Built-in routine rulebooks (`routines/*.md`, excluding `_index`) drive
+ * the morning / evening / weekly task-flow prompts and must declare the
+ * canonical frontmatter shape so the loader can dispatch by slug + type.
+ *
+ * Custom routines (`routines/custom/*.md`) are user-authored and parsed
+ * by `parseCustomRoutineSpec`; we only translate the structured error
+ * into a human-readable message here so the API can surface a 400
+ * response that the agent can self-correct from in-session.
+ *
+ * `.base` files (today: only `projects/_active.base`) carry the active
+ * project list as inline YAML. Validation is deliberately syntactic
+ * (no schema check) so the file can evolve without a daemon edit; the
+ * loader does the per-row validation when it parses.
+ */
+/**
+ * Validate the canonical built-in routine rulebook shape:
+ *   - YAML frontmatter present
+ *   - `type: rule`
+ *   - `slug` matches the filename (relative to `routines/`)
+ *   - `## Checks` section is present in the body
+ *
+ * Returns a human-readable error message string, or `null` if the file
+ * is valid. The caller maps `null` to 200 and any string to 400.
+ */
+export function validateBuiltInRoutineRulebook(path, content) {
+    const frontmatter = extractRoutineFrontmatter(content);
+    if (frontmatter === null) {
+        return "Routine rulebooks require YAML frontmatter.";
+    }
+    const expectedSlug = path.slice("routines/".length);
+    const typeRaw = readRoutineFrontmatterScalar(frontmatter, "type");
+    if (!typeRaw) {
+        return "Routine rulebooks require `type: rule` in frontmatter.";
+    }
+    if (typeRaw !== "rule") {
+        return "Routine rulebooks must declare `type: rule`.";
+    }
+    const slugRaw = readRoutineFrontmatterScalar(frontmatter, "slug");
+    if (!slugRaw) {
+        return "Routine rulebooks require a `slug` frontmatter field.";
+    }
+    if (slugRaw !== expectedSlug) {
+        return `Routine rulebook slug must match the filename (${expectedSlug}).`;
+    }
+    if (!/^##\s+Checks\s*$/m.test(content)) {
+        return "Routine rulebooks require a `## Checks` section.";
+    }
+    return null;
+}
+/**
+ * Translate a structured `CustomRoutineParseError` from
+ * `parseCustomRoutineSpec` into a human-readable string suitable for
+ * the API error response.
+ */
+export function explainCustomRoutineValidationError(error) {
+    switch (error.kind) {
+        case "missing_field":
+            return `Custom routine files require \`${error.field}\` in frontmatter.`;
+        case "invalid_cron":
+            return `Invalid cron expression: \`${error.value}\`.`;
+        case "invalid_slug":
+            return `Custom routine slug is invalid or does not match the filename: \`${error.value}\`.`;
+        case "invalid_type":
+            return `Custom routines must declare \`type: rule\`, got \`${error.value}\`.`;
+        case "invalid_process_key":
+            return `Custom routine \`process_key\` must match the filename-derived key, got \`${error.value}\`.`;
+        case "invalid_enabled":
+            return `Custom routine \`enabled\` must be \`true\` or \`false\`, got \`${error.value}\`.`;
+        case "invalid_tier":
+            return `Custom routine \`backend_tier\` must be \`light\` or \`heavy\`, got \`${error.value}\`.`;
+        case "invalid_budget":
+            return `Custom routine \`max_budget_usd\` must be a positive number, got \`${error.value}\`.`;
+        case "missing_checks_section":
+            return "Custom routines require a `## Checks` section.";
+        case "no_frontmatter":
+            return "Custom routines require YAML frontmatter.";
+    }
+}
+/**
+ * Extract the YAML frontmatter body (without the `---` delimiters)
+ * from a markdown file, or return `null` if no frontmatter block is
+ * present at the start of the file. Accepts both LF and CRLF line
+ * endings on the opening delimiter so Windows-edited files do not
+ * round-trip as "no frontmatter".
+ */
+export function extractRoutineFrontmatter(content) {
+    if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+        return null;
+    }
+    const afterOpen = content.startsWith("---\r\n") ? 5 : 4;
+    const endIdx = content.indexOf("\n---", afterOpen - 1);
+    if (endIdx < 0)
+        return null;
+    return content.slice(afterOpen, endIdx);
+}
+/**
+ * Read a single top-level scalar field from a routine frontmatter
+ * block. Quoted strings (single or double) have the quotes stripped;
+ * everything else is returned trimmed verbatim. Returns `null` if the
+ * field is absent.
+ */
+export function readRoutineFrontmatterScalar(frontmatter, field) {
+    const re = new RegExp(`^${field}\\s*:\\s*(.+?)\\s*$`, "m");
+    const match = frontmatter.match(re);
+    if (!match)
+        return null;
+    let value = match[1].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Syntactic gate for `.base` YAML context files.
+ *
+ * Only rejects files that are obviously broken — tabs in indentation,
+ * odd indent counts, non-mapping non-list lines. The schema check (what
+ * fields must be present) belongs in the loader; the API gate exists
+ * so that a malformed PATCH cannot wedge the project-list reader.
+ */
+export function validateBaseYamlSyntax(content) {
+    if (content.trim().length === 0) {
+        return ".base files must not be empty.";
+    }
+    const lines = content.split("\n");
+    let sawMeaningfulLine = false;
+    for (let index = 0; index < lines.length; index++) {
+        const raw = lines[index];
+        const lineNo = index + 1;
+        if (raw.includes("\t")) {
+            return `.base YAML may not contain tab indentation (line ${lineNo}).`;
+        }
+        const trimmed = raw.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        sawMeaningfulLine = true;
+        const indent = raw.length - raw.trimStart().length;
+        if (indent % 2 !== 0) {
+            return `.base YAML uses 2-space indentation (line ${lineNo}).`;
+        }
+        const isListItem = /^-\s+\S/.test(trimmed);
+        const isMapping = /^[^:#][^:]*:\s*(?:.*)?$/.test(trimmed);
+        if (!isListItem && !isMapping) {
+            return `Invalid .base YAML structure on line ${lineNo}.`;
+        }
+    }
+    if (!sawMeaningfulLine) {
+        return ".base files must contain at least one mapping entry.";
+    }
+    return null;
+}
+//# sourceMappingURL=routine-rulebook.js.map

package/dist/core/context-validation/routine-rulebook.js.map

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

package/dist/core/context-validation/section.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure helpers for locating `## Section` blocks in context-file markdown.
+ *
+ * Used by `/api/context` PATCH handlers and by `agent/journal` trim/clear
+ * logic. No I/O, no Hono — keep these importable from any layer.
+ *
+ * Section names are normalized case- and whitespace-insensitively so that
+ * the agent's freeform `## Raw signals` matches the literal `## Raw Signals`
+ * in the file. See `docs/design/06-memory.md` for the section vocabulary.
+ */
+/**
+ * Normalize a section name for matching:
+ * lowercase, spaces → underscores, strip leading `## `.
+ */
+export declare function normalizeSection(name: string): string;
+/**
+ * Find a section in markdown content and return its boundaries.
+ * Returns `{ start, end, headerEnd }` where the section body sits between
+ * this `## ` header and the next `## ` header (or EOF). `start` and
+ * `headerEnd` both point at the first character after the `## …\n` line;
+ * they exist as separate fields so callers can distinguish "where the body
+ * starts" from "where to anchor inserts".
+ */
+export declare function findSection(content: string, sectionName: string): {
+    start: number;
+    end: number;
+    headerEnd: number;
+} | null;
+/**
+ * Sum the byte length (including line terminators) of the first
+ * `upToIndex` lines. Used to convert a (lines, lineIndex) position back
+ * into an offset into the original string after `split("\n")`.
+ */
+export declare function sumLength(lines: string[], upToIndex: number): number;
+/**
+ * Enumerate every `## ` section header in the file in document order,
+ * returning their normalized names. Used to surface "did you mean X?"
+ * style hints when a PATCH targets a section that does not exist.
+ */
+export declare function getAvailableSections(content: string): string[];
+//# sourceMappingURL=section.d.ts.map

package/dist/core/context-validation/section.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../../src/core/context-validation/section.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAgC1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAK9D"}

package/dist/core/context-validation/section.js

@@ -0,0 +1,82 @@
+/**
+ * Pure helpers for locating `## Section` blocks in context-file markdown.
+ *
+ * Used by `/api/context` PATCH handlers and by `agent/journal` trim/clear
+ * logic. No I/O, no Hono — keep these importable from any layer.
+ *
+ * Section names are normalized case- and whitespace-insensitively so that
+ * the agent's freeform `## Raw signals` matches the literal `## Raw Signals`
+ * in the file. See `docs/design/06-memory.md` for the section vocabulary.
+ */
+/**
+ * Normalize a section name for matching:
+ * lowercase, spaces → underscores, strip leading `## `.
+ */
+export function normalizeSection(name) {
+    return name
+        .replace(/^#+\s*/, "")
+        .toLowerCase()
+        .replace(/\s+/g, "_");
+}
+/**
+ * Find a section in markdown content and return its boundaries.
+ * Returns `{ start, end, headerEnd }` where the section body sits between
+ * this `## ` header and the next `## ` header (or EOF). `start` and
+ * `headerEnd` both point at the first character after the `## …\n` line;
+ * they exist as separate fields so callers can distinguish "where the body
+ * starts" from "where to anchor inserts".
+ */
+export function findSection(content, sectionName) {
+    const normalized = normalizeSection(sectionName);
+    const lines = content.split("\n");
+    let sectionStart = -1;
+    let headerEnd = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].startsWith("## ")) {
+            const lineNormalized = normalizeSection(lines[i]);
+            if (lineNormalized === normalized) {
+                sectionStart = i;
+                const lineStart = sumLength(lines, i);
+                const nlPos = content.indexOf("\n", lineStart);
+                // Handle file ending without trailing newline
+                headerEnd = nlPos === -1 ? content.length : nlPos + 1;
+                break;
+            }
+        }
+    }
+    if (sectionStart === -1)
+        return null;
+    // Find end: next ## header or EOF
+    let sectionEnd = content.length;
+    for (let i = sectionStart + 1; i < lines.length; i++) {
+        if (lines[i].startsWith("## ")) {
+            sectionEnd = sumLength(lines, i);
+            break;
+        }
+    }
+    return { start: headerEnd, end: sectionEnd, headerEnd };
+}
+/**
+ * Sum the byte length (including line terminators) of the first
+ * `upToIndex` lines. Used to convert a (lines, lineIndex) position back
+ * into an offset into the original string after `split("\n")`.
+ */
+export function sumLength(lines, upToIndex) {
+    let len = 0;
+    for (let i = 0; i < upToIndex; i++) {
+        len += lines[i].length + 1; // +1 for \n
+    }
+    return len;
+}
+/**
+ * Enumerate every `## ` section header in the file in document order,
+ * returning their normalized names. Used to surface "did you mean X?"
+ * style hints when a PATCH targets a section that does not exist.
+ */
+export function getAvailableSections(content) {
+    return content
+        .split("\n")
+        .filter((l) => l.startsWith("## "))
+        .map((l) => normalizeSection(l));
+}
+//# sourceMappingURL=section.js.map

package/dist/core/context-validation/section.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.js","sourceRoot":"","sources":["../../../src/core/context-validation/section.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI;SACR,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,WAAW,EAAE;SACb,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,WAAmB;IAEnB,MAAM,UAAU,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC;IACtB,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;IAEnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,cAAc,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAClD,IAAI,cAAc,KAAK,UAAU,EAAE,CAAC;gBAClC,YAAY,GAAG,CAAC,CAAC;gBACjB,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;gBACtC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBAC/C,8CAA8C;gBAC9C,SAAS,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;gBACtD,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,YAAY,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAErC,kCAAkC;IAClC,IAAI,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrD,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,UAAU,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACjC,MAAM;QACR,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAe,EAAE,SAAiB;IAC1D,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,YAAY;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,OAAO;SACX,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;SAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC"}

package/dist/core/context-validation/snapshot-debounce.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure helpers for context-file write debouncing and bullet-entry retention.
+ *
+ * `SNAPSHOT_DEBOUNCE_MS` is the floor the route handler enforces between
+ * snapshot rows persisted to `md_file_snapshots`. Without it a busy section
+ * (e.g. `agent/journal` Raw Signals) would write a new row per append.
+ *
+ * The trim/clear helpers run during PATCH against bullet-list sections
+ * that grow unbounded — `agent/journal` Raw Signals (timestamp-clear) and
+ * any section with a `maxEntries` cap (FIFO trim). They preserve
+ * continuation lines (indented) and inter-entry blank lines, leaving
+ * non-bullet decoration (headings, prose) untouched.
+ */
+/**
+ * Minimum elapsed milliseconds between two snapshot rows for the same
+ * file. 5 minutes — picked so a chatty section (`agent/journal`) does
+ * not write a snapshot per append, while still capturing the dominant
+ * state of the file every ~5 min for forensics.
+ *
+ * The route handler accepts a `force` flag for non-routine triggers
+ * (e.g. archive-today, restore-snapshot) that must bypass the floor.
+ */
+export declare const SNAPSHOT_DEBOUNCE_MS: number;
+/**
+ * Parse a timestamp from a bullet entry like `- [2026-04-10 02:32:59] …`.
+ * Returns the timestamp string or null if the line doesn't match
+ * (plain bullets, blank lines, headers all return null).
+ */
+export declare function parseEntryTimestamp(line: string): string | null;
+/**
+ * Remove entries whose `- [YYYY-MM-DD HH:MM:SS]` timestamp is ≤ cutoff.
+ * Non-matching lines (blank lines, continuation lines, prose) are
+ * preserved except for the trailing continuation/blank lines that
+ * immediately follow a removed entry — those are dropped so the
+ * section does not accumulate orphaned whitespace.
+ */
+export declare function clearEntriesBefore(sectionBody: string, cutoff: string): {
+    remaining: string;
+    removedCount: number;
+};
+/**
+ * Trim oldest bullet entries (`- ` lines) from the top of a section
+ * body to keep at most `maxEntries` entries. Continuation lines
+ * (2-space indent) and inter-entry blank lines that belong to a removed
+ * entry are dropped along with it; non-bullet decorations elsewhere
+ * are preserved verbatim.
+ */
+export declare function trimBulletEntries(body: string, maxEntries: number): {
+    body: string;
+    trimmed: number;
+};
+//# sourceMappingURL=snapshot-debounce.d.ts.map

package/dist/core/context-validation/snapshot-debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-debounce.d.ts","sourceRoot":"","sources":["../../../src/core/context-validation/snapshot-debounce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,QAAgB,CAAC;AASlD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CA2B7C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAgCnC"}

package/dist/core/context-validation/snapshot-debounce.js

@@ -0,0 +1,110 @@
+/**
+ * Pure helpers for context-file write debouncing and bullet-entry retention.
+ *
+ * `SNAPSHOT_DEBOUNCE_MS` is the floor the route handler enforces between
+ * snapshot rows persisted to `md_file_snapshots`. Without it a busy section
+ * (e.g. `agent/journal` Raw Signals) would write a new row per append.
+ *
+ * The trim/clear helpers run during PATCH against bullet-list sections
+ * that grow unbounded — `agent/journal` Raw Signals (timestamp-clear) and
+ * any section with a `maxEntries` cap (FIFO trim). They preserve
+ * continuation lines (indented) and inter-entry blank lines, leaving
+ * non-bullet decoration (headings, prose) untouched.
+ */
+/**
+ * Minimum elapsed milliseconds between two snapshot rows for the same
+ * file. 5 minutes — picked so a chatty section (`agent/journal`) does
+ * not write a snapshot per append, while still capturing the dominant
+ * state of the file every ~5 min for forensics.
+ *
+ * The route handler accepts a `force` flag for non-routine triggers
+ * (e.g. archive-today, restore-snapshot) that must bypass the floor.
+ */
+export const SNAPSHOT_DEBOUNCE_MS = 5 * 60 * 1000;
+/**
+ * Bullet entries are expected to lead with `- [YYYY-MM-DD HH:MM:SS]`,
+ * the canonical timestamp the agent emits when appending to a Log /
+ * Raw Signals style section.
+ */
+const ENTRY_TIMESTAMP_RE = /^- \[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\]/;
+/**
+ * Parse a timestamp from a bullet entry like `- [2026-04-10 02:32:59] …`.
+ * Returns the timestamp string or null if the line doesn't match
+ * (plain bullets, blank lines, headers all return null).
+ */
+export function parseEntryTimestamp(line) {
+    const match = ENTRY_TIMESTAMP_RE.exec(line);
+    return match ? match[1] : null;
+}
+/**
+ * Remove entries whose `- [YYYY-MM-DD HH:MM:SS]` timestamp is ≤ cutoff.
+ * Non-matching lines (blank lines, continuation lines, prose) are
+ * preserved except for the trailing continuation/blank lines that
+ * immediately follow a removed entry — those are dropped so the
+ * section does not accumulate orphaned whitespace.
+ */
+export function clearEntriesBefore(sectionBody, cutoff) {
+    const lines = sectionBody.split("\n");
+    const kept = [];
+    let removedCount = 0;
+    let skipContinuation = false;
+    for (const line of lines) {
+        const ts = parseEntryTimestamp(line);
+        if (ts !== null) {
+            // This is a timestamped entry
+            if (ts <= cutoff) {
+                removedCount++;
+                skipContinuation = true;
+                continue;
+            }
+            skipContinuation = false;
+            kept.push(line);
+        }
+        else if (skipContinuation && (line.startsWith("  ") || line.trim() === "")) {
+            // Continuation or trailing blank line of a removed entry
+            continue;
+        }
+        else {
+            skipContinuation = false;
+            kept.push(line);
+        }
+    }
+    return { remaining: kept.join("\n"), removedCount };
+}
+/**
+ * Trim oldest bullet entries (`- ` lines) from the top of a section
+ * body to keep at most `maxEntries` entries. Continuation lines
+ * (2-space indent) and inter-entry blank lines that belong to a removed
+ * entry are dropped along with it; non-bullet decorations elsewhere
+ * are preserved verbatim.
+ */
+export function trimBulletEntries(body, maxEntries) {
+    const lines = body.split("\n");
+    // Collect indices of bullet entry start lines
+    const bulletIndices = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].startsWith("- ")) {
+            bulletIndices.push(i);
+        }
+    }
+    const excess = bulletIndices.length - maxEntries;
+    if (excess <= 0) {
+        return { body, trimmed: 0 };
+    }
+    // Remove the oldest (topmost) `excess` entries and their continuations.
+    // Also remove blank lines between consecutive removed entries to avoid
+    // orphaned whitespace accumulating over many trim cycles.
+    const removeSet = new Set();
+    for (let i = 0; i < excess; i++) {
+        const start = bulletIndices[i];
+        const end = i + 1 < bulletIndices.length ? bulletIndices[i + 1] : lines.length;
+        for (let j = start; j < end; j++) {
+            if (j === start || lines[j].startsWith("  ") || lines[j].trim() === "") {
+                removeSet.add(j);
+            }
+        }
+    }
+    const kept = lines.filter((_, i) => !removeSet.has(i));
+    return { body: kept.join("\n"), trimmed: excess };
+}
+//# sourceMappingURL=snapshot-debounce.js.map

package/dist/core/context-validation/snapshot-debounce.js.map

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

package/dist/core/context-validation/today.d.ts

@@ -0,0 +1,85 @@
+import { type TodayAgentPlanMetadata } from "../today-agent-plan.js";
+/**
+ * Validators and shape helpers for the `today.md` context file.
+ *
+ * `today.md` is the agent's daily working surface. Its line-1 header is
+ * the canonical agent-day date; its `## Agent Plan` rows feed the
+ * scheduler that fires `→DM` / `→notify` / `→check-in` / `→wake` actions
+ * at their listed times. Both halves are parsed by every downstream
+ * event handler, so the schema is enforced server-side at write time
+ * with explicit messages that the agent can self-correct from.
+ */
+/**
+ * Canonical `## ` section headers, in document order. The validator
+ * walks the file once and requires each to appear after the previous
+ * one — extra sections may sit between them but the relative order is
+ * fixed.
+ */
+export declare const TODAY_REQUIRED_SECTIONS: readonly ["User Schedule", "User Tasks", "Agent Plan", "Agent Notes", "Agent Log", "Handoff"];
+/**
+ * Line 1: `# YYYY-MM-DD (day-of-week)`. Date and dashes are ASCII;
+ * only the optional `(...)` weekday may be localized into the user's
+ * primary language. The capture group is consulted to compare against
+ * the current agent-day date when the route handler passes
+ * `expectedAgentDay`.
+ */
+export declare const TODAY_H1_RE: RegExp;
+/**
+ * Line 2: `> Day type: Weekday|Weekend | Work focus: on|off | …`.
+ * This line is parsed by every event handler — keep the casing,
+ * pipe separators, and `> ` prefix exact ASCII.
+ */
+export declare const TODAY_DAY_TYPE_RE: RegExp;
+/**
+ * Pre-schema legacy form — first line literally `# Today`. Recognized
+ * only when the route handler explicitly opts in via
+ * `allowLegacyToday`; used to bridge old fixtures during reload paths
+ * that don't carry the agent-day context.
+ */
+export declare function isLegacyTodayContent(content: string): boolean;
+/**
+ * Validate a `today.md` payload for the canonical schema.
+ *
+ * Returns a human-readable error message string, or `null` if the
+ * content is valid. The caller maps `null` to 200 and any string to
+ * 400. Messages echo both the expected and observed shape so the
+ * agent gets immediate feedback and can correct the offending line in
+ * the same session — see EXECUTION-MODE-DESIGN follow-up
+ * §morning-routine for the rationale.
+ */
+export declare function validateTodayContent(content: string, options?: {
+    allowLegacyToday?: boolean;
+    expectedAgentDay?: string;
+}): string | null;
+export interface TodayScheduleCandidate {
+    id: number;
+    scheduledFor: string;
+    localDate: string;
+    localTime: string;
+    taskType: string;
+    status: string;
+    description: string | null;
+    taskContext: Record<string, unknown>;
+}
+export interface AgentPlanScheduleCandidate extends TodayScheduleCandidate {
+    agentPlan: TodayAgentPlanMetadata;
+}
+/**
+ * Project a raw `agent_schedule` row into a `today.md`-reconciliation
+ * candidate: derive the local date/time in the caller's timezone, lift
+ * the task-context blob into an object, and surface the canonical row
+ * id so the route handler can correlate against parsed Agent Plan rows.
+ *
+ * Returns `null` for rows with an unparseable `scheduled_for`, so the
+ * caller can `.filter(Boolean)` past corrupt timestamps without
+ * crashing the reconciliation pass.
+ */
+export declare function toTodayScheduleCandidate(row: {
+    id: number;
+    scheduled_for: string;
+    task_type: string;
+    task_description: string | null;
+    task_context: string | null;
+    status: string;
+}, timezone: string | undefined): TodayScheduleCandidate | null;
+//# sourceMappingURL=today.d.ts.map

package/dist/core/context-validation/today.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"today.d.ts","sourceRoot":"","sources":["../../../src/core/context-validation/today.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,+FAO1B,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,QAAyC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,QACkF,CAAC;AAEjH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GACtE,MAAM,GAAG,IAAI,CAuEf;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,0BAA2B,SAAQ,sBAAsB;IACxE,SAAS,EAAE,sBAAsB,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE;IACH,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB,EACD,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,sBAAsB,GAAG,IAAI,CAgB/B"}