@sentropic/artifacts 0.2.4 → 0.2.6

package/dist/server/failures.d.ts

@@ -4,9 +4,28 @@ export type ArtifactCommitState = 'not_committed' | 'committed' | 'unknown';
 export type ArtifactInternalKey = string & {
     readonly __brand: 'internal-key';
 };
-export type ArtifactErrorKind = 'provider_unavailable' | 'command_conflict' | 'pointer_conflict' | 'unauthorized_at_commit' | 'capability_unselected' | 'admission_unavailable' | 'invalid_request' | 'anonymous' | 'access_denied' | 'not_found' | 'gone' | 'unprocessable' | 'verification_failed';
+export type ArtifactErrorKind = 'provider_unavailable' | 'command_conflict' | 'pointer_conflict' | 'unauthorized_at_commit' | 'capability_unselected' | 'admission_unavailable' | 'invalid_request' | 'anonymous' | 'access_denied' | 'not_found' | 'gone' | 'release_unavailable' | 'limit_exceeded' | 'unprocessable' | 'verification_failed' | 'edit_mismatch' | 'precondition_required';
+/** Optimistic-concurrency payload: the caller re-reads and merges against this. */
+export interface ArtifactConflictDetails {
+    readonly artifactId?: string;
+    readonly expectedCurrentReleaseId?: string | null;
+    readonly currentReleaseId: string | null;
+    readonly currentDigest: string | null;
+    readonly currentSource?: Readonly<Record<string, unknown>>;
+}
+/** Edit-application payload: which path failed the exactly-once rule and how often oldStr occurred. */
+export interface ArtifactEditDetails {
+    readonly path: string;
+    readonly occurrences: number;
+    readonly editIndex?: number;
+    readonly reason?: 'missing' | 'ambiguous' | 'not_text' | 'file_missing';
+}
+export interface ArtifactReleaseUnavailableDetails {
+    readonly reason: 'purged' | 'not_retained' | 'unpublished';
+}
 export type ArtifactFailureCategory = ArtifactFailure['category'];
 interface ArtifactFailureFields {
+    readonly details?: Readonly<Record<string, unknown>>;
     readonly variant?: string;
     readonly httpStatus: number;
     readonly publicCode: string;
@@ -15,6 +34,11 @@ interface ArtifactFailureFields {
     readonly operation: string;
     readonly phase: string;
     readonly commitState: ArtifactCommitState;
+    /** Present on pointer/command conflicts so the caller can re-read and merge. */
+    readonly conflict?: ArtifactConflictDetails;
+    /** Present on edit_mismatch so the caller sees the failing path and occurrence count. */
+    readonly edit?: ArtifactEditDetails;
+    readonly release?: ArtifactReleaseUnavailableDetails;
     /** Original thrown value, retained by identity and deliberately non-enumerable. */
     readonly cause: unknown;
 }
@@ -24,7 +48,7 @@ export interface ArtifactOperationalFailure extends ArtifactFailureFields {
 }
 export interface ArtifactOrdinaryFailure extends Omit<ArtifactFailureFields, 'variant' | 'retriable'> {
     readonly kind: 'ordinary';
-    readonly category: 'invalid_request' | 'not_found' | 'gone' | 'unprocessable' | 'verification_failed';
+    readonly category: 'invalid_request' | 'not_found' | 'gone' | 'release_unavailable' | 'limit_exceeded' | 'unprocessable' | 'verification_failed' | 'edit_mismatch' | 'precondition_required';
     readonly retriable: false;
 }
 /** Entry authority outcomes are separate from ordinary and operational failures. */
@@ -65,10 +89,18 @@ export declare class ArtifactOperationError extends Error {
     readonly details: {
         readonly cause?: unknown;
         readonly refusal?: ArtifactPublicRefusal;
+        readonly publicDetails?: Readonly<Record<string, unknown>>;
+        readonly conflict?: ArtifactConflictDetails;
+        readonly edit?: ArtifactEditDetails;
+        readonly release?: ArtifactReleaseUnavailableDetails;
     };
     constructor(kind: ArtifactErrorKind, details?: {
         readonly cause?: unknown;
         readonly refusal?: ArtifactPublicRefusal;
+        readonly publicDetails?: Readonly<Record<string, unknown>>;
+        readonly conflict?: ArtifactConflictDetails;
+        readonly edit?: ArtifactEditDetails;
+        readonly release?: ArtifactReleaseUnavailableDetails;
     });
 }
 /** Mint only at verified per-key row contention, using the full scoped operation key. */

package/dist/server/failures.js

@@ -28,7 +28,8 @@ const UNAVAILABLE_CODES = new Set([
 const TIMEOUT_NAMES = new Set(['TimeoutError', 'RequestTimeout', 'RequestTimeoutError']);
 const DOMAIN_STATUS = {
     invalid_request: 400, anonymous: 401, access_denied: 403,
-    not_found: 404, gone: 410, unprocessable: 422, verification_failed: 422,
+    not_found: 404, gone: 410, release_unavailable: 410, limit_exceeded: 413, unprocessable: 422, verification_failed: 422, edit_mismatch: 422,
+    precondition_required: 428,
 };
 function field(value, name) {
     if (typeof value !== 'object' || value === null)
@@ -64,7 +65,10 @@ function operationProjection(error) {
         case 'provider_unavailable':
         case 'admission_unavailable': return unavailable(kind);
         case 'command_conflict':
-        case 'pointer_conflict': return conflict(kind);
+        case 'pointer_conflict': {
+            const base = conflict(kind);
+            return error.details.conflict === undefined ? base : { ...base, conflict: error.details.conflict };
+        }
         case 'capability_unselected': return {
             kind: 'operational', category: kind, variant: 'unselected_operation',
             httpStatus: 503, publicCode: 'capability_unavailable', retriable: false,
@@ -86,7 +90,14 @@ function operationProjection(error) {
         case 'anonymous':
         case 'access_denied':
             return { kind: 'admission', category: kind, httpStatus: DOMAIN_STATUS[kind], publicCode: kind, retriable: false };
-        default: return { kind: 'ordinary', category: kind, httpStatus: DOMAIN_STATUS[kind], publicCode: kind, retriable: false };
+        default: {
+            const base = { kind: 'ordinary', category: kind, httpStatus: DOMAIN_STATUS[kind], publicCode: kind, retriable: false };
+            if (kind === 'precondition_required')
+                return { ...base, details: error.details.publicDetails };
+            if (kind === 'release_unavailable' && error.details.release !== undefined)
+                return { ...base, release: error.details.release };
+            return kind === 'edit_mismatch' && error.details.edit !== undefined ? { ...base, edit: error.details.edit } : base;
+        }
     }
 }
 function classify(cause, context, mapHostError) {
@@ -126,6 +137,9 @@ export function classifyArtifactFailure(cause, context, mapHostError) {
         projection = unavailable();
     const failure = {
         ...projection, invocationId: context.invocationId, operation: context.operation,
+        ...(cause instanceof ArtifactOperationError && cause.details.publicDetails &&
+            ['confirmation_required', 'confirmation_invalid', 'confirmation_expired', 'confirmation_stale', 'release_unavailable'].includes(projection.publicCode)
+            ? { details: cause.details.publicDetails } : {}),
         phase: context.phase, commitState: context.commitState, cause,
     };
     Object.defineProperty(failure, 'cause', { value: cause, enumerable: false });

package/dist/server/lifecycle.d.ts

@@ -12,6 +12,8 @@ export type ArtifactState = 'active' | 'withdrawn' | 'deleted' | 'purged';
 /** Release states use `ready` (not `active`) to match the releases table. */
 export type ReleaseState = 'ready' | 'retired' | 'purged';
 export interface LifecycleStore {
+    isTerminal(artifactId: string): Promise<boolean>;
+    markTerminal(artifactId: string): Promise<void>;
     register(artifactId: string, ownerId: string): Promise<void>;
     getOwner(artifactId: string): Promise<string | undefined>;
     getArtifactState(artifactId: string): Promise<ArtifactState>;
@@ -53,6 +55,8 @@ export interface LifecycleService {
     listReleases(artifactId: string): Promise<string[]>;
     /** Track a published release so promotion sees it (idempotent). */
     trackRelease(artifactId: string, releaseId: string): Promise<void>;
+    /** Per-release lifecycle state (ready/retired/purged; ready when untracked). */
+    getReleaseState(releaseId: string): Promise<ReleaseState>;
 }
 /** Create a lifecycle service over an injected store (mutations owner-only). */
 export declare function createLifecycleService(store: LifecycleStore, clock?: () => string, current?: CurrentPointer, claims?: DeletionClaimStore): LifecycleService;

package/dist/server/lifecycle.js

@@ -16,6 +16,14 @@ export function createMemoryLifecycleStore() {
     const artifacts = new Map();
     const releaseStates = new Map();
     const store = {
+        async isTerminal(id) { return artifacts.get(id)?.terminal === true; },
+        async markTerminal(id) {
+            const entry = artifacts.get(id);
+            if (!entry)
+                throw new Error('unknown artifact');
+            entry.terminal = true;
+            entry.state = 'deleted';
+        },
         async register(artifactId, ownerId) {
             const entry = artifacts.get(artifactId);
             if (entry !== undefined) {
@@ -35,6 +43,8 @@ export function createMemoryLifecycleStore() {
             const entry = artifacts.get(artifactId);
             if (entry === undefined)
                 throw new Error(`unknown artifact: ${artifactId}`);
+            if (entry.terminal && state !== 'deleted' && state !== 'purged')
+                throw new Error('terminal artifact');
             entry.state = state;
         },
         async getRenewedAt(artifactId) {
@@ -88,6 +98,9 @@ export function createLifecycleService(store, clock = () => new Date().toISOStri
         async stateOf(artifactId) {
             return store.getArtifactState(artifactId);
         },
+        async getReleaseState(releaseId) {
+            return store.getReleaseState(releaseId);
+        },
         canRead(artifact, acl, actorId, action = 'read', isApproved = () => false) {
             if (artifact.state === 'deleted' || artifact.state === 'purged')
                 return false;
@@ -108,6 +121,8 @@ export function createLifecycleService(store, clock = () => new Date().toISOStri
         },
         async restore(artifactId, actorId) {
             await assertOwner(artifactId, actorId);
+            if (await store.isTerminal(artifactId))
+                throw new Error('cannot restore terminal artifact');
             const state = await store.getArtifactState(artifactId);
             if (state === 'purged')
                 throw new Error(`cannot restore purged artifact: terminal ${artifactId}`);

package/dist/server/management.d.ts

@@ -0,0 +1,46 @@
+import type { ArtifactAcl } from './access.js';
+import type { ArtifactInvocationContext, ArtifactCommitCoordinator, FinalizeTxClient } from './commit/types.js';
+import type { EffectiveArtifactCommand } from './command-identity.js';
+import { ArtifactOperationError, type ArtifactOutcome } from './failures.js';
+export interface ManagementTarget {
+    acl: ArtifactAcl;
+    state: string;
+    terminal: boolean;
+    currentReleaseId: string | null;
+}
+export interface ManagementUnit {
+    lock(artifactId: string): Promise<void>;
+    read(artifactId: string): Promise<ManagementTarget | undefined>;
+    setAccess(artifactId: string, principalId: string, action: 'grant' | 'revoke', updatedAt: string): Promise<{
+        grants: unknown;
+        updatedAt: string | null;
+    }>;
+    delete(artifactId: string, deletedAt: string): Promise<void>;
+}
+export interface DeleteConfirmationContext {
+    actorId: string;
+    storageScopeId: string;
+    artifactId: string;
+    expectedCurrentReleaseId: string | null;
+    commandHash: string;
+    internalKey: string;
+}
+/** Host challenges require trusted human approval; consume on the domain transaction. */
+export interface ArtifactConfirmationPort {
+    request(context: DeleteConfirmationContext): Promise<{
+        confirmationRef: string;
+        managementUrl: string;
+        expiresAt: string;
+    }>;
+    consume(client: FinalizeTxClient, context: DeleteConfirmationContext, confirmationRef: string): Promise<'valid' | 'invalid' | 'expired' | 'stale'>;
+}
+export declare function confirmationFailure(code: string, details?: Record<string, unknown>): ArtifactOperationError;
+/** Targeted writes and proof consumption share the existing coordinator receipt transaction. */
+export declare function manageArtifact(deps: {
+    coordinator: ArtifactCommitCoordinator;
+    createUnit(client: FinalizeTxClient): ManagementUnit;
+    readPolicyRevision(): Promise<string>;
+    isApprovedPrincipal(principalId: string): boolean | Promise<boolean>;
+    confirmation?: ArtifactConfirmationPort;
+    validateNewCommand?(): void;
+}, invocation: ArtifactInvocationContext, command: EffectiveArtifactCommand, proof?: string): Promise<ArtifactOutcome<unknown>>;

package/dist/server/management.js

@@ -0,0 +1,86 @@
+import { ArtifactOperationError } from './failures.js';
+export function confirmationFailure(code, details) {
+    return new ArtifactOperationError('unauthorized_at_commit', { publicDetails: details,
+        refusal: { allowed: false, reason: 'denied', publicCode: code,
+            status: code === 'confirmation_invalid' ? 403 : 409, retriable: false } });
+}
+function refused(code) {
+    return new ArtifactOperationError('unauthorized_at_commit', { refusal: { allowed: false,
+            reason: 'denied', status: code === 'gone' ? 410 : code === 'not_found' ? 404 : 403,
+            publicCode: code, retriable: false } });
+}
+/** Targeted writes and proof consumption share the existing coordinator receipt transaction. */
+export async function manageArtifact(deps, invocation, command, proof) {
+    const artifactId = command.payload.artifactId;
+    const deleting = command.operation === 'delete';
+    let unit;
+    const receipt = {};
+    const context = { actorId: invocation.actorId, storageScopeId: invocation.storageScopeId,
+        artifactId, expectedCurrentReleaseId: command.payload.expectedCurrentReleaseId,
+        commandHash: command.identity.commandHash, internalKey: command.identity.internalKey };
+    const owned = async () => {
+        const target = await unit.read(artifactId);
+        if (!target || target.acl.storageScopeId !== invocation.storageScopeId)
+            throw refused('not_found');
+        if (target.acl.ownerId !== invocation.actorId)
+            throw refused('access_denied');
+        return target;
+    };
+    const request = {
+        ...command.identity, scopeId: invocation.storageScopeId, actorId: invocation.actorId,
+        invocationId: invocation.invocationId, operation: command.operation, artifactId,
+        policyRevision: await deps.readPolicyRevision(), receiptData: receipt,
+        locks: { 'artifact-lifecycle': [async (client) => {
+                    unit = deps.createUnit(client);
+                    await unit.lock(artifactId);
+                    await owned();
+                }] },
+        provisional: async (client) => {
+            const target = await owned();
+            if (target.terminal || target.state === 'deleted' || target.state === 'purged')
+                throw refused('gone');
+            const now = new Date().toISOString();
+            if (deleting) {
+                // Bind omitted v1 input to the locked confirmation context, without rewriting the command.
+                if (!Object.hasOwn(command.payload, 'expectedCurrentReleaseId'))
+                    context.expectedCurrentReleaseId = target.currentReleaseId;
+                if (target.currentReleaseId !== context.expectedCurrentReleaseId) {
+                    if (proof)
+                        throw confirmationFailure('confirmation_stale');
+                    throw new ArtifactOperationError('pointer_conflict');
+                }
+                if (!deps.confirmation)
+                    throw new ArtifactOperationError('provider_unavailable');
+                if (!proof)
+                    throw confirmationFailure('confirmation_required', await deps.confirmation.request(context));
+                const verdict = await deps.confirmation.consume(client, context, proof);
+                if (verdict !== 'valid')
+                    throw confirmationFailure(`confirmation_${verdict}`);
+                await unit.delete(artifactId, now);
+                Object.assign(receipt, { artifactId, state: 'deleted', terminal: true, deletedAt: now, purgeState: 'pending' });
+            }
+            else {
+                const principalId = command.payload.principalId;
+                if (command.payload.action === 'grant' && !await deps.isApprovedPrincipal(principalId))
+                    throw refused('access_denied');
+                const output = await unit.setAccess(artifactId, principalId, command.payload.action, now);
+                Object.assign(receipt, { artifactId, isPublic: false, ...output });
+            }
+        },
+        guard: async (ctx, tx) => {
+            const target = await owned();
+            if (!deleting && (target.terminal || target.state === 'deleted' || target.state === 'purged'))
+                throw refused('gone');
+            if (!deleting && command.payload.action === 'grant' && !await deps.isApprovedPrincipal(command.payload.principalId))
+                throw refused('access_denied');
+            return invocation.authorizeCommit(ctx, tx);
+        },
+        validateReplayReceipt: (stored) => stored.receipt?.artifactId === artifactId,
+    };
+    const replay = await deps.coordinator.findReplayPrepared(request);
+    if (replay === undefined)
+        deps.validateNewCommand?.();
+    const result = replay ?? await deps.coordinator.finalizePrepared(request);
+    return result.ok ? { ...result, result: result.result.receipt }
+        : { ok: false, failure: { ...result.failure, kind: 'operational' } };
+}

package/dist/server/outcome-projection.d.ts

@@ -2,9 +2,9 @@
 import type { AppToolResult } from '@sentropic/mcp-platform';
 import type { HttpResponse } from '../http.js';
 import type { ArtifactFailure, ArtifactOutcome } from './failures.js';
-export declare function projectArtifactHttpOutcome(outcome: ArtifactOutcome<HttpResponse>): HttpResponse;
+export declare function projectArtifactHttpOutcome(outcome: ArtifactOutcome<HttpResponse>, complete?: boolean): HttpResponse;
 /** Feed this application result to mcp-platform's existing result codec. No second wire protocol. */
-export declare function projectArtifactMcpOutcome(outcome: ArtifactOutcome<HttpResponse>, auditId: string): AppToolResult;
+export declare function projectArtifactMcpOutcome(outcome: ArtifactOutcome<HttpResponse>, auditId: string, resultEnvelopeVersion?: 1 | 2): AppToolResult;
 export interface ArtifactWriteFailure {
     readonly invocationId: string;
     readonly operation: string;

package/dist/server/outcome-projection.js

@@ -1,16 +1,34 @@
-export function projectArtifactHttpOutcome(outcome) {
+import { PRECONDITION_REQUIRED_MESSAGE } from '../profile/contracts.js';
+export function projectArtifactHttpOutcome(outcome, complete = false) {
+    if (complete) {
+        const { auditId: _audit, redactionClass: _redaction, ...body } = projectArtifactMcpOutcome(outcome, '');
+        return { status: outcome.ok ? outcome.result.status : outcome.failure.httpStatus, body };
+    }
     if (outcome.ok)
         return outcome.result;
-    return { status: outcome.failure.httpStatus, body: { error: outcome.failure.publicCode } };
+    const { failure } = outcome;
+    return { status: failure.httpStatus, body: { error: failure.publicCode,
+            ...(failure.publicCode === 'precondition_required' ? { message: PRECONDITION_REQUIRED_MESSAGE, retryable: false } : {}),
+            ...(failure.details ? { details: failure.details } : {}),
+            ...(failure.conflict !== undefined ? { conflict: failure.conflict } : {}),
+            ...(failure.release !== undefined ? { details: failure.release } : {}),
+            ...(failure.edit !== undefined ? { edit: failure.edit } : {}) } };
 }
 /** Feed this application result to mcp-platform's existing result codec. No second wire protocol. */
-export function projectArtifactMcpOutcome(outcome, auditId) {
+export function projectArtifactMcpOutcome(outcome, auditId, resultEnvelopeVersion = 2) {
     if (outcome.ok)
-        return { ok: true, output: outcome.result.body, auditId, redactionClass: 'low' };
-    const { publicCode, retriable } = outcome.failure;
+        return { ok: true, output: outcome.result.body, auditId, redactionClass: 'low',
+            ...(resultEnvelopeVersion === 2 ? { invocationId: outcome.invocationId,
+                commitState: outcome.commitState, replayed: outcome.replayed } : {}) };
+    const { publicCode, retriable, conflict, edit, release, invocationId, commitState } = outcome.failure;
+    const variant = 'variant' in outcome.failure ? outcome.failure.variant : undefined;
+    const details = conflict !== undefined ? { variant: 'pointer_conflict', ...conflict }
+        : edit !== undefined ? { ...edit } : release !== undefined ? { ...release }
+            : outcome.failure.details ?? (variant !== undefined ? { variant } : undefined);
     return {
-        ok: false, auditId, redactionClass: 'low',
-        error: { code: publicCode, message: publicCode, retriable },
+        ok: false, auditId, redactionClass: 'low', ...(resultEnvelopeVersion === 2 ? { invocationId, commitState } : {}),
+        error: { code: publicCode, message: publicCode === 'precondition_required' ? PRECONDITION_REQUIRED_MESSAGE : publicCode,
+            retriable, ...(details === undefined ? {} : { details }) },
     };
 }
 /**

package/dist/server/publication.d.ts

@@ -3,23 +3,28 @@ 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 { ArtifactAcl, ArtifactMetadata } from './access.js';
+import type { ArtifactState, ReleaseState } from './lifecycle.js';
 import { type RefcountStore } from './gc.js';
 import type { CommandIdentity } from './command-identity.js';
 import type { AuthorizeCommit, CommitLockFn, ArtifactCommitCoordinator, FinalizeResult, FinalizeTxClient } from './commit/types.js';
 export { DEFAULT_PUBLICATION_LIMITS, type PublicationLimits } from './publication-limits.js';
 export interface ReleaseRecord {
+    authorPrincipalId?: string | null;
+    parentReleaseId?: string | null;
+    revertedFromReleaseId?: string | null;
     releaseId: string;
     artifactId: string;
     manifestDigest: string;
     manifest: string;
-    state: 'ready';
+    state: ReleaseState;
     createdAt: string;
 }
 export interface PublicationStateStore {
     putRelease(release: ReleaseRecord): Promise<void>;
     getRelease(releaseId: string): Promise<ReleaseRecord | undefined>;
+    /** Full release history of one artifact, oldest first (creation order, then id). */
+    listReleases(artifactId: string): Promise<ReleaseRecord[]>;
     getCurrentReleaseId(artifactId: string): Promise<string | undefined>;
     compareAndSwapCurrent(artifactId: string, expected: string | null, next: string): Promise<boolean>;
 }
@@ -61,14 +66,10 @@ export interface PublicationService {
     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;
-    } | undefined>;
-    getRelease(releaseId: string): Promise<{
-        releaseId: string;
-        manifest: string;
-    } | undefined>;
+    getCurrent(artifactId: string): Promise<ReleaseRecord | undefined>;
+    getRelease(releaseId: string): Promise<ReleaseRecord | undefined>;
+    /** Release history records (digest, manifest, createdAt) for list_versions. */
+    listReleases(artifactId: string): Promise<ReleaseRecord[]>;
 }
 /** Create a publication service over injected stores (no driver imports). */
 export declare function createPublicationService(deps: {
@@ -109,6 +110,12 @@ export declare function decidePublishAuthorization(input: PublishAuthorizationIn
 };
 /** Transaction-scoped provisional writers for the finalized unit. */
 export interface PublicationUnitWriter {
+    /** Lock the artifact row, including when no pointer exists, then read the current release. */
+    lockCurrent(artifactId: string): Promise<{
+        currentReleaseId: string | null;
+        currentDigest: string | null;
+    }>;
+    updateMetadata(artifactId: string, metadata: ArtifactMetadata): Promise<ArtifactMetadata>;
     readAuthorization(artifactId: string): Promise<{
         state: ArtifactState;
         acl: ArtifactAcl | undefined;
@@ -123,6 +130,9 @@ export interface PublicationUnitWriter {
 /** PostgreSQL unit writer over the coordinator's leased client. */
 export declare function createPostgresPublicationUnitWriter(client: FinalizeTxClient): PublicationUnitWriter;
 export interface GuardedPublishInput extends PublishInput {
+    readonly expectedCurrentReleaseId?: string | null;
+    readonly metadata?: ArtifactMetadata;
+    readonly operation?: 'publish' | 'revert';
     /** Frozen trusted identity supplied by the host's L1 command normalizer. */
     readonly identity: CommandIdentity;
     readonly actorId: string;
@@ -147,6 +157,7 @@ export interface GuardedPublicationDeps {
     readonly limits?: Partial<PublicationLimits>;
 }
 export interface GuardedPublicationService {
+    replayFinalized(input: Omit<GuardedPublishInput, 'files' | 'source' | 'profile'>): Promise<FinalizeResult | undefined>;
     publishFinalized(input: GuardedPublishInput): Promise<FinalizeResult>;
 }
 /** Create a publication service whose commits finalize through L3 ports. */

package/dist/server/publication.js

@@ -16,6 +16,7 @@ import { assertBlobPrefix } from './blob-prefix.js';
 import { canonicalManifest, manifestDigest } from '../codecs.js';
 import { parseSourceRef } from './sources.js';
 import { publicationLimits, validatePublicationFiles } from './publication-limits.js';
+import { ArtifactOperationError } from './failures.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. */
@@ -37,6 +38,12 @@ export function createMemoryStateStore() {
         getRelease(releaseId) {
             return Promise.resolve(releases.get(releaseId));
         },
+        listReleases(artifactId) {
+            // Stable sort: createdAt ties keep insertion (creation) order.
+            return Promise.resolve([...releases.values()]
+                .filter((release) => release.artifactId === artifactId)
+                .sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0)));
+        },
         getCurrentReleaseId(artifactId) {
             return Promise.resolve(current.get(artifactId));
         },
@@ -168,13 +175,16 @@ export function createPublicationService(deps) {
             const release = await deps.state.getRelease(releaseId);
             if (release === undefined)
                 return undefined;
-            return { releaseId: release.releaseId, manifest: release.manifest };
+            return release;
         },
         async getRelease(releaseId) {
             const release = await deps.state.getRelease(releaseId);
             if (release === undefined)
                 return undefined;
-            return { releaseId: release.releaseId, manifest: release.manifest };
+            return release;
+        },
+        async listReleases(artifactId) {
+            return deps.state.listReleases(artifactId);
         },
     };
 }
@@ -199,6 +209,17 @@ export function decidePublishAuthorization(input) {
 /** PostgreSQL unit writer over the coordinator's leased client. */
 export function createPostgresPublicationUnitWriter(client) {
     return {
+        async lockCurrent(artifactId) {
+            await client.query('SELECT id FROM artifacts.artifacts WHERE id = $1 FOR UPDATE', [artifactId]);
+            const { rows } = await client.query(`SELECT c.release_id, r.manifest_digest FROM artifacts.artifact_current c
+         JOIN artifacts.releases r ON r.id = c.release_id WHERE c.artifact_id = $1`, [artifactId]);
+            return { currentReleaseId: rows[0]?.release_id ?? null, currentDigest: rows[0]?.manifest_digest ?? null };
+        },
+        async updateMetadata(artifactId, metadata) {
+            const { rows } = await client.query(`UPDATE artifacts.artifacts SET metadata = COALESCE(metadata, '{}'::jsonb) || $2::jsonb
+         WHERE id = $1 RETURNING metadata`, [artifactId, JSON.stringify(metadata)]);
+            return rows[0]?.metadata ?? {};
+        },
         async readAuthorization(artifactId) {
             const { rows } = await client.query('SELECT lifecycle_state, owner_id FROM artifacts.artifacts WHERE id = $1', [artifactId]);
             const row = rows[0];
@@ -213,8 +234,10 @@ export function createPostgresPublicationUnitWriter(client) {
                 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]);
+            await client.query(`INSERT INTO artifacts.releases (id, artifact_id, manifest_digest, manifest, state, created_at,
+          author_principal_id, parent_release_id, reverted_from_release_id)
+         VALUES ($1, $2, $3, $4, 'ready', $5, $6, $7, $8)`, [release.releaseId, release.artifactId, release.manifestDigest, release.manifest, release.createdAt,
+                release.authorPrincipalId ?? null, release.parentReleaseId ?? null, release.revertedFromReleaseId ?? null]);
         },
         async registerBlob(storageScopeId, digest, size) {
             await client.query(`INSERT INTO artifacts.blobs (storage_scope_id, digest, size)
@@ -280,6 +303,16 @@ export function createGuardedPublicationService(deps) {
         return { allowed: true, fence: transaction.participant.mintFence(revision, context.invocationId) };
     };
     return {
+        async replayFinalized(input) {
+            let client;
+            return deps.coordinator.findReplayPrepared({ ...input.identity,
+                scopeId: input.storageScopeId, invocationId: input.invocationId, actorId: input.actorId,
+                artifactId: input.artifactId, operation: input.operation ?? 'publish', policyRevision: input.policyRevision,
+                receiptData: null, locks: { ...deps.locks, 'artifact-lifecycle': [
+                        async (tx) => { client = tx; await deps.createUnitWriter(tx).lockCurrent(input.artifactId); },
+                        ...(deps.locks?.['artifact-lifecycle'] ?? []),
+                    ] }, guard: guard(() => client, input.authorizeCommit), });
+        },
         async publishFinalized(input) {
             validatePublicationFiles(input.files, limits);
             const prepared = preparePublication(input);
@@ -321,6 +354,10 @@ export function createGuardedPublicationService(deps) {
                 const addedRefs = [];
                 const source = input.source === undefined ? undefined : parseSourceRef(input.source);
                 let finalizationClient;
+                let current;
+                const revertedFromReleaseId = input.operation === 'revert' && source?.kind === 'base-commit' ? source.commit : null;
+                const receiptData = { releaseId, manifest: prepared.manifest, metadata: {},
+                    previousReleaseId: null, updatedAt: new Date(nowMs).toISOString(), revertedFromReleaseId };
                 const request = {
                     scopeId: input.storageScopeId,
                     internalKey,
@@ -328,18 +365,29 @@ export function createGuardedPublicationService(deps) {
                     codecVersion,
                     invocationId,
                     actorId: input.actorId,
-                    operation: 'publish',
+                    operation: input.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; },
+                            async (client) => {
+                                finalizationClient = client;
+                                current = await deps.createUnitWriter(client).lockCurrent(input.artifactId);
+                            },
                             ...(deps.locks?.['artifact-lifecycle'] ?? []),
                         ] },
+                    assertPrecondition: () => {
+                        if (input.expectedCurrentReleaseId !== undefined && current.currentReleaseId !== input.expectedCurrentReleaseId) {
+                            throw new ArtifactOperationError('pointer_conflict', { conflict: { ...current,
+                                    artifactId: input.artifactId, expectedCurrentReleaseId: input.expectedCurrentReleaseId } });
+                        }
+                    },
                     provisional: async (client) => {
                         const unit = deps.createUnitWriter(client);
+                        receiptData.previousReleaseId = current.currentReleaseId;
                         await unit.putRelease({
+                            authorPrincipalId: input.actorId, parentReleaseId: current.currentReleaseId, revertedFromReleaseId,
                             releaseId,
                             artifactId: input.artifactId,
                             manifestDigest: prepared.digest,
@@ -353,6 +401,7 @@ export function createGuardedPublicationService(deps) {
                             addedRefs.push(staged.entry.digest);
                         }
                         await unit.promoteCurrentLatestWins(input.artifactId, releaseId);
+                        receiptData.metadata = await unit.updateMetadata(input.artifactId, input.metadata ?? {});
                         if (source !== undefined)
                             await unit.putSource(input.artifactId, source);
                     },
@@ -370,7 +419,7 @@ export function createGuardedPublicationService(deps) {
                             await deps.noteAbandoned?.(attemptId);
                         },
                     attemptId,
-                    receiptData: { releaseId, manifest: prepared.manifest },
+                    receiptData,
                 };
                 preservePins = true;
                 const outcome = await deps.coordinator.finalizePrepared(request);

package/dist/server/result-schema.d.ts

@@ -0,0 +1,14 @@
+export declare const ARTIFACT_RESULT_SCHEMA: {
+    readonly type: "object";
+    readonly oneOf: readonly [{
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    }, {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    }];
+};