@sentropic/artifacts 0.1.3 → 0.2.0

package/dist/server/preparation-cleanup.js

@@ -0,0 +1,106 @@
+import { blobDigestOfKey } from './publication.js';
+function preparation(intent) {
+    const p = intent.payload;
+    if (typeof p.attemptId !== 'string' || typeof p.invocationId !== 'string' ||
+        typeof p.preparedAtMs !== 'number' || !Number.isFinite(p.preparedAtMs) ||
+        typeof p.cleanupDeadlineMs !== 'number' || !Number.isFinite(p.cleanupDeadlineMs) ||
+        p.cleanupDeadlineMs <= p.preparedAtMs || !Array.isArray(p.blobKeys) ||
+        !p.blobKeys.every((key) => typeof key === 'string'))
+        throw new Error('invalid preparation metadata');
+    return { attemptId: p.attemptId, invocationId: p.invocationId,
+        preparedAtMs: p.preparedAtMs, cleanupDeadlineMs: p.cleanupDeadlineMs, blobKeys: [...p.blobKeys],
+        state: p.cleanupState === 'failed-cleaned' ? 'failed-cleaned' : intent.state === 'failed' ? 'failed' : 'pending-cleanup' };
+}
+async function hasResidualBytes(host, attempt) {
+    for (const key of attempt.blobKeys) {
+        const digest = blobDigestOfKey(key);
+        if (await host.refs.count(digest) === 0 && !await host.refs.isPinned(digest) &&
+            (await host.blobs.listKeys(key)).includes(key))
+            return true;
+    }
+    return false;
+}
+/** Historical attempt attribution plus current protection, scoped to one artifact. */
+export async function inspectPreparations(host, artifactId) {
+    const intents = await host.intents.listPreparationIntents({ artifactId });
+    const attempts = [];
+    const invalidIntents = [];
+    for (const intent of intents) {
+        let attempt;
+        try {
+            attempt = preparation(intent);
+        }
+        catch (error) {
+            invalidIntents.push({ intentId: intent.intentId, error: String(error) });
+            continue;
+        }
+        attempts.push(attempt.state === 'failed-cleaned' && await hasResidualBytes(host, attempt)
+            ? { ...attempt, state: 'failed' } : attempt);
+    }
+    const protectedKeys = [], abandonedKeys = [];
+    for (const key of [...new Set(attempts.flatMap((attempt) => attempt.blobKeys))].sort()) {
+        const digest = blobDigestOfKey(key);
+        const protectedBlob = await host.refs.count(digest) > 0 || await host.refs.isPinned(digest);
+        (protectedBlob ? protectedKeys : abandonedKeys).push(key);
+    }
+    return { attempts, protectedKeys, abandonedKeys, invalidIntents };
+}
+/** Run one deterministic, bounded sweep through the supplied clock deadline. */
+export async function scheduleBoundedPreparationCleanup(host, throughMs) {
+    const limit = host.cleanupBatchSize ?? 100;
+    if (!Number.isFinite(throughMs) || !Number.isSafeInteger(limit) || limit < 1)
+        throw new Error('invalid cleanup bound');
+    const candidates = await host.intents.listPreparationIntents({ throughMs, limit });
+    const failures = [];
+    for (const candidate of candidates) {
+        try {
+            let previous;
+            try {
+                previous = preparation(candidate);
+            }
+            catch (error) {
+                await host.intents.markFailed(candidate.intentId, `invalid preparation metadata: ${candidate.intentId}`);
+                throw error;
+            }
+            if (previous.state === 'failed-cleaned' && !await hasResidualBytes(host, previous))
+                continue;
+            const intent = await host.intents.claimPreparationCleanup(candidate.intentId, throughMs);
+            if (intent === undefined)
+                continue;
+            const attempt = preparation(intent);
+            if (typeof intent.payload.releaseId !== 'string')
+                throw new Error('preparation has no pin owner');
+            for (const key of [...new Set(attempt.blobKeys)].sort()) {
+                const digest = blobDigestOfKey(key);
+                await host.claims.withDigestLock(digest, async (claims) => {
+                    try {
+                        await host.refs.unpin(digest, `preparation:${intent.payload.releaseId}`);
+                    }
+                    catch (error) {
+                        if (!(error instanceof Error) || !/not pinned/.test(error.message))
+                            throw error;
+                    }
+                    if (await host.refs.count(digest) > 0 || await host.refs.isPinned(digest))
+                        return;
+                    // A different purge owns its claim and acknowledges its own external DELETE.
+                    if (await claims.isClaimed(digest))
+                        throw new Error('preparation cleanup blocked by deletion claim');
+                    await claims.claim(digest, `cleanup:${intent.intentId}`);
+                    try {
+                        if ((await host.blobs.listKeys(key)).includes(key))
+                            await host.blobs.deleteBlob(key);
+                    }
+                    finally {
+                        await claims.releaseClaim(digest);
+                    }
+                });
+            }
+            await host.intents.settlePreparationCleanup(intent.intentId);
+        }
+        catch (error) {
+            failures.push(new Error(`preparation ${candidate.intentId}: ${String(error)}`, { cause: error }));
+        }
+    }
+    if (failures.length)
+        throw new AggregateError(failures, 'preparation cleanup failed; debt retained for retry');
+}

package/dist/server/publication-limits.d.ts

@@ -0,0 +1,10 @@
+import type { PublicationFileInput } from './publication.js';
+export interface PublicationLimits {
+    maxFiles: number;
+    maxFileBytes: number;
+    maxTotalBytes: number;
+}
+export declare const DEFAULT_PUBLICATION_LIMITS: Readonly<PublicationLimits>;
+export declare function publicationLimits(overrides?: Partial<PublicationLimits>): Readonly<PublicationLimits>;
+/** Validate before copying bytes, hashing, idempotency lookup or recording intents. */
+export declare function validatePublicationFiles(files: PublicationFileInput[], limits: Readonly<PublicationLimits>): void;

package/dist/server/publication-limits.js

@@ -0,0 +1,38 @@
+export const DEFAULT_PUBLICATION_LIMITS = Object.freeze({
+    maxFiles: 128, maxFileBytes: 16 * 1024 * 1024, maxTotalBytes: 64 * 1024 * 1024,
+});
+export function publicationLimits(overrides = {}) {
+    const limits = { ...DEFAULT_PUBLICATION_LIMITS, ...overrides };
+    if (Object.values(limits).some((value) => !Number.isSafeInteger(value) || value <= 0)) {
+        throw new Error('invalid publication limits');
+    }
+    return Object.freeze(limits);
+}
+/** Validate before copying bytes, hashing, idempotency lookup or recording intents. */
+export function validatePublicationFiles(files, limits) {
+    if (!Array.isArray(files) || files.length === 0 || files.length > limits.maxFiles) {
+        throw new Error('invalid publication file count budget');
+    }
+    const paths = new Set();
+    let total = 0;
+    for (const file of files) {
+        if (typeof file.path !== 'string' || Buffer.byteLength(file.path) > 1024 ||
+            /[\\%?#:\u0000-\u001f\u007f]/.test(file.path) ||
+            file.path.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+            throw new Error('invalid publication path');
+        }
+        if (paths.has(file.path))
+            throw new Error('duplicate publication path');
+        paths.add(file.path);
+        if (typeof file.mimeType !== 'string' || file.mimeType.length === 0 ||
+            file.mimeType.length > 256 || /[\u0000-\u001f\u007f]/.test(file.mimeType)) {
+            throw new Error('invalid publication MIME type');
+        }
+        if (!(file.bytes instanceof Uint8Array) || file.bytes.byteLength > limits.maxFileBytes) {
+            throw new Error('invalid publication file byte budget');
+        }
+        total += file.bytes.byteLength;
+        if (total > limits.maxTotalBytes)
+            throw new Error('invalid publication total byte budget');
+    }
+}

package/dist/server/publication.d.ts

@@ -1,6 +1,14 @@
 import type { JsonValue } from '../contracts.js';
 import type { IntentStore } from './object-intents.js';
 import type { IdempotencyStore } from './idempotency.js';
+import { type SourceRef, type SourceStore } from './sources.js';
+import { type PublicationLimits } from './publication-limits.js';
+import type { ArtifactAcl } from './access.js';
+import type { ArtifactState } from './lifecycle.js';
+import { type RefcountStore } from './gc.js';
+import type { CommandIdentity } from './command-identity.js';
+import type { CommitLockFn, ArtifactCommitCoordinator, FinalizeResult, FinalizeTxClient } from './commit/types.js';
+export { DEFAULT_PUBLICATION_LIMITS, type PublicationLimits } from './publication-limits.js';
 export interface ReleaseRecord {
     releaseId: string;
     artifactId: string;
@@ -40,7 +48,9 @@ export interface PublishInput {
     artifactId: string;
     profile: Record<string, JsonValue | undefined>;
     files: PublicationFileInput[];
+    source?: SourceRef;
     idempotencyKey?: string;
+    /** @deprecated Ignored; the server hashes release metadata and file digests. */
     paramsHash?: string;
 }
 export interface PublishResult {
@@ -48,7 +58,9 @@ export interface PublishResult {
     manifest: string;
 }
 export interface PublicationService {
-    publish(input: PublishInput): Promise<PublishResult>;
+    readonly limits?: Readonly<PublicationLimits>;
+    /** The host source store participates in the idempotent commit when a source is supplied. */
+    publish(input: PublishInput, sources?: SourceStore): Promise<PublishResult>;
     getCurrent(artifactId: string): Promise<{
         releaseId: string;
         manifest: string;
@@ -64,4 +76,76 @@ export declare function createPublicationService(deps: {
     blobs: PublicationBlobStore;
     intents: IntentStore;
     idempotency?: IdempotencyStore;
+    limits?: Partial<PublicationLimits>;
 }): PublicationService;
+/**
+ * L4 (immo #861) — guarded publication through the L3 atomic finalization
+ * unit (spec r2 A3–A6).
+ *
+ * Blob bytes are staged and read-back-verified in preparation (no key lock
+ * or leased connection spans S3 I/O). The unit then runs caller lifecycle /
+ * ACL / pointer locks, provisional release + pointer + refcount writes, the
+ * host guard after all waits (lifecycle-active + owner ACL + participant
+ * approval), a single success insert with intent completion, and one COMMIT.
+ * Denial or conflict rolls everything back: no release, pointer, receipt or
+ * (transactional) refcount residue. Same caller key replays the winner.
+ */
+export type PublishDenialReason = 'denied' | 'revoked' | 'invalid_object';
+export interface PublishAuthorizationInput {
+    readonly lifecycleState: ArtifactState;
+    readonly acl: ArtifactAcl | undefined;
+    readonly actorId: string;
+}
+/**
+ * Pure lifecycle/ACL predicate evaluated after the unit waits with fresh
+ * reads. Owner-only publication: lifecycle mutations are owner-only across
+ * the service, and grant-based publish rights stay a host/L5 decision.
+ */
+export declare function decidePublishAuthorization(input: PublishAuthorizationInput): {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: PublishDenialReason;
+};
+/** Transaction-scoped provisional writers for the finalized unit. */
+export interface PublicationUnitWriter {
+    readAuthorization(artifactId: string): Promise<{
+        state: ArtifactState;
+        acl: ArtifactAcl | undefined;
+    }>;
+    putSource(artifactId: string, source: SourceRef): Promise<void>;
+    putRelease(release: ReleaseRecord): Promise<void>;
+    registerBlob(storageScopeId: string, digest: string, size: number): Promise<void>;
+    promoteCurrentLatestWins(artifactId: string, releaseId: string): Promise<void>;
+    addReleaseRef(digest: string, holder: string): Promise<void>;
+    completeIntent(intentId: string): Promise<void>;
+}
+/** PostgreSQL unit writer over the coordinator's leased client. */
+export declare function createPostgresPublicationUnitWriter(client: FinalizeTxClient): PublicationUnitWriter;
+export interface GuardedPublishInput extends PublishInput {
+    /** Frozen trusted identity supplied by the host's L1 command normalizer. */
+    readonly identity: CommandIdentity;
+    readonly actorId: string;
+    readonly policyRevision: string;
+    readonly callerKey?: string;
+    readonly attemptId?: string;
+    readonly invocationId?: string;
+}
+export interface GuardedPublicationDeps {
+    readonly coordinator: ArtifactCommitCoordinator;
+    readonly blobs: PublicationBlobStore;
+    readonly intents: IntentStore;
+    readonly createUnitWriter: (client: FinalizeTxClient) => PublicationUnitWriter;
+    /** Host row locks in PARTICIPANT_LOCK_ORDER classes (PG FOR UPDATE; empty for memory). */
+    readonly locks?: Partial<Record<'artifact-lifecycle' | 'acl' | 'current-pointer', CommitLockFn[]>>;
+    /** Shared retention store: preparation pins and denial compensation. */
+    readonly refs: RefcountStore;
+    readonly noteAbandoned?: (attemptId: string) => void | Promise<void>;
+    readonly cleanupWindowMs?: number;
+    readonly limits?: Partial<PublicationLimits>;
+}
+export interface GuardedPublicationService {
+    publishFinalized(input: GuardedPublishInput): Promise<FinalizeResult>;
+}
+/** Create a publication service whose commits finalize through L3 ports. */
+export declare function createGuardedPublicationService(deps: GuardedPublicationDeps): GuardedPublicationService;

package/dist/server/publication.js

@@ -13,6 +13,10 @@
  */
 import { createHash } from 'node:crypto';
 import { canonicalManifest, manifestDigest } from '../codecs.js';
+import { parseSourceRef } from './sources.js';
+import { publicationLimits, validatePublicationFiles } from './publication-limits.js';
+import { createPostgresDeletionClaimStore } from './gc.js';
+export { DEFAULT_PUBLICATION_LIMITS } from './publication-limits.js';
 /** Derive the `sha256:<hex>` digest from a digest-addressed blob key. */
 export function blobDigestOfKey(key) {
     const hex = key.split('/').pop() ?? '';
@@ -70,28 +74,46 @@ export function createMemoryBlobStore() {
 function shaHex(bytes) {
     return createHash('sha256').update(bytes).digest('hex');
 }
+/** Validate-free preparation shared by the split and finalized paths. */
+function preparePublication(input) {
+    const entries = input.files.map((file) => {
+        const hex = shaHex(file.bytes);
+        return {
+            entry: { path: file.path, digest: `sha256:${hex}`, size: file.bytes.length, mimeType: file.mimeType },
+            key: `artifacts/${input.storageScopeId}/blobs/sha256/${hex}`,
+            bytes: file.bytes,
+        };
+    });
+    const body = {
+        schemaVersion: 'artifacts/v1',
+        artifactId: input.artifactId,
+        storageScopeId: input.storageScopeId,
+        ownerId: input.ownerId,
+        profile: input.profile,
+        files: entries.map((e) => e.entry),
+    };
+    const digest = manifestDigest(body);
+    const manifest = canonicalManifest({ ...body, digest });
+    return { entries, digest, manifest };
+}
+/** Read-back verification shared by the split and finalized paths. */
+async function verifyStagedBlobs(blobs, entries) {
+    for (const { key, bytes } of entries) {
+        const stored = await blobs.getBlob(key);
+        if (stored === undefined || shaHex(stored) !== shaHex(bytes)) {
+            throw new Error(`publication digest mismatch for ${key}: read-back failed`);
+        }
+        if (stored.length !== bytes.length) {
+            throw new Error(`publication size mismatch for ${key}: read-back failed`);
+        }
+    }
+}
 /** Create a publication service over injected stores (no driver imports). */
 export function createPublicationService(deps) {
-    async function commitOnce(input) {
+    const limits = publicationLimits(deps.limits);
+    async function commitOnce(input, prepared, sources) {
         const releaseId = crypto.randomUUID();
-        const entries = input.files.map((file) => {
-            const hex = shaHex(file.bytes);
-            return {
-                entry: { path: file.path, digest: `sha256:${hex}`, size: file.bytes.length, mimeType: file.mimeType },
-                key: `artifacts/${input.storageScopeId}/blobs/sha256/${hex}`,
-                bytes: file.bytes,
-            };
-        });
-        const body = {
-            schemaVersion: 'artifacts/v1',
-            artifactId: input.artifactId,
-            storageScopeId: input.storageScopeId,
-            ownerId: input.ownerId,
-            profile: input.profile,
-            files: entries.map((e) => e.entry),
-        };
-        const digest = manifestDigest(body);
-        const manifest = canonicalManifest({ ...body, digest });
+        const { entries, digest, manifest } = prepared;
         const intent = await deps.intents.record('commit-release', {
             artifactId: input.artifactId,
             releaseId,
@@ -101,15 +123,7 @@ export function createPublicationService(deps) {
         for (const { key, bytes } of entries) {
             await deps.blobs.putBlob(key, bytes);
         }
-        for (const { key, bytes } of entries) {
-            const stored = await deps.blobs.getBlob(key);
-            if (stored === undefined || shaHex(stored) !== shaHex(bytes)) {
-                throw new Error(`publication digest mismatch for ${key}: read-back failed`);
-            }
-            if (stored.length !== bytes.length) {
-                throw new Error(`publication size mismatch for ${key}: read-back failed`);
-            }
-        }
+        await verifyStagedBlobs(deps.blobs, entries);
         await deps.state.putRelease({
             releaseId,
             artifactId: input.artifactId,
@@ -124,16 +138,26 @@ export function createPublicationService(deps) {
             await deps.intents.markFailed(intent.intentId, 'commit race lost: explicit conflict');
             throw new Error(`publication conflict for ${input.artifactId}: concurrent commit won`);
         }
+        if (input.source !== undefined)
+            await sources.putSource(input.artifactId, input.source);
         await deps.intents.complete(intent.intentId);
         return { releaseId, manifest };
     }
     return {
-        async publish(input) {
+        limits,
+        async publish(input, sources) {
+            validatePublicationFiles(input.files, limits);
+            const source = input.source === undefined ? undefined : parseSourceRef(input.source);
+            if (source !== undefined && sources === undefined)
+                throw new Error('invalid publication: missing source store');
+            input = { ...input, source, files: input.files.map((file) => ({ ...file, bytes: new Uint8Array(file.bytes) })) };
+            const prepared = preparePublication(input);
+            const requestHash = createHash('sha256').update(JSON.stringify([prepared.digest, source ?? null])).digest('hex');
             if (input.idempotencyKey !== undefined && deps.idempotency !== undefined) {
-                const { result } = await deps.idempotency.execute(input.idempotencyKey, input.paramsHash ?? '', () => commitOnce(input));
+                const { result } = await deps.idempotency.execute(JSON.stringify(['publish', input.ownerId, input.idempotencyKey]), requestHash, () => commitOnce(input, prepared, sources));
                 return result;
             }
-            return commitOnce(input);
+            return commitOnce(input, prepared, sources);
         },
         async getCurrent(artifactId) {
             const releaseId = await deps.state.getCurrentReleaseId(artifactId);
@@ -152,3 +176,236 @@ export function createPublicationService(deps) {
         },
     };
 }
+/**
+ * Pure lifecycle/ACL predicate evaluated after the unit waits with fresh
+ * reads. Owner-only publication: lifecycle mutations are owner-only across
+ * the service, and grant-based publish rights stay a host/L5 decision.
+ */
+export function decidePublishAuthorization(input) {
+    if (input.lifecycleState === 'withdrawn')
+        return { allowed: false, reason: 'revoked' };
+    if (input.lifecycleState === 'deleted' || input.lifecycleState === 'purged') {
+        return { allowed: false, reason: 'invalid_object' };
+    }
+    if (input.lifecycleState !== 'active')
+        return { allowed: false, reason: 'revoked' };
+    if (input.acl === undefined || input.acl.ownerId !== input.actorId) {
+        return { allowed: false, reason: 'denied' };
+    }
+    return { allowed: true };
+}
+/** PostgreSQL unit writer over the coordinator's leased client. */
+export function createPostgresPublicationUnitWriter(client) {
+    return {
+        async readAuthorization(artifactId) {
+            const { rows } = await client.query('SELECT lifecycle_state, owner_id FROM artifacts.artifacts WHERE id = $1', [artifactId]);
+            const row = rows[0];
+            return { state: row?.lifecycle_state ?? 'purged',
+                acl: row === undefined ? undefined : { ownerId: row.owner_id, grants: [], isPublic: false,
+                    withdrawn: row.lifecycle_state === 'withdrawn' } };
+        },
+        async putSource(artifactId, source) {
+            await client.query(`INSERT INTO artifacts.artifact_sources (artifact_id, kind, commit_tx, steps)
+         VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT (artifact_id) DO UPDATE
+         SET kind = EXCLUDED.kind, commit_tx = EXCLUDED.commit_tx, steps = EXCLUDED.steps`, [artifactId, source.kind, source.kind === 'base-commit' ? source.commit : null,
+                source.kind === 'recipe' ? JSON.stringify(source.steps) : null]);
+        },
+        async putRelease(release) {
+            await client.query(`INSERT INTO artifacts.releases (id, artifact_id, manifest_digest, manifest, state, created_at)
+         VALUES ($1, $2, $3, $4, 'ready', $5)`, [release.releaseId, release.artifactId, release.manifestDigest, release.manifest, release.createdAt]);
+        },
+        async registerBlob(storageScopeId, digest, size) {
+            await client.query(`INSERT INTO artifacts.blobs (storage_scope_id, digest, size)
+         VALUES ($1, $2, $3) ON CONFLICT DO NOTHING`, [storageScopeId, digest, size]);
+        },
+        async promoteCurrentLatestWins(artifactId, releaseId) {
+            // CR-3 latest-wins: last committer wins the pointer, no loser conflict.
+            await client.query(`INSERT INTO artifacts.artifact_current (artifact_id, release_id)
+         VALUES ($1, $2) ON CONFLICT (artifact_id) DO UPDATE SET release_id = EXCLUDED.release_id`, [artifactId, releaseId]);
+        },
+        async addReleaseRef(digest, holder) {
+            await createPostgresDeletionClaimStore(client).withDigestLock(digest, async (claims) => {
+                if (await claims.isClaimed(digest))
+                    throw new Error(`blob scheduled for deletion: ${digest}`);
+                await client.query(`INSERT INTO artifacts.blob_ref_holders (digest, holder)
+           VALUES ($1, $2) ON CONFLICT DO NOTHING`, [digest, holder]);
+            });
+        },
+        async completeIntent(intentId) {
+            const { rowCount } = await client.query(`UPDATE artifacts.object_intents SET state = 'done', updated_at = now() WHERE id = $1
+         AND state = 'pending' AND (NOT (payload ? 'cleanupDeadlineMs')
+           OR (payload->>'cleanupDeadlineMs')::numeric > EXTRACT(EPOCH FROM clock_timestamp()) * 1000)`, [intentId]);
+            if (rowCount === 0)
+                throw new Error('preparation expired or abandoned; explicit retry required');
+        },
+    };
+}
+const DEFAULT_CLEANUP_WINDOW_MS = 15 * 60 * 1000;
+/** Create a publication service whose commits finalize through L3 ports. */
+export function createGuardedPublicationService(deps) {
+    const limits = publicationLimits(deps.limits);
+    const cleanupWindowMs = deps.cleanupWindowMs ?? DEFAULT_CLEANUP_WINDOW_MS;
+    if (!Number.isSafeInteger(cleanupWindowMs) || cleanupWindowMs < 1)
+        throw new Error('invalid preparation lifetime');
+    const guard = (client) => async (context, transaction) => {
+        const { state, acl } = await deps.createUnitWriter(client()).readAuthorization(context.artifactId);
+        const verdict = decidePublishAuthorization({ lifecycleState: state, acl, actorId: context.actorId });
+        if (!verdict.allowed) {
+            return {
+                allowed: false,
+                reason: verdict.reason,
+                publicCode: 'access_denied',
+                status: 403,
+                retriable: false,
+            };
+        }
+        const approval = await transaction.participant.checkApproval({
+            actorId: context.actorId,
+            operation: context.operation,
+        });
+        if (!approval.approved) {
+            return {
+                allowed: false,
+                reason: approval.reason ?? 'denied',
+                publicCode: 'access_denied',
+                status: 403,
+                retriable: false,
+            };
+        }
+        const revision = await transaction.participant.readRevision();
+        if (revision !== context.policyRevision) {
+            return {
+                allowed: false,
+                reason: 'revoked',
+                publicCode: 'access_denied',
+                status: 403,
+                retriable: false,
+            };
+        }
+        return { allowed: true, fence: transaction.participant.mintFence(revision, context.invocationId) };
+    };
+    return {
+        async publishFinalized(input) {
+            validatePublicationFiles(input.files, limits);
+            const prepared = preparePublication(input);
+            const { internalKey, commandHash, codecVersion } = input.identity;
+            const callerKey = input.callerKey ?? internalKey;
+            const releaseId = crypto.randomUUID();
+            const invocationId = input.invocationId ?? crypto.randomUUID();
+            const attemptId = input.attemptId ?? releaseId;
+            const nowMs = Date.now();
+            const intent = await deps.intents.record('commit-release', {
+                artifactId: input.artifactId,
+                releaseId,
+                manifestDigest: prepared.digest,
+                blobKeys: prepared.entries.map((e) => e.key),
+                attemptId,
+                invocationId,
+                operation: 'publish',
+                preparedAtMs: nowMs,
+                cleanupDeadlineMs: nowMs + cleanupWindowMs,
+            });
+            const pinned = [];
+            const pinReason = `preparation:${releaseId}`;
+            let preservePins = false;
+            try {
+                for (const digest of [...new Set(prepared.entries.map((entry) => entry.entry.digest))].sort()) {
+                    await deps.refs.pin(digest, pinReason);
+                    pinned.push(digest);
+                }
+                await deps.coordinator.testObserver?.arrive('before_blob_put', invocationId);
+                for (const { key, bytes } of prepared.entries) {
+                    if ((await deps.intents.get(intent.intentId))?.state !== 'pending') {
+                        throw new Error('preparation abandoned before blob PUT');
+                    }
+                    await deps.blobs.putBlob(key, bytes);
+                }
+                await deps.coordinator.testObserver?.arrive('after_blob_put_before_verify', invocationId);
+                await deps.coordinator.testObserver?.arrive('before_blob_readback', invocationId);
+                await verifyStagedBlobs(deps.blobs, prepared.entries);
+                const addedRefs = [];
+                const source = input.source === undefined ? undefined : parseSourceRef(input.source);
+                let finalizationClient;
+                const request = {
+                    scopeId: input.storageScopeId,
+                    internalKey,
+                    commandHash,
+                    codecVersion,
+                    invocationId,
+                    actorId: input.actorId,
+                    operation: 'publish',
+                    artifactId: input.artifactId,
+                    bindingName: null,
+                    policyRevision: input.policyRevision,
+                    quotaBytes: prepared.entries.reduce((total, entry) => total + entry.bytes.byteLength, 0),
+                    locks: { ...deps.locks, 'artifact-lifecycle': [
+                            async (client) => { finalizationClient = client; },
+                            ...(deps.locks?.['artifact-lifecycle'] ?? []),
+                        ] },
+                    provisional: async (client) => {
+                        const unit = deps.createUnitWriter(client);
+                        await unit.putRelease({
+                            releaseId,
+                            artifactId: input.artifactId,
+                            manifestDigest: prepared.digest,
+                            manifest: prepared.manifest,
+                            state: 'ready',
+                            createdAt: new Date(nowMs).toISOString(),
+                        });
+                        for (const staged of prepared.entries) {
+                            await unit.registerBlob(input.storageScopeId, staged.entry.digest, staged.entry.size);
+                            await unit.addReleaseRef(staged.entry.digest, releaseId);
+                            addedRefs.push(staged.entry.digest);
+                        }
+                        await unit.promoteCurrentLatestWins(input.artifactId, releaseId);
+                        if (source !== undefined)
+                            await unit.putSource(input.artifactId, source);
+                    },
+                    guard: guard(() => {
+                        if (finalizationClient === undefined)
+                            throw new Error('publication guard needs the finalization client');
+                        return finalizationClient;
+                    }),
+                    finishIntents: async (client) => {
+                        await deps.createUnitWriter(client).completeIntent(intent.intentId);
+                    },
+                    noteAbandonedAttempt: deps.noteAbandoned === undefined
+                        ? undefined
+                        : async (attemptId) => {
+                            await deps.noteAbandoned?.(attemptId);
+                        },
+                    attemptId,
+                    receiptData: { releaseId, manifest: prepared.manifest },
+                };
+                preservePins = true;
+                const outcome = await deps.coordinator.finalizePrepared(request);
+                preservePins = !outcome.ok && outcome.failure.commitState === 'unknown';
+                if (!outcome.ok && outcome.failure.commitState === 'not_committed') {
+                    // Best-effort compensation for ref stores outside the unit transaction.
+                    for (const digest of addedRefs) {
+                        try {
+                            await deps.refs.releaseRef(digest, releaseId);
+                        }
+                        catch {
+                            /* already rolled back or never added */
+                        }
+                    }
+                }
+                return outcome;
+            }
+            finally {
+                if (!preservePins) {
+                    for (const digest of pinned) {
+                        try {
+                            await deps.refs.unpin(digest, pinReason);
+                        }
+                        catch (error) {
+                            if (!(error instanceof Error) || !/not pinned/.test(error.message))
+                                throw error;
+                        }
+                    }
+                }
+            }
+        },
+    };
+}