maka-agent 0.2.2-dev.92.20261019 → 0.2.2-dev.97.20261024

package/node_modules/@maka/storage/dist/production-session-snapshot.js

@@ -127,6 +127,18 @@ export function createFileSessionSnapshotWorkspacePreparer(options) {
  * unreconciled.
  */
 export async function createFileProductionSessionSnapshotService(options) {
+    // Retain the original adapter's stricter state/config layout contract.
+    await assertProductionRootsSeparate({
+        stateRoot: options.stateRoot,
+        configRoot: options.configRoot,
+    });
+    return createProductionSessionSnapshotService({
+        ...options,
+        sourceRoots: [options.stateRoot, options.configRoot],
+        state: createFileSessionSnapshotStatePreparer(options),
+    });
+}
+export async function createProductionSessionSnapshotService(options) {
     const session = requireProductionSessionSnapshotBinding(options.session);
     assertSessionBundleLimits(options.limits);
     const limits = Object.freeze({ ...options.limits });
@@ -138,17 +150,13 @@ export async function createFileProductionSessionSnapshotService(options) {
     });
     await stagingCleanup.recover();
     await assertProductionRootsSeparate({
-        stateRoot: options.stateRoot,
-        configRoot: options.configRoot,
+        ...Object.fromEntries(options.sourceRoots.map((root, index) => [`source${index}`, root])),
         workspaceRoot: options.workspaceRoot,
         stagingParent: stagingCleanup.stagingParent,
         cleanupStateRoot: options.cleanupStateRoot,
     });
     const stateBudgetsByStagingRoot = new Map();
-    const fileStatePreparer = createFileSessionSnapshotStatePreparer({
-        stateRoot: options.stateRoot,
-        configRoot: options.configRoot,
-    });
+    const fileStatePreparer = options.state;
     const state = {
         async prepareState(input) {
             const identity = await fileStatePreparer.prepareState(input);

package/node_modules/@maka/storage/dist/runtime-event-persistence.js

@@ -47,6 +47,7 @@ export async function openRuntimeEventReadPersistence(input) {
             listSessionInvocationsPage: (sessionId, input) => store.listSessionInvocationsPage(sessionId, input),
             readInvocation: (sessionId, invocationId) => store.readInvocation(sessionId, invocationId),
             readRuntimeEvents: (sessionId, runId) => store.readRuntimeEvents(sessionId, runId),
+            readToolProvenanceEvents: (sessionId, runId, toolCallId, budget) => store.readToolProvenanceEvents(sessionId, runId, toolCallId, budget),
             readRuntimeEventsBounded: (sessionId, runId, budget) => store.readRuntimeEventsBounded(sessionId, runId, budget),
             readImmutableRuntimeEvents: (sessionId, runId) => store.readImmutableRuntimeEvents(sessionId, runId),
             readSessionRuntimeEvents: (sessionId) => store.readSessionRuntimeEvents(sessionId),

package/node_modules/@maka/storage/dist/session-bundle-policy.js

@@ -44,7 +44,7 @@ async function withBundleArtifactWriterLock(stateRoot, lease, operation) {
 }
 import { runWithContextValueMutation } from './context-value-mutation-gate.js';
 import { withOfflineContextSnapshot, copyContextSnapshot, validateContextSnapshot, planContextSnapshotFiles, } from './context-offload-snapshot.js';
-import { CONTEXT_OFFLOAD_DATABASE_NAME, CONTEXT_OFFLOAD_VALUES_DIRECTORY_NAME, } from './sqlite-context-offload-store.js';
+import { CONTEXT_OFFLOAD_DATABASE_NAME, CONTEXT_OFFLOAD_VALUES_DIRECTORY_NAME, SqliteContextOffloadStore, } from './sqlite-context-offload-store.js';
 import { acquireOperationalStateDatabase, inspectOperationalStateSchema, OPERATIONAL_STATE_DATABASE_NAME, OperationalStateMigrationBlockedError, } from './operational-state-store.js';
 import { TERMINAL_RUNTIME_EVENT_SQL } from './runtime-transcript-query.js';
 import { isSafeStorageId } from './storage-id.js';
@@ -169,7 +169,7 @@ export async function planSessionBundleExport(input) {
     };
 }
 export async function exportSessionBundleState(input) {
-    return withOfflineContextSnapshot(input.stateRoot, (contextLocked) => withBundleArtifactWriterLock(input.stateRoot, input.lease, async (stateRoot) => {
+    return withOfflineContextSnapshot(input.stateRoot, (contextLocked) => withBundleArtifactWriterLock(input.stateRoot, input.lease, async (stateRoot) => runWithContextValueMutation(stateRoot, async () => {
         const destinationRoot = resolve(input.destinationRoot);
         await assertDestinationMissing(destinationRoot);
         const stagingRoot = `${destinationRoot}.${process.pid}.${randomUUID()}.tmp`;
@@ -183,7 +183,8 @@ export async function exportSessionBundleState(input) {
             await backupOperationalState(stateRoot, databasePath);
             const plan = await planSessionBundleExport({ ...input, stateRoot, databasePath });
             for (const entry of plan.entries) {
-                if (entry.source === 'context_snapshot' || entry.source === 'filtered_runtime_sqlite') {
+                if (entry.source === 'context_snapshot' ||
+                    entry.source === 'filtered_runtime_sqlite') {
                     continue;
                 }
                 const destination = resolveInside(stagingRoot, entry.relativePath);
@@ -209,7 +210,7 @@ export async function exportSessionBundleState(input) {
             await rm(stagingRoot, { recursive: true, force: true }).catch(() => { });
             throw error;
         }
-    }), input.lease ? { lease: input.lease } : {});
+    })), input.lease ? { lease: input.lease } : {});
 }
 /**
  * Take the private copy the whole export is derived from.
@@ -320,6 +321,20 @@ async function filterBackedUpDatabase(destinationPath, sessionIds, options) {
         for (const row of tables) {
             if (typeof row.name !== 'string' || PORTABLE_GLOBAL_TABLES.has(row.name))
                 continue;
+            if (row.name === EVENT_WAIT_SOURCE_TABLE && !options.omitEventWaits) {
+                // A checkpoint must retain the source throttle/reservation constraining
+                // its waits, not merely their cursors. Select by Session explicitly so
+                // this is independent of SQLite's table iteration order. Unrelated
+                // sources are not part of this checkpoint's closure.
+                database
+                    .prepare(`DELETE FROM ${EVENT_WAIT_SOURCE_TABLE} WHERE source_key NOT IN (
+          SELECT json_array(json_extract(record_json, '$.resource.providerId'),
+            json_extract(record_json, '$.resource.connectionId'))
+          FROM ${EVENT_WAIT_TABLE} WHERE session_id IN (${sessionIds.map(() => '?').join(', ')})
+        )`)
+                    .run(...sessionIds);
+                continue;
+            }
             if (options.omitEventWaits && row.name === EVENT_WAIT_TABLE) {
                 // Keep the schema while leaving root-owned wait authority behind.
                 database.exec(`DELETE FROM ${quoteIdentifier(row.name)}`);
@@ -509,6 +524,7 @@ const LOCAL_SEQUENCE_COLUMNS = new Map([
     ['message_admissions', 'sequence'],
 ]);
 const EVENT_WAIT_TABLE = 'workflow_event_waits';
+const EVENT_WAIT_SOURCE_TABLE = 'workflow_event_wait_source_cooldowns';
 const PORTABLE_GLOBAL_TABLES = new Set([
     'operational_schema_migrations',
     'session_metadata_schema',
@@ -765,17 +781,31 @@ export async function importSessionBundleState(input) {
             // a Session already visible whose bytes never arrived -- and which a
             // retry could not fix, because the ids are now taken.
             const artifacts = await copyBundleArtifacts(bundleStateRoot, stateRoot);
+            let contextRefs;
             try {
-                const contextRefs = await mergeBundleContext(bundleStateRoot, stateRoot, contextLocked, sessionIds);
+                contextRefs = await mergeBundleContext(bundleStateRoot, stateRoot, contextLocked, sessionIds);
                 const inserted = mergeBundleDatabase(lease, bundleDatabasePath);
                 return { sessionIds: inserted, artifactFiles: artifacts.copied, contextRefs };
             }
             catch (error) {
-                // Take back only what this attempt created. Anything already there
-                // belongs to someone else, or to an earlier attempt that the next
-                // one will recognise.
-                for (const path of artifacts.created)
-                    await rm(path, { force: true }).catch(() => { });
+                // A failure after COMMIT (for example while detaching the bundle)
+                // must not remove bytes the published Session now references.
+                try {
+                    const present = lease.database.prepare('SELECT 1 FROM session_metadata WHERE session_id = ?');
+                    const unpublished = sessionIds.filter((id) => present.get(id) === undefined);
+                    if (contextRefs !== undefined && contextRefs > 0) {
+                        await releaseUnpublishedBundleContext(stateRoot, unpublished);
+                    }
+                    for (const path of artifacts.created) {
+                        const artifactPath = relative(resolveInside(stateRoot, 'artifacts'), path);
+                        if (unpublished.some((id) => isArtifactPathForSession(artifactPath, id))) {
+                            await rm(path, { force: true }).catch(() => { });
+                        }
+                    }
+                }
+                catch {
+                    // Preserve the import error if storage also refuses cleanup.
+                }
                 throw error;
             }
         }
@@ -1010,7 +1040,8 @@ export function listSessionBundleMergeTables(target) {
             TRIGGER_MAINTAINED_TABLES.has(name) ||
             // Older bundles and snapshots can contain wait rows. Import is a
             // Session transfer, so it must independently refuse to copy them.
-            name === EVENT_WAIT_TABLE) {
+            name === EVENT_WAIT_TABLE ||
+            name === EVENT_WAIT_SOURCE_TABLE) {
             continue;
         }
         // Mirror the export's own classification instead of trusting that it
@@ -1158,18 +1189,35 @@ async function mergeBundleContextDatabase(bundleContext, stateRoot, sessionIds)
             database.exec('BEGIN IMMEDIATE');
             try {
                 database.exec('INSERT OR IGNORE INTO main.context_blobs SELECT * FROM bundle.context_blobs');
+                // The payload files are already published. Adopt their representation
+                // when the target still holds the same bytes inline after a v2 upgrade,
+                // so retiring the last reference also collects the imported file.
+                database.exec(`
+          UPDATE main.context_blobs AS target
+          SET storage_kind = 'managed_file', payload = source.payload
+          FROM bundle.context_blobs AS source
+          WHERE target.blob_id = source.blob_id
+            AND target.storage_kind = 'inline'
+            AND source.storage_kind = 'managed_file'
+        `);
                 // A retry re-inserts the same rows. Skipping an identical one is what
                 // makes the second attempt work; skipping a DIFFERENT row that happens
                 // to share an id would hide a real collision, so the two are separated.
                 const colliding = database
                     .prepare(`
             SELECT b.ref_id FROM bundle.context_refs b
-            JOIN main.context_refs m USING(ref_id)
-            WHERE m.session_id <> b.session_id OR m.blob_id <> b.blob_id
+            JOIN main.context_refs m ON m.ref_id = b.ref_id OR (
+              m.session_id = b.session_id AND m.owner_kind = b.owner_kind AND m.owner_id = b.owner_id
+            )
+            WHERE m.ref_id <> b.ref_id OR m.session_id <> b.session_id
+              OR m.owner_kind <> b.owner_kind OR m.owner_id <> b.owner_id
+              OR m.blob_id <> b.blob_id OR m.media_type <> b.media_type
+              OR m.created_at <> b.created_at
+            LIMIT 1
           `)
-                    .all();
-                if (colliding.length > 0) {
-                    throw new SessionBundleImportError('conflict', `Context reference already names different content: ${String(colliding[0]?.ref_id)}`);
+                    .get();
+                if (colliding) {
+                    throw new SessionBundleImportError('conflict', `Context reference already names different content: ${colliding.ref_id}`);
                 }
                 database.exec('INSERT OR IGNORE INTO main.context_refs SELECT * FROM bundle.context_refs');
                 // A blob the target already held may have been queued for collection
@@ -1223,6 +1271,28 @@ async function mergeBundleContextDatabase(bundleContext, stateRoot, sessionIds)
     }
     return countContextRefs(targetContext, sessionIds);
 }
+async function releaseUnpublishedBundleContext(stateRoot, sessionIds) {
+    if (sessionIds.length === 0)
+        return;
+    await runWithContextValueMutation(stateRoot, async () => {
+        // Reuse retirement's accounting and GC candidate updates. Retirement does
+        // not add payloads, so it needs no write quota.
+        const store = new SqliteContextOffloadStore(resolveInside(stateRoot, CONTEXT_OFFLOAD_DATABASE_NAME), {
+            limits: {
+                ownerMaxBytes: { read_image_snapshot: 0, tool_result_archive: 0 },
+                sessionLogicalBytes: 0,
+                workspacePhysicalBytes: 0,
+            },
+        });
+        try {
+            for (const sessionId of sessionIds)
+                await store.retireSession(sessionId);
+        }
+        finally {
+            store.close();
+        }
+    });
+}
 /**
  * Copy a managed-payload tree, structure and all.
  *

package/node_modules/@maka/storage/dist/session-checkpoint-publication-store.js

@@ -0,0 +1,204 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeAtomicFile } from './atomic-file-write.js';
+import { readStableBoundedFile } from './stable-storage.js';
+import { withProcessLifetimeFileUpdateLock } from './process-lifetime-file-update-lock.js';
+import { createSessionCheckpointManifestV1, encodeSessionCheckpointManifestV1, SESSION_CHECKPOINT_MANIFEST_MEDIA_TYPE, } from './session-repository.js';
+const MAX_DOCUMENT_BYTES = 4 * 1024 * 1024;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+/**
+ * Host operation recovery facts, NOT a second checkpoint Head. The Repository
+ * remains the only authority for the current revision. Documents are bounded;
+ * receipts are never silently expired to make space.
+ */
+export async function openSessionCheckpointPublicationStore(input) {
+    await mkdir(input.directory, { recursive: true, mode: 0o700 });
+    const authorityPath = join(input.directory, 'authority-v1.json');
+    const agentId = await withProcessLifetimeFileUpdateLock(authorityPath, async () => {
+        const existing = await readOptional(authorityPath);
+        if (existing !== undefined) {
+            if (!record(existing) ||
+                existing.schemaVersion !== 1 ||
+                existing.rootId !== input.rootId ||
+                !identifier(existing.agentId) ||
+                !UUID.test(existing.agentId))
+                throw invalid();
+            return existing.agentId;
+        }
+        const agentId = randomUUID();
+        await writeDocument(authorityPath, { schemaVersion: 1, rootId: input.rootId, agentId });
+        return agentId;
+    });
+    return {
+        async withSession(makaSessionId, operation) {
+            if (!identifier(makaSessionId))
+                throw new TypeError('Invalid checkpoint Session identity');
+            const key = createHash('sha256').update(makaSessionId).digest('hex');
+            const path = join(input.directory, `session-${key}.json`);
+            return withProcessLifetimeFileUpdateLock(path, async () => {
+                const existing = await readOptional(path);
+                const document = existing === undefined
+                    ? {
+                        schemaVersion: 1,
+                        rootId: input.rootId,
+                        binding: { makaSessionId, repositorySessionId: randomUUID(), agentId },
+                        requests: [],
+                    }
+                    : decode(existing, input.rootId, makaSessionId, agentId);
+                const save = async () => {
+                    decode(document, input.rootId, makaSessionId, agentId);
+                    await writeDocument(path, document);
+                };
+                if (existing === undefined)
+                    await save();
+                return operation(document, save);
+            });
+        },
+    };
+}
+function decode(value, rootId, sessionId, agentId) {
+    if (!record(value) ||
+        value.schemaVersion !== 1 ||
+        value.rootId !== rootId ||
+        !record(value.binding) ||
+        value.binding.makaSessionId !== sessionId ||
+        value.binding.agentId !== agentId ||
+        !identifier(value.binding.repositorySessionId) ||
+        !UUID.test(value.binding.repositorySessionId) ||
+        !Array.isArray(value.requests))
+        throw invalid();
+    const ids = new Set();
+    const commits = new Set();
+    let pending = 0;
+    for (const request of value.requests) {
+        if (!record(request) ||
+            !identifier(request.requestId) ||
+            !identifier(request.commitId) ||
+            !UUID.test(request.commitId) ||
+            ids.has(request.requestId) ||
+            commits.has(request.commitId) ||
+            !(request.expectedRevision === null || identifier(request.expectedRevision)) ||
+            !(request.snapshotCleanupPending === undefined || request.snapshotCleanupPending === true) ||
+            !(request.bundleCleanupPending === undefined || request.bundleCleanupPending === true) ||
+            !(request.confirmationGrantId === undefined || identifier(request.confirmationGrantId)))
+            throw invalid();
+        ids.add(request.requestId);
+        commits.add(request.commitId);
+        if (request.phase === 'capturing' || request.phase === 'aborted') {
+            if (request.checkpoint !== undefined || request.result !== undefined)
+                throw invalid();
+            if (request.phase === 'capturing')
+                pending++;
+        }
+        else if (request.phase === 'prepared' ||
+            request.phase === 'conflicted' ||
+            request.phase === 'committed') {
+            assertCheckpoint(request.checkpoint);
+            if (request.phase !== 'committed') {
+                if (request.phase === 'prepared')
+                    pending++;
+                if (request.result !== undefined)
+                    throw invalid();
+            }
+            else {
+                const result = request.result;
+                if (!record(result) ||
+                    !record(result.ref) ||
+                    result.ref.sessionId !== value.binding.repositorySessionId ||
+                    !identifier(result.ref.revision) ||
+                    result.agentId !== agentId ||
+                    result.forkedFrom !== undefined ||
+                    result.lastCommittedActivationId !== undefined)
+                    throw invalid();
+                assertCheckpoint(result.checkpoint);
+                if (JSON.stringify(result.checkpoint) !== JSON.stringify(request.checkpoint))
+                    throw invalid();
+            }
+        }
+        else
+            throw invalid();
+    }
+    if (pending > 1)
+        throw invalid();
+    return value;
+}
+function assertCheckpoint(value) {
+    try {
+        if (!record(value) ||
+            !record(value.value) ||
+            value.value.schemaVersion !== 1 ||
+            !record(value.manifest))
+            throw invalid();
+        const manifest = createSessionCheckpointManifestV1(value.value.compatibilityBundle);
+        const bytes = encodeSessionCheckpointManifestV1(manifest);
+        if (!identifier(value.manifest.objectRef) ||
+            value.manifest.mediaType !== SESSION_CHECKPOINT_MANIFEST_MEDIA_TYPE ||
+            value.manifest.bytes !== bytes.byteLength ||
+            value.manifest.digest !== `sha256:${createHash('sha256').update(bytes).digest('hex')}`)
+            throw invalid();
+    }
+    catch (cause) {
+        throw invalid(cause);
+    }
+}
+async function readOptional(path) {
+    try {
+        const bytes = await readStableBoundedFile({
+            path,
+            maxBytes: MAX_DOCUMENT_BYTES,
+            invalidFile: invalid,
+        });
+        return JSON.parse(bytes.toString('utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+async function writeDocument(path, document) {
+    const bytes = `${JSON.stringify(document)}\n`;
+    // Reserve the duplicated checkpoint plus binding/revision envelope BEFORE
+    // admitting CAS. Otherwise a prepared record near the quota could commit a
+    // Head whose receipt can never fit, permanently blocking reconciliation.
+    const receiptReserve = record(document) && Array.isArray(document.requests)
+        ? document.requests.reduce((total, request) => total +
+            (record(request) && request.phase === 'prepared'
+                ? Buffer.byteLength(JSON.stringify(request.checkpoint)) + 8192
+                : 0), 0)
+        : 0;
+    if (Buffer.byteLength(bytes) + receiptReserve > MAX_DOCUMENT_BYTES)
+        throw new Error('Checkpoint publication journal quota exceeded');
+    await writeAtomicFile(path, bytes, { fileMode: 0o600 });
+}
+function record(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function identifier(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= 512 &&
+        !/[\u0000-\u001f]/u.test(value));
+}
+function invalid(cause) {
+    return new Error('Invalid checkpoint publication recovery record', cause === undefined ? undefined : { cause });
+}

package/node_modules/@maka/storage/dist/snapshot-operation-gate.js

@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Normal operations remain concurrent; an explicit snapshot drains and fences them. */
+export class SnapshotOperationGate {
+    #active = new Set();
+    #context = new AsyncLocalStorage();
+    #barrier;
+    run(operation) {
+        if (this.#context.getStore()?.active)
+            return operation();
+        const barrier = this.#barrier;
+        const task = barrier ? barrier.then(operation) : operation();
+        return this.#track(task);
+    }
+    exclusive(operation) {
+        if (this.#context.getStore()?.active) {
+            return Promise.reject(new Error('Cannot nest an execution snapshot boundary'));
+        }
+        // Register the barrier synchronously, before draining existing operations.
+        const previous = [...this.#active];
+        const precedingBarrier = this.#barrier;
+        let release;
+        const barrier = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.#barrier = barrier;
+        const task = (async () => {
+            await precedingBarrier;
+            await Promise.allSettled(previous);
+            const context = { active: true };
+            try {
+                return await this.#context.run(context, operation);
+            }
+            finally {
+                context.active = false;
+                release();
+                if (this.#barrier === barrier)
+                    this.#barrier = undefined;
+            }
+        })();
+        return this.#track(task);
+    }
+    #track(task) {
+        this.#active.add(task);
+        void task.finally(() => this.#active.delete(task)).catch(() => { });
+        return task;
+    }
+}

package/node_modules/@maka/storage/dist/sqlite-context-offload-schema.js

@@ -222,7 +222,7 @@ export function migrateSqliteContextOffloadDatabase(db) {
         throw newerSchemaError(observedVersion);
     }
     if (observedVersion === SQLITE_CONTEXT_OFFLOAD_SCHEMA_VERSION) {
-        validateSchema(db);
+        validateSqliteContextOffloadSchema(db);
         return;
     }
     db.exec('BEGIN IMMEDIATE');
@@ -248,7 +248,7 @@ export function migrateSqliteContextOffloadDatabase(db) {
             db.exec(`PRAGMA user_version = ${SQLITE_CONTEXT_OFFLOAD_SCHEMA_VERSION}`);
             current = SQLITE_CONTEXT_OFFLOAD_SCHEMA_VERSION;
         }
-        validateSchema(db);
+        validateSqliteContextOffloadSchema(db);
         db.exec('COMMIT');
     }
     catch (error) {
@@ -264,7 +264,7 @@ export function readSqliteContextOffloadSchemaVersion(db) {
     }
     return value;
 }
-function validateSchema(db) {
+export function validateSqliteContextOffloadSchema(db) {
     const autoVacuum = db.prepare('PRAGMA auto_vacuum').get();
     if (autoVacuum?.auto_vacuum !== 2) {
         throw new Error('Incomplete context-offload SQLite schema: incremental auto-vacuum required');

package/node_modules/@maka/storage/dist/sqlite-context-offload-store.js

@@ -25,6 +25,7 @@ import { CONTEXT_OFFLOAD_ID_MAX_CODE_POINTS, } from '@maka/core/context-offload'
 import { configureSqliteContextOffloadDatabase, migrateSqliteContextOffloadDatabase, } from './sqlite-context-offload-schema.js';
 import { readStableBoundedFile, syncDirectory, syncDirectoryChain, syncFile, } from './stable-storage.js';
 import { runWithContextValueMutation } from './context-value-mutation-gate.js';
+import { SqliteReclamationCheckpoint } from './sqlite-reclamation-checkpoint.js';
 const MAX_MEDIA_TYPE_CODE_POINTS = 256;
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 const MANAGED_FILE_LOCATOR_PATTERN = /^sha256\/([0-9a-f]{2})\/([0-9a-f]{64})$/;
@@ -42,6 +43,7 @@ export class SqliteContextOffloadStore {
     #storageRoot;
     #valueRoot;
     #mutationGateKey;
+    #reclamationCheckpoint = new SqliteReclamationCheckpoint();
     #closed = false;
     constructor(path, options) {
         if (!path)
@@ -359,6 +361,7 @@ export class SqliteContextOffloadStore {
         this.#assertOpen();
         // Probe under a read transaction so an idle tick never takes the write lock.
         if (this.#readTransaction(() => this.#freelistPages()) === 0) {
+            this.#reclamationCheckpoint.run(this.#database, 0);
             return { reclaimedPages: 0, hasMore: false };
         }
         const result = this.#writeTransaction(() => {
@@ -372,8 +375,7 @@ export class SqliteContextOffloadStore {
             return { reclaimedPages: before - after, hasMore: after > 0 && after < before };
         });
         // PASSIVE never waits on readers; it moves the shrink into the main file.
-        if (result.reclaimedPages > 0)
-            this.#database.exec('PRAGMA wal_checkpoint(PASSIVE)');
+        this.#reclamationCheckpoint.run(this.#database, result.reclaimedPages);
         return result;
     }
     #freelistPages() {

package/node_modules/@maka/storage/dist/sqlite-reclamation-checkpoint.js

@@ -0,0 +1,37 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/** Retains an unfinished reclamation checkpoint across idle maintenance ticks. */
+export class SqliteReclamationCheckpoint {
+    #pending = false;
+    run(database, reclaimedPages) {
+        if (reclaimedPages > 0)
+            this.#pending = true;
+        if (!this.#pending)
+            return;
+        // Call outside transactions. PASSIVE never waits for a reader or writer;
+        // completion affects the next idle tick, not the maintenance lane's hasMore.
+        const row = database.prepare('PRAGMA wal_checkpoint(PASSIVE)').get();
+        if (typeof row?.busy !== 'number' ||
+            typeof row.log !== 'number' ||
+            typeof row.checkpointed !== 'number') {
+            throw new Error('Invalid SQLite wal_checkpoint result');
+        }
+        this.#pending = row.busy !== 0 || row.checkpointed < row.log;
+    }
+}

package/node_modules/@maka/storage/dist/sqlite-runtime-store.js

@@ -984,6 +984,37 @@ export class SqliteRuntimeStore {
         }
         return true;
     }
+    async readToolProvenanceEvents(sessionId, runId, toolCallId, budget) {
+        assertEvidenceReadBudget(budget);
+        assertRuntimeStorageSafeId(sessionId, 'Invalid session id');
+        assertRuntimeStorageSafeId(runId, 'Invalid run id');
+        return this.readTransaction(() => {
+            // Select immutable call/T1/T2 facts only. Unrelated output never consumes the
+            // proof budget, and sizes are checked before payloads cross into JavaScript.
+            const predicate = `session_id = ? AND run_id = ? AND (
+      json_extract(payload_json, '$.content.id') = ? OR
+      json_extract(payload_json, '$.refs.toolCallId') = ? OR
+      json_extract(payload_json, '$.actions.toolDispatch.providerToolCallId') = ?
+    )`;
+            const parameters = [sessionId, runId, toolCallId, toolCallId, toolCallId];
+            const rows = this.db
+                .prepare(`SELECT length(CAST(payload_json AS BLOB)) AS stored_bytes
+      FROM runtime_events WHERE ${predicate} ORDER BY event_seq, event_id LIMIT ?`)
+                .all(...parameters, budget.maxRecords + 1);
+            const measurement = measureEvidenceRows(rows, budget, 'Invalid tool provenance measurement');
+            if (!measurement)
+                return { status: 'limit_exceeded' };
+            const facts = this.db
+                .prepare(`SELECT event_id, session_id, invocation_id, run_id, turn_id, payload_json
+      FROM runtime_events WHERE ${predicate} ORDER BY event_seq, event_id LIMIT ?`)
+                .all(...parameters, budget.maxRecords + 1);
+            return {
+                status: 'complete',
+                records: facts.map(decodeRuntimeEventStorageRow),
+                ...measurement,
+            };
+        });
+    }
     async readRuntimeEventsBounded(sessionId, runId, budget) {
         assertEvidenceReadBudget(budget);
         const rows = this.db

package/node_modules/@maka/storage/package.json

@@ -44,6 +44,9 @@
     "./scheduled-task-store": "./dist/scheduled-task-store.js",
     "./quiescent-session-snapshot": "./dist/quiescent-session-snapshot.js",
     "./production-session-snapshot": "./dist/production-session-snapshot.js",
+    "./session-repository": "./dist/session-repository.js",
+    "./file-session-repository": "./dist/file-session-repository.js",
+    "./session-checkpoint-publication-store": "./dist/session-checkpoint-publication-store.js",
     "./session-bundle-contract": "./dist/session-bundle-contract.js",
     "./session-bundle-file-service": "./dist/session-bundle-file-service.js",
     "./session-bundle-policy": "./dist/session-bundle-policy.js",