poe-code 3.0.184 → 3.0.186

package/packages/config-mutations/dist/mutations/template-mutation.js

@@ -0,0 +1,32 @@
+function write(options) {
+    return {
+        kind: "templateWrite",
+        target: options.target,
+        templateId: options.templateId,
+        context: options.context,
+        label: options.label
+    };
+}
+function mergeToml(options) {
+    return {
+        kind: "templateMergeToml",
+        target: options.target,
+        templateId: options.templateId,
+        context: options.context,
+        label: options.label
+    };
+}
+function mergeJson(options) {
+    return {
+        kind: "templateMergeJson",
+        target: options.target,
+        templateId: options.templateId,
+        context: options.context,
+        label: options.label
+    };
+}
+export const templateMutation = {
+    write,
+    mergeToml,
+    mergeJson
+};

package/packages/config-mutations/dist/template/render.d.ts

@@ -0,0 +1,7 @@
+export type TemplateVariables = Record<string, string | number | boolean | string[]>;
+/**
+ * Render a mustache template with the given variables.
+ * Arrays are automatically joined with newlines.
+ * HTML escaping is disabled.
+ */
+export declare function renderTemplate(template: string, variables: TemplateVariables): string;

package/packages/config-mutations/dist/template/render.js

@@ -0,0 +1,28 @@
+import Mustache from "mustache";
+// Disable HTML escaping - we're rendering prompts, not HTML
+const originalEscape = Mustache.escape;
+/**
+ * Render a mustache template with the given variables.
+ * Arrays are automatically joined with newlines.
+ * HTML escaping is disabled.
+ */
+export function renderTemplate(template, variables) {
+    // Pre-process variables to handle arrays
+    const processed = {};
+    for (const [key, value] of Object.entries(variables)) {
+        if (Array.isArray(value)) {
+            processed[key] = value.join("\n");
+        }
+        else {
+            processed[key] = value;
+        }
+    }
+    // Temporarily disable HTML escaping
+    Mustache.escape = (text) => text;
+    try {
+        return Mustache.render(template, processed);
+    }
+    finally {
+        Mustache.escape = originalEscape;
+    }
+}

package/packages/config-mutations/dist/testing/format-utils.d.ts

@@ -0,0 +1,7 @@
+import type { ConfigObject } from "../types.js";
+export declare function parseToml(content: string): ConfigObject;
+export declare function serializeToml(obj: ConfigObject): string;
+export declare function parseJson(content: string): ConfigObject;
+export declare function serializeJson(obj: ConfigObject): string;
+export declare function parseYaml(content: string): ConfigObject;
+export declare function serializeYaml(obj: ConfigObject): string;

package/packages/config-mutations/dist/testing/format-utils.js

@@ -0,0 +1,21 @@
+import { jsonFormat } from "../formats/json.js";
+import { tomlFormat } from "../formats/toml.js";
+import { yamlFormat } from "../formats/yaml.js";
+export function parseToml(content) {
+    return tomlFormat.parse(content);
+}
+export function serializeToml(obj) {
+    return tomlFormat.serialize(obj);
+}
+export function parseJson(content) {
+    return jsonFormat.parse(content);
+}
+export function serializeJson(obj) {
+    return jsonFormat.serialize(obj);
+}
+export function parseYaml(content) {
+    return yamlFormat.parse(content);
+}
+export function serializeYaml(obj) {
+    return yamlFormat.serialize(obj);
+}

package/packages/config-mutations/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { createMockFs } from "./mock-fs.js";
+export type { MockFileSystem } from "./mock-fs.js";
+export { parseToml, serializeToml, parseJson, serializeJson, parseYaml, serializeYaml } from "./format-utils.js";

package/packages/config-mutations/dist/testing/index.js

@@ -0,0 +1,2 @@
+export { createMockFs } from "./mock-fs.js";
+export { parseToml, serializeToml, parseJson, serializeJson, parseYaml, serializeYaml } from "./format-utils.js";

package/packages/config-mutations/dist/testing/mock-fs.d.ts

@@ -0,0 +1,25 @@
+import type { FileSystem } from "../types.js";
+export interface MockFileSystem extends FileSystem {
+    /** Current file contents, keyed by absolute path */
+    files: Record<string, string>;
+    /** Created directories */
+    directories: Set<string>;
+    /** Check if a path exists (file or directory) */
+    exists(path: string): boolean;
+    /** Get file content or undefined if not found */
+    getContent(path: string): string | undefined;
+    /** Read file with encoding overloads for compatibility */
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    readFile(path: string): Promise<Buffer>;
+}
+export interface MockFsOptions {
+    /** Initial files - paths can use ~ which will be expanded to homeDir */
+    [path: string]: string;
+}
+/**
+ * Create an in-memory mock filesystem for testing mutations.
+ *
+ * @param initialFiles - Initial files to populate the filesystem with
+ * @param homeDir - Home directory for ~ expansion (defaults to /home/test)
+ */
+export declare function createMockFs(initialFiles?: MockFsOptions, homeDir?: string): MockFileSystem;

package/packages/config-mutations/dist/testing/mock-fs.js

@@ -0,0 +1,170 @@
+import path from "node:path";
+const DEFAULT_HOME_DIR = "/home/test";
+/**
+ * Create an in-memory mock filesystem for testing mutations.
+ *
+ * @param initialFiles - Initial files to populate the filesystem with
+ * @param homeDir - Home directory for ~ expansion (defaults to /home/test)
+ */
+export function createMockFs(initialFiles, homeDir = DEFAULT_HOME_DIR) {
+    const files = {};
+    const directories = new Set();
+    // Initialize with provided files
+    if (initialFiles) {
+        for (const [filePath, content] of Object.entries(initialFiles)) {
+            const absolutePath = expandPath(filePath, homeDir);
+            files[absolutePath] = content;
+            // Ensure parent directories exist
+            const parentDir = path.dirname(absolutePath);
+            addDirectoryTree(parentDir, directories);
+        }
+    }
+    // Ensure home directory exists
+    addDirectoryTree(homeDir, directories);
+    const mockFs = {
+        files,
+        directories,
+        exists(filePath) {
+            const absolutePath = expandPath(filePath, homeDir);
+            return absolutePath in files || directories.has(absolutePath);
+        },
+        getContent(filePath) {
+            const absolutePath = expandPath(filePath, homeDir);
+            return files[absolutePath];
+        },
+        async readFile(filePath, encoding) {
+            const absolutePath = expandPath(filePath, homeDir);
+            if (!(absolutePath in files)) {
+                const error = new Error(`ENOENT: no such file or directory, open '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            const content = files[absolutePath];
+            if (encoding) {
+                return content;
+            }
+            return Buffer.from(content, "utf8");
+        },
+        async writeFile(filePath, content, options) {
+            void options; // TypeScript satisfaction
+            const absolutePath = expandPath(filePath, homeDir);
+            // Ensure parent directory exists
+            const parentDir = path.dirname(absolutePath);
+            if (!directories.has(parentDir)) {
+                const error = new Error(`ENOENT: no such file or directory, open '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            if (typeof content === "string") {
+                files[absolutePath] = content;
+            }
+            else if (Buffer.isBuffer(content)) {
+                files[absolutePath] = content.toString("utf8");
+            }
+            else {
+                files[absolutePath] = Buffer.from(content.buffer, content.byteOffset, content.byteLength).toString("utf8");
+            }
+        },
+        async mkdir(dirPath, options) {
+            const absolutePath = expandPath(dirPath, homeDir);
+            if (options?.recursive) {
+                addDirectoryTree(absolutePath, directories);
+            }
+            else {
+                // Check parent exists
+                const parentDir = path.dirname(absolutePath);
+                if (parentDir !== absolutePath && !directories.has(parentDir)) {
+                    const error = new Error(`ENOENT: no such file or directory, mkdir '${absolutePath}'`);
+                    error.code = "ENOENT";
+                    throw error;
+                }
+                directories.add(absolutePath);
+            }
+        },
+        async unlink(filePath) {
+            const absolutePath = expandPath(filePath, homeDir);
+            if (!(absolutePath in files)) {
+                const error = new Error(`ENOENT: no such file or directory, unlink '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            delete files[absolutePath];
+        },
+        async stat(filePath) {
+            const absolutePath = expandPath(filePath, homeDir);
+            if (absolutePath in files) {
+                return { mode: 0o644 };
+            }
+            if (directories.has(absolutePath)) {
+                return { mode: 0o755 };
+            }
+            const error = new Error(`ENOENT: no such file or directory, stat '${absolutePath}'`);
+            error.code = "ENOENT";
+            throw error;
+        },
+        async readdir(dirPath) {
+            const absolutePath = expandPath(dirPath, homeDir);
+            if (absolutePath in files) {
+                const error = new Error(`ENOTDIR: not a directory, scandir '${absolutePath}'`);
+                error.code = "ENOTDIR";
+                throw error;
+            }
+            if (!directories.has(absolutePath)) {
+                const error = new Error(`ENOENT: no such file or directory, scandir '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            const entries = new Set();
+            for (const filePath of Object.keys(files)) {
+                if (path.dirname(filePath) === absolutePath) {
+                    entries.add(path.basename(filePath));
+                }
+            }
+            for (const dir of directories) {
+                if (dir !== absolutePath && path.dirname(dir) === absolutePath) {
+                    entries.add(path.basename(dir));
+                }
+            }
+            return Array.from(entries);
+        },
+        async chmod(filePath, mode) {
+            void mode; // In mock fs, we don't actually store mode changes
+            const absolutePath = expandPath(filePath, homeDir);
+            if (!(absolutePath in files) && !directories.has(absolutePath)) {
+                const error = new Error(`ENOENT: no such file or directory, chmod '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            // Mode change is a no-op in mock fs but we don't throw
+        }
+    };
+    return mockFs;
+}
+/**
+ * Expand ~ to homeDir in a path.
+ */
+function expandPath(inputPath, homeDir) {
+    if (inputPath.startsWith("~/")) {
+        return path.join(homeDir, inputPath.slice(2));
+    }
+    if (inputPath === "~") {
+        return homeDir;
+    }
+    if (inputPath.startsWith("~")) {
+        // ~something (not ~/) - treat as relative path from home
+        return path.join(homeDir, inputPath.slice(1));
+    }
+    return inputPath;
+}
+/**
+ * Add a directory and all its parent directories to the set.
+ */
+function addDirectoryTree(dirPath, directories) {
+    const parts = dirPath.split(path.sep).filter(Boolean);
+    let current = "/";
+    directories.add(current);
+    for (const part of parts) {
+        current = path.join(current, part);
+        directories.add(current);
+    }
+}

package/packages/config-mutations/dist/types.d.ts

@@ -0,0 +1,156 @@
+export type ConfigPrimitive = string | number | boolean | null;
+export type ConfigValue = ConfigPrimitive | ConfigObject | ConfigArray | Date;
+export interface ConfigObject {
+    [key: string]: ConfigValue;
+}
+export type ConfigArray = ConfigValue[];
+export declare function isConfigObject(value: unknown): value is ConfigObject;
+export interface FileSystem {
+    readFile(path: string, encoding: "utf8"): Promise<string>;
+    writeFile(path: string, content: string, options?: {
+        encoding: "utf8";
+    }): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive: boolean;
+    }): Promise<void>;
+    unlink(path: string): Promise<void>;
+    rm?(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    readdir(path: string): Promise<string[]>;
+    chmod?(path: string, mode: number): Promise<void>;
+}
+export type TemplateLoader = (templateId: string) => Promise<string>;
+export interface ConfigFormat {
+    /** Parse string content into object */
+    parse(content: string): ConfigObject;
+    /** Serialize object to string (with consistent formatting) */
+    serialize(obj: ConfigObject): string;
+    /** Deep merge patch into base, returning new object */
+    merge(base: ConfigObject, patch: ConfigObject): ConfigObject;
+    /** Remove keys matching shape from object, returning new object */
+    prune(obj: ConfigObject, shape: ConfigObject): {
+        changed: boolean;
+        result: ConfigObject;
+    };
+}
+export interface PathMapper {
+    /** Map a target directory to a different location (e.g., for isolated configs) */
+    mapTargetDirectory(input: {
+        targetDirectory: string;
+    }): string;
+}
+export interface MutationContext {
+    /** Filesystem interface - required */
+    fs: FileSystem;
+    /** Home directory for ~ expansion - required */
+    homeDir: string;
+    /** Optional dry-run mode */
+    dryRun?: boolean;
+    /** Optional observers for logging */
+    observers?: MutationObservers;
+    /** Required for template mutations */
+    templates?: TemplateLoader;
+    /** Optional path mapper for redirecting paths (used for isolated configs) */
+    pathMapper?: PathMapper;
+}
+export interface MutationOptions {
+    [key: string]: unknown;
+}
+export type ValueResolver<T> = T | ((ctx: MutationOptions) => T);
+interface BaseMutation {
+    /** Human-readable label for logging */
+    label?: string;
+}
+export interface ConfigMergeMutation extends BaseMutation {
+    kind: "configMerge";
+    target: ValueResolver<string>;
+    value: ValueResolver<ConfigObject>;
+    format?: "json" | "toml" | "yaml";
+    pruneByPrefix?: Record<string, string>;
+}
+export interface ConfigPruneMutation extends BaseMutation {
+    kind: "configPrune";
+    target: ValueResolver<string>;
+    shape: ValueResolver<ConfigObject>;
+    format?: "json" | "toml" | "yaml";
+    onlyIf?: (doc: ConfigObject, ctx: MutationOptions) => boolean;
+}
+export interface ConfigTransformMutation extends BaseMutation {
+    kind: "configTransform";
+    target: ValueResolver<string>;
+    format?: "json" | "toml" | "yaml";
+    transform: (content: ConfigObject, ctx: MutationOptions) => {
+        content: ConfigObject | null;
+        changed: boolean;
+    };
+}
+export interface EnsureDirectoryMutation extends BaseMutation {
+    kind: "ensureDirectory";
+    path: ValueResolver<string>;
+}
+export interface RemoveDirectoryMutation extends BaseMutation {
+    kind: "removeDirectory";
+    path: ValueResolver<string>;
+    force?: boolean;
+}
+export interface RemoveFileMutation extends BaseMutation {
+    kind: "removeFile";
+    target: ValueResolver<string>;
+    whenEmpty?: boolean;
+    whenContentMatches?: RegExp;
+}
+export interface ChmodMutation extends BaseMutation {
+    kind: "chmod";
+    target: ValueResolver<string>;
+    mode: number;
+}
+export interface BackupMutation extends BaseMutation {
+    kind: "backup";
+    target: ValueResolver<string>;
+}
+export interface TemplateWriteMutation extends BaseMutation {
+    kind: "templateWrite";
+    target: ValueResolver<string>;
+    templateId: string;
+    context?: ValueResolver<ConfigObject>;
+}
+export interface TemplateMergeTomlMutation extends BaseMutation {
+    kind: "templateMergeToml";
+    target: ValueResolver<string>;
+    templateId: string;
+    context?: ValueResolver<ConfigObject>;
+}
+export interface TemplateMergeJsonMutation extends BaseMutation {
+    kind: "templateMergeJson";
+    target: ValueResolver<string>;
+    templateId: string;
+    context?: ValueResolver<ConfigObject>;
+}
+export type Mutation = ConfigMergeMutation | ConfigPruneMutation | ConfigTransformMutation | EnsureDirectoryMutation | RemoveDirectoryMutation | RemoveFileMutation | ChmodMutation | BackupMutation | TemplateWriteMutation | TemplateMergeTomlMutation | TemplateMergeJsonMutation;
+export type MutationEffect = "none" | "mkdir" | "write" | "delete" | "chmod" | "copy";
+export type MutationDetail = "create" | "update" | "delete" | "noop" | "backup";
+export interface MutationOutcome {
+    changed: boolean;
+    effect: MutationEffect;
+    detail?: MutationDetail;
+}
+export interface MutationDetails {
+    kind: string;
+    label: string;
+    targetPath?: string;
+}
+export interface MutationObservers {
+    onStart?(details: MutationDetails): void;
+    onComplete?(details: MutationDetails, outcome: MutationOutcome): void;
+    onError?(details: MutationDetails, error: unknown): void;
+}
+export interface MutationResult {
+    changed: boolean;
+    effects: MutationOutcome[];
+}
+export {};

package/packages/config-mutations/dist/types.js

@@ -0,0 +1,6 @@
+// ============================================================================
+// Config Object Types
+// ============================================================================
+export function isConfigObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/memory/dist/audit.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryRoot } from "./types.js";
+export type AuditClaimsOptions = {
+    minInferredConfidence?: number;
+    rejectUntagged?: boolean;
+    untaggedBodyThresholdChars?: number;
+};
+export type PageAudit = {
+    page: string;
+    issues: string[];
+};
+export declare function auditClaims(root: MemoryRoot, repoRoot: string, options?: AuditClaimsOptions): Promise<PageAudit[]>;

package/packages/memory/dist/audit.js

@@ -0,0 +1,131 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { parseClaims } from "./confidence.js";
+import { serializeSourceRef } from "./frontmatter.js";
+import { listPages } from "./pages.js";
+const DEFAULT_MIN_INFERRED_CONFIDENCE = 0.3;
+const DEFAULT_REJECT_UNTAGGED = false;
+const DEFAULT_UNTAGGED_BODY_THRESHOLD_CHARS = 200;
+export async function auditClaims(root, repoRoot, options = {}) {
+    const minInferredConfidence = options.minInferredConfidence ?? DEFAULT_MIN_INFERRED_CONFIDENCE;
+    const rejectUntagged = options.rejectUntagged ?? DEFAULT_REJECT_UNTAGGED;
+    const untaggedBodyThresholdChars = options.untaggedBodyThresholdChars ?? DEFAULT_UNTAGGED_BODY_THRESHOLD_CHARS;
+    const sourceCache = new Map();
+    const pages = await listPages(root);
+    const audits = [];
+    for (const page of pages) {
+        const issues = [];
+        let claims;
+        try {
+            claims = parseClaims(page.body);
+        }
+        catch (error) {
+            issues.push(formatError(error));
+            audits.push({ page: page.relPath, issues });
+            continue;
+        }
+        if (rejectUntagged && claims.length === 0 && page.body.trim().length > untaggedBodyThresholdChars) {
+            issues.push(`Page has a long untagged body (>${untaggedBodyThresholdChars} chars) with no memory:* tags.`);
+        }
+        const inlineSources = new Set();
+        for (const claim of claims) {
+            if (claim.tag.verb === "inferred" && claim.tag.confidence < minInferredConfidence) {
+                issues.push(`Claim on line ${claim.lineNumber} uses inferred confidence=${claim.tag.confidence}, below the minimum ${minInferredConfidence}.`);
+            }
+            const source = "source" in claim.tag ? claim.tag.source : undefined;
+            if (source === undefined) {
+                continue;
+            }
+            const serializedSource = serializeSourceRef(source);
+            inlineSources.add(serializedSource);
+            const sourceIssue = await auditSourceRef(source, claim.lineNumber, repoRoot, sourceCache);
+            if (sourceIssue !== undefined) {
+                issues.push(sourceIssue);
+            }
+        }
+        issues.push(...auditFrontmatterSources(page.frontmatter.sources ?? [], inlineSources));
+        if (issues.length > 0) {
+            audits.push({ page: page.relPath, issues });
+        }
+    }
+    return audits;
+}
+async function auditSourceRef(source, claimLineNumber, repoRoot, sourceCache) {
+    if (isUrlLike(source.path)) {
+        return undefined;
+    }
+    if (path.isAbsolute(source.path)) {
+        return `Claim on line ${claimLineNumber} cites "${serializeSourceRef(source)}", but source paths must be repo-relative or URLs.`;
+    }
+    const absPath = path.resolve(repoRoot, source.path);
+    if (!isWithinRoot(repoRoot, absPath)) {
+        return `Claim on line ${claimLineNumber} cites "${serializeSourceRef(source)}", which resolves outside the repo root.`;
+    }
+    const meta = await readSourceFile(absPath, sourceCache);
+    if (!meta.exists) {
+        return `Claim on line ${claimLineNumber} cites "${serializeSourceRef(source)}", resolved to "${meta.absPath}", but the file does not exist.`;
+    }
+    const lastReferencedLine = source.endLine ?? source.startLine;
+    if (lastReferencedLine !== undefined && lastReferencedLine > meta.lineCount) {
+        return `Claim on line ${claimLineNumber} cites "${serializeSourceRef(source)}", but current EOF ${meta.lineCount} is before the referenced line.`;
+    }
+    return undefined;
+}
+function auditFrontmatterSources(frontmatterSources, inlineSources) {
+    const serializedFrontmatterSources = new Set(frontmatterSources.map((source) => serializeSourceRef(source)));
+    const issues = [];
+    const missingSources = [...inlineSources].filter((source) => !serializedFrontmatterSources.has(source));
+    for (const source of missingSources.sort((left, right) => left.localeCompare(right))) {
+        issues.push(`Page frontmatter sources are missing "${source}" from inline tags.`);
+    }
+    const staleSources = [...serializedFrontmatterSources].filter((source) => !inlineSources.has(source));
+    for (const source of staleSources.sort((left, right) => left.localeCompare(right))) {
+        issues.push(`Page frontmatter sources contain stale entry "${source}" not found in inline tags.`);
+    }
+    return issues;
+}
+function readSourceFile(absPath, sourceCache) {
+    const cached = sourceCache.get(absPath);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const pending = fs
+        .readFile(absPath, "utf8")
+        .then((content) => ({
+        exists: true,
+        absPath,
+        lineCount: countLines(content)
+    }))
+        .catch((error) => {
+        if (isMissing(error)) {
+            return {
+                exists: false,
+                absPath
+            };
+        }
+        throw error;
+    });
+    sourceCache.set(absPath, pending);
+    return pending;
+}
+function countLines(content) {
+    if (content.length === 0) {
+        return 0;
+    }
+    const normalized = content.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+    const trimmed = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
+    return trimmed.length === 0 ? 0 : trimmed.split("\n").length;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function isUrlLike(value) {
+    return /^[a-z][a-z\d+.-]*:\/\//i.test(value);
+}
+function isWithinRoot(root, absPath) {
+    const relative = path.relative(root, absPath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}

package/packages/memory/dist/cache.cli.d.ts

@@ -0,0 +1,9 @@
+import type { MemoryRoot } from "./types.js";
+export declare function runMemoryCacheStatus(): Promise<void>;
+export declare function runMemoryCacheClear(input: {
+    root: MemoryRoot;
+    olderThan?: string;
+    yes?: boolean;
+}): Promise<{
+    removed: number;
+}>;

package/packages/memory/dist/cache.cli.js

@@ -0,0 +1,24 @@
+import parseDuration from "parse-duration";
+import { clearCache } from "./cache.js";
+export async function runMemoryCacheStatus() {
+    console.log("cache status not implemented yet");
+}
+export async function runMemoryCacheClear(input) {
+    if (!input.yes) {
+        throw new Error("Refusing to clear cache without --yes.");
+    }
+    const olderThanMs = parseOlderThan(input.olderThan);
+    const result = await clearCache(input.root, olderThanMs === undefined ? {} : { olderThanMs });
+    console.log(`removed ${result.removed} cache ${result.removed === 1 ? "entry" : "entries"}`);
+    return result;
+}
+function parseOlderThan(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const duration = parseDuration(value);
+    if (duration === null || Number.isNaN(duration) || duration < 0) {
+        throw new Error(`Invalid duration for --older-than: "${value}".`);
+    }
+    return duration;
+}

package/packages/memory/dist/cache.d.ts

@@ -0,0 +1,14 @@
+import type { IngestCacheEntry, IngestCacheKey, MemoryRoot } from "./types.js";
+export declare function computeIngestKey(input: {
+    sourceBytes: Buffer;
+    indexMdBytes: Buffer;
+    promptTemplateVersion: string;
+    agentId: string;
+}): IngestCacheKey;
+export declare function readCacheEntry(root: MemoryRoot, key: IngestCacheKey): Promise<IngestCacheEntry | null>;
+export declare function writeCacheEntry(root: MemoryRoot, entry: IngestCacheEntry): Promise<void>;
+export declare function clearCache(root: MemoryRoot, opts?: {
+    olderThanMs?: number;
+}): Promise<{
+    removed: number;
+}>;