@sentropic/artifacts 0.2.5 → 0.2.7

package/dist/server/edits.js

@@ -0,0 +1,43 @@
+/**
+ * Parity P0 — small old/new edits on publish.
+ *
+ * Edits apply to the current release's text files without resending the
+ * whole file set. `oldStr` must occur exactly once in the file text; any
+ * other count (or an unknown/non-text path) raises a typed `edit_mismatch`
+ * before anything is staged, so a failed call changes nothing. The edited
+ * files then become the new release through the same commit path.
+ */
+import { ArtifactOperationError } from './failures.js';
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = haystack.indexOf(needle, index + Math.max(1, needle.length));
+    }
+    return count;
+}
+/**
+ * Apply edits to a copy of the file list. Throws ArtifactOperationError
+ * ('edit_mismatch') on the first violation; the input files are never mutated.
+ */
+export function applyEdits(files, edits) {
+    const result = files.map((file) => ({ ...file }));
+    for (const [editIndex, edit] of edits.entries()) {
+        const file = result.find((entry) => entry.path === edit.path);
+        if (file === undefined || file.text === undefined) {
+            throw new ArtifactOperationError('edit_mismatch', { edit: { path: edit.path, occurrences: -1,
+                    editIndex, reason: file === undefined ? 'file_missing' : 'not_text' } });
+        }
+        const occurrences = countOccurrences(file.text, edit.oldStr);
+        if (occurrences !== 1) {
+            throw new ArtifactOperationError('edit_mismatch', { edit: { path: edit.path, occurrences,
+                    editIndex, reason: occurrences === 0 ? 'missing' : 'ambiguous' } });
+        }
+        file.text = file.text.slice(0, file.text.indexOf(edit.oldStr)) + edit.newStr +
+            file.text.slice(file.text.indexOf(edit.oldStr) + edit.oldStr.length);
+    }
+    return result;
+}

package/dist/server/failures.d.ts

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

package/dist/server/failures.js

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

package/dist/server/lifecycle.d.ts

@@ -55,6 +55,8 @@ export interface LifecycleService {
     listReleases(artifactId: string): Promise<string[]>;
     /** Track a published release so promotion sees it (idempotent). */
     trackRelease(artifactId: string, releaseId: string): Promise<void>;
+    /** Per-release lifecycle state (ready/retired/purged; ready when untracked). */
+    getReleaseState(releaseId: string): Promise<ReleaseState>;
 }
 /** Create a lifecycle service over an injected store (mutations owner-only). */
 export declare function createLifecycleService(store: LifecycleStore, clock?: () => string, current?: CurrentPointer, claims?: DeletionClaimStore): LifecycleService;

package/dist/server/lifecycle.js

@@ -98,6 +98,9 @@ export function createLifecycleService(store, clock = () => new Date().toISOStri
         async stateOf(artifactId) {
             return store.getArtifactState(artifactId);
         },
+        async getReleaseState(releaseId) {
+            return store.getReleaseState(releaseId);
+        },
         canRead(artifact, acl, actorId, action = 'read', isApproved = () => false) {
             if (artifact.state === 'deleted' || artifact.state === 'purged')
                 return false;

package/dist/server/management.d.ts

@@ -42,4 +42,5 @@ export declare function manageArtifact(deps: {
     readPolicyRevision(): Promise<string>;
     isApprovedPrincipal(principalId: string): boolean | Promise<boolean>;
     confirmation?: ArtifactConfirmationPort;
+    validateNewCommand?(): void;
 }, invocation: ArtifactInvocationContext, command: EffectiveArtifactCommand, proof?: string): Promise<ArtifactOutcome<unknown>>;

package/dist/server/management.js

@@ -26,7 +26,7 @@ export async function manageArtifact(deps, invocation, command, proof) {
             throw refused('access_denied');
         return target;
     };
-    const result = await deps.coordinator.finalizePrepared({
+    const request = {
         ...command.identity, scopeId: invocation.storageScopeId, actorId: invocation.actorId,
         invocationId: invocation.invocationId, operation: command.operation, artifactId,
         policyRevision: await deps.readPolicyRevision(), receiptData: receipt,
@@ -41,6 +41,9 @@ export async function manageArtifact(deps, invocation, command, proof) {
                 throw refused('gone');
             const now = new Date().toISOString();
             if (deleting) {
+                // Bind omitted v1 input to the locked confirmation context, without rewriting the command.
+                if (!Object.hasOwn(command.payload, 'expectedCurrentReleaseId'))
+                    context.expectedCurrentReleaseId = target.currentReleaseId;
                 if (target.currentReleaseId !== context.expectedCurrentReleaseId) {
                     if (proof)
                         throw confirmationFailure('confirmation_stale');
@@ -73,7 +76,11 @@ export async function manageArtifact(deps, invocation, command, proof) {
             return invocation.authorizeCommit(ctx, tx);
         },
         validateReplayReceipt: (stored) => stored.receipt?.artifactId === artifactId,
-    });
+    };
+    const replay = await deps.coordinator.findReplayPrepared(request);
+    if (replay === undefined)
+        deps.validateNewCommand?.();
+    const result = replay ?? await deps.coordinator.finalizePrepared(request);
     return result.ok ? { ...result, result: result.result.receipt }
         : { ok: false, failure: { ...result.failure, kind: 'operational' } };
 }

package/dist/server/mime.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Canonical text-mime pattern shared by publication input rules and source
+ * reads. Leaf module: both `http.ts` and `server/source-read.ts` import it
+ * without an import cycle.
+ */
+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 declare const TEXT_MIME_RE: RegExp;

package/dist/server/mime.js

@@ -0,0 +1,7 @@
+/**
+ * Canonical text-mime pattern shared by publication input rules and source
+ * reads. Leaf module: both `http.ts` and `server/source-read.ts` import it
+ * without an import cycle.
+ */
+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 const TEXT_MIME_RE = new RegExp(TEXT_MIME_PATTERN);

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

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

package/dist/server/outcome-projection.js

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

package/dist/server/publication.d.ts

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

package/dist/server/publication.js

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

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

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

package/dist/server/result-schema.js

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

package/dist/server/service.d.ts

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

package/dist/server/service.js

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

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

@@ -11,6 +11,11 @@ export interface SourceReadPorts {
         stableUrl: string;
         pinnedUrl: string;
     };
+    /** Guide reference returned instead of embedding the guide body. */
+    guideRef?: {
+        tool: string;
+        version: string;
+    };
     maxFiles: number;
     maxTotalBytes: number;
 }
@@ -27,12 +32,27 @@ export declare function readArtifactSource(ports: SourceReadPorts, input: Source
     releaseId: string;
     digest: string;
     manifest: string;
-    files: {
-        bytes: number[];
+    files: ({
+        text: string;
+        encoding: "utf8";
+        path: string;
+        mimeType: string;
+        digest: string;
+        size: number;
+    } | {
+        base64: string;
+        encoding: "base64";
         path: string;
         mimeType: string;
         digest: string;
         size: number;
-    }[];
+    })[];
     sourceRef: SourceRef | null;
+    guideRef: {
+        readonly tool: "artifacts_get_api_guide";
+        readonly version: "v1";
+    } | {
+        tool: string;
+        version: string;
+    };
 }>;