@prodero/curator 0.0.0-stage → 0.2.0

package/dist/core/session-review.js

@@ -0,0 +1,150 @@
+import { reconcileCandidate, reconciliationSignal, actionClassification } from './reconciliation.js';
+import { INTELLIGENCE_LIMITS } from './intelligence.js';
+import fs from 'node:fs/promises';
+import { summarizeSessionMemory } from './telemetry.js';
+import { z } from 'zod';
+import { readSession, renderSession, serializeObservation, validateEntries, OBSERVATION_SECTIONS } from './sessions.js';
+import { exactKnowledge } from './semantic-safety.js';
+import { sessionCandidates, candidateReviewSignals } from './consolidation.js';
+import { discoverSessions } from './session-index.js';
+import { loadMemoryCatalog } from './memory-index.js';
+import { listProjectSkills } from './skills.js';
+import { readConfig, checkedDataPath, sha256, writeFileAtomic } from './storage.js';
+import { withSyncLock, recoverSyncTransaction } from './sync-transaction.js';
+export const sessionReviewMutationSchema = z.object({
+    sessionId: z.string().regex(/^sess_[a-zA-Z0-9_]+$/), revision: z.string().regex(/^[a-f0-9]{64}$/),
+    action: z.enum(['edit', 'discard', 'discard-all']), id: z.string().max(300).optional(),
+    content: z.string().trim().min(1).max(10000).optional(), title: z.string().trim().min(1).max(200).regex(/^[^\r\n]+$/).optional(),
+    type: z.enum(['decision', 'lesson', 'discovery', 'state_change', 'global_instruction_candidate', 'skill_candidate']).optional(),
+    scope: z.enum(['global', 'module', 'task']).optional(), scopeRef: z.string().max(300).nullable().optional(), scopeKind: z.enum(['path', 'topic']).nullable().optional(),
+}).strict();
+async function reviewLocked(root, sessionId, provider) {
+    provider = (await readConfig(root))?.knowledgeEngine?.mode === 'assisted' ? provider : undefined;
+    const session = await readSession(root, sessionId);
+    const file = await checkedDataPath(root, 'sessions', session.path);
+    const revision = sha256(await fs.readFile(file, 'utf8'));
+    const discovery = await discoverSessions(root);
+    const consolidated = discovery.processedSessionPaths.has(session.path);
+    const editable = session.status === 'closed' && !consolidated;
+    const catalog = await loadMemoryCatalog(root);
+    const skills = consolidated ? await listProjectSkills(root) : [];
+    const positions = Object.entries(session.sections).flatMap(([section, rows]) => rows.filter(row => row.trim()).map((_, index) => ({ section, index })));
+    const candidates = sessionCandidates(session);
+    // Child remember sessions keep their own checkpoints and observation evidence. The
+    // parent link is canonical session provenance, never a second learning store.
+    const sources = new Set([sessionId, ...discovery.sessions.filter(s => s.parentSessionId === sessionId).map(s => s.id)]);
+    const produced = await Promise.all(catalog.summaries.filter(m => m.sourceSessions.some(id => sources.has(id))).map(async (m) => ({ ...await catalog.load(m.id), layer: m.layer })));
+    const items = await Promise.all(candidates.map(async (candidate, index) => {
+        const position = positions[index];
+        const type = Object.entries(OBSERVATION_SECTIONS).find(([, section]) => section === position.section)[0];
+        const entry = { type, applicability: candidate.applicability, title: candidate.title, content: candidate.content, scopeHint: candidate.scope,
+            ...(candidate.scopeRef ? { scopeRef: candidate.scopeRef } : {}), ...(candidate.scopeKind ? { scopeKind: candidate.scopeKind } : {}),
+            importanceHint: candidate.priority, categoryHint: candidate.category, description: candidate.description, triggers: candidate.triggers,
+            proposedReason: candidate.proposedReason, supersedes: candidate.supersedes, relations: candidate.relations };
+        const related = await Promise.all(catalog.selectRelated({ ...candidate, explicitIds: candidate.supersedes }).map(item => catalog.load(item.id)));
+        let signals = candidateReviewSignals(candidate, related);
+        if (!consolidated && provider && index < INTELLIGENCE_LIMITS.candidatesPerBatch && related.length && !candidate.skill && !candidate.instructionCandidate) {
+            const evidence = { ...candidate, id: `candidate_review_${index}`, kind: 'knowledge', sources: [candidate.derivedFrom], evidence: [{ source: candidate.derivedFrom, quote: candidate.content }] };
+            try {
+                const action = await reconcileCandidate(evidence, related, provider);
+                signals = action.sources.filter(id => id !== evidence.id).map(id => reconciliationSignal(actionClassification(action), related.find(m => m.id === id)));
+            }
+            catch { /* Optional review retains neutral offline signals; Sync still validates its plan. */ }
+        }
+        try {
+            validateEntries([entry]);
+        }
+        catch (error) {
+            signals.push({ kind: 'validation', detail: error instanceof Error ? error.message : String(error), severity: 'info', requiresReview: true });
+        }
+        const outputs = consolidated ? [...produced.filter(m => m.derivedFrom.includes(candidate.derivedFrom)), ...related.filter(m => !produced.some(p => p.id === m.id) && exactKnowledge(m.content) === exactKnowledge(candidate.content)).map(m => ({ ...m, layer: catalog.summaries.find(s => s.id === m.id).layer }))] : [];
+        return { id: candidate.derivedFrom, type, title: candidate.title, content: candidate.content, applicability: candidate.applicability, scope: candidate.scope, scopeRef: candidate.scopeRef, scopeKind: candidate.scopeKind,
+            signals: consolidated ? outputs.filter(m => m.status === 'disputed').map(m => reconciliationSignal('potential_conflict', m)) : signals,
+            outputs, skills: skills.filter(s => s.derivedFrom.includes(candidate.derivedFrom)), entry, position };
+    }));
+    items.sort((a, b) => Number(b.signals.some(s => s.requiresReview)) - Number(a.signals.some(s => s.requiresReview)));
+    const represented = new Set(items.flatMap(i => i.outputs.map(o => o.id)));
+    const knowledge = await Promise.all(produced.filter(m => !represented.has(m.id)).map(async (m) => ({ ...m,
+        signals: [
+            ...(m.status === 'disputed' ? [reconciliationSignal('potential_conflict')] : []),
+            ...await Promise.all(m.supersedes.filter(id => catalog.summaries.some(s => s.id === id)).map(async (id) => {
+                const previous = await catalog.load(id);
+                return reconciliationSignal('state_transition', previous);
+            })),
+        ],
+    })));
+    knowledge.sort((a, b) => Number(b.signals.some(s => s.requiresReview)) - Number(a.signals.some(s => s.requiresReview)) || a.id.localeCompare(b.id));
+    const needsReview = [...items, ...knowledge].filter(i => i.signals.some(s => s.requiresReview)).length;
+    return { root, sessionId, revision, status: session.status, editable, consolidated, items, knowledge,
+        learned: { ...summarizeSessionMemory(session), syncState: consolidated ? "synchronized" : "pending-auto-sync", synchronization: null },
+        summary: { total: items.length + knowledge.length, localKnowledge: knowledge.filter(m => m.layer === 'local').length, versionedKnowledge: knowledge.filter(m => m.layer === 'versioned').length, needsReview, automatic: items.length + knowledge.length - needsReview } };
+}
+export async function reviewSessionKnowledge(root, sessionId, provider) {
+    return withSyncLock(root, async () => { await recoverSyncTransaction(root); return reviewLocked(root, sessionId, provider); }, { waitMs: 5000 });
+}
+export async function mutateSessionKnowledge(root, raw, provider) {
+    const input = sessionReviewMutationSchema.parse(raw);
+    return withSyncLock(root, async () => {
+        await recoverSyncTransaction(root);
+        const view = await reviewLocked(root, input.sessionId);
+        if (!view.editable)
+            throw new Error('This session has already synchronized or is still active. Use Knowledge to revise durable items; session history cannot be rewritten.');
+        if (view.revision !== input.revision)
+            throw new Error('Session knowledge changed. Reload before applying changes. Your draft has not been saved.');
+        const session = await readSession(root, input.sessionId);
+        if (input.action === 'discard-all')
+            for (const section of Object.keys(session.sections))
+                session.sections[section] = [];
+        else {
+            const item = view.items.find(i => i.id === input.id);
+            if (!item)
+                throw new Error('Session observation was not found. Reload the review.');
+            const section = item.position.section;
+            if (input.action === 'discard')
+                session.sections[section].splice(item.position.index, 1);
+            else {
+                if (input.content === undefined)
+                    throw new Error('Editing requires the complete observation content.');
+                const entry = { ...item.entry, content: input.content, title: input.title ?? item.title, type: input.type ?? item.type,
+                    scopeHint: input.scope ?? item.scope, scopeRef: input.scopeRef === undefined ? item.entry.scopeRef : input.scopeRef ?? undefined,
+                    scopeKind: input.scopeKind === undefined ? item.entry.scopeKind : input.scopeKind ?? undefined };
+                if (item.entry.applicability && item.entry.applicability.kind !== 'legacy' && [input.scope, input.scopeRef, input.scopeKind].some(v => v !== undefined) && (entry.scopeHint !== item.scope || entry.scopeRef !== item.entry.scopeRef || entry.scopeKind !== item.entry.scopeKind))
+                    throw new Error('Structured work boundaries are preserved when editing an observation.');
+                if (entry.scopeHint === 'global') {
+                    entry.scopeRef = undefined;
+                    entry.scopeKind = undefined;
+                }
+                if (entry.scopeHint === 'module' && !entry.scopeRef?.trim())
+                    throw new Error('Module scope requires a scope reference.');
+                if (entry.type !== item.type) {
+                    entry.categoryHint = { decision: 'decision', lesson: 'lesson', discovery: 'state', state_change: 'state', global_instruction_candidate: 'instruction', skill_candidate: 'instruction' }[entry.type];
+                    if (entry.type === 'global_instruction_candidate') {
+                        entry.applicability = undefined;
+                        entry.scopeHint = 'global';
+                        entry.scopeRef = undefined;
+                        entry.scopeKind = undefined;
+                    }
+                }
+                validateEntries([entry]);
+                const id = item.id.split('#')[1];
+                if (!/^obs_[a-zA-Z0-9_]+$/.test(id))
+                    throw new Error('Legacy observation identities are read-only. Record a corrected observation in a new session.');
+                const rendered = serializeObservation(id, entry);
+                if (OBSERVATION_SECTIONS[entry.type] === section)
+                    session.sections[section][item.position.index] = rendered;
+                else {
+                    session.sections[section].splice(item.position.index, 1);
+                    session.sections[OBSERVATION_SECTIONS[entry.type]].push(rendered);
+                }
+            }
+        }
+        session.updatedAt = new Date().toISOString();
+        const target = await checkedDataPath(root, 'sessions', session.path);
+        if (sha256(await fs.readFile(target, 'utf8')) !== view.revision)
+            throw new Error('Session changed during review. Reload before saving.');
+        await writeFileAtomic(target, renderSession(session, session.sections));
+        // Discovery verifies file stamps and content hashes, rebuilding derived state on change.
+        return reviewLocked(root, input.sessionId, provider);
+    }, { waitMs: 5000 });
+}
+//# sourceMappingURL=session-review.js.map

package/dist/core/sessions.js

@@ -0,0 +1,289 @@
+import { writeFileExclusive, CANONICAL_ID_PATTERN } from "./storage.js";
+import { validateApplicability, inferApplicability, buildTaskContext } from "./applicability.js";
+import { assertPathScope } from "./path-scope.js";
+import { assertNoSecrets } from "./secrets.js";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { frontmatter, parseFrontmatter, sectionBullets } from "./format.js";
+import { skillInputSchema } from "./skills.js";
+import { sortableId } from "./ids.js";
+import { exists, checkedDataPath } from "./storage.js";
+import { writeFileAtomic } from "./storage.js";
+import { withSyncLock } from "./sync-transaction.js";
+import { assertEnglishProse } from "./language.js";
+const exec = promisify(execFile);
+export const SESSION_SECTIONS = [
+    "Decisions",
+    "Lessons",
+    "Discoveries",
+    "Project State Changes",
+    "Global Instruction Candidates",
+    "Skill Candidates",
+];
+export const OBSERVATION_SECTIONS = {
+    decision: "Decisions",
+    lesson: "Lessons",
+    discovery: "Discoveries",
+    state_change: "Project State Changes",
+    global_instruction_candidate: "Global Instruction Candidates",
+    skill_candidate: "Skill Candidates",
+};
+export class SessionFormatError extends Error {
+    constructor(message) { super(`Invalid Prodero session: ${message}`); this.name = "SessionFormatError"; }
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value !== "null" ? value : null;
+}
+async function gitValue(root, args) {
+    try {
+        return (await exec("git", ["-C", root, ...args])).stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function renderSession(session, sections) {
+    assertNoSecrets([session, sections]);
+    const body = [`# Prodero Session ${session.id}`];
+    for (const heading of SESSION_SECTIONS) {
+        body.push(`## ${heading}`);
+        const items = sections?.[heading] ?? [];
+        body.push(items.length ? items.map((item) => `- ${item.replace(/\r?\n/g, "\n  ")}`).join("\n") : "_No durable observations recorded._");
+    }
+    return frontmatter({
+        id: session.id,
+        kind: "session-memory",
+        ...(session.taskContext ? { task_context: session.taskContext } : {}),
+        ...(session.parentSessionId ? { parent_session_id: session.parentSessionId } : {}),
+        created_at: session.createdAt,
+        updated_at: session.updatedAt,
+        status: session.status,
+        agent: session.agent,
+        branch: session.branch,
+        base_commit: session.baseCommit,
+    }, body.join("\n\n"));
+}
+export function parseSession(content, sessionPath) {
+    assertNoSecrets(content);
+    const { metadata, body } = parseFrontmatter(content, sessionPath);
+    // v1 checkpoint-ready sessions used date-based IDs and omitted timestamps.
+    const legacyCheckpoint = metadata.kind === "session-memory" && metadata.status === "checkpoint-ready" && metadata.version === undefined
+        && typeof metadata.id === "string" && /^\d{4}-\d{2}-\d{2}-[a-zA-Z0-9_-]+$/.test(metadata.id) && `${metadata.id}.md` === path.basename(sessionPath);
+    const modern = !legacyCheckpoint && (metadata.kind === "session-memory" || path.basename(sessionPath).startsWith("sess_"));
+    if (metadata.kind !== undefined && metadata.kind !== "session-memory")
+        throw new SessionFormatError(`${sessionPath} has unsupported kind.`);
+    if (metadata.version !== undefined)
+        throw new SessionFormatError(`${sessionPath} has unsupported version.`);
+    if (modern && (typeof metadata.id !== "string" || !/^sess_[a-zA-Z0-9_]+$/.test(metadata.id) || metadata.id !== path.basename(sessionPath, ".md")))
+        throw new SessionFormatError(`${sessionPath} id does not match its filename.`);
+    if (!legacyCheckpoint && (modern || metadata.status !== undefined) && !["active", "open", "closed"].includes(String(metadata.status)))
+        throw new SessionFormatError(`${sessionPath} has unsupported status.`);
+    for (const field of ["created_at", "updated_at"])
+        if ((modern || metadata[field] !== undefined) && (typeof metadata[field] !== "string" || !Number.isFinite(Date.parse(metadata[field]))))
+            throw new SessionFormatError(`${sessionPath} has invalid ${field}.`);
+    if (metadata.parent_session_id !== undefined && (typeof metadata.parent_session_id !== "string" || !/^sess_[a-zA-Z0-9_]+$/.test(metadata.parent_session_id) || metadata.parent_session_id === metadata.id))
+        throw new SessionFormatError(`${sessionPath} has invalid parent_session_id.`);
+    const statelessId = path.basename(sessionPath, path.extname(sessionPath));
+    const createdAt = stringOrNull(metadata.created_at) ?? new Date(0).toISOString();
+    const rawStatus = stringOrNull(metadata.status);
+    const status = rawStatus === "closed" || rawStatus === "active" ? rawStatus : "open";
+    return {
+        id: stringOrNull(metadata.id) ?? statelessId,
+        ...(metadata.parent_session_id ? { parentSessionId: metadata.parent_session_id } : {}),
+        ...(metadata.task_context ? { taskContext: metadata.task_context } : {}),
+        createdAt,
+        updatedAt: stringOrNull(metadata.updated_at) ?? createdAt,
+        status,
+        agent: stringOrNull(metadata.agent) ?? "unknown",
+        branch: stringOrNull(metadata.branch),
+        baseCommit: stringOrNull(metadata.base_commit),
+        path: path.basename(sessionPath),
+        sections: sectionBullets(body, SESSION_SECTIONS),
+    };
+}
+function parseSessionStrict(content, sessionPath) {
+    const { metadata } = parseFrontmatter(content);
+    if (typeof metadata.id !== "string" || !/^sess_[a-zA-Z0-9_]+$/.test(metadata.id))
+        throw new SessionFormatError(`${sessionPath} has a missing or invalid id.`);
+    if (metadata.status !== "open" && metadata.status !== "active" && metadata.status !== "closed")
+        throw new SessionFormatError(`${sessionPath} has an unsupported status.`);
+    if (typeof metadata.created_at !== "string" || Number.isNaN(Date.parse(metadata.created_at)))
+        throw new SessionFormatError(`${sessionPath} has an invalid created_at.`);
+    const session = parseSession(content, sessionPath);
+    if (session.id !== path.basename(sessionPath, ".md"))
+        throw new SessionFormatError(`${sessionPath} id does not match its filename.`);
+    return session;
+}
+export async function listSessions(root) {
+    const directory = await checkedDataPath(root, "sessions");
+    if (!(await exists(directory)))
+        return [];
+    const names = (await fs.readdir(directory)).filter((name) => name.endsWith(".md") && !name.startsWith(".")).sort();
+    const sessions = [];
+    for (const name of names)
+        sessions.push(parseSession(await fs.readFile(await checkedDataPath(root, "sessions", name), "utf8"), name));
+    return sessions;
+}
+export async function readSession(root, sessionId) {
+    const filename = sessionFilename(sessionId);
+    const target = await checkedDataPath(root, "sessions", filename);
+    if (!(await exists(target)))
+        throw new Error(`Prodero session ${sessionId} was not found.`);
+    return parseSessionStrict(await fs.readFile(target, "utf8"), filename);
+}
+export async function createSession(root, options = {}) {
+    assertNoSecrets(options);
+    return withSyncLock(root, () => createSessionLocked(root, options), { waitMs: 5_000 });
+}
+async function createSessionLocked(root, options) {
+    if (options.parentSessionId) {
+        const parent = await readSession(root, options.parentSessionId);
+        if (parent.status === "closed" || parent.parentSessionId)
+            throw new Error("Remember provenance requires an active work session.");
+    }
+    const id = sortableId("sess");
+    const now = new Date().toISOString();
+    const session = {
+        id,
+        ...(options.parentSessionId ? { parentSessionId: options.parentSessionId } : {}),
+        ...(options.taskContext ? { taskContext: options.taskContext } : {}),
+        createdAt: now,
+        updatedAt: now,
+        status: options.status ?? "active",
+        agent: options.agent ?? "coding-agent",
+        branch: await gitValue(root, ["branch", "--show-current"]),
+        baseCommit: await gitValue(root, ["rev-parse", "HEAD"]),
+    };
+    const filename = `${id}.md`;
+    await writeFileExclusive(await checkedDataPath(root, "sessions", filename), renderSession(session));
+    return parseSession(await fs.readFile(await checkedDataPath(root, "sessions", filename), "utf8"), filename);
+}
+function sessionFilename(sessionId) {
+    if (!/^sess_[a-zA-Z0-9_]+$/.test(sessionId))
+        throw new SessionFormatError("sessionId is malformed.");
+    return `${sessionId}.md`;
+}
+function annotationValue(value) {
+    return JSON.stringify(value.trim());
+}
+export function serializeObservation(id, entry) {
+    const attributes = [`id=${id}`];
+    if (entry.title?.trim())
+        attributes.push(`title=${annotationValue(entry.title)}`);
+    if (entry.applicability)
+        attributes.push(`applicability=${annotationValue(JSON.stringify(validateApplicability(entry.applicability)))}`);
+    if (entry.scopeKind)
+        attributes.push(`scope_kind=${entry.scopeKind}`);
+    if (entry.scopeHint)
+        attributes.push(`scope=${entry.scopeHint}`);
+    if (entry.scopeRef?.trim())
+        attributes.push(`scope_ref=${annotationValue(entry.scopeRef)}`);
+    if (entry.importanceHint)
+        attributes.push(`priority=${entry.importanceHint}`);
+    if (entry.categoryHint)
+        attributes.push(`category=${entry.categoryHint}`);
+    if (entry.description)
+        attributes.push(`description=${annotationValue(entry.description)}`);
+    if (entry.triggers)
+        attributes.push(`triggers=${annotationValue(JSON.stringify(entry.triggers))}`);
+    if (entry.proposedReason)
+        attributes.push(`proposed_reason=${annotationValue(entry.proposedReason)}`);
+    if (entry.supersedes?.length)
+        attributes.push(`supersedes=${annotationValue(entry.supersedes.join(","))}`);
+    if (entry.relations?.length)
+        attributes.push(`relations=${annotationValue(JSON.stringify(entry.relations))}`);
+    const content = entry.type === "skill_candidate" ? entry.content.trim() : entry.content.replace(/\s+/g, " ").trim();
+    return `[${attributes.join(" ")}] ${content}`;
+}
+export function validateEntries(entries) {
+    assertNoSecrets(entries);
+    if (entries.length > 100)
+        throw new Error("A Prodero session record batch may contain at most 100 observations.");
+    for (const entry of entries) {
+        if (entry.applicability)
+            validateApplicability(entry.applicability);
+        if (entry.scopeKind !== undefined && !["path", "topic"].includes(entry.scopeKind))
+            throw new Error("Invalid scope kind");
+        assertPathScope({ scope: entry.scopeHint ?? "task", scopeRef: entry.scopeRef ?? null, scopeKind: entry.scopeKind });
+        if (!(entry.type in OBSERVATION_SECTIONS))
+            throw new Error(`Unsupported Prodero observation type: ${String(entry.type)}.`);
+        const content = entry.content.trim();
+        if (!content)
+            throw new Error("Prodero session observations require non-empty content.");
+        assertEnglishProse([entry.title, content, entry.description, ...(entry.triggers ?? []), entry.proposedReason], "Prodero session knowledge");
+        if (entry.type === "skill_candidate") {
+            skillInputSchema.parse({ title: entry.title ?? "Candidate", description: entry.description ?? "Candidate", content, scope: entry.scopeRef ?? "project", triggers: entry.triggers ?? [] });
+            if (entry.proposedReason && entry.proposedReason.length > 1_000)
+                throw new Error("Skill proposal reasons may not exceed 1,000 characters.");
+        }
+        if (entry.supersedes?.some((id) => !CANONICAL_ID_PATTERN.test(id)))
+            throw new Error("Superseded Prodero memory ids are malformed.");
+        if (entry.relations?.some((relation) => !["related_to", "depends_on", "implements"].includes(relation.type) || !CANONICAL_ID_PATTERN.test(relation.target)))
+            throw new Error("Prodero memory relationships are malformed.");
+        if (content.length > 10_000)
+            throw new Error("A Prodero session observation may not exceed 10,000 characters.");
+    }
+}
+async function mutateSession(root, sessionId, entries, close) {
+    return withSyncLock(root, () => mutateSessionLocked(root, sessionId, entries, close), { waitMs: 5_000 });
+}
+async function mutateSessionLocked(root, sessionId, entries, close) {
+    const context = (await readSession(root, sessionId)).taskContext;
+    entries = entries.map(entry => ({ ...entry, applicability: entry.applicability ?? (['skill_candidate', 'global_instruction_candidate'].includes(entry.type) ? undefined : entry.taskContext ? inferApplicability(entry.content, buildTaskContext('', entry.taskContext)) : entry.scopeHint ? { kind: 'legacy' } : inferApplicability(entry.content, context)) }));
+    validateEntries(entries);
+    const filename = sessionFilename(sessionId);
+    const target = await checkedDataPath(root, "sessions", filename);
+    const session = await readSession(root, sessionId);
+    if (session.status === "closed") {
+        // Retrying an identical final batch after a lost response or failed Sync must
+        // not append fresh observation IDs. Compare the recorded suffix per section.
+        const repeatedBatch = SESSION_SECTIONS.every((section) => {
+            const expected = entries.filter((entry) => OBSERVATION_SECTIONS[entry.type] === section)
+                .map((entry) => serializeObservation("retry", entry));
+            const actual = session.sections[section].slice(-expected.length)
+                .map((entry) => entry.replace(/^\[id=obs_[a-zA-Z0-9_]+/, "[id=retry"));
+            return expected.length === 0 || (actual.length === expected.length && expected.every((entry, index) => entry === actual[index]));
+        });
+        if (close && repeatedBatch)
+            return { session, recorded: [], alreadyClosed: true };
+        throw new Error(`Prodero session ${sessionId} is closed and cannot accept new observations.`);
+    }
+    const recorded = [];
+    for (const entry of entries) {
+        if (entry.applicability)
+            validateApplicability(entry.applicability);
+        if (entry.scopeKind !== undefined && !["path", "topic"].includes(entry.scopeKind))
+            throw new Error("Invalid scope kind");
+        assertPathScope({ scope: entry.scopeHint ?? "task", scopeRef: entry.scopeRef ?? null, scopeKind: entry.scopeKind });
+        const id = sortableId("obs");
+        session.sections[OBSERVATION_SECTIONS[entry.type]].push(serializeObservation(id, entry));
+        recorded.push({ id, type: entry.type, content: entry.content.trim() });
+    }
+    session.updatedAt = new Date().toISOString();
+    if (close)
+        session.status = "closed";
+    await writeFileAtomic(target, renderSession(session, session.sections));
+    return { session: parseSessionStrict(await fs.readFile(target, "utf8"), filename), recorded, alreadyClosed: false };
+}
+export async function recordSessionObservations(root, sessionId, entries) {
+    if (!entries.length)
+        throw new Error("Prodero session recording requires at least one observation.");
+    return mutateSession(root, sessionId, entries, false);
+}
+export async function closeSession(root, sessionId, finalEntries = []) {
+    return mutateSession(root, sessionId, finalEntries, true);
+}
+/** A retry explicitly refreshes future observation context, not previously delivered snapshots. */
+export async function updateSessionTaskContext(root, id, context) {
+    return withSyncLock(root, async () => {
+        const session = await readSession(root, id);
+        if (session.status === 'closed')
+            throw new Error('Cannot enrich a closed session');
+        session.taskContext = context;
+        await writeFileAtomic(await checkedDataPath(root, 'sessions', sessionFilename(id)), renderSession(session, session.sections));
+        return session;
+    });
+}
+//# sourceMappingURL=sessions.js.map

package/dist/core/settings.js

@@ -0,0 +1,94 @@
+import { SETTINGS, settingKeySchema } from '../settings-definition.js';
+import fs from 'node:fs/promises';
+import { presentationConfigSchema } from '../settings-definition.js';
+import { readConfig, writeConfig, projectDataPath, assertSafePath, exists, assertSupportedSchema, assertSupportedKnowledgeSchema } from './storage.js';
+import { withSyncLock } from './sync-transaction.js';
+import { readLocalPreferences, saveLocalPreference } from './local-preferences.js';
+async function supportedConfig(root) {
+    const config = await readConfig(root);
+    if (config) {
+        assertSupportedSchema(config.schemaVersion);
+        assertSupportedKnowledgeSchema(config.knowledgeSchemaVersion);
+    }
+    return config;
+}
+export function effectiveSettings(config, local = {}) {
+    const legacy = { 'presentation.mode': config?.presentation?.mode, 'presentation.theme': config?.presentation?.theme, 'context.max_tokens': config?.context?.max_tokens ?? config?.context?.budgetTokens };
+    const overrides = { 'presentation.mode': local.mode, 'presentation.theme': local.theme, 'context.max_tokens': undefined };
+    const values = { ...legacy, 'presentation.mode': local.mode ?? legacy['presentation.mode'], 'presentation.theme': local.theme ?? legacy['presentation.theme'] };
+    return SETTINGS.map(def => {
+        const value = values[def.key] ?? def.defaultValue;
+        const option = 'options' in def ? def.options.find(o => o.id === value) : undefined;
+        return { key: def.key, group: def.group, label: def.label, description: option && 'description' in option ? option.description : def.description, type: def.type, value,
+            displayValue: option?.label ?? (typeof value === 'number' ? `${value.toLocaleString('en-US')} ${'unit' in def ? def.unit : ''}`.trim() : String(value)),
+            source: overrides[def.key] !== undefined ? 'local override' : legacy[def.key] === undefined ? 'default' : def.group === 'Presentation' ? 'legacy project default' : 'project override',
+            defaultValue: def.defaultValue, ...('options' in def ? { options: def.options } : {}), ...('min' in def ? { min: def.min, max: def.max } : {}) };
+    });
+}
+export async function projectSettings(root) {
+    let config;
+    try {
+        config = await supportedConfig(root);
+    }
+    catch (error) {
+        // Presentation preferences are metadata, never a permission to read/write newer knowledge.
+        const marker = projectDataPath(root, '.transactions/migration.json');
+        await assertSafePath(marker);
+        if (!String(error).includes('SCHEMA_NEWER') && !await exists(marker))
+            throw error;
+        const file = projectDataPath(root, 'config.json');
+        await assertSafePath(file);
+        let raw;
+        try {
+            raw = JSON.parse(await fs.readFile(file, 'utf8'));
+        }
+        catch {
+            raw = {};
+        }
+        const presentation = presentationConfigSchema.safeParse(raw?.presentation);
+        config = { presentation: presentation.success ? presentation.data : undefined };
+    }
+    const local = await readLocalPreferences(root), settings = effectiveSettings(config, local.presentation);
+    return { root, initialized: config !== null, settings, presentation: { mode: local.presentation.mode ?? config?.presentation?.mode ?? SETTINGS[0].defaultValue, theme: local.presentation.theme ?? config?.presentation?.theme ?? SETTINGS[1].defaultValue },
+        presentationSources: { mode: settings[0].source, theme: settings[1].source }, diagnostics: local.diagnostics };
+}
+export function renderSettings(view) {
+    const lines = ['Prodero · Project Settings'];
+    for (const group of [...new Set(view.settings.map(s => s.group))]) {
+        lines.push(group);
+        for (const s of view.settings.filter(s => s.group === group))
+            lines.push(`${s.label}: ${s.displayValue} (${s.source})`, s.description);
+    }
+    lines.push('Display mode and theme are saved on this checkout. Context budget is shared project configuration.');
+    for (const diagnostic of view.diagnostics)
+        lines.push(`${diagnostic.code}: ${diagnostic.cause}`, diagnostic.recovery);
+    if (!view.initialized)
+        lines.push('Project is not initialized. Defaults are shown; initialize Prodero before saving settings.');
+    return lines.join('\n\n');
+}
+export async function setProjectSetting(root, key, value, options = {}) {
+    const name = settingKeySchema.parse(key), def = SETTINGS.find(s => s.key === name);
+    const reset = options.reset === true;
+    if (reset && (value !== undefined || name === 'context.max_tokens'))
+        throw new Error('Reset requires a presentation key and no value.');
+    const parsed = reset ? undefined : def.validation.parse(value);
+    if (!await supportedConfig(root))
+        throw new Error('Initialize Prodero before changing project settings.');
+    return withSyncLock(root, async () => {
+        const config = await supportedConfig(root);
+        if (!config)
+            throw new Error('Initialize Prodero before changing project settings.');
+        switch (name) {
+            case 'presentation.mode':
+            case 'presentation.theme':
+                await saveLocalPreference(root, name === 'presentation.mode' ? 'mode' : 'theme', parsed, reset);
+                return projectSettings(root);
+            case 'context.max_tokens':
+                config.context = { ...config.context, max_tokens: parsed };
+                break;
+        }
+        await writeConfig(root, config);
+        return projectSettings(root);
+    }, { waitMs: 5000, ...(name === 'context.max_tokens' ? {} : { recoverLifecycle: false, maintainIntegration: false }) });
+}
+//# sourceMappingURL=settings.js.map