@prodero/curator 0.0.0-stage → 0.2.0

package/dist/core/sync-transaction.js

@@ -0,0 +1,290 @@
+import { PRIVATE_DIRECTORY_MODE } from "../filesystem/permissions.js";
+import { writeFileExclusive } from "./storage.js";
+import { protectKnowledgeWrites } from './knowledge-write-policy.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { assertNoSecrets } from "./secrets.js";
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { parseKnowledge } from './memory.js';
+import { parseSkill } from './skills.js';
+import { readConfig, checkedDataPath, exists, parseCheckpointData, ensureRuntimeDirectories, ensureDataDirectory, ensureSelfIgnoredPrivateDirectory, sha256, writeFileAtomic } from './storage.js';
+const writeSchema = z.object({ path: z.string().regex(/^(memory|local\/memory|local\/skills|skills|(local\/)?archive\/\d{4}_(0[1-9]|1[0-2]))\/[a-zA-Z0-9_-]+\.md$|^checkpoints\/chk_[a-zA-Z0-9_-]+\.json$/), before: z.string().nullable(), after: z.string() }).strict();
+const moveSchema = z.object({ from: z.string().regex(/^(local\/)?memory\/[a-zA-Z0-9_-]+\.md$/), to: z.string().regex(/^(local\/)?archive\/\d{4}_(0[1-9]|1[0-2])\/[a-zA-Z0-9_-]+\.md$/), before: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+const journalSchema = z.discriminatedUnion('version', [
+    z.object({ version: z.literal(1), writes: z.array(writeSchema).min(1) }).strict(),
+    z.object({ version: z.literal(2), writes: z.array(writeSchema).min(1), moves: z.array(moveSchema) }).strict(),
+]);
+export async function safeProjectPath(root, relative) {
+    if (!/^(memory|local\/memory|local\/skills|skills|sessions|checkpoints|(local\/)?archive\/\d{4}_(0[1-9]|1[0-2]))\/[a-zA-Z0-9_-]+\.(md|json)$/.test(relative))
+        throw new Error('Unsafe canonical path');
+    return checkedDataPath(root, relative);
+}
+async function runtimeDirectory(root) {
+    await ensureRuntimeDirectories(root);
+    for (const directory of ['memory', 'skills'])
+        await checkedDataPath(root, directory);
+    const dir = await ensureDataDirectory(root, '.transactions');
+    await writeFileExclusive(await checkedDataPath(root, '.transactions/.gitignore'), '*\n').catch((error) => { if (error.code !== 'EEXIST')
+        throw error; });
+    return dir;
+}
+export async function fileHash(target) {
+    try {
+        return sha256(await fs.readFile(target, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+// An unforgeable async-context capability for Core composition, never a caller boolean.
+const writerContext = new AsyncLocalStorage();
+export function ownsSyncLock(root) {
+    const owner = writerContext.getStore();
+    return Boolean(owner?.active && owner.root === path.resolve(root));
+}
+function sameLock(a, b) { return a.dev === b.dev && a.ino === b.ino; }
+// Recovery may inspect a PID only while every cooperating acquisition/release is
+// excluded. Otherwise a dead PID can describe the previous directory generation.
+// An interrupted transition guard remains fail-closed, as documented in RECOVERY.
+async function tryLockTransition(root, transition) {
+    const guard = await checkedDataPath(root, '.transactions/lock-recovery');
+    try {
+        await fs.mkdir(guard, { mode: PRIVATE_DIRECTORY_MODE });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return null;
+        throw error;
+    }
+    const identity = await fs.lstat(guard);
+    try {
+        return { value: await transition() };
+    }
+    finally {
+        const current = await fs.lstat(await checkedDataPath(root, '.transactions/lock-recovery'));
+        if (!sameLock(identity, current))
+            throw new Error('Sync lock recovery guard changed; preserve transaction state for inspection');
+        await fs.rm(guard, { recursive: true, force: true });
+    }
+}
+async function removeOwnedLock(root, identity, owner) {
+    const lock = await checkedDataPath(root, '.transactions/lock');
+    const current = await fs.lstat(lock);
+    if (!sameLock(identity, current) || (owner !== undefined && await fs.readFile(await checkedDataPath(root, '.transactions/lock/owner'), 'utf8') !== owner)) {
+        throw new Error('Sync storage writer lock ownership changed; preserve transaction state for inspection');
+    }
+    await fs.rm(lock, { recursive: true, force: true });
+}
+const writerBusy = () => new Error('Another Sync or storage writer is already running, or its lock has no live owner; inspect .prodero/.transactions/lock and .prodero/.transactions/lock-recovery before retrying');
+/** Per-worktree writer exclusion shared by migration, Sync and session mutations. */
+export async function withSyncLock(root, operation, options = {}) {
+    if (options.maintainIntegration === false)
+        await ensureSelfIgnoredPrivateDirectory(root, '.transactions');
+    else
+        await runtimeDirectory(root);
+    const lock = await checkedDataPath(root, '.transactions/lock');
+    const deadline = Date.now() + (options.waitMs ?? 0);
+    let identity;
+    while (true) {
+        const attempt = await tryLockTransition(root, async () => {
+            let created = false;
+            try {
+                await fs.mkdir(lock, { mode: PRIVATE_DIRECTORY_MODE });
+                created = true;
+                const acquired = await fs.lstat(lock);
+                try {
+                    await writeFileExclusive(await checkedDataPath(root, '.transactions/lock/owner'), String(process.pid));
+                }
+                catch (error) {
+                    await removeOwnedLock(root, acquired);
+                    throw error;
+                }
+                return { identity: acquired, recovered: false };
+            }
+            catch (error) {
+                if (created || error.code !== 'EEXIST')
+                    throw error;
+                const stale = await fs.lstat(await checkedDataPath(root, '.transactions/lock')).catch(error => { if (error.code === 'ENOENT')
+                    return null; throw error; });
+                if (!stale)
+                    return { identity: null, recovered: true };
+                const owner = await fs.readFile(await checkedDataPath(root, '.transactions/lock/owner'), 'utf8').catch(error => { if (error.code === 'ENOENT')
+                    return ''; throw error; });
+                const pid = /^\d+$/.test(owner) ? Number(owner) : 0;
+                if (pid > 0 && Number.isSafeInteger(pid)) {
+                    try {
+                        process.kill(pid, 0);
+                    }
+                    catch (probe) {
+                        if (probe.code !== 'ESRCH')
+                            throw probe;
+                        await removeOwnedLock(root, stale, owner);
+                        return { identity: null, recovered: true };
+                    }
+                }
+                return { identity: null, recovered: false };
+            }
+        });
+        if (attempt?.value.identity) {
+            identity = attempt.value.identity;
+            break;
+        }
+        if (attempt?.value.recovered)
+            continue;
+        if (Date.now() >= deadline)
+            throw writerBusy();
+        await new Promise(resolve => setTimeout(resolve, 10));
+    }
+    try {
+        if (!options.migrationRecovery && await exists(await checkedDataPath(root, '.transactions/migration.json')))
+            throw new Error('Interrupted migration requires recovery; run Prodero init or prepare before recording new data. Preserve .prodero/.backups and .prodero/.transactions.');
+        const pending = await fs.readFile(await checkedDataPath(root, '.transactions/pending.json'), 'utf8').catch(error => { if (error.code === 'ENOENT')
+            return null; throw error; });
+        let pendingVersion;
+        try {
+            pendingVersion = pending ? JSON.parse(pending).version : undefined;
+        }
+        catch {
+            throw new Error("PRODERO_INVALID_JOURNAL: invalid pending journal JSON; preserve it for recovery.");
+        }
+        if (pendingVersion === 2) {
+            if (options.recoverLifecycle === false)
+                throw new Error('Lifecycle transaction pending; explicit recovery required before preview');
+            await recoverSyncTransaction(root);
+        }
+        const owner = { root: path.resolve(root), active: true };
+        try {
+            return await writerContext.run(owner, operation);
+        }
+        finally {
+            owner.active = false;
+        }
+    }
+    finally {
+        const releaseDeadline = Date.now() + 5_000;
+        while (!await tryLockTransition(root, () => removeOwnedLock(root, identity, String(process.pid)))) {
+            if (Date.now() >= releaseDeadline)
+                throw writerBusy();
+            await new Promise(resolve => setTimeout(resolve, 10));
+        }
+    }
+}
+async function validateWriteContent(root, writes) {
+    assertNoSecrets(writes.map(write => write.after));
+    const schema = (await readConfig(root))?.knowledgeSchemaVersion;
+    for (const write of writes) {
+        const filename = path.basename(write.path);
+        if (write.path.startsWith('checkpoints/'))
+            parseCheckpointData(write.after, filename);
+        else if ((write.path.startsWith('skills/') || write.path.startsWith('local/skills/')))
+            parseSkill(write.after, filename);
+        else
+            parseKnowledge(write.after, filename, schema);
+    }
+}
+function validateMoves(writes, moves) {
+    const sources = new Set();
+    for (const move of moves) {
+        if (sources.has(move.from) || writes.some(w => w.path === move.from))
+            throw new Error('Invalid lifecycle move source');
+        sources.add(move.from);
+        const destination = writes.find(w => w.path === move.to);
+        if (!destination || destination.before !== null || path.basename(move.from) !== path.basename(move.to) || move.from.startsWith('local/') !== move.to.startsWith('local/'))
+            throw new Error('Invalid lifecycle archive move');
+        const archived = parseKnowledge(destination.after, path.basename(move.to));
+        if (['active', 'disputed'].includes(archived.status))
+            throw new Error('Only historical knowledge can be archived');
+        if (!archived.archivedAt || !move.to.includes(`archive/${new Date(archived.archivedAt).toISOString().slice(0, 7).replace('-', '_')}/`))
+            throw new Error('Archive move requires matching archived_at');
+    }
+}
+async function applyWrites(root, writes, moves = []) {
+    // Validate the entire journal and every before-image before the first write.
+    const targets = await Promise.all(writes.map((write) => safeProjectPath(root, write.path)));
+    await validateWriteContent(root, writes);
+    validateMoves(writes, moves);
+    for (const move of moves) {
+        const actual = await fileHash(await safeProjectPath(root, move.from));
+        const destination = writes.find(w => w.path === move.to);
+        if (actual !== move.before && (actual !== null || await fileHash(await safeProjectPath(root, move.to)) !== sha256(destination.after)))
+            throw new Error('Lifecycle recovery found a changed or missing source; journal preserved');
+    }
+    for (let i = 0; i < writes.length; i++) {
+        const actual = await fileHash(targets[i]);
+        if (actual !== writes[i].before && actual !== sha256(writes[i].after))
+            throw new Error(`Sync recovery found concurrently changed ${writes[i].path}; preserved journal for review`);
+    }
+    for (let i = 0; i < writes.length; i++) {
+        if (i === writes.length - 1)
+            for (const move of moves)
+                await fs.rm(await safeProjectPath(root, move.from), { force: true });
+        if (await fileHash(targets[i]) !== sha256(writes[i].after)) {
+            if (/^(local\/)?archive\//.test(writes[i].path))
+                await ensureDataDirectory(root, path.dirname(writes[i].path));
+            await writeFileAtomic(targets[i], writes[i].after);
+        }
+    }
+}
+export async function recoverSyncTransaction(root) {
+    await runtimeDirectory(root);
+    const target = await checkedDataPath(root, '.transactions/pending.json');
+    const content = await fs.readFile(target, 'utf8').catch((error) => { if (error.code === 'ENOENT')
+        return null; throw error; });
+    if (!content)
+        return false;
+    let journal;
+    try {
+        journal = journalSchema.parse(JSON.parse(content));
+    }
+    catch {
+        throw new Error("PRODERO_INVALID_JOURNAL: .prodero/.transactions/pending.json has invalid JSON or metadata. Preserve the journal and inspect or restore it before retrying Sync.");
+    }
+    validateWriteOrder(journal.writes);
+    await applyWrites(root, journal.writes, journal.version === 2 ? journal.moves : []);
+    await fs.rm(target);
+    return true;
+}
+function validateWriteOrder(writes) {
+    if (new Set(writes.map((w) => w.path)).size !== writes.length || !writes.at(-1)?.path.startsWith('checkpoints/') || writes.slice(0, -1).some((w) => w.path.startsWith('checkpoints/')))
+        throw new Error('Invalid Sync transaction order');
+    if (writes.at(-1).before !== null)
+        throw new Error('Checkpoint must be immutable');
+}
+/** Durable journal is NOT a disposable cache. Checkpoint is committed last. */
+export async function commitSyncTransaction(root, writes, lifecycle) {
+    assertNoSecrets(writes.map(w => w.after));
+    // Validate paths and preimages before interpreting any untrusted content.
+    journalSchema.parse(lifecycle?.moves ? { version: 2, writes, moves: lifecycle.moves } : { version: 1, writes });
+    validateWriteOrder(writes);
+    for (const write of writes) {
+        if (await fileHash(await safeProjectPath(root, write.path)) !== write.before)
+            throw new Error(`Knowledge changed while reasoning: ${write.path}; retry Sync`);
+    }
+    const guarded = await protectKnowledgeWrites(root, writes, lifecycle?.policyMode === 'exact', lifecycle?.moves);
+    writes = guarded.writes;
+    const journal = journalSchema.parse(lifecycle?.moves ? { version: 2, writes, moves: lifecycle.moves } : { version: 1, writes });
+    if (lifecycle?.moves)
+        validateMoves(writes, lifecycle.moves);
+    validateWriteOrder(journal.writes);
+    for (const write of writes) {
+        const target = await safeProjectPath(root, write.path);
+        if (await fileHash(target) !== write.before)
+            throw new Error(`Knowledge changed while reasoning: ${write.path}; retry Sync`);
+    }
+    for (const move of lifecycle?.moves ?? [])
+        if (await fileHash(await safeProjectPath(root, move.from)) !== move.before)
+            throw new Error('Knowledge source changed before archive; retry lifecycle preview');
+    await runtimeDirectory(root);
+    const target = await checkedDataPath(root, '.transactions/pending.json');
+    if (await fileHash(target))
+        throw new Error('Unrecovered Sync journal');
+    await validateWriteContent(root, writes);
+    await writeFileAtomic(target, JSON.stringify(journal));
+    await applyWrites(root, journal.writes, journal.version === 2 ? journal.moves : []);
+    await fs.rm(target);
+    return guarded.policy;
+}
+//# sourceMappingURL=sync-transaction.js.map

package/dist/core/telemetry.js

@@ -0,0 +1,64 @@
+import { parseObservationAnnotations } from "./format.js";
+export const TOKEN_COUNT_METHOD = "estimated-utf8-bytes-div-4-v1";
+export const DEFAULT_CONTEXT_BUDGET_TOKENS = 6_000;
+export const DEFAULT_REQUIRED_CONTEXT_BUDGET_TOKENS = 2_000;
+export const MAX_CANONICAL_ITEM_TOKENS = 2_000;
+export const STALE_STATE_AFTER_DAYS = 180;
+/**
+ * Deterministic local approximation: ceil(UTF-8 byte length / 4).
+ * It is deliberately model-neutral and must never be presented as provider billing usage.
+ */
+export function estimateTokens(value) {
+    return value ? Math.ceil(Buffer.byteLength(value, "utf8") / 4) : 0;
+}
+export function knowledgeText(item) {
+    return `${item.title}\n${item.content}`;
+}
+export function safeRatio(numerator, denominator) {
+    if (!Number.isFinite(numerator) || !Number.isFinite(denominator) || denominator <= 0)
+        return 0;
+    return Math.max(0, numerator) / denominator;
+}
+export function contextPressure(requiredTokens, budgetTokens) {
+    const ratio = safeRatio(requiredTokens, budgetTokens);
+    return ratio >= 0.75 ? "high" : ratio >= 0.5 ? "moderate" : "normal";
+}
+export function memoryCompression(rawTokens, canonicalTokens) {
+    if (rawTokens <= 0)
+        return { kind: "unavailable", ratio: null };
+    if (canonicalTokens < rawTokens)
+        return { kind: "compression", ratio: 1 - canonicalTokens / rawTokens };
+    if (canonicalTokens > rawTokens)
+        return { kind: "expansion", ratio: canonicalTokens / rawTokens - 1 };
+    return { kind: "unchanged", ratio: 0 };
+}
+const SECTION_TYPES = {
+    Decisions: "decision",
+    Lessons: "lesson",
+    Discoveries: "discovery",
+    "Project State Changes": "state_change",
+    "Global Instruction Candidates": "global_instruction_candidate",
+    "Skill Candidates": "skill_candidate",
+};
+export function summarizeSessionMemory(session) {
+    const byType = {
+        decision: 0, lesson: 0, discovery: 0, state_change: 0, global_instruction_candidate: 0, skill_candidate: 0,
+    };
+    let observations = 0;
+    let rawSessionTokens = 0;
+    for (const [section, entries] of Object.entries(session.sections)) {
+        const type = SECTION_TYPES[section];
+        if (!type)
+            continue;
+        for (const raw of entries) {
+            const content = parseObservationAnnotations(raw).content;
+            if (!content)
+                continue;
+            observations += 1;
+            byType[type] += 1;
+            rawSessionTokens += estimateTokens(content);
+        }
+    }
+    return { observations, byType, rawSessionTokens };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/core/templates.js

@@ -0,0 +1,53 @@
+import { fileURLToPath } from "node:url";
+import { MANAGED_END, MANAGED_START, PRODERO_SCHEMA_VERSION } from "./constants.js";
+// The same relative location works from src/core (dev) and dist/core (installed).
+export const AGENT_INSTRUCTIONS_PATH = fileURLToPath(new URL("../../instructions/AGENTS.md", import.meta.url));
+export const AGENTS_BLOCK = `${MANAGED_START}
+Read and follow the instructions returned by prodero_instructions_read from the connected Prodero MCP server.
+${MANAGED_END}`;
+export const INDEX_TEMPLATE = `---
+prodero_schema: ${PRODERO_SCHEMA_VERSION}
+kind: project-index
+generated: true
+---
+
+# Prodero · Project Intelligence
+
+> Compact router for progressive context loading. Open only references relevant to the current task.
+
+## Required Global Context
+
+_No required global knowledge._
+
+## Contextual Knowledge
+
+_No contextual knowledge._
+
+## Local Knowledge
+
+- [Developer-local knowledge](local/index.md) — ignored by Git and retrieved together with Versioned Knowledge.
+
+## Project Skills
+
+_No project skills._
+
+## Loading Rules
+
+1. Use bounded context resolution; required global knowledge is priority-ranked and budgeted.
+2. Follow only bounded graph relationships selected by context resolution; never recursively load the graph or unrelated scopes.
+3. Load relevant project skills; do not recursively load \`.prodero/\`.
+4. Use session memory for agent-inferred observations; normal learning and conversational remember default to Local Knowledge.
+5. Use the promotion review workflow for Versioned Knowledge. Review repository changes before committing or pushing; Prodero does neither.
+`;
+export function replaceManagedBlock(existing) {
+    const start = existing.indexOf(MANAGED_START);
+    const end = existing.indexOf(MANAGED_END);
+    if (start >= 0 && end >= start) {
+        const before = existing.slice(0, start).trimEnd();
+        const after = existing.slice(end + MANAGED_END.length).trimStart();
+        return `${before}${before ? "\n\n" : ""}${AGENTS_BLOCK}${after ? `\n${after}` : "\n"}`;
+    }
+    const prefix = existing.trimEnd();
+    return `${prefix}${prefix ? "\n\n" : ""}${AGENTS_BLOCK}\n`;
+}
+//# sourceMappingURL=templates.js.map

package/dist/core/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map