theorum 0.1.4 → 0.1.6

package/esm/src/kernel/engine/hash.js

@@ -0,0 +1,9 @@
+const HEX_PAD = 2;
+const HEX_RADIX = 16;
+function hexSha256(bytes) {
+    return [...bytes].map((b) => b.toString(HEX_RADIX).padStart(HEX_PAD, '0')).join('');
+}
+export async function sha256(text) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return hexSha256(new Uint8Array(buf));
+}

package/esm/src/kernel/engine/record.d.ts

@@ -0,0 +1,2 @@
+declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export { asRecord };

package/esm/src/kernel/engine/record.js

@@ -0,0 +1,7 @@
+function asRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+export { asRecord };

package/esm/src/kernel/engine/repair.d.ts

@@ -0,0 +1,7 @@
+import type { Profile, TurnHistoryMessage, TurnRepairRequest } from '../types.js';
+declare function synthesizeRepairPrompt(args: {
+    profile: Profile;
+    repair: TurnRepairRequest;
+    history?: TurnHistoryMessage[];
+}): string;
+export { synthesizeRepairPrompt };

package/esm/src/kernel/engine/repair.js

@@ -0,0 +1,38 @@
+const MAX_REPAIR_HISTORY_EXCHANGES = 2;
+const MAX_REPAIR_HISTORY_MESSAGES = MAX_REPAIR_HISTORY_EXCHANGES * 2;
+function scopeHistory(history) {
+    if (!history || history.length === 0) {
+        return [];
+    }
+    return history.slice(-MAX_REPAIR_HISTORY_MESSAGES);
+}
+function formatHistoryBlock(messages) {
+    if (messages.length === 0) {
+        return '';
+    }
+    const lines = messages.map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`);
+    return `### RECENT CONVERSATION CONTEXT (LAST ${messages.length} TURNS)\n${lines.join('\n')}\n\n`;
+}
+function synthesizeRepairPrompt(args) {
+    const { profile, repair, history } = args;
+    const guidance = repair.guidance ||
+        profile.outputs.validation?.repairGuidance ||
+        'Revise the previous output so it satisfies the validator rejection. Preserve the intended user-facing substance unless the guidance says otherwise.';
+    const historyBlock = formatHistoryBlock(scopeHistory(history));
+    let prompt = `## OUTPUT REPAIR REQUEST\n\n`;
+    prompt += `The previous assistant output was rejected by a host validator and must be revised.\n\n`;
+    prompt += `### PREVIOUS OUTPUT\n\`\`\`\n${repair.previousOutput.trim()}\n\`\`\`\n\n`;
+    prompt += `### VALIDATOR REJECTION\n${repair.rejection.trim()}\n\n`;
+    if (guidance.trim()) {
+        prompt += `### REPAIR GUIDANCE\n${guidance.trim()}\n\n`;
+    }
+    if (historyBlock) {
+        prompt += historyBlock;
+    }
+    prompt += `### INSTRUCTIONS\n`;
+    prompt += `1. Inspect the previous output and validator rejection.\n`;
+    prompt += `2. Apply the repair guidance without inventing unsupported facts.\n`;
+    prompt += `3. Return only the corrected assistant output required by the active profile.`;
+    return prompt;
+}
+export { synthesizeRepairPrompt };

package/esm/src/kernel/engine/runner/gates.d.ts

@@ -0,0 +1,4 @@
+import type { ModelProvider, Profile, ResolvedGeneration, TurnEvent, TurnRequest } from '../../types.js';
+import type { StepExecutionState } from './state.js';
+declare function runAttemptsWithValidation(safe: TurnRequest, profile: Profile, generation: ResolvedGeneration, system: string, provider: ModelProvider, gemini: Record<string, unknown>[], state: StepExecutionState): AsyncGenerator<TurnEvent>;
+export { runAttemptsWithValidation };

package/esm/src/kernel/engine/runner/gates.js

@@ -0,0 +1,208 @@
+import { TheorumError, toErrorEvent } from '../../../guardrails/error.js';
+import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { resolveTurn } from '../../registry/resolve.js';
+import { getStructured } from '../../registry/schemas.js';
+import { collectValidationFailures, formatValidationFailures } from './schema-validation.js';
+import { executeAttempt } from './steps.js';
+function collectAttemptText(events) {
+    return events
+        .filter((e) => e.type === 'text' && e.text)
+        .map((e) => e.text)
+        .join('');
+}
+function buildRepairRequest(safe, previousOutput, rejection, repairGuidance) {
+    return {
+        ...safe,
+        input: {
+            ...safe.input,
+            repair: {
+                previousOutput: typeof previousOutput === 'string' ? previousOutput : JSON.stringify(previousOutput),
+                rejection,
+                guidance: repairGuidance,
+            },
+        },
+    };
+}
+async function evaluateEgressOutcome(args) {
+    const { egress, attemptEvents, generation, request, profile, canRetry } = args;
+    const attemptText = collectAttemptText(attemptEvents);
+    const result = await egress.enforce({
+        text: attemptText,
+        canary: generation.canary,
+        slots: request.input?.slots,
+        profile,
+        role: request.input?.role,
+    });
+    if (!result.blocked) {
+        return { action: 'pass' };
+    }
+    if (egress.onBlock === 'refuse_to_user') {
+        return { action: 'refusal', event: { type: 'text', text: result.text } };
+    }
+    if (canRetry) {
+        const rejectionMsg = result.rejectionMessage || 'Egress disclosure violation detected.';
+        const repairGuidance = egress.repairGuidance ||
+            'Rewrite the message as corrected user-visible prose only. Keep the same helpful substance; scrub all internal tool names, leak phrases, and disclosure markers.';
+        const nextRequest = buildRepairRequest(request, attemptText, rejectionMsg, repairGuidance);
+        return { action: 'retry', nextRequest };
+    }
+    return {
+        action: 'withhold',
+        event: toErrorEvent('Turn withheld: egress disclosure violation'),
+    };
+}
+async function evaluateValidationOutcome(args) {
+    const { validation, generation, latestStructured, request, canRetry } = args;
+    if (latestStructured === undefined) {
+        return { action: 'pass' };
+    }
+    const structuredId = generation.structured;
+    if (!structuredId) {
+        throw new TheorumError('outputs.validation requires outputs.structured with a JSON Schema');
+    }
+    const spec = getStructured(structuredId);
+    if (!spec.jsonSchema) {
+        throw new TheorumError(`structured schema '${structuredId}' has no jsonSchema for validation`);
+    }
+    const failures = await collectValidationFailures(spec.jsonSchema, latestStructured, validation.fields, request.input?.slots);
+    if (failures.length === 0) {
+        return { action: 'pass' };
+    }
+    const error = formatValidationFailures(failures);
+    if (canRetry) {
+        const nextRequest = buildRepairRequest(request, latestStructured, error, validation.repairGuidance);
+        return { action: 'retry', nextRequest };
+    }
+    return {
+        action: 'accept',
+        event: { type: 'structured', structured: latestStructured },
+    };
+}
+function* yieldBufferedAttemptEvents(events, alreadyStreamedUserVisible) {
+    for (const ev of events) {
+        if (ev.type === 'tokens') {
+            continue;
+        }
+        // When validation-only, thought/text already streamed live.
+        if (alreadyStreamedUserVisible && (ev.type === 'thought' || ev.type === 'text')) {
+            continue;
+        }
+        yield ev;
+    }
+}
+function updateFlowForRetry(flow, nextReq) {
+    flow.currentAttempt++;
+    flow.currentReq = nextReq;
+    flow.currentGen = resolveTurn(sanitizeTurnRequest(nextReq)).generation;
+}
+async function* handleEgressGate(egress, flow, state, profile, maxRetries) {
+    const canRetry = flow.currentAttempt < maxRetries;
+    const outcome = await evaluateEgressOutcome({
+        egress,
+        attemptEvents: state.attemptEvents,
+        generation: flow.currentGen,
+        request: flow.currentReq,
+        profile,
+        canRetry,
+    });
+    if (outcome.action === 'refusal') {
+        state.allEmittedEvents.push(outcome.event);
+        yield outcome.event;
+        return 'terminal';
+    }
+    if (outcome.action === 'withhold') {
+        yield outcome.event;
+        return 'terminal';
+    }
+    if (outcome.action === 'retry') {
+        updateFlowForRetry(flow, outcome.nextRequest);
+        return 'continue';
+    }
+    return 'pass';
+}
+async function* handleValidationGate(validation, flow, state, latestStructured, maxRetries) {
+    const canRetry = flow.currentAttempt < maxRetries;
+    const outcome = await evaluateValidationOutcome({
+        validation,
+        generation: flow.currentGen,
+        latestStructured,
+        request: flow.currentReq,
+        canRetry,
+    });
+    if (outcome.action === 'retry') {
+        updateFlowForRetry(flow, outcome.nextRequest);
+        return 'continue';
+    }
+    if (outcome.action === 'accept') {
+        state.allEmittedEvents.push(outcome.event);
+        yield outcome.event;
+        return 'terminal';
+    }
+    return 'pass';
+}
+function gateStatusToAction(status, terminalStatus = 'terminal') {
+    if (status === 'terminal') {
+        return { status: terminalStatus };
+    }
+    if (status === 'continue') {
+        return { status: 'continue' };
+    }
+    return null;
+}
+async function* executeSingleAttemptCycle(args) {
+    const { flow, state, profile, system, provider, gemini, maxRetries } = args;
+    const validation = profile.outputs.validation;
+    const egress = profile.guardrails.egress;
+    state.attemptEvents = [];
+    const { latestStructured } = yield* executeAttempt({
+        safe: flow.currentReq,
+        profile,
+        generation: flow.currentGen,
+        system,
+        provider,
+        gemini,
+        state,
+    });
+    if (egress?.enforce) {
+        const status = yield* handleEgressGate(egress, flow, state, profile, maxRetries);
+        const action = gateStatusToAction(status, 'terminal');
+        if (action) {
+            return action;
+        }
+    }
+    if (validation) {
+        const status = yield* handleValidationGate(validation, flow, state, latestStructured, maxRetries);
+        const action = gateStatusToAction(status, 'success');
+        if (action) {
+            return action;
+        }
+    }
+    if (validation || egress?.enforce) {
+        const alreadyStreamedUserVisible = !egress?.enforce;
+        yield* yieldBufferedAttemptEvents(state.attemptEvents, alreadyStreamedUserVisible);
+    }
+    return { status: 'success' };
+}
+async function* runAttemptsWithValidation(safe, profile, generation, system, provider, gemini, state) {
+    const maxRetries = Math.max(profile.outputs.validation?.maxRetries ?? 0, profile.guardrails.egress?.maxRetries ?? 2);
+    const flow = {
+        currentAttempt: 0,
+        currentGen: generation,
+        currentReq: safe,
+    };
+    while (flow.currentAttempt <= maxRetries) {
+        const step = yield* executeSingleAttemptCycle({
+            flow,
+            state,
+            profile,
+            system,
+            provider,
+            gemini,
+            maxRetries,
+        });
+        if (step.status === 'terminal' || step.status === 'success') {
+            break;
+        }
+    }
+}
+export { runAttemptsWithValidation };

package/esm/src/kernel/engine/runner/mod.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deterministic turn runner for THEORUM.
+ *
+ * `runTurn` resolves a profile, sanitizes input, binds canary boundaries,
+ * streams provider events, executes allowed tools, applies validation and
+ * egress repair loops, writes traces, and emits one terminal `done` event.
+ *
+ * @module
+ */
+import { type TraceSink } from '../../../observability/trace.js';
+import type { ModelProvider, TurnEvent, TurnRequest } from '../../types.js';
+/** Execute one host turn against a provider adapter. */
+declare function runTurn(req: TurnRequest, provider: ModelProvider, sink?: TraceSink): AsyncGenerator<TurnEvent>;
+export { runTurn };

package/esm/src/kernel/engine/runner/mod.js

@@ -0,0 +1,103 @@
+/**
+ * Deterministic turn runner for THEORUM.
+ *
+ * `runTurn` resolves a profile, sanitizes input, binds canary boundaries,
+ * streams provider events, executes allowed tools, applies validation and
+ * egress repair loops, writes traces, and emits one terminal `done` event.
+ *
+ * @module
+ */
+import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { noopSink, writeTrace } from '../../../observability/trace.js';
+import { buildRecord } from '../../../observability/trace-record.js';
+import { pickSystemRole, resolveTurn } from '../../registry/resolve.js';
+import { bindCanary } from '../boundary.js';
+import { runAttemptsWithValidation } from './gates.js';
+import { shouldSkipStreamEvent, systemFromProfile } from './stream.js';
+import { calculateFallbackTokens } from './tokens.js';
+import { invokeFromUi } from './tools.js';
+async function* emitTurn(args) {
+    const { safe, profile, generation, system, provider, gemini } = args;
+    if (safe.toolInvoke) {
+        yield* invokeFromUi(profile, safe);
+        return;
+    }
+    const state = {
+        currentHistory: [...(generation.history ?? [])],
+        stepCount: 0,
+        sawTokensEvent: false,
+        allEmittedEvents: [],
+        attemptEvents: [],
+    };
+    yield* runAttemptsWithValidation(safe, profile, generation, system, provider, gemini, state);
+    if (!state.sawTokensEvent) {
+        yield* calculateFallbackTokens(safe, system, state.allEmittedEvents);
+    }
+    yield { type: 'done' };
+}
+/** Execute one host turn against a provider adapter. */
+async function* runTurn(req, provider, sink = noopSink()) {
+    const started = Date.now();
+    const seen = [];
+    const gemini = [];
+    let model;
+    let bucket;
+    let canary = '';
+    let system;
+    let generation;
+    try {
+        const safe = sanitizeTurnRequest(req);
+        const { profile, generation: gen } = resolveTurn(safe);
+        generation = gen;
+        const { model: resolvedModel, geminiBucket, canary: turnCanary } = gen;
+        model = resolvedModel;
+        bucket = geminiBucket;
+        canary = turnCanary;
+        const role = pickSystemRole(profile, safe.input?.role);
+        const profileSys = systemFromProfile(profile, role);
+        const combinedSys = [profileSys, safe.system].filter(Boolean).join('\n\n');
+        const bound = bindCanary(combinedSys, turnCanary);
+        system = bound;
+        for await (const event of emitTurn({
+            safe,
+            profile,
+            generation: gen,
+            system: bound,
+            provider,
+            gemini,
+        })) {
+            seen.push(event);
+            if (shouldSkipStreamEvent(event, profile)) {
+                continue;
+            }
+            yield event;
+        }
+    }
+    catch (err) {
+        await writeTrace(sink, buildRecord({
+            req,
+            events: seen,
+            started,
+            model,
+            bucket,
+            thrown: err,
+            gemini,
+            canary,
+            system,
+            generation,
+        }));
+        throw err;
+    }
+    await writeTrace(sink, buildRecord({
+        req,
+        events: seen,
+        started,
+        model,
+        bucket,
+        gemini,
+        canary,
+        system,
+        generation,
+    }));
+}
+export { runTurn };

package/esm/src/kernel/engine/runner/schema-validation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Schema-driven structured-output validation.
+ *
+ * Required vs optional comes only from the JSON Schema. Host field validators
+ * run for required paths and for optional paths that are present.
+ *
+ * @module
+ */
+import type { ProfileValidator } from '../../types.js';
+interface ValidationFailure {
+    path: string;
+    error: string;
+}
+declare function isAbsent(value: unknown): boolean;
+/**
+ * Collect schema presence failures and host field-validator failures.
+ * Throws when the root schema is not an object schema.
+ */
+declare function collectValidationFailures(jsonSchema: Record<string, unknown>, structured: unknown, fields: Record<string, ProfileValidator> | undefined, slots?: Record<string, string>): Promise<ValidationFailure[]>;
+declare function formatValidationFailures(failures: ValidationFailure[]): string;
+export type { ValidationFailure };
+export { collectValidationFailures, formatValidationFailures, isAbsent };

package/esm/src/kernel/engine/runner/schema-validation.js

@@ -0,0 +1,113 @@
+/**
+ * Schema-driven structured-output validation.
+ *
+ * Required vs optional comes only from the JSON Schema. Host field validators
+ * run for required paths and for optional paths that are present.
+ *
+ * @module
+ */
+import { TheorumError } from '../../../guardrails/error.js';
+function isAbsent(value) {
+    return value === undefined || value === null;
+}
+function asRecord(value) {
+    if (isAbsent(value) || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function asObjectSchema(schema) {
+    const rec = asRecord(schema);
+    if (!rec) {
+        return null;
+    }
+    if (rec.type !== undefined && rec.type !== 'object') {
+        return null;
+    }
+    return rec;
+}
+function requiredKeys(schema) {
+    const raw = schema.required;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((k) => typeof k === 'string');
+}
+function propertySchemas(schema) {
+    const props = schema.properties;
+    return asRecord(props) ?? {};
+}
+function joinPath(prefix, key) {
+    return prefix ? `${prefix}.${key}` : key;
+}
+function pushMissing(path, failures) {
+    failures.push({ path, error: `required field '${path}' is missing` });
+}
+async function runFieldValidator(path, value, validator, slots, failures) {
+    if (!validator) {
+        return;
+    }
+    const check = await validator(value, slots);
+    if (check.isValid) {
+        return;
+    }
+    failures.push({
+        path,
+        error: check.error || check.finding || `Validation failed for '${path}'`,
+    });
+}
+async function visitProperty(args) {
+    const { path, propSchema, child, isRequired, fields, slots, failures } = args;
+    if (isAbsent(child)) {
+        if (isRequired) {
+            pushMissing(path, failures);
+        }
+        return;
+    }
+    await runFieldValidator(path, child, fields?.[path], slots, failures);
+    const nested = asObjectSchema(propSchema);
+    const nestedValue = nested ? asRecord(child) : null;
+    if (nested && nestedValue) {
+        await walkObject(nested, nestedValue, path, fields, slots, failures);
+    }
+}
+async function walkObject(schema, value, pathPrefix, fields, slots, failures) {
+    const props = propertySchemas(schema);
+    const required = new Set(requiredKeys(schema));
+    const keys = new Set([...Object.keys(props), ...required]);
+    const record = asRecord(value);
+    for (const key of keys) {
+        await visitProperty({
+            path: joinPath(pathPrefix, key),
+            propSchema: props[key],
+            child: record?.[key],
+            isRequired: required.has(key),
+            fields,
+            slots,
+            failures,
+        });
+    }
+}
+/**
+ * Collect schema presence failures and host field-validator failures.
+ * Throws when the root schema is not an object schema.
+ */
+async function collectValidationFailures(jsonSchema, structured, fields, slots) {
+    const root = asObjectSchema(jsonSchema);
+    if (!root) {
+        throw new TheorumError('structured validation requires a JSON Schema object root');
+    }
+    const failures = [];
+    if (!asRecord(structured)) {
+        for (const key of requiredKeys(root)) {
+            pushMissing(key, failures);
+        }
+        return failures;
+    }
+    await walkObject(root, structured, '', fields, slots, failures);
+    return failures;
+}
+function formatValidationFailures(failures) {
+    return failures.map((f) => f.error).join('; ');
+}
+export { collectValidationFailures, formatValidationFailures, isAbsent };

package/esm/src/kernel/engine/runner/state.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnRequest } from '../../types.js';
+interface StepExecutionState {
+    currentHistory: TurnHistoryMessage[];
+    stepCount: number;
+    sawTokensEvent: boolean;
+    allEmittedEvents: TurnEvent[];
+    attemptEvents: TurnEvent[];
+}
+interface AttemptFlowState {
+    currentAttempt: number;
+    currentReq: TurnRequest;
+    currentGen: ResolvedGeneration;
+}
+declare function recordStepEvent(event: TurnEvent, state: StepExecutionState): void;
+export type { AttemptFlowState, StepExecutionState };
+export { recordStepEvent };

package/esm/src/kernel/engine/runner/state.js

@@ -0,0 +1,8 @@
+function recordStepEvent(event, state) {
+    if (event.type === 'tokens') {
+        state.sawTokensEvent = true;
+    }
+    state.allEmittedEvents.push(event);
+    state.attemptEvents.push(event);
+}
+export { recordStepEvent };

package/esm/src/kernel/engine/runner/steps.d.ts

@@ -0,0 +1,15 @@
+import type { ModelProvider, Profile, ResolvedGeneration, TurnEvent, TurnRequest } from '../../types.js';
+import { type StepExecutionState } from './state.js';
+declare function executeAttempt(args: {
+    safe: TurnRequest;
+    profile: Profile;
+    generation: ResolvedGeneration;
+    system: string;
+    provider: ModelProvider;
+    gemini: Record<string, unknown>[];
+    state: StepExecutionState;
+}): AsyncGenerator<TurnEvent, {
+    pendingTools: TurnEvent[];
+    latestStructured?: unknown;
+}>;
+export { executeAttempt };