@dharma-ai-labs/agent-fabric 0.2.186 → 0.2.187

package/dist/repositoryCandidateSync.d.ts

@@ -30,9 +30,65 @@ type CandidateOutbox = {
         expectedLatestSourceFingerprint?: string;
     };
     candidateId: string | null;
-    state: 'pending_upload' | RepositoryCandidateState;
+    state: 'pending_upload' | 'fenced' | RepositoryCandidateState;
     releaseId: string | null;
+    restoration?: RestorationCheckpoint;
+    fence?: RepositoryCandidateFence;
+    fenceRequestGenerationId?: string;
+    registryReceiptHash?: string;
 };
+type RestorationCheckpoint = {
+    planHash: string;
+    localSnapshotHash: string;
+    baselineSnapshotHash: string | null;
+    previousOperationId: string | null;
+    priorReleaseId: string;
+    attemptId?: string;
+    headCandidateId?: string;
+};
+type RestorationContext = {
+    headCandidateId: string;
+    priorReleaseId: string;
+};
+type RepositoryCandidateFence = {
+    fenceId: string;
+    operationId: string;
+    workspaceId: string;
+    repositoryBindingId: string;
+    repositoryAgentId: string;
+    sourceSnapshotHash: string;
+    sourceManifestHash: string;
+    policyGenerationId: string;
+    requestPolicyGenerationId?: string;
+    state: 'fenced';
+    createdAt: string;
+};
+export declare function repositoryCandidateOperationId(input: {
+    scope: RepositoryCandidateScope;
+    snapshotHash: string;
+    sourceManifestHash: string;
+    consolidation: CandidateOutbox['consolidation'];
+    recoveryAttempt?: boolean;
+    restorationAttempt?: string;
+    restorationContext?: RestorationContext;
+}): string;
+export declare function checkpointRepositoryRestorationRegistry(input: {
+    outboxRoot: string;
+    scope: RepositoryCandidateScope;
+    repositoryPackage: {
+        state: string;
+        candidateId: string | null;
+        operationId: string | null;
+        snapshotHash: string | null;
+        releaseId: string | null;
+        sourceManifestHash: string | null;
+        consolidationMode: string | null;
+        localBaselineSnapshotHash?: string | null;
+        publishedLocalSnapshotHash?: string | null;
+        pendingLocalSnapshotHash?: string | null;
+        pendingLocalOperationId?: string | null;
+    };
+}): Promise<void>;
 export declare function synchronizeRepositoryCandidate(input: {
     transport: RepositoryCandidateTransport;
     outboxRoot: string;
@@ -41,7 +97,51 @@ export declare function synchronizeRepositoryCandidate(input: {
     initialRepository: boolean;
     expectedLatestSourceFingerprint?: string;
     blockedCandidate?: RepositoryCandidateReceipt;
+    restoration?: RestorationCheckpoint;
 }): Promise<RepositoryCandidateReceipt>;
+export declare function recoverRepositoryRestorationCandidate(input: {
+    transport: Pick<RepositoryCandidateTransport, 'signedGet'>;
+    outboxRoot: string;
+    scope: RepositoryCandidateScope;
+    planHash: string;
+}): Promise<{
+    planHash: string;
+    localSnapshotHash: string;
+    baselineSnapshotHash: string | null;
+    previousOperationId: string | null;
+    priorReleaseId: string;
+    attemptId?: string;
+    headCandidateId?: string;
+    candidate: RepositoryCandidateReceipt;
+    sourceManifestHash: string;
+} | null>;
+export declare function checkpointRepositoryRestorationCandidate(input: {
+    outboxRoot: string;
+    scope: RepositoryCandidateScope;
+    recovered: NonNullable<Awaited<ReturnType<typeof recoverRepositoryRestorationCandidate>>>;
+}): Promise<RepositoryCandidateReceipt>;
+export declare function readRepositoryRestorationAttempt(input: {
+    outboxRoot: string;
+    scope: RepositoryCandidateScope;
+}): Promise<string | undefined>;
+export declare function fenceRepositoryRestorationUpload(input: {
+    transport: RepositoryCandidateTransport;
+    outboxRoot: string;
+    scope: RepositoryCandidateScope;
+    planHash: string;
+    policyGenerationId: string;
+    expectedPreviousOperationId: string | null;
+}): Promise<{
+    checkpointHash: string;
+    pending: CandidateOutbox;
+    fence: RepositoryCandidateFence | null;
+    candidate: RepositoryCandidateReceipt | null;
+}>;
+export declare function checkpointRepositoryRestorationFence(input: {
+    outboxRoot: string;
+    scope: RepositoryCandidateScope;
+    fenced: Awaited<ReturnType<typeof fenceRepositoryRestorationUpload>>;
+}): Promise<RepositoryCandidateFence>;
 export declare function pollRepositoryCandidate(input: {
     transport: Pick<RepositoryCandidateTransport, 'signedGet'>;
     outboxRoot: string;
@@ -53,6 +153,13 @@ export declare function adoptRepositoryCandidate(input: {
     sourceManifestHash: string;
     consolidationMode: CandidateOutbox['consolidation']['mode'];
     candidate: RepositoryCandidateReceipt;
-}): Promise<RepositoryCandidateReceipt>;
+}): Promise<RepositoryCandidateReceipt & {
+    restorationRegistryBaseline?: {
+        localBaselineSnapshotHash: string | null;
+        publishedLocalSnapshotHash: string | null;
+        pendingLocalSnapshotHash: null;
+        pendingLocalOperationId: null;
+    };
+}>;
 export {};
 //# sourceMappingURL=repositoryCandidateSync.d.ts.map

package/dist/repositoryCandidateSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repositoryCandidateSync.d.ts","sourceRoot":"","sources":["../src/repositoryCandidateSync.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,CAAC;AAE3F,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5E;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,wBAAwB,CAAC;IAChC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,uCAAuC,CAAC;IAChD,KAAK,EAAE,wBAAwB,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE;QACb,IAAI,EAAE,oBAAoB,GAAG,mBAAmB,CAAC;QACjD,sBAAsB,EAAE,IAAI,CAAC;QAC7B,uBAAuB,EAAE,IAAI,CAAC;QAC9B,+BAA+B,CAAC,EAAE,MAAM,CAAC;KAC1C,CAAC;IACF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,gBAAgB,GAAG,wBAAwB,CAAC;IACnD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAsGF,wBAAsB,8BAA8B,CAAC,KAAK,EAAE;IAC1D,SAAS,EAAE,4BAA4B,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,wBAAwB,CAAC;IAChC,QAAQ,EAAE,yBAAyB,CAAC;IACpC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;CAC/C,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAuEtC;AAED,wBAAsB,uBAAuB,CAAC,KAAK,EAAE;IACnD,SAAS,EAAE,IAAI,CAAC,4BAA4B,EAAE,WAAW,CAAC,CAAC;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,wBAAwB,CAAC;CACjC,GAAG,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC,CAgB7C;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,wBAAwB,CAAC;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,eAAe,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5D,SAAS,EAAE,0BAA0B,CAAC;CACvC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CActC"}
+{"version":3,"file":"repositoryCandidateSync.d.ts","sourceRoot":"","sources":["../src/repositoryCandidateSync.ts"],"names":[],"mappings":"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"}

package/dist/repositoryCandidateSync.js

@@ -1,17 +1,49 @@
 import { constants } from 'node:fs';
-import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { link, lstat, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
-import { canonicalize, sha256 } from '@dharma-ai-labs/agent-fabric-contracts';
+import { fileURLToPath } from 'node:url';
+import { canonicalize, sha256, validateContract } from '@dharma-ai-labs/agent-fabric-contracts';
 import { serializeRepositoryPackageSnapshot, } from './repositoryPackage.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$(?![\s\S])/i;
 const HASH = /^sha256:[0-9a-f]{64}$(?![\s\S])/;
 const ORG = /^org_[A-Za-z0-9_]{1,156}$(?![\s\S])/;
 const STATES = new Set(['accepted', 'processing', 'published', 'blocked']);
-const OUTBOX_STATES = new Set(['pending_upload', ...STATES]);
+const OUTBOX_STATES = new Set(['pending_upload', 'fenced', ...STATES]);
+export function repositoryCandidateOperationId(input) {
+    requireFact(input.restorationAttempt === undefined || UUID.test(input.restorationAttempt), 'Repository restoration attempt is invalid.');
+    requireFact(input.restorationContext === undefined || UUID.test(input.restorationContext.headCandidateId)
+        && UUID.test(input.restorationContext.priorReleaseId), 'Repository restoration context is invalid.');
+    return sha256(canonicalize({ schema: 'dharma.repository-candidate-operation/v1',
+        organizationId: input.scope.organizationId, workspaceId: input.scope.workspaceId,
+        repositoryBindingId: input.scope.repositoryBindingId, repositoryAgentId: input.scope.repositoryAgentId,
+        snapshotHash: input.snapshotHash, sourceManifestHash: input.sourceManifestHash, consolidation: input.consolidation,
+        ...(input.recoveryAttempt ? { recoveryAttempt: 1 } : {}),
+        ...(input.restorationAttempt ? { restorationAttempt: input.restorationAttempt } : {}),
+        ...(input.restorationContext ? { restorationContext: input.restorationContext } : {}) }));
+}
 function requireFact(value, message) {
     if (!value)
         throw new Error(message);
 }
+function restorationCheckpoint(value) {
+    requireFact(value !== null && typeof value === 'object' && !Array.isArray(value), 'Repository restoration checkpoint is invalid.');
+    const row = value;
+    requireFact(Object.keys(row).sort().join(',') === ['baselineSnapshotHash', 'localSnapshotHash', 'planHash',
+        'previousOperationId', 'priorReleaseId', ...(Object.hasOwn(row, 'attemptId') ? ['attemptId'] : []),
+        ...(Object.hasOwn(row, 'headCandidateId') ? ['headCandidateId'] : [])].sort().join(',')
+        && typeof row.planHash === 'string' && HASH.test(row.planHash)
+        && typeof row.localSnapshotHash === 'string' && HASH.test(row.localSnapshotHash)
+        && (row.baselineSnapshotHash === null || typeof row.baselineSnapshotHash === 'string' && HASH.test(row.baselineSnapshotHash))
+        && (row.previousOperationId === null || typeof row.previousOperationId === 'string' && HASH.test(row.previousOperationId))
+        && typeof row.priorReleaseId === 'string' && UUID.test(row.priorReleaseId)
+        && (row.attemptId === undefined || typeof row.attemptId === 'string' && UUID.test(row.attemptId))
+        && (!Object.hasOwn(row, 'headCandidateId') || typeof row.headCandidateId === 'string' && UUID.test(row.headCandidateId)), 'Repository restoration checkpoint is invalid.');
+    return row;
+}
+function restorationContext(checkpoint) {
+    return checkpoint?.headCandidateId ? { headCandidateId: checkpoint.headCandidateId, priorReleaseId: checkpoint.priorReleaseId } : undefined;
+}
 function checkedScope(value) {
     requireFact(ORG.test(value.organizationId), 'Repository candidate organization is invalid.');
     for (const id of [value.workspaceId, value.repositoryBindingId, value.repositoryAgentId]) {
@@ -19,7 +51,7 @@ function checkedScope(value) {
     }
     return { ...value };
 }
-function receipt(value, scope, operationId, snapshotHash) {
+function receipt(value, scope, operationId, snapshotHash, archivedReleaseId) {
     requireFact(value !== null && typeof value === 'object' && !Array.isArray(value), 'Repository candidate response is invalid.');
     const response = value;
     requireFact(response.ok === true && response.organizationId === scope.organizationId
@@ -33,6 +65,7 @@ function receipt(value, scope, operationId, snapshotHash) {
         && typeof candidate.state === 'string' && STATES.has(candidate.state)
         && (candidate.releaseId === null || typeof candidate.releaseId === 'string' && UUID.test(candidate.releaseId))
         && (candidate.state === 'published') === (candidate.releaseId !== null), 'Repository candidate receipt is inconsistent.');
+    requireFact(candidate.state !== 'published' || candidate.releaseId !== archivedReleaseId, 'Repository restoration cannot reuse the archived release identity.');
     return candidate;
 }
 function outboxPath(root, scope) {
@@ -64,7 +97,8 @@ function outbox(value, expectedScope) {
         'candidateId', 'state', 'releaseId'];
     requireFact(row.schema === 'dharma.repository-candidate-outbox/v1'
         && Reflect.ownKeys(row).every(key => typeof key === 'string')
-        && keys.every(key => Object.hasOwn(row, key)) && Object.keys(row).every(key => keys.includes(key)), 'Repository candidate outbox is invalid.');
+        && keys.every(key => Object.hasOwn(row, key)) && Object.keys(row).every(key => keys.includes(key)
+        || ['restoration', 'fence', 'fenceRequestGenerationId', 'registryReceiptHash'].includes(key)), 'Repository candidate outbox is invalid.');
     const scope = checkedScope(row.scope);
     if (expectedScope)
         requireFact(canonicalize(scope) === canonicalize(expectedScope), 'Repository candidate outbox scope is invalid.');
@@ -74,7 +108,7 @@ function outbox(value, expectedScope) {
         && typeof row.state === 'string' && OUTBOX_STATES.has(row.state)
         && (row.candidateId === null || typeof row.candidateId === 'string' && UUID.test(row.candidateId))
         && (row.releaseId === null || typeof row.releaseId === 'string' && UUID.test(row.releaseId))
-        && (row.state === 'pending_upload') === (row.candidateId === null)
+        && ['pending_upload', 'fenced'].includes(String(row.state)) === (row.candidateId === null)
         && (row.state === 'published') === (row.releaseId !== null), 'Repository candidate outbox is inconsistent.');
     requireFact(row.consolidation !== null && typeof row.consolidation === 'object' && !Array.isArray(row.consolidation), 'Repository candidate consolidation is invalid.');
     const consolidation = row.consolidation;
@@ -86,11 +120,65 @@ function outbox(value, expectedScope) {
         && (consolidation.expectedLatestSourceFingerprint === undefined
             || consolidation.mode === 'repository_update' && typeof consolidation.expectedLatestSourceFingerprint === 'string'
                 && HASH.test(consolidation.expectedLatestSourceFingerprint)), 'Repository candidate consolidation is invalid.');
+    const restoration = Object.hasOwn(row, 'restoration') ? restorationCheckpoint(row.restoration) : undefined;
+    requireFact(!Object.hasOwn(row, 'registryReceiptHash') || Boolean(restoration) && typeof row.registryReceiptHash === 'string'
+        && HASH.test(row.registryReceiptHash), 'Repository restoration registry checkpoint is invalid.');
+    requireFact((row.state === 'fenced') === Object.hasOwn(row, 'fence') && (row.state !== 'fenced' || Boolean(restoration)), 'Repository candidate fence checkpoint is inconsistent.');
+    requireFact(!Object.hasOwn(row, 'fenceRequestGenerationId') || Boolean(restoration)
+        && typeof row.fenceRequestGenerationId === 'string' && UUID.test(row.fenceRequestGenerationId), 'Repository candidate fence request provenance is invalid.');
+    const fence = row.state === 'fenced' ? checkedFence(row.fence, scope, String(row.operationId), String(row.snapshotHash), String(row.sourceManifestHash), row.fenceRequestGenerationId) : undefined;
     return { schema: 'dharma.repository-candidate-outbox/v1', scope,
         operationId: row.operationId, sourceManifestHash: row.sourceManifestHash,
         snapshotHash: row.snapshotHash, consolidation: consolidation,
         candidateId: row.candidateId, state: row.state,
-        releaseId: row.releaseId };
+        releaseId: row.releaseId,
+        ...(restoration ? { restoration } : {}), ...(fence ? { fence } : {}),
+        ...(typeof row.fenceRequestGenerationId === 'string' ? { fenceRequestGenerationId: row.fenceRequestGenerationId } : {}),
+        ...(typeof row.registryReceiptHash === 'string' ? { registryReceiptHash: row.registryReceiptHash } : {}) };
+}
+function registryReceiptHash(pending) {
+    return sha256(canonicalize({ scope: pending.scope, operationId: pending.operationId, candidateId: pending.candidateId,
+        snapshotHash: pending.snapshotHash, sourceManifestHash: pending.sourceManifestHash, state: pending.state,
+        releaseId: pending.releaseId, restoration: pending.restoration }));
+}
+function assertRestorationReconciled(pending) {
+    requireFact(!pending.restoration || pending.registryReceiptHash === registryReceiptHash(pending), 'Repository restoration requires registry reconciliation before replacement.');
+}
+// Called under the registry mutation lock, only after its durable save. A crash
+// before this marker leaves provenance retained and exact recovery retryable.
+export async function checkpointRepositoryRestorationRegistry(input) {
+    const scope = checkedScope(input.scope), path = outboxPath(input.outboxRoot, scope), pending = await readOutbox(path, scope);
+    if (!pending?.restoration || pending.state === 'fenced')
+        return;
+    const saved = input.repositoryPackage;
+    const restoration = pending.restoration, inFlight = ['accepted', 'processing'].includes(pending.state);
+    requireFact(STATES.has(pending.state)
+        && ['state', 'candidateId', 'operationId', 'snapshotHash', 'releaseId', 'sourceManifestHash'].every(key => saved[key] === pending[key])
+        && saved.consolidationMode === 'repository_update'
+        && saved.localBaselineSnapshotHash === (pending.state === 'blocked' ? restoration.baselineSnapshotHash : restoration.localSnapshotHash)
+        && saved.publishedLocalSnapshotHash === (pending.state === 'published' ? restoration.localSnapshotHash : restoration.baselineSnapshotHash)
+        && saved.pendingLocalSnapshotHash === (inFlight ? restoration.localSnapshotHash : null)
+        && saved.pendingLocalOperationId === (inFlight ? pending.operationId : null), 'Repository restoration registry receipt does not match its durable checkpoint.');
+    await writeOutbox(path, { ...pending, registryReceiptHash: registryReceiptHash(pending) });
+}
+function checkedFence(value, scope, operationId, snapshotHash, sourceManifestHash, requestPolicyGenerationId) {
+    requireFact(value !== null && typeof value === 'object' && !Array.isArray(value), 'Repository candidate fence receipt is invalid.');
+    const row = value;
+    const keys = ['createdAt', 'fenceId', 'operationId', 'policyGenerationId', 'repositoryAgentId', 'repositoryBindingId',
+        'sourceManifestHash', 'sourceSnapshotHash', 'state', 'workspaceId',
+        ...(Object.hasOwn(row, 'requestPolicyGenerationId') ? ['requestPolicyGenerationId'] : [])];
+    requireFact(Object.keys(row).sort().join(',') === keys.sort().join(',')
+        && typeof row.fenceId === 'string' && UUID.test(row.fenceId) && row.operationId === operationId
+        && row.workspaceId === scope.workspaceId && row.repositoryBindingId === scope.repositoryBindingId && row.repositoryAgentId === scope.repositoryAgentId
+        && row.sourceSnapshotHash === snapshotHash && row.sourceManifestHash === sourceManifestHash && row.state === 'fenced'
+        && typeof row.policyGenerationId === 'string' && UUID.test(row.policyGenerationId)
+        && (!Object.hasOwn(row, 'requestPolicyGenerationId') || typeof row.requestPolicyGenerationId === 'string'
+            && UUID.test(row.requestPolicyGenerationId))
+        && (requestPolicyGenerationId === undefined || (Object.hasOwn(row, 'requestPolicyGenerationId')
+            ? row.requestPolicyGenerationId === requestPolicyGenerationId : row.policyGenerationId === requestPolicyGenerationId))
+        && typeof row.createdAt === 'string' && Number.isFinite(Date.parse(row.createdAt))
+        && new Date(row.createdAt).toISOString() === row.createdAt, 'Repository candidate fence receipt is inconsistent.');
+    return row;
 }
 async function readOutbox(path, expectedScope) {
     try {
@@ -107,7 +195,7 @@ async function readOutbox(path, expectedScope) {
 export async function synchronizeRepositoryCandidate(input) {
     const scope = checkedScope(input.scope);
     const serialized = serializeRepositoryPackageSnapshot(input.snapshot);
-    requireFact(Buffer.byteLength(serialized) <= 8_388_608, 'Repository candidate exceeds its upload byte limit.');
+    requireFact(Buffer.byteLength(serialized) <= 4_194_304, 'Repository candidate exceeds its upload byte limit.');
     requireFact(input.snapshot.schema === 'dharma.repository-package-snapshot/v1'
         && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(input.snapshot.capturedAt)
         && Number.isFinite(Date.parse(input.snapshot.capturedAt))
@@ -137,53 +225,241 @@ export async function synchronizeRepositoryCandidate(input) {
             expectedLatestSourceFingerprint: input.expectedLatestSourceFingerprint,
         } : {}),
     };
-    const operationId = sha256(canonicalize({ schema: 'dharma.repository-candidate-operation/v1', ...scope,
-        snapshotHash: snapshot.manifest.snapshotHash, sourceManifestHash, consolidation,
-        ...(input.blockedCandidate ? { recoveryAttempt: 1 } : {}) }));
+    const restoration = input.restoration === undefined ? undefined : restorationCheckpoint(input.restoration);
+    requireFact(!restoration || !input.initialRepository && Boolean(input.expectedLatestSourceFingerprint)
+        && !input.blockedCandidate, 'Repository restoration checkpoint requires an update.');
+    const operationId = repositoryCandidateOperationId({ scope, snapshotHash: snapshot.manifest.snapshotHash,
+        sourceManifestHash, consolidation, recoveryAttempt: Boolean(input.blockedCandidate), restorationAttempt: restoration?.attemptId,
+        restorationContext: restorationContext(restoration) });
     const path = outboxPath(input.outboxRoot, scope);
     const prior = await readOutbox(path, scope);
+    requireFact(prior?.state !== 'pending_upload' || !prior.fenceRequestGenerationId, 'Repository restoration fence outcome must be reconciled before any upload retry.');
+    if (prior?.state === 'fenced') {
+        requireFact(prior.fence && restoration?.attemptId === prior.fence.fenceId && prior.operationId !== operationId, 'A fenced operation requires its verified new restoration attempt.');
+        await archiveFencedCheckpoint(input.outboxRoot, prior);
+    }
     if (prior && (prior.operationId !== operationId || canonicalize(prior.scope) !== canonicalize(scope))) {
-        requireFact(['published', 'blocked'].includes(prior.state)
+        requireFact(['published', 'blocked', 'fenced'].includes(prior.state)
             || input.blockedCandidate?.candidateId === prior.candidateId, 'A different repository candidate is still pending.');
+        if (prior.state !== 'fenced')
+            assertRestorationReconciled(prior);
     }
     const pending = prior?.operationId === operationId ? prior : {
         schema: 'dharma.repository-candidate-outbox/v1', scope, operationId,
         sourceManifestHash, snapshotHash: snapshot.manifest.snapshotHash, consolidation,
         candidateId: null, state: 'pending_upload', releaseId: null,
+        ...(restoration ? { restoration } : {}),
     };
     requireFact(pending.sourceManifestHash === sourceManifestHash && pending.snapshotHash === snapshot.manifest.snapshotHash
-        && canonicalize(pending.consolidation) === canonicalize(consolidation), 'Repository candidate outbox does not match the current upload.');
+        && canonicalize(pending.consolidation) === canonicalize(consolidation)
+        && canonicalize(pending.restoration ?? null) === canonicalize(restoration ?? null), 'Repository candidate outbox does not match the current upload.');
+    const body = {
+        schema: 'dharma.repository-candidate-upload/v1', operationId, workspaceId: scope.workspaceId,
+        repositoryBindingId: scope.repositoryBindingId, repositoryAgentId: scope.repositoryAgentId,
+        sourceSnapshotHash: snapshot.manifest.snapshotHash, sourceManifestHash: pending.sourceManifestHash,
+        consolidation: pending.consolidation, snapshot,
+        ...(restoration?.attemptId ? { restorationAttempt: restoration.attemptId } : {}),
+        ...(restorationContext(restoration) ? { restorationContext: restorationContext(restoration) } : {}),
+    };
+    // The relay caps the complete encoded request, not only raw repository bytes.
+    requireFact(Buffer.byteLength(canonicalize(body)) <= 4_194_304, 'Repository candidate exceeds its upload byte limit.');
+    requireFact((await validateContract(fileURLToPath(new URL('./schemas/', import.meta.url)), 'https://schemas.dharma-ai.io/repository-candidate-upload/v1', body)).ok, 'Repository candidate upload contract is invalid.');
     await writeOutbox(path, pending);
     const route = `/agent-fabric/repository-agents/${encodeURIComponent(scope.repositoryAgentId)}/package-candidates`;
     let accepted;
     if (pending.candidateId) {
         const query = new URLSearchParams({ workspaceId: scope.workspaceId, operationId });
-        accepted = receipt(await input.transport.signedGet(`${route}/${encodeURIComponent(pending.candidateId)}?${query}`), scope, operationId, snapshot.manifest.snapshotHash);
+        accepted = receipt(await input.transport.signedGet(`${route}/${encodeURIComponent(pending.candidateId)}?${query}`), scope, operationId, snapshot.manifest.snapshotHash, restoration?.priorReleaseId);
     }
     else {
-        accepted = receipt(await input.transport.signedPost(route, {
-            schema: 'dharma.repository-candidate-upload/v1', operationId, workspaceId: scope.workspaceId,
-            repositoryBindingId: scope.repositoryBindingId, repositoryAgentId: scope.repositoryAgentId,
-            sourceSnapshotHash: snapshot.manifest.snapshotHash, sourceManifestHash: pending.sourceManifestHash,
-            consolidation: pending.consolidation, snapshot,
-        }), scope, operationId, snapshot.manifest.snapshotHash);
+        accepted = receipt(await input.transport.signedPost(route, body), scope, operationId, snapshot.manifest.snapshotHash, restoration?.priorReleaseId);
     }
     await writeOutbox(path, { ...pending, candidateId: accepted.candidateId, state: accepted.state, releaseId: accepted.releaseId });
     return accepted;
 }
+// Only reconcile an already admitted operation. This never uploads or obtains
+// new restoration authority, even if the original registry write was lost.
+export async function recoverRepositoryRestorationCandidate(input) {
+    const scope = checkedScope(input.scope);
+    requireFact(HASH.test(input.planHash), 'Repository restoration plan hash is invalid.');
+    const path = outboxPath(input.outboxRoot, scope), pending = await readOutbox(path, scope);
+    if (!pending?.restoration || pending.state === 'fenced' || pending.restoration.planHash !== input.planHash)
+        return null;
+    requireFact(pending.consolidation.mode === 'repository_update' && Boolean(pending.consolidation.expectedLatestSourceFingerprint)
+        && repositoryCandidateOperationId({ scope, snapshotHash: pending.snapshotHash,
+            sourceManifestHash: pending.sourceManifestHash, consolidation: pending.consolidation,
+            restorationAttempt: pending.restoration.attemptId, restorationContext: restorationContext(pending.restoration) }) === pending.operationId, 'Repository restoration checkpoint operation is invalid.');
+    const query = new URLSearchParams({ workspaceId: scope.workspaceId, operationId: pending.operationId });
+    const suffix = pending.candidateId ? `/${encodeURIComponent(pending.candidateId)}` : '';
+    const response = await input.transport.signedGet(`/agent-fabric/repository-agents/${encodeURIComponent(scope.repositoryAgentId)}/package-candidates${suffix}?${query}`);
+    if (!pending.candidateId && response.ok === true && response.organizationId === scope.organizationId && response.candidate === null) {
+        throw new Error('repository_source_restoration_upload_unresolved');
+    }
+    const candidate = receipt(response, scope, pending.operationId, pending.snapshotHash, pending.restoration.priorReleaseId);
+    requireFact(!pending.candidateId || candidate.candidateId === pending.candidateId, 'Repository restoration checkpoint candidate changed.');
+    return { candidate, sourceManifestHash: pending.sourceManifestHash, ...pending.restoration };
+}
+// Called only after the command's final authority, CAS and stopped-runtime
+// checks. Keep restoration provenance if the following registry write fails.
+export async function checkpointRepositoryRestorationCandidate(input) {
+    const scope = checkedScope(input.scope), recovered = input.recovered;
+    const path = outboxPath(input.outboxRoot, scope), pending = await readOutbox(path, scope);
+    const expected = restorationCheckpoint({ planHash: recovered.planHash, localSnapshotHash: recovered.localSnapshotHash,
+        baselineSnapshotHash: recovered.baselineSnapshotHash, previousOperationId: recovered.previousOperationId,
+        priorReleaseId: recovered.priorReleaseId, ...(recovered.attemptId ? { attemptId: recovered.attemptId } : {}),
+        ...(recovered.headCandidateId ? { headCandidateId: recovered.headCandidateId } : {}) });
+    requireFact(pending?.restoration && pending.state !== 'fenced' && canonicalize(pending.restoration) === canonicalize(expected)
+        && pending.sourceManifestHash === recovered.sourceManifestHash
+        && pending.consolidation.mode === 'repository_update' && Boolean(pending.consolidation.expectedLatestSourceFingerprint)
+        && repositoryCandidateOperationId({ scope, snapshotHash: pending.snapshotHash,
+            sourceManifestHash: pending.sourceManifestHash, consolidation: pending.consolidation,
+            restorationAttempt: pending.restoration.attemptId, restorationContext: restorationContext(pending.restoration) }) === pending.operationId, 'Repository restoration checkpoint changed.');
+    const candidate = receipt({ ok: true, organizationId: scope.organizationId, candidate: recovered.candidate }, scope, pending.operationId, pending.snapshotHash, pending.restoration.priorReleaseId);
+    requireFact(!pending.candidateId || pending.candidateId === candidate.candidateId, 'Repository restoration checkpoint candidate changed.');
+    requireFact(!['published', 'blocked'].includes(pending.state)
+        || pending.state === candidate.state && pending.releaseId === candidate.releaseId, 'Repository restoration checkpoint terminal state changed.');
+    await writeOutbox(path, { ...pending, ...candidate });
+    return candidate;
+}
+export async function readRepositoryRestorationAttempt(input) {
+    const scope = checkedScope(input.scope), pending = await readOutbox(outboxPath(input.outboxRoot, scope), scope);
+    return pending?.state === 'fenced' ? pending.fence.fenceId
+        : pending?.state === 'pending_upload' ? pending.restoration?.attemptId : undefined;
+}
+// Explicit recovery only: this can fence an unadmitted operation but never
+// cancels admitted work, uploads source, or retires a local checkpoint.
+export async function fenceRepositoryRestorationUpload(input) {
+    const scope = checkedScope(input.scope);
+    requireFact(HASH.test(input.planHash) && UUID.test(input.policyGenerationId), 'Repository restoration fence authority is invalid.');
+    let pending = await readOutbox(outboxPath(input.outboxRoot, scope), scope);
+    requireFact(pending?.restoration && pending.restoration.planHash === input.planHash
+        && pending.restoration.previousOperationId === input.expectedPreviousOperationId
+        && ['pending_upload', 'fenced'].includes(pending.state) && pending.candidateId === null
+        && pending.consolidation.mode === 'repository_update' && Boolean(pending.consolidation.expectedLatestSourceFingerprint)
+        && repositoryCandidateOperationId({ scope, snapshotHash: pending.snapshotHash, sourceManifestHash: pending.sourceManifestHash,
+            consolidation: pending.consolidation, restorationAttempt: pending.restoration.attemptId,
+            restorationContext: restorationContext(pending.restoration) }) === pending.operationId, 'Repository restoration fence checkpoint is invalid.');
+    const schemaDirectory = fileURLToPath(new URL('./schemas/', import.meta.url));
+    if (pending.state === 'fenced') {
+        // Containment is already durable. Reposting under a newer policy cannot
+        // change this receipt; the guarded checkpoint verifies the immutable archive.
+        requireFact((await validateContract(schemaDirectory, 'https://schemas.dharma-ai.io/repository-candidate-fence/v1#/$defs/fence', pending.fence)).ok, 'Repository restoration fence receipt schema is invalid.');
+        return { checkpointHash: sha256(canonicalize(pending)), pending, fence: pending.fence, candidate: null };
+    }
+    // The command holds its registry mutation lock. Persist request provenance
+    // before transport so response loss cannot erase the original retry binding.
+    const restoration = pending.restoration;
+    if (!pending.fenceRequestGenerationId) {
+        pending = { ...pending, fenceRequestGenerationId: input.policyGenerationId };
+        await writeOutbox(outboxPath(input.outboxRoot, scope), pending);
+        if (process.platform !== 'win32') {
+            const parent = await open(resolve(input.outboxRoot), constants.O_RDONLY | constants.O_DIRECTORY | (constants.O_NOFOLLOW || 0));
+            try {
+                await parent.sync();
+            }
+            finally {
+                await parent.close();
+            }
+        }
+    }
+    const body = {
+        schema: 'dharma.repository-candidate-fence/v1', operationId: pending.operationId,
+        workspaceId: scope.workspaceId, repositoryBindingId: scope.repositoryBindingId, repositoryAgentId: scope.repositoryAgentId,
+        sourceSnapshotHash: pending.snapshotHash, sourceManifestHash: pending.sourceManifestHash, consolidation: pending.consolidation,
+        requestPolicyGenerationId: pending.fenceRequestGenerationId,
+        ...(restoration.attemptId ? { restorationAttempt: restoration.attemptId } : {}),
+        ...(restorationContext(restoration) ? { restorationContext: restorationContext(restoration) } : {}),
+    };
+    requireFact((await validateContract(schemaDirectory, 'https://schemas.dharma-ai.io/repository-candidate-fence/v1', body)).ok
+        && Buffer.byteLength(canonicalize(body)) <= 4096, 'Repository restoration fence metadata is invalid.');
+    const response = await input.transport.signedPost(`/agent-fabric/repository-agents/${encodeURIComponent(scope.repositoryAgentId)}/package-candidates/fence`, body);
+    requireFact(response.ok === true && response.organizationId === scope.organizationId
+        && Object.hasOwn(response, 'candidate') && Object.hasOwn(response, 'fence')
+        && (response.candidate === null) !== (response.fence === null), 'Repository restoration fence response is invalid.');
+    const fence = response.fence === null ? null : checkedFence(response.fence, scope, pending.operationId, pending.snapshotHash, pending.sourceManifestHash, pending.fenceRequestGenerationId);
+    requireFact(!fence || (await validateContract(schemaDirectory, 'https://schemas.dharma-ai.io/repository-candidate-fence/v1#/$defs/fence', fence)).ok, 'Repository restoration fence receipt schema is invalid.');
+    const candidate = fence ? null : receipt(response, scope, pending.operationId, pending.snapshotHash, restoration.priorReleaseId);
+    return { checkpointHash: sha256(canonicalize(pending)), pending, fence, candidate };
+}
+async function archiveFencedCheckpoint(root, pending) {
+    requireFact(pending.state === 'fenced' && pending.fence && pending.restoration, 'Repository restoration terminal fence is required.');
+    const { fence, ...checkpoint } = pending;
+    const value = { checkpoint: { ...checkpoint, state: 'pending_upload' }, fence };
+    const bytes = `${canonicalize(value)}\n`, directory = resolve(root, 'fenced');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const directoryStat = await lstat(directory);
+    requireFact(directoryStat.isDirectory() && !directoryStat.isSymbolicLink(), 'Repository restoration archive directory is invalid.');
+    const path = resolve(directory, `${pending.scope.workspaceId}.${fence.fenceId}.json`);
+    const temporary = resolve(directory, `.${pending.scope.workspaceId}.${fence.fenceId}.${randomUUID()}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    try {
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // Publishing a fully flushed inode with a link cannot replace an existing archive.
+        try {
+            await link(temporary, path);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const before = await lstat(path);
+            requireFact(before.isFile() && !before.isSymbolicLink() && before.size <= 65_536, 'Repository restoration archive is invalid.');
+            const existing = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+            try {
+                const after = await existing.stat();
+                requireFact(after.isFile() && before.ino === after.ino && before.dev === after.dev && after.size <= 65_536
+                    && await existing.readFile('utf8') === bytes, 'Repository restoration archive changed.');
+            }
+            finally {
+                await existing.close();
+            }
+        }
+        if (process.platform !== 'win32') {
+            const parent = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | (constants.O_NOFOLLOW || 0));
+            try {
+                await parent.sync();
+            }
+            finally {
+                await parent.close();
+            }
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+// The command invokes this only after the registry CAS, current authority and
+// stopped-runtime guards. Persist the terminal archive before replacement.
+export async function checkpointRepositoryRestorationFence(input) {
+    const scope = checkedScope(input.scope), path = outboxPath(input.outboxRoot, scope), pending = await readOutbox(path, scope);
+    requireFact(pending && sha256(canonicalize(pending)) === input.fenced.checkpointHash
+        && input.fenced.fence && input.fenced.candidate === null, 'Repository restoration fence checkpoint changed.');
+    const fence = checkedFence(input.fenced.fence, scope, pending.operationId, pending.snapshotHash, pending.sourceManifestHash, pending.fenceRequestGenerationId);
+    const next = { ...pending, state: 'fenced', fence };
+    await archiveFencedCheckpoint(input.outboxRoot, next);
+    if (canonicalize(next) !== canonicalize(pending))
+        await writeOutbox(path, next);
+    return fence;
+}
 export async function pollRepositoryCandidate(input) {
     const scope = checkedScope(input.scope);
     const path = outboxPath(input.outboxRoot, scope);
     const pending = await readOutbox(path, scope);
-    if (!pending || pending.state === 'pending_upload')
+    if (!pending || pending.state === 'pending_upload' || pending.state === 'fenced')
         return null;
     if (pending.state === 'published' || pending.state === 'blocked') {
+        requireFact(pending.state !== 'published' || pending.releaseId !== pending.restoration?.priorReleaseId, 'Repository restoration cannot reuse the archived release identity.');
         return { candidateId: pending.candidateId, operationId: pending.operationId, snapshotHash: pending.snapshotHash,
             state: pending.state, releaseId: pending.releaseId };
     }
     const route = `/agent-fabric/repository-agents/${encodeURIComponent(scope.repositoryAgentId)}/package-candidates`;
     const query = new URLSearchParams({ workspaceId: scope.workspaceId, operationId: pending.operationId });
-    const current = receipt(await input.transport.signedGet(`${route}/${encodeURIComponent(pending.candidateId)}?${query}`), scope, pending.operationId, pending.snapshotHash);
+    const current = receipt(await input.transport.signedGet(`${route}/${encodeURIComponent(pending.candidateId)}?${query}`), scope, pending.operationId, pending.snapshotHash, pending.restoration?.priorReleaseId);
     await writeOutbox(path, { ...pending, candidateId: current.candidateId, state: current.state, releaseId: current.releaseId });
     return current;
 }
@@ -191,6 +467,35 @@ export async function adoptRepositoryCandidate(input) {
     const scope = checkedScope(input.scope);
     requireFact(HASH.test(input.sourceManifestHash), 'Canonical repository candidate manifest hash is invalid.');
     const candidate = receipt({ ok: true, organizationId: scope.organizationId, candidate: input.candidate }, scope, input.candidate.operationId, input.candidate.snapshotHash);
+    const prior = await readOutbox(outboxPath(input.outboxRoot, scope), scope);
+    if (prior?.state === 'fenced') {
+        requireFact(prior.operationId !== candidate.operationId, 'A fenced operation cannot be adopted.');
+        requireFact(['published', 'blocked'].includes(candidate.state), 'A fenced restoration requires a terminal canonical candidate before adoption. Retry after canonical publication completes.');
+        await archiveFencedCheckpoint(input.outboxRoot, prior);
+        // Registry adoption is not a new restoration. Keep its terminal retry
+        // identity active until a restoration explicitly carries this fence ID.
+        return candidate;
+    }
+    else if (prior?.restoration) {
+        requireFact(['published', 'blocked'].includes(prior.state), 'An unresolved restoration checkpoint cannot be replaced by adoption.');
+        if (prior.operationId === candidate.operationId) {
+            requireFact(prior.candidateId === candidate.candidateId && prior.snapshotHash === candidate.snapshotHash
+                && prior.sourceManifestHash === input.sourceManifestHash && prior.state === candidate.state && prior.releaseId === candidate.releaseId
+                && prior.consolidation.mode === input.consolidationMode, 'Restoration adoption changed its checkpoint.');
+            requireFact(prior.consolidation.mode === 'repository_update' && Boolean(prior.consolidation.expectedLatestSourceFingerprint)
+                && repositoryCandidateOperationId({ scope, snapshotHash: prior.snapshotHash,
+                    sourceManifestHash: prior.sourceManifestHash, consolidation: prior.consolidation,
+                    restorationAttempt: prior.restoration.attemptId, restorationContext: restorationContext(prior.restoration) }) === prior.operationId, 'Repository restoration checkpoint operation is invalid.');
+            requireFact(candidate.state !== 'published' || candidate.releaseId !== prior.restoration.priorReleaseId, 'Repository restoration cannot reuse the archived release identity.');
+            // Internal save metadata only; never add it to a signed candidate receipt.
+            return { ...candidate, restorationRegistryBaseline: {
+                    localBaselineSnapshotHash: prior.state === 'blocked' ? prior.restoration.baselineSnapshotHash : prior.restoration.localSnapshotHash,
+                    publishedLocalSnapshotHash: prior.state === 'published' ? prior.restoration.localSnapshotHash : prior.restoration.baselineSnapshotHash,
+                    pendingLocalSnapshotHash: null, pendingLocalOperationId: null,
+                } };
+        }
+        assertRestorationReconciled(prior);
+    }
     requireFact(candidate.state !== 'accepted' || candidate.candidateId !== null, 'Canonical repository candidate is incomplete.');
     await writeOutbox(outboxPath(input.outboxRoot, scope), {
         schema: 'dharma.repository-candidate-outbox/v1', scope, operationId: candidate.operationId,