openplanr 1.25.3 → 2.0.0

package/dist/services/operate/planning-handoff-service.js

@@ -0,0 +1,304 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { assertOperatingPlanningProposalV1 } from 'planr-pipeline/operate/planning-bridge-v2';
+import { loadConfig } from '../config-service.js';
+import { prepareOperatingSpecDraft, resolveSpecDir } from '../spec-service.js';
+import { readSpecOperatingOrigin, readSpecOperatingOriginAuthority, } from './spec-operating-origin-service.js';
+const FRAMING_FIELDS = Object.freeze([
+    'title',
+    'slug',
+    'problem',
+    'objective',
+    'users',
+    'scope',
+    'nonScope',
+    'risks',
+    'constraints',
+    'requirements',
+    'acceptanceOutcomes',
+]);
+const LIST_FIELDS = new Set([
+    'users',
+    'scope',
+    'nonScope',
+    'risks',
+    'constraints',
+    'requirements',
+    'acceptanceOutcomes',
+]);
+function fail(code, message) {
+    throw Object.assign(new Error(message), { code });
+}
+function hashText(value) {
+    return `sha256:${createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+/** Validate human-owned Planning framing before preview or create. */
+export function assertPlanningFraming(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        fail('E_OPERATE_PLANNING_INVALID', 'Planning framing must be a closed object.');
+    }
+    for (const field of FRAMING_FIELDS) {
+        if (!Object.hasOwn(value, field)) {
+            fail('E_OPERATE_PLANNING_INVALID', `Planning framing is missing ${field}.`);
+        }
+        if (LIST_FIELDS.has(field)) {
+            const entries = value[field];
+            if (!Array.isArray(entries) || entries.some((entry) => typeof entry !== 'string')) {
+                fail('E_OPERATE_PLANNING_INVALID', `Planning framing field ${field} must be a string list.`);
+            }
+            continue;
+        }
+        if (typeof value[field] !== 'string' || String(value[field]).length === 0) {
+            fail('E_OPERATE_PLANNING_INVALID', `Planning framing field ${field} must be a non-empty string.`);
+        }
+    }
+    const foreign = Object.keys(value).find((field) => !FRAMING_FIELDS.includes(field));
+    if (foreign) {
+        fail('E_OPERATE_PLANNING_INVALID', `Planning framing contains unsupported field ${foreign}.`);
+    }
+    return value;
+}
+function framingFromProposal(proposal) {
+    return assertPlanningFraming(proposal.framing);
+}
+function operatingOriginPreviewInput(proposal) {
+    const decision = proposal.decision;
+    const action = proposal.action;
+    const verification = proposal.verification;
+    return {
+        correlationId: String(proposal.correlationId),
+        proposalId: String(proposal.proposalId),
+        cycleId: String(proposal.cycleId),
+        decision: {
+            decisionId: String(decision.decisionId),
+            revision: Number(decision.revision),
+            title: String(decision.title),
+            outcome: String(decision.outcome),
+            rationale: String(decision.rationale),
+        },
+        action: {
+            actionId: String(action.actionId),
+            revision: Number(action.revision),
+            expectedResult: String(action.expectedResult),
+        },
+        perspectives: proposal.acceptedPerspectiveSummaries.map((perspective) => ({
+            roleId: String(perspective.roleId),
+            roleKind: perspective.roleKind,
+            stance: String(perspective.stance),
+            summary: String(perspective.summary),
+            constraints: perspective.constraints,
+            uncertainties: perspective.uncertainties,
+        })),
+        evidence: proposal.evidence.map((entry) => ({
+            evidenceRefId: String(entry.evidenceRefId),
+            relation: String(entry.relation),
+            freshness: String(entry.freshness),
+            confidence: Number(entry.confidence),
+            accessState: String(entry.accessState),
+            summary: entry.summary === null ? null : String(entry.summary),
+            limitations: entry.limitations,
+        })),
+        omissions: proposal.omissions.map((entry) => ({
+            count: Number(entry.count),
+            reason: String(entry.reason),
+        })),
+        verification: {
+            metricId: String(verification.metricId),
+            baseline: Number(verification.baseline),
+            target: Number(verification.target),
+            window: String(verification.window),
+            method: String(verification.method),
+        },
+    };
+}
+/** Render the exact SPEC bytes OpenPlanr will publish for one reviewed proposal. */
+export async function buildOperatingSpecPreviewFromProposal(input) {
+    assertOperatingPlanningProposalV1(input.proposal);
+    const config = input.config ?? (await loadConfig(input.projectDir));
+    const framing = framingFromProposal(input.proposal);
+    const actor = input.proposal.actor;
+    const draft = await prepareOperatingSpecDraft(input.projectDir, config, {
+        title: String(framing.title),
+        slug: String(framing.slug),
+        actorId: String(actor.actorId),
+        framing: {
+            problem: String(framing.problem),
+            objective: String(framing.objective),
+            users: framing.users,
+            scope: framing.scope,
+            nonScope: framing.nonScope,
+            risks: framing.risks,
+            constraints: framing.constraints,
+            requirements: framing.requirements,
+            acceptanceOutcomes: framing.acceptanceOutcomes,
+        },
+        operatingOrigin: operatingOriginPreviewInput(input.proposal),
+        createdAt: String(input.proposal.createdAt),
+    });
+    const preview = input.proposal.preview;
+    const eventHead = input.proposal.eventHead;
+    return Object.freeze({
+        specId: draft.id,
+        title: String(framing.title),
+        slug: draft.slug,
+        status: 'shaping',
+        content: draft.content,
+        contentHash: hashText(draft.content),
+        proposalId: String(input.proposal.proposalId),
+        proposalHash: String(input.proposal.proposalHash),
+        eventHead: Object.freeze({
+            sequence: Number(eventHead.sequence),
+            hash: String(eventHead.hash),
+        }),
+        previewDigest: String(preview.digest),
+        generatedAt: String(input.proposal.createdAt),
+    });
+}
+export function buildPlanningDeliveryProgress(origin) {
+    const decision = origin.decision;
+    const spec = origin.spec;
+    const specId = String(spec.specId);
+    const status = String(spec.status ?? 'shaping');
+    return Object.freeze({
+        nodes: Object.freeze([
+            Object.freeze({
+                kind: 'decision',
+                label: 'Decision accepted',
+                state: 'complete',
+                owner: 'Operate',
+                reason: 'Exact accepted source',
+                subjectId: String(decision.id),
+            }),
+            Object.freeze({
+                kind: 'proposal',
+                label: 'Proposal confirmed',
+                state: 'complete',
+                owner: 'Operate',
+                reason: 'Human digest confirmation',
+                subjectId: String(origin.proposalId),
+            }),
+            Object.freeze({
+                kind: 'spec',
+                label: `${specId} ${status}`,
+                state: status,
+                owner: 'Planning',
+                subjectId: specId,
+                href: `#/detail/${encodeURIComponent(specId)}`,
+            }),
+            Object.freeze({
+                kind: 'plan',
+                label: 'PLAN',
+                state: 'not-started',
+                owner: 'Planning',
+                reason: 'Separate human invocation required',
+            }),
+            Object.freeze({
+                kind: 'ship',
+                label: 'SHIP',
+                state: 'not-started',
+                owner: 'Pipeline',
+                reason: 'Requires reviewed PLAN and later invocation',
+            }),
+            Object.freeze({
+                kind: 'verify',
+                label: 'Verify value',
+                state: 'waiting',
+                owner: 'Operate',
+                reason: 'Delivery is not Outcome success',
+            }),
+            Object.freeze({
+                kind: 'learn',
+                label: 'Learning',
+                state: 'waiting',
+                owner: 'Operate',
+                reason: 'No accepted observation yet',
+            }),
+        ]),
+    });
+}
+function publicReceipt(receipt, title) {
+    return Object.freeze({
+        transactionId: receipt.transactionId,
+        receiptHash: receipt.receiptHash,
+        correlationId: receipt.correlationId,
+        proposalId: receipt.proposalId,
+        proposalHash: receipt.proposalHash,
+        specId: receipt.specId,
+        title,
+        slug: receipt.slug,
+        contentHash: receipt.contentHash,
+        originHash: receipt.originHash,
+        provenanceEventId: receipt.provenanceEventId,
+        replayed: receipt.replayed,
+        planningHref: `#/detail/${encodeURIComponent(receipt.specId)}`,
+    });
+}
+export function buildPlanningHandoffCreation(input) {
+    return Object.freeze({
+        receipt: publicReceipt(input.receipt, input.title),
+        origin: structuredClone(input.origin),
+        progress: buildPlanningDeliveryProgress(input.origin),
+        nextCommands: Object.freeze([
+            `planr spec show ${input.receipt.specId}`,
+            `$planr:plan ${input.receipt.specId}`,
+            `/planr:plan ${input.receipt.specId}`,
+        ]),
+    });
+}
+export async function readPlanningHandoffSourceAuthority(input) {
+    const config = input.config ?? (await loadConfig(input.projectDir));
+    const resolved = await resolveSpecDir(input.projectDir, config, input.specId);
+    if (!resolved) {
+        fail('E_OPERATE_PLANNING_ACCESS', 'The requested Planning origin is not available.');
+    }
+    const authority = await readSpecOperatingOriginAuthority(resolved.dir);
+    if (authority.specId !== input.specId) {
+        fail('E_OPERATE_PLANNING_ACCESS', 'The requested Planning origin is not available.');
+    }
+    return authority;
+}
+export async function readPlanningHandoffTrace(input) {
+    const config = input.config ?? (await loadConfig(input.projectDir));
+    const resolved = await resolveSpecDir(input.projectDir, config, input.specId);
+    if (!resolved) {
+        fail('E_OPERATE_ORIGIN_INVALID', 'The requested SPEC does not exist in Planning custody.');
+    }
+    const origin = await readSpecOperatingOrigin(resolved.dir);
+    if (input.authority &&
+        (String(origin.originHash) !== input.authority.originHash ||
+            String(origin.cycleId) !== input.authority.cycleId ||
+            String(origin.scopeId) !== input.authority.scopeId ||
+            String(origin.domainId) !== input.authority.domainId ||
+            String(origin.domainVersion) !== input.authority.domainVersion ||
+            String(origin.actor.actorId) !== input.authority.actorId ||
+            String(origin.spec.specId) !== input.authority.specId)) {
+        fail('E_OPERATE_PLANNING_ACCESS', 'The authorized Planning origin changed during the read.');
+    }
+    const receipt = publicReceipt({
+        transactionId: String(origin.transaction.transactionId),
+        receiptHash: String(origin.transaction.receiptHash),
+        correlationId: String(origin.correlationId),
+        proposalId: String(origin.proposalId),
+        proposalHash: String(origin.proposalHash),
+        specId: String(origin.spec.specId),
+        slug: String(origin.spec.slug),
+        specDir: resolved.dir,
+        specFile: path.join(resolved.dir, `${input.specId}-${resolved.slug}.md`),
+        contentHash: String(origin.spec.contentHash),
+        originPath: path.join(resolved.dir, 'operating-origin.json'),
+        originHash: String(origin.originHash),
+        provenanceEventId: String(origin.transaction.planningProvenanceEventId),
+        replayed: true,
+    }, String(origin.spec.specId));
+    return Object.freeze({
+        receipt,
+        origin: structuredClone(origin),
+        progress: buildPlanningDeliveryProgress(origin),
+        nextCommands: Object.freeze([
+            `planr spec show ${input.specId}`,
+            `$planr:plan ${input.specId}`,
+            `/planr:plan ${input.specId}`,
+        ]),
+    });
+}
+//# sourceMappingURL=planning-handoff-service.js.map

package/dist/services/operate/planning-handoff-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-handoff-service.js","sourceRoot":"","sources":["../../../src/services/operate/planning-handoff-service.ts"],"names":[],"mappings":"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"}

package/dist/services/operate/project-transaction-lock.d.ts

@@ -0,0 +1,6 @@
+/** Serializes every project-local Operate writer, migration, and rollback. */
+export declare function withOperateProjectTransaction<T>(projectDir: string, action: () => Promise<T>, options?: Readonly<{
+    timeoutMs?: number;
+    pollMs?: number;
+}>): Promise<T>;
+//# sourceMappingURL=project-transaction-lock.d.ts.map

package/dist/services/operate/project-transaction-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-transaction-lock.d.ts","sourceRoot":"","sources":["../../../src/services/operate/project-transaction-lock.ts"],"names":[],"mappings":"AAuFA,8EAA8E;AAC9E,wBAAsB,6BAA6B,CAAC,CAAC,EACnD,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE,QAAQ,CAAC;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAM,GAC9D,OAAO,CAAC,CAAC,CAAC,CAiEZ"}

package/dist/services/operate/project-transaction-lock.js

@@ -0,0 +1,146 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { assertOperatePathCustody } from './path-custody.js';
+const TRANSACTION_LOCK_FILE = '.operate-transaction-lock.json';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_POLL_MS = 25;
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function conflict(message) {
+    return Object.assign(new Error(message), { code: 'OPERATE_STORE_CONFLICT' });
+}
+async function wait(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function parseRecord(raw) {
+    let candidate;
+    try {
+        candidate = JSON.parse(raw);
+    }
+    catch {
+        throw conflict('The Operate transaction lock is unreadable.');
+    }
+    const value = candidate;
+    if (value === null ||
+        typeof value !== 'object' ||
+        value.kind !== 'operate-project-transaction' ||
+        value.schemaVersion !== '1.0.0' ||
+        !Number.isSafeInteger(value.pid) ||
+        Number(value.pid) < 1 ||
+        typeof value.nonce !== 'string' ||
+        !/^[a-f0-9]{32}$/u.test(value.nonce) ||
+        !Number.isSafeInteger(value.createdAt) ||
+        Number(value.createdAt) < 0 ||
+        JSON.stringify(Object.keys(value).sort()) !==
+            JSON.stringify(['createdAt', 'kind', 'nonce', 'pid', 'schemaVersion'])) {
+        throw conflict('The Operate transaction lock has an invalid identity.');
+    }
+    return value;
+}
+async function readLock(lockPath) {
+    const metadata = await lstat(lockPath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (metadata === null)
+        return null;
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > 1024) {
+        throw conflict('The Operate transaction lock is unsafe.');
+    }
+    const raw = await readFile(lockPath, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    return raw === null ? null : Object.freeze({ raw, record: parseRecord(raw) });
+}
+async function removeExactLock(lockPath, expectedRaw) {
+    const current = await readLock(lockPath);
+    if (current === null)
+        return true;
+    if (current.raw !== expectedRaw)
+        return false;
+    await rm(lockPath);
+    return true;
+}
+/** Serializes every project-local Operate writer, migration, and rollback. */
+export async function withOperateProjectTransaction(projectDir, action, options = {}) {
+    const canonicalProject = path.resolve(projectDir);
+    const planrRoot = path.join(canonicalProject, '.planr');
+    const lockPath = path.join(planrRoot, TRANSACTION_LOCK_FILE);
+    await assertOperatePathCustody(canonicalProject, lockPath, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate transaction custody cannot traverse symbolic links.',
+    });
+    await mkdir(planrRoot, { recursive: true, mode: 0o700 });
+    await assertOperatePathCustody(canonicalProject, planrRoot, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate transaction custody cannot traverse symbolic links.',
+        requireDirectory: true,
+    });
+    if (process.platform !== 'win32')
+        await chmod(planrRoot, 0o700);
+    const createdAt = Date.now();
+    const record = Object.freeze({
+        kind: 'operate-project-transaction',
+        schemaVersion: '1.0.0',
+        pid: process.pid,
+        nonce: randomUUID().replaceAll('-', ''),
+        createdAt,
+    });
+    const serialized = `${JSON.stringify(record)}\n`;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    for (;;) {
+        try {
+            await writeFile(lockPath, serialized, { flag: 'wx', mode: 0o600 });
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const current = await readLock(lockPath);
+            if (current === null)
+                continue;
+            if (!processIsAlive(current.record.pid)) {
+                if (await removeExactLock(lockPath, current.raw))
+                    continue;
+            }
+            if (Date.now() - createdAt >= timeoutMs) {
+                throw conflict('Timed out waiting for another Operate transaction to finish.');
+            }
+            await wait(pollMs);
+        }
+    }
+    let outcome;
+    try {
+        outcome = Object.freeze({ ok: true, value: await action() });
+    }
+    catch (error) {
+        outcome = Object.freeze({ ok: false, error });
+    }
+    try {
+        if (!(await removeExactLock(lockPath, serialized))) {
+            throw conflict('Operate transaction ownership changed before release.');
+        }
+    }
+    catch (releaseError) {
+        throw Object.assign(conflict('Operate transaction ownership could not be released safely.'), {
+            cause: releaseError,
+            actionError: outcome.ok ? undefined : outcome.error,
+        });
+    }
+    if (!outcome.ok)
+        throw outcome.error;
+    return outcome.value;
+}
+//# sourceMappingURL=project-transaction-lock.js.map

package/dist/services/operate/project-transaction-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-transaction-lock.js","sourceRoot":"","sources":["../../../src/services/operate/project-transaction-lock.ts"],"names":[],"mappings":"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"}

package/dist/services/operate/recovery-service.d.ts

@@ -0,0 +1,16 @@
+import type { OperateComposition } from './composition.js';
+import type { OperateStore } from './store.js';
+/** Inspect durable storage and advertise only the exact recovery action proved safe. */
+export declare function inspectOperateRecovery(input: {
+    store: OperateStore;
+    composition: OperateComposition;
+}): Promise<unknown>;
+/** Restore only a store-verified replayable generation and return to the last Cycle. */
+export declare function restoreOperateGeneration(input: {
+    store: OperateStore;
+    composition: OperateComposition;
+    generation: string;
+}): Promise<unknown>;
+/** Archive one verified stale lock; no runtime state is interpreted or rewritten here. */
+export declare function clearOperateStaleLock(store: OperateStore): Promise<unknown>;
+//# sourceMappingURL=recovery-service.d.ts.map

package/dist/services/operate/recovery-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-service.d.ts","sourceRoot":"","sources":["../../../src/services/operate/recovery-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAiB/C,wFAAwF;AACxF,wBAAsB,sBAAsB,CAAC,KAAK,EAAE;IAClD,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,kBAAkB,CAAC;CACjC,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBnB;AAED,wFAAwF;AACxF,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IACpD,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,kBAAkB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBnB;AAED,0FAA0F;AAC1F,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAcjF"}

package/dist/services/operate/recovery-service.js

@@ -0,0 +1,59 @@
+function success(operation, data, allowedActions = []) {
+    return { ok: true, operation, data, allowedActions };
+}
+/** Inspect durable storage and advertise only the exact recovery action proved safe. */
+export async function inspectOperateRecovery(input) {
+    const inspection = await input.store.inspect(async ({ baseState, events, artifacts }) => input.composition.replay(baseState, events, artifacts));
+    const allowedActions = inspection.allowedRecovery === 'clear-stale-lock'
+        ? [
+            {
+                tool: 'operate.recovery.clear-stale-lock',
+                arguments: {},
+                label: 'Archive the stale writer lock and retry safely',
+                effect: 'machine-local-write',
+            },
+        ]
+        : inspection.allowedRecovery === 'restore-generation' && inspection.recoverableGeneration
+            ? [
+                {
+                    tool: 'operate.recovery.restore',
+                    arguments: { generation: inspection.recoverableGeneration },
+                    label: 'Restore the last exactly replayable generation',
+                    effect: 'machine-local-write',
+                },
+            ]
+            : [];
+    return success('operate.recovery.inspect', inspection, allowedActions);
+}
+/** Restore only a store-verified replayable generation and return to the last Cycle. */
+export async function restoreOperateGeneration(input) {
+    const recovered = await input.store.restore(input.generation, async ({ baseState, events, artifacts }) => input.composition.replay(baseState, events, artifacts));
+    const cycleAction = recovered.preferences.lastCycleId
+        ? [
+            {
+                tool: 'operate.cycle.get',
+                arguments: { cycleId: recovered.preferences.lastCycleId },
+                label: 'Inspect the current cycle',
+                effect: 'read-only',
+            },
+        ]
+        : [];
+    return success('operate.recovery.restore', {
+        generation: recovered.generation,
+        lastCycleId: recovered.preferences.lastCycleId,
+        status: 'restored',
+    }, cycleAction);
+}
+/** Archive one verified stale lock; no runtime state is interpreted or rewritten here. */
+export async function clearOperateStaleLock(store) {
+    await store.clearStaleLock();
+    return success('operate.recovery.clear-stale-lock', { status: 'cleared', recovery: 'stale-lock-archived' }, [
+        {
+            tool: 'operate.recovery.inspect',
+            arguments: {},
+            label: 'Inspect safe recovery options',
+            effect: 'read-only',
+        },
+    ]);
+}
+//# sourceMappingURL=recovery-service.js.map

package/dist/services/operate/recovery-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-service.js","sourceRoot":"","sources":["../../../src/services/operate/recovery-service.ts"],"names":[],"mappings":"AAcA,SAAS,OAAO,CAAC,SAAiB,EAAE,IAAa,EAAE,iBAA0C,EAAE;IAC7F,OAAO,EAAE,EAAE,EAAE,IAAa,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;AAChE,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAG5C;IACC,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,CACtF,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,CACvD,CAAC;IACF,MAAM,cAAc,GAClB,UAAU,CAAC,eAAe,KAAK,kBAAkB;QAC/C,CAAC,CAAC;YACE;gBACE,IAAI,EAAE,mCAAmC;gBACzC,SAAS,EAAE,EAAE;gBACb,KAAK,EAAE,gDAAgD;gBACvD,MAAM,EAAE,qBAAqB;aAC9B;SACF;QACH,CAAC,CAAC,UAAU,CAAC,eAAe,KAAK,oBAAoB,IAAI,UAAU,CAAC,qBAAqB;YACvF,CAAC,CAAC;gBACE;oBACE,IAAI,EAAE,0BAA0B;oBAChC,SAAS,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,qBAAqB,EAAE;oBAC3D,KAAK,EAAE,gDAAgD;oBACvD,MAAM,EAAE,qBAAqB;iBAC9B;aACF;YACH,CAAC,CAAC,EAAE,CAAC;IACX,OAAO,OAAO,CAAC,0BAA0B,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC;AACzE,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,KAI9C;IACC,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,OAAO,CACzC,KAAK,CAAC,UAAU,EAChB,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,CACzC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,CACzD,CAAC;IACF,MAAM,WAAW,GAA4B,SAAS,CAAC,WAAW,CAAC,WAAW;QAC5E,CAAC,CAAC;YACE;gBACE,IAAI,EAAE,mBAAmB;gBACzB,SAAS,EAAE,EAAE,OAAO,EAAE,SAAS,CAAC,WAAW,CAAC,WAAW,EAAE;gBACzD,KAAK,EAAE,2BAA2B;gBAClC,MAAM,EAAE,WAAW;aACpB;SACF;QACH,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,OAAO,CACZ,0BAA0B,EAC1B;QACE,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,WAAW,EAAE,SAAS,CAAC,WAAW,CAAC,WAAW;QAC9C,MAAM,EAAE,UAAU;KACnB,EACD,WAAW,CACZ,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,KAAmB;IAC7D,MAAM,KAAK,CAAC,cAAc,EAAE,CAAC;IAC7B,OAAO,OAAO,CACZ,mCAAmC,EACnC,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,qBAAqB,EAAE,EACtD;QACE;YACE,IAAI,EAAE,0BAA0B;YAChC,SAAS,EAAE,EAAE;YACb,KAAK,EAAE,+BAA+B;YACtC,MAAM,EAAE,WAAW;SACpB;KACF,CACF,CAAC;AACJ,CAAC"}

package/dist/services/operate/replay-safe-retry-service.d.ts

@@ -0,0 +1,21 @@
+type ReplaySafeRetryOptions = Readonly<{
+    maximumAttempts?: number;
+    wait?: (milliseconds: number) => Promise<void>;
+}>;
+/**
+ * Only optimistic-generation conflicts with both custody generations are safe to
+ * replay. The predicate is deliberately total so an unrelated error is preserved
+ * byte-for-byte instead of being replaced by adapter validation.
+ */
+export declare function isReplaySafeGenerationConflict(error: unknown): boolean;
+export declare function replaySafeRetryDelay(requestKey: string, retryOrdinal: number): number;
+/** Initial attempt plus at most four byte-identical optimistic retries. */
+export declare function retryReplaySafeGenerationConflict<T>(requestKey: string, attempt: () => Promise<T>, options?: ReplaySafeRetryOptions): Promise<T>;
+/**
+ * Prevents same-process clients for one Store from manufacturing a live-lock.
+ * Cross-process custody remains protected by the durable Store lock; this lane
+ * only orders the full load/transition/commit attempt in the current adapter.
+ */
+export declare function withOperateMutationLane<T>(storeRoot: string, mutation: () => Promise<T>): Promise<T>;
+export {};
+//# sourceMappingURL=replay-safe-retry-service.d.ts.map

package/dist/services/operate/replay-safe-retry-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-safe-retry-service.d.ts","sourceRoot":"","sources":["../../../src/services/operate/replay-safe-retry-service.ts"],"names":[],"mappings":"AAKA,KAAK,sBAAsB,GAAG,QAAQ,CAAC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD,CAAC,CAAC;AAQH;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAStE;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAGrF;AAED,2EAA2E;AAC3E,wBAAsB,iCAAiC,CAAC,CAAC,EACvD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CASZ"}