@sentropic/artifacts 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.2.7
+
+- Fix the `artifacts_get_source` wire payload that broke page editing in claude.ai:
+  files are no longer returned as a JSON integer array (`bytes: Array.from(bytes)`).
+  Text mime types (the canonical `TEXT_MIME_PATTERN`) come back as `text` with
+  `encoding: "utf8"`; every other file — including non-UTF-8 "text" — as `base64`
+  with `encoding: "base64"`. Size and digest verification still run on the raw
+  bytes before encoding. An 816-byte page now serializes to a few KiB instead of
+  blowing the tool-result budget.
+- `get_source` (and the conflict `currentSource`) no longer embeds any authoring
+  guide; the result carries only a `guideRef` (`{tool: "artifacts_get_api_guide",
+  version}`) naming the tool and version to fetch it from.
+- Per-call budgets are unchanged: at most 32 files and 262144 decoded bytes; the
+  2 MiB serialized MCP result budget still holds for the full snapshot.
+- Tool schema (`artifacts_get_source` description, v2 result schema source files),
+  the API guide text and the README source section describe the text/base64
+  encoding and the guide reference.
+
+## 0.2.6
+
+- Integrate part 1 with the source reads, sharing, terminal deletion, masking and
+  summaries published in 0.2.5. Apply `0005_metadata.sql` after 0004; it adds
+  editorial metadata and nullable release authors/lineage without backfilling history.
+- Add version history and revert as a new release on the same stable URL, preserving
+  current metadata and ACLs. The v2 profile uses `targetReleaseId` and paginated history.
+- Add full-bundle or exactly-once text edits, metadata on ensure/publish, and
+  transactional release CAS, metadata, references, quota and receipts.
+- Separate trusted `profileRevisionId`, `requireExpectedCurrentReleaseId` and
+  `resultEnvelopeVersion`. Compatible bindings keep root results; strict v2 retains
+  commit state, replay status and typed failures through mcp-platform 0.4.1.
+- Replay historical receipts before enforcing new preconditions or preparing edits.
+  Missing strict preconditions use the R2 `precondition_required` message and details.
+
+IMMO activates part 1 only after its qualified input and result switchovers.
+Artifacts 0.2.6 stays inside the existing cluster-mesh `>=0.2.0 <0.3.0` range;
+the API consumes the workspace package and retains its pinned APP-P1 profile.
+
 ## 0.2.5
 
 - D1: Read verified author manifests and file bytes for the current or a selected

package/README.md

@@ -1,5 +1,12 @@
 # @sentropic/artifacts — generic artifact contracts (L-5a)
 
+Publication profiles can set `requireExpectedCurrentReleaseId: true` to require an
+explicit UUID or `null` on publish/revert. Strict profiles reject writers without
+CAS. Omission remains supported in generic profiles. Replay the same caller key
+after an unknown commit outcome; changing files, edits, metadata or the precondition
+requires a new key. The `artifacts-outcome/v2` MCP envelope requires
+`@sentropic/mcp-platform >=0.4.1` and preserves commit state and typed error details.
+
 ## Shared PostgreSQL activation (UP-T, 0.2.3)
 
 W1.c/W3.a and Radar S1/A6 use the same imports:
@@ -314,7 +321,8 @@ The installed package includes SQL resources exported under
 ```js
 import { readFile } from 'node:fs/promises';
 
-const migrations = ['0001_artifacts.sql', '0002_lifecycle.sql'];
+const migrations = ['0001_artifacts.sql', '0002_lifecycle.sql', '0003_coordinator.sql',
+  '0004_terminal_controls.sql', '0005_metadata.sql'];
 for (const name of migrations) {
   const sql = await readFile(new URL(import.meta.resolve(
     `@sentropic/artifacts/migrations/${name}`,
@@ -324,8 +332,10 @@ for (const name of migrations) {
 ```
 
 Apply `0001_artifacts.sql` first to create the domain schema, then
-`0002_lifecycle.sql` to add lifecycle, sharing, sources and GC support, before
-using the Postgres store. The host owns migration credentials, serialization,
+`0002_lifecycle.sql` to add lifecycle, sharing, sources and GC support, then
+`0003_coordinator.sql`, `0004_terminal_controls.sql`, and `0005_metadata.sql`
+(artifact display metadata and nullable release lineage),
+before using the Postgres store. The host owns migration credentials, serialization,
 transactions and the migration journal; execute each version through that
 runner rather than running this read loop at application startup.
 
@@ -429,9 +439,13 @@ empty defaults. Existing profile selections remain explicit.
 
 `POST /get_source` accepts `artifactId`, optional `releaseId`, and optional unique
 `paths` (1–32 entries). Bind `publication.getRelease` and `sources.getSource` on
-the HTTP app. It returns the canonical manifest, verified author file bytes,
-and separate nullable `sourceRef`; readers need the distinct source permission.
-The snapshot is limited to 32 files and 262144 decoded bytes. Hosts must qualify
+the HTTP app. It returns the canonical manifest, verified author files, and a
+separate nullable `sourceRef`; readers need the distinct source permission.
+Size and digest are verified on the raw bytes, then each file is encoded for the
+wire: text mime types as `text` with `encoding: "utf8"`, all other files as
+`base64` with `encoding: "base64"` — never an integer array. The result carries
+a `guideRef` (`{tool, version}`) instead of the guide body. The snapshot is
+limited to 32 files and 262144 decoded bytes. Hosts must qualify
 a 2 MiB serialized MCP result budget before selecting this capability.
 
 `POST /set_access` grants or revokes a named principal's read access, requires a

package/dist/adapters/postgres.js

@@ -21,6 +21,9 @@ function toIntent(row) {
 }
 function toRelease(row) {
     return {
+        authorPrincipalId: row.author_principal_id ?? null,
+        parentReleaseId: row.parent_release_id ?? null,
+        revertedFromReleaseId: row.reverted_from_release_id ?? null,
         releaseId: row.id,
         artifactId: row.artifact_id,
         manifestDigest: row.manifest_digest,
@@ -143,11 +146,14 @@ export function createPostgresArtifactStore(pool) {
             }
         },
         async getRelease(releaseId) {
-            const { rows } = await pool.query(`SELECT id, artifact_id, manifest_digest, manifest, state, created_at
-         FROM artifacts.releases WHERE id = $1`, [releaseId]);
+            const { rows } = await pool.query(`SELECT * FROM artifacts.releases WHERE id = $1`, [releaseId]);
             const row = rows[0];
             return row === undefined ? undefined : toRelease(row);
         },
+        async listReleases(artifactId) {
+            const { rows } = await pool.query(`SELECT * FROM artifacts.releases WHERE artifact_id = $1 ORDER BY created_at, id`, [artifactId]);
+            return rows.map(toRelease);
+        },
         async getCurrentReleaseId(artifactId) {
             const { rows } = await pool.query(`SELECT release_id FROM artifacts.artifact_current WHERE artifact_id = $1`, [artifactId]);
             return rows[0]?.release_id;
@@ -209,14 +215,15 @@ export function createPostgresArtifactStore(pool) {
                     principalId: grant.principal_id,
                     grant: grant.permission,
                 })),
+                ...(row.metadata === null || Object.keys(row.metadata).length === 0 ? {} : { metadata: row.metadata }),
             };
         },
         async putArtifactAcl(artifactId, acl) {
-            await pool.query(`UPDATE artifacts.artifacts SET is_public = $2,
+            await pool.query(`UPDATE artifacts.artifacts SET is_public = $2, metadata = $4,
          lifecycle_state = CASE WHEN $3 THEN 'withdrawn'
            WHEN lifecycle_state = 'withdrawn' THEN 'active'
            ELSE lifecycle_state END
-         WHERE id = $1`, [artifactId, acl.isPublic, acl.withdrawn]);
+         WHERE id = $1`, [artifactId, acl.isPublic, acl.withdrawn, JSON.stringify(acl.metadata ?? {})]);
             await pool.query(`DELETE FROM artifacts.artifact_access WHERE artifact_id = $1`, [
                 artifactId,
             ]);

package/dist/http.d.ts

@@ -40,7 +40,8 @@ export interface HttpAppDeps {
     ensureHost: GuardedEnsureHost;
     publication: Omit<GuardedPublicationDeps, 'coordinator' | 'limits'> & {
         getCurrent: PublicationService['getCurrent'];
-        getRelease?: PublicationService['getRelease'];
+        getRelease: PublicationService['getRelease'];
+        listReleases: PublicationService['listReleases'];
     };
     sources?: Pick<SourceStore, 'getSource'>;
     management?: {
@@ -48,7 +49,7 @@ export interface HttpAppDeps {
         confirmation?: ArtifactConfirmationPort;
     };
     acls: AclStore;
-    lifecycle: Pick<LifecycleService, 'stateOf' | 'canRead'>;
+    lifecycle: Pick<LifecycleService, 'stateOf' | 'canRead' | 'getReleaseState'>;
     isApprovedAccount?: (principalId: string) => boolean;
     /** One trusted URL policy shared by HTTP and MCP receipts. */
     publicationUrls?: (artifactId: string, releaseId: string) => {
@@ -63,7 +64,7 @@ export interface ArtifactApp {
     handle(request: HttpRequest, invocation: ArtifactInvocationContext): Promise<HttpResponse>;
 }
 /** Retained for consumers describing canonical textual publication inputs. */
-export declare const TEXT_MIME_PATTERN = "^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])";
+export { TEXT_MIME_PATTERN } from './server/mime.js';
 /** Other mutation surfaces need their own qualification before host activation. */
 export declare function assertArtifactsTransportProfile(value: unknown): asserts value is CompiledArtifactsProfile;
 export declare function createHttpArtifactApp(deps: HttpAppDeps): ArtifactApp;

package/dist/http.js

@@ -1,16 +1,22 @@
+/** Selected HTTP control surface over the authorized atomic services. */
+import { createHash } from 'node:crypto';
 import { parseManifest } from './codecs.js';
 import { assertCompiledArtifactsProfile, ArtifactProfileInputError } from './profile/index.js';
 import { createArtifactCommand } from './server/command-identity.js';
 import { createGuardedEnsureService } from './server/service.js';
 import { assertArtifactReplayMigration } from './server/idempotency.js';
 import { createGuardedPublicationService } from './server/publication.js';
+import { applyEdits } from './server/edits.js';
 import { CommitQuarantineError } from './server/commit/types.js';
 import { ArtifactOperationError, classifyArtifactFailure } from './server/failures.js';
 import { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 import { readArtifactSource } from './server/source-read.js';
 import { artifactSummary } from './server/summary.js';
+import { artifactVersions } from './server/versions.js';
 import { manageArtifact } from './server/management.js';
 import { createPostgresManagementUnit } from './adapters/postgres-management.js';
+import { TEXT_MIME_RE } from './server/mime.js';
+import { API_GUIDE_REF } from './server/templates.js';
 export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 /** Stable content-route error codes; private driver messages never leave the host. */
 export function errorBody(status) {
@@ -19,7 +25,7 @@ export function errorBody(status) {
             500: 'internal_error', 503: 'capability_unavailable' }[status] ?? 'internal_error' };
 }
 /** Retained for consumers describing canonical textual publication inputs. */
-export const TEXT_MIME_PATTERN = '^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])';
+export { TEXT_MIME_PATTERN } from './server/mime.js';
 function object(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
         throw new ArtifactProfileInputError();
@@ -29,7 +35,7 @@ function object(value) {
 export function assertArtifactsTransportProfile(value) {
     assertCompiledArtifactsProfile(value);
     const supported = ['artifacts_ensure', 'artifacts_publish', 'artifacts_list', 'artifacts_get',
-        'artifacts_get_source', 'artifacts_set_access', 'artifacts_delete'];
+        'artifacts_list_versions', 'artifacts_get_source', 'artifacts_revert', 'artifacts_set_access', 'artifacts_delete'];
     if (value.selectedCapabilities.some((name) => !supported.includes(name))) {
         throw new Error('unsupported artifacts transport capability');
     }
@@ -52,23 +58,140 @@ export function createHttpArtifactApp(deps) {
         throw new Error('artifact delete confirmation port required');
     }
     const ensure = createGuardedEnsureService({ profile, coordinator: deps.coordinator,
-        derivation: deps.derivation, host: deps.ensureHost });
-    async function visible(artifactId, invocation, allowTerminalOwner = false) {
+        derivation: deps.derivation, host: {
+            lockBinding: (client, binding) => deps.ensureHost.lockBinding(client, binding),
+            abandonAttempt: id => deps.ensureHost.abandonAttempt(id),
+            readPolicyRevision: () => deps.ensureHost.readPolicyRevision(),
+            async resolveBinding(client, binding) {
+                const receipt = await deps.ensureHost.resolveBinding(client, binding);
+                if (receipt.created && binding.metadata) {
+                    await deps.publication.createUnitWriter(client).updateMetadata(receipt.artifactId, binding.metadata);
+                }
+                return receipt;
+            },
+        } });
+    async function visible(artifactId, invocation, action = 'read') {
         const acl = await deps.acls.getArtifactAcl(artifactId);
         if (!acl || acl.storageScopeId !== invocation.storageScopeId)
             throw new ArtifactOperationError('not_found');
         const state = await deps.lifecycle.stateOf(artifactId);
         if (acl.ownerId === invocation.actorId && (state === 'deleted' || state === 'purged')) {
             // Management must still authorize terminal owners before replaying a receipt.
-            if (allowTerminalOwner)
+            if (action === true)
                 return acl;
             throw new ArtifactOperationError('gone');
         }
-        if (!deps.lifecycle.canRead({ artifactId, state }, acl, invocation.actorId, 'read', deps.isApprovedAccount)) {
+        if (!deps.lifecycle.canRead({ artifactId, state }, acl, invocation.actorId, action === true ? 'read' : action, deps.isApprovedAccount)) {
             throw new ArtifactOperationError('not_found');
         }
         return acl;
     }
+    /** Display metadata fields present on validated args (ensure/publish). */
+    function metadataOf(normalized) {
+        const meta = {};
+        if (typeof normalized.title === 'string')
+            meta.title = normalized.title;
+        if (typeof normalized.description === 'string')
+            meta.description = normalized.description;
+        if (typeof normalized.icon === 'string' || normalized.icon === null)
+            meta.icon = normalized.icon;
+        return Object.keys(meta).length > 0 ? meta : undefined;
+    }
+    function blobKey(storageScopeId, digest) {
+        // Manifest digests are `sha256:<hex>`; physical keys are `.../blobs/sha256/<hex>`.
+        return `artifacts/${storageScopeId}/blobs/${digest.replace(':', '/')}`;
+    }
+    async function readManifestFiles(manifest, storageScopeId) {
+        const parsed = parseManifest(manifest);
+        const entries = parsed.files ?? [];
+        const files = [];
+        for (const entry of entries) {
+            const bytes = await deps.publication.blobs.getBlob(blobKey(storageScopeId, entry.digest));
+            if (bytes === undefined)
+                throw new ArtifactOperationError('release_unavailable', { release: { reason: 'not_retained' } });
+            if (bytes.byteLength !== entry.size || `sha256:${createHash('sha256').update(bytes).digest('hex')}` !== entry.digest) {
+                throw new ArtifactOperationError('verification_failed');
+            }
+            let text;
+            if (TEXT_MIME_RE.test(entry.mimeType)) {
+                try {
+                    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+                }
+                catch { /* Non-UTF-8 is not editable. */ }
+            }
+            files.push({ path: entry.path, mimeType: entry.mimeType, bytes: new Uint8Array(bytes),
+                ...(text === undefined ? {} : { text }) });
+        }
+        return files;
+    }
+    /** Apply publish edits to the current release's text files; typed edit_mismatch changes nothing. */
+    async function editedFiles(artifactId, invocation, edits, expected) {
+        const current = expected === undefined ? await deps.publication.getCurrent(artifactId)
+            : expected === null ? undefined : await deps.publication.getRelease(expected);
+        if (current === undefined) {
+            if (expected === null || expected === undefined)
+                throw new ArtifactOperationError('release_unavailable', { release: { reason: 'unpublished' } });
+            throw new ArtifactOperationError('not_found');
+        }
+        if (parseManifest(current.manifest).artifactId !== artifactId)
+            throw new ArtifactOperationError('not_found');
+        if (await deps.lifecycle.getReleaseState(current.releaseId) === 'purged') {
+            throw new ArtifactOperationError('release_unavailable', { release: { reason: 'purged' } });
+        }
+        const files = await readManifestFiles(current.manifest, invocation.storageScopeId);
+        return applyEdits(files, edits).map((file) => ({
+            path: file.path, mimeType: file.mimeType,
+            bytes: file.text === undefined ? file.bytes : new Uint8Array(Buffer.from(file.text, 'utf8')),
+        }));
+    }
+    async function conflictSource(outcome, normalized, invocation) {
+        if (outcome.ok || outcome.failure.kind !== 'operational' || outcome.failure.variant !== 'pointer_conflict')
+            return outcome;
+        const artifactId = normalized.artifactId;
+        await visible(artifactId, invocation, 'source');
+        const conflict = outcome.failure.conflict;
+        if (!conflict?.currentReleaseId || normalized.edits === undefined)
+            return outcome;
+        const release = await deps.publication.getRelease(conflict.currentReleaseId);
+        if (!release || await deps.lifecycle.getReleaseState(release.releaseId) === 'purged')
+            return outcome;
+        const manifest = parseManifest(release.manifest);
+        const paths = new Set(normalized.edits.map(edit => edit.path));
+        const entries = manifest.files;
+        const files = (await readManifestFiles(release.manifest, invocation.storageScopeId)).filter(file => paths.has(file.path))
+            .map(file => ({ path: file.path, mimeType: file.mimeType, size: file.bytes.byteLength,
+            digest: entries.find(entry => entry.path === file.path).digest,
+            ...(file.text === undefined
+                ? { base64: Buffer.from(file.bytes).toString('base64'), encoding: 'base64' }
+                : { text: file.text, encoding: 'utf8' }) }));
+        await visible(artifactId, invocation, 'source');
+        const failure = { ...outcome.failure, conflict: { ...conflict, currentSource: {
+                    artifactId, releaseId: release.releaseId, digest: conflict.currentDigest, manifest: release.manifest,
+                    files, sourceRef: null, guideRef: API_GUIDE_REF, ...deps.publicationUrls?.(artifactId, release.releaseId),
+                } } };
+        Object.defineProperty(failure, 'cause', { value: outcome.failure.cause, enumerable: false });
+        return { ok: false, failure: Object.freeze(failure) };
+    }
+    /** Shared guarded-commit response for publish and revert (same commit path, same receipt shape). */
+    function commitOutcome(outcome, artifactId, meta, setCommitState) {
+        if (!outcome.ok) {
+            const failure = { ...outcome.failure, kind: 'operational' };
+            Object.defineProperty(failure, 'cause', { value: outcome.failure.cause, enumerable: false });
+            return { ok: false, failure: Object.freeze(failure) };
+        }
+        setCommitState(outcome.commitState);
+        const receipt = object(outcome.result.receipt);
+        if (typeof receipt.releaseId !== 'string' || typeof receipt.manifest !== 'string') {
+            throw new Error('invalid publication receipt');
+        }
+        return { ...outcome, result: { status: 201, body: {
+                    artifactId, releaseId: receipt.releaseId, manifest: receipt.manifest,
+                    previousReleaseId: receipt.previousReleaseId ?? null, updatedAt: receipt.updatedAt ?? null,
+                    ...(typeof receipt.revertedFromReleaseId === 'string' ? { revertedFromReleaseId: receipt.revertedFromReleaseId } : {}),
+                    digest: parseManifest(receipt.manifest).digest,
+                    ...deps.publicationUrls?.(artifactId, receipt.releaseId), ...(receipt.metadata ?? meta ?? {}),
+                } } };
+    }
     const app = {
         selectedCapabilities: profile.selectedCapabilities,
         profileDigest: profile.profileDigest,
@@ -96,10 +219,13 @@ export function createHttpArtifactApp(deps) {
                     throw new ArtifactProfileInputError();
                 }
                 let args;
-                if (capability === 'artifacts_get') {
+                const getPrefix = request.method !== 'GET' ? undefined : capability === 'artifacts_get' ? '/meta/'
+                    : capability === 'artifacts_list_versions' ? '/versions/'
+                        : capability === 'artifacts_get_source' ? '/source/' : undefined;
+                if (getPrefix !== undefined) {
                     if (request.body !== undefined && Object.keys(object(request.body)).length)
                         throw new ArtifactProfileInputError();
-                    args = { artifactId: request.path.slice('/meta/'.length) };
+                    args = { artifactId: request.path.slice(getPrefix.length) };
                 }
                 else {
                     args = { ...object(request.body ?? {}) };
@@ -109,9 +235,9 @@ export function createHttpArtifactApp(deps) {
                         delete args.storageScopeId;
                     }
                 }
-                const normalized = profile.validate(capability, args, request.idempotencyKey);
-                const command = ['artifacts_ensure', 'artifacts_publish', 'artifacts_set_access', 'artifacts_delete'].includes(capability)
-                    ? createArtifactCommand(profile, capability, args, invocation, deps.derivation, request.idempotencyKey) : undefined;
+                const normalized = profile.validate(capability, args, request.idempotencyKey, { deferPrecondition: true });
+                const command = ['artifacts_ensure', 'artifacts_publish', 'artifacts_set_access', 'artifacts_delete', 'artifacts_revert'].includes(capability)
+                    ? createArtifactCommand(profile, capability, args, invocation, deps.derivation, request.idempotencyKey, { deferPrecondition: true }) : undefined;
                 if (command && ['ensure', 'publish'].includes(command.operation)) {
                     phase = 'migration';
                     await assertArtifactReplayMigration(deps.legacyRecords, command, invocation, normalized.idempotencyKey);
@@ -121,11 +247,20 @@ export function createHttpArtifactApp(deps) {
                     const outcome = await ensure.ensure(invocation, { ...normalized,
                         envelopeKey: request.idempotencyKey });
                     if (outcome.ok) {
+                        commitState = outcome.commitState;
                         const state = await deps.lifecycle.stateOf(outcome.result.artifactId);
                         if (state === 'deleted' || state === 'purged')
                             throw new ArtifactOperationError('gone');
                     }
-                    return outcome.ok ? { ...outcome, result: { status: 201, body: outcome.result } } : outcome;
+                    if (!outcome.ok)
+                        return outcome;
+                    const artifactId = outcome.result.artifactId;
+                    const acl = await visible(artifactId, invocation);
+                    const summary = artifactSummary({ artifactId, acl, actorId: invocation.actorId,
+                        state: await deps.lifecycle.stateOf(artifactId), current: await deps.publication.getCurrent(artifactId),
+                        urls: deps.publicationUrls, approved: deps.isApprovedAccount });
+                    return { ...outcome, result: { status: 201, body: profile.resultEnvelopeVersion === 2
+                                ? { ...summary, ...outcome.result } : { ...outcome.result, ...acl.metadata } } };
                 }
                 if (capability === 'artifacts_get_source') {
                     const artifactId = normalized.artifactId;
@@ -145,15 +280,18 @@ export function createHttpArtifactApp(deps) {
                         commitState: 'not_committed', replayed: false };
                 }
                 if (capability === 'artifacts_set_access' || capability === 'artifacts_delete') {
-                    await visible(normalized.artifactId, invocation, true);
+                    const acl = await visible(normalized.artifactId, invocation, true);
+                    if (acl.ownerId !== invocation.actorId)
+                        throw new ArtifactOperationError('access_denied');
                     const outcome = await manageArtifact({ coordinator: deps.coordinator,
                         createUnit: deps.management?.createUnit ?? createPostgresManagementUnit,
                         confirmation: deps.management?.confirmation, readPolicyRevision: () => deps.ensureHost.readPolicyRevision(),
                         isApprovedPrincipal: deps.isApprovedAccount ?? (() => false),
+                        validateNewCommand: () => { profile.validate(capability, args, request.idempotencyKey); },
                     }, invocation, command, normalized.confirmationRef);
                     return outcome.ok ? { ...outcome, result: { status: 200, body: outcome.result } } : outcome;
                 }
-                if (capability === 'artifacts_publish') {
+                if (capability === 'artifacts_publish' || capability === 'artifacts_revert') {
                     const artifactId = normalized.artifactId;
                     const acl = await visible(artifactId, invocation);
                     if (acl.ownerId !== invocation.actorId)
@@ -162,31 +300,53 @@ export function createHttpArtifactApp(deps) {
                     const publication = createGuardedPublicationService({ ...deps.publication, coordinator: deps.coordinator,
                         limits: { maxFiles: limits.publishFilesMax, maxFileBytes: limits.maxDecodedFileBytes,
                             maxTotalBytes: limits.maxDecodedTotalBytes } });
-                    const outcome = await publication.publishFinalized({
-                        ownerId: acl.ownerId, storageScopeId: invocation.storageScopeId, artifactId,
+                    const meta = metadataOf(normalized);
+                    const input = { ownerId: acl.ownerId, storageScopeId: invocation.storageScopeId, artifactId,
                         identity: command.identity, actorId: invocation.actorId, invocationId: invocation.invocationId,
                         attemptId: invocation.invocationId, policyRevision: await deps.ensureHost.readPolicyRevision(),
-                        authorizeCommit: invocation.authorizeCommit,
-                        source: { kind: 'inline-original' }, profile: normalized.profile,
-                        files: normalized.files.map((file) => ({
-                            path: file.path, mimeType: file.mimeType, bytes: Uint8Array.from(file.bytes),
-                        })),
-                    });
-                    if (!outcome.ok) {
-                        const failure = { ...outcome.failure, kind: 'operational' };
-                        Object.defineProperty(failure, 'cause', { value: outcome.failure.cause, enumerable: false });
-                        return { ok: false, failure: Object.freeze(failure) };
+                        authorizeCommit: invocation.authorizeCommit, metadata: meta,
+                        operation: capability === 'artifacts_revert' ? 'revert' : 'publish',
+                        expectedCurrentReleaseId: normalized.expectedCurrentReleaseId };
+                    const replay = await publication.replayFinalized(input);
+                    if (replay !== undefined)
+                        return commitOutcome(replay, artifactId, meta, state => { commitState = state; });
+                    profile.validate(capability, args, request.idempotencyKey);
+                    let files;
+                    let source;
+                    let releaseProfile;
+                    if (capability === 'artifacts_publish') {
+                        files = normalized.edits !== undefined
+                            ? await editedFiles(artifactId, invocation, normalized.edits, input.expectedCurrentReleaseId)
+                            : normalized.files.map((file) => ({
+                                path: file.path, mimeType: file.mimeType, bytes: Uint8Array.from(file.bytes),
+                            }));
+                        if (normalized.edits !== undefined) {
+                            const { edits: _edits, ...snapshot } = normalized;
+                            profile.validate(capability, { ...snapshot, files: files.map(file => ({ ...file, bytes: Array.from(file.bytes) })) });
+                        }
+                        source = { kind: 'inline-original' };
+                        releaseProfile = normalized.profile;
                     }
-                    commitState = outcome.commitState;
-                    const receipt = object(outcome.result.receipt);
-                    if (typeof receipt.releaseId !== 'string' || typeof receipt.manifest !== 'string') {
-                        throw new Error('invalid publication receipt');
+                    else {
+                        const releaseId = normalized[profile.resultEnvelopeVersion === 2 ? 'targetReleaseId' : 'releaseId'];
+                        const target = await deps.publication.getRelease(releaseId);
+                        const targetManifest = target === undefined ? undefined : parseManifest(target.manifest);
+                        if (target === undefined || targetManifest?.artifactId !== artifactId) {
+                            throw new ArtifactOperationError('not_found');
+                        }
+                        if (await deps.lifecycle.getReleaseState(releaseId) === 'purged') {
+                            throw new ArtifactOperationError('release_unavailable', { release: { reason: 'purged' } });
+                        }
+                        files = (await readManifestFiles(target.manifest, invocation.storageScopeId))
+                            .map((file) => ({ path: file.path, mimeType: file.mimeType, bytes: file.bytes }));
+                        source = { kind: 'base-commit', commit: releaseId };
+                        releaseProfile = (targetManifest.profile ?? {});
                     }
-                    return { ...outcome, result: { status: 201, body: {
-                                artifactId, releaseId: receipt.releaseId, manifest: receipt.manifest,
-                                digest: parseManifest(receipt.manifest).digest,
-                                ...deps.publicationUrls?.(artifactId, receipt.releaseId),
-                            } } };
+                    const outcome = await publication.publishFinalized({
+                        ...input, source, profile: releaseProfile, files,
+                    });
+                    const committed = commitOutcome(outcome, artifactId, meta, (state) => { commitState = state; });
+                    return await conflictSource(committed, normalized, invocation);
                 }
                 if (capability === 'artifacts_get') {
                     const artifactId = normalized.artifactId;
@@ -196,8 +356,34 @@ export function createHttpArtifactApp(deps) {
                     return { ok: true, invocationId: invocation.invocationId, commitState: 'not_committed', replayed: false,
                         result: { status: 200, body: { ...artifactSummary({ artifactId, acl, state, current,
                                     actorId: invocation.actorId, urls: deps.publicationUrls, approved: deps.isApprovedAccount }),
+                                ...(acl.metadata !== undefined ? { metadata: acl.metadata } : {}),
                                 ...(acl.ownerId === invocation.actorId ? { grants: acl.grants } : {}) } } };
                 }
+                if (capability === 'artifacts_list_versions') {
+                    const artifactId = normalized.artifactId;
+                    await visible(artifactId, invocation);
+                    const current = await deps.publication.getCurrent(artifactId);
+                    if (profile.resultEnvelopeVersion === 2) {
+                        const body = await artifactVersions({ artifactId, storageScopeId: invocation.storageScopeId,
+                            currentReleaseId: current?.releaseId ?? null, releases: await deps.publication.listReleases(artifactId),
+                            limit: normalized.limit, cursor: normalized.cursor,
+                            state: id => deps.lifecycle.getReleaseState(id), urls: deps.publicationUrls });
+                        await visible(artifactId, invocation);
+                        return { ok: true, invocationId: invocation.invocationId, commitState: 'not_committed', replayed: false,
+                            result: { status: 200, body } };
+                    }
+                    const releases = [];
+                    for (const release of await deps.publication.listReleases(artifactId)) {
+                        const manifest = parseManifest(release.manifest);
+                        releases.push({ releaseId: release.releaseId, createdAt: release.createdAt,
+                            author: typeof manifest.ownerId === 'string' ? manifest.ownerId : null,
+                            state: await deps.lifecycle.getReleaseState(release.releaseId),
+                            isCurrent: current?.releaseId === release.releaseId,
+                            digest: release.manifestDigest });
+                    }
+                    return { ok: true, invocationId: invocation.invocationId, commitState: 'not_committed', replayed: false,
+                        result: { status: 200, body: { artifactId, total: releases.length, releases } } };
+                }
                 const visibleArtifacts = [];
                 for (const artifactId of await deps.acls.listArtifactIds()) {
                     const acl = await deps.acls.getArtifactAcl(artifactId);
@@ -217,7 +403,7 @@ export function createHttpArtifactApp(deps) {
             catch (cause) {
                 const failure = classifyArtifactFailure(cause, { invocationId: invocation?.invocationId ?? '',
                     operation, phase, commitState }, (error) => error instanceof ArtifactProfileInputError
-                    ? new ArtifactOperationError(error.category) : deps.mapHostError?.(error));
+                    ? new ArtifactOperationError(error.category, { publicDetails: error.details }) : deps.mapHostError?.(error));
                 if (cause instanceof CommitQuarantineError) {
                     const migration = { ...failure, kind: 'operational', category: 'provider_unavailable',
                         variant: 'legacy_quarantine', httpStatus: 503, publicCode: 'capability_unavailable', retriable: false };
@@ -227,7 +413,9 @@ export function createHttpArtifactApp(deps) {
                 return { ok: false, failure };
             }
         },
-        async handle(request, invocation) { return projectArtifactHttpOutcome(await app.execute(request, invocation)); },
+        async handle(request, invocation) {
+            return projectArtifactHttpOutcome(await app.execute(request, invocation), profile.resultEnvelopeVersion === 2);
+        },
     };
     return Object.freeze(app);
 }

package/dist/mcp-core.d.ts

@@ -10,11 +10,11 @@ export { createRadarKeyDerivation } from './server/command-identity.js';
 export type { ArtifactKeyDerivationBinding } from './server/command-identity.js';
 export declare const ARTIFACTS_PROVIDER_ID = "sentropic.artifacts";
 export declare const ARTIFACTS_APP_ID = "sentropic-artifacts";
-export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.5";
-export declare const ARTIFACTS_TOOL_NAMES: readonly ["artifacts_get_template", "artifacts_get_api_guide", "artifacts_ensure", "artifacts_publish", "artifacts_create_upload", "artifacts_commit_upload", "artifacts_list", "artifacts_get", "artifacts_get_source", "artifacts_fork", "artifacts_set_access", "artifacts_promote", "artifacts_renew", "artifacts_delete", "artifacts_restore"];
+export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.7";
+export declare const ARTIFACTS_TOOL_NAMES: readonly ["artifacts_get_template", "artifacts_get_api_guide", "artifacts_ensure", "artifacts_publish", "artifacts_create_upload", "artifacts_commit_upload", "artifacts_list", "artifacts_get", "artifacts_get_source", "artifacts_fork", "artifacts_set_access", "artifacts_promote", "artifacts_renew", "artifacts_delete", "artifacts_restore", "artifacts_list_versions", "artifacts_revert"];
 export type ArtifactsToolName = (typeof ARTIFACTS_TOOL_NAMES)[number];
 export declare const ARTIFACTS_TOOL_SPECS: {
-    name: "artifacts_ensure" | "artifacts_publish" | "artifacts_set_access" | "artifacts_delete" | "artifacts_get_template" | "artifacts_get_api_guide" | "artifacts_create_upload" | "artifacts_commit_upload" | "artifacts_list" | "artifacts_get" | "artifacts_get_source" | "artifacts_fork" | "artifacts_promote" | "artifacts_renew" | "artifacts_restore";
+    name: "artifacts_ensure" | "artifacts_publish" | "artifacts_set_access" | "artifacts_delete" | "artifacts_revert" | "artifacts_get_template" | "artifacts_get_api_guide" | "artifacts_create_upload" | "artifacts_commit_upload" | "artifacts_list" | "artifacts_get" | "artifacts_get_source" | "artifacts_fork" | "artifacts_promote" | "artifacts_renew" | "artifacts_restore" | "artifacts_list_versions";
     description: string;
     mutability: import("@sentropic/mcp-platform").Mutability;
 }[];