@sentropic/artifacts 0.1.4 → 0.2.1

package/README.md

@@ -1,5 +1,35 @@
 # @sentropic/artifacts — generic artifact contracts (L-5a)
 
+Version 0.2.1 fixes host commit authorization being masked by the built-in
+publication guard and wires the optional trusted `mapHostError` dependency.
+Publication retains its lifecycle, ACL and policy revision checks; the host
+`authorizeCommit` binding decides account approval and its sanitized refusal code.
+Custom services using `createGuardedPublicationService` may pass the request-bound
+`authorizeCommit` in `publishFinalized(input)`. It runs after
+lifecycle, ACL and policy revision checks. When omitted, publication keeps the
+default `participant.checkApproval` check and denies unapproved or expired commits.
+
+Bind the same mapper on `createHttpArtifactApp`, `createArtifactsToolExecutor`
+(or `createArtifactsAdapter`) and `createArtifactCommitCoordinator` so host wrapper
+errors are classified at their originating layer. For example:
+
+```ts
+import { ArtifactOperationError, type ArtifactHostFailureMapper }
+  from '@sentropic/artifacts/server/outcome-contract';
+
+const mapHostError: ArtifactHostFailureMapper = cause => {
+  const code = (cause as { code?: string } | null)?.code;
+  return code === 'artifact_s3_timeout' || code === 'artifact_connection_lost'
+    ? new ArtifactOperationError('provider_unavailable', { cause }) : undefined;
+};
+```
+
+Pass `{ ...existingOptions, mapHostError }` to each construction. The packed
+`examples/radar-commit-setup.ts` also accepts this option. Unrecognized failures
+keep their existing classification; private causes never enter HTTP/MCP results.
+Frozen contracts, command identity and selected tools remain unchanged.
+
+
 Generic, host-independent artifact domain state for the Sentropic artifacts
 provider (`sentropic.artifacts`, spec-v8 §9), covering L-5a–5e. Version
 `0.1.2` adds UTF-8 text publication, exposes storage adapters and ships SQL migrations.
@@ -7,6 +37,23 @@ Version `0.1.1` fixed activation ticket release and channel binding (FL-ACT).
 Version `0.1.4` hardens host authority, replay isolation, publication and content
 responses, and adds the platform-free `@sentropic/artifacts/mcp-core` entry.
 
+## 0.2.0 contract line (L0 frozen)
+
+The `0.2.0` line freezes the immo #861 declaration shapes only:
+explicit capability selection and the effective publication profile
+(`l0-freeze/profile-contract.ts`), the effective command identity
+(`l0-freeze/command-identity-contract.ts`), the commit finalization unit
+(`l0-freeze/commit-contract.ts`) and the typed failure outcome
+(`l0-freeze/failure-contract.ts`). The section 3.2 host API names are frozen
+against spec r2. Trusted scope/subject domain qualification and
+actor-mapping acceptance remain gated on i-cond Q0; the structural freeze
+is not a completed Q0-dependent qualification. L1+ promotes the shapes
+into `src/`; version reservations are pack-only dev versions owned by the
+integration owner, never registry candidates. The common-contract reuse map lives in
+`docs/common-contract-map.md`; the migration inventory lives in
+`docs/migration-inventory-l0.md`. L0 changes no behavior, no `src/` file
+and no package version.
+
 ## Migrating to 0.1.4
 
 HTTP hosts must supply a trusted `HttpRequest.storageScopeId` for `/ensure`.

package/dist/adapters/postgres-commit.d.ts

@@ -0,0 +1,15 @@
+/**
+ * L3 (immo #861) — PostgreSQL finalization executor (spec r2 §3.1 A4).
+ *
+ * Owns every coordinator SQL statement against coordinator tables only
+ * (`artifacts.operation_keys`, `artifacts.operation_receipts`). No domain
+ * table, no policy table and no caller SQL here: host domain reads and
+ * writes arrive through the participant and the provider-internal
+ * transaction handle. Connections are raw pooled clients; the coordinator
+ * owns BEGIN/COMMIT/rollback/release. No nested pool lease spans S3 I/O:
+ * preparation happens before the coordinator acquires its client.
+ */
+import type { Pool } from 'pg';
+import type { CommitExecutor } from '../server/commit/types.js';
+/** Create the PostgreSQL finalization executor over an injected pool (no DDL). */
+export declare function createPostgresCommitExecutor(pool: Pool): CommitExecutor;

package/dist/adapters/postgres-commit.js

@@ -0,0 +1,80 @@
+function toReceipt(row) {
+    return {
+        scopeId: row.storage_scope_id,
+        internalKey: row.internal_key,
+        commandHash: row.command_hash,
+        codecVersion: row.command_codec,
+        receipt: row.receipt,
+        createdAt: row.created_at.toISOString(),
+    };
+}
+class PgFinalizeConnection {
+    client;
+    released = false;
+    constructor(client) {
+        this.client = client;
+    }
+    async query(text, params) {
+        const result = await this.client.query(text, [...params]);
+        return { rows: result.rows, rowCount: result.rowCount ?? 0 };
+    }
+    async beginReadCommitted() {
+        await this.client.query('BEGIN ISOLATION LEVEL READ COMMITTED');
+    }
+    async lockOperationKey(scopeId, internalKey) {
+        await this.client.query(`SELECT 1 FROM artifacts.operation_keys
+       WHERE storage_scope_id = $1 AND internal_key = $2 FOR UPDATE`, [scopeId, internalKey]);
+    }
+    async readReceipt(scopeId, internalKey) {
+        const result = await this.client.query(`SELECT storage_scope_id, internal_key, command_codec, command_hash, receipt, created_at
+       FROM artifacts.operation_receipts
+       WHERE storage_scope_id = $1 AND internal_key = $2`, [scopeId, internalKey]);
+        const row = result.rows[0];
+        return row === undefined ? undefined : toReceipt(row);
+    }
+    async insertReceipt(receipt) {
+        await this.client.query(`INSERT INTO artifacts.operation_receipts
+         (storage_scope_id, internal_key, command_codec, command_hash, receipt)
+       VALUES ($1, $2, $3, $4, $5)`, [
+            receipt.scopeId,
+            receipt.internalKey,
+            receipt.codecVersion,
+            receipt.commandHash,
+            JSON.stringify(receipt.receipt),
+        ]);
+    }
+    async commit() {
+        await this.client.query('COMMIT');
+    }
+    async rollback() {
+        await this.client.query('ROLLBACK');
+    }
+    release(error) {
+        if (this.released)
+            throw new Error('finalization client already released');
+        this.released = true;
+        this.client.release(error === undefined ? undefined : error);
+    }
+}
+/** Create the PostgreSQL finalization executor over an injected pool (no DDL). */
+export function createPostgresCommitExecutor(pool) {
+    return {
+        async ensureCoordinationRow(scopeId, internalKey) {
+            await pool.query(`INSERT INTO artifacts.operation_keys (storage_scope_id, internal_key)
+         VALUES ($1, $2) ON CONFLICT DO NOTHING`, [scopeId, internalKey]);
+        },
+        async beginFinalization() {
+            const client = await pool.connect();
+            try {
+                await client.query('BEGIN ISOLATION LEVEL READ COMMITTED');
+            }
+            catch (error) {
+                // Never hand out a client whose transaction failed to open: destroy
+                // it instead of leaking a leased connection the coordinator cannot see.
+                client.release(error);
+                throw error;
+            }
+            return new PgFinalizeConnection(client);
+        },
+    };
+}

package/dist/adapters/postgres.d.ts

@@ -12,9 +12,12 @@ import type { AclStore } from '../server/access.js';
 import type { RefcountStore } from '../server/gc.js';
 import type { LifecycleStore } from '../server/lifecycle.js';
 import type { SourceStore } from '../server/sources.js';
-import type { IntentStore } from '../server/object-intents.js';
+import type { PreparationIntentStore } from '../server/object-intents.js';
 import type { IdempotencyStore } from '../server/idempotency.js';
 import type { PublicationStateStore } from '../server/publication.js';
+import type { KvPort } from '../server/ports.js';
+/** Read-only migration inventory. Never promotes a legacy success into an authorized receipt. */
+export declare function createPostgresLegacyArtifactRecords(pool: Pool): Pick<KvPort, 'get'>;
 export interface ArtifactBindingInput {
     storageScopeId: string;
     ownerId: string;
@@ -25,7 +28,7 @@ export interface ArtifactBinding {
     artifactId: string;
     created: boolean;
 }
-export interface PostgresArtifactBasics extends IntentStore {
+export interface PostgresArtifactBasics extends PreparationIntentStore {
     ensureArtifact(input: ArtifactBindingInput): Promise<ArtifactBinding>;
 }
 export interface PostgresArtifactStore extends PostgresArtifactBasics, PublicationStateStore, IdempotencyStore, AclStore, SourceStore, LifecycleStore, RefcountStore {

package/dist/adapters/postgres.js

@@ -1,3 +1,12 @@
+/** Read-only migration inventory. Never promotes a legacy success into an authorized receipt. */
+export function createPostgresLegacyArtifactRecords(pool) {
+    return {
+        async get(key) {
+            const { rows } = await pool.query('SELECT params_hash, result FROM artifacts.idempotency_keys WHERE key = $1', [key]);
+            return rows[0] === undefined ? undefined : JSON.stringify(rows[0]);
+        },
+    };
+}
 function toIntent(row) {
     return {
         intentId: row.id,
@@ -71,6 +80,36 @@ export function createPostgresArtifactStore(pool) {
          FROM artifacts.object_intents WHERE state = 'pending' ORDER BY created_at`);
             return rows.map(toIntent);
         },
+        async listPreparationIntents(query = {}) {
+            const { rows } = await pool.query(`SELECT * FROM artifacts.object_intents WHERE kind = 'commit-release' AND state <> 'done'
+         AND payload ? 'cleanupDeadlineMs'
+         AND ($1::text IS NULL OR payload->>'artifactId' = $1)
+         AND ($2::numeric IS NULL OR (COALESCE(error, '') NOT LIKE 'invalid preparation metadata%'
+           AND
+           CASE WHEN jsonb_typeof(payload->'cleanupDeadlineMs') = 'number'
+             THEN (payload->>'cleanupDeadlineMs')::numeric ELSE 0 END <= $2
+           AND (payload->>'cleanupState' IS DISTINCT FROM 'failed-cleaned'
+             OR (payload->>'cleanupDeadlineMs')::numeric >= $2 - 60000)))
+         ORDER BY COALESCE(payload->>'cleanupState' = 'failed-cleaned', false),
+           CASE WHEN jsonb_typeof(payload->'cleanupDeadlineMs') = 'number'
+             THEN (payload->>'cleanupDeadlineMs')::numeric ELSE 0 END, id
+         LIMIT $3`, [query.artifactId ?? null, query.throughMs ?? null, query.limit ?? null]);
+            return rows.map(toIntent);
+        },
+        async claimPreparationCleanup(intentId, throughMs) {
+            // This UPDATE serializes with finalization's intent completion on the same row.
+            const { rows } = await pool.query(`UPDATE artifacts.object_intents SET state = 'failed',
+           error = COALESCE(error, 'preparation expired; explicit retry required'), updated_at = now()
+         WHERE id = $1 AND kind = 'commit-release' AND state <> 'done'
+           AND (payload->>'cleanupDeadlineMs')::numeric <= $2 RETURNING *`, [intentId, throughMs]);
+            return rows[0] === undefined ? undefined : toIntent(rows[0]);
+        },
+        async settlePreparationCleanup(intentId) {
+            const { rowCount } = await pool.query(`UPDATE artifacts.object_intents SET payload = payload || '{"cleanupState":"failed-cleaned"}'::jsonb,
+           updated_at = now() WHERE id = $1 AND state = 'failed'`, [intentId]);
+            if (rowCount === 0)
+                throw new Error('cleanup needs a failed preparation');
+        },
         async putRelease(release) {
             const parsed = JSON.parse(release.manifest);
             const client = await pool.connect();

package/dist/http.d.ts

@@ -1,47 +1,60 @@
-import type { ParameterSchema } from './parameters.js';
-import type { ArtifactService } from './server/service.js';
-import type { PublicationBlobStore, PublicationService } from './server/publication.js';
+import { type CompiledArtifactsProfile } from './profile/index.js';
+import { type ArtifactKeyDerivationBinding } from './server/command-identity.js';
+import { type GuardedEnsureHost } from './server/service.js';
+import type { KvPort } from './server/ports.js';
+import { type GuardedPublicationDeps, type PublicationService } from './server/publication.js';
+import type { AclStore } from './server/access.js';
 import type { LifecycleService } from './server/lifecycle.js';
-import type { ForkService } from './server/fork.js';
-import { type AclStore } from './server/access.js';
-import { type SourceStore } from './server/sources.js';
-import type { StagingStore, UploadService } from './server/uploads.js';
-import type { TemplateCatalogPort } from './server/templates.js';
+import { type ArtifactInvocationContext, type ArtifactCommitCoordinator } from './server/commit/types.js';
+import { type ArtifactOutcome, type ArtifactHostFailureMapper } from './server/failures.js';
+export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 export interface HttpRequest {
     method: string;
     path: string;
     body: unknown;
     actorId: string;
-    /** Trusted host context, resolved alongside actorId; never copy from the body. */
+    /** Trusted host assertion, never caller authority. */
     storageScopeId?: string;
+    /** Optional platform envelope; must equal the tool argument byte for byte. */
+    idempotencyKey?: string;
 }
 export interface HttpResponse {
     status: number;
     body: unknown;
 }
+/** Stable content-route error codes; private driver messages never leave the host. */
+export declare function errorBody(status: number): {
+    error: string;
+};
 export interface HttpAppDeps {
-    parameterSchema: ParameterSchema;
-    artifacts: ArtifactService;
-    publication: PublicationService;
-    lifecycle: LifecycleService;
-    forks: ForkService;
+    /** Trusted mapping of host wrapper errors; causes remain private. Also bind on the coordinator. */
+    mapHostError?: ArtifactHostFailureMapper;
+    profile: CompiledArtifactsProfile;
+    coordinator: ArtifactCommitCoordinator;
+    derivation: ArtifactKeyDerivationBinding;
+    /** Explicit pilot-state inventory reader; supply an empty reader only for a verified fresh store. */
+    legacyRecords: Pick<KvPort, 'get'>;
+    ensureHost: GuardedEnsureHost;
+    publication: Omit<GuardedPublicationDeps, 'coordinator' | 'limits'> & {
+        getCurrent: PublicationService['getCurrent'];
+    };
     acls: AclStore;
-    sources: SourceStore;
-    blobs: PublicationBlobStore;
+    lifecycle: Pick<LifecycleService, 'stateOf' | 'canRead'>;
     isApprovedAccount?: (principalId: string) => boolean;
-    /** Bounded upload sessions (L-5e); upload routes refuse when unwired. */
-    uploads?: UploadService;
-    staging?: StagingStore;
-    /** Template kit + API guide catalog (L-5e); refuses when unwired. */
-    templates?: TemplateCatalogPort;
+    /** One trusted URL policy shared by HTTP and MCP receipts. */
+    publicationUrls?: (artifactId: string, releaseId: string) => {
+        stableUrl: string;
+        pinnedUrl: string;
+    };
 }
-/** Stable error body for one status; internal messages never leave the app. */
-export declare function errorBody(status: number): {
-    error: string;
-};
-/** Canonical text MIME types; parameters are omitted (encoding is always UTF-8). */
+export interface ArtifactApp {
+    readonly selectedCapabilities: CompiledArtifactsProfile['selectedCapabilities'];
+    readonly profileDigest: string;
+    execute(request: HttpRequest, invocation: ArtifactInvocationContext): Promise<ArtifactOutcome<HttpResponse>>;
+    handle(request: HttpRequest, invocation: ArtifactInvocationContext): Promise<HttpResponse>;
+}
+/** Retained for consumers describing canonical textual publication inputs. */
 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])";
-/** Create the HTTP app over injected services (no server, no fetch). */
-export declare function createHttpArtifactApp(deps: HttpAppDeps): {
-    handle(request: HttpRequest): Promise<HttpResponse>;
-};
+/** Other mutation surfaces need their own qualification before host activation. */
+export declare function assertArtifactsTransportProfile(value: unknown): asserts value is CompiledArtifactsProfile;
+export declare function createHttpArtifactApp(deps: HttpAppDeps): ArtifactApp;