@zq-silk/yui 2.0.0 → 2.2.0

package/dist/nativeAgent/compactionDemo.js

@@ -0,0 +1,158 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createAgent, createContextBuilder, createProviderCompressor, createModelGateway, createSessionStore, createSqliteSessionBackend, createExecutionOwner, createTextTools } from './index.js';
+const digest = (v) => createHash('sha256').update(JSON.stringify(v)).digest('hex');
+/** Only model responses are fixtures. Real gateway, kernel, tools, SQLite and owner remain in the path. */
+export async function runCompactionDemo() {
+    const root = await mkdtemp(path.join(tmpdir(), 'agent-compaction-demo-'));
+    let store, owner;
+    let summaryCalls = 0, codingCalls = 0, compressedRequests = 0;
+    const observedSummaryBytes = [];
+    const observedSourceBytes = [];
+    const codingProjections = [];
+    const sessionId = 'long-session';
+    const verifySources = (serialized, report, full) => {
+        const summary = JSON.parse(serialized).contextSummary;
+        const selected = report.entries.filter(entry => entry.action === 'summarized');
+        assert.equal(summary.historyDigest, report.historyDigest);
+        assert.equal(summary.digest, digest(selected.map(entry => entry.digest)));
+        assert.equal(summary.sources.provenanceDigest, digest(selected.map(({ action: _action, reason: _reason, ...entry }) => entry)));
+        const span = summary.sources.history;
+        assert.equal(span.rangeKind, 'enclosing');
+        assert.equal(span.digest, digest(full.slice(...span.historyRange)));
+        const outcomes = selected.flatMap(entry => entry.toolOutcomes ?? []);
+        assert.deepEqual(summary.sources.toolSettlements, {
+            representation: 'aggregate-only', succeeded: outcomes.filter(outcome => outcome.ok).length,
+            failedWithoutEffect: outcomes.filter(outcome => !outcome.ok && outcome.effect === 'none').length,
+            digest: digest(outcomes),
+        });
+        const bytes = Buffer.byteLength(JSON.stringify(summary.sources));
+        assert.ok(bytes < 1500);
+        observedSourceBytes.push(bytes);
+    };
+    const verifyTurn = (before, result) => {
+        for (const { report } of result.contextReports) {
+            assert.ok(report.estimatedInput <= report.availableInput);
+            assert.equal(report.baseReceipt.digest, before.digest);
+            const full = [...before.messages, ...result.messages].slice(0, Math.max(...report.entries.filter(e => e.historyRange).map(e => e.historyRange[1])));
+            assert.equal(report.historyDigest, digest(full));
+            for (const entry of report.entries)
+                if (entry.historyRange)
+                    assert.equal(entry.digest, digest(full.slice(...entry.historyRange)));
+            const serialized = codingProjections.shift();
+            if (serialized)
+                verifySources(serialized, report, full);
+            else
+                assert.ok(report.entries.every(entry => entry.action !== 'summarized'));
+        }
+    };
+    try {
+        await writeFile(path.join(root, 'input.txt'), 'Selected workspace evidence.\n'.repeat(30));
+        const transport = async (_endpoint, init) => {
+            const wire = JSON.parse(init.body);
+            const isSummary = wire.messages[0]?.content.startsWith('Summarize coding-session data');
+            let content, toolCalls;
+            if (isSummary) {
+                summaryCalls++;
+                assert.equal(wire.tools?.length ?? 0, 0);
+                // The adapter adds its own wire overhead, which the JSON-byte fixture does not call tokens.
+                observedSummaryBytes.push(Buffer.byteLength(init.body));
+                content = 'Workspace reads confirmed. Preserve API; never publish. Continue coding from saved original facts.';
+            }
+            else {
+                codingCalls++;
+                codingProjections.push(wire.messages.find((message) => typeof message.content === 'string' && message.content.includes('"contextSummary":'))?.content);
+                assert.ok(wire.messages.some((m) => m.content.includes('Goal: preserve API; never publish')));
+                assert.ok(wire.messages.some((m) => m.role === 'system' && m.content.includes('Trusted project guidance')));
+                for (const message of wire.messages) {
+                    if (typeof message.content !== 'string' || !message.content.includes('"contextSummary":'))
+                        continue;
+                    const summary = JSON.parse(message.content).contextSummary;
+                    assert.equal(summary.trust, 'data');
+                    compressedRequests++;
+                }
+                const last = wire.messages.at(-1);
+                if (last.role === 'user') {
+                    content = 'Read the explicitly selected file.';
+                    toolCalls = [{ id: `read-${codingCalls}`, type: 'function',
+                            function: { name: 'read', arguments: '{"path":"input.txt"}' } }];
+                }
+                else {
+                    assert.equal(last.role, 'tool');
+                    assert.equal(JSON.parse(last.content).ok, true);
+                    content = 'Read confirmed; detailed intermediate progress. '.repeat(65);
+                }
+            }
+            return new Response(JSON.stringify({ choices: [{ index: 0,
+                        finish_reason: toolCalls ? 'tool_calls' : 'stop',
+                        message: { role: 'assistant', content, ...(toolCalls ? { tool_calls: toolCalls } : {}) },
+                    }] }));
+        };
+        const gateway = createModelGateway({ endpoint: 'https://offline.invalid/chat', model: 'fixture',
+            account: { kind: 'none' }, transport });
+        const compressor = createProviderCompressor({ id: 'provider-summary-v1', provider: gateway,
+            budget: { capacity: 6500, reserveOutput: 500 }, maxSummaryBytes: 500, maxCalls: 32 });
+        const context = createContextBuilder({ compressor, sources: [{ id: 'explicit-guide', async load() {
+                        return [{ id: 'guide', kind: 'guidance', content: 'Trusted project guidance: bounded edits only.',
+                                source: 'demo-guide', revision: 'v1', required: true }];
+                    } }] });
+        const tools = createTextTools({ root }).filter(t => t.definition.name === 'read');
+        const budget = { capacity: 14_000, reserveOutput: 1000, reserveTools: 500 };
+        const filename = path.join(root, 'sessions.sqlite');
+        store = createSessionStore(createSqliteSessionBackend(filename));
+        await store.create(sessionId);
+        owner = createExecutionOwner({ store, maxSteps: 2,
+            context: { builder: context, budget, tools: tools.map(t => t.definition) },
+            agent: recording => createAgent({ tools, recorder: recording, provider: gateway,
+                contextBuilder: context, contextBudget: budget }),
+        });
+        for (let i = 0; i < 8; i++) {
+            const before = await store.load(sessionId);
+            await owner.submit(sessionId, i === 0 ? 'Goal: preserve API; never publish' : `Continue coding: ${i}`);
+            const result = (await owner.settle(sessionId)).result;
+            assert.equal(result.reason, 'completed', result.error?.message);
+            const saved = await store.load(sessionId);
+            assert.deepEqual(saved.document.events.slice(0, before.document.events.length), before.document.events);
+            assert.deepEqual(saved.messages.slice(0, before.messages.length), before.messages);
+            assert.equal(saved.recovery.disposition, 'ready');
+            verifyTurn(before, result);
+        }
+        const beforeManual = await store.load(sessionId);
+        const manual = await owner.compact(sessionId);
+        assert.ok(manual.report.entries.some(e => e.action === 'summarized'));
+        const manualSummary = manual.request.messages.flatMap(message => 'content' in message && message.content.includes('"contextSummary":') ? [message.content] : [])[0];
+        assert.ok(manualSummary);
+        verifySources(manualSummary, manual.report, beforeManual.messages);
+        assert.deepEqual(await store.load(sessionId), beforeManual);
+        await owner.submit(sessionId, 'Continue after manual compact');
+        const continued = (await owner.settle(sessionId)).result;
+        assert.equal(continued.reason, 'completed');
+        verifyTurn(beforeManual, continued);
+        assert.equal(codingProjections.length, 0);
+        const saved = await store.load(sessionId);
+        assert.equal(saved.recovery.calls.length, 9);
+        assert.ok(saved.recovery.calls.every(c => c.status === 'settled' && c.outcome?.ok));
+        assert.ok(summaryCalls >= 2);
+        assert.ok(compressedRequests >= 2);
+        await owner.close();
+        await store.close();
+        store = createSessionStore(createSqliteSessionBackend(filename));
+        assert.equal((await store.load(sessionId)).digest, saved.digest);
+        return { turns: 9, summaryCalls, compressedRequests, codingCalls, verifiedToolPairs: 9,
+            immutableHistory: true, provenanceVerified: true, sqliteRestartVerified: true,
+            largestSummaryWireBytes: Math.max(...observedSummaryBytes),
+            largestSourceMetadataBytes: Math.max(...observedSourceBytes),
+            validation: 'offline fixture responses; not real-model summary quality' };
+    }
+    finally {
+        await owner?.close();
+        await store?.close();
+        await rm(root, { recursive: true, force: true });
+    }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url))
+    console.log(JSON.stringify(await runCompactionDemo(), null, 2));

package/dist/nativeAgent/composition.js

@@ -0,0 +1,71 @@
+import { createModelObservationAdapter } from './model/index.js';
+/** Live display fanout with no retained body or durable cursor. UI consumers
+ * own bounded buffering; final messages always come from the Session store. */
+export function createInteractionProgress() {
+    const listeners = new Set();
+    return {
+        observe(event) {
+            if (event.data.type !== 'text_delta')
+                return;
+            for (const listener of listeners) {
+                try {
+                    void Promise.resolve(listener({ sessionId: event.sessionId, turnId: event.turnId, text: event.data.text })).catch(() => { });
+                }
+                catch { /* Display cannot reject model execution. */ }
+            }
+        },
+        subscribe(listener) {
+            if (listeners.size >= 32)
+                throw new Error('Progress subscriber limit reached');
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+    };
+}
+/** Connect actual model evidence; never synthesize starts, usage or AgentEvent sequences. */
+export function connectModelObservations(observer, display) {
+    return createModelObservationAdapter({
+        display(event) {
+            if (event.data.type === 'text_delta')
+                observer.observeStream({ ...event, text: event.data.text }, event.source);
+            display?.(event);
+        },
+        diagnostics(event) {
+            const { sessionId, turnId, step, requestId, attempt, source, data } = event;
+            const identity = { sessionId, turnId, step, requestId, attempt };
+            if (data.type === 'retry') {
+                observer.observeModel({ ...identity, phase: 'retry', retryAfterMs: data.delayMs }, source);
+            }
+            else {
+                const r = data.record;
+                observer.observeModel({
+                    ...identity, phase: 'ended',
+                    status: r.outcome === 'success' ? 'completed' : r.outcome === 'cancelled' ? 'cancelled'
+                        : r.effect === 'unknown' ? 'unknown' : 'error',
+                    ...(r.effect !== 'completed' ? { effect: r.effect } : {}),
+                    ...(r.outcome !== 'success' ? { errorCode: r.outcome } : {}),
+                    ...(r.usage ? { usage: r.usage } : {}),
+                    clientRequestId: r.clientRequestId,
+                    ...(r.providerRequestId ? { providerRequestId: r.providerRequestId } : {}),
+                    ...(r.status === undefined ? {} : { httpStatus: r.status }),
+                    elapsedMs: r.elapsedMs,
+                }, source);
+            }
+        },
+    });
+}
+/** UI offsets are opaque observation cursors, never message or session revisions. */
+export function createInteractionDiagnostics(observer) {
+    return {
+        async query(sessionId, after, limit) {
+            const page = observer.query({ sessionId, after, limit });
+            const metadata = { gap: page.gap, evicted: page.evicted, closed: page.closed };
+            const lines = page.records.map((record, i) => JSON.stringify(i ? record : { ...record, ...metadata }));
+            if (!lines.length)
+                lines.push(JSON.stringify(metadata));
+            return { lines, nextOffset: page.nextCursor < page.throughCursor ? page.nextCursor : null };
+        },
+        async health() { return JSON.stringify(observer.health()); },
+        subscribe(changed) { return observer.subscribe({ export() { changed(); } }); },
+    };
+}

package/dist/nativeAgent/context/budget.js

@@ -0,0 +1,44 @@
+import { ContextBuildError } from './index.js';
+export function validCount(n) {
+    return typeof n === 'number' && Number.isSafeInteger(n) && n >= 0;
+}
+const units = ['tokens', 'bytes', 'custom'];
+const text = (v) => typeof v === 'string' && v.trim().length > 0;
+export function measure(counter, request, capacity) {
+    let measurement;
+    try {
+        measurement = structuredClone(counter.count(request));
+    }
+    catch {
+        throw new ContextBuildError('estimation_failed', `Counter failed: ${counter.id}`);
+    }
+    if (!measurement || measurement.accuracy === 'unknown')
+        throw new ContextBuildError('count_unknown', 'Request count is unknown; no model request admitted');
+    if (!units.includes(measurement.unit) || !text(measurement.source)
+        || !validCount(measurement.value)
+        || !['exact', 'estimated'].includes(measurement.accuracy)
+        || !validCount(measurement.uncertainty)
+        || (measurement.accuracy === 'exact' && measurement.uncertainty !== 0))
+        throw new ContextBuildError('invalid_estimate', 'Count requires units, source, accuracy and explicit uncertainty');
+    if (capacity && (capacity.unit !== measurement.unit || capacity.counterId !== counter.id))
+        throw new ContextBuildError('capacity_mismatch', 'Model capacity and counter units/identity differ');
+    const upper = measurement.value + measurement.uncertainty;
+    if (!validCount(upper))
+        throw new ContextBuildError('invalid_estimate', 'Count plus uncertainty overflows');
+    return { measurement, upper };
+}
+export function budgetBounds(budget, model) {
+    if (!budget || typeof budget !== 'object')
+        throw new ContextBuildError('invalid_budget', 'An explicit capacity and reserve budget is required');
+    const capacity = model?.contextWindow ?? budget.capacity;
+    const reserveTools = budget.reserveTools ?? 0, safetyMargin = budget.safetyMargin ?? 0;
+    const reserve = budget.reserveOutput + reserveTools + safetyMargin;
+    if (![capacity, budget.capacity, budget.reserveOutput, reserveTools, safetyMargin, reserve].every(validCount)
+        || capacity === 0 || reserve > capacity)
+        throw new ContextBuildError('invalid_budget', 'Invalid capacity or output/tool/safety reservations');
+    if (model && (!text(model.model) || !text(model.revision) || !text(model.counterId)
+        || !units.includes(model.unit) || (model.maxOutput !== undefined
+        && (!validCount(model.maxOutput) || budget.reserveOutput > model.maxOutput))))
+        throw new ContextBuildError('capacity_mismatch', 'Invalid model capability or output reservation exceeds supported output');
+    return { capacity, reserveOutput: budget.reserveOutput, reserveTools, safetyMargin, availableInput: capacity - reserve };
+}

package/dist/nativeAgent/context/index.js

@@ -0,0 +1,339 @@
+import { createHash } from 'node:crypto';
+import { history, limits, size } from '../validation.js';
+import { budgetBounds, measure, validCount } from './budget.js';
+export { createProviderCompressor } from './providerCompressor.js';
+export class ContextBuildError extends Error {
+    code;
+    report;
+    recovery;
+    constructor(code, message, report) {
+        const recovery = code === 'cancelled' ? 'Wait for started summarization to settle; retry explicitly from saved history.'
+            : ['storage_failed', 'session_recovery_required', 'history_changed'].includes(code)
+                ? 'Inspect the exact SessionStore receipt, unsettled effects and original failure; reload/reconcile saved facts without replaying tools.'
+                : code === 'byte_budget_exceeded'
+                    ? 'Reduce the projected request or use a smaller summary; the independent kernel byte ceiling cannot be raised by model capacity.'
+                    : ['count_unknown', 'capacity_mismatch', 'capacity_changed', 'invalid_estimate', 'estimation_failed', 'capacity_failed'].includes(code)
+                        ? 'Refresh model capability and supply a matching complete-request counter with explicit uncertainty; rebuild.'
+                        : ['budget_exceeded', 'summary_input_exceeded', 'summary_budget_exhausted', 'compression_no_gain'].includes(code)
+                            ? 'Inspect retained anchors and tool groups; choose a larger authorized capacity or a bounded summary strategy. Do not truncate or replay tools.'
+                            : 'Inspect the failed source/compressor and authoritative history; correct it and explicitly rebuild. No projection or tool replay was installed.';
+        super(`${code}: ${message}. ${recovery}`);
+        this.code = code;
+        this.report = report;
+        this.recovery = recovery;
+    }
+}
+function frozen(value) {
+    const copy = structuredClone(value);
+    function freeze(item) {
+        if (item && typeof item === 'object') {
+            Object.values(item).forEach(freeze);
+            Object.freeze(item);
+        }
+    }
+    freeze(copy);
+    return copy;
+}
+function fail(code, message) { throw new ContextBuildError(code, message); }
+function cancelled(signal) {
+    if (signal.aborted)
+        fail('cancelled', 'Context construction cancelled; no request produced');
+}
+const count = validCount;
+function nonempty(value) { return typeof value === 'string' && value.trim().length > 0; }
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+/** Deterministic approximation, not a provider tokenizer. Budgets are UTF-8 JSON bytes. */
+export const jsonByteEstimator = Object.freeze({
+    id: 'utf8-json-bytes',
+    estimate: (request) => Buffer.byteLength(JSON.stringify(request), 'utf8'),
+});
+function historyUnits(request, keep, ranges) {
+    const messages = request.messages;
+    try {
+        history(messages, Infinity);
+    }
+    catch {
+        fail('invalid_history', 'Source history must contain valid, bounded messages and complete tool batches');
+    }
+    const historyRevision = `sha256:${digest(messages)}`;
+    const units = [];
+    const used = new Set();
+    let latestUser = -1;
+    let firstUser = -1;
+    for (let i = 0; i < messages.length; i++)
+        if (messages[i].role === 'user') {
+            latestUser = i;
+            if (firstUser < 0)
+                firstUser = i;
+        }
+    for (const range of ranges ?? [])
+        if (range.length !== 2 || !count(range[0]) || !count(range[1])
+            || range[0] >= range[1] || range[1] > messages.length)
+            fail('invalid_history', 'Protected history ranges must be valid original [start,end) bounds');
+    for (let i = 0; i < messages.length;) {
+        const start = i;
+        const m = messages[i++];
+        if (!m || !['system', 'user', 'assistant'].includes(m.role) || !('content' in m)
+            || typeof m.content !== 'string')
+            fail('invalid_history', 'Unexpected or unpaired history message');
+        if (m.role === 'assistant') {
+            if (!Array.isArray(m.toolCalls))
+                fail('invalid_history', 'Missing assistant tool calls');
+            const pending = new Map();
+            for (const call of m.toolCalls) {
+                if (!nonempty(call.id) || !nonempty(call.name) || used.has(call.id))
+                    fail('invalid_history', 'Duplicate or invalid tool call identity');
+                used.add(call.id);
+                pending.set(call.id, call.name);
+            }
+            while (pending.size) {
+                const result = messages[i++];
+                if (!result || result.role !== 'tool' || !pending.has(result.toolCallId)
+                    || pending.get(result.toolCallId) !== result.name || !result.outcome
+                    || (result.outcome.ok !== true && result.outcome.ok !== false))
+                    fail('invalid_history', 'Tool batch requires exactly one matching result per call');
+                pending.delete(result.toolCallId);
+                if (!result.outcome.ok && result.outcome.error.effect === 'unknown')
+                    fail('unresolved_effect', 'Unknown tool effects must be reconciled in authoritative history before projection');
+            }
+        }
+        const required = m.role === 'system' || start === firstUser || (latestUser >= 0 && start >= latestUser)
+            || (ranges ?? []).some(([a, b]) => a < i && b > start);
+        units.push({ messages: messages.slice(start, i), required, entry: {
+                source: `session:${request.sessionId}`, revision: historyRevision,
+                digest: digest(messages.slice(start, i)),
+                ...(m.role === 'assistant' && m.toolCalls.length ? { toolOutcomes: messages.slice(start + 1, i).map(result => {
+                        const tool = result;
+                        return { toolCallId: tool.toolCallId, name: tool.name, ok: tool.outcome.ok,
+                            ...(!tool.outcome.ok ? { errorCode: tool.outcome.error.code, effect: tool.outcome.error.effect } : {}) };
+                    }) } : {}),
+                historyRange: [start, i], action: 'retained', reason: required ? 'system-or-current-input' : 'within-budget',
+            } });
+    }
+    for (const unit of units.slice(Math.max(0, units.length - keep))) {
+        unit.required = true;
+        unit.entry.reason = 'recent-group';
+    }
+    return units;
+}
+/** Model-facing commitments, not a second history or an enumeration of old groups.
+ * Exact selected ranges/material identities/outcomes remain in this build's report. */
+function summarySources(entries, messages) {
+    const provenance = entries.map(({ action: _action, reason: _reason, ...entry }) => entry);
+    const historical = entries.filter(entry => entry.historyRange);
+    const materials = provenance.filter(entry => !entry.historyRange);
+    const outcomes = entries.flatMap(entry => entry.toolOutcomes ?? []);
+    const historyRange = historical.length
+        ? [historical[0].historyRange[0], historical.at(-1).historyRange[1]] : undefined;
+    return {
+        representation: 'aggregate', details: 'report.entries', groups: entries.length,
+        provenanceDigest: digest(provenance),
+        ...(historyRange ? { history: {
+                // Protected groups can leave holes: this commits the enclosing original
+                // span, while provenanceDigest binds the exact selected groups in report.
+                rangeKind: 'enclosing', historyRange, digest: digest(messages.slice(...historyRange)),
+                groups: historical.length,
+            } } : {}),
+        ...(materials.length ? { materials: { count: materials.length, digest: digest(materials) } } : {}),
+        ...(outcomes.length ? { toolSettlements: {
+                representation: 'aggregate-only',
+                succeeded: outcomes.filter(outcome => outcome.ok).length,
+                failedWithoutEffect: outcomes.filter(outcome => !outcome.ok && outcome.effect === 'none').length,
+                digest: digest(outcomes),
+            } } : {}),
+    };
+}
+export function createContextBuilder(options = {}) {
+    const sources = [...(options.sources ?? [])];
+    const estimator = options.estimator ?? jsonByteEstimator;
+    const compressor = options.compressor;
+    const counter = options.counter ?? {
+        id: estimator.id, count: request => ({ value: estimator.estimate(request),
+            unit: estimator.id === jsonByteEstimator.id ? 'bytes' : 'custom',
+            source: estimator.id, accuracy: estimator.id === jsonByteEstimator.id ? 'exact' : 'estimated', uncertainty: 0 }),
+    };
+    if (options.counter && options.estimator)
+        fail('invalid_options', 'Select a counter or a legacy estimator, not both');
+    // One bounded, disposable projection. Never a transcript, persistent fact or shared Session authority.
+    let cached;
+    if (!nonempty(estimator.id) || !nonempty(counter.id) || (compressor && !nonempty(compressor.id))
+        || (options.capacity && !nonempty(options.capacity.id))
+        || sources.some(s => !nonempty(s.id)) || new Set(sources.map(s => s.id)).size !== sources.length)
+        fail('invalid_options', 'Extensions require nonempty unique source identities');
+    return {
+        discard(sessionId) { if (cached?.sessionId === sessionId)
+            cached = undefined; },
+        async build(input, signal) {
+            cancelled(signal);
+            input = frozen(input);
+            const keep = input.keepRecentGroups ?? 2;
+            if (!count(keep) || (input.mode !== undefined && !['auto', 'manual'].includes(input.mode)))
+                fail('invalid_budget', 'Invalid retention count or projection mode');
+            // Snapshot before the first await; extensions never receive caller-owned history.
+            const request = frozen(input.request);
+            const units = historyUnits(request, keep, input.protectedHistoryRanges);
+            const scope = frozen({ sessionId: request.sessionId, turnId: request.turnId, step: request.step });
+            const baseReceipt = input.baseReceipt && frozen(input.baseReceipt);
+            if (baseReceipt && (baseReceipt.sessionId !== request.sessionId || !count(baseReceipt.revision)
+                || !count(baseReceipt.messageCount) || baseReceipt.messageCount > request.messages.length
+                || !/^[a-f0-9]{64}$/.test(baseReceipt.digest)))
+                fail('invalid_history', 'Invalid stored-prefix receipt');
+            let model;
+            if (options.capacity) {
+                try {
+                    model = frozen(await options.capacity.resolve(scope, signal));
+                }
+                catch {
+                    cancelled(signal);
+                    fail('capacity_failed', `Capacity source failed: ${options.capacity.id}`);
+                }
+                cancelled(signal);
+                if (!model)
+                    fail('capacity_mismatch', 'Capacity source returned no model capability');
+            }
+            const bounds = budgetBounds(input.budget, model);
+            const capability = digest({ model, counter: counter.id });
+            const materials = [];
+            for (const source of sources) {
+                cancelled(signal);
+                let loaded;
+                try {
+                    loaded = frozen(await source.load(scope, signal));
+                }
+                catch {
+                    cancelled(signal);
+                    fail('source_failed', `Context source failed: ${source.id}`);
+                }
+                cancelled(signal);
+                if (!Array.isArray(loaded))
+                    fail('invalid_material', `Invalid source output: ${source.id}`);
+                const ids = new Set();
+                for (const material of loaded) {
+                    if (!material || !nonempty(material.id) || ids.has(material.id) || !nonempty(material.source)
+                        || !nonempty(material.revision) || typeof material.content !== 'string'
+                        || typeof material.required !== 'boolean' || !['guidance', 'file', 'data'].includes(material.kind))
+                        fail('invalid_material', `Invalid material from source: ${source.id}`);
+                    ids.add(material.id);
+                    materials.push({
+                        messages: [{ role: material.kind === 'guidance' ? 'system' : 'user',
+                                content: JSON.stringify({ contextMaterial: { ...material, loader: source.id } }) }],
+                        required: material.required || material.kind === 'guidance',
+                        entry: { source: material.source, revision: material.revision, sourceId: source.id,
+                            digest: digest(material),
+                            materialId: material.id, action: 'retained',
+                            reason: material.required || material.kind === 'guidance' ? 'required-material' : 'within-budget' },
+                    });
+                }
+            }
+            // Required material is not summarized, but its changes still invalidate derived
+            // history summaries. Include selection and order, not only compressible units.
+            const sourceSnapshot = digest({
+                sources: sources.map(source => source.id),
+                materials: materials.map(unit => ({ entry: unit.entry, required: unit.required })),
+            });
+            if (cached?.sessionId === request.sessionId && cached.sourceSnapshot !== sourceSnapshot)
+                cached = undefined;
+            // Material order is explicit; history order remains unchanged.
+            const all = [...materials, ...units];
+            const makeRequest = () => frozen({ ...request, messages: all.flatMap(u => [...u.messages]) });
+            let measurement;
+            const estimate = () => {
+                cancelled(signal);
+                const counted = measure(counter, makeRequest(), model);
+                measurement = counted.measurement;
+                cancelled(signal);
+                return counted.upper;
+            };
+            const { availableInput } = bounds;
+            let estimatedInput = estimate();
+            const historyDigest = digest(request.messages);
+            const report = () => frozen({ estimator: counter.id,
+                ...(compressor ? { compressor: compressor.id } : {}), ...bounds, estimatedInput, measurement,
+                ...(model ? { model, capacitySource: options.capacity.id } : {}), historyDigest, byteInput: size(makeRequest()),
+                ...(baseReceipt ? { baseReceipt } : {}), entries: all.map(u => u.entry) });
+            const candidates = all.filter(u => !u.required);
+            const keys = candidates.map(u => digest({ source: u.entry.source, sourceId: u.entry.sourceId,
+                materialId: u.entry.materialId, revision: u.entry.sourceId ? u.entry.revision : undefined, digest: u.entry.digest }));
+            const reusable = cached?.sessionId === request.sessionId && cached.capability === capability
+                && cached.keys.length <= keys.length && cached.keys.every((key, i) => keys[i] === key);
+            const install = (summary, selected) => {
+                const originals = selected.map(u => u.entry);
+                const summaryDigest = digest(originals.map(e => e.digest));
+                selected[0].messages = [{ role: 'user', content: JSON.stringify({ contextSummary: {
+                                trust: 'data', sessionId: request.sessionId, historyDigest, digest: summaryDigest,
+                                compressor: compressor.id, sources: summarySources(originals, request.messages),
+                                summary,
+                            } }) }];
+                for (const u of selected.slice(1))
+                    u.messages = [];
+                for (const u of selected) {
+                    u.entry.action = 'summarized';
+                    u.entry.reason = 'budget-compression';
+                }
+                estimatedInput = estimate();
+            };
+            const originalEstimate = estimatedInput;
+            let usedCache = 0;
+            let nextCache;
+            if (compressor && reusable && cached.keys.length) {
+                usedCache = cached.keys.length;
+                install(cached.summary, candidates.slice(0, usedCache));
+            }
+            if (estimatedInput > availableInput || (input.mode === 'manual' && candidates.length > usedCache)) {
+                if (compressor && candidates.length) {
+                    cancelled(signal);
+                    let summary;
+                    const groups = candidates.filter(u => u.messages.length).map(u => u.messages);
+                    try {
+                        summary = await compressor.summarize(frozen({
+                            entry: { source: `session:${request.sessionId}`, revision: `sha256:${historyDigest}`,
+                                digest: digest(candidates.map(u => u.entry.digest)), action: 'retained', reason: 'summary-input' },
+                            messages: groups.flatMap(group => [...group]), groups,
+                        }), signal);
+                    }
+                    catch (error) {
+                        cancelled(signal);
+                        if (error instanceof ContextBuildError)
+                            throw error;
+                        const failure = new ContextBuildError('compression_failed', `Context compressor failed: ${compressor.id}`);
+                        failure.cause = error;
+                        throw failure;
+                    }
+                    cancelled(signal);
+                    if (!nonempty(summary))
+                        fail('invalid_summary', 'Compressor must return nonempty plain text');
+                    if (Buffer.byteLength(summary, 'utf8') > 128 * 1024)
+                        fail('invalid_summary', 'Summary exceeds the bounded projection text limit');
+                    install(summary, candidates);
+                    if (estimatedInput >= originalEstimate)
+                        throw new ContextBuildError('compression_no_gain', 'Summary did not reduce the full request', report());
+                    if (estimatedInput <= availableInput)
+                        nextCache = { sessionId: request.sessionId, capability, sourceSnapshot, keys, summary };
+                }
+            }
+            if (estimatedInput > availableInput)
+                throw new ContextBuildError('budget_exceeded', 'Preserved context and request overhead exceed available input budget', report());
+            if (size(makeRequest()) > limits.historyBytes || makeRequest().messages.some(m => size(m) > limits.messageBytes))
+                throw new ContextBuildError('byte_budget_exceeded', 'Projection exceeds the independent request/message byte ceiling', report());
+            // Sources/summarization can await long enough for model selection to change. Do not
+            // publish an old budget conclusion or install its cache under a new capability.
+            if (options.capacity) {
+                let current;
+                try {
+                    current = frozen(await options.capacity.resolve(scope, signal));
+                }
+                catch {
+                    cancelled(signal);
+                    fail('capacity_failed', `Capacity refresh failed: ${options.capacity.id}`);
+                }
+                cancelled(signal);
+                if (digest(current) !== digest(model))
+                    throw new ContextBuildError('capacity_changed', 'Model capability changed while projecting; no request admitted', report());
+            }
+            cancelled(signal);
+            if (nextCache)
+                cached = nextCache;
+            return frozen({ request: makeRequest(), report: report() });
+        },
+    };
+}