@sentropic/artifacts 0.2.4 → 0.2.6

package/dist/http.js

@@ -1,12 +1,20 @@
+/** 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';
 export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 /** Stable content-route error codes; private driver messages never leave the host. */
 export function errorBody(status) {
@@ -16,6 +24,7 @@ export function errorBody(status) {
 }
 /** 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])';
+const TEXT_MIME_RE = new RegExp(TEXT_MIME_PATTERN);
 function object(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
         throw new ArtifactProfileInputError();
@@ -24,7 +33,8 @@ function object(value) {
 /** Other mutation surfaces need their own qualification before host activation. */
 export function assertArtifactsTransportProfile(value) {
     assertCompiledArtifactsProfile(value);
-    const supported = ['artifacts_ensure', 'artifacts_publish', 'artifacts_list', 'artifacts_get'];
+    const supported = ['artifacts_ensure', 'artifacts_publish', 'artifacts_list', 'artifacts_get',
+        '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');
     }
@@ -40,18 +50,145 @@ export function createHttpArtifactApp(deps) {
     if (typeof deps.legacyRecords?.get !== 'function')
         throw new Error('artifacts requires a legacy record inventory');
     const profile = deps.profile;
+    if (profile.selectedCapabilities.includes('artifacts_get_source') &&
+        (!deps.sources || !deps.publication.getRelease))
+        throw new Error('artifact source read ports required');
+    if (profile.selectedCapabilities.includes('artifacts_delete') && !deps.management?.confirmation) {
+        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) {
+        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 (!deps.lifecycle.canRead({ artifactId, state }, acl, invocation.actorId, 'read', deps.isApprovedAccount)) {
+        if (acl.ownerId === invocation.actorId && (state === 'deleted' || state === 'purged')) {
+            // Management must still authorize terminal owners before replaying a receipt.
+            if (action === true)
+                return acl;
+            throw new ArtifactOperationError('gone');
+        }
+        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 ? { bytes: Array.from(file.bytes) } : { text: file.text }) }));
+        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, ...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,
@@ -79,10 +216,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 ?? {}) };
@@ -92,10 +232,10 @@ export function createHttpArtifactApp(deps) {
                         delete args.storageScopeId;
                     }
                 }
-                const normalized = profile.validate(capability, args, request.idempotencyKey);
-                const command = capability === 'artifacts_ensure' || capability === 'artifacts_publish'
-                    ? createArtifactCommand(profile, capability, args, invocation, deps.derivation, request.idempotencyKey) : undefined;
-                if (command) {
+                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);
                 }
@@ -103,9 +243,52 @@ export function createHttpArtifactApp(deps) {
                 if (capability === 'artifacts_ensure') {
                     const outcome = await ensure.ensure(invocation, { ...normalized,
                         envelopeKey: request.idempotencyKey });
-                    return outcome.ok ? { ...outcome, result: { status: 201, body: outcome.result } } : outcome;
+                    if (outcome.ok) {
+                        commitState = outcome.commitState;
+                        const state = await deps.lifecycle.stateOf(outcome.result.artifactId);
+                        if (state === 'deleted' || state === 'purged')
+                            throw new ArtifactOperationError('gone');
+                    }
+                    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;
+                    const result = await readArtifactSource({
+                        storageScopeId: invocation.storageScopeId,
+                        authorize: async () => {
+                            const acl = await visible(artifactId, invocation);
+                            const state = await deps.lifecycle.stateOf(artifactId);
+                            if (!deps.lifecycle.canRead({ artifactId, state }, acl, invocation.actorId, 'source', deps.isApprovedAccount)) {
+                                throw new ArtifactOperationError('access_denied');
+                            }
+                        }, getCurrent: deps.publication.getCurrent, getRelease: deps.publication.getRelease,
+                        getSource: (id) => deps.sources.getSource(id), getBlob: (key) => deps.publication.blobs.getBlob(key),
+                        urls: deps.publicationUrls, maxFiles: 32, maxTotalBytes: 262144,
+                    }, normalized);
+                    return { ok: true, result: { status: 200, body: result }, invocationId: invocation.invocationId,
+                        commitState: 'not_committed', replayed: false };
                 }
-                if (capability === 'artifacts_publish') {
+                if (capability === 'artifacts_set_access' || capability === 'artifacts_delete') {
+                    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' || capability === 'artifacts_revert') {
                     const artifactId = normalized.artifactId;
                     const acl = await visible(artifactId, invocation);
                     if (acl.ownerId !== invocation.actorId)
@@ -114,31 +297,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;
@@ -146,10 +351,36 @@ export function createHttpArtifactApp(deps) {
                     const state = await deps.lifecycle.stateOf(artifactId);
                     const current = await deps.publication.getCurrent(artifactId);
                     return { ok: true, invocationId: invocation.invocationId, commitState: 'not_committed', replayed: false,
-                        result: { status: 200, body: { artifactId, ownerId: acl.ownerId, storageScopeId: acl.storageScopeId,
-                                state, isPublic: acl.isPublic, withdrawn: state === 'withdrawn', currentReleaseId: current?.releaseId,
+                        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);
@@ -157,7 +388,8 @@ export function createHttpArtifactApp(deps) {
                         continue;
                     const state = await deps.lifecycle.stateOf(artifactId);
                     if (deps.lifecycle.canRead({ artifactId, state }, acl, invocation.actorId, 'read', deps.isApprovedAccount)) {
-                        visibleArtifacts.push({ artifactId, ownerId: acl.ownerId, state, isPublic: acl.isPublic });
+                        visibleArtifacts.push(artifactSummary({ artifactId, acl, state, actorId: invocation.actorId,
+                            current: await deps.publication.getCurrent(artifactId), urls: deps.publicationUrls, approved: deps.isApprovedAccount }));
                     }
                 }
                 const offset = normalized.offset;
@@ -168,7 +400,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 };
@@ -178,7 +410,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/index.d.ts

@@ -25,3 +25,6 @@ export * from './server/reader-profile.js';
 export * from './http.js';
 export * from './server/commit-contract.js';
 export * from './server/outcome-contract.js';
+export * from './server/source-read.js';
+export * from './server/management.js';
+export * from './adapters/postgres-management.js';

package/dist/index.js

@@ -29,3 +29,6 @@ export * from './server/reader-profile.js';
 export * from './http.js';
 export * from './server/commit-contract.js';
 export * from './server/outcome-contract.js';
+export * from './server/source-read.js';
+export * from './server/management.js';
+export * from './adapters/postgres-management.js';

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.4";
-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.6";
+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_get_template" | "artifacts_get_api_guide" | "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";
+    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;
 }[];

package/dist/mcp-core.js

@@ -2,16 +2,17 @@ import { assertArtifactsTransportProfile } from './http.js';
 import { ARTIFACT_CAPABILITY_NAMES, ArtifactProfileInputError } from './profile/index.js';
 import { ArtifactOperationError, classifyArtifactFailure } from './server/failures.js';
 import { projectArtifactHttpOutcome, projectArtifactMcpOutcome } from './server/outcome-projection.js';
+import { ARTIFACT_RESULT_SCHEMA } from './server/result-schema.js';
 export * from './profile/index.js';
 export { createRadarKeyDerivation } from './server/command-identity.js';
 export const ARTIFACTS_PROVIDER_ID = 'sentropic.artifacts';
 export const ARTIFACTS_APP_ID = 'sentropic-artifacts';
-export const ARTIFACTS_PROVIDER_VERSION = '0.2.4';
+export const ARTIFACTS_PROVIDER_VERSION = '0.2.6';
 export const ARTIFACTS_TOOL_NAMES = ARTIFACT_CAPABILITY_NAMES;
 export const ARTIFACTS_TOOL_SPECS = ARTIFACTS_TOOL_NAMES.map((name) => ({ name,
     description: `Artifacts ${name.slice('artifacts_'.length).replaceAll('_', ' ')}.`,
     mutability: (['artifacts_list', 'artifacts_get', 'artifacts_get_template', 'artifacts_get_api_guide',
-        'artifacts_get_source'].includes(name) ? 'read-only' : name === 'artifacts_publish' ? 'append' : 'state-transition'),
+        'artifacts_get_source', 'artifacts_list_versions'].includes(name) ? 'read-only' : name === 'artifacts_publish' ? 'append' : 'state-transition'),
 }));
 export const ARTIFACTS_PARAMETER_SCHEMA = { properties: {}, required: [] };
 export function createArtifactsManifest(options) {
@@ -24,12 +25,14 @@ export function createArtifactsManifest(options) {
         resources: [], prompts: [],
         tools: ARTIFACTS_TOOL_SPECS.filter((spec) => profile.selectedCapabilities.includes(spec.name)).map((spec) => ({
             kind: 'tool', name: spec.name,
-            description: spec.description,
-            inputSchema: profile.schemas[spec.name], outputSchema: { type: 'object' },
+            description: spec.description + (profile.profileRevisionId
+                ? ` Active profile: ${profile.profileRevisionId}; resultEnvelopeVersion: ${profile.resultEnvelopeVersion}.` : ''),
+            inputSchema: profile.schemas[spec.name], outputSchema: profile.resultEnvelopeVersion === 2
+                ? ARTIFACT_RESULT_SCHEMA : { type: 'object', additionalProperties: true },
             requiredScopes: [...scopes], requiredClaims: [], redactionClass: 'low',
             mutability: spec.mutability, mutatesExternalSystem: spec.mutability !== 'read-only',
             idempotency: profile.idempotency[spec.name] ?? { required: false },
-            gates: { requiresElicitation: false, requiresHumanConfirmation: false, requiresPrincipalGate: false },
+            gates: { requiresElicitation: false, requiresHumanConfirmation: spec.name === 'artifacts_delete', requiresPrincipalGate: false },
         })),
         authz: { requiredClaims: [], scopes, tenantResolution: 'custom-resolver' },
         // The existing manifest codec includes audit metadata, including for an empty tool set.
@@ -38,7 +41,8 @@ export function createArtifactsManifest(options) {
 }
 function rejected(cause, invocationId, operation, mapHostError) {
     return { ok: false, failure: classifyArtifactFailure(cause, { invocationId, operation,
-            phase: cause instanceof ArtifactProfileInputError ? cause.phase : 'entry', commitState: 'not_committed' }, (error) => error instanceof ArtifactProfileInputError ? new ArtifactOperationError(error.category) : mapHostError?.(error)) };
+            phase: cause instanceof ArtifactProfileInputError ? cause.phase : 'entry', commitState: 'not_committed' }, (error) => error instanceof ArtifactProfileInputError
+            ? new ArtifactOperationError(error.category, { publicDetails: error.details }) : mapHostError?.(error)) };
 }
 export function createArtifactsToolExecutor(deps) {
     assertArtifactsTransportProfile(deps.profile);
@@ -49,7 +53,7 @@ export function createArtifactsToolExecutor(deps) {
     }
     async function execute(input) {
         try {
-            const args = profile.validate(input.tool, input.args, input.idempotencyKey);
+            const args = profile.validate(input.tool, input.args, input.idempotencyKey, { deferPrecondition: true });
             let request;
             switch (input.tool) {
                 case 'artifacts_ensure':
@@ -64,6 +68,21 @@ export function createArtifactsToolExecutor(deps) {
                 case 'artifacts_get':
                     request = { method: 'GET', path: `/meta/${args.artifactId}`, body: undefined };
                     break;
+                case 'artifacts_get_source':
+                    request = { method: 'POST', path: '/get_source', body: args };
+                    break;
+                case 'artifacts_set_access':
+                    request = { method: 'POST', path: '/set_access', body: args };
+                    break;
+                case 'artifacts_delete':
+                    request = { method: 'POST', path: '/delete', body: args };
+                    break;
+                case 'artifacts_list_versions':
+                    request = { method: 'POST', path: '/list_versions', body: args };
+                    break;
+                case 'artifacts_revert':
+                    request = { method: 'POST', path: '/revert', body: args };
+                    break;
                 default: throw new ArtifactProfileInputError(true);
             }
             return await deps.app.execute({ ...request, actorId: input.invocation.actorId,
@@ -74,7 +93,7 @@ export function createArtifactsToolExecutor(deps) {
         }
     }
     return { execute, async invoke(input) {
-            return projectArtifactHttpOutcome(await execute(input));
+            return projectArtifactHttpOutcome(await execute(input), profile.resultEnvelopeVersion === 2);
         } };
 }
 export function createArtifactsAdapter(options) {
@@ -92,7 +111,7 @@ export function createArtifactsAdapter(options) {
             let outcome;
             try {
                 // Selection and closed input checks precede even the host invocation binding.
-                options.profile.validate(request.capabilityRef, request.input, request.idempotencyKey);
+                options.profile.validate(request.capabilityRef, request.input, request.idempotencyKey, { deferPrecondition: true });
                 const invocation = await options.createInvocation(request);
                 if (invocation.actorId !== request.ctx.principal.sub)
                     throw new ArtifactProfileInputError();
@@ -102,7 +121,7 @@ export function createArtifactsAdapter(options) {
             catch (cause) {
                 outcome = rejected(cause, request.ctx.requestId, request.capabilityRef, options.mapHostError);
             }
-            return projectArtifactMcpOutcome(outcome, request.ctx.auditId);
+            return projectArtifactMcpOutcome(outcome, request.ctx.auditId, options.profile.resultEnvelopeVersion ?? 1);
         },
         readResource: async (request) => ({ ok: false, auditId: request.ctx.auditId, redactionClass: 'low',
             error: { code: 'not_found', message: 'not_found', retriable: false } }),

package/dist/profile/contracts.d.ts

@@ -1,7 +1,7 @@
 import type { JsonValue } from '../contracts.js';
 import type { EffectiveArtifactCommand } from '../server/command-identity.js';
 export declare const PROFILE_CONTRACT_VERSION: "artifacts-profile/v1";
-export declare const ARTIFACT_CAPABILITY_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 ARTIFACT_CAPABILITY_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 ArtifactCapabilityName = (typeof ARTIFACT_CAPABILITY_NAMES)[number];
 export type ArtifactSchema = Readonly<Record<string, unknown>>;
 export interface OperationProfile {
@@ -22,6 +22,12 @@ export interface ArtifactProfileRules {
     readonly mimeTypes: readonly string[];
 }
 export interface ArtifactProviderProfile {
+    /** Trusted public contract revision; independent from the host policy revision. */
+    readonly profileRevisionId?: string;
+    /** Explicit projection switchover; omitted profiles retain the v1 wire shape. */
+    readonly resultEnvelopeVersion?: 1 | 2;
+    /** Require caller-supplied CAS preconditions on every publication writer. */
+    readonly requireExpectedCurrentReleaseId?: boolean;
     readonly version: typeof PROFILE_CONTRACT_VERSION;
     readonly selectedCapabilities: readonly string[];
     readonly operations: readonly OperationProfile[];
@@ -42,7 +48,9 @@ export interface CompiledArtifactsProfile extends EffectiveArtifactProfile {
         readonly required: true;
         readonly scope: 'principal';
     }>>>;
-    validate(name: string, args: unknown, envelopeKey?: string): Readonly<Record<string, JsonValue>>;
+    validate(name: string, args: unknown, envelopeKey?: string, options?: {
+        deferPrecondition: true;
+    }): Readonly<Record<string, JsonValue>>;
     assertSelected(name: string): asserts name is ArtifactCapabilityName;
     capabilityForRoute(method: string, path: string): ArtifactCapabilityName | undefined;
 }
@@ -53,15 +61,17 @@ export interface CompiledValidators {
     readonly normalizeCommand: (command: unknown) => EffectiveArtifactCommand;
 }
 /** Projection fields are data-only; invocation correlation is added by L6. */
+export declare const PRECONDITION_REQUIRED_MESSAGE = "expectedCurrentReleaseId is required by the active artifact profile. Re-read this artifact with artifacts_get or artifacts_list, then send expectedCurrentReleaseId using the currentReleaseId returned by that read. Send null only if the read confirms that there is no current release. Before editing an existing release, read it with artifacts_get_source and use that releaseId. The server will not infer this value.";
 export declare class ArtifactProfileInputError extends Error {
+    readonly details?: Record<string, unknown> | undefined;
     readonly kind: 'operational' | 'ordinary';
     readonly status: number;
     readonly httpStatus: number;
-    readonly variant: 'unselected_operation' | 'invalid_request';
+    readonly variant: 'unselected_operation' | 'invalid_request' | 'precondition_required';
     readonly publicCode: string;
-    readonly category: 'invalid_request' | 'capability_unselected';
+    readonly category: 'invalid_request' | 'capability_unselected' | 'precondition_required';
     readonly retriable = false;
     readonly phase: 'selection' | 'entry';
     readonly commitState = "not_committed";
-    constructor(unselected?: boolean);
+    constructor(unselected?: boolean, preconditionRequired?: boolean, details?: Record<string, unknown> | undefined);
 }