@sentropic/artifacts 0.1.4 → 0.2.1

package/dist/server/service.js

@@ -11,6 +11,9 @@ import { assertArtifactAccess } from './authorization.js';
 import { createBindingService } from './bindings.js';
 import { createIdempotencyStore } from './idempotency.js';
 import { manifestDigest } from '../codecs.js';
+import { ArtifactProfileInputError } from '../profile/index.js';
+import { createArtifactCommand, } from './command-identity.js';
+import { projectEnsureReceipt, replayEnsureGuarded, } from './authorized-replay.js';
 /** Create the artifact service over explicit injected ports (no defaults). */
 export function createArtifactService(ports) {
     const bindings = createBindingService(ports.kv, ports.uuid);
@@ -35,3 +38,181 @@ export function createArtifactService(ports) {
         },
     };
 }
+/** Private causes stay on the failure object but never serialize: projection picks fields. */
+const conceal = (failure) => {
+    Object.defineProperty(failure, 'cause', { value: failure.cause, enumerable: false });
+    return Object.freeze(failure);
+};
+const profileEntryFailure = (error, invocationId) => {
+    if (error.kind === 'operational') {
+        return conceal({
+            kind: 'operational', category: 'capability_unselected', variant: error.variant,
+            httpStatus: error.httpStatus, publicCode: error.publicCode, retriable: false,
+            invocationId, operation: 'ensure', phase: error.phase, commitState: 'not_committed', cause: error,
+        });
+    }
+    return conceal({
+        kind: 'ordinary', category: 'invalid_request',
+        httpStatus: error.httpStatus, publicCode: error.publicCode, retriable: false,
+        invocationId, operation: 'ensure', phase: error.phase, commitState: 'not_committed', cause: error,
+    });
+};
+const internalFailure = (invocationId, phase, cause) => conceal({
+    kind: 'operational', category: 'provider_error', variant: 'unclassified',
+    httpStatus: 500, publicCode: 'internal_error', retriable: false,
+    invocationId, operation: 'ensure', phase, commitState: 'not_committed', cause,
+});
+const unavailableFailure = (invocationId, phase, cause) => conceal({
+    kind: 'operational', category: 'provider_unavailable', variant: 'dispatch_failure',
+    httpStatus: 503, publicCode: 'capability_unavailable', retriable: true,
+    invocationId, operation: 'ensure', phase, commitState: 'not_committed', cause,
+});
+const anonymousFailure = (invocation) => conceal({
+    kind: 'admission', category: 'anonymous',
+    httpStatus: 401, publicCode: 'anonymous', retriable: false,
+    invocationId: invocation.invocationId, operation: 'ensure', phase: 'admit',
+    commitState: 'not_committed', cause: { invocation: invocation.invocationId },
+});
+const coordinatorFailure = (failure) => conceal({
+    kind: 'operational', category: failure.category, variant: failure.variant,
+    httpStatus: failure.httpStatus, publicCode: failure.publicCode, retriable: failure.retriable,
+    invocationId: failure.invocationId, operation: failure.operation, phase: failure.phase,
+    commitState: failure.commitState, cause: failure.cause,
+});
+const ensureResult = (receipt, replayed, invocationId) => ({
+    ok: true,
+    result: { artifactId: receipt.artifactId, created: receipt.created, replayed },
+    invocationId,
+    commitState: 'committed',
+    replayed,
+});
+export function createGuardedEnsureService(deps) {
+    const finalizeRequest = (invocation, command, policyRevision) => {
+        const binding = {
+            ownerId: invocation.actorId,
+            storageScopeId: invocation.storageScopeId,
+            bindingName: command.payload.bindingName,
+            attemptId: invocation.invocationId,
+        };
+        const captured = {};
+        const request = {
+            scopeId: invocation.storageScopeId,
+            internalKey: command.identity.internalKey,
+            commandHash: command.identity.commandHash,
+            codecVersion: command.identity.codecVersion,
+            invocationId: invocation.invocationId,
+            actorId: invocation.actorId,
+            operation: 'ensure',
+            get artifactId() { return captured.artifactId ?? null; },
+            bindingName: binding.bindingName,
+            policyRevision,
+            locks: { 'binding-identity': [async (client) => {
+                        await deps.host.lockBinding(client, binding);
+                        const receipt = await deps.host.resolveBinding(client, binding);
+                        captured.artifactId = receipt.artifactId;
+                        captured.created = receipt.created;
+                    }] },
+            validateReplayReceipt: (receipt) => captured.created === false &&
+                projectEnsureReceipt(receipt).artifactId === captured.artifactId,
+            noteAbandonedAttempt: (attemptId) => deps.host.abandonAttempt(attemptId),
+            attemptId: invocation.invocationId,
+            guard: invocation.authorizeCommit,
+            receiptData: captured,
+        };
+        return { request, captured };
+    };
+    return {
+        async ensure(invocation, args) {
+            if (invocation.actorId.length === 0 || invocation.storageScopeId.length === 0) {
+                return { ok: false, failure: anonymousFailure(invocation) };
+            }
+            let command;
+            try {
+                const { envelopeKey, ...commandArgs } = args;
+                command = createArtifactCommand(deps.profile, 'artifacts_ensure', commandArgs, { storageScopeId: invocation.storageScopeId, actorId: invocation.actorId }, deps.derivation, envelopeKey);
+            }
+            catch (error) {
+                if (error instanceof ArtifactProfileInputError) {
+                    return { ok: false, failure: profileEntryFailure(error, invocation.invocationId) };
+                }
+                return { ok: false, failure: internalFailure(invocation.invocationId, 'entry', error) };
+            }
+            let policyRevision;
+            try {
+                policyRevision = await deps.host.readPolicyRevision();
+            }
+            catch (error) {
+                return { ok: false, failure: unavailableFailure(invocation.invocationId, 'acquire', error) };
+            }
+            const { request } = finalizeRequest(invocation, command, policyRevision);
+            const outcome = await deps.coordinator.finalizePrepared(request);
+            if (!outcome.ok)
+                return { ok: false, failure: coordinatorFailure(outcome.failure) };
+            let receipt;
+            try {
+                receipt = projectEnsureReceipt(outcome.result);
+            }
+            catch (error) {
+                return { ok: false, failure: internalFailure(invocation.invocationId, 'resolve', error) };
+            }
+            return ensureResult(receipt, outcome.replayed, outcome.invocationId);
+        },
+        async replay(invocation, args) {
+            if (invocation.actorId.length === 0 || invocation.storageScopeId.length === 0) {
+                return { ok: false, failure: anonymousFailure(invocation) };
+            }
+            try {
+                deps.profile.assertSelected('artifacts_ensure');
+                if (!args.binding || args.binding.ownerId !== invocation.actorId ||
+                    args.binding.storageScopeId !== invocation.storageScopeId || !args.binding.bindingName) {
+                    throw new ArtifactProfileInputError();
+                }
+            }
+            catch (error) {
+                if (error instanceof ArtifactProfileInputError) {
+                    return { ok: false, failure: profileEntryFailure(error, invocation.invocationId) };
+                }
+                return { ok: false, failure: internalFailure(invocation.invocationId, 'entry', error) };
+            }
+            let policyRevision;
+            try {
+                policyRevision = await deps.host.readPolicyRevision();
+            }
+            catch (error) {
+                return { ok: false, failure: unavailableFailure(invocation.invocationId, 'acquire', error) };
+            }
+            let artifactId;
+            let missingTarget = false;
+            const binding = args.binding;
+            const outcome = await replayEnsureGuarded(deps.coordinator, {
+                invocation,
+                internalKey: args.internalKey,
+                commandHash: args.commandHash,
+                policyRevision,
+                get artifactId() { return artifactId; },
+                bindingName: binding?.bindingName,
+                validateReplayReceipt: (receipt) => !missingTarget &&
+                    projectEnsureReceipt(receipt).artifactId === artifactId,
+                noteAbandonedAttempt: (attemptId) => deps.host.abandonAttempt(attemptId),
+                locks: binding === undefined ? undefined : {
+                    'binding-identity': [async (client) => {
+                            await deps.host.lockBinding(client, binding);
+                            const target = await deps.host.resolveBinding(client, binding);
+                            missingTarget = target.created;
+                            artifactId = target.artifactId;
+                        }],
+                },
+            });
+            if (!outcome.ok)
+                return { ok: false, failure: coordinatorFailure(outcome.failure) };
+            let receipt;
+            try {
+                receipt = projectEnsureReceipt(outcome.result);
+            }
+            catch (error) {
+                return { ok: false, failure: internalFailure(invocation.invocationId, 'resolve', error) };
+            }
+            return ensureResult(receipt, outcome.replayed, outcome.invocationId);
+        },
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1,50 @@
+/**
+ * L3 (immo #861) — test-only commit barrier (spec r2 §3.2).
+ *
+ * Test seam for pausing finalization at deterministic points with
+ * invocation correlation. `waitUntilReached` resolves after arrival;
+ * `release` resumes only that invocation/point pair. The coordinator
+ * rechecks authority after a resumed barrier; a barrier can never mark
+ * an operation authorized or successful.
+ *
+ * Pass `observer` as the coordinator `testObserver`. Register a wait before
+ * starting the operation to pause that invocation/point; other arrivals
+ * are observed without blocking. The three preparation points are fired by L4
+ * preparation adapters holding this same observer, never by the
+ * coordinator (arming one throws at construction).
+ */
+import type { InspectableDeletionClaimStore } from './server/gc.js';
+import type { PublicationBlobStore } from './server/publication.js';
+export declare const COMMIT_BARRIER_POINTS: readonly ["before_connection_acquire", "before_key_lock", "before_blob_put", "after_blob_put_before_verify", "before_blob_readback", "before_finalization_row_lock", "after_finalization_locks_before_guard", "after_replay_lookup_before_guard", "before_commit"];
+export type CommitBarrierPoint = (typeof COMMIT_BARRIER_POINTS)[number];
+export type CommitBarrierObserver = (point: CommitBarrierPoint, invocationId: string) => Promise<void>;
+export interface CommitArrivalObserver {
+    arrive(point: CommitBarrierPoint, invocationId: string): void;
+}
+/** Explicit host binding: purge must use the supplied deletion adapter for this call only. */
+export interface PurgeTestHost {
+    readonly claims: InspectableDeletionClaimStore;
+    readonly storageScopeId: string;
+    readonly blobs: PublicationBlobStore;
+    purge(artifactId: string, deleting: PublicationBlobStore): Promise<void>;
+}
+export declare function inspectDeletionClaims(host: Pick<PurgeTestHost, 'claims' | 'storageScopeId'>): Promise<Array<{
+    claimId: string;
+    state: string;
+    blobKeys: string[];
+}>>;
+/** Start one correlated purge and pause immediately before its first external DELETE. */
+export declare function pausePurgeBeforeDelete(host: PurgeTestHost, artifactId: string): Promise<{
+    claimId: string;
+    blobKeys: string[];
+    release(): void;
+    finished: Promise<void>;
+}>;
+/** Create a correlated test barrier for one finalization run. */
+export declare function createArtifactCommitBarrier(options?: {
+    readonly points: readonly CommitBarrierPoint[];
+}): {
+    observer: CommitBarrierObserver & CommitArrivalObserver;
+    waitUntilReached(point: CommitBarrierPoint, invocationId: string): Promise<void>;
+    release(point: CommitBarrierPoint, invocationId: string): void;
+};

package/dist/testing.js

@@ -0,0 +1,86 @@
+export const COMMIT_BARRIER_POINTS = [
+    'before_connection_acquire',
+    'before_key_lock',
+    'before_blob_put',
+    'after_blob_put_before_verify',
+    'before_blob_readback',
+    'before_finalization_row_lock',
+    'after_finalization_locks_before_guard',
+    'after_replay_lookup_before_guard',
+    'before_commit',
+];
+export async function inspectDeletionClaims(host) {
+    return (await host.claims.listClaims()).map((claim) => ({ claimId: claim.claimId, state: claim.state,
+        blobKeys: [`artifacts/${host.storageScopeId}/blobs/sha256/${claim.digest.slice(7)}`] }));
+}
+/** Start one correlated purge and pause immediately before its first external DELETE. */
+export async function pausePurgeBeforeDelete(host, artifactId) {
+    let release;
+    const gate = new Promise((resolve) => { release = resolve; });
+    let reached;
+    let fail;
+    const arrival = new Promise((resolve, reject) => {
+        reached = resolve;
+        fail = reject;
+    });
+    const deleting = { ...host.blobs,
+        putBlob: (key, bytes) => host.blobs.putBlob(key, bytes),
+        getBlob: (key) => host.blobs.getBlob(key), listKeys: (prefix) => host.blobs.listKeys(prefix),
+        async deleteBlob(key) {
+            const claims = (await host.claims.listClaims()).filter((claim) => claim.holder === `purge:${artifactId}` && claim.state === 'pending');
+            const matching = claims.find((claim) => key.endsWith(`/sha256/${claim.digest.slice(7)}`));
+            if (matching === undefined)
+                return host.blobs.deleteBlob(key);
+            reached({ claimId: matching.claimId,
+                blobKeys: claims.map((claim) => `artifacts/${host.storageScopeId}/blobs/sha256/${claim.digest.slice(7)}`) });
+            await gate;
+            await host.blobs.deleteBlob(key);
+        },
+    };
+    const finished = host.purge(artifactId, deleting);
+    void finished.then(() => fail(new Error('purge finished without external DELETE')), fail);
+    return { ...await arrival, release, finished };
+}
+/** Create a correlated test barrier for one finalization run. */
+export function createArtifactCommitBarrier(options) {
+    const gates = new Map();
+    const gateFor = (point, invocationId) => {
+        const key = `${point}:${invocationId}`;
+        const existing = gates.get(key);
+        if (existing !== undefined)
+            return existing;
+        const created = { arrivals: 0, armed: options?.points.includes(point) ?? false, waiters: [], releases: [] };
+        gates.set(key, created);
+        return created;
+    };
+    const arrive = (point, invocationId) => {
+        const gate = gateFor(point, invocationId);
+        gate.arrivals += 1;
+        for (const waiter of gate.waiters.splice(0))
+            waiter();
+        if (!gate.armed)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            gate.releases.push(resolve);
+        });
+    };
+    return {
+        observer: Object.assign(arrive, { arrive }),
+        waitUntilReached: (point, invocationId) => {
+            const gate = gateFor(point, invocationId);
+            if (gate.arrivals > 0)
+                return Promise.resolve();
+            gate.armed = true;
+            return new Promise((resolve) => {
+                gate.waiters.push(resolve);
+            });
+        },
+        release: (point, invocationId) => {
+            const gate = gateFor(point, invocationId);
+            const resume = gate.releases.shift();
+            if (resume === undefined)
+                throw new Error(`no paused barrier at ${point} for ${invocationId}`);
+            resume();
+        },
+    };
+}

package/docs/migration-l6.md

@@ -0,0 +1,134 @@
+# Artifacts 0.2.0 transport migration
+
+The registry baseline checked for this change is `@sentropic/artifacts@0.1.4`.
+Radar 0.1.2 and upstream 0.1.4 hosts must migrate their composition before
+loading the 0.2.0 HTTP or MCP surface. Publication is a separate owner-approved
+release step; this branch does not publish packages.
+
+## Required host composition
+
+Compile an explicit immutable profile with `compileArtifactsProfile`. Radar
+selects `artifacts_ensure`, `artifacts_publish`, `artifacts_list` and
+`artifacts_get`. Pass the same compiled profile to `createHttpArtifactApp`,
+the MCP adapter/executor and `createArtifactsRegistryDefinition`. Empty
+selection exposes nothing. Missing configuration fails construction.
+
+Supply a raw PostgreSQL pool to `createPostgresCommitExecutor` and a
+transaction-bound policy participant factory to `createArtifactCommitCoordinator`.
+The coordinator owns BEGIN, key locking, COMMIT, rollback and release.
+Remove session advisory-lock wrappers, pool-routing proxies, nested BEGIN
+and no-op release wrappers from the old provider composition.
+
+Create one trusted `ArtifactInvocationContext` for every request, containing
+the verified actor, trusted scope, invocation ID and `authorizeCommit` guard.
+Pass it to `app.execute(request, invocation)` or `app.handle(request, invocation)`.
+Accounting hosts call `execute` once and project its typed outcome themselves.
+Do not call both methods for the same operation. The MCP adapter requires
+`createInvocation` and verifies its actor against `ctx.principal.sub`.
+HTTP and MCP must use the identical canonical verified actor string.
+
+Supply one qualified `createRadarKeyDerivation` binding to both transports.
+Caller arguments contain the original caller key; actor, scope, internal key,
+hash and guard come from the host. An optional platform envelope must exactly
+match the argument key. Keep publication URLs under one shared
+`publicationUrls` policy so HTTP and MCP return identical receipts.
+
+## Public coordinator example and cleanup
+
+The packed `examples/radar-commit-setup.ts` uses public entrypoints only:
+`@sentropic/artifacts/adapters/postgres-commit`, `/server/commit-contract`
+and `/mcp-core`. The commit contract exports `CommitExecutor`,
+`CommitCoordinatorOptions`, `ArtifactPolicyDriver` and `CoordinatorTestPoint`.
+The example compiles the frozen `ArtifactProviderProfile` shape, binds policy
+reads/quota to the acquired PostgreSQL transaction and mints its guard fence.
+
+Before activation, configure `cleanupWindowMs` on guarded publication and
+start a cleanup scheduler; the example supplies a 30-second preparation
+lifetime and a one-second serialized sweep. Each sweep processes at most
+100 attempts. Capacity, sweep cadence and storage availability determine
+whether the configured deadline is met; failed cleanup remains observable debt.
+Reads are limited to the same batch size, with unsettled debt first. Settled
+attempts receive metadata-only existence checks for 60 seconds after their
+deadline; subsequent orphan recovery uses the host's ordinary GC. No cleanup
+or inspection downloads blob contents. Invalid metadata is retained as failed
+debt, excluded from subsequent sweeps, and returned in inspection's
+`invalidIntents`; the sweep reports it after processing the remaining batch.
+
+`/server/object-intents` exposes `inspectPreparations(host, artifactId)` and
+`scheduleBoundedPreparationCleanup(host, throughMs)`. Bind `host.intents`
+to the PostgreSQL artifact store, plus `blobs`, `refs` and `claims`.
+Keep the claim store's transaction open through external DELETE, then commit
+or roll back and release it, as `startRadarPreparationCleanup` demonstrates.
+Inspection returns `attempts`, `protectedKeys` and `abandonedKeys`; every
+attempt retains its ID, invocation, blob keys, preparation time and deadline.
+Cleanup invalidates expired preparations before removing their pins, retains
+other references/pins, and never promotes an abandoned attempt to success.
+
+`/testing` exports `pausePurgeBeforeDelete(host, artifactId)` and
+`inspectDeletionClaims(host)`. Bind the test host's `storageScopeId`, `blobs`,
+inspectable `claims`, and `purge(artifactId, deletingBlobs)` callback. The
+callback must commit its durable `purge:<artifactId>` claims and use the
+supplied deletion adapter for that purge only. The pause returns `claimId`,
+`blobKeys`, `release()` and `finished`; release it in a `finally` block.
+Inspection reads durable claim history without releasing exclusion or
+granting publication authority. The seams do not alter L3 ports or profiles.
+
+## Domain adapters and transaction boundaries
+
+`ensureHost.lockBinding` and `resolveBinding` receive the coordinator's
+transaction client. Resolve the binding and write ACL/lifecycle state on that
+same client. Concurrent commands must serialize on the binding identity,
+including when their caller keys differ. Replay resolves current identity
+under this lock and compares it to the stored receipt. Missing or changed
+targets deny before the host guard; explicit replay requires a binding.
+
+Use `createGuardedEnsureService` and `createGuardedPublicationService` for
+custom services. Pass the request-bound host guard as `publishFinalized(input)`'s
+optional `authorizeCommit` field to preserve host approval policy and refusal codes;
+it runs after lifecycle, ACL and policy revision checks. When omitted, publication
+uses `participant.checkApproval` and denies unapproved or expired commits.
+HTTP/MCP pass the invocation's host guard automatically.
+The canonical coordinator exposes `finalizeOperation` and
+`replayOperation` with the frozen L0 inputs. Bind fresh domain request plans
+through its `operations` option; no process-local replay cache is used.
+Provider adapters use `finalizePrepared` and `replayPrepared` on that same
+coordinator. Guards run after all blocking waits and must be side-effect-free.
+Policy/quota registration is trusted construction, never a public argument.
+
+`ArtifactCommitParticipant.readAdmission` reads current approval/revision on
+the leased transaction. Keep policy locks through COMMIT. Quota reservation
+is provisional and rolls back with denial. Object authorization also runs
+for replay; a stored success alone confers no authority.
+
+Use `createPostgresGcService(executor, refsForTransaction)` for PostgreSQL GC.
+The reference-store factory must bind its reads to the supplied client.
+GC keeps the transaction and digest exclusion through external deletion and
+claim completion. Do not pass a raw pool to transaction-scoped deletion claims.
+
+## Durable state and failures
+
+Stop old writers before enabling the new composition. Apply migrations
+`0001_artifacts.sql`, `0002_lifecycle.sql` and additive `0003_coordinator.sql`.
+Preserve historical rows and objects. Supply `legacyRecords`, using
+`createPostgresLegacyArtifactRecords(pool)` for PostgreSQL. An empty inventory
+reader is appropriate only for a verified fresh store.
+
+Ambiguous legacy keys and unknown command codecs return a stable
+503 `capability_unavailable`, non-retriable migration condition. They are
+never promoted to newly authorized successes and never trigger allocation
+under another key. Reconcile actual pilot inventory separately; unknown
+historical array order cannot be recovered from a sorted manifest.
+
+New receipts store the ordered `artifacts-command/v1` identity in
+`artifacts.operation_receipts`. Manifest digests retain their historical
+codec. A denied attempt has no success receipt; reauthorization may retry the
+same key. An unknown COMMIT outcome requires the same key and a fresh guarded
+lookup. Private failure causes remain internal. HTTP and MCP project the same
+public code and retry classification; status 503 alone does not imply retry.
+
+Public host imports are `@sentropic/artifacts/server/commit-contract`,
+`@sentropic/artifacts/server/outcome-contract` and `@sentropic/artifacts/testing`.
+The `/mcp-core` runtime stays independent of the MCP platform runtime.
+For tests that subscribe after arrival, explicitly arm barrier points with
+`createArtifactCommitBarrier({ points: ['before_commit'] })`. Other arrivals
+remain observational; a barrier cannot grant authority or certify success.