@sentropic/artifacts 0.2.5 → 0.2.6

package/dist/server/failures.d.ts

@@ -4,7 +4,25 @@ 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' | 'release_unavailable' | 'limit_exceeded' | '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>>;
@@ -16,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;
 }
@@ -25,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' | 'release_unavailable' | 'limit_exceeded' | '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. */
@@ -67,11 +90,17 @@ export declare class ArtifactOperationError extends Error {
         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, release_unavailable: 410, limit_exceeded: 413, 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) {

package/dist/server/lifecycle.d.ts

@@ -55,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

@@ -98,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;

package/dist/server/management.d.ts

@@ -42,4 +42,5 @@ export declare function manageArtifact(deps: {
     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

@@ -26,7 +26,7 @@ export async function manageArtifact(deps, invocation, command, proof) {
             throw refused('access_denied');
         return target;
     };
-    const result = await deps.coordinator.finalizePrepared({
+    const request = {
         ...command.identity, scopeId: invocation.storageScopeId, actorId: invocation.actorId,
         invocationId: invocation.invocationId, operation: command.operation, artifactId,
         policyRevision: await deps.readPolicyRevision(), receiptData: receipt,
@@ -41,6 +41,9 @@ export async function manageArtifact(deps, invocation, command, proof) {
                 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');
@@ -73,7 +76,11 @@ export async function manageArtifact(deps, invocation, command, proof) {
             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,18 +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,
-            ...(outcome.failure.details ? { details: outcome.failure.details } : {}) } };
+    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,
-            ...(outcome.failure.details ? { details: outcome.failure.details } : {}) },
+        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,13 +3,16 @@ 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 { 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;
@@ -20,6 +23,8 @@ export interface ReleaseRecord {
 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>;
 }
@@ -63,6 +68,8 @@ export interface PublicationService {
     publish(input: PublishInput, sources?: SourceStore): Promise<PublishResult>;
     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: {
@@ -103,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;
@@ -117,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;
@@ -141,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));
         },
@@ -176,6 +183,9 @@ export function createPublicationService(deps) {
                 return undefined;
             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;
+    }];
+};

package/dist/server/result-schema.js

@@ -0,0 +1,35 @@
+/** Published domain-result envelope; error details are selected by code and variant. */
+const string = { type: 'string' };
+const nullable = { type: ['string', 'null'] };
+const object = (properties, required = Object.keys(properties)) => ({
+    type: 'object', properties, required, additionalProperties: false,
+});
+const error = (code, details) => object({
+    code: { enum: [code] }, message: string, retriable: { type: 'boolean' }, details,
+});
+const pointer = object({ variant: { enum: ['pointer_conflict'] }, artifactId: string,
+    expectedCurrentReleaseId: nullable, currentReleaseId: nullable, currentDigest: nullable,
+    currentSource: object({ artifactId: string, releaseId: string, digest: nullable,
+        manifest: string, files: { type: 'array', items: { type: 'object' } }, sourceRef: { type: ['object', 'null'] },
+        stableUrl: string, pinnedUrl: string }, ['artifactId', 'releaseId', 'digest', 'manifest', 'files', 'sourceRef']),
+}, ['variant', 'artifactId', 'expectedCurrentReleaseId', 'currentReleaseId', 'currentDigest']);
+const common = { invocationId: string,
+    commitState: { enum: ['not_committed', 'committed', 'unknown'] } };
+export const ARTIFACT_RESULT_SCHEMA = {
+    type: 'object',
+    oneOf: [
+        object({ ok: { enum: [true] }, ...common, replayed: { type: 'boolean' }, output: { type: 'object' } }),
+        object({ ok: { enum: [false] }, ...common, error: { oneOf: [
+                    error('conflict', { oneOf: [pointer, object({ variant: { enum: ['command_conflict', 'key_contention', 'quota_exhausted'] } })] }),
+                    error('edit_mismatch', object({ path: string, editIndex: { type: 'integer', minimum: 0 },
+                        reason: { enum: ['missing', 'ambiguous', 'not_text', 'file_missing'] }, occurrences: { type: 'integer' } })),
+                    error('release_unavailable', object({ reason: { enum: ['purged', 'not_retained', 'unpublished'] } })),
+                    error('precondition_required', object({ profileRevisionId: string, resultEnvelopeVersion: { enum: [1, 2] },
+                        requiredField: { enum: ['expectedCurrentReleaseId'] }, readTools: { type: 'array', items: string } })),
+                    error('confirmation_required', object({ confirmationRef: string, managementUrl: string, expiresAt: string })),
+                    object({ code: { type: 'string', not: { enum: ['conflict', 'edit_mismatch', 'release_unavailable',
+                                    'precondition_required', 'confirmation_required'] } },
+                        message: string, retriable: { type: 'boolean' }, details: object({ variant: string }) }, ['code', 'message', 'retriable']),
+                ] } }),
+    ],
+};

package/dist/server/service.d.ts

@@ -3,6 +3,7 @@ import { type CompiledArtifactsProfile } from '../profile/index.js';
 import { type ArtifactKeyDerivationBinding } from './command-identity.js';
 import type { ArtifactInvocationContext, ArtifactCommitCoordinator, FinalizeTxClient, InternalIdempotencyKey } from './commit/types.js';
 import type { ArtifactOutcome } from './failures.js';
+import type { ArtifactMetadata } from './access.js';
 export interface EnsurePrivateViewInput {
     actorUserId: string;
     ownerId: string;
@@ -48,6 +49,7 @@ export interface GuardedEnsureResult {
 }
 /** Binding identity resolved inside the finalization unit. */
 export interface EnsureBindingInput {
+    readonly metadata?: ArtifactMetadata;
     readonly ownerId: string;
     readonly storageScopeId: string;
     readonly bindingName: string;

package/dist/server/service.js

@@ -88,7 +88,9 @@ const ensureResult = (receipt, replayed, invocationId) => ({
 });
 export function createGuardedEnsureService(deps) {
     const finalizeRequest = (invocation, command, policyRevision) => {
+        const metadata = Object.fromEntries(['title', 'description', 'icon'].filter(key => Object.hasOwn(command.payload, key)).map(key => [key, command.payload[key]]));
         const binding = {
+            ...(Object.keys(metadata).length ? { metadata } : {}),
             ownerId: invocation.actorId,
             storageScopeId: invocation.storageScopeId,
             bindingName: command.payload.bindingName,

package/dist/server/summary.d.ts

@@ -20,9 +20,7 @@ export declare function artifactSummary(input: {
         write: boolean;
         manage: boolean;
     };
-    icon?: string | null | undefined;
-    description?: string | undefined;
-    title?: string | undefined;
+    metadata?: import("./access.js").ArtifactMetadata | undefined;
     artifactId: string;
     bindingName: string | null;
     ownerId: string;
@@ -36,4 +34,7 @@ export declare function artifactSummary(input: {
     digest: string | null;
     stableUrl: string | null;
     pinnedUrl: string | null;
+    title: string;
+    description: string;
+    icon: string | null;
 };

package/dist/server/summary.js

@@ -9,9 +9,10 @@ export function artifactSummary(input) {
         createdAt: acl.createdAt ?? null, updatedAt: acl.updatedAt ?? null,
         currentReleaseId: current?.releaseId ?? null, digest: current ? parseManifest(current.manifest).digest ?? null : null,
         stableUrl: urls?.stableUrl ?? null, pinnedUrl: current ? urls?.pinnedUrl ?? null : null,
-        ...(acl.title === undefined ? {} : { title: acl.title }),
-        ...(acl.description === undefined ? {} : { description: acl.description }),
-        ...(acl.icon === undefined ? {} : { icon: acl.icon }),
+        title: acl.metadata?.title ?? acl.title ?? acl.bindingName ?? artifactId,
+        description: acl.metadata?.description ?? acl.description ?? '',
+        icon: acl.metadata?.icon !== undefined ? acl.metadata.icon : acl.icon ?? null,
+        ...(acl.metadata === undefined ? {} : { metadata: acl.metadata }),
         permissions: { read: evaluateAccess(acl, actorId, 'read', input.approved),
             source: evaluateAccess(acl, actorId, 'source', input.approved), write: owner, manage: owner } };
 }

package/dist/server/templates.js

@@ -44,11 +44,32 @@ const GUIDE_V1 = [
     'Publish and share static web pages through the `artifacts_*` tools:',
     '',
     '- `artifacts_get_template` / `artifacts_get_api_guide`: start here.',
-    '- `artifacts_ensure`: resolve (or create) your private artifact view.',
-    '- `artifacts_publish`: publish inline files as a new release.',
+    '- `artifacts_ensure`: resolve (or create) your private artifact view;',
+    '  optional `title`, `description` and `icon` (one short word) describe it.',
+    '- `artifacts_publish`: publish inline `files` as a new release, or apply',
+    '  small `edits` (`[{path, oldStr, newStr}]`) to the current release\'s',
+    '  text files — `oldStr` must occur exactly once per file, otherwise the',
+    '  call fails with `edit_mismatch` and changes nothing. Both accept',
+    '  optional metadata and `expectedCurrentReleaseId`: when set and not the',
+    '  current release, the call fails with a `conflict` error carrying the',
+    '  current release id and digest so you can re-read and merge.',
+    '  Strict profiles require this field on publish and revert; null means unpublished.',
+    '  Edits target that observed release, with at most 100 ordered substitutions.',
+    '  Reuse the exact idempotency key after a lost response, including commitState unknown.',
+    '  Replays precede edits and CAS; changing metadata, edits or the precondition under',
+    '  the same key returns conflict with variant command_conflict.',
+    '  MCP returns the complete artifacts-outcome/v2 JSON envelope: ok, invocationId,',
+    '  commitState, replayed/output on success, or typed error details on failure.',
     '- `artifacts_create_upload` + bounded HTTP append +',
     '  `artifacts_commit_upload`: stage large bytes, then commit them.',
-    '- `artifacts_list` / `artifacts_get` / `artifacts_get_source`: discover.',
+    '- `artifacts_list` / `artifacts_get`: discover (metadata included).',
+    '- `artifacts_list_versions`: full release history of one artifact —',
+    '  per release: id, created at, author, state, whether it is current,',
+    '  and a content digest.',
+    '- `artifacts_get_source`: current file contents (text decoded) for editing.',
+    '- `artifacts_revert`: make an earlier release current again as a NEW',
+    '  release that copies its content — the artifact URL stays stable and',
+    '  history only grows. Purged releases are refused with `release_unavailable`.',
     '- `artifacts_fork`: private independent copy (no ACL copied).',
     '- `artifacts_set_access`: grant/revoke read or source, toggle public.',
     '- `artifacts_promote`: explicit version selection (expected-current).',

package/dist/server/versions.d.ts

@@ -0,0 +1,29 @@
+import type { ReleaseRecord } from './publication.js';
+/** A cursor fixes the release boundary and is bound to the authorized artifact and scope. */
+export declare function artifactVersions(input: {
+    artifactId: string;
+    storageScopeId: string;
+    currentReleaseId: string | null;
+    releases: ReleaseRecord[];
+    limit?: number;
+    cursor?: string;
+    state(releaseId: string): Promise<string>;
+    urls?: (artifactId: string, releaseId: string) => {
+        pinnedUrl: string;
+    };
+}): Promise<{
+    artifactId: string;
+    currentReleaseId: string | null;
+    versions: {
+        releaseId: string;
+        createdAt: string;
+        state: string;
+        authorPrincipalId: string | null;
+        parentReleaseId: string | null;
+        revertedFromReleaseId: string | null;
+        digest: string;
+        isCurrent: boolean;
+        pinnedUrl: string | null;
+    }[];
+    nextCursor: string | null;
+}>;