maka-agent 0.2.0-dev.25.20260908 → 0.2.0-dev.26.20260909

package/node_modules/@maka/runtime-host/dist/server/workhub-coordination-coordinator.js

@@ -22,34 +22,35 @@ import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { normalizeMessageContent } from '@maka/core/events';
 import { WORKHUB_COORDINATION_SESSION_ID, WORKHUB_COORDINATION_SESSION_ROLE, WORKHUB_COORDINATION_REPLACEMENT_SCHEMA_VERSION, WORKHUB_COORDINATION_STOP_SCHEMA_VERSION, isWorkHubCoordinationSession, isWorkHubCoordinationSessionId, } from '@maka/core/session';
-import { WORKHUB_COORDINATION_SUMMARY_MAX_BYTES, WORKHUB_COORDINATION_TEXT_MAX_BYTES, } from '../protocol/index.js';
-import { SessionOperationFailure } from './session-catalog-coordinator.js';
+import { WORKHUB_COORDINATION_TEXT_MAX_BYTES } from '../protocol/index.js';
+import { SessionOperationFailure, projectSessionCatalogRecord, } from './session-catalog-coordinator.js';
 import { WorkHubActionEffectFailure, WorkHubActionGateFailure, WorkHubCoordinationActionGate, } from './workhub-coordination-action-gate.js';
 const CREATE_FINGERPRINT = `sha256:${createHash('sha256')
     .update('maka:workhub-coordination-session:v1', 'utf8')
     .digest('hex')}`;
 const COORDINATION_CWD_DIRECTORY = 'workhub-coordination';
-const COORDINATION_TOOL_PROFILE = 'workhub-coordination-v1';
-const SYNTHETIC_COORDINATION_MODEL_ID = 'maka-workhub-coordination';
-const COORDINATION_PERMISSION_MODE = 'explore';
+const COORDINATION_TOOL_PROFILE = 'workhub-coordination-v2';
+const COORDINATION_PERMISSION_MODE = 'bypass';
 const COORDINATION_COLLABORATION_MODE = 'agent';
 const COORDINATION_ORCHESTRATION_MODE = 'default';
 const COORDINATION_SUMMARY_MESSAGE_KINDS = ['user', 'assistant', 'state'];
 const TURN_IDENTITY_CONFLICT_MESSAGE = 'WorkHub Coordination Turn identity belongs to a different operation';
 // A one-byte control character can occupy six bytes as a JSON `\u0000` escape.
 const JSON_ESCAPE_MAX_BYTES_PER_INPUT_BYTE = 6;
-const COORDINATION_SUMMARY_READ_MAX_BYTES = JSON_ESCAPE_MAX_BYTES_PER_INPUT_BYTE *
-    (WORKHUB_COORDINATION_TEXT_MAX_BYTES + WORKHUB_COORDINATION_SUMMARY_MAX_BYTES) +
+const COORDINATION_SUMMARY_READ_MAX_BYTES = JSON_ESCAPE_MAX_BYTES_PER_INPUT_BYTE * (WORKHUB_COORDINATION_TEXT_MAX_BYTES + 8 * 1024) +
     16 * 1024;
 /** Resolves the one durable Coordination Session owned by this Runtime Host. */
 export class HostWorkHubCoordinationCoordinator {
     handlers = {
         'workhub.coordination.resolve': () => this.#resolve(),
+        'workhub.coordination.query': () => this.#query(),
+        'workhub.coordination.configureModel': (input) => this.#configureModel(input),
         'workhub.coordination.answer': (input, context) => this.#answer(input, context),
-        'workhub.coordination.record': (input) => this.#record(input),
         'workhub.coordination.candidates': () => this.#candidates(),
-        'workhub.coordination.act': (input, context) => this.#act(input, context),
+        'workhub.coordination.actFromTurn': (input, context) => this.#actFromTurn(input, context),
     };
+    #transitionConfiguration;
+    #configureModel;
     #coordinationCwd;
     #stores;
     #admission;
@@ -60,6 +61,8 @@ export class HostWorkHubCoordinationCoordinator {
     #actionGate;
     #readDelegationRetirement;
     constructor(options) {
+        this.#configureModel = options.configureModel;
+        this.#transitionConfiguration = options.transitionConfiguration;
         this.#coordinationCwd = join(options.stateRoot, COORDINATION_CWD_DIRECTORY);
         this.#stores = options.stores;
         this.#readDelegationRetirement = options.sessionActions.readDelegationRetirement;
@@ -87,22 +90,6 @@ export class HostWorkHubCoordinationCoordinator {
             readSupersession: (delegationId) => this.#stores.readWorkHubSupersession(delegationId),
             readStopRequest: (delegationId) => this.#stores.readWorkHubStopRequest(delegationId),
             readStopResolution: (delegationId) => this.#stores.readWorkHubStopResolution(delegationId),
-            answer: async (input, context) => {
-                const outcome = await this.#answer(input, context);
-                if (!outcome.ok) {
-                    throw new WorkHubActionEffectFailure(outcome.error.code, outcome.error.message);
-                }
-            },
-            clarify: async (input) => {
-                const outcome = await this.#record({
-                    turnId: input.turnId,
-                    userText: input.userText,
-                    assistantText: input.assistantText,
-                });
-                if (!outcome.ok) {
-                    throw new WorkHubActionEffectFailure(outcome.error.code, outcome.error.message);
-                }
-            },
             assign: options.sessionActions.assign,
             prepareReplacement: (input) => this.#prepareReplacement(input),
             abortReplacement: (input) => this.#abortReplacement(input),
@@ -113,7 +100,7 @@ export class HostWorkHubCoordinationCoordinator {
             resume: async (input, context) => ({
                 disposition: 'resume_work',
                 targetSessionId: input.source.targetSessionId,
-                ...(await options.sessionActions.resumeDelegation(input.source, context, input.actionId)),
+                ...(await options.sessionActions.resumeDelegation(input.source, context, input.actionId, input.validateFreshTarget)),
             }),
         });
     }
@@ -125,18 +112,19 @@ export class HostWorkHubCoordinationCoordinator {
             build: (existing) => ({
                 type: 'workhub_coordination',
                 id: `whp_${suffix}`,
-                turnId: input.actionId,
+                turnId: existing?.turnId ?? input.coordinationTurnId ?? input.actionId,
                 ts: existing?.ts ?? Date.now(),
                 schemaVersion: WORKHUB_COORDINATION_REPLACEMENT_SCHEMA_VERSION,
                 kind: 'delegation_replacement_requested',
                 actionId: input.actionId,
                 actionFingerprint: input.actionFingerprint,
-                coordinationTurnId: input.actionId,
+                coordinationTurnId: existing?.coordinationTurnId ?? input.coordinationTurnId ?? input.actionId,
                 targetSessionId: input.targetSessionId,
                 targetSessionName: input.targetSessionName,
                 disposition: input.disposition,
                 userText: input.userText,
                 ...(input.attachments ? { attachments: input.attachments } : {}),
+                ...(input.delegationText === undefined ? {} : { delegationText: input.delegationText }),
                 replacesActionId: input.replacesActionId,
                 replacesDelegationId: input.replacesDelegationId,
                 replacedTargetSessionId: input.replacedTargetSessionId,
@@ -178,13 +166,13 @@ export class HostWorkHubCoordinationCoordinator {
             build: (existing) => ({
                 type: 'workhub_coordination',
                 id: `whq_${suffix}`,
-                turnId: input.actionId,
+                turnId: existing?.turnId ?? input.coordinationTurnId ?? input.actionId,
                 ts: existing?.ts ?? Date.now(),
                 schemaVersion: WORKHUB_COORDINATION_STOP_SCHEMA_VERSION,
                 kind: 'delegation_stop_requested',
                 actionId: input.actionId,
                 actionFingerprint: input.actionFingerprint,
-                coordinationTurnId: input.actionId,
+                coordinationTurnId: existing?.coordinationTurnId ?? input.coordinationTurnId ?? input.actionId,
                 stopsActionId: input.stopsActionId,
                 stopsDelegationId: input.stopsDelegationId,
                 targetSessionId: input.targetSessionId,
@@ -232,7 +220,7 @@ export class HostWorkHubCoordinationCoordinator {
             build: (existing) => ({
                 type: 'workhub_coordination',
                 id: `whz_${suffix}`,
-                turnId: request.actionId,
+                turnId: request.coordinationTurnId,
                 ts: existing?.ts ?? Date.now(),
                 schemaVersion: WORKHUB_COORDINATION_STOP_SCHEMA_VERSION,
                 kind: 'delegation_stop_resolved',
@@ -263,13 +251,13 @@ export class HostWorkHubCoordinationCoordinator {
             build: (existing) => ({
                 type: 'workhub_coordination',
                 id: `whb_${suffix}`,
-                turnId: replacement.actionId,
+                turnId: replacement.coordinationTurnId,
                 ts: existing?.ts ?? Date.now(),
                 schemaVersion: WORKHUB_COORDINATION_REPLACEMENT_SCHEMA_VERSION,
                 kind: 'delegation_replacement_aborted',
                 actionId: replacement.actionId,
                 actionFingerprint: replacement.actionFingerprint,
-                coordinationTurnId: replacement.actionId,
+                coordinationTurnId: replacement.coordinationTurnId,
                 abortedActionId: replacement.replacesActionId,
                 abortedDelegationId: replacement.replacesDelegationId,
                 targetSessionId: replacement.targetSessionId,
@@ -339,9 +327,44 @@ export class HostWorkHubCoordinationCoordinator {
             };
         }
     }
-    async #act(input, context) {
+    async #actFromTurn(input, context) {
+        let content;
         try {
-            return { ok: true, result: await this.#actionGate.act(input, context) };
+            content = await this.#executions.readActiveWorkHubRequest(input.turnId);
+        }
+        catch {
+            return {
+                ok: false,
+                error: {
+                    code: 'persistence_failed',
+                    message: 'WorkHub active Turn authority is unavailable',
+                },
+            };
+        }
+        if (!content) {
+            return {
+                ok: false,
+                error: {
+                    code: 'operation_conflict',
+                    message: 'WorkHub action requires its currently active model Turn',
+                },
+            };
+        }
+        const { turnId: _turnId, ...action } = input;
+        const carriesAttachments = action.proposal.disposition === 'delegate_existing' ||
+            action.proposal.disposition === 'create_new' ||
+            action.proposal.disposition === 'replace';
+        try {
+            return {
+                ok: true,
+                result: await this.#actionGate.act({
+                    ...action,
+                    userText: content.text,
+                    ...(carriesAttachments && content.attachments
+                        ? { attachments: content.attachments }
+                        : {}),
+                }, context, input.turnId),
+            };
         }
         catch (error) {
             if (error instanceof WorkHubActionEffectFailure) {
@@ -357,7 +380,11 @@ export class HostWorkHubCoordinationCoordinator {
                 return {
                     ok: false,
                     error: {
-                        code: error.code === 'target_waiting_for_user' ? 'session_busy' : 'operation_conflict',
+                        code: error.code === 'target_waiting_for_user'
+                            ? 'session_busy'
+                            : error.code === 'candidate_set_stale'
+                                ? 'candidate_set_stale'
+                                : 'operation_conflict',
                         message: error.message,
                     },
                 };
@@ -371,6 +398,23 @@ export class HostWorkHubCoordinationCoordinator {
             };
         }
     }
+    async #query() {
+        try {
+            return {
+                ok: true,
+                result: projectSessionCatalogRecord(await this.#stores.readCatalogRecord(WORKHUB_COORDINATION_SESSION_ID, 'recoverable')),
+            };
+        }
+        catch {
+            return {
+                ok: false,
+                error: {
+                    code: 'persistence_failed',
+                    message: 'WorkHub Coordination Session state is unavailable',
+                },
+            };
+        }
+    }
     #resolve() {
         return this.#admission.run(WORKHUB_COORDINATION_SESSION_ID, async (lease) => {
             // The workspace exists for provisioning and for reuse alike: a directory
@@ -437,7 +481,7 @@ export class HostWorkHubCoordinationCoordinator {
     }
     async #answer(input, context) {
         if (!input.text.trim()) {
-            return turnFailure('workhub.coordination.answer', 'operation_conflict', 'WorkHub answer text is empty');
+            return turnFailure('operation_conflict', 'WorkHub answer text is empty');
         }
         const outcome = await this.#executions.startWorkHubCoordinationMessage({
             sessionId: WORKHUB_COORDINATION_SESSION_ID,
@@ -450,9 +494,8 @@ export class HostWorkHubCoordinationCoordinator {
                 }),
             },
             archivedMessage: 'WorkHub Coordination Session is unavailable',
-            // A recorded summary owns its Turn identity durably but is admitted
-            // outside this ledger, so the probe runs under the admission lease: a
-            // concurrent `record` cannot slip a second triplet into this Turn.
+            // Historical v1 summaries still own their Turn identities. Reject a
+            // fresh answer that would reuse one, even though new summaries are no longer written.
             prepareFreshContent: async () => {
                 let recorded;
                 try {
@@ -477,46 +520,7 @@ export class HostWorkHubCoordinationCoordinator {
         }, context);
         return outcome.ok ? { ok: true, result: { turnId: input.turnId } } : outcome;
     }
-    #record(input) {
-        if (!input.userText.trim() || !input.assistantText.trim()) {
-            return Promise.resolve(turnFailure('workhub.coordination.record', 'operation_conflict', 'WorkHub Coordination summary text is empty'));
-        }
-        return this.#admission.run(WORKHUB_COORDINATION_SESSION_ID, async (lease) => {
-            let header;
-            try {
-                header = await this.#stores.readHeaderSnapshot(WORKHUB_COORDINATION_SESSION_ID);
-            }
-            catch {
-                return turnFailure('workhub.coordination.record', 'persistence_failed', 'WorkHub Coordination Session state is unavailable');
-            }
-            if (!validCoordinationHeader(header)) {
-                return turnFailure('workhub.coordination.record', 'operation_conflict', 'WorkHub Coordination Session identity is unavailable');
-            }
-            const messages = coordinationSummaryMessages(input);
-            try {
-                const existing = await this.#readSummaryMessages(input.turnId);
-                if (existing.length > 0) {
-                    return coordinationSummaryMatches(existing, input)
-                        ? { ok: true, result: { turnId: input.turnId } }
-                        : turnFailure('workhub.coordination.record', 'operation_conflict', 'WorkHub Coordination Turn identity belongs to different content');
-                }
-                // An answer owns its Turn identity in the root admission ledger. Both
-                // operations take the same Session admission, so this probe settles the
-                // race in one direction and the answer's own probe settles the other.
-                if (await this.#executions.hasRootTurnAdmission(WORKHUB_COORDINATION_SESSION_ID, input.turnId)) {
-                    return turnFailure('workhub.coordination.record', 'operation_conflict', TURN_IDENTITY_CONFLICT_MESSAGE);
-                }
-                await this.#stores.appendMessages(WORKHUB_COORDINATION_SESSION_ID, messages);
-                await this.#continuity.refreshCanonical(WORKHUB_COORDINATION_SESSION_ID, lease);
-                return { ok: true, result: { turnId: input.turnId } };
-            }
-            catch {
-                this.#requestDrain();
-                return turnFailure('workhub.coordination.record', 'commit_outcome_unknown', 'WorkHub Coordination summary outcome is unknown');
-            }
-        });
-    }
-    /** Reads the durable summary triplet a `record` would own for this Turn. */
+    /** Reads a historical v1 summary to preserve its durable Turn identity. */
     async #readSummaryMessages(turnId) {
         const throughSequence = await this.#stores.readTranscriptHighWaterSnapshot(WORKHUB_COORDINATION_SESSION_ID);
         if (throughSequence === null)
@@ -536,32 +540,52 @@ export class HostWorkHubCoordinationCoordinator {
      */
     async #alignSession(record) {
         if (record.header.toolProfile !== undefined &&
+            record.header.toolProfile !== 'workhub-coordination-v1' &&
             record.header.toolProfile !== COORDINATION_TOOL_PROFILE) {
             return identityConflict();
         }
-        if (record.header.cwd === this.#coordinationCwd && validCoordinationHeader(record.header)) {
+        if (record.header.cwd === this.#coordinationCwd &&
+            record.header.toolProfile === COORDINATION_TOOL_PROFILE &&
+            validCoordinationHeader(record.header)) {
             return success();
         }
+        // Resolving an old Session is the explicit durable upgrade boundary. Active
+        // or recovering v1 Turns must finish under their original zero-tool ceiling.
+        if (!this.#executions.isSessionExecutionIdle(WORKHUB_COORDINATION_SESSION_ID)) {
+            return validCoordinationHeader(record.header)
+                ? success()
+                : failure('operation_unavailable', 'WorkHub Coordination Session is still executing or recovering');
+        }
         let repaired;
         try {
+            // Permission mode is a projection of the execution boundary. Transition
+            // through Runtime authority to update both and retire cached backends
+            // before changing the profile. An interrupted upgrade remains closed to
+            // execution until a later resolve completes this versioned repair.
+            const configured = await this.#transitionConfiguration({
+                expectedRevision: record.revision,
+                clearConnectionBlock: false,
+                configuration: {
+                    backend: record.header.backend,
+                    llmConnectionId: record.header.llmConnectionId,
+                    llmConnectionSlug: record.header.llmConnectionSlug,
+                    connectionLocked: record.header.connectionLocked,
+                    model: record.header.model,
+                    thinkingLevel: record.header.thinkingLevel,
+                    permissionMode: COORDINATION_PERMISSION_MODE,
+                    collaborationMode: COORDINATION_COLLABORATION_MODE,
+                    orchestrationMode: COORDINATION_ORCHESTRATION_MODE,
+                },
+            });
             repaired = await this.#stores.updateHeaderVersioned(WORKHUB_COORDINATION_SESSION_ID, {
                 ...(record.header.cwd === this.#coordinationCwd ? {} : { cwd: this.#coordinationCwd }),
                 ...(record.header.toolProfile === COORDINATION_TOOL_PROFILE
                     ? {}
                     : { toolProfile: COORDINATION_TOOL_PROFILE }),
-                ...(record.header.permissionMode === COORDINATION_PERMISSION_MODE
-                    ? {}
-                    : { permissionMode: COORDINATION_PERMISSION_MODE }),
-                ...((record.header.collaborationMode ?? 'agent') === COORDINATION_COLLABORATION_MODE
-                    ? {}
-                    : { collaborationMode: COORDINATION_COLLABORATION_MODE }),
-                ...((record.header.orchestrationMode ?? 'default') === COORDINATION_ORCHESTRATION_MODE
-                    ? {}
-                    : { orchestrationMode: COORDINATION_ORCHESTRATION_MODE }),
-            }, record.revision);
+            }, configured.revision);
         }
         catch {
-            return failure('persistence_failed', 'WorkHub Coordination Session workspace could not be relocated');
+            return failure('persistence_failed', 'WorkHub Coordination Session configuration could not be aligned');
         }
         return validCoordinationHeader(repaired.header) && repaired.header.cwd === this.#coordinationCwd
             ? success()
@@ -587,8 +611,9 @@ function validCoordinationIdentityHeader(header) {
 }
 function validCoordinationHeader(header) {
     return (validCoordinationIdentityHeader(header) &&
-        header.toolProfile === COORDINATION_TOOL_PROFILE &&
-        header.permissionMode === COORDINATION_PERMISSION_MODE &&
+        ((header.toolProfile === COORDINATION_TOOL_PROFILE &&
+            header.permissionMode === COORDINATION_PERMISSION_MODE) ||
+            (header.toolProfile === 'workhub-coordination-v1' && header.permissionMode === 'explore')) &&
         (header.collaborationMode ?? 'agent') === COORDINATION_COLLABORATION_MODE &&
         (header.orchestrationMode ?? 'default') === COORDINATION_ORCHESTRATION_MODE);
 }
@@ -604,48 +629,6 @@ function coordinationSummaryMessageId(turnId, kind) {
         .digest('hex')
         .slice(0, 48)}`;
 }
-function coordinationSummaryMessages(input) {
-    const ts = Date.now();
-    const messageId = (kind) => coordinationSummaryMessageId(input.turnId, kind);
-    return [
-        {
-            type: 'user',
-            id: messageId('user'),
-            turnId: input.turnId,
-            ts,
-            text: input.userText,
-        },
-        {
-            type: 'assistant',
-            id: messageId('assistant'),
-            turnId: input.turnId,
-            ts: ts + 1,
-            text: input.assistantText,
-            modelId: SYNTHETIC_COORDINATION_MODEL_ID,
-        },
-        {
-            type: 'turn_state',
-            id: messageId('state'),
-            turnId: input.turnId,
-            ts: ts + 2,
-            status: 'completed',
-        },
-    ];
-}
-function coordinationSummaryMatches(existing, input) {
-    if (existing.length !== 3)
-        return false;
-    const user = existing.find((message) => message.type === 'user');
-    const assistant = existing.find((message) => message.type === 'assistant');
-    const state = existing.find((message) => message.type === 'turn_state');
-    return (user?.turnId === input.turnId &&
-        user.text === input.userText &&
-        assistant?.turnId === input.turnId &&
-        assistant.text === input.assistantText &&
-        assistant.modelId === SYNTHETIC_COORDINATION_MODEL_ID &&
-        state?.turnId === input.turnId &&
-        state.status === 'completed');
-}
 function success() {
     return {
         ok: true,
@@ -668,6 +651,6 @@ function turnIdentityConflict() {
 function operationUnavailable(message) {
     return { ok: false, error: { code: 'operation_unavailable', message } };
 }
-function turnFailure(_operation, code, message) {
+function turnFailure(code, message) {
     return { ok: false, error: { code, message } };
 }

package/node_modules/@maka/storage/dist/agent-run-store.js

@@ -1347,12 +1347,25 @@ function normalizeRootExecutionDescriptor(value) {
         });
     }
     if (value.kind === 'workhub_coordination') {
-        if (!hasExactKeys(value, ['kind', 'inputDigest']) || !isSha256Digest(value.inputDigest)) {
+        if (!hasExactKeys(value, value.operation === undefined
+            ? ['kind', 'inputDigest']
+            : [
+                'kind',
+                'inputDigest',
+                'operation',
+                ...(value.actionId === undefined ? [] : ['actionId']),
+            ]) ||
+            (value.operation !== undefined && value.operation !== 'action') ||
+            (value.actionId !== undefined &&
+                (typeof value.actionId !== 'string' || !isSafeId(value.actionId))) ||
+            !isSha256Digest(value.inputDigest)) {
             throw new Error('Invalid root execution descriptor');
         }
         return Object.freeze({
             kind: 'workhub_coordination',
+            ...(value.operation === 'action' ? { operation: 'action' } : {}),
             inputDigest: value.inputDigest,
+            ...(typeof value.actionId === 'string' ? { actionId: value.actionId } : {}),
         });
     }
     if (value.kind === 'regenerate') {

package/node_modules/@maka/storage/dist/artifact-store.js

@@ -252,6 +252,7 @@ class SqliteArtifactStore {
             const directories = new Set();
             const discharged = [];
             let failedPaths = 0;
+            let realArtifactRoot;
             try {
                 for (const relativePath of selected) {
                     if (this.metadataRepository.hasRelativePath(relativePath) ||
@@ -259,10 +260,28 @@ class SqliteArtifactStore {
                         discharged.push(relativePath);
                         continue;
                     }
-                    const target = join(this.artifactRoot, relativePath);
+                    const entry = await resolveArtifactRemovalEntry(this.artifactRoot, relativePath);
+                    if (!entry) {
+                        discharged.push(relativePath);
+                        continue;
+                    }
+                    realArtifactRoot ??= await ensureRealDirectory(this.artifactRoot);
+                    if (!isInsideOrSamePath(realArtifactRoot, dirname(entry.unlinkPath))) {
+                        failedPaths += 1;
+                        continue;
+                    }
+                    const artifactIds = new Set([
+                        ...artifactIdsFromUpgradeOrphanPath(relativePath),
+                        ...artifactIdsFromUpgradeOrphanPath(entry.unlinkPath),
+                    ]);
+                    if (artifactIds.size > 0 &&
+                        (await this.hasClaimedRemovalIdentityUnlocked([...artifactIds], entry.comparisonIdentity))) {
+                        discharged.push(relativePath);
+                        continue;
+                    }
                     try {
-                        await unlink(target);
-                        directories.add(dirname(target));
+                        await unlink(entry.unlinkPath);
+                        directories.add(dirname(entry.unlinkPath));
                     }
                     catch (error) {
                         if (!isNotFound(error)) {
@@ -286,6 +305,14 @@ class SqliteArtifactStore {
             };
         });
     }
+    async hasClaimedRemovalIdentityUnlocked(artifactIds, comparisonIdentity) {
+        for (const relativePath of this.metadataRepository.readRelativePathsByCaseFoldedArtifactIds(artifactIds)) {
+            const entry = await resolveArtifactRemovalEntry(this.artifactRoot, relativePath);
+            if (entry?.comparisonIdentity === comparisonIdentity)
+                return true;
+        }
+        return false;
+    }
     async replayExistingArtifactUnlocked(existing, input, canonical) {
         const expectedBytes = Buffer.from(input.content);
         if (existing.id !== canonical.id ||
@@ -835,6 +862,16 @@ function symlinkEntryIdentity(entryStat) {
         entryStat.mtimeNs,
     ].join(':');
 }
+function artifactIdsFromUpgradeOrphanPath(relativePath) {
+    const name = basename(relativePath);
+    const artifactIds = [];
+    for (let separator = name.indexOf('-'); separator > 0; separator = name.indexOf('-', separator + 1)) {
+        const artifactId = name.slice(0, separator);
+        if (isCanonicalArtifactEntityId(artifactId))
+            artifactIds.push(artifactId);
+    }
+    return artifactIds;
+}
 function isInsideOrSamePath(root, target) {
     if (target === root)
         return true;

package/node_modules/@maka/storage/dist/atomic-file-write.js

@@ -0,0 +1,74 @@
+/*
+ * 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 { randomUUID } from 'node:crypto';
+import { open, rename, rm } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { syncDirectory } from './stable-storage.js';
+const defaultDependencies = {
+    open,
+    randomUUID,
+    syncDirectory,
+};
+export class AtomicFileWriteCommitUnknownError extends Error {
+    published = true;
+    constructor(options) {
+        super('Atomic file commit outcome is unknown; reload before retrying', options);
+        this.name = 'AtomicFileWriteCommitUnknownError';
+    }
+}
+export async function writeAtomicFile(path, contents, options, dependencies = {}) {
+    const deps = { ...defaultDependencies, ...dependencies };
+    const { fileMode } = options;
+    const tempPath = join(dirname(path), `.${basename(path)}.${deps.randomUUID()}.tmp`);
+    // Only the entry this call created — and hasn't renamed away — may be
+    // cleaned up. A pre-existing file or planted symlink the 'wx' open refused
+    // must not be deleted as "our" temp.
+    let tempCreated = false;
+    let published = false;
+    try {
+        const handle = await deps.open(tempPath, 'wx', fileMode);
+        tempCreated = true;
+        try {
+            await handle.writeFile(contents, 'utf8');
+            if (process.platform !== 'win32')
+                await handle.chmod(fileMode);
+            await handle.sync();
+            await handle.close();
+        }
+        catch (error) {
+            // Release the descriptor best-effort; never let a close failure mask
+            // the error that actually aborted the write.
+            await handle.close().catch(() => { });
+            throw error;
+        }
+        await rename(tempPath, path);
+        published = true;
+        tempCreated = false;
+        await deps.syncDirectory(dirname(path));
+    }
+    catch (error) {
+        if (tempCreated) {
+            // Cleanup must never mask the original failure.
+            await rm(tempPath, { force: true }).catch(() => { });
+        }
+        if (published)
+            throw new AtomicFileWriteCommitUnknownError({ cause: error });
+        throw error;
+    }
+}