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

package/node_modules/@maka/runtime-host/dist/server/session-checkpoint-publication.js

@@ -0,0 +1,250 @@
+/*
+ * 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 { mkdir, realpath, rm } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { SessionConfigurationTransitionError } from '@maka/runtime/session-manager';
+import { openFileSessionRepository } from '@maka/storage/file-session-repository';
+import { openSessionCheckpointPublicationStore } from '@maka/storage/session-checkpoint-publication-store';
+import { acquireProcessLifetimeOwner } from '@maka/storage/process-lifetime-owner';
+import { runWithStorageRootLease } from '@maka/storage/root-authority';
+import { assertSessionBundleLimits, } from '@maka/storage/session-bundle-contract';
+import { createProductionSessionSnapshotService } from '@maka/storage/production-session-snapshot';
+import { createFileSessionSnapshotStagingCleanupAuthority, } from '@maka/storage/quiescent-session-snapshot';
+import { HostCheckpointError, HostSessionCheckpointCoordinator, } from './session-checkpoint-coordinator.js';
+/** Trusted service capability; no protocol endpoint or model tool is added by PR2. */
+export async function createHostSessionCheckpointPublication(input) {
+    const { context, stores, options } = input;
+    if (!options)
+        return unavailable('Checkpoint publication is not configured');
+    if (!stores.snapshot)
+        return unavailable('Selected execution persistence does not support checkpoints');
+    if (!options.workspace || typeof options.workspace.runExclusive !== 'function') {
+        return unavailable('A trusted workspace snapshot authority is required');
+    }
+    if (process.platform === 'win32' && !options.privateStagingRootAuthority) {
+        return unavailable('Checkpoint staging requires a Windows ACL verification authority');
+    }
+    assertSessionBundleLimits(options.limits);
+    // Freeze caller policy at composition, not midway through a publication.
+    const limits = Object.freeze({ ...options.limits });
+    let owner;
+    try {
+        if (!options.directory || !isAbsolute(options.directory)) {
+            throw new Error('Checkpoint directory must be an explicit absolute durable path');
+        }
+        const root = await canonicalPlannedDirectory(options.directory);
+        for (const source of [context.owner.capability.canonicalPath, context.owner.controlDirectory]) {
+            assertDisjoint(root, await canonicalPlannedDirectory(source));
+        }
+        const stagingParent = join(root, 'staging');
+        const cleanupStateRoot = join(root, 'cleanup');
+        const bundlesRoot = join(root, 'bundles');
+        await Promise.all([stagingParent, cleanupStateRoot, bundlesRoot].map((path) => mkdir(path, { recursive: true, mode: 0o700 })));
+        const cleanupOwner = await acquireProcessLifetimeOwner(cleanupStateRoot);
+        owner = cleanupOwner;
+        // Validate durable Root binding before recovering anything owned by an earlier process.
+        const journal = await openSessionCheckpointPublicationStore({
+            directory: join(root, 'operations'),
+            rootId: context.owner.lease.rootId,
+        });
+        // Recover crashed owners before exposing publication, even when this Host
+        // never captures again or only replays an already committed receipt.
+        const recovery = await createFileSessionSnapshotStagingCleanupAuthority({
+            cleanupStateRoot,
+            stagingParent,
+            processLifetimeOwner: cleanupOwner,
+            privateStagingRootAuthority: options.privateStagingRootAuthority,
+        }).recover();
+        if (recovery.failed.length > 0) {
+            throw new AggregateError(recovery.failed.map(({ error }) => error), 'Checkpoint staging recovery failed');
+        }
+        const repository = await openFileSessionRepository({ storageRoot: join(root, 'repository') });
+        const coordinator = new HostSessionCheckpointCoordinator({
+            journal,
+            repository,
+            objects: repository.objectStore,
+            runAuthorized: (operation) => runWithStorageRootLease(context.owner.lease, 'interactive', 'write', async () => {
+                const residency = context.acquireResidency('session-checkpoint');
+                try {
+                    return await operation();
+                }
+                finally {
+                    residency.release();
+                }
+            }),
+            cleanupBundle: async (commitId) => {
+                // This UUID was validated in the journal; never remove a caller path.
+                if (!/^[0-9a-f-]{36}$/u.test(commitId))
+                    throw new Error('Invalid checkpoint bundle identity');
+                await rm(join(bundlesRoot, `${commitId}.tar.zst`), { force: true });
+            },
+            capture: async (request) => {
+                const sessionId = request.binding.makaSessionId;
+                const header = await stores.sessionStore.readHeader(sessionId);
+                if (!header.cwd)
+                    throw new HostCheckpointError('unsupported', 'Session has no snapshot-capable workspace');
+                const workspaceRoot = await realpath(header.cwd);
+                assertDisjoint(root, workspaceRoot);
+                let statePreparer;
+                const service = await createProductionSessionSnapshotService({
+                    session: {
+                        makaSessionId: sessionId,
+                        cloudSessionId: request.binding.repositorySessionId,
+                    },
+                    sourceRoots: [context.owner.capability.canonicalPath],
+                    state: {
+                        prepareState: (stateInput) => {
+                            if (!statePreparer)
+                                throw new Error('Snapshot state requested outside its provider boundary');
+                            return statePreparer.prepareState(stateInput);
+                        },
+                    },
+                    workspaceRoot,
+                    stagingParent,
+                    cleanupStateRoot,
+                    processLifetimeOwner: cleanupOwner,
+                    limits,
+                    privateStagingRootAuthority: options.privateStagingRootAuthority,
+                    confirmationAuthority: options.confirmationAuthority,
+                    quiescence: {
+                        runQuiescent: (snapshotInput, operation) => input.admission.run(sessionId, async () => {
+                            snapshotInput.cancellation.signal.throwIfAborted();
+                            try {
+                                return await input.manager.runSessionSubtreeQuiescentMutation(sessionId, async (sessionIds) => {
+                                    if (sessionIds.length !== 1)
+                                        throw new HostCheckpointError('unsupported', 'Linked Session snapshot closure is not supported yet');
+                                    return stores.snapshot.runExclusive(async (state) => {
+                                        snapshotInput.cancellation.signal.throwIfAborted();
+                                        const current = await stores.sessionStore.readHeaderSnapshot(sessionId);
+                                        if (!current.cwd || (await realpath(current.cwd)) !== workspaceRoot) {
+                                            throw new HostCheckpointError('conflict', 'Session workspace changed before capture');
+                                        }
+                                        if (current.role !== undefined ||
+                                            current.subagentParent ||
+                                            current.conversationCopy?.state === 'preparing') {
+                                            throw new HostCheckpointError('unsupported', 'Session kind is not supported for checkpoint publication');
+                                        }
+                                        const [pending, operations, approvals, boundaries, shells, sessions] = await Promise.all([
+                                            stores.sessionStore.listMessageAdmissions(sessionId),
+                                            stores.runtimeEventStore.listUnsettledToolOperations(sessionId),
+                                            stores.interactionStore.listPending({ sessionId }),
+                                            stores.sessionStore.listPendingSandboxBoundaryRequests(sessionId),
+                                            input.shellRuns.listSessionShellRuns(sessionId),
+                                            stores.sessionStore.listForRecovery(),
+                                        ]);
+                                        if (!input.isSessionIdle(sessionId) ||
+                                            pending.length ||
+                                            operations.length ||
+                                            approvals.length ||
+                                            boundaries.length ||
+                                            shells.some((shell) => shell.status === 'starting' ||
+                                                shell.status === 'running' ||
+                                                shell.status === 'orphaned')) {
+                                            throw new HostCheckpointError('busy', 'Session has pending execution or external work');
+                                        }
+                                        for (const other of sessions) {
+                                            if (other.id !== sessionId &&
+                                                other.cwd &&
+                                                (await realpath(other.cwd).catch(() => undefined)) === workspaceRoot) {
+                                                throw new HostCheckpointError('unsupported', 'Shared workspaces require a multi-Session snapshot boundary');
+                                            }
+                                        }
+                                        return options.workspace.runExclusive({ sessionId, workspaceRoot, cancellation: snapshotInput.cancellation }, async () => {
+                                            snapshotInput.cancellation.signal.throwIfAborted();
+                                            statePreparer = state;
+                                            try {
+                                                return await operation();
+                                            }
+                                            finally {
+                                                statePreparer = undefined;
+                                            }
+                                        });
+                                    });
+                                });
+                            }
+                            catch (error) {
+                                if (error instanceof SessionConfigurationTransitionError &&
+                                    error.code === 'session_busy') {
+                                    throw new HostCheckpointError('busy', 'Session has an active Runtime execution', { cause: error });
+                                }
+                                throw error;
+                            }
+                        }),
+                    },
+                });
+                return service.pack({
+                    destination: join(bundlesRoot, `${request.commitId}.tar.zst`),
+                    confirmationGrantId: request.confirmationGrantId,
+                    signal: request.signal,
+                    deadlineAt: request.deadlineAt,
+                });
+            },
+        });
+        let close;
+        return {
+            publish: (request) => coordinator.publish(request),
+            beginDrain: () => coordinator.beginDrain(),
+            close: () => (close ??= (async () => {
+                await coordinator.close();
+                await cleanupOwner.close();
+            })()),
+        };
+    }
+    catch (error) {
+        await owner?.close();
+        // Optional checkpoint metadata must not prevent live-state recovery. Fail
+        // this capability closed and retain the cause for the trusted caller.
+        return unavailable('Checkpoint publication initialization failed', 'publication_failed', error);
+    }
+}
+// Resolve existing ancestors too: an apparently separate path through a symlink
+// must not place checkpoint state inside the live Root or disposable control tree.
+async function canonicalPlannedDirectory(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || dirname(path) === path)
+            throw error;
+        return join(await canonicalPlannedDirectory(dirname(path)), basename(path));
+    }
+}
+function assertDisjoint(left, right) {
+    const contains = (parent, child) => {
+        const path = relative(parent, child);
+        return path === '' || (!isAbsolute(path) && path !== '..' && !path.startsWith(`..${sep}`));
+    };
+    if (contains(left, right) || contains(right, left)) {
+        throw new Error('Checkpoint directory must not overlap live state, control or workspace roots');
+    }
+}
+function unavailable(message, code = 'unsupported', cause) {
+    let closed = false;
+    return {
+        publish: async () => {
+            throw new HostCheckpointError(closed ? 'closed' : code, message, { cause });
+        },
+        beginDrain: () => {
+            closed = true;
+        },
+        close: async () => {
+            closed = true;
+        },
+    };
+}

package/node_modules/@maka/runtime-host/dist/server/shell-run-event-wait-access.js

@@ -0,0 +1,166 @@
+/*
+ * 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 { validateToolLedgerEventLane } from '@maka/core/tool-ledger-scanner';
+import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
+import { parseShellRunResourceRef } from '@maka/runtime/shell-run-contract';
+export const SHELL_RUN_WAIT_SOURCE = Object.freeze({
+    providerId: 'shell_run',
+    resourceType: 'background_task',
+    conditionType: 'terminal',
+    conditionVersion: 1,
+});
+export function validateShellRunWait(wait) {
+    const target = parseShellRunResourceRef(wait.resource.resourceId);
+    if (!target ||
+        wait.resource.providerId !== SHELL_RUN_WAIT_SOURCE.providerId ||
+        wait.resource.resourceType !== SHELL_RUN_WAIT_SOURCE.resourceType ||
+        wait.resource.connectionId !== null ||
+        wait.condition.typeId !== SHELL_RUN_WAIT_SOURCE.conditionType ||
+        wait.condition.version !== 1 ||
+        Object.keys(wait.condition.parameters).length !== 0)
+        throw new TypeError('Unsupported background task condition');
+    return target.shellRunId;
+}
+/** Reads the same Host's stores. Neither a reference nor the wait is an access credential. */
+export class ShellRunEventWaitAccess {
+    shellRuns;
+    events;
+    constructor(shellRuns, events) {
+        this.shellRuns = shellRuns;
+        this.events = events;
+    }
+    async authorize(wait, signal) {
+        const result = await this.read(wait, signal);
+        return result.kind === 'allowed' ? { kind: 'allowed', context: null } : result;
+    }
+    async read(wait, signal) {
+        const taskId = validateShellRunWait(wait);
+        signal.throwIfAborted();
+        let task;
+        try {
+            task = await this.shellRuns.readShellRun(wait.sessionId, taskId);
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return { kind: 'revoked', reason: 'shell_run_missing' };
+            throw error;
+        }
+        if (task.sessionId !== wait.sessionId || task.shellRunId !== taskId || !task.sourceRunId)
+            return { kind: 'revoked', reason: 'shell_run_identity_invalid' };
+        if (task.visibility === 'user')
+            return { kind: 'revoked', reason: 'shell_run_access_revoked' };
+        const invocation = await this.events.readRunInvocation(wait.sessionId, task.sourceRunId);
+        if (!invocation ||
+            invocation.turnId !== task.sourceTurnId ||
+            invocation.opening.route.provenance !== 'runtime' ||
+            invocation.opening.route.backendKind !== 'ai-sdk')
+            return { kind: 'revoked', reason: 'shell_run_provenance_invalid' };
+        const proof = await this.events.readToolProvenanceEvents(wait.sessionId, task.sourceRunId, task.sourceToolCallId, { maxRecords: 8, maxBytes: 2 * 1024 * 1024 });
+        signal.throwIfAborted();
+        if (proof.status !== 'complete')
+            return { kind: 'revoked', reason: 'shell_run_provenance_unavailable' };
+        const facts = proof.records;
+        const calls = facts.filter((e) => e.content?.kind === 'function_call');
+        const dispatches = facts.filter((e) => e.actions?.toolDispatch);
+        const outcomes = facts.filter((e) => e.content?.kind === 'function_response');
+        const call = calls[0]?.content, dispatch = dispatches[0]?.actions?.toolDispatch, outcome = outcomes[0]?.content;
+        if (calls.length !== 1 ||
+            dispatches.length !== 1 ||
+            outcomes.length !== 1 ||
+            call?.kind !== 'function_call' ||
+            outcome?.kind !== 'function_response' ||
+            !dispatch ||
+            facts.some((e) => !validateToolLedgerEventLane(e).ok ||
+                e.partial ||
+                e.sessionId !== wait.sessionId ||
+                e.runId !== task.sourceRunId ||
+                e.turnId !== task.sourceTurnId ||
+                e.invocationId !== invocation.invocationId) ||
+            call.id !== task.sourceToolCallId ||
+            outcome.id !== call.id ||
+            dispatch.providerToolCallId !== call.id ||
+            call.name !== 'Bash' ||
+            outcome.name !== 'Bash' ||
+            dispatch.toolName !== 'Bash' ||
+            call.providerExecuted === true ||
+            outcome.providerExecuted === true ||
+            dispatch.protocol !== 't1_after_preflight_v1' ||
+            dispatch.canonicalArgsHash !== canonicalToolArgsHash('Bash', call.args) ||
+            outcomes[0]?.refs?.operationId !== dispatch.operationId ||
+            facts.indexOf(calls[0]) >= facts.indexOf(dispatches[0]) ||
+            facts.indexOf(dispatches[0]) >= facts.indexOf(outcomes[0]) ||
+            !isBackgroundCall(call.args) ||
+            !isTaskResult(outcome.result, wait.resource.resourceId))
+            return { kind: 'revoked', reason: 'shell_run_provenance_invalid' };
+        // Proof reads may suspend. Recheck the live resource binding after them;
+        // a registration-time snapshot cannot authorize a later admission.
+        let current;
+        try {
+            current = await this.shellRuns.readShellRun(wait.sessionId, taskId);
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return { kind: 'revoked', reason: 'shell_run_missing' };
+            throw error;
+        }
+        signal.throwIfAborted();
+        if (current.visibility === 'user')
+            return { kind: 'revoked', reason: 'shell_run_access_revoked' };
+        if (current.sessionId !== task.sessionId ||
+            current.shellRunId !== task.shellRunId ||
+            current.sourceRunId !== task.sourceRunId ||
+            current.sourceTurnId !== task.sourceTurnId ||
+            current.sourceToolCallId !== task.sourceToolCallId ||
+            current.startedAt !== task.startedAt)
+            return { kind: 'revoked', reason: 'shell_run_identity_invalid' };
+        task = current;
+        // Canonical immutable T2 retains the original outcome even after its model
+        // projection is archived/pruned. Never authorize from a placeholder or UI row.
+        const { sessionId, shellRunId, sourceRunId, sourceTurnId, sourceToolCallId, startedAt, status, completedAt, exitCode, failureMessage, } = task;
+        return {
+            kind: 'allowed',
+            fact: {
+                sessionId,
+                shellRunId,
+                sourceRunId,
+                sourceTurnId,
+                sourceToolCallId,
+                startedAt,
+                status,
+                ...(completedAt === undefined ? {} : { completedAt }),
+                ...(exitCode === undefined ? {} : { exitCode }),
+                ...(failureMessage === undefined ? {} : { failureMessage }),
+            },
+        };
+    }
+}
+function isBackgroundCall(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'run_in_background' in value &&
+        value.run_in_background === true);
+}
+function isTaskResult(value, ref) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'kind' in value &&
+        value.kind === 'shell_run' &&
+        'ref' in value &&
+        value.ref === ref);
+}

package/node_modules/@maka/runtime-host/dist/server/shell-run-event-wait-adapter.js

@@ -0,0 +1,59 @@
+/*
+ * 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 } from 'node:crypto';
+import { isTerminalShellRunStatus } from '@maka/core/shell-run';
+import { SHELL_RUN_WAIT_SOURCE, validateShellRunWait, } from './shell-run-event-wait-access.js';
+export class ShellRunEventWaitAdapter {
+    access;
+    manager;
+    providerId = SHELL_RUN_WAIT_SOURCE.providerId;
+    resourceType = SHELL_RUN_WAIT_SOURCE.resourceType;
+    conditionType = SHELL_RUN_WAIT_SOURCE.conditionType;
+    conditionVersion = SHELL_RUN_WAIT_SOURCE.conditionVersion;
+    reconciliation = 'snapshot';
+    constructor(access, manager) {
+        this.access = access;
+        this.manager = manager;
+    }
+    validate(wait) {
+        validateShellRunWait(wait);
+    }
+    async read(input) {
+        const result = await this.access.read(input.wait, input.signal);
+        // The next access check cancels and pauses on confirmed revocation. A read
+        // racing that check must not fabricate a terminal outcome in the meantime.
+        if (result.kind === 'revoked')
+            return { kind: 'unknown', reason: result.reason };
+        const fact = result.fact;
+        if (!isTerminalShellRunStatus(fact.status))
+            return { kind: 'pending' };
+        const digest = createHash('sha256').update(JSON.stringify(fact)).digest('hex');
+        const receiptKey = `shell-run/terminal-v1/${fact.shellRunId}/${digest}`;
+        return {
+            kind: fact.status === 'orphaned' ? 'source_unavailable' : 'satisfied',
+            receiptKey,
+            eventKey: receiptKey,
+            evidenceRefs: [input.wait.resource.resourceId],
+        };
+    }
+    async subscribe(input, changed) {
+        this.validate(input.wait);
+        return this.manager.subscribeChanges(input.wait.sessionId, input.wait.resource.resourceId, input.signal, changed);
+    }
+}

package/node_modules/@maka/runtime-host/dist/server/skill-catalog-repository.js

@@ -225,6 +225,7 @@ export class SkillCatalogRepository {
                 const publicationNamespace = await readPublicationNamespace(root);
                 return buildSnapshot({
                     projectRoot,
+                    workspaceSkillDirectory: join(root, 'skills'),
                     scan,
                     managedSourcesRoot: this.#managedSourcesRoot,
                     publicationNamespace,
@@ -601,7 +602,7 @@ async function buildSnapshot(input) {
         publicationNamespace: input.publicationNamespace,
         effectiveMigration,
     }));
-    const model = freezeModelSnapshot(revision, input.projectRoot, input.scan, effectiveMigration);
+    const model = freezeModelSnapshot(revision, input.projectRoot, input.workspaceSkillDirectory, input.scan, effectiveMigration);
     return Object.freeze({
         revision,
         projectRoot: input.projectRoot,
@@ -965,7 +966,7 @@ function canonicalRevisionFacts(input) {
         },
     };
 }
-function freezeModelSnapshot(revision, projectRoot, scan, migration) {
+function freezeModelSnapshot(revision, projectRoot, workspaceSkillDirectory, scan, migration) {
     const inventory = scan.inventory.filter(hasDurableSkillIdentity).map((skill) => {
         const preference = migration === null ? undefined : getSkillRuntimePreference(migration, skill);
         const enabled = preference?.enabled ?? skill.enabled;
@@ -987,6 +988,7 @@ function freezeModelSnapshot(revision, projectRoot, scan, migration) {
     return Object.freeze({
         revision,
         projectRoot,
+        workspaceSkillDirectory,
         inventory: Object.freeze(inventory),
         diagnostics: Object.freeze(diagnostics),
         discoveryDiagnostics: Object.freeze(discoveryDiagnostics),

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

@@ -23,7 +23,7 @@ import { dirname, join, resolve } from 'node:path';
 import { backup, DatabaseSync } from 'node:sqlite';
 import { isCanonicalStorageRef } from '@maka/core/events';
 import { discoverMarkedStorageRoot, resolveStorageRoot, runWithStorageRootLease, tryAcquireInteractiveRootOwner, } from './root-authority.js';
-import { migrateSqliteContextOffloadDatabase, SQLITE_CONTEXT_OFFLOAD_SCHEMA_VERSION, } from './sqlite-context-offload-schema.js';
+import { migrateSqliteContextOffloadDatabase, SQLITE_CONTEXT_OFFLOAD_SCHEMA_VERSION, validateSqliteContextOffloadSchema, } from './sqlite-context-offload-schema.js';
 import { CONTEXT_OFFLOAD_DATABASE_NAME, CONTEXT_OFFLOAD_VALUES_DIRECTORY_NAME, } from './sqlite-context-offload-store.js';
 import { syncDirectoryChain, syncFile } from './stable-storage.js';
 import { SQLITE_SESSION_MESSAGE_CHUNK_MARKER } from './sqlite-session-metadata-schema.js';
@@ -187,6 +187,7 @@ export async function validateContextSnapshot(root, sessionIds) {
             if (context.prepare('PRAGMA user_version').get()?.user_version !==
                 SQLITE_CONTEXT_OFFLOAD_SCHEMA_VERSION)
                 throw new Error('Unsupported context snapshot schema');
+            validateSqliteContextOffloadSchema(context);
             if (context.prepare('PRAGMA integrity_check').get()?.integrity_check !== 'ok' ||
                 context.prepare('PRAGMA foreign_key_check').get())
                 throw new Error('Invalid context snapshot database');

package/node_modules/@maka/storage/dist/execution-stores.js

@@ -17,6 +17,7 @@
  * under the License.
  */
 import { openInteractiveEventWaitAuthorityForWrite, } from './event-wait-authority.js';
+import { SnapshotOperationGate } from './snapshot-operation-gate.js';
 import { createSqliteAgentRunStore, } from './agent-run-store.js';
 import { createSessionStore } from './session-store.js';
 import { assertStorageRootLease, assertStorageRootLeaseActive, runWithStorageRootLease, StorageRootAuthorityError, } from './root-authority.js';
@@ -102,6 +103,7 @@ async function createExecutionStoresForWrite(lease, provider) {
     let closed = false;
     let closeTask;
     const active = new Set();
+    const snapshotGate = new SnapshotOperationGate();
     const subscriptions = new Set();
     const run = (operation) => {
         if (closed)
@@ -109,7 +111,7 @@ async function createExecutionStoresForWrite(lease, provider) {
         const pending = runWithStorageRootLease(lease, kind, 'write', () => {
             if (closed)
                 throw invalidExecutionStores(kind, 'write');
-            return operation();
+            return snapshotGate.run(operation);
         });
         active.add(pending);
         void pending.finally(() => active.delete(pending)).catch(() => undefined);
@@ -279,6 +281,37 @@ async function createExecutionStoresForWrite(lease, provider) {
         close: () => { },
     });
     const stores = {
+        ...(persistence.createSnapshotStatePreparer
+            ? {
+                snapshot: Object.freeze({
+                    runExclusive(operation) {
+                        if (closed)
+                            return Promise.reject(invalidExecutionStores(kind, 'write'));
+                        const pending = snapshotGate.exclusive(() => runWithStorageRootLease(lease, kind, 'write', async () => {
+                            if (closed)
+                                throw invalidExecutionStores(kind, 'write');
+                            const state = persistence.createSnapshotStatePreparer(lease);
+                            let scopeActive = true;
+                            try {
+                                return await operation({
+                                    prepareState: (input) => {
+                                        if (!scopeActive || closed)
+                                            return Promise.reject(invalidExecutionStores(kind, 'write'));
+                                        return state.prepareState(input);
+                                    },
+                                });
+                            }
+                            finally {
+                                scopeActive = false;
+                            }
+                        }));
+                        active.add(pending);
+                        void pending.finally(() => active.delete(pending)).catch(() => { });
+                        return pending;
+                    },
+                }),
+            }
+            : {}),
         interactionStore,
         graphControlStore,
         goalStore,
@@ -410,6 +443,7 @@ async function createExecutionStoresForWrite(lease, provider) {
                 }
                 : {}),
             scanRuntimeEvents: (sessionId, runId, budget, visit) => run(() => runtimeEventStore.scanRuntimeEvents(sessionId, runId, budget, visit)),
+            readToolProvenanceEvents: (sessionId, runId, toolCallId, budget) => run(() => runtimeEventStore.readToolProvenanceEvents(sessionId, runId, toolCallId, budget)),
             readRuntimeEventsBounded: (sessionId, runId, budget) => run(() => runtimeEventStore.readRuntimeEventsBounded(sessionId, runId, budget)),
             readImmutableRuntimeEvents: (sessionId, runId) => run(() => runtimeEventStore.readImmutableRuntimeEvents(sessionId, runId)),
             readRecoveryMessageEvents: (input) => run(() => runtimeEventStore.readRecoveryMessageEvents(input)),
@@ -527,6 +561,7 @@ async function openExecutionStoresForRead(lease, kind, extension) {
                     readSessionRuntimeSnapshot: (sessionId) => run(() => runtimeEventStore.readSessionRuntimeSnapshot(sessionId)),
                 }
                 : {}),
+            readToolProvenanceEvents: (sessionId, runId, toolCallId, budget) => run(() => runtimeEventStore.readToolProvenanceEvents(sessionId, runId, toolCallId, budget)),
             readRuntimeEventsBounded: (sessionId, runId, budget) => run(() => runtimeEventStore.readRuntimeEventsBounded(sessionId, runId, budget)),
             readImmutableRuntimeEvents: (sessionId, runId) => run(() => runtimeEventStore.readImmutableRuntimeEvents(sessionId, runId)),
             listSessionInvocations: (sessionId) => run(() => runtimeEventStore.listSessionInvocations(sessionId)),

package/node_modules/@maka/storage/dist/local-execution-persistence.js

@@ -24,6 +24,9 @@ import { createAgentGraphControlStore } from './agent-graph-control-store.js';
 import { createSqliteEventWaitAuthority } from './sqlite-event-wait-authority.js';
 import { createSqliteGoalAuthority } from './goal-authority.js';
 import { createSqliteInteractionStore } from './interaction-store.js';
+import { exportSessionBundleState } from './session-bundle-policy.js';
+import { createSessionSnapshotStateIdentity } from './production-session-snapshot.js';
+import { runWithStorageRootLease } from './root-authority.js';
 export const localExecutionPersistenceProvider = Object.freeze({
     async open({ canonicalPath }) {
         const closes = [];
@@ -60,6 +63,29 @@ export const localExecutionPersistenceProvider = Object.freeze({
             closes.push(() => interactionStore.close());
             await Promise.all([sessionStore.ready(), agentRunStore.ready?.(), interactionStore.ready()]);
             return {
+                createSnapshotStatePreparer(lease) {
+                    if (lease.canonicalPath !== canonicalPath)
+                        throw new Error('Snapshot lease belongs to another backend');
+                    return {
+                        async prepareState(input) {
+                            input.cancellation.signal.throwIfAborted();
+                            // Lock order: execution fence -> Artifact writer -> context values.
+                            // The exporter holds the Artifact lock until both databases and
+                            // their payloads are private. GC/publication uses these same locks.
+                            await runWithStorageRootLease(lease, 'interactive', 'write', () => exportSessionBundleState({
+                                stateRoot: canonicalPath,
+                                configRoot: canonicalPath,
+                                allowShared: true,
+                                destinationRoot: input.destinationRoot,
+                                sessionId: input.makaSessionId,
+                                requireQuiescent: true,
+                                lease,
+                            }));
+                            input.cancellation.signal.throwIfAborted();
+                            return createSessionSnapshotStateIdentity(input.makaSessionId);
+                        },
+                    };
+                },
                 sessionStore,
                 agentRunStore,
                 runtimeEventStore: runtime.runtimeEventStore,