@sentropic/artifacts 0.1.3 → 0.2.0

package/docs/migration-l6.md

@@ -0,0 +1,129 @@
+# 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. 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.

package/examples/radar-commit-setup.ts

@@ -0,0 +1,299 @@
+/**
+ * L3 (immo #861) — typed Radar construction example (conductor-directed).
+ *
+ * Shows the exact construction Radar wires: a real coordinator over the
+ * PostgreSQL executor, a transaction-bound PG policy/quota participant
+ * registered at construction, fence minting in the host guard, and the
+ * preparation-abandonment queue bound to a cleanup sweeper. Imports only
+ * public package entrypoints. Pass this coordinator plus the compiled profile to
+ * `createHttpArtifactApp` (r2 section 3.2); nothing here invents that seam.
+ * The `radar_commit_example` tables below are illustrative host tables so
+ * the example runs standalone; Radar's real adapter owns its own tables.
+ */
+import type { Pool } from 'pg';
+import { createPostgresCommitExecutor } from '@sentropic/artifacts/adapters/postgres-commit';
+import { createArtifactCommitCoordinator } from '@sentropic/artifacts/server/commit-contract';
+import { compileArtifactsProfile, RADAR_ARTIFACTS_PROFILE } from '@sentropic/artifacts/mcp-core';
+import { createPostgresArtifactStore } from '@sentropic/artifacts/adapters/postgres';
+import { createPostgresDeletionClaimStore } from '@sentropic/artifacts/server/gc';
+import { scheduleBoundedPreparationCleanup } from '@sentropic/artifacts/server/object-intents';
+import type { PublicationBlobStore } from '@sentropic/artifacts/server/publication';
+import type {
+  ArtifactAuthorizationDecision,
+  ArtifactCommitContext,
+  ArtifactCommitTransaction,
+  ArtifactPolicyDriver,
+  CommitPolicyParticipantFactory,
+  CommitCoordinatorOptions,
+  CoordinatorTestPoint,
+  ArtifactCommitCoordinator,
+  FinalizeRequest,
+  FinalizeResult,
+  InternalIdempotencyKey,
+} from '@sentropic/artifacts/server/commit-contract';
+
+/** One abandoned preparation awaiting host cleanup. */
+export interface AbandonedAttempt {
+  readonly attemptId: string;
+  readonly scopeId: string;
+  readonly internalKey: string;
+  readonly atMs: number;
+}
+
+/** Configure publication with this lifetime; sweep cadence is part of the activation bound. */
+export const RADAR_PREPARATION_LIFETIME_MS = 30_000;
+
+/** Bind durable intent cleanup before activation; observe failures as preparation debt. */
+export function startRadarPreparationCleanup(options: {
+  pool: Pool;
+  blobs: PublicationBlobStore;
+  onError(error: unknown): void;
+  intervalMs?: number;
+}): { runOnce(): Promise<void>; stop(): void } {
+  const intervalMs = options.intervalMs ?? 1000;
+  if (!Number.isSafeInteger(intervalMs) || intervalMs < 1 || intervalMs > RADAR_PREPARATION_LIFETIME_MS) {
+    throw new Error('invalid preparation cleanup interval');
+  }
+  const executor = createPostgresCommitExecutor(options.pool);
+  const store = createPostgresArtifactStore(options.pool);
+  let running: Promise<void> | undefined;
+  const runOnce = (): Promise<void> => {
+    if (running !== undefined) return running;
+    running = (async () => {
+      const client = await executor.beginFinalization();
+      let failure: unknown;
+      try {
+        await client.beginReadCommitted();
+        await scheduleBoundedPreparationCleanup({ intents: store, refs: store,
+          claims: createPostgresDeletionClaimStore(client), blobs: options.blobs }, Date.now());
+        await client.commit();
+      } catch (error) {
+        failure = error;
+        try { await client.rollback(); } catch (rollbackError) { failure = rollbackError; }
+        throw error;
+      } finally { client.release(failure); }
+    })().finally(() => { running = undefined; });
+    return running;
+  };
+  const timer = setInterval(() => { void runOnce().catch(options.onError); }, intervalMs);
+  return { runOnce, stop: () => clearInterval(timer) };
+}
+
+/** Create the illustrative host tables and seed one approved actor plus quota. */
+export async function prepareRadarCommitExample(pool: Pool): Promise<void> {
+  await pool.query('CREATE SCHEMA IF NOT EXISTS radar_commit_example');
+  await pool.query(
+    `CREATE TABLE IF NOT EXISTS radar_commit_example.policy_revision
+       (id INT PRIMARY KEY CHECK (id = 1), revision TEXT NOT NULL)`,
+  );
+  await pool.query(
+    `INSERT INTO radar_commit_example.policy_revision (id, revision)
+     VALUES (1, 'rev-1') ON CONFLICT (id) DO UPDATE SET revision = 'rev-1'`,
+  );
+  await pool.query(
+    `CREATE TABLE IF NOT EXISTS radar_commit_example.approvals
+       (actor_id TEXT PRIMARY KEY, approved BOOLEAN NOT NULL, expires_at_ms BIGINT NOT NULL)`,
+  );
+  await pool.query(
+    `INSERT INTO radar_commit_example.approvals (actor_id, approved, expires_at_ms)
+     VALUES ('radar-actor', true, 9999999999999)
+     ON CONFLICT (actor_id) DO UPDATE SET approved = true, expires_at_ms = 9999999999999`,
+  );
+  await pool.query(
+    `CREATE TABLE IF NOT EXISTS radar_commit_example.quotas
+       (quota_key TEXT PRIMARY KEY, total INT NOT NULL, used INT NOT NULL)`,
+  );
+  await pool.query(
+    `INSERT INTO radar_commit_example.quotas (quota_key, total, used)
+     VALUES ('radar-quota', 100, 0) ON CONFLICT (quota_key) DO UPDATE SET used = 0`,
+  );
+}
+
+/** The host guard Radar wires: current revision, approval and fence minting. */
+export async function allowRadarGuard(
+  context: ArtifactCommitContext,
+  transaction: ArtifactCommitTransaction,
+): Promise<ArtifactAuthorizationDecision> {
+  const revision = await transaction.participant.readRevision();
+  if (context.policyRevision !== revision) {
+    return {
+      allowed: false, reason: 'revoked', publicCode: 'access_denied', status: 403, retriable: false,
+    };
+  }
+  const check = await transaction.participant.checkApproval({
+    actorId: context.actorId,
+    operation: context.operation,
+  });
+  if (!check.approved) {
+    return {
+      allowed: false, reason: check.reason ?? 'denied',
+      publicCode: 'access_denied', status: 403, retriable: false,
+    };
+  }
+  return { allowed: true, fence: transaction.participant.mintFence(revision, context.invocationId) };
+}
+
+const createParticipantFactory = (
+  quotaKey: string,
+  clock: { nowMs: number },
+): CommitPolicyParticipantFactory => ({
+  createParticipant: (client, transactionToken): ArtifactPolicyDriver => ({
+    async readRevision(): Promise<string> {
+      const { rows } = await client.query<{ revision: string }>(
+        'SELECT revision FROM radar_commit_example.policy_revision WHERE id = 1 FOR SHARE',
+        [],
+      );
+      const row = rows[0];
+      if (row === undefined) throw new Error('missing policy revision');
+      return row.revision;
+    },
+    async checkApproval(input: { actorId: string }) {
+      const { rows } = await client.query<{ approved: boolean; expires_at_ms: string }>(
+        'SELECT approved, expires_at_ms FROM radar_commit_example.approvals WHERE actor_id = $1 FOR SHARE',
+        [input.actorId],
+      );
+      const row = rows[0];
+      if (row === undefined || !row.approved) return { approved: false as const, reason: 'denied' as const };
+      if (Number(row.expires_at_ms) <= clock.nowMs) {
+        return { approved: false as const, reason: 'expired' as const };
+      }
+      return { approved: true as const };
+    },
+    async reserveQuota(): Promise<{ reserved: boolean }> {
+      const { rowCount } = await client.query(
+        'UPDATE radar_commit_example.quotas SET used = used + 1 WHERE quota_key = $1 AND used < total',
+        [quotaKey],
+      );
+      return { reserved: rowCount > 0 };
+    },
+    mintFence: (revision: string, invocationId: string) => ({
+      fenceId: `fence-${transactionToken}`,
+      transactionId: transactionToken,
+      invocationId,
+      policyRevision: revision,
+    }),
+  }),
+});
+
+export interface RadarCommitInput {
+  readonly scopeId: string;
+  readonly internalKey: string;
+  readonly commandHash: string;
+  readonly invocationId: string;
+  readonly operation: string;
+  readonly receiptData: unknown;
+}
+
+export interface RadarCommitSetup {
+  readonly coordinator: ArtifactCommitCoordinator;
+  readonly profile: ReturnType<typeof compileArtifactsProfile>;
+  readonly abandonedAttempts: AbandonedAttempt[];
+  finalizePrepared(input: RadarCommitInput): Promise<FinalizeResult>;
+  replayPrepared(input: RadarCommitInput): Promise<FinalizeResult>;
+  drainAbandonedAttempts(onSweep: (batch: AbandonedAttempt[]) => void): void;
+  startAbandonedAttemptSweep(
+    onSweep: (batch: AbandonedAttempt[]) => void | Promise<void>,
+    intervalMs: number,
+  ): () => void;
+}
+
+/**
+ * Build the exact Radar construction over one pool. The optional
+ * `testObserver` forwards barrier observations to the coordinator;
+ * `testPoints` optionally filters them (see `testing.ts`).
+ */
+export function createRadarCommitSetup(options: {
+  pool: Pool;
+  clock: { nowMs: number };
+  quotaKey?: string;
+  testObserver?: CommitCoordinatorOptions['testObserver'];
+  testPoints?: readonly CoordinatorTestPoint[];
+}): RadarCommitSetup {
+  const quotaKey = options.quotaKey ?? 'radar-quota';
+  const abandonedAttempts: AbandonedAttempt[] = [];
+  const coordinator = createArtifactCommitCoordinator({
+    executor: createPostgresCommitExecutor(options.pool),
+    policy: createParticipantFactory(quotaKey, options.clock),
+    nowMs: () => options.clock.nowMs,
+    testObserver: options.testObserver,
+    testPoints: options.testPoints,
+  });
+  const toRequest = (
+    input: RadarCommitInput,
+  ): FinalizeRequest & { attemptId: string } => ({
+    scopeId: input.scopeId,
+    internalKey: input.internalKey as InternalIdempotencyKey,
+    commandHash: input.commandHash,
+    codecVersion: 'artifacts-command/v1',
+    invocationId: input.invocationId,
+    actorId: 'radar-actor',
+    operation: input.operation,
+    artifactId: null,
+    bindingName: null,
+    policyRevision: 'rev-1',
+    guard: allowRadarGuard,
+    receiptData: input.receiptData,
+    attemptId: input.invocationId,
+    noteAbandonedAttempt: async (attemptId: string) => {
+      abandonedAttempts.push({
+        attemptId,
+        scopeId: input.scopeId,
+        internalKey: input.internalKey,
+        atMs: options.clock.nowMs,
+      });
+    },
+  });
+  const drainAbandonedAttempts = (onSweep: (batch: AbandonedAttempt[]) => void): void => {
+    if (abandonedAttempts.length === 0) return;
+    // Retain-then-remove: a throwing sweeper keeps the batch for the next
+    // sweep instead of losing it. Durable cleanup state, per-attempt
+    // deadlines and restart recovery stay L4-owned (intent metadata).
+    const batch = abandonedAttempts.slice();
+    onSweep(batch);
+    abandonedAttempts.splice(0, batch.length);
+  };
+  return {
+    coordinator,
+    profile: compileArtifactsProfile(RADAR_ARTIFACTS_PROFILE),
+    abandonedAttempts,
+    finalizePrepared: (input: RadarCommitInput) => coordinator.finalizePrepared(toRequest(input)),
+    replayPrepared: (input: RadarCommitInput) => coordinator.replayPrepared(toRequest(input)),
+    drainAbandonedAttempts,
+    startAbandonedAttemptSweep: (onSweep, intervalMs) => {
+      // Serialized sweeps: an overlapping tick queues behind the running
+      // sweep instead of sweeping concurrently, and only the swept entries
+      // are removed, so arrivals landing mid-sweep are never deleted.
+      let sweeping = false;
+      let queued = false;
+      const runSweep = (): void => {
+        if (sweeping) {
+          queued = true;
+          return;
+        }
+        sweeping = true;
+        void (async () => {
+          try {
+            do {
+              queued = false;
+              const batch = abandonedAttempts.slice();
+              try {
+                await onSweep(batch);
+              } catch {
+                /* retained for the next sweep */
+                break;
+              }
+              for (const entry of batch) {
+                const index = abandonedAttempts.indexOf(entry);
+                if (index !== -1) abandonedAttempts.splice(index, 1);
+              }
+            } while (queued);
+          } finally {
+            sweeping = false;
+          }
+        })();
+      };
+      const timer = setInterval(runSweep, intervalMs);
+      return () => clearInterval(timer);
+    },
+  };
+}