@sentropic/artifacts 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.2.5
+
+- D1: Read verified author manifests and file bytes for the current or a selected
+  release, with path selection, source authorization, bounded snapshots and
+  separate provenance. Reject purged releases and mismatched record digests.
+- D2: Grant or revoke named read access and delete artifacts terminally with
+  host-approved confirmation, transactional receipts and idempotent replay.
+  Mask artifacts outside the caller's visibility as `not_found`.
+- D4: Enrich get/list results with binding names, dates, current release IDs,
+  digests, stable/pinned URLs, permissions and available optional metadata.
+
+Apply `0004_terminal_controls.sql` after migrations 0001–0003 before enabling
+the management capabilities.

package/README.md

@@ -76,7 +76,69 @@ Reconcile current authority independently of the restored ACL snapshot. Fresh
 authorized sessions create fresh flows; revoked readers stay denied. Rollback
 disables activation while retaining the additive schema and accepted artifacts.
 
-Package conformance lives in `tests/postgres-activation.test.ts` and
+### Importable host conformance (UP-T-2, 0.2.4)
+
+The packed package exports the framework-independent host suite and its stable
+vector IDs. Install the SQL asset through your test migration executor first:
+
+```ts
+import assert from 'node:assert/strict';
+import {
+  POSTGRES_ACTIVATION_VECTOR_IDS, runPostgresActivationConformance,
+} from '@sentropic/artifacts/adapters/postgres-activation/vectors';
+
+assert.equal(process.env.ACTIVATION_DISPOSABLE, '1');
+const { rows: [{ databaseName }] } = await pool.query('SELECT current_database() AS "databaseName"');
+assert.match(databaseName, /^test[_-][a-z0-9_-]+$/i); // Check before any schema setup/reset.
+const passed = await runPostgresActivationConformance({
+  disposable: { confirmed: true, databaseName },
+  createStore: namespace => createPostgresActivationStore({ pool, namespace }),
+  inspectTicket, // Host query returning persisted issuedAt/expiresAt and current DB now, in milliseconds.
+  createStoreWithCommitAckLoss, // Host composition with acknowledgement loss AFTER real consume COMMIT.
+  wait: async (ms, client) => { await (client ?? pool).query('SELECT pg_sleep($1)', [ms / 1000]); },
+  onPass: id => console.log('activation vector passed:', id),
+});
+assert.deepEqual(passed, POSTGRES_ACTIVATION_VECTOR_IDS); // 16 vectors
+```
+
+Supply your host's store composition in `createStore`, using the supplied namespace
+and the same disposable PostgreSQL database/executor for every instance. Replica
+instances must share durable state. `wait` uses database time and the supplied
+leased client during authority checks, including when the pool has one connection.
+`inspectTicket(namespace, ticketId)` reads `issued_ms`, `expires_ms` and
+`floor(extract(epoch FROM clock_timestamp()) * 1000)` through that same executor.
+`createStoreWithCommitAckLoss(namespace)` wraps the host's leased client: execute
+COMMIT, then throw before returning its acknowledgement. Seed with the normal
+store; inject only into the store returned by this hook. Both hooks are optional
+in the interface for additive compatibility; their vectors always run and fail
+if either hook is absent. A complete host fixture is in
+`packages/cluster-mesh/tests/packaging/activation-vectors.spec.ts`.
+Run in an isolated process: the clock-skew vector temporarily replaces `Date.now`
+by +/-120 seconds and restores it even on failure. TypeScript hosts install
+`@types/pg` alongside `pg` in their consumer project.
+The runner throws with the failing vector ID and original cause; it returns all
+16 IDs only after every assertion passes. It uses fresh namespaces and invalidates
+and cleans its records after each vector. Namespace rows remain in the disposable
+database. The runner refuses without explicit disposable confirmation and an
+actual database name starting `test_` or `test-`. Check `current_database()` on the
+host executor before installing/resetting the schema. Never use a serving database.
+
+The vectors cover namespace isolation, immutable records, all nine exact binding
+comparisons, wrong IDs, denial/outage preservation, single use, concurrent replicas,
+expiry without cleanup and after authority waits, bounded cleanup, invalidation
+and fresh recovery, the 60-second TTL cap, flow/ticket association, DB-time-only
+issuance/expiry under app clock skew, and `ActivationCommitUnknownError` without
+a grant followed by replay denial. This adds
+only a testing export in 0.2.4; adapter behavior and SQL bytes are unchanged.
+
+`make -f packages/cluster-mesh/packaging.mk test-lazy-package-activation ENV=test-artifacts-upt2`
+packs and installs the candidate in a clean consumer, verifies the SQL hash, and
+runs all 16 vectors on that consumer's PostgreSQL executor (pool max 1 and 4).
+It requires explicit disposable configuration and checks the JSON result for
+nine passing tests and zero skipped tests; missing CI wiring fails. Follow with
+`make down ENV=test-artifacts-upt2` (use the shared Docker lock for both commands).
+
+Additional fault/process conformance lives in `tests/postgres-activation.test.ts` and
 `tests/postgres-activation.integration.test.ts`, with the independent process
 witness `tests/fixtures/activation-process.mjs`. Run through
 `make test-artifacts` and `make test-artifacts-integration` on an isolated test
@@ -355,3 +417,41 @@ publication, use the current package version and this bootstrap sequence
 3. After that, merges to `main` touching the artifacts package publish
    through the `publish-artifacts` job (`make publish-artifacts`, OIDC +
    provenance), gated by `validate-artifacts`.
+
+## Source and management capabilities
+
+Version 0.3.0 introduces D1, D2 and D4; see [CHANGELOG.md](./CHANGELOG.md).
+
+Hosts may explicitly select `artifacts_get_source`, `artifacts_set_access`, and
+`artifacts_delete` in their compiled profile. Configure `get_source` with empty
+limits/defaults, and `set_access`/`delete` with `idempotencyKeyMaxUnits: 256` and
+empty defaults. Existing profile selections remain explicit.
+
+`POST /get_source` accepts `artifactId`, optional `releaseId`, and optional unique
+`paths` (1–32 entries). Bind `publication.getRelease` and `sources.getSource` on
+the HTTP app. It returns the canonical manifest, verified author file bytes,
+and separate nullable `sourceRef`; readers need the distinct source permission.
+The snapshot is limited to 32 files and 262144 decoded bytes. Hosts must qualify
+a 2 MiB serialized MCP result budget before selecting this capability.
+
+`POST /set_access` grants or revokes a named principal's read access, requires a
+caller `idempotencyKey`, and keeps the artifact private. Bind
+`isApprovedAccount` to the host's principal policy. `POST /delete` also requires
+`expectedCurrentReleaseId` (nullable) and a trusted `management.confirmation`
+port. Its `request` method issues a challenge for the host management UI;
+`consume` verifies the human-approved proof, expiration and full command context
+on the supplied transaction. A caller boolean is never confirmation. Repeated
+successful deletes return the stored receipt without consuming proof again.
+
+Apply `migrations/0004_terminal_controls.sql` after `0001_artifacts.sql`,
+`0002_lifecycle.sql` and `0003_coordinator.sql` before activation.
+The default management writer uses the coordinator's PostgreSQL
+transaction; alternative stores implement `management.createUnit` with the same
+parent/ACL/current lock order and transactional effects. Terminal markers and
+SQL guards prevent restoration and later publication. Deletion reports
+`purgeState: "pending"`; physical purge belongs to host retention policy.
+
+Get/list include binding, creation/modification dates, current release, digest,
+host URLs and available metadata. Historical modification dates stay nullable.
+The PostgreSQL projection reads the optional metadata column added by the
+publication parity lane without requiring that column for older stores.

package/dist/adapters/postgres-activation-vectors.d.ts

@@ -0,0 +1,31 @@
+import type { PoolClient } from 'pg';
+import { type PostgresActivationStore } from './postgres-activation.js';
+export declare const POSTGRES_ACTIVATION_VECTOR_IDS: readonly ["namespace-isolation", "immutable-records", "binding-mismatch", "wrong-ids", "authority-denial", "authority-outage", "single-use", "concurrent-consume", "expiry-without-cleanup", "expiry-after-authority", "bounded-cleanup", "invalidation-recovery", "ttl-cap", "flow-association", "db-time-skew", "commit-unknown"];
+export type PostgresActivationVectorId = typeof POSTGRES_ACTIVATION_VECTOR_IDS[number];
+export interface PostgresActivationConformanceHost {
+    /** Explicit opt-in; databaseName must be the executor's actual current_database(), starting test_ or test-. */
+    disposable?: {
+        confirmed: true;
+        databaseName: string;
+    };
+    /** Same disposable DB/executor for every namespace and replica; schema installed by the host. */
+    createStore(namespace: string): PostgresActivationStore;
+    /** Wait on DB time; use the supplied leased client during authority checks (supports max:1). */
+    wait(milliseconds: number, client?: PoolClient): Promise<void>;
+    /** Read persisted issuance/expiry and current DB milliseconds through the host executor. */
+    inspectTicket?(namespace: string, ticketId: string): Promise<{
+        issuedAt: number;
+        expiresAt: number;
+        now: number;
+    }>;
+    /** Same host composition, but throw AFTER the consume COMMIT succeeds, losing its acknowledgement. */
+    createStoreWithCommitAckLoss?(namespace: string): PostgresActivationStore;
+    onPass?(id: PostgresActivationVectorId): void;
+}
+/** Test-only, framework-independent host conformance. Throws on the first failing vector.
+ * Uses fresh isolated namespaces; invalidates and collects its own records after each vector.
+ * Process crashes and restore snapshots remain package integration tests.
+ * Optional hooks preserve interface compatibility; their vectors are mandatory and fail if absent.
+ * Run in an isolated process: db-time-skew temporarily replaces Date.now and always restores it.
+ */
+export declare function runPostgresActivationConformance(host: PostgresActivationConformanceHost): Promise<PostgresActivationVectorId[]>;

package/dist/adapters/postgres-activation-vectors.js

@@ -0,0 +1,178 @@
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import { ActivationCommitUnknownError } from './postgres-activation.js';
+export const POSTGRES_ACTIVATION_VECTOR_IDS = Object.freeze([
+    'namespace-isolation', 'immutable-records', 'binding-mismatch', 'wrong-ids',
+    'authority-denial', 'authority-outage', 'single-use', 'concurrent-consume',
+    'expiry-without-cleanup', 'expiry-after-authority', 'bounded-cleanup',
+    'invalidation-recovery', 'ttl-cap', 'flow-association',
+    'db-time-skew', 'commit-unknown',
+]);
+/** Test-only, framework-independent host conformance. Throws on the first failing vector.
+ * Uses fresh isolated namespaces; invalidates and collects its own records after each vector.
+ * Process crashes and restore snapshots remain package integration tests.
+ * Optional hooks preserve interface compatibility; their vectors are mandatory and fail if absent.
+ * Run in an isolated process: db-time-skew temporarily replaces Date.now and always restores it.
+ */
+export async function runPostgresActivationConformance(host) {
+    assert.ok(host.disposable?.confirmed === true, 'Explicit disposable database confirmation is required');
+    assert.match(host.disposable.databaseName, /^test[_-][a-z0-9_-]+$/i, 'A test database name is required');
+    const passed = [];
+    for (const id of POSTGRES_ACTIVATION_VECTOR_IDS) {
+        const namespace = `upt2:${randomUUID()}`;
+        const store = host.createStore(namespace);
+        const foreign = host.createStore(`${namespace}:other`);
+        const expected = { subjectId: 'alice', artifactId: 'a', releaseId: 'r', channel: 'stable',
+            nonceDigest: 'ab'.repeat(32), sessionId: 'session', profileDigest: 'cd'.repeat(32),
+            policyRevision: 'p1', targetOrigin: 'https://activation.example.test' };
+        async function seed(ttl = 50_000, target = store) {
+            assert.ok(target.tickets.issue, 'DB-time ticket issuance is required');
+            const ticket = await target.tickets.issue({ ...expected, ticketId: randomUUID() }, ttl);
+            const flow = { ...expected, ticketId: ticket.ticketId, flowId: randomUUID(), expiresAt: ticket.expiresAt };
+            await target.flows.put(flow);
+            return { ticket, flow, input: { ticketId: ticket.ticketId, flowId: flow.flowId, expected } };
+        }
+        try {
+            const { ticket, flow, input } = await seed();
+            const redeem = () => store.consume(input, async () => true);
+            const preserved = async () => {
+                assert.deepEqual(await store.tickets.peek(ticket.ticketId), ticket);
+                assert.deepEqual(await store.flows.peek(flow.flowId), flow);
+            };
+            if (id === 'namespace-isolation') {
+                assert.equal(await foreign.tickets.peek(ticket.ticketId), undefined);
+                assert.equal(await foreign.flows.peek(flow.flowId), undefined);
+                assert.equal(await foreign.consume(input, async () => true), undefined);
+                await foreign.tickets.remove(ticket.ticketId);
+                await preserved();
+            }
+            else if (id === 'immutable-records') {
+                await assert.rejects(store.tickets.put({ ...ticket, subjectId: 'mallory' }));
+                await assert.rejects(store.flows.put({ ...flow, sessionId: 'other' }));
+                await preserved();
+            }
+            else if (id === 'binding-mismatch') {
+                for (const key of Object.keys(expected)) {
+                    const mismatch = { ...expected, [key]: key === 'channel' ? 'pinned' : 'different' };
+                    assert.equal(await store.consume({ ...input, expected: mismatch }, async () => true), undefined, key);
+                }
+                await preserved();
+                assert.deepEqual(await redeem(), ticket);
+            }
+            else if (id === 'wrong-ids') {
+                for (const key of ['ticketId', 'flowId']) {
+                    assert.equal(await store.consume({ ...input, [key]: randomUUID() }, async () => true), undefined);
+                }
+                await preserved();
+            }
+            else if (id === 'authority-denial') {
+                assert.equal(await store.consume(input, async () => false), undefined);
+                await preserved();
+            }
+            else if (id === 'authority-outage') {
+                const outage = new Error('conformance authority unavailable');
+                await assert.rejects(store.consume(input, async () => { throw outage; }), error => error === outage);
+                await preserved();
+            }
+            else if (id === 'single-use') {
+                assert.deepEqual(await redeem(), ticket);
+                assert.equal(await redeem(), undefined);
+                assert.equal(await store.flows.peek(flow.flowId), undefined);
+            }
+            else if (id === 'concurrent-consume') {
+                const replica = host.createStore(namespace);
+                const results = await Promise.all([redeem(), replica.consume(input, async () => true)]);
+                assert.deepEqual(results.filter(Boolean), [ticket]);
+            }
+            else if (id === 'expiry-without-cleanup' || id === 'expiry-after-authority') {
+                const expired = await seed(1000);
+                if (id === 'expiry-without-cleanup')
+                    await host.wait(1200);
+                assert.equal(await store.consume(expired.input, async ({ client }) => {
+                    await host.wait(1200, client);
+                    return true;
+                }), undefined);
+                assert.equal(await store.tickets.peek(expired.ticket.ticketId), undefined);
+                assert.equal(await store.flows.peek(expired.flow.flowId), undefined);
+            }
+            else if (id === 'bounded-cleanup') {
+                for (let i = 0; i < 3; i++)
+                    await seed(1000);
+                const other = await seed(50_000, foreign);
+                await host.wait(1200);
+                let total = 0;
+                for (let i = 0; i < 4; i++) {
+                    const removed = await store.cleanup(2);
+                    const count = removed.flows + removed.tickets;
+                    assert.ok(count >= 0 && count <= 2);
+                    total += count;
+                }
+                assert.equal(total, 6);
+                await preserved();
+                assert.deepEqual(await foreign.tickets.peek(other.ticket.ticketId), other.ticket);
+            }
+            else if (id === 'invalidation-recovery') {
+                await store.invalidate();
+                const replica = host.createStore(namespace);
+                assert.equal(await replica.consume(input, async () => true), undefined);
+                assert.equal(await replica.tickets.peek(ticket.ticketId), undefined);
+                assert.equal(await replica.flows.peek(flow.flowId), undefined);
+                const fresh = await seed();
+                assert.deepEqual(await replica.consume(fresh.input, async () => true), fresh.ticket);
+            }
+            else if (id === 'ttl-cap') {
+                for (const ttl of [0, 60_001]) {
+                    await assert.rejects(store.tickets.issue({ ...expected, ticketId: randomUUID() }, ttl));
+                }
+                await seed(60_000);
+            }
+            else if (id === 'flow-association') {
+                await assert.rejects(store.flows.put({ ...flow, flowId: randomUUID(), subjectId: 'mallory' }));
+                await assert.rejects(store.flows.put({ ...flow, flowId: randomUUID(), expiresAt: ticket.expiresAt + 1 }));
+            }
+            else if (id === 'db-time-skew') {
+                assert.ok(host.inspectTicket, 'inspectTicket hook is required for db-time-skew');
+                const originalNow = Date.now;
+                try {
+                    for (const skew of [-120_000, 120_000]) {
+                        Date.now = () => originalNow() + skew;
+                        const issued = await seed(60_000);
+                        const db = await host.inspectTicket(namespace, issued.ticket.ticketId);
+                        assert.equal(db.expiresAt - db.issuedAt, 60_000);
+                        assert.equal(issued.ticket.expiresAt, db.expiresAt);
+                        assert.ok(db.expiresAt - db.now > 59_000 && db.expiresAt - db.now <= 60_000);
+                        assert.deepEqual(await store.consume(issued.input, async () => true), issued.ticket);
+                        const expired = await seed(50);
+                        await host.wait(80);
+                        assert.equal(await store.consume(expired.input, async () => true), undefined);
+                        assert.equal(await store.tickets.peek(expired.ticket.ticketId), undefined);
+                    }
+                }
+                finally {
+                    Date.now = originalNow;
+                }
+            }
+            else if (id === 'commit-unknown') {
+                assert.ok(host.createStoreWithCommitAckLoss, 'createStoreWithCommitAckLoss hook is required for commit-unknown');
+                const uncertain = host.createStoreWithCommitAckLoss(namespace);
+                const grants = [];
+                await assert.rejects(uncertain.consume(input, async () => true).then(result => grants.push(result)), error => error instanceof ActivationCommitUnknownError);
+                assert.deepEqual(grants, []);
+                assert.equal(await host.createStore(namespace).consume(input, async () => true), undefined);
+                assert.equal(await store.flows.peek(flow.flowId), undefined);
+            }
+        }
+        catch (cause) {
+            throw new Error(`UP-T conformance failed: ${id}`, { cause });
+        }
+        finally {
+            for (const target of [store, foreign]) {
+                await target.invalidate();
+                await target.cleanup(1000);
+            }
+        }
+        passed.push(id);
+        host.onPass?.(id);
+    }
+    return passed;
+}

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

@@ -0,0 +1,4 @@
+import type { FinalizeTxClient } from '../server/commit/types.js';
+import type { ManagementUnit } from '../server/management.js';
+/** Parent lock serializes ACL inserts, lifecycle changes and publication FKs. */
+export declare function createPostgresManagementUnit(client: FinalizeTxClient): ManagementUnit;

package/dist/adapters/postgres-management.js

@@ -0,0 +1,36 @@
+/** Parent lock serializes ACL inserts, lifecycle changes and publication FKs. */
+export function createPostgresManagementUnit(client) {
+    return {
+        async lock(id) {
+            await client.query('SELECT id FROM artifacts.artifacts WHERE id = $1 FOR UPDATE', [id]);
+            await client.query('SELECT principal_id FROM artifacts.artifact_access WHERE artifact_id = $1 ORDER BY principal_id FOR UPDATE', [id]);
+            await client.query('SELECT release_id FROM artifacts.artifact_current WHERE artifact_id = $1 FOR UPDATE', [id]);
+        },
+        async read(id) {
+            const { rows } = await client.query(`SELECT a.owner_id, a.storage_scope_id, a.lifecycle_state, a.is_public, a.terminal_deleted_at, c.release_id
+         FROM artifacts.artifacts a LEFT JOIN artifacts.artifact_current c ON c.artifact_id = a.id WHERE a.id = $1`, [id]);
+            const row = rows[0];
+            if (!row)
+                return undefined;
+            const acl = { ownerId: row.owner_id, storageScopeId: row.storage_scope_id,
+                isPublic: row.is_public, withdrawn: row.lifecycle_state === 'withdrawn', grants: [] };
+            return { acl, state: row.lifecycle_state, terminal: row.terminal_deleted_at !== null,
+                currentReleaseId: row.release_id };
+        },
+        async setAccess(id, principalId, action, updatedAt) {
+            const changed = action === 'grant' ? await client.query(`INSERT INTO artifacts.artifact_access (artifact_id, principal_id, permission) VALUES ($1, $2, 'read')
+         ON CONFLICT (artifact_id, principal_id) DO NOTHING`, [id, principalId])
+                : await client.query('DELETE FROM artifacts.artifact_access WHERE artifact_id = $1 AND principal_id = $2', [id, principalId]);
+            await client.query(`UPDATE artifacts.artifacts SET is_public = false, updated_at = $2
+        WHERE id = $1 AND ($3::boolean OR is_public)`, [id, updatedAt, changed.rowCount > 0]);
+            const result = await client.query('SELECT principal_id, permission FROM artifacts.artifact_access WHERE artifact_id = $1 ORDER BY principal_id', [id]);
+            const stamp = await client.query('SELECT updated_at FROM artifacts.artifacts WHERE id = $1', [id]);
+            return { grants: result.rows.map((row) => ({ principalId: row.principal_id, grant: row.permission })),
+                updatedAt: stamp.rows[0]?.updated_at?.toISOString() ?? null };
+        },
+        async delete(id, deletedAt) {
+            await client.query(`UPDATE artifacts.artifacts SET lifecycle_state = 'deleted', terminal_deleted_at = $2,
+        updated_at = $2, is_public = false WHERE id = $1`, [id, deletedAt]);
+        },
+    };
+}

package/dist/adapters/postgres.js

@@ -1,3 +1,4 @@
+import { ArtifactOperationError } from '../server/failures.js';
 /** Read-only migration inventory. Never promotes a legacy success into an authorized receipt. */
 export function createPostgresLegacyArtifactRecords(pool) {
     return {
@@ -34,8 +35,10 @@ export function createPostgresArtifactStore(pool) {
         async ensureArtifact(input) {
             const where = `WHERE storage_scope_id = $1 AND owner_id = $2 AND binding_name = $3`;
             const args = [input.storageScopeId, input.ownerId, input.bindingName];
-            const found = await pool.query(`SELECT id FROM artifacts.artifacts ${where}`, args);
+            const found = await pool.query(`SELECT id, (to_jsonb(a)->>'terminal_deleted_at') IS NOT NULL AS terminal FROM artifacts.artifacts a ${where}`, args);
             if (found.rowCount !== 0 && found.rows[0] !== undefined) {
+                if (found.rows[0].terminal)
+                    throw new ArtifactOperationError('gone');
                 return { artifactId: found.rows[0].id, created: false };
             }
             const inserted = await pool.query(`INSERT INTO artifacts.artifacts (id, storage_scope_id, owner_id, binding_name, profile)
@@ -44,10 +47,12 @@ export function createPostgresArtifactStore(pool) {
             if (inserted.rowCount !== 0 && inserted.rows[0] !== undefined) {
                 return { artifactId: inserted.rows[0].id, created: true };
             }
-            const raced = await pool.query(`SELECT id FROM artifacts.artifacts ${where}`, args);
+            const raced = await pool.query(`SELECT id, (to_jsonb(a)->>'terminal_deleted_at') IS NOT NULL AS terminal FROM artifacts.artifacts a ${where}`, args);
             const row = raced.rows[0];
             if (row === undefined)
                 throw new Error(`artifact binding lost for ${input.bindingName}`);
+            if (row.terminal)
+                throw new ArtifactOperationError('gone');
             return { artifactId: row.id, created: false };
         },
         async record(kind, payload) {
@@ -185,14 +190,17 @@ export function createPostgresArtifactStore(pool) {
             return rows.map((row) => row.digest);
         },
         async getArtifactAcl(artifactId) {
-            const { rows } = await pool.query(`SELECT owner_id, storage_scope_id, is_public, lifecycle_state
-         FROM artifacts.artifacts WHERE id = $1`, [artifactId]);
+            const { rows } = await pool.query(`SELECT owner_id, storage_scope_id, is_public, lifecycle_state, binding_name, created_at,
+          to_jsonb(a)->>'updated_at' AS updated_at, to_jsonb(a)->'metadata' AS metadata
+         FROM artifacts.artifacts a WHERE id = $1`, [artifactId]);
             const row = rows[0];
             if (row === undefined)
                 return undefined;
             const grants = await pool.query(`SELECT principal_id, permission FROM artifacts.artifact_access
          WHERE artifact_id = $1 ORDER BY principal_id`, [artifactId]);
             return {
+                bindingName: row.binding_name, createdAt: row.created_at.toISOString(), updatedAt: row.updated_at,
+                ...(row.metadata ?? {}),
                 ownerId: row.owner_id,
                 storageScopeId: row.storage_scope_id,
                 isPublic: row.is_public,
@@ -263,6 +271,13 @@ export function createPostgresArtifactStore(pool) {
             const { rows } = await pool.query(`SELECT lifecycle_state FROM artifacts.artifacts WHERE id = $1`, [artifactId]);
             return rows[0]?.lifecycle_state ?? 'active';
         },
+        async isTerminal(artifactId) {
+            const { rows } = await pool.query("SELECT (to_jsonb(a)->>'terminal_deleted_at') IS NOT NULL AS terminal FROM artifacts.artifacts a WHERE id = $1", [artifactId]);
+            return rows[0]?.terminal === true;
+        },
+        async markTerminal(artifactId) {
+            await pool.query("UPDATE artifacts.artifacts SET terminal_deleted_at = coalesce(terminal_deleted_at, now()), lifecycle_state = 'deleted' WHERE id = $1", [artifactId]);
+        },
         async setArtifactState(artifactId, state) {
             const updated = await pool.query(`UPDATE artifacts.artifacts SET lifecycle_state = $2 WHERE id = $1`, [artifactId, state]);
             if ((updated.rowCount ?? 0) === 0)

package/dist/http.d.ts

@@ -7,6 +7,9 @@ import type { AclStore } from './server/access.js';
 import type { LifecycleService } from './server/lifecycle.js';
 import { type ArtifactInvocationContext, type ArtifactCommitCoordinator } from './server/commit/types.js';
 import { type ArtifactOutcome, type ArtifactHostFailureMapper } from './server/failures.js';
+import { type ManagementUnit, type ArtifactConfirmationPort } from './server/management.js';
+import type { FinalizeTxClient } from './server/commit/types.js';
+import type { SourceStore } from './server/sources.js';
 export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 export interface HttpRequest {
     method: string;
@@ -37,6 +40,12 @@ export interface HttpAppDeps {
     ensureHost: GuardedEnsureHost;
     publication: Omit<GuardedPublicationDeps, 'coordinator' | 'limits'> & {
         getCurrent: PublicationService['getCurrent'];
+        getRelease?: PublicationService['getRelease'];
+    };
+    sources?: Pick<SourceStore, 'getSource'>;
+    management?: {
+        createUnit?: (client: FinalizeTxClient) => ManagementUnit;
+        confirmation?: ArtifactConfirmationPort;
     };
     acls: AclStore;
     lifecycle: Pick<LifecycleService, 'stateOf' | 'canRead'>;

package/dist/http.js

@@ -7,6 +7,10 @@ import { createGuardedPublicationService } from './server/publication.js';
 import { CommitQuarantineError } from './server/commit/types.js';
 import { ArtifactOperationError, classifyArtifactFailure } from './server/failures.js';
 import { projectArtifactHttpOutcome } from './server/outcome-projection.js';
+import { readArtifactSource } from './server/source-read.js';
+import { artifactSummary } from './server/summary.js';
+import { manageArtifact } from './server/management.js';
+import { createPostgresManagementUnit } from './adapters/postgres-management.js';
 export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 /** Stable content-route error codes; private driver messages never leave the host. */
 export function errorBody(status) {
@@ -24,7 +28,8 @@ function object(value) {
 /** Other mutation surfaces need their own qualification before host activation. */
 export function assertArtifactsTransportProfile(value) {
     assertCompiledArtifactsProfile(value);
-    const supported = ['artifacts_ensure', 'artifacts_publish', 'artifacts_list', 'artifacts_get'];
+    const supported = ['artifacts_ensure', 'artifacts_publish', 'artifacts_list', 'artifacts_get',
+        'artifacts_get_source', 'artifacts_set_access', 'artifacts_delete'];
     if (value.selectedCapabilities.some((name) => !supported.includes(name))) {
         throw new Error('unsupported artifacts transport capability');
     }
@@ -40,13 +45,25 @@ export function createHttpArtifactApp(deps) {
     if (typeof deps.legacyRecords?.get !== 'function')
         throw new Error('artifacts requires a legacy record inventory');
     const profile = deps.profile;
+    if (profile.selectedCapabilities.includes('artifacts_get_source') &&
+        (!deps.sources || !deps.publication.getRelease))
+        throw new Error('artifact source read ports required');
+    if (profile.selectedCapabilities.includes('artifacts_delete') && !deps.management?.confirmation) {
+        throw new Error('artifact delete confirmation port required');
+    }
     const ensure = createGuardedEnsureService({ profile, coordinator: deps.coordinator,
         derivation: deps.derivation, host: deps.ensureHost });
-    async function visible(artifactId, invocation) {
+    async function visible(artifactId, invocation, allowTerminalOwner = false) {
         const acl = await deps.acls.getArtifactAcl(artifactId);
         if (!acl || acl.storageScopeId !== invocation.storageScopeId)
             throw new ArtifactOperationError('not_found');
         const state = await deps.lifecycle.stateOf(artifactId);
+        if (acl.ownerId === invocation.actorId && (state === 'deleted' || state === 'purged')) {
+            // Management must still authorize terminal owners before replaying a receipt.
+            if (allowTerminalOwner)
+                return acl;
+            throw new ArtifactOperationError('gone');
+        }
         if (!deps.lifecycle.canRead({ artifactId, state }, acl, invocation.actorId, 'read', deps.isApprovedAccount)) {
             throw new ArtifactOperationError('not_found');
         }
@@ -93,9 +110,9 @@ export function createHttpArtifactApp(deps) {
                     }
                 }
                 const normalized = profile.validate(capability, args, request.idempotencyKey);
-                const command = capability === 'artifacts_ensure' || capability === 'artifacts_publish'
+                const command = ['artifacts_ensure', 'artifacts_publish', 'artifacts_set_access', 'artifacts_delete'].includes(capability)
                     ? createArtifactCommand(profile, capability, args, invocation, deps.derivation, request.idempotencyKey) : undefined;
-                if (command) {
+                if (command && ['ensure', 'publish'].includes(command.operation)) {
                     phase = 'migration';
                     await assertArtifactReplayMigration(deps.legacyRecords, command, invocation, normalized.idempotencyKey);
                 }
@@ -103,8 +120,39 @@ export function createHttpArtifactApp(deps) {
                 if (capability === 'artifacts_ensure') {
                     const outcome = await ensure.ensure(invocation, { ...normalized,
                         envelopeKey: request.idempotencyKey });
+                    if (outcome.ok) {
+                        const state = await deps.lifecycle.stateOf(outcome.result.artifactId);
+                        if (state === 'deleted' || state === 'purged')
+                            throw new ArtifactOperationError('gone');
+                    }
                     return outcome.ok ? { ...outcome, result: { status: 201, body: outcome.result } } : outcome;
                 }
+                if (capability === 'artifacts_get_source') {
+                    const artifactId = normalized.artifactId;
+                    const result = await readArtifactSource({
+                        storageScopeId: invocation.storageScopeId,
+                        authorize: async () => {
+                            const acl = await visible(artifactId, invocation);
+                            const state = await deps.lifecycle.stateOf(artifactId);
+                            if (!deps.lifecycle.canRead({ artifactId, state }, acl, invocation.actorId, 'source', deps.isApprovedAccount)) {
+                                throw new ArtifactOperationError('access_denied');
+                            }
+                        }, getCurrent: deps.publication.getCurrent, getRelease: deps.publication.getRelease,
+                        getSource: (id) => deps.sources.getSource(id), getBlob: (key) => deps.publication.blobs.getBlob(key),
+                        urls: deps.publicationUrls, maxFiles: 32, maxTotalBytes: 262144,
+                    }, normalized);
+                    return { ok: true, result: { status: 200, body: result }, invocationId: invocation.invocationId,
+                        commitState: 'not_committed', replayed: false };
+                }
+                if (capability === 'artifacts_set_access' || capability === 'artifacts_delete') {
+                    await visible(normalized.artifactId, invocation, true);
+                    const outcome = await manageArtifact({ coordinator: deps.coordinator,
+                        createUnit: deps.management?.createUnit ?? createPostgresManagementUnit,
+                        confirmation: deps.management?.confirmation, readPolicyRevision: () => deps.ensureHost.readPolicyRevision(),
+                        isApprovedPrincipal: deps.isApprovedAccount ?? (() => false),
+                    }, invocation, command, normalized.confirmationRef);
+                    return outcome.ok ? { ...outcome, result: { status: 200, body: outcome.result } } : outcome;
+                }
                 if (capability === 'artifacts_publish') {
                     const artifactId = normalized.artifactId;
                     const acl = await visible(artifactId, invocation);
@@ -146,8 +194,8 @@ export function createHttpArtifactApp(deps) {
                     const state = await deps.lifecycle.stateOf(artifactId);
                     const current = await deps.publication.getCurrent(artifactId);
                     return { ok: true, invocationId: invocation.invocationId, commitState: 'not_committed', replayed: false,
-                        result: { status: 200, body: { artifactId, ownerId: acl.ownerId, storageScopeId: acl.storageScopeId,
-                                state, isPublic: acl.isPublic, withdrawn: state === 'withdrawn', currentReleaseId: current?.releaseId,
+                        result: { status: 200, body: { ...artifactSummary({ artifactId, acl, state, current,
+                                    actorId: invocation.actorId, urls: deps.publicationUrls, approved: deps.isApprovedAccount }),
                                 ...(acl.ownerId === invocation.actorId ? { grants: acl.grants } : {}) } } };
                 }
                 const visibleArtifacts = [];
@@ -157,7 +205,8 @@ export function createHttpArtifactApp(deps) {
                         continue;
                     const state = await deps.lifecycle.stateOf(artifactId);
                     if (deps.lifecycle.canRead({ artifactId, state }, acl, invocation.actorId, 'read', deps.isApprovedAccount)) {
-                        visibleArtifacts.push({ artifactId, ownerId: acl.ownerId, state, isPublic: acl.isPublic });
+                        visibleArtifacts.push(artifactSummary({ artifactId, acl, state, actorId: invocation.actorId,
+                            current: await deps.publication.getCurrent(artifactId), urls: deps.publicationUrls, approved: deps.isApprovedAccount }));
                     }
                 }
                 const offset = normalized.offset;

package/dist/index.d.ts

@@ -25,3 +25,6 @@ export * from './server/reader-profile.js';
 export * from './http.js';
 export * from './server/commit-contract.js';
 export * from './server/outcome-contract.js';
+export * from './server/source-read.js';
+export * from './server/management.js';
+export * from './adapters/postgres-management.js';

package/dist/index.js

@@ -29,3 +29,6 @@ export * from './server/reader-profile.js';
 export * from './http.js';
 export * from './server/commit-contract.js';
 export * from './server/outcome-contract.js';
+export * from './server/source-read.js';
+export * from './server/management.js';
+export * from './adapters/postgres-management.js';

package/dist/mcp-core.d.ts

@@ -10,11 +10,11 @@ export { createRadarKeyDerivation } from './server/command-identity.js';
 export type { ArtifactKeyDerivationBinding } from './server/command-identity.js';
 export declare const ARTIFACTS_PROVIDER_ID = "sentropic.artifacts";
 export declare const ARTIFACTS_APP_ID = "sentropic-artifacts";
-export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.3";
+export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.5";
 export declare const ARTIFACTS_TOOL_NAMES: readonly ["artifacts_get_template", "artifacts_get_api_guide", "artifacts_ensure", "artifacts_publish", "artifacts_create_upload", "artifacts_commit_upload", "artifacts_list", "artifacts_get", "artifacts_get_source", "artifacts_fork", "artifacts_set_access", "artifacts_promote", "artifacts_renew", "artifacts_delete", "artifacts_restore"];
 export type ArtifactsToolName = (typeof ARTIFACTS_TOOL_NAMES)[number];
 export declare const ARTIFACTS_TOOL_SPECS: {
-    name: "artifacts_ensure" | "artifacts_publish" | "artifacts_get_template" | "artifacts_get_api_guide" | "artifacts_create_upload" | "artifacts_commit_upload" | "artifacts_list" | "artifacts_get" | "artifacts_get_source" | "artifacts_fork" | "artifacts_set_access" | "artifacts_promote" | "artifacts_renew" | "artifacts_delete" | "artifacts_restore";
+    name: "artifacts_ensure" | "artifacts_publish" | "artifacts_set_access" | "artifacts_delete" | "artifacts_get_template" | "artifacts_get_api_guide" | "artifacts_create_upload" | "artifacts_commit_upload" | "artifacts_list" | "artifacts_get" | "artifacts_get_source" | "artifacts_fork" | "artifacts_promote" | "artifacts_renew" | "artifacts_restore";
     description: string;
     mutability: import("@sentropic/mcp-platform").Mutability;
 }[];