maka-agent 0.2.1-dev.91.20261018 → 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

@@ -16,6 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+import { decodeGoalAuthorityRecord } from '@maka/core/goal';
 import { copyFile, link, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, unlink, writeFile, } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { randomUUID } from 'node:crypto';
@@ -43,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';
@@ -168,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`;
@@ -182,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);
@@ -208,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.
@@ -319,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)}`);
@@ -358,6 +374,8 @@ async function filterBackedUpDatabase(destinationPath, sessionIds, options) {
                 database.exec(`DELETE FROM ${quoteIdentifier(row.name)}`);
             }
         }
+        if (options.omitEventWaits)
+            stripPortableGoalWaits(database);
         // Operational rows that describe a REQUEST rather than the conversation.
         // None of them reach the model, and in a real Session they are the large
         // majority of this table. The two record kinds that do decide what the
@@ -506,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',
@@ -762,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;
             }
         }
@@ -1007,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
@@ -1050,6 +1084,7 @@ function mergeAttachedBundle(target) {
            WHERE is_archived = 1
              AND session_id IN (SELECT session_id FROM bundle.session_metadata)`)
                 .run(Date.now());
+            stripPortableGoalWaits(target, true);
             const violation = target.prepare('PRAGMA foreign_key_check').get();
             if (violation) {
                 throw new SessionBundleImportError('conflict', 'Imported Sessions would leave dangling references');
@@ -1154,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
@@ -1219,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.
  *
@@ -1372,3 +1446,29 @@ function countContextRefs(databasePath, sessionIds) {
         database.close();
     }
 }
+function stripPortableGoalWaits(database, importedOnly = false) {
+    const scope = importedOnly
+        ? 'AND session_id IN (SELECT session_id FROM bundle.session_metadata)'
+        : '';
+    for (const row of database
+        .prepare(`SELECT session_id, record_json FROM workflow_goal_authority WHERE (json_type(record_json, '$.activeEventWait') IS NOT NULL OR json_type(record_json, '$.pendingContinuation.eventWait') IS NOT NULL) ${scope}`)
+        .all()) {
+        const old = decodeGoalAuthorityRecord(JSON.parse(String(row.record_json)));
+        const { activeEventWait: _gate, ...base } = old;
+        const record = decodeGoalAuthorityRecord({
+            ...base,
+            currentExecution: null,
+            pendingContinuation: null,
+            controlLease: { ...base.controlLease, generation: base.controlLease.generation + 1 },
+            goal: {
+                ...base.goal,
+                revision: base.goal.revision + 1,
+                status: 'paused',
+                lastReason: 'Event waits do not transfer between State Roots.',
+            },
+        });
+        database
+            .prepare('UPDATE workflow_goal_authority SET authority_revision = authority_revision + 1, goal_revision = ?, status = ?, record_json = ? WHERE session_id = ?')
+            .run(record.goal.revision, record.goal.status, JSON.stringify(record), row.session_id);
+    }
+}

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/session-store.js

@@ -18,7 +18,7 @@
  */
 import { assertCoordinationIdentityPairing, buildSessionHeader, toSummary, } from './session-store-values.js';
 export { normalizeSessionHeader, decodePersistedSessionHeader, createUserMessage, } from './session-store-values.js';
-import { SessionMetadataVersionConflictError, EXTERNAL_SESSION_IMPORT_LOOKUP_MAX_SOURCE_IDS, EXTERNAL_SESSION_IMPORT_LOOKUP_MAX_RECENT_SESSION_IDS, } from './session-store-contract.js';
+import { SessionMetadataVersionConflictError, EXTERNAL_SESSION_IMPORT_LOOKUP_MAX_SOURCE_IDS, EXTERNAL_SESSION_IMPORT_LOOKUP_MAX_RECENT_SESSION_IDS, isSessionNotFoundError, } from './session-store-contract.js';
 export { isSafeSessionId, assertSafeSessionId, SessionNotFoundError, isSessionNotFoundError, EXTERNAL_SESSION_IMPORT_LOOKUP_MAX_SOURCE_IDS, EXTERNAL_SESSION_IMPORT_LOOKUP_MAX_RECENT_SESSION_IDS, } from './session-store-contract.js';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
@@ -62,19 +62,48 @@ class SqliteSessionStore {
         if (input.subagentSpawn) {
             throw new Error('Subagent spawn metadata requires createSubagent()');
         }
-        const canonicalMessages = messages.map((message) => decodeCanonicalMessage(JSON.parse(JSON.stringify(message))));
         const header = {
             ...buildSessionHeader(this.workspaceRoot, input),
             externalOrigin,
             transcriptLedgerVersion: 0,
         };
-        const catalogProjection = projectSessionCatalogMessages(canonicalMessages);
-        options.onCommitStarted?.();
-        const outcome = await this.metadata.importSession(header, canonicalMessages, catalogProjection);
-        if (outcome !== 'imported') {
-            throw new Error(`Generated Session id already exists: ${header.id}`);
+        let commitStarted = false;
+        try {
+            const preparedMessages = options.prepareMessages
+                ? await options.prepareMessages(header.id, messages)
+                : messages;
+            const canonicalMessages = preparedMessages.map((message) => decodeCanonicalMessage(JSON.parse(JSON.stringify(message))));
+            const catalogProjection = projectSessionCatalogMessages(canonicalMessages);
+            options.onCommitStarted?.();
+            commitStarted = true;
+            const outcome = await this.metadata.importSession(header, canonicalMessages, catalogProjection);
+            if (outcome !== 'imported') {
+                throw new Error(`Generated Session id already exists: ${header.id}`);
+            }
+            return (await this.metadata.read(header.id)).header;
+        }
+        catch (error) {
+            let uncommitted = !commitStarted;
+            if (commitStarted) {
+                try {
+                    await this.metadata.read(header.id);
+                }
+                catch (readError) {
+                    // An uncertain commit must retain its bytes for recovery. Only an
+                    // authoritative absence makes the prepared artifacts safe to discard.
+                    uncommitted = isSessionNotFoundError(readError);
+                }
+            }
+            if (uncommitted) {
+                try {
+                    await options.discardPreparedMessages?.(header.id);
+                }
+                catch {
+                    // Best-effort cleanup must not replace the original import failure.
+                }
+            }
+            throw error;
         }
-        return (await this.metadata.read(header.id)).header;
     }
     async lookupExternalSessionImports(adapterId, sourceSessionIds, recentSessionIdLimit) {
         await this.ensureReady();

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');