@sentropic/artifacts 0.2.3 → 0.2.4

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

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/mcp-core.d.ts

@@ -10,7 +10,7 @@ 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.4";
 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: {

package/dist/mcp-core.js

@@ -6,7 +6,7 @@ export * from './profile/index.js';
 export { createRadarKeyDerivation } from './server/command-identity.js';
 export const ARTIFACTS_PROVIDER_ID = 'sentropic.artifacts';
 export const ARTIFACTS_APP_ID = 'sentropic-artifacts';
-export const ARTIFACTS_PROVIDER_VERSION = '0.2.3';
+export const ARTIFACTS_PROVIDER_VERSION = '0.2.4';
 export const ARTIFACTS_TOOL_NAMES = ARTIFACT_CAPABILITY_NAMES;
 export const ARTIFACTS_TOOL_SPECS = ARTIFACTS_TOOL_NAMES.map((name) => ({ name,
     description: `Artifacts ${name.slice('artifacts_'.length).replaceAll('_', ' ')}.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/artifacts",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Generic configurable artifacts MCP and artifact service: StorageScope/Artifact/Binding/Release model, canonical manifests, object authorization, idempotent intents (spec-v8 §9).",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,10 @@
       "types": "./dist/adapters/postgres-activation.d.ts",
       "import": "./dist/adapters/postgres-activation.js"
     },
+    "./adapters/postgres-activation/vectors": {
+      "types": "./dist/adapters/postgres-activation-vectors.d.ts",
+      "import": "./dist/adapters/postgres-activation-vectors.js"
+    },
     "./sql/*": "./sql/*",
     "./migrations/*": "./migrations/*",
     "./server/ports": {