@sentropic/artifacts 0.1.4 → 0.2.1

package/dist/server/failures.js

@@ -0,0 +1,133 @@
+export class ArtifactOperationError extends Error {
+    kind;
+    details;
+    constructor(kind, details = {}) {
+        super(kind, { cause: details.cause });
+        this.kind = kind;
+        this.details = details;
+        this.name = 'ArtifactOperationError';
+    }
+}
+/** Mint only at verified per-key row contention, using the full scoped operation key. */
+export class ArtifactKeyLockConflict extends Error {
+    storageScopeId;
+    operationKey;
+    constructor(storageScopeId, operationKey, cause) {
+        super('artifact key lock contention', { cause });
+        this.storageScopeId = storageScopeId;
+        this.operationKey = operationKey;
+        this.name = 'ArtifactKeyLockConflict';
+    }
+}
+const UNAVAILABLE_CODES = new Set([
+    'artifact_connection_lost', '57P06', '55P03', 'lock_timeout', '40001', '40P01', '57014',
+    'ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'ENETUNREACH', 'EHOSTUNREACH',
+    'ENOTFOUND', 'EAI_AGAIN', 'ERR_STREAM_PREMATURE_CLOSE',
+    'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'UND_ERR_SOCKET',
+]);
+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,
+};
+function field(value, name) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    // Unknown thrown objects can have getters; inspection must not replace the original failure.
+    try {
+        return value[name];
+    }
+    catch {
+        return undefined;
+    }
+}
+function chain(cause) {
+    const seen = new Set();
+    const values = [];
+    for (let current = cause; current !== undefined && !seen.has(current); current = field(current, 'cause')) {
+        seen.add(current);
+        values.push(current);
+    }
+    return values;
+}
+const unavailable = (category = 'provider_unavailable') => {
+    const fields = { httpStatus: 503, publicCode: 'capability_unavailable', retriable: true };
+    return category === 'admission_unavailable'
+        ? { ...fields, kind: 'admission', category, variant: 'entry_outage' }
+        : { ...fields, kind: 'operational', category, variant: 'dispatch_failure' };
+};
+const conflict = (variant = 'key_contention') => ({ kind: 'operational', category: 'conflict', variant, httpStatus: 409, publicCode: 'conflict', retriable: false });
+const internal = () => ({ kind: 'operational', category: 'provider_error', variant: 'unclassified', httpStatus: 500, publicCode: 'internal_error', retriable: false });
+function operationProjection(error) {
+    const { kind } = error;
+    switch (kind) {
+        case 'provider_unavailable':
+        case 'admission_unavailable': return unavailable(kind);
+        case 'command_conflict':
+        case 'pointer_conflict': return conflict(kind);
+        case 'capability_unselected': return {
+            kind: 'operational', category: kind, variant: 'unselected_operation',
+            httpStatus: 503, publicCode: 'capability_unavailable', retriable: false,
+        };
+        case 'unauthorized_at_commit': {
+            const refusal = error.details.refusal ?? { allowed: false, reason: 'denied', status: 403, publicCode: 'access_denied', retriable: false };
+            // Stable host-approved codes only; a malformed mapping never exposes its text.
+            if (!Number.isInteger(refusal.status) || refusal.status < 400 || refusal.status > 599
+                || !/^[a-z][a-z0-9_]{0,63}$/.test(refusal.publicCode))
+                return internal();
+            const authorityUnavailable = refusal.reason === 'unavailable' && refusal.status === 503;
+            return {
+                kind: 'operational', category: kind, httpStatus: refusal.status,
+                variant: authorityUnavailable ? 'authority_unavailable' : 'policy_denial',
+                publicCode: refusal.status === 503 ? 'capability_unavailable' : refusal.publicCode,
+                retriable: authorityUnavailable,
+            };
+        }
+        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 };
+    }
+}
+function classify(cause, context, mapHostError) {
+    for (const current of chain(cause)) {
+        if (current instanceof ArtifactOperationError)
+            return operationProjection(current);
+        if (current instanceof ArtifactKeyLockConflict
+            && context.phase === 'lock'
+            && /^[a-f0-9]{64}$/.test(current.operationKey)
+            && context.storageScopeId === current.storageScopeId
+            && context.operationKey === current.operationKey)
+            return conflict();
+        if (mapHostError !== undefined) {
+            try {
+                const mapped = mapHostError(current);
+                if (mapped instanceof ArtifactOperationError)
+                    return operationProjection(mapped);
+            }
+            catch {
+                return internal();
+            }
+        }
+        const code = field(current, 'code');
+        if (typeof code === 'string' && (UNAVAILABLE_CODES.has(code) || /^08[A-Z0-9]{3}$/.test(code)))
+            return unavailable();
+        const name = field(current, 'name');
+        if (current instanceof Error && typeof name === 'string' && TIMEOUT_NAMES.has(name))
+            return unavailable();
+    }
+    return internal();
+}
+/** Pure per-invocation classification. Cleanup errors must not replace the primary cause. */
+export function classifyArtifactFailure(cause, context, mapHostError) {
+    let projection = classify(cause, context, mapHostError);
+    // Monitoring after a proven commit cannot become a prevented finalization.
+    if (context.commitState === 'committed' && projection.category === 'unauthorized_at_commit')
+        projection = unavailable();
+    const failure = {
+        ...projection, invocationId: context.invocationId, operation: context.operation,
+        phase: context.phase, commitState: context.commitState, cause,
+    };
+    Object.defineProperty(failure, 'cause', { value: cause, enumerable: false });
+    return Object.freeze(failure);
+}

package/dist/server/gc.d.ts

@@ -1,3 +1,4 @@
+import type { CommitExecutor, FinalizeTxClient } from './commit/types.js';
 import { type PublicationBlobStore } from './publication.js';
 export interface RefcountStore {
     addRef(digest: string, holder: string): Promise<void>;
@@ -18,7 +19,47 @@ export interface GcReport {
     }[];
 }
 export interface GcService {
-    collect(blobs: PublicationBlobStore, prefix: string): Promise<GcReport>;
+    collect(blobs: PublicationBlobStore, prefix: string, claims: DeletionClaimStore): Promise<GcReport>;
+}
+/**
+ * Durable exclusive deletion claims (spec r2 A4/A6). Purge claims a digest
+ * before dereferencing it; reference creation MUST check the claim and
+ * refuse new references to claimed digests; erasure acknowledges the claim.
+ */
+export interface DeletionClaimStore {
+    /** Share this exclusion across claims, reference/pin creation and erasure. */
+    withDigestLock<T>(digest: string, action: (locked: DeletionClaimAccess) => Promise<T>): Promise<T>;
+    /** Exclusive claim; throws when the digest is already claimed. */
+    claim(digest: string, holder: string): Promise<void>;
+    /** Release the claim after the blob is gone (or the purge aborts). */
+    releaseClaim(digest: string): Promise<void>;
+    isClaimed(digest: string): Promise<boolean>;
+}
+type DeletionClaimAccess = Pick<DeletionClaimStore, 'claim' | 'releaseClaim' | 'isClaimed'>;
+export interface DeletionClaimRecord {
+    readonly claimId: string;
+    readonly digest: string;
+    readonly holder: string;
+    readonly state: 'pending' | 'done';
 }
+export interface InspectableDeletionClaimStore extends DeletionClaimStore {
+    listClaims(): Promise<DeletionClaimRecord[]>;
+}
+/** GC keeps the advisory lock's transaction open through deletion and claim completion. */
+export declare function createPostgresGcService(executor: CommitExecutor, refsForTransaction: (client: FinalizeTxClient) => RefcountStore): {
+    collect(blobs: PublicationBlobStore, prefix: string): Promise<GcReport>;
+};
+/** Short preparation transactions; no leased connection spans blob I/O. */
+export declare function createPostgresClaimGuardedRefs(refs: RefcountStore, executor: CommitExecutor): RefcountStore;
+/** Transaction-scoped claims; callers commit the claim before external deletion. */
+export declare function createPostgresDeletionClaimStore(client: FinalizeTxClient): InspectableDeletionClaimStore;
+export declare function createMemoryDeletionClaimStore(): InspectableDeletionClaimStore;
+/**
+ * A RefcountStore that refuses new references to claimed digests. Purge
+ * claims first, so racing publications cannot pin a blob scheduled for
+ * deletion; already-held references still protect the blob in collect.
+ */
+export declare function createClaimGuardedRefs(refs: RefcountStore, claims: DeletionClaimStore): RefcountStore;
 /** Create a GC service over an injected refcount store (no driver imports). */
 export declare function createGcService(refs: RefcountStore): GcService;
+export {};

package/dist/server/gc.js

@@ -7,8 +7,8 @@
  * throwing, so revoked access, pending purge and actual erasure stay
  * distinguishable. Reference updates serialize per digest (in-process
  * mutex); the memory double yields mid-update to simulate store latency so
- * races are genuinely exercised. Deleting state (refcounts vs purge) is
- * serialized by the caller: purge dereferences first, then collects.
+ * races are genuinely exercised. Collection claims and re-checks each
+ * digest under the exclusion shared with reference and pin creation.
  */
 import { createKeyMutex } from './ports.js';
 import { blobDigestOfKey } from './publication.js';
@@ -58,10 +58,155 @@ export function createMemoryRefcountStore() {
         },
     };
 }
+/** GC keeps the advisory lock's transaction open through deletion and claim completion. */
+export function createPostgresGcService(executor, refsForTransaction) {
+    return {
+        async collect(blobs, prefix) {
+            const client = await executor.beginFinalization();
+            let failure;
+            try {
+                const refs = refsForTransaction(client);
+                const claims = createPostgresDeletionClaimStore(client);
+                const report = await createGcService(refs).collect(blobs, prefix, claims);
+                await client.commit();
+                return report;
+            }
+            catch (error) {
+                failure = error;
+                try {
+                    await client.rollback();
+                }
+                catch (rollbackError) {
+                    failure = rollbackError;
+                }
+                throw error;
+            }
+            finally {
+                client.release(failure);
+            }
+        },
+    };
+}
+/** Short preparation transactions; no leased connection spans blob I/O. */
+export function createPostgresClaimGuardedRefs(refs, executor) {
+    const insert = async (digest, holder, sql) => {
+        const client = await executor.beginFinalization();
+        try {
+            await createPostgresDeletionClaimStore(client).withDigestLock(digest, async (claims) => {
+                if (await claims.isClaimed(digest))
+                    throw new Error(`blob scheduled for deletion: ${digest}`);
+                await client.query(sql, [digest, holder]);
+            });
+            await client.commit();
+        }
+        catch (error) {
+            await client.rollback();
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    };
+    return { ...refs,
+        addRef: (digest, holder) => insert(digest, holder, 'INSERT INTO artifacts.blob_ref_holders (digest, holder) VALUES ($1, $2) ON CONFLICT DO NOTHING'),
+        pin: (digest, reason) => insert(digest, reason, 'INSERT INTO artifacts.blob_pins (digest, reason) VALUES ($1, $2)'),
+    };
+}
+/** Transaction-scoped claims; callers commit the claim before external deletion. */
+export function createPostgresDeletionClaimStore(client) {
+    const predicate = `kind = 'delete-blob' AND state = 'pending'
+    AND payload->>'deletionClaim' = 'true' AND payload->>'digest' = $1`;
+    const access = {
+        async isClaimed(digest) {
+            const { rows } = await client.query(`SELECT EXISTS (SELECT 1 FROM artifacts.object_intents WHERE ${predicate}) AS present`, [digest]);
+            return rows[0]?.present === true;
+        },
+        async claim(digest, holder) {
+            if (await access.isClaimed(digest))
+                throw new Error(`deletion already claimed: ${digest}`);
+            await client.query(`INSERT INTO artifacts.object_intents (id, kind, payload)
+        VALUES ($1, 'delete-blob', $2::jsonb)`, [crypto.randomUUID(), JSON.stringify({ deletionClaim: true, digest, holder })]);
+        },
+        async releaseClaim(digest) {
+            const { rowCount } = await client.query(`UPDATE artifacts.object_intents SET state = 'done', updated_at = now() WHERE ${predicate}`, [digest]);
+            if (rowCount === 0)
+                throw new Error(`deletion not claimed: ${digest}`);
+        },
+    };
+    const withDigestLock = async (digest, action) => {
+        await client.query('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [`artifacts-blob:${digest}`]);
+        return action(access);
+    };
+    return { ...access, withDigestLock,
+        async listClaims() {
+            const { rows } = await client.query(`SELECT id, state, payload->>'digest' AS digest, payload->>'holder' AS holder
+         FROM artifacts.object_intents WHERE kind = 'delete-blob'
+         AND payload->>'deletionClaim' = 'true' ORDER BY created_at, id`, []);
+            return rows.map((row) => ({ claimId: row.id, digest: row.digest, holder: row.holder, state: row.state }));
+        },
+        claim: (digest, holder) => withDigestLock(digest, (locked) => locked.claim(digest, holder)),
+        releaseClaim: (digest) => withDigestLock(digest, (locked) => locked.releaseClaim(digest)) };
+}
+export function createMemoryDeletionClaimStore() {
+    const holders = new Map();
+    const history = [];
+    const mutex = createKeyMutex();
+    const access = {
+        async claim(digest, holder) {
+            if (holders.has(digest))
+                throw new Error(`deletion already claimed: ${digest}`);
+            holders.set(digest, holder);
+            history.push({ claimId: crypto.randomUUID(), digest, holder, state: 'pending' });
+        },
+        async releaseClaim(digest) {
+            if (!holders.has(digest))
+                throw new Error(`deletion not claimed: ${digest}`);
+            holders.delete(digest);
+            const claim = history.find((entry) => entry.digest === digest && entry.state === 'pending');
+            if (claim !== undefined)
+                claim.state = 'done';
+        },
+        async isClaimed(digest) {
+            return holders.has(digest);
+        },
+    };
+    return {
+        ...access,
+        listClaims: async () => structuredClone(history),
+        claim: (digest, holder) => mutex.runSerialized(digest, () => access.claim(digest, holder)),
+        releaseClaim: (digest) => mutex.runSerialized(digest, () => access.releaseClaim(digest)),
+        withDigestLock: (digest, action) => mutex.runSerialized(digest, () => action(access)),
+    };
+}
+/**
+ * A RefcountStore that refuses new references to claimed digests. Purge
+ * claims first, so racing publications cannot pin a blob scheduled for
+ * deletion; already-held references still protect the blob in collect.
+ */
+export function createClaimGuardedRefs(refs, claims) {
+    return {
+        addRef: async (digest, holder) => {
+            await claims.withDigestLock(digest, async (locked) => {
+                if (await locked.isClaimed(digest))
+                    throw new Error(`blob scheduled for deletion: ${digest}`);
+                await refs.addRef(digest, holder);
+            });
+        },
+        releaseRef: (digest, holder) => refs.releaseRef(digest, holder),
+        count: (digest) => refs.count(digest),
+        isPinned: (digest) => refs.isPinned(digest),
+        pin: (digest, holder) => claims.withDigestLock(digest, async (locked) => {
+            if (await locked.isClaimed(digest))
+                throw new Error(`blob scheduled for deletion: ${digest}`);
+            await refs.pin(digest, holder);
+        }),
+        unpin: (digest, holder) => refs.unpin(digest, holder),
+    };
+}
 /** Create a GC service over an injected refcount store (no driver imports). */
 export function createGcService(refs) {
     return {
-        async collect(blobs, prefix) {
+        async collect(blobs, prefix, claims) {
             const report = { deleted: [], retained: [], failures: [] };
             for (const key of await blobs.listKeys(prefix)) {
                 let digest;
@@ -77,8 +222,26 @@ export function createGcService(refs) {
                     continue;
                 }
                 try {
-                    await blobs.deleteBlob(key);
-                    report.deleted.push(key);
+                    await claims.withDigestLock(digest, async (locked) => {
+                        const alreadyClaimed = await locked.isClaimed(digest);
+                        if (!alreadyClaimed)
+                            await locked.claim(digest, 'gc');
+                        let deleted = false;
+                        try {
+                            if ((await refs.count(digest)) !== 0 || (await refs.isPinned(digest))) {
+                                report.retained.push(key);
+                                return;
+                            }
+                            await blobs.deleteBlob(key);
+                            deleted = true;
+                            report.deleted.push(key);
+                        }
+                        finally {
+                            // Preserve a purge claim until erasure; always release our GC claim.
+                            if (!alreadyClaimed || deleted)
+                                await locked.releaseClaim(digest);
+                        }
+                    });
                 }
                 catch (error) {
                     report.failures.push({ key, error: String(error) });

package/dist/server/idempotency.d.ts

@@ -10,6 +10,10 @@
  * KvPort only (ports.ts); the memory double serves unit tests.
  */
 import { type KvPort } from './ports.js';
+import { type ArtifactInvocationContext } from './commit/types.js';
+import type { EffectiveArtifactCommand } from './command-identity.js';
+/** Known 0.1.x durable key encodings. Their sorted hashes cannot prove command order or authority. */
+export declare function assertArtifactReplayMigration(records: Pick<KvPort, 'get'>, command: EffectiveArtifactCommand, invocation: ArtifactInvocationContext, callerKey: string): Promise<void>;
 export interface IdempotentResult<T> {
     result: T;
     replayed: boolean;

package/dist/server/idempotency.js

@@ -10,6 +10,20 @@
  * KvPort only (ports.ts); the memory double serves unit tests.
  */
 import { createKeyMutex, createMemoryKv } from './ports.js';
+import { CommitQuarantineError } from './commit/types.js';
+/** Known 0.1.x durable key encodings. Their sorted hashes cannot prove command order or authority. */
+export async function assertArtifactReplayMigration(records, command, invocation, callerKey) {
+    const { internalKey } = command.identity;
+    const keys = new Set([callerKey, internalKey]);
+    for (const key of [callerKey, internalKey]) {
+        keys.add(JSON.stringify([command.operation, invocation.actorId, key]));
+    }
+    for (const key of keys) {
+        if (await records.get(`idempotency:${key}`) !== undefined) {
+            throw new CommitQuarantineError(invocation.storageScopeId, internalKey, 'legacy-unknown');
+        }
+    }
+}
 /** Memory-backed KvPort for unit tests (re-exported from the ports module). */
 export function createMemoryIdempotencyKv() {
     return createMemoryKv();

package/dist/server/lifecycle.d.ts

@@ -1,4 +1,5 @@
 import { type AccessAction, type ArtifactAcl } from './access.js';
+import type { DeletionClaimStore } from './gc.js';
 import type { PublicationStateStore } from './publication.js';
 /**
  * The current-release pointer the service promotes through. A subset of the
@@ -54,4 +55,4 @@ export interface LifecycleService {
     trackRelease(artifactId: string, releaseId: string): Promise<void>;
 }
 /** Create a lifecycle service over an injected store (mutations owner-only). */
-export declare function createLifecycleService(store: LifecycleStore, clock?: () => string, current?: CurrentPointer): LifecycleService;
+export declare function createLifecycleService(store: LifecycleStore, clock?: () => string, current?: CurrentPointer, claims?: DeletionClaimStore): LifecycleService;

package/dist/server/lifecycle.js

@@ -71,7 +71,7 @@ export function createMemoryLifecycleStore() {
     return store;
 }
 /** Create a lifecycle service over an injected store (mutations owner-only). */
-export function createLifecycleService(store, clock = () => new Date().toISOString(), current) {
+export function createLifecycleService(store, clock = () => new Date().toISOString(), current, claims) {
     async function ownerOf(artifactId) {
         const owner = await store.getOwner(artifactId);
         if (owner === undefined)
@@ -131,6 +131,20 @@ export function createLifecycleService(store, clock = () => new Date().toISOStri
                 throw new Error(`can only purge a deleted artifact: ${artifactId} is ${state}`);
             }
             const releases = await store.listArtifactReleases(artifactId);
+            const acquired = [];
+            if (claims !== undefined) {
+                try {
+                    for (const digest of new Set(blobDigests)) {
+                        await claims.claim(digest, `purge:${artifactId}`);
+                        acquired.push(digest);
+                    }
+                }
+                catch (error) {
+                    for (const digest of acquired)
+                        await claims.releaseClaim(digest);
+                    throw error;
+                }
+            }
             for (const releaseId of releases) {
                 await store.setReleaseState(releaseId, 'purged');
             }

package/dist/server/object-intents.d.ts

@@ -9,6 +9,8 @@
  * Postgres adapter serves the L-5b integration proof.
  */
 import type { JsonValue } from '../contracts.js';
+export { inspectPreparations, scheduleBoundedPreparationCleanup } from './preparation-cleanup.js';
+export type { PreparationCleanupHost, PreparationAttempt } from './preparation-cleanup.js';
 export type IntentKind = 'commit-release' | 'delete-blob' | 'promote-release';
 export type IntentState = 'pending' | 'done' | 'failed';
 export interface ObjectIntent {
@@ -27,8 +29,19 @@ export interface IntentStore {
     get(intentId: string): Promise<ObjectIntent | undefined>;
     listPending(): Promise<ObjectIntent[]>;
 }
+/** Durable preparation history; cleanup never turns a failed attempt into success. */
+export interface PreparationIntentQuery {
+    readonly artifactId?: string;
+    readonly throughMs?: number;
+    readonly limit?: number;
+}
+export interface PreparationIntentStore extends IntentStore {
+    listPreparationIntents(query?: PreparationIntentQuery): Promise<ObjectIntent[]>;
+    claimPreparationCleanup(intentId: string, throughMs: number): Promise<ObjectIntent | undefined>;
+    settlePreparationCleanup(intentId: string): Promise<void>;
+}
 /** In-memory IntentStore double for unit tests. */
-export declare function createMemoryIntentStore(clock?: () => string, ids?: () => string): IntentStore;
+export declare function createMemoryIntentStore(clock?: () => string, ids?: () => string): PreparationIntentStore;
 export type IntentResolution = 'done' | 'failed';
 /**
  * Reconcile pending intents after a crash: the resolver inspects each

package/dist/server/object-intents.js

@@ -1,3 +1,4 @@
+export { inspectPreparations, scheduleBoundedPreparationCleanup } from './preparation-cleanup.js';
 /** In-memory IntentStore double for unit tests. */
 export function createMemoryIntentStore(clock = () => new Date().toISOString(), ids = () => crypto.randomUUID()) {
     const intents = new Map();
@@ -38,6 +39,36 @@ export function createMemoryIntentStore(clock = () => new Date().toISOString(),
                 .filter((intent) => intent.state === 'pending')
                 .sort((a, b) => (a.createdAt < b.createdAt ? -1 : 1));
         },
+        async listPreparationIntents(query = {}) {
+            return structuredClone([...intents.values()].filter((intent) => {
+                const deadline = intent.payload.cleanupDeadlineMs;
+                return intent.kind === 'commit-release' && intent.state !== 'done' && deadline !== undefined &&
+                    (query.artifactId === undefined || intent.payload.artifactId === query.artifactId) &&
+                    (query.throughMs === undefined || (!intent.error?.startsWith('invalid preparation metadata') && Number(deadline) <= query.throughMs &&
+                        (intent.payload.cleanupState !== 'failed-cleaned' || Number(deadline) >= query.throughMs - 60_000)));
+            }).sort((a, b) => query.throughMs === undefined ? 0 : Number(a.payload.cleanupState === 'failed-cleaned') -
+                Number(b.payload.cleanupState === 'failed-cleaned') ||
+                Number(a.payload.cleanupDeadlineMs) - Number(b.payload.cleanupDeadlineMs))
+                .slice(0, query.limit));
+        },
+        async claimPreparationCleanup(intentId, throughMs) {
+            const intent = intents.get(intentId);
+            if (intent === undefined || intent.state === 'done' ||
+                typeof intent.payload.cleanupDeadlineMs !== 'number' ||
+                intent.payload.cleanupDeadlineMs > throughMs)
+                return undefined;
+            intent.state = 'failed';
+            intent.error ??= 'preparation expired; explicit retry required';
+            intent.updatedAt = clock();
+            return structuredClone(intent);
+        },
+        async settlePreparationCleanup(intentId) {
+            const intent = intents.get(intentId);
+            if (intent === undefined || intent.state !== 'failed')
+                throw new Error('cleanup needs a failed preparation');
+            intent.payload.cleanupState = 'failed-cleaned';
+            intent.updatedAt = clock();
+        },
     };
 }
 /**

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

@@ -0,0 +1,3 @@
+/** One typed outcome and one projection for both host transports. */
+export * from './failures.js';
+export { projectArtifactHttpOutcome, projectArtifactMcpOutcome, projectArtifactWriteFailure } from './outcome-projection.js';

package/dist/server/outcome-contract.js

@@ -0,0 +1,3 @@
+/** One typed outcome and one projection for both host transports. */
+export * from './failures.js';
+export { projectArtifactHttpOutcome, projectArtifactMcpOutcome, projectArtifactWriteFailure } from './outcome-projection.js';

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

@@ -0,0 +1,21 @@
+/** HTTP and platform result projections share one classified outcome; neither inspects causes. */
+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;
+/** 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 interface ArtifactWriteFailure {
+    readonly invocationId: string;
+    readonly operation: string;
+    readonly reason: 'provider_unavailable' | 'provider_conflict' | 'unauthorized_at_commit' | 'provider_error';
+    readonly status: number;
+}
+/**
+ * Pure accounting descriptor. The host persists/deduplicates by invocation ID;
+ * observing the same outcome in nested adapters never records another event here.
+ */
+export declare function projectArtifactWriteFailure(failure: ArtifactFailure, dispatch: {
+    readonly dispatched: boolean;
+    readonly write: boolean;
+}): ArtifactWriteFailure | undefined;

package/dist/server/outcome-projection.js

@@ -0,0 +1,29 @@
+export function projectArtifactHttpOutcome(outcome) {
+    if (outcome.ok)
+        return outcome.result;
+    return { status: outcome.failure.httpStatus, body: { error: outcome.failure.publicCode } };
+}
+/** Feed this application result to mcp-platform's existing result codec. No second wire protocol. */
+export function projectArtifactMcpOutcome(outcome, auditId) {
+    if (outcome.ok)
+        return { ok: true, output: outcome.result.body, auditId, redactionClass: 'low' };
+    const { publicCode, retriable } = outcome.failure;
+    return {
+        ok: false, auditId, redactionClass: 'low',
+        error: { code: publicCode, message: publicCode, retriable },
+    };
+}
+/**
+ * Pure accounting descriptor. The host persists/deduplicates by invocation ID;
+ * observing the same outcome in nested adapters never records another event here.
+ */
+export function projectArtifactWriteFailure(failure, dispatch) {
+    if (failure.kind !== 'operational' || !dispatch.dispatched || !dispatch.write
+        || failure.phase === 'selection' || failure.phase === 'admit'
+        || failure.category === 'capability_unselected')
+        return undefined;
+    const reason = failure.category === 'conflict' ? 'provider_conflict'
+        : failure.category === 'provider_unavailable' || failure.category === 'unauthorized_at_commit'
+            ? failure.category : 'provider_error';
+    return { invocationId: failure.invocationId, operation: failure.operation, reason, status: failure.httpStatus };
+}

package/dist/server/preparation-cleanup.d.ts

@@ -0,0 +1,31 @@
+import type { PreparationIntentStore } from './object-intents.js';
+import { type PublicationBlobStore } from './publication.js';
+import type { DeletionClaimStore, RefcountStore } from './gc.js';
+export interface PreparationCleanupHost {
+    readonly intents: PreparationIntentStore;
+    readonly blobs: PublicationBlobStore;
+    readonly refs: RefcountStore;
+    /** PostgreSQL callers retain the transaction-scoped exclusion through DELETE. */
+    readonly claims: DeletionClaimStore;
+    readonly cleanupBatchSize?: number;
+}
+export interface PreparationAttempt {
+    readonly attemptId: string;
+    readonly invocationId: string;
+    readonly preparedAtMs: number;
+    readonly cleanupDeadlineMs: number;
+    readonly blobKeys: string[];
+    readonly state: 'pending-cleanup' | 'failed' | 'failed-cleaned';
+}
+/** Historical attempt attribution plus current protection, scoped to one artifact. */
+export declare function inspectPreparations(host: PreparationCleanupHost, artifactId: string): Promise<{
+    attempts: PreparationAttempt[];
+    protectedKeys: string[];
+    abandonedKeys: string[];
+    invalidIntents: Array<{
+        intentId: string;
+        error: string;
+    }>;
+}>;
+/** Run one deterministic, bounded sweep through the supplied clock deadline. */
+export declare function scheduleBoundedPreparationCleanup(host: PreparationCleanupHost, throughMs: number): Promise<void>;