源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)
Dependency audit / audit (push) Canceled after 0s
CI / plan (push) Canceled after 0s
Gitoxide helper admission / macos-latest (push) Canceled after 0s
Gitoxide helper admission / ubuntu-latest (push) Canceled after 0s
Gitoxide helper admission / windows-latest (push) Canceled after 0s
Runtime Host peer admission / quality (push) Canceled after 0s
Windows recovery / windows_recovery (push) Canceled after 0s
CI / heavy (push) Canceled after 0s
CI / test (push) Canceled after 0s

This commit is contained in:
agent-radar committed 2026-09-01 19:05:14 +08:00
commit 7be535059e
3358 files changed
+1306357

No files matched your search

+74
View File
@@ -0,0 +1,74 @@
{
"name": "@maka/storage",
"version": "0.1.0",
"license": "Apache-2.0",
"private": true,
"type": "module",
"exports": {
"./activation-secret-injector": "./dist/activation-secret-injector.js",
"./agent-graph-control-store": "./dist/agent-graph-control-store.js",
"./agent-run-store": "./dist/agent-run-store.js",
"./artifact-stores": "./dist/artifact-stores.js",
"./config-transfer": "./dist/config-transfer.js",
"./context-offload-store": "./dist/context-offload-store.js",
"./credential-store": "./dist/credential-store.js",
"./daily-review-authority": "./dist/daily-review-authority.js",
"./deep-research-authority": "./dist/deep-research-authority.js",
"./deep-research-store": "./dist/deep-research-store.js",
"./encrypted-file-managed-secret-store": "./dist/encrypted-file-managed-secret-store.js",
"./execution-stores": "./dist/execution-stores.js",
"./external-sessions": "./dist/external-sessions.js",
"./file-lifetime-owner": "./dist/file-lifetime-owner.js",
"./file-update-lock": "./dist/file-update-lock.js",
"./foreign-session-store": "./dist/foreign-session-store.js",
"./git-worktree-child-executor": "./dist/git-worktree-child-executor.js",
"./goal-authority": "./dist/goal-authority.js",
"./interaction-store": "./dist/interaction-store-public.js",
"./long-term-memory-store": "./dist/long-term-memory-store.js",
"./managed-secret-store": "./dist/managed-secret-store.js",
"./mcp-config-store": "./dist/mcp-config-store.js",
"./memory-bundle-store": "./dist/memory-bundle-store.js",
"./model-call-ledger": "./dist/model-call-ledger.js",
"./operational-state-store": "./dist/operational-state-store-public.js",
"./pet-pack-store": "./dist/pet-pack-store.js",
"./plan-authority": "./dist/plan-authority.js",
"./process-lifetime-file-update-lock": "./dist/process-lifetime-file-update-lock.js",
"./process-lifetime-owner": "./dist/process-lifetime-owner.js",
"./project-catalog": "./dist/project-catalog.js",
"./project-catalog-authority": "./dist/project-catalog-authority.js",
"./root-authority": "./dist/root-authority.js",
"./read-image-snapshot-store": "./dist/read-image-snapshot-store.js",
"./runtime-event-persistence": "./dist/runtime-event-persistence.js",
"./runtime-policy-stores": "./dist/runtime-policy-stores.js",
"./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-bundle-policy": "./dist/session-bundle-policy.js",
"./session-copy-cleanup": "./dist/session-copy-cleanup.js",
"./session-todo-authority": "./dist/session-todo-authority.js",
"./session-store": "./dist/session-store.js",
"./settings-store": "./dist/settings-store.js",
"./shell-run-authority": "./dist/shell-run-authority.js",
"./shell-run-store": "./dist/shell-run-store.js",
"./sqlite-runtime-store": "./dist/sqlite-runtime-store.js",
"./sqlite-session-metadata-store": "./dist/sqlite-session-metadata-store.js",
"./stable-storage": "./dist/stable-storage.js",
"./state-root-composition": "./dist/state-root-composition.js",
"./storage-writer-composition": "./dist/storage-writer-composition.js",
"./usage-stores": "./dist/usage-stores.js",
"./work-board-store": "./dist/work-board-store.js",
"./workspace-identity": "./dist/workspace-identity.js",
"./workspace-root": "./dist/workspace-root.js",
"./write-queue": "./dist/write-queue.js"
},
"scripts": {
"clean": "node ../../scripts/clean-paths.mjs dist tsconfig.tsbuildinfo",
"build": "tsc -p tsconfig.json",
"typecheck": "tsc -p tsconfig.json --noEmit",
"test:dist": "node --test \"dist/**/*.test.js\""
},
"dependencies": {
"@maka/core": "0.1.0",
"fs-native-extensions": "^1.5.0"
}
}
@@ -0,0 +1,362 @@
/*
* 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 assert from 'node:assert/strict';
import { describe, test } from 'node:test';
import {
ActivationEnvironmentSecretSink,
ActivationSecretInjector,
type ActivationSecretInjectionLease,
type ActivationSecretSink,
} from '../activation-secret-injector.js';
import {
InMemoryManagedSecretStore,
ManagedSecretError,
type ManagedSecretMaterial,
type ManagedSecretMetadata,
type ResolveManagedSecretsForActivationInput,
} from '../managed-secret-store.js';
const PRINCIPAL = 'user-1';
const SESSION = 'cloud-session-1';
const CONTEXT = {
principalId: PRINCIPAL,
cloudSessionId: SESSION,
activationId: 'activation-1',
};
describe('ActivationSecretInjector', () => {
test('injects into an isolated launch environment and restores its prior state', async () => {
const { store, first, second } = await preparedStore();
const environment: NodeJS.ProcessEnv = { FIRST_TOKEN: 'previous', UNRELATED: 'kept' };
const handle = await new ActivationSecretInjector(store).prepare({
context: CONTEXT,
bindings: [binding(first, 'FIRST_TOKEN'), binding(second, 'SECOND_TOKEN')],
sink: new ActivationEnvironmentSecretSink(environment),
});
assert.deepEqual(environment, {
FIRST_TOKEN: 'first-value',
SECOND_TOKEN: 'second-value',
UNRELATED: 'kept',
});
await handle.release();
assert.deepEqual(environment, { FIRST_TOKEN: 'previous', UNRELATED: 'kept' });
});
test('literal redaction cannot rewrite its own replacement marker', async () => {
const ids = ['00000000-0000-4000-8000-000000000011', '00000000-0000-4000-8000-000000000012'];
const store = new InMemoryManagedSecretStore({ newSecretId: () => ids.shift()! });
const longer = await store.createSecret({ principalId: PRINCIPAL, value: 'long-value' });
const markerSubstring = await store.createSecret({ principalId: PRINCIPAL, value: 'red' });
for (const secret of [longer, markerSubstring]) {
await store.authorizeSession({
principalId: PRINCIPAL,
reference: secret.reference,
cloudSessionId: SESSION,
});
}
const handle = await new ActivationSecretInjector(store).prepare({
context: CONTEXT,
bindings: [binding(longer, 'LONGER'), binding(markerSubstring, 'SHORTER')],
sink: recordingSink([]),
});
assert.equal(handle.redact('long-value then red'), '[redacted] then [redacted]');
await handle.release();
});
test('resolves before injection and gives the sink one complete batch effect', async () => {
const { store, first, second } = await preparedStore();
const events: string[] = [];
const sink = recordingSink(events);
const handle = await new ActivationSecretInjector(store).prepare({
context: CONTEXT,
bindings: [binding(first, 'FIRST_TOKEN'), binding(second, 'SECOND_TOKEN')],
sink,
});
assert.deepEqual(events, [
'inject:FIRST_TOKEN:first-value',
'inject:SECOND_TOKEN:second-value',
]);
assert.equal(JSON.stringify(handle).includes('first-value'), false);
assert.deepEqual(handle.references, [first.reference, second.reference]);
assert.equal(
handle.redact('tool printed first-value and second-value'),
'tool printed [redacted] and [redacted]',
);
assert.equal(handle.redact('the red value is first-value'), 'the red value is [redacted]');
await handle.release();
await handle.release();
assert.equal(handle.redact('first-value'), 'first-value');
assert.deepEqual(events, [
'inject:FIRST_TOKEN:first-value',
'inject:SECOND_TOKEN:second-value',
'release:batch',
]);
});
test('the environment sink restores the complete batch if applying an entry fails', async () => {
const target = { FIRST_TOKEN: 'previous', UNRELATED: 'kept' } as NodeJS.ProcessEnv;
const environment = new Proxy(target, {
set(object, property, value) {
if (property === 'SECOND_TOKEN') throw new Error('setter failed');
return Reflect.set(object, property, value);
},
});
await assert.rejects(
new ActivationEnvironmentSecretSink(environment).injectEnvironmentVariables({
entries: [
{ name: 'FIRST_TOKEN', value: 'first-value' },
{ name: 'SECOND_TOKEN', value: 'second-value' },
],
}),
/setter failed/u,
);
assert.deepEqual(target, { FIRST_TOKEN: 'previous', UNRELATED: 'kept' });
});
test('injects nothing when any reference is missing authorization', async () => {
const { store, first, second } = await preparedStore();
await store.revokeSessionAuthorization({
principalId: PRINCIPAL,
reference: second.reference,
cloudSessionId: SESSION,
});
const events: string[] = [];
await assert.rejects(
new ActivationSecretInjector(store).prepare({
context: CONTEXT,
bindings: [binding(first, 'FIRST_TOKEN'), binding(second, 'SECOND_TOKEN')],
sink: recordingSink(events),
}),
(error: unknown) => error instanceof ManagedSecretError && error.code === 'unauthorized',
);
assert.deepEqual(events, []);
});
test('rejects reordered material references before the first sink effect', async () => {
const ids = ['00000000-0000-4000-8000-000000000021', '00000000-0000-4000-8000-000000000022'];
const store = new ReorderingManagedSecretStore({ newSecretId: () => ids.shift()! });
const first = await store.createSecret({ principalId: PRINCIPAL, value: 'first-value' });
const second = await store.createSecret({ principalId: PRINCIPAL, value: 'second-value' });
for (const secret of [first, second]) {
await store.authorizeSession({
principalId: PRINCIPAL,
reference: secret.reference,
cloudSessionId: SESSION,
});
}
const events: string[] = [];
await assert.rejects(
new ActivationSecretInjector(store).prepare({
context: CONTEXT,
bindings: [binding(first, 'FIRST_TOKEN'), binding(second, 'SECOND_TOKEN')],
sink: recordingSink(events),
}),
(error: unknown) => error instanceof ManagedSecretError && error.code === 'integrity_failure',
);
assert.deepEqual(events, []);
});
test('uses a private material snapshot across asynchronous sink effects', async () => {
const ids = ['00000000-0000-4000-8000-000000000031', '00000000-0000-4000-8000-000000000032'];
const store = new MutableMaterialManagedSecretStore({ newSecretId: () => ids.shift()! });
const first = await store.createSecret({ principalId: PRINCIPAL, value: 'first-value' });
const second = await store.createSecret({ principalId: PRINCIPAL, value: 'second-value' });
for (const secret of [first, second]) {
await store.authorizeSession({
principalId: PRINCIPAL,
reference: secret.reference,
cloudSessionId: SESSION,
});
}
const events: string[] = [];
const handle = await new ActivationSecretInjector(store).prepare({
context: CONTEXT,
bindings: [binding(first, 'FIRST_TOKEN'), binding(second, 'SECOND_TOKEN')],
sink: {
async injectEnvironmentVariables({ entries }) {
store.replaceSecondMaterialWithFirst();
events.push(...entries.map(({ name, value }) => `inject:${name}:${value}`));
return oneShotLease(() => events.push('release:batch'));
},
},
});
assert.deepEqual(events, [
'inject:FIRST_TOKEN:first-value',
'inject:SECOND_TOKEN:second-value',
]);
await handle.release();
});
test('wraps a batch sink failure without exposing resolved material', async () => {
const { store, first, second } = await preparedStore();
const events: string[] = [];
const leaked = 'second-value';
const sink: ActivationSecretSink = {
async injectEnvironmentVariables({ entries }) {
events.push(...entries.map(({ name, value }) => `inject:${name}:${value}`));
throw new Error(`sink exposed ${leaked}`);
},
};
await assert.rejects(
new ActivationSecretInjector(store).prepare({
context: CONTEXT,
bindings: [binding(first, 'FIRST_TOKEN'), binding(second, 'SECOND_TOKEN')],
sink,
}),
(error: unknown) => {
assert.ok(error instanceof ManagedSecretError);
assert.equal(error.code, 'injection_failed');
assert.equal(error.message.includes(leaked), false);
assert.equal(JSON.stringify(error).includes(leaked), false);
return true;
},
);
assert.deepEqual(events, [
'inject:FIRST_TOKEN:first-value',
'inject:SECOND_TOKEN:second-value',
]);
});
test('keeps successful-handle cleanup failures retryable', async () => {
const { store, first } = await preparedStore();
let attempts = 0;
const handle = await new ActivationSecretInjector(store).prepare({
context: CONTEXT,
bindings: [binding(first, 'FIRST_TOKEN')],
sink: {
async injectEnvironmentVariables() {
return {
async release() {
attempts += 1;
if (attempts === 1) throw new Error('transient');
},
};
},
},
});
await assert.rejects(
handle.release(),
(error: unknown) => error instanceof ManagedSecretError && error.code === 'cleanup_failed',
);
await handle.release();
assert.equal(attempts, 2);
});
test('rejects duplicate and malformed environment targets before resolution', async () => {
const { store, first, second } = await preparedStore();
const injector = new ActivationSecretInjector(store);
await assert.rejects(
injector.prepare({
context: CONTEXT,
bindings: [binding(first, 'TOKEN'), binding(second, 'token')],
sink: recordingSink([]),
}),
(error: unknown) => error instanceof ManagedSecretError && error.code === 'invalid_input',
);
await assert.rejects(
injector.prepare({
context: CONTEXT,
bindings: [binding(first, 'NOT-AN-ENV-NAME')],
sink: recordingSink([]),
}),
(error: unknown) => error instanceof ManagedSecretError && error.code === 'invalid_input',
);
});
});
class ReorderingManagedSecretStore extends InMemoryManagedSecretStore {
override async resolveForActivation(
input: ResolveManagedSecretsForActivationInput,
): Promise<readonly ManagedSecretMaterial[]> {
return [...(await super.resolveForActivation(input))].reverse();
}
}
class MutableMaterialManagedSecretStore extends InMemoryManagedSecretStore {
#material: ManagedSecretMaterial[] = [];
override async resolveForActivation(
input: ResolveManagedSecretsForActivationInput,
): Promise<readonly ManagedSecretMaterial[]> {
this.#material = (await super.resolveForActivation(input)).map((item) => ({
...item,
reference: { ...item.reference },
}));
return this.#material;
}
replaceSecondMaterialWithFirst(): void {
const first = this.#material[0];
if (first) this.#material[1] = first;
}
}
async function preparedStore() {
const ids = ['00000000-0000-4000-8000-000000000001', '00000000-0000-4000-8000-000000000002'];
const store = new InMemoryManagedSecretStore({
newSecretId: () => {
const id = ids.shift();
if (!id) throw new Error('ids exhausted');
return id;
},
});
const first = await store.createSecret({ principalId: PRINCIPAL, value: 'first-value' });
const second = await store.createSecret({ principalId: PRINCIPAL, value: 'second-value' });
for (const secret of [first, second]) {
await store.authorizeSession({
principalId: PRINCIPAL,
reference: secret.reference,
cloudSessionId: SESSION,
});
}
return { store, first, second };
}
function binding(secret: ManagedSecretMetadata, name: string) {
return { reference: secret.reference, target: { kind: 'environment' as const, name } };
}
function recordingSink(events: string[]): ActivationSecretSink {
return {
async injectEnvironmentVariables({ entries }) {
events.push(...entries.map(({ name, value }) => `inject:${name}:${value}`));
return oneShotLease(() => events.push('release:batch'));
},
};
}
function oneShotLease(release: () => void): ActivationSecretInjectionLease {
let released = false;
return {
async release() {
if (released) return;
release();
released = true;
},
};
}
@@ -0,0 +1,220 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { AgentGraphEpochConflictError } from '@maka/core/agent-graph-epoch';
import { createSqliteSessionMetadataStore } from '../sqlite-session-metadata-store.js';
describe('SQLite Agent Graph epochs', () => {
test('resolves legacy epoch 1 without persisting state for an unused graph', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-agent-graph-epoch-'));
const path = join(root, 'state.sqlite');
try {
const store = createSqliteSessionMetadataStore(path, { now: () => 100 });
assert.deepEqual(
await store.resolveCurrentAgentGraphEpoch({
rootSessionId: 'root-1',
legacyGraphId: 'agent_graph_legacy',
}),
{
schemaVersion: 1,
rootSessionId: 'root-1',
epoch: 1,
graphId: 'agent_graph_legacy',
createdAt: 0,
},
);
assert.deepEqual(await store.listAgentGraphEpochs('root-1'), []);
store.close();
const reopened = createSqliteSessionMetadataStore(path, { now: () => 200 });
assert.deepEqual(
await reopened.resolveCurrentAgentGraphEpoch({
rootSessionId: 'root-1',
legacyGraphId: 'agent_graph_legacy',
}),
{
schemaVersion: 1,
rootSessionId: 'root-1',
epoch: 1,
graphId: 'agent_graph_legacy',
createdAt: 0,
},
);
reopened.close();
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('advances with compare-and-swap semantics and makes retries idempotent', async () => {
const store = createSqliteSessionMetadataStore(':memory:', { now: nextNow(100) });
await store.resolveCurrentAgentGraphEpoch({
rootSessionId: 'root-1',
legacyGraphId: 'agent_graph_1',
});
const request = {
rootSessionId: 'root-1',
expectedEpoch: 1,
expectedGraphId: 'agent_graph_1',
nextGraphId: 'agent_graph_2',
} as const;
assert.equal((await store.advanceAgentGraphEpoch(request)).graphId, 'agent_graph_2');
assert.equal((await store.advanceAgentGraphEpoch(request)).graphId, 'agent_graph_2');
assert.deepEqual(
(await store.listAgentGraphEpochs('root-1')).map(({ epoch, graphId }) => ({
epoch,
graphId,
})),
[
{ epoch: 1, graphId: 'agent_graph_1' },
{ epoch: 2, graphId: 'agent_graph_2' },
],
);
assert.equal((await store.readAgentGraphEpochByGraphId('agent_graph_1'))?.epoch, 1);
assert.deepEqual(await store.listAgentGraphEpochPage({ rootSessionId: 'root-1', limit: 1 }), {
epochs: [
{
schemaVersion: 1,
rootSessionId: 'root-1',
epoch: 2,
graphId: 'agent_graph_2',
createdAt: 100,
},
],
nextBeforeEpoch: 2,
currentEpoch: 2,
});
assert.deepEqual(
await store.listAgentGraphEpochPage({
rootSessionId: 'root-1',
beforeEpoch: 2,
limit: 1,
}),
{
epochs: [
{
schemaVersion: 1,
rootSessionId: 'root-1',
epoch: 1,
graphId: 'agent_graph_1',
createdAt: 0,
},
],
nextBeforeEpoch: null,
currentEpoch: 2,
},
);
// A root Session without durable rows reports no current epoch, letting the
// caller fall back to the legacy virtual identity.
assert.deepEqual(await store.listAgentGraphEpochPage({ rootSessionId: 'root-2', limit: 1 }), {
epochs: [],
nextBeforeEpoch: null,
currentEpoch: null,
});
store.close();
});
test('rejects stale writers and graph identities already bound elsewhere', async () => {
const store = createSqliteSessionMetadataStore(':memory:');
await store.resolveCurrentAgentGraphEpoch({
rootSessionId: 'root-1',
legacyGraphId: 'agent_graph_1',
});
await store.advanceAgentGraphEpoch({
rootSessionId: 'root-1',
expectedEpoch: 1,
expectedGraphId: 'agent_graph_1',
nextGraphId: 'agent_graph_2',
});
await assert.rejects(
() =>
store.advanceAgentGraphEpoch({
rootSessionId: 'root-1',
expectedEpoch: 1,
expectedGraphId: 'agent_graph_1',
nextGraphId: 'agent_graph_competing',
}),
AgentGraphEpochConflictError,
);
await assert.rejects(
() =>
store.resolveCurrentAgentGraphEpoch({
rootSessionId: 'root-2',
legacyGraphId: 'agent_graph_2',
}),
AgentGraphEpochConflictError,
);
store.close();
});
test('rejects a drifted legacy identity after adoption', async () => {
const store = createSqliteSessionMetadataStore(':memory:');
await store.resolveCurrentAgentGraphEpoch({
rootSessionId: 'root-1',
legacyGraphId: 'agent_graph_1',
});
await store.advanceAgentGraphEpoch({
rootSessionId: 'root-1',
expectedEpoch: 1,
expectedGraphId: 'agent_graph_1',
nextGraphId: 'agent_graph_2',
});
await assert.rejects(
() =>
store.resolveCurrentAgentGraphEpoch({
rootSessionId: 'root-1',
legacyGraphId: 'agent_graph_other',
}),
AgentGraphEpochConflictError,
);
store.close();
});
test('retains the epoch directory until root-scoped retirement cleanup commits', async () => {
const store = createSqliteSessionMetadataStore(':memory:');
await store.advanceAgentGraphEpoch({
rootSessionId: 'root-1',
expectedEpoch: 1,
expectedGraphId: 'agent_graph_1',
nextGraphId: 'agent_graph_2',
});
await store.purgeAgentGraphControlState('agent_graph_1');
assert.deepEqual(
(await store.listAgentGraphEpochs('root-1')).map(({ graphId }) => graphId),
['agent_graph_1', 'agent_graph_2'],
);
assert.equal(await store.purgeAgentGraphEpochs('root-1'), 2);
assert.deepEqual(await store.listAgentGraphEpochs('root-1'), []);
assert.equal(await store.purgeAgentGraphEpochs('root-1'), 0);
store.close();
});
});
function nextNow(start: number): () => number {
let value = start;
return () => value++;
}
@@ -0,0 +1,173 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { DatabaseSync } from 'node:sqlite';
import { AGENT_GRAPH_INTENT_CLAIM_SCHEMA_VERSION } from '@maka/core/agent-graph-control';
import {
AgentGraphIntentClaimConflictError,
createSqliteSessionMetadataStore,
SQLITE_SESSION_METADATA_SCHEMA_VERSION,
} from '../sqlite-session-metadata-store.js';
describe('SQLite agent graph intent claims', () => {
test('atomically allocates one stable activation identity per intent', async () => {
const store = createSqliteSessionMetadataStore(':memory:', { now: () => 42 });
try {
const first = await store.claimAgentGraphIntent(request());
const retry = await store.claimAgentGraphIntent(
request({ targetTurnId: 'discarded-turn', targetRunId: 'discarded-run' }),
);
assert.equal(first.created, true);
assert.equal(retry.created, false);
assert.deepEqual(retry.claim, first.claim);
assert.equal(retry.claim.targetTurnId, 'turn-next');
assert.equal(retry.claim.targetRunId, 'run-next');
assert.deepEqual(await store.readAgentGraphIntentClaim('graph-1', request().intentId), {
...request(),
claimedAt: 42,
});
assert.deepEqual(await store.listAgentGraphIntentClaims('graph-1'), [first.claim]);
} finally {
store.close();
}
});
test('rejects reused intent and activation identities with different semantics', async () => {
const store = createSqliteSessionMetadataStore(':memory:');
try {
await store.claimAgentGraphIntent(request());
await assert.rejects(
store.claimAgentGraphIntent(request({ intentFingerprint: `sha256:${'e'.repeat(64)}` })),
AgentGraphIntentClaimConflictError,
);
await assert.rejects(
store.claimAgentGraphIntent(
request({
claimId: `graph_claim_${'f'.repeat(32)}`,
intentId: `graph_intent_${'e'.repeat(32)}`,
}),
),
AgentGraphIntentClaimConflictError,
);
await assert.rejects(
store.claimAgentGraphIntent(
request({
claimId: `graph_claim_${'1'.repeat(32)}`,
intentId: `graph_intent_${'2'.repeat(32)}`,
targetRunId: 'different-run',
}),
),
AgentGraphIntentClaimConflictError,
);
assert.equal((await store.listAgentGraphIntentClaims()).length, 1);
} finally {
store.close();
}
});
test('rolls back a claim when the transaction fails before commit', async () => {
const store = createSqliteSessionMetadataStore(':memory:', {
failpoint(point) {
if (point === 'after_agent_graph_intent_claim_write') throw new Error('crash');
},
});
try {
await assert.rejects(store.claimAgentGraphIntent(request()), /crash/);
assert.deepEqual(await store.listAgentGraphIntentClaims(), []);
} finally {
store.close();
}
});
test('atomically transitions claimed work to executing or cancelled', async () => {
const store = createSqliteSessionMetadataStore(':memory:', { now: nextNumber(50) });
try {
await store.claimAgentGraphIntent(request());
assert.deepEqual(
await store.beginAgentGraphIntentExecutionAtScheduleRevision(
'graph-1',
request().intentId,
0,
),
{
state: 'executing',
previousState: 'claimed',
changed: true,
},
);
assert.deepEqual(
await store.cancelAgentGraphIntentExecution(
'graph-1',
request().intentId,
'Supervisor stopped the work.',
),
{
state: 'cancelled',
previousState: 'executing',
changed: true,
},
);
assert.deepEqual(
await store.beginAgentGraphIntentExecutionAtScheduleRevision(
'graph-1',
request().intentId,
0,
),
{
state: 'cancelled',
previousState: 'cancelled',
changed: false,
},
);
} finally {
store.close();
}
});
});
function request(
overrides: Partial<ReturnType<typeof baseRequest>> = {},
): ReturnType<typeof baseRequest> {
return { ...baseRequest(), ...overrides };
}
function baseRequest() {
return {
schemaVersion: AGENT_GRAPH_INTENT_CLAIM_SCHEMA_VERSION,
claimId: `graph_claim_${'a'.repeat(32)}`,
graphId: 'graph-1',
intentId: `graph_intent_${'b'.repeat(32)}`,
intentFingerprint: `sha256:${'c'.repeat(64)}`,
readinessContextFingerprint: `sha256:${'d'.repeat(64)}`,
targetOperatorId: 'summarizer',
targetSessionId: 'session-child',
targetTurnId: 'turn-next',
targetRunId: 'run-next',
};
}
function nextNumber(start: number): () => number {
let value = start;
return () => value++;
}
@@ -0,0 +1,270 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import {
AGENT_GRAPH_SCHEDULE_UPDATE_SCHEMA_VERSION,
AgentGraphScheduleClosedError,
AgentGraphScheduleRevisionConflictError,
type AgentGraphScheduleUpdateRequest,
} from '@maka/core/agent-graph-schedule';
import {
AGENT_GRAPH_INTENT_CLAIM_SCHEMA_VERSION,
type AgentGraphIntentClaimRequest,
} from '@maka/core/agent-graph-control';
import {
AgentGraphScheduleUpdateConflictError,
createSqliteSessionMetadataStore,
} from '../sqlite-session-metadata-store.js';
describe('SQLite agent graph schedule updates', () => {
test('commits ordered idempotent updates and closes the schedule atomically', async () => {
const store = createSqliteSessionMetadataStore(':memory:', { now: nextNumber(40) });
try {
const first = await store.commitAgentGraphScheduleUpdate(request());
const retry = await store.commitAgentGraphScheduleUpdate(request());
const finish = await store.commitAgentGraphScheduleUpdate(
request({
updateId: `graph_update_${'d'.repeat(32)}`,
updateFingerprint: `sha256:${'e'.repeat(64)}`,
source: {
sessionId: 'session-main',
runId: 'run-main',
turnId: 'turn-main',
toolCallId: 'tool-finish',
},
addWork: [],
stop: [{ targetId: first.update.addWork[0]!.workId, reason: 'evidence is sufficient' }],
finish: { resultIds: ['result-1'], reason: 'accept the verified result' },
}),
);
assert.equal(first.created, true);
assert.equal(retry.created, false);
assert.deepEqual(retry.update, first.update);
assert.equal(first.update.revision, 1);
assert.equal(finish.update.revision, 2);
assert.deepEqual(await store.listAgentGraphScheduleUpdates('graph-1'), [
first.update,
finish.update,
]);
await assert.rejects(
store.commitAgentGraphScheduleUpdate(
request({
updateId: `graph_update_${'f'.repeat(32)}`,
updateFingerprint: `sha256:${'1'.repeat(64)}`,
source: {
sessionId: 'session-main',
runId: 'run-main',
turnId: 'turn-later',
toolCallId: 'tool-later',
},
}),
),
/already finished/,
);
} finally {
store.close();
}
});
test('rejects tool-call and update identities reused for different work', async () => {
const store = createSqliteSessionMetadataStore(':memory:');
try {
await store.commitAgentGraphScheduleUpdate(request());
await assert.rejects(
store.commitAgentGraphScheduleUpdate(
request({
updateFingerprint: `sha256:${'9'.repeat(64)}`,
addWork: [
{
...request().addWork[0]!,
instruction: 'Perform different work.',
},
],
}),
),
AgentGraphScheduleUpdateConflictError,
);
await assert.rejects(
store.commitAgentGraphScheduleUpdate(
request({
updateId: `graph_update_${'7'.repeat(32)}`,
updateFingerprint: `sha256:${'8'.repeat(64)}`,
}),
),
AgentGraphScheduleUpdateConflictError,
);
assert.equal((await store.listAgentGraphScheduleUpdates('graph-1')).length, 1);
} finally {
store.close();
}
});
test('rolls back an update when the transaction fails before commit', async () => {
const store = createSqliteSessionMetadataStore(':memory:', {
failpoint(point) {
if (point === 'after_agent_graph_schedule_update_write') throw new Error('crash');
},
});
try {
await assert.rejects(store.commitAgentGraphScheduleUpdate(request()), /crash/);
assert.deepEqual(await store.listAgentGraphScheduleUpdates('graph-1'), []);
} finally {
store.close();
}
});
test('replays the same schedule after reopening the workspace database', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-agent-graph-schedule-'));
const path = join(root, 'state.sqlite');
try {
const store = createSqliteSessionMetadataStore(path, { now: () => 77 });
const committed = await store.commitAgentGraphScheduleUpdate(request());
store.close();
const reopened = createSqliteSessionMetadataStore(path);
try {
assert.deepEqual(await reopened.listAgentGraphScheduleUpdates('graph-1'), [
committed.update,
]);
} finally {
reopened.close();
}
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('linearizes scheduled admission against revision changes and closure', async () => {
const store = createSqliteSessionMetadataStore(':memory:', { now: nextNumber(90) });
try {
await store.commitAgentGraphScheduleUpdate(request());
const first = await store.claimAgentGraphIntentAtScheduleRevision(claimRequest(), 1);
assert.equal(first.created, true);
await store.commitAgentGraphScheduleUpdate(
request({
updateId: `graph_update_${'d'.repeat(32)}`,
updateFingerprint: `sha256:${'e'.repeat(64)}`,
source: {
sessionId: 'session-main',
runId: 'run-main',
turnId: 'turn-finish',
toolCallId: 'tool-finish',
},
addWork: [],
stop: [],
finish: { resultIds: ['result-1'], reason: 'accept the result' },
}),
);
await assert.rejects(
store.claimAgentGraphIntentAtScheduleRevision(
{
...claimRequest(),
claimId: `graph_claim_${'d'.repeat(32)}`,
intentId: `graph_intent_${'e'.repeat(32)}`,
targetTurnId: 'turn-2',
targetRunId: 'run-2',
},
1,
),
(error: unknown) =>
error instanceof AgentGraphScheduleRevisionConflictError && error.currentRevision === 2,
);
assert.equal(
(
await store.claimAgentGraphIntentAtScheduleRevision(
{ ...claimRequest(), targetTurnId: 'discarded', targetRunId: 'discarded' },
2,
)
).created,
false,
);
await assert.rejects(
store.claimAgentGraphIntentAtScheduleRevision(
{
...claimRequest(),
claimId: `graph_claim_${'d'.repeat(32)}`,
intentId: `graph_intent_${'e'.repeat(32)}`,
targetTurnId: 'turn-2',
targetRunId: 'run-2',
},
2,
),
AgentGraphScheduleClosedError,
);
assert.equal((await store.listAgentGraphIntentClaims('graph-1')).length, 1);
} finally {
store.close();
}
});
});
function request(
overrides: Partial<AgentGraphScheduleUpdateRequest> = {},
): AgentGraphScheduleUpdateRequest {
return {
schemaVersion: AGENT_GRAPH_SCHEDULE_UPDATE_SCHEMA_VERSION,
updateId: `graph_update_${'a'.repeat(32)}`,
updateFingerprint: `sha256:${'b'.repeat(64)}`,
graphId: 'graph-1',
source: {
sessionId: 'session-main',
runId: 'run-main',
turnId: 'turn-main',
toolCallId: 'tool-main',
},
addWork: [
{
workId: `graph_work_${'c'.repeat(32)}`,
target: { kind: 'agent', agentId: 'fact-checker' },
instruction: 'Verify the selected evidence.',
inputIds: ['result-1'],
},
],
stop: [],
...overrides,
};
}
function nextNumber(start: number): () => number {
let value = start;
return () => value++;
}
function claimRequest(): AgentGraphIntentClaimRequest {
return {
schemaVersion: AGENT_GRAPH_INTENT_CLAIM_SCHEMA_VERSION,
claimId: `graph_claim_${'a'.repeat(32)}`,
graphId: 'graph-1',
intentId: `graph_intent_${'b'.repeat(32)}`,
intentFingerprint: `sha256:${'c'.repeat(64)}`,
readinessContextFingerprint: `sha256:${'d'.repeat(64)}`,
targetOperatorId: 'writer',
targetSessionId: 'session-writer',
targetTurnId: 'turn-1',
targetRunId: 'run-1',
};
}
@@ -0,0 +1,135 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import type { RootExecutionDescriptor } from '@maka/core/agent-run';
import { createSqliteAgentRunStore, type AdmitRootTurnInput } from '../agent-run-store.js';
test('Agent Graph supervisor admission durably binds wake identity and Graph orchestration', async () => {
await withTempRoot(async (_root, openStore) => {
const store = openStore();
const admitted = await store.admitRootTurn(admissionInput());
assert.equal(admitted.kind, 'admitted');
assert.deepEqual(admitted.admission.execution, admissionInput().execution);
assert.deepEqual(admitted.admission.turnOrchestration, {
mode: 'graph',
source: 'host_api',
});
const reopened = openStore();
assert.deepEqual(
await reopened.readRootTurnAdmission('root-session', 'supervisor-turn'),
admitted.admission,
);
});
});
test('Agent Graph supervisor admission rejects malformed identity and non-Graph orchestration', async () => {
await withTempRoot(async (_root, openStore) => {
const store = openStore();
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
execution: {
...admissionInput().execution,
wakeId: ' wake ',
} as RootExecutionDescriptor,
}),
),
/Invalid root execution descriptor/,
);
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
turnOrchestration: { mode: 'swarm', source: 'host_api' },
}),
),
/requires Host Graph orchestration/,
);
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
execution: {
...admissionInput().execution,
wakeId: 'agent_graph_ffffffffffffffffffffffffffffffff:snapshot-1',
} as RootExecutionDescriptor,
}),
),
/Invalid root execution descriptor/,
);
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
turnOrchestration: undefined,
}),
),
/requires Host Graph orchestration/,
);
});
});
function admissionInput(overrides: Partial<AdmitRootTurnInput> = {}): AdmitRootTurnInput {
return {
sessionId: 'root-session',
turnId: 'supervisor-turn',
proposedRunId: 'supervisor-run',
proposedUserMessageId: 'supervisor-message',
execution: {
kind: 'agent_graph_supervisor_wake',
graphId: 'agent_graph_0123456789abcdef0123456789abcdef',
wakeId: 'agent_graph_0123456789abcdef0123456789abcdef:snapshot-1',
attemptId: 'attempt-1',
},
previousRootTurnId: null,
normalizedInput: { text: 'Inspect the durable graph.' },
turnOrchestration: { mode: 'graph', source: 'host_api' },
sourceMessages: [],
admittedAt: 50,
...overrides,
};
}
async function withTempRoot(
run: (
root: string,
openStore: () => ReturnType<typeof createSqliteAgentRunStore>,
) => Promise<void>,
): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-graph-supervisor-admission-'));
const stores: ReturnType<typeof createSqliteAgentRunStore>[] = [];
try {
await run(root, () => {
const store = createSqliteAgentRunStore(root);
stores.push(store);
return store;
});
} finally {
for (const store of stores.reverse()) store.close?.();
await rm(root, { recursive: true, force: true });
}
}
@@ -0,0 +1,222 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { DatabaseSync } from 'node:sqlite';
import { describe, test } from 'node:test';
import { AGENT_GRAPH_SUPERVISOR_WAKE_SCHEMA_VERSION } from '@maka/core/agent-graph-supervisor-wake';
import {
createSqliteSessionMetadataStore,
SQLITE_SESSION_METADATA_SCHEMA_VERSION,
} from '../sqlite-session-metadata-store.js';
describe('SQLite Agent Graph supervisor wakes', () => {
test('tracks retry attempts separately and marks delivery only after completion', async () => {
let now = 10;
const store = createSqliteSessionMetadataStore(':memory:', { now: () => now++ });
try {
const claim = await store.claimAgentGraphSupervisorWake({
schemaVersion: AGENT_GRAPH_SUPERVISOR_WAKE_SCHEMA_VERSION,
graphId: 'graph-1',
wakeId: 'wake-1',
snapshotVersion: 'snapshot-1',
rootSessionId: 'session-1',
});
assert.equal(claim.created, true);
assert.equal(claim.wake.status, 'pending');
const first = await store.beginAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-1',
attemptId: 'attempt-1',
turnId: 'turn-1',
});
assert.equal(first.acquired, true);
assert.equal(first.wake.status, 'running');
assert.equal(first.wake.attemptCount, 1);
await store.completeAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-1',
attemptId: 'attempt-1',
status: 'retryable_failed',
failureReason: 'provider failed after prompt persistence',
});
const second = await store.beginAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-1',
attemptId: 'attempt-2',
turnId: 'turn-2',
});
assert.equal(second.acquired, true);
assert.equal(second.wake.attemptCount, 2);
const parked = await store.completeAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-1',
attemptId: 'attempt-2',
status: 'waiting_permission',
});
assert.equal(parked.status, 'waiting_permission');
assert.equal(
(await store.listAgentGraphSupervisorWakeAttempts('graph-1', 'wake-1'))[1]?.completedAt,
undefined,
);
assert.equal(
(
await store.beginAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-1',
attemptId: 'attempt-3',
turnId: 'turn-3',
})
).acquired,
false,
);
const delivered = await store.completeAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-1',
attemptId: 'attempt-2',
status: 'delivered',
});
assert.equal(delivered.status, 'delivered');
assert.deepEqual(
(await store.listAgentGraphSupervisorWakeAttempts('graph-1', 'wake-1')).map(
(attempt) => attempt.status,
),
['retryable_failed', 'delivered'],
);
assert.equal(
(
await store.beginAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-1',
attemptId: 'attempt-3',
turnId: 'turn-3',
})
).acquired,
false,
);
} finally {
store.close();
}
});
test('recovers pre-run pending wakes without guessing the AgentRun state', async () => {
let now = 20;
const store = createSqliteSessionMetadataStore(':memory:', { now: () => now++ });
try {
await store.claimAgentGraphSupervisorWake({
schemaVersion: AGENT_GRAPH_SUPERVISOR_WAKE_SCHEMA_VERSION,
graphId: 'graph-pending',
wakeId: 'wake-pending',
snapshotVersion: 'snapshot-pending',
rootSessionId: 'session-pending',
});
await store.claimAgentGraphSupervisorWake({
schemaVersion: AGENT_GRAPH_SUPERVISOR_WAKE_SCHEMA_VERSION,
graphId: 'graph-running',
wakeId: 'wake-running',
snapshotVersion: 'snapshot-running',
rootSessionId: 'session-running',
});
await store.beginAgentGraphSupervisorWakeAttempt({
graphId: 'graph-running',
wakeId: 'wake-running',
attemptId: 'attempt-running',
turnId: 'turn-running',
});
assert.equal(await store.recoverAgentGraphSupervisorWakes(), 1);
assert.equal(
(await store.readAgentGraphSupervisorWake('graph-pending', 'wake-pending'))?.status,
'retryable_failed',
);
assert.equal(
(await store.readAgentGraphSupervisorWake('graph-running', 'wake-running'))?.status,
'running',
);
assert.equal(
(await store.listAgentGraphSupervisorWakeAttempts('graph-running', 'wake-running'))[0]
?.failureReason,
undefined,
);
assert.deepEqual(
(await store.listUnsettledAgentGraphSupervisorWakes()).map((wake) => wake.wakeId),
['wake-running'],
);
} finally {
store.close();
}
});
test('terminally supersedes only non-delivered wakes for retired Sessions', async () => {
const store = createSqliteSessionMetadataStore(':memory:');
try {
for (const wakeId of ['wake-pending', 'wake-running', 'wake-delivered']) {
await store.claimAgentGraphSupervisorWake({
schemaVersion: AGENT_GRAPH_SUPERVISOR_WAKE_SCHEMA_VERSION,
graphId: 'graph-1',
wakeId,
snapshotVersion: wakeId,
rootSessionId: 'session-1',
});
}
for (const wakeId of ['wake-running', 'wake-delivered']) {
await store.beginAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId,
attemptId: `${wakeId}-attempt`,
turnId: `${wakeId}-turn`,
});
}
await store.completeAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-delivered',
attemptId: 'wake-delivered-attempt',
status: 'delivered',
});
assert.equal(
await store.supersedeAgentGraphSupervisorWakes({
rootSessionIds: ['session-1'],
reason: 'session_retired',
}),
2,
);
assert.equal(
(await store.readAgentGraphSupervisorWake('graph-1', 'wake-pending'))?.status,
'superseded',
);
assert.equal(
(await store.listAgentGraphSupervisorWakeAttempts('graph-1', 'wake-running'))[0]?.status,
'superseded',
);
assert.equal(
(await store.readAgentGraphSupervisorWake('graph-1', 'wake-delivered'))?.status,
'delivered',
);
assert.deepEqual(await store.listRetryableAgentGraphSupervisorWakes(), []);
} finally {
store.close();
}
});
});
@@ -0,0 +1,136 @@
/*
* 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 assert from 'node:assert/strict';
import { describe, test } from 'node:test';
import { AGENT_GRAPH_INTENT_CLAIM_SCHEMA_VERSION } from '@maka/core/agent-graph-control';
import { AGENT_GRAPH_SCHEDULE_UPDATE_SCHEMA_VERSION } from '@maka/core/agent-graph-schedule';
import { AGENT_GRAPH_SUPERVISOR_WAKE_SCHEMA_VERSION } from '@maka/core/agent-graph-supervisor-wake';
import { createSqliteSessionMetadataStore } from '../sqlite-session-metadata-store.js';
describe('SQLite agent graph timeline metadata', () => {
test('reads one graph control-plane snapshot with current admission and wake attempts', async () => {
let now = 100;
const store = createSqliteSessionMetadataStore(':memory:', { now: () => now++ });
try {
await store.commitAgentGraphScheduleUpdate({
schemaVersion: AGENT_GRAPH_SCHEDULE_UPDATE_SCHEMA_VERSION,
updateId: `graph_update_${'a'.repeat(32)}`,
updateFingerprint: `sha256:${'b'.repeat(64)}`,
graphId: 'graph-1',
source: {
sessionId: 'root-session',
runId: 'root-run',
turnId: 'root-turn',
toolCallId: 'schedule-call',
},
addWork: [
{
workId: `graph_work_${'c'.repeat(32)}`,
target: { kind: 'operator', operatorId: 'operator-1' },
instruction: 'Sensitive schedule instruction.',
inputIds: [],
},
],
stop: [],
});
await store.claimAgentGraphIntentAtScheduleRevision(
{
schemaVersion: AGENT_GRAPH_INTENT_CLAIM_SCHEMA_VERSION,
claimId: `graph_claim_${'d'.repeat(32)}`,
graphId: 'graph-1',
intentId: `graph_intent_${'e'.repeat(32)}`,
intentFingerprint: `sha256:${'f'.repeat(64)}`,
readinessContextFingerprint: `sha256:${'1'.repeat(64)}`,
targetOperatorId: 'operator-1',
targetSessionId: 'child-session',
targetTurnId: 'child-turn',
targetRunId: 'child-run',
},
1,
);
await store.beginAgentGraphIntentExecutionAtScheduleRevision(
'graph-1',
`graph_intent_${'e'.repeat(32)}`,
1,
);
await store.claimAgentGraphSupervisorWake({
schemaVersion: AGENT_GRAPH_SUPERVISOR_WAKE_SCHEMA_VERSION,
graphId: 'graph-1',
wakeId: 'wake-1',
snapshotVersion: 'snapshot-1',
rootSessionId: 'root-session',
});
await store.beginAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-1',
attemptId: 'attempt-1',
turnId: 'wake-turn',
});
await store.completeAgentGraphSupervisorWakeAttempt({
graphId: 'graph-1',
wakeId: 'wake-1',
attemptId: 'attempt-1',
status: 'delivered',
});
const snapshot = await store.readAgentGraphTimelineMetadata('graph-1');
assert.equal(snapshot.graphId, 'graph-1');
assert.equal(snapshot.scheduleUpdates.length, 1);
assert.equal(snapshot.operatorProvisions.length, 0);
assert.equal(snapshot.intentClaims.length, 1);
assert.deepEqual(snapshot.intentAdmissions, [
{
graphId: 'graph-1',
intentId: `graph_intent_${'e'.repeat(32)}`,
state: 'executing',
updatedAt: 102,
},
]);
assert.equal(snapshot.supervisorWakes.length, 1);
assert.equal(snapshot.supervisorWakes[0]?.wake.status, 'delivered');
assert.deepEqual(
snapshot.supervisorWakes[0]?.attempts.map((attempt) => ({
attemptId: attempt.attemptId,
status: attempt.status,
startedAt: attempt.startedAt,
completedAt: attempt.completedAt,
})),
[
{
attemptId: 'attempt-1',
status: 'delivered',
startedAt: 104,
completedAt: 105,
},
],
);
assert.deepEqual(await store.readAgentGraphTimelineMetadata('another-graph'), {
graphId: 'another-graph',
scheduleUpdates: [],
operatorProvisions: [],
intentClaims: [],
intentAdmissions: [],
supervisorWakes: [],
});
} finally {
store.close();
}
});
});
@@ -0,0 +1,363 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { MAX_ATTACHMENT_BYTES } from '@maka/core/attachments';
import type { ReadImageSnapshotReader } from '@maka/core/context-offload';
import { type StorageRef } from '@maka/core/events';
import {
createArtifactAttachmentResourceReader,
createAttachmentByteReader,
createReadImageSnapshotPlanner,
createReadImageSnapshotter,
} from '../artifact-attachments.js';
import {
createSqliteArtifactStoreWriteAuthority,
type ArtifactAuthorityStore,
} from '../artifact-store.js';
const png = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
describe('artifact attachment authority', () => {
test('reads only live user-uploaded text within the invoking Session', async () => {
await withStore(async (store) => {
await store.create({
id: 'notes-1',
sessionId: 'session-1',
turnId: 'turn-1',
name: 'notes.txt',
kind: 'file',
content: 'attachment marker',
mimeType: 'text/plain',
source: 'user_upload',
now: 1,
});
const reader = createArtifactAttachmentResourceReader({ artifactStore: store });
const signal = new AbortController().signal;
assert.deepEqual(await reader.readAttachmentResource('session-1', 'notes-1', signal), {
kind: 'text',
text: 'attachment marker',
});
await assert.rejects(
reader.readAttachmentResource('session-2', 'notes-1', signal),
/not found in this Session/,
);
await store.delete('notes-1');
await assert.rejects(
reader.readAttachmentResource('session-1', 'notes-1', signal),
/not found in this Session/,
);
});
});
test('resolves a live session ref and never forwards tombstoned bytes', async () => {
await withStore(async (store) => {
await store.create({
id: 'image-1',
sessionId: 'session-1',
turnId: 'turn-1',
name: 'image.png',
kind: 'image',
content: png,
now: 1,
});
const reader = createAttachmentByteReader({
artifactStore: store,
sessionId: 'session-1',
});
assert.deepEqual(await reader(sessionFileRef('image-1')), {
ok: true,
bytes: Buffer.from(png),
});
await store.delete('image-1');
assert.deepEqual(await reader(sessionFileRef('image-1')), {
ok: false,
reason: 'deleted',
});
assert.deepEqual(await reader(sessionFileRef('image-1', 'other-session')), {
ok: false,
reason: 'session_mismatch',
});
});
});
test('rejects unsupported refs and applies the shared byte limit inside authority', async () => {
await withStore(async (store) => {
await store.create({
id: 'large-image',
sessionId: 'session-1',
turnId: 'turn-1',
name: 'large.png',
kind: 'image',
content: new Uint8Array(MAX_ATTACHMENT_BYTES + 1).fill(0x89),
now: 1,
});
const reader = createAttachmentByteReader({
artifactStore: store,
sessionId: 'session-1',
});
assert.deepEqual(await reader({ kind: 'workspace_file', relativePath: 'image.png' }), {
ok: false,
reason: 'unsupported_ref_kind',
});
assert.deepEqual(await reader(sessionFileRef('large-image')), {
ok: false,
reason: 'too_large',
});
const unavailableReader = createAttachmentByteReader({
artifactStore: store,
sessionId: 'session-1',
readImageSnapshotsUnavailable: true,
});
assert.deepEqual(await unavailableReader(sessionContextRef('ref-1')), {
ok: false,
reason: 'unavailable',
});
});
});
test('routes durable context refs through the Session-bound snapshot reader', async () => {
await withStore(async (store) => {
const reads: string[] = [];
const readImageSnapshots: ReadImageSnapshotReader = {
async read(ref) {
reads.push(ref.refId);
if (ref.refId === 'missing') return { ok: false, reason: 'not_found' };
return {
ok: true,
record: {
refId: ref.refId,
sessionId: ref.sessionId,
owner: { kind: 'read_image_snapshot', ownerId: 'owner-1' },
blobId: 'a'.repeat(64),
sizeBytes: png.byteLength,
mediaType: 'image/png',
createdAt: 1,
},
bytes: png,
};
},
};
const reader = createAttachmentByteReader({
artifactStore: store,
sessionId: 'session-1',
readImageSnapshots,
});
assert.deepEqual(await reader(sessionContextRef('ref-1')), {
ok: true,
bytes: png,
});
assert.deepEqual(await reader(sessionContextRef('missing')), {
ok: false,
reason: 'not_found',
});
assert.deepEqual(await reader(sessionContextRef('ref-2', 'other-session')), {
ok: false,
reason: 'session_mismatch',
});
assert.deepEqual(reads, ['ref-1', 'missing']);
});
});
test('passes through real store not-found and unsupported-mime failures', async () => {
await withStore(async (store) => {
const reader = createAttachmentByteReader({
artifactStore: store,
sessionId: 'session-1',
});
assert.deepEqual(await reader(sessionFileRef('missing')), {
ok: false,
reason: 'not_found',
});
await store.create({
id: 'unknown-binary',
sessionId: 'session-1',
turnId: 'turn-1',
name: 'unknown.bin',
kind: 'file',
content: Uint8Array.from([0, 1, 2, 3]),
now: 1,
});
assert.deepEqual(await reader(sessionFileRef('unknown-binary')), {
ok: false,
reason: 'unsupported_mime',
});
});
});
test('snapshotter rejects provider-unsafe images before publication', async () => {
await withStore(async (store) => {
await assert.rejects(
createReadImageSnapshotter(store)({
sessionId: 'session-1',
turnId: 'turn-1',
name: 'large.png',
bytes: new Uint8Array(5 * 1024 * 1024 + 1),
mimeType: 'image/png',
}),
/Image exceeds the 5MB model input limit/,
);
assert.deepEqual(await store.list('session-1'), []);
});
});
test('snapshotter reuses one content-addressed artifact for the same turn image', async () => {
await withStore(async (store) => {
const snapshot = createReadImageSnapshotter(store);
const input = {
sessionId: 'session-1',
turnId: 'turn-1',
name: 'Tool Result image',
bytes: Uint8Array.from([1, 2, 3]),
mimeType: 'image/png',
};
const first = await snapshot(input);
const repeated = await snapshot(input);
assert.deepEqual(repeated, first);
assert.equal((await store.list('session-1')).length, 1);
});
});
test('keeps a durable projection image live when a user requests deletion', async () => {
await withStore(async (store) => {
const ref = await createReadImageSnapshotter(store)({
sessionId: 'session-1',
turnId: 'turn-1',
name: 'Tool Result image',
bytes: png,
mimeType: 'image/png',
});
assert.deepEqual(await store.deleteUserArtifactInSession('session-1', ref.relativePath), {
kind: 'protected',
});
assert.deepEqual(await store.readBinary(ref.relativePath), {
ok: true,
base64: Buffer.from(png).toString('base64'),
mimeType: 'image/png',
});
});
});
test('planner derives the final ref without publishing before commit', async () => {
await withStore(async (store) => {
const bytes = png.slice();
const input = {
sessionId: 'session-1',
turnId: 'turn-1',
name: 'Tool Result image',
bytes,
mimeType: 'image/png',
};
const plan = createReadImageSnapshotPlanner(store)(input);
assert.deepEqual(await store.list('session-1'), []);
bytes[0] = 0;
input.name = 'mutated after prepare';
await Promise.all([plan.persist(), plan.persist()]);
const published = await store.list('session-1');
assert.deepEqual(
published.map((artifact) => artifact.id),
[plan.ref.relativePath],
);
assert.equal(published[0]?.name, 'Tool Result image');
assert.deepEqual(await store.readBinary(plan.ref.relativePath), {
ok: true,
base64: Buffer.from(png).toString('base64'),
mimeType: 'image/png',
});
});
});
test('retraction reclaims only what the retracting plan published', async () => {
await withStore(async (store) => {
const input = {
sessionId: 'session-1',
turnId: 'turn-1',
name: 'Tool Result image',
bytes: png.slice(),
mimeType: 'image/png',
};
const deleted: string[] = [];
// The id is derived from the bytes, so a second projection for the same
// image in the same Turn gets the first one's record back. Retracting the
// second must not delete the artifact the first one committed.
const owned = {
create: (createInput: Parameters<typeof store.create>[0]) => store.create(createInput),
createOwned: async (createInput: Parameters<typeof store.create>[0]) => {
const existing = createInput.id
? await store.getInSession(createInput.sessionId, createInput.id)
: undefined;
const record = await store.create(createInput);
return { record, publishedByThisCall: !existing?.record };
},
};
const planner = createReadImageSnapshotPlanner(owned, async (_sessionId, artifactId) => {
deleted.push(artifactId);
await store.delete(artifactId);
});
const first = planner(input);
await first.persist();
const second = planner(input);
await second.persist();
assert.equal(second.ref.relativePath, first.ref.relativePath);
await second.retract();
assert.deepEqual(deleted, []);
assert.equal((await store.readBinary(first.ref.relativePath)).ok, true);
await first.retract();
assert.deepEqual(deleted, [first.ref.relativePath]);
assert.equal((await store.readBinary(first.ref.relativePath)).ok, false);
});
});
});
function sessionFileRef(relativePath: string, sessionId = 'session-1'): StorageRef {
return { kind: 'session_file', sessionId, relativePath };
}
function sessionContextRef(refId: string, sessionId = 'session-1'): StorageRef {
return { kind: 'session_context', sessionId, refId };
}
async function withStore(run: (store: ArtifactAuthorityStore) => Promise<void>): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-artifact-attachment-'));
const authority = createSqliteArtifactStoreWriteAuthority(root);
try {
await authority.recover();
const { store } = authority;
await run(store);
} finally {
authority.close();
await rm(root, { recursive: true, force: true });
}
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,211 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm, stat } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, describe, test } from 'node:test';
import {
authenticateInteractiveArtifactStoreWriter,
openInteractiveArtifactStoreForWrite,
type InteractiveArtifactStoreWriter,
} from '../artifact-stores.js';
import { ARTIFACT_WRITER_LOCK_FILE } from '../artifact-storage-layout.js';
import {
resolveStorageRoot,
StorageRootAuthorityError,
tryAcquireInteractiveRootOwner,
type StorageRootLease,
} from '../root-authority.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
// The control directory of each resolved root lives outside that root, so a
// temporary root's removal leaves it behind; reclaim the recorded rootIds here.
after(removeTrackedControlDirectories);
describe('interactive artifact store authority', () => {
test('requires authentic leases and writer facades', async () => {
await assert.rejects(
() =>
openInteractiveArtifactStoreForWrite(
{} as unknown as StorageRootLease<'interactive', 'write'>,
),
invalidLease,
);
assert.throws(
() =>
authenticateInteractiveArtifactStoreWriter({} as unknown as InteractiveArtifactStoreWriter),
invalidLease,
);
});
test('returns one authenticated writer per lease and preserves mutation operations', async () => {
await withInteractiveOwner(async (owner, root, track) => {
const [first, second] = await Promise.all([
openInteractiveArtifactStoreForWrite(owner.lease),
openInteractiveArtifactStoreForWrite(owner.lease),
]);
track(first);
track(second);
assert.strictEqual(first, second);
assert.strictEqual(authenticateInteractiveArtifactStoreWriter(first), first);
await first.recover();
await first.create(artifactInput('deleted', 'delete me'));
const deleted = await first.deleteUserArtifactInSession('session-1', 'deleted');
assert.strictEqual(await openInteractiveArtifactStoreForWrite(owner.lease), first);
assert.equal(deleted.kind, 'deleted');
const page = await first.listPage('session-1', { offset: 0, limit: 1 });
assert.equal(page.total, 1);
assert.equal(page.records[0]?.status, 'deleted');
assert.deepEqual(await first.getInSession('session-1', 'deleted'), {
revision: page.revision,
record: page.records[0],
});
assert.deepEqual(await first.readTextInSession('session-1', 'deleted'), {
ok: false,
reason: 'deleted',
});
assert.deepEqual(await first.readTextInSession('other-session', 'deleted'), {
ok: false,
reason: 'not_found',
});
await assert.rejects(() => stat(join(root, ARTIFACT_WRITER_LOCK_FILE)), { code: 'ENOENT' });
first.close();
const reopened = track(await openInteractiveArtifactStoreForWrite(owner.lease));
assert.notStrictEqual(reopened, first);
assert.equal((await reopened.getInSession('session-1', 'deleted')).record?.status, 'deleted');
});
});
test('root close revokes new facade operations after draining an in-flight write', async () => {
await withTemporaryRoot('interactive', async (root, track) => {
const capability = trackControlDirectory(
await resolveStorageRoot({ path: root, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
const writer = track(await openInteractiveArtifactStoreForWrite(owner.lease));
await writer.recover();
const accepted = writer.create(
artifactInput('accepted', new Uint8Array(8 * 1024 * 1024).fill(0x62)),
);
await owner.close();
assert.equal((await accepted).id, 'accepted');
await assert.rejects(
() => writer.listPage('session-1', { offset: 0, limit: 1 }),
invalidLease,
);
});
});
test('snapshots create inputs and makes user deletion idempotent', async () => {
await withInteractiveOwner(async (owner, _root, track) => {
const writer = track(await openInteractiveArtifactStoreForWrite(owner.lease));
await writer.recover();
const bytes = Uint8Array.from([0x73, 0x61, 0x66, 0x65]);
const createInput = artifactInput('accepted', bytes);
const created = writer.create(createInput);
createInput.id = 'mutated';
createInput.sessionId = 'mutated-session';
createInput.content = 'mutated';
bytes.fill(0x78);
const record = await created;
assert.equal(record.id, 'accepted');
assert.deepEqual(await writer.readTextInSession('session-1', 'accepted'), {
ok: true,
text: 'safe',
});
const deleted = writer.deleteUserArtifactInSession('session-1', record.id);
assert.equal((await deleted).kind, 'deleted');
assert.equal(
(await writer.deleteUserArtifactInSession('session-1', record.id)).kind,
'deleted',
);
assert.equal((await writer.getInSession('session-1', 'accepted')).record?.status, 'deleted');
});
});
});
function artifactInput(id: string, content: string | Uint8Array) {
return {
id,
sessionId: 'session-1',
turnId: 'turn-1',
name: `${id}.txt`,
kind: 'file' as const,
content,
now: 1,
};
}
function invalidLease(error: unknown): boolean {
return error instanceof StorageRootAuthorityError && error.code === 'invalid_lease';
}
async function withInteractiveOwner(
run: (
owner: NonNullable<Awaited<ReturnType<typeof tryAcquireInteractiveRootOwner>>>,
root: string,
track: TrackArtifactWriter,
) => Promise<void>,
): Promise<void> {
await withTemporaryRoot('interactive', async (root, track) => {
const capability = trackControlDirectory(
await resolveStorageRoot({ path: root, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
try {
await run(owner, root, track);
} finally {
await owner.close();
}
});
}
async function withTemporaryRoot(
kind: 'interactive',
run: (root: string, track: TrackArtifactWriter) => Promise<void>,
): Promise<void> {
const root = await mkdtemp(join(tmpdir(), `maka-artifact-${kind}-`));
const writers = new Set<{ close(): void }>();
const track: TrackArtifactWriter = (writer) => {
writers.add(writer);
return writer;
};
try {
await run(root, track);
} finally {
for (const writer of [...writers].reverse()) writer.close();
await rm(root, { recursive: true, force: true });
}
}
type TrackArtifactWriter = <T extends { close(): void }>(writer: T) => T;
@@ -0,0 +1,732 @@
/*
* 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 assert from 'node:assert/strict';
import { fork, type ChildProcess } from 'node:child_process';
import {
lstat,
mkdir,
mkdtemp,
readFile,
readdir,
rename,
rm,
stat,
symlink,
writeFile,
} from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join, sep } from 'node:path';
import { setTimeout as delay } from 'node:timers/promises';
import { after, test } from 'node:test';
import type { ArtifactRecord } from '@maka/core/artifacts';
import {
openInteractiveArtifactStoreForWrite as openInteractiveArtifactStoreForWriteRaw,
type InteractiveArtifactStoreWriter,
} from '../artifact-stores.js';
import {
type ArtifactStore,
type CreateArtifactInput,
createSqliteArtifactStore,
} from '../artifact-store.js';
import { withArtifactWriterLock } from '../artifact-writer-lock.js';
import {
resolveStorageRoot,
tryAcquireInteractiveRootOwner,
type StorageRootLease,
} from '../root-authority.js';
import { exportSessionBundleState } from '../session-bundle-policy.js';
import { createSessionStore } from '../session-store.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
// The control directory of each resolved root lives outside that root, so a
// temporary root's removal leaves it behind; reclaim the recorded rootIds here.
after(removeTrackedControlDirectories);
const TEST_TIMEOUT_MS = 15_000;
const OPERATION_TIMEOUT_MS = 5_000;
const BUNDLE_EXPORT_TIMEOUT_MS = 10_000;
const COMPETING_PAYLOAD_BYTES = 4 * 1024 * 1024;
// Windows does not permit replacing or deleting a directory while SQLite has files open in it.
// These tests exercise POSIX root-replacement semantics; Windows coverage verifies cleanup after
// every owner is closed instead.
const SKIP_OPEN_SQLITE_ROOT_REPLACEMENT = process.platform === 'win32';
const artifactStoreClosersByRoot = new Map<string, Set<() => void>>();
function createArtifactStore(root: string): ArtifactStore {
const store = createSqliteArtifactStore(root);
const closers = artifactStoreClosersByRoot.get(root) ?? new Set<() => void>();
closers.add(() => store.close?.());
artifactStoreClosersByRoot.set(root, closers);
return store;
}
async function openInteractiveArtifactStoreForWrite(
lease: StorageRootLease<'interactive', 'write'>,
): Promise<InteractiveArtifactStoreWriter> {
const store = await openInteractiveArtifactStoreForWriteRaw(lease);
const root = lease.canonicalPath;
const closers = artifactStoreClosersByRoot.get(root) ?? new Set<() => void>();
closers.add(() => store.close());
artifactStoreClosersByRoot.set(root, closers);
return store;
}
function closeArtifactStoresUnder(root: string): void {
for (const [storeRoot, closers] of artifactStoreClosersByRoot) {
if (storeRoot !== root && !storeRoot.startsWith(`${root}${sep}`)) continue;
artifactStoreClosersByRoot.delete(storeRoot);
for (const close of [...closers].reverse()) close();
}
}
test('public Store mutation waits for a child-held writer lock and preserves metadata', {
timeout: TEST_TIMEOUT_MS,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
const store = createArtifactStore(stateRoot);
await store.create(artifactInput('seed'));
const holder = await spawnLockHolder(stateRoot);
try {
const mutation = store.create(artifactInput('after-lock'));
await assertPending(mutation, 'Store mutation');
await releaseHolder(holder);
await withTimeout(mutation, OPERATION_TIMEOUT_MS, 'Store mutation');
assert.deepEqual(
(await createArtifactStore(stateRoot).list('session-1')).map((record) => record.id).sort(),
['after-lock', 'seed'],
);
} finally {
await stopHolder(holder);
}
});
});
test('public Store mutations in separate processes reload and publish under one OS lock', {
timeout: TEST_TIMEOUT_MS,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
const seedRecord = await createArtifactStore(stateRoot).create(artifactInput('seed'));
const parentStore = createArtifactStore(stateRoot);
await parentStore.list('session-1');
const child = await spawnPublicWriter(stateRoot, 'session-1');
const holder = await spawnLockHolder(stateRoot);
try {
const childInput = artifactInput('child-public', undefined, 3);
const childPayload = repeatedPayload('child-public:', COMPETING_PAYLOAD_BYTES);
const childMutation = startPublicWriterMutation(child, childInput, 'child-public:');
const parentPayload = repeatedPayload('parent-public:', COMPETING_PAYLOAD_BYTES);
const parentMutation = parentStore.create(artifactInput('parent-public', parentPayload, 2));
await childMutation.queued;
await new Promise<void>((resolve) => setImmediate(resolve));
await releaseHolder(holder);
const [parentRecord, childCreated] = await withTimeout(
Promise.all([parentMutation, childMutation.created]),
OPERATION_TIMEOUT_MS,
'competing public Store mutations',
);
await withTimeout(waitForExit(child), OPERATION_TIMEOUT_MS, 'public writer shutdown');
const freshStore = createArtifactStore(stateRoot);
const records = (await freshStore.list('session-1')).sort(compareRecordsById);
assert.deepEqual(
records,
[seedRecord, parentRecord, childCreated.record].sort(compareRecordsById),
);
assert.deepEqual(await freshStore.readText('parent-public'), {
ok: true,
text: parentPayload,
});
assert.deepEqual(await freshStore.readText('child-public'), { ok: true, text: childPayload });
} finally {
await stopHolder(child);
await stopHolder(holder);
}
});
});
test('public Store mutations share the rootId writer lock used by lease-bound authority', {
timeout: TEST_TIMEOUT_MS,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
await mkdir(stateRoot);
const capability = trackControlDirectory(
await resolveStorageRoot({ path: stateRoot, kind: 'interactive' }),
);
const holder = await spawnAuthorityLockHolder(stateRoot, capability.rootId);
try {
const mutation = createArtifactStore(stateRoot).create(artifactInput('public-marked-root'));
await assertPending(mutation, 'public Store mutation on a marked root');
await releaseHolder(holder);
assert.equal(
(
await withTimeout(
mutation,
OPERATION_TIMEOUT_MS,
'public Store mutation on a marked root',
)
).id,
'public-marked-root',
);
} finally {
await stopHolder(holder);
}
});
});
test('mutations spanning initial root marking remain serialized by the bootstrap writer lock', {
timeout: TEST_TIMEOUT_MS,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
await mkdir(stateRoot);
const holder = await spawnLockHolder(stateRoot);
try {
const firstMutation = createArtifactStore(stateRoot).create(
artifactInput('before-root-marking'),
);
await assertPending(firstMutation, 'public mutation started before root marking');
trackControlDirectory(await resolveStorageRoot({ path: stateRoot, kind: 'interactive' }));
const secondMutation = createArtifactStore(stateRoot).create(
artifactInput('after-root-marking', undefined, 2),
);
await assertPending(secondMutation, 'public mutation started after root marking');
await releaseHolder(holder);
await withTimeout(
Promise.all([firstMutation, secondMutation]),
OPERATION_TIMEOUT_MS,
'mutations spanning initial root marking',
);
const freshStore = createArtifactStore(stateRoot);
assert.deepEqual((await freshStore.list('session-1')).map((record) => record.id).sort(), [
'after-root-marking',
'before-root-marking',
]);
assert.deepEqual(await freshStore.readText('before-root-marking'), {
ok: true,
text: 'before-root-marking',
});
assert.deepEqual(await freshStore.readText('after-root-marking'), {
ok: true,
text: 'after-root-marking',
});
} finally {
await stopHolder(holder);
}
});
});
test('public mutation rejects an unmarked replacement installed while waiting for bootstrap', {
timeout: TEST_TIMEOUT_MS,
skip: SKIP_OPEN_SQLITE_ROOT_REPLACEMENT,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
const displacedRoot = join(root, 'displaced-state');
await mkdir(stateRoot);
const holder = await spawnLockHolder(stateRoot);
try {
const mutation = createArtifactStore(stateRoot).create(
artifactInput('stale-public-replacement'),
);
await assertPending(mutation, 'public mutation waiting for its captured bootstrap authority');
await rename(stateRoot, displacedRoot);
await mkdir(stateRoot);
await writeFile(join(stateRoot, 'replacement-sentinel'), 'replacement');
await releaseHolder(holder);
await assert.rejects(mutation);
assert.deepEqual(await readdir(stateRoot), ['replacement-sentinel']);
await assert.rejects(() => lstat(join(stateRoot, 'artifacts')), { code: 'ENOENT' });
await assert.rejects(() => lstat(join(displacedRoot, 'artifacts')), { code: 'ENOENT' });
} finally {
await stopHolder(holder);
}
});
});
test('public mutation through a retargeted alias stays bound to its verified canonical root', {
timeout: TEST_TIMEOUT_MS,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
const replacementRoot = join(root, 'replacement');
const alias = join(root, 'state-alias');
await Promise.all([mkdir(stateRoot), mkdir(replacementRoot)]);
await writeFile(join(replacementRoot, 'replacement-sentinel'), 'replacement');
const capability = trackControlDirectory(
await resolveStorageRoot({ path: stateRoot, kind: 'interactive' }),
);
await createArtifactStore(stateRoot).create(artifactInput('seed'));
await symlink(stateRoot, alias, process.platform === 'win32' ? 'junction' : 'dir');
const store = createArtifactStore(alias);
assert.deepEqual(
(await store.list('session-1')).map((record) => record.id),
['seed'],
);
const holder = await spawnAuthorityLockHolder(stateRoot, capability.rootId);
try {
const mutation = store.create(artifactInput('alias-mutation', undefined, 2));
await assertPending(mutation, 'public mutation through the original alias target');
await rm(alias, { force: true });
await symlink(replacementRoot, alias, process.platform === 'win32' ? 'junction' : 'dir');
await releaseHolder(holder);
assert.equal((await mutation).id, 'alias-mutation');
assert.deepEqual(
(await createArtifactStore(stateRoot).list('session-1')).map((record) => record.id).sort(),
['alias-mutation', 'seed'],
);
assert.deepEqual(await readdir(replacementRoot), ['replacement-sentinel']);
await assert.rejects(() => lstat(join(replacementRoot, 'artifacts')), { code: 'ENOENT' });
} finally {
await stopHolder(holder);
}
});
});
test('admitted lease-bound mutations reject a replacement root without modifying it', {
timeout: TEST_TIMEOUT_MS,
skip: SKIP_OPEN_SQLITE_ROOT_REPLACEMENT,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
await mkdir(stateRoot);
const capability = trackControlDirectory(
await resolveStorageRoot({ path: stateRoot, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
const firstStore = await openInteractiveArtifactStoreForWrite(owner.lease);
const holder = await spawnLockHolder(stateRoot);
const displacedRoot = join(root, 'displaced-state');
try {
const firstMutation = firstStore.create(artifactInput('stale-replacement-first'));
const secondMutation = firstStore.create(
artifactInput('stale-replacement-second', undefined, 2),
);
await Promise.all([
assertPending(firstMutation, 'first admitted lease-bound mutation'),
assertPending(secondMutation, 'second admitted lease-bound mutation'),
]);
await rename(stateRoot, displacedRoot);
await mkdir(stateRoot, { mode: 0o750 });
await writeFile(join(stateRoot, 'replacement-sentinel'), 'replacement');
const replacementMode = (await stat(stateRoot)).mode & 0o777;
await releaseHolder(holder);
await Promise.all([assert.rejects(firstMutation), assert.rejects(secondMutation)]);
assert.deepEqual(await readdir(stateRoot), ['replacement-sentinel']);
assert.equal((await stat(stateRoot)).mode & 0o777, replacementMode);
await assert.rejects(() => lstat(join(stateRoot, '.maka-artifact-writer.lock')), {
code: 'ENOENT',
});
await assert.rejects(() => stat(join(stateRoot, 'artifacts')), { code: 'ENOENT' });
} finally {
await stopHolder(holder);
await owner.close();
}
});
});
test('lease-bound mutation does not rebuild a root deleted while waiting for the writer lock', {
timeout: TEST_TIMEOUT_MS,
skip: SKIP_OPEN_SQLITE_ROOT_REPLACEMENT,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
await mkdir(stateRoot);
const capability = trackControlDirectory(
await resolveStorageRoot({ path: stateRoot, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
const store = await openInteractiveArtifactStoreForWrite(owner.lease);
const holder = await spawnLockHolder(stateRoot);
try {
const mutation = store.create(artifactInput('stale-deleted'));
await assertPending(mutation, 'lease-bound mutation');
await rm(stateRoot, { recursive: true });
await releaseHolder(holder);
await assert.rejects(mutation);
await assert.rejects(() => lstat(stateRoot), { code: 'ENOENT' });
} finally {
await stopHolder(holder);
await owner.close();
}
});
});
test('bundle export excludes a mutation queued behind the same child-held writer lock', {
timeout: TEST_TIMEOUT_MS,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
const configRoot = join(root, 'config');
const destinationRoot = join(root, 'export');
await Promise.all([mkdir(stateRoot), mkdir(configRoot)]);
const sessions = createSessionStore(stateRoot);
const session = await sessions.create(sessionInput());
await sessions.close?.();
const store = createArtifactStore(stateRoot);
await store.create({ ...artifactInput('seed'), sessionId: session.id });
const holder = await spawnLockHolder(stateRoot, session.id);
try {
const bundleExport = exportSessionBundleState({
stateRoot,
configRoot,
destinationRoot,
sessionId: session.id,
});
await assertPending(bundleExport, 'bundle export');
const mutation = store.create({
...artifactInput('after-export'),
sessionId: session.id,
});
await assertPending(mutation, 'Store mutation');
await releaseHolder(holder);
await withTimeout(bundleExport, BUNDLE_EXPORT_TIMEOUT_MS, 'bundle export');
await withTimeout(mutation, OPERATION_TIMEOUT_MS, 'Store mutation');
const exportedStore = createSqliteArtifactStore(destinationRoot);
try {
assert.deepEqual(
(await exportedStore.list(session.id)).map((record) => record.id),
['seed'],
);
} finally {
exportedStore.close?.();
}
assert.deepEqual(
(await createArtifactStore(stateRoot).list(session.id)).map((record) => record.id).sort(),
['after-export', 'seed'],
);
} finally {
await stopHolder(holder);
}
});
});
test('bundle export holds Artifact authority through selected-session projection', {
timeout: TEST_TIMEOUT_MS,
}, async () => {
await withTemporaryDirectory(async (root) => {
const stateRoot = join(root, 'state');
const configRoot = join(root, 'config');
const destinationRoot = join(root, 'export');
await Promise.all([mkdir(stateRoot), mkdir(configRoot)]);
const sessions = createSessionStore(stateRoot);
const session = await sessions.create(sessionInput());
await sessions.appendMessage(session.id, {
type: 'user',
id: 'message-1',
turnId: 'turn-1',
ts: 1,
text: 'portable transcript',
});
await sessions.close?.();
await createArtifactStore(stateRoot).create({
...artifactInput('seed'),
sessionId: session.id,
});
const holder = await spawnLockHolder(stateRoot, session.id);
try {
const bundleExport = exportSessionBundleState({
stateRoot,
configRoot,
destinationRoot,
sessionId: session.id,
});
await assertPending(bundleExport, 'bundle export');
const projectedMessages = withArtifactWriterLock(stateRoot, async () => {
const projectedSessions = createSessionStore(destinationRoot);
try {
return await projectedSessions.readMessagesSnapshot(session.id);
} finally {
await projectedSessions.close?.();
}
});
await assertPending(projectedMessages, 'writer queued after bundle export');
await releaseHolder(holder);
assert.equal(
(
await withTimeout(
projectedMessages,
BUNDLE_EXPORT_TIMEOUT_MS,
'selected-session projection',
)
).find((message) => message.type === 'user')?.text,
'portable transcript',
);
await withTimeout(bundleExport, BUNDLE_EXPORT_TIMEOUT_MS, 'bundle export');
} finally {
await stopHolder(holder);
}
});
});
function artifactInput(id: string, content = id, now = 1): CreateArtifactInput {
return {
id,
sessionId: 'session-1',
turnId: 'turn-1',
name: `${id}.txt`,
kind: 'file' as const,
content,
now,
};
}
function sessionInput() {
return {
cwd: '/repo',
backend: 'fake' as const,
llmConnectionSlug: 'fixture',
model: 'fixture-model',
permissionMode: 'ask' as const,
name: 'Selected',
};
}
async function spawnLockHolder(
workspaceRoot: string,
transientResidueSessionId?: string,
): Promise<ChildProcess> {
const child = fork(
new URL('./fixtures/artifact-writer-lock-holder.js', import.meta.url),
[workspaceRoot, ...(transientResidueSessionId ? [transientResidueSessionId] : [])],
{ stdio: ['ignore', 'ignore', 'ignore', 'ipc'] },
);
try {
await waitForChildMessage(child, 'locked');
return child;
} catch (error) {
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
await withTimeout(waitForExit(child), OPERATION_TIMEOUT_MS, 'failed lock holder shutdown');
throw error;
}
}
async function spawnAuthorityLockHolder(
workspaceRoot: string,
rootId: string,
): Promise<ChildProcess> {
const child = fork(
new URL('./fixtures/artifact-writer-lock-holder.js', import.meta.url),
[workspaceRoot, '--authority-holder', rootId],
{ stdio: ['ignore', 'ignore', 'ignore', 'ipc'] },
);
try {
await waitForChildMessage(child, 'locked');
return child;
} catch (error) {
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
await withTimeout(waitForExit(child), OPERATION_TIMEOUT_MS, 'failed lock holder shutdown');
throw error;
}
}
async function spawnPublicWriter(workspaceRoot: string, sessionId: string): Promise<ChildProcess> {
const child = fork(
new URL('./fixtures/artifact-writer-lock-holder.js', import.meta.url),
[workspaceRoot, '--public-writer', sessionId],
{ stdio: ['ignore', 'ignore', 'ignore', 'ipc'] },
);
try {
await waitForChildMessage(child, 'ready');
return child;
} catch (error) {
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
await withTimeout(waitForExit(child), OPERATION_TIMEOUT_MS, 'failed public writer shutdown');
throw error;
}
}
function startPublicWriterMutation(
child: ChildProcess,
input: CreateArtifactInput,
payloadUnit: string,
): {
queued: Promise<FixtureMessageOfType<'queued'>>;
created: Promise<FixtureMessageOfType<'created'>>;
} {
const queued = waitForChildMessage(child, 'queued');
const created = waitForChildMessage(child, 'created');
const { content: _content, ...inputWithoutContent } = input;
child.send({
type: 'create',
input: inputWithoutContent,
payloadUnit,
payloadBytes: COMPETING_PAYLOAD_BYTES,
});
return { queued, created };
}
async function releaseHolder(child: ChildProcess): Promise<void> {
if (child.exitCode !== null || child.signalCode !== null) {
throw new Error('Artifact writer lock holder exited before release');
}
const released = waitForChildMessage(child, 'released');
child.send({ type: 'release' });
await released;
await waitForExit(child);
}
async function stopHolder(child: ChildProcess): Promise<void> {
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
await withTimeout(waitForExit(child), OPERATION_TIMEOUT_MS, 'lock holder shutdown');
}
async function waitForChildMessage<T extends FixtureMessage['type']>(
child: ChildProcess,
expected: T,
): Promise<FixtureMessageOfType<T>> {
return withTimeout(
new Promise<FixtureMessageOfType<T>>((resolve, reject) => {
const cleanup = () => {
child.off('error', onError);
child.off('exit', onExit);
child.off('message', onMessage);
};
const onError = (error: Error) => {
cleanup();
reject(error);
};
const onExit = (code: number | null, signal: NodeJS.Signals | null) => {
cleanup();
reject(new Error(`Lock holder exited before ${expected}: ${code ?? signal}`));
};
const onMessage = (message: unknown) => {
if (!isFixtureMessage(message)) return;
if (message.type === 'error') {
cleanup();
reject(new Error(`Lock holder failed: ${message.message}`));
} else if (message.type === expected) {
cleanup();
resolve(message as FixtureMessageOfType<T>);
}
};
child.on('error', onError);
child.on('exit', onExit);
child.on('message', onMessage);
}),
OPERATION_TIMEOUT_MS,
`lock holder ${expected}`,
);
}
type FixtureMessage =
| { type: 'locked' | 'released' | 'ready' | 'queued' }
| { type: 'created'; record: ArtifactRecord }
| { type: 'error'; message: string };
type FixtureMessageOfType<T extends FixtureMessage['type']> = Extract<FixtureMessage, { type: T }>;
function isFixtureMessage(message: unknown): message is FixtureMessage {
if (!message || typeof message !== 'object' || !('type' in message)) return false;
const type = message.type;
return (
type === 'locked' ||
type === 'released' ||
type === 'ready' ||
type === 'queued' ||
type === 'created' ||
type === 'error'
);
}
async function assertPending(operation: Promise<unknown>, label: string): Promise<void> {
let settled = false;
void operation.then(
() => {
settled = true;
},
() => {
settled = true;
},
);
await delay(100);
assert.equal(settled, false, `${label} did not wait for the child-held writer lock`);
}
async function waitForExit(child: ChildProcess): Promise<void> {
if (child.exitCode !== null || child.signalCode !== null) return;
await new Promise<void>((resolve) => child.once('exit', () => resolve()));
}
async function withTimeout<T>(
operation: Promise<T>,
milliseconds: number,
label: string,
): Promise<T> {
let timer: NodeJS.Timeout | undefined;
try {
return await Promise.race([
operation,
new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new Error(`${label} timed out`)), milliseconds);
}),
]);
} finally {
if (timer) clearTimeout(timer);
}
}
async function withTemporaryDirectory(run: (root: string) => Promise<void>): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-artifact-writer-lock-'));
try {
await run(root);
} finally {
closeArtifactStoresUnder(root);
await rm(root, { recursive: true, force: true });
}
}
function repeatedPayload(unit: string, bytes: number): string {
return unit.repeat(Math.ceil(bytes / unit.length)).slice(0, bytes);
}
function compareRecordsById(left: ArtifactRecord, right: ArtifactRecord): number {
return left.id.localeCompare(right.id);
}
@@ -0,0 +1,243 @@
/*
* 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 assert from 'node:assert/strict';
import { access, mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { AGENT_GRAPH_INTENT_CLAIM_SCHEMA_VERSION } from '@maka/core/agent-graph-control';
import type { RootExecutionDescriptor } from '@maka/core/agent-run';
import { createSqliteAgentRunStore, type AdmitRootTurnInput } from '../agent-run-store.js';
describe('claimed agent graph root admission', () => {
test('round-trips an exact, deeply frozen durable descriptor', async () => {
await withTempRoot(async (_root, openStore) => {
const store = openStore();
const result = await store.admitRootTurn(admissionInput());
assert.equal(result.kind, 'admitted');
assert.equal(result.admission.execution.kind, 'claimed_agent_graph_intent');
if (result.admission.execution.kind !== 'claimed_agent_graph_intent') return;
assert.deepEqual(result.admission.execution.claim, claim());
assert.equal(result.admission.execution.agentId, 'trusted-agent');
assert.equal(result.admission.execution.agentName, 'Trusted Agent');
assert.equal(Object.isFrozen(result.admission.execution), true);
assert.equal(Object.isFrozen(result.admission.execution.claim), true);
const reopened = openStore();
const stored = await reopened.readRootTurnAdmission('session-child', 'turn-next');
assert.deepEqual(stored, result.admission);
assert.equal(Object.isFrozen(stored?.execution), true);
if (stored?.execution.kind === 'claimed_agent_graph_intent') {
assert.equal(Object.isFrozen(stored.execution.claim), true);
}
});
});
test('rejects descriptor unknown fields and malformed claims', async () => {
await withTempRoot(async (_root, openStore) => {
const store = openStore();
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
execution: {
...admissionInput().execution,
unexpected: true,
} as unknown as RootExecutionDescriptor,
}),
),
/Invalid root execution descriptor/,
);
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
execution: {
kind: 'claimed_agent_graph_intent',
claim: { ...claim(), claimId: 'not-a-claim-id' },
agentId: 'trusted-agent',
agentName: 'Trusted Agent',
} as unknown as RootExecutionDescriptor,
}),
),
/Invalid root execution descriptor/,
);
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
execution: {
kind: 'claimed_agent_graph_intent',
claim: { ...claim(), unexpected: true },
agentId: 'trusted-agent',
agentName: 'Trusted Agent',
} as unknown as RootExecutionDescriptor,
}),
),
/Invalid root execution descriptor/,
);
});
});
test('rejects every claim target identity drift before writing admission', async () => {
await withTempRoot(async (root, openStore) => {
const store = openStore();
for (const [field, value] of [
['targetSessionId', 'different-session'],
['targetTurnId', 'different-turn'],
['targetRunId', 'different-run'],
] as const) {
const sessionId = `session-drift-${field}`;
const turnId = 'turn-next';
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
sessionId,
execution: {
kind: 'claimed_agent_graph_intent',
claim: {
...claim({
targetSessionId: sessionId,
targetTurnId: turnId,
targetRunId: 'run-next',
}),
[field]: value,
},
agentId: 'trusted-agent',
agentName: 'Trusted Agent',
},
}),
),
/claim target does not match admission identity/,
);
await assert.rejects(
access(join(root, 'sessions', sessionId, 'turn-admissions', `${turnId}.json`)),
(error: unknown) => (error as NodeJS.ErrnoException).code === 'ENOENT',
);
}
});
});
test('rejects queue sources and a missing canonical UserMessage', async () => {
await withTempRoot(async (root, openStore) => {
const store = openStore();
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
normalizedInput: { text: 'queued graph prompt' },
sourceMessages: [
{
messageId: 'message-next',
content: { text: 'queued graph prompt' },
placement: 'current_turn',
disposition: 'turn_started',
},
],
}),
),
/host-authored execution cannot have source messages/,
);
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
proposedUserMessageId: null,
}),
),
/execution has an invalid UserMessage requirement/,
);
await assert.rejects(
access(join(root, 'sessions', 'session-child', 'turn-admissions', 'turn-next.json')),
(error: unknown) => (error as NodeJS.ErrnoException).code === 'ENOENT',
);
});
});
});
function admissionInput(overrides: Partial<AdmitRootTurnInput> = {}): AdmitRootTurnInput {
const sessionId = overrides.sessionId ?? 'session-child';
const turnId = overrides.turnId ?? 'turn-next';
const proposedRunId = overrides.proposedRunId ?? 'run-next';
return {
sessionId,
turnId,
proposedRunId,
proposedUserMessageId: 'message-next',
execution: {
kind: 'claimed_agent_graph_intent',
claim: claim({
targetSessionId: sessionId,
targetTurnId: turnId,
targetRunId: proposedRunId,
}),
agentId: 'trusted-agent',
agentName: 'Trusted Agent',
},
previousRootTurnId: null,
normalizedInput: { text: 'canonical graph prompt' },
sourceMessages: [],
admittedAt: 50,
...overrides,
};
}
function claim(
overrides: Partial<ReturnType<typeof baseClaim>> = {},
): ReturnType<typeof baseClaim> {
return { ...baseClaim(), ...overrides };
}
function baseClaim() {
return {
schemaVersion: AGENT_GRAPH_INTENT_CLAIM_SCHEMA_VERSION,
claimId: `graph_claim_${'a'.repeat(32)}`,
graphId: 'graph-1',
intentId: `graph_intent_${'b'.repeat(32)}`,
intentFingerprint: `sha256:${'c'.repeat(64)}`,
readinessContextFingerprint: `sha256:${'d'.repeat(64)}`,
targetOperatorId: 'summarizer',
targetSessionId: 'session-child',
targetTurnId: 'turn-next',
targetRunId: 'run-next',
claimedAt: 40,
};
}
async function withTempRoot(
run: (
root: string,
openStore: () => ReturnType<typeof createSqliteAgentRunStore>,
) => Promise<void>,
): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-claimed-graph-admission-'));
const stores: ReturnType<typeof createSqliteAgentRunStore>[] = [];
try {
await run(root, () => {
const store = createSqliteAgentRunStore(root);
stores.push(store);
return store;
});
} finally {
for (const store of stores.reverse()) store.close?.();
await rm(root, { recursive: true, force: true });
}
}
@@ -0,0 +1,526 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { decodeCanonicalMessage, type StoredMessage } from '@maka/core/session';
import { ClaudeCodeSessionAdapter } from '../claude-code-session-adapter.js';
import { createExternalSessionAdapterRegistry } from '../external-session-adapters.js';
/**
* The load-bearing question for this adapter is which turns get a terminal
* `turn_state`. The Ledger refuses a reconstructed terminal that no record
* corroborates (`runtime-ledger-repair.ts`), so emitting one for a turn that
* was killed mid-answer would import a crash as a clean completion — and
* emitting none for a turn that did finish leaves every imported Run repaired
* to `failed`.
*
* `stop_reason` is the record that answers it. Measured across 1130 local
* transcripts: 86% of turns carry a terminal one, and the rest end with no
* assistant reply at all or stopped at `tool_use` — genuinely unfinished.
*/
const CWD = '/workspace/project';
describe('ClaudeCodeSessionAdapter', () => {
test('a turn that stopped with end_turn imports as completed', async () => {
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000001', [
userRecord('ship the parser'),
assistantRecord({ text: 'Done.', stopReason: 'end_turn' }),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000001');
const state = terminalState(messages);
assert.equal(state?.status, 'completed');
});
});
test('a turn stopped at tool_use with no result is recorded as a snapshot cutoff', async () => {
// The process died between the call and its result. Reporting `completed`
// here is the failure mode this adapter exists to avoid.
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000002', [
userRecord('read the file'),
assistantRecord({ toolUse: { id: 'toolu_1', name: 'Read' }, stopReason: 'tool_use' }),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000002');
const state = terminalState(messages);
assert.equal(state?.status, 'aborted');
assert.equal(state?.abortSource, 'external_session_snapshot');
// The call itself still imports — the conversation is real up to the cut.
assert.equal(messages.filter((m) => m.type === 'tool_call').length, 1);
});
});
test('a prompt with no answer at all is recorded as a snapshot cutoff', async () => {
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000003', [userRecord('are you there?')]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000003');
const state = terminalState(messages);
assert.equal(state?.status, 'aborted');
assert.equal(state?.abortSource, 'external_session_snapshot');
assert.equal(messages.filter((m) => m.type === 'user').length, 1);
});
});
test('an interrupt notice imports as aborted, not as a user message', async () => {
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000004', [
userRecord('start the long job'),
assistantRecord({ text: 'Working…', stopReason: 'tool_use' }),
userRecord('[Request interrupted by user for tool use]'),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000004');
const state = terminalState(messages);
assert.equal(state?.status, 'aborted');
// The notice is the harness speaking, not the human. One user message.
assert.equal(messages.filter((m) => m.type === 'user').length, 1);
});
});
test('an API error imports as failed', async () => {
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000005', [
userRecord('summarize this'),
{ ...assistantRecord({ text: 'API Error: overloaded' }), isApiErrorMessage: true },
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000005');
const state = terminalState(messages);
assert.equal(state?.status, 'failed');
assert.equal(state?.errorClass, 'claude_code_api_error');
});
});
test('tool results arrive as user records and must not import as user turns', async () => {
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000006', [
userRecord('read it'),
assistantRecord({ toolUse: { id: 'toolu_9', name: 'Read' }, stopReason: 'tool_use' }),
toolResultRecord('toolu_9', 'file contents'),
assistantRecord({ text: 'Here it is.', stopReason: 'end_turn' }),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000006');
assert.equal(messages.filter((m) => m.type === 'user').length, 1);
const results = messages.filter((m) => m.type === 'tool_result');
assert.equal(results.length, 1);
// The result must point back at the call, or the pair renders detached.
assert.equal(results[0]?.type === 'tool_result' ? results[0].toolUseId : null, 'toolu_9');
});
});
test('a turn cut off by max_tokens is not reported as completed', async () => {
// `max_tokens` does say generation stopped — because the answer hit the
// output limit mid-sentence. Treating "stopped" as "finished" is the
// specific mistake this adapter is built to avoid.
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000011', [
userRecord('write the whole file'),
assistantRecord({ text: 'Here is the beg', stopReason: 'max_tokens' }),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000011');
const state = terminalState(messages);
// Cut off, not completed — and named as the snapshot's edge rather than
// as a user Stop.
assert.equal(state?.status, 'aborted');
assert.equal(state?.abortSource, 'external_session_snapshot');
});
});
test('a tool result with no tool_use_id is dropped rather than left detached', async () => {
// Minting an id produces a result guaranteed not to pair with any call —
// a detached row in the transcript view, worse than an absent one.
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000012', [
userRecord('read it'),
assistantRecord({ toolUse: { id: 'toolu_a', name: 'Read' }, stopReason: 'tool_use' }),
{
type: 'user',
timestamp: '2026-08-01T00:00:02.000Z',
message: { role: 'user', content: [{ type: 'tool_result', content: 'orphan' }] },
},
assistantRecord({ text: 'done', stopReason: 'end_turn' }),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000012');
assert.equal(messages.filter((m) => m.type === 'tool_result').length, 0);
// Every result that does survive must name a call that is present.
const callIds = new Set(messages.filter((m) => m.type === 'tool_call').map((m) => m.id));
for (const message of messages) {
if (message.type === 'tool_result') assert.ok(callIds.has(message.toolUseId));
}
});
});
test('turn ids are dense and never collide with message ids', async () => {
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000013', [
userRecord('one'),
assistantRecord({ text: 'a', stopReason: 'end_turn' }),
userRecord('two'),
assistantRecord({ text: 'b', stopReason: 'end_turn' }),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000013');
const turnIds = [...new Set(messages.map((m) => m.turnId))];
assert.deepEqual(turnIds, [
'claude-code:aaaaaaaa-0000-4000-8000-000000000013:turn:0',
'claude-code:aaaaaaaa-0000-4000-8000-000000000013:turn:1',
]);
const messageIds = new Set(messages.map((m) => m.id));
for (const turnId of turnIds) assert.equal(messageIds.has(turnId), false);
});
});
test('a record written twice emits one message, not two', async () => {
// A transcript is an append log: resume and recovery can replay a line.
// Persisting both copies duplicates the prompt in canonical history, and
// re-importing produces the same result — it is not recoverable after the
// fact.
await withClaudeHome(async (home) => {
const prompt = { ...userRecord('build the thing'), uuid: 'u-1' };
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000014', [
prompt,
prompt,
assistantRecord({ text: 'Done.', stopReason: 'end_turn' }),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000014');
assert.equal(messages.filter((m) => m.type === 'user').length, 1);
assert.equal(new Set(messages.map((m) => m.turnId)).size, 1);
});
});
test('one response is assembled from every fragment, calls before their results', async () => {
// The real shape, measured across 1130 local transcripts: a response is
// written as several records sharing `message.id`, the pieces separated by
// the results of calls the earlier pieces made. In 4093 of 14095
// responses the visible text is NOT in the first fragment — so a guard
// that emits prose at the first record and suppresses it afterwards drops
// the reply.
//
// Both calls share one `message.id`, so they came from one API response
// and were issued together however the log interleaved them with the
// results arriving: they are one assistant step, and both precede both
// results.
await withClaudeHome(async (home) => {
const fragment = (blocks: Parameters<typeof assistantFragment>[1]) =>
assistantFragment('msg_shared', blocks);
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000015', [
userRecord('read both files'),
fragment([{ type: 'thinking', thinking: 'Two files to read.' }]),
fragment([{ type: 'tool_use', id: 'toolu_1', name: 'Read', input: {} }]),
toolResultRecord('toolu_1', 'first file'),
// The text arrives last, after a call and its result — the 4093 case.
fragment([
{ type: 'text', text: 'Reading them now.' },
{ type: 'tool_use', id: 'toolu_2', name: 'Read', input: {} },
]),
toolResultRecord('toolu_2', 'second file'),
assistantRecord({ text: 'Both read.', stopReason: 'end_turn' }),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000015');
const assistants = messages.filter(
(m): m is Extract<StoredMessage, { type: 'assistant' }> => m.type === 'assistant',
);
// The reply survives even though no fragment before it carried text, and
// the response is still one reply rather than one per fragment.
assert.deepEqual(
assistants.filter((m) => m.text.length > 0).map((m) => m.text),
['Reading them now.', 'Both read.'],
);
// The thinking from the first fragment belongs to the same response.
assert.deepEqual(
assistants.filter((m) => m.thinking).map((m) => m.thinking?.text),
['Two files to read.'],
);
const order = messages
.filter((m) => m.type === 'tool_call' || m.type === 'tool_result')
.map((m) => (m.type === 'tool_call' ? `call:${m.id}` : `result:${m.toolUseId}`));
assert.deepEqual(order, ['call:toolu_1', 'call:toolu_2', 'result:toolu_1', 'result:toolu_2']);
});
});
test('a sidechain transcript is neither listed nor readable', async () => {
// Sub-agent transcripts are whole files, so exclusion is per file.
// Importing one would present a fragment of a conversation as a whole.
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000007', [
{ ...userRecord('sub-agent work'), isSidechain: true },
{ ...assistantRecord({ text: 'done', stopReason: 'end_turn' }), isSidechain: true },
]);
const adapter = new ClaudeCodeSessionAdapter({ claudeHome: home });
assert.deepEqual(await adapter.listSessions(), []);
await assert.rejects(
() => adapter.readSession('aaaaaaaa-0000-4000-8000-000000000007'),
/sidechain/u,
);
});
});
test('a text query filters the source, before paging', async () => {
// The catalog pages 16 at a time over a source with 1128 sessions here, so
// the term has to reach the adapter. A filter applied to an assembled page
// would search the rows already fetched, which is worse than none.
await withClaudeHome(async (home) => {
await seed(
home,
'aaaaaaaa-0000-4000-8000-000000000030',
[userRecord('fix the parser'), assistantRecord({ text: 'ok', stopReason: 'end_turn' })],
'/Users/someone/compiler',
);
await seed(
home,
'aaaaaaaa-0000-4000-8000-000000000031',
[userRecord('write the docs'), assistantRecord({ text: 'ok', stopReason: 'end_turn' })],
'/Users/someone/handbook',
);
const adapter = new ClaudeCodeSessionAdapter({ claudeHome: home });
const byTitle = await adapter.listSessions({ text: 'parser' });
assert.deepEqual(
byTitle.map((s) => s.id),
['aaaaaaaa-0000-4000-8000-000000000030'],
);
// The path is the other half of what a user remembers.
const byPath = await adapter.listSessions({ text: 'handbook' });
assert.deepEqual(
byPath.map((s) => s.id),
['aaaaaaaa-0000-4000-8000-000000000031'],
);
assert.equal((await adapter.listSessions({ text: 'kubernetes' })).length, 0);
// A blank box is not a filter.
assert.equal((await adapter.listSessions({ text: ' ' })).length, 2);
assert.equal((await adapter.listSessions()).length, 2);
});
});
test('a rewritten transcript is re-read, a deleted one drops out', async () => {
// Listing parses every transcript, and the catalog is listed once per
// search term — so summaries are cached against the file's own mtime and
// size. The risk a cache carries is serving a stale answer, so both
// directions are pinned: an appended transcript must be re-read, and a
// removed one must not survive in the map.
await withClaudeHome(async (home) => {
const id = 'aaaaaaaa-0000-4000-8000-000000000033';
await seed(home, id, [
userRecord('first title'),
assistantRecord({ text: 'ok', stopReason: 'end_turn' }),
]);
const adapter = new ClaudeCodeSessionAdapter({ claudeHome: home });
assert.equal((await adapter.listSessions())[0]?.name, 'first title');
// Rewritten with a different title. Same path, new content.
await seed(home, id, [
userRecord('second title'),
assistantRecord({ text: 'ok', stopReason: 'end_turn' }),
]);
assert.equal(
(await adapter.listSessions())[0]?.name,
'second title',
'a changed transcript must not keep its cached summary',
);
await rm(join(home, 'projects', CWD.replace(/\//gu, '-'), `${id}.jsonl`));
assert.deepEqual(await adapter.listSessions(), []);
});
});
test('a project query tolerates a trailing separator', async () => {
// The adapter compared raw strings, so the same project reached with a
// trailing slash answered "no such project". Both sources now share one
// path rule.
await withClaudeHome(async (home) => {
await seed(
home,
'aaaaaaaa-0000-4000-8000-000000000032',
[userRecord('one'), assistantRecord({ text: 'ok', stopReason: 'end_turn' })],
'/Users/someone/my-project',
);
const adapter = new ClaudeCodeSessionAdapter({ claudeHome: home });
assert.equal((await adapter.listSessions({ cwd: '/Users/someone/my-project/' })).length, 1);
});
});
test('a project query matches the record cwd, not the mangled directory name', async () => {
// `-Users-a-b` cannot be reversed — it is ambiguous between `/Users/a/b`
// and `/Users/a-b` — so only a record's own `cwd` can answer this.
await withClaudeHome(async (home) => {
await seed(
home,
'aaaaaaaa-0000-4000-8000-000000000008',
[userRecord('one'), assistantRecord({ text: 'ok', stopReason: 'end_turn' })],
'/Users/someone/my-project',
);
const adapter = new ClaudeCodeSessionAdapter({ claudeHome: home });
assert.equal((await adapter.listSessions({ cwd: '/Users/someone/my-project' })).length, 1);
assert.equal((await adapter.listSessions({ cwd: '/Users/someone/my' })).length, 0);
});
});
test('every emitted message survives the canonical decoder', async () => {
// The importer round-trips adapter output through `decodeStoredMessage`,
// so a shape this adapter invents is rejected at persistence rather than
// stored. Asserting it here names the adapter as the culprit instead.
await withClaudeHome(async (home) => {
await seed(home, 'aaaaaaaa-0000-4000-8000-000000000009', [
userRecord('do the thing'),
assistantRecord({ thinking: 'considering', stopReason: 'tool_use' }),
assistantRecord({ toolUse: { id: 'toolu_x', name: 'Bash' }, stopReason: 'tool_use' }),
toolResultRecord('toolu_x', 'ok'),
assistantRecord({ text: 'Finished.', stopReason: 'end_turn' }),
]);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000009');
assert.ok(messages.length > 0);
for (const message of messages) {
assert.doesNotThrow(() => decodeCanonicalMessage(JSON.parse(JSON.stringify(message))));
}
});
});
test('a corrupt line does not fail an otherwise readable transcript', async () => {
await withClaudeHome(async (home) => {
const dir = join(home, 'projects', '-workspace-project');
await mkdir(dir, { recursive: true });
const lines = [
JSON.stringify(userRecord('first')),
'{ this is not json',
JSON.stringify(assistantRecord({ text: 'second', stopReason: 'end_turn' })),
];
await writeFile(
join(dir, 'aaaaaaaa-0000-4000-8000-000000000010.jsonl'),
`${lines.join('\n')}\n`,
);
const messages = await read(home, 'aaaaaaaa-0000-4000-8000-000000000010');
assert.equal(terminalState(messages)?.status, 'completed');
});
});
test('is registered by the internal default registry', () => {
const registry = createExternalSessionAdapterRegistry();
assert.equal(registry.require('claude-code').id, 'claude-code');
// Codex must still be there — this adds a source rather than replacing one.
assert.equal(registry.require('codex').id, 'codex');
});
});
/* ------------------------------------------------------------------ */
function terminalState(
messages: readonly StoredMessage[],
): Extract<StoredMessage, { type: 'turn_state' }> | undefined {
return messages.find(
(message): message is Extract<StoredMessage, { type: 'turn_state' }> =>
message.type === 'turn_state',
);
}
async function read(home: string, sessionId: string): Promise<readonly StoredMessage[]> {
const adapter = new ClaudeCodeSessionAdapter({ claudeHome: home });
return (await adapter.readSession(sessionId)).messages;
}
function userRecord(text: string): Record<string, unknown> {
return {
type: 'user',
cwd: CWD,
timestamp: '2026-08-01T00:00:00.000Z',
message: { role: 'user', content: text },
};
}
function toolResultRecord(toolUseId: string, text: string): Record<string, unknown> {
return {
type: 'user',
cwd: CWD,
timestamp: '2026-08-01T00:00:02.000Z',
message: {
role: 'user',
content: [{ type: 'tool_result', tool_use_id: toolUseId, content: text }],
},
};
}
function assistantFragment(
messageId: string,
content: readonly Record<string, unknown>[],
): Record<string, unknown> {
return {
type: 'assistant',
cwd: CWD,
timestamp: '2026-08-01T00:00:01.000Z',
message: {
role: 'assistant',
id: messageId,
model: 'claude-opus-5',
content,
stop_reason: 'tool_use',
},
};
}
function assistantRecord(input: {
text?: string;
thinking?: string;
toolUse?: { id: string; name: string };
stopReason?: string;
}): Record<string, unknown> {
const content: Record<string, unknown>[] = [];
if (input.thinking) content.push({ type: 'thinking', thinking: input.thinking });
if (input.text) content.push({ type: 'text', text: input.text });
if (input.toolUse) {
content.push({ type: 'tool_use', id: input.toolUse.id, name: input.toolUse.name, input: {} });
}
return {
type: 'assistant',
cwd: CWD,
timestamp: '2026-08-01T00:00:01.000Z',
message: {
role: 'assistant',
id: 'msg_test',
model: 'claude-opus-5',
content,
...(input.stopReason ? { stop_reason: input.stopReason } : {}),
},
};
}
async function seed(
home: string,
sessionId: string,
records: readonly Record<string, unknown>[],
cwd = CWD,
): Promise<void> {
const dir = join(home, 'projects', cwd.replace(/\//gu, '-'));
await mkdir(dir, { recursive: true });
const lines = records.map((record) => JSON.stringify({ ...record, cwd }));
await writeFile(join(dir, `${sessionId}.jsonl`), `${lines.join('\n')}\n`);
}
async function withClaudeHome(run: (home: string) => Promise<void>): Promise<void> {
const home = await mkdtemp(join(tmpdir(), 'maka-claude-home-'));
try {
await run(home);
} finally {
await rm(home, { recursive: true, force: true });
}
}
@@ -0,0 +1,254 @@
/*
* 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 assert from 'node:assert/strict';
import { describe, test } from 'node:test';
import {
isPromptRecord,
resolveTranscriptLineage,
transcriptParentUuid,
type TranscriptRecord,
} from '../claude-code-transcript-lineage.js';
function user(uuid: string, parentUuid: string | null, text: string): TranscriptRecord {
return { type: 'user', uuid, parentUuid, message: { role: 'user', content: text } };
}
function assistant(
uuid: string,
parentUuid: string | null,
messageId: string,
content: readonly Record<string, unknown>[],
): TranscriptRecord {
return {
type: 'assistant',
uuid,
parentUuid,
message: { role: 'assistant', id: messageId, content },
};
}
function toolResult(uuid: string, parentUuid: string, toolUseId: string): TranscriptRecord {
return {
type: 'user',
uuid,
parentUuid,
message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: toolUseId }] },
};
}
/** The boundary as Claude Code writes it: no parent, and a *forward* logical link. */
function compactBoundary(uuid: string, preservedTailUuid: string): TranscriptRecord {
return {
type: 'system',
subtype: 'compact_boundary',
uuid,
parentUuid: null,
logicalParentUuid: preservedTailUuid,
compactMetadata: { trigger: 'manual', preservedSegment: { tailUuid: preservedTailUuid } },
};
}
const uuids = (result: { records: readonly TranscriptRecord[] }): readonly unknown[] =>
result.records.map((record) => record.uuid);
describe('resolveTranscriptLineage', () => {
test('a withdrawn prompt and its answer are dropped, the edit kept', () => {
// The corpus shape, 72 times: the user typed a prompt, edited it, and
// resubmitted. Both are written under the same parent. Importing both
// presents a question the user withdrew, and its answer, as conversation.
const result = resolveTranscriptLineage([
{ type: 'system', uuid: 'p0', parentUuid: null },
user('u1', 'p0', 'StreamVByte 是什么类型?我忘了'),
assistant('a1', 'u1', 'msg_1', [{ type: 'text', text: 'answer to the withdrawn one' }]),
user('u2', 'p0', 'StreamVByte 是什么方式?我忘了'),
assistant('a2', 'u2', 'msg_2', [{ type: 'text', text: 'answer to the one asked' }]),
]);
assert.deepEqual(uuids(result), ['p0', 'u2', 'a2']);
assert.equal(result.withdrawnPrompts, 1);
assert.equal(result.abandoned, 2);
});
test('the whole withdrawn subtree goes, not just its head', () => {
const result = resolveTranscriptLineage([
{ type: 'system', uuid: 'p0', parentUuid: null },
user('u1', 'p0', 'withdrawn'),
assistant('a1', 'u1', 'msg_1', [{ type: 'tool_use', id: 'call_dead', name: 'Read' }]),
toolResult('r1', 'a1', 'call_dead'),
assistant('a2', 'r1', 'msg_2', [{ type: 'text', text: 'abandoned' }]),
user('u2', 'p0', 'asked'),
assistant('a3', 'u2', 'msg_3', [{ type: 'text', text: 'kept' }]),
]);
assert.deepEqual(uuids(result), ['p0', 'u2', 'a3']);
assert.equal(result.abandoned, 4);
});
test('three siblings leave only the last', () => {
// Measured 3 times in the corpus: a prompt edited twice.
const result = resolveTranscriptLineage([
{ type: 'system', uuid: 'p0', parentUuid: null },
user('u1', 'p0', 'first try'),
user('u2', 'p0', 'second try'),
user('u3', 'p0', 'third try'),
assistant('a3', 'u3', 'msg_3', [{ type: 'text', text: 'kept' }]),
]);
assert.deepEqual(uuids(result), ['p0', 'u3', 'a3']);
assert.equal(result.withdrawnPrompts, 2);
});
test('an ordinary tool fork survives whole', () => {
// 281 of 358 forks in the corpus are this: a `tool_use` record has two
// children — the next fragment of the same response, and the result of
// the call it just made. Nothing was abandoned, and a walk that picked
// one child would strand the other.
const result = resolveTranscriptLineage([
user('u1', null, 'prompt'),
assistant('a1', 'u1', 'msg_1', [{ type: 'tool_use', id: 'call_1', name: 'Read' }]),
assistant('a2', 'a1', 'msg_1', [{ type: 'tool_use', id: 'call_2', name: 'Read' }]),
toolResult('r1', 'a1', 'call_1'),
toolResult('r2', 'a2', 'call_2'),
]);
assert.deepEqual(uuids(result), ['u1', 'a1', 'a2', 'r1', 'r2']);
assert.equal(result.abandoned, 0);
});
test('two tool results under one parent are both kept', () => {
// Sibling `user` records are a rewind only when they are prompts. A tool
// result is the harness answering the model, not the user asking again.
const result = resolveTranscriptLineage([
user('u1', null, 'prompt'),
assistant('a1', 'u1', 'msg_1', [
{ type: 'tool_use', id: 'call_1', name: 'Read' },
{ type: 'tool_use', id: 'call_2', name: 'Read' },
]),
toolResult('r1', 'a1', 'call_1'),
toolResult('r2', 'a1', 'call_2'),
]);
assert.deepEqual(uuids(result), ['u1', 'a1', 'r1', 'r2']);
assert.equal(result.abandoned, 0);
assert.equal(result.withdrawnPrompts, 0);
});
test('an assistant fork with no prompt in it is left alone', () => {
const result = resolveTranscriptLineage([
user('u1', null, 'prompt'),
assistant('a1', 'u1', 'msg_1', [{ type: 'text', text: 'one' }]),
assistant('a2', 'u1', 'msg_2', [{ type: 'text', text: 'two' }]),
]);
assert.deepEqual(uuids(result), ['u1', 'a1', 'a2']);
assert.equal(result.abandoned, 0);
});
test('a tool result is not a prompt', () => {
assert.equal(isPromptRecord(user('u1', null, 'ask')), true);
assert.equal(isPromptRecord(toolResult('r1', 'a1', 'call_1')), false);
assert.equal(isPromptRecord(assistant('a1', 'u1', 'm', [])), false);
});
test('both sides of a compaction boundary survive', () => {
// The boundary starts a new root because the model's context restarted
// there. Both sides are conversation that happened.
const result = resolveTranscriptLineage([
user('u1', null, 'before compaction'),
assistant('a1', 'u1', 'msg_1', [{ type: 'text', text: 'pre-boundary reply' }]),
compactBoundary('b1', 'a1'),
{ type: 'user', uuid: 's1', parentUuid: 'b1', isCompactSummary: true, message: {} },
user('u2', 's1', 'after compaction'),
assistant('a2', 'u2', 'msg_2', [{ type: 'text', text: 'post-boundary reply' }]),
]);
assert.deepEqual(uuids(result), ['u1', 'a1', 'b1', 's1', 'u2', 'a2']);
assert.equal(result.abandoned, 0);
assert.equal(result.compactBoundaries, 1);
});
test("a boundary's logicalParentUuid is not followed as a parent", () => {
// It holds `preservedSegment.tailUuid` — a record written AFTER the
// boundary. Reading it as a parent points forward and closes a cycle
// through the summary.
assert.equal(transcriptParentUuid(compactBoundary('b1', 'later')), undefined);
const result = resolveTranscriptLineage([
user('u1', null, 'before'),
assistant('a1', 'u1', 'msg_1', [{ type: 'text', text: 'pre' }]),
compactBoundary('b1', 'u2'),
{ type: 'user', uuid: 's1', parentUuid: 'b1', isCompactSummary: true, message: {} },
user('u2', 's1', 'after'),
]);
assert.deepEqual(uuids(result), ['u1', 'a1', 'b1', 's1', 'u2']);
assert.equal(result.abandoned, 0);
});
test('a rewind before a compaction boundary does not disturb what follows', () => {
const result = resolveTranscriptLineage([
{ type: 'system', uuid: 'p0', parentUuid: null },
user('u1', 'p0', 'withdrawn before'),
assistant('a_dead', 'u1', 'msg_dead', [{ type: 'text', text: 'abandoned pre-boundary' }]),
user('u1b', 'p0', 'asked before'),
assistant('a1', 'u1b', 'msg_1', [{ type: 'text', text: 'kept pre-boundary' }]),
compactBoundary('b1', 'a1'),
user('u2', 'b1', 'after'),
assistant('a2', 'u2', 'msg_2', [{ type: 'text', text: 'kept post-boundary' }]),
]);
assert.deepEqual(uuids(result), ['p0', 'u1b', 'a1', 'b1', 'u2', 'a2']);
assert.equal(result.abandoned, 2);
});
test('a repeated uuid is kept once', () => {
const first = user('u1', null, 'prompt');
const result = resolveTranscriptLineage([first, { ...first }, assistant('a1', 'u1', 'm', [])]);
assert.deepEqual(uuids(result), ['u1', 'a1']);
assert.equal(result.duplicates, 1);
});
test('a record the graph cannot place is kept', () => {
// Silence from the graph is not evidence of abandonment. Dropping history
// is the failure that cannot be undone once it is canonical.
const result = resolveTranscriptLineage([
{ type: 'user', message: { role: 'user', content: 'no uuid' } },
user('u1', null, 'prompt'),
assistant('a1', 'u1', 'msg_1', [{ type: 'text', text: 'reply' }]),
]);
assert.equal(result.records.length, 3);
assert.equal(result.abandoned, 0);
});
test('a sidechain record is passed through untouched', () => {
const result = resolveTranscriptLineage([
user('u1', null, 'prompt'),
{ type: 'assistant', uuid: 'sc1', parentUuid: 'nothing', isSidechain: true, message: {} },
]);
assert.equal(result.records.length, 2);
assert.equal(result.abandoned, 0);
});
test('a parent cycle terminates instead of hanging the import', () => {
// These links are written by another process; a cycle has to fail the
// walk, not spin in it.
const result = resolveTranscriptLineage([
{ type: 'user', uuid: 'x', parentUuid: 'y', message: { role: 'user', content: 'a' } },
{ type: 'user', uuid: 'y', parentUuid: 'x', message: { role: 'user', content: 'b' } },
]);
assert.equal(result.records.length, 2);
});
test('an empty transcript resolves to nothing rather than throwing', () => {
const result = resolveTranscriptLineage([]);
assert.deepEqual(result.records, []);
assert.equal(result.abandoned, 0);
});
});
@@ -0,0 +1,105 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, test } from 'node:test';
import { createConversationOperationalStateStore } from '../conversation-operational-state.js';
import {
closeSqliteInteractionStoreFacade,
openSqliteInteractiveInteractionStoreForWrite,
} from '../interaction-store.js';
import { resolveStorageRoot, tryAcquireInteractiveRootOwner } from '../root-authority.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
after(removeTrackedControlDirectories);
test('persists Client Capability grants for one Session and purges them with it', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-client-capability-grant-'));
try {
const capability = trackControlDirectory(
await resolveStorageRoot({ path: root, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
const store = await openSqliteInteractiveInteractionStoreForWrite(owner.lease);
const key = {
sessionId: 'session-1',
providerId: 'provider-1',
contractId: 'contract-1',
serverId: 'desktop_browser',
toolName: 'browser_snapshot',
capability: 'browser' as const,
scope: { kind: 'browser_origin' as const, origin: 'https://example.com' },
};
try {
const grant = {
version: 1,
...key,
grantedAt: 10,
} as const;
const established = await store.establishRequest({
sessionId: 'session-1',
turnId: 'turn-1',
runId: 'run-1',
requestId: 'request-1',
createdAt: 5,
request: {
kind: 'client_capability',
toolUseId: 'tool-call-1',
target: key,
},
});
assert.equal(established.status, 'stable');
const committed = await store.commitClientCapabilityOutcome(
'request-1',
{ kind: 'client_capability_decision', decision: 'allow', committedAt: 10 },
grant,
);
assert.equal(committed.status, 'stable');
assert.deepEqual(await store.readClientCapabilitySessionGrant(key), grant);
assert.deepEqual(
await store.readClientCapabilitySessionGrant({
...key,
toolName: 'browser_click',
}),
grant,
);
const operationalState = createConversationOperationalStateStore(root);
try {
await operationalState.purge('session-1');
} finally {
operationalState.close();
}
assert.equal(await store.readClientCapabilitySessionGrant(key), undefined);
} finally {
closeSqliteInteractionStoreFacade(store);
await owner.close();
}
} finally {
await rm(root, { recursive: true, force: true });
}
});
@@ -0,0 +1,644 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { fileURLToPath } from 'node:url';
import { decodeCanonicalMessage } from '@maka/core/session';
import { CodexSessionAdapter } from '../codex-session-adapter.js';
import { createExternalSessionAdapterRegistry } from '../external-session-adapters.js';
const CURRENT_FIXTURE = fixturePath('codex-rollout-v0.144.jsonl');
const ITEM_COMPLETED_FIXTURE = fixturePath('codex-rollout-v0.149-item-completed.jsonl');
describe('CodexSessionAdapter', () => {
test('lists active and archived root Sessions from the newest Codex state database', async () => {
await withCodexHome(async (codexHome) => {
const activePath = await seedFixtureRollout(codexHome, 'codex-session-1', false);
const archivedPath = await seedMinimalRollout(
codexHome,
'codex-session-archived',
true,
'/workspace/archive',
'Archived task',
);
await seedStateDatabase(codexHome, [
{
id: 'codex-session-1',
rolloutPath: activePath,
cwd: '/workspace/project',
name: 'Named Codex thread',
createdAtMs: 1000,
updatedAtMs: 3000,
archived: false,
source: 'cli',
},
{
id: 'codex-session-archived',
rolloutPath: archivedPath,
cwd: '/workspace/archive',
name: 'Archived Codex thread',
createdAtMs: 1500,
updatedAtMs: 2000,
archived: true,
source: 'vscode',
},
{
id: 'codex-subagent',
rolloutPath: activePath,
cwd: '/workspace/project',
name: 'Internal child',
createdAtMs: 2000,
updatedAtMs: 4000,
archived: false,
source: '{"subagent":{"thread_spawn":{"parent_thread_id":"parent"}}}',
},
]);
const adapter = new CodexSessionAdapter({ codexHome });
assert.equal(await adapter.detect(), true);
assert.deepEqual(await adapter.listSessions(), [
{
id: 'codex-session-1',
name: 'Named Codex thread',
cwd: '/workspace/project',
createdAt: 1_000_000,
updatedAt: 3_000_000,
archived: false,
},
]);
assert.deepEqual(
(await adapter.listSessions({ includeArchived: true })).map((session) => session.id),
['codex-session-1', 'codex-session-archived'],
);
// The same text query the Claude Code adapter honours. A catalog filter
// that silently worked for one source and not the other would be worse
// than none — the user cannot see which source dropped their term.
assert.deepEqual(
(await adapter.listSessions({ text: 'named' })).map((session) => session.id),
['codex-session-1'],
);
assert.deepEqual(
(await adapter.listSessions({ text: '/workspace/project' })).map((session) => session.id),
['codex-session-1'],
);
assert.equal((await adapter.listSessions({ text: 'kubernetes' })).length, 0);
// A blank box selects nothing, so it must not filter.
assert.equal((await adapter.listSessions({ text: ' ' })).length, 1);
// Text does not override the archived gate.
assert.equal((await adapter.listSessions({ text: 'archived' })).length, 0);
assert.deepEqual(
(await adapter.listSessions({ includeArchived: true, text: 'archived' })).map(
(session) => session.id,
),
['codex-session-archived'],
);
assert.deepEqual(
await adapter.listSessions({ includeArchived: true, cwd: '/workspace/archive/' }),
[
{
id: 'codex-session-archived',
name: 'Archived Codex thread',
cwd: '/workspace/archive',
createdAt: 1_500_000,
updatedAt: 2_000_000,
archived: true,
},
],
);
});
});
test('lists every thread source the foreign-session scanner accepts (#3693)', async () => {
// The adapter owned its own token set, so bare `atlas`/`chatgpt` and a
// wrapped `{"custom":"cli"}` were dropped here while the scanner in
// `@maka/core/foreign-session` listed them. Both gates now share one
// authority, so the catalog and the scan agree on every shape.
await withCodexHome(async (codexHome) => {
const sources = ['cli', 'exec', 'vscode', 'atlas', 'chatgpt'] as const;
const rows: StateRow[] = [];
for (const [index, source] of sources.entries()) {
const bareId = `codex-bare-${source}`;
const wrappedId = `codex-wrapped-${source}`;
rows.push({
id: bareId,
rolloutPath: await seedMinimalRollout(codexHome, bareId, false, '/workspace', 'Task'),
cwd: '/workspace',
name: `bare ${source}`,
createdAtMs: 1000 + index,
updatedAtMs: 3000 + index,
archived: false,
source,
});
rows.push({
id: wrappedId,
rolloutPath: await seedMinimalRollout(codexHome, wrappedId, false, '/workspace', 'Task'),
cwd: '/workspace',
name: `wrapped ${source}`,
createdAtMs: 1100 + index,
updatedAtMs: 3100 + index,
archived: false,
source: JSON.stringify({ custom: source }),
});
}
const subagentId = 'codex-subagent-drop';
rows.push({
id: subagentId,
rolloutPath: await seedMinimalRollout(codexHome, subagentId, false, '/workspace', 'Task'),
cwd: '/workspace',
name: 'internal child',
createdAtMs: 2000,
updatedAtMs: 4000,
archived: false,
source: '{"subagent":{"thread_spawn":{"parent_thread_id":"parent"}}}',
});
await seedStateDatabase(codexHome, rows);
const listed = new Set(
(await new CodexSessionAdapter({ codexHome }).listSessions()).map((session) => session.id),
);
for (const source of sources) {
assert.ok(listed.has(`codex-bare-${source}`), `bare ${source} was dropped`);
assert.ok(listed.has(`codex-wrapped-${source}`), `wrapped ${source} was dropped`);
}
// Internal subagent threads stay out of the catalog.
assert.equal(listed.has(subagentId), false);
assert.equal(listed.size, sources.length * 2);
});
});
test('a Windows path spelling reaches the matcher instead of being lost in SQL', async () => {
// The SQL used to prefilter with `cwd IN (<spelling variants>)`, and
// SQLite compares those exactly — a row stored `C:\\Repo\\App` was
// discarded before the shared matcher could see that `c:/repo/app` names
// the same project. This drives the real state-database path, not the
// matcher in isolation, because that is where the row was being dropped.
await withCodexHome(async (codexHome) => {
const rolloutPath = await seedMinimalRollout(
codexHome,
'codex-win',
false,
'C:\\Repo\\App',
'hello',
);
await seedStateDatabase(codexHome, [
{
id: 'codex-win',
rolloutPath,
cwd: 'C:\\Repo\\App',
name: 'Windows-shaped path',
createdAtMs: 1_000,
updatedAtMs: 2_000,
archived: false,
source: 'cli',
},
]);
const adapter = new CodexSessionAdapter({ codexHome });
for (const cwd of ['C:\\Repo\\App', 'C:/Repo/App', 'c:/repo/app', 'c:\\repo\\app\\']) {
assert.deepEqual(
(await adapter.listSessions({ cwd })).map((session) => session.id),
['codex-win'],
`cwd=${cwd}`,
);
}
// A genuinely different project is still excluded.
assert.equal((await adapter.listSessions({ cwd: 'C:/Repo/Other' })).length, 0);
});
});
test('converts Codex presentation events and raw tool items without duplicates', async () => {
await withCodexHome(async (codexHome) => {
await seedFixtureRollout(codexHome, 'codex-session-1', false);
const adapter = new CodexSessionAdapter({ codexHome });
assert.deepEqual(await adapter.listSessions(), [
{
id: 'codex-session-1',
name: 'Fix the parser',
cwd: '/workspace/project',
createdAt: Date.parse('2026-08-08T00:00:00.000Z'),
updatedAt: await rolloutMtime(codexHome, 'codex-session-1', false),
archived: false,
},
]);
const session = await adapter.readSession('codex-session-1');
assert.deepEqual(session.metadata, {
name: 'Fix the parser',
cwd: '/workspace/project',
});
assert.equal(session.messages.length, 9);
for (const message of session.messages) {
assert.deepEqual(decodeCanonicalMessage(message), message);
}
assert.deepEqual(session.messages[0], {
type: 'user',
id: 'codex-user-1',
turnId: 'codex-turn-1',
ts: Date.parse('2026-08-08T00:00:02.000Z'),
text: 'Fix the parser',
});
assert.deepEqual(session.messages[1], {
type: 'assistant',
id: 'codex-codex-session-1-reasoning-7',
turnId: 'codex-turn-1',
ts: Date.parse('2026-08-08T00:00:03.000Z'),
text: '',
thinking: { text: 'Inspect the failing path.' },
contentOrder: ['thinking'],
modelId: 'gpt-codex-test',
});
assert.equal(session.messages[2]?.type, 'assistant');
assert.equal(session.messages[2]?.text, 'I found the issue.');
assert.deepEqual(session.messages[3], {
type: 'tool_call',
id: 'call-wait-1',
turnId: 'codex-turn-1',
ts: Date.parse('2026-08-08T00:00:05.000Z'),
toolName: 'wait',
args: { milliseconds: 25 },
});
assert.deepEqual(session.messages[4], {
type: 'tool_result',
id: 'function-output-1',
turnId: 'codex-turn-1',
ts: Date.parse('2026-08-08T00:00:06.000Z'),
toolUseId: 'call-wait-1',
isError: false,
content: { kind: 'text', text: 'waited' },
});
assert.equal(session.messages[5]?.type, 'tool_call');
assert.equal(session.messages[5]?.args, '*** Begin Patch');
assert.deepEqual(
session.messages[6]?.type === 'tool_result' ? session.messages[6].content : undefined,
{ kind: 'text', text: 'Done\n1 file changed' },
);
assert.equal(session.messages[7]?.type, 'system_note');
assert.equal(session.messages[8]?.type, 'turn_state');
assert.equal(session.messages[8]?.status, 'completed');
});
});
test('converts Codex Desktop completed items without importing response mirrors', async () => {
await withCodexHome(async (codexHome) => {
const sessionId = 'codex-item-completed';
await seedRawRollout(codexHome, sessionId, await readFile(ITEM_COMPLETED_FIXTURE, 'utf8'));
const adapter = new CodexSessionAdapter({ codexHome });
assert.deepEqual(
(await adapter.listSessions()).map(({ id, name }) => ({ id, name })),
[{ id: sessionId, name: 'Analyze the image. Use OpenCV.js.' }],
);
const session = await adapter.readSession(sessionId);
assert.deepEqual(session.metadata, {
name: 'Analyze the image. Use OpenCV.js.',
cwd: '/workspace/opencv',
});
assert.equal(session.messages.length, 4);
assert.deepEqual(
session.messages.map((message) => message.type),
['user', 'assistant', 'assistant', 'turn_state'],
);
for (const message of session.messages) {
assert.deepEqual(decodeCanonicalMessage(message), message);
}
assert.deepEqual(session.messages[0], {
type: 'user',
id: 'user-client-1',
turnId: 'codex-turn-item-completed',
ts: Date.parse('2026-08-22T00:00:02.100Z'),
text: 'Analyze the image. Use OpenCV.js.',
});
assert.deepEqual(session.messages[1], {
type: 'assistant',
id: 'reasoning-item-1',
turnId: 'codex-turn-item-completed',
ts: Date.parse('2026-08-22T00:00:03.000Z'),
text: '',
thinking: { text: 'Inspect the pixels.\nDraft the solution.' },
contentOrder: ['thinking'],
modelId: 'gpt-codex-item-test',
});
assert.deepEqual(session.messages[2], {
type: 'assistant',
id: 'assistant-item-1',
turnId: 'codex-turn-item-completed',
ts: Date.parse('2026-08-22T00:00:04.000Z'),
text: 'Use canvas. Then process the pixels.',
modelId: 'gpt-codex-item-test',
contentOrder: ['text'],
});
assert.equal(session.messages[3]?.type, 'turn_state');
assert.equal(session.messages[3]?.status, 'completed');
});
});
test('imports terminal errors as failed without failing turns on non-terminal errors', async () => {
await withCodexHome(async (codexHome) => {
const sessionId = 'codex-error-semantics';
await seedRawRollout(codexHome, sessionId, errorSemanticsRollout(sessionId));
const session = await new CodexSessionAdapter({ codexHome }).readSession(sessionId);
assert.deepEqual(
session.messages
.filter((message) => message.type === 'turn_state')
.map(({ turnId, status, errorClass }) => ({ turnId, status, errorClass })),
[
{ turnId: 'turn-terminal', status: 'failed', errorClass: 'codex_error' },
{ turnId: 'turn-rollback', status: 'completed', errorClass: undefined },
{ turnId: 'turn-not-steerable', status: 'completed', errorClass: undefined },
],
);
});
});
test('filesystem fallback excludes internal subagent rollouts', async () => {
await withCodexHome(async (codexHome) => {
await seedMinimalRollout(
codexHome,
'codex-root-fallback',
false,
'/workspace/root',
'Root task',
);
const subagentId = 'codex-subagent-fallback';
await seedRawRollout(
codexHome,
subagentId,
minimalRollout(subagentId, '/workspace/root', 'Internal task', {
subagent: {
thread_spawn: { parent_thread_id: 'parent', depth: 1 },
},
}),
);
const adapter = new CodexSessionAdapter({ codexHome });
assert.deepEqual(
(await adapter.listSessions()).map((session) => session.id),
['codex-root-fallback'],
);
await assert.rejects(adapter.readSession(subagentId), /not found/);
});
});
test('rejects corrupt interior records, tolerates a torn tail, and bounds full reads', async () => {
await withCodexHome(async (codexHome) => {
const fixture = await readFile(CURRENT_FIXTURE, 'utf8');
const corruptId = 'codex-corrupt';
await seedRawRollout(
codexHome,
corruptId,
fixture
.replaceAll('codex-session-1', corruptId)
.replace(
'\n{"timestamp":"2026-08-08T00:00:01.000Z"',
'\nnot-json\n{"timestamp":"2026-08-08T00:00:01.000Z"',
),
);
const tornId = 'codex-torn';
await seedRawRollout(
codexHome,
tornId,
`${fixture.replaceAll('codex-session-1', tornId)}{"timestamp"`,
);
const adapter = new CodexSessionAdapter({ codexHome });
await assert.rejects(adapter.readSession(corruptId), /Invalid Codex rollout.*line 2/);
assert.equal((await adapter.readSession(tornId)).messages.length, 9);
const bounded = new CodexSessionAdapter({ codexHome, maxRolloutBytes: 100 });
await assert.rejects(bounded.readSession(tornId), /exceeds 100 bytes/);
});
});
test('never follows a state database rollout path outside CODEX_HOME', async () => {
const outside = await mkdtemp(join(tmpdir(), 'maka-codex-outside-'));
try {
await withCodexHome(async (codexHome) => {
const id = 'codex-escaped';
const escapedPath = join(outside, `rollout-2026-08-08T00-00-00-${id}.jsonl`);
await writeFile(escapedPath, minimalRollout(id, '/outside', 'outside'));
await seedStateDatabase(codexHome, [
{
id,
rolloutPath: escapedPath,
cwd: '/outside',
name: 'Escaped',
createdAtMs: 1000,
updatedAtMs: 2000,
archived: false,
source: 'cli',
},
]);
const adapter = new CodexSessionAdapter({ codexHome });
assert.deepEqual(await adapter.listSessions(), []);
await assert.rejects(adapter.readSession(id), /not found/);
});
} finally {
await rm(outside, { recursive: true, force: true });
}
});
test('is registered by the internal default registry', async () => {
await withCodexHome(async (codexHome) => {
const registry = createExternalSessionAdapterRegistry({ codex: { codexHome } });
assert.equal(registry.require('codex').id, 'codex');
});
});
});
function fixturePath(name: string): string {
return fileURLToPath(new URL(`../../src/__tests__/fixtures/${name}`, import.meta.url));
}
async function withCodexHome(run: (codexHome: string) => Promise<void>): Promise<void> {
const codexHome = await mkdtemp(join(tmpdir(), 'maka-codex-adapter-'));
try {
await run(codexHome);
} finally {
await rm(codexHome, { recursive: true, force: true });
}
}
async function seedFixtureRollout(
codexHome: string,
sessionId: string,
archived: boolean,
): Promise<string> {
const fixture = (await readFile(CURRENT_FIXTURE, 'utf8')).replaceAll(
'codex-session-1',
sessionId,
);
return seedRawRollout(codexHome, sessionId, fixture, archived);
}
async function seedMinimalRollout(
codexHome: string,
sessionId: string,
archived: boolean,
cwd: string,
userText: string,
): Promise<string> {
return seedRawRollout(codexHome, sessionId, minimalRollout(sessionId, cwd, userText), archived);
}
async function seedRawRollout(
codexHome: string,
sessionId: string,
content: string,
archived = false,
): Promise<string> {
const directory = archived
? join(codexHome, 'archived_sessions')
: join(codexHome, 'sessions', '2026', '08', '08');
await mkdir(directory, { recursive: true });
const path = join(directory, `rollout-2026-08-08T00-00-00-${sessionId}.jsonl`);
await writeFile(path, content);
return path;
}
function minimalRollout(
sessionId: string,
cwd: string,
userText: string,
source: unknown = 'cli',
): string {
return [
JSON.stringify({
timestamp: '2026-08-08T00:00:00.000Z',
type: 'session_meta',
payload: { session_id: sessionId, id: sessionId, cwd, source },
}),
JSON.stringify({
timestamp: '2026-08-08T00:00:01.000Z',
type: 'event_msg',
payload: { type: 'user_message', message: userText },
}),
'',
].join('\n');
}
function errorSemanticsRollout(sessionId: string): string {
const event = (second: number, payload: Record<string, unknown>): string =>
JSON.stringify({
timestamp: `2026-08-08T00:00:${String(second).padStart(2, '0')}.000Z`,
type: 'event_msg',
payload,
});
return [
JSON.stringify({
timestamp: '2026-08-08T00:00:00.000Z',
type: 'session_meta',
payload: { session_id: sessionId, id: sessionId, cwd: '/workspace', source: 'cli' },
}),
event(1, { type: 'task_started', turn_id: 'turn-terminal' }),
event(2, { type: 'user_message', message: 'Fail terminally' }),
event(3, {
type: 'task_complete',
turn_id: 'turn-terminal',
error: { message: 'capacity', codex_error_info: 'server_overloaded' },
}),
event(4, { type: 'task_started', turn_id: 'turn-rollback' }),
event(5, { type: 'user_message', message: 'Rollback warning' }),
event(6, {
type: 'error',
message: 'rollback failed',
codex_error_info: 'thread_rollback_failed',
}),
event(7, { type: 'task_complete', turn_id: 'turn-rollback' }),
event(8, { type: 'task_started', turn_id: 'turn-not-steerable' }),
event(9, { type: 'user_message', message: 'Steer review' }),
event(10, {
type: 'error',
message: 'cannot steer review',
codex_error_info: { active_turn_not_steerable: { turn_kind: 'review' } },
}),
event(11, { type: 'task_complete', turn_id: 'turn-not-steerable' }),
'',
].join('\n');
}
interface StateRow {
id: string;
rolloutPath: string;
cwd: string;
name: string;
createdAtMs: number;
updatedAtMs: number;
archived: boolean;
source: string;
}
async function seedStateDatabase(codexHome: string, rows: readonly StateRow[]): Promise<void> {
const { DatabaseSync } = await import('node:sqlite');
const database = new DatabaseSync(join(codexHome, 'state_5.sqlite'));
try {
database.exec(`
CREATE TABLE threads (
id TEXT PRIMARY KEY,
rollout_path TEXT NOT NULL,
cwd TEXT,
name TEXT,
created_at_ms INTEGER,
updated_at_ms INTEGER,
archived INTEGER,
source TEXT
)
`);
const insert = database.prepare(`
INSERT INTO threads (
id, rollout_path, cwd, name, created_at_ms, updated_at_ms, archived, source
) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
`);
for (const row of rows) {
insert.run(
row.id,
row.rolloutPath,
row.cwd,
row.name,
row.createdAtMs,
row.updatedAtMs,
row.archived ? 1 : 0,
row.source,
);
}
} finally {
database.close();
}
}
async function rolloutMtime(
codexHome: string,
sessionId: string,
archived: boolean,
): Promise<number> {
const { stat } = await import('node:fs/promises');
const directory = archived
? join(codexHome, 'archived_sessions')
: join(codexHome, 'sessions', '2026', '08', '08');
return (await stat(join(directory, `rollout-2026-08-08T00-00-00-${sessionId}.jsonl`))).mtimeMs;
}
@@ -0,0 +1,153 @@
/*
* 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 { strict as assert } from 'node:assert';
import { describe, it } from 'node:test';
import type { LlmConnection } from '@maka/core/llm-connections';
import {
CONFIG_TRANSFER_SCHEMA_VERSION,
buildConfigBundle,
parseConfigBundle,
planConnectionMerge,
serializeConfigBundle,
} from '../config-transfer.js';
function conn(slug: string, extra: Partial<LlmConnection> = {}): LlmConnection {
return {
slug,
name: slug,
providerType: 'deepseek',
defaultModel: 'deepseek-v4-pro',
enabled: true,
createdAt: 1,
updatedAt: 1,
...extra,
};
}
describe('config-transfer', () => {
it('records only the selected categories in includedData and round-trips', () => {
const bundle = buildConfigBundle({
appVersion: '0.1.0',
data: {
connections: [conn('deepseek-main')],
settings: { theme: 'dark' },
},
now: () => new Date('2026-07-02T00:00:00.000Z'),
});
assert.equal(bundle.schemaVersion, CONFIG_TRANSFER_SCHEMA_VERSION);
assert.deepEqual(bundle.includedData, ['connections', 'settings']);
assert.equal(bundle.exportedAt, '2026-07-02T00:00:00.000Z');
const parsed = parseConfigBundle(serializeConfigBundle(bundle));
assert.ok(parsed.ok);
assert.deepEqual(parsed.bundle.includedData, ['connections', 'settings']);
assert.deepEqual(parsed.bundle.data.connections, [conn('deepseek-main')]);
assert.deepEqual(parsed.bundle.data.settings, { theme: 'dark' });
assert.equal(parsed.bundle.data.memory, undefined);
});
it('carries credentials only when the user opted into that category', () => {
const withCreds = buildConfigBundle({
appVersion: '0.1.0',
data: { credentials: [{ slug: 'deepseek-main', kind: 'api_key', value: 'sk-real' }] },
});
assert.deepEqual(withCreds.includedData, ['credentials']);
const parsed = parseConfigBundle(serializeConfigBundle(withCreds));
assert.ok(parsed.ok);
assert.deepEqual(parsed.bundle.data.credentials, [
{ slug: 'deepseek-main', kind: 'api_key', value: 'sk-real' },
]);
});
it('drops a credentials payload that is not declared in includedData', () => {
// Hand-edited / mislabeled file: data has credentials but manifest omits it.
const raw = JSON.stringify({
schemaVersion: 1,
includedData: ['connections'],
data: {
connections: [conn('deepseek-main')],
credentials: [{ slug: 'x', kind: 'api_key', value: 'sk-should-not-import' }],
},
});
const parsed = parseConfigBundle(raw);
assert.ok(parsed.ok);
assert.equal(parsed.bundle.data.credentials, undefined);
assert.ok(!parsed.bundle.includedData.includes('credentials'));
assert.ok(!serializeConfigBundle(parsed.bundle).includes('sk-should-not-import'));
});
it('fails closed on an unknown schema version', () => {
const raw = JSON.stringify({ schemaVersion: 999, includedData: [], data: {} });
const parsed = parseConfigBundle(raw);
assert.equal(parsed.ok, false);
assert.equal(parsed.ok === false && parsed.reason, 'unsupported_version');
});
it('rejects non-JSON and malformed payloads', () => {
assert.equal((parseConfigBundle('not json') as { reason: string }).reason, 'not_json');
assert.equal(
(parseConfigBundle(JSON.stringify({ schemaVersion: 1, data: {} })) as { reason: string })
.reason,
'malformed',
'missing includedData is malformed',
);
assert.equal(
(
parseConfigBundle(
JSON.stringify({ schemaVersion: 1, includedData: ['bogus'], data: {} }),
) as { reason: string }
).reason,
'malformed',
'unknown category in includedData is malformed',
);
});
it('plans connection merges with skip vs overwrite conflict strategies', () => {
const existing = [conn('a'), conn('b')];
const incoming = [conn('a', { name: 'A-new' }), conn('c')];
const skip = planConnectionMerge(existing, incoming, 'skip');
assert.deepEqual(skip.skipped, [{ slug: 'a', reason: 'exists' }]);
assert.deepEqual(
skip.create.map((c) => c.slug),
['c'],
);
assert.equal(skip.overwrite.length, 0);
const overwrite = planConnectionMerge(existing, incoming, 'overwrite');
assert.deepEqual(
overwrite.overwrite.map((c) => c.slug),
['a'],
);
assert.deepEqual(
overwrite.create.map((c) => c.slug),
['c'],
);
assert.equal(overwrite.skipped.length, 0);
});
it('de-dupes repeated slugs within the imported set', () => {
const plan = planConnectionMerge([], [conn('x'), conn('x'), conn('y')], 'skip');
assert.deepEqual(
plan.create.map((c) => c.slug),
['x', 'y'],
);
});
});
@@ -0,0 +1,245 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm, stat } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, test } from 'node:test';
import type { ContextOffloadLimits } from '@maka/core/context-offload';
import {
authenticateInteractiveContextOffloadReader,
authenticateInteractiveContextOffloadWriter,
createInteractiveContextOffloadReader,
openInteractiveContextOffloadStoreForWrite,
type InteractiveContextOffloadReader,
type InteractiveContextOffloadWriter,
} from '../context-offload-store.js';
import {
resolveStorageRoot,
StorageRootAuthorityError,
tryAcquireInteractiveRootOwner,
type InteractiveRootOwner,
type StorageRootLease,
} from '../root-authority.js';
import { CONTEXT_OFFLOAD_DATABASE_NAME } from '../sqlite-context-offload-store.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
after(removeTrackedControlDirectories);
test('requires authentic Storage Root leases and writer facades', async () => {
await assert.rejects(
() =>
openInteractiveContextOffloadStoreForWrite({} as StorageRootLease<'interactive', 'write'>, {
limits: testLimits(),
}),
invalidLease,
);
assert.throws(
() => authenticateInteractiveContextOffloadWriter({} as InteractiveContextOffloadWriter),
invalidLease,
);
assert.throws(
() => authenticateInteractiveContextOffloadReader({} as InteractiveContextOffloadReader),
invalidLease,
);
});
test('single-flights one limit-bound writer and snapshots admitted inputs', async () => {
await withInteractiveOwner(async (owner, root) => {
const mutableLimits = testLimits();
const opening = openInteractiveContextOffloadStoreForWrite(owner.lease, {
limits: mutableLimits,
});
const concurrentOpening = openInteractiveContextOffloadStoreForWrite(owner.lease, {
limits: testLimits(),
});
const conflictingOpening = assert.rejects(
openInteractiveContextOffloadStoreForWrite(owner.lease, {
limits: { ...testLimits(), workspacePhysicalBytes: 63 },
}),
/different limits/u,
);
(mutableLimits.ownerMaxBytes as { tool_result_archive: number }).tool_result_archive = 0;
(mutableLimits as { sessionLogicalBytes: number }).sessionLogicalBytes = 0;
const [first, second] = await Promise.all([opening, concurrentOpening]);
try {
await conflictingOpening;
assert.strictEqual(second, first);
assert.strictEqual(authenticateInteractiveContextOffloadWriter(first), first);
const reader = createInteractiveContextOffloadReader(first);
assert.strictEqual(createInteractiveContextOffloadReader(first), reader);
assert.strictEqual(authenticateInteractiveContextOffloadReader(reader), reader);
assert.deepEqual(Object.keys(reader).sort(), ['access', 'kind', 'read']);
assert.equal((await stat(join(root, CONTEXT_OFFLOAD_DATABASE_NAME))).isFile(), true);
const bytes = new TextEncoder().encode('safe');
const input = {
sessionId: 'source',
owner: { kind: 'tool_result_archive' as const, ownerId: 'source-owner' },
bytes,
mediaType: 'application/json',
};
const putting = first.put(input);
input.sessionId = 'mutated';
input.owner.ownerId = 'mutated-owner';
input.mediaType = 'text/plain';
bytes.fill(0x78);
const stored = await putting;
assert.equal(stored.ok, true);
if (!stored.ok) return;
assert.equal(stored.record.sessionId, 'source');
assert.equal(stored.record.owner.ownerId, 'source-owner');
assert.equal(stored.record.mediaType, 'application/json');
assert.deepEqual(
await reader.read({ sessionId: 'source', refId: stored.record.refId, maxBytes: 64 }),
{ ok: true, record: stored.record, bytes: new TextEncoder().encode('safe') },
);
const copyInput = {
sourceSessionId: 'source',
targetSessionId: 'target',
references: [
{
sourceRefId: stored.record.refId,
targetOwner: { kind: 'tool_result_archive' as const, ownerId: 'target-owner' },
},
],
};
const copying = first.copyReferences(copyInput);
copyInput.targetSessionId = 'mutated-target';
copyInput.references[0]!.targetOwner.ownerId = 'mutated-target-owner';
const copied = await copying;
assert.equal(copied.ok, true);
if (!copied.ok) return;
assert.deepEqual(
await first.copyReferences({
sourceSessionId: 'source',
targetSessionId: 'target',
references: [
{
sourceRefId: stored.record.refId,
targetOwner: { kind: 'tool_result_archive', ownerId: 'target-owner' },
},
],
}),
copied,
);
} finally {
await first.close();
}
});
});
test('close drains admitted work, revokes the facade, and permits a clean reopen', async () => {
await withInteractiveOwner(async (owner) => {
const writer = await openInteractiveContextOffloadStoreForWrite(owner.lease, {
limits: testLimits(),
});
const admitted = writer.put({
sessionId: 'session-1',
owner: { kind: 'read_image_snapshot', ownerId: 'read-1' },
bytes: new TextEncoder().encode('image'),
mediaType: 'image/png',
});
const reader = createInteractiveContextOffloadReader(writer);
const closing = writer.close();
const reopening = openInteractiveContextOffloadStoreForWrite(owner.lease, {
limits: testLimits(),
});
assert.equal((await admitted).ok, true);
await closing;
await assert.rejects(writer.usage(), invalidLease);
assert.throws(() => authenticateInteractiveContextOffloadWriter(writer), invalidLease);
assert.throws(() => authenticateInteractiveContextOffloadReader(reader), invalidLease);
await assert.rejects(
reader.read({ sessionId: 'session-1', refId: 'ref-1', maxBytes: 64 }),
invalidLease,
);
const reopened = await reopening;
try {
assert.notStrictEqual(reopened, writer);
assert.deepEqual(await reopened.usage('session-1'), {
references: 1,
logicalBytes: 5,
physicalBytes: 5,
});
} finally {
await reopened.close();
}
});
});
test('root-owner close revokes new context-offload operations', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-context-offload-authority-revoke-'));
const capability = trackControlDirectory(
await resolveStorageRoot({ path: root, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
const writer = await openInteractiveContextOffloadStoreForWrite(owner.lease, {
limits: testLimits(),
});
try {
await owner.close();
await assert.rejects(writer.usage(), invalidLease);
} finally {
await writer.close();
await owner.close();
await rm(root, { recursive: true, force: true });
}
});
function testLimits(): ContextOffloadLimits {
return {
ownerMaxBytes: {
read_image_snapshot: 64,
tool_result_archive: 64,
},
sessionLogicalBytes: 64,
workspacePhysicalBytes: 64,
};
}
function invalidLease(error: unknown): boolean {
return error instanceof StorageRootAuthorityError && error.code === 'invalid_lease';
}
async function withInteractiveOwner(
run: (owner: InteractiveRootOwner, root: string) => Promise<void>,
): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-context-offload-authority-'));
const capability = trackControlDirectory(
await resolveStorageRoot({ path: root, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
await run(owner, root);
} finally {
await owner.close();
await rm(root, { recursive: true, force: true });
}
}
@@ -0,0 +1,336 @@
/*
* 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 assert from 'node:assert/strict';
import { chmod, mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import {
CREDENTIAL_SCHEMA_VERSION,
createFileCredentialStore,
withCredentialFileLock,
type CredentialCasResult,
type CredentialKind,
type CredentialStore,
} from '../credential-store.js';
const isPosix = process.platform !== 'win32';
async function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
const dir = await mkdtemp(join(tmpdir(), 'maka-cred-'));
try {
return await fn(dir);
} finally {
await rm(dir, { recursive: true, force: true });
}
}
describe('FileCredentialStore', () => {
test('round-trips secrets and returns null for missing ones', async () => {
await withTempDir(async (dir) => {
const store = createFileCredentialStore(dir);
assert.equal(await store.getSecret('openai-prod', 'api_key'), null);
await store.setSecret('openai-prod', 'api_key', 'sk-test-123');
assert.equal(await store.getSecret('openai-prod', 'api_key'), 'sk-test-123');
await store.deleteSecret('openai-prod', 'api_key');
assert.equal(await store.getSecret('openai-prod', 'api_key'), null);
});
});
test('deleteSecret(slug) with no kind clears every kind for that slug only', async () => {
await withTempDir(async (dir) => {
const store = createFileCredentialStore(dir);
await store.setSecret('a', 'api_key', 'key-a');
await store.setSecret('a', 'oauth_token', 'tok-a');
await store.setSecret('b', 'api_key', 'key-b');
await store.deleteSecret('a');
assert.equal(await store.getSecret('a', 'api_key'), null);
assert.equal(await store.getSecret('a', 'oauth_token'), null);
assert.equal(await store.getSecret('b', 'api_key'), 'key-b');
});
});
test('writes a versioned, plaintext (file-first) file', async () => {
await withTempDir(async (dir) => {
const store = createFileCredentialStore(dir);
await store.setSecret('openai-prod', 'api_key', 'sk-plain');
const raw = JSON.parse(await readFile(join(dir, 'credentials.json'), 'utf8')) as {
version: number;
values: Record<string, string>;
};
assert.equal(raw.version, CREDENTIAL_SCHEMA_VERSION);
// File-first: the value is stored as plaintext, not encoded.
assert.equal(raw.values['openai-prod:apiKey'], 'sk-plain');
});
});
test('reading an unknown / pre-migration schema fails closed', async () => {
await withTempDir(async (dir) => {
const path = join(dir, 'credentials.json');
// Legacy file: no `version` field (the safeStorage-era shape).
await writeFile(path, JSON.stringify({ values: { 'x:apiKey': 'enc' } }), 'utf8');
const legacy = createFileCredentialStore(dir);
await assert.rejects(legacy.getSecret('x', 'api_key'), /schema version/);
// Future version we don't understand.
await writeFile(path, JSON.stringify({ version: 999, values: {} }), 'utf8');
const future = createFileCredentialStore(dir);
await assert.rejects(future.getSecret('x', 'api_key'), /schema version/);
});
});
test('leaves no temp file behind after a write', async () => {
await withTempDir(async (dir) => {
const store = createFileCredentialStore(dir);
await store.setSecret('a', 'api_key', 'k');
const entries = await readdir(dir);
assert.deepEqual(entries, ['credentials.json']);
});
});
test('creates the file 0600 on POSIX', { skip: !isPosix }, async () => {
await withTempDir(async (dir) => {
const store = createFileCredentialStore(dir);
await store.setSecret('a', 'api_key', 'k');
const mode = (await stat(join(dir, 'credentials.json'))).mode & 0o777;
assert.equal(mode, 0o600);
});
});
test('re-chmods a pre-existing world-readable file to 0600 on write', {
skip: !isPosix,
}, async () => {
await withTempDir(async (dir) => {
const path = join(dir, 'credentials.json');
// A valid v1 file that was created with a loose mode.
await writeFile(path, JSON.stringify({ version: CREDENTIAL_SCHEMA_VERSION, values: {} }), {
encoding: 'utf8',
mode: 0o644,
});
const store = createFileCredentialStore(dir);
await store.setSecret('a', 'api_key', 'k');
const mode = (await stat(path)).mode & 0o777;
assert.equal(mode, 0o600);
});
});
test('hardens a pre-existing world-accessible workspace dir to 0700 on write', {
skip: !isPosix,
}, async () => {
await withTempDir(async (dir) => {
await chmod(dir, 0o777); // a loose dir that predates the hardening
const store = createFileCredentialStore(dir);
await store.setSecret('a', 'api_key', 'k');
// ensureSecretDir re-chmods an existing dir (mkdir's mode only applies on
// creation); the writer and the lock share it, so the lock can't leave
// the dir loose either.
assert.equal((await stat(dir)).mode & 0o777, 0o700);
});
});
test('serializes concurrent writes across slugs without clobbering', async () => {
await withTempDir(async (dir) => {
// With no in-instance queue, these contend directly on the file lock —
// this proves the lock alone serializes a read-modify-write so no slug is
// dropped. A handful is enough; more just adds lock-poll wall-clock.
const store = createFileCredentialStore(dir);
const count = 8;
await Promise.all(
Array.from({ length: count }, (_unused, i) =>
store.setSecret(`conn-${i}`, 'api_key', `key-${i}`),
),
);
for (let i = 0; i < count; i++) {
assert.equal(await store.getSecret(`conn-${i}`, 'api_key'), `key-${i}`);
}
});
});
test('two independent store instances writing concurrently both survive (cross-process lock)', async () => {
await withTempDir(async (dir) => {
// Separate instances => separate in-instance queues; only the file
// lock can stop a read-modify-write lost update between them.
const a = createFileCredentialStore(dir);
const b = createFileCredentialStore(dir);
await Promise.all([
a.setSecret('slug-a', 'api_key', 'AAA'),
b.setSecret('slug-b', 'api_key', 'BBB'),
]);
const reader = createFileCredentialStore(dir);
assert.equal(await reader.getSecret('slug-a', 'api_key'), 'AAA');
assert.equal(await reader.getSecret('slug-b', 'api_key'), 'BBB');
});
});
test('a held lock is waited on, never stolen (no lost update)', async () => {
await withTempDir(async (dir) => {
const path = join(dir, 'credentials.json');
// Hold the lock as another process (or a crashed one) would: the lock is
// the `${path}.lock` directory. The store must wait for it, never steal it.
const lockPath = `${path}.lock`;
await mkdir(lockPath);
const store = createFileCredentialStore(dir);
let settled = false;
const write = store.setSecret('a', 'api_key', 'V').then(() => {
settled = true;
});
// The lock is held, so the write is blocked before its critical section:
// it must not steal the lock and must not have written the file yet.
await assert.rejects(stat(path)); // file absent — proven blocked, not stolen
assert.equal(settled, false);
await rm(lockPath, { recursive: true, force: true }); // release
await write;
assert.equal(await store.getSecret('a', 'api_key'), 'V'); // proceeds only once the lock frees
});
});
test('a never-released lock fails loud with the lock path and recovery hint', async () => {
await withTempDir(async (dir) => {
const path = join(dir, 'credentials.json');
await mkdir(`${path}.lock`); // a crashed holder's lock that never releases
// A small timeout drives the fail-loud path without the production wait.
// The error must name the lock dir AND how to recover, so the guidance
// can't silently regress.
await assert.rejects(
withCredentialFileLock(path, async () => 'unreachable', 60),
(error: Error) =>
error.message.includes(`${path}.lock`) &&
/remove that directory and retry/.test(error.message),
);
});
});
});
describe('FileCredentialStore compareAndSetSecret', () => {
// Optional capability: exercise it through a guarded helper so a store that
// does not expose CAS is a caller's own fallback problem, not a test crash.
function cas(
store: CredentialStore,
slug: string,
kind: CredentialKind,
expected: string | null,
value: string,
): Promise<CredentialCasResult> {
assert.ok(store.compareAndSetSecret, 'file store exposes the CAS capability');
return store.compareAndSetSecret(slug, kind, expected, value);
}
test('commits when the basis still matches, and the write persists', async () => {
await withTempDir(async (dir) => {
const store = createFileCredentialStore(dir);
await store.setSecret('acct', 'oauth_token', 'tok-basis');
const result = await cas(store, 'acct', 'oauth_token', 'tok-basis', 'tok-next');
assert.deepEqual(result, { committed: true });
assert.equal(await store.getSecret('acct', 'oauth_token'), 'tok-next');
});
});
test('commits a write-if-absent (expected null) only while the entry is absent', async () => {
await withTempDir(async (dir) => {
// Decide "store has no token" and write in one serialized step. A value
// written between the check and the write must make this writer lose.
const importer = createFileCredentialStore(dir);
const other = createFileCredentialStore(dir);
// Someone writes a token after the importer would have read "absent".
await other.setSecret('acct', 'oauth_token', 'tok-live');
const blocked = await cas(importer, 'acct', 'oauth_token', null, 'tok-import');
assert.deepEqual(blocked, { committed: false, current: 'tok-live' });
assert.equal(await other.getSecret('acct', 'oauth_token'), 'tok-live');
// With a genuinely absent entry the same write-if-absent commits.
const committed = await cas(importer, 'other-acct', 'oauth_token', null, 'tok-import');
assert.deepEqual(committed, { committed: true });
assert.equal(await importer.getSecret('other-acct', 'oauth_token'), 'tok-import');
});
});
test('two store instances racing on the same basis: loser sees the entry changed and adopts it', async () => {
await withTempDir(async (dir) => {
// Two separate instances share the file (a cross-process refresh). Both
// read the same basis; only the file lock decides the winner.
const a = createFileCredentialStore(dir);
const b = createFileCredentialStore(dir);
await a.setSecret('acct', 'oauth_token', 'tok-basis');
// A commits first, then B tries with the now-stale basis.
const winner = await cas(a, 'acct', 'oauth_token', 'tok-basis', 'tok-A');
const loser = await cas(b, 'acct', 'oauth_token', 'tok-basis', 'tok-B');
assert.deepEqual(winner, { committed: true });
// Entry changed (not gone): current is a string the loser adopts.
assert.deepEqual(loser, { committed: false, current: 'tok-A' });
const reader = createFileCredentialStore(dir);
assert.equal(await reader.getSecret('acct', 'oauth_token'), 'tok-A');
});
});
test('a basis whose entry was deleted (logout) is distinguishable from a changed one', async () => {
await withTempDir(async (dir) => {
const a = createFileCredentialStore(dir);
const b = createFileCredentialStore(dir);
await a.setSecret('acct', 'oauth_token', 'tok-basis');
// A terminal logout removes the entry after B read its basis.
await a.deleteSecret('acct', 'oauth_token');
const result = await cas(b, 'acct', 'oauth_token', 'tok-basis', 'tok-resurrect');
// Entry gone (current === null): the caller must NOT resurrect it, and the
// write did not commit.
assert.deepEqual(result, { committed: false, current: null });
const reader = createFileCredentialStore(dir);
assert.equal(await reader.getSecret('acct', 'oauth_token'), null);
});
});
test('concurrent CAS from the same basis: exactly one wins, the loser returns the winner value', async () => {
await withTempDir(async (dir) => {
const a = createFileCredentialStore(dir);
const b = createFileCredentialStore(dir);
await a.setSecret('acct', 'oauth_token', 'tok-basis');
const [ra, rb] = await Promise.all([
cas(a, 'acct', 'oauth_token', 'tok-basis', 'tok-A'),
cas(b, 'acct', 'oauth_token', 'tok-basis', 'tok-B'),
]);
const winners = [ra, rb].filter((r) => r.committed);
assert.equal(winners.length, 1, 'exactly one CAS commits');
const winnerValue = ra.committed ? 'tok-A' : 'tok-B';
const loser = ra.committed ? rb : ra;
assert.deepEqual(loser, { committed: false, current: winnerValue });
const reader = createFileCredentialStore(dir);
assert.equal(await reader.getSecret('acct', 'oauth_token'), winnerValue);
});
});
});
@@ -0,0 +1,201 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, test } from 'node:test';
import type { DailyReviewArchive } from '@maka/core/daily-review';
import {
authenticateInteractiveDailyReviewAuthorityWriter,
openInteractiveDailyReviewAuthorityForWrite,
} from '../daily-review-authority.js';
import {
resolveStorageRoot,
StorageRootAuthorityError,
tryAcquireInteractiveRootOwner,
} from '../root-authority.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
// The control directory of each resolved root lives outside that root, so a
// temporary root's removal leaves it behind; reclaim the recorded rootIds here.
after(removeTrackedControlDirectories);
test('Daily Review authority serializes config revisions and preserves archives', async () => {
await withInteractiveRoot(async ({ capability }) => {
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
const [first, second] = await Promise.all([
openInteractiveDailyReviewAuthorityForWrite(owner.lease),
openInteractiveDailyReviewAuthorityForWrite(owner.lease),
]);
assert.equal(first, second);
assert.equal(authenticateInteractiveDailyReviewAuthorityWriter(first), first);
assert.deepEqual(await first.readConfig(), {
revision: 0,
config: { enabled: false, executeTime: '08:00', modelKey: '' },
});
assert.deepEqual(
await first.updateConfig(0, {
enabled: true,
executeTime: '09:30',
modelKey: 'openrouter::openrouter/free',
}),
{
kind: 'committed',
snapshot: {
revision: 1,
config: {
enabled: true,
executeTime: '09:30',
modelKey: 'openrouter::openrouter/free',
},
},
},
);
assert.deepEqual(
await second.updateConfig(0, {
enabled: false,
executeTime: '10:00',
modelKey: '',
}),
{ kind: 'revision_conflict', expectedRevision: 0, actualRevision: 1 },
);
const stored = await first.publishArchive(archive(), 180);
assert.deepEqual(await second.getArchive(stored.id), stored);
assert.deepEqual(
(await second.listArchivePage(null, 180)).archives.map((item) => item.id),
[stored.id],
);
first.close();
assert.throws(() => authenticateInteractiveDailyReviewAuthorityWriter(first), isInvalidLease);
const reopened = await openInteractiveDailyReviewAuthorityForWrite(owner.lease);
assert.equal((await reopened.readConfig()).revision, 1);
assert.deepEqual(await reopened.getArchive(stored.id), stored);
reopened.close();
} finally {
if (!owner.closed) await owner.close();
}
});
});
test('Daily Review authority rejects operations after its root lease closes', async () => {
await withInteractiveRoot(async ({ capability }) => {
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
const writer = await openInteractiveDailyReviewAuthorityForWrite(owner.lease);
await owner.close();
await assert.rejects(() => writer.readConfig(), isInvalidLease);
await assert.rejects(() => writer.publishArchive(archive(), 180), isInvalidLease);
writer.close();
});
});
test('Daily Review authority publishes and prunes archives in one operation', async () => {
await withInteractiveRoot(async ({ capability }) => {
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
const writer = await openInteractiveDailyReviewAuthorityForWrite(owner.lease);
const older = archive();
const newer = {
...archive(new Date(2026, 7, 4).getTime()),
id: '2026-08-04-1d',
generatedAt: older.generatedAt + 1,
};
await writer.publishArchive(older, 1);
await writer.publishArchive(newer, 1);
assert.deepEqual(
(await writer.listArchivePage(null, 180)).archives.map((item) => item.id),
[newer.id],
);
assert.equal(await writer.getArchive(older.id), null);
const oldest = archive(new Date(2026, 7, 2).getTime());
await writer.publishArchive(oldest, 1);
assert.deepEqual(
(await writer.listArchivePage(null, 180)).archives.map((item) => item.id),
[oldest.id],
);
assert.deepEqual(await writer.getArchive(oldest.id), oldest);
await assert.rejects(() => writer.publishArchive({ ...newer, id: '2026-08-05-1d' }, 1));
assert.deepEqual(
(await writer.listArchivePage(null, 180)).archives.map((item) => item.id),
[oldest.id],
);
writer.close();
} finally {
if (!owner.closed) await owner.close();
}
});
});
function archive(fromMs = new Date(2026, 7, 3).getTime()): DailyReviewArchive {
const start = new Date(fromMs);
const toMs = new Date(start.getFullYear(), start.getMonth(), start.getDate() + 1).getTime();
return {
id: `${start.getFullYear()}-${String(start.getMonth() + 1).padStart(2, '0')}-${String(
start.getDate(),
).padStart(2, '0')}-1d`,
day: { fromMs, toMs },
range: 1,
status: 'ok',
generatedAt: toMs + 1,
trigger: 'manual',
modelKey: 'openrouter::openrouter/free',
sections: { summary: 'One durable review.' },
totals: {
sessionCount: 1,
requestCount: 2,
totalTokens: 3,
costUsd: 0,
errorCount: 0,
},
};
}
async function withInteractiveRoot(
run: (input: {
capability: Awaited<ReturnType<typeof resolveStorageRoot<'interactive'>>>;
}) => Promise<void>,
): Promise<void> {
const base = await mkdtemp(join(tmpdir(), 'maka-daily-review-authority-'));
try {
const capability = trackControlDirectory(
await resolveStorageRoot({ path: join(base, 'interactive'), kind: 'interactive' }),
);
await run({ capability });
} finally {
await rm(base, { recursive: true, force: true });
}
}
function isInvalidLease(error: unknown): boolean {
return error instanceof StorageRootAuthorityError && error.code === 'invalid_lease';
}
@@ -0,0 +1,191 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import type { SessionExternalOrigin, SessionHeader, StoredMessage } from '@maka/core/session';
import {
ExternalSessionAdapterRegistry,
type ExternalSessionAdapter,
} from '@maka/core/external-session';
import {
ExternalSessionImporter,
type ExternalSessionImportTarget,
} from '../external-session-importer.js';
import { createSessionStore } from '../session-store.js';
describe('ExternalSessionImporter', () => {
test('forwards the exact external Session origin to imported persistence', async () => {
const calls: SessionExternalOrigin[] = [];
const adapter = fakeAdapter({
metadata: { name: 'Imported parser work', cwd: '/external/repo' },
messages: [],
});
const importer = new ExternalSessionImporter(new ExternalSessionAdapterRegistry([adapter]), {
createImportedSession: async (_input, _messages, externalOrigin) => {
calls.push(externalOrigin);
return {} as SessionHeader;
},
});
await importer.import({
adapterId: 'fake',
sourceSessionId: 'source-1',
target: target(),
});
assert.deepEqual(calls, [{ adapterId: 'fake', sourceSessionId: 'source-1' }]);
});
test('persists adapter output as native Maka StoredMessages', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-external-session-import-'));
const sessions = createSessionStore(root);
const messages: StoredMessage[] = [
{ type: 'user', id: 'user-1', turnId: 'turn-1', ts: 10, text: 'fix the parser' },
{
type: 'assistant',
id: 'assistant-1',
turnId: 'turn-1',
ts: 20,
text: 'done',
modelId: 'external-model',
},
];
const adapter = fakeAdapter({
metadata: { name: 'Imported parser work', cwd: '/external/repo' },
messages,
});
const importer = new ExternalSessionImporter(
new ExternalSessionAdapterRegistry([adapter]),
sessions,
);
try {
const header = await importer.import({
adapterId: 'fake',
sourceSessionId: 'source-1',
target: target(),
});
assert.equal(header.name, 'Imported parser work');
assert.equal(header.cwd, '/external/repo');
assert.equal(header.model, 'maka-model');
assert.equal(header.connectionLocked, true);
assert.deepEqual(header.externalOrigin, {
adapterId: 'fake',
sourceSessionId: 'source-1',
});
assert.deepEqual(await sessions.readMessages(header.id), messages);
await sessions.close?.();
const reopened = createSessionStore(root);
try {
assert.deepEqual((await reopened.readHeaderSnapshot(header.id)).externalOrigin, {
adapterId: 'fake',
sourceSessionId: 'source-1',
});
assert.deepEqual(await reopened.readMessages(header.id), messages);
} finally {
await reopened.close?.();
}
} finally {
await sessions.close?.();
await rm(root, { recursive: true, force: true });
}
});
test('allows the Maka target to override imported name and cwd', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-external-session-target-'));
const sessions = createSessionStore(root);
const importer = new ExternalSessionImporter(
new ExternalSessionAdapterRegistry([
fakeAdapter({ metadata: { name: 'Source name', cwd: '/source' }, messages: [] }),
]),
sessions,
);
try {
const header = await importer.import({
adapterId: 'fake',
sourceSessionId: 'source-1',
target: target({ name: 'Maka name', cwd: '/target' }),
});
assert.equal(header.name, 'Maka name');
assert.equal(header.cwd, '/target');
} finally {
await sessions.close?.();
await rm(root, { recursive: true, force: true });
}
});
test('rejects invalid adapter messages without exposing a partial Session', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-external-session-invalid-'));
const sessions = createSessionStore(root);
const adapter = fakeAdapter({
metadata: { name: 'Invalid import', cwd: '/repo' },
messages: [{ type: 'assistant' } as unknown as StoredMessage],
});
const importer = new ExternalSessionImporter(
new ExternalSessionAdapterRegistry([adapter]),
sessions,
);
try {
await assert.rejects(
importer.import({
adapterId: 'fake',
sourceSessionId: 'source-1',
target: target(),
}),
/Invalid stored message schema/,
);
assert.deepEqual(await sessions.listHeaders(), []);
} finally {
await sessions.close?.();
await rm(root, { recursive: true, force: true });
}
});
});
function target(overrides: Partial<ExternalSessionImportTarget> = {}): ExternalSessionImportTarget {
return {
llmConnectionSlug: 'fake',
model: 'maka-model',
permissionMode: 'ask',
...overrides,
};
}
function fakeAdapter(
session: Pick<
Awaited<ReturnType<ExternalSessionAdapter['readSession']>>,
'metadata' | 'messages'
>,
): ExternalSessionAdapter {
return {
id: 'fake',
detect: async () => true,
listSessions: async () => [],
readSession: async (sourceSessionId) => ({ sourceSessionId, ...session }),
};
}
@@ -0,0 +1,60 @@
/*
* 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 assert from 'node:assert/strict';
import { fork } from 'node:child_process';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { tryAcquireFileLifetimeOwner } from '../file-lifetime-owner.js';
test('a file lifetime owner fails closed and recovers after owner death', async (t) => {
const root = await mkdtemp(join(tmpdir(), 'maka-file-lifetime-owner-'));
const path = join(root, 'nested', 'publication.lease');
const holder = fork(
new URL('./fixtures/file-lifetime-owner-holder.js', import.meta.url),
[path],
{
stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
},
);
t.after(async () => {
if (holder.exitCode === null && holder.signalCode === null) holder.kill('SIGKILL');
await rm(root, { recursive: true, force: true });
});
await new Promise<void>((resolve, reject) => {
holder.once('message', (message) => {
if (message === 'owned') resolve();
else reject(new Error(`Unexpected file owner message: ${String(message)}`));
});
holder.once('error', reject);
holder.once('exit', (code, signal) => {
reject(new Error(`File owner exited before acquisition (${String(code)}, ${signal})`));
});
});
assert.equal(await tryAcquireFileLifetimeOwner(path), undefined);
holder.kill('SIGKILL');
await new Promise<void>((resolve) => holder.once('exit', () => resolve()));
const successor = await tryAcquireFileLifetimeOwner(path);
assert.ok(successor);
await Promise.all([successor.close(), successor.close()]);
});
@@ -0,0 +1,138 @@
/*
* 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 { fork } from 'node:child_process';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import assert from 'node:assert/strict';
import { test, type TestContext } from 'node:test';
import { withProcessLifetimeFileUpdateLock } from '../process-lifetime-file-update-lock.js';
test('releases a file update lock when its process is killed', async (t) => {
await assertKilledHolderCanBeRecovered(t, []);
});
test('recovers a supervised legacy directory lock when its process is killed', async (t) => {
await assertKilledHolderCanBeRecovered(t, ['legacy']);
});
test('keeps the authority lease held by an inherited package-switch descriptor', async (t) => {
const root = await mkdtemp(join(tmpdir(), 'maka-inherited-file-update-lock-'));
const targetPath = join(root, 'state');
const holder = fork(
new URL('./fixtures/file-update-lock-holder.js', import.meta.url),
[targetPath, 'inherit'],
{ stdio: ['ignore', 'ignore', 'inherit', 'ipc'] },
);
let inheritorPid: number | undefined;
t.after(async () => {
if (holder.exitCode === null && holder.signalCode === null) holder.kill('SIGKILL');
if (inheritorPid !== undefined) killIfRunning(inheritorPid);
await rm(root, { recursive: true, force: true });
});
inheritorPid = await new Promise<number>((resolve, reject) => {
holder.once('message', (message) => {
if (
typeof message === 'object' &&
message !== null &&
'kind' in message &&
message.kind === 'locked' &&
'inheritorPid' in message &&
typeof message.inheritorPid === 'number'
) {
resolve(message.inheritorPid);
} else reject(new Error(`Unexpected child message: ${String(message)}`));
});
holder.once('error', reject);
});
holder.kill('SIGKILL');
await new Promise<void>((resolve) => holder.once('exit', () => resolve()));
await assert.rejects(
withProcessLifetimeFileUpdateLock(targetPath, async () => undefined, 150),
/locked by another process/u,
);
killIfRunning(inheritorPid);
await waitForExit(inheritorPid);
await withProcessLifetimeFileUpdateLock(targetPath, async () => undefined, 2_000);
});
async function assertKilledHolderCanBeRecovered(
t: TestContext,
args: readonly string[],
): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-file-update-lock-'));
const targetPath = join(root, 'state');
const child = fork(
new URL('./fixtures/file-update-lock-holder.js', import.meta.url),
[targetPath, ...args],
{ stdio: ['ignore', 'ignore', 'inherit', 'ipc'] },
);
t.after(async () => {
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
await rm(root, { recursive: true, force: true });
});
await new Promise<void>((resolve, reject) => {
child.once('message', (message) => {
if (message === 'locked') resolve();
else reject(new Error(`Unexpected child message: ${String(message)}`));
});
child.once('error', reject);
child.once('exit', (code, signal) => {
reject(new Error(`Lock holder exited before acquisition (${String(code)}, ${signal})`));
});
});
child.kill('SIGKILL');
await new Promise<void>((resolve) => child.once('exit', () => resolve()));
let entered = false;
await withProcessLifetimeFileUpdateLock(
targetPath,
async () => {
entered = true;
},
2_000,
);
assert.equal(entered, true);
}
function killIfRunning(pid: number): void {
try {
process.kill(pid, 'SIGKILL');
} catch (error) {
if (!(error instanceof Error && 'code' in error && error.code === 'ESRCH')) throw error;
}
}
async function waitForExit(pid: number): Promise<void> {
const deadline = Date.now() + 2_000;
while (Date.now() < deadline) {
try {
process.kill(pid, 0);
} catch (error) {
if (error instanceof Error && 'code' in error && error.code === 'ESRCH') return;
throw error;
}
await new Promise((resolve) => setTimeout(resolve, 20));
}
throw new Error(`Inherited lock holder ${pid} did not exit`);
}
@@ -0,0 +1,191 @@
/*
* 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 { mkdir, rm, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import {
createSqliteArtifactStore as createArtifactStore,
type CreateArtifactInput,
} from '../../artifact-store.js';
import {
withArtifactWriterLock,
withLeaseBoundArtifactWriterLock,
} from '../../artifact-writer-lock.js';
import {
prepareArtifactWriterLockAuthorityForLease,
resolveExistingStorageRoot,
tryAcquireInteractiveRootOwner,
} from '../../root-authority.js';
const [workspaceRoot, modeOrTransientResidueSessionId, modeArgument] = process.argv.slice(2);
if (!workspaceRoot || !process.send) {
throw new Error(
'usage: artifact-writer-lock-holder <workspace-root> [transient-residue-session-id | --public-writer <session-id> | --authority-holder <root-id>]',
);
}
try {
if (modeOrTransientResidueSessionId === '--public-writer') {
if (!modeArgument) throw new Error('public writer session id is required');
await runPublicWriter(workspaceRoot, modeArgument);
} else if (modeOrTransientResidueSessionId === '--authority-holder') {
if (!modeArgument) throw new Error('authority holder root id is required');
await runAuthorityLockHolder(workspaceRoot, modeArgument);
} else {
await runLockHolder(workspaceRoot, modeOrTransientResidueSessionId);
}
} catch (error) {
await send({
type: 'error',
message: error instanceof Error ? error.message : String(error),
}).catch(() => {});
process.exitCode = 1;
} finally {
process.disconnect?.();
}
async function runLockHolder(
workspaceRoot: string,
transientResidueSessionId: string | undefined,
): Promise<void> {
await withArtifactWriterLock(workspaceRoot, async () => {
const residuePath = transientResidueSessionId
? await createTransientPublicationResidue(workspaceRoot, transientResidueSessionId)
: undefined;
try {
await send({ type: 'locked' });
await waitForRelease();
} finally {
if (residuePath) await rm(residuePath, { force: true });
}
});
await send({ type: 'released' });
}
async function runAuthorityLockHolder(workspaceRoot: string, rootId: string): Promise<void> {
const capability = await resolveExistingStorageRoot({
path: workspaceRoot,
kind: 'interactive',
expectedRootId: rootId,
});
const owner = await tryAcquireInteractiveRootOwner(capability);
if (!owner) throw new Error('interactive storage root is already owned');
try {
const authority = await prepareArtifactWriterLockAuthorityForLease(owner.lease, 'interactive');
await withLeaseBoundArtifactWriterLock(authority, async () => {
await send({ type: 'locked' });
await waitForRelease();
});
await send({ type: 'released' });
} finally {
await owner.close();
}
}
async function runPublicWriter(workspaceRoot: string, sessionId: string): Promise<void> {
const store = createArtifactStore(workspaceRoot);
try {
await store.list(sessionId);
await send({ type: 'ready' });
const command = await waitForCreateCommand();
const mutation = store.create({
...command.input,
content: repeatedPayload(command.payloadUnit, command.payloadBytes),
});
await new Promise<void>((resolve) => setImmediate(resolve));
await send({ type: 'queued' });
await send({ type: 'created', record: await mutation });
} finally {
store.close?.();
}
}
function waitForRelease(): Promise<void> {
return new Promise((resolve, reject) => {
process.once('message', resolve);
process.once('disconnect', () => reject(new Error('parent disconnected before release')));
});
}
function waitForCreateCommand(): Promise<{
input: Omit<CreateArtifactInput, 'content'>;
payloadUnit: string;
payloadBytes: number;
}> {
return new Promise((resolve, reject) => {
process.once('message', (message: unknown) => {
if (!isCreateCommand(message)) {
reject(new Error('public writer received an invalid create command'));
return;
}
resolve(message);
});
process.once('disconnect', () =>
reject(new Error('parent disconnected before public writer create')),
);
});
}
function isCreateCommand(message: unknown): message is {
type: 'create';
input: Omit<CreateArtifactInput, 'content'>;
payloadUnit: string;
payloadBytes: number;
} {
if (!message || typeof message !== 'object') return false;
const candidate = message as Record<string, unknown>;
return (
candidate.type === 'create' &&
typeof candidate.input === 'object' &&
candidate.input !== null &&
typeof candidate.payloadUnit === 'string' &&
candidate.payloadUnit.length > 0 &&
Number.isSafeInteger(candidate.payloadBytes) &&
(candidate.payloadBytes as number) >= 0
);
}
function repeatedPayload(unit: string, bytes: number): string {
return unit.repeat(Math.ceil(bytes / unit.length)).slice(0, bytes);
}
async function createTransientPublicationResidue(
workspaceRoot: string,
sessionId: string,
): Promise<string> {
const sessionRoot = join(workspaceRoot, 'artifacts', sessionId);
const targetHash = createHash('sha256').update('transient.txt').digest('hex');
const residuePath = join(
sessionRoot,
`.artifact-publish.${targetHash}.00000000-0000-4000-8000-000000000000.tmp`,
);
await mkdir(sessionRoot, { recursive: true });
await writeFile(residuePath, 'transient publication');
return residuePath;
}
function send(message: object): Promise<void> {
return new Promise((resolve, reject) => {
process.send?.(message, (error) => {
if (error) reject(error);
else resolve();
});
});
}
@@ -0,0 +1,16 @@
{"timestamp":"2026-08-08T00:00:00.000Z","type":"session_meta","payload":{"session_id":"codex-session-1","id":"codex-session-1","timestamp":"2026-08-08T00:00:00.000Z","cwd":"/workspace/project","originator":"codex_cli_rs","cli_version":"0.144.1","source":"cli","model_provider":"openai"}}
{"timestamp":"2026-08-08T00:00:01.000Z","type":"event_msg","payload":{"type":"task_started","turn_id":"codex-turn-1","started_at":1786147201}}
{"timestamp":"2026-08-08T00:00:01.100Z","type":"response_item","payload":{"type":"message","role":"developer","content":[{"type":"input_text","text":"synthetic developer context"}]}}
{"timestamp":"2026-08-08T00:00:01.200Z","type":"response_item","payload":{"type":"message","role":"user","content":[{"type":"input_text","text":"synthetic model input"}]}}
{"timestamp":"2026-08-08T00:00:01.300Z","type":"turn_context","payload":{"turn_id":"codex-turn-1","cwd":"/workspace/project","model":"gpt-codex-test","approval_policy":"on-request","sandbox_policy":{"type":"workspace-write"}}}
{"timestamp":"2026-08-08T00:00:02.000Z","type":"event_msg","payload":{"type":"user_message","client_id":"codex-user-1","message":"Fix the parser","images":[],"local_images":[],"text_elements":[]}}
{"timestamp":"2026-08-08T00:00:03.000Z","type":"event_msg","payload":{"type":"agent_reasoning","text":"Inspect the failing path."}}
{"timestamp":"2026-08-08T00:00:03.100Z","type":"response_item","payload":{"type":"reasoning","id":"reasoning-provider-1","summary":[{"type":"summary_text","text":"Inspect the failing path."}],"encrypted_content":"opaque"}}
{"timestamp":"2026-08-08T00:00:04.000Z","type":"event_msg","payload":{"type":"agent_message","message":"I found the issue.","phase":"commentary"}}
{"timestamp":"2026-08-08T00:00:04.100Z","type":"response_item","payload":{"type":"message","id":"assistant-provider-1","role":"assistant","content":[{"type":"output_text","text":"I found the issue."}],"phase":"commentary"}}
{"timestamp":"2026-08-08T00:00:05.000Z","type":"response_item","payload":{"type":"function_call","id":"function-provider-1","name":"wait","arguments":"{\"milliseconds\":25}","call_id":"call-wait-1"}}
{"timestamp":"2026-08-08T00:00:06.000Z","type":"response_item","payload":{"type":"function_call_output","id":"function-output-1","call_id":"call-wait-1","output":"waited"}}
{"timestamp":"2026-08-08T00:00:07.000Z","type":"response_item","payload":{"type":"custom_tool_call","id":"custom-provider-1","name":"apply_patch","input":"*** Begin Patch","call_id":"call-patch-1"}}
{"timestamp":"2026-08-08T00:00:08.000Z","type":"response_item","payload":{"type":"custom_tool_call_output","id":"custom-output-1","call_id":"call-patch-1","output":[{"type":"input_text","text":"Done"},{"type":"input_text","text":"1 file changed"}]}}
{"timestamp":"2026-08-08T00:00:09.000Z","type":"event_msg","payload":{"type":"context_compacted"}}
{"timestamp":"2026-08-08T00:00:10.000Z","type":"event_msg","payload":{"type":"task_complete","turn_id":"codex-turn-1","last_agent_message":"I found the issue.","completed_at":1786147210}}
@@ -0,0 +1,10 @@
{"timestamp":"2026-08-22T00:00:00.000Z","ordinal":0,"type":"session_meta","payload":{"session_id":"codex-item-completed","id":"codex-item-completed","timestamp":"2026-08-22T00:00:00.000Z","cwd":"/workspace/opencv","originator":"Codex Desktop","cli_version":"0.149.0-alpha.4.1","source":"vscode","model_provider":"openai"}}
{"timestamp":"2026-08-22T00:00:01.000Z","ordinal":1,"type":"event_msg","payload":{"type":"task_started","turn_id":"codex-turn-item-completed","started_at":"2026-08-22T00:00:01.000Z"}}
{"timestamp":"2026-08-22T00:00:01.100Z","ordinal":2,"type":"turn_context","payload":{"turn_id":"codex-turn-item-completed","cwd":"/workspace/opencv","model":"gpt-codex-item-test"}}
{"timestamp":"2026-08-22T00:00:02.000Z","ordinal":3,"type":"response_item","payload":{"type":"message","id":"provider-user-mirror","role":"user","content":[{"type":"input_text","text":"Analyze the image. Use OpenCV.js."}]}}
{"timestamp":"2026-08-22T00:00:02.100Z","ordinal":4,"type":"event_msg","payload":{"type":"item_completed","thread_id":"codex-item-completed","turn_id":"codex-turn-item-completed","item":{"type":"UserMessage","id":"user-item-1","client_id":"user-client-1","content":[{"type":"text","text":"Analyze the ima","text_elements":[]},{"type":"local_image","path":"/tmp/input.png"},{"type":"text","text":"ge. Use OpenCV.js.","text_elements":[]}]},"started_at_ms":1787356802000,"completed_at_ms":1787356802100}}
{"timestamp":"2026-08-22T00:00:03.000Z","ordinal":5,"type":"event_msg","payload":{"type":"item_completed","thread_id":"codex-item-completed","turn_id":"codex-turn-item-completed","item":{"type":"Reasoning","id":"reasoning-item-1","summary_text":["Inspect the pixels.","Draft the solution."],"raw_content":[]},"started_at_ms":1787356803000,"completed_at_ms":1787356803100}}
{"timestamp":"2026-08-22T00:00:03.100Z","ordinal":6,"type":"response_item","payload":{"type":"reasoning","id":"reasoning-item-1","summary":[{"type":"summary_text","text":"Inspect the pixels."},{"type":"summary_text","text":"Draft the solution."}],"encrypted_content":"opaque"}}
{"timestamp":"2026-08-22T00:00:04.000Z","ordinal":7,"type":"event_msg","payload":{"type":"item_completed","thread_id":"codex-item-completed","turn_id":"codex-turn-item-completed","item":{"type":"AgentMessage","id":"assistant-item-1","content":[{"type":"Text","text":"Use can"},{"type":"Text","text":"vas. Then process the pixels."}],"phase":"final_answer"},"started_at_ms":1787356804000,"completed_at_ms":1787356804100}}
{"timestamp":"2026-08-22T00:00:04.100Z","ordinal":8,"type":"response_item","payload":{"type":"message","id":"assistant-item-1","role":"assistant","content":[{"type":"output_text","text":"Use canvas. Then process the pixels."}],"phase":"final_answer"}}
{"timestamp":"2026-08-22T00:00:05.000Z","ordinal":9,"type":"event_msg","payload":{"type":"task_complete","turn_id":"codex-turn-item-completed","last_agent_message":"Use canvas. Then process the pixels.","completed_at":"2026-08-22T00:00:05.000Z"}}
@@ -0,0 +1,55 @@
/*
* 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 { join } from 'node:path';
import {
CONTEXT_OFFLOAD_DATABASE_NAME,
SqliteContextOffloadStore,
} from '../../sqlite-context-offload-store.js';
const root = process.env.MAKA_CONTEXT_OFFLOAD_CRASH_ROOT;
if (!root) throw new Error('Missing context-offload crash fixture root');
const store = new SqliteContextOffloadStore(join(root, CONTEXT_OFFLOAD_DATABASE_NAME), {
limits: {
ownerMaxBytes: {
read_image_snapshot: 5 * 1024 * 1024,
tool_result_archive: 8 * 1024 * 1024,
},
sessionLogicalBytes: 16 * 1024 * 1024,
workspacePhysicalBytes: 32 * 1024 * 1024,
},
failpoint(point) {
const requested = process.env.MAKA_CONTEXT_OFFLOAD_CRASH_POINT ?? 'after_managed_file_publish';
if (point === requested) process.exit(73);
},
});
await store.put({
sessionId: 'session-1',
owner: {
kind: 'read_image_snapshot',
ownerId: process.env.MAKA_CONTEXT_OFFLOAD_OWNER_ID ?? 'read-call-1',
},
bytes: new TextEncoder().encode(
process.env.MAKA_CONTEXT_OFFLOAD_VALUE ?? 'crash-safe-managed-value',
),
mediaType: 'image/png',
});
throw new Error('Managed-file publication crash failpoint was not reached');
@@ -0,0 +1,89 @@
/*
* 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 { readFile, rm } from 'node:fs/promises';
import { join } from 'node:path';
import {
resolveRootControlNamespace,
resolveRootOwnershipNamespace,
STORAGE_ROOT_MARKER_FILE,
} from '../../root-authority.js';
// A storage root's control directory lives under the real OS account home, not
// inside the temporary root a test creates, so removing the temporary directory
// leaves the control directory behind. `resolveRootControlNamespace` reads
// `userInfo().homedir` on purpose — the directory carries `owner.lock`, which
// decides who may write a State Root, and an environment variable must not be
// able to move that trust boundary. Tests therefore have to remove what they
// created, and these helpers are the one place that knows how.
/** Removes the control directory for a rootId. Safe to call when none exists. */
export async function removeControlDirectory(rootId: string): Promise<void> {
if (rootId.length === 0) return;
await Promise.all([
rm(join(resolveRootControlNamespace(), rootId), { recursive: true, force: true }),
rm(join(resolveRootOwnershipNamespace(), `${rootId}.lock`), { force: true }),
]);
}
/**
* Removes the control directory belonging to a storage root path, reading the
* rootId from the root's own marker file.
*
* Only usable while the root still exists. A test that removes or quarantines
* its root before teardown has already destroyed the marker that names the
* control directory, so such tests must record the rootId at resolution time
* with `trackControlDirectory` instead.
*/
export async function removeControlDirectoryForRootPath(rootPath: string): Promise<void> {
const marker = await readFile(join(rootPath, STORAGE_ROOT_MARKER_FILE), 'utf8').catch(
() => undefined,
);
if (marker === undefined) return;
let rootId: unknown;
try {
rootId = (JSON.parse(marker) as { rootId?: unknown }).rootId;
} catch {
return;
}
if (typeof rootId !== 'string') return;
await removeControlDirectory(rootId);
}
const trackedRootIds = new Set<string>();
/**
* Records a resolved root's control directory for teardown and returns the
* capability unchanged, so it can wrap a `resolveStorageRoot` call in place.
* The record survives the root itself, which is what teardown needs. Node's
* test runner gives each file its own process, so the set is per-file state.
*/
export function trackControlDirectory<Capability extends { readonly rootId: string }>(
capability: Capability,
): Capability {
trackedRootIds.add(capability.rootId);
return capability;
}
/** Removes every control directory recorded by `trackControlDirectory` so far. */
export async function removeTrackedControlDirectories(): Promise<void> {
const rootIds = [...trackedRootIds];
trackedRootIds.clear();
await Promise.all(rootIds.map(removeControlDirectory));
}
@@ -0,0 +1,29 @@
/*
* 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 { tryAcquireFileLifetimeOwner } from '../../file-lifetime-owner.js';
const path = process.argv[2];
if (!path) throw new Error('Missing file lifetime owner path');
const owner = await tryAcquireFileLifetimeOwner(path);
if (!owner) throw new Error('File lifetime owner is already active');
process.send?.('owned');
setInterval(() => undefined, 1_000).unref();
await new Promise<void>((resolve) => process.once('disconnect', resolve));
await owner.close();
@@ -0,0 +1,55 @@
/*
* 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 { spawn } from 'node:child_process';
import { mkdir } from 'node:fs/promises';
import {
withLegacyFileUpdateLockLease,
withProcessLifetimeFileUpdateLock,
} from '../../process-lifetime-file-update-lock.js';
const targetPath = process.argv[2];
if (!targetPath) throw new Error('Missing file update lock target');
const hold = async () => {
process.send?.('locked');
await new Promise<never>(() => setInterval(() => undefined, 1_000));
};
if (process.argv[3] === 'legacy') {
await withLegacyFileUpdateLockLease(targetPath, async (inheritedFd) => {
if (inheritedFd <= 2) throw new Error('Legacy lock lease is not inheritable');
await mkdir(`${targetPath}.lock`);
await hold();
});
} else if (process.argv[3] === 'inherit') {
await withProcessLifetimeFileUpdateLock(targetPath, async (inheritedFd) => {
const child = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 30_000)'], {
stdio: ['ignore', 'ignore', 'inherit', inheritedFd],
});
await new Promise<void>((resolve, reject) => {
child.once('spawn', resolve);
child.once('error', reject);
});
process.send?.({ kind: 'locked', inheritorPid: child.pid });
await new Promise<never>(() => setInterval(() => undefined, 1_000));
});
} else {
await withProcessLifetimeFileUpdateLock(targetPath, hold);
}
@@ -0,0 +1,53 @@
/*
* 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 { execFile } from 'node:child_process';
import { mkdir, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { promisify } from 'node:util';
const execFileAsync = promisify(execFile);
export async function createGitRepositoryWithWorktree(
repository: string,
linkedWorktree: string,
branch: string,
): Promise<void> {
await mkdir(repository);
await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
await writeFile(join(repository, 'tracked.txt'), 'tracked\n', 'utf8');
await execFileAsync('git', ['add', 'tracked.txt'], { cwd: repository });
await execFileAsync(
'git',
[
'-c',
'user.name=Maka Test',
'-c',
'user.email=test@maka.invalid',
'commit',
'--quiet',
'-m',
'init',
],
{ cwd: repository },
);
await execFileAsync('git', ['worktree', 'add', '--quiet', '-b', branch, linkedWorktree], {
cwd: repository,
});
}
@@ -0,0 +1,83 @@
/*
* 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, writeFile } from 'node:fs/promises';
import {
computeManagedDependencyEnvironmentIdentity,
createManagedDependencyEnvironmentAuthority,
createManagedDependencyEnvironmentProducerCapability,
type ManagedDependencyEnvironmentFailpoint,
} from '../../managed-dependency-environment.js';
const storageRoot = process.env.MAKA_DEPENDENCY_CRASH_ROOT;
const failpoint = process.env.MAKA_DEPENDENCY_CRASH_POINT as
| ManagedDependencyEnvironmentFailpoint
| 'during_environment_provision'
| undefined;
if (!storageRoot || !failpoint) throw new Error('Missing dependency crash fixture input');
const producerCapability = createManagedDependencyEnvironmentProducerCapability(
`sha256:${'a'.repeat(64)}`,
);
const source = {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from('{"lockfileVersion":3}\n'),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: process.platform,
arch: process.arch,
producerRuntimeIdentitySha256: producerCapability.runtimeIdentitySha256,
producerPolicyIdentitySha256: producerCapability.policyIdentitySha256,
policyVersion: 'managed_dependency_environment_v1' as const,
};
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer: {
capability: producerCapability,
packageManagerName: 'npm',
packageManagerVersion: '11.12.1',
nodeRuntime: {
version: '24.7.0',
abi: '137',
platform: process.platform,
arch: process.arch,
},
async provision(input) {
await mkdir(joinPath(input.outputRoot, 'fixture-package'), {
recursive: true,
});
await writeFile(joinPath(input.outputRoot, 'fixture-package', 'index.js'), 'safe\n');
if (failpoint === 'during_environment_provision') process.exit(73);
},
},
failpoint(point) {
if (point === failpoint) process.exit(73);
},
});
await authority.acquire(computeManagedDependencyEnvironmentIdentity(source), source);
throw new Error('Crash failpoint was not reached');
function joinPath(...parts: string[]): string {
return parts.join(process.platform === 'win32' ? '\\' : '/');
}
@@ -0,0 +1,47 @@
/*
* 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 {
createManagedDependencyEnvironmentAuthority,
createManagedDependencyEnvironmentProducerCapability,
} from '../../managed-dependency-environment.js';
const storageRoot = process.env.MAKA_DEPENDENCY_OWNER_ROOT;
if (!storageRoot) throw new Error('Missing dependency owner fixture root');
const producerCapability = createManagedDependencyEnvironmentProducerCapability(
`sha256:${'a'.repeat(64)}`,
);
await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer: {
capability: producerCapability,
packageManagerName: 'npm',
packageManagerVersion: '11.12.1',
nodeRuntime: {
version: '24.7.0',
abi: '137',
platform: process.platform,
arch: process.arch,
},
async provision() {},
},
});
process.stdout.write('READY\n');
setInterval(() => undefined, 1_000);
@@ -0,0 +1,29 @@
/*
* 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 { createMcpConfigStore } from '../../mcp-config-store.js';
const root = process.argv[2];
if (!root) throw new Error('Missing MCP config workspace root');
await createMcpConfigStore(root).transform(async (current) => {
process.send?.('locked');
await new Promise<never>(() => setInterval(() => undefined, 1_000));
return current;
});
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,27 @@
/*
* 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 { acquireProcessLifetimeOwner } from '../../process-lifetime-owner.js';
const root = process.argv[2];
if (!root) throw new Error('Missing process lifetime owner root');
const owner = await acquireProcessLifetimeOwner(root);
process.send?.({ reference: owner.reference });
await new Promise<never>(() => setInterval(() => undefined, 1_000));
@@ -0,0 +1,94 @@
/*
* 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 fs from 'node:fs';
import { basename } from 'node:path';
const [rootArgument, markerFile] = process.argv.slice(2);
if (!rootArgument || !markerFile || !process.send) {
throw new Error('usage: root-initialization-race <root> <marker-file>');
}
const root = fs.realpathSync(rootArgument);
const markerTempPrefix = `${markerFile}.`;
const originalOpen = fs.promises.open;
let intercepted = false;
fs.promises.open = (async (path, flags, mode) => {
// This child initializes one root. Match its unique marker basename so the
// cut does not depend on Windows long/short, namespaced, or case spelling.
if (
!intercepted &&
typeof path === 'string' &&
basename(path).startsWith(markerTempPrefix) &&
basename(path).endsWith('.tmp')
) {
intercepted = true;
await send({ type: 'marker_open_pending' });
await waitForResume();
}
return originalOpen(path, flags, mode);
}) as typeof fs.promises.open;
// Import after the interposition: marker-file captures the intrinsic at module
// evaluation, while production code must ignore later global mutations.
const { resolveStorageRoot, StorageRootAuthorityError } = await import('../../root-authority.js');
const parentDisconnected = new Promise<void>((resolvePromise) =>
process.once('disconnect', resolvePromise),
);
try {
await resolveStorageRoot({ path: root, kind: 'interactive' });
await send({ type: 'resolved' });
} catch (error) {
await send({
type: 'error',
code: error instanceof StorageRootAuthorityError ? error.code : 'unexpected',
});
}
await parentDisconnected;
function waitForResume(): Promise<void> {
return new Promise((resolvePromise, reject) => {
const onMessage = (message: unknown) => {
if (message !== 'resume') return;
cleanup();
resolvePromise();
};
const onDisconnect = () => {
cleanup();
reject(new Error('parent disconnected before resuming marker initialization'));
};
const cleanup = () => {
process.off('message', onMessage);
process.off('disconnect', onDisconnect);
};
process.on('message', onMessage);
process.once('disconnect', onDisconnect);
});
}
function send(message: object): Promise<void> {
return new Promise((resolvePromise, reject) => {
process.send?.(message, (error) => {
if (error) reject(error);
else resolvePromise();
});
});
}
@@ -0,0 +1,67 @@
/*
* 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 { spawn } from 'node:child_process';
import {
resolveStorageRoot,
tryAcquireInteractiveRootOwner,
tryAcquireInteractiveRootReader,
} from '../../root-authority.js';
const [root, access] = process.argv.slice(2);
if (!root || (access !== 'read' && access !== 'write')) {
throw new Error('usage: root-lock-holder <root> <read|write>');
}
const capability = await resolveStorageRoot({ path: root, kind: 'interactive' });
const lock =
access === 'write'
? await tryAcquireInteractiveRootOwner(capability)
: await tryAcquireInteractiveRootReader(capability);
if (!lock) {
process.send?.({ type: 'denied' });
process.exit(2);
}
process.send?.({ type: 'locked' });
process.on('message', (message) => {
if (message === 'close') {
void lock.close().finally(() => process.exit(0));
return;
}
if (message === 'throw') {
throw new Error('intentional uncaught holder failure');
}
if (message === 'abort') {
process.abort();
}
if (message === 'spawn-descendant') {
const descendant = spawn(process.execPath, ['-e', 'setInterval(() => undefined, 1000)'], {
detached: true,
stdio: 'ignore',
});
const pid = descendant.pid;
if (pid === undefined) throw new Error('descendant did not receive a process id');
descendant.unref();
process.send?.({ type: 'descendant', pid }, () => process.exit(0));
}
});
setInterval(() => undefined, 1_000).unref();
@@ -0,0 +1,43 @@
/*
* 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 { resolveStorageRoot, StorageRootAuthorityError } from '../../root-authority.js';
const [root] = process.argv.slice(2);
if (!root || !process.send) throw new Error('usage: root-resolver <root>');
try {
await resolveStorageRoot({ path: root, kind: 'interactive' });
await send({ type: 'resolved' });
} catch (error) {
await send({
type: 'error',
code: error instanceof StorageRootAuthorityError ? error.code : 'unexpected',
});
}
process.disconnect?.();
function send(message: object): Promise<void> {
return new Promise((resolve, reject) => {
process.send?.(message, (error) => {
if (error) reject(error);
else resolve();
});
});
}
@@ -0,0 +1,72 @@
/*
* 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 fs from 'node:fs';
import { syncBuiltinESMExports } from 'node:module';
const [archivePath, archiveDigest, limitsJson, destinationRoot] = process.argv.slice(2);
if (
archivePath === undefined ||
archiveDigest === undefined ||
limitsJson === undefined ||
destinationRoot === undefined
) {
process.exit(2);
}
const originalOpen = fs.promises.open.bind(fs.promises);
let targeted = false;
fs.promises.open = async (...args) => {
const handle = await originalOpen(...args);
if (targeted || !args[0].toString().endsWith('.owner.json')) return handle;
targeted = true;
const originalWrite = handle.write.bind(handle);
handle.write = (async (
buffer: Uint8Array,
offset: number,
length: number,
position: number | null,
) => {
if (position === null) return originalWrite(buffer, offset, length, position);
await originalWrite(buffer, offset, Math.min(length, 1), position);
process.stdout.write('binding-partial\n');
return new Promise<never>(() => {});
}) as typeof handle.write;
return handle;
};
syncBuiltinESMExports();
const { createSessionBundleFileService } = await import('../../session-bundle-file-service.js');
// Keep the deliberately wedged top-level await alive until the parent delivers
// SIGKILL. Without a referenced handle, Node exits with code 13 as soon as the
// event loop is empty and races the crash-state assertions in the parent test.
const keepAlive = setInterval(() => undefined, 60_000);
try {
await createSessionBundleFileService().hydrate({
source: {
path: archivePath,
expectedArchiveDigest: archiveDigest as `sha256:${string}`,
},
limits: JSON.parse(limitsJson),
expectedSessionId: 'cloud-session-1',
destinationRoot,
});
} finally {
clearInterval(keepAlive);
}
@@ -0,0 +1,79 @@
/*
* 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 fs from 'node:fs';
import { syncBuiltinESMExports } from 'node:module';
const [archivePath, archiveDigest, limitsJson, destinationRoot] = process.argv.slice(2);
if (
archivePath === undefined ||
archiveDigest === undefined ||
limitsJson === undefined ||
destinationRoot === undefined
) {
process.exit(2);
}
const originalOpen = fs.promises.open.bind(fs.promises);
let targeted = false;
fs.promises.open = async (...args) => {
const handle = await originalOpen(...args);
if (targeted || !args[0].toString().endsWith('.owner.json')) return handle;
targeted = true;
const originalWrite = handle.write.bind(handle);
let wroteOneByte = false;
handle.write = (async (
buffer: Uint8Array,
offset: number,
length: number,
position: number | null,
) => {
if (wroteOneByte) {
throw Object.assign(new Error('injected ownership write failure'), {
code: 'EIO',
});
}
wroteOneByte = true;
return originalWrite(buffer, offset, Math.min(length, 1), position);
}) as typeof handle.write;
return handle;
};
syncBuiltinESMExports();
const { createSessionBundleFileService } = await import('../../session-bundle-file-service.js');
const { SessionBundleFileError } = await import('../../session-bundle-contract.js');
try {
await createSessionBundleFileService().hydrate({
source: {
path: archivePath,
expectedArchiveDigest: archiveDigest as `sha256:${string}`,
},
limits: JSON.parse(limitsJson),
expectedSessionId: 'cloud-session-1',
destinationRoot,
});
process.exit(3);
} catch (error) {
process.stdout.write(
JSON.stringify({
code: error instanceof SessionBundleFileError ? error.code : 'unexpected',
}),
);
process.exit(error instanceof SessionBundleFileError && error.code === 'io_failure' ? 0 : 4);
}
@@ -0,0 +1,48 @@
/*
* 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 { createSessionBundleFileService } from '../../session-bundle-file-service.js';
import type { SessionBundleLimits } from '../../session-bundle-contract.js';
const [archivePath, archiveDigest, limitsJson, destinationRoot] = process.argv.slice(2);
if (!archivePath || !archiveDigest || !limitsJson) process.exit(2);
const limits = JSON.parse(limitsJson) as SessionBundleLimits;
const service = createSessionBundleFileService();
const source = {
path: archivePath,
expectedArchiveDigest: archiveDigest as `sha256:${string}`,
};
const result = destinationRoot
? await service.hydrate({
source,
limits,
expectedSessionId: 'cloud-session-1',
destinationRoot,
})
: await service.inspect({ source, limits });
process.stdout.write(
JSON.stringify({
sessionId: result.manifest.envelope.sessionId,
archiveDigest: result.archiveDigest,
identityHex: Buffer.from(result.stateIdentity.bytes).toString('hex'),
verified: result.verified,
...(destinationRoot ? { destinationRoot } : {}),
}),
);
@@ -0,0 +1,62 @@
/*
* 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 fs from 'node:fs';
import { resolve } from 'node:path';
import { syncBuiltinESMExports } from 'node:module';
const [archivePath, limitsJson] = process.argv.slice(2);
if (archivePath === undefined || limitsJson === undefined) process.exit(2);
const target = resolve(archivePath);
const originalOpen = fs.promises.open.bind(fs.promises);
let mutated = false;
fs.promises.open = async (...args) => {
const handle = await originalOpen(...args);
if (resolve(args[0].toString()) !== target) return handle;
const originalCreateReadStream = handle.createReadStream.bind(handle);
handle.createReadStream = (options) => {
if (!mutated) {
mutated = true;
const changed = new Date(Date.now() + 60_000);
fs.utimesSync(target, changed, changed);
}
return originalCreateReadStream(options);
};
return handle;
};
syncBuiltinESMExports();
const { createSessionBundleFileService } = await import('../../session-bundle-file-service.js');
const { SessionBundleFileError } = await import('../../session-bundle-contract.js');
try {
await createSessionBundleFileService().inspect({
source: { path: target },
limits: JSON.parse(limitsJson),
});
process.exit(3);
} catch (error) {
process.stdout.write(
JSON.stringify({
code: error instanceof SessionBundleFileError ? error.code : 'unexpected',
operation: error instanceof SessionBundleFileError ? error.details?.operation : undefined,
}),
);
process.exit(error instanceof SessionBundleFileError && error.code === 'source_changed' ? 0 : 4);
}
@@ -0,0 +1,73 @@
/*
* 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 fs from 'node:fs';
import { syncBuiltinESMExports } from 'node:module';
const [stateRoot, workspaceRoot, destination, resultPath, limitsJson, identityHex] =
process.argv.slice(2);
if (
stateRoot === undefined ||
workspaceRoot === undefined ||
destination === undefined ||
resultPath === undefined ||
limitsJson === undefined ||
identityHex === undefined
) {
process.exit(2);
}
const originalLink = fs.promises.link.bind(fs.promises);
fs.promises.link = async (existingPath, newPath) => {
await originalLink(existingPath, newPath);
await fs.promises.rm(newPath);
await fs.promises.writeFile(newPath, 'UNRELATED');
};
syncBuiltinESMExports();
const { createSessionBundleFileService } = await import('../../session-bundle-file-service.js');
const { SessionBundleFileError } = await import('../../session-bundle-contract.js');
try {
await createSessionBundleFileService().pack({
snapshot: {
stateRoot,
workspaceRoot,
stateIdentity: {
mediaType: 'application/vnd.maka.session-state-identity+json;version=1',
bytes: Buffer.from(identityHex, 'hex'),
},
},
envelope: {
sessionId: 'cloud-session-1',
lastCommittedActivationId: 'activation-9',
},
destination,
limits: JSON.parse(limitsJson),
});
process.exit(3);
} catch (error) {
await fs.promises.writeFile(
resultPath,
JSON.stringify({
code: error instanceof SessionBundleFileError ? error.code : 'unexpected',
destinationContents: await fs.promises.readFile(destination, 'utf8'),
}),
);
process.exit(error instanceof SessionBundleFileError && error.code === 'source_changed' ? 0 : 4);
}
@@ -0,0 +1,78 @@
/*
* 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 fs from 'node:fs';
import { syncBuiltinESMExports } from 'node:module';
const [stateRoot, workspaceRoot, destination, resultPath, limitsJson, identityHex] =
process.argv.slice(2);
if (
stateRoot === undefined ||
workspaceRoot === undefined ||
destination === undefined ||
resultPath === undefined ||
limitsJson === undefined ||
identityHex === undefined
) {
process.exit(2);
}
const originalLink = fs.promises.link.bind(fs.promises);
let capturedPath: string | undefined;
let temporaryPath: string | undefined;
fs.promises.link = async (existingPath, newPath) => {
temporaryPath = existingPath.toString();
capturedPath = `${temporaryPath}.captured`;
await fs.promises.rename(temporaryPath, capturedPath);
await fs.promises.writeFile(temporaryPath, 'EVIL');
await originalLink(existingPath, newPath);
};
syncBuiltinESMExports();
const { createSessionBundleFileService } = await import('../../session-bundle-file-service.js');
const { SessionBundleFileError } = await import('../../session-bundle-contract.js');
try {
await createSessionBundleFileService().pack({
snapshot: {
stateRoot,
workspaceRoot,
stateIdentity: {
mediaType: 'application/vnd.maka.session-state-identity+json;version=1',
bytes: Buffer.from(identityHex, 'hex'),
},
},
envelope: {
sessionId: 'cloud-session-1',
lastCommittedActivationId: 'activation-9',
},
destination,
limits: JSON.parse(limitsJson),
});
process.exit(3);
} catch (error) {
await fs.promises.writeFile(
resultPath,
JSON.stringify({
code: error instanceof SessionBundleFileError ? error.code : 'unexpected',
capturedPath,
temporaryPath,
}),
);
process.exit(error instanceof SessionBundleFileError && error.code === 'source_changed' ? 0 : 4);
}
@@ -0,0 +1,75 @@
/*
* 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 fs from 'node:fs';
import { syncBuiltinESMExports } from 'node:module';
const [stateRoot, workspaceRoot, destination, resultPath, limitsJson, identityHex] =
process.argv.slice(2);
if (
stateRoot === undefined ||
workspaceRoot === undefined ||
destination === undefined ||
resultPath === undefined ||
limitsJson === undefined ||
identityHex === undefined
) {
process.exit(2);
}
const originalLink = fs.promises.link.bind(fs.promises);
let capturedPath: string | undefined;
fs.promises.link = async (existingPath, newPath) => {
await originalLink(existingPath, newPath);
const temporaryPath = existingPath.toString();
capturedPath = `${temporaryPath}.captured`;
await fs.promises.rename(temporaryPath, capturedPath);
};
syncBuiltinESMExports();
const { createSessionBundleFileService } = await import('../../session-bundle-file-service.js');
const { SessionBundleFileError } = await import('../../session-bundle-contract.js');
try {
await createSessionBundleFileService().pack({
snapshot: {
stateRoot,
workspaceRoot,
stateIdentity: {
mediaType: 'application/vnd.maka.session-state-identity+json;version=1',
bytes: Buffer.from(identityHex, 'hex'),
},
},
envelope: {
sessionId: 'cloud-session-1',
lastCommittedActivationId: 'activation-9',
},
destination,
limits: JSON.parse(limitsJson),
});
process.exit(3);
} catch (error) {
await fs.promises.writeFile(
resultPath,
JSON.stringify({
code: error instanceof SessionBundleFileError ? error.code : 'unexpected',
capturedPath,
}),
);
process.exit(error instanceof SessionBundleFileError && error.code === 'io_failure' ? 0 : 4);
}
@@ -0,0 +1,44 @@
/*
* 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 { readdirSync, renameSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
const [root, resultPath] = process.argv.slice(2);
if (root === undefined || resultPath === undefined) process.exit(2);
process.stdout.write('ready\n');
const deadline = Date.now() + 10_000;
while (Date.now() < deadline) {
const name = readdirSync(root).find((candidate) =>
candidate.includes('.maka-session-bundle-pack-'),
);
if (name === undefined) continue;
const temporaryPath = join(root, name);
const capturedPath = `${temporaryPath}.captured`;
try {
renameSync(temporaryPath, capturedPath);
writeFileSync(temporaryPath, 'EVIL');
writeFileSync(resultPath, JSON.stringify({ capturedPath, temporaryPath }));
process.exit(0);
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
}
}
process.exit(3);
@@ -0,0 +1,67 @@
/*
* 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 { parentPort, workerData } from 'node:worker_threads';
import type { SandboxBoundarySettlement } from '@maka/core/sandbox-boundary';
import { createSqliteSessionMetadataStore } from '../../sqlite-session-metadata-store.js';
interface WorkerInput {
path: string;
requestId: string;
startSettlement: SharedArrayBuffer;
holdAfterBoundaryWrite?: SharedArrayBuffer;
}
const input = workerData as WorkerInput;
const startSettlement = new Int32Array(input.startSettlement);
const release = input.holdAfterBoundaryWrite
? new Int32Array(input.holdAfterBoundaryWrite)
: undefined;
const store = createSqliteSessionMetadataStore(input.path, {
...(release
? {
failpoint: (point) => {
if (point !== 'after_sandbox_boundary_write') return;
parentPort?.postMessage({ type: 'holding' });
Atomics.wait(release, 0, 0);
},
}
: {}),
});
try {
parentPort?.postMessage({ type: 'ready' });
Atomics.wait(startSettlement, 0, 0);
parentPort?.postMessage({ type: 'attempting' });
const settlement: SandboxBoundarySettlement = await store.settleSandboxBoundaryRequest({
sessionId: 'session-1',
requestId: input.requestId,
decision: 'allow',
});
parentPort?.postMessage({ type: 'settled', settlement });
} catch (error) {
parentPort?.postMessage({
type: 'failed',
message: error instanceof Error ? error.message : String(error),
});
} finally {
store.close();
}
@@ -0,0 +1,390 @@
/*
* 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 { existsSync, writeSync } from 'node:fs';
import { dirname } from 'node:path';
import { type RuntimeEvent } from '@maka/core/runtime-event';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { type ToolRecoveryFactEnvelope } from '@maka/core/tool-recovery-fact';
import { type WorkspaceBaselineAuthorityInput } from '@maka/core/workspace-version-authority';
import { createRuntimeBoundaryCursor, runtimePrefixSegment } from '@maka/core/runtime-boundary';
import { createSqliteRuntimeStore } from '../../sqlite-runtime-store.js';
import { acquireOperationalStateDatabase } from '../../operational-state-store.js';
import {
bindWorkspaceBaselineAuthorityStoreRootInternal,
commitWorkspaceBaselineInternal,
} from '../../workspace-version-authority-internal.js';
const mode = requiredEnv('MAKA_SQLITE_RECOVERY_CONCURRENCY_MODE');
const dbPath = requiredEnv('MAKA_SQLITE_RECOVERY_CONCURRENCY_DB');
const startPath = requiredEnv('MAKA_SQLITE_RECOVERY_CONCURRENCY_START');
const stopPath = process.env.MAKA_SQLITE_RECOVERY_CONCURRENCY_STOP;
writeSync(1, 'READY\n');
while (!existsSync(startPath)) {
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
}
let store: ReturnType<typeof createSqliteRuntimeStore> | undefined;
let operationalLease: ReturnType<typeof acquireOperationalStateDatabase> | undefined;
try {
if (mode === 'operational_open_only') {
operationalLease = acquireOperationalStateDatabase(dirname(dbPath));
} else {
store = createSqliteRuntimeStore(dbPath);
}
writeSync(1, 'OPENED\n');
if (mode === 'open_only' || mode === 'operational_open_only') {
if (!stopPath) throw new Error('Missing MAKA_SQLITE_RECOVERY_CONCURRENCY_STOP');
while (!existsSync(stopPath)) {
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
}
} else if (mode === 'completed') {
await store!.commitToolRecoveryBundle(completedBundle());
} else if (mode === 'parked') {
await store!.commitToolRecoveryBundle(parkedBundle());
} else if (mode === 'rebuild') {
await store!.rebuildToolProjectionsFromRuntimeEvents();
} else if (mode === 'workspace_baseline_a' || mode === 'workspace_baseline_b') {
bindWorkspaceBaselineAuthorityStoreRootInternal(store!, 'a'.repeat(64));
const result = await commitWorkspaceBaselineInternal(
store!,
workspaceBaselineInput(mode === 'workspace_baseline_b' ? 'b' : 'a'),
);
writeSync(1, `BASELINE ${result.created ? 'created' : 'existing'}\n`);
} else if (mode === 'managed_mutation_a' || mode === 'managed_mutation_b') {
bindWorkspaceBaselineAuthorityStoreRootInternal(store!, 'a'.repeat(64));
await store!.commitToolPrepared(managedMutationPreparedCommit(mode.endsWith('_b') ? 'b' : 'a'));
writeSync(1, 'MUTATION reserved\n');
} else if (mode === 'append_source') {
await store!.ensureTerminalRuntimeEventDurable('session-1', 'run-1', {
...baseEvent('concurrent-source-terminal', 3),
status: 'failed',
actions: {
endInvocation: true,
stateDelta: { failureClass: 'runtime_interrupted' },
},
});
writeSync(1, 'APPEND committed\n');
} else if (mode === 'append_target') {
await store!.appendRuntimeEvent('session-1', 'fixed-target-run', {
id: `target-event-${process.pid}`,
sessionId: 'session-1',
invocationId: 'fixed-target-invocation',
runId: 'fixed-target-run',
turnId: 'fixed-target-turn',
ts: process.pid,
partial: false,
role: 'model',
author: 'agent',
content: { kind: 'text', text: 'racing ordinary target event' },
});
writeSync(1, 'TARGET_APPEND committed\n');
} else if (mode === 'claim' || mode === 'claim_fixed_target' || mode === 'claim_nonterminal') {
const sourceRunId = mode === 'claim_nonterminal' ? 'run-1' : 'continuation-source-run';
const prefix = await store!.readImmutableRuntimePrefix({
sessionId: 'session-1',
runId: sourceRunId,
...(mode === 'claim_nonterminal' ? { upToEventSeq: 2 } : {}),
});
const boundary = createRuntimeBoundaryCursor([runtimePrefixSegment(prefix)]);
const source = boundary.segments.at(-1)!;
const target =
mode === 'claim_fixed_target'
? {
sessionId: 'session-1',
invocationId: 'fixed-target-invocation',
runId: 'fixed-target-run',
turnId: 'fixed-target-turn',
}
: {
sessionId: 'session-1',
invocationId: `invocation-${process.pid}`,
runId: `run-${process.pid}`,
turnId: `turn-${process.pid}`,
};
const result = await store!.claimContinuation({
claim: {
protocol: 'continuation_claim_v1',
claimId: `claim-${process.pid}`,
boundaryDigest: boundary.manifestDigest,
boundary,
providerProjectionVersion: 1,
providerReplayDigest: `sha256:${'a'.repeat(64)}`,
target,
targetRunHeader: {
...target,
status: 'created',
backendKind: 'fake',
llmConnectionSlug: 'connection-1',
modelId: 'model-1',
cwd: '/workspace/repo',
permissionMode: 'ask',
collaborationMode: 'agent',
orchestrationMode: 'default',
orchestrationSource: 'session',
agentSwarmAuthorization: 'none',
createdAt: process.pid,
updatedAt: process.pid,
parentRunId: source.identity.runId,
parentTurnId: source.identity.turnId,
continuationSource: {
protocol: 'continuation_source_v2',
claimId: `claim-${process.pid}`,
boundaryDigest: boundary.manifestDigest,
sourceInvocationId: source.identity.invocationId,
sourceRunId: source.identity.runId,
sourceTurnId: source.identity.turnId,
sourceRuntimeEventHighWater: source.position.lastEventSeq,
sourcePrefixDigest: source.prefixDigest,
replayManifestDigest: boundary.manifestDigest,
},
},
claimedAt: process.pid,
},
});
writeSync(1, `CLAIM ${result.kind}\n`);
} else {
throw new Error(`Unknown concurrency mode ${mode}`);
}
writeSync(1, 'RESULT ok\n');
} catch (error) {
writeSync(2, `RESULT error ${error instanceof Error ? error.message : String(error)}\n`);
process.exitCode = 2;
} finally {
store?.close();
operationalLease?.close();
}
function completedBundle() {
return {
operationId: 'operation-1',
reconcileRuntimeEvent: recoveryFact(
'completed-reconcile',
'maka.tool.reconcile_result',
{
protocol: 'tool_reconcile_v1',
operationId: 'operation-1',
observation: 'matches_expected_state',
observationSchema: 'state_identity_v1',
observationDigest:
'sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
},
3,
),
outcomeRuntimeEvent: outcomeEvent(),
decisionRuntimeEvent: recoveryFact(
'completed-decision',
'maka.tool.recovery_decision',
{
protocol: 'tool_recovery_v1',
operationId: 'operation-1',
disposition: 'completed',
reasonCode: 'reconcile_matches_expected_state',
outcomeEventId: 'completed-outcome',
evidenceEventIds: [
'call-event-1',
'dispatch-event-1',
'completed-reconcile',
'completed-outcome',
],
},
5,
),
} as const;
}
function parkedBundle() {
return {
operationId: 'operation-1',
reconcileRuntimeEvent: recoveryFact(
'parked-reconcile',
'maka.tool.reconcile_result',
{
protocol: 'tool_reconcile_v1',
operationId: 'operation-1',
observation: 'diverged',
observationSchema: 'state_identity_v1',
observationDigest:
'sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
},
3,
),
decisionRuntimeEvent: recoveryFact(
'parked-decision',
'maka.tool.recovery_decision',
{
protocol: 'tool_recovery_v1',
operationId: 'operation-1',
disposition: 'parked',
reasonCode: 'reconcile_diverged',
evidenceEventIds: ['call-event-1', 'dispatch-event-1', 'parked-reconcile'],
},
4,
),
} as const;
}
function outcomeEvent(): RuntimeEvent {
return {
...baseEvent('completed-outcome', 4),
role: 'tool',
author: 'tool',
content: {
kind: 'function_response',
id: 'provider-call-1',
name: 'Write',
result: 'ok',
},
refs: { operationId: 'operation-1', toolCallId: 'provider-call-1' },
};
}
function recoveryFact(
id: string,
kind: 'maka.tool.reconcile_result' | 'maka.tool.recovery_decision',
payload: Record<string, unknown>,
ts: number,
): RuntimeEvent {
return {
...baseEvent(id, ts),
actions: {
toolRecovery: { kind, version: 1, payload } as unknown as ToolRecoveryFactEnvelope,
},
refs: { operationId: 'operation-1', toolCallId: 'provider-call-1' },
};
}
function baseEvent(id: string, ts: number): RuntimeEvent {
return {
id,
invocationId: 'invocation-1',
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
ts,
partial: false,
role: 'system',
author: 'system',
};
}
function requiredEnv(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Missing ${name}`);
return value;
}
function workspaceBaselineInput(variant: 'a' | 'b'): WorkspaceBaselineAuthorityInput {
const alternate = variant === 'b';
return {
epochOpenedEventId: alternate ? 'workspace-epoch-event-b' : 'workspace-epoch-event-a',
baselineAcceptedEventId: alternate ? 'workspace-version-event-b' : 'workspace-version-event-a',
committedAt: 1_700_000_000_000,
epoch: {
repositoryId: `repository_${'1'.repeat(32)}`,
workspaceId: `workspace_${'2'.repeat(32)}`,
workspaceEpochId: `epoch_${'3'.repeat(32)}`,
workspaceInstanceId: `instance_${'4'.repeat(32)}`,
mode: 'managed_worktree',
objectFormat: 'sha1',
sourceCommitOid: '1'.repeat(40),
sourceTreeOid: '2'.repeat(40),
materializationProfileDigest: `sha256:${'3'.repeat(64)}`,
materializationSemantics: 'git_tree_materialized_with_fixed_config_v1',
policyHash: `sha256:${'4'.repeat(64)}`,
},
baseline: {
workspaceVersionId: `version_${(alternate ? '9' : '5').repeat(32)}`,
commitOid: (alternate ? '9' : '5').repeat(40),
treeOid: '2'.repeat(40),
treeDeltaDigest: `sha256:${'6'.repeat(64)}`,
changedFileCount: 7,
deletedFileCount: 0,
},
};
}
function managedMutationPreparedCommit(variant: 'a' | 'b') {
const operationId = `managed-mutation-${variant}`;
const toolCallId = `${operationId}-call`;
const args = { path: 'notes.txt', content: variant };
const canonicalArgsHash = canonicalToolArgsHash('Write', args);
return {
operationId,
journalEventId: `${operationId}_prepared`,
runtimeEvent: {
id: `${operationId}-call-event`,
invocationId: `${operationId}-invocation`,
runId: `${operationId}-run`,
sessionId: `${operationId}-session`,
turnId: `${operationId}-turn`,
ts: 1_700_000_000_001,
partial: false,
role: 'model' as const,
author: 'agent' as const,
content: { kind: 'function_call' as const, id: toolCallId, name: 'Write', args },
refs: { operationId, toolCallId },
},
dispatchRuntimeEvent: {
id: `${operationId}-dispatch-event`,
invocationId: `${operationId}-invocation`,
runId: `${operationId}-run`,
sessionId: `${operationId}-session`,
turnId: `${operationId}-turn`,
ts: 1_700_000_000_001,
partial: false,
role: 'system' as const,
author: 'system' as const,
actions: {
toolDispatch: {
protocol: 't1_after_preflight_v1' as const,
operationId,
providerToolCallId: toolCallId,
toolName: 'Write',
canonicalArgsHash,
recoveryMode: 'reconcile' as const,
managedMutation: {
protocol: 'managed_mutation_v2' as const,
repositoryId: `repository_${'1'.repeat(32)}`,
workspaceId: `workspace_${'2'.repeat(32)}`,
workspaceEpochId: `epoch_${'3'.repeat(32)}`,
workspaceInstanceId: `instance_${'4'.repeat(32)}`,
objectFormat: 'sha1' as const,
baseWorkspaceVersionId: `version_${'5'.repeat(32)}`,
baseAcceptedEventId: 'workspace-version-event-a',
baseHeadRevision: 1,
baseCommitOid: '5'.repeat(40),
baseTreeOid: '2'.repeat(40),
expectedPath: 'notes.txt',
pathPolicyVersion: 3 as const,
executionProfileDigest:
'sha256:ffdfdda9cf38f382e0c4db81dac7319cd33586a6c65051a97a15e6c41b88f825' as const,
},
},
},
refs: { operationId, toolCallId },
},
providerToolCallId: toolCallId,
toolName: 'Write',
canonicalArgsHash,
recoveryMode: 'reconcile' as const,
committedAt: 1_700_000_000_001,
};
}
@@ -0,0 +1,47 @@
/*
* 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 { parentPort, threadId, workerData } from 'node:worker_threads';
import { createWorkBoardStore } from '../../work-board-store.js';
interface WorkerInput {
workspaceRoot: string;
itemId: string;
}
const input = workerData as WorkerInput;
const store = createWorkBoardStore(input.workspaceRoot);
try {
const updated = await store.update(
input.itemId,
{ title: `worker-${threadId}` },
{ expectedRevision: 1 },
200,
);
parentPort?.postMessage({ ok: true, revision: updated.revision });
} catch (error) {
parentPort?.postMessage({
ok: false,
code:
error instanceof Error && 'code' in error ? (error as { code?: unknown }).code : 'unknown',
});
} finally {
store.close();
}
@@ -0,0 +1,609 @@
/*
* 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 { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { mkdir, mkdtemp, symlink, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join, win32 } from 'node:path';
import { DatabaseSync } from 'node:sqlite';
import {
FOREIGN_SESSION_SCAN_MAX_SESSIONS,
type ForeignSessionSummary,
} from '@maka/core/foreign-session';
import {
codexCwdSqlVariants,
createForeignSessionStore,
isClaudeCodeImportEnabled,
isCodexImportEnabled,
} from '../foreign-session-store.js';
const NOW = Date.now();
async function tempHome(): Promise<string> {
return mkdtemp(join(tmpdir(), 'maka-foreign-'));
}
function claudeLine(record: Record<string, unknown>): string {
return JSON.stringify(record) + '\n';
}
async function seedClaudeSession(
home: string,
options: {
id: string;
cwd: string;
aiTitle?: string;
sidechain?: boolean;
userText?: string;
assistantText?: string;
filePath?: string;
/** Bytes of leading summary noise before the cwd-bearing record. */
leadingPadBytes?: number;
},
): Promise<string> {
const dir = join(home, '.claude', 'projects', options.cwd.replace(/\//g, '-'));
await mkdir(dir, { recursive: true });
const path = join(dir, `${options.id}.jsonl`);
const lines = [
claudeLine({ type: 'mode', sessionId: options.id, mode: 'default' }),
...(options.leadingPadBytes
? [
claudeLine({
type: 'summary',
sessionId: options.id,
summary: 'x'.repeat(options.leadingPadBytes),
}),
]
: []),
claudeLine({
type: 'user',
sessionId: options.id,
cwd: options.cwd,
gitBranch: 'main',
isSidechain: options.sidechain ?? false,
timestamp: new Date(NOW - 60_000).toISOString(),
message: { role: 'user', content: options.userText ?? 'do the thing' },
}),
claudeLine({
type: 'assistant',
sessionId: options.id,
cwd: options.cwd,
isSidechain: options.sidechain ?? false,
timestamp: new Date(NOW - 30_000).toISOString(),
message: {
role: 'assistant',
content: [
{ type: 'text', text: options.assistantText ?? 'done' },
...(options.filePath
? [{ type: 'tool_use', name: 'Edit', input: { file_path: options.filePath } }]
: []),
],
},
}),
'not valid json\n',
...(options.aiTitle
? [claudeLine({ type: 'ai-title', sessionId: options.id, aiTitle: options.aiTitle })]
: []),
];
await writeFile(path, lines.join(''), 'utf8');
return path;
}
type CodexThreadSeed = {
id: string;
cwd: string;
title?: string;
updatedAtMs?: number;
archived?: number;
source?: string | null;
rolloutRelPath?: string;
};
function seedCodexSqlite(home: string, threads: CodexThreadSeed[]): Promise<void> {
return seedCodexSqliteGen(home, 3, threads);
}
async function seedCodexSqliteGen(
home: string,
gen: number,
threads: CodexThreadSeed[],
): Promise<void> {
const codexRoot = join(home, '.codex');
await mkdir(join(codexRoot, 'sessions', '2026', '07', '18'), { recursive: true });
const db = new DatabaseSync(join(codexRoot, `state_${gen}.sqlite`));
db.exec(`CREATE TABLE threads (
id TEXT PRIMARY KEY, rollout_path TEXT, cwd TEXT, title TEXT,
first_user_message TEXT, updated_at_ms INTEGER, git_branch TEXT,
archived INTEGER DEFAULT 0, source TEXT DEFAULT 'cli'
)`);
const insert = db.prepare(
'INSERT INTO threads (id, rollout_path, cwd, title, updated_at_ms, archived, source) VALUES (?, ?, ?, ?, ?, ?, ?)',
);
for (const t of threads) {
const rollout = join(
codexRoot,
t.rolloutRelPath ?? `sessions/2026/07/18/rollout-1750000000000-${t.id}.jsonl`,
);
await writeFile(
rollout,
[
JSON.stringify({
type: 'session_meta',
timestamp: new Date(NOW - 60_000).toISOString(),
payload: { id: t.id, cwd: t.cwd, git: { branch: 'main' } },
}),
JSON.stringify({
type: 'response_item',
payload: {
type: 'message',
role: 'user',
content: [{ type: 'input_text', text: 'codex task' }],
},
}),
JSON.stringify({
type: 'response_item',
payload: {
type: 'message',
role: 'assistant',
content: [{ type: 'output_text', text: 'codex reply' }],
},
}),
JSON.stringify({
type: 'response_item',
payload: { type: 'function_call', name: 'shell', arguments: '{"cmd":"rm -rf /"}' },
}),
].join('\n') + '\n',
'utf8',
).catch(() => {});
insert.run(
t.id,
rollout,
t.cwd,
t.title ?? null,
t.updatedAtMs ?? NOW - 60_000,
t.archived ?? 0,
t.source === undefined ? 'cli' : t.source,
);
}
db.close();
}
describe('foreign session store — enable flags', () => {
it('defaults on, disabled by exactly "0"', () => {
assert.equal(isClaudeCodeImportEnabled({}), true);
assert.equal(isClaudeCodeImportEnabled({ MAKA_IMPORT_CLAUDE_CODE: '0' }), false);
assert.equal(isCodexImportEnabled({ MAKA_IMPORT_CODEX: '1' }), true);
assert.equal(isCodexImportEnabled({ MAKA_IMPORT_CODEX: '0' }), false);
});
it('reports only sources that are enabled AND present on disk', async () => {
const home = await tempHome();
await mkdir(join(home, '.claude', 'projects'), { recursive: true });
const store = createForeignSessionStore({ homeDir: home, env: {} });
assert.deepEqual(await store.availableSources(), ['claude-code']);
const disabled = createForeignSessionStore({
homeDir: home,
env: { MAKA_IMPORT_CLAUDE_CODE: '0' },
});
assert.deepEqual(await disabled.availableSources(), []);
});
});
describe('foreign session store — Claude scan', () => {
it('lists sessions with title, cwd filter, and drops sidechains', async () => {
const home = await tempHome();
await seedClaudeSession(home, { id: 'aaa', cwd: '/repo/one', aiTitle: '修复登录 bug' });
await seedClaudeSession(home, { id: 'bbb', cwd: '/repo/two' });
await seedClaudeSession(home, { id: 'ccc', cwd: '/repo/one', sidechain: true });
const store = createForeignSessionStore({ homeDir: home, env: {} });
const all = await store.listSessions();
assert.deepEqual(all.map((s) => s.id).sort(), ['aaa', 'bbb']);
const filtered = await store.listSessions({ cwd: '/repo/one' });
assert.equal(filtered.length, 1);
assert.equal(filtered[0]!.id, 'aaa');
assert.equal(filtered[0]!.title, '修复登录 bug');
assert.equal(filtered[0]!.source, 'claude-code');
assert.equal(filtered[0]!.gitBranch, 'main');
});
it('sanitizes hostile titles at the scan boundary', async () => {
const home = await tempHome();
await seedClaudeSession(home, {
id: 'evil',
cwd: '/repo',
aiTitle: 'safe‮titlewith sk-ant-api03-abcdefghijklmnop injected',
});
const store = createForeignSessionStore({ homeDir: home, env: {} });
const [session] = await store.listSessions();
assert.ok(session);
assert.ok(!session.title.includes('‮'));
assert.ok(!session.title.includes(''));
assert.ok(!session.title.includes('sk-ant-api03-abcdefghijklmnop'), session.title);
});
it('caps the number of listed sessions', async () => {
const home = await tempHome();
for (let i = 0; i < FOREIGN_SESSION_SCAN_MAX_SESSIONS + 5; i++) {
await seedClaudeSession(home, { id: `s${String(i).padStart(3, '0')}`, cwd: '/repo' });
}
const store = createForeignSessionStore({ homeDir: home, env: {} });
const all = await store.listSessions();
assert.equal(all.length, FOREIGN_SESSION_SCAN_MAX_SESSIONS);
});
it('finds cwd past the 4KB head via the adaptive window (does not drop the session)', async () => {
const home = await tempHome();
// 100KB of leading summary noise pushes the cwd-bearing user record far
// past a fixed 4KB head — the adaptive read must still find it.
await seedClaudeSession(home, {
id: 'big',
cwd: '/repo',
leadingPadBytes: 100_000,
aiTitle: '大会话',
});
const store = createForeignSessionStore({ homeDir: home, env: {} });
const all = await store.listSessions();
assert.deepEqual(
all.map((s) => s.id),
['big'],
);
assert.equal(all[0]!.cwd, '/repo');
});
it('sanitizes and redacts cwd / gitBranch in the returned summary', async () => {
const home = await tempHome();
const dir = join(home, '.claude', 'projects', '-repo');
await mkdir(dir, { recursive: true });
await writeFile(
join(dir, '0fb0463a-ec8e-4d50-896d-c825c3148ae7.jsonl'),
claudeLine({
type: 'user',
// A cwd carrying a bidi override and a branch carrying a secret must
// not reach a TUI consumer verbatim.
cwd: '/repo' + '\u202E' + 'spoof',
gitBranch: 'feat-AIzaSyA1234567890abcdefghijklmnop',
isSidechain: false,
message: { content: 'hi' },
}),
'utf8',
);
const store = createForeignSessionStore({ homeDir: home, env: {} });
const [session] = await store.listSessions();
assert.ok(session);
assert.ok(!session.cwd.includes('\u202E'), 'bidi override must be stripped from summary cwd');
assert.ok(
!session.gitBranch!.includes('AIzaSyA1234567890abcdefghijklmnop'),
'secret must be redacted from branch',
);
});
it('drops a session whose transcript filename is not a safe id', async () => {
const home = await tempHome();
const dir = join(home, '.claude', 'projects', '-repo');
await mkdir(dir, { recursive: true });
await writeFile(
join(dir, 'has space.jsonl'),
claudeLine({ type: 'user', cwd: '/repo', isSidechain: false, message: { content: 'hi' } }),
'utf8',
);
const store = createForeignSessionStore({ homeDir: home, env: {} });
assert.deepEqual(
(await store.listSessions()).map((s) => s.id),
[],
);
});
});
describe('foreign session store — Codex scan', () => {
it('includes POSIX-shaped SQL variants for a native Windows cwd', () => {
const native = win32.join('C:\\', 'Users', 'me', 'project');
const variants = codexCwdSqlVariants(native);
assert.ok(variants.includes('C:/Users/me/project'));
assert.ok(variants.includes('C:/Users/me/project/'));
});
it('lists threads from sqlite, dropping archived and foreign-source rows', async () => {
const home = await tempHome();
await seedCodexSqlite(home, [
{ id: 't1', cwd: '/repo', title: 'Codex 任务' },
{ id: 't2', cwd: '/repo', archived: 1 },
{ id: 't3', cwd: '/repo', source: 'exotic' },
{ id: 't4', cwd: '/elsewhere' },
]);
const store = createForeignSessionStore({ homeDir: home, env: {} });
const all = await store.listSessions();
assert.deepEqual(all.map((s) => s.id).sort(), ['t1', 't4']);
const filtered = await store.listSessions({ cwd: '/repo' });
assert.deepEqual(
filtered.map((s) => s.id),
['t1'],
);
assert.equal(filtered[0]!.title, 'Codex 任务');
});
it('lists atlas/chatgpt threads whose source is a JSON object', async () => {
const home = await tempHome();
await seedCodexSqlite(home, [
{ id: 'atl', cwd: '/repo', title: 'Atlas', source: '{"custom":"atlas"}' },
{ id: 'gpt', cwd: '/repo', title: 'ChatGPT', source: '{"custom":"chatgpt"}' },
{ id: 'bad', cwd: '/repo', source: '{"custom":"unknown"}' },
]);
const store = createForeignSessionStore({ homeDir: home, env: {} });
assert.deepEqual((await store.listSessions()).map((s) => s.id).sort(), ['atl', 'gpt']);
});
it('routes every supported sqlite source shape through the shared gate', async () => {
const home = await tempHome();
await seedCodexSqlite(home, [
{ id: 'bare-exec', cwd: '/repo', source: 'exec' },
{ id: 'bare-atlas', cwd: '/repo', source: 'atlas' },
{ id: 'bare-chatgpt', cwd: '/repo', source: 'chatgpt' },
{ id: 'wrapped-cli', cwd: '/repo', source: '{ "custom": "cli" }' },
{ id: 'wrapped-vscode', cwd: '/repo', source: '{"custom":"vscode"}' },
{ id: 'legacy-null', cwd: '/repo', source: null },
{ id: 'unsupported', cwd: '/repo', source: '{"custom":"other"}' },
]);
const store = createForeignSessionStore({ homeDir: home, env: {} });
assert.deepEqual((await store.listSessions()).map((session) => session.id).sort(), [
'bare-atlas',
'bare-chatgpt',
'bare-exec',
'legacy-null',
'wrapped-cli',
'wrapped-vscode',
]);
});
it('rejects rollout paths that escape ~/.codex', async () => {
const home = await tempHome();
const outside = join(home, 'outside.jsonl');
await writeFile(
outside,
JSON.stringify({ type: 'session_meta', payload: { id: 'x', cwd: '/repo' } }),
'utf8',
);
await seedCodexSqlite(home, [{ id: 'esc', cwd: '/repo', rolloutRelPath: '../outside.jsonl' }]);
const store = createForeignSessionStore({ homeDir: home, env: {} });
const all = await store.listSessions();
assert.deepEqual(
all.map((s) => s.id),
[],
);
});
it('applies the cwd filter in SQL so a LIMIT of newer other-project rows cannot hide it', async () => {
const home = await tempHome();
const threads = [];
// 120 newer threads in /other, then one older thread in /target. If cwd
// were filtered only after a LIMIT, the target row would be truncated away.
for (let i = 0; i < 120; i++) {
threads.push({
id: `o${String(i).padStart(3, '0')}`,
cwd: '/other',
updatedAtMs: NOW - 1000 * i,
});
}
threads.push({ id: 'target', cwd: '/target', title: 'the one', updatedAtMs: NOW - 10_000_000 });
await seedCodexSqlite(home, threads);
const store = createForeignSessionStore({ homeDir: home, env: {} });
const found = await store.listSessions({ cwd: '/target' });
assert.deepEqual(
found.map((s) => s.id),
['target'],
);
});
it('matches a stored trailing-slash cwd against a caller path without one', async () => {
const home = await tempHome();
await seedCodexSqlite(home, [{ id: 'ts', cwd: '/target/', title: 'trailing slash' }]);
const store = createForeignSessionStore({ homeDir: home, env: {} });
assert.deepEqual(
(await store.listSessions({ cwd: '/target' })).map((s) => s.id),
['ts'],
);
});
it('treats the first usable DB as authoritative: an all-archived newest gen does not resurface older rows', async () => {
const home = await tempHome();
// Newest gen (state_5) has only an archived thread; an older gen has an
// active one. The archived-in-newest session must stay hidden.
await seedCodexSqliteGen(home, 5, [{ id: 'archived-now', cwd: '/repo', archived: 1 }]);
await seedCodexSqliteGen(home, 2, [{ id: 'stale-active', cwd: '/repo', title: 'old' }]);
const store = createForeignSessionStore({ homeDir: home, env: {} });
assert.deepEqual(
(await store.listSessions()).map((s) => s.id),
[],
);
});
it('descends to an older generation only when the newest DB lacks the threads schema', async () => {
const home = await tempHome();
await seedCodexSqliteGen(home, 2, [{ id: 'real', cwd: '/repo', title: 'real' }]);
// Newest gen has no threads table → unusable → skip to gen 2.
const codexRoot = join(home, '.codex');
const badDb = new DatabaseSync(join(codexRoot, 'state_9.sqlite'));
badDb.exec('CREATE TABLE other (x TEXT)');
badDb.close();
const store = createForeignSessionStore({ homeDir: home, env: {} });
assert.deepEqual(
(await store.listSessions()).map((s) => s.id),
['real'],
);
});
it('drops a thread whose rollout filename uuid does not match the row id', async () => {
const home = await tempHome();
// rollout file names a different session than the thread row claims.
await seedCodexSqlite(home, [
{
id: 'realid',
cwd: '/repo',
rolloutRelPath: 'sessions/2026/07/18/rollout-1750000000000-otherid.jsonl',
},
]);
const store = createForeignSessionStore({ homeDir: home, env: {} });
assert.deepEqual(
(await store.listSessions()).map((s) => s.id),
[],
);
});
it('falls back to the rollout walk when no sqlite exists', async () => {
const home = await tempHome();
const day = join(home, '.codex', 'sessions', '2026', '07', '18');
await mkdir(day, { recursive: true });
await writeFile(
join(day, 'rollout-t9.jsonl'),
[
JSON.stringify({
type: 'session_meta',
timestamp: new Date(NOW - 60_000).toISOString(),
payload: { id: 't9', cwd: '/repo' },
}),
JSON.stringify({
type: 'response_item',
payload: {
type: 'message',
role: 'user',
content: [{ type: 'input_text', text: '走兜底路径' }],
},
}),
].join('\n'),
'utf8',
);
const store = createForeignSessionStore({ homeDir: home, env: {} });
const all = await store.listSessions();
assert.equal(all.length, 1);
assert.equal(all[0]!.id, 't9');
assert.equal(all[0]!.title, '走兜底路径');
});
});
describe('foreign session store — digest', () => {
it('builds a digest with user/assistant text and file paths, dropping tool output', async () => {
const home = await tempHome();
await seedClaudeSession(home, {
id: 'd1',
cwd: '/repo',
userText: '帮我修复解析器',
assistantText: '已修复并补了测试',
filePath: '/repo/src/parser.ts',
});
const store = createForeignSessionStore({ homeDir: home, env: {} });
const [session] = await store.listSessions();
assert.ok(session);
const digest = await store.readDigest(session);
assert.deepEqual(digest.userMessages, ['帮我修复解析器']);
assert.deepEqual(digest.assistantTexts, ['已修复并补了测试']);
assert.deepEqual(digest.filesTouched, ['/repo/src/parser.ts']);
// The seeded transcript contains one deliberately-broken line.
assert.ok(
digest.warnings.some((w) => w.includes('malformed')),
JSON.stringify(digest.warnings),
);
});
it('excludes interleaved sidechain records (both user and assistant) from the digest', async () => {
const home = await tempHome();
// A main-session transcript (first record is not sidechain, so the file
// is not dropped) with a sub-agent's sidechain user AND assistant records
// interleaved. None of the sidechain content may enter the main handoff.
const dir = join(home, '.claude', 'projects', '-repo');
await mkdir(dir, { recursive: true });
const id = '0fb0463a-ec8e-4d50-896d-c825c3148ae7';
await writeFile(
join(dir, `${id}.jsonl`),
[
claudeLine({
type: 'user',
cwd: '/repo',
isSidechain: false,
message: { content: 'main request' },
}),
claudeLine({
type: 'user',
isSidechain: true,
message: { content: 'SIDECHAIN USER PROMPT' },
}),
claudeLine({
type: 'assistant',
isSidechain: true,
message: {
content: [
{ type: 'text', text: 'SIDECHAIN ASSISTANT REPLY' },
{ type: 'tool_use', name: 'Edit', input: { file_path: '/repo/sidechain-only.ts' } },
],
},
}),
claudeLine({
type: 'assistant',
isSidechain: false,
message: {
content: [
{ type: 'text', text: 'main reply' },
{ type: 'tool_use', name: 'Edit', input: { file_path: '/repo/main.ts' } },
],
},
}),
].join(''),
'utf8',
);
const store = createForeignSessionStore({ homeDir: home, env: {} });
const [session] = await store.listSessions();
assert.ok(session);
const digest = await store.readDigest(session);
assert.deepEqual(digest.userMessages, ['main request']);
assert.deepEqual(digest.assistantTexts, ['main reply']);
assert.deepEqual(digest.filesTouched, ['/repo/main.ts']);
const flat = JSON.stringify(digest);
assert.ok(!flat.includes('SIDECHAIN'), flat);
assert.ok(!flat.includes('sidechain-only.ts'), flat);
});
it('reads codex rollout digests and drops function calls', async () => {
const home = await tempHome();
await seedCodexSqlite(home, [{ id: 'c1', cwd: '/repo' }]);
const store = createForeignSessionStore({ homeDir: home, env: {} });
const [session] = await store.listSessions();
assert.ok(session);
const digest = await store.readDigest(session);
assert.deepEqual(digest.userMessages, ['codex task']);
assert.deepEqual(digest.assistantTexts, ['codex reply']);
const flat = JSON.stringify(digest);
assert.ok(!flat.includes('rm -rf'), flat);
});
it('refuses a transcript path replaced by an out-of-root symlink', async () => {
const home = await tempHome();
const path = await seedClaudeSession(home, { id: 'sym', cwd: '/repo' });
const store = createForeignSessionStore({ homeDir: home, env: {} });
const [session] = await store.listSessions();
assert.ok(session);
// Swap the transcript for a symlink pointing outside ~/.claude.
const secret = join(home, 'secret.txt');
await writeFile(secret, 'not yours', 'utf8');
const { rm } = await import('node:fs/promises');
await rm(path);
await symlink(secret, path);
await assert.rejects(() => store.readDigest(session as ForeignSessionSummary), /escaped/);
});
});
@@ -0,0 +1,280 @@
/*
* 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 assert from 'node:assert/strict';
import { execFile } from 'node:child_process';
import { mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { promisify } from 'node:util';
import { afterEach, describe, test } from 'node:test';
import { createGitWorktreeChildExecutor } from '../git-worktree-child-executor.js';
import { createGitRepositoryWithWorktree } from './fixtures/git-repository.js';
const execFileAsync = promisify(execFile);
const cleanup: string[] = [];
afterEach(async () => {
await Promise.all(cleanup.splice(0).map((path) => rm(path, { recursive: true, force: true })));
});
describe('Git worktree child executor', () => {
test('reports availability only when the source workspace is a Git project', async () => {
const root = await temporaryRoot();
const repository = join(root, 'repository');
const folder = join(root, 'folder');
await createGitRepositoryWithWorktree(repository, join(root, 'existing-worktree'), 'existing');
await writeFileAfterMkdir(folder, 'file.txt', 'plain\n');
const executor = createGitWorktreeChildExecutor({ storageRoot: join(root, 'storage') });
assert.equal(await executor.isAvailable({ sourceCwd: repository }), true);
assert.equal(await executor.isAvailable({ sourceCwd: folder }), false);
assert.equal(await executor.isAvailable({ sourceCwd: join(root, 'missing') }), false);
});
test('provisions deterministic isolated worktrees for concurrent child leases', async () => {
const root = await temporaryRoot();
const repository = join(root, 'repository');
await createGitRepositoryWithWorktree(repository, join(root, 'existing-worktree'), 'existing');
const executor = createGitWorktreeChildExecutor({ storageRoot: join(root, 'storage') });
const [left, right] = await Promise.all([
executor.provision({
leaseId: `subagent_worktree_${'1'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: repository,
sourceProjectId: 'project-1',
}),
executor.provision({
leaseId: `subagent_worktree_${'2'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: repository,
sourceProjectId: 'project-1',
}),
]);
assert.notEqual(left.worktreePath, right.worktreePath);
assert.notEqual(left.branch, right.branch);
assert.equal((await stat(left.worktreePath)).isDirectory(), true);
assert.equal((await stat(right.worktreePath)).isDirectory(), true);
assert.equal(await git(left.worktreePath, 'branch', '--show-current'), left.branch);
assert.equal(await git(right.worktreePath, 'branch', '--show-current'), right.branch);
assert.equal(left.baseCommit, await git(repository, 'rev-parse', 'HEAD'));
assert.equal(right.baseCommit, left.baseCommit);
await writeFile(join(left.worktreePath, 'left.txt'), 'left\n', 'utf8');
await writeFile(join(right.worktreePath, 'right.txt'), 'right\n', 'utf8');
assert.match(await git(left.worktreePath, 'status', '--short'), /left\.txt/);
assert.match(await git(right.worktreePath, 'status', '--short'), /right\.txt/);
assert.equal(await git(repository, 'status', '--short'), '');
});
test('reuses the durable branch/path binding across executor restart and child edits', async () => {
const root = await temporaryRoot();
const repository = join(root, 'repository');
await createGitRepositoryWithWorktree(repository, join(root, 'existing-worktree'), 'existing');
const storageRoot = join(root, 'storage');
const request = {
leaseId: `subagent_worktree_${'3'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: repository,
};
const first = await createGitWorktreeChildExecutor({ storageRoot }).provision(request);
await writeFile(join(first.worktreePath, 'work.txt'), 'work\n', 'utf8');
await git(first.worktreePath, 'switch', '-c', 'maka/issue-3-a-contract');
const restarted = createGitWorktreeChildExecutor({ storageRoot });
const second = await restarted.provision(request);
assert.deepEqual(second, first);
await restarted.ensure(first);
assert.equal(
await git(first.worktreePath, 'branch', '--show-current'),
'maka/issue-3-a-contract',
);
assert.match(await git(first.worktreePath, 'status', '--short'), /work\.txt/);
await git(
first.worktreePath,
'config',
'--local',
`branch.${first.branch}.maka-worktree-lease`,
`subagent_worktree_${'f'.repeat(32)}`,
);
await assert.rejects(restarted.ensure(first), /worktree lease changed/);
});
test('captures committed, tracked, and untracked changes as one base-relative patch', async () => {
const root = await temporaryRoot();
const repository = join(root, 'repository');
await createGitRepositoryWithWorktree(repository, join(root, 'existing-worktree'), 'existing');
const executor = createGitWorktreeChildExecutor({ storageRoot: join(root, 'storage') });
const binding = await executor.provision({
leaseId: `subagent_worktree_${'6'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: repository,
});
await writeFile(join(binding.worktreePath, 'tracked.txt'), 'committed change\n', 'utf8');
await writeFile(join(binding.worktreePath, '.gitignore'), 'forced.txt\n', 'utf8');
await writeFile(join(binding.worktreePath, 'forced.txt'), 'forced committed change\n', 'utf8');
await git(binding.worktreePath, 'add', 'tracked.txt', '.gitignore');
await git(binding.worktreePath, 'add', '--force', 'forced.txt');
await git(
binding.worktreePath,
'-c',
'user.name=Maka Test',
'-c',
'user.email=test@maka.invalid',
'commit',
'-m',
'child commit',
);
await writeFile(join(binding.worktreePath, 'pending.txt'), 'pending change\n', 'utf8');
const patch = Buffer.from(await executor.capturePatch(binding)).toString('utf8');
assert.match(patch, /diff --git a\/tracked\.txt b\/tracked\.txt/);
assert.match(patch, /\+committed change/);
assert.match(patch, /diff --git a\/forced\.txt b\/forced\.txt/);
assert.match(patch, /\+forced committed change/);
assert.match(patch, /diff --git a\/pending\.txt b\/pending\.txt/);
assert.match(patch, /\+pending change/);
});
test('captures complete patches larger than the former 10 MiB process buffer', async () => {
const root = await temporaryRoot();
const repository = join(root, 'repository');
await createGitRepositoryWithWorktree(repository, join(root, 'existing-worktree'), 'existing');
const executor = createGitWorktreeChildExecutor({ storageRoot: join(root, 'storage') });
const binding = await executor.provision({
leaseId: `subagent_worktree_${'b'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: repository,
});
const formerCeiling = 10 * 1024 * 1024;
await writeFile(
join(binding.worktreePath, 'large-generated.txt'),
'x'.repeat(formerCeiling + 1024),
'utf8',
);
const patch = await executor.capturePatch(binding);
assert.ok(patch.byteLength > formerCeiling);
assert.match(Buffer.from(patch.subarray(0, 512)).toString('utf8'), /large-generated\.txt/);
});
test('retires only the Host lease branch after a child switches branches', async () => {
const root = await temporaryRoot();
const repository = join(root, 'repository');
await createGitRepositoryWithWorktree(repository, join(root, 'existing-worktree'), 'existing');
const executor = createGitWorktreeChildExecutor({ storageRoot: join(root, 'storage') });
const binding = await executor.provision({
leaseId: `subagent_worktree_${'7'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: repository,
});
await git(binding.worktreePath, 'switch', '-c', 'child-owned-branch');
await writeFile(join(binding.worktreePath, 'ignored.tmp'), 'discard me\n', 'utf8');
await executor.retire(binding);
await executor.retire(binding);
await assert.rejects(stat(binding.worktreePath), { code: 'ENOENT' });
assert.equal(await git(repository, 'branch', '--list', binding.branch), '');
assert.equal(
await git(repository, 'branch', '--list', 'child-owned-branch'),
'child-owned-branch',
);
});
test('recovery preserves live bindings and retires orphaned worktrees', async () => {
const root = await temporaryRoot();
const repository = join(root, 'repository');
await createGitRepositoryWithWorktree(repository, join(root, 'existing-worktree'), 'existing');
const storageRoot = join(root, 'storage');
const executor = createGitWorktreeChildExecutor({ storageRoot });
const live = await executor.provision({
leaseId: `subagent_worktree_${'8'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: repository,
});
const orphan = await executor.provision({
leaseId: `subagent_worktree_${'9'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: repository,
});
const partial = join(storageRoot, 'subagent-worktrees', 'a'.repeat(32));
await mkdir(partial);
await createGitWorktreeChildExecutor({ storageRoot }).recover([live]);
assert.equal((await stat(live.worktreePath)).isDirectory(), true);
await assert.rejects(stat(orphan.worktreePath), { code: 'ENOENT' });
await assert.rejects(stat(partial), { code: 'ENOENT' });
assert.equal(await git(repository, 'branch', '--list', orphan.branch), '');
});
test('fails closed when a fresh lease would omit uncommitted parent work', async () => {
const root = await temporaryRoot();
const repository = join(root, 'repository');
await createGitRepositoryWithWorktree(repository, join(root, 'existing-worktree'), 'existing');
await writeFile(join(repository, 'dirty.txt'), 'dirty\n', 'utf8');
const executor = createGitWorktreeChildExecutor({ storageRoot: join(root, 'storage') });
await assert.rejects(
executor.provision({
leaseId: `subagent_worktree_${'4'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: repository,
}),
/no uncommitted changes/,
);
});
test('rejects non-Git project roots', async () => {
const root = await temporaryRoot();
const source = join(root, 'folder');
await writeFileAfterMkdir(source, 'file.txt', 'plain\n');
const executor = createGitWorktreeChildExecutor({ storageRoot: join(root, 'storage') });
await assert.rejects(
executor.provision({
leaseId: `subagent_worktree_${'5'.repeat(32)}`,
sourceSessionId: 'parent-session',
sourceCwd: source,
}),
/requires a Git project/,
);
});
});
async function temporaryRoot(): Promise<string> {
const root = await mkdtemp(join(tmpdir(), 'maka-worktree-child-'));
cleanup.push(root);
return root;
}
async function writeFileAfterMkdir(root: string, name: string, contents: string): Promise<void> {
await mkdir(root, { recursive: true });
await writeFile(join(root, name), contents, 'utf8');
}
async function git(cwd: string, ...args: string[]): Promise<string> {
const { stdout } = await execFileAsync('git', args, { cwd, encoding: 'utf8' });
return stdout.trim();
}
@@ -0,0 +1,211 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, test } from 'node:test';
import type { GoalAuthorityRecord } from '@maka/core/goal';
import { openInteractiveExecutionStoresForWrite } from '../execution-stores.js';
import { openInteractiveGoalAuthorityForWrite } from '../goal-authority.js';
import { resolveStorageRoot, tryAcquireInteractiveRootOwner } from '../root-authority.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
// The control directory of each resolved root lives outside that root, so a
// temporary root's removal leaves it behind; reclaim the recorded rootIds here.
after(removeTrackedControlDirectories);
test('Goal authority commits one revisioned record and preserves its execution reference', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-goal-authority-'));
const capability = trackControlDirectory(
await resolveStorageRoot({ path: join(base, 'interactive'), kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
const writer = await openInteractiveGoalAuthorityForWrite(owner.lease);
try {
const initial = goalRecord(0, null);
const created = await writer.commit({
sessionId: initial.goal.sessionId,
expectedAuthorityRevision: null,
record: initial,
});
assert.equal(created.kind, 'committed');
if (created.kind !== 'committed') return;
assert.equal(created.snapshot?.authorityRevision, 0);
const running = goalRecord(0, {
execution: {
sessionId: initial.goal.sessionId,
turnId: 'turn_goal_1',
runId: 'run_goal_1',
},
checkpoint: { goalId: initial.goal.id, revision: 0 },
controlLease: initial.controlLease,
});
const updated = await writer.commit({
sessionId: running.goal.sessionId,
expectedAuthorityRevision: 0,
record: running,
});
assert.equal(updated.kind, 'committed');
assert.deepEqual((await writer.read(running.goal.sessionId))?.record, running);
const stale = await writer.commit({
sessionId: running.goal.sessionId,
expectedAuthorityRevision: 0,
record: { ...running, goal: { ...running.goal, revision: 1 } },
});
assert.deepEqual(stale, {
kind: 'revision_conflict',
actualAuthorityRevision: 1,
});
assert.equal((await writer.list()).length, 1);
} finally {
await writer.close();
await owner.close();
await rm(base, { recursive: true, force: true });
}
});
test('Goal authority close lets an admitted commit finish before releasing storage', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-goal-authority-close-'));
const capability = trackControlDirectory(
await resolveStorageRoot({ path: join(base, 'interactive'), kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
const writer = await openInteractiveGoalAuthorityForWrite(owner.lease);
const record = goalRecord(0, null);
const committing = writer.commit({
sessionId: record.goal.sessionId,
expectedAuthorityRevision: null,
record,
});
const closing = writer.close();
assert.equal((await committing).kind, 'committed');
await closing;
await owner.close();
const successor = await tryAcquireInteractiveRootOwner(capability);
assert.ok(successor);
if (!successor) return;
try {
const reopened = await openInteractiveGoalAuthorityForWrite(successor.lease);
assert.equal((await reopened.read(record.goal.sessionId))?.record.goal.id, record.goal.id);
await reopened.close();
} finally {
await successor.close();
}
} finally {
await owner.close();
await rm(base, { recursive: true, force: true });
}
});
test('Session retirement atomically removes its Goal authority', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-goal-authority-retirement-'));
const capability = trackControlDirectory(
await resolveStorageRoot({ path: join(base, 'interactive'), kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
const goals = await openInteractiveGoalAuthorityForWrite(owner.lease);
const stores = await openInteractiveExecutionStoresForWrite(owner.lease);
try {
const sessions = await Promise.all(
['archive', 'remove'].map((name) =>
stores.sessionStore.create({
cwd: capability.canonicalPath,
llmConnectionSlug: 'fake',
model: 'fake-model',
permissionMode: 'ask',
name,
}),
),
);
for (const session of sessions) {
const record = goalRecord(0, null, session.id);
assert.equal(
(
await goals.commit({
sessionId: session.id,
expectedAuthorityRevision: null,
record,
})
).kind,
'committed',
);
}
const [archived, removed] = await Promise.all(
sessions.map((session) => stores.sessionStore.readHeaderRecordSnapshot(session.id)),
);
await stores.sessionStore.setSessionsArchivedVersioned(
[{ sessionId: archived.header.id, expectedVersion: archived.revision }],
true,
);
await stores.sessionStore.removeSessionsVersioned([
{ sessionId: removed.header.id, expectedVersion: removed.revision },
]);
assert.equal(await goals.read(archived.header.id), null);
assert.equal(await goals.read(removed.header.id), null);
} finally {
await goals.close();
await stores.sessionStore.close?.();
await owner.close();
await rm(base, { recursive: true, force: true });
}
});
function goalRecord(
revision: number,
currentExecution: GoalAuthorityRecord['currentExecution'],
sessionId = 'session_goal_1',
): GoalAuthorityRecord {
return {
schemaVersion: 1,
goal: {
id: 'goal_1',
revision,
sessionId,
condition: 'Finish the durable Goal refactor.',
status: 'active',
setAt: 1,
iterations: 0,
maxIterations: 50,
consecutiveNoProgress: 0,
blockCap: 8,
tokensAtStart: 0,
tokensNow: 0,
tokensBaselinePending: true,
},
controlLease: { goalId: 'goal_1', generation: 0 },
currentExecution,
};
}
@@ -0,0 +1,31 @@
/*
* 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 assert from 'node:assert/strict';
import { test } from 'node:test';
import { canonicalizeLegacyPlanReminderCronExpression } from '../legacy-cron-expression.js';
test('converts released single-value steps without changing wildcard steps', () => {
assert.equal(canonicalizeLegacyPlanReminderCronExpression('5/10 * * * *'), '5 * * * *');
assert.equal(canonicalizeLegacyPlanReminderCronExpression('*/5 * * * *'), '*/5 * * * *');
});
test('rejects a source expression outside the released grammar', () => {
assert.throws(() => canonicalizeLegacyPlanReminderCronExpression('0 0 30 2 *'));
});
@@ -0,0 +1,205 @@
/*
* 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 assert from 'node:assert/strict';
import { execFile, spawn, type ChildProcess } from 'node:child_process';
import { mkdtemp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { promisify } from 'node:util';
import test from 'node:test';
import {
computeManagedDependencyEnvironmentIdentity,
createManagedDependencyEnvironmentAuthority,
createManagedDependencyEnvironmentProducerCapability,
type ManagedDependencyEnvironmentFailpoint,
} from '../managed-dependency-environment.js';
const execFileAsync = promisify(execFile);
const producerCapability = createManagedDependencyEnvironmentProducerCapability(
`sha256:${'a'.repeat(64)}`,
);
const childEntrypoint = fileURLToPath(
new URL('./fixtures/managed-dependency-environment-crash-child.js', import.meta.url),
);
const ownerChildEntrypoint = fileURLToPath(
new URL('./fixtures/managed-dependency-environment-owner-child.js', import.meta.url),
);
test('rejects a second authority for the same storage root in another process', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-owner-process-'));
const child = spawn(process.execPath, [ownerChildEntrypoint], {
env: { ...process.env, MAKA_DEPENDENCY_OWNER_ROOT: storageRoot },
stdio: ['ignore', 'pipe', 'pipe'],
windowsHide: true,
});
t.after(async () => {
if (child.exitCode === null) child.kill();
if (child.exitCode === null) await onceChildExit(child);
await rm(storageRoot, { recursive: true, force: true });
});
await waitForChildReady(child);
const second = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer: {
capability: producerCapability,
packageManagerName: 'npm',
packageManagerVersion: '11.12.1',
nodeRuntime: {
version: '24.7.0',
abi: '137',
platform: process.platform,
arch: process.arch,
},
async provision() {},
},
}).then(
(authority) => ({ authority }),
(error: unknown) => ({ error }),
);
if ('authority' in second) {
await second.authority.close();
assert.fail('a second process acquired the same dependency authority');
}
assert.match(String(second.error), /already has an active owner/u);
});
for (const failpoint of [
'during_environment_provision',
'after_environment_tree_durable',
'after_environment_receipt_durable',
'after_environment_publish',
] as const satisfies readonly (
| ManagedDependencyEnvironmentFailpoint
| 'during_environment_provision'
)[]) {
test(`converges after process exit at ${failpoint}`, async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-crash-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
await assert.rejects(
execFileAsync(process.execPath, [childEntrypoint], {
env: {
...process.env,
MAKA_DEPENDENCY_CRASH_ROOT: storageRoot,
MAKA_DEPENDENCY_CRASH_POINT: failpoint,
},
windowsHide: true,
}),
(error: unknown) => error instanceof Error && 'code' in error && Number(error.code) === 73,
);
let provisionCalls = 0;
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer: {
capability: producerCapability,
packageManagerName: 'npm',
packageManagerVersion: '11.12.1',
nodeRuntime: {
version: '24.7.0',
abi: '137',
platform: process.platform,
arch: process.arch,
},
async provision(input) {
provisionCalls += 1;
await mkdir(join(input.outputRoot, 'fixture-package'), {
recursive: true,
});
await writeFile(join(input.outputRoot, 'fixture-package', 'index.js'), 'safe\n');
},
},
});
const source = dependencySource();
const lease = await authority.acquire(
computeManagedDependencyEnvironmentIdentity(source),
source,
);
assert.equal(
await readFile(join(lease.dependencyRoot, 'fixture-package', 'index.js'), 'utf8'),
'safe\n',
);
assert.equal(provisionCalls, failpoint === 'after_environment_receipt_durable' ? 0 : 1);
assert.deepEqual(
await readdir(join(storageRoot, 'managed-workspaces', 'dependency-environments', '.staging')),
[],
);
await lease.release();
await authority.close();
});
}
function dependencySource() {
return {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from('{"lockfileVersion":3}\n'),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: process.platform,
arch: process.arch,
producerRuntimeIdentitySha256: producerCapability.runtimeIdentitySha256,
producerPolicyIdentitySha256: producerCapability.policyIdentitySha256,
policyVersion: 'managed_dependency_environment_v1' as const,
};
}
async function waitForChildReady(child: ChildProcess): Promise<void> {
await new Promise<void>((resolve, reject) => {
let output = '';
const timeout = setTimeout(() => finish(new Error('owner child did not become ready')), 15_000);
const finish = (error?: Error) => {
clearTimeout(timeout);
child.stdout?.off('data', onData);
child.stderr?.off('data', onErrorData);
child.off('error', onError);
child.off('exit', onExit);
if (error) reject(error);
else resolve();
};
const onData = (chunk: Buffer) => {
output += chunk.toString('utf8');
if (output.includes('READY\n')) finish();
};
const onErrorData = (chunk: Buffer) => finish(new Error(chunk.toString('utf8')));
const onError = (error: Error) => finish(error);
const onExit = (code: number | null) => finish(new Error(`owner child exited early: ${code}`));
child.stdout?.on('data', onData);
child.stderr?.on('data', onErrorData);
child.on('error', onError);
child.on('exit', onExit);
});
}
async function onceChildExit(child: ChildProcess): Promise<void> {
if (child.exitCode !== null) return;
await new Promise<void>((resolve) => {
const onExit = () => resolve();
child.once('exit', onExit);
if (child.exitCode !== null) {
child.off('exit', onExit);
resolve();
}
});
}
@@ -0,0 +1,847 @@
/*
* 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 assert from 'node:assert/strict';
import {
access,
chmod,
type FileHandle,
mkdtemp,
mkdir,
open,
readFile,
rm,
stat,
symlink,
writeFile,
} from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import {
computeManagedDependencyEnvironmentIdentity,
createManagedDependencyEnvironmentAuthority,
createManagedDependencyEnvironmentProducerCapability,
} from '../managed-dependency-environment.js';
const FIXTURE_PRODUCER_RUNTIME_IDENTITY = `sha256:${'a'.repeat(64)}` as const;
const FIXTURE_PRODUCER_CAPABILITY = createManagedDependencyEnvironmentProducerCapability(
FIXTURE_PRODUCER_RUNTIME_IDENTITY,
);
test('computes one shared environment identity for equivalent dependency inputs', () => {
const input = {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from('{"lockfileVersion":3}\n'),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: 'linux' as const,
arch: 'x64' as const,
producerRuntimeIdentitySha256: `sha256:${'1'.repeat(64)}` as const,
producerPolicyIdentitySha256: `sha256:${'2'.repeat(64)}` as const,
policyVersion: 'managed_dependency_environment_v1' as const,
};
const first = computeManagedDependencyEnvironmentIdentity(input);
const second = computeManagedDependencyEnvironmentIdentity({ ...input });
assert.match(first.environmentId, /^sha256:[0-9a-f]{64}$/);
assert.equal(first.environmentId, second.environmentId);
assert.equal(first.manifestSha256, second.manifestSha256);
assert.equal(first.lockfileSha256, second.lockfileSha256);
assert.notEqual(
first.environmentId,
computeManagedDependencyEnvironmentIdentity({ ...input, nodeAbi: '138' }).environmentId,
);
assert.notEqual(
first.environmentId,
computeManagedDependencyEnvironmentIdentity({
...input,
platform: 'darwin',
}).environmentId,
);
assert.notEqual(
first.environmentId,
computeManagedDependencyEnvironmentIdentity({
...input,
producerRuntimeIdentitySha256: `sha256:${'3'.repeat(64)}`,
}).environmentId,
);
assert.notEqual(
first.environmentId,
computeManagedDependencyEnvironmentIdentity({
...input,
producerPolicyIdentitySha256: `sha256:${'4'.repeat(64)}`,
}).environmentId,
);
});
test('rejects a producer that does not declare the exact hermetic capability', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-capability-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
await assert.rejects(
createManagedDependencyEnvironmentAuthority({
storageRoot,
producer: {
capability: {
...FIXTURE_PRODUCER_CAPABILITY,
network: 'unrestricted' as never,
},
packageManagerName: 'npm',
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision() {},
},
}),
/producer capability is invalid/u,
);
});
test('rejects a second authority for the same storage root in one process', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-single-owner-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision() {},
};
const first = await createManagedDependencyEnvironmentAuthority({ storageRoot, producer });
const second = await createManagedDependencyEnvironmentAuthority({ storageRoot, producer }).then(
(authority) => ({ authority }),
(error: unknown) => ({ error }),
);
if ('authority' in second) {
await second.authority.close();
assert.fail('a second authority acquired the same storage root');
}
assert.match(String(second.error), /already has an active owner/u);
await first.close();
});
test('rejects a published environment whose dependency content was modified', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-tamper-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
await mkdir(join(input.outputRoot, 'fixture-package'), {
recursive: true,
});
await writeFile(join(input.outputRoot, 'fixture-package', 'index.js'), 'trusted\n', 'utf8');
},
};
const identityInput = {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from('{"lockfileVersion":3}\n'),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: process.platform,
arch: process.arch,
producerRuntimeIdentitySha256: FIXTURE_PRODUCER_RUNTIME_IDENTITY,
producerPolicyIdentitySha256: FIXTURE_PRODUCER_CAPABILITY.policyIdentitySha256,
policyVersion: 'managed_dependency_environment_v1' as const,
};
const identity = computeManagedDependencyEnvironmentIdentity(identityInput);
const firstAuthority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
});
const lease = await firstAuthority.acquire(identity, identityInput);
await writeFile(join(lease.dependencyRoot, 'fixture-package', 'index.js'), 'tampered\n', 'utf8');
await lease.release();
await firstAuthority.close();
const reopened = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
});
await assert.rejects(reopened.acquire(identity, identityInput), /does not match its receipt/u);
await reopened.close();
});
test('keeps the receipt in a constrained authority outside the producer-owned artifact domain', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-receipt-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
await writeFile(join(input.outputRoot, 'index.js'), 'trusted\n', 'utf8');
},
};
const source = {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from('{"lockfileVersion":3}\n'),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: process.platform,
arch: process.arch,
producerRuntimeIdentitySha256: FIXTURE_PRODUCER_RUNTIME_IDENTITY,
producerPolicyIdentitySha256: FIXTURE_PRODUCER_CAPABILITY.policyIdentitySha256,
policyVersion: 'managed_dependency_environment_v1' as const,
};
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
});
const lease = await authority.acquire(identity, source);
const artifactRoot = dirname(lease.dependencyRoot);
const authorityDatabasePath = join(
storageRoot,
'managed-workspaces',
'dependency-environment-authority-v1.sqlite',
);
await lease.release();
await assert.rejects(readFile(join(artifactRoot, 'environment-receipt.json'), 'utf8'), {
code: 'ENOENT',
});
await access(authorityDatabasePath);
const reopened = await authority.acquire(identity, source);
await reopened.release();
await authority.close();
});
test('rejects a coordinated artifact and co-located receipt rewrite', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-coordinated-tamper-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
await writeFile(join(input.outputRoot, 'index.js'), 'trusted\n', 'utf8');
},
};
const source = {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from('{"lockfileVersion":3}\n'),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: process.platform,
arch: process.arch,
producerRuntimeIdentitySha256: FIXTURE_PRODUCER_RUNTIME_IDENTITY,
producerPolicyIdentitySha256: FIXTURE_PRODUCER_CAPABILITY.policyIdentitySha256,
policyVersion: 'managed_dependency_environment_v1' as const,
};
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
});
const lease = await authority.acquire(identity, source);
const artifactRoot = dirname(lease.dependencyRoot);
await lease.release();
await authority.close();
await writeFile(join(lease.dependencyRoot, 'index.js'), 'malicious\n', 'utf8');
await writeFile(
join(artifactRoot, 'environment-receipt.json'),
`${JSON.stringify({ environmentId: identity.environmentId, contentTreeSha256: 'forged' })}\n`,
'utf8',
);
const reopened = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
});
await assert.rejects(
reopened.acquire(identity, source),
/artifact contains an unowned entry|content does not match its receipt/u,
);
await reopened.close();
});
test('rejects an environment id that is not the digest of the requested identity', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-identity-forgery-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision() {},
};
const source = {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from('{"lockfileVersion":3}\n'),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: process.platform,
arch: process.arch,
producerRuntimeIdentitySha256: FIXTURE_PRODUCER_RUNTIME_IDENTITY,
producerPolicyIdentitySha256: FIXTURE_PRODUCER_CAPABILITY.policyIdentitySha256,
policyVersion: 'managed_dependency_environment_v1' as const,
};
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
});
await assert.rejects(
authority.acquire({ ...identity, environmentId: `sha256:${'f'.repeat(64)}` }, source),
/identity is not canonical/u,
);
await assert.rejects(
authority.acquire(
{ ...identity, environmentId: 'sha256:../../escaped' } as typeof identity,
source,
),
/identity is not canonical/u,
);
await assert.rejects(access(join(storageRoot, 'escaped')), {
code: 'ENOENT',
});
await authority.close();
});
test('rejects an NTFS alternate stream created inside a dependency artifact', {
skip: process.platform !== 'win32',
}, async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-ads-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
const target = join(input.outputRoot, 'index.js');
await writeFile(target, 'trusted\n', 'utf8');
await writeFile(`${target}:unhashed`, 'malicious\n', 'utf8');
},
};
const source = dependencySourceForName('ads');
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
});
await assert.rejects(
authority.acquire(identity, source),
(error: unknown) =>
error instanceof Error &&
error.message === 'Managed dependency environment contains an alternate data stream',
);
await authority.close();
});
test('rejects an NTFS alternate stream attached to the published dependency root', {
skip: process.platform !== 'win32',
}, async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-root-ads-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
await writeFile(join(input.outputRoot, 'index.js'), 'trusted\n', 'utf8');
},
};
const source = dependencySourceForName('root-ads');
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({ storageRoot, producer });
const lease = await authority.acquire(identity, source);
await writeFile(`${lease.dependencyRoot}:unhashed`, 'malicious\n', 'utf8');
await lease.release();
await authority.close();
const reopened = await createManagedDependencyEnvironmentAuthority({ storageRoot, producer });
await assert.rejects(
reopened.acquire(identity, source),
(error: unknown) =>
error instanceof Error &&
error.message === 'Managed dependency environment contains an alternate data stream',
);
await reopened.close();
});
test('rejects an NTFS alternate stream attached to a published nested directory', {
skip: process.platform !== 'win32',
}, async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-目录-ads-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
const packageRoot = join(input.outputRoot, 'fixture-包');
await mkdir(packageRoot);
await writeFile(join(packageRoot, 'index.js'), 'trusted\n', 'utf8');
},
};
const source = dependencySourceForName('nested-directory-ads');
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({ storageRoot, producer });
const lease = await authority.acquire(identity, source);
await writeFile(`${join(lease.dependencyRoot, 'fixture-包')}:unhashed`, 'malicious\n', 'utf8');
await lease.release();
await authority.close();
const reopened = await createManagedDependencyEnvironmentAuthority({ storageRoot, producer });
await assert.rejects(
reopened.acquire(identity, source),
(error: unknown) =>
error instanceof Error &&
error.message === 'Managed dependency environment contains an alternate data stream',
);
await reopened.close();
});
test('accepts a POSIX package bin symlink whose target remains inside the dependency root', {
skip: process.platform === 'win32',
}, async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-bin-link-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
await mkdir(join(input.outputRoot, 'fixture-package'), {
recursive: true,
});
await mkdir(join(input.outputRoot, '.bin'), { recursive: true });
await writeFile(join(input.outputRoot, 'fixture-package', 'cli.js'), 'trusted\n', 'utf8');
await symlink('../fixture-package/cli.js', join(input.outputRoot, '.bin', 'fixture-cli'));
},
};
const source = dependencySourceForName('posix-bin-link');
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
});
const lease = await authority.acquire(identity, source);
assert.equal(
await readFile(join(lease.dependencyRoot, '.bin', 'fixture-cli'), 'utf8'),
'trusted\n',
);
await lease.release();
await authority.close();
});
test('publishes authority-owned file inodes instead of producer-owned inodes', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-inode-handoff-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
let producerFileIdentity: { dev: bigint; ino: bigint } | undefined;
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
const producerFile = join(input.outputRoot, 'payload');
await writeFile(producerFile, 'trusted\n', 'utf8');
const producerInfo = await stat(producerFile, { bigint: true });
producerFileIdentity = { dev: producerInfo.dev, ino: producerInfo.ino };
},
};
const source = dependencySourceForName('inode-handoff');
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({ storageRoot, producer });
const lease = await authority.acquire(identity, source);
const publishedInfo = await stat(join(lease.dependencyRoot, 'payload'), { bigint: true });
assert.notDeepEqual(
{ dev: publishedInfo.dev, ino: publishedInfo.ino },
producerFileIdentity,
'published content retained the producer-owned inode',
);
await lease.release();
await authority.close();
});
test('seals the complete authority-owned tree before publishing its receipt', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-durable-tree-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
const observedBoundaries: string[] = [];
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
await mkdir(join(input.outputRoot, 'nested', 'package'), { recursive: true });
await writeFile(join(input.outputRoot, 'root.js'), 'root\n', 'utf8');
await writeFile(join(input.outputRoot, 'nested', 'package', 'index.js'), 'nested\n', 'utf8');
},
};
const source = dependencySourceForName('durable-tree');
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
failpoint(point) {
observedBoundaries.push(point);
},
});
const lease = await authority.acquire(identity, source);
assert.deepEqual(observedBoundaries, [
'after_environment_tree_durable',
'after_environment_publish',
'after_environment_receipt_durable',
'before_environment_lease',
]);
await lease.release();
await authority.close();
});
test('publishes Windows read-only dependency files without changing their final mode', {
skip: process.platform !== 'win32',
}, async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-readonly-file-'));
let publishedFile: string | undefined;
t.after(async () => {
if (publishedFile) await chmod(publishedFile, 0o644).catch(() => undefined);
await rm(storageRoot, { recursive: true, force: true });
});
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
const path = join(input.outputRoot, 'readonly.js');
await writeFile(path, 'readonly dependency\n', 'utf8');
await chmod(path, 0o444);
},
};
const source = dependencySourceForName('readonly-file');
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({ storageRoot, producer });
const lease = await authority.acquire(identity, source);
publishedFile = join(lease.dependencyRoot, 'readonly.js');
assert.equal(await readFile(publishedFile, 'utf8'), 'readonly dependency\n');
assert.equal((await stat(publishedFile)).mode & 0o222, 0);
await lease.release();
await authority.close();
});
test('isolates published POSIX content from a producer-retained writable handle', {
skip: process.platform === 'win32',
}, async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-retained-handle-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
let retainedHandle: FileHandle | undefined;
t.after(async () => retainedHandle?.close().catch(() => undefined));
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
retainedHandle = await open(join(input.outputRoot, 'payload'), 'w+');
await retainedHandle.writeFile('trusted\n', 'utf8');
await retainedHandle.sync();
},
};
const source = dependencySourceForName('retained-handle');
const identity = computeManagedDependencyEnvironmentIdentity(source);
const authority = await createManagedDependencyEnvironmentAuthority({ storageRoot, producer });
const lease = await authority.acquire(identity, source);
const malicious = Buffer.from('MALICIOUS\n', 'utf8');
await retainedHandle?.write(malicious, 0, malicious.length, 0);
await retainedHandle?.truncate(malicious.length);
await retainedHandle?.sync();
assert.equal(await readFile(join(lease.dependencyRoot, 'payload'), 'utf8'), 'trusted\n');
await retainedHandle?.close();
retainedHandle = undefined;
await lease.release();
await authority.close();
});
test('publishes one Maka-owned artifact for concurrent equivalent acquisitions', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-environment-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
let provisionCalls = 0;
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer: {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm',
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input) {
provisionCalls += 1;
await mkdir(join(input.outputRoot, 'fixture-package'), {
recursive: true,
});
await writeFile(
join(input.outputRoot, 'fixture-package', 'index.js'),
'export const source = "maka-owned";\n',
'utf8',
);
},
},
});
const identityInput = {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from('{"lockfileVersion":3}\n'),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: process.platform,
arch: process.arch,
producerRuntimeIdentitySha256: FIXTURE_PRODUCER_RUNTIME_IDENTITY,
producerPolicyIdentitySha256: FIXTURE_PRODUCER_CAPABILITY.policyIdentitySha256,
policyVersion: 'managed_dependency_environment_v1' as const,
};
const identity = computeManagedDependencyEnvironmentIdentity(identityInput);
const [first, second] = await Promise.all([
authority.acquire(identity, {
manifestBytes: identityInput.manifestBytes,
lockfileBytes: identityInput.lockfileBytes,
}),
authority.acquire(identity, {
manifestBytes: identityInput.manifestBytes,
lockfileBytes: identityInput.lockfileBytes,
}),
]);
assert.equal(provisionCalls, 1);
assert.equal(first.environmentId, second.environmentId);
assert.equal(first.dependencyRoot, second.dependencyRoot);
await first.release();
await second.release();
await authority.close();
});
test('close drains an acquisition through lease installation before deciding its outcome', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-close-drain-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
let acknowledgeLeaseBoundary!: () => void;
const leaseBoundary = new Promise<void>((resolve) => {
acknowledgeLeaseBoundary = resolve;
});
let continueLeaseInstallation!: () => void;
const leaseInstallationAllowed = new Promise<void>((resolve) => {
continueLeaseInstallation = resolve;
});
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string }) {
await writeFile(join(input.outputRoot, 'payload'), 'trusted\n', 'utf8');
},
};
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
async failpoint(point) {
if (point !== 'before_environment_lease') return;
acknowledgeLeaseBoundary();
await leaseInstallationAllowed;
},
});
const source = dependencySourceForName('close-drain');
const identity = computeManagedDependencyEnvironmentIdentity(source);
const acquireTask = authority.acquire(identity, source);
await leaseBoundary;
const closeTask = authority.close().then(
() => ({ closed: true as const }),
(error: unknown) => ({ error }),
);
await Promise.resolve();
continueLeaseInstallation();
const [lease, closeResult] = await Promise.all([acquireTask, closeTask]);
if ('closed' in closeResult) {
await assert.rejects(lease.release(), /receipt authority is closed/u);
assert.fail('close succeeded while an acquisition was still installing its lease');
}
assert.match(String(closeResult.error), /still has active leases/u);
await lease.release();
await authority.close();
});
test('collects the least-recently-used unleased environment under the cache quota', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-gc-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
let provisionCalls = 0;
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string; identity: { lockfileSha256: string } }) {
provisionCalls += 1;
await writeFile(input.outputRoot + '/payload', input.identity.lockfileSha256.slice(-8));
},
};
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
maxCacheBytes: 8,
});
const source = {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from('{"lockfileVersion":3,"name":"first"}\n'),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: process.platform,
arch: process.arch,
producerRuntimeIdentitySha256: FIXTURE_PRODUCER_RUNTIME_IDENTITY,
producerPolicyIdentitySha256: FIXTURE_PRODUCER_CAPABILITY.policyIdentitySha256,
policyVersion: 'managed_dependency_environment_v1' as const,
};
const firstIdentity = computeManagedDependencyEnvironmentIdentity(source);
const first = await authority.acquire(firstIdentity, source);
await first.release();
const secondSource = {
...source,
lockfileBytes: Buffer.from('{"lockfileVersion":3,"name":"second"}\n'),
};
const secondIdentity = computeManagedDependencyEnvironmentIdentity(secondSource);
const second = await authority.acquire(secondIdentity, secondSource);
await second.release();
const firstAgain = await authority.acquire(firstIdentity, source);
assert.equal(provisionCalls, 3);
await firstAgain.release();
await authority.close();
});
test('does not collect a published environment while its acquisition is still pending', async (t) => {
const storageRoot = await mkdtemp(join(tmpdir(), 'maka-dependency-pending-gc-'));
t.after(() => rm(storageRoot, { recursive: true, force: true }));
let releasePendingPublish!: () => void;
const pendingPublish = new Promise<void>((resolve) => {
releasePendingPublish = resolve;
});
let acknowledgeReceiptDurable!: () => void;
const receiptDurable = new Promise<void>((resolve) => {
acknowledgeReceiptDurable = resolve;
});
let pendingDigest: string | undefined;
const producer = {
capability: FIXTURE_PRODUCER_CAPABILITY,
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeRuntime: fixtureNodeRuntime(),
async provision(input: { outputRoot: string; identity: { lockfileSha256: string } }) {
await writeFile(join(input.outputRoot, 'payload'), input.identity.lockfileSha256, 'utf8');
},
};
const authority = await createManagedDependencyEnvironmentAuthority({
storageRoot,
producer,
maxCacheBytes: 0,
async failpoint(point) {
if (point === 'after_environment_receipt_durable' && pendingDigest) {
acknowledgeReceiptDurable();
await pendingPublish;
}
},
});
const firstSource = dependencySourceForName('first');
const firstIdentity = computeManagedDependencyEnvironmentIdentity(firstSource);
const first = await authority.acquire(firstIdentity, firstSource);
const secondSource = dependencySourceForName('second');
const secondIdentity = computeManagedDependencyEnvironmentIdentity(secondSource);
pendingDigest = secondIdentity.environmentId;
const secondTask = authority.acquire(secondIdentity, secondSource);
await receiptDurable;
await first.release();
releasePendingPublish();
const second = await secondTask;
assert.equal(
await readFile(join(second.dependencyRoot, 'payload'), 'utf8'),
secondIdentity.lockfileSha256,
);
await second.release();
await authority.close();
});
function dependencySourceForName(name: string) {
return {
manifestPath: 'package.json',
manifestBytes: Buffer.from('{"packageManager":"npm@11.12.1"}\n'),
lockfilePath: 'package-lock.json',
lockfileBytes: Buffer.from(`{"lockfileVersion":3,"name":"${name}"}\n`),
packageManagerName: 'npm' as const,
packageManagerVersion: '11.12.1',
nodeVersion: '24.7.0',
nodeAbi: '137',
platform: process.platform,
arch: process.arch,
producerRuntimeIdentitySha256: FIXTURE_PRODUCER_RUNTIME_IDENTITY,
producerPolicyIdentitySha256: FIXTURE_PRODUCER_CAPABILITY.policyIdentitySha256,
policyVersion: 'managed_dependency_environment_v1' as const,
};
}
function fixtureNodeRuntime() {
return {
version: '24.7.0',
abi: '137',
platform: process.platform,
arch: process.arch,
} as const;
}
@@ -0,0 +1,625 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import {
createEncryptedFileManagedSecretStore,
type EncryptedFileManagedSecretKey,
type EncryptedFileManagedSecretKeyProvider,
MANAGED_SECRET_DOCUMENT_FILE,
MANAGED_SECRET_DOCUMENT_SCHEMA_VERSION,
} from '../encrypted-file-managed-secret-store.js';
import {
InMemoryManagedSecretStore,
ManagedSecretError,
type ManagedSecretStore,
} from '../managed-secret-store.js';
const PRINCIPAL = 'user-1';
const SOURCE_SESSION = 'cloud-session-source';
const TARGET_SESSION = 'cloud-session-target';
const ACTIVATION = 'activation-1';
const SECRET_ONE = '00000000-0000-4000-8000-000000000001';
const SECRET_TWO = '00000000-0000-4000-8000-000000000002';
interface StoreHarness {
readonly store: ManagedSecretStore;
close(): Promise<void>;
}
const harnesses: readonly [string, () => Promise<StoreHarness>][] = [
[
'in-memory',
async () => ({
store: new InMemoryManagedSecretStore({ newSecretId: sequenceIds() }),
async close() {},
}),
],
[
'encrypted-file',
async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-managed-secrets-'));
return {
store: createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: new TestKeyProvider(),
newSecretId: sequenceIds(),
}),
close: () => rm(root, { recursive: true, force: true }),
};
},
],
];
for (const [name, createHarness] of harnesses) {
describe(`${name} ManagedSecretStore`, () => {
test('requires an explicit target-Session authorization for copied references', async () => {
await withHarness(createHarness, async ({ store }) => {
const secret = await store.createSecret({ principalId: PRINCIPAL, value: 'source-value' });
await assertRejectCode(
store.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [secret.reference],
}),
'unauthorized',
);
await store.authorizeSession({
principalId: PRINCIPAL,
reference: secret.reference,
cloudSessionId: SOURCE_SESSION,
});
assert.equal(
(
await store.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [secret.reference],
})
)[0]?.value,
'source-value',
);
// A Fork may copy this reference, but the target has no implicit grant.
await assertRejectCode(
store.resolveForActivation({
context: activationContext(TARGET_SESSION),
references: [secret.reference],
}),
'unauthorized',
);
await store.authorizeSession({
principalId: PRINCIPAL,
reference: secret.reference,
cloudSessionId: TARGET_SESSION,
});
assert.equal(
(
await store.resolveForActivation({
context: activationContext(TARGET_SESSION),
references: [secret.reference],
})
)[0]?.value,
'source-value',
);
});
});
test('rotates behind a stable reference and rejects a stale CAS basis', async () => {
await withHarness(createHarness, async ({ store }) => {
const created = await store.createSecret({ principalId: PRINCIPAL, value: 'version-one' });
await store.authorizeSession({
principalId: PRINCIPAL,
reference: created.reference,
cloudSessionId: SOURCE_SESSION,
});
const rotated = await store.rotateSecret({
principalId: PRINCIPAL,
reference: created.reference,
expectedRevision: created.revision,
value: 'version-two',
});
assert.equal(rotated.kind, 'committed');
if (rotated.kind !== 'committed') return;
assert.deepEqual(rotated.secret.reference, created.reference);
assert.equal(rotated.secret.revision, 2);
assert.deepEqual(
await store.rotateSecret({
principalId: PRINCIPAL,
reference: created.reference,
expectedRevision: created.revision,
value: 'stale-write',
}),
{ kind: 'revision_conflict', actualRevision: 2 },
);
const resolved = await store.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [created.reference],
});
assert.equal(resolved[0]?.revision, 2);
assert.equal(resolved[0]?.value, 'version-two');
});
});
test('revocation and grant removal affect later Activations without changing references', async () => {
await withHarness(createHarness, async ({ store }) => {
const first = await store.createSecret({ principalId: PRINCIPAL, value: 'revocable' });
await store.authorizeSession({
principalId: PRINCIPAL,
reference: first.reference,
cloudSessionId: SOURCE_SESSION,
});
await store.revokeSessionAuthorization({
principalId: PRINCIPAL,
reference: first.reference,
cloudSessionId: SOURCE_SESSION,
});
await assertRejectCode(
store.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [first.reference],
}),
'unauthorized',
);
await store.authorizeSession({
principalId: PRINCIPAL,
reference: first.reference,
cloudSessionId: SOURCE_SESSION,
});
const revoked = await store.revokeSecret({
principalId: PRINCIPAL,
reference: first.reference,
expectedRevision: first.revision,
});
assert.equal(revoked.kind, 'committed');
await assertRejectCode(
store.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [first.reference],
}),
'secret_revoked',
);
});
});
test('deletion removes material and target grants without retaining a tombstone', async () => {
await withHarness(createHarness, async ({ store }) => {
const first = await store.createSecret({ principalId: PRINCIPAL, value: 'delete-me' });
await store.authorizeSession({
principalId: PRINCIPAL,
reference: first.reference,
cloudSessionId: SOURCE_SESSION,
});
const deleted = await store.deleteSecret({
principalId: PRINCIPAL,
reference: first.reference,
expectedRevision: first.revision,
});
assert.equal(deleted.kind, 'committed');
if (deleted.kind === 'committed') assert.equal(deleted.secret.status, 'deleted');
assert.equal(
await store.getSecretMetadata({ principalId: PRINCIPAL, reference: first.reference }),
null,
);
await assertRejectCode(
store.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [first.reference],
}),
'secret_not_found',
);
});
});
test('does not expose secret material through metadata or unauthorized principals', async () => {
await withHarness(createHarness, async ({ store }) => {
const value = 'metadata-must-not-contain-this';
const created = await store.createSecret({ principalId: PRINCIPAL, value });
assert.equal(JSON.stringify(created).includes(value), false);
assert.equal(
JSON.stringify(
await store.getSecretMetadata({ principalId: PRINCIPAL, reference: created.reference }),
).includes(value),
false,
);
await assertRejectCode(
store.getSecretMetadata({
principalId: 'another-user',
reference: created.reference,
}),
'unauthorized',
);
});
});
});
}
describe('encrypted file ManagedSecretStore security boundary', () => {
test('keeps mutation timestamps monotonic when the wall clock moves backwards', async () => {
await withTempRoot(async (root) => {
let now = 1_000;
const ids = [generatedSecretId(1), generatedSecretId(2), generatedSecretId(3)];
const store = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: new TestKeyProvider(),
now: () => now,
newSecretId: () => ids.shift()!,
});
const rotating = await store.createSecret({ principalId: PRINCIPAL, value: 'rotate' });
const revoking = await store.createSecret({ principalId: PRINCIPAL, value: 'revoke' });
const deleting = await store.createSecret({ principalId: PRINCIPAL, value: 'delete' });
now = 900;
const rotated = await store.rotateSecret({
principalId: PRINCIPAL,
reference: rotating.reference,
expectedRevision: rotating.revision,
value: 'rotated',
});
const revoked = await store.revokeSecret({
principalId: PRINCIPAL,
reference: revoking.reference,
expectedRevision: revoking.revision,
});
const deleted = await store.deleteSecret({
principalId: PRINCIPAL,
reference: deleting.reference,
expectedRevision: deleting.revision,
});
for (const result of [rotated, revoked, deleted]) {
assert.equal(result.kind, 'committed');
if (result.kind === 'committed') assert.equal(result.secret.updatedAt, 1_000);
}
const reopened = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: new TestKeyProvider(),
});
assert.equal(
(
await reopened.getSecretMetadata({
principalId: PRINCIPAL,
reference: rotating.reference,
})
)?.updatedAt,
1_000,
);
assert.equal(
(
await reopened.getSecretMetadata({
principalId: PRINCIPAL,
reference: revoking.reference,
})
)?.updatedAt,
1_000,
);
assert.equal(
await reopened.getSecretMetadata({
principalId: PRINCIPAL,
reference: deleting.reference,
}),
null,
);
});
});
test('physically removes deleted records and grants so capacity is reusable', async () => {
await withTempRoot(async (root) => {
const ids = [SECRET_ONE, SECRET_TWO];
const path = join(root, MANAGED_SECRET_DOCUMENT_FILE);
const store = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: new TestKeyProvider(),
newSecretId: () => ids.shift()!,
});
const first = await store.createSecret({ principalId: PRINCIPAL, value: 'first' });
await store.authorizeSession({
principalId: PRINCIPAL,
reference: first.reference,
cloudSessionId: SOURCE_SESSION,
});
await store.deleteSecret({
principalId: PRINCIPAL,
reference: first.reference,
expectedRevision: first.revision,
});
const second = await store.createSecret({ principalId: PRINCIPAL, value: 'second' });
const document = JSON.parse(await readFile(path, 'utf8')) as {
secrets: Array<{ secretId: string }>;
grants: Array<{ secretId: string }>;
};
assert.deepEqual(
document.secrets.map((record) => record.secretId),
[second.reference.secretId],
);
assert.deepEqual(document.grants, []);
});
});
test('persists only authenticated ciphertext in a private control-plane root', async () => {
await withTempRoot(async (root) => {
const value = 'never-write-this-in-plaintext';
const store = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: new TestKeyProvider(),
newSecretId: () => SECRET_ONE,
});
await store.createSecret({ principalId: PRINCIPAL, value });
const path = join(root, MANAGED_SECRET_DOCUMENT_FILE);
const raw = await readFile(path, 'utf8');
assert.equal(raw.includes(value), false);
assert.match(raw, /"algorithm": "A256GCM"/u);
if (process.platform !== 'win32') {
assert.equal((await stat(root)).mode & 0o777, 0o700);
assert.equal((await stat(path)).mode & 0o777, 0o600);
}
});
});
test('reopens with the external key and fails closed when the key is unavailable', async () => {
await withTempRoot(async (root) => {
const provider = new TestKeyProvider();
const writer = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: provider,
newSecretId: () => SECRET_ONE,
});
const secret = await writer.createSecret({ principalId: PRINCIPAL, value: 'persisted' });
await writer.authorizeSession({
principalId: PRINCIPAL,
reference: secret.reference,
cloudSessionId: SOURCE_SESSION,
});
const reader = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: provider,
});
assert.equal(
(
await reader.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [secret.reference],
})
)[0]?.value,
'persisted',
);
provider.keys.clear();
await assertRejectCode(
reader.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [secret.reference],
}),
'key_unavailable',
);
});
});
test('uses the provider active key on rotation without changing the portable reference', async () => {
await withTempRoot(async (root) => {
const provider = new TestKeyProvider();
const store = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: provider,
newSecretId: () => SECRET_ONE,
});
const secret = await store.createSecret({ principalId: PRINCIPAL, value: 'before' });
await store.authorizeSession({
principalId: PRINCIPAL,
reference: secret.reference,
cloudSessionId: SOURCE_SESSION,
});
provider.keys.set('test-key-2', Buffer.alloc(32, 9));
provider.activeKeyId = 'test-key-2';
const rotated = await store.rotateSecret({
principalId: PRINCIPAL,
reference: secret.reference,
expectedRevision: secret.revision,
value: 'after',
});
assert.equal(rotated.kind, 'committed');
if (rotated.kind !== 'committed') return;
assert.deepEqual(rotated.secret.reference, secret.reference);
provider.keys.delete('test-key-1');
assert.equal(
(
await store.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [secret.reference],
})
)[0]?.value,
'after',
);
const raw = await readFile(join(root, MANAGED_SECRET_DOCUMENT_FILE), 'utf8');
assert.match(raw, /"keyId": "test-key-2"/u);
assert.doesNotMatch(raw, /"keyId": "test-key-1"/u);
});
});
test('binds ciphertext to identity, owner, and revision with AEAD authentication', async () => {
await withTempRoot(async (root) => {
const store = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: new TestKeyProvider(),
newSecretId: () => SECRET_ONE,
});
const secret = await store.createSecret({ principalId: PRINCIPAL, value: 'authenticated' });
await store.authorizeSession({
principalId: PRINCIPAL,
reference: secret.reference,
cloudSessionId: SOURCE_SESSION,
});
const path = join(root, MANAGED_SECRET_DOCUMENT_FILE);
const document = JSON.parse(await readFile(path, 'utf8')) as {
secrets: Array<{ envelope: { ciphertext: string } }>;
};
const ciphertext = document.secrets[0]!.envelope.ciphertext;
document.secrets[0]!.envelope.ciphertext =
`${ciphertext.startsWith('A') ? 'B' : 'A'}${ciphertext.slice(1)}`;
await writeFile(path, `${JSON.stringify(document)}\n`, 'utf8');
await assertRejectCode(
store.resolveForActivation({
context: activationContext(SOURCE_SESSION),
references: [secret.reference],
}),
'integrity_failure',
);
});
});
test('serializes two store owners so concurrent creates do not lose records', async () => {
await withTempRoot(async (root) => {
const provider = new TestKeyProvider();
const first = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: provider,
newSecretId: () => SECRET_ONE,
});
const second = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: provider,
newSecretId: () => SECRET_TWO,
});
const [one, two] = await Promise.all([
first.createSecret({ principalId: PRINCIPAL, value: 'one' }),
second.createSecret({ principalId: PRINCIPAL, value: 'two' }),
]);
const reader = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: provider,
});
assert.equal(
(await reader.getSecretMetadata({ principalId: PRINCIPAL, reference: one.reference }))
?.revision,
1,
);
assert.equal(
(await reader.getSecretMetadata({ principalId: PRINCIPAL, reference: two.reference }))
?.revision,
1,
);
});
});
test('fails closed on an unknown document schema', async () => {
await withTempRoot(async (root) => {
await writeFile(
join(root, MANAGED_SECRET_DOCUMENT_FILE),
JSON.stringify({
schemaVersion: MANAGED_SECRET_DOCUMENT_SCHEMA_VERSION + 1,
revision: 0,
secrets: [],
grants: [],
}),
'utf8',
);
const store = createEncryptedFileManagedSecretStore({
controlPlaneRoot: root,
keyProvider: new TestKeyProvider(),
});
await assertRejectCode(
store.getSecretMetadata({
principalId: PRINCIPAL,
reference: {
schemaVersion: 1,
secretId: SECRET_ONE,
},
}),
'integrity_failure',
);
});
});
});
class TestKeyProvider implements EncryptedFileManagedSecretKeyProvider {
activeKeyId = 'test-key-1';
readonly keys = new Map<string, Uint8Array>([['test-key-1', Buffer.alloc(32, 7)]]);
async activeKey(): Promise<EncryptedFileManagedSecretKey> {
const key = this.keys.get(this.activeKeyId);
if (!key) throw new Error('missing test key');
return { keyId: this.activeKeyId, key };
}
async keyById(keyId: string): Promise<EncryptedFileManagedSecretKey | null> {
const key = this.keys.get(keyId);
return key ? { keyId, key } : null;
}
}
function sequenceIds(): () => string {
const ids = [SECRET_ONE, SECRET_TWO];
return () => {
const value = ids.shift();
if (!value) throw new Error('test secret ids exhausted');
return value;
};
}
function generatedSecretId(index: number): string {
return `10000000-0000-4000-8000-${index.toString(16).padStart(12, '0')}`;
}
function activationContext(cloudSessionId: string) {
return { principalId: PRINCIPAL, cloudSessionId, activationId: ACTIVATION };
}
async function assertRejectCode(
promise: Promise<unknown>,
code: ManagedSecretError['code'],
): Promise<void> {
await assert.rejects(
promise,
(error: unknown) => error instanceof ManagedSecretError && error.code === code,
);
}
async function withHarness(
createHarness: () => Promise<StoreHarness>,
operation: (harness: StoreHarness) => Promise<void>,
): Promise<void> {
const harness = await createHarness();
try {
await operation(harness);
} finally {
await harness.close();
}
}
async function withTempRoot(operation: (root: string) => Promise<void>): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-managed-secrets-'));
try {
await operation(root);
} finally {
await rm(root, { recursive: true, force: true });
}
}
@@ -0,0 +1,129 @@
/*
* 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 assert from 'node:assert/strict';
import fs from 'node:fs';
import { mkdtemp, open, readdir, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import {
publishMarkerFile,
type MarkerFileDependencies,
type MarkerFileHandle,
} from '../marker-file.js';
test('keeps the open primitive captured at module initialization', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-marker-file-captured-open-'));
const markerFile = '.marker.json';
const originalOpen = fs.promises.open;
let intercepted = false;
fs.promises.open = (async (path, flags, mode) => {
if (typeof path === 'string' && path.startsWith(join(root, `${markerFile}.`))) {
intercepted = true;
}
return originalOpen(path, flags, mode);
}) as typeof fs.promises.open;
try {
await publishMarkerFile({
root,
markerFile,
contents: '{"schemaVersion":1}\n',
maxBytes: 1_024,
publication: 'create',
invalidFile: () => new Error('invalid marker'),
});
assert.equal(intercepted, false);
} finally {
fs.promises.open = originalOpen;
await rm(root, { recursive: true, force: true });
}
});
for (const publication of ['create', 'replace'] as const) {
for (const failurePhase of ['write', 'sync', 'close'] as const) {
test(`${publication} removes its temporary marker after a ${failurePhase} failure`, async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-marker-file-fault-'));
const markerFile = '.marker.json';
const temporaryPath = join(root, `${markerFile}.${process.pid}.fault.tmp`);
const fault = new Error(`${failurePhase} failed`);
try {
await assert.rejects(
() =>
publishMarkerFile(
{
root,
markerFile,
contents: '{"schemaVersion":1}\n',
maxBytes: 1_024,
publication,
invalidFile: () => new Error('invalid marker'),
},
{
randomUUID: () => 'fault',
open: faultingOpen(temporaryPath, failurePhase, fault),
},
),
fault,
);
assert.deepEqual(await readdir(root), []);
} finally {
await rm(root, { recursive: true, force: true });
}
});
}
}
function faultingOpen(
temporaryPath: string,
failurePhase: 'write' | 'sync' | 'close',
fault: Error,
): MarkerFileDependencies['open'] {
return async (path, flags, mode) => {
const handle = await open(path, flags, mode);
if (path !== temporaryPath) return handle;
let closeFailed = false;
const wrapped: MarkerFileHandle = {
stat: (options) => handle.stat(options),
read: (buffer, offset, length, position) => handle.read(buffer, offset, length, position),
writeFile: async (data, encoding) => {
if (failurePhase === 'write') {
await handle.writeFile(data.slice(0, 1), encoding);
throw fault;
}
await handle.writeFile(data, encoding);
},
sync: async () => {
if (failurePhase === 'sync') throw fault;
await handle.sync();
},
close: async () => {
if (failurePhase === 'close' && !closeFailed) {
closeFailed = true;
await handle.close();
throw fault;
}
await handle.close();
},
};
return wrapped;
};
}
@@ -0,0 +1,594 @@
/*
* 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 assert from 'node:assert/strict';
import { fork } from 'node:child_process';
import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, test } from 'node:test';
import { MCP_CONFIG_VERSION, resolveMcpProtocolPreference } from '@maka/core/mcp';
import {
createMcpConfigStore,
normalizeMcpConfig,
normalizeMcpImport,
} from '../mcp-config-store.js';
const roots: string[] = [];
afterEach(async () =>
Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))),
);
test('creates and atomically updates a Claude-compatible mcp.json', async () => {
const root = await tempRoot();
const store = createMcpConfigStore(root);
assert.deepEqual(await store.get(), { version: MCP_CONFIG_VERSION, mcpServers: {} });
const next = await store.upsert('filesystem', {
command: 'npx',
args: ['-y', 'server'],
env: { TOKEN: 'secret' },
enabled: true,
});
assert.equal(
next.mcpServers.filesystem && 'command' in next.mcpServers.filesystem
? next.mcpServers.filesystem.command
: undefined,
'npx',
);
assert.deepEqual(JSON.parse(await readFile(join(root, 'mcp.json'), 'utf8')), next);
if (process.platform !== 'win32')
assert.equal((await stat(join(root, 'mcp.json'))).mode & 0o777, 0o600);
await store.remove('filesystem');
assert.deepEqual((await store.get()).mcpServers, {});
});
test('reads version 1 without rewriting and persists version 3 on the next mutation', async () => {
const root = await tempRoot();
const path = join(root, 'mcp.json');
const legacyText = `${JSON.stringify(
{
version: 1,
mcpServers: {
remote: { enabled: false, url: 'https://example.com/mcp' },
},
},
null,
2,
)}\n`;
await writeFile(path, legacyText, 'utf8');
const store = createMcpConfigStore(root);
const migrated = await store.get();
assert.equal(migrated.version, MCP_CONFIG_VERSION);
assert.deepEqual(migrated.mcpServers.remote, {
enabled: false,
url: 'https://example.com/mcp',
transport: 'auto',
});
assert.equal(await readFile(path, 'utf8'), legacyText);
await store.upsert('local', { command: 'node' });
const persisted = JSON.parse(await readFile(path, 'utf8')) as {
version: number;
mcpServers: Record<string, Record<string, unknown>>;
};
assert.equal(persisted.version, MCP_CONFIG_VERSION);
assert.equal(Object.hasOwn(persisted.mcpServers.remote, 'protocol'), false);
});
test('reads a missing wrapper version as version 1 without rewriting it', async () => {
const root = await tempRoot();
const path = join(root, 'mcp.json');
const legacyText = '{"mcpServers":{"remote":{"url":"https://example.com/mcp"}}}\n';
await writeFile(path, legacyText, 'utf8');
const migrated = await createMcpConfigStore(root).get();
const remote = migrated.mcpServers.remote;
assert.ok(remote && 'url' in remote);
assert.equal(migrated.version, MCP_CONFIG_VERSION);
assert.equal(Object.hasOwn(remote, 'protocol'), false);
assert.equal(resolveMcpProtocolPreference(remote), 'legacy');
assert.equal(await readFile(path, 'utf8'), legacyText);
});
test('reads version 2 remote pins without rewriting and projects them as version 3', async () => {
const root = await tempRoot();
const path = join(root, 'mcp.json');
const versionTwo =
'{"version":2,"mcpServers":{"local":{"command":"node"},"remote":{"url":"https://example.com/mcp","protocol":"2026-07-28"}}}\n';
await writeFile(path, versionTwo, 'utf8');
const migrated = await createMcpConfigStore(root).get();
assert.equal(migrated.version, MCP_CONFIG_VERSION);
assert.equal(resolveMcpProtocolPreference(migrated.mcpServers.local!), 'legacy');
assert.equal(resolveMcpProtocolPreference(migrated.mcpServers.remote!), '2026-07-28');
assert.equal(await readFile(path, 'utf8'), versionTwo);
});
test('round-trips every version 3 protocol preference for remote and stdio', () => {
for (const protocol of ['legacy', 'auto', '2026-07-28'] as const) {
const normalized = normalizeMcpConfig({
version: MCP_CONFIG_VERSION,
mcpServers: {
local: { command: 'node', protocol },
remote: {
url: 'https://example.com/mcp',
transport: 'streamable-http',
protocol,
},
},
});
assert.deepEqual(normalized.mcpServers.remote, {
enabled: true,
url: 'https://example.com/mcp',
transport: 'streamable-http',
protocol,
});
assert.deepEqual(normalized.mcpServers.local, {
enabled: true,
command: 'node',
protocol,
});
}
assert.throws(
() =>
normalizeMcpConfig({
version: MCP_CONFIG_VERSION,
mcpServers: {
remote: { url: 'https://example.com/mcp', protocol: 'future' },
},
}),
/remote\.protocol is invalid/u,
);
});
test('rejects protocol fields under missing or version 1 wrappers', () => {
assert.throws(
() =>
normalizeMcpConfig({
version: 1,
mcpServers: {
remote: { url: 'https://example.com/mcp', protocol: 'legacy' },
},
}),
/version 1 must not contain "protocol"/u,
);
assert.throws(
() =>
normalizeMcpConfig({
mcpServers: {
remote: { url: 'https://example.com/mcp', protocol: undefined },
},
}),
/without a version must not contain "protocol"/u,
);
});
test('rejects protocol on version 2 stdio servers', () => {
assert.throws(
() =>
normalizeMcpConfig({
version: 2,
mcpServers: { local: { command: 'node', protocol: 'legacy' } },
}),
/protocol is not supported for stdio in version 2/u,
);
});
test('allows SSE only with an omitted or explicit legacy protocol', () => {
for (const config of [
{ url: 'https://example.com/sse', transport: 'sse' },
{ url: 'https://example.com/sse', transport: 'sse', protocol: 'legacy' },
] as const) {
assert.doesNotThrow(() => normalizeMcpConfig({ version: 2, mcpServers: { remote: config } }));
}
for (const protocol of ['auto', '2026-07-28'] as const) {
assert.throws(
() =>
normalizeMcpConfig({
version: 2,
mcpServers: {
remote: {
url: 'https://example.com/sse',
transport: 'sse',
protocol,
},
},
}),
/transport "sse" requires protocol "legacy"/u,
);
}
});
test('transform sees the latest committed config, not a caller snapshot', async () => {
// The restore-plus-mutation seam: a marker-bearing write that derived its
// restores from a stale snapshot could roll a rotated secret back. Inside
// transform, apply() must observe the concurrent writer's commit under the
// shared file transaction.
const root = await tempRoot();
const store = createMcpConfigStore(root);
await store.upsert('local', { command: 'npx', env: { TOKEN: 'v1' } });
const rotate = store.upsert('local', { command: 'npx', env: { TOKEN: 'v2-rotated' } });
const observed: string[] = [];
const restoreLike = store.transform((current) => {
const server = current.mcpServers.local;
if (server && 'command' in server && server.env) observed.push(server.env.TOKEN ?? '');
return current;
});
await Promise.all([rotate, restoreLike]);
assert.deepEqual(observed, ['v2-rotated']);
const final = (await store.get()).mcpServers.local;
assert.ok(final && 'command' in final);
assert.equal(final.env?.TOKEN, 'v2-rotated');
});
test('two independent stores preserve concurrent additions to one workspace', async () => {
const root = await tempRoot();
await createMcpConfigStore(root).get();
const desktop = createMcpConfigStore(root);
const tui = createMcpConfigStore(root);
await Promise.all([
desktop.upsert('desktop', { command: 'desktop-server' }),
tui.upsert('tui', { command: 'tui-server' }),
]);
const saved = await createMcpConfigStore(root).get();
assert.equal(
saved.mcpServers.desktop && 'command' in saved.mcpServers.desktop
? saved.mcpServers.desktop.command
: undefined,
'desktop-server',
);
assert.equal(
saved.mcpServers.tui && 'command' in saved.mcpServers.tui
? saved.mcpServers.tui.command
: undefined,
'tui-server',
);
});
test('a new store commits after a killed MCP config writer releases its native lock', async (t) => {
const root = await tempRoot();
const holder = fork(new URL('./fixtures/mcp-config-lock-holder.js', import.meta.url), [root], {
stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
});
t.after(() => {
if (holder.exitCode === null && holder.signalCode === null) holder.kill('SIGKILL');
});
await new Promise<void>((resolve, reject) => {
holder.once('message', (message) => {
if (message === 'locked') resolve();
else reject(new Error(`Unexpected child message: ${String(message)}`));
});
holder.once('error', reject);
holder.once('exit', (code, signal) => {
reject(new Error(`MCP config lock holder exited early (${String(code)}, ${signal})`));
});
});
holder.kill('SIGKILL');
await new Promise<void>((resolve) => holder.once('exit', () => resolve()));
const saved = await createMcpConfigStore(root).upsert('recovered', {
command: 'recovered-server',
});
const recovered = saved.mcpServers.recovered;
assert.ok(recovered && 'command' in recovered);
assert.equal(recovered.command, 'recovered-server');
const reopened = (await createMcpConfigStore(root).get()).mcpServers.recovered;
assert.ok(reopened && 'command' in reopened);
assert.equal(reopened.command, 'recovered-server');
});
test('serializes concurrent updates without corrupting the file', async () => {
const root = await tempRoot();
const store = createMcpConfigStore(root);
await Promise.all(
Array.from({ length: 20 }, (_, index) =>
store.upsert(`s-${index}`, { command: `cmd-${index}` }),
),
);
const saved = await store.get();
assert.deepEqual(
Object.fromEntries(
Object.entries(saved.mcpServers).map(([id, server]) => [
id,
'command' in server ? server.command : undefined,
]),
),
Object.fromEntries(Array.from({ length: 20 }, (_, index) => [`s-${index}`, `cmd-${index}`])),
);
const text = await readFile(join(root, 'mcp.json'), 'utf8');
assert.deepEqual(JSON.parse(text), saved);
});
test('rejects corrupt files and unsafe or invalid configs', async () => {
const root = await tempRoot();
await writeFile(join(root, 'mcp.json'), '{bad', 'utf8');
await assert.rejects(createMcpConfigStore(root).get(), /JSON/u);
assert.throws(
() =>
normalizeMcpConfig({
version: 2,
mcpServers: { constructor: { command: 'x' } },
}),
/Invalid server id/u,
);
assert.throws(
() =>
normalizeMcpConfig({
version: 2,
mcpServers: { bad: { url: 'file:///tmp/x' } },
}),
/http or https/u,
);
await assert.rejects(
createMcpConfigStore(await tempRoot()).upsert('bad', {
url: 'https://user:secret@example.com/mcp',
}),
/embedded credentials/u,
);
assert.throws(() => normalizeMcpConfig({ version: 4, mcpServers: {} }), /Unsupported/u);
});
test('leaves a higher-version file untouched when it is rejected', async () => {
const root = await tempRoot();
const path = join(root, 'mcp.json');
const futureText = '{"version":4,"mcpServers":{}}\n';
await writeFile(path, futureText, 'utf8');
const store = createMcpConfigStore(root);
await assert.rejects(store.get(), /Unsupported MCP config version: 4/u);
await assert.rejects(
store.upsert('local', { command: 'node' }),
/Unsupported MCP config version: 4/u,
);
assert.equal(await readFile(path, 'utf8'), futureText);
});
test('normalizes wrapped imports and direct maps without losing source-version rules', () => {
assert.deepEqual(
normalizeMcpImport(
'{"version":2,"mcpServers":{"remote":{"url":"https://example.com/mcp","protocol":"auto"}}}',
),
{
version: MCP_CONFIG_VERSION,
mcpServers: {
remote: {
enabled: true,
url: 'https://example.com/mcp',
transport: 'auto',
protocol: 'auto',
},
},
},
);
assert.deepEqual(normalizeMcpImport('{"version":{"command":"node"}}'), {
version: MCP_CONFIG_VERSION,
mcpServers: { version: { enabled: true, command: 'node' } },
});
assert.deepEqual(normalizeMcpImport('{"mcpServers":{"command":"node"}}'), {
version: MCP_CONFIG_VERSION,
mcpServers: { mcpServers: { enabled: true, command: 'node' } },
});
});
test('import rejects malformed wrappers and protocol fields from older eras', () => {
assert.throws(() => normalizeMcpImport('{bad'), { reason: 'invalid-json' });
assert.throws(() => normalizeMcpImport('[]'), { reason: 'not-object' });
assert.throws(() => normalizeMcpImport('{"version":3}'), { reason: 'missing-servers' });
assert.throws(() => normalizeMcpImport('{"version":4,"mcpServers":{}}'), {
reason: 'unsupported-version',
version: '4',
});
for (const source of [
'{"remote":{"url":"https://example.com/mcp","protocol":"auto"}}',
'{"version":1,"mcpServers":{"remote":{"url":"https://example.com/mcp","protocol":"auto"}}}',
'{"version":2,"mcpServers":{"local":{"command":"node","protocol":"auto"}}}',
]) {
assert.throws(() => normalizeMcpImport(source), { reason: 'protocol-version' });
}
});
test('refuses cleartext http for non-loopback hosts at the write boundary', async () => {
const store = createMcpConfigStore(await tempRoot());
await assert.rejects(
store.upsert('bad', { url: 'http://example.com/mcp' }),
/https for non-loopback/u,
);
for (const url of [
'http://127.0.0.1:8080/mcp',
'http://localhost:3000/mcp',
'https://example.com/mcp',
]) {
await assert.doesNotReject(store.upsert('ok', { url }));
}
});
test('grandfathers a pre-existing cleartext server on read and keeps the file repairable', async () => {
// A single entry every prior release accepted must not brick the whole
// file: the page would come up empty and even the remove that could fix
// it would take the same throwing path.
const root = await tempRoot();
const path = join(root, 'mcp.json');
await writeFile(
path,
`${JSON.stringify({
version: 2,
mcpServers: {
internal: { url: 'http://mcp.internal.corp/mcp', transport: 'auto' },
good: { command: 'npx' },
},
})}\n`,
'utf8',
);
const store = createMcpConfigStore(root);
const loaded = await store.get();
assert.ok(loaded.mcpServers.internal);
assert.ok(loaded.mcpServers.good);
// Repair paths stay open: removing either server works, and toggling the
// grandfathered entry (same URL) works.
await assert.doesNotReject(store.remove('good'));
await assert.doesNotReject(
store.upsert('internal', { url: 'http://mcp.internal.corp/mcp', enabled: false }),
);
// Introducing or repointing a cleartext endpoint still refuses.
await assert.rejects(
store.upsert('internal', { url: 'http://other.internal.corp/mcp' }),
/https for non-loopback/u,
);
await assert.rejects(
store.upsert('fresh', { url: 'http://example.com/mcp' }),
/https for non-loopback/u,
);
await assert.doesNotReject(store.remove('internal'));
assert.deepEqual((await store.get()).mcpServers, {});
});
test('normalizes and bounds the remote oauth block', async () => {
const normalized = normalizeMcpConfig({
version: 1,
mcpServers: {
notion: {
url: 'https://mcp.notion.com/mcp',
oauth: { clientId: 'abc', scopes: ['read', 'write'], callbackPort: 33389 },
},
},
});
const notion = normalized.mcpServers.notion;
assert.ok(notion && 'url' in notion);
assert.deepEqual(notion.oauth, {
clientId: 'abc',
scopes: ['read', 'write'],
callbackPort: 33389,
});
assert.throws(
() =>
normalizeMcpConfig({
version: 1,
mcpServers: { bad: { url: 'https://example.com/mcp', oauth: { callbackPort: 0 } } },
}),
/callbackPort/u,
);
assert.throws(
() =>
normalizeMcpConfig({
version: 1,
mcpServers: { bad: { url: 'https://example.com/mcp', oauth: { clientId: '' } } },
}),
/clientId/u,
);
// Scopes join space-delimited on the wire and must be RFC 6749 §3.3
// scope-tokens: an empty, whitespace-containing, control-carrying,
// quoted/backslashed or non-ASCII entry would silently change the
// requested grant or come back as invalid_scope far from the mistake.
for (const scopes of [
[''],
['read write'],
['read', 'a\tb'],
['read"admin'],
['read\\admin'],
['read\u0001admin'],
['caf\u00e9'],
]) {
assert.throws(
() =>
normalizeMcpConfig({
version: 1,
mcpServers: { bad: { url: 'https://example.com/mcp', oauth: { clientId: 'x', scopes } } },
}),
/scope token/u,
);
}
// A clientSecret alone cannot form static client credentials.
assert.throws(
() =>
normalizeMcpConfig({
version: 1,
mcpServers: { bad: { url: 'https://example.com/mcp', oauth: { clientSecret: 's3cr3t' } } },
}),
/clientId is required/u,
);
// Scopes join space-delimited on the wire and must be RFC 6749 §3.3
// scope-tokens: an empty, whitespace-containing, control-carrying,
// quoted/backslashed or non-ASCII entry would silently change the
// requested grant or come back as invalid_scope far from the mistake.
for (const scopes of [
[''],
['read write'],
['read', 'a\tb'],
['read"admin'],
['read\\admin'],
['readadmin'],
['café'],
]) {
assert.throws(
() =>
normalizeMcpConfig({
version: 1,
mcpServers: { bad: { url: 'https://example.com/mcp', oauth: { clientId: 'x', scopes } } },
}),
/scope token/u,
);
}
// stdio servers have no oauth block; unknown fields there stay rejected
// by the stdio branch simply dropping them.
const stdio = normalizeMcpConfig({
version: 1,
mcpServers: { local: { command: 'npx', oauth: { clientId: 'x' } } },
}).mcpServers.local;
assert.ok(stdio && !('oauth' in stdio));
});
test('rejects a config that declares both an Authorization header and oauth', () => {
assert.throws(
() =>
normalizeMcpConfig({
version: 1,
mcpServers: {
bad: {
url: 'https://example.com/mcp',
headers: { authorization: 'Bearer x' },
oauth: { clientId: 'abc' },
},
},
}),
/must not include Authorization when oauth is configured/u,
);
// Either alone is fine.
assert.doesNotThrow(() =>
normalizeMcpConfig({
version: 1,
mcpServers: {
headerOnly: { url: 'https://example.com/mcp', headers: { Authorization: 'Bearer x' } },
oauthOnly: { url: 'https://example.com/mcp', oauth: { clientId: 'abc' } },
},
}),
);
});
async function tempRoot(): Promise<string> {
const root = await mkdtemp(join(tmpdir(), 'maka-mcp-store-'));
roots.push(root);
return root;
}
@@ -0,0 +1,813 @@
/*
* 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 assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
import { lstat, mkdir, mkdtemp, readFile, readdir, rm, symlink, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import {
MemoryBundleBackupRevisionConflictError,
MemoryBundleRevisionConflictError,
MemoryBundleBackupNotFoundError,
MemoryBundleStoreError,
authenticateInteractiveMemoryBundleStoreReader,
authenticateInteractiveMemoryBundleStoreWriter,
openInteractiveMemoryBundleStoreForRead,
openInteractiveMemoryBundleStoreForWrite,
type MemoryBundleSnapshot,
type MemoryDocumentSnapshot,
type MemoryRevision,
} from '../memory-bundle-store.js';
import {
resolveStorageRoot,
tryAcquireInteractiveRootOwner,
tryAcquireInteractiveRootReader,
type InteractiveRootOwner,
type StorageRootCapability,
} from '../root-authority.js';
import { removeControlDirectory } from './fixtures/control-directory-hygiene.js';
const MEMORY_DIRECTORY = 'memory';
const TRANSACTION_DIRECTORY = '.memory-bundle-transaction';
describe('interactive Memory bundle storage authority', () => {
test('reader and writer recovery are non-mutating when no transaction exists', async () => {
await withInteractiveRoot(async ({ root, capability }) => {
const readerOwner = await tryAcquireInteractiveRootReader(capability);
assert.ok(readerOwner);
if (!readerOwner) return;
try {
const reader = await openInteractiveMemoryBundleStoreForRead(readerOwner.lease);
assert.strictEqual(authenticateInteractiveMemoryBundleStoreReader(reader), reader);
const snapshot = await reader.read();
assert.equal(snapshot.memory.kind, 'missing');
assert.equal(snapshot.pending.kind, 'missing');
await assert.rejects(lstat(memoryDirectory(root)), { code: 'ENOENT' });
} finally {
await readerOwner.close();
}
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
const writer = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
assert.strictEqual(authenticateInteractiveMemoryBundleStoreWriter(writer), writer);
const snapshot = await writer.read();
assert.equal(snapshot.memory.kind, 'missing');
assert.equal(snapshot.pending.kind, 'missing');
await assert.rejects(lstat(memoryDirectory(root)), { code: 'ENOENT' });
await assert.rejects(lstat(pendingPath(root)), { code: 'ENOENT' });
} finally {
await owner.close();
}
});
});
test('commits MEMORY.md and PENDING.md under one exact bundle CAS', async () => {
await withInteractiveOwner(async ({ root, owner }) => {
const store = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
const initial = await store.read();
const memory = Buffer.from('# Maka Memory\n\n## Preference\nUse concise answers.\n');
const pending = Buffer.from('# Maka Pending Memory\n\n## Candidate\nReview this.\n');
const committed = await store.commit({
expectedRevision: initial.revision,
memory,
pending,
});
assert.equal(committed.changed, true);
assert.deepEqual(await readFile(memoryPath(root)), memory);
assert.deepEqual(await readFile(pendingPath(root)), pending);
assert.equal(committed.snapshot.memory.kind, 'document');
assert.equal(committed.snapshot.pending.kind, 'document');
const unchanged = await store.commit({
expectedRevision: committed.snapshot.revision,
memory,
pending,
});
assert.equal(unchanged.changed, false);
await assert.rejects(
store.commit({
expectedRevision: initial.revision,
memory: Buffer.from('# Stale overwrite\n'),
pending,
}),
(error: unknown) =>
error instanceof MemoryBundleRevisionConflictError &&
error.actual.revision === committed.snapshot.revision,
);
});
});
test('detects direct external edits before publishing a mutation', async () => {
await withInteractiveOwner(async ({ root, owner }) => {
const store = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
const basis = await store.read();
const external = Buffer.from('# External edit\n');
await mkdir(memoryDirectory(root), { mode: 0o700 });
await writeFile(memoryPath(root), external);
await assert.rejects(
store.commit({
expectedRevision: basis.revision,
memory: Buffer.from('# Lost update\n'),
pending: null,
}),
(error: unknown) =>
error instanceof MemoryBundleRevisionConflictError &&
error.actual.memory.kind === 'document' &&
error.actual.memory.revision === revision(external),
);
assert.deepEqual(await readFile(memoryPath(root)), external);
});
});
test('restores a selected backup, preserves PENDING.md, and rotates restore undo history', async () => {
await withInteractiveOwner(async ({ root, owner }) => {
const store = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
const initial = await store.read();
const first = Buffer.from('# First memory\n');
const second = Buffer.from('# Second memory\n');
const pending = Buffer.from('# Pending remains\n');
const firstCommit = await store.commit({
expectedRevision: initial.revision,
memory: first,
pending,
});
const secondCommit = await store.commit({
expectedRevision: firstCommit.snapshot.revision,
memory: second,
pending,
backup: 'save',
});
const saveBackup = (await store.listBackups()).find((backup) => backup.kind === 'save');
assert.ok(saveBackup);
const restoredFirst = await store.restoreBackup({
expectedRevision: secondCommit.snapshot.revision,
expectedBackupRevision: saveBackup.revision,
kind: 'save',
});
assert.deepEqual(await readFile(memoryPath(root)), first);
assert.deepEqual(await readFile(pendingPath(root)), pending);
assert.deepEqual(
await readFile(join(memoryDirectory(root), 'MEMORY.md.restore.bak')),
second,
);
const restoreBackup = (await store.listBackups()).find((backup) => backup.kind === 'restore');
assert.ok(restoreBackup);
const restoredSecond = await store.restoreBackup({
expectedRevision: restoredFirst.snapshot.revision,
expectedBackupRevision: restoreBackup.revision,
kind: 'restore',
});
assert.deepEqual(await readFile(memoryPath(root)), second);
assert.deepEqual(await readFile(join(memoryDirectory(root), 'MEMORY.md.restore.bak')), first);
assert.deepEqual(
await readFile(join(memoryDirectory(root), 'MEMORY.md.restore.1.bak')),
second,
);
assert.equal(restoredSecond.changed, true);
await assert.rejects(
store.restoreBackup({
expectedRevision: restoredSecond.snapshot.revision,
expectedBackupRevision: revision(Buffer.from('missing reset backup')),
kind: 'reset',
}),
(error: unknown) =>
error instanceof MemoryBundleBackupNotFoundError && error.kind === 'reset',
);
});
});
test('can restore a bounded safe-mode backup for manual recovery', async () => {
await withInteractiveOwner(async ({ root, owner }) => {
const store = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
const initial = await store.read();
const current = await store.commit({
expectedRevision: initial.revision,
memory: Buffer.from('# Current memory\n'),
pending: null,
});
const oversized = Buffer.alloc(128 * 1024 + 1, 0x61);
await writeFile(join(memoryDirectory(root), 'MEMORY.md.bak'), oversized);
const saveBackup = (await store.listBackups()).find((backup) => backup.kind === 'save');
assert.ok(saveBackup);
const restored = await store.restoreBackup({
expectedRevision: current.snapshot.revision,
expectedBackupRevision: saveBackup.revision,
kind: 'save',
});
assert.equal(restored.snapshot.memory.kind, 'safe_mode');
if (restored.snapshot.memory.kind === 'safe_mode') {
assert.equal(restored.snapshot.memory.reason, 'oversize');
assert.equal(restored.snapshot.memory.byteLength, oversized.byteLength);
}
assert.deepEqual(await readFile(memoryPath(root)), oversized);
});
});
test('rejects a stale backup candidate even when the bundle revision is unchanged', async () => {
await withInteractiveOwner(async ({ root, owner }) => {
const store = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
const initial = await store.read();
const first = Buffer.from('# First memory\n');
const firstCommit = await store.commit({
expectedRevision: initial.revision,
memory: first,
pending: null,
});
const second = Buffer.from('# Second memory\n');
const secondCommit = await store.commit({
expectedRevision: firstCommit.snapshot.revision,
memory: second,
pending: null,
backup: 'save',
});
const selected = (await store.listBackups()).find((backup) => backup.kind === 'save');
assert.ok(selected);
assert.equal(selected.revision, revision(first));
const unchanged = await store.commit({
expectedRevision: secondCommit.snapshot.revision,
memory: second,
pending: null,
backup: 'save',
});
assert.equal(unchanged.changed, false);
assert.equal(unchanged.snapshot.revision, secondCommit.snapshot.revision);
const replaced = (await store.listBackups()).find((backup) => backup.kind === 'save');
assert.ok(replaced);
assert.equal(replaced.revision, revision(second));
await assert.rejects(
store.restoreBackup({
expectedRevision: secondCommit.snapshot.revision,
expectedBackupRevision: selected.revision,
kind: 'save',
}),
(error: unknown) =>
error instanceof MemoryBundleBackupRevisionConflictError &&
error.kind === 'save' &&
error.expectedRevision === selected.revision &&
error.actualRevision === replaced.revision,
);
assert.deepEqual(await readFile(memoryPath(root)), second);
});
});
test('rolls a durable two-document decision forward after partial materialization', async () => {
await withInteractiveRoot(async ({ root, capability }) => {
const targetMemory = Buffer.from('# Target memory\n');
const oldPending = Buffer.from('# Old pending\n');
const targetPending = Buffer.from('# Target pending\n');
await mkdir(memoryDirectory(root), { mode: 0o700 });
await writeFile(memoryPath(root), targetMemory);
await writeFile(pendingPath(root), oldPending);
const readerOwner = await tryAcquireInteractiveRootReader(capability);
assert.ok(readerOwner);
if (!readerOwner) return;
let basis: MemoryBundleSnapshot;
let target: MemoryBundleSnapshot;
try {
const reader = await openInteractiveMemoryBundleStoreForRead(readerOwner.lease);
basis = await reader.read();
await writeFile(pendingPath(root), targetPending);
target = await reader.read();
} finally {
await readerOwner.close();
}
await writeFile(pendingPath(root), oldPending);
const transaction = join(memoryDirectory(root), TRANSACTION_DIRECTORY);
await mkdir(transaction, { mode: 0o700 });
await writeFile(join(transaction, 'MEMORY.md.next'), targetMemory, { mode: 0o600 });
await writeFile(join(transaction, 'PENDING.md.next'), targetPending, { mode: 0o600 });
await writeFile(
join(transaction, 'decision.json'),
`${JSON.stringify({
schemaVersion: 1,
basis: transactionBundleDecision(basis),
target: transactionBundleDecision(target),
})}\n`,
{ mode: 0o600 },
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
const store = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
const recovered = await store.read();
assert.equal(recovered.revision, target.revision);
assert.deepEqual(await readFile(memoryPath(root)), targetMemory);
assert.deepEqual(await readFile(pendingPath(root)), targetPending);
await assert.rejects(lstat(transaction), { code: 'ENOENT' });
} finally {
await owner.close();
}
});
});
test('preserves external edits made after a durable decision', async () => {
await withInteractiveRoot(async ({ root, capability }) => {
const basisMemory = Buffer.from('# Basis memory\n');
const basisPending = Buffer.from('# Basis pending\n');
const targetMemory = Buffer.from('# Target memory\n');
const targetPending = Buffer.from('# Target pending\n');
const externalPending = Buffer.from('# External edit after commit\n');
await mkdir(memoryDirectory(root), { mode: 0o700 });
await writeFile(memoryPath(root), basisMemory);
await writeFile(pendingPath(root), basisPending);
const readerOwner = await tryAcquireInteractiveRootReader(capability);
assert.ok(readerOwner);
if (!readerOwner) return;
let basis: MemoryBundleSnapshot;
let target: MemoryBundleSnapshot;
try {
const reader = await openInteractiveMemoryBundleStoreForRead(readerOwner.lease);
basis = await reader.read();
await writeFile(memoryPath(root), targetMemory);
await writeFile(pendingPath(root), targetPending);
target = await reader.read();
} finally {
await readerOwner.close();
}
await writeFile(pendingPath(root), externalPending);
const transaction = join(memoryDirectory(root), TRANSACTION_DIRECTORY);
await mkdir(transaction, { mode: 0o700 });
await writeFile(join(transaction, 'MEMORY.md.next'), targetMemory, { mode: 0o600 });
await writeFile(join(transaction, 'PENDING.md.next'), targetPending, { mode: 0o600 });
await writeFile(
join(transaction, 'decision.json'),
`${JSON.stringify({
schemaVersion: 1,
basis: transactionBundleDecision(basis),
target: transactionBundleDecision(target),
})}\n`,
{ mode: 0o600 },
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
await assert.rejects(
openInteractiveMemoryBundleStoreForWrite(owner.lease),
(error: unknown) =>
error instanceof MemoryBundleStoreError && error.code === 'recovery_conflict',
);
assert.deepEqual(await readFile(memoryPath(root)), targetMemory);
assert.deepEqual(await readFile(pendingPath(root)), externalPending);
assert.equal((await lstat(transaction)).isDirectory(), true);
} finally {
await owner.close();
}
});
});
test('does not replace an external save published after basis displacement', async () => {
await withInteractiveRoot(async ({ root, capability }) => {
const basisMemory = Buffer.from('# Basis memory\n');
const targetMemory = Buffer.from('# Target memory\n');
const externalMemory = Buffer.from('# External replacement\n');
await mkdir(memoryDirectory(root), { mode: 0o700 });
await writeFile(memoryPath(root), basisMemory);
const readerOwner = await tryAcquireInteractiveRootReader(capability);
assert.ok(readerOwner);
if (!readerOwner) return;
let basis: MemoryBundleSnapshot;
let target: MemoryBundleSnapshot;
try {
const reader = await openInteractiveMemoryBundleStoreForRead(readerOwner.lease);
basis = await reader.read();
await writeFile(memoryPath(root), targetMemory);
target = await reader.read();
} finally {
await readerOwner.close();
}
const transaction = join(memoryDirectory(root), TRANSACTION_DIRECTORY);
await mkdir(transaction, { mode: 0o700 });
await writeFile(join(transaction, 'MEMORY.md.next'), targetMemory, { mode: 0o600 });
await writeFile(join(transaction, 'MEMORY.md.displaced'), basisMemory, { mode: 0o600 });
await writeFile(
join(transaction, 'decision.json'),
`${JSON.stringify({
schemaVersion: 1,
basis: transactionBundleDecision(basis),
target: transactionBundleDecision(target),
})}\n`,
{ mode: 0o600 },
);
await writeFile(memoryPath(root), externalMemory);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
await assert.rejects(
openInteractiveMemoryBundleStoreForWrite(owner.lease),
(error: unknown) =>
error instanceof MemoryBundleStoreError && error.code === 'recovery_conflict',
);
assert.deepEqual(await readFile(memoryPath(root)), externalMemory);
assert.deepEqual(await readFile(join(transaction, 'MEMORY.md.displaced')), basisMemory);
assert.deepEqual(await readFile(join(transaction, 'MEMORY.md.next')), targetMemory);
assert.equal((await lstat(transaction)).isDirectory(), true);
} finally {
await owner.close();
}
});
});
test('restores an external save captured while displacing the basis', async () => {
await withInteractiveRoot(async ({ root, capability }) => {
const basisMemory = Buffer.from('# Basis memory\n');
const targetMemory = Buffer.from('# Target memory\n');
const externalMemory = Buffer.from('# External in-place save\n');
await mkdir(memoryDirectory(root), { mode: 0o700 });
await writeFile(memoryPath(root), basisMemory);
const readerOwner = await tryAcquireInteractiveRootReader(capability);
assert.ok(readerOwner);
if (!readerOwner) return;
let basis: MemoryBundleSnapshot;
let target: MemoryBundleSnapshot;
try {
const reader = await openInteractiveMemoryBundleStoreForRead(readerOwner.lease);
basis = await reader.read();
await writeFile(memoryPath(root), targetMemory);
target = await reader.read();
} finally {
await readerOwner.close();
}
const transaction = join(memoryDirectory(root), TRANSACTION_DIRECTORY);
await mkdir(transaction, { mode: 0o700 });
await writeFile(join(transaction, 'MEMORY.md.next'), targetMemory, { mode: 0o600 });
await writeFile(join(transaction, 'MEMORY.md.displaced'), externalMemory, { mode: 0o600 });
await writeFile(
join(transaction, 'decision.json'),
`${JSON.stringify({
schemaVersion: 1,
basis: transactionBundleDecision(basis),
target: transactionBundleDecision(target),
})}\n`,
{ mode: 0o600 },
);
await rm(memoryPath(root));
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
await assert.rejects(
openInteractiveMemoryBundleStoreForWrite(owner.lease),
(error: unknown) =>
error instanceof MemoryBundleStoreError && error.code === 'recovery_conflict',
);
assert.deepEqual(await readFile(memoryPath(root)), externalMemory);
assert.deepEqual(await readFile(join(transaction, 'MEMORY.md.displaced')), externalMemory);
assert.deepEqual(await readFile(join(transaction, 'MEMORY.md.next')), targetMemory);
assert.equal((await lstat(transaction)).isDirectory(), true);
} finally {
await owner.close();
}
});
});
test('keeps staged targets immutable after partial materialization', async () => {
await withInteractiveRoot(async ({ root, capability }) => {
const basisMemory = Buffer.from('# Basis memory\n');
const basisPending = Buffer.from('# Basis pending\n');
const targetMemory = Buffer.from('# Target memory\n');
const targetPending = Buffer.from('# Target pending\n');
const externalMemory = Buffer.from('# External in-place edit\n');
const externalPending = Buffer.from('# External pending edit\n');
await mkdir(memoryDirectory(root), { mode: 0o700 });
await writeFile(memoryPath(root), basisMemory);
await writeFile(pendingPath(root), basisPending);
const readerOwner = await tryAcquireInteractiveRootReader(capability);
assert.ok(readerOwner);
if (!readerOwner) return;
let basis: MemoryBundleSnapshot;
let target: MemoryBundleSnapshot;
try {
const reader = await openInteractiveMemoryBundleStoreForRead(readerOwner.lease);
basis = await reader.read();
await writeFile(memoryPath(root), targetMemory);
await writeFile(pendingPath(root), targetPending);
target = await reader.read();
} finally {
await readerOwner.close();
}
await writeFile(memoryPath(root), basisMemory);
await writeFile(pendingPath(root), externalPending);
const transaction = join(memoryDirectory(root), TRANSACTION_DIRECTORY);
await mkdir(transaction, { mode: 0o700 });
await writeFile(join(transaction, 'MEMORY.md.next'), targetMemory, { mode: 0o600 });
await writeFile(join(transaction, 'PENDING.md.next'), targetPending, { mode: 0o600 });
await writeFile(
join(transaction, 'decision.json'),
`${JSON.stringify({
schemaVersion: 1,
basis: transactionBundleDecision(basis),
target: transactionBundleDecision(target),
})}\n`,
{ mode: 0o600 },
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
await assert.rejects(
openInteractiveMemoryBundleStoreForWrite(owner.lease),
(error: unknown) =>
error instanceof MemoryBundleStoreError && error.code === 'recovery_conflict',
);
assert.deepEqual(await readFile(memoryPath(root)), targetMemory);
assert.deepEqual(await readFile(pendingPath(root)), externalPending);
await writeFile(memoryPath(root), externalMemory);
assert.deepEqual(await readFile(memoryPath(root)), externalMemory);
assert.deepEqual(await readFile(join(transaction, 'MEMORY.md.next')), targetMemory);
assert.equal(
(await readdir(transaction)).some((entry) => entry.endsWith('.publish')),
false,
);
} finally {
await owner.close();
}
});
});
test('rejects a durable decision whose document state disagrees with staged bytes', async () => {
await withInteractiveRoot(async ({ root, capability }) => {
const current = Buffer.from('# Current memory\n');
const currentRevision = revision(current);
await mkdir(memoryDirectory(root), { mode: 0o700 });
await writeFile(memoryPath(root), current);
const readerOwner = await tryAcquireInteractiveRootReader(capability);
assert.ok(readerOwner);
if (!readerOwner) return;
let basis: MemoryBundleSnapshot;
try {
basis = await (await openInteractiveMemoryBundleStoreForRead(readerOwner.lease)).read();
} finally {
await readerOwner.close();
}
const transaction = join(memoryDirectory(root), TRANSACTION_DIRECTORY);
await mkdir(transaction, { mode: 0o700 });
await writeFile(join(transaction, 'MEMORY.md.next'), current, { mode: 0o600 });
await writeFile(
join(transaction, 'decision.json'),
`${JSON.stringify({
schemaVersion: 1,
basis: transactionBundleDecision(basis),
target: {
revision: decisionBundleRevision('safe_mode', current.byteLength, currentRevision),
memory: {
kind: 'safe_mode',
byteLength: current.byteLength,
revision: currentRevision,
reason: 'invalid_utf8',
},
pending: {
kind: 'missing',
byteLength: 0,
revision: null,
reason: null,
},
},
})}\n`,
{ mode: 0o600 },
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
await assert.rejects(
openInteractiveMemoryBundleStoreForWrite(owner.lease),
(error: unknown) =>
error instanceof MemoryBundleStoreError && error.code === 'invalid_document',
);
assert.deepEqual(await readFile(memoryPath(root)), current);
assert.equal((await lstat(transaction)).isDirectory(), true);
} finally {
await owner.close();
}
});
});
test('discards an undecided transaction without touching user documents', async () => {
await withInteractiveOwner(async ({ root, owner }) => {
await mkdir(memoryDirectory(root), { mode: 0o700 });
const current = Buffer.from('# Current\n');
await writeFile(memoryPath(root), current);
const transaction = join(memoryDirectory(root), TRANSACTION_DIRECTORY);
await mkdir(transaction, { mode: 0o700 });
await writeFile(join(transaction, 'MEMORY.md.next'), '# Uncommitted\n');
const store = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
assert.deepEqual(await readFile(memoryPath(root)), current);
await assert.rejects(lstat(transaction), { code: 'ENOENT' });
assert.equal((await store.read()).memory.kind, 'document');
});
});
test('read-only inspection fails closed until a writer recovers a transaction', async () => {
await withInteractiveRoot(async ({ root, capability }) => {
await mkdir(memoryDirectory(root), { mode: 0o700 });
const current = Buffer.from('# Current\n');
await writeFile(memoryPath(root), current);
const transaction = join(memoryDirectory(root), TRANSACTION_DIRECTORY);
await mkdir(transaction, { mode: 0o700 });
await writeFile(join(transaction, 'MEMORY.md.next'), '# Uncommitted\n');
const readerOwner = await tryAcquireInteractiveRootReader(capability);
assert.ok(readerOwner);
if (!readerOwner) return;
try {
const reader = await openInteractiveMemoryBundleStoreForRead(readerOwner.lease);
await assert.rejects(
reader.read(),
(error: unknown) => error instanceof MemoryBundleStoreError && error.code === 'io_failed',
);
} finally {
await readerOwner.close();
}
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
const store = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
assert.equal((await store.read()).memory.kind, 'document');
assert.deepEqual(await readFile(memoryPath(root)), current);
await assert.rejects(lstat(transaction), { code: 'ENOENT' });
} finally {
await owner.close();
}
});
});
test('rejects a symbolic-link Memory parent without reading or writing outside the root', async () => {
await withInteractiveOwner(async ({ root, owner }) => {
const outside = await mkdtemp(join(tmpdir(), 'maka-memory-outside-'));
try {
const outsideMemory = join(outside, 'MEMORY.md');
await writeFile(outsideMemory, '# Outside\n');
await symlink(
outside,
memoryDirectory(root),
process.platform === 'win32' ? 'junction' : 'dir',
);
await assert.rejects(
openInteractiveMemoryBundleStoreForWrite(owner.lease),
(error: unknown) =>
error instanceof MemoryBundleStoreError && error.code === 'invalid_document',
);
assert.equal(await readFile(outsideMemory, 'utf8'), '# Outside\n');
} finally {
await rm(outside, { recursive: true, force: true });
}
});
});
test('root owner close drains mutations admitted before close', async () => {
await withInteractiveRoot(async ({ capability }) => {
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
const store = await openInteractiveMemoryBundleStoreForWrite(owner.lease);
const initial = await store.read();
const commit = store.commit({
expectedRevision: initial.revision,
memory: Buffer.alloc(128 * 1024, 0x61),
pending: null,
});
const close = owner.close();
const committed = await commit;
assert.equal(committed.changed, true);
await close;
await assert.rejects(store.read(), { code: 'invalid_lease' });
});
});
});
async function withInteractiveOwner(
run: (input: { root: string; owner: InteractiveRootOwner }) => Promise<void>,
): Promise<void> {
await withInteractiveRoot(async ({ root, capability }) => {
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
await run({ root, owner });
} finally {
if (!owner.closed) await owner.close();
}
});
}
async function withInteractiveRoot(
run: (input: { root: string; capability: StorageRootCapability<'interactive'> }) => Promise<void>,
): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-memory-bundle-store-'));
try {
const capability = await resolveStorageRoot({ path: root, kind: 'interactive' });
try {
await run({ root, capability });
} finally {
await removeControlDirectory(capability.rootId);
}
} finally {
await rm(root, { recursive: true, force: true });
}
}
function memoryDirectory(root: string): string {
return join(root, MEMORY_DIRECTORY);
}
function memoryPath(root: string): string {
return join(memoryDirectory(root), 'MEMORY.md');
}
function pendingPath(root: string): string {
return join(memoryDirectory(root), 'PENDING.md');
}
function revision(bytes: Uint8Array): MemoryRevision {
return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
}
function decisionBundleRevision(
memoryKind: 'document' | 'safe_mode',
memoryByteLength: number,
memoryRevision: MemoryRevision,
): MemoryRevision {
const hash = createHash('sha256');
hash.update('maka-memory-bundle-v1\0');
hash.update(`memory\0${memoryKind}\0${memoryByteLength}\0`);
hash.update(memoryRevision);
hash.update('\0');
hash.update('pending\0missing\0');
hash.update('0');
hash.update('\0missing\0');
return `sha256:${hash.digest('hex')}`;
}
function transactionBundleDecision(snapshot: MemoryBundleSnapshot) {
return {
revision: snapshot.revision,
memory: transactionDocumentDecision(snapshot.memory),
pending: transactionDocumentDecision(snapshot.pending),
};
}
function transactionDocumentDecision(snapshot: MemoryDocumentSnapshot) {
return {
kind: snapshot.kind,
byteLength: snapshot.byteLength,
revision: snapshot.revision,
reason: snapshot.kind === 'safe_mode' ? snapshot.reason : null,
};
}
@@ -0,0 +1,500 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { DatabaseSync } from 'node:sqlite';
import { describe, test } from 'node:test';
import type { AgentRunHeader } from '@maka/core/agent-run';
import {
MODEL_CALL_ATTEMPT_EVENT_TYPE,
MODEL_CALL_ATTEMPT_SCHEMA_VERSION,
type ModelCallAttempt,
} from '@maka/core/model-call-attempt';
import {
createSqliteModelCallLedger,
ModelCallLedgerClosedError,
ModelCallLedgerPublicationError,
type ModelCallLedger,
} from '../model-call-ledger.js';
import { acquireOperationalStateDatabase } from '../operational-state-store.js';
import { createSqliteAgentRunStore } from '../agent-run-store.js';
const NOW = 1_750_000_000_000;
function attempt(overrides: Partial<ModelCallAttempt> = {}): ModelCallAttempt {
return {
schemaVersion: MODEL_CALL_ATTEMPT_SCHEMA_VERSION,
logicalCallId: 'call-1',
attemptId: 'attempt-1',
traceId: 'trace-1',
sessionId: 'session-1',
runId: 'run-1',
turnId: 'turn-1',
step: 0,
attempt: 0,
callKind: 'main',
providerId: 'anthropic',
modelId: 'claude-opus-5',
startedAt: NOW - 1_000,
completedAt: NOW - 500,
latencyMs: 500,
status: 'completed',
usageBasis: 'reported',
inputTokens: 100,
outputTokens: 20,
costBasis: 'priced',
costUsd: 0.004,
...overrides,
};
}
async function withLedger(run: (ledger: ModelCallLedger, root: string) => Promise<void>) {
const root = await mkdtemp(join(tmpdir(), 'maka-model-call-ledger-'));
const ledger = createSqliteModelCallLedger(root);
try {
await run(ledger, root);
} finally {
await ledger.close().catch(() => undefined);
await rm(root, { recursive: true, force: true });
}
}
function appendAuthorityEvent(
root: string,
sequence: number,
value: ModelCallAttempt | { readonly schemaVersion: number },
sessionId = 'session-1',
runId = 'run-1',
): void {
const lease = acquireOperationalStateDatabase(root);
try {
lease.transaction('write', () => {
lease.database
.prepare(`
INSERT OR IGNORE INTO core_agent_runs(session_id, run_id, created_at, record_json)
VALUES (?, ?, ?, '{}')
`)
.run(sessionId, runId, NOW - 1_000);
lease.database
.prepare(`
INSERT INTO core_agent_run_events(
session_id, run_id, sequence, event_id, event_type, event_ts, record_json
) VALUES (?, ?, ?, ?, ?, ?, ?)
`)
.run(
sessionId,
runId,
sequence,
`event-${sessionId}-${runId}-${sequence}`,
MODEL_CALL_ATTEMPT_EVENT_TYPE,
NOW - 500 + sequence,
JSON.stringify({
id: `event-${sessionId}-${runId}-${sequence}`,
type: MODEL_CALL_ATTEMPT_EVENT_TYPE,
ts: NOW - 500 + sequence,
sessionId,
runId,
turnId: 'turn-1',
data: value,
}),
);
lease.database
.prepare(`
UPDATE core_agent_runs
SET latest_model_call_sequence = ?
WHERE session_id = ? AND run_id = ?
`)
.run(sequence, sessionId, runId);
});
} finally {
lease.close();
}
}
describe('canonical model call ledger', () => {
test('reads back what it recorded, bounded to the queried window', async () => {
await withLedger(async (ledger, root) => {
appendAuthorityEvent(root, 0, attempt({ attemptId: 'inside', completedAt: NOW - 500 }));
appendAuthorityEvent(
root,
1,
attempt({ attemptId: 'before', startedAt: NOW - 10_500, completedAt: NOW - 10_000 }),
);
await ledger.catchUpProjection();
const page = ledger.read({ from: NOW - 1_000, to: NOW });
assert.deepEqual(
page.attempts.map((row) => row.attemptId),
['inside'],
);
assert.equal(page.unreadableRecords, 0);
});
});
test('provider failure diagnostics survive closing and reopening the ledger', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-model-call-ledger-reopen-'));
const first = createSqliteModelCallLedger(root);
try {
appendAuthorityEvent(
root,
0,
attempt({
callKind: 'history_compact',
historyCompactRoute: 'provider_native',
providerId: 'openai-codex',
status: 'failed',
usageBasis: 'missing',
inputTokens: undefined,
outputTokens: undefined,
costBasis: 'unpriced',
costUsd: undefined,
errorClass: 'RequestRejected',
httpStatus: 400,
providerCode: 'invalid_request_error',
providerRequestId: 'req-reopen-1',
retryable: false,
}),
);
await first.catchUpProjection();
await first.close();
const reopened = createSqliteModelCallLedger(root);
try {
const restored = reopened.read({ from: 0, to: NOW }).attempts[0];
assert.equal(restored?.historyCompactRoute, 'provider_native');
assert.equal(restored?.errorClass, 'RequestRejected');
assert.equal(restored?.httpStatus, 400);
assert.equal(restored?.providerCode, 'invalid_request_error');
assert.equal(restored?.providerRequestId, 'req-reopen-1');
assert.equal(restored?.retryable, false);
} finally {
await reopened.close();
}
} finally {
await first.close().catch(() => undefined);
await rm(root, { recursive: true, force: true });
}
});
test('migration deletes legacy repair intent without losing discoverable authority', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-model-call-ledger-migrate-'));
const first = createSqliteModelCallLedger(root);
appendAuthorityEvent(root, 0, attempt({ attemptId: 'pre-checkpoint' }));
await first.close();
const database = new DatabaseSync(join(root, 'runtime.sqlite'));
database.exec(`
DROP TABLE usage_model_call_projection_checkpoints;
CREATE TABLE usage_model_call_reprojection (
session_id TEXT NOT NULL,
run_id TEXT NOT NULL,
marked_at INTEGER NOT NULL,
PRIMARY KEY (session_id, run_id)
);
INSERT INTO usage_model_call_reprojection VALUES ('session-1', 'run-1', 1);
UPDATE operational_schema_migrations SET version = 4 WHERE scope = 'usage';
`);
database.close();
const migrated = createSqliteModelCallLedger(root);
try {
await migrated.catchUpProjection();
assert.deepEqual(
migrated.read({ from: 0, to: NOW }).attempts.map((row) => row.attemptId),
['pre-checkpoint'],
);
const lease = acquireOperationalStateDatabase(root);
try {
assert.equal(
lease.database
.prepare(
"SELECT COUNT(*) AS count FROM sqlite_schema WHERE name = 'usage_model_call_reprojection'",
)
.get()?.count,
0,
);
} finally {
lease.close();
}
} finally {
await migrated.close();
await rm(root, { recursive: true, force: true });
}
});
test('a late settlement replaces the provisional record under the same attempt id', async () => {
// The abort path records provisionally without usage; a `finish` arriving
// afterwards settles the same attempt. Two rows would double-count it.
await withLedger(async (ledger, root) => {
appendAuthorityEvent(
root,
0,
attempt({
status: 'aborted',
usageBasis: 'missing',
inputTokens: undefined,
outputTokens: undefined,
}),
);
appendAuthorityEvent(root, 1, attempt({ status: 'completed', usageBasis: 'reported' }));
await ledger.catchUpProjection();
const page = ledger.read({ from: 0, to: NOW });
assert.equal(page.attempts.length, 1);
assert.equal(page.attempts[0]?.status, 'completed');
assert.equal(page.attempts[0]?.inputTokens, 100);
});
});
test('reports an authority record that does not satisfy the canonical schema', async () => {
await withLedger(async (ledger, root) => {
appendAuthorityEvent(root, 0, attempt({ costBasis: 'unpriced', costUsd: 0.004 }));
const result = await ledger.catchUpProjection();
assert.equal(result.unreadableEvents, 1);
assert.equal(ledger.read({ from: 0, to: NOW }).attempts.length, 0);
});
});
test('one unreadable row is reported rather than failing the whole query', async () => {
await withLedger(async (ledger, root) => {
appendAuthorityEvent(root, 0, attempt({ attemptId: 'good' }));
await ledger.catchUpProjection();
const lease = acquireOperationalStateDatabase(root);
try {
lease.transaction('write', () => {
lease.database
.prepare(
'INSERT INTO usage_model_call_attempts(attempt_id, completed_at, record_json) VALUES (?, ?, ?)',
)
.run('corrupt', NOW - 400, '{"schemaVersion":1,');
});
} finally {
lease.close();
}
const page = ledger.read({ from: 0, to: NOW });
assert.deepEqual(
page.attempts.map((row) => row.attemptId),
['good'],
);
assert.equal(page.unreadableRecords, 1);
});
});
test('a Session-scoped read excludes another Session records and corruption', async () => {
await withLedger(async (ledger, root) => {
appendAuthorityEvent(
root,
0,
attempt({ attemptId: 'session-a-call', sessionId: 'session-a', runId: 'run-a' }),
'session-a',
'run-a',
);
appendAuthorityEvent(
root,
0,
attempt({ attemptId: 'session-b-call', sessionId: 'session-b', runId: 'run-b' }),
'session-b',
'run-b',
);
await ledger.catchUpProjection();
const lease = acquireOperationalStateDatabase(root);
try {
lease.transaction('write', () => {
lease.database
.prepare(
`INSERT INTO usage_model_call_attempts(
attempt_id, completed_at, record_json, session_id
) VALUES (?, ?, ?, ?)`,
)
.run('session-b-corrupt', NOW - 400, '{', 'session-b');
});
} finally {
lease.close();
}
const page = ledger.read({ from: 0, to: NOW }, 'session-a');
assert.deepEqual(
page.attempts.map((row) => row.attemptId),
['session-a-call'],
);
assert.equal(page.unreadableRecords, 0);
});
});
test('reads and catch-up after close report the lifecycle rather than corrupting state', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-model-call-ledger-'));
const ledger = createSqliteModelCallLedger(root);
appendAuthorityEvent(root, 0, attempt());
await ledger.close();
await assert.rejects(() => ledger.catchUpProjection(), ModelCallLedgerClosedError);
assert.throws(() => ledger.read({ from: 0, to: NOW }), ModelCallLedgerClosedError);
await rm(root, { recursive: true, force: true });
});
});
describe('catching the read model up from the AgentRun authority', () => {
test('consumes the high-water published by the real AgentRun append path', async () => {
await withLedger(async (ledger, root) => {
const runStore = createSqliteAgentRunStore(root);
const header: AgentRunHeader = {
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
status: 'created',
backendKind: 'fake',
llmConnectionSlug: 'fake',
modelId: 'fake-model',
cwd: '/tmp/cwd',
permissionMode: 'ask',
createdAt: 1,
updatedAt: 1,
};
await runStore.createRun(header);
await runStore.appendEvent('session-1', 'run-1', {
id: 'attempt-real-append',
type: MODEL_CALL_ATTEMPT_EVENT_TYPE,
ts: NOW,
sessionId: 'session-1',
runId: 'run-1',
turnId: 'turn-1',
data: { ...attempt({ attemptId: 'real-append' }) },
});
runStore.close?.();
await ledger.catchUpProjection({ sessionId: 'session-1' });
assert.deepEqual(
ledger.read({ from: 0, to: NOW }).attempts.map((row) => row.attemptId),
['real-append'],
);
});
});
test('recovers an authority append even when no repair marker was written', async () => {
await withLedger(async (ledger, root) => {
appendAuthorityEvent(root, 0, attempt({ attemptId: 'missed' }));
const result = await ledger.catchUpProjection({ sessionId: 'session-1' });
assert.deepEqual(result, {
changedSessionIds: ['session-1'],
pendingRuns: 0,
unreadableEvents: 0,
});
assert.deepEqual(
ledger.read({ from: 0, to: NOW }).attempts.map((row) => row.attemptId),
['missed'],
);
});
});
test('a later authority append remains discoverable after an earlier catch-up', async () => {
await withLedger(async (ledger, root) => {
appendAuthorityEvent(root, 0, attempt({ attemptId: 'old' }));
await ledger.catchUpProjection({ sessionId: 'session-1', runId: 'run-1' });
appendAuthorityEvent(root, 1, attempt({ attemptId: 'new' }));
const result = await ledger.catchUpProjection({ sessionId: 'session-1' });
assert.equal(result.pendingRuns, 0);
assert.deepEqual(
ledger
.read({ from: 0, to: NOW })
.attempts.map((row) => row.attemptId)
.sort(),
['new', 'old'],
);
});
});
test('persists corrupt authority evidence without pinning later events', async () => {
await withLedger(async (ledger, root) => {
appendAuthorityEvent(root, 0, { schemaVersion: 1 });
appendAuthorityEvent(root, 1, attempt({ attemptId: 'good' }));
const first = await ledger.catchUpProjection({ sessionId: 'session-1' });
const second = await ledger.catchUpProjection({ sessionId: 'session-1' });
assert.equal(first.unreadableEvents, 1);
assert.equal(first.pendingRuns, 0);
assert.equal(second.unreadableEvents, 1);
assert.deepEqual(second.changedSessionIds, []);
assert.deepEqual(
ledger.read({ from: 0, to: NOW }).attempts.map((row) => row.attemptId),
['good'],
);
});
});
test('reports a run as pending until a bounded catch-up reaches its high-water mark', async () => {
await withLedger(async (ledger, root) => {
appendAuthorityEvent(root, 0, attempt({ attemptId: 'first' }));
appendAuthorityEvent(root, 1, attempt({ attemptId: 'second' }));
const first = await ledger.catchUpProjection({
sessionId: 'session-1',
eventsPerRun: 1,
});
const second = await ledger.catchUpProjection({
sessionId: 'session-1',
eventsPerRun: 1,
});
assert.equal(first.pendingRuns, 1);
assert.equal(second.pendingRuns, 0);
assert.equal(ledger.read({ from: 0, to: NOW }).attempts.length, 2);
});
});
test('does not advance the checkpoint when projection storage fails', async () => {
await withLedger(async (ledger, root) => {
appendAuthorityEvent(root, 0, attempt({ attemptId: 'retry-after-storage-failure' }));
const lease = acquireOperationalStateDatabase(root);
try {
lease.transaction('write', () => {
lease.database.exec(`
CREATE TRIGGER reject_model_call_projection
BEFORE INSERT ON usage_model_call_attempts
BEGIN
SELECT RAISE(ABORT, 'projection unavailable');
END;
`);
});
await assert.rejects(() => ledger.catchUpProjection(), ModelCallLedgerPublicationError);
lease.transaction('write', () => {
lease.database.exec('DROP TRIGGER reject_model_call_projection');
});
} finally {
lease.close();
}
const recovered = await ledger.catchUpProjection();
assert.equal(recovered.pendingRuns, 0);
assert.deepEqual(
ledger.read({ from: 0, to: NOW }).attempts.map((row) => row.attemptId),
['retry-after-storage-failure'],
);
});
});
});
@@ -0,0 +1,78 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, readdir, readFile, writeFile, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import test from 'node:test';
import { ModelFactsDocumentOwner } from '../model-facts-store.js';
import { cleanupRuntimePolicyDocumentTemps } from '../runtime-policy/document-io.js';
test('model facts persist and malformed documents fail closed with a bounded diagnostic', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-model-facts-'));
try {
const owner = new ModelFactsDocumentOwner();
assert.deepEqual((await owner.readWithDiagnostics(root)).document.overrides, {});
await writeFile(join(root, 'model-facts.json'), '{not-json}', 'utf8');
const result = await owner.readWithDiagnostics(root);
assert.equal(result.diagnostic, 'malformed');
assert.deepEqual(result.document.overrides, {});
await writeFile(
join(root, 'model-facts.json'),
JSON.stringify({ schemaVersion: 1, overrides: { 'openai:o4-mini': { unknown: true } } }),
'utf8',
);
assert.equal((await owner.readWithDiagnostics(root)).diagnostic, 'malformed');
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('model facts temporary writes are removed by runtime policy recovery', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-model-facts-recovery-'));
try {
await writeFile(
join(root, 'model-facts.json.00000000-0000-4000-8000-000000000000.tmp'),
'{}',
'utf8',
);
await cleanupRuntimePolicyDocumentTemps(root);
assert.deepEqual(await readdir(root), []);
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('future model facts schemas fail closed without rewriting the document', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-model-facts-future-'));
try {
const owner = new ModelFactsDocumentOwner();
const future = JSON.stringify({
schemaVersion: 2,
overrides: { 'openai:o4-mini': { contextWindow: 1 } },
});
await writeFile(join(root, 'model-facts.json'), future, 'utf8');
const read = await owner.readWithDiagnostics(root);
assert.equal(read.diagnostic, 'unsupported_schema');
assert.equal(await readFile(join(root, 'model-facts.json'), 'utf8'), future);
} finally {
await rm(root, { recursive: true, force: true });
}
});
@@ -0,0 +1,83 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, test } from 'node:test';
import {
readConnectionOnboardingIntent,
writeConnectionOnboardingIntent,
prepareConnectionOnboardingIntent,
} from '../runtime-policy/onboarding-transaction.js';
const roots: string[] = [];
async function root(): Promise<string> {
const directory = await mkdtemp(join(tmpdir(), 'maka-onboarding-intent-'));
roots.push(directory);
return directory;
}
after(async () => {
await Promise.all(roots.map((directory) => rm(directory, { recursive: true, force: true })));
});
const BASE = {
connectionId: '00000000-0000-4000-8000-000000000001',
slug: 'openai-compatible-2',
providerType: 'openai-compatible',
suppliedSecret: 'relay-secret',
enabledModelIds: ['relay/model'],
discovery: { models: [{ id: 'relay/model' }], source: 'fetched', fetchedAt: 123 },
invalidateLastTest: false,
};
test('an onboarding intent round-trips its endpoint override through the journal', async () => {
const directory = await root();
const intent = prepareConnectionOnboardingIntent({
...BASE,
baseUrl: 'https://relay.example.test/v1',
});
await writeConnectionOnboardingIntent(directory, intent);
assert.deepEqual(await readConnectionOnboardingIntent(directory), intent);
const persisted = JSON.parse(
await readFile(join(directory, 'runtime-policy-onboarding.json'), 'utf8'),
) as { schemaVersion: number; slug: string };
assert.deepEqual(persisted, { ...intent });
assert.equal(persisted.schemaVersion, 2);
assert.equal(persisted.slug, 'openai-compatible-2');
});
test('a journal written before the baseUrl field replays as no override', async () => {
const directory = await root();
// The exact persisted shape an older build leaves behind on crash: no
// `baseUrl` key at all. Recovery must replay it, not reject the document.
const { slug: _slug, ...legacyBase } = BASE;
await writeFile(
join(directory, 'runtime-policy-onboarding.json'),
JSON.stringify({ schemaVersion: 1, ...legacyBase }),
);
const replayed = await readConnectionOnboardingIntent(directory);
assert.equal(replayed?.schemaVersion, 1);
assert.equal(replayed?.slug, null);
assert.equal(replayed?.baseUrl, null);
assert.deepEqual(replayed?.enabledModelIds, ['relay/model']);
});
@@ -0,0 +1,525 @@
/*
* 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 assert from 'node:assert/strict';
import { DatabaseSync } from 'node:sqlite';
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { fileURLToPath } from 'node:url';
import { decodeCanonicalMessage } from '@maka/core/session';
import { createExternalSessionAdapterRegistry } from '../external-session-adapters.js';
import {
OPENCODE_SESSION_ADAPTER_ID,
OpenCodeSessionAdapter,
} from '../opencode-session-adapter.js';
// Captured from opencode 1.18.21 with `opencode db`: one session that reads
// files, runs commands, writes one, and ends on an aborted message. Paths are
// rewritten and long tool output truncated; the record shapes are verbatim.
// Resolved against `src` rather than the compiled location: the fixture is
// data, so it is not emitted into `dist` beside the test that reads it.
const FIXTURE = fileURLToPath(
new URL('../../src/__tests__/fixtures/opencode-session-1.18.21.json', import.meta.url),
);
interface Fixture {
session: {
id: string;
title: string;
directory: string;
time_created: number;
time_updated: number;
time_archived: number | null;
parent_id: string | null;
};
messages: { id: string; time_created: number; data: unknown }[];
parts: { id: string; message_id: string; time_created: number; data: unknown }[];
}
describe('OpenCodeSessionAdapter', () => {
test('reports absent when no database exists', async () => {
await withOpenCodeHome(async (home) => {
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
assert.equal(await adapter.detect(), false);
assert.deepEqual(await adapter.listSessions(), []);
});
});
test('an unreadable database is reported, not answered as an empty catalog', async () => {
await withOpenCodeHome(async (home) => {
await writeFile(join(home, 'opencode.db'), 'not a database');
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
// The file is there, so the source is present; what fails is reading it.
assert.equal(await adapter.detect(), true);
await assert.rejects(adapter.listSessions(), /could not be (opened|read)/u);
// Reporting "not found" here would send a user looking for a session
// that exists in a database this could not open.
await assert.rejects(adapter.readSession('ses_anything'), /could not be (opened|read)/u);
});
});
test('a session whose transcript tables are missing fails instead of importing empty', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home, undefined, { omitPartTable: true });
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
// The session row still reads, so the catalog offers it...
assert.equal((await adapter.listSessions()).length, 1);
// ...and the import must not answer with a conversation of nothing. A
// future opencode that renames these tables would otherwise silently
// import every session as empty and report success.
await assert.rejects(adapter.readSession(fixture.session.id), /could not be read/u);
});
});
test('a user message with no prompt does not produce a turn holding no messages', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home, (f) => {
// One user message, no parts at all.
f.messages = [{ id: 'msg_empty', time_created: 1, data: { role: 'user' } }];
f.parts = [];
return f;
});
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
assert.deepEqual(
session.messages,
[],
'no turn_state is emitted for a turn that holds nothing',
);
});
});
test('lists a captured session with its directory and title', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home);
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
assert.equal(await adapter.detect(), true);
const sessions = await adapter.listSessions();
assert.equal(sessions.length, 1);
assert.equal(sessions[0]?.id, fixture.session.id);
assert.equal(sessions[0]?.cwd, fixture.session.directory);
assert.equal(sessions[0]?.name, fixture.session.title);
assert.equal(sessions[0]?.createdAt, fixture.session.time_created);
});
});
test('a cwd query selects by the session directory', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home);
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
assert.equal((await adapter.listSessions({ cwd: fixture.session.directory })).length, 1);
assert.equal((await adapter.listSessions({ cwd: '/somewhere/else' })).length, 0);
});
});
test('child sessions are neither listed nor readable as conversations', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home, (f) => {
f.session.parent_id = 'ses_parent';
return f;
});
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
assert.deepEqual(await adapter.listSessions(), []);
await assert.rejects(adapter.readSession(fixture.session.id), /child of another session/u);
});
});
test('converts the captured session into canonical Maka messages', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home);
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
assert.equal(session.sourceSessionId, fixture.session.id);
assert.equal(session.metadata.cwd, fixture.session.directory);
// Every emitted message has to survive Maka's own decoder, or the
// import would be rejected at the persistence boundary rather than here.
for (const message of session.messages) {
assert.ok(decodeCanonicalMessage(message), `undecodable: ${message.type}`);
}
const kinds = new Set(session.messages.map((message) => message.type));
assert.ok(kinds.has('user'));
assert.ok(kinds.has('assistant'));
assert.ok(kinds.has('tool_call'));
assert.ok(kinds.has('tool_result'));
assert.ok(kinds.has('turn_state'));
});
});
test('pairs every tool result with the call it answers', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home);
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
const callIds = new Set(
session.messages.filter((m) => m.type === 'tool_call').map((m) => m.id),
);
const results = session.messages.filter((m) => m.type === 'tool_result');
assert.ok(results.length > 0, 'the capture contains completed tool calls');
for (const result of results) {
assert.ok(
callIds.has((result as { toolUseId: string }).toolUseId),
'every result names a call that was emitted',
);
}
});
});
test('reasoning is carried as thinking rather than as reply text', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home);
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
const thinking = session.messages.filter(
(m) => m.type === 'assistant' && (m as { thinking?: unknown }).thinking !== undefined,
);
assert.ok(thinking.length > 0, 'the capture contains reasoning parts');
for (const message of thinking) {
assert.equal((message as { text: string }).text, '');
}
});
});
test('an aborted final message closes its turn as aborted, not completed', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home);
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
const states = session.messages.filter((m) => m.type === 'turn_state') as {
status: string;
}[];
assert.ok(states.length > 0);
// The capture ends on a message carrying MessageAbortedError.
assert.equal(states.at(-1)?.status, 'aborted');
// Earlier turns finished on `finish: "stop"` and must not be dragged
// into the last one's verdict.
assert.ok(
states.slice(0, -1).some((state) => state.status === 'completed'),
'completed turns are recorded as completed',
);
});
});
test('a turn left waiting on a tool call is aborted rather than completed', async () => {
await withOpenCodeHome(async (home) => {
// Drop everything after the first tool-calls message, which is what a
// run killed between a call and its answer leaves behind.
const fixture = await seed(home, (f) => {
const cut = f.messages.findIndex(
(m) => (m.data as { finish?: string }).finish === 'tool-calls',
);
assert.ok(cut > 0, 'the capture has a tool-calls message');
const kept = f.messages.slice(0, cut + 1);
const keptIds = new Set(kept.map((m) => m.id));
f.messages = kept;
f.parts = f.parts.filter((p) => keptIds.has(p.message_id));
return f;
});
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
const states = session.messages.filter((m) => m.type === 'turn_state') as {
status: string;
}[];
assert.equal(states.at(-1)?.status, 'aborted');
});
});
test('an in-flight tool call is imported without a synthesised result', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home, (f) => {
for (const part of f.parts) {
const data = part.data as { type?: string; state?: { status?: string } };
if (data.type === 'tool' && data.state) data.state.status = 'running';
}
return f;
});
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
assert.ok(session.messages.some((m) => m.type === 'tool_call'));
assert.equal(
session.messages.filter((m) => m.type === 'tool_result').length,
0,
'no result is invented for a call that never answered',
);
});
});
test('a terminal tool failure is imported as an errored result, not a dangling call', async () => {
await withOpenCodeHome(async (home) => {
// The reviewer's reproduction: a failed call inside a step that a later
// `finish: "stop"` closes. Without a result the transcript asserts the
// tool never replied, inside a turn recorded as completed.
const fixture = await seed(home, (f) => {
f.messages = [
{ id: 'm_user', time_created: 1, data: { role: 'user' } },
{
id: 'm_call',
time_created: 2,
data: { role: 'assistant', finish: 'tool-calls', modelID: 'm' },
},
{
id: 'm_stop',
time_created: 3,
data: { role: 'assistant', finish: 'stop', modelID: 'm' },
},
];
f.parts = [
{
id: 'p_prompt',
message_id: 'm_user',
time_created: 1,
data: { type: 'text', text: 'go' },
},
{
id: 'p_tool',
message_id: 'm_call',
time_created: 2,
data: {
type: 'tool',
tool: 'bash',
callID: 'call_failed',
state: { status: 'error', input: { command: 'false' }, error: 'exit 1' },
},
},
{
id: 'p_text',
message_id: 'm_stop',
time_created: 3,
data: { type: 'text', text: 'done' },
},
];
return f;
});
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
const result = session.messages.find((m) => m.type === 'tool_result') as
| { toolUseId: string; isError: boolean; content: { text: string } }
| undefined;
assert.ok(result, 'a failed call still answered, and the answer is a failure');
assert.equal(result?.toolUseId, 'call_failed');
assert.equal(result?.isError, true);
assert.equal(result?.content.text, 'exit 1');
});
});
test('a call still running when the session was written gets no result', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home, (f) => {
f.messages = [
{ id: 'm_user', time_created: 1, data: { role: 'user' } },
{
id: 'm_call',
time_created: 2,
data: { role: 'assistant', finish: 'tool-calls', modelID: 'm' },
},
];
f.parts = [
{
id: 'p_prompt',
message_id: 'm_user',
time_created: 1,
data: { type: 'text', text: 'go' },
},
{
id: 'p_tool',
message_id: 'm_call',
time_created: 2,
data: {
type: 'tool',
tool: 'bash',
callID: 'call_running',
state: { status: 'running', input: {} },
},
},
];
return f;
});
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
assert.ok(session.messages.some((m) => m.type === 'tool_call'));
assert.equal(session.messages.filter((m) => m.type === 'tool_result').length, 0);
});
});
test('parts keep the order the session recorded them in', async () => {
await withOpenCodeHome(async (home) => {
// opencode accepts text -> reasoning -> tool and its own replay keeps
// that order. Bucketing by type would emit reasoning first.
const fixture = await seed(home, (f) => {
f.messages = [
{ id: 'm_user', time_created: 1, data: { role: 'user' } },
{
id: 'm_reply',
time_created: 2,
data: { role: 'assistant', finish: 'stop', modelID: 'm' },
},
];
f.parts = [
{
id: 'p_prompt',
message_id: 'm_user',
time_created: 1,
data: { type: 'text', text: 'go' },
},
{
id: 'p1',
message_id: 'm_reply',
time_created: 2,
data: { type: 'text', text: 'first' },
},
{
id: 'p2',
message_id: 'm_reply',
time_created: 3,
data: { type: 'reasoning', text: 'second' },
},
{
id: 'p3',
message_id: 'm_reply',
time_created: 4,
data: {
type: 'tool',
tool: 'bash',
callID: 'call_third',
state: { status: 'completed', input: {}, output: 'ok' },
},
},
];
return f;
});
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
const session = await adapter.readSession(fixture.session.id);
const reply = session.messages.filter((m) => m.type !== 'user');
assert.deepEqual(
reply.slice(0, 4).map((m) => {
if (m.type !== 'assistant') return m.type;
return (m as { thinking?: unknown }).thinking !== undefined ? 'thinking' : 'text';
}),
['text', 'thinking', 'tool_call', 'tool_result'],
);
});
});
test('an undecodable transcript row fails the import rather than truncating it', async () => {
await withOpenCodeHome(async (home) => {
const fixture = await seed(home, (f) => {
f.messages = [{ id: 'm_user', time_created: 1, data: { role: 'user' } }];
f.parts = [];
return f;
});
// Replace the message payload with something that is not JSON.
const db = new DatabaseSync(join(home, 'opencode.db'));
try {
db.prepare('UPDATE message SET data = ? WHERE id = ?').run('{not json', 'm_user');
} finally {
db.close();
}
const adapter = new OpenCodeSessionAdapter({ opencodeHome: home });
await assert.rejects(adapter.readSession(fixture.session.id), /could not be read/u);
});
});
test('the registry exposes the adapter under its own id', async () => {
const registry = createExternalSessionAdapterRegistry();
const adapter = registry.get(OPENCODE_SESSION_ADAPTER_ID);
assert.ok(adapter);
assert.equal(adapter?.id, OPENCODE_SESSION_ADAPTER_ID);
});
});
async function withOpenCodeHome(run: (home: string) => Promise<void>): Promise<void> {
const home = await mkdtemp(join(tmpdir(), 'maka-opencode-adapter-'));
try {
await run(home);
} finally {
await rm(home, { recursive: true, force: true });
}
}
async function seed(
home: string,
mutate?: (fixture: Fixture) => Fixture,
options: { omitPartTable?: boolean } = {},
): Promise<Fixture> {
const raw = JSON.parse(await readFile(FIXTURE, 'utf8')) as Fixture;
const fixture = mutate ? mutate(raw) : raw;
const db = new DatabaseSync(join(home, 'opencode.db'));
try {
db.exec(`
CREATE TABLE session (
id text PRIMARY KEY, project_id text, workspace_id text, parent_id text,
slug text, directory text NOT NULL, path text, title text,
version text, time_created integer, time_updated integer,
time_compacting integer, time_archived integer
);
CREATE TABLE message (
id text PRIMARY KEY, session_id text NOT NULL,
time_created integer NOT NULL, time_updated integer, data text NOT NULL
);
`);
if (!options.omitPartTable) {
db.exec(`
CREATE TABLE part (
id text PRIMARY KEY, message_id text NOT NULL, session_id text NOT NULL,
time_created integer NOT NULL, time_updated integer, data text NOT NULL
);
`);
}
db.prepare(
'INSERT INTO session (id, parent_id, directory, title, time_created, time_updated, time_archived) VALUES (?, ?, ?, ?, ?, ?, ?)',
).run(
fixture.session.id,
fixture.session.parent_id,
fixture.session.directory,
fixture.session.title,
fixture.session.time_created,
fixture.session.time_updated,
fixture.session.time_archived,
);
const message = db.prepare(
'INSERT INTO message (id, session_id, time_created, data) VALUES (?, ?, ?, ?)',
);
for (const row of fixture.messages) {
message.run(row.id, fixture.session.id, row.time_created, JSON.stringify(row.data));
}
if (options.omitPartTable) return fixture;
const part = db.prepare(
'INSERT INTO part (id, message_id, session_id, time_created, data) VALUES (?, ?, ?, ?, ?)',
);
for (const row of fixture.parts) {
part.run(
row.id,
row.message_id,
fixture.session.id,
row.time_created,
JSON.stringify(row.data),
);
}
} finally {
db.close();
}
return fixture;
}
@@ -0,0 +1,184 @@
/*
* 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 assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { DatabaseSync } from 'node:sqlite';
import { test } from 'node:test';
import { createSqliteArtifactStore } from '../artifact-store.js';
import { createProjectCatalog } from '../project-catalog.js';
import { createSessionStore } from '../session-store.js';
import {
createOperationalStateBackup,
OperationalBackupError,
restoreOperationalStateBackup,
validateOperationalStateBackup,
} from '../operational-state-backup.js';
test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-operational-backup-'));
const stateRoot = join(base, 'state');
const backupRoot = join(base, 'backup');
const restoreRoot = join(base, 'restore');
const projectPath = join(base, 'project');
await mkdir(projectPath);
const sessions = createSessionStore(stateRoot);
try {
// The project catalog decides how every session is grouped, and its name,
// relink aliases and archive state exist nowhere else. Restoring sessions
// without it would silently reorganize the user's whole sidebar.
const catalog = createProjectCatalog(stateRoot, { now: () => 5 });
const project = await catalog.register(projectPath);
await catalog.rename(project.id, 'Renamed Project');
await catalog.archive(project.id);
catalog.close();
const session = await sessions.create({
projectId: project.id,
cwd: '/tmp/cwd',
llmConnectionSlug: 'fake',
model: 'fake-model',
permissionMode: 'ask',
name: 'Backup',
labels: [],
});
const message = {
type: 'user',
id: 'message-1',
turnId: 'turn-1',
ts: 1,
text: 'durable'.repeat(12_000),
} as const;
await sessions.appendMessage(session.id, message);
await sessions.close?.();
const artifacts = createSqliteArtifactStore(stateRoot);
const artifact = await artifacts.create({
id: 'artifact-1',
sessionId: session.id,
turnId: 'turn-1',
name: 'note.txt',
kind: 'file',
content: 'artifact',
source: 'fixture',
now: 2,
});
artifacts.close?.();
await createOperationalStateBackup({ stateRoot, destinationRoot: backupRoot, now: () => 10 });
assert.equal((await validateOperationalStateBackup(backupRoot)).createdAt, 10);
await restoreOperationalStateBackup({ backupRoot, destinationRoot: restoreRoot });
const restored = createSessionStore(restoreRoot);
const restoredCatalog = createProjectCatalog(restoreRoot);
try {
assert.deepEqual(await restored.readMessages(session.id), [message]);
assert.equal(
await readFile(join(restoreRoot, 'artifacts', artifact.relativePath), 'utf8'),
'artifact',
);
assert.equal(
(await restored.readHeaderSnapshot(session.id)).projectId,
project.id,
'a restored session still belongs to the project it was grouped under',
);
assert.deepEqual(await restoredCatalog.list(), [
{
id: project.id,
name: 'Renamed Project',
locations: [{ path: await realpath(projectPath), isWorktree: false }],
archivedAt: 5,
available: true,
preferredPath: await realpath(projectPath),
},
]);
} finally {
await restored.close?.();
restoredCatalog.close();
}
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('rejects a backup whose SQLite Artifact metadata has no matching payload', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-operational-backup-artifact-'));
const stateRoot = join(base, 'state');
try {
const artifacts = createSqliteArtifactStore(stateRoot);
const artifact = await artifacts.create({
id: 'artifact-1',
sessionId: 'session-1',
turnId: 'turn-1',
name: 'note.txt',
kind: 'file',
content: 'artifact',
source: 'fixture',
now: 2,
});
artifacts.close?.();
await rm(join(stateRoot, 'artifacts', artifact.relativePath));
await assert.rejects(
createOperationalStateBackup({
stateRoot,
destinationRoot: join(base, 'backup'),
now: () => 10,
}),
(error: unknown) =>
error instanceof OperationalBackupError &&
error.code === 'corrupt_backup' &&
/artifact payload/i.test(error.message),
);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('rejects a backup whose native Runtime version contradicts its registry', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-operational-backup-version-'));
const stateRoot = join(base, 'state');
const backupRoot = join(base, 'backup');
try {
const sessions = createSessionStore(stateRoot);
await sessions.close?.();
await createOperationalStateBackup({ stateRoot, destinationRoot: backupRoot, now: () => 10 });
const databasePath = join(backupRoot, 'runtime.sqlite');
const database = new DatabaseSync(databasePath);
database.exec('PRAGMA user_version = 999');
database.close();
const bytes = await readFile(databasePath);
const manifestPath = join(backupRoot, 'operational-backup.json');
const manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as {
files: Array<{ path: string; size: number; sha256: string }>;
};
const entry = manifest.files.find((file) => file.path === 'runtime.sqlite');
assert.ok(entry);
entry.size = bytes.byteLength;
entry.sha256 = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
await writeFile(manifestPath, `${JSON.stringify(manifest)}\n`);
await assert.rejects(validateOperationalStateBackup(backupRoot), /newer than supported/);
} finally {
await rm(base, { recursive: true, force: true });
}
});
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,234 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, readFile, readdir, rm, symlink, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { PET_PACK_SCHEMA_V1 } from '@maka/core/pet';
import {
PET_PACK_DIRECTORY,
PET_PACK_MANIFEST_FILE,
PET_PACK_SPRITE_SHEET_MAX_BYTES,
PetPackStoreError,
createPetPackStore,
} from '../pet-pack-store.js';
function manifest(overrides: Record<string, unknown> = {}): Record<string, unknown> {
return {
schema: PET_PACK_SCHEMA_V1,
id: 'likun.maodie',
displayName: '我的耄耋',
description: 'A user-installed custom pet.',
spriteSheet: {
path: 'assets/maodie.png',
format: 'png',
frameWidth: 32,
frameHeight: 32,
columns: 2,
rows: 2,
frameCount: 4,
},
animations: {
idle: { frames: [0], fps: 2, loop: true },
working: { frames: [1], fps: 4, loop: true },
'needs-input': { frames: [2], fps: 2, loop: true },
ready: { frames: [3], fps: 4, loop: false, fallback: 'idle' },
blocked: { frames: [2], fps: 2, loop: true },
},
...overrides,
};
}
function pngHeader(width: number, height: number): Buffer {
const bytes = Buffer.alloc(33);
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(bytes);
bytes.writeUInt32BE(13, 8);
bytes.write('IHDR', 12, 'ascii');
bytes.writeUInt32BE(width, 16);
bytes.writeUInt32BE(height, 20);
return bytes;
}
describe('PetPackStore', () => {
test('atomically installs, lists, reads, and removes a custom pet', async () => {
await withStore(async ({ root, store }) => {
const installed = await store.install({
manifest: manifest(),
spriteSheet: pngHeader(64, 64),
});
assert.equal(installed.id, 'likun.maodie');
assert.deepEqual(
(await store.list()).map((item) => item.id),
['likun.maodie'],
);
assert.equal((await store.get('likun.maodie'))?.displayName, '我的耄耋');
const asset = await store.readSpriteSheet('likun.maodie');
assert.equal(asset?.format, 'png');
assert.deepEqual(Buffer.from(asset?.bytes ?? []), pngHeader(64, 64));
const packRoot = join(root, ...PET_PACK_DIRECTORY.split('/'), 'likun.maodie');
assert.equal(
JSON.parse(await readFile(join(packRoot, PET_PACK_MANIFEST_FILE), 'utf8')).id,
'likun.maodie',
);
assert.deepEqual(
(await readdir(join(root, ...PET_PACK_DIRECTORY.split('/')))).filter((name) =>
name.startsWith('.install-'),
),
[],
);
assert.equal(await store.remove('likun.maodie'), true);
assert.equal(await store.remove('likun.maodie'), false);
assert.deepEqual(await store.list(), []);
});
});
test('rejects malformed manifests before publishing any directory', async () => {
await withStore(async ({ root, store }) => {
const invalid = manifest({ script: 'pet.js' });
await assert.rejects(store.install({ manifest: invalid, spriteSheet: pngHeader(64, 64) }));
await assert.rejects(readdir(join(root, ...PET_PACK_DIRECTORY.split('/'))), {
code: 'ENOENT',
});
});
});
test('rejects mismatched dimensions, invalid headers, and oversized assets', async () => {
await withStore(async ({ store }) => {
await assert.rejects(
store.install({ manifest: manifest(), spriteSheet: pngHeader(32, 64) }),
isStoreError('invalid_asset'),
);
await assert.rejects(
store.install({ manifest: manifest(), spriteSheet: Buffer.from('not an image') }),
isStoreError('invalid_asset'),
);
await assert.rejects(
store.install({
manifest: manifest(),
spriteSheet: new Uint8Array(PET_PACK_SPRITE_SHEET_MAX_BYTES + 1),
}),
isStoreError('invalid_asset'),
);
assert.deepEqual(await store.list(), []);
});
});
test('never replaces an installed pet with the same id', async () => {
await withStore(async ({ store }) => {
await store.install({ manifest: manifest(), spriteSheet: pngHeader(64, 64) });
await assert.rejects(
store.install({
manifest: manifest({ displayName: 'Replacement' }),
spriteSheet: pngHeader(64, 64),
}),
isStoreError('already_installed'),
);
assert.equal((await store.get('likun.maodie'))?.displayName, '我的耄耋');
});
});
test('snapshots caller-owned manifest and image bytes before waiting for publication', async () => {
await withStore(async ({ store }) => {
const mutableManifest = manifest({ id: 'likun.snapshot' });
const mutableSprite = pngHeader(64, 64);
const install = store.install({
manifest: mutableManifest,
spriteSheet: mutableSprite,
});
mutableManifest.displayName = 'Mutated after admission';
mutableSprite.fill(0);
await install;
assert.equal((await store.get('likun.snapshot'))?.displayName, '我的耄耋');
assert.deepEqual(
Buffer.from((await store.readSpriteSheet('likun.snapshot'))?.bytes ?? []),
pngHeader(64, 64),
);
});
});
test('rejects non-canonical ids at every direct lookup boundary', async () => {
await withStore(async ({ store }) => {
await assert.rejects(store.get('../maodie'), isStoreError('invalid_id'));
await assert.rejects(store.readSpriteSheet('/tmp/maodie'), isStoreError('invalid_id'));
await assert.rejects(store.remove('MAODIE'), isStoreError('invalid_id'));
});
});
test('detects sprite sheets redirected outside the installed pack', {
skip:
process.platform === 'win32'
? 'Windows file-symlink permissions are not guaranteed in CI'
: false,
}, async () => {
await withStore(async ({ root, store }) => {
await store.install({ manifest: manifest(), spriteSheet: pngHeader(64, 64) });
const packRoot = join(root, ...PET_PACK_DIRECTORY.split('/'), 'likun.maodie');
const assetPath = join(packRoot, 'assets', 'maodie.png');
const outsidePath = join(root, 'outside.png');
await writeFile(outsidePath, pngHeader(64, 64));
await rm(assetPath);
await symlink(outsidePath, assetPath);
await assert.rejects(store.readSpriteSheet('likun.maodie'), isStoreError('corrupt_pack'));
});
});
test('rejects a store root redirected outside the state root', async () => {
await withStore(async ({ root, store }) => {
const outside = await mkdtemp(join(tmpdir(), 'maka-pet-pack-outside-'));
try {
await symlink(
outside,
join(root, 'pets'),
process.platform === 'win32' ? 'junction' : 'dir',
);
await assert.rejects(store.list(), isStoreError('corrupt_store'));
await assert.rejects(
store.install({ manifest: manifest(), spriteSheet: pngHeader(64, 64) }),
isStoreError('corrupt_store'),
);
assert.deepEqual(await readdir(outside), []);
} finally {
await rm(join(root, 'pets'), { force: true });
await rm(outside, { recursive: true, force: true });
}
});
});
});
function isStoreError(code: PetPackStoreError['code']): (error: unknown) => boolean {
return (error) => error instanceof PetPackStoreError && error.code === code;
}
async function withStore(
run: (input: { root: string; store: ReturnType<typeof createPetPackStore> }) => Promise<void>,
): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-pet-pack-store-'));
try {
await run({ root, store: createPetPackStore(root) });
} finally {
await rm(root, { recursive: true, force: true });
}
}
@@ -0,0 +1,132 @@
/*
* 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 { strict as assert } from 'node:assert';
import { fork } from 'node:child_process';
import { mkdtemp, readdir, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test, type TestContext } from 'node:test';
import { acquireProcessLifetimeOwner } from '../process-lifetime-owner.js';
test('claims an owner only after its process exits', async (t) => {
const root = await mkdtemp(join(tmpdir(), 'maka-process-lifetime-owner-'));
const child = fork(
new URL('./fixtures/process-lifetime-owner-holder.js', import.meta.url),
[root],
{ stdio: ['ignore', 'ignore', 'inherit', 'ipc'] },
);
const observer = await acquireProcessLifetimeOwner(root);
const competingObserver = await acquireProcessLifetimeOwner(root);
t.after(async () => {
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
await observer.close().catch(() => undefined);
await competingObserver.close().catch(() => undefined);
await rm(root, { recursive: true, force: true });
});
const reference = await waitForReference(t, child);
assert.equal(await observer.tryClaimReleased(reference), undefined);
child.kill('SIGKILL');
await new Promise<void>((resolve) => child.once('exit', () => resolve()));
const claims = await Promise.all([
observer.tryClaimReleased(reference),
competingObserver.tryClaimReleased(reference),
]);
const acquired = claims.filter((claim) => claim !== undefined);
assert.equal(acquired.length, 1);
await acquired[0]?.retire();
});
test('releases its owner reference on graceful close', async (t) => {
const root = await mkdtemp(join(tmpdir(), 'maka-process-lifetime-owner-'));
const owner = await acquireProcessLifetimeOwner(root);
const observer = await acquireProcessLifetimeOwner(root);
t.after(async () => {
await owner.close().catch(() => undefined);
await observer.close().catch(() => undefined);
await rm(root, { recursive: true, force: true });
});
assert.equal(await observer.tryClaimReleased(owner.reference), undefined);
await owner.close();
const claim = await observer.tryClaimReleased(owner.reference);
assert.ok(claim);
await claim.retire();
});
test('retires an unreferenced owner file after an unclean process exit', async (t) => {
const root = await mkdtemp(join(tmpdir(), 'maka-process-lifetime-owner-'));
const child = fork(
new URL('./fixtures/process-lifetime-owner-holder.js', import.meta.url),
[root],
{ stdio: ['ignore', 'ignore', 'inherit', 'ipc'] },
);
t.after(async () => {
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
await rm(root, { recursive: true, force: true });
});
const deadReference = await waitForReference(t, child);
child.kill('SIGKILL');
await new Promise<void>((resolve) => child.once('exit', () => resolve()));
const successor = await acquireProcessLifetimeOwner(root);
t.after(() => successor.close());
await successor.retireUnreferencedReleasedOwners(new Set());
const files = await readdir(join(root, 'owners'));
assert.deepEqual(files, [`${successor.reference.slice('lock-v1:'.length)}.lease`]);
assert.equal(files.includes(`${deadReference.slice('lock-v1:'.length)}.lease`), false);
});
test('rejects owner references outside its versioned namespace', async (t) => {
const root = await mkdtemp(join(tmpdir(), 'maka-process-lifetime-owner-'));
const owner = await acquireProcessLifetimeOwner(root);
t.after(async () => {
await owner.close().catch(() => undefined);
await rm(root, { recursive: true, force: true });
});
await assert.rejects(owner.tryClaimReleased('../other'), /Invalid process lifetime owner/);
});
async function waitForReference(t: TestContext, child: ReturnType<typeof fork>): Promise<string> {
return new Promise<string>((resolve, reject) => {
const onMessage = (message: unknown) => {
if (
typeof message === 'object' &&
message !== null &&
'reference' in message &&
typeof message.reference === 'string'
) {
resolve(message.reference);
} else {
reject(new Error(`Unexpected child message: ${String(message)}`));
}
};
child.once('message', onMessage);
child.once('error', reject);
child.once('exit', (code, signal) => {
reject(new Error(`Owner exited before acquisition (${String(code)}, ${signal})`));
});
t.after(() => child.off('message', onMessage));
});
}
@@ -0,0 +1,373 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import type { CreateSessionInput } from '@maka/core/runtime-inputs';
import { acquireProcessLifetimeOwner } from '../process-lifetime-owner.js';
import {
createFileProductionSessionSnapshotService,
SESSION_SNAPSHOT_STATE_IDENTITY_MEDIA_TYPE,
} from '../production-session-snapshot.js';
import {
SessionSnapshotError,
type SessionSnapshotQuiescenceAuthority,
type SessionSnapshotWorkspaceConfirmationAuthority,
} from '../quiescent-session-snapshot.js';
import type { PackQuiescentSessionBundleInput } from '../production-session-snapshot.js';
import type { SessionBundleFileService, SessionBundleLimits } from '../session-bundle-contract.js';
import { createSessionBundleFileService } from '../session-bundle-file-service.js';
import { createSessionStore } from '../session-store.js';
const limits: SessionBundleLimits = {
maxCompressedBytes: 4 * 1024 * 1024,
maxDecompressedTarBytes: 8 * 1024 * 1024,
maxPayloadBytes: 4 * 1024 * 1024,
maxFileBytes: 2 * 1024 * 1024,
maxEntryCount: 100,
maxManifestBytes: 256 * 1024,
maxStateIdentityBytes: 64 * 1024,
maxPathBytes: 255,
maxPathDepth: 16,
};
const immediateQuiescence: SessionSnapshotQuiescenceAuthority = {
async runQuiescent(_input, operation) {
return await operation();
},
};
test('prepares real Session state and a policy-filtered workspace, then packs and hydrates it', async () => {
const fixture = await createFixture();
try {
await writeFile(join(fixture.workspaceRoot, 'README.md'), 'portable workspace\n');
await writeFile(join(fixture.workspaceRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
await mkdir(join(fixture.workspaceRoot, 'node_modules', 'dep'), { recursive: true });
await writeFile(join(fixture.workspaceRoot, 'node_modules', 'dep', 'index.js'), 'excluded');
await mkdir(join(fixture.workspaceRoot, '.git'), { recursive: true });
await writeFile(join(fixture.workspaceRoot, '.git', 'config'), 'excluded');
await mkdir(join(fixture.workspaceRoot, '.cache'), { recursive: true });
await writeFile(join(fixture.workspaceRoot, '.cache', 'result'), 'excluded');
await mkdir(join(fixture.workspaceRoot, 'logs'), { recursive: true });
await writeFile(join(fixture.workspaceRoot, 'logs', 'runtime.log'), 'excluded');
const service = await fixture.createService();
const archivePath = join(fixture.root, 'bundle.tar.zst');
const artifact = await service.pack({ destination: archivePath });
assert.deepEqual(artifact.snapshotCleanup, { state: 'released' });
const hydratedRoot = join(fixture.root, 'hydrated');
const hydrated = await createSessionBundleFileService().hydrate({
source: { path: archivePath, expectedArchiveDigest: artifact.archiveDigest },
expectedSessionId: fixture.cloudSessionId,
destinationRoot: hydratedRoot,
limits,
});
assert.equal(
await readFile(join(hydrated.workspaceRoot, 'README.md'), 'utf8'),
'portable workspace\n',
);
assert.equal(
await readFile(join(hydrated.workspaceRoot, 'package-lock.json'), 'utf8'),
'{"lockfileVersion":3}\n',
);
await assert.rejects(readFile(join(hydrated.workspaceRoot, 'node_modules', 'dep', 'index.js')));
await assert.rejects(readFile(join(hydrated.workspaceRoot, '.git', 'config')));
await assert.rejects(readFile(join(hydrated.workspaceRoot, '.cache', 'result')));
await assert.rejects(readFile(join(hydrated.workspaceRoot, 'logs', 'runtime.log')));
assert.equal((await readFile(join(hydrated.stateRoot, 'runtime.sqlite'))).byteLength > 0, true);
const inspection = await createSessionBundleFileService().inspect({
source: { path: archivePath, expectedArchiveDigest: artifact.archiveDigest },
limits,
});
assert.equal(inspection.stateIdentity.mediaType, SESSION_SNAPSHOT_STATE_IDENTITY_MEDIA_TYPE);
assert.deepEqual(JSON.parse(Buffer.from(inspection.stateIdentity.bytes).toString('utf8')), {
schemaVersion: 1,
makaSessionId: fixture.sessionId,
});
assert.deepEqual(
(await readdir(fixture.stagingParent)).filter((name) => name.startsWith('.snapshot-')),
[],
);
assert.deepEqual(
(await readdir(fixture.stagingParent)).filter((name) => name.startsWith('snapshot-')),
[],
);
} finally {
await fixture.close();
}
});
test('fails closed for a known user-authored secret and removes private staging', async () => {
const fixture = await createFixture();
try {
await writeFile(join(fixture.workspaceRoot, '.env'), 'TOKEN=not-portable\n');
const service = await fixture.createService();
await assert.rejects(service.prepare({}), (error) => {
assert.ok(error instanceof SessionSnapshotError);
assert.equal(error.code, 'policy_rejected');
assert.deepEqual(error.details, {
phase: 'workspace',
policyCategory: 'known_secret_file',
});
return true;
});
assert.deepEqual(
(await readdir(fixture.stagingParent)).filter((name) => name.includes('snapshot')),
[],
);
} finally {
await fixture.close();
}
});
test('binds the configured Maka Session and Cloud envelope despite untrusted call fields', async () => {
const fixture = await createFixture();
try {
await writeFile(join(fixture.workspaceRoot, 'README.md'), 'bound workspace\n');
const service = await fixture.createService();
const archivePath = join(fixture.root, 'bound.tar.zst');
const artifact = await service.pack({
destination: archivePath,
makaSessionId: 'other-session',
sessionId: 'other-cloud-session',
} as unknown as PackQuiescentSessionBundleInput);
const inspection = await createSessionBundleFileService().inspect({
source: { path: archivePath, expectedArchiveDigest: artifact.archiveDigest },
limits,
});
assert.equal(inspection.manifest.envelope.sessionId, fixture.cloudSessionId);
assert.deepEqual(JSON.parse(Buffer.from(inspection.stateIdentity.bytes).toString('utf8')), {
schemaVersion: 1,
makaSessionId: fixture.sessionId,
});
} finally {
await fixture.close();
}
});
test('rejects a production root nested under the workspace before copying', async () => {
const fixture = await createFixture();
try {
await assert.rejects(
fixture.createService({ stagingParent: join(fixture.workspaceRoot, 'staging') }),
(error) => error instanceof SessionSnapshotError && error.code === 'unsafe_source',
);
} finally {
await fixture.close();
}
});
test('uses an authenticated confirmation authority for suspected secret directories', async () => {
const fixture = await createFixture();
try {
await mkdir(join(fixture.workspaceRoot, 'secrets'));
await writeFile(
join(fixture.workspaceRoot, 'secrets', 'reference.txt'),
'not a secret value\n',
);
const confirmations: string[] = [];
const confirmationAuthority: SessionSnapshotWorkspaceConfirmationAuthority = {
async resolveConfirmation(input) {
confirmations.push(`${input.makaSessionId}:${input.confirmationPath}`);
assert.equal(input.confirmationGrantId, 'grant-1');
return { action: 'include' };
},
};
const service = await fixture.createService({ confirmationAuthority });
const prepared = await service.prepare({ confirmationGrantId: 'grant-1' });
try {
assert.equal(
await readFile(join(prepared.snapshot.workspaceRoot, 'secrets', 'reference.txt'), 'utf8'),
'not a secret value\n',
);
assert.deepEqual(confirmations, [`${fixture.sessionId}:secrets`]);
} finally {
await prepared.release();
}
} finally {
await fixture.close();
}
});
test('reserves state entries before admitting workspace entries', async () => {
const fixture = await createFixture();
try {
await writeFile(join(fixture.workspaceRoot, 'README.md'), 'would exceed bundle entry quota\n');
const service = await fixture.createService({
limits: { ...limits, maxEntryCount: 4 },
});
await assert.rejects(service.prepare({}), (error) => {
assert.ok(error instanceof SessionSnapshotError);
assert.equal(error.code, 'quota_exceeded');
assert.deepEqual(error.details, { phase: 'workspace' });
return true;
});
} finally {
await fixture.close();
}
});
test('returns the written Bundle and reports recoverable staging cleanup failure', async () => {
const fixture = await createFixture();
try {
await writeFile(join(fixture.workspaceRoot, 'README.md'), 'durable artifact\n');
const codec = createSessionBundleFileService();
const bundleFileService: SessionBundleFileService = {
async pack(input) {
const artifact = await codec.pack(input);
const snapshotRoot = dirname(input.snapshot.stateRoot);
await rename(snapshotRoot, `${snapshotRoot}.displaced`);
await mkdir(snapshotRoot, { mode: 0o700 });
await writeFile(join(snapshotRoot, 'unrelated.txt'), 'do not remove\n');
return artifact;
},
inspect: codec.inspect.bind(codec),
hydrate: codec.hydrate.bind(codec),
cleanupHydrationStaging: codec.cleanupHydrationStaging.bind(codec),
};
const service = await fixture.createService({ bundleFileService });
const archivePath = join(fixture.root, 'bundle-with-pending-cleanup.tar.zst');
const artifact = await service.pack({ destination: archivePath });
assert.equal((await readFile(archivePath)).byteLength > 0, true);
const inspection = await codec.inspect({
source: { path: archivePath, expectedArchiveDigest: artifact.archiveDigest },
limits,
});
assert.equal(inspection.verified, true);
assert.equal(artifact.snapshotCleanup.state, 'pending_recovery');
if (artifact.snapshotCleanup.state === 'pending_recovery') {
assert.equal(artifact.snapshotCleanup.error.code, 'cleanup_failed');
assert.deepEqual(artifact.snapshotCleanup.error.details, { phase: 'cleanup' });
}
} finally {
await fixture.close();
}
});
test('rejects a POSIX-only workspace name with a bounded portability diagnostic', {
skip: process.platform === 'win32',
}, async () => {
const fixture = await createFixture();
try {
await writeFile(join(fixture.workspaceRoot, 'name.'), 'not portable\n');
const service = await fixture.createService();
await assert.rejects(service.prepare({}), (error) => {
assert.ok(error instanceof SessionSnapshotError);
assert.equal(error.code, 'unsafe_source');
assert.deepEqual(error.details, {
phase: 'workspace',
policyCategory: 'unsupported_portable_path',
observed: 1,
});
return true;
});
} finally {
await fixture.close();
}
});
async function createFixture(): Promise<{
readonly root: string;
readonly stateRoot: string;
readonly configRoot: string;
readonly workspaceRoot: string;
readonly stagingParent: string;
readonly cleanupStateRoot: string;
readonly sessionId: string;
readonly cloudSessionId: string;
createService: (overrides?: {
readonly workspaceRoot?: string;
readonly stagingParent?: string;
readonly cleanupStateRoot?: string;
readonly limits?: SessionBundleLimits;
readonly confirmationAuthority?: SessionSnapshotWorkspaceConfirmationAuthority;
readonly bundleFileService?: SessionBundleFileService;
}) => ReturnType<typeof createFileProductionSessionSnapshotService>;
close(): Promise<void>;
}> {
const root = await mkdtemp(join(tmpdir(), 'maka-production-snapshot-'));
const stateRoot = join(root, 'state');
const configRoot = join(root, 'config');
const workspaceRoot = join(root, 'workspace');
const stagingParent = join(root, 'staging');
const cleanupStateRoot = join(root, 'cleanup-state');
await Promise.all([
mkdir(configRoot),
mkdir(workspaceRoot),
mkdir(stagingParent, { mode: 0o700 }),
]);
const sessions = createSessionStore(stateRoot);
const session = await sessions.create(sessionInput());
await sessions.appendMessage(session.id, {
type: 'user',
id: 'message-1',
turnId: 'turn-1',
ts: 1,
text: 'durable message',
});
await sessions.close?.();
const owner = await acquireProcessLifetimeOwner(cleanupStateRoot);
const cloudSessionId = 'cloud-session-1';
return {
root,
stateRoot,
configRoot,
workspaceRoot,
stagingParent,
cleanupStateRoot,
sessionId: session.id,
cloudSessionId,
createService: (overrides = {}) =>
createFileProductionSessionSnapshotService({
session: { makaSessionId: session.id, cloudSessionId },
stateRoot,
configRoot,
workspaceRoot: overrides.workspaceRoot ?? workspaceRoot,
stagingParent: overrides.stagingParent ?? stagingParent,
cleanupStateRoot: overrides.cleanupStateRoot ?? cleanupStateRoot,
processLifetimeOwner: owner,
quiescence: immediateQuiescence,
limits: overrides.limits ?? limits,
confirmationAuthority: overrides.confirmationAuthority,
bundleFileService: overrides.bundleFileService,
}),
async close(): Promise<void> {
await owner.close();
await rm(root, { recursive: true, force: true });
},
};
}
function sessionInput(): CreateSessionInput {
return {
cwd: '/tmp/workspace',
llmConnectionSlug: 'fake',
model: 'fake-model',
permissionMode: 'ask',
name: 'Portable Session',
labels: [],
};
}
@@ -0,0 +1,77 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdir, mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, test } from 'node:test';
import {
authenticateInteractiveProjectCatalogWriter,
openInteractiveProjectCatalogForWrite,
} from '../project-catalog-authority.js';
import {
resolveStorageRoot,
StorageRootAuthorityError,
tryAcquireInteractiveRootOwner,
} from '../root-authority.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
// The control directory of each resolved root lives outside that root, so a
// temporary root's removal leaves it behind; reclaim the recorded rootIds here.
after(removeTrackedControlDirectories);
test('Project Catalog writes require one live interactive root owner', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-catalog-authority-'));
const dataRoot = join(base, 'data');
const projectRoot = join(base, 'project');
await mkdir(projectRoot);
const capability = trackControlDirectory(
await resolveStorageRoot({ path: dataRoot, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
let writer: Awaited<ReturnType<typeof openInteractiveProjectCatalogForWrite>> | undefined;
try {
const [first, second] = await Promise.all([
openInteractiveProjectCatalogForWrite(owner.lease),
openInteractiveProjectCatalogForWrite(owner.lease),
]);
writer = first;
assert.equal(first, second);
assert.equal(authenticateInteractiveProjectCatalogWriter(first), first);
const project = await first.register(projectRoot);
assert.equal((await second.list())[0]?.id, project.id);
await owner.close();
await assert.rejects(
() => first.rename(project.id, 'Renamed'),
(error: unknown) =>
error instanceof StorageRootAuthorityError && error.code === 'invalid_lease',
);
} finally {
writer?.close();
if (!owner.closed) await owner.close();
await rm(base, { recursive: true, force: true });
}
});
@@ -0,0 +1,708 @@
/*
* 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 assert from 'node:assert/strict';
import { execFile } from 'node:child_process';
import { mkdir, mkdtemp, readFile, realpath, rm as remove, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { isAbsolute, join, parse, relative, resolve } from 'node:path';
import { test } from 'node:test';
import { promisify } from 'node:util';
import {
createProjectCatalog as createProjectCatalogBase,
type ProjectCatalog,
ProjectPathBoundaryError,
ProjectUnavailableError,
ProjectPathMismatchError,
type ResolvedProjectLocation,
resolveProjectLocation,
} from '../project-catalog.js';
import { createSessionStore } from '../session-store.js';
import { createGitRepositoryWithWorktree } from './fixtures/git-repository.js';
const execFileAsync = promisify(execFile);
const trackedCatalogs = new Map<ProjectCatalog, string>();
// Every catalog owns a lease on runtime.sqlite. POSIX can unlink that database
// while it is open, but Windows cannot, so test cleanup must release every
// catalog under the temporary root before removing the root itself.
function createProjectCatalog(
storageRoot: string,
deps?: Parameters<typeof createProjectCatalogBase>[1],
): ProjectCatalog {
const catalog = createProjectCatalogBase(storageRoot, deps);
const close = catalog.close.bind(catalog);
catalog.close = () => {
if (!trackedCatalogs.delete(catalog)) return;
close();
};
trackedCatalogs.set(catalog, storageRoot);
return catalog;
}
async function rm(path: string, options?: Parameters<typeof remove>[1]): Promise<void> {
const removedRoot = resolve(path);
for (const [catalog, storageRoot] of [...trackedCatalogs].reverse()) {
const storagePath = resolve(storageRoot);
const fromRemovedRoot = relative(removedRoot, storagePath);
if (
fromRemovedRoot === '' ||
(!fromRemovedRoot.startsWith('..') && !isAbsolute(fromRemovedRoot))
) {
catalog.close();
}
}
await remove(path, options);
}
function sessionInput(cwd: string, projectId: string) {
return {
cwd,
projectId,
backend: 'fake' as const,
llmConnectionSlug: 'fake',
model: 'fake-model',
permissionMode: 'ask' as const,
};
}
test('a plain folder resolves without requiring the Git executable', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-folder-no-git-'));
try {
const folder = join(base, 'folder');
await mkdir(folder);
assert.deepEqual(await resolveProjectLocationWithoutGit(folder), {
canonicalPath: await realpath(folder),
identity: `folder:${await realpath(folder)}`,
kind: 'folder',
});
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('a Git probe failure cannot persistently downgrade a repository to a folder', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-repository-no-git-'));
try {
const repository = join(base, 'repository');
const storage = join(base, 'storage');
await mkdir(repository);
await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
await assert.rejects(() => registerProjectWithoutGit(repository, storage));
// Nothing may be recorded: a folder identity written here would outlive the
// probe failure and permanently split the repository from its worktrees.
assert.deepEqual(await createProjectCatalog(storage).list(), []);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('a repository and its linked worktree resolve to one project identity', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-location-'));
try {
const repository = join(base, 'repository');
const linkedWorktree = join(base, 'linked');
await createGitRepositoryWithWorktree(repository, linkedWorktree, 'project-catalog-test');
const main = await resolveProjectLocation({ path: repository });
const linked = await resolveProjectLocation({ path: linkedWorktree });
assert.equal(main.kind, 'git');
assert.equal(linked.kind, 'git');
assert.equal(main.identity, linked.identity);
assert.notEqual(main.canonicalPath, linked.canonicalPath);
assert.equal(main.git?.isWorktree, false);
assert.equal(linked.git?.isWorktree, true);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('registering a nested folder keeps that folder instead of the enclosing repository', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-nested-folder-'));
try {
const parent = join(base, 'parent-project');
const child = join(parent, 'child-project');
await mkdir(child, { recursive: true });
await execFileAsync('git', ['init', '--quiet'], { cwd: parent });
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => 1_000,
createId: (() => {
let id = 0;
return () => `project-${++id}`;
})(),
});
const parentProject = await catalog.register(parent);
const childProject = await catalog.register(child);
const parentPath = await realpath(parent);
const childPath = await realpath(child);
assert.notEqual(childProject.id, parentProject.id);
assert.equal(parentProject.preferredPath, parentPath);
assert.equal(childProject.preferredPath, childPath);
assert.equal(childProject.name, 'child-project');
// session.create → HostWorkspaceResolver.touch(projectId, preferredPath)
const touched = await catalog.touch(childProject.id, childProject.preferredPath);
assert.equal(touched.id, childProject.id);
assert.equal(touched.preferredPath, childPath);
await assert.rejects(
() => catalog.touch(childProject.id, parentPath),
(error) => error instanceof ProjectPathMismatchError && error.projectId === childProject.id,
);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('registration validates the final canonical path against its boundary', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-boundary-'));
try {
const publishedRoot = join(base, 'published');
const outside = join(base, 'outside');
await Promise.all([mkdir(publishedRoot), mkdir(outside)]);
const catalog = createProjectCatalog(join(base, 'storage'));
await assert.rejects(
() => catalog.register(outside, { withinRoot: publishedRoot }),
(error) => error instanceof ProjectPathBoundaryError,
);
assert.deepEqual(await catalog.list(), []);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('relink and relinkWithSessions keep a nested repository directory', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-nested-relink-'));
const storage = join(base, 'storage');
const sessions = createSessionStore(storage);
try {
const parent = join(base, 'parent-project');
const child = join(parent, 'child-project');
const childTwo = join(parent, 'child-two');
const elsewhere = join(base, 'elsewhere');
const elsewhereTwo = join(base, 'elsewhere-two');
await mkdir(child, { recursive: true });
await mkdir(childTwo, { recursive: true });
await mkdir(elsewhere, { recursive: true });
await mkdir(elsewhereTwo, { recursive: true });
await execFileAsync('git', ['init', '--quiet'], { cwd: parent });
const catalog = createProjectCatalog(storage, {
now: () => 1_000,
createId: (() => {
let id = 0;
return () => `project-${++id}`;
})(),
});
const parentProject = await catalog.register(parent);
const original = await catalog.register(elsewhere);
const originalSessions = await catalog.register(elsewhereTwo);
const childPath = await realpath(child);
const childTwoPath = await realpath(childTwo);
const assigned = await sessions.create(sessionInput(elsewhereTwo, originalSessions.id));
const relinked = await catalog.relink(original.id, child);
assert.equal(relinked.id, original.id);
assert.notEqual(relinked.id, parentProject.id);
assert.equal(relinked.preferredPath, childPath);
const { project: relinkedSessions, updatedSessionIds } = await catalog.relinkWithSessions(
originalSessions.id,
childTwo,
);
assert.equal(relinkedSessions.id, originalSessions.id);
assert.notEqual(relinkedSessions.id, parentProject.id);
assert.equal(relinkedSessions.preferredPath, childTwoPath);
assert.deepEqual(updatedSessionIds, [assigned.id]);
const header = await sessions.readHeaderSnapshot(assigned.id);
assert.equal(header.projectId, relinkedSessions.id);
assert.equal(header.cwd, childTwoPath);
} finally {
await sessions.close?.();
await rm(base, { recursive: true, force: true });
}
});
async function resolveProjectLocationWithoutGit(path: string): Promise<ResolvedProjectLocation> {
const stdout = await runProjectCatalogWithoutGit(
'const [moduleUrl, path] = process.argv.slice(1); const { resolveProjectLocation } = await import(moduleUrl); console.log(JSON.stringify(await resolveProjectLocation({ path })));',
path,
);
return JSON.parse(stdout) as ResolvedProjectLocation;
}
async function registerProjectWithoutGit(path: string, storage: string): Promise<void> {
await runProjectCatalogWithoutGit(
'const [moduleUrl, path, storage] = process.argv.slice(1); const { createProjectCatalog } = await import(moduleUrl); await createProjectCatalog(storage).register(path);',
path,
storage,
);
}
async function runProjectCatalogWithoutGit(source: string, ...args: string[]): Promise<string> {
const env: NodeJS.ProcessEnv = { ...process.env, PATH: '' };
delete env.Path;
const moduleUrl = new URL('../project-catalog.js', import.meta.url).href;
const { stdout } = await execFileAsync(
process.execPath,
['--input-type=module', '-e', source, moduleUrl, ...args],
{ env, encoding: 'utf8' },
);
return stdout;
}
test('registering a repository and its linked worktree creates one project with two locations', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-catalog-'));
try {
const repository = join(base, 'repository');
const linkedWorktree = join(base, 'linked');
await createGitRepositoryWithWorktree(repository, linkedWorktree, 'catalog-linked');
let now = 1_000;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => now,
createId: () => 'project-1',
});
const first = await catalog.register(repository);
now = 2_000;
const second = await catalog.register(linkedWorktree);
const repositoryPath = await realpath(repository);
const linkedWorktreePath = await realpath(linkedWorktree);
const expectedPaths = [linkedWorktreePath, repositoryPath].sort();
assert.equal(first.id, 'project-1');
assert.equal(first.preferredPath, repositoryPath);
assert.equal(second.id, first.id);
assert.equal(second.preferredPath, linkedWorktreePath);
assert.deepEqual(
(await catalog.list()).map((project) => ({
id: project.id,
name: project.name,
paths: project.locations.map((location) => location.path).sort(),
worktrees: project.locations.map((location) => location.isWorktree).sort(),
})),
[
{
id: 'project-1',
name: 'repository',
paths: expectedPaths,
worktrees: [false, true],
},
],
);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('registering without preference preserves the preferred location until it is touched', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-catalog-not-preferred-'));
try {
const repository = join(base, 'repository');
const linkedWorktree = join(base, 'linked');
await createGitRepositoryWithWorktree(repository, linkedWorktree, 'catalog-not-preferred');
let now = 1_000;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => now,
createId: () => 'project-1',
});
const doNotPrefer = { prefer: false } as const;
const repositoryPath = await realpath(repository);
const linkedWorktreePath = await realpath(linkedWorktree);
const first = await catalog.register(repository, doNotPrefer);
now = 2_000;
const added = await catalog.register(linkedWorktree, doNotPrefer);
assert.equal(added.id, first.id);
assert.equal(added.locations.length, 2);
assert.equal(added.preferredPath, repositoryPath);
now = 3_000;
const registeredAgain = await catalog.register(linkedWorktree, doNotPrefer);
assert.equal(registeredAgain.preferredPath, repositoryPath);
now = 4_000;
const touched = await catalog.touch(first.id, linkedWorktreePath);
assert.equal(touched.preferredPath, linkedWorktreePath);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('archiving a project preserves it with an archive timestamp', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-archive-'));
try {
const workspace = join(base, 'workspace');
await mkdir(workspace);
let now = 1_000;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => now,
createId: () => 'project-1',
});
const project = await catalog.register(workspace);
now = 2_000;
const archived = await catalog.archive(project.id);
assert.equal(archived.archivedAt, 2_000);
assert.equal((await catalog.list())[0]?.id, project.id);
assert.equal((await catalog.list())[0]?.archivedAt, 2_000);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('restoring an archived project makes the same project active again', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-restore-'));
try {
const workspace = join(base, 'workspace');
await mkdir(workspace);
let now = 1_000;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => now,
createId: () => 'project-1',
});
const project = await catalog.register(workspace);
now = 2_000;
await catalog.archive(project.id);
now = 3_000;
const restored = await catalog.restore(project.id);
assert.equal(restored.id, project.id);
assert.equal(restored.archivedAt, undefined);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('renaming a project stores the trimmed display name without changing its identity', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-rename-'));
try {
const workspace = join(base, 'workspace');
await mkdir(workspace);
let now = 1_000;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => now,
createId: () => 'project-1',
});
const project = await catalog.register(workspace);
now = 2_000;
const renamed = await catalog.rename(project.id, ' Design System ');
assert.equal(renamed.id, project.id);
assert.equal(renamed.name, 'Design System');
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('a missing project directory remains in the catalog as unavailable', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-unavailable-'));
try {
const workspace = join(base, 'workspace');
const storage = join(base, 'storage');
await mkdir(workspace);
const catalog = createProjectCatalog(storage, {
now: () => 1_000,
createId: () => 'project-1',
});
const project = await catalog.register(workspace);
await rm(workspace, { recursive: true, force: true });
const restoredCatalog = createProjectCatalog(storage);
const [unavailable] = await restoredCatalog.list();
assert.equal(unavailable?.id, project.id);
assert.equal(unavailable?.available, false);
assert.equal(unavailable?.preferredPath, undefined);
assert.equal(unavailable?.locations.length, 1);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('two catalogs changing one project at the same time keep both changes', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-concurrent-'));
try {
const workspace = join(base, 'workspace');
const storage = join(base, 'storage');
await mkdir(workspace);
const first = createProjectCatalog(storage, { now: () => 1_000 });
const second = createProjectCatalog(storage, { now: () => 2_000 });
const project = await first.register(workspace);
// Each catalog rewrites the whole table; without holding the write lock
// across its own read, the later writer replays a stale copy and the other
// window's edit disappears with no error anywhere.
await Promise.all([second.archive(project.id), first.rename(project.id, 'Renamed')]);
const [merged] = await first.list();
assert.equal(merged?.name, 'Renamed', 'the rename must survive the concurrent archive');
assert.equal(merged?.archivedAt, 2_000, 'the archive must survive the concurrent rename');
first.close();
second.close();
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('relinking an unavailable project preserves its id and adopts the new directory', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-'));
try {
const workspace = join(base, 'workspace');
const relocated = join(base, 'relocated');
await mkdir(workspace);
let now = 1_000;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => now,
createId: () => 'project-1',
});
const project = await catalog.register(workspace);
await rm(workspace, { recursive: true, force: true });
await mkdir(relocated);
now = 2_000;
const relinked = await catalog.relink(project.id, relocated);
assert.equal(relinked.id, project.id);
assert.equal(relinked.available, true);
assert.equal(relinked.preferredPath, await realpath(relocated));
assert.deepEqual(
relinked.locations.map((location) => location.path),
[await realpath(relocated)],
);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('Host relink rolls Project and Session membership back in one transaction', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-session-relink-'));
const storage = join(base, 'storage');
const originalPath = join(base, 'original');
const destinationPath = join(base, 'destination');
await Promise.all([mkdir(originalPath), mkdir(destinationPath)]);
const injected = new Error('injected atomic relink failure');
const catalog = createProjectCatalog(storage, {
createId: (() => {
let id = 0;
return () => `project-${++id}`;
})(),
relinkFailpoint: () => {
throw injected;
},
});
const sessions = createSessionStore(storage);
try {
const original = await catalog.register(originalPath);
const duplicate = await catalog.register(destinationPath);
const originalSession = await sessions.create(sessionInput(originalPath, original.id));
const duplicateSession = await sessions.create(sessionInput(destinationPath, duplicate.id));
await assert.rejects(
() => catalog.relinkWithSessions(original.id, destinationPath),
(error) => error === injected,
);
assert.deepEqual(
(await catalog.list()).map(({ id }) => id).sort(),
[original.id, duplicate.id].sort(),
);
assert.equal((await sessions.readHeaderSnapshot(originalSession.id)).projectId, original.id);
assert.equal((await sessions.readHeaderSnapshot(originalSession.id)).cwd, originalPath);
assert.equal((await sessions.readHeaderSnapshot(duplicateSession.id)).projectId, duplicate.id);
assert.equal((await sessions.readHeaderSnapshot(duplicateSession.id)).cwd, destinationPath);
} finally {
await sessions.close?.();
await rm(base, { recursive: true, force: true });
}
});
test('conflicting relink preserves every available worktree location from the merged project', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-worktrees-'));
try {
const repository = join(base, 'repository');
const linkedWorktree = join(base, 'linked');
await createGitRepositoryWithWorktree(repository, linkedWorktree, 'relink-linked');
let id = 0;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => 1_000,
createId: () => `project-${++id}`,
});
const originalPath = join(base, 'original');
await mkdir(originalPath);
const original = await catalog.register(originalPath);
await rm(originalPath, { recursive: true, force: true });
await catalog.register(repository);
await catalog.register(linkedWorktree);
const { project: relinked } = await catalog.relinkWithSessions(original.id, repository);
assert.deepEqual(
relinked.locations.map((location) => location.path).sort(),
[await realpath(repository), await realpath(linkedWorktree)].sort(),
);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('projects are listed by most recent use', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-recency-'));
try {
const firstPath = join(base, 'first');
const secondPath = join(base, 'second');
await mkdir(firstPath);
await mkdir(secondPath);
let now = 1_000;
let id = 0;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => now,
createId: () => `project-${++id}`,
});
await catalog.register(firstPath);
now = 2_000;
await catalog.register(secondPath);
assert.deepEqual(
(await catalog.list()).map((project) => project.name),
['second', 'first'],
);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('touching a project moves it to the front of the recent list', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-touch-'));
try {
const firstPath = join(base, 'first');
const secondPath = join(base, 'second');
await mkdir(firstPath);
await mkdir(secondPath);
let now = 1_000;
let id = 0;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => now,
createId: () => `project-${++id}`,
});
const first = await catalog.register(firstPath);
now = 2_000;
await catalog.register(secondPath);
now = 3_000;
await catalog.touch(first.id);
assert.deepEqual(
(await catalog.list()).map((project) => project.id),
[first.id, 'project-2'],
);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('touch reports a Project that disappears before path resolution as unavailable', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-touch-missing-'));
try {
const path = join(base, 'project');
await mkdir(path);
const catalog = createProjectCatalog(join(base, 'storage'));
const project = await catalog.register(path);
await remove(path, { recursive: true });
await assert.rejects(
() => catalog.touch(project.id, path),
(error) => error instanceof ProjectUnavailableError && error.projectId === project.id,
);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('selecting a project returns its most recent available location and rejects inactive projects', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-select-'));
try {
const availablePath = join(base, 'available');
const missingPath = join(base, 'missing');
await mkdir(availablePath);
let now = 1_000;
let id = 0;
const catalog = createProjectCatalog(join(base, 'storage'), {
now: () => now,
createId: () => `project-${++id}`,
});
const available = await catalog.register(availablePath);
await mkdir(missingPath);
const missing = await catalog.register(missingPath);
await rm(missingPath, { recursive: true, force: true });
now = 2_000;
const selected = await catalog.select(available.id);
assert.equal(selected.path, await realpath(availablePath));
assert.equal(selected.project.id, available.id);
await assert.rejects(() => catalog.select(missing.id), /unavailable/i);
await catalog.archive(available.id);
await assert.rejects(() => catalog.select(available.id), /archived/i);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('registering a filesystem root writes a project that a fresh catalog can read', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-root-'));
const storage = join(base, 'storage');
try {
const root = parse(base).root;
const catalog = createProjectCatalog(storage, {
createId: () => 'project-root',
});
const project = await catalog.register(root);
const reopened = createProjectCatalog(storage);
assert.ok(project.name.length > 0);
assert.equal((await reopened.list())[0]?.id, project.id);
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('catalog validates generated state before publishing it', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-project-write-validation-'));
const workspace = join(base, 'workspace');
await mkdir(workspace);
try {
const catalog = createProjectCatalog(join(base, 'storage'), {
createId: () => '',
});
await assert.rejects(() => catalog.register(workspace), /Invalid project catalog/);
} finally {
await rm(base, { recursive: true, force: true });
}
});
@@ -0,0 +1,56 @@
/*
* 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 { mkdtemp } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { createSqliteArtifactStore as createArtifactStore } from '../artifact-store.js';
import * as providerRequestCapture from '../provider-request-capture-artifact.js';
test('persists the exact prepared request as a private artifact', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-provider-capture-'));
const store = createArtifactStore(root);
const persist = Reflect.get(
providerRequestCapture,
'persistProviderRequestCaptureArtifact',
) as unknown as
| ((
store: ReturnType<typeof createArtifactStore>,
input: Record<string, unknown>,
) => Promise<{ id: string; source?: string; sizeBytes: number }>)
| undefined;
assert.equal(typeof persist, 'function');
const serializedRequest = '{"messages":[{"role":"user","content":"exact"}]}';
const artifact = await persist!(store, {
sessionId: 'session-1',
turnId: 'turn-1',
captureId: 'capture-1',
step: 2,
serializedRequest,
now: 1,
});
assert.equal(artifact.source, 'provider_request_capture');
assert.equal(artifact.sizeBytes, Buffer.byteLength(serializedRequest));
assert.deepEqual(await store.readText(artifact.id), { ok: true, text: serializedRequest });
});
@@ -0,0 +1,270 @@
/*
* 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 assert from 'node:assert/strict';
import { execFile } from 'node:child_process';
import { existsSync } from 'node:fs';
import { readdir, readFile } from 'node:fs/promises';
import { dirname, join, relative, resolve } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { promisify } from 'node:util';
import { test } from 'node:test';
const run = promisify(execFile);
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
/**
* Entrypoints whose module graph reaches `node:sqlite` at load time, so
* importing one emits Node's SQLite ExperimentalWarning.
*
* This list is the package's SQLite boundary, stated out loud. `@maka/storage`
* publishes no barrel: a consumer that needs a durable store imports the entry
* that owns it and accepts the warning, and a consumer that needs
* `workspace-root` or `credential-store` pays nothing. Issue #1257 came from
* the opposite arrangement, where one `export *` barrel made every consumer —
* `maka --help` included — load SQLite.
*
* Adding an entry here is a deliberate widening of that boundary. Removing one
* means an entrypoint became SQLite-free. Either way, update this list in the
* same change and say why.
*/
const SQLITE_BACKED_ENTRYPOINTS = [
'./agent-graph-control-store',
'./agent-run-store',
'./artifact-stores',
'./daily-review-authority',
'./deep-research-authority',
'./deep-research-store',
'./execution-stores',
'./git-worktree-child-executor',
'./goal-authority',
'./interaction-store',
'./model-call-ledger',
'./operational-state-store',
'./plan-authority',
// Production snapshot composition exports one filtered runtime SQLite database.
'./production-session-snapshot',
'./project-catalog',
'./project-catalog-authority',
// Snapshot staging cleanup persists a lease through Session-copy cleanup.
'./quiescent-session-snapshot',
'./runtime-event-persistence',
'./scheduled-task-store',
'./session-bundle-policy',
'./session-copy-cleanup',
'./session-store',
'./session-todo-authority',
'./shell-run-authority',
'./shell-run-store',
'./sqlite-session-metadata-store',
'./storage-writer-composition',
'./usage-stores',
'./work-board-store',
];
/**
* Loads an entrypoint in a child process and reports whether `node:sqlite`
* entered its module graph, observed through a `module.registerHooks` resolve
* hook. Matching Node's ExperimentalWarning text instead would tie this guard
* to a string Node owns and has already reworded once.
*/
async function loadsSqlite(target: string): Promise<boolean> {
const specifier = pathToFileURL(resolve(packageRoot, target)).href;
const probe = [
"import { registerHooks } from 'node:module';",
'let sawSqlite = false;',
'registerHooks({',
' resolve(request, context, nextResolve) {',
' const resolved = nextResolve(request, context);',
" if (resolved.url === 'node:sqlite') sawSqlite = true;",
' return resolved;',
' },',
'});',
`await import(${JSON.stringify(specifier)});`,
"process.stdout.write(sawSqlite ? '\\nSQLITE_IN_GRAPH=yes' : '\\nSQLITE_IN_GRAPH=no');",
].join('\n');
const { stdout } = await run(process.execPath, ['--input-type=module', '--eval', probe], {
encoding: 'utf8',
});
const verdict = /SQLITE_IN_GRAPH=(yes|no)$/u.exec(stdout);
assert.ok(verdict, `probe for ${target} produced no verdict; stdout was: ${stdout}`);
return verdict[1] === 'yes';
}
async function publishedEntrypoints(): Promise<Record<string, string>> {
const manifest = JSON.parse(await readFile(resolve(packageRoot, 'package.json'), 'utf8')) as {
exports: Record<string, string>;
};
return manifest.exports;
}
test('the package publishes no barrel entrypoint', async () => {
const exports = await publishedEntrypoints();
assert.equal('.' in exports, false);
const manifest = JSON.parse(await readFile(resolve(packageRoot, 'package.json'), 'utf8')) as {
main?: string;
types?: string;
};
assert.equal(manifest.main, undefined, 'a `main` field would re-advertise the barrel');
assert.equal(manifest.types, undefined, 'a `types` field would re-advertise the barrel');
});
test('every published entrypoint target is emitted by the build', async () => {
const exports = await publishedEntrypoints();
for (const [subpath, target] of Object.entries(exports)) {
assert.ok(
existsSync(resolve(packageRoot, target)),
`"${subpath}" points at ${target}, which the build did not emit`,
);
}
});
/**
* Published entrypoints no file outside this package imports today. Every one
* of them predates this change, so retiring them is a separate compatibility
* decision. The assertion is exact in both directions — gaining a consumer
* means removing the entry, and publishing a *new* consumer-less entrypoint
* fails outright, which is the direction this guard exists to hold.
*
* `./model-call-ledger` is on the list without this change touching it: it was
* already published, and `repairPendingModelCallProjections` lost its last
* caller when `canonical-usage-reader` was rewritten on `main`. It is listed
* here rather than unpublished for the same reason as the rest — retiring a
* subpath that already shipped is a compatibility call of its own.
*/
const PREEXISTING_UNCONSUMED_ENTRYPOINTS = [
'./activation-secret-injector',
'./encrypted-file-managed-secret-store',
'./managed-secret-store',
'./model-call-ledger',
'./write-queue',
];
interface StorageImportScan {
bareImporters: string[];
subpathImporters: Map<string, string[]>;
externalSubpaths: Set<string>;
}
let storageImportScan: Promise<StorageImportScan> | undefined;
/** Collects every `@maka/storage` import specifier in the repository's sources, once. */
function scanStorageImports(): Promise<StorageImportScan> {
storageImportScan ??= runStorageImportScan();
return storageImportScan;
}
async function runStorageImportScan(): Promise<StorageImportScan> {
const repoRoot = resolve(packageRoot, '../..');
const specifierPattern =
/(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)['"]@maka\/storage(\/[^'"]*)?['"]/gu;
const sourceExtensions = /\.(?:ts|tsx|mts|cts|js|mjs|cjs)$/u;
const skipped = new Set(['node_modules', 'dist', '.git']);
const scan: StorageImportScan = {
bareImporters: [],
subpathImporters: new Map(),
externalSubpaths: new Set(),
};
async function walk(directory: string): Promise<void> {
const entries = await readdir(directory, { withFileTypes: true });
await Promise.all(
entries.map(async (entry) => {
if (skipped.has(entry.name)) return;
const path = join(directory, entry.name);
if (entry.isDirectory()) return walk(path);
if (!sourceExtensions.test(entry.name)) return;
const source = await readFile(path, 'utf8');
for (const match of source.matchAll(specifierPattern)) {
if (!match[1]) {
scan.bareImporters.push(path);
continue;
}
const subpath = `.${match[1]}`;
const importers = scan.subpathImporters.get(subpath) ?? [];
importers.push(path);
scan.subpathImporters.set(subpath, importers);
if (relative(packageRoot, path).startsWith('..')) scan.externalSubpaths.add(subpath);
}
}),
);
}
await Promise.all(
['packages', 'apps', 'scripts'].map((directory) => walk(join(repoRoot, directory))),
);
return scan;
}
test('no source file imports the retired bare specifier', { timeout: 60_000 }, async () => {
const { bareImporters } = await scanStorageImports();
assert.deepEqual(
bareImporters,
[],
'bare `@maka/storage` imports resolve to the removed `.` entrypoint and fail at runtime',
);
});
test('published entrypoints and their consumers match exactly', { timeout: 60_000 }, async () => {
const exports = await publishedEntrypoints();
const { subpathImporters, externalSubpaths } = await scanStorageImports();
const unpublished = [...subpathImporters.keys()].filter((subpath) => !(subpath in exports));
assert.deepEqual(unpublished.sort(), [], 'imported subpaths missing from the exports map');
const unconsumed = Object.keys(exports).filter((subpath) => !externalSubpaths.has(subpath));
assert.deepEqual(
unconsumed.sort(),
PREEXISTING_UNCONSUMED_ENTRYPOINTS,
'each published subpath is a compatibility promise — publish it when a consumer exists',
);
});
/** Caps concurrent probe children at `limit`; the outer test runner is already concurrent. */
async function mapWithConcurrency<Item, Result>(
items: Item[],
limit: number,
task: (item: Item) => Promise<Result>,
): Promise<Result[]> {
const results: Result[] = new Array(items.length);
let next = 0;
await Promise.all(
Array.from({ length: Math.min(limit, items.length) }, async () => {
while (next < items.length) {
const index = next;
next += 1;
results[index] = await task(items[index]);
}
}),
);
return results;
}
test('only the declared entrypoints load node:sqlite', { timeout: 120_000 }, async () => {
const exports = await publishedEntrypoints();
const results = await mapWithConcurrency(
Object.entries(exports),
4,
async ([subpath, target]) => ({
subpath,
sqlite: await loadsSqlite(target),
}),
);
const actual = results
.filter((entry) => entry.sqlite)
.map((entry) => entry.subpath)
.sort();
assert.deepEqual(actual, [...SQLITE_BACKED_ENTRYPOINTS].sort());
});
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,242 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, test } from 'node:test';
import { MAX_READ_IMAGE_BYTES } from '@maka/core/attachments';
import { ReadImageSnapshotStoreError, type ContextOffloadLimits } from '@maka/core/context-offload';
import {
createInteractiveContextOffloadReader,
openInteractiveContextOffloadStoreForWrite,
type InteractiveContextOffloadWriter,
} from '../context-offload-store.js';
import {
createReadImageSnapshotReader,
createReadImageSnapshotStore,
} from '../read-image-snapshot-store.js';
import {
resolveStorageRoot,
tryAcquireInteractiveRootOwner,
type InteractiveRootOwner,
} from '../root-authority.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
after(removeTrackedControlDirectories);
test('derives Read image storage only from an authentic context writer', () => {
assert.throws(
() => createReadImageSnapshotStore({} as InteractiveContextOffloadWriter, 'session-1'),
/authentic interactive context-offload writer/u,
);
});
test('snapshots one stable Read image identity and authorizes reads by Session', async () => {
await withReadImageStore(defaultLimits(), async (images, writer) => {
const bytes = new TextEncoder().encode('image');
const input = {
ownerId: 'read-call-1',
bytes,
mimeType: 'image/png',
};
const snapshotting = images.snapshot(input);
input.ownerId = 'mutated-owner';
input.mimeType = 'image/jpeg';
bytes.fill(0x78);
const ref = await snapshotting;
assert.deepEqual(ref, {
kind: 'session_context',
sessionId: 'session-1',
refId: ref.refId,
});
assert.deepEqual(
await images.snapshot({
ownerId: 'read-call-1',
bytes: new TextEncoder().encode('image'),
mimeType: 'image/png',
}),
ref,
);
const read = await images.read(ref);
assert.equal(read.ok, true);
if (!read.ok) return;
assert.equal(read.record.owner.kind, 'read_image_snapshot');
assert.equal(read.record.owner.ownerId, 'read-call-1');
assert.equal(read.record.mediaType, 'image/png');
assert.deepEqual(read.bytes, new TextEncoder().encode('image'));
const reader = createReadImageSnapshotReader(
createInteractiveContextOffloadReader(writer),
'session-1',
);
assert.deepEqual(await reader.read(ref), read);
assert.deepEqual(Object.keys(reader), ['read']);
assert.deepEqual(await images.read({ ...ref, sessionId: 'session-2' }), {
ok: false,
reason: 'session_mismatch',
});
const sessionTwoImages = createReadImageSnapshotStore(writer, 'session-2');
assert.deepEqual(await sessionTwoImages.read(ref), {
ok: false,
reason: 'session_mismatch',
});
await assert.rejects(
images.snapshot({
ownerId: 'read-call-1',
bytes: new TextEncoder().encode('changed'),
mimeType: 'image/png',
}),
(error) =>
error instanceof ReadImageSnapshotStoreError && error.reason === 'identity_conflict',
);
await assert.rejects(
images.snapshot({
ownerId: 'read-call-1',
bytes: new TextEncoder().encode('image'),
mimeType: 'image/jpeg',
}),
(error) =>
error instanceof ReadImageSnapshotStoreError && error.reason === 'identity_conflict',
);
await assert.rejects(
images.snapshot({
ownerId: 'not-an-image',
bytes: new Uint8Array([1]),
mimeType: 'text/plain',
}),
/media type must be an image/u,
);
});
});
test('maps configured quota failures and rejects non-image owner references', async () => {
await withReadImageStore(
{
ownerMaxBytes: {
read_image_snapshot: 4,
tool_result_archive: 64,
},
sessionLogicalBytes: 64,
workspacePhysicalBytes: 64,
},
async (images, writer) => {
await assert.rejects(
images.snapshot({
ownerId: 'over-configured-limit',
bytes: new Uint8Array(5),
mimeType: 'image/png',
}),
(error) => error instanceof ReadImageSnapshotStoreError && error.reason === 'too_large',
);
const archive = await writer.put({
sessionId: 'session-1',
owner: { kind: 'tool_result_archive', ownerId: 'archive-1' },
bytes: new TextEncoder().encode('{}'),
mediaType: 'application/json',
});
assert.equal(archive.ok, true);
if (!archive.ok) return;
assert.deepEqual(
await images.read({
kind: 'session_context',
sessionId: 'session-1',
refId: archive.record.refId,
}),
{ ok: false, reason: 'corrupt' },
);
},
);
});
test('enforces the Read image product cap before touching storage', async () => {
const limits: ContextOffloadLimits = {
ownerMaxBytes: {
read_image_snapshot: MAX_READ_IMAGE_BYTES + 1,
tool_result_archive: 64,
},
sessionLogicalBytes: MAX_READ_IMAGE_BYTES + 1,
workspacePhysicalBytes: MAX_READ_IMAGE_BYTES + 1,
};
await withReadImageStore(limits, async (images, writer) => {
await assert.rejects(
images.snapshot({
ownerId: 'over-product-limit',
bytes: new Uint8Array(MAX_READ_IMAGE_BYTES + 1),
mimeType: 'image/png',
}),
(error) => error instanceof ReadImageSnapshotStoreError && error.reason === 'too_large',
);
assert.deepEqual(await writer.usage(), {
references: 0,
logicalBytes: 0,
physicalBytes: 0,
});
});
});
function defaultLimits(): ContextOffloadLimits {
return {
ownerMaxBytes: {
read_image_snapshot: MAX_READ_IMAGE_BYTES,
tool_result_archive: 64,
},
sessionLogicalBytes: MAX_READ_IMAGE_BYTES * 2,
workspacePhysicalBytes: MAX_READ_IMAGE_BYTES * 2,
};
}
async function withReadImageStore(
limits: ContextOffloadLimits,
run: (
images: ReturnType<typeof createReadImageSnapshotStore>,
writer: InteractiveContextOffloadWriter,
) => Promise<void>,
): Promise<void> {
await withInteractiveOwner(async (owner) => {
const writer = await openInteractiveContextOffloadStoreForWrite(owner.lease, { limits });
try {
await run(createReadImageSnapshotStore(writer, 'session-1'), writer);
} finally {
await writer.close();
}
});
}
async function withInteractiveOwner(run: (owner: InteractiveRootOwner) => Promise<void>) {
const root = await mkdtemp(join(tmpdir(), 'maka-read-image-context-store-'));
const capability = trackControlDirectory(
await resolveStorageRoot({ path: root, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
await run(owner);
} finally {
await owner.close();
await rm(root, { recursive: true, force: true });
}
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,122 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import type { RootExecutionDescriptor } from '@maka/core/agent-run';
import { createSqliteAgentRunStore, type AdmitRootTurnInput } from '../agent-run-store.js';
test('regenerate admission durably binds the immutable source Turn', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-regenerate-admission-'));
try {
const store = createSqliteAgentRunStore(root);
const input = admissionInput();
const admitted = await store.admitRootTurn(input);
assert.equal(admitted.kind, 'admitted');
assert.deepEqual(admitted.admission.execution, {
kind: 'regenerate',
sourceTurnId: 'source-turn',
});
store.close?.();
const reopened = createSqliteAgentRunStore(root);
assert.deepEqual(
await reopened.readRootTurnAdmission(input.sessionId, input.turnId),
admitted.admission,
);
await assert.rejects(
() =>
reopened.admitRootTurn(
admissionInput({
execution: {
kind: 'regenerate',
sourceTurnId: ' source-turn ',
} as RootExecutionDescriptor,
}),
),
/Invalid root execution descriptor/,
);
await assert.rejects(
() =>
reopened.admitRootTurn(
admissionInput({
execution: { kind: 'regenerate', sourceTurnId: 'regenerated-turn' },
}),
),
/regenerate source Turn cannot be the admitted Turn/,
);
const compact = await reopened.admitRootTurn({
sessionId: input.sessionId,
turnId: 'compact-turn',
proposedRunId: 'compact-run',
proposedUserMessageId: null,
execution: { kind: 'context_compact' },
previousRootTurnId: input.turnId,
normalizedInput: null,
sourceMessages: [],
admittedAt: 60,
});
assert.equal(compact.kind, 'admitted');
assert.deepEqual(compact.admission.execution, { kind: 'context_compact' });
reopened.close?.();
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('new root admissions reject removed Automation authority', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-legacy-automation-admission-'));
try {
const store = createSqliteAgentRunStore(root);
await assert.rejects(
() =>
store.admitRootTurn(
admissionInput({
execution: {
kind: 'legacy_automation',
automationId: 'automation-1',
} as RootExecutionDescriptor,
}),
),
/removed Automation authority/,
);
store.close?.();
} finally {
await rm(root, { recursive: true, force: true });
}
});
function admissionInput(overrides: Partial<AdmitRootTurnInput> = {}): AdmitRootTurnInput {
return {
sessionId: 'root-session',
turnId: 'regenerated-turn',
proposedRunId: 'regenerated-run',
proposedUserMessageId: 'regenerated-message',
execution: { kind: 'regenerate', sourceTurnId: 'source-turn' },
previousRootTurnId: null,
normalizedInput: { text: 'Original request' },
sourceMessages: [],
admittedAt: 50,
...overrides,
};
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,103 @@
/*
* 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 assert from 'node:assert/strict';
import { test } from 'node:test';
import { normalizeRootTurnAdmissionPayload } from '../agent-run-store.js';
test('root admission preserves an explicit empty inline-reference marker from its sources', () => {
const content = { text: 'plain', inlineReferences: [] } as const;
const normalized = normalizeRootTurnAdmissionPayload(content, [
{
messageId: 'message-1',
content,
placement: 'next_turn',
disposition: 'followup',
},
]);
assert.deepEqual(normalized.normalizedInput, content);
assert.deepEqual(normalized.sourceMessages[0]?.content, content);
});
test('root admission preserves and validates each source submission digest', () => {
const digest = `sha256:${'a'.repeat(64)}` as const;
const source = {
messageId: 'message-1',
content: { text: 'prepared', displayText: 'submitted' },
submittedContentDigest: digest,
placement: 'next_turn' as const,
disposition: 'followup' as const,
};
const normalized = normalizeRootTurnAdmissionPayload(source.content, [source]);
assert.equal(normalized.sourceMessages[0]?.submittedContentDigest, digest);
assert.throws(() =>
normalizeRootTurnAdmissionPayload(source.content, [
{ ...source, submittedContentDigest: 'sha256:not-a-digest' },
]),
);
});
test('root admission preserves and validates each source submitted placement', () => {
const content = { text: 'promoted follow-up' } as const;
const source = {
messageId: 'promoted-message',
content,
submittedPlacement: 'next_turn' as const,
placement: 'current_turn' as const,
disposition: 'steering' as const,
};
assert.equal(
normalizeRootTurnAdmissionPayload(content, [source]).sourceMessages[0]?.submittedPlacement,
'next_turn',
);
assert.throws(() =>
normalizeRootTurnAdmissionPayload(content, [
{ ...source, submittedPlacement: 'invalid-placement' },
]),
);
});
test('root admission preserves and validates each source Skill outcome', () => {
const content = { text: 'prepared', displayText: '/skill:writer draft' } as const;
const skillInvocation = {
loaded: [{ id: 'writer', name: 'Writer' }],
failed: [{ request: 'typo', reason: 'not_found' as const }],
receipts: [],
};
const source = {
messageId: 'message-skill',
content,
skillInvocation,
placement: 'next_turn' as const,
disposition: 'followup' as const,
};
assert.deepEqual(
normalizeRootTurnAdmissionPayload(content, [source]).sourceMessages[0]?.skillInvocation,
skillInvocation,
);
assert.throws(() =>
normalizeRootTurnAdmissionPayload(content, [
{ ...source, skillInvocation: { loaded: [], failed: [], receipts: 'invalid' } },
]),
);
});
@@ -0,0 +1,349 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import test from 'node:test';
import { RuntimePolicyCoordinator } from '../runtime-policy/coordinator.js';
test('runtime policy catalog overlays enabled custom model facts without changing the raw catalog', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-runtime-facts-'));
try {
const coordinator = new RuntimePolicyCoordinator((operation) => operation(root));
const created = await coordinator.createConnection({
expectedCatalogRevision: 0,
connection: {
slug: 'custom-openai',
name: 'Custom OpenAI',
providerType: 'ollama',
enabled: true,
enabledModelIds: ['custom-model'],
},
});
assert.equal(created.kind, 'committed');
assert.equal(Object.isFrozen(created), true);
if (created.kind === 'committed') assert.equal(Object.isFrozen(created.snapshot), true);
await writeModelFacts(root, { 'ollama:custom-model': { contextWindow: 64_000 } });
const snapshot = await coordinator.getCatalogSnapshot();
const model = snapshot.connections[0]?.models.find(
(candidate) => candidate.id === 'custom-model',
);
assert.equal(model?.contextWindow, 64_000);
const prepared = await coordinator.beginConnectionTest(
snapshot.connections[0]!.connectionId,
null,
);
assert.equal(prepared.kind, 'ready');
if (prepared.kind === 'ready') {
const tested = await coordinator.completeConnectionTest(prepared.ticket, {
status: 'verified',
checkedAt: '2026-08-01T00:00:00.000Z',
});
assert.equal(tested.kind, 'committed');
}
assert.equal(
(await coordinator.getCatalogSnapshot()).connections[0]?.lastTest?.status,
'verified',
);
const restarted = new RuntimePolicyCoordinator((operation) => operation(root));
const persisted = await restarted.getCatalogSnapshot();
assert.equal(
persisted.connections[0]?.models.find((candidate) => candidate.id === 'custom-model')
?.contextWindow,
64_000,
);
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('legacy connection verification survives unrelated model facts overrides', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-runtime-facts-legacy-verification-'));
try {
const coordinator = new RuntimePolicyCoordinator((operation) => operation(root));
const connectionId = await createTestConnection(coordinator);
const prepared = await coordinator.beginConnectionTest(connectionId, null);
assert.equal(prepared.kind, 'ready');
if (prepared.kind === 'ready') {
assert.equal(
(
await coordinator.completeConnectionTest(
prepared.ticket,
verifiedAt('2026-08-01T00:00:00.000Z'),
)
).kind,
'committed',
);
}
const catalogPath = join(root, 'connection-catalog.json');
const catalog = JSON.parse(await readFile(catalogPath, 'utf8')) as {
connections: Array<Record<string, unknown>>;
};
delete catalog.connections[0]!.lastTestModelFactsFingerprint;
await writeFile(catalogPath, `${JSON.stringify(catalog)}\n`, 'utf8');
await writeModelFacts(root, { 'openai:unrelated-model': { contextWindow: 64_000 } });
assert.equal(
(await coordinator.getCatalogSnapshot()).connections[0]?.lastTest?.status,
'verified',
);
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('display-only model facts preserve verification and in-flight tests', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-runtime-facts-display-only-'));
try {
const coordinator = new RuntimePolicyCoordinator((operation) => operation(root));
const connectionId = await createTestConnection(coordinator);
const initial = await coordinator.beginConnectionTest(connectionId, null);
assert.equal(initial.kind, 'ready');
if (initial.kind !== 'ready') return;
assert.equal(
(
await coordinator.completeConnectionTest(
initial.ticket,
verifiedAt('2026-08-01T00:00:00.000Z'),
)
).kind,
'committed',
);
const inFlight = await coordinator.beginConnectionTest(connectionId, null);
assert.equal(inFlight.kind, 'ready');
await writeModelFacts(root, { 'ollama:custom-model': { displayName: 'Friendly name' } });
assert.equal(
(await coordinator.getCatalogSnapshot()).connections[0]?.lastTest?.status,
'verified',
);
if (inFlight.kind === 'ready') {
assert.equal(
(
await coordinator.completeConnectionTest(
inFlight.ticket,
verifiedAt('2026-08-01T00:01:00.000Z'),
)
).kind,
'committed',
);
}
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('model fetch keeps an enabled facts-backed model outside provider inventory', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-runtime-facts-refresh-'));
try {
const coordinator = new RuntimePolicyCoordinator((operation) => operation(root));
const connectionId = await createTestConnection(coordinator);
await writeModelFacts(root, {
'ollama:custom-model': { contextWindow: 64_000 },
'ollama:unselected-model': { contextWindow: 128_000 },
});
const beforeRefresh = await coordinator.getCatalogSnapshot();
const defaulted = await coordinator.setDefaultTarget({
expectedCatalogRevision: beforeRefresh.revision,
target: { connectionId, modelId: 'custom-model' },
});
assert.equal(defaulted.kind, 'committed');
const fetch = await coordinator.beginModelFetch(connectionId);
assert.equal(fetch.kind, 'ready');
if (fetch.kind !== 'ready') return;
const refreshed = await coordinator.completeModelFetch(fetch.ticket, {
models: [{ id: 'live-model' }],
source: 'fetched',
fetchedAt: 1,
});
assert.equal(refreshed.kind, 'committed');
if (refreshed.kind !== 'committed') return;
const raw = await (
coordinator as unknown as {
catalog: {
read(root: string): Promise<{
connections: readonly { models: readonly unknown[] }[];
}>;
};
}
).catalog.read(root);
assert.deepEqual(raw.connections[0]?.models, [{ id: 'live-model' }]);
const projected = refreshed.snapshot.connections[0];
assert.deepEqual(projected?.enabledModelIds, ['custom-model']);
assert.deepEqual(refreshed.snapshot.defaultTarget, {
connectionId,
modelId: 'custom-model',
});
assert.equal(
projected?.models.find((model) => model.id === 'custom-model')?.contextWindow,
64_000,
);
assert.equal(
projected?.models.some((model) => model.id === 'unselected-model'),
false,
);
const execution = await coordinator.resolveExecutionConnection({
kind: 'catalog_slug',
connectionSlug: 'custom-openai',
});
assert.equal(execution.kind, 'ready');
if (execution.kind === 'ready') {
assert.equal(
execution.connection.models?.some((model) => model.id === 'custom-model'),
true,
);
}
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('model fetch keeps enabled facts-backed models when provider inventory fills the bound', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-runtime-facts-refresh-bound-'));
try {
const coordinator = new RuntimePolicyCoordinator((operation) => operation(root));
const connectionId = await createTestConnection(coordinator);
await writeModelFacts(root, { 'ollama:custom-model': { contextWindow: 64_000 } });
const fetch = await coordinator.beginModelFetch(connectionId);
assert.equal(fetch.kind, 'ready');
if (fetch.kind !== 'ready') return;
const refreshed = await coordinator.completeModelFetch(fetch.ticket, {
models: Array.from({ length: 2_048 }, (_, index) => ({ id: `live-model-${index}` })),
source: 'fetched',
fetchedAt: 1,
});
assert.equal(refreshed.kind, 'committed');
if (refreshed.kind !== 'committed') return;
const projected = refreshed.snapshot.connections[0];
assert.equal(projected?.models.length, 2_048);
assert.equal(projected?.models.at(-1)?.id, 'custom-model');
assert.equal(projected?.models.at(-1)?.contextWindow, 64_000);
assert.equal(
projected?.models.some((model) => model.id === 'live-model-2047'),
false,
);
const execution = await coordinator.resolveExecutionConnection({
kind: 'catalog_slug',
connectionSlug: 'custom-openai',
});
assert.equal(execution.kind, 'ready');
if (execution.kind === 'ready') {
const model = execution.connection.models?.find((entry) => entry.id === 'custom-model');
assert.equal(model?.contextWindow, 64_000);
}
} finally {
await rm(root, { recursive: true, force: true });
}
});
test('protocol model facts edits clear verification, supersede tickets, and warn on malformed input', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-runtime-facts-external-edit-'));
const emitWarning = process.emitWarning;
const warnings: string[] = [];
process.emitWarning = ((warning: string | Error) => {
warnings.push(String(warning));
}) as typeof process.emitWarning;
try {
const coordinator = new RuntimePolicyCoordinator((operation) => operation(root));
const connectionId = await createTestConnection(coordinator);
await writeModelFacts(root, { 'ollama:custom-model': { contextWindow: 64_000 } });
const verified = await coordinator.beginConnectionTest(connectionId, null);
assert.equal(verified.kind, 'ready');
if (verified.kind === 'ready') {
assert.equal(
(
await coordinator.completeConnectionTest(
verified.ticket,
verifiedAt('2026-08-01T00:00:00.000Z'),
)
).kind,
'committed',
);
}
const ticket = await coordinator.beginConnectionTest(connectionId, null);
assert.equal(ticket.kind, 'ready');
await writeFile(
join(root, 'model-facts.json'),
JSON.stringify({
schemaVersion: 1,
overrides: { 'ollama:custom-model': { apiProtocol: 'openai-responses' } },
}),
'utf8',
);
if (ticket.kind === 'ready') {
assert.deepEqual(
await coordinator.completeConnectionTest(
ticket.ticket,
verifiedAt('2026-08-01T00:01:00.000Z'),
),
{ kind: 'superseded', changed: ['connection'] },
);
}
assert.equal((await coordinator.getCatalogSnapshot()).connections[0]?.lastTest, undefined);
await writeFile(join(root, 'model-facts.json'), '{not-json}', 'utf8');
const snapshot = await coordinator.getCatalogSnapshot();
assert.equal(
snapshot.connections[0]?.models.find((model) => model.id === 'custom-model')?.contextWindow,
undefined,
);
assert.equal(
warnings.some((warning) => warning.includes('model-facts.json')),
true,
);
} finally {
process.emitWarning = emitWarning;
await rm(root, { recursive: true, force: true });
}
});
async function createTestConnection(coordinator: RuntimePolicyCoordinator): Promise<string> {
const created = await coordinator.createConnection({
expectedCatalogRevision: 0,
connection: {
slug: 'custom-openai',
name: 'Custom OpenAI',
providerType: 'ollama',
enabled: true,
enabledModelIds: ['custom-model'],
},
});
assert.equal(created.kind, 'committed');
if (created.kind !== 'committed') throw new Error('Expected connection creation to commit');
return created.snapshot.connections[0]!.connectionId;
}
function verifiedAt(checkedAt: string) {
return { status: 'verified' as const, checkedAt };
}
async function writeModelFacts(root: string, overrides: Record<string, unknown>): Promise<void> {
await writeFile(
join(root, 'model-facts.json'),
JSON.stringify({ schemaVersion: 1, overrides }),
'utf8',
);
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,329 @@
/*
* 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 assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
import { test } from 'node:test';
import {
compareSessionBundleCanonicalPaths,
computeSessionBundleCanonicalTreeDigest,
encodeSessionBundleCanonicalTree,
SessionBundleCanonicalTreeDigestBuilder,
type SessionBundleCanonicalTreeEntry,
} from '../session-bundle-canonical-tree.js';
import { SessionBundleFileError, type Sha256Digest } from '../session-bundle-contract.js';
const identityDigest: Sha256Digest =
'sha256:0e9561cfb83d50990a103b3896fe249a11fe27fa28985448187f93ec12116d72';
const executableDigest: Sha256Digest =
'sha256:b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c';
const emptyDigest = `sha256:${createHash('sha256').update('').digest('hex')}` as Sha256Digest;
const canonicalEntries: readonly SessionBundleCanonicalTreeEntry[] = [
{
kind: 'file',
path: 'state-identity.json',
mode: 0o644,
size: 19,
contentDigest: identityDigest,
},
{ kind: 'directory', path: 'state/' },
{ kind: 'directory', path: 'state/empty/' },
{ kind: 'directory', path: 'workspace/' },
{
kind: 'file',
path: 'workspace/run.sh',
mode: 0o755,
size: 18,
contentDigest: executableDigest,
},
];
const unsortedEntries: readonly SessionBundleCanonicalTreeEntry[] = [
canonicalEntries[3],
canonicalEntries[0],
canonicalEntries[2],
canonicalEntries[4],
canonicalEntries[1],
];
const expectedTreeHex = [
'4d414b415f53455353494f4e5f42554e444c455f5452454500',
'00000001',
'0000000000000005',
'02',
'00000013',
'73746174652d6964656e746974792e6a736f6e',
'01a4',
'0000000000000013',
'0e9561cfb83d50990a103b3896fe249a11fe27fa28985448187f93ec12116d72',
'01',
'00000006',
'73746174652f',
'01ed',
'0000000000000000',
'0000000000000000000000000000000000000000000000000000000000000000',
'01',
'0000000c',
'73746174652f656d7074792f',
'01ed',
'0000000000000000',
'0000000000000000000000000000000000000000000000000000000000000000',
'01',
'0000000a',
'776f726b73706163652f',
'01ed',
'0000000000000000',
'0000000000000000000000000000000000000000000000000000000000000000',
'02',
'00000010',
'776f726b73706163652f72756e2e7368',
'01ed',
'0000000000000012',
'b4d644d4279594903f1a9911956432d9473041f2984fc6014c14d7402c7d126c',
].join('');
const expectedTreeDigest =
'sha256:429f57cded2f9a22620adc7da0ad9d33eb1c690f8ded102042e7c6904c70d0df';
test('pins exact canonical tree-record bytes and SHA-256 digest', () => {
const encoded = encodeSessionBundleCanonicalTree(unsortedEntries);
assert.equal(Buffer.from(encoded).toString('hex'), expectedTreeHex);
assert.equal(encoded.byteLength, 335);
assert.equal(`sha256:${createHash('sha256').update(encoded).digest('hex')}`, expectedTreeDigest);
assert.deepEqual(computeSessionBundleCanonicalTreeDigest(unsortedEntries), {
treeDigest: expectedTreeDigest,
payloadBytes: 37,
entryCount: 5,
});
});
test('incrementally hashes the same stream without retaining file bytes', () => {
const builder = new SessionBundleCanonicalTreeDigestBuilder(canonicalEntries.length);
for (const entry of canonicalEntries) builder.add(entry);
assert.deepEqual(builder.finish(), {
treeDigest: expectedTreeDigest,
payloadBytes: 37,
entryCount: 5,
});
assert.deepEqual(builder.finish(), {
treeDigest: expectedTreeDigest,
payloadBytes: 37,
entryCount: 5,
});
assertBundleError(() => builder.add(canonicalEntries[0]), 'integrity_mismatch');
const incomplete = new SessionBundleCanonicalTreeDigestBuilder(canonicalEntries.length + 1);
for (const entry of canonicalEntries) incomplete.add(entry);
assertBundleError(() => incomplete.finish(), 'integrity_mismatch');
});
test('preserves raw UTF-8 path bytes without Unicode normalization', () => {
const decomposed = 'state/e\u0301.txt';
const composed = 'state/é.txt';
assert.ok(compareSessionBundleCanonicalPaths(decomposed, composed) < 0);
const result = computeSessionBundleCanonicalTreeDigest([
...canonicalEntries.filter((entry) => entry.path !== 'state/empty/'),
{
kind: 'file',
path: composed,
mode: 0o644,
size: 0,
contentDigest: emptyDigest,
},
{
kind: 'file',
path: decomposed,
mode: 0o644,
size: 0,
contentDigest: emptyDigest,
},
]);
assert.equal(result.entryCount, 6);
assert.notEqual(result.treeDigest, expectedTreeDigest);
});
test('makes empty directories and executable semantics digest-significant', () => {
const withoutEmptyDirectory = canonicalEntries.filter((entry) => entry.path !== 'state/empty/');
const nonExecutable = canonicalEntries.map((entry) =>
entry.kind === 'file' && entry.path === 'workspace/run.sh'
? { ...entry, mode: 0o644 as const }
: entry,
);
assert.notEqual(
computeSessionBundleCanonicalTreeDigest(withoutEmptyDirectory).treeDigest,
expectedTreeDigest,
);
assert.notEqual(
computeSessionBundleCanonicalTreeDigest(nonExecutable).treeDigest,
expectedTreeDigest,
);
});
test('rejects traversal, host path syntax, invalid Unicode, and paths outside V1 roots', () => {
for (const path of [
'/state/file',
'C:/state/file',
'state\\file',
'state/../secret',
'state/./file',
'state//file',
'state/\ud800',
'other/file',
]) {
assertBundleError(
() =>
computeSessionBundleCanonicalTreeDigest([
...canonicalEntries,
{
kind: 'file',
path,
mode: 0o644,
size: 0,
contentDigest: emptyDigest,
},
]),
'unsafe_path',
);
}
});
test('rejects duplicate, conflicting, orphaned, and incomplete payload trees', () => {
assertBundleError(
() => computeSessionBundleCanonicalTreeDigest([...canonicalEntries, canonicalEntries[1]]),
'unsafe_path',
);
assertBundleError(
() =>
computeSessionBundleCanonicalTreeDigest([
...canonicalEntries,
{
kind: 'file',
path: 'state/empty',
mode: 0o644,
size: 0,
contentDigest: emptyDigest,
},
]),
'unsafe_path',
);
assertBundleError(
() =>
computeSessionBundleCanonicalTreeDigest([
...canonicalEntries,
{
kind: 'file',
path: 'state/missing/file',
mode: 0o644,
size: 0,
contentDigest: emptyDigest,
},
]),
'unsafe_path',
);
assertBundleError(
() =>
computeSessionBundleCanonicalTreeDigest(
canonicalEntries.filter((entry) => entry.path !== 'workspace/'),
),
'unsafe_path',
);
});
test('rejects non-normalized file metadata and an out-of-order streaming source', () => {
for (const entry of [
{
kind: 'file',
path: 'state/private',
mode: 0o600,
size: 0,
contentDigest: emptyDigest,
},
{
kind: 'file',
path: 'state/bad-digest',
mode: 0o644,
size: 0,
contentDigest: `sha256:${'AB'.repeat(32)}`,
},
{
kind: 'file',
path: 'state-identity.json',
mode: 0o755,
size: 19,
contentDigest: identityDigest,
},
]) {
assertBundleError(
() =>
computeSessionBundleCanonicalTreeDigest([
...canonicalEntries.filter(
(candidate) =>
candidate.path !== (entry.path === 'state-identity.json' ? entry.path : ''),
),
entry as unknown as SessionBundleCanonicalTreeEntry,
]),
'unsupported_entry',
);
}
const builder = new SessionBundleCanonicalTreeDigestBuilder(canonicalEntries.length);
builder.add(canonicalEntries[1]);
assertBundleError(() => builder.add(canonicalEntries[0]), 'unsafe_path');
assertBundleError(() => builder.finish(), 'integrity_mismatch');
});
test('fails closed after aggregate payload size overflows', () => {
const builder = new SessionBundleCanonicalTreeDigestBuilder(4);
builder.add({
kind: 'file',
path: 'state-identity.json',
mode: 0o644,
size: Number.MAX_SAFE_INTEGER,
contentDigest: identityDigest,
});
builder.add({ kind: 'directory', path: 'state/' });
assertBundleError(
() =>
builder.add({
kind: 'file',
path: 'state/file',
mode: 0o644,
size: 1,
contentDigest: emptyDigest,
}),
'unsupported_entry',
);
assertBundleError(
() => builder.add({ kind: 'directory', path: 'workspace/' }),
'integrity_mismatch',
);
assertBundleError(() => builder.finish(), 'integrity_mismatch');
});
function assertBundleError(action: () => unknown, code: SessionBundleFileError['code']): void {
assert.throws(action, (error) => {
assert.ok(error instanceof SessionBundleFileError);
assert.equal(error.code, code);
return true;
});
}
@@ -0,0 +1,148 @@
/*
* 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 assert from 'node:assert/strict';
import { test } from 'node:test';
import {
assertSessionBundleLimits,
copyOpaqueStateIdentityDescriptor,
isSha256Digest,
isValidUnicodeString,
SESSION_BUNDLE_LIMIT_NAMES,
SessionBundleFileError,
type SessionBundleLimits,
} from '../session-bundle-contract.js';
const limits: SessionBundleLimits = {
maxCompressedBytes: 0,
maxDecompressedTarBytes: 0,
maxPayloadBytes: 0,
maxFileBytes: 0,
maxEntryCount: 0,
maxManifestBytes: 0,
maxStateIdentityBytes: 0,
maxPathBytes: 0,
maxPathDepth: 0,
};
test('exposes strict lowercase SHA-256 digest validation', () => {
const digest = `sha256:${'ab'.repeat(32)}`;
assert.equal(isSha256Digest(digest), true);
assert.equal(isSha256Digest(`sha256:${'AB'.repeat(32)}`), false);
assert.equal(isSha256Digest(`sha256:${'ab'.repeat(31)}`), false);
assert.equal(isSha256Digest(`sha512:${'ab'.repeat(32)}`), false);
assert.equal(isSha256Digest(42), false);
});
test('validates Unicode strings safely at the runtime boundary', () => {
assert.equal(isValidUnicodeString('session-🚀'), true);
assert.equal(isValidUnicodeString('\ud800'), false);
assert.equal(isValidUnicodeString('\udc00'), false);
assert.equal(isValidUnicodeString(42), false);
assert.equal(isValidUnicodeString(null), false);
assert.equal(isValidUnicodeString({}), false);
});
test('requires every explicit quota while permitting a fail-closed zero budget', () => {
assert.doesNotThrow(() => assertSessionBundleLimits(limits));
assert.deepEqual([...SESSION_BUNDLE_LIMIT_NAMES].sort(), Object.keys(limits).sort());
const missing = { ...limits } as Record<string, number>;
delete missing.maxPathDepth;
assert.throws(
() => assertSessionBundleLimits(missing as unknown as SessionBundleLimits),
TypeError,
);
assert.throws(
() =>
assertSessionBundleLimits({
...limits,
maxPathDepth: -1,
}),
RangeError,
);
assert.throws(
() =>
assertSessionBundleLimits({
...limits,
maxPathDepth: 1.5,
}),
RangeError,
);
assert.throws(
() =>
assertSessionBundleLimits({
...limits,
unexpected: 1,
} as SessionBundleLimits),
TypeError,
);
});
test('copies opaque state identity bytes without interpreting or aliasing them', () => {
const source = new Uint8Array([0, 255, 123, 34, 0, 10]);
const copied = copyOpaqueStateIdentityDescriptor({
mediaType: 'application/vnd.maka.session-state-identity+json;version=1',
bytes: source,
});
assert.equal(copied.mediaType, 'application/vnd.maka.session-state-identity+json;version=1');
assert.deepEqual(copied.bytes, source);
assert.notEqual(copied.bytes, source);
source[0] = 99;
assert.equal(copied.bytes[0], 0);
assert.throws(
() => copyOpaqueStateIdentityDescriptor(null as unknown as typeof copied),
TypeError,
);
assert.throws(
() =>
copyOpaqueStateIdentityDescriptor({
mediaType: '\ud800',
bytes: new Uint8Array(),
}),
TypeError,
);
});
test('keeps stable bundle failures bounded and preserves their causes', () => {
const cause = new Error('filesystem failure');
const error = new SessionBundleFileError('io_failure', 'Session bundle I/O failed', {
cause,
details: {
operation: 'inspect',
quota: 'maxCompressedBytes',
limit: 10,
observed: 11,
},
});
assert.equal(error.name, 'SessionBundleFileError');
assert.equal(error.code, 'io_failure');
assert.equal(error.cause, cause);
assert.deepEqual(error.details, {
operation: 'inspect',
quota: 'maxCompressedBytes',
limit: 10,
observed: 11,
});
assert.equal(Object.isFrozen(error.details), true);
});
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,221 @@
/*
* 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 assert from 'node:assert/strict';
import { test } from 'node:test';
import {
SessionBundleFileError,
type SessionBundleManifestV1,
} from '../session-bundle-contract.js';
import {
decodeSessionBundleManifestV1,
encodeSessionBundleManifestV1,
} from '../session-bundle-manifest.js';
const manifest: SessionBundleManifestV1 = {
schemaVersion: 1,
codec: {
name: 'maka-session-bundle',
version: 1,
canonicalizationVersion: 1,
archive: 'ustar',
compression: 'zstd',
compressionLevel: 3,
},
envelope: {
sessionId: 'cloud-session-α',
lastCommittedActivationId: 'activation-7',
},
stateIdentity: {
path: 'state-identity.json',
mediaType: 'application/vnd.maka.session-state-identity+json;version=1',
},
payload: {
statePath: 'state/',
workspacePath: 'workspace/',
treeDigest: `sha256:${'ab'.repeat(32)}`,
payloadBytes: 37,
entryCount: 5,
},
};
const canonicalManifestText =
`{"codec":{"archive":"ustar","canonicalizationVersion":1,"compression":"zstd",` +
`"compressionLevel":3,"name":"maka-session-bundle","version":1},` +
`"envelope":{"lastCommittedActivationId":"activation-7","sessionId":"cloud-session-α"},` +
`"payload":{"entryCount":5,"payloadBytes":37,"statePath":"state/",` +
`"treeDigest":"sha256:${'ab'.repeat(32)}","workspacePath":"workspace/"},` +
`"schemaVersion":1,"stateIdentity":{"mediaType":` +
`"application/vnd.maka.session-state-identity+json;version=1","path":"state-identity.json"}}`;
test('pins canonical Manifest V1 UTF-8 bytes and round-trips them', () => {
const encoded = encodeSessionBundleManifestV1(manifest);
assert.equal(new TextDecoder().decode(encoded), canonicalManifestText);
assert.equal(encoded[0], '{'.charCodeAt(0));
assert.equal(encoded.at(-1), '}'.charCodeAt(0));
assert.deepEqual(decodeSessionBundleManifestV1(encoded), manifest);
});
test('omits optional Activation provenance instead of inventing authority', () => {
const withoutActivation: SessionBundleManifestV1 = {
...manifest,
envelope: { sessionId: manifest.envelope.sessionId },
};
const text = new TextDecoder().decode(encodeSessionBundleManifestV1(withoutActivation));
assert.match(text, /"envelope":\{"sessionId":"cloud-session-α"\}/);
assert.doesNotMatch(text, /lastCommittedActivationId/);
});
test('does not serialize inherited Activation provenance', () => {
const envelope = Object.assign(
Object.create({ lastCommittedActivationId: 'inherited-activation' }) as object,
{ sessionId: manifest.envelope.sessionId },
) as SessionBundleManifestV1['envelope'];
const encoded = encodeSessionBundleManifestV1({ ...manifest, envelope });
const text = new TextDecoder().decode(encoded);
assert.match(text, /"envelope":\{"sessionId":"cloud-session-α"\}/);
assert.doesNotMatch(text, /inherited-activation|lastCommittedActivationId/);
assert.deepEqual(decodeSessionBundleManifestV1(encoded).envelope, {
sessionId: manifest.envelope.sessionId,
});
});
test('rejects parseable but non-canonical manifest bytes', () => {
const nonCanonical = new TextEncoder().encode(JSON.stringify(manifest));
assertBundleError(() => decodeSessionBundleManifestV1(nonCanonical), 'invalid_manifest');
assertBundleError(
() => decodeSessionBundleManifestV1(new TextEncoder().encode(`${canonicalManifestText}\n`)),
'invalid_manifest',
);
assertBundleError(
() =>
decodeSessionBundleManifestV1(
Uint8Array.from([0xef, 0xbb, 0xbf, ...new TextEncoder().encode(canonicalManifestText)]),
),
'invalid_manifest',
);
assertBundleError(
() =>
decodeSessionBundleManifestV1(
new TextEncoder().encode(
canonicalManifestText.replace('"schemaVersion":1', '"schemaVersion":1,"schemaVersion":1'),
),
),
'invalid_manifest',
);
});
test('does not expose attacker-controlled parser diagnostics', () => {
assert.throws(
() =>
decodeSessionBundleManifestV1(
new TextEncoder().encode('SECRET_SESSION_TOKEN is not a JSON manifest'),
),
(error) => {
assert.ok(error instanceof SessionBundleFileError);
assert.equal(error.code, 'invalid_manifest');
assert.equal(error.cause, undefined);
assert.doesNotMatch(error.message, /SECRET_SESSION_TOKEN/);
return true;
},
);
});
test('rejects control-plane revision and fork authority fields', () => {
for (const extra of [
{ revision: 'r7' },
{ head: 'r7' },
{ forkedFrom: { sessionId: 'source', revision: 'r6' } },
]) {
assertBundleError(
() =>
encodeSessionBundleManifestV1({
...manifest,
...extra,
} as SessionBundleManifestV1),
'invalid_manifest',
);
}
});
test('distinguishes unsupported schema and codec versions from malformed manifests', () => {
assertBundleError(
() =>
encodeSessionBundleManifestV1({
...manifest,
schemaVersion: 2,
} as unknown as SessionBundleManifestV1),
'unsupported_schema',
);
assertBundleError(
() =>
encodeSessionBundleManifestV1({
...manifest,
codec: { ...manifest.codec, version: 2 },
} as unknown as SessionBundleManifestV1),
'unsupported_codec',
);
assertBundleError(
() =>
encodeSessionBundleManifestV1({
...manifest,
payload: {
...manifest.payload,
treeDigest: `sha256:${'AB'.repeat(32)}`,
},
} as SessionBundleManifestV1),
'invalid_manifest',
);
});
test('rejects unknown nested fields, invalid Unicode, and incomplete layouts', () => {
assertBundleError(
() =>
encodeSessionBundleManifestV1({
...manifest,
payload: { ...manifest.payload, revision: 'r7' },
} as SessionBundleManifestV1),
'invalid_manifest',
);
assertBundleError(
() =>
encodeSessionBundleManifestV1({
...manifest,
envelope: { sessionId: '\ud800' },
}),
'invalid_manifest',
);
assertBundleError(
() =>
encodeSessionBundleManifestV1({
...manifest,
payload: { ...manifest.payload, entryCount: 2 },
}),
'invalid_manifest',
);
});
function assertBundleError(action: () => unknown, code: SessionBundleFileError['code']): void {
assert.throws(action, (error) => {
assert.ok(error instanceof SessionBundleFileError);
assert.equal(error.code, code);
return true;
});
}
@@ -0,0 +1,195 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdir, mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { DatabaseSync } from 'node:sqlite';
import { test } from 'node:test';
import type { CreateSessionInput } from '@maka/core/runtime-inputs';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import { createSessionStore } from '../session-store.js';
import { exportSessionBundleState } from '../session-bundle-policy.js';
import { createSqliteRuntimeStore } from '../sqlite-runtime-store.js';
test('exports one Session as filtered SQLite', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-session-bundle-'));
const stateRoot = join(base, 'state');
const configRoot = join(base, 'config');
const destinationRoot = join(base, 'bundle');
await mkdir(configRoot, { recursive: true });
const sessions = createSessionStore(stateRoot);
try {
const selected = await sessions.create(input('Selected'));
const excluded = await sessions.create(input('Excluded'));
await sessions.appendMessage(selected.id, message('selected-message'));
await sessions.appendMessage(excluded.id, message('excluded-message'));
await sessions.close?.();
const sourceDatabase = new DatabaseSync(join(stateRoot, 'runtime.sqlite'));
sourceDatabase
.prepare('INSERT INTO usage_pricing_overrides(model_key, record_json) VALUES (?, ?)')
.run('private-model', '{}');
sourceDatabase.close();
const plan = await exportSessionBundleState({
stateRoot,
configRoot,
destinationRoot,
sessionId: selected.id,
});
assert.deepEqual(plan.includedEntries, ['runtime.sqlite']);
const database = new DatabaseSync(join(destinationRoot, 'runtime.sqlite'), { readOnly: true });
try {
const ids = database
.prepare('SELECT session_id FROM session_metadata ORDER BY session_id')
.all()
.map((row) => (row as { session_id: string }).session_id);
assert.deepEqual(ids, [selected.id]);
assert.equal(
(
database.prepare('SELECT COUNT(*) AS count FROM session_messages').get() as {
count: number;
}
).count,
1,
);
assert.equal(
(
database.prepare('SELECT COUNT(*) AS count FROM usage_pricing_overrides').get() as {
count: number;
}
).count,
0,
);
} finally {
database.close();
}
} finally {
await rm(base, { recursive: true, force: true });
}
});
test('retains only the selected Session partial stream segments', async () => {
const base = await mkdtemp(join(tmpdir(), 'maka-session-bundle-partials-'));
const stateRoot = join(base, 'state');
const configRoot = join(base, 'config');
const destinationRoot = join(base, 'bundle');
const databasePath = join(stateRoot, 'runtime.sqlite');
await mkdir(configRoot, { recursive: true });
const sessions = createSessionStore(stateRoot);
try {
const selected = await sessions.create(input('Selected'));
const excluded = await sessions.create(input('Excluded'));
await sessions.close?.();
const runtime = createSqliteRuntimeStore(databasePath);
try {
await runtime.appendRuntimeEvent(
selected.id,
'selected-run',
partialEvent(selected.id, 'selected-run', 'selected', 1, 'a'),
);
await runtime.appendRuntimeEvent(
selected.id,
'selected-run',
partialEvent(selected.id, 'selected-run', 'selected', 2, 'b'),
);
await runtime.appendRuntimeEvent(
excluded.id,
'excluded-run',
partialEvent(excluded.id, 'excluded-run', 'excluded', 3, 'secret'),
);
} finally {
runtime.close();
}
await exportSessionBundleState({
stateRoot,
configRoot,
destinationRoot,
sessionId: selected.id,
});
const bundledDatabasePath = join(destinationRoot, 'runtime.sqlite');
const bundledRuntime = createSqliteRuntimeStore(bundledDatabasePath, { readOnly: true });
try {
const selectedEvents = await bundledRuntime.readRuntimeEvents(selected.id, 'selected-run');
assert.equal(selectedEvents.length, 1);
assert.equal(
selectedEvents[0]?.content?.kind === 'text' ? selectedEvents[0].content.text : undefined,
'ab',
);
assert.deepEqual(await bundledRuntime.readRuntimeEvents(excluded.id, 'excluded-run'), []);
} finally {
bundledRuntime.close();
}
const bundledDatabase = new DatabaseSync(bundledDatabasePath, { readOnly: true });
try {
assert.deepEqual(
bundledDatabase
.prepare('SELECT text_content FROM runtime_partial_segments ORDER BY segment_seq')
.all()
.map((row) => (row as { text_content: string }).text_content),
['ab'],
);
} finally {
bundledDatabase.close();
}
} finally {
await rm(base, { recursive: true, force: true });
}
});
function input(name: string): CreateSessionInput {
return {
cwd: '/tmp/cwd',
llmConnectionSlug: 'fake',
model: 'fake-model',
permissionMode: 'ask' as const,
name,
labels: [],
};
}
function message(id: string) {
return { type: 'user' as const, id, turnId: 'turn-1', ts: 1, text: id };
}
function partialEvent(
sessionId: string,
runId: string,
prefix: string,
ts: number,
text: string,
): RuntimeEvent {
return {
id: `${prefix}-partial-${ts}`,
invocationId: `${prefix}-invocation`,
runId,
sessionId,
turnId: `${prefix}-turn`,
ts,
partial: true,
role: 'model',
author: 'agent',
content: { kind: 'text', text },
refs: { providerEventId: `${prefix}-message` },
};
}
@@ -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 assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
import { test } from 'node:test';
import { SessionBundleFileError } from '../session-bundle-contract.js';
import {
decodeSessionBundleUstarHeaderV1,
encodeSessionBundleUstarHeaderV1,
} from '../session-bundle-ustar.js';
test('pins the exact canonical USTAR V1 header', () => {
const header = Buffer.from(
encodeSessionBundleUstarHeaderV1({
kind: 'file',
path: 'workspace/run.sh',
mode: 0o755,
size: 18,
}),
);
assert.equal(header.byteLength, 512);
assert.equal(header.subarray(0, 16).toString('utf8'), 'workspace/run.sh');
assert.equal(header.subarray(100, 108).toString('ascii'), '0000755\0');
assert.equal(header.subarray(124, 136).toString('ascii'), '00000000022\0');
assert.equal(header.subarray(257, 265).toString('hex'), '7573746172003030');
assert.equal(
createHash('sha256').update(header).digest('hex'),
'1d69bf3bf7dcb40b103d0d405c1d21ebc49a22c0ae3771b07dfd17eeeb4b6c4d',
);
assert.deepEqual(decodeSessionBundleUstarHeaderV1(header), {
kind: 'file',
path: 'workspace/run.sh',
mode: 0o755,
size: 18,
});
});
test('uses the rightmost representable USTAR prefix split', () => {
const path = `workspace/${'a'.repeat(90)}/${'b'.repeat(90)}`;
const header = Buffer.from(
encodeSessionBundleUstarHeaderV1({ kind: 'file', path, mode: 0o644, size: 0 }),
);
assert.equal(header.subarray(0, 100).toString('utf8').replaceAll('\0', ''), 'b'.repeat(90));
assert.equal(
header.subarray(345, 500).toString('utf8').replaceAll('\0', ''),
`workspace/${'a'.repeat(90)}`,
);
assert.equal(decodeSessionBundleUstarHeaderV1(header).path, path);
});
test('accepts exact USTAR field boundaries and non-BMP paths', () => {
const name100 = 'n'.repeat(100);
const nameHeader = Buffer.from(
encodeSessionBundleUstarHeaderV1({ kind: 'file', path: name100, mode: 0o644, size: 0 }),
);
assert.equal(nameHeader.subarray(0, 100).toString('utf8'), name100);
assert.equal(decodeSessionBundleUstarHeaderV1(nameHeader).path, name100);
const prefix155 = 'p'.repeat(155);
const total256 = `${prefix155}/${name100}`;
assert.equal(Buffer.byteLength(total256), 256);
const splitHeader = Buffer.from(
encodeSessionBundleUstarHeaderV1({
kind: 'file',
path: total256,
mode: 0o644,
size: 0o77_777_777_777,
}),
);
assert.equal(splitHeader.subarray(0, 100).toString('utf8'), name100);
assert.equal(splitHeader.subarray(345, 500).toString('utf8'), prefix155);
assert.deepEqual(decodeSessionBundleUstarHeaderV1(splitHeader), {
kind: 'file',
path: total256,
mode: 0o644,
size: 0o77_777_777_777,
});
const nonBmpPath = 'workspace/😀.txt';
const nonBmpHeader = encodeSessionBundleUstarHeaderV1({
kind: 'file',
path: nonBmpPath,
mode: 0o644,
size: 0,
});
assert.equal(decodeSessionBundleUstarHeaderV1(nonBmpHeader).path, nonBmpPath);
assertBundleError(
() =>
encodeSessionBundleUstarHeaderV1({
kind: 'file',
path: `${'p'.repeat(156)}/n`,
mode: 0o644,
size: 0,
}),
'unsafe_path',
);
});
test('rejects noncanonical metadata and unrepresentable paths', () => {
for (const path of [
'/absolute',
'../outside',
'state//file',
'C:/drive',
'workspace/file:stream',
'workspace/CON',
'workspace/con.txt',
'workspace/LPT9.log',
'workspace/trailing.',
'workspace/trailing ',
'workspace/question?',
]) {
assertBundleError(
() => encodeSessionBundleUstarHeaderV1({ kind: 'file', path, mode: 0o644, size: 0 }),
'unsafe_path',
);
}
assertBundleError(
() =>
encodeSessionBundleUstarHeaderV1({
kind: 'file',
path: `${'a'.repeat(101)}`,
mode: 0o644,
size: 0,
}),
'unsafe_path',
);
const header = Buffer.from(
encodeSessionBundleUstarHeaderV1({
kind: 'directory',
path: 'state/',
mode: 0o755,
size: 0,
}),
);
header[135] = '1'.charCodeAt(0);
assertBundleError(() => decodeSessionBundleUstarHeaderV1(header), 'integrity_mismatch');
});
function assertBundleError(action: () => unknown, code: SessionBundleFileError['code']): void {
assert.throws(action, (error) => {
assert.ok(error instanceof SessionBundleFileError);
assert.equal(error.code, code);
return true;
});
}
@@ -0,0 +1,692 @@
/*
* 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 { strict as assert } from 'node:assert';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, describe, it } from 'node:test';
import { DatabaseSync } from 'node:sqlite';
import { createSessionCopyCleanupAuthority } from '../session-copy-cleanup.js';
import type {
ProcessLifetimeOwner,
ProcessLifetimeRecoveryClaim,
} from '../process-lifetime-owner.js';
const roots: string[] = [];
async function createWorkspace(): Promise<string> {
const root = await mkdtemp(join(tmpdir(), 'maka-session-copy-cleanup-'));
roots.push(root);
return root;
}
afterEach(async () => {
await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
});
describe('session copy cleanup authority', () => {
it('forgets a known rejected creation without trying to resume or remove it', async () => {
const workspaceRoot = await createWorkspace();
let resumes = 0;
let removals = 0;
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
resumeSessionCopy: async () => {
resumes += 1;
},
removeSession: async () => {
removals += 1;
},
});
const creation = {
sessionId: 'fork-rejected',
kind: 'branch' as const,
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
intent: 'side_conversation' as const,
ownerId: 'web-contents:1',
};
await assert.rejects(
authority.ownCreation(creation, async () => {
throw new Error('session busy');
}),
/session busy/,
);
assert.deepEqual(await readPendingIds(workspaceRoot), ['fork-rejected']);
await authority.rejectCreation('fork-rejected');
assert.deepEqual(await readPendingIds(workspaceRoot), []);
assert.equal(resumes, 0);
assert.equal(removals, 0);
assert.equal(await authority.ownCreation(creation, async () => 'retried'), 'retried');
});
it('releases a rejected creation lease so the same identity can retry', async () => {
const workspaceRoot = await createWorkspace();
let removalFails = true;
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
removeSession: async () => {
if (removalFails) throw new Error('temporary removal failure');
},
});
await assert.rejects(authority.cleanup('fork-retry'), /temporary removal failure/);
const creation = {
sessionId: 'fork-retry',
kind: 'branch' as const,
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
ownerId: 'web-contents:1',
};
await assert.rejects(
authority.ownCreation(creation, async () => 'unreachable'),
/scheduled for cleanup/,
);
removalFails = false;
await authority.cleanup('fork-retry');
assert.equal(await authority.ownCreation(creation, async () => 'created'), 'created');
});
it('orders cancellation after an in-flight copy reaches a known outcome', async () => {
const workspaceRoot = await createWorkspace();
let releaseCreation!: () => void;
const creationGate = new Promise<void>((resolve) => {
releaseCreation = resolve;
});
const events: string[] = [];
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'process-current',
resumeSessionCopy: async () => {
events.push('resume');
},
removeSession: async () => {
events.push('remove');
},
});
const creation = authority.ownCreation(
{
sessionId: 'fork-racing-create',
kind: 'branch',
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
ownerId: 'web-contents:1',
},
async () => {
events.push('create');
await creationGate;
return 'created';
},
);
await authority.schedule('fork-racing-create');
assert.deepEqual(events, ['create']);
releaseCreation();
assert.equal(await creation, 'created');
await authority.cleanup('fork-racing-create');
assert.deepEqual(events, ['create', 'remove']);
assert.deepEqual(await readPendingIds(workspaceRoot), []);
});
it('resolves an unknown creating lease before removing it after restart', async () => {
const workspaceRoot = await createWorkspace();
const first = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'process-before-crash',
removeSession: async () => {
throw new Error('remove should belong to the successor');
},
});
await assert.rejects(
first.ownCreation(
{
sessionId: 'fork-unknown-create',
kind: 'branch',
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
intent: 'side_conversation',
ownerId: 'web-contents:2',
},
async () => {
throw new Error('response lost');
},
),
/response lost/,
);
const events: string[] = [];
const successor = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'process-after-crash',
resumeSessionCopy: async (creation) => {
events.push(`resume:${creation.sessionId}:${creation.sourceTurnId}:${creation.intent}`);
},
removeSession: async (sessionId) => {
events.push(`remove:${sessionId}`);
},
});
assert.deepEqual(await successor.recover(), {
removed: ['fork-unknown-create'],
failed: [],
});
assert.deepEqual(events, [
'resume:fork-unknown-create:source-turn:side_conversation',
'remove:fork-unknown-create',
]);
assert.deepEqual(await readPendingIds(workspaceRoot), []);
});
it('does not recover a live copy whose owning process is still active', async () => {
const workspaceRoot = await createWorkspace();
const owner = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:101',
removeSession: async () => {},
});
await owner.ownCreation(
{
sessionId: 'fork-live-owner',
kind: 'branch',
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
ownerId: 'tui-side',
},
async () => 'created',
);
const removed: string[] = [];
const concurrent = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:202',
isOwnerProcessActive: (ownerProcessId) => ownerProcessId === 'tui:101',
removeSession: async (sessionId) => {
removed.push(sessionId);
},
});
assert.deepEqual(await concurrent.recover(), { removed: [], failed: [] });
assert.deepEqual(removed, []);
assert.deepEqual(await readPendingIds(workspaceRoot), ['fork-live-owner']);
});
it('claims one released process incarnation across all of its copies', async () => {
const workspaceRoot = await createWorkspace();
const original = fakeLifetimeOwner('lock-v1:11111111-1111-4111-8111-111111111111');
const owner = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:101',
processLifetimeOwner: original.owner,
removeSession: async () => {},
});
for (const sessionId of ['fork-lifetime-a', 'fork-lifetime-b']) {
await owner.ownCreation(
{
sessionId,
kind: 'branch',
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
ownerId: 'tui-side',
},
async () => 'created',
);
}
const successor = fakeLifetimeOwner('lock-v1:22222222-2222-4222-8222-222222222222');
const removed: string[] = [];
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:202',
processLifetimeOwner: successor.owner,
removeSession: async (sessionId) => {
assert.equal(successor.claimClosed, false);
removed.push(sessionId);
},
});
assert.deepEqual(await authority.recover(), {
removed: ['fork-lifetime-a', 'fork-lifetime-b'],
failed: [],
});
assert.deepEqual(removed, ['fork-lifetime-a', 'fork-lifetime-b']);
assert.equal(successor.claimAttempts, 1);
assert.equal(successor.claimRetired, true);
assert.deepEqual(await readPendingIds(workspaceRoot), []);
});
it('holds the released owner claim while recovering a cleanup-phase copy', async () => {
const workspaceRoot = await createWorkspace();
const original = fakeLifetimeOwner('lock-v1:77777777-7777-4777-8777-777777777777');
const owner = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:707',
processLifetimeOwner: original.owner,
removeSession: async () => {},
});
await owner.ownCreation(
{
sessionId: 'fork-cleanup-phase',
kind: 'branch',
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
ownerId: 'tui-side',
},
async () => 'created',
);
updatePendingLease(workspaceRoot, 'fork-cleanup-phase', (record) => ({
...record,
phase: 'cleanup',
cancelRequested: true,
}));
const successor = fakeLifetimeOwner('lock-v1:88888888-8888-4888-8888-888888888888');
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:808',
processLifetimeOwner: successor.owner,
removeSession: async () => {
assert.equal(successor.claimClosed, false);
},
});
assert.deepEqual(await authority.recover(), {
removed: ['fork-cleanup-phase'],
failed: [],
});
assert.equal(successor.claimAttempts, 1);
assert.equal(successor.claimRetired, true);
});
it('falls back to process liveness for an unsupported owner reference version', async () => {
const workspaceRoot = await createWorkspace();
const original = fakeLifetimeOwner('lock-v1:99999999-9999-4999-8999-999999999999');
const owner = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:909',
processLifetimeOwner: original.owner,
removeSession: async () => {},
});
await owner.ownCreation(
{
sessionId: 'fork-future-owner',
kind: 'branch',
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
ownerId: 'tui-side',
},
async () => 'created',
);
updatePendingLease(workspaceRoot, 'fork-future-owner', (record) => ({
...record,
ownerLifetimeRef: 'lock-v2:future-owner',
}));
let claimAttempts = 0;
const removed: string[] = [];
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:1001',
processLifetimeOwner: {
reference: 'lock-v1:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
tryClaimReleased: async () => {
claimAttempts += 1;
throw new Error('unsupported owner reference must use the PID fallback');
},
retireUnreferencedReleasedOwners: async () => {},
close: async () => {},
},
isOwnerProcessActive: () => false,
removeSession: async (sessionId) => {
removed.push(sessionId);
},
});
assert.deepEqual(await authority.recover(), {
removed: ['fork-future-owner'],
failed: [],
});
assert.equal(claimAttempts, 0);
assert.deepEqual(removed, ['fork-future-owner']);
});
it('asks the process owner to retire released files with no database references', async () => {
const workspaceRoot = await createWorkspace();
let referenced: ReadonlySet<string> | undefined;
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
processLifetimeOwner: {
reference: 'lock-v1:bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb',
tryClaimReleased: async () => undefined,
retireUnreferencedReleasedOwners: async (current) => {
referenced = current;
},
close: async () => {},
},
removeSession: async () => {},
});
assert.deepEqual(await authority.recover(), { removed: [], failed: [] });
assert.ok(referenced);
assert.deepEqual([...referenced], []);
});
it('fails closed when process-incarnation ownership cannot be inspected', async () => {
const workspaceRoot = await createWorkspace();
const original = fakeLifetimeOwner('lock-v1:33333333-3333-4333-8333-333333333333');
const owner = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:303',
processLifetimeOwner: original.owner,
removeSession: async () => {},
});
await owner.ownCreation(
{
sessionId: 'fork-unknown-owner',
kind: 'branch',
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
ownerId: 'tui-side',
},
async () => 'created',
);
const failure = new Error('native lock unavailable');
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:404',
processLifetimeOwner: {
reference: 'lock-v1:44444444-4444-4444-8444-444444444444',
tryClaimReleased: async () => {
throw failure;
},
retireUnreferencedReleasedOwners: async () => {},
close: async () => {},
},
removeSession: async () => {
throw new Error('must not remove an indeterminate owner');
},
});
const recovery = await authority.recover();
assert.deepEqual(recovery.removed, []);
assert.deepEqual(recovery.failed, [{ sessionId: 'fork-unknown-owner', error: failure }]);
assert.deepEqual(await readPendingIds(workspaceRoot), ['fork-unknown-owner']);
});
it('abandons every live copy owned by a renderer that exits', async () => {
const workspaceRoot = await createWorkspace();
const removed: string[] = [];
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'process-current',
removeSession: async (sessionId) => {
removed.push(sessionId);
},
});
await authority.ownCreation(
{
sessionId: 'fork-owned-renderer',
kind: 'branch',
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
ownerId: 'web-contents:7',
},
async () => 'created',
);
await authority.abandonOwner('web-contents:7');
await authority.cleanup('fork-owned-renderer');
assert.deepEqual(removed, ['fork-owned-renderer']);
assert.deepEqual(await readPendingIds(workspaceRoot), []);
});
it('abandons only copies owned by the current process incarnation', async () => {
const workspaceRoot = await createWorkspace();
const firstLifetime = fakeLifetimeOwner('lock-v1:55555555-5555-4555-8555-555555555555');
const secondLifetime = fakeLifetimeOwner('lock-v1:66666666-6666-4666-8666-666666666666');
const first = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:505',
processLifetimeOwner: firstLifetime.owner,
removeSession: async () => {},
});
const removed: string[] = [];
const second = createSessionCopyCleanupAuthority({
workspaceRoot,
processId: 'tui:505',
processLifetimeOwner: secondLifetime.owner,
removeSession: async (sessionId) => {
removed.push(sessionId);
},
});
for (const [authority, sessionId] of [
[first, 'fork-first-incarnation'],
[second, 'fork-second-incarnation'],
] as const) {
await authority.ownCreation(
{
sessionId,
kind: 'branch',
sourceSessionId: 'source-session',
sourceTurnId: 'source-turn',
ownerId: 'tui-side',
},
async () => 'created',
);
}
await second.abandonOwner('tui-side');
await second.cleanup('fork-second-incarnation');
assert.deepEqual(removed, ['fork-second-incarnation']);
assert.deepEqual(await readPendingIds(workspaceRoot), ['fork-first-incarnation']);
});
it('acknowledges abandon after the intent is durable without waiting for removal', async () => {
const workspaceRoot = await createWorkspace();
let releaseRemoval: (() => void) | undefined;
const removal = new Promise<void>((resolve) => {
releaseRemoval = resolve;
});
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
removeSession: async () => removal,
});
await authority.schedule('fork-scheduled');
assert.deepEqual(await readPendingIds(workspaceRoot), ['fork-scheduled']);
releaseRemoval?.();
await authority.cleanup('fork-scheduled');
assert.deepEqual(await readPendingIds(workspaceRoot), []);
});
it('persists a failed removal and recovers it through a new authority instance', async () => {
const workspaceRoot = await createWorkspace();
const first = createSessionCopyCleanupAuthority({
workspaceRoot,
removeSession: async () => {
throw new Error('temporary removal failure');
},
});
await assert.rejects(first.cleanup('fork-1'), /temporary removal failure/);
assert.deepEqual(await readPendingIds(workspaceRoot), ['fork-1']);
const removed: string[] = [];
const afterRestart = createSessionCopyCleanupAuthority({
workspaceRoot,
removeSession: async (sessionId) => {
removed.push(sessionId);
},
});
const recovery = await afterRestart.recover();
assert.deepEqual(removed, ['fork-1']);
assert.deepEqual(recovery, { removed: ['fork-1'], failed: [] });
assert.deepEqual(await readPendingIds(workspaceRoot), []);
});
it('clears the durable intent only after the complete removal succeeds', async () => {
const workspaceRoot = await createWorkspace();
let pendingDuringRemoval: string[] = [];
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
removeSession: async () => {
pendingDuringRemoval = await readPendingIds(workspaceRoot);
},
});
await authority.cleanup('fork-2');
assert.deepEqual(pendingDuringRemoval, ['fork-2']);
assert.deepEqual(await readPendingIds(workspaceRoot), []);
});
it('continues recovering other companions when one removal still fails', async () => {
const workspaceRoot = await createWorkspace();
const seed = createSessionCopyCleanupAuthority({
workspaceRoot,
removeSession: async () => {
throw new Error('offline');
},
});
await assert.rejects(seed.cleanup('fork-a'));
await assert.rejects(seed.cleanup('fork-b'));
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
removeSession: async (sessionId) => {
if (sessionId === 'fork-a') throw new Error('still offline');
},
});
const recovery = await authority.recover();
assert.deepEqual(recovery.removed, ['fork-b']);
assert.deepEqual(
recovery.failed.map(({ sessionId }) => sessionId),
['fork-a'],
);
assert.deepEqual(await readPendingIds(workspaceRoot), ['fork-a']);
});
it('forgets a terminal retained Revision without reporting deletion', async () => {
const workspaceRoot = await createWorkspace();
const seed = createSessionCopyCleanupAuthority({
workspaceRoot,
removeSession: async () => {
throw new Error('offline');
},
});
await assert.rejects(seed.cleanup('retained-revision'));
const authority = createSessionCopyCleanupAuthority({
workspaceRoot,
removeSession: async () => 'retained',
});
assert.deepEqual(await authority.recover(), { removed: [], failed: [] });
assert.deepEqual(await readPendingIds(workspaceRoot), []);
});
});
async function readPendingIds(workspaceRoot: string): Promise<string[]> {
const database = new DatabaseSync(join(workspaceRoot, 'runtime.sqlite'), { readOnly: true });
try {
return (
database
.prepare(`
SELECT session_id AS sessionId
FROM workflow_quote_companion_cleanup
ORDER BY tracked_at, session_id
`)
.all() as Array<{ sessionId: string }>
).map(({ sessionId }) => sessionId);
} finally {
database.close();
}
}
function updatePendingLease(
workspaceRoot: string,
sessionId: string,
update: (record: Record<string, unknown>) => Record<string, unknown>,
): void {
const database = new DatabaseSync(join(workspaceRoot, 'runtime.sqlite'));
try {
const row = database
.prepare(
'SELECT record_json AS recordJson FROM workflow_quote_companion_cleanup WHERE session_id = ?',
)
.get(sessionId) as { recordJson: string } | undefined;
assert.ok(row);
database
.prepare('UPDATE workflow_quote_companion_cleanup SET record_json = ? WHERE session_id = ?')
.run(
JSON.stringify(update(JSON.parse(row.recordJson) as Record<string, unknown>)),
sessionId,
);
} finally {
database.close();
}
}
function fakeLifetimeOwner(reference: string): {
owner: ProcessLifetimeOwner;
readonly claimAttempts: number;
readonly claimClosed: boolean;
readonly claimRetired: boolean;
} {
let claimAttempts = 0;
let claimClosed = false;
let claimRetired = false;
const claim: ProcessLifetimeRecoveryClaim = {
retire: async () => {
claimRetired = true;
claimClosed = true;
},
close: async () => {
claimClosed = true;
},
};
return {
owner: {
reference,
tryClaimReleased: async () => {
claimAttempts += 1;
return claim;
},
retireUnreferencedReleasedOwners: async () => {},
close: async () => {},
},
get claimAttempts() {
return claimAttempts;
},
get claimClosed() {
return claimClosed;
},
get claimRetired() {
return claimRetired;
},
};
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,97 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, describe, test } from 'node:test';
import {
authenticateInteractiveSessionTodoWriter,
openInteractiveSessionTodoStoreForWrite,
type InteractiveSessionTodoWriter,
} from '../session-todo-authority.js';
import {
resolveStorageRoot,
StorageRootAuthorityError,
tryAcquireInteractiveRootOwner,
type StorageRootLease,
} from '../root-authority.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
after(removeTrackedControlDirectories);
describe('interactive SessionTodo authority', () => {
test('single-flights opens and invalidates the facade when closed', async () => {
await withInteractiveRoot(async (capability) => {
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
const [first, second] = await Promise.all([
openInteractiveSessionTodoStoreForWrite(owner.lease),
openInteractiveSessionTodoStoreForWrite(owner.lease),
]);
assert.equal(first, second);
assert.equal(authenticateInteractiveSessionTodoWriter(first), first);
await first.replaceAll('authority-session', [{ content: 'owned', status: 'pending' }]);
assert.deepEqual(await second.readOrBootstrap('authority-session'), {
items: [{ content: 'owned', status: 'pending' }],
});
first.close();
assert.throws(() => authenticateInteractiveSessionTodoWriter(first), isInvalidLease);
await assert.rejects(() => first.readOrBootstrap('authority-session'), isInvalidLease);
} finally {
if (!owner.closed) await owner.close();
}
});
});
test('rejects forged leases and facades', async () => {
await assert.rejects(
() => openInteractiveSessionTodoStoreForWrite({} as StorageRootLease<'interactive', 'write'>),
isInvalidLease,
);
assert.throws(
() => authenticateInteractiveSessionTodoWriter({} as InteractiveSessionTodoWriter),
isInvalidLease,
);
});
});
async function withInteractiveRoot(
run: (capability: Awaited<ReturnType<typeof resolveStorageRoot<'interactive'>>>) => Promise<void>,
): Promise<void> {
const base = await mkdtemp(join(tmpdir(), 'maka-session-todo-authority-'));
try {
const capability = trackControlDirectory(
await resolveStorageRoot({ path: join(base, 'interactive'), kind: 'interactive' }),
);
await run(capability);
} finally {
await rm(base, { recursive: true, force: true });
}
}
function isInvalidLease(error: unknown): boolean {
return error instanceof StorageRootAuthorityError && error.code === 'invalid_lease';
}
@@ -0,0 +1,276 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { DatabaseSync } from 'node:sqlite';
import { createSqliteSessionTodoStore } from '../session-todo-store.js';
const SESSION_ID = 'session-todo';
describe('SQLite SessionTodo store', () => {
test('persists an initialized-empty document on the first read', async () => {
await withRoot(async (root) => {
const todos = createSqliteSessionTodoStore(root);
assert.deepEqual(await todos.readOrBootstrap(SESSION_ID), { items: [] });
assert.deepEqual(await todos.readOrBootstrap(SESSION_ID), { items: [] });
todos.close();
const database = new DatabaseSync(join(root, 'runtime.sqlite'), { readOnly: true });
try {
assert.equal(
database
.prepare(
'SELECT COUNT(*) AS count FROM workflow_session_todo_documents WHERE session_id = ?',
)
.get(SESSION_ID)!.count,
1,
);
} finally {
database.close();
}
});
});
test('serializes a first explicit replacement ahead of a following bootstrap read', async () => {
await withRoot(async (root) => {
const todos = createSqliteSessionTodoStore(root);
const [written, read] = await Promise.all([
todos.replaceAll(SESSION_ID, [{ content: 'explicit work', status: 'in_progress' }]),
todos.readOrBootstrap(SESSION_ID),
]);
assert.deepEqual(written, {
items: [{ content: 'explicit work', status: 'in_progress' }],
});
assert.deepEqual(read, written);
todos.close();
});
});
test('persists replacement order across reopen and purge restores uninitialized state', async () => {
await withRoot(async (root) => {
const first = createSqliteSessionTodoStore(root);
await first.replaceAll(SESSION_ID, [
{ content: 'second', status: 'in_progress' },
{ content: 'first', status: 'pending' },
]);
first.close();
const reopened = createSqliteSessionTodoStore(root);
assert.deepEqual(await reopened.readOrBootstrap(SESSION_ID), {
items: [
{ content: 'second', status: 'in_progress' },
{ content: 'first', status: 'pending' },
],
});
await reopened.purgeSessionState(SESSION_ID);
assert.deepEqual(await reopened.readOrBootstrap(SESSION_ID), { items: [] });
reopened.close();
});
});
test('fails closed on a corrupt current document but permits explicit replacement recovery', async () => {
await withRoot(async (root) => {
const initialized = createSqliteSessionTodoStore(root);
await initialized.replaceAll(SESSION_ID, []);
initialized.close();
const database = new DatabaseSync(join(root, 'runtime.sqlite'));
try {
database
.prepare(
'UPDATE workflow_session_todo_documents SET record_json = ? WHERE session_id = ?',
)
.run('{not-json', SESSION_ID);
} finally {
database.close();
}
const todos = createSqliteSessionTodoStore(root);
await assert.rejects(() => todos.readOrBootstrap(SESSION_ID), /Invalid SessionTodo document/);
assert.deepEqual(
await todos.replaceAll(SESSION_ID, [{ content: 'recovered', status: 'pending' }]),
{ items: [{ content: 'recovered', status: 'pending' }] },
);
assert.deepEqual(await todos.readOrBootstrap(SESSION_ID), {
items: [{ content: 'recovered', status: 'pending' }],
});
todos.close();
});
});
test('initializes latest copies atomically and accepts only an identical retry', async () => {
await withRoot(async (root) => {
const todos = createSqliteSessionTodoStore(root);
await todos.replaceAll('source', [{ content: 'current work', status: 'in_progress' }]);
const input = { sourceSessionId: 'source', targetSessionId: 'target', copyCurrent: true };
const expected = { items: [{ content: 'current work', status: 'in_progress' as const }] };
assert.deepEqual(await todos.initializeCopy(input), expected);
assert.deepEqual(await todos.initializeCopy(input), expected);
await todos.replaceAll('target', [{ content: 'different', status: 'pending' }]);
await assert.rejects(() => todos.initializeCopy(input), /different state/);
todos.close();
});
});
test('fails closed when a copy source or target document is corrupt', async () => {
await withRoot(async (root) => {
const todos = createSqliteSessionTodoStore(root);
await todos.replaceAll('source', [{ content: 'current work', status: 'pending' }]);
await todos.replaceAll('corrupt-target', []);
const database = new DatabaseSync(join(root, 'runtime.sqlite'));
try {
database
.prepare(
'UPDATE workflow_session_todo_documents SET record_json = ? WHERE session_id = ?',
)
.run('{not-json', 'corrupt-target');
} finally {
database.close();
}
await assert.rejects(
() =>
todos.initializeCopy({
sourceSessionId: 'source',
targetSessionId: 'corrupt-target',
copyCurrent: true,
}),
/Invalid SessionTodo document JSON/,
);
const corruptSource = new DatabaseSync(join(root, 'runtime.sqlite'));
try {
corruptSource
.prepare(
'UPDATE workflow_session_todo_documents SET record_json = ? WHERE session_id = ?',
)
.run('{not-json', 'source');
} finally {
corruptSource.close();
}
await assert.rejects(
() =>
todos.initializeCopy({
sourceSessionId: 'source',
targetSessionId: 'new-target',
copyCurrent: true,
}),
/Invalid SessionTodo document JSON/,
);
const verified = new DatabaseSync(join(root, 'runtime.sqlite'), { readOnly: true });
try {
assert.equal(
verified
.prepare(
'SELECT COUNT(*) AS count FROM workflow_session_todo_documents WHERE session_id = ?',
)
.get('new-target')!.count,
0,
);
} finally {
verified.close();
}
todos.close();
});
});
test('writes an explicit empty copy marker when the copy skips current state', async () => {
await withRoot(async (root) => {
const todos = createSqliteSessionTodoStore(root);
assert.deepEqual(
await todos.initializeCopy({
sourceSessionId: 'source',
targetSessionId: 'historical-target',
copyCurrent: false,
}),
{ items: [] },
);
todos.close();
// The copy must persist the marker itself: reading it back would return an
// empty document either way, so only the stored row separates "wrote an
// explicit empty copy" from "wrote nothing at all".
const database = new DatabaseSync(join(root, 'runtime.sqlite'), { readOnly: true });
try {
assert.equal(
database
.prepare(
'SELECT COUNT(*) AS count FROM workflow_session_todo_documents WHERE session_id = ?',
)
.get('historical-target')!.count,
1,
);
} finally {
database.close();
}
});
});
test('copies an uninitialized source as empty without initializing the source', async () => {
await withRoot(async (root) => {
const todos = createSqliteSessionTodoStore(root);
const input = { sourceSessionId: 'source', targetSessionId: 'target', copyCurrent: true };
assert.deepEqual(await todos.initializeCopy(input), { items: [] });
assert.deepEqual(await todos.initializeCopy(input), { items: [] });
todos.close();
const database = new DatabaseSync(join(root, 'runtime.sqlite'), { readOnly: true });
try {
const rows = database
.prepare('SELECT session_id FROM workflow_session_todo_documents ORDER BY session_id')
.all() as Array<{ session_id: string }>;
assert.deepEqual(
rows.map((row) => row.session_id),
['target'],
);
} finally {
database.close();
}
});
});
test('linearizes concurrent whole-document replacements', async () => {
await withRoot(async (root) => {
const todos = createSqliteSessionTodoStore(root);
const writes = Array.from({ length: 128 }, (_, index) =>
todos.replaceAll(SESSION_ID, [{ content: `write ${index}`, status: 'pending' }]),
);
await Promise.all(writes);
assert.deepEqual(await todos.readOrBootstrap(SESSION_ID), {
items: [{ content: 'write 127', status: 'pending' }],
});
todos.close();
});
});
});
async function withRoot(run: (root: string) => Promise<void>): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-session-todo-'));
try {
await run(root);
} finally {
await rm(root, { recursive: true, force: true });
}
}
@@ -0,0 +1,323 @@
/*
* 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.
*/
/**
* Tests for SettingsStore.upsertOnboardingMilestone (PR110b).
*
* Verifies the write path:
* - timestamp is generated by the store (never accepted from caller)
* - invalid id surfaces an error (via the sanitizer's closed enum)
* - last-valid-entry-wins dedup with stable first-seen position
* - settings.json round-trips through the sanitizer on read
* - upserting one milestone never disturbs other milestones
*/
import { strict as assert } from 'node:assert';
import { describe, it } from 'node:test';
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { createSettingsStore } from '../settings-store.js';
describe('SettingsStore.upsertOnboardingMilestone (PR110b)', () => {
it('stamps a fresh Date.now() timestamp (renderer cannot tamper)', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-'));
try {
const store = createSettingsStore(workspaceRoot);
const before = Date.now();
const result = await store.upsertOnboardingMilestone('first_chat_sent', 'completed');
const after = Date.now();
assert.equal(result.length, 1);
const entry = result[0];
assert.ok(entry);
assert.equal(entry.id, 'first_chat_sent');
assert.ok(typeof entry.completedAt === 'number');
assert.ok(
entry.completedAt! >= before && entry.completedAt! <= after,
'timestamp must come from main process clock',
);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('skipped status writes skippedAt (mutually exclusive with completedAt)', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-skipped-'));
try {
const store = createSettingsStore(workspaceRoot);
const result = await store.upsertOnboardingMilestone('first_personalization', 'skipped');
const entry = result[0];
assert.ok(entry);
assert.equal(entry.id, 'first_personalization');
assert.ok(typeof entry.skippedAt === 'number');
assert.equal(entry.completedAt, undefined);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('rejects invalid status (TypeScript-bypassing call)', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-invalid-'));
try {
const store = createSettingsStore(workspaceRoot);
// Cast to bypass TS so we can prove the runtime guard works.
// Keep the receiver via arrow fn so `this` isn't lost.
await assert.rejects(
() =>
(
store.upsertOnboardingMilestone as unknown as (
id: string,
status: string,
) => Promise<unknown>
).call(store, 'first_chat_sent', 'unknown_status'),
/invalid onboarding milestone status/,
);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('rejects invalid milestone id (sanitizer drops, then store re-throws)', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-bad-id-'));
try {
const store = createSettingsStore(workspaceRoot);
await assert.rejects(
() =>
(
store.upsertOnboardingMilestone as unknown as (
id: string,
status: 'completed' | 'skipped',
) => Promise<unknown>
).call(store, 'not_a_milestone', 'completed'),
/invalid onboarding milestone id/,
);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('upserting the same id last-valid-entry wins (skipped overrides completed)', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-upsert-'));
try {
const store = createSettingsStore(workspaceRoot);
await store.upsertOnboardingMilestone('first_chat_sent', 'completed');
const after = await store.upsertOnboardingMilestone('first_chat_sent', 'skipped');
assert.equal(after.length, 1);
const entry = after[0];
assert.equal(entry?.id, 'first_chat_sent');
assert.ok(typeof entry?.skippedAt === 'number');
// Once skipped is set, completed must NOT survive.
assert.equal(entry?.completedAt, undefined);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('does not disturb other milestones when upserting one', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-others-'));
try {
const store = createSettingsStore(workspaceRoot);
await store.upsertOnboardingMilestone('first_chat_sent', 'completed');
const before = (await store.get()).onboarding.milestones[0]?.completedAt;
await store.upsertOnboardingMilestone('first_personalization', 'completed');
const after = (await store.get()).onboarding.milestones;
assert.equal(after.length, 2);
const chat = after.find((m) => m.id === 'first_chat_sent');
const pers = after.find((m) => m.id === 'first_personalization');
assert.equal(chat?.completedAt, before, 'first_chat_sent timestamp preserved');
assert.ok(pers?.completedAt);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('settings.json on disk contains only sanitized milestones', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-disk-'));
try {
const store = createSettingsStore(workspaceRoot);
await store.upsertOnboardingMilestone('first_chat_sent', 'completed');
const raw = await readFile(join(workspaceRoot, 'settings.json'), 'utf8');
const parsed = JSON.parse(raw) as {
onboarding: { milestones: Array<Record<string, unknown>> };
};
assert.equal(parsed.onboarding.milestones.length, 1);
const entry = parsed.onboarding.milestones[0]!;
// Must contain only the schema fields — nothing else.
assert.deepEqual(Object.keys(entry).sort(), ['completedAt', 'id']);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('reading settings.json with garbage milestones drops them via sanitizer', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-garbage-'));
try {
const store = createSettingsStore(workspaceRoot);
// Seed a bad settings.json by hand and reload.
const { writeFile, mkdir } = await import('node:fs/promises');
await mkdir(workspaceRoot, { recursive: true });
await writeFile(
join(workspaceRoot, 'settings.json'),
JSON.stringify({
schemaVersion: 1,
onboarding: {
milestones: [
{ id: 'first_chat_sent', completedAt: 1 },
{ id: 'first_personalization', completedAt: 'bad' }, // invalid
{ id: 'first_chat_sent', skippedAt: 2 }, // last-wins
{ id: 'unknown_id', completedAt: 3 }, // invalid id
{ id: 'first_chat_sent', completedAt: 4, prompt: 'leak' }, // extra field
],
},
}),
);
const settings = await store.get();
// After sanitize: first_chat_sent has skippedAt: 2 (last valid;
// the 4-with-extra is rejected before it could overwrite).
assert.equal(settings.onboarding.milestones.length, 1);
assert.equal(settings.onboarding.milestones[0]?.id, 'first_chat_sent');
assert.equal(settings.onboarding.milestones[0]?.skippedAt, 2);
assert.equal(settings.onboarding.milestones[0]?.completedAt, undefined);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
});
describe('SettingsStore.clearOnboardingMilestone', () => {
it('removes one milestone and preserves the rest', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-clear-'));
try {
const store = createSettingsStore(workspaceRoot);
await store.upsertOnboardingMilestone('first_chat_sent', 'completed');
await store.upsertOnboardingMilestone('first_model_swap', 'skipped');
const after = await store.clearOnboardingMilestone('first_model_swap');
assert.equal(
after.some((entry) => entry.id === 'first_model_swap'),
false,
);
assert.equal(
after.some((entry) => entry.id === 'first_chat_sent'),
true,
);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('rejects invalid milestone id (TypeScript-bypassing call)', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-milestone-clear-invalid-'));
try {
const store = createSettingsStore(workspaceRoot);
await assert.rejects(
() =>
(store.clearOnboardingMilestone as unknown as (id: string) => Promise<unknown>).call(
store,
'not_a_milestone',
),
/invalid onboarding milestone id/,
);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
});
describe('SettingsStore.updateIf', () => {
it('checks and writes atomically against the latest queued settings', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-conditional-'));
try {
const store = createSettingsStore(workspaceRoot);
await store.update({
botChat: { channels: { dingtalk: { appId: 'installed-id' } } },
});
const applied = await store.updateIf(
(current) => current.botChat.channels.dingtalk.appId === 'installed-id',
{ botChat: { channels: { dingtalk: { appId: 'rolled-back-id' } } } },
);
assert.equal(applied.applied, true);
assert.equal(applied.settings.botChat.channels.dingtalk.appId, 'rolled-back-id');
const skipped = await store.updateIf(
(current) => current.botChat.channels.dingtalk.appId === 'installed-id',
{ botChat: { channels: { dingtalk: { appId: 'must-not-win' } } } },
);
assert.equal(skipped.applied, false);
assert.equal((await store.get()).botChat.channels.dingtalk.appId, 'rolled-back-id');
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
});
describe('SettingsStore.get file recovery', () => {
it('serializes concurrent first reads while creating default settings', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-concurrent-defaults-'));
const originalNow = Date.now;
try {
Date.now = () => 1_000;
const store = createSettingsStore(workspaceRoot);
const settings = await Promise.all(Array.from({ length: 16 }, () => store.get()));
assert.equal(
settings.every((value) => value.schemaVersion === 1),
true,
);
const raw = await readFile(join(workspaceRoot, 'settings.json'), 'utf8');
assert.equal(JSON.parse(raw).schemaVersion, 1);
} finally {
Date.now = originalNow;
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('creates defaults only when settings.json is missing', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-defaults-'));
try {
const store = createSettingsStore(workspaceRoot);
const settings = await store.get();
const raw = await readFile(join(workspaceRoot, 'settings.json'), 'utf8');
assert.equal(settings.schemaVersion, 1);
assert.match(raw, /"schemaVersion": 1/);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
it('rejects corrupt settings.json without overwriting user settings bytes', async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), 'maka-settings-corrupt-'));
try {
const store = createSettingsStore(workspaceRoot);
const settingsPath = join(workspaceRoot, 'settings.json');
const corrupt = '{"appearance":{"theme":"dark"}';
await writeFile(settingsPath, corrupt, 'utf8');
await assert.rejects(() => store.get(), SyntaxError);
assert.equal(await readFile(settingsPath, 'utf8'), corrupt);
} finally {
await rm(workspaceRoot, { recursive: true, force: true });
}
});
});
@@ -0,0 +1,185 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, describe, test } from 'node:test';
import type { ShellRunRecord } from '@maka/core/shell-run';
import {
authenticateInteractiveShellRunWriter,
openInteractiveShellRunStoreForWrite,
type InteractiveShellRunWriter,
} from '../shell-run-authority.js';
import {
resolveStorageRoot,
StorageRootAuthorityError,
tryAcquireInteractiveRootOwner,
type StorageRootLease,
} from '../root-authority.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
// The control directory of each resolved root lives outside that root, so a
// temporary root's removal leaves it behind; reclaim the recorded rootIds here.
after(removeTrackedControlDirectories);
describe('interactive ShellRun authority', () => {
test('single-flights one authentic writer and preserves durable lifecycle state', async () => {
await withInteractiveRoot(async ({ capability }) => {
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
try {
const [first, second] = await Promise.all([
openInteractiveShellRunStoreForWrite(owner.lease),
openInteractiveShellRunStoreForWrite(owner.lease),
]);
assert.equal(first, second);
assert.equal(authenticateInteractiveShellRunWriter(first), first);
const input = record();
const createdPromise = first.createShellRun(input);
if (input.output.mode !== 'pipes') assert.fail('Expected pipe output fixture');
input.output.stdout = 'mutated after acceptance';
const created = await createdPromise;
assert.equal(created.output.mode === 'pipes' ? created.output.stdout : undefined, '');
const completed = await second.updateShellRun('session-1', 'shell-1', {
status: 'completed',
exitCode: 0,
completedAt: 2,
updatedAt: 2,
output: pipeOutput('done'),
});
assert.equal(completed.status, 'completed');
assert.equal(completed.revision, 2);
first.close();
assert.throws(() => authenticateInteractiveShellRunWriter(first), isInvalidLease);
const reopened = await openInteractiveShellRunStoreForWrite(owner.lease);
assert.notEqual(reopened, first);
assert.equal((await reopened.readShellRun('session-1', 'shell-1')).status, 'completed');
reopened.close();
} finally {
if (!owner.closed) await owner.close();
}
});
});
test('rejects reads and mutations after its owner lease is released', async () => {
await withInteractiveRoot(async ({ capability }) => {
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
const writer = await openInteractiveShellRunStoreForWrite(owner.lease);
await writer.createShellRun(record());
await owner.close();
await assert.rejects(() => writer.readShellRun('session-1', 'shell-1'), isInvalidLease);
await assert.rejects(
() => writer.updateShellRun('session-1', 'shell-1', { updatedAt: 2 }),
isInvalidLease,
);
writer.close();
});
});
test('rejects forged leases and forged writer facades', async () => {
await assert.rejects(
() => openInteractiveShellRunStoreForWrite({} as StorageRootLease<'interactive', 'write'>),
isInvalidLease,
);
await withInteractiveRoot(async ({ capability }) => {
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
const writer = await openInteractiveShellRunStoreForWrite(owner.lease);
try {
assert.throws(
() =>
authenticateInteractiveShellRunWriter({
...writer,
} as InteractiveShellRunWriter),
isInvalidLease,
);
} finally {
writer.close();
await owner.close();
}
});
});
});
function record(): ShellRunRecord {
return {
shellRunId: 'shell-1',
sessionId: 'session-1',
sourceTurnId: 'turn-1',
sourceToolCallId: 'tool-1',
cwd: '/workspace',
command: 'printf done',
status: 'running',
startedAt: 1,
updatedAt: 1,
revision: 1,
output: pipeOutput(''),
};
}
function pipeOutput(stdout: string): Extract<ShellRunRecord['output'], { mode: 'pipes' }> {
return {
mode: 'pipes',
stdout,
stderr: '',
stdoutTruncated: false,
stderrTruncated: false,
redacted: false,
};
}
async function withInteractiveRoot(
run: (input: {
capability: Awaited<ReturnType<typeof resolveStorageRoot<'interactive'>>>;
}) => Promise<void>,
): Promise<void> {
await withTempDir(async (base) => {
const capability = trackControlDirectory(
await resolveStorageRoot({ path: join(base, 'interactive'), kind: 'interactive' }),
);
await run({ capability });
});
}
async function withTempDir(run: (base: string) => Promise<void>): Promise<void> {
const base = await mkdtemp(join(tmpdir(), 'maka-shell-run-authority-'));
try {
await run(base);
} finally {
await rm(base, { recursive: true, force: true });
}
}
function isInvalidLease(error: unknown): boolean {
return error instanceof StorageRootAuthorityError && error.code === 'invalid_lease';
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,808 @@
/*
* 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 assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { after, describe, test } from 'node:test';
import { DatabaseSync } from 'node:sqlite';
import type { AgentRunHeader, EmittedAgentRunEvent } from '@maka/core/agent-run';
import {
MODEL_CALL_ATTEMPT_SCHEMA_VERSION,
decodeModelCallAttempt,
type ModelCallAttempt,
} from '@maka/core/model-call-attempt';
import type { InteractionCanonicalOutcome, InteractionRequest } from '@maka/core/interaction';
import type { ShellRunRecord } from '@maka/core/shell-run';
import { createSqliteAgentRunStore } from '../agent-run-store.js';
import {
closeSqliteInteractionStoreFacade,
openSqliteInteractiveInteractionStoreForWrite,
type StoredInteractionRequest,
} from '../interaction-store.js';
import { resolveStorageRoot, tryAcquireInteractiveRootOwner } from '../root-authority.js';
import { createSqliteShellRunStore } from '../shell-run-store.js';
import {
removeTrackedControlDirectories,
trackControlDirectory,
} from './fixtures/control-directory-hygiene.js';
// The control directory of each resolved root lives outside that root, so a
// temporary root's removal leaves it behind; reclaim the recorded rootIds here.
after(removeTrackedControlDirectories);
describe('SQLite core execution stores', () => {
test('persists AgentRun header and events', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
await store.createRun(runHeader());
await store.appendEvent('session-1', 'run-1', runEvent());
store.close?.();
const reopened = createSqliteAgentRunStore(root);
try {
assert.equal((await reopened.readRun('session-1', 'run-1')).runId, 'run-1');
assert.equal((await reopened.readEvents('session-1', 'run-1'))[0]?.id, 'event-1');
} finally {
reopened.close?.();
}
});
});
test('folds retired AgentRun values only when reading persisted rows', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
await store.createRun(runHeader());
await assert.rejects(
() =>
store.createRun({
...runHeader({ runId: 'run-retired', turnId: 'turn-retired' }),
permissionMode: 'execute',
} as unknown as AgentRunHeader),
/Invalid AgentRun header schema/,
);
store.close?.();
const database = new DatabaseSync(join(root, 'runtime.sqlite'));
try {
const row = database
.prepare("SELECT record_json AS recordJson FROM core_agent_runs WHERE run_id = 'run-1'")
.get() as { recordJson: string };
const retired = JSON.parse(row.recordJson) as Record<string, unknown>;
retired.status = 'waiting_permission';
retired.permissionMode = 'execute';
retired.automationId = 'automation-1';
database
.prepare("UPDATE core_agent_runs SET record_json = ? WHERE run_id = 'run-1'")
.run(JSON.stringify(retired));
} finally {
database.close();
}
const reopened = createSqliteAgentRunStore(root);
try {
const decoded = await reopened.readRun('session-1', 'run-1');
assert.equal(decoded.status, 'waiting_for_user');
assert.equal(decoded.permissionMode, 'ask');
assert.equal(decoded.legacyAutomationId, 'automation-1');
assert.equal(Object.hasOwn(decoded, 'automationId'), false);
} finally {
reopened.close?.();
}
});
});
test('advances the model-call high-water index with the authority append', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
await store.createRun(runHeader());
await store.appendEvent('session-1', 'run-1', runEvent());
await store.appendEvent('session-1', 'run-1', {
...runEvent(),
id: 'model-call-event',
type: 'model_call_attempt_recorded',
data: { ...modelCallAttempt() },
});
const database = new DatabaseSync(join(root, 'runtime.sqlite'), { readOnly: true });
try {
assert.equal(
database
.prepare(`
SELECT latest_model_call_sequence AS sequence
FROM core_agent_runs
WHERE session_id = 'session-1' AND run_id = 'run-1'
`)
.get()?.sequence,
1,
);
} finally {
database.close();
store.close?.();
}
});
});
test('commits canonical authority without guessing a malformed projection order', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
await store.createRun(runHeader());
await store.appendEvent(
'session-1',
'run-1',
{
...runEvent(),
id: 'model-call-newer',
type: 'model_call_attempt_recorded',
ts: 100,
data: {
...modelCallAttempt({
attemptId: 'attempt-newer',
completedAt: 100,
latencyMs: 99,
}),
},
},
{
latestContext: {
attemptId: 'attempt-newer',
orderedAt: 100,
snapshot: {
schemaVersion: 2,
attemptId: 'attempt-newer',
providerId: 'openai',
modelId: 'gpt-5',
completedAt: 100,
},
},
},
);
store.close?.();
const database = new DatabaseSync(join(root, 'runtime.sqlite'));
try {
database
.prepare(`
UPDATE core_agent_run_projections
SET event_json = '{malformed'
WHERE session_id = 'session-1' AND event_type = 'latest_context'
`)
.run();
} finally {
database.close();
}
const reopened = createSqliteAgentRunStore(root);
try {
await reopened.appendEvent(
'session-1',
'run-1',
{
...runEvent(),
id: 'model-call-older',
type: 'model_call_attempt_recorded',
ts: 50,
data: {
...modelCallAttempt({
logicalCallId: 'call-older',
attemptId: 'attempt-older',
traceId: 'trace-older',
completedAt: 50,
latencyMs: 49,
}),
},
},
{
latestContext: {
attemptId: 'attempt-older',
orderedAt: 50,
snapshot: {
schemaVersion: 2,
attemptId: 'attempt-older',
providerId: 'openai',
modelId: 'gpt-5',
completedAt: 50,
},
},
},
);
assert.ok(
(await reopened.readEvents('session-1', 'run-1')).some(
(event) => event.id === 'model-call-older',
),
);
} finally {
reopened.close?.();
}
const inspected = new DatabaseSync(join(root, 'runtime.sqlite'), { readOnly: true });
try {
assert.equal(
inspected
.prepare(`
SELECT event_json AS eventJson
FROM core_agent_run_projections
WHERE session_id = 'session-1' AND event_type = 'latest_context'
`)
.get()?.eventJson,
'{malformed',
'unknown incumbent ordering stays untouched until a ledger rebuild can repair it',
);
} finally {
inspected.close();
}
});
});
test('does not repair a malformed projection from a stale ledger revision', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
await store.createRun(runHeader());
await store.appendEvent('session-1', 'run-1', runEvent());
await store.repairEventProjection(
'session-1',
'history_compact_checkpoint_recorded',
{
...runEvent(),
id: 'checkpoint-a',
type: 'history_compact_checkpoint_recorded',
},
{ ifLedgerRevision: await store.readEventLedgerRevision('session-1') },
);
const database = new DatabaseSync(join(root, 'runtime.sqlite'));
try {
database
.prepare(`
UPDATE core_agent_run_projections
SET event_json = '{malformed'
WHERE session_id = 'session-1'
AND event_type = 'history_compact_checkpoint_recorded'
`)
.run();
} finally {
database.close();
}
const staleRevision = await store.readEventLedgerRevision('session-1');
await store.appendEvent('session-1', 'run-1', {
...runEvent(),
id: 'event-2',
ts: 2,
});
await store.repairEventProjection(
'session-1',
'history_compact_checkpoint_recorded',
{
...runEvent(),
id: 'checkpoint-a',
type: 'history_compact_checkpoint_recorded',
},
{ ifLedgerRevision: staleRevision },
);
const inspected = new DatabaseSync(join(root, 'runtime.sqlite'), { readOnly: true });
try {
assert.equal(
inspected
.prepare(`
SELECT event_json AS eventJson
FROM core_agent_run_projections
WHERE session_id = 'session-1'
AND event_type = 'history_compact_checkpoint_recorded'
`)
.get()?.eventJson,
'{malformed',
);
} finally {
inspected.close();
store.close?.();
}
});
});
test('rejects a projection repair without a canonical ledger revision', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
await store.createRun(runHeader());
await store.appendEvent('session-1', 'run-1', runEvent());
const before = await store.readEventProjection(
'session-1',
'history_compact_checkpoint_recorded',
);
await assert.rejects(
// @ts-expect-error A repair must prove which canonical ledger revision it rebuilt.
store.repairEventProjection('session-1', 'history_compact_checkpoint_recorded', {
...runEvent(),
id: 'checkpoint-a',
type: 'history_compact_checkpoint_recorded',
}),
/ledger revision/i,
);
assert.equal(
await store.readEventProjection('session-1', 'history_compact_checkpoint_recorded'),
before,
);
store.close?.();
});
});
test('backfills the model-call high-water when upgrading existing AgentRun rows', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
await store.createRun(runHeader());
await store.appendEvent('session-1', 'run-1', {
...runEvent(),
id: 'legacy-model-call-event',
type: 'model_call_attempt_recorded',
data: { ...modelCallAttempt() },
});
store.close?.();
const database = new DatabaseSync(join(root, 'runtime.sqlite'));
database.exec(`
DROP INDEX core_agent_runs_model_call_high_water;
ALTER TABLE core_agent_runs DROP COLUMN latest_model_call_sequence;
UPDATE operational_schema_migrations SET version = 3 WHERE scope = 'core_execution';
`);
database.close();
const migrated = createSqliteAgentRunStore(root);
try {
const inspected = new DatabaseSync(join(root, 'runtime.sqlite'), { readOnly: true });
try {
assert.equal(
inspected
.prepare(`
SELECT latest_model_call_sequence AS sequence
FROM core_agent_runs
WHERE session_id = 'session-1' AND run_id = 'run-1'
`)
.get()?.sequence,
0,
);
} finally {
inspected.close();
}
} finally {
migrated.close?.();
}
});
});
test('drops obsolete Host-Epoch message receipt tables on upgrade', async () => {
await withRoot(async (root) => {
createSqliteAgentRunStore(root).close?.();
const path = join(root, 'runtime.sqlite');
const legacy = new DatabaseSync(path);
legacy.exec(`
CREATE TABLE core_message_host_epochs (host_epoch TEXT PRIMARY KEY);
CREATE TABLE core_message_receipts (
host_epoch TEXT NOT NULL,
operation TEXT NOT NULL,
session_id TEXT NOT NULL,
operation_id TEXT NOT NULL,
payload_json TEXT NOT NULL,
result_json TEXT NOT NULL,
PRIMARY KEY (host_epoch, operation, session_id, operation_id)
);
UPDATE operational_schema_migrations SET version = 4 WHERE scope = 'core_execution';
`);
legacy.close();
createSqliteAgentRunStore(root).close?.();
const migrated = new DatabaseSync(path, { readOnly: true });
try {
assert.deepEqual(
migrated
.prepare(
"SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'core_message_%'",
)
.all(),
[],
);
} finally {
migrated.close();
}
});
});
test('drops the obsolete AgentRun identity index on upgrade', async () => {
await withRoot(async (root) => {
createSqliteAgentRunStore(root).close?.();
const path = join(root, 'runtime.sqlite');
const legacy = new DatabaseSync(path);
legacy.exec(`
CREATE INDEX IF NOT EXISTS core_agent_runs_identity
ON core_agent_runs(run_id, session_id);
UPDATE operational_schema_migrations SET version = 5 WHERE scope = 'core_execution';
`);
legacy.close();
createSqliteAgentRunStore(root).close?.();
const migrated = new DatabaseSync(path, { readOnly: true });
try {
assert.deepEqual(
migrated
.prepare(
"SELECT name FROM sqlite_master WHERE type = 'index' AND name = 'core_agent_runs_identity'",
)
.all(),
[],
);
} finally {
migrated.close();
}
});
});
test('pages AgentRuns by stable creation and run identity order', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
try {
await store.createRun(runHeader({ runId: 'run-a', turnId: 'turn-a', createdAt: 1 }));
await store.createRun(runHeader({ runId: 'run-b', turnId: 'turn-b', createdAt: 2 }));
await store.createRun(runHeader({ runId: 'run-c', turnId: 'turn-c', createdAt: 2 }));
const first = await store.listSessionRunsPage('session-1', { limit: 2 });
assert.deepEqual(
first.runs.map((run) => run.runId),
['run-c', 'run-b'],
);
assert.deepEqual(first.nextCursor, { createdAt: 2, runId: 'run-b' });
await store.createRun(runHeader({ runId: 'run-d', turnId: 'turn-d', createdAt: 3 }));
const older = await store.listSessionRunsPage('session-1', {
limit: 2,
before: first.nextCursor ?? undefined,
});
assert.deepEqual(
older.runs.map((run) => run.runId),
['run-a'],
);
assert.equal(older.nextCursor, null);
} finally {
store.close?.();
}
});
});
test('rejects a non-finite AgentRun page cursor', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
try {
await assert.rejects(
store.listSessionRunsPage('session-1', {
limit: 1,
before: { createdAt: Number.NaN, runId: 'run-1' },
}),
/Invalid AgentRun page cursor/u,
);
} finally {
store.close?.();
}
});
});
test('preserves provider failure diagnostics in the AgentRun authority after reopen', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
await store.createRun(runHeader());
await store.appendEvent('session-1', 'run-1', {
type: 'model_call_attempt_recorded',
id: 'attempt-1',
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
ts: 10,
data: {
...modelCallAttempt({
callKind: 'history_compact',
historyCompactRoute: 'provider_native',
connectionSlug: 'codex-subscription',
providerId: 'openai-codex',
modelId: 'gpt-5.6-sol',
completedAt: 10,
latencyMs: 9,
status: 'failed',
errorClass: 'RequestRejected',
httpStatus: 400,
providerCode: 'invalid_request_error',
providerRequestId: 'req-authority-1',
retryable: false,
usageBasis: 'missing',
inputTokens: undefined,
outputTokens: undefined,
costBasis: 'unpriced',
costUsd: undefined,
}),
},
});
store.close?.();
const reopened = createSqliteAgentRunStore(root);
try {
const event = (await reopened.readEvents('session-1', 'run-1'))[0];
const attempt = decodeModelCallAttempt(event?.data);
assert.equal(attempt.historyCompactRoute, 'provider_native');
assert.equal(attempt.httpStatus, 400);
assert.equal(attempt.providerRequestId, 'req-authority-1');
} finally {
reopened.close?.();
}
});
});
test('commits one immutable Run Composition snapshot', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
try {
await store.createRun(runHeader());
const composition = runComposition('1');
await store.updateRun('session-1', 'run-1', { runComposition: composition });
await store.updateRun('session-1', 'run-1', { runComposition: composition });
assert.deepEqual((await store.readRun('session-1', 'run-1')).runComposition, composition);
await assert.rejects(
store.updateRun('session-1', 'run-1', { runComposition: runComposition('2') }),
/AgentRun Run Composition is immutable/u,
);
} finally {
store.close?.();
}
});
});
test('reads an AgentRun event type this build does not write', async () => {
await withRoot(async (root) => {
const store = createSqliteAgentRunStore(root);
await store.createRun(runHeader());
await store.appendEvent('session-1', 'run-1', runEvent());
store.close?.();
// Rewrite the stored row into what a build that still had this writer would have left
// behind. Going through the database rather than appendEvent is the point: this build
// must be able to read a record it is no longer allowed to produce (#1942).
const db = new DatabaseSync(join(root, 'runtime.sqlite'));
try {
const record = {
...runEvent(),
type: 'written_by_another_version',
data: { inputTokens: 7 },
};
db.prepare(
`UPDATE core_agent_run_events SET event_type = ?, record_json = ? WHERE event_id = ?`,
).run('written_by_another_version', JSON.stringify(record), 'event-1');
} finally {
db.close();
}
const reopened = createSqliteAgentRunStore(root);
try {
const events = await reopened.readEvents('session-1', 'run-1');
assert.deepEqual(
events.map((event) => event.type),
['written_by_another_version'],
);
assert.equal(events[0]?.data?.inputTokens, 7);
const recovered = await reopened.readEventsForRecovery('session-1', 'run-1');
assert.deepEqual(
recovered.map((event) => event.type),
['written_by_another_version'],
);
} finally {
reopened.close?.();
}
});
});
test('persists ShellRun records', async () => {
await withRoot(async (root) => {
const store = createSqliteShellRunStore(root);
await store.createShellRun(shellRun());
store.close();
const reopened = createSqliteShellRunStore(root);
try {
assert.equal((await reopened.readShellRun('session-1', 'shell-1')).command, 'printf "ok"');
} finally {
reopened.close();
}
});
});
test('reports a missing ShellRun with the ENOENT store contract', async () => {
await withRoot(async (root) => {
const store = createSqliteShellRunStore(root);
try {
await assert.rejects(store.readShellRun('session-1', 'missing-shell'), { code: 'ENOENT' });
} finally {
store.close();
}
});
});
test('persists interaction request and outcome', async () => {
await withRoot(async (root) => {
const capability = trackControlDirectory(
await resolveStorageRoot({ path: root, kind: 'interactive' }),
);
const owner = await tryAcquireInteractiveRootOwner(capability);
assert.ok(owner);
if (!owner) return;
const store = await openSqliteInteractiveInteractionStoreForWrite(owner.lease);
try {
await store.establishRequest(storedQuestion());
await store.commitOutcome('request-1', questionOutcome());
assert.equal(
(await store.readInteraction('request-1'))?.outcome?.outcome.kind,
'question_answer',
);
} finally {
closeSqliteInteractionStoreFacade(store);
await owner.close();
}
});
});
});
async function withRoot(run: (root: string) => Promise<void>): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-sqlite-execution-'));
try {
await run(root);
} finally {
await rm(root, { recursive: true, force: true });
}
}
function runHeader(overrides: Partial<AgentRunHeader> = {}): AgentRunHeader {
return {
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
status: 'created',
backendKind: 'fake',
llmConnectionSlug: 'fake',
modelId: 'fake-model',
cwd: '/tmp/cwd',
permissionMode: 'ask',
createdAt: 1,
updatedAt: 1,
...overrides,
};
}
function runEvent(): EmittedAgentRunEvent {
return {
type: 'run_started',
id: 'event-1',
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
ts: 2,
};
}
function modelCallAttempt(overrides: Partial<ModelCallAttempt> = {}): ModelCallAttempt {
return {
schemaVersion: MODEL_CALL_ATTEMPT_SCHEMA_VERSION,
logicalCallId: 'call-1',
attemptId: 'attempt-1',
traceId: 'trace-1',
sessionId: 'session-1',
runId: 'run-1',
turnId: 'turn-1',
step: 0,
attempt: 0,
callKind: 'main' as const,
providerId: 'openai',
modelId: 'gpt-5',
startedAt: 1,
completedAt: 2,
latencyMs: 1,
status: 'completed' as const,
usageBasis: 'reported' as const,
inputTokens: 1,
outputTokens: 1,
costBasis: 'priced' as const,
costUsd: 0.001,
...overrides,
};
}
function runComposition(seed: string): NonNullable<AgentRunHeader['runComposition']> {
return {
schemaVersion: 1,
composerId: 'maka.interactive',
composerRevision: '1',
sourceRevisions: [
{ id: 'runtime-policy', revision: '1' },
{ id: 'skill-catalog', revision: 'skills-1' },
],
baseSystemPromptHash: hash(seed),
toolCatalogHash: hash(seed),
toolAvailabilityHash: hash(seed),
baseProviderOptionsHash: hash(seed),
toolNames: ['Read'],
contextWindow: 128_000,
};
}
function hash(seed: string): `sha256:${string}` {
return `sha256:${seed.repeat(64)}`;
}
function shellRun(): ShellRunRecord {
return {
shellRunId: 'shell-1',
sessionId: 'session-1',
sourceRunId: 'run-1',
sourceTurnId: 'turn-1',
sourceToolCallId: 'tool-1',
cwd: '/workspace',
command: 'printf "ok"',
status: 'running',
startedAt: 1,
updatedAt: 1,
revision: 1,
output: {
mode: 'pipes',
stdout: '',
stderr: '',
stdoutTruncated: false,
stderrTruncated: false,
redacted: false,
},
};
}
function storedQuestion(): StoredInteractionRequest {
return {
sessionId: 'session-1',
turnId: 'turn-1',
runId: 'run-1',
requestId: 'request-1',
createdAt: 1,
request: {
kind: 'question',
toolUseId: 'tool-1',
questions: [
{
question: 'Choose',
options: [
{ label: 'First', description: 'First' },
{ label: 'Second', description: 'Second' },
],
},
],
} as InteractionRequest,
};
}
function questionOutcome(): InteractionCanonicalOutcome {
return {
kind: 'question_answer',
answers: ['First'],
committedAt: 2,
} as InteractionCanonicalOutcome;
}
@@ -0,0 +1,154 @@
/*
* 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 assert from 'node:assert/strict';
import { spawn } from 'node:child_process';
import { writeSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { fileURLToPath } from 'node:url';
import type { MemoryItemWrite } from '@maka/core/long-term-memory';
import {
SqliteMemoryItemStore,
type SqliteMemoryItemStoreFailpoint,
} from '../sqlite-long-term-memory-store.js';
const childMode = process.env.MAKA_LONG_TERM_MEMORY_CRASH_CHILD;
if (childMode) {
await runCrashChild(childMode);
} else {
test('retains one committed Item and its receipt when killed between COMMIT and return', {
timeout: 30_000,
}, async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-long-term-memory-crash-'));
const databasePath = join(root, 'memory.sqlite');
const child = spawn(process.execPath, [fileURLToPath(import.meta.url)], {
env: {
...process.env,
MAKA_LONG_TERM_MEMORY_CRASH_CHILD: 'after_commit',
MAKA_LONG_TERM_MEMORY_CRASH_DB: databasePath,
},
stdio: ['ignore', 'pipe', 'pipe'],
});
try {
await waitForReady(child);
child.kill('SIGKILL');
await new Promise<void>((resolve, reject) => {
child.once('exit', () => resolve());
child.once('error', reject);
});
const store = new SqliteMemoryItemStore(databasePath, { now: () => 1_000 });
try {
const record = await store.readItem('crash-item');
assert.equal(record?.item.content, memoryWrite().content);
assert.ok(await store.readOperation('crash-create'));
const replayed = await store.applyMutations({
operationId: 'crash-create',
mutations: [{ type: 'create', item: memoryWrite() }],
});
assert.equal(replayed.replayed, true);
assert.equal(replayed.results[0]?.itemId, 'crash-item');
assert.equal((await store.searchByKeys({ terms: ['crash'], match: 'exact' })).length, 1);
} finally {
store.close();
}
} finally {
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
await rm(root, { recursive: true, force: true });
}
});
}
async function runCrashChild(mode: string): Promise<void> {
if (mode !== 'after_commit') throw new Error(`Unknown long-term memory crash mode ${mode}`);
const databasePath = requiredEnv('MAKA_LONG_TERM_MEMORY_CRASH_DB');
const failpoint = (point: SqliteMemoryItemStoreFailpoint): void => {
if (point === 'after_commit') blockUntilKilled();
};
const store = new SqliteMemoryItemStore(databasePath, {
now: () => 1_000,
idFactory: () => 'crash-item',
failpoint,
});
await store.applyMutations({
operationId: 'crash-create',
mutations: [{ type: 'create', item: memoryWrite() }],
});
throw new Error('Long-term memory crash mode missed its failpoint');
}
function waitForReady(child: ReturnType<typeof spawn>): Promise<void> {
return new Promise((resolve, reject) => {
let stdout = '';
let stderr = '';
child.stdout?.on('data', (chunk) => {
stdout += String(chunk);
if (stdout.includes('READY\n')) resolve();
});
child.stderr?.on('data', (chunk) => {
stderr += String(chunk);
});
child.once('exit', (code, signal) => {
reject(
new Error(
`long-term memory crash child exited before READY: code=${code} signal=${signal} ${stderr}`,
),
);
});
child.once('error', reject);
});
}
function memoryWrite(): MemoryItemWrite {
return {
content: 'Committed before the process was killed.',
kind: 'knowledge',
statementType: 'fact',
temporalType: 'undated',
scopeType: 'global',
observedAt: 900,
origin: 'agent_extracted',
keys: [{ key: 'crash', keyType: 'exact', keyOrigin: 'deterministic' }],
sources: [
{
sessionId: 'session-crash',
runId: 'run-crash',
turnId: 'turn-crash',
eventId: 'event-crash',
},
],
};
}
function blockUntilKilled(): never {
writeSync(1, 'READY\n');
Atomics.wait(new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT)), 0, 0);
throw new Error('unreachable');
}
function requiredEnv(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Missing ${name}`);
return value;
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,702 @@
/*
* 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 assert from 'node:assert/strict';
import { spawn } from 'node:child_process';
import { writeFile } from 'node:fs/promises';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { DatabaseSync } from 'node:sqlite';
import { describe, it } from 'node:test';
import { fileURLToPath } from 'node:url';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { WorkspaceBaselineAuthorityInput } from '@maka/core/workspace-version-authority';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { scanToolLedger } from '@maka/core/tool-ledger-scanner';
import {
SQLITE_RUNTIME_SCHEMA_VERSION,
createSqliteRuntimeStore,
} from '../sqlite-runtime-store.js';
import {
acquireOperationalStateDatabase,
inspectOperationalStateSchema,
} from '../operational-state-store.js';
import {
bindWorkspaceBaselineAuthorityStoreRootInternal,
commitWorkspaceBaselineInternal,
readActiveManagedMutationInternal,
} from '../workspace-version-authority-internal.js';
const WORKER_READY_TIMEOUT_MS = 15_000;
const WORKER_EXECUTION_TIMEOUT_MS = 30_000;
const WORKER_SHUTDOWN_TIMEOUT_MS = 5_000;
interface WorkerResult {
code: number | null;
stdout: string;
stderr: string;
}
interface WorkerHandle {
mode: string;
child: ReturnType<typeof spawn>;
ready: Promise<void>;
opened: Promise<void>;
result: Promise<WorkerResult>;
output(): Pick<WorkerResult, 'stdout' | 'stderr'>;
}
// Race amplification (re-rolling the same interleaving many times) is stress
// coverage, not contract coverage. Same gate the other multi-process storage
// probes use, so there is one stress route rather than a flag per file.
const RUN_RACE_AMPLIFICATION = process.env.MAKA_STORAGE_STRESS === '1';
describe('SQLite recovery authority multi-process races', () => {
it('makes an exact concurrent recovery bundle idempotent', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const results = await runWorkers(dbPath, startPath, ['completed', 'completed']);
assert.deepEqual(
results.map(({ code }) => code),
[0, 0],
);
const store = createSqliteRuntimeStore(dbPath);
try {
assert.equal(
(await store.readToolOperation('operation-1'))?.currentState,
'recovery_completed',
);
assert.equal((await store.readImmutableRuntimeEvents('session-1', 'run-1')).length, 5);
} finally {
store.close();
}
});
});
it('serializes conflicting completed and parked bundles to one terminal decision', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const results = await runWorkers(dbPath, startPath, ['completed', 'parked']);
assert.deepEqual(results.map(({ code }) => code).sort(), [0, 2]);
const store = createSqliteRuntimeStore(dbPath);
try {
const operation = await store.readToolOperation('operation-1');
assert.ok(
operation?.currentState === 'recovery_completed' ||
operation?.currentState === 'recovery_parked',
);
const events = await store.readImmutableRuntimeEvents('session-1', 'run-1');
assert.equal(scanToolLedger(events).hasCorruption, false);
} finally {
store.close();
}
});
});
it('serializes projection rebuild against recovery commit', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const results = await runWorkers(dbPath, startPath, ['completed', 'rebuild']);
assert.deepEqual(
results.map(({ code }) => code),
[0, 0],
);
const store = createSqliteRuntimeStore(dbPath);
try {
assert.equal(
(await store.readToolOperation('operation-1'))?.currentState,
'recovery_completed',
);
assert.equal(
scanToolLedger(await store.readImmutableRuntimeEvents('session-1', 'run-1'))
.hasCorruption,
false,
);
} finally {
store.close();
}
});
});
it('grants provider authority to exactly one process for one continuation boundary', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const results = await runWorkers(dbPath, startPath, ['claim', 'claim']);
assert.deepEqual(
results.map(({ code }) => code),
[0, 0],
);
assert.deepEqual(
results.flatMap(({ stdout }) => stdout.match(/CLAIM (acquired|existing)/g) ?? []).sort(),
['CLAIM acquired', 'CLAIM existing'],
);
});
});
it('never claims an active source while its terminal append races in another process', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const results = await runWorkers(dbPath, startPath, ['claim_nonterminal', 'append_source']);
assert.deepEqual(results.map(({ code }) => code).sort(), [0, 2]);
const store = createSqliteRuntimeStore(dbPath);
try {
const sourceEvents = await store.readImmutableRuntimeEvents('session-1', 'run-1');
const claims = await store.listContinuationClaimsForRecovery('session-1');
assert.equal(sourceEvents.length, 3);
assert.equal(claims.length, 0);
} finally {
store.close();
}
});
});
it('serializes a continuation claim against an ordinary first target event', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const results = await runWorkers(dbPath, startPath, ['claim_fixed_target', 'append_target']);
assert.deepEqual(results.map(({ code }) => code).sort(), [0, 2]);
const store = createSqliteRuntimeStore(dbPath);
try {
const claims = await store.listContinuationClaimsForRecovery('session-1');
const targetEvents = await store.readImmutableRuntimeEvents(
'session-1',
'fixed-target-run',
);
assert.ok(
(claims.length === 1 && targetEvents.length === 0) ||
(claims.length === 0 && targetEvents.length === 1),
);
} finally {
store.close();
}
});
});
it('allows concurrent processes to keep the same initialized WAL database open', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const results = await runOpenWorkers(dbPath, startPath);
assert.deepEqual(
results.map(({ code }) => code),
[0, 0],
);
});
});
it('allows concurrent operational owners to initialize the same fresh WAL database', async () => {
// One round proves the contract: two owners racing to initialize the same
// fresh database both succeed, and the result is a WAL database at the
// current schema version. Repetition does not make that assertion stronger
// — it re-rolls the scheduler hoping to catch a rarer interleaving, which
// is stress, not contract coverage. The extra rounds stay available on the
// storage stress route (MAKA_STORAGE_STRESS=1) alongside the other
// multi-process probes, and out of every ordinary run.
const rounds = RUN_RACE_AMPLIFICATION ? 12 : 1;
for (let round = 0; round < rounds; round += 1) {
const root = await mkdtemp(join(tmpdir(), 'maka-operational-fresh-open-race-'));
const dbPath = join(root, 'runtime.sqlite');
const startPath = join(root, 'start');
try {
const results = await runOpenWorkers(dbPath, startPath, 'operational_open_only');
assert.deepEqual(
results.map(({ code }) => code),
[0, 0],
`fresh concurrent operational open failed in round ${round + 1}: ${JSON.stringify(results)}`,
);
const database = new DatabaseSync(dbPath, { readOnly: true });
try {
assert.equal(
(database.prepare('PRAGMA journal_mode').get() as { journal_mode: string })
.journal_mode,
'wal',
);
assert.equal(
(database.prepare('PRAGMA user_version').get() as { user_version: number })
.user_version,
SQLITE_RUNTIME_SCHEMA_VERSION,
);
} finally {
database.close();
}
} finally {
await rm(root, { recursive: true, force: true });
}
}
});
it('makes an exact concurrent workspace baseline open idempotent', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const results = await runWorkers(dbPath, startPath, [
'workspace_baseline_a',
'workspace_baseline_a',
]);
assert.deepEqual(
results.map(({ code }) => code),
[0, 0],
);
assert.deepEqual(
results
.flatMap(({ stdout }) =>
stdout.includes('BASELINE created')
? ['created']
: stdout.includes('BASELINE existing')
? ['existing']
: [],
)
.sort(),
['created', 'existing'],
);
});
});
it('accepts only one of two conflicting concurrent workspace baselines', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const results = await runWorkers(dbPath, startPath, [
'workspace_baseline_a',
'workspace_baseline_b',
]);
assert.deepEqual(results.map(({ code }) => code).sort(), [0, 2]);
assert.equal(
results.filter(({ stderr }) => /Workspace baseline authority conflict/.test(stderr)).length,
1,
);
const store = createSqliteRuntimeStore(dbPath);
try {
const head = await store.readWorkspaceHead(
`workspace_${'2'.repeat(32)}`,
`epoch_${'3'.repeat(32)}`,
);
assert.ok(
head?.workspaceVersionId === `version_${'5'.repeat(32)}` ||
head?.workspaceVersionId === `version_${'9'.repeat(32)}`,
);
} finally {
store.close();
}
});
});
it('grants durable managed mutation ownership to exactly one process', async () => {
await withPreparedDatabase(async ({ dbPath, startPath }) => {
const setupStore = createSqliteRuntimeStore(dbPath);
try {
bindWorkspaceBaselineAuthorityStoreRootInternal(setupStore, 'a'.repeat(64));
await commitWorkspaceBaselineInternal(setupStore, workspaceBaselineInput('a'));
} finally {
setupStore.close();
}
const results = await runWorkers(dbPath, startPath, [
'managed_mutation_a',
'managed_mutation_b',
]);
assert.deepEqual(results.map(({ code }) => code).sort(), [0, 2]);
assert.equal(
results.filter(({ stderr }) => /managed mutation reservation conflict/i.test(stderr))
.length,
1,
);
const store = createSqliteRuntimeStore(dbPath);
try {
bindWorkspaceBaselineAuthorityStoreRootInternal(store, 'a'.repeat(64));
const reservation = await readActiveManagedMutationInternal(
store,
`instance_${'4'.repeat(32)}`,
);
assert.ok(
reservation?.operationId === 'managed-mutation-a' ||
reservation?.operationId === 'managed-mutation-b',
);
} finally {
store.close();
}
});
});
it('serializes concurrent operational runtime migration', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-operational-migration-race-'));
const dbPath = join(root, 'runtime.sqlite');
const startPath = join(root, 'start');
try {
acquireOperationalStateDatabase(root).close();
const db = new DatabaseSync(dbPath);
try {
db.exec(`
DROP TABLE runtime_managed_mutation_reservations;
DROP TABLE runtime_session_event_ordinals;
PRAGMA user_version = 10;
UPDATE operational_schema_migrations SET version = 10 WHERE scope = 'runtime';
`);
} finally {
db.close();
}
const results = await runOpenWorkers(dbPath, startPath, 'operational_open_only');
assert.deepEqual(
results.map(({ code }) => code),
[0, 0],
);
const upgraded = createSqliteRuntimeStore(dbPath);
try {
assert.equal(upgraded.schemaVersion(), SQLITE_RUNTIME_SCHEMA_VERSION);
} finally {
upgraded.close();
}
const current = new DatabaseSync(dbPath, { readOnly: true });
try {
assert.equal(inspectOperationalStateSchema(current).status, 'current');
} finally {
current.close();
}
} finally {
await rm(root, { recursive: true, force: true });
}
});
it('captures a fast worker initialization failure after releasing the barrier', async () => {
const root = await mkdtemp(join(tmpdir(), 'maka-recovery-race-invalid-db-'));
try {
const results = await runWorkers(root, join(root, 'start'), ['completed']);
assert.equal(results[0]?.code, 2);
assert.match(results[0]?.stderr ?? '', /RESULT error/);
} finally {
await rm(root, { recursive: true, force: true });
}
});
});
async function withPreparedDatabase(
run: (input: { dbPath: string; startPath: string }) => Promise<void>,
): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-recovery-race-'));
const dbPath = join(root, 'runtime.sqlite');
const startPath = join(root, 'start');
const store = createSqliteRuntimeStore(dbPath);
try {
bindWorkspaceBaselineAuthorityStoreRootInternal(store, 'a'.repeat(64));
await store.commitToolPrepared(preparedCommit());
await store.appendRuntimeEvent('session-1', 'continuation-source-run', {
id: 'continuation-source-user',
sessionId: 'session-1',
invocationId: 'continuation-source-invocation',
runId: 'continuation-source-run',
turnId: 'continuation-source-turn',
ts: 10,
partial: false,
role: 'user',
author: 'user',
content: { kind: 'text', text: 'continue after this completed boundary' },
});
await store.ensureTerminalRuntimeEventDurable('session-1', 'continuation-source-run', {
id: 'continuation-source-terminal',
sessionId: 'session-1',
invocationId: 'continuation-source-invocation',
runId: 'continuation-source-run',
turnId: 'continuation-source-turn',
ts: 11,
partial: false,
role: 'system',
author: 'system',
status: 'failed',
actions: {
endInvocation: true,
stateDelta: { failureClass: 'runtime_interrupted' },
},
});
store.close();
await run({ dbPath, startPath });
} finally {
store.close();
await rm(root, { recursive: true, force: true });
}
}
async function runWorkers(
dbPath: string,
startPath: string,
modes: readonly string[],
): Promise<WorkerResult[]> {
const workers = modes.map((mode) => startWorker(dbPath, startPath, mode));
try {
await withTimeout(
Promise.all(workers.map(({ ready }) => ready)),
WORKER_READY_TIMEOUT_MS,
'workers to reach the start barrier',
);
await writeFile(startPath, 'go');
return await withTimeout(
Promise.all(workers.map(({ result }) => result)),
WORKER_EXECUTION_TIMEOUT_MS,
'workers to finish their SQLite operations',
);
} catch (error) {
await stopWorkers(workers);
const diagnostics = workers.map(formatWorkerDiagnostics).join('\n');
throw new Error(`${error instanceof Error ? error.message : String(error)}\n${diagnostics}`);
}
}
async function runOpenWorkers(
dbPath: string,
startPath: string,
mode = 'open_only',
): Promise<WorkerResult[]> {
const stopPath = `${startPath}.stop`;
const workers = [mode, mode].map((workerMode) =>
startWorker(dbPath, startPath, workerMode, stopPath),
);
try {
await withTimeout(
Promise.all(workers.map(({ ready }) => ready)),
WORKER_READY_TIMEOUT_MS,
'workers to reach the concurrent-open start barrier',
);
await writeFile(startPath, 'go');
await withTimeout(
Promise.all(workers.map(({ opened }) => opened)),
WORKER_READY_TIMEOUT_MS,
'workers to open the same SQLite database',
);
await writeFile(stopPath, 'close');
return await withTimeout(
Promise.all(workers.map(({ result }) => result)),
WORKER_EXECUTION_TIMEOUT_MS,
'concurrent-open workers to close',
);
} catch (error) {
await stopWorkers(workers);
const diagnostics = workers.map(formatWorkerDiagnostics).join('\n');
throw new Error(`${error instanceof Error ? error.message : String(error)}\n${diagnostics}`);
}
}
function startWorker(
dbPath: string,
startPath: string,
mode: string,
stopPath?: string,
): WorkerHandle {
const child = spawn(
process.execPath,
[fileURLToPath(new URL('./fixtures/sqlite-recovery-concurrency-child.js', import.meta.url))],
{
env: {
...process.env,
MAKA_SQLITE_RECOVERY_CONCURRENCY_MODE: mode,
MAKA_SQLITE_RECOVERY_CONCURRENCY_DB: dbPath,
MAKA_SQLITE_RECOVERY_CONCURRENCY_START: startPath,
...(stopPath ? { MAKA_SQLITE_RECOVERY_CONCURRENCY_STOP: stopPath } : {}),
},
stdio: ['ignore', 'pipe', 'pipe'],
},
);
let stdout = '';
let stderr = '';
let readySeen = false;
let openedSeen = false;
let resolveReady!: () => void;
let rejectReady!: (error: Error) => void;
let resolveOpened!: () => void;
let rejectOpened!: (error: Error) => void;
const ready = new Promise<void>((resolve, reject) => {
resolveReady = resolve;
rejectReady = reject;
});
const opened = new Promise<void>((resolve, reject) => {
resolveOpened = resolve;
rejectOpened = reject;
});
const result = new Promise<WorkerResult>((resolve, reject) => {
child.once('error', (error) => {
rejectReady(error);
rejectOpened(error);
reject(error);
});
child.once('close', (code) => {
if (!readySeen) {
rejectReady(new Error(`worker ${mode} exited before READY: ${code} ${stderr}`));
}
if (!openedSeen) {
rejectOpened(new Error(`worker ${mode} exited before OPENED: ${code} ${stderr}`));
}
resolve({ code, stdout, stderr });
});
});
// A worker can fail before the coordinator reaches the phase that awaits one
// of these promises. Attach handlers immediately so the diagnostic path, not
// the process-level unhandled-rejection policy, owns the failure.
void opened.catch(() => {});
void result.catch(() => {});
child.stdout?.on('data', (chunk) => {
stdout += String(chunk);
if (!readySeen && stdout.includes('READY\n')) {
readySeen = true;
resolveReady();
}
if (!openedSeen && stdout.includes('OPENED\n')) {
openedSeen = true;
resolveOpened();
}
});
child.stderr?.on('data', (chunk) => {
stderr += String(chunk);
});
return {
mode,
child,
ready,
opened,
result,
output: () => ({ stdout, stderr }),
};
}
async function stopWorkers(workers: readonly WorkerHandle[]): Promise<void> {
for (const { child } of workers) {
if (child.exitCode === null && child.signalCode === null) {
child.kill('SIGKILL');
}
}
await withTimeout(
Promise.allSettled(workers.map(({ result }) => result)),
WORKER_SHUTDOWN_TIMEOUT_MS,
'workers to stop',
).catch(() => {});
}
function formatWorkerDiagnostics(worker: WorkerHandle): string {
const { stdout, stderr } = worker.output();
const state =
worker.child.exitCode !== null
? `exit=${worker.child.exitCode}`
: worker.child.signalCode !== null
? `signal=${worker.child.signalCode}`
: 'still-running';
return [
`worker mode=${worker.mode} pid=${worker.child.pid ?? 'unknown'} ${state}`,
`stdout=${JSON.stringify(stdout)}`,
`stderr=${JSON.stringify(stderr)}`,
].join('\n');
}
async function withTimeout<T>(
promise: Promise<T>,
timeoutMs: number,
description: string,
): Promise<T> {
let timer: ReturnType<typeof setTimeout> | undefined;
try {
return await Promise.race([
promise,
new Promise<never>((_, reject) => {
timer = setTimeout(
() => reject(new Error(`Timed out after ${timeoutMs}ms waiting for ${description}`)),
timeoutMs,
);
}),
]);
} finally {
if (timer !== undefined) clearTimeout(timer);
}
}
function preparedCommit() {
const args = { path: 'notes.txt', content: 'after' };
const hash = canonicalToolArgsHash('Write', args);
return {
operationId: 'operation-1',
journalEventId: 'operation-1_prepared',
runtimeEvent: {
...baseEvent('call-event-1', 1),
role: 'model' as const,
author: 'agent' as const,
content: {
kind: 'function_call' as const,
id: 'provider-call-1',
name: 'Write',
args,
},
},
dispatchRuntimeEvent: {
...baseEvent('dispatch-event-1', 2),
actions: {
toolDispatch: {
protocol: 't1_after_preflight_v1' as const,
operationId: 'operation-1',
providerToolCallId: 'provider-call-1',
toolName: 'Write',
canonicalArgsHash: hash,
recoveryMode: 'reconcile' as const,
},
},
refs: { operationId: 'operation-1', toolCallId: 'provider-call-1' },
},
providerToolCallId: 'provider-call-1',
toolName: 'Write',
canonicalArgsHash: hash,
recoveryMode: 'reconcile' as const,
committedAt: 2,
};
}
function workspaceBaselineInput(variant: 'a' | 'b'): WorkspaceBaselineAuthorityInput {
const alternate = variant === 'b';
return {
epochOpenedEventId: alternate ? 'workspace-epoch-event-b' : 'workspace-epoch-event-a',
baselineAcceptedEventId: alternate ? 'workspace-version-event-b' : 'workspace-version-event-a',
committedAt: 1_700_000_000_000,
epoch: {
repositoryId: `repository_${'1'.repeat(32)}`,
workspaceId: `workspace_${'2'.repeat(32)}`,
workspaceEpochId: `epoch_${'3'.repeat(32)}`,
workspaceInstanceId: `instance_${'4'.repeat(32)}`,
mode: 'managed_worktree',
objectFormat: 'sha1',
sourceCommitOid: '1'.repeat(40),
sourceTreeOid: '2'.repeat(40),
materializationProfileDigest: `sha256:${'3'.repeat(64)}`,
materializationSemantics: 'git_tree_materialized_with_fixed_config_v1',
policyHash: `sha256:${'4'.repeat(64)}`,
},
baseline: {
workspaceVersionId: `version_${(alternate ? '9' : '5').repeat(32)}`,
commitOid: (alternate ? '9' : '5').repeat(40),
treeOid: '2'.repeat(40),
treeDeltaDigest: `sha256:${'6'.repeat(64)}`,
changedFileCount: 7,
deletedFileCount: 0,
},
};
}
function baseEvent(id: string, ts: number): RuntimeEvent {
return {
id,
invocationId: 'invocation-1',
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
ts,
partial: false,
role: 'system',
author: 'system',
};
}
@@ -0,0 +1,798 @@
/*
* 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 assert from 'node:assert/strict';
import { spawn } from 'node:child_process';
import { mkdtemp, readFile, rm } from 'node:fs/promises';
import { writeFileSync, writeSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';
import { fileURLToPath } from 'node:url';
import { type RuntimeEvent } from '@maka/core/runtime-event';
import {
type WorkspaceBaselineAuthorityInput,
type WorkspaceSuccessorAuthorityInput,
} from '@maka/core/workspace-version-authority';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import {
createSqliteRuntimeStore,
type SqliteRuntimeStoreFailpoint,
} from '../sqlite-runtime-store.js';
import {
bindWorkspaceBaselineAuthorityStoreRootInternal,
commitManagedMutationTerminalInternal,
commitWorkspaceBaselineInternal,
commitWorkspaceSuccessorInternal,
readActiveManagedMutationInternal,
registerManagedMutationNoEffectVerifierInternal,
registerWorkspaceSuccessorCandidateVerifierInternal,
type ManagedMutationNoEffectClaimV1,
type WorkspaceSuccessorCommitInput,
} from '../workspace-version-authority-internal.js';
const CRASH_READ_ARGS_HASH = canonicalToolArgsHash('Read', {
path: '/workspace/README.md',
});
const CRASH_CANDIDATES = new WeakMap<object, WorkspaceSuccessorAuthorityInput>();
const CRASH_NO_EFFECT_CLAIMS = new WeakMap<object, ManagedMutationNoEffectClaimV1>();
function registerCrashCandidateVerifier(store: object): void {
registerWorkspaceSuccessorCandidateVerifierInternal(store, (capability) => {
const successor = CRASH_CANDIDATES.get(capability);
if (!successor) throw new Error('Unrecognized crash-test candidate capability');
return structuredClone(successor);
});
registerManagedMutationNoEffectVerifierInternal(store, (capability) => {
const claim = CRASH_NO_EFFECT_CLAIMS.get(capability);
if (!claim) throw new Error('Unrecognized crash-test no-effect capability');
return structuredClone(claim);
});
}
function issueCrashNoEffect(claim: ManagedMutationNoEffectClaimV1): object {
const capability = Object.freeze({});
CRASH_NO_EFFECT_CLAIMS.set(capability, structuredClone(claim));
return capability;
}
const childMode = process.env.MAKA_SQLITE_CRASH_CHILD;
if (childMode) {
await runCrashChild(childMode);
} else {
describe('SqliteRuntimeStore real-process crash boundaries', () => {
it('rolls back a process killed inside T1', { timeout: 30_000 }, async () => {
await withKilledChild('inside_t1', async (store) => {
assert.deepEqual(await store.readRuntimeEvents('session-1', 'run-1'), []);
assert.deepEqual(await store.listUnsettledToolOperations(), []);
});
});
it('retains a prepared operation when killed after T1 and a possible side effect', {
timeout: 30_000,
}, async () => {
await withKilledChild('after_effect', async (store, markerPath) => {
assert.equal(await readFile(markerPath, 'utf8'), 'effect-happened');
assert.deepEqual(
(await store.readRuntimeEvents('session-1', 'run-1')).map((event) => event.id),
['call-event-1', 'dispatch-event-1'],
);
assert.deepEqual(
(await store.listUnsettledToolOperations()).map((operation) => operation.operationId),
['operation-1'],
);
});
});
it('rolls back a process killed inside T2 without losing T1', { timeout: 30_000 }, async () => {
await withKilledChild('inside_t2', async (store) => {
assert.deepEqual(
(await store.readRuntimeEvents('session-1', 'run-1')).map((event) => event.id),
['call-event-1', 'dispatch-event-1'],
);
assert.equal((await store.readToolOperation('operation-1'))?.currentState, 'prepared');
});
});
it('retains the committed outcome when killed after T2', { timeout: 30_000 }, async () => {
await withKilledChild('after_t2', async (store) => {
assert.deepEqual(
(await store.readRuntimeEvents('session-1', 'run-1')).map((event) => event.id),
['call-event-1', 'dispatch-event-1', 'response-event-1'],
);
assert.equal(
(await store.readToolOperation('operation-1'))?.currentState,
'outcome_committed',
);
assert.deepEqual(await store.listUnsettledToolOperations(), []);
});
});
for (const mode of [
'inside_recovery_reconcile',
'inside_recovery_outcome',
'inside_recovery_decision',
]) {
it(`rolls back the whole recovery bundle when killed at ${mode}`, {
timeout: 30_000,
}, async () => {
await withKilledChild(mode, async (store) => {
assert.deepEqual(
(await store.readRuntimeEvents('session-1', 'run-1')).map((event) => event.id),
['call-event-1', 'dispatch-event-1'],
);
assert.equal((await store.readToolOperation('operation-1'))?.currentState, 'prepared');
});
});
}
it('retains the whole recovery bundle when killed after COMMIT', {
timeout: 30_000,
}, async () => {
await withKilledChild('after_recovery_commit', async (store) => {
assert.deepEqual(
(await store.readRuntimeEvents('session-1', 'run-1')).map((event) => event.id),
[
'call-event-1',
'dispatch-event-1',
'reconcile-event-1',
'response-event-1',
'decision-event-1',
],
);
assert.equal(
(await store.readToolOperation('operation-1'))?.currentState,
'recovery_completed',
);
});
});
it('rolls back a workspace baseline when killed inside its authority transaction', {
timeout: 30_000,
}, async () => {
await withKilledChild('inside_workspace_baseline', async (store) => {
assert.equal(
await store.readWorkspaceHead(`workspace_${'2'.repeat(32)}`, `epoch_${'3'.repeat(32)}`),
undefined,
);
});
});
it('retains the complete workspace baseline when killed after COMMIT', {
timeout: 30_000,
}, async () => {
await withKilledChild('after_workspace_baseline_commit', async (store) => {
assert.equal(
(await store.readWorkspaceHead(`workspace_${'2'.repeat(32)}`, `epoch_${'3'.repeat(32)}`))
?.workspaceVersionId,
`version_${'5'.repeat(32)}`,
);
});
});
it('retains exclusive managed mutation ownership when killed after T1', {
timeout: 30_000,
}, async () => {
await withKilledChild('after_workspace_mutation_t1', async (store) => {
bindWorkspaceBaselineAuthorityStoreRootInternal(store, 'a'.repeat(64));
assert.equal(
(await readActiveManagedMutationInternal(store, `instance_${'4'.repeat(32)}`))
?.operationId,
'workspace-successor-operation',
);
await assert.rejects(
store.commitToolPrepared(
workspaceSuccessorPreparedCommit('workspace-conflicting-operation'),
),
/managed mutation reservation conflict/i,
);
});
});
it('rolls back a workspace successor when killed inside its authority transaction', {
timeout: 30_000,
}, async () => {
await withKilledChild('inside_workspace_successor', async (store) => {
assert.equal(
(await store.readWorkspaceHead(`workspace_${'2'.repeat(32)}`, `epoch_${'3'.repeat(32)}`))
?.workspaceVersionId,
`version_${'5'.repeat(32)}`,
);
assert.equal(
(await store.readToolOperation('workspace-successor-operation'))?.currentState,
'prepared',
);
assert.equal(await store.readWorkspaceVersion(`version_${'7'.repeat(32)}`), undefined);
});
});
it('returns the accepted workspace successor after a process is killed post-commit', {
timeout: 30_000,
}, async () => {
await withKilledChild('after_workspace_successor_commit', async (store) => {
bindWorkspaceBaselineAuthorityStoreRootInternal(store, 'a'.repeat(64));
const retry = await commitWorkspaceSuccessorInternal(store, workspaceSuccessorCommit());
assert.equal(retry.created, false);
assert.equal(retry.committedSuccessor.workspaceVersionId, `version_${'7'.repeat(32)}`);
assert.equal(
(await store.readToolOperation('workspace-successor-operation'))?.currentState,
'outcome_committed',
);
});
});
it('rolls back a no-effect terminal when killed inside its transaction', {
timeout: 30_000,
}, async () => {
await withKilledChild('inside_workspace_terminal', async (store) => {
bindWorkspaceBaselineAuthorityStoreRootInternal(store, 'a'.repeat(64));
assert.equal(
(await store.readToolOperation('workspace-successor-operation'))?.currentState,
'prepared',
);
assert.equal(
(await readActiveManagedMutationInternal(store, `instance_${'4'.repeat(32)}`))
?.operationId,
'workspace-successor-operation',
);
});
});
it('retains a no-effect terminal and released reservation after process exit', {
timeout: 30_000,
}, async () => {
await withKilledChild('after_workspace_terminal_commit', async (store) => {
bindWorkspaceBaselineAuthorityStoreRootInternal(store, 'a'.repeat(64));
assert.equal(
(await store.readToolOperation('workspace-successor-operation'))?.currentState,
'outcome_committed',
);
assert.equal(
await readActiveManagedMutationInternal(store, `instance_${'4'.repeat(32)}`),
undefined,
);
});
});
});
}
async function withKilledChild(
mode: string,
inspect: (
store: ReturnType<typeof createSqliteRuntimeStore>,
markerPath: string,
) => Promise<void>,
): Promise<void> {
const root = await mkdtemp(join(tmpdir(), 'maka-sqlite-crash-'));
const dbPath = join(root, 'runtime.sqlite');
const markerPath = join(root, 'effect.marker');
const child = spawn(process.execPath, [fileURLToPath(import.meta.url)], {
env: {
...process.env,
MAKA_SQLITE_CRASH_CHILD: mode,
MAKA_SQLITE_CRASH_DB: dbPath,
MAKA_SQLITE_CRASH_MARKER: markerPath,
},
stdio: ['ignore', 'pipe', 'pipe'],
});
try {
await waitForReady(child);
child.kill('SIGKILL');
await new Promise<void>((resolve, reject) => {
child.once('exit', () => resolve());
child.once('error', reject);
});
const store = createSqliteRuntimeStore(dbPath);
registerCrashCandidateVerifier(store);
try {
await inspect(store, markerPath);
} finally {
store.close();
}
} finally {
if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
await rm(root, { recursive: true, force: true });
}
}
function waitForReady(child: ReturnType<typeof spawn>): Promise<void> {
return new Promise((resolve, reject) => {
let stdout = '';
let stderr = '';
child.stdout?.on('data', (chunk) => {
stdout += String(chunk);
if (stdout.includes('READY\n')) resolve();
});
child.stderr?.on('data', (chunk) => {
stderr += String(chunk);
});
child.once('exit', (code, signal) => {
reject(new Error(`crash child exited before READY: code=${code} signal=${signal} ${stderr}`));
});
child.once('error', reject);
});
}
async function runCrashChild(mode: string): Promise<void> {
const dbPath = requiredEnv('MAKA_SQLITE_CRASH_DB');
const markerPath = requiredEnv('MAKA_SQLITE_CRASH_MARKER');
let runtimeInsertCount = 0;
const failpoint = (point: SqliteRuntimeStoreFailpoint) => {
if (point === 'after_runtime_event_insert') {
runtimeInsertCount += 1;
if (mode === 'inside_t1' && runtimeInsertCount === 1) blockUntilKilled();
if (mode === 'inside_t2' && runtimeInsertCount === 2) blockUntilKilled();
if (mode === 'inside_workspace_terminal' && runtimeInsertCount === 2) blockUntilKilled();
}
if (point === 'after_recovery_reconcile' && mode === 'inside_recovery_reconcile') {
blockUntilKilled();
}
if (point === 'after_recovery_outcome' && mode === 'inside_recovery_outcome') {
blockUntilKilled();
}
if (point === 'after_recovery_decision' && mode === 'inside_recovery_decision') {
blockUntilKilled();
}
if (point === 'after_workspace_version_event_insert' && mode === 'inside_workspace_baseline') {
blockUntilKilled();
}
if (
point === 'after_workspace_successor_event_insert' &&
mode === 'inside_workspace_successor'
) {
blockUntilKilled();
}
};
const store = createSqliteRuntimeStore(dbPath, { failpoint });
registerCrashCandidateVerifier(store);
if (
mode === 'inside_workspace_baseline' ||
mode === 'after_workspace_baseline_commit' ||
mode === 'after_workspace_mutation_t1' ||
mode === 'inside_workspace_successor' ||
mode === 'after_workspace_successor_commit' ||
mode === 'inside_workspace_terminal' ||
mode === 'after_workspace_terminal_commit'
) {
bindWorkspaceBaselineAuthorityStoreRootInternal(store, 'a'.repeat(64));
await commitWorkspaceBaselineInternal(store, workspaceBaselineInput());
if (mode === 'after_workspace_baseline_commit') blockUntilKilled();
if (mode === 'after_workspace_mutation_t1') {
await store.commitToolPrepared(workspaceSuccessorPreparedCommit());
blockUntilKilled();
}
if (mode === 'inside_workspace_successor' || mode === 'after_workspace_successor_commit') {
await store.commitToolPrepared(workspaceSuccessorPreparedCommit());
await commitWorkspaceSuccessorInternal(store, workspaceSuccessorCommit());
if (mode === 'after_workspace_successor_commit') blockUntilKilled();
}
if (mode === 'inside_workspace_terminal' || mode === 'after_workspace_terminal_commit') {
await store.commitToolPrepared(workspaceSuccessorPreparedCommit());
await commitManagedMutationTerminalInternal(store, workspaceTerminalCommit());
if (mode === 'after_workspace_terminal_commit') blockUntilKilled();
}
throw new Error(`Workspace baseline crash mode ${mode} missed its failpoint`);
}
await store.commitToolPrepared(preparedCommit());
if (mode === 'after_effect') {
writeFileSync(markerPath, 'effect-happened');
blockUntilKilled();
}
if (mode.startsWith('inside_recovery_') || mode === 'after_recovery_commit') {
await store.commitToolRecoveryBundle(recoveryCommit());
if (mode === 'after_recovery_commit') blockUntilKilled();
throw new Error(`Recovery crash mode ${mode} missed its failpoint`);
}
await store.commitToolOutcome(outcomeCommit());
if (mode === 'after_t2') blockUntilKilled();
throw new Error(`Unknown crash child mode ${mode}`);
}
function blockUntilKilled(): never {
writeSync(1, 'READY\n');
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0);
throw new Error('unreachable');
}
function requiredEnv(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Missing ${name}`);
return value;
}
function preparedCommit() {
return {
operationId: 'operation-1',
journalEventId: 'operation-1_prepared',
runtimeEvent: functionCallEvent(),
dispatchRuntimeEvent: toolDispatchEvent(),
providerToolCallId: 'provider-call-1',
toolName: 'Read',
canonicalArgsHash: CRASH_READ_ARGS_HASH,
recoveryMode: 'reconcile' as const,
committedAt: 1,
};
}
function workspaceBaselineInput(): WorkspaceBaselineAuthorityInput {
return {
epochOpenedEventId: 'workspace-epoch-event-1',
baselineAcceptedEventId: 'workspace-version-event-1',
committedAt: 1_700_000_000_000,
epoch: {
repositoryId: `repository_${'1'.repeat(32)}`,
workspaceId: `workspace_${'2'.repeat(32)}`,
workspaceEpochId: `epoch_${'3'.repeat(32)}`,
workspaceInstanceId: `instance_${'4'.repeat(32)}`,
mode: 'managed_worktree',
objectFormat: 'sha1',
sourceCommitOid: '1'.repeat(40),
sourceTreeOid: '2'.repeat(40),
materializationProfileDigest: `sha256:${'3'.repeat(64)}`,
materializationSemantics: 'git_tree_materialized_with_fixed_config_v1',
policyHash: `sha256:${'4'.repeat(64)}`,
},
baseline: {
workspaceVersionId: `version_${'5'.repeat(32)}`,
commitOid: '5'.repeat(40),
treeOid: '2'.repeat(40),
treeDeltaDigest: `sha256:${'6'.repeat(64)}`,
changedFileCount: 7,
deletedFileCount: 0,
},
};
}
function workspaceSuccessorPreparedCommit(operationId = 'workspace-successor-operation') {
const args = { path: 'notes.txt', content: 'successor' };
const canonicalArgsHash = canonicalToolArgsHash('Write', args);
const isCanonicalFixture = operationId === 'workspace-successor-operation';
const toolCallId = isCanonicalFixture ? 'workspace-successor-call-id' : `${operationId}-call-id`;
const callEventId = isCanonicalFixture ? 'workspace-successor-call' : `${operationId}-call`;
const dispatchEventId = isCanonicalFixture
? 'workspace-successor-dispatch'
: `${operationId}-dispatch`;
return {
operationId,
journalEventId: `${operationId}_prepared`,
runtimeEvent: {
id: callEventId,
invocationId: 'workspace-successor-invocation',
runId: 'workspace-successor-run',
sessionId: 'workspace-successor-session',
turnId: 'workspace-successor-turn',
ts: 1_700_000_000_001,
partial: false,
role: 'model' as const,
author: 'agent' as const,
content: {
kind: 'function_call' as const,
id: toolCallId,
name: 'Write',
args,
},
refs: {
operationId,
toolCallId,
},
},
dispatchRuntimeEvent: {
id: dispatchEventId,
invocationId: 'workspace-successor-invocation',
runId: 'workspace-successor-run',
sessionId: 'workspace-successor-session',
turnId: 'workspace-successor-turn',
ts: 1_700_000_000_001,
partial: false,
role: 'system' as const,
author: 'system' as const,
actions: {
toolDispatch: {
protocol: 't1_after_preflight_v1' as const,
operationId,
providerToolCallId: toolCallId,
toolName: 'Write',
canonicalArgsHash,
recoveryMode: 'reconcile' as const,
managedMutation: {
protocol: 'managed_mutation_v2' as const,
repositoryId: `repository_${'1'.repeat(32)}`,
workspaceId: `workspace_${'2'.repeat(32)}`,
workspaceEpochId: `epoch_${'3'.repeat(32)}`,
workspaceInstanceId: `instance_${'4'.repeat(32)}`,
objectFormat: 'sha1' as const,
baseWorkspaceVersionId: `version_${'5'.repeat(32)}`,
baseAcceptedEventId: 'workspace-version-event-1',
baseHeadRevision: 1,
baseCommitOid: '5'.repeat(40),
baseTreeOid: '2'.repeat(40),
expectedPath: 'notes.txt',
pathPolicyVersion: 3 as const,
executionProfileDigest:
'sha256:ffdfdda9cf38f382e0c4db81dac7319cd33586a6c65051a97a15e6c41b88f825' as const,
},
},
},
refs: {
operationId,
toolCallId,
},
},
providerToolCallId: toolCallId,
toolName: 'Write',
canonicalArgsHash,
recoveryMode: 'reconcile' as const,
committedAt: 1_700_000_000_001,
};
}
function workspaceSuccessorCommit(): WorkspaceSuccessorCommitInput {
const successor: WorkspaceSuccessorAuthorityInput = {
acceptedEventId: 'workspace-successor-accepted',
committedAt: 1_700_000_000_002,
successor: {
repositoryId: `repository_${'1'.repeat(32)}`,
workspaceId: `workspace_${'2'.repeat(32)}`,
workspaceEpochId: `epoch_${'3'.repeat(32)}`,
workspaceVersionId: `version_${'7'.repeat(32)}`,
objectFormat: 'sha1',
parentWorkspaceVersionId: `version_${'5'.repeat(32)}`,
baseAcceptedEventId: 'workspace-version-event-1',
baseHeadRevision: 1,
commitOid: '7'.repeat(40),
treeOid: '8'.repeat(40),
policyHash: `sha256:${'4'.repeat(64)}`,
treeDeltaDigest: `sha256:${'9'.repeat(64)}`,
changedPaths: ['notes.txt'],
changedFileCount: 1,
deletedFileCount: 0,
executionProfileDigest:
'sha256:ffdfdda9cf38f382e0c4db81dac7319cd33586a6c65051a97a15e6c41b88f825' as const,
},
origin: {
operationId: 'workspace-successor-operation',
dispatchEventId: 'workspace-successor-dispatch',
outcomeEventId: 'workspace-successor-outcome',
},
};
const candidateOutcome = Object.freeze({});
CRASH_CANDIDATES.set(candidateOutcome, successor);
return {
candidateOutcome,
toolOutcome: {
operationId: 'workspace-successor-operation',
journalEventId: 'workspace-successor-operation_outcome',
committedAt: 1_700_000_000_002,
runtimeEvent: {
id: 'workspace-successor-outcome',
invocationId: 'workspace-successor-invocation',
runId: 'workspace-successor-run',
sessionId: 'workspace-successor-session',
turnId: 'workspace-successor-turn',
ts: 1_700_000_000_002,
partial: false,
role: 'tool',
author: 'tool',
content: {
kind: 'function_response',
id: 'workspace-successor-call-id',
name: 'Write',
result: 'Wrote notes.txt',
},
refs: {
operationId: 'workspace-successor-operation',
toolCallId: 'workspace-successor-call-id',
},
},
},
};
}
function workspaceTerminalCommit() {
return {
noEffectOutcome: issueCrashNoEffect({
operationId: 'workspace-successor-operation',
dispatchEventId: 'workspace-successor-dispatch',
workspaceInstanceId: `instance_${'4'.repeat(32)}`,
terminalKind: 'no_workspace_change',
}),
toolOutcome: {
operationId: 'workspace-successor-operation',
journalEventId: 'workspace-successor-operation_outcome',
committedAt: 1_700_000_000_002,
runtimeEvent: {
id: 'workspace-terminal-outcome',
invocationId: 'workspace-successor-invocation',
runId: 'workspace-successor-run',
sessionId: 'workspace-successor-session',
turnId: 'workspace-successor-turn',
ts: 1_700_000_000_002,
partial: false,
role: 'tool' as const,
author: 'tool' as const,
content: {
kind: 'function_response' as const,
id: 'workspace-successor-call-id',
name: 'Write',
result: 'No workspace change',
},
actions: {
managedMutationTerminal: {
protocol: 'managed_mutation_terminal_v1' as const,
operationId: 'workspace-successor-operation',
dispatchEventId: 'workspace-successor-dispatch',
workspaceInstanceId: `instance_${'4'.repeat(32)}`,
terminalKind: 'no_workspace_change' as const,
},
},
refs: {
operationId: 'workspace-successor-operation',
toolCallId: 'workspace-successor-call-id',
},
},
},
};
}
function outcomeCommit() {
return {
operationId: 'operation-1',
journalEventId: 'operation-1_outcome',
runtimeEvent: functionResponseEvent(),
committedAt: 2,
};
}
function toolDispatchEvent(): RuntimeEvent {
return {
id: 'dispatch-event-1',
invocationId: 'invocation-1',
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
ts: 1,
partial: false,
role: 'system',
author: 'system',
actions: {
toolDispatch: {
protocol: 't1_after_preflight_v1',
operationId: 'operation-1',
providerToolCallId: 'provider-call-1',
toolName: 'Read',
canonicalArgsHash: CRASH_READ_ARGS_HASH,
recoveryMode: 'reconcile',
},
},
refs: { operationId: 'operation-1', toolCallId: 'provider-call-1' },
};
}
function functionCallEvent(): RuntimeEvent {
return {
id: 'call-event-1',
invocationId: 'invocation-1',
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
ts: 1,
partial: false,
role: 'model',
author: 'agent',
content: {
kind: 'function_call',
id: 'provider-call-1',
name: 'Read',
args: { path: '/workspace/README.md' },
},
};
}
function functionResponseEvent(): RuntimeEvent {
return {
id: 'response-event-1',
invocationId: 'invocation-1',
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
ts: 2,
partial: false,
role: 'tool',
author: 'tool',
content: {
kind: 'function_response',
id: 'provider-call-1',
name: 'Read',
result: 'contents',
},
refs: { operationId: 'operation-1', toolCallId: 'provider-call-1' },
};
}
function recoveryCommit() {
return {
operationId: 'operation-1',
reconcileRuntimeEvent: reconcileEvent(),
outcomeRuntimeEvent: functionResponseEvent(),
decisionRuntimeEvent: decisionEvent(),
};
}
function reconcileEvent(): RuntimeEvent {
return {
id: 'reconcile-event-1',
invocationId: 'invocation-1',
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
ts: 2,
partial: false,
role: 'system',
author: 'system',
actions: {
toolRecovery: {
kind: 'maka.tool.reconcile_result',
version: 1,
payload: {
protocol: 'tool_reconcile_v1',
operationId: 'operation-1',
observation: 'matches_expected_state',
observationSchema: 'state_identity_v1',
observationDigest:
'sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
},
},
},
refs: { operationId: 'operation-1', toolCallId: 'provider-call-1' },
};
}
function decisionEvent(): RuntimeEvent {
return {
id: 'decision-event-1',
invocationId: 'invocation-1',
runId: 'run-1',
sessionId: 'session-1',
turnId: 'turn-1',
ts: 3,
partial: false,
role: 'system',
author: 'system',
actions: {
toolRecovery: {
kind: 'maka.tool.recovery_decision',
version: 1,
payload: {
protocol: 'tool_recovery_v1',
operationId: 'operation-1',
disposition: 'completed',
reasonCode: 'reconcile_matches_expected_state',
outcomeEventId: 'response-event-1',
evidenceEventIds: [
'call-event-1',
'dispatch-event-1',
'reconcile-event-1',
'response-event-1',
],
},
},
},
refs: { operationId: 'operation-1', toolCallId: 'provider-call-1' },
};
}
Loaded 100 of 3358 files, more files were not shown because too many files have changed in this diff. Show more