dsh-continual-evolve 0.10.6 → 0.12.0

package/lib/planner.js

@@ -1,144 +0,0 @@
-import { parseProposal } from "./plan.js";
-import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
-import { recentUserText, sessionEventsOf } from "./inject.js";
-import { buildPrefixMessages, detectPlannerRoute, resolvePrefixCache } from "./prefix-cache.js";
-import { skillQualityGuide } from "./skillquality.js";
-import { asLlmSessionId, streamText } from "./llm-text.js";
-import { createTokenUsageObserver } from "./token-usage.js";
-import { recordLanguageInstruction, resolveRecordLanguage } from "./record-language.js";
-export const PLANNER_SYSTEM_PROMPT = `You are the /evolve continual harness subsystem.
-
-Your job is to improve the editable continual harness state. Instead of
-summarizing the conversation you emit precise Create, Update, or Delete edits
-to reusable state: prompt notes, memories, skills, and subagent specs.
-
-Rules:
-- The base system prompt is immutable and MUST NOT be rewritten (never edit id "base_system_prompt").
-- Prefer small evidence-backed edits. If no useful edit is justified, return an empty edits array.
-- Repeated evidence is mandatory for prompt/skill/subagent proposals: the same
-  pattern must recur at least twice in the trajectory. A single one-off
-  interaction never justifies a prompt, skill, or subagent edit — return an
-  empty edits array with a rationale instead. Session-scoped local prompt
-  landings converge on /evolve wrapup human review; the turn pipeline must
-  not silently persist one-off abstractions.
-- prompt = narrow behavioral policy addendums; memory = ONE FACT per entry, typed via metadata.memoryType
--   (user = who the user is; feedback = a pitfall/correction or confirmed approach, MUST carry Why + How to apply;
--   project = work goal/constraint not derivable from the repo; reference = URL/dashboard/ticket pointer).
--   Memory rules: one fact per entry (title = one-line retrieval hook, content = the fact alone);
--   never save what the repo already records (code structure, past fixes, git history, AGENTS.md) or what only
--   matters to this conversation — save the non-obvious point instead; before creating, update the existing
--   entry when one already covers the fact (creates carry metadata {memoryType} or they are rejected);
--   skill = repeatable procedures (must carry a python reference {type:"python", import, callable}
-  and an arguments object); subagent = reusable delegation roles.
-- Skill entries are authored to the DSH skill quality standard
-  (skill-creator, distilled from the official deepseek-harness 11 skills;
-  the full facts are provided in the <skill_quality_standard> block below):
-  only for a REAL trigger scenario grounded in the trajectory
-  (who, in what real task, what signal) — never invent one to pad the store;
-  never duplicate the official 11 skills or existing entries; content is a
-  SKILL.md document (frontmatter routing with "use when / do not use when"
-  description, boundary declaration, prerequisites and exclusions, layered
-  information, verifiable completion criteria). Self-check every proposed
-  skill against the 7 structural features and state the result in its
-  reason field.
-- Repeated multi-step workflows (session start/end routines, recurring
-  wrap-up or handoff procedures) may be proposed as guidance skills:
-  kind=skill, skill_kind="guidance", content = a SKILL.md document (no
-  python reference — executable skills keep requiring reference +
-  arguments). Only propose with repeated evidence in the trajectory, never
-  for one-off flows. Guidance skills materialize as discoverable SKILL.md
-  files under <skillsRoot>/<kebab-name>/SKILL.md and are always offered to
-  the user for a decision before they land.
-- Local edits are session-scoped; global edits persist across sessions.
-- Gap C2: EVERY edit MUST include a "blastRadius" field indicating how broadly
-  the edit applies: "general" (cross-project tactical rule, applies everywhere),
-  "project" (valid for the current project/repo), or "session" (one-off,
-  specific to this session's context). The review gate validates that
-  local-scope edits use "session" or "project", and global-scope edits use
-  "general" or "project". When in doubt, prefer narrower blast radius.
-- Ground every edit in evidence: the session trajectory (recent direct user
-  messages) is provided when available; prefer edits backed by it over
-  speculation, and never invent preferences the user did not express.
-- Stale entries (superseded by newer ones, never referenced in recent
-  trajectories, obsolete facts): propose action "archive" instead of
-  "delete" — archive hides the entry from injection while keeping its data
-  restorable; it requires only kind + id.
-- Output JSON only, exactly this shape:
-{
-  "summary": "one sentence",
-  "rationale": "why these edits are justified by the evidence",
-  "expectedOutcome": "what should improve and how to validate it",
-  "edits": [
-    {
-      "action": "create|update|delete",
-      "kind": "prompt|memory|skill|subagent",
-      "id": "stable id for update/delete, optional for create",
-      "title": "required for create/update except delete",
-      "content": "required for create/update except delete",
-      "path": "optional grouping path",
-      "reference": {"type":"python","import":"pkg.mod","callable":"fn"} ,
-      "arguments": {"name": {"type":"string","required":true,"description":"..."}},
-      "skill_kind": "executable|guidance (optional; skill kind only — guidance = SKILL.md document without reference)",
-      "metadata": {},
-      "reason": "why this edit is useful",
-      "blastRadius": "general|project|session"
-    }
-  ]
-}`;
-export async function planWithLlm(ctx, options) {
-    const { agent, state, history } = options;
-    if (!agent.options.provider || !agent.options.model) {
-        throw new Error("evolve: the calling agent has no provider/model route to plan with");
-    }
-    const scopeInstruction = options.global
-        ? "Requested scope: global. Only propose stable cross-session lessons, durable preferences, reusable skills/subagents, or explicitly project-qualified facts."
-        : "Requested scope: local. Propose session-scoped edits only when the trajectory shows repeated evidence (>=2 occurrences of the same pattern); a single one-off interaction returns an empty edits array. Global entries are read-only context — do not propose update/delete for them.";
-    // Ground the plan in the caller's session: Route A carries the context
-    // as a session-derived message prefix (cache-eligible on providers with
-    // prompt caching) and drops the auto-extracted trajectory block; Route B
-    // keeps the legacy flat-text block. An empty prefix falls back to B.
-    const events = options.trajectoryEvents ?? sessionEventsOf(agent);
-    const routing = resolvePrefixCache(options.prefixCache);
-    const route = detectPlannerRoute(events, routing.mode);
-    let prefixMessages = [];
-    if (route === "A") {
-        prefixMessages = buildPrefixMessages(events, {
-            ...(agent.options.provider ? { provider: agent.options.provider } : {}),
-            ...(agent.options.model ? { model: agent.options.model } : {}),
-            maxChars: routing.maxChars,
-        });
-    }
-    const trajectory = prefixMessages.length > 0 ? (options.trajectory ?? "") : (options.trajectory ?? recentUserText(agent));
-    const language = options.language ?? resolveRecordLanguage({ ctx, trajectoryText: trajectory });
-    // The skill quality standard is always present: the skill-creator
-    // template facts when installed, the builtin distilled guide otherwise
-    // (~1KB — planning is low-frequency, and the standard keeps skill
-    // proposals from drifting off the quality bar).
-    const qualityGuide = skillQualityGuide(options.skillsRoot);
-    const userPrompt = [
-        `<current_harness_state>\n${formatHarnessStateForPrompt(state)}\n</current_harness_state>`,
-        `<refinement_history>\n${historyForPrompt(history)}\n</refinement_history>`,
-        `<scope_policy>\n${scopeInstruction}\n</scope_policy>`,
-        trajectory ? `<session_trajectory>\n${trajectory}\n</session_trajectory>` : "",
-        `<skill_quality_standard>\n${qualityGuide.text}\n</skill_quality_standard>`,
-        options.instructions ? `<user_instructions>\n${options.instructions}\n</user_instructions>` : "",
-        "Return only JSON edits. If no useful edit is justified, return an empty edits array with a rationale.",
-    ]
-        .filter(Boolean)
-        .join("\n\n");
-    const text = await streamText(ctx, {
-        provider: agent.options.provider,
-        model: agent.options.model,
-        sessionId: asLlmSessionId(agent.id),
-        system: `${PLANNER_SYSTEM_PROMPT}\n\n${recordLanguageInstruction(language)}`,
-        prompt: userPrompt,
-        maxTokens: options.maxOutputTokens ?? 8000,
-        signal: options.signal,
-        ...(prefixMessages.length > 0 ? { prefixMessages } : {}),
-        ...(options.tokenUsage
-            ? { onUsage: createTokenUsageObserver(options.tokenUsage, "planner", agent.options.provider, agent.options.model) }
-            : {}),
-    });
-    return parseProposal(text);
-}
-//# sourceMappingURL=planner.js.map

package/lib/pool.d.ts

@@ -1,7 +0,0 @@
-/**
- * Bounded-concurrency map: run async workers over items with at most
- * `concurrency` in flight. Used by the evaluation matrix so case × run units
- * execute in parallel without unbounded subagent fan-out.
- */
-export declare function mapPool<T, R>(items: readonly T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
-//# sourceMappingURL=pool.d.ts.map

package/lib/pool.js

@@ -1,25 +0,0 @@
-/**
- * Bounded-concurrency map: run async workers over items with at most
- * `concurrency` in flight. Used by the evaluation matrix so case × run units
- * execute in parallel without unbounded subagent fan-out.
- */
-export async function mapPool(items, concurrency, worker) {
-    if (items.length === 0) {
-        return [];
-    }
-    const results = new Array(items.length);
-    const limit = Math.max(1, Math.min(concurrency, items.length));
-    let next = 0;
-    async function runner() {
-        while (true) {
-            const index = next;
-            next += 1;
-            if (index >= items.length)
-                return;
-            results[index] = await worker(items[index], index);
-        }
-    }
-    await Promise.all(Array.from({ length: limit }, () => runner()));
-    return results;
-}
-//# sourceMappingURL=pool.js.map

package/lib/prefix-cache.d.ts

@@ -1,78 +0,0 @@
-/**
- * Prefix-cache-aware planning input routing (Route A/B).
- *
- * The planner and the review gate re-send session context on every call as
- * flat text. On providers with prompt caching that context is re-billed at
- * full price each time. Route A instead prepends session-derived messages —
- * the same evidence in structured form, eligible for cache-read pricing —
- * and drops the redundant flat trajectory block. Route B keeps the legacy
- * flat-text input byte-for-byte.
- *
- * Adapted from dsh-continual-harness (Route A/B + cache-detect): this port
- * deliberately does NOT reproduce the host loop's byte-identical cache key
- * (no deriveMessages/tools/sessionId plumbing on this seam), so a hit needs
- * a provider that keys on the message-prefix content. Sources are stamped
- * honestly and every reduction is documented below.
- */
-import { type AssistantMessage, type UserMessage } from "@deepseek-ai/dsh-llm";
-/** Planning input shape: A = session-derived message prefix, B = flat-text trajectory. */
-export type PlannerRoute = "A" | "B";
-/** Routing mode: auto-detect from cache evidence, always prefix, or never. */
-export type PlannerPrefixCacheMode = "auto" | "session" | "off";
-/** Per-call routing overrides; absent fields fall back to the resolved defaults. */
-export interface PrefixCacheOptions {
-    mode?: PlannerPrefixCacheMode;
-    maxChars?: number;
-}
-/** Default session-prefix budget for one Route A input, in characters. */
-export declare const DEFAULT_PREFIX_MAX_CHARS = 12000;
-/**
- * Resolve per-call overrides against the defaults.
- *
- * @param opts - sparse per-call overrides.
- * @returns the effective mode (default "auto") and char budget.
- * @throws When maxChars is present but not a positive safe integer (fail loud on misconfiguration).
- */
-export declare function resolvePrefixCache(opts?: PrefixCacheOptions): {
-    mode: PlannerPrefixCacheMode;
-    maxChars: number;
-};
-/**
- * True when any assistant message in this session reported cache-read
- * tokens — evidence the provider can serve a warm prefix.
- *
- * @param events - session log rows, newest last.
- * @returns whether cache evidence exists (false on an empty/unreadable log).
- */
-export declare function hasCacheEvidence(events: readonly unknown[]): boolean;
-/**
- * Pick the planning input route for one call.
- *
- * @param events - session log rows, newest last.
- * @param mode - routing mode (default "auto").
- * @returns "A" when the session prefix should carry the context, else "B".
- */
-export declare function detectPlannerRoute(events: readonly unknown[], mode?: PlannerPrefixCacheMode): PlannerRoute;
-/**
- * Rebuild a tail-biased session prefix from the event log.
- *
- * Inclusion mirrors the trajectory grounding (only direct human `user`
- * speech plus the model's own assistant text), so injected plugin context
- * and tool results never echo back into the planning input. Whole messages
- * are dropped oldest-first over budget; a single over-budget message keeps
- * its tail.
- *
- * @param events - session log rows, newest last.
- * @param opts - provider/model stamps the assistant messages (the calling
- * agent's own route); maxChars caps the prefix (default {@link DEFAULT_PREFIX_MAX_CHARS}).
- * @returns the prefix messages, oldest first ([] when nothing qualifies —
- * callers fall back to Route B).
- * @throws When assistant text exists but provider/model is missing (an
- * assistant message cannot be honestly stamped without its route).
- */
-export declare function buildPrefixMessages(events: readonly unknown[], opts: {
-    provider?: string;
-    model?: string;
-    maxChars?: number;
-}): (UserMessage | AssistantMessage)[];
-//# sourceMappingURL=prefix-cache.d.ts.map

package/lib/prefix-cache.js

@@ -1,168 +0,0 @@
-/**
- * Prefix-cache-aware planning input routing (Route A/B).
- *
- * The planner and the review gate re-send session context on every call as
- * flat text. On providers with prompt caching that context is re-billed at
- * full price each time. Route A instead prepends session-derived messages —
- * the same evidence in structured form, eligible for cache-read pricing —
- * and drops the redundant flat trajectory block. Route B keeps the legacy
- * flat-text input byte-for-byte.
- *
- * Adapted from dsh-continual-harness (Route A/B + cache-detect): this port
- * deliberately does NOT reproduce the host loop's byte-identical cache key
- * (no deriveMessages/tools/sessionId plumbing on this seam), so a hit needs
- * a provider that keys on the message-prefix content. Sources are stamped
- * honestly and every reduction is documented below.
- */
-import { createAssistantMessage, createUserMessage } from "@deepseek-ai/dsh-llm";
-/** Default session-prefix budget for one Route A input, in characters. */
-export const DEFAULT_PREFIX_MAX_CHARS = 12000;
-/**
- * Resolve per-call overrides against the defaults.
- *
- * @param opts - sparse per-call overrides.
- * @returns the effective mode (default "auto") and char budget.
- * @throws When maxChars is present but not a positive safe integer (fail loud on misconfiguration).
- */
-export function resolvePrefixCache(opts) {
-    const mode = opts?.mode ?? "auto";
-    const maxChars = opts?.maxChars ?? DEFAULT_PREFIX_MAX_CHARS;
-    if (!Number.isSafeInteger(maxChars) || maxChars < 1) {
-        throw new Error(`evolve: prefix-cache maxChars must be a positive integer, got ${String(opts?.maxChars)}`);
-    }
-    return { mode, maxChars };
-}
-/**
- * True when any assistant message in this session reported cache-read
- * tokens — evidence the provider can serve a warm prefix.
- *
- * @param events - session log rows, newest last.
- * @returns whether cache evidence exists (false on an empty/unreadable log).
- */
-export function hasCacheEvidence(events) {
-    for (const raw of events) {
-        if (typeof raw !== "object" || raw === null)
-            continue;
-        const event = raw;
-        if (event.type !== "assistant/message")
-            continue;
-        const read = event.data?.usage?.cacheReadTokens;
-        if (typeof read === "number" && read > 0)
-            return true;
-    }
-    return false;
-}
-/**
- * Pick the planning input route for one call.
- *
- * @param events - session log rows, newest last.
- * @param mode - routing mode (default "auto").
- * @returns "A" when the session prefix should carry the context, else "B".
- */
-export function detectPlannerRoute(events, mode) {
-    const resolved = mode ?? "auto";
-    if (resolved === "session")
-        return "A";
-    if (resolved === "off")
-        return "B";
-    return hasCacheEvidence(events) ? "A" : "B";
-}
-/**
- * Extract one message's text without depending on the dsh-llm ContentBlock
- * type: string blocks pass through, object blocks contribute their `text`
- * field when present. Non-text blocks (tool calls, images) are dropped.
- */
-function blockText(content) {
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    const parts = [];
-    for (const block of content) {
-        if (typeof block === "string") {
-            parts.push(block);
-        }
-        else if (block !== null && typeof block === "object" && "text" in block && typeof block.text === "string") {
-            parts.push(block.text);
-        }
-    }
-    return parts.filter((text) => text.length > 0).join(" ");
-}
-/**
- * Rebuild a tail-biased session prefix from the event log.
- *
- * Inclusion mirrors the trajectory grounding (only direct human `user`
- * speech plus the model's own assistant text), so injected plugin context
- * and tool results never echo back into the planning input. Whole messages
- * are dropped oldest-first over budget; a single over-budget message keeps
- * its tail.
- *
- * @param events - session log rows, newest last.
- * @param opts - provider/model stamps the assistant messages (the calling
- * agent's own route); maxChars caps the prefix (default {@link DEFAULT_PREFIX_MAX_CHARS}).
- * @returns the prefix messages, oldest first ([] when nothing qualifies —
- * callers fall back to Route B).
- * @throws When assistant text exists but provider/model is missing (an
- * assistant message cannot be honestly stamped without its route).
- */
-export function buildPrefixMessages(events, opts) {
-    const maxChars = opts.maxChars ?? DEFAULT_PREFIX_MAX_CHARS;
-    if (!Number.isSafeInteger(maxChars) || maxChars < 1) {
-        throw new Error(`evolve: prefix-cache maxChars must be a positive integer, got ${String(opts.maxChars)}`);
-    }
-    const pairs = [];
-    for (let i = events.length - 1; i >= 0; i -= 1) {
-        const raw = events[i];
-        if (typeof raw !== "object" || raw === null)
-            continue;
-        const event = raw;
-        const isUser = event.type === "user/message";
-        const isAssistant = event.type === "assistant/message";
-        if (!isUser && !isAssistant)
-            continue;
-        if (isUser) {
-            const kind = event.data?.source?.kind;
-            if (kind !== undefined && kind !== "user")
-                continue;
-        }
-        const text = blockText(event.data?.content).trim();
-        if (text.length === 0)
-            continue;
-        pairs.push({ role: isUser ? "user" : "assistant", text });
-    }
-    if (pairs.length === 0)
-        return [];
-    // Collected newest-first; restore conversation order before budgeting.
-    pairs.reverse();
-    // Tail-biased budget: drop oldest whole messages over budget; a lone
-    // over-budget message keeps its tail.
-    let total = pairs.reduce((sum, pair) => sum + pair.text.length, 0);
-    while (pairs.length > 1 && total > maxChars) {
-        const dropped = pairs.shift();
-        total -= dropped?.text.length ?? 0;
-    }
-    const oldest = pairs[0];
-    if (oldest !== undefined && total > maxChars) {
-        oldest.text = oldest.text.slice(-maxChars);
-    }
-    const messages = [];
-    for (const pair of pairs) {
-        if (pair.role === "user") {
-            messages.push(createUserMessage({
-                source: { kind: "user" },
-                content: [{ type: "text", text: pair.text }],
-            }));
-        }
-        else {
-            if (!opts.provider || !opts.model) {
-                throw new Error("evolve: prefix-cache needs the agent provider/model to stamp assistant messages");
-            }
-            messages.push(createAssistantMessage({
-                source: { provider: opts.provider, model: opts.model },
-                content: [{ type: "text", text: pair.text }],
-            }));
-        }
-    }
-    return messages;
-}
-//# sourceMappingURL=prefix-cache.js.map

package/lib/project.d.ts

@@ -1,28 +0,0 @@
-/**
- * Stable project key for a workspace. `workspaceIdentity` (when set)
- * replaces the path as the hash source so renamed checkouts of the same
- * logical project keep one store.
- */
-export declare function resolveProjectKey(workspacePath: string, workspaceIdentity?: string): string;
-/** Defense for externally supplied keys (explicit opts): single safe segment. */
-export declare function sanitizeProjectKey(key: string): string;
-/** Minimal agent shape the project-key derivation needs (duck-typed). */
-export interface ProjectKeyAgentLike {
-    session?: {
-        header?: {
-            cwd?: unknown;
-            meta?: {
-                cwd?: unknown;
-            };
-        };
-    };
-}
-/**
- * Derive the project key from an assembling agent's session cwd. Returns
- * undefined when no validated absolute cwd is present — the caller then
- * skips the project layer rather than failing the whole assembly.
- */
-export declare function projectKeyOf(agent: unknown, opts?: {
-    workspaceIdentity?: string;
-}): string | undefined;
-//# sourceMappingURL=project.d.ts.map

package/lib/project.js

@@ -1,66 +0,0 @@
-/**
- * Project scope identity: the third harness layer between session-local
- * staging and the cross-project global store.
- *
- * A project is identified by the session's validated absolute `cwd`
- * (stable slug + sha256, mirroring ZCode's `project-root.ts`), so every
- * session opened in the same workspace shares one project store while
- * different checkouts never collide. All helpers are pure and never throw —
- * a missing cwd simply means "no project layer" (the caller degrades to
- * global+local, the same shape as an empty project store).
- */
-import { createHash } from "node:crypto";
-import { basename, isAbsolute, resolve } from "node:path";
-/**
- * Stable project key for a workspace. `workspaceIdentity` (when set)
- * replaces the path as the hash source so renamed checkouts of the same
- * logical project keep one store.
- */
-export function resolveProjectKey(workspacePath, workspaceIdentity) {
-    const identity = workspaceIdentity?.trim();
-    const normalized = resolve(workspacePath);
-    const keySource = identity && identity.length > 0 ? identity : process.platform === "win32" ? normalized.toLowerCase() : normalized;
-    const hash = createHash("sha256").update(keySource).digest("hex").slice(0, 16);
-    const slug = identity && identity.length > 0 ? "project" : sanitizeSlug(basename(normalized) || "project");
-    return `${slug}-${hash}`;
-}
-function sanitizeSlug(value) {
-    const slug = value
-        .toLowerCase()
-        .replace(/[^a-z0-9._-]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 48);
-    return slug.length > 0 ? slug : "project";
-}
-/** Defense for externally supplied keys (explicit opts): single safe segment. */
-export function sanitizeProjectKey(key) {
-    const cleaned = key
-        .trim()
-        .replace(/[^a-zA-Z0-9._-]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 64);
-    return cleaned.length > 0 ? cleaned : "project";
-}
-/**
- * Derive the project key from an assembling agent's session cwd. Returns
- * undefined when no validated absolute cwd is present — the caller then
- * skips the project layer rather than failing the whole assembly.
- */
-export function projectKeyOf(agent, opts) {
-    try {
-        const header = agent?.session?.header;
-        const raw = header?.cwd ?? header?.meta?.cwd;
-        if (typeof raw !== "string" || raw.trim().length === 0) {
-            return undefined;
-        }
-        const cwd = raw.trim();
-        if (!isAbsolute(cwd)) {
-            return undefined;
-        }
-        return resolveProjectKey(cwd, opts?.workspaceIdentity);
-    }
-    catch {
-        return undefined;
-    }
-}
-//# sourceMappingURL=project.js.map

package/lib/projection.d.ts

@@ -1,22 +0,0 @@
-import type { HarnessState } from "./types.js";
-/** Index file name at the store root. */
-export declare const MEMORY_INDEX_FILE = "MEMORY.md";
-/** Per-fact file directory inside the store. */
-export declare const MEMORY_FACTS_DIR = "memory";
-/** Map a memory id to a flat filename (`:` is legal on disk but hostile to tools). */
-export declare function memoryFactFilename(id: string): string;
-/**
- * Rewrite the whole projection from the post-apply state: index, one file
- * per memory entry (including archived ones, flagged), and deletion of
- * files whose ids no longer exist. Deterministic — the same state always
- * produces the same files.
- *
- * @param stateDir The store directory holding harness_state.json.
- * @param state The freshly persisted state (post-apply, post-rollback).
- */
-export declare function materializeMemoryProjection(stateDir: string, state: HarnessState): void;
-/** Read back one projected fact file (round-trip helper for tests and tools). */
-export declare function readMemoryFact(factsDir: string, filename: string): string;
-/** True when the store directory carries a projection from a previous apply. */
-export declare function hasMemoryProjection(stateDir: string): boolean;
-//# sourceMappingURL=projection.d.ts.map

package/lib/projection.js

@@ -1,112 +0,0 @@
-/**
- * Readable Markdown projection (P1): a ZCode-style `MEMORY.md` index plus
- * one file per memory fact, materialized from the JSON store.
- *
- * The JSON harness state stays the single source of truth (versions,
- * rollback, audit). The projection is a derived, human-trustable view:
- * it is rewritten from the post-apply state inside the engine, so the
- * model can never write it directly and rollback/archive stay in sync.
- *
- * Layout per store directory:
- *
- *   <stateDir>/MEMORY.md          one line per memory entry
- *   <stateDir>/memory/<file>.md   one fact per file with frontmatter
- */
-import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { isArchived, isMemoryType, MEMORY_TYPE_KEY } from "./types.js";
-/** Index file name at the store root. */
-export const MEMORY_INDEX_FILE = "MEMORY.md";
-/** Per-fact file directory inside the store. */
-export const MEMORY_FACTS_DIR = "memory";
-/** Map a memory id to a flat filename (`:` is legal on disk but hostile to tools). */
-export function memoryFactFilename(id) {
-    return `${id.replace(/:/g, "_")}.md`;
-}
-/**
- * Rewrite the whole projection from the post-apply state: index, one file
- * per memory entry (including archived ones, flagged), and deletion of
- * files whose ids no longer exist. Deterministic — the same state always
- * produces the same files.
- *
- * @param stateDir The store directory holding harness_state.json.
- * @param state The freshly persisted state (post-apply, post-rollback).
- */
-export function materializeMemoryProjection(stateDir, state) {
-    const entries = Object.values(state.entries.memory).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
-    const factsDir = join(stateDir, MEMORY_FACTS_DIR);
-    mkdirSync(factsDir, { recursive: true });
-    const expected = new Map();
-    for (const entry of entries) {
-        let filename = memoryFactFilename(entry.id);
-        let suffix = 1;
-        while (expected.has(filename)) {
-            suffix += 1;
-            filename = `${memoryFactFilename(entry.id).replace(/\.md$/, "")}~${suffix}.md`;
-        }
-        expected.set(filename, entry);
-    }
-    for (const [filename, entry] of expected) {
-        writeFileSync(join(factsDir, filename), renderMemoryFact(entry), { encoding: "utf8", mode: 0o600 });
-    }
-    // Sweep facts whose entries vanished (delete); archived entries keep
-    // their file with archived:true frontmatter.
-    let existing;
-    try {
-        existing = readdirSync(factsDir).filter((file) => file.endsWith(".md"));
-    }
-    catch {
-        existing = [];
-    }
-    for (const file of existing) {
-        if (!expected.has(file)) {
-            try {
-                unlinkSync(join(factsDir, file));
-            }
-            catch {
-                // A stale fact file must not break the apply path; the next
-                // materialization retries the sweep.
-            }
-        }
-    }
-    writeFileSync(join(stateDir, MEMORY_INDEX_FILE), renderMemoryIndex([...expected]), { encoding: "utf8", mode: 0o600 });
-}
-/** Read back one projected fact file (round-trip helper for tests and tools). */
-export function readMemoryFact(factsDir, filename) {
-    return readFileSync(join(factsDir, filename), "utf8");
-}
-/** True when the store directory carries a projection from a previous apply. */
-export function hasMemoryProjection(stateDir) {
-    return existsSync(join(stateDir, MEMORY_INDEX_FILE)) && existsSync(join(stateDir, MEMORY_FACTS_DIR));
-}
-function renderMemoryFact(entry) {
-    const type = isMemoryType(entry.metadata[MEMORY_TYPE_KEY]) ? String(entry.metadata[MEMORY_TYPE_KEY]) : "untyped";
-    const frontmatter = [
-        "---",
-        `id: ${entry.id}`,
-        `scope: ${entry.scope}`,
-        `kind: memory`,
-        `memoryType: ${type}`,
-        `version: ${entry.version}`,
-        `path: ${entry.path}`,
-        `archived: ${isArchived(entry)}`,
-        `created_at: ${entry.created_at}`,
-        `updated_at: ${entry.updated_at}`,
-        "---",
-    ].join("\n");
-    return `${frontmatter}\n\n# ${entry.title}\n\n${entry.content}\n`;
-}
-function renderMemoryIndex(files) {
-    const lines = ["# Memory Index", "", "Derived from the JSON harness state — do not edit by hand; it is rewritten on every memory apply.", ""];
-    if (files.length === 0) {
-        lines.push("(no memory entries yet)");
-        return `${lines.join("\n")}\n`;
-    }
-    for (const [file, entry] of files) {
-        const type = isMemoryType(entry.metadata[MEMORY_TYPE_KEY]) ? String(entry.metadata[MEMORY_TYPE_KEY]) : "untyped";
-        const archived = isArchived(entry) ? ", archived" : "";
-        lines.push(`- [${entry.scope}:${entry.id}] ${entry.title} (type=${type}, v${entry.version}${archived}) → ${MEMORY_FACTS_DIR}/${file}`);
-    }
-    return `${lines.join("\n")}\n`;
-}
-//# sourceMappingURL=projection.js.map