@sentropic/artifacts 0.2.3 → 0.2.5

package/dist/mcp-core.js

@@ -6,7 +6,7 @@ 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.3';
+export const ARTIFACTS_PROVIDER_VERSION = '0.2.5';
 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('_', ' ')}.`,
@@ -29,7 +29,7 @@ export function createArtifactsManifest(options) {
             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.
@@ -64,6 +64,15 @@ 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;
                 default: throw new ArtifactProfileInputError(true);
             }
             return await deps.app.execute({ ...request, actorId: input.invocation.actorId,

package/dist/profile/index.js

@@ -79,7 +79,7 @@ export function compileArtifactsProfile(input) {
             if (!Object.hasOwn(props, key) || !matchesSchema(value, props[key]))
                 throw new Error('profile/schema default mismatch');
         }
-        if (name === 'artifacts_ensure' || name === 'artifacts_publish' || name === 'artifacts_commit_upload') {
+        if (['artifacts_ensure', 'artifacts_publish', 'artifacts_commit_upload', 'artifacts_set_access', 'artifacts_delete'].includes(name)) {
             idempotency[name] = { required: true, scope: 'principal' };
         }
     }
@@ -106,6 +106,12 @@ export function compileArtifactsProfile(input) {
                 name = 'artifacts_publish';
             if (method === 'POST' && path === '/list')
                 name = 'artifacts_list';
+            if (method === 'POST' && path === '/get_source')
+                name = 'artifacts_get_source';
+            if (method === 'POST' && path === '/set_access')
+                name = 'artifacts_set_access';
+            if (method === 'POST' && path === '/delete')
+                name = 'artifacts_delete';
             if (method === 'GET' && path.startsWith('/meta/') && isArtifactId(path.slice(6)))
                 name = 'artifacts_get';
             return name && selectedCapabilities.includes(name) ? name : undefined;

package/dist/profile/schemas.js

@@ -14,6 +14,8 @@ export function assertCompleteOperation(config) {
                 'maxDecodedFileBytes', 'maxDecodedTotalBytes'], defaults: ['profile'] },
         list: { limits: ['listLimitMin', 'listLimitMax'], defaults: ['limit', 'offset'] },
         commit_upload: { limits: ['idempotencyKeyMaxUnits'], defaults: ['profile'] },
+        set_access: { limits: ['idempotencyKeyMaxUnits'], defaults: [] },
+        delete: { limits: ['idempotencyKeyMaxUnits'], defaults: [] },
     };
     const fields = required[config.operation];
     if (fields && (fields.limits.some((key) => !Object.hasOwn(config.limits, key)) ||
@@ -58,18 +60,23 @@ export function capabilitySchema(name, profile) {
         case 'list': return obj({ limit: { ...integer(limits.listLimitMin, limits.listLimitMax), default: config.defaults.limit },
             offset: { ...integer(0), default: config.defaults.offset } });
         case 'get':
-        case 'get_source':
         case 'fork':
         case 'renew':
-        case 'delete':
         case 'restore': return idOnly;
+        case 'get_source': return obj({ artifactId: id, releaseId: id,
+            paths: { type: 'array', minItems: 1, maxItems: 32, items: { ...str, maxLength: profile.rules.pathMaxBytes } } }, ['artifactId']);
+        case 'delete': return obj({ artifactId: id, expectedCurrentReleaseId: { ...id, type: ['string', 'null'] },
+            idempotencyKey: key, confirmationRef: { ...str, maxLength: 4096 } }, ['artifactId', 'expectedCurrentReleaseId', 'idempotencyKey']);
         case 'get_template': return obj({ templateId: str }, ['templateId']);
         case 'get_api_guide': return obj({ version: str });
         case 'create_upload': return obj({ artifactId: id, mimeType: str, maxSize: integer(1) }, ['artifactId', 'mimeType']);
         case 'commit_upload': return obj({ artifactId: id, uploadId: str, path: str, mimeType: str,
             digest: str, size: integer(0), profile: primitiveRecord, idempotencyKey: key }, ['artifactId', 'uploadId', 'path', 'mimeType', 'digest', 'size', 'idempotencyKey']);
-        case 'set_access': return obj({ artifactId: id, action: { type: 'string', enum: ['grant', 'revoke', 'set-public'] },
-            principalId: str, grant: { type: 'string', enum: ['read', 'source'] }, isPublic: { type: 'boolean' } }, ['artifactId', 'action']);
+        case 'set_access': return { ...obj({ artifactId: id, action: { type: 'string', enum: ['grant', 'revoke'] },
+                principalId: { ...str, maxLength: 256 }, grant: { type: 'string', enum: ['read'] }, idempotencyKey: key }, ['artifactId', 'action', 'principalId', 'idempotencyKey']), oneOf: [
+                { properties: { action: { enum: ['grant'] } }, required: ['grant'] },
+                { properties: { action: { enum: ['revoke'] } }, not: { required: ['grant'] } },
+            ] };
         case 'promote': return obj({ artifactId: id, releaseId: id, expectedCurrent: id }, ['artifactId', 'releaseId', 'expectedCurrent']);
         default: throw new Error(`unsupported operation profile: ${operation}`);
     }

package/dist/profile/validation.js

@@ -78,7 +78,7 @@ export function normalizeArguments(profile, name, input, schema, envelopeKey) {
     const operation = name.slice('artifacts_'.length);
     const { defaults, limits } = operationProfile(profile, operation);
     const normalized = { ...copyJson(defaults), ...args };
-    if (operation === 'ensure' || operation === 'publish' || operation === 'commit_upload') {
+    if (['ensure', 'publish', 'commit_upload', 'set_access', 'delete'].includes(operation)) {
         const key = args.idempotencyKey;
         requireInput(typeof key === 'string' && key.trim().length > 0 && key.length <= limits.idempotencyKeyMaxUnits);
         requireInput(envelopeKey === undefined || envelopeKey === key);
@@ -87,6 +87,10 @@ export function normalizeArguments(profile, name, input, schema, envelopeKey) {
         requireInput(envelopeKey === undefined);
     if (Object.hasOwn(args, 'artifactId'))
         requireInput(isArtifactId(args.artifactId));
+    if (operation === 'get_source' && args.paths !== undefined) {
+        const paths = args.paths;
+        requireInput(new Set(paths).size === paths.length && paths.every((path) => Buffer.byteLength(path, 'utf8') <= profile.rules.pathMaxBytes));
+    }
     if (operation === 'publish') {
         const paths = new Set();
         let total = 0;

package/dist/server/access.d.ts

@@ -16,6 +16,12 @@ export interface GrantRecord {
     grant: AccessGrant;
 }
 export interface ArtifactAcl {
+    bindingName?: string;
+    createdAt?: string;
+    updatedAt?: string | null;
+    title?: string;
+    description?: string;
+    icon?: string | null;
     ownerId: string;
     /** Physical scope of the artifact (set at creation; read by publish). */
     storageScopeId?: string;

package/dist/server/command-identity.d.ts

@@ -8,13 +8,14 @@ export type CallerIdempotencyKey = string & {
 export type InternalIdempotencyKey = string & {
     readonly __brand: 'internal-key';
 };
+export type ArtifactCommandOperation = 'ensure' | 'publish' | 'set_access' | 'delete';
 export interface CommandIdentity {
     readonly internalKey: InternalIdempotencyKey;
     readonly commandHash: string;
     readonly codecVersion: typeof COMMAND_CODEC_VERSION;
 }
 export interface EffectiveArtifactCommand {
-    readonly operation: 'ensure' | 'publish';
+    readonly operation: ArtifactCommandOperation;
     readonly scopeBinding: string;
     readonly payload: Readonly<Record<string, JsonValue>>;
     readonly provenance: {
@@ -29,7 +30,7 @@ export interface ArtifactCommandAuthority {
 export interface ArtifactKeyDerivationBinding {
     readonly algorithm: string;
     derive(input: ArtifactCommandAuthority & {
-        readonly operation: 'ensure' | 'publish';
+        readonly operation: ArtifactCommandOperation;
         readonly objectId: string;
         readonly callerKey: CallerIdempotencyKey;
     }): InternalIdempotencyKey;

package/dist/server/command-identity.js

@@ -20,7 +20,7 @@ export function createRadarKeyDerivation(config) {
             if (other === actor || !other.startsWith(`${actor}|`))
                 continue;
             const [operation, objectId] = other.slice(actor.length + 1).split('|');
-            if ((operation === 'ensure' && objectId === '') || (operation === 'publish' && isArtifactId(objectId))) {
+            if ((operation === 'ensure' && objectId === '') || (['publish', 'set_access', 'delete'].includes(operation) && isArtifactId(objectId))) {
                 throw new Error('ambiguous Radar actor domain');
             }
         }
@@ -30,7 +30,7 @@ export function createRadarKeyDerivation(config) {
         derive(input) {
             const { storageScopeId, actorId, operation, objectId, callerKey } = input;
             if (storageScopeId !== scope || !actors.has(actorId) ||
-                (operation !== 'ensure' && operation !== 'publish') ||
+                !['ensure', 'publish', 'set_access', 'delete'].includes(operation) ||
                 (operation === 'ensure' ? objectId !== '' : !isArtifactId(objectId)))
                 throw new ArtifactProfileInputError();
             assertWellFormed(callerKey);
@@ -48,10 +48,10 @@ export function createArtifactCommand(profile, name, args, authority, derivation
     if (derivation.algorithm !== profile.profile.rules.keyDerivationAlgorithm)
         throw new Error('profile/derivation mismatch');
     const normalized = profile.validate(name, args, envelopeKey);
-    if (name !== 'artifacts_ensure' && name !== 'artifacts_publish')
+    if (!['artifacts_ensure', 'artifacts_publish', 'artifacts_set_access', 'artifacts_delete'].includes(name))
         throw new ArtifactProfileInputError(true);
-    const operation = name === 'artifacts_ensure' ? 'ensure' : 'publish';
-    const { idempotencyKey, ...payload } = normalized;
+    const operation = name.slice('artifacts_'.length);
+    const { idempotencyKey, confirmationRef: _proof, ...payload } = normalized;
     const scopeBinding = authority.storageScopeId;
     if (typeof scopeBinding !== 'string' || typeof authority.actorId !== 'string')
         throw new ArtifactProfileInputError();
@@ -62,7 +62,7 @@ export function createArtifactCommand(profile, name, args, authority, derivation
     const provenance = { kind: 'inline-original' };
     const effective = copyJson({ operation, scopeBinding, payload: { ...payload, provenance } });
     const internalKey = derivation.derive({ storageScopeId: scopeBinding, actorId: authority.actorId, operation,
-        objectId: operation === 'publish' ? normalized.artifactId : '',
+        objectId: operation === 'ensure' ? '' : normalized.artifactId,
         callerKey: idempotencyKey });
     if (!/^[0-9a-f]{64}$/.test(internalKey) || !derivation.algorithm)
         throw new Error('invalid key derivation binding');

package/dist/server/commit/coordinator.js

@@ -285,7 +285,7 @@ export function createArtifactCommitCoordinator(options) {
                     (input.storageScopeId !== request.scopeId || input.bytes !== bytes)) ||
                     ('actorId' in input && input.actorId !== request.actorId))
                     return Promise.resolve({ reserved: false });
-                if (purpose === 'replay')
+                if (purpose === 'replay' || ['set_access', 'delete'].includes(request.operation))
                     return Promise.resolve({ reserved: true });
                 return reservation ??= raw.reserveQuota({ actorId: request.actorId, operation: request.operation,
                     storageScopeId: request.scopeId, bytes });

package/dist/server/failures.d.ts

@@ -4,9 +4,10 @@ export type ArtifactCommitState = 'not_committed' | 'committed' | 'unknown';
 export type ArtifactInternalKey = string & {
     readonly __brand: 'internal-key';
 };
-export type ArtifactErrorKind = 'provider_unavailable' | 'command_conflict' | 'pointer_conflict' | 'unauthorized_at_commit' | 'capability_unselected' | 'admission_unavailable' | 'invalid_request' | 'anonymous' | 'access_denied' | 'not_found' | 'gone' | 'unprocessable' | 'verification_failed';
+export type ArtifactErrorKind = 'provider_unavailable' | 'command_conflict' | 'pointer_conflict' | 'unauthorized_at_commit' | 'capability_unselected' | 'admission_unavailable' | 'invalid_request' | 'anonymous' | 'access_denied' | 'not_found' | 'gone' | 'release_unavailable' | 'limit_exceeded' | 'unprocessable' | 'verification_failed';
 export type ArtifactFailureCategory = ArtifactFailure['category'];
 interface ArtifactFailureFields {
+    readonly details?: Readonly<Record<string, unknown>>;
     readonly variant?: string;
     readonly httpStatus: number;
     readonly publicCode: string;
@@ -24,7 +25,7 @@ export interface ArtifactOperationalFailure extends ArtifactFailureFields {
 }
 export interface ArtifactOrdinaryFailure extends Omit<ArtifactFailureFields, 'variant' | 'retriable'> {
     readonly kind: 'ordinary';
-    readonly category: 'invalid_request' | 'not_found' | 'gone' | 'unprocessable' | 'verification_failed';
+    readonly category: 'invalid_request' | 'not_found' | 'gone' | 'release_unavailable' | 'limit_exceeded' | 'unprocessable' | 'verification_failed';
     readonly retriable: false;
 }
 /** Entry authority outcomes are separate from ordinary and operational failures. */
@@ -65,10 +66,12 @@ export declare class ArtifactOperationError extends Error {
     readonly details: {
         readonly cause?: unknown;
         readonly refusal?: ArtifactPublicRefusal;
+        readonly publicDetails?: Readonly<Record<string, unknown>>;
     };
     constructor(kind: ArtifactErrorKind, details?: {
         readonly cause?: unknown;
         readonly refusal?: ArtifactPublicRefusal;
+        readonly publicDetails?: Readonly<Record<string, unknown>>;
     });
 }
 /** Mint only at verified per-key row contention, using the full scoped operation key. */

package/dist/server/failures.js

@@ -28,7 +28,7 @@ const UNAVAILABLE_CODES = new Set([
 const TIMEOUT_NAMES = new Set(['TimeoutError', 'RequestTimeout', 'RequestTimeoutError']);
 const DOMAIN_STATUS = {
     invalid_request: 400, anonymous: 401, access_denied: 403,
-    not_found: 404, gone: 410, unprocessable: 422, verification_failed: 422,
+    not_found: 404, gone: 410, release_unavailable: 410, limit_exceeded: 413, unprocessable: 422, verification_failed: 422,
 };
 function field(value, name) {
     if (typeof value !== 'object' || value === null)
@@ -126,6 +126,9 @@ export function classifyArtifactFailure(cause, context, mapHostError) {
         projection = unavailable();
     const failure = {
         ...projection, invocationId: context.invocationId, operation: context.operation,
+        ...(cause instanceof ArtifactOperationError && cause.details.publicDetails &&
+            ['confirmation_required', 'confirmation_invalid', 'confirmation_expired', 'confirmation_stale', 'release_unavailable'].includes(projection.publicCode)
+            ? { details: cause.details.publicDetails } : {}),
         phase: context.phase, commitState: context.commitState, cause,
     };
     Object.defineProperty(failure, 'cause', { value: cause, enumerable: false });

package/dist/server/lifecycle.d.ts

@@ -12,6 +12,8 @@ export type ArtifactState = 'active' | 'withdrawn' | 'deleted' | 'purged';
 /** Release states use `ready` (not `active`) to match the releases table. */
 export type ReleaseState = 'ready' | 'retired' | 'purged';
 export interface LifecycleStore {
+    isTerminal(artifactId: string): Promise<boolean>;
+    markTerminal(artifactId: string): Promise<void>;
     register(artifactId: string, ownerId: string): Promise<void>;
     getOwner(artifactId: string): Promise<string | undefined>;
     getArtifactState(artifactId: string): Promise<ArtifactState>;

package/dist/server/lifecycle.js

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

package/dist/server/management.d.ts

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

package/dist/server/management.js

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

package/dist/server/outcome-projection.js

@@ -1,7 +1,8 @@
 export function projectArtifactHttpOutcome(outcome) {
     if (outcome.ok)
         return outcome.result;
-    return { status: outcome.failure.httpStatus, body: { error: outcome.failure.publicCode } };
+    return { status: outcome.failure.httpStatus, body: { error: outcome.failure.publicCode,
+            ...(outcome.failure.details ? { details: outcome.failure.details } : {}) } };
 }
 /** Feed this application result to mcp-platform's existing result codec. No second wire protocol. */
 export function projectArtifactMcpOutcome(outcome, auditId) {
@@ -10,7 +11,8 @@ export function projectArtifactMcpOutcome(outcome, auditId) {
     const { publicCode, retriable } = outcome.failure;
     return {
         ok: false, auditId, redactionClass: 'low',
-        error: { code: publicCode, message: publicCode, retriable },
+        error: { code: publicCode, message: publicCode, retriable,
+            ...(outcome.failure.details ? { details: outcome.failure.details } : {}) },
     };
 }
 /**

package/dist/server/publication.d.ts

@@ -4,7 +4,7 @@ import type { IdempotencyStore } from './idempotency.js';
 import { type SourceRef, type SourceStore } from './sources.js';
 import { type PublicationLimits } from './publication-limits.js';
 import type { ArtifactAcl } from './access.js';
-import type { ArtifactState } from './lifecycle.js';
+import type { 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';
@@ -14,7 +14,7 @@ export interface ReleaseRecord {
     artifactId: string;
     manifestDigest: string;
     manifest: string;
-    state: 'ready';
+    state: ReleaseState;
     createdAt: string;
 }
 export interface PublicationStateStore {
@@ -61,14 +61,8 @@ export interface PublicationService {
     readonly limits?: Readonly<PublicationLimits>;
     /** The host source store participates in the idempotent commit when a source is supplied. */
     publish(input: PublishInput, sources?: SourceStore): Promise<PublishResult>;
-    getCurrent(artifactId: string): Promise<{
-        releaseId: string;
-        manifest: string;
-    } | undefined>;
-    getRelease(releaseId: string): Promise<{
-        releaseId: string;
-        manifest: string;
-    } | undefined>;
+    getCurrent(artifactId: string): Promise<ReleaseRecord | undefined>;
+    getRelease(releaseId: string): Promise<ReleaseRecord | undefined>;
 }
 /** Create a publication service over injected stores (no driver imports). */
 export declare function createPublicationService(deps: {

package/dist/server/publication.js

@@ -168,13 +168,13 @@ export function createPublicationService(deps) {
             const release = await deps.state.getRelease(releaseId);
             if (release === undefined)
                 return undefined;
-            return { releaseId: release.releaseId, manifest: release.manifest };
+            return release;
         },
         async getRelease(releaseId) {
             const release = await deps.state.getRelease(releaseId);
             if (release === undefined)
                 return undefined;
-            return { releaseId: release.releaseId, manifest: release.manifest };
+            return release;
         },
     };
 }

package/dist/server/source-read.d.ts

@@ -0,0 +1,38 @@
+import type { SourceRef } from './sources.js';
+import type { PublicationService } from './publication.js';
+export interface SourceReadPorts {
+    storageScopeId?: string;
+    authorize(): Promise<void>;
+    getCurrent: PublicationService['getCurrent'];
+    getRelease: PublicationService['getRelease'];
+    getSource(artifactId: string): Promise<SourceRef | undefined>;
+    getBlob(key: string): Promise<Uint8Array | undefined>;
+    urls?: (artifactId: string, releaseId: string) => {
+        stableUrl: string;
+        pinnedUrl: string;
+    };
+    maxFiles: number;
+    maxTotalBytes: number;
+}
+export interface SourceReadInput {
+    artifactId: string;
+    releaseId?: string;
+    paths?: readonly string[];
+}
+/** Read author bytes only. Provenance never substitutes for a stored snapshot. */
+export declare function readArtifactSource(ports: SourceReadPorts, input: SourceReadInput): Promise<{
+    stableUrl?: string | undefined;
+    pinnedUrl?: string | undefined;
+    artifactId: string;
+    releaseId: string;
+    digest: string;
+    manifest: string;
+    files: {
+        bytes: number[];
+        path: string;
+        mimeType: string;
+        digest: string;
+        size: number;
+    }[];
+    sourceRef: SourceRef | null;
+}>;

package/dist/server/source-read.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { parseManifest } from '../codecs.js';
+import { ArtifactOperationError } from './failures.js';
+/** Read author bytes only. Provenance never substitutes for a stored snapshot. */
+export async function readArtifactSource(ports, input) {
+    await ports.authorize();
+    const release = input.releaseId === undefined ? await ports.getCurrent(input.artifactId)
+        : await ports.getRelease(input.releaseId);
+    if (!release)
+        throw input.releaseId ? new ArtifactOperationError('not_found')
+            : new ArtifactOperationError('release_unavailable', { publicDetails: { reason: 'unpublished' } });
+    if ((input.releaseId !== undefined && release.releaseId !== input.releaseId) ||
+        release.artifactId !== input.artifactId)
+        throw new ArtifactOperationError('not_found');
+    let manifest;
+    try {
+        manifest = parseManifest(release.manifest);
+    }
+    catch (cause) {
+        throw new ArtifactOperationError('verification_failed', { cause });
+    }
+    if (manifest.artifactId !== input.artifactId)
+        throw new ArtifactOperationError('not_found');
+    if (ports.storageScopeId !== undefined && manifest.storageScopeId !== ports.storageScopeId)
+        throw new ArtifactOperationError('verification_failed');
+    if (release.manifestDigest !== manifest.digest)
+        throw new ArtifactOperationError('verification_failed');
+    if (release.state === 'purged')
+        throw new ArtifactOperationError('release_unavailable', { publicDetails: { reason: 'purged' } });
+    if (!manifest.digest || !Array.isArray(manifest.files) || manifest.files.length > ports.maxFiles) {
+        throw new ArtifactOperationError('verification_failed');
+    }
+    const entries = [];
+    const paths = new Set();
+    let total = 0;
+    for (const value of manifest.files) {
+        const file = value;
+        if (!file || typeof file.path !== 'string' || typeof file.mimeType !== 'string' ||
+            !/^sha256:[0-9a-f]{64}$/.test(file.digest) || !Number.isSafeInteger(file.size) || file.size < 0 ||
+            paths.has(file.path))
+            throw new ArtifactOperationError('verification_failed');
+        total += file.size;
+        if (total > ports.maxTotalBytes)
+            throw new ArtifactOperationError('limit_exceeded');
+        paths.add(file.path);
+        entries.push(file);
+    }
+    if (input.paths !== undefined && (!input.paths.length || input.paths.length > ports.maxFiles ||
+        new Set(input.paths).size !== input.paths.length || input.paths.some((path) => !paths.has(path)))) {
+        throw new ArtifactOperationError('invalid_request');
+    }
+    const selected = input.paths === undefined ? entries : entries.filter((file) => input.paths.includes(file.path));
+    const files = [];
+    for (const file of selected) {
+        const bytes = await ports.getBlob(`artifacts/${manifest.storageScopeId}/blobs/sha256/${file.digest.slice(7)}`);
+        if (!bytes)
+            throw new ArtifactOperationError('release_unavailable', { publicDetails: { reason: 'not_retained' } });
+        if (bytes.length !== file.size ||
+            createHash('sha256').update(bytes).digest('hex') !== file.digest.slice(7)) {
+            throw new ArtifactOperationError('verification_failed');
+        }
+        files.push({ ...file, bytes: Array.from(bytes) });
+    }
+    const sourceRef = await ports.getSource(input.artifactId) ?? null;
+    await ports.authorize();
+    return { artifactId: input.artifactId, releaseId: release.releaseId, digest: manifest.digest,
+        manifest: release.manifest, files, sourceRef, ...ports.urls?.(input.artifactId, release.releaseId) };
+}