context-brake 0.0.0-stage → 1.0.0

package/dist/src/infrastructure/process/process-tree.d.ts

@@ -0,0 +1,2 @@
+import { type ChildProcess } from 'node:child_process';
+export declare function killProcessTree(child: ChildProcess): Promise<void>;

package/dist/src/infrastructure/process/process-tree.js

@@ -0,0 +1,28 @@
+import { execFile } from 'node:child_process';
+import process from 'node:process';
+function killWindowsTree(child) {
+    return new Promise((resolve) => {
+        if (!child.pid) {
+            resolve();
+            return;
+        }
+        execFile('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true }, () => resolve());
+    });
+}
+function killPosixTree(child) {
+    if (!child.pid) {
+        child.kill('SIGKILL');
+        return Promise.resolve();
+    }
+    try {
+        process.kill(-child.pid, 'SIGKILL');
+    }
+    catch (cause) {
+        if (!child.kill('SIGKILL'))
+            return Promise.reject(new Error('Unable to stop timed-out process tree.', { cause }));
+    }
+    return Promise.resolve();
+}
+export function killProcessTree(child) {
+    return process.platform === 'win32' ? killWindowsTree(child) : killPosixTree(child);
+}

package/dist/src/infrastructure/runtime/hook-deadline.d.ts

@@ -0,0 +1,26 @@
+import type { HookPhase, PhaseTiming } from '../../core/contracts/hook-phase.js';
+import type { RuntimeEvent } from '../../core/contracts/runtime.js';
+export declare const SESSION_START_DEADLINE_MILLISECONDS = 5000;
+export type DeadlineLimits = {
+    readonly event: number;
+    readonly sessionStart: number;
+};
+export declare const DEFAULT_DEADLINE_LIMITS: DeadlineLimits;
+export declare class HookDeadline {
+    private readonly now;
+    private phase;
+    private expiredAtLeastOnce;
+    private timer;
+    private rejectExpired;
+    private readonly startedAt;
+    private readonly expired;
+    constructor(milliseconds: number, initialPhase: HookPhase, now?: () => number);
+    readonly mark: (phase: HookPhase) => void;
+    readonly isExpired: () => boolean;
+    readonly commit: () => boolean;
+    extendTo(milliseconds: number): void;
+    run<T>(work: Promise<T>): Promise<T>;
+    private schedule;
+}
+export declare function deadlineFor(event: RuntimeEvent | null, limits: DeadlineLimits): number;
+export declare function deadlineTiming(error: unknown): PhaseTiming | undefined;

package/dist/src/infrastructure/runtime/hook-deadline.js

@@ -0,0 +1,55 @@
+import { performance } from 'node:perf_hooks';
+import { DeadlineExceededError, INTERNAL_DEADLINE_MILLISECONDS } from '../../core/services/failure-policy.js';
+export const SESSION_START_DEADLINE_MILLISECONDS = 5000;
+export const DEFAULT_DEADLINE_LIMITS = { event: INTERNAL_DEADLINE_MILLISECONDS, sessionStart: SESSION_START_DEADLINE_MILLISECONDS };
+export class HookDeadline {
+    now;
+    phase;
+    expiredAtLeastOnce = false;
+    timer;
+    rejectExpired = () => undefined;
+    startedAt;
+    expired;
+    constructor(milliseconds, initialPhase, now = () => performance.now()) {
+        this.now = now;
+        this.phase = initialPhase;
+        this.startedAt = now();
+        this.expired = new Promise((_, reject) => { this.rejectExpired = reject; });
+        this.expired.catch(() => undefined);
+        this.schedule(milliseconds);
+    }
+    mark = (phase) => { this.phase = phase; };
+    isExpired = () => this.expiredAtLeastOnce;
+    commit = () => {
+        if (this.expiredAtLeastOnce)
+            return false;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        return true;
+    };
+    extendTo(milliseconds) {
+        if (this.timer === undefined)
+            return;
+        clearTimeout(this.timer);
+        this.schedule(milliseconds);
+    }
+    async run(work) {
+        try {
+            return await Promise.race([work, this.expired]);
+        }
+        finally {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    schedule(milliseconds) {
+        const remaining = Math.max(0, milliseconds - (this.now() - this.startedAt));
+        this.timer = setTimeout(() => { this.expiredAtLeastOnce = true; this.rejectExpired(new DeadlineExceededError(this.phase, Math.round(this.now() - this.startedAt))); }, remaining);
+    }
+}
+export function deadlineFor(event, limits) {
+    return event?.kind === 'session_reset' ? limits.sessionStart : limits.event;
+}
+export function deadlineTiming(error) {
+    return error instanceof DeadlineExceededError ? { phase: error.phase, elapsedMs: error.elapsedMs } : undefined;
+}

package/dist/src/infrastructure/runtime/hook-failure.d.ts

@@ -0,0 +1,14 @@
+import type { ContextBrakeConfig } from '../../core/contracts/configuration.js';
+import type { RuntimeDecision, RuntimeDescriptor, RuntimeEvent } from '../../core/contracts/runtime.js';
+export type HookState = {
+    event: RuntimeEvent | null;
+    projectRoot: string | null;
+    config: ContextBrakeConfig | null;
+};
+export type HookFailure = {
+    readonly descriptor: RuntimeDescriptor;
+    readonly state: HookState;
+    readonly error: unknown;
+    readonly eventName: string;
+};
+export declare function failureDecision(input: HookFailure): Promise<RuntimeDecision>;

package/dist/src/infrastructure/runtime/hook-failure.js

@@ -0,0 +1,22 @@
+import { failureDetail, failureErrorCode, recordRuntimeFailure, resolveFailure } from '../../core/services/failure-policy.js';
+import { deadlineTiming } from './hook-deadline.js';
+import { createRuntimePorts, systemClock } from './runtime-composition.js';
+const NEUTRAL = { kind: 'neutral' };
+export async function failureDecision(input) {
+    if (input.state.projectRoot === null)
+        return NEUTRAL;
+    const ports = createRuntimePorts({ projectRoot: input.state.projectRoot, config: input.state.config, clock: systemClock });
+    const code = failureErrorCode(input.error);
+    const detail = failureDetail(input.error);
+    const timing = deadlineTiming(input.error);
+    if (input.state.event === null) {
+        await recordRuntimeFailure(ports.errors, { harness: input.descriptor.harness, event: input.eventName, code, detail, ...timing });
+        return NEUTRAL;
+    }
+    try {
+        return await resolveFailure({ event: input.state.event, code, detail, timing, config: input.state.config, descriptor: input.descriptor, ledger: ports.ledger, errors: ports.errors });
+    }
+    catch {
+        return NEUTRAL;
+    }
+}

package/dist/src/infrastructure/runtime/in-process-host.d.ts

@@ -0,0 +1,16 @@
+import type { ContextBrakeConfig } from '../../core/contracts/configuration.js';
+import type { RuntimeDecision, RuntimeDescriptor, RuntimeEvent } from '../../core/contracts/runtime.js';
+import type { Clock } from '../../core/contracts/session-ledger.js';
+import type { RuntimeInput } from '../../core/services/brake-engine.js';
+import { type DeadlineLimits } from './hook-deadline.js';
+export type InProcessRuntimeInput = {
+    readonly projectRoot: string;
+    readonly descriptor: RuntimeDescriptor;
+    readonly config: ContextBrakeConfig;
+    readonly clock?: Clock | undefined;
+    readonly deadlines?: DeadlineLimits | undefined;
+};
+export type InProcessRuntime = {
+    readonly handle: (event: RuntimeEvent, input?: RuntimeInput) => Promise<RuntimeDecision>;
+};
+export declare function createInProcessRuntime(input: InProcessRuntimeInput): InProcessRuntime;

package/dist/src/infrastructure/runtime/in-process-host.js

@@ -0,0 +1,75 @@
+import { failureDetail, failureErrorCode, resolveFailure } from '../../core/services/failure-policy.js';
+import { deadlineFor, deadlineTiming, DEFAULT_DEADLINE_LIMITS, HookDeadline } from './hook-deadline.js';
+import { NodeSessionLedger } from './node-session-ledger.js';
+import { composeRuntime, systemClock } from './runtime-composition.js';
+import { sessionLedgerHash } from './runtime-paths.js';
+export function createInProcessRuntime(input) {
+    const clock = input.clock ?? systemClock;
+    const ledger = new CachedSessionLedger(new NodeSessionLedger(input.projectRoot, clock), clock);
+    const services = composeRuntime({ projectRoot: input.projectRoot, descriptor: input.descriptor, config: input.config, clock, ledger });
+    return {
+        async handle(event, engineInput) {
+            try {
+                if (event.kind === 'session_reset')
+                    ledger.invalidate(event.session);
+                const deadline = new HookDeadline(deadlineFor(event, input.deadlines ?? DEFAULT_DEADLINE_LIMITS), 'engine');
+                return await deadline.run(services.engine.handle(event, { ...engineInput, onPhase: deadline.mark, deadline }));
+            }
+            catch (error) {
+                return handleFailure({ event, error, config: input.config, descriptor: input.descriptor, services, ledger });
+            }
+        },
+    };
+}
+async function handleFailure(input) {
+    try {
+        return await resolveFailure({ event: input.event, code: failureErrorCode(input.error), detail: failureDetail(input.error), timing: deadlineTiming(input.error), config: input.config, descriptor: input.descriptor, ledger: input.ledger, errors: input.services.errors });
+    }
+    catch {
+        return { kind: 'neutral' };
+    }
+}
+class CachedSessionLedger {
+    inner;
+    clock;
+    cache = new Map();
+    constructor(inner, clock) {
+        this.inner = inner;
+        this.clock = clock;
+    }
+    async readLines(key) {
+        const cached = this.cache.get(entryKey(key));
+        if (cached !== undefined)
+            return cached;
+        const lines = [...await this.inner.readLines(key)];
+        this.cache.set(entryKey(key), lines);
+        return lines;
+    }
+    async appendSessionLine(key) {
+        await this.inner.appendSessionLine(key);
+        this.cache.get(entryKey(key))?.push({ v: 1, type: 'session', at: this.clock.now().toISOString(), harness: key.harness, sessionId: key.sessionId, agentId: key.agentId });
+    }
+    async appendToolLine(key, input) {
+        await this.inner.appendToolLine(key, input);
+        this.cache.get(entryKey(key))?.push({ v: 1, type: 'tool', at: this.clock.now().toISOString(), ...input });
+    }
+    async appendResetLine(key, reason) {
+        await this.inner.appendResetLine(key, reason);
+        this.cache.get(entryKey(key))?.push({ v: 1, type: 'reset', at: this.clock.now().toISOString(), reason });
+    }
+    async appendStatuslineLine(key, input) {
+        await this.inner.appendStatuslineLine(key, input);
+        this.cache.get(entryKey(key))?.push({ v: 1, type: 'statusline', at: this.clock.now().toISOString(), ...input });
+    }
+    async pruneStaleSessions() {
+        const pruned = await this.inner.pruneStaleSessions();
+        this.cache.clear();
+        return pruned;
+    }
+    invalidate(key) {
+        this.cache.delete(entryKey(key));
+    }
+}
+function entryKey(key) {
+    return `${key.harness}\0${sessionLedgerHash(key)}`;
+}

package/dist/src/infrastructure/runtime/node-runtime-logs.d.ts

@@ -0,0 +1,8 @@
+import type { HarnessId } from '../../core/contracts/harness.js';
+import type { Clock, ErrorRecordInput, RuntimeErrorLog } from '../../core/contracts/session-ledger.js';
+export declare class NodeRuntimeErrorLog implements RuntimeErrorLog {
+    readonly projectRoot: string;
+    readonly clock: Clock;
+    constructor(projectRoot: string, clock: Clock);
+    append(harness: HarnessId, input: ErrorRecordInput): Promise<void>;
+}

package/dist/src/infrastructure/runtime/node-runtime-logs.js

@@ -0,0 +1,21 @@
+import { appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { errorLineSchema } from '../../core/contracts/session-ledger.js';
+import { ensureRuntimeDirectory, runtimeDirectory } from './runtime-paths.js';
+const ERRORS_FILE_NAME = 'errors.jsonl';
+export class NodeRuntimeErrorLog {
+    projectRoot;
+    clock;
+    constructor(projectRoot, clock) {
+        this.projectRoot = projectRoot;
+        this.clock = clock;
+    }
+    async append(harness, input) {
+        const line = errorLineSchema.parse({ v: 1, at: this.clock.now().toISOString(), harness, ...input });
+        await appendRuntimeLine(this.projectRoot, ERRORS_FILE_NAME, line);
+    }
+}
+async function appendRuntimeLine(projectRoot, fileName, line) {
+    await ensureRuntimeDirectory(projectRoot);
+    await appendFile(join(runtimeDirectory(projectRoot), fileName), `${JSON.stringify(line)}\n`, 'utf8');
+}

package/dist/src/infrastructure/runtime/node-session-ledger.d.ts

@@ -0,0 +1,17 @@
+import type { SessionKey } from '../../core/contracts/runtime.js';
+import type { Clock, LedgerLine, ResetReason, SessionLedger, ToolLineInput } from '../../core/contracts/session-ledger.js';
+import { type StatuslineLineInput } from '../../core/contracts/statusline-line.js';
+export declare class NodeSessionLedger implements SessionLedger {
+    readonly projectRoot: string;
+    readonly clock: Clock;
+    constructor(projectRoot: string, clock: Clock);
+    readLines(key: SessionKey): Promise<readonly LedgerLine[]>;
+    appendSessionLine(key: SessionKey): Promise<void>;
+    appendToolLine(key: SessionKey, input: ToolLineInput): Promise<void>;
+    appendResetLine(key: SessionKey, reason: ResetReason): Promise<void>;
+    appendStatuslineLine(key: SessionKey, input: StatuslineLineInput): Promise<void>;
+    pruneStaleSessions(): Promise<number>;
+    private prune;
+    private append;
+    private timestamp;
+}

package/dist/src/infrastructure/runtime/node-session-ledger.js

@@ -0,0 +1,68 @@
+import { appendFile, readFile, stat, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseLedgerLines, resetLineSchema, sessionLineSchema, toolLineSchema, SESSION_RETENTION_DAYS } from '../../core/contracts/session-ledger.js';
+import { statuslineLineSchema } from '../../core/contracts/statusline-line.js';
+import { listRuntimeStateFiles } from '../storage/runtime-state-files.js';
+import { ensureSessionDirectory, isMissingFileError, LEDGER_FILE_EXTENSION, sessionLedgerPath, SESSIONS_RELATIVE_PREFIX } from './runtime-paths.js';
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+export class NodeSessionLedger {
+    projectRoot;
+    clock;
+    constructor(projectRoot, clock) {
+        this.projectRoot = projectRoot;
+        this.clock = clock;
+    }
+    async readLines(key) {
+        const content = await readFile(sessionLedgerPath(this.projectRoot, key), 'utf8').catch((error) => {
+            if (isMissingFileError(error))
+                return '';
+            throw error;
+        });
+        return parseLedgerLines(content);
+    }
+    async appendSessionLine(key) {
+        await this.append(key, sessionLineSchema.parse({ v: 1, type: 'session', at: this.timestamp(), harness: key.harness, sessionId: key.sessionId, agentId: key.agentId }));
+    }
+    async appendToolLine(key, input) {
+        await this.append(key, toolLineSchema.parse({ v: 1, type: 'tool', at: this.timestamp(), ...input }));
+    }
+    async appendResetLine(key, reason) {
+        await this.append(key, resetLineSchema.parse({ v: 1, type: 'reset', at: this.timestamp(), reason }));
+    }
+    async appendStatuslineLine(key, input) {
+        await this.append(key, statuslineLineSchema.parse({ v: 1, type: 'statusline', at: this.timestamp(), ...input }));
+    }
+    async pruneStaleSessions() {
+        const cutoff = this.clock.now().getTime() - SESSION_RETENTION_DAYS * MILLISECONDS_PER_DAY;
+        const files = await listRuntimeStateFiles(this.projectRoot);
+        let pruned = 0;
+        for (const file of files) {
+            if (!file.startsWith(SESSIONS_RELATIVE_PREFIX) || !file.endsWith(LEDGER_FILE_EXTENSION))
+                continue;
+            if (await this.prune(resolve(this.projectRoot, file), cutoff))
+                pruned += 1;
+        }
+        return pruned;
+    }
+    async prune(filePath, cutoffMilliseconds) {
+        const stats = await stat(filePath).catch((error) => {
+            if (isMissingFileError(error))
+                return null;
+            throw error;
+        });
+        if (stats === null || stats.mtime.getTime() >= cutoffMilliseconds)
+            return false;
+        await unlink(filePath).catch((error) => {
+            if (!isMissingFileError(error))
+                throw error;
+        });
+        return true;
+    }
+    async append(key, line) {
+        await ensureSessionDirectory(this.projectRoot, key);
+        await appendFile(sessionLedgerPath(this.projectRoot, key), `${JSON.stringify(line)}\n`, 'utf8');
+    }
+    timestamp() {
+        return this.clock.now().toISOString();
+    }
+}

package/dist/src/infrastructure/runtime/process-hook-host.d.ts

@@ -0,0 +1,25 @@
+import type { RuntimeDecision, RuntimeDescriptor, RuntimeEvent } from '../../core/contracts/runtime.js';
+import type { RuntimeInput } from '../../core/services/brake-engine.js';
+import { type RuntimePorts } from './runtime-composition.js';
+export declare const MAXIMUM_STDIN_BYTES: number;
+export type ProcessHarnessAdapter = {
+    readonly descriptor: RuntimeDescriptor;
+    readonly mapEvent: (eventName: string, payload: unknown) => RuntimeEvent | null;
+    readonly mapInput: (eventName: string, payload: unknown, errors: RuntimePorts['errors']) => RuntimeInput | Promise<RuntimeInput>;
+    readonly renderDecision: (decision: RuntimeDecision, eventName: string) => string | null;
+    readonly resolveProjectRoot: (input: {
+        readonly eventName: string;
+        readonly payload: unknown;
+    }) => Promise<string>;
+};
+export type ProcessHookContext = {
+    readonly argv: readonly string[];
+    readonly readStdin: () => Promise<string>;
+    readonly writeStdout: (text: string) => void;
+    readonly writeStderr: (text: string) => void;
+    readonly deadlineMilliseconds: number;
+    readonly sessionStartDeadlineMilliseconds?: number | undefined;
+};
+export declare const defaultProcessHookContext: ProcessHookContext;
+export declare function readStdinUpTo(stream: NodeJS.ReadableStream, maximumBytes: number): Promise<string>;
+export declare function runProcessHook(adapter: ProcessHarnessAdapter, context?: ProcessHookContext): Promise<number>;

package/dist/src/infrastructure/runtime/process-hook-host.js

@@ -0,0 +1,79 @@
+import { failureErrorCode, INTERNAL_DEADLINE_MILLISECONDS } from '../../core/services/failure-policy.js';
+import { deadlineFor, HookDeadline, SESSION_START_DEADLINE_MILLISECONDS } from './hook-deadline.js';
+import { failureDecision } from './hook-failure.js';
+import { composeRuntime, loadRuntimeConfiguration, systemClock } from './runtime-composition.js';
+export const MAXIMUM_STDIN_BYTES = 16 * 1024 * 1024;
+const NEUTRAL = { kind: 'neutral' };
+export const defaultProcessHookContext = {
+    argv: process.argv,
+    readStdin: () => readStdinUpTo(process.stdin, MAXIMUM_STDIN_BYTES),
+    writeStdout: (text) => { process.stdout.write(text); },
+    writeStderr: (text) => { process.stderr.write(text); },
+    deadlineMilliseconds: INTERNAL_DEADLINE_MILLISECONDS,
+    sessionStartDeadlineMilliseconds: SESSION_START_DEADLINE_MILLISECONDS,
+};
+export function readStdinUpTo(stream, maximumBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        stream.on('data', (chunk) => {
+            const remaining = maximumBytes - size;
+            if (remaining <= 0)
+                return;
+            chunks.push(remaining >= chunk.length ? chunk : chunk.subarray(0, remaining));
+            size += chunk.length;
+        });
+        stream.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        stream.on('error', (error) => reject(error));
+    });
+}
+export async function runProcessHook(adapter, context = defaultProcessHookContext) {
+    const eventName = context.argv[2] ?? '';
+    const state = { event: null, projectRoot: null, config: null };
+    const deadline = new HookDeadline(context.deadlineMilliseconds, 'project_root');
+    const limits = { event: context.deadlineMilliseconds, sessionStart: context.sessionStartDeadlineMilliseconds ?? SESSION_START_DEADLINE_MILLISECONDS };
+    try {
+        const decision = await deadline.run(dispatchHook({ adapter, context, eventName, state, deadline, limits }));
+        writeDecision({ adapter, context, decision, eventName });
+    }
+    catch (error) {
+        const decision = await failureDecision({ descriptor: adapter.descriptor, state, error, eventName });
+        writeDecision({ adapter, context, decision, eventName });
+        context.writeStderr(`ContextBrake: ${failureErrorCode(error)}\n`);
+    }
+    return 0;
+}
+async function dispatchHook(input) {
+    const { deadline } = input;
+    const projectRoot = await input.adapter.resolveProjectRoot({ eventName: input.eventName, payload: null });
+    input.state.projectRoot = projectRoot;
+    deadline.mark('stdin');
+    const payload = parsePayload(await input.context.readStdin());
+    deadline.mark('event');
+    const event = input.adapter.mapEvent(input.eventName, payload);
+    input.state.event = event;
+    deadline.extendTo(deadlineFor(event, input.limits));
+    deadline.mark('config');
+    const config = await loadRuntimeConfiguration(projectRoot);
+    input.state.config = config;
+    if (event === null)
+        return NEUTRAL;
+    const services = composeRuntime({ projectRoot, descriptor: input.adapter.descriptor, config, clock: systemClock });
+    deadline.mark('input');
+    const engineInput = await input.adapter.mapInput(input.eventName, payload, services.errors);
+    deadline.mark('engine');
+    return services.engine.handle(event, { ...engineInput, onPhase: deadline.mark, deadline });
+}
+function writeDecision(input) {
+    const text = input.adapter.renderDecision(input.decision, input.eventName);
+    if (text !== null && text !== '')
+        input.context.writeStdout(text);
+}
+function parsePayload(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/infrastructure/runtime/runtime-composition.d.ts

@@ -0,0 +1,29 @@
+import { type ContextBrakeConfig } from '../../core/contracts/configuration.js';
+import type { HarnessId } from '../../core/contracts/harness.js';
+import type { RuntimeDescriptor } from '../../core/contracts/runtime.js';
+import type { Clock, RuntimeErrorLog, SessionLedger } from '../../core/contracts/session-ledger.js';
+import { type BrakeEngine } from '../../core/services/brake-engine.js';
+export declare const CONFIG_RELATIVE_PATH = "context-brake.config.json";
+export declare const systemClock: Clock;
+export type RuntimePorts = {
+    readonly ledger: SessionLedger;
+    readonly errors: RuntimeErrorLog;
+};
+export type RuntimeServices = RuntimePorts & {
+    readonly engine: BrakeEngine;
+    readonly config: ContextBrakeConfig;
+};
+export type RuntimePortsInput = {
+    readonly projectRoot: string;
+    readonly config: ContextBrakeConfig | null;
+    readonly clock: Clock;
+    readonly ledger?: SessionLedger | undefined;
+    readonly harness?: HarnessId;
+};
+export type RuntimeCompositionInput = RuntimePortsInput & {
+    readonly descriptor: RuntimeDescriptor;
+    readonly config: ContextBrakeConfig;
+};
+export declare function loadRuntimeConfiguration(projectRoot: string): Promise<ContextBrakeConfig>;
+export declare function createRuntimePorts(input: RuntimePortsInput): RuntimePorts;
+export declare function composeRuntime(input: RuntimeCompositionInput): RuntimeServices;

package/dist/src/infrastructure/runtime/runtime-composition.js

@@ -0,0 +1,41 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { DEFAULT_CONFIG } from '../../core/contracts/configuration.js';
+import { createBrakeEngine } from '../../core/services/brake-engine.js';
+import { invalidSyntaxError, parseConfiguration } from '../../core/validation/configuration-validator.js';
+import { NodeHandoffStore } from '../storage/node-handoff-store.js';
+import { NodeRuntimeErrorLog } from './node-runtime-logs.js';
+import { NodeSessionLedger } from './node-session-ledger.js';
+import { isMissingFileError } from './runtime-paths.js';
+export const CONFIG_RELATIVE_PATH = 'context-brake.config.json';
+export const systemClock = { now: () => new Date() };
+export async function loadRuntimeConfiguration(projectRoot) {
+    const filePath = resolve(projectRoot, CONFIG_RELATIVE_PATH);
+    const content = await readFile(filePath, 'utf8').catch((error) => {
+        if (isMissingFileError(error))
+            return null;
+        throw error;
+    });
+    if (content === null)
+        return DEFAULT_CONFIG;
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch (error) {
+        throw invalidSyntaxError(filePath, content, error);
+    }
+    return parseConfiguration(value, filePath);
+}
+export function createRuntimePorts(input) {
+    return {
+        ledger: input.ledger ?? new NodeSessionLedger(input.projectRoot, input.clock),
+        errors: new NodeRuntimeErrorLog(input.projectRoot, input.clock),
+    };
+}
+export function composeRuntime(input) {
+    const ports = createRuntimePorts({ ...input, harness: input.descriptor.harness });
+    const handoff = new NodeHandoffStore(input.projectRoot, input.clock);
+    const engine = createBrakeEngine({ descriptor: input.descriptor, config: input.config, ledger: ports.ledger, errors: ports.errors, handoff });
+    return { ...ports, engine, config: input.config };
+}

package/dist/src/infrastructure/runtime/runtime-paths.d.ts

@@ -0,0 +1,12 @@
+import type { SessionKey } from '../../core/contracts/runtime.js';
+export declare const RUNTIME_GITIGNORE_CONTENT = "*\n";
+export declare const SESSIONS_DIR_NAME = "sessions";
+export declare const LEDGER_FILE_EXTENSION = ".jsonl";
+export declare const SESSIONS_RELATIVE_PREFIX: string;
+export declare function runtimeDirectory(projectRoot: string): string;
+export declare function sessionsDirectory(projectRoot: string, harness: SessionKey['harness']): string;
+export declare function sessionLedgerHash(key: SessionKey): string;
+export declare function sessionLedgerPath(projectRoot: string, key: SessionKey): string;
+export declare function ensureRuntimeDirectory(projectRoot: string): Promise<void>;
+export declare function ensureSessionDirectory(projectRoot: string, key: SessionKey): Promise<void>;
+export declare function isMissingFileError(error: unknown): boolean;

package/dist/src/infrastructure/runtime/runtime-paths.js

@@ -0,0 +1,45 @@
+import { createHash } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { RUNTIME_STATE_RELATIVE_DIR } from '../storage/runtime-state-files.js';
+export const RUNTIME_GITIGNORE_CONTENT = '*\n';
+export const SESSIONS_DIR_NAME = 'sessions';
+export const LEDGER_FILE_EXTENSION = '.jsonl';
+export const SESSIONS_RELATIVE_PREFIX = `${RUNTIME_STATE_RELATIVE_DIR}/${SESSIONS_DIR_NAME}/`;
+const HASH_LENGTH = 32;
+export function runtimeDirectory(projectRoot) {
+    return resolve(projectRoot, RUNTIME_STATE_RELATIVE_DIR);
+}
+export function sessionsDirectory(projectRoot, harness) {
+    return join(runtimeDirectory(projectRoot), SESSIONS_DIR_NAME, harness);
+}
+export function sessionLedgerHash(key) {
+    return createHash('sha256').update(`${key.sessionId}\0${key.agentId ?? ''}`).digest('hex').slice(0, HASH_LENGTH);
+}
+export function sessionLedgerPath(projectRoot, key) {
+    return join(sessionsDirectory(projectRoot, key.harness), `${sessionLedgerHash(key)}${LEDGER_FILE_EXTENSION}`);
+}
+export async function ensureRuntimeDirectory(projectRoot) {
+    const directory = runtimeDirectory(projectRoot);
+    await mkdir(join(directory, SESSIONS_DIR_NAME), { recursive: true });
+    await writeGitignoreIfMissing(join(directory, '.gitignore'));
+}
+export async function ensureSessionDirectory(projectRoot, key) {
+    await ensureRuntimeDirectory(projectRoot);
+    await mkdir(sessionsDirectory(projectRoot, key.harness), { recursive: true });
+}
+export function isMissingFileError(error) {
+    return error.code === 'ENOENT';
+}
+async function writeGitignoreIfMissing(filePath) {
+    try {
+        await writeFile(filePath, RUNTIME_GITIGNORE_CONTENT, { flag: 'wx' });
+    }
+    catch (error) {
+        if (!isAlreadyCreated(error))
+            throw error;
+    }
+}
+function isAlreadyCreated(error) {
+    return error.code === 'EEXIST';
+}

package/dist/src/infrastructure/runtime/runtime-state-reader.d.ts

@@ -0,0 +1,9 @@
+import type { Clock } from '../../core/contracts/session-ledger.js';
+import { type RuntimeStateReading } from '../../core/services/runtime-error-checks.js';
+export declare class NodeRuntimeStateReader {
+    readonly projectRoot: string;
+    readonly clock: Clock;
+    constructor(projectRoot: string, clock: Clock);
+    read(): Promise<RuntimeStateReading | null>;
+    private readLedgers;
+}