@sentropic/artifacts 0.2.2 → 0.2.4

package/README.md

@@ -1,5 +1,154 @@
 # @sentropic/artifacts — generic artifact contracts (L-5a)
 
+## Shared PostgreSQL activation (UP-T, 0.2.3)
+
+W1.c/W3.a and Radar S1/A6 use the same imports:
+
+```ts
+import {
+  createPostgresActivationStore, ACTIVATION_MAX_TTL_SECONDS, ACTIVATION_SQL_ASSET,
+  ACTIVATION_SQL_ASSET_SHA256,
+} from '@sentropic/artifacts/adapters/postgres-activation';
+import { createTicketService } from '@sentropic/artifacts/content/grants';
+import { readFile } from 'node:fs/promises';
+
+const sql = await readFile(new URL(import.meta.resolve(ACTIVATION_SQL_ASSET)), 'utf8');
+// Apply these exact bytes once through the host's journaled migration executor.
+const activation = createPostgresActivationStore({ pool, namespace: trustedHostNamespace });
+const tickets = createTicketService({ store: activation.tickets, ttlSeconds: ACTIVATION_MAX_TTL_SECONDS });
+```
+
+The SQL asset is `@sentropic/artifacts/sql/0001_activation.sql`; it creates the
+independent `artifact_host` schema. The adapter never applies DDL or opens a
+connection on construction. Journal the asset hash and verify it against
+`ACTIVATION_SQL_ASSET_SHA256` before serving. A unit test pins the exact file bytes;
+future schema changes require a new numbered SQL asset.
+This store is independent of the publication coordinator.
+
+Persist a flow through `activation.flows.put`: `flowId`, `ticketId`, `subjectId`,
+`artifactId`, `releaseId`, `channel`, `nonceDigest`, `sessionId`, `profileDigest`,
+`policyRevision`, `targetOrigin`, `expiresAt`. Nonce/profile digests are lowercase
+SHA-256 hex; the origin is an exact HTTPS origin. One flow is associated with one
+ticket. Both IDs must be fresh cryptographically random values, never reused on
+retry or after cleanup. Duplicate IDs reject; records cannot be updated. The
+trusted namespace comes from host configuration, never browser input.
+
+`createTicketService` uses the adapter's optional `tickets.issue(record, ttlMs)`
+port: PostgreSQL samples its clock after lock waits and adds the requested TTL
+in SQL. The returned deadline is authoritative; issuance and redemption tolerate
+application clock skew. Use that returned deadline for the browser flow, whose
+expiry must be live and no later than its ticket. Low-level `tickets.put` imports
+an absolute PostgreSQL-time deadline and enforces the same 60-second cap. The historical
+120-second default of `createTicketService` is unchanged; hosts explicitly select
+`ttlSeconds <= ACTIVATION_MAX_TTL_SECONDS` for this adapter.
+
+For browser activation call `activation.consume({flowId,ticketId,expected},
+authorize)`. `expected` contains every flow binding above except IDs and expiry.
+Obtain these values from verified session/browser evidence and compiled policy.
+The adapter locks namespace, flow, then ticket on one leased READ COMMITTED client,
+checks exact bindings and database-time expiry after lock waits, invokes current
+authority, and checks expiry again after authority waits at the atomic deletion.
+Missing/expired/wrong bindings and explicit denial return `undefined`; authority
+outage and transaction failures reject. Neither path permits a grant.
+
+The host's `authorize({client,namespace,ticket,flow})` must recheck current session,
+ACL, policy/profile, exact origin and stable-release fence on that client, holding
+the relevant policy locks until COMMIT. Return `true` only with this protection.
+Do not sign, set cookies, or perform externally visible effects in this callback.
+Sign and emit a host-only cookie only after `consume` resolves with a record.
+`ActivationCommitUnknownError` means issue no grant; obtain a fresh ticket/flow
+after a new authority check. A crash after commit similarly requires a fresh
+flow. Do not automatically replay a consumed ticket. Standalone `tickets.take`
+implements the existing port; browser activation uses the combined operation.
+
+Schedule `cleanup(limit)` at least once per minute and collect counts/errors
+without token values. It deletes at most `limit` total rows (default 100, maximum
+1000), skips locked candidates and respects namespace boundaries. Expiry denial
+works even when cleanup stops. Ordinary application-process restart preserves
+live state and single use.
+
+During restore keep both replicas/issuers closed, restore the activation tables
+and migration journal alongside business/ACL state, call `invalidate()` for each
+trusted namespace, and rotate the host signing credential before admitting
+either replica. Invalidation advances a durable namespace generation in O(1);
+all restored tickets/flows deny immediately and bounded cleanup removes them.
+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.
+
+### 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
+environment. The vectors cover namespace/binding isolation, immutable IDs,
+one connection, no pre-commit result, uncertain commit, DB expiry after lock and
+authority waits, bounded cleanup, two OS processes, restart, race, crashes before
+and after commit, restored snapshot invalidation and fresh authority recovery.
+Host migration/journal, actual session/ACL fences, signing-key rotation and real
+browser/deployment receipts remain W1.c/W3.a/A6 obligations.
+
 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

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-activation.d.ts

@@ -0,0 +1,59 @@
+import type { Pool, PoolClient } from 'pg';
+import type { TicketBinding, TicketRecord, TicketStore } from '../content/grants.js';
+export declare const ACTIVATION_MAX_TTL_SECONDS = 60;
+export declare const ACTIVATION_SQL_ASSET = "@sentropic/artifacts/sql/0001_activation.sql";
+export declare const ACTIVATION_SQL_ASSET_SHA256 = "13767c826a62aa5f880809ca2ebc60bdc638b2e59f983e195d4351356b282d8b";
+export interface BrowserFlowBinding extends TicketBinding {
+    nonceDigest: string;
+    sessionId: string;
+    profileDigest: string;
+    policyRevision: string;
+    targetOrigin: string;
+}
+export interface BrowserFlowRecord extends BrowserFlowBinding {
+    flowId: string;
+    ticketId: string;
+    expiresAt: number;
+}
+export interface BrowserFlowStore {
+    put(record: BrowserFlowRecord): Promise<void>;
+    peek(flowId: string): Promise<BrowserFlowRecord | undefined>;
+    remove(flowId: string): Promise<void>;
+}
+export interface ActivationConsumeInput {
+    flowId: string;
+    ticketId: string;
+    expected: BrowserFlowBinding;
+}
+/** Host locks current session/ACL/release/policy on this client through COMMIT.
+ * No cookies, signing or externally visible effects inside this callback.
+ */
+export type ActivationAuthority = (context: {
+    client: PoolClient;
+    namespace: string;
+    ticket: Readonly<TicketRecord>;
+    flow: Readonly<BrowserFlowRecord>;
+}) => Promise<boolean>;
+export interface PostgresActivationStore {
+    tickets: TicketStore;
+    flows: BrowserFlowStore;
+    consume(input: ActivationConsumeInput, authorize: ActivationAuthority): Promise<TicketRecord | undefined>;
+    /** Total deleted rows <= limit (1..1000), including no unbounded cascades. */
+    cleanup(limit?: number): Promise<{
+        flows: number;
+        tickets: number;
+    }>;
+    /** Closed-serving restore step: invalidate all prior state in O(1). Rotate signing keys separately. */
+    invalidate(): Promise<void>;
+}
+export declare class ActivationCommitUnknownError extends Error {
+    constructor(cause: unknown);
+}
+/** No eager I/O or DDL. Hosts issue fresh random IDs with ttlSeconds <=60.
+ * Use consume for browser activation; standalone TicketStore supports existing services.
+ * Only an acknowledged consume result permits the host to sign/set a grant cookie.
+ */
+export declare function createPostgresActivationStore(options: {
+    pool: Pool;
+    namespace: string;
+}): PostgresActivationStore;

package/dist/adapters/postgres-activation.js

@@ -0,0 +1,218 @@
+export const ACTIVATION_MAX_TTL_SECONDS = 60;
+export const ACTIVATION_SQL_ASSET = '@sentropic/artifacts/sql/0001_activation.sql';
+export const ACTIVATION_SQL_ASSET_SHA256 = '13767c826a62aa5f880809ca2ebc60bdc638b2e59f983e195d4351356b282d8b';
+export class ActivationCommitUnknownError extends Error {
+    constructor(cause) {
+        super('activation commit outcome unknown; start a fresh flow', { cause });
+        this.name = 'ActivationCommitUnknownError';
+    }
+}
+const bindingKeys = ['subjectId', 'artifactId', 'releaseId', 'channel'];
+const flowKeys = [...bindingKeys, 'nonceDigest', 'sessionId', 'profileDigest', 'policyRevision', 'targetOrigin'];
+const nowSql = 'floor(extract(epoch FROM clock_timestamp()) * 1000)';
+function text(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 256 ||
+        value.includes('\0') || Buffer.from(value).toString('utf8') !== value) {
+        throw new Error('invalid activation binding');
+    }
+    return value;
+}
+function binding(value) {
+    if (value.channel !== 'stable' && value.channel !== 'pinned')
+        throw new Error('invalid activation channel');
+    return { subjectId: text(value.subjectId), artifactId: text(value.artifactId),
+        releaseId: text(value.releaseId), channel: value.channel };
+}
+function deadline(value) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error('invalid activation deadline');
+    return value;
+}
+function flowBinding(value) {
+    const targetOrigin = text(value.targetOrigin);
+    const url = new URL(targetOrigin);
+    if (url.protocol !== 'https:' || url.origin !== targetOrigin)
+        throw new Error('invalid activation origin');
+    for (const digest of [value.nonceDigest, value.profileDigest]) {
+        if (!/^[0-9a-f]{64}$/.test(digest))
+            throw new Error('invalid activation digest');
+    }
+    return { ...binding(value), nonceDigest: value.nonceDigest, profileDigest: value.profileDigest,
+        sessionId: text(value.sessionId), policyRevision: text(value.policyRevision), targetOrigin };
+}
+async function transaction(pool, namespace, work, exclusive = false) {
+    const client = await pool.connect();
+    let committing = false;
+    let destroy = false;
+    try {
+        await client.query('BEGIN ISOLATION LEVEL READ COMMITTED');
+        await client.query('INSERT INTO artifact_host.activation_namespaces(namespace) VALUES ($1) ON CONFLICT DO NOTHING', [namespace]);
+        const { rows } = await client.query(`SELECT generation FROM artifact_host.activation_namespaces WHERE namespace=$1 FOR ${exclusive ? 'UPDATE' : 'SHARE'}`, [namespace]);
+        const result = await work(client, rows[0].generation);
+        committing = true;
+        await client.query('COMMIT');
+        return result;
+    }
+    catch (cause) {
+        if (committing) {
+            destroy = true;
+            throw new ActivationCommitUnknownError(cause);
+        }
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch {
+            destroy = true;
+        }
+        throw cause;
+    }
+    finally {
+        client.release(destroy);
+    }
+}
+function recordStores(run, namespace) {
+    const parameters = (id, generation) => [namespace, text(id), generation];
+    async function lockTicket(client, id, generation) {
+        // Same lock order as consume: browser flow, then ticket (including cascades).
+        await client.query('SELECT flow_id FROM artifact_host.browser_flows WHERE namespace=$1 AND ticket_id=$2 FOR UPDATE', [namespace, id]);
+        await client.query('SELECT ticket_id FROM artifact_host.activation_tickets WHERE namespace=$1 AND ticket_id=$2 AND generation=$3 FOR UPDATE', parameters(id, generation));
+    }
+    const tickets = {
+        async issue(value, ttlMs) {
+            if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > ACTIVATION_MAX_TTL_SECONDS * 1000) {
+                throw new Error('invalid activation lifetime');
+            }
+            const payload = { ...binding(value), ticketId: text(value.ticketId) };
+            return run(async (client, generation) => {
+                const { rows } = await client.query(`WITH issued AS (SELECT ${nowSql}::bigint AS ms)
+           INSERT INTO artifact_host.activation_tickets(namespace,generation,payload,issued_ms)
+           SELECT $1,$2,jsonb_set($3::jsonb,'{expiresAt}',to_jsonb(ms+$4::bigint)),ms FROM issued
+           RETURNING payload`, [namespace, generation, JSON.stringify(payload), ttlMs]);
+                return rows[0].payload;
+            });
+        },
+        async put(value) {
+            const payload = { ...binding(value), ticketId: text(value.ticketId), expiresAt: deadline(value.expiresAt) };
+            await run(async (client, generation) => {
+                await client.query('INSERT INTO artifact_host.activation_tickets(namespace,generation,payload) VALUES ($1,$2,$3)', [namespace, generation, JSON.stringify(payload)]);
+            });
+        },
+        async peek(id) {
+            text(id);
+            return run(async (client, generation) => {
+                const { rows } = await client.query(`SELECT payload FROM artifact_host.activation_tickets WHERE namespace=$1 AND ticket_id=$2 AND generation=$3 AND expires_ms>${nowSql}`, parameters(id, generation));
+                return rows[0]?.payload;
+            });
+        },
+        async take(id) {
+            text(id);
+            return run(async (client, generation) => {
+                await lockTicket(client, id, generation);
+                const { rows } = await client.query(`DELETE FROM artifact_host.activation_tickets WHERE namespace=$1 AND ticket_id=$2 AND generation=$3 AND expires_ms>${nowSql} RETURNING payload`, parameters(id, generation));
+                return rows[0]?.payload;
+            });
+        },
+        async remove(id) {
+            text(id);
+            await run(async (client, generation) => {
+                await lockTicket(client, id, generation);
+                await client.query('DELETE FROM artifact_host.activation_tickets WHERE namespace=$1 AND ticket_id=$2 AND generation=$3', parameters(id, generation));
+            });
+        },
+    };
+    const flows = {
+        async put(value) {
+            const payload = { ...flowBinding(value), flowId: text(value.flowId),
+                ticketId: text(value.ticketId), expiresAt: deadline(value.expiresAt) };
+            await run(async (client, generation) => {
+                await client.query('SELECT ticket_id FROM artifact_host.activation_tickets WHERE namespace=$1 AND ticket_id=$2 AND generation=$3 FOR UPDATE', parameters(payload.ticketId, generation));
+                const { rowCount } = await client.query(`INSERT INTO artifact_host.browser_flows(namespace,generation,payload,ticket_expires_ms)
+           SELECT namespace,generation,$4,expires_ms FROM artifact_host.activation_tickets
+           WHERE namespace=$1 AND ticket_id=$2 AND generation=$3 AND expires_ms>${nowSql} AND $5::bigint>${nowSql}`, [...parameters(payload.ticketId, generation), JSON.stringify(payload), payload.expiresAt]);
+                if (rowCount !== 1)
+                    throw new Error('invalid activation ticket');
+            });
+        },
+        async peek(id) {
+            text(id);
+            return run(async (client, generation) => {
+                const { rows } = await client.query(`SELECT payload FROM artifact_host.browser_flows WHERE namespace=$1 AND flow_id=$2 AND generation=$3 AND expires_ms>${nowSql}`, parameters(id, generation));
+                return rows[0]?.payload;
+            });
+        },
+        async remove(id) {
+            text(id);
+            await run(async (client, generation) => {
+                await client.query('DELETE FROM artifact_host.browser_flows WHERE namespace=$1 AND flow_id=$2 AND generation=$3', parameters(id, generation));
+            });
+        },
+    };
+    return { tickets, flows };
+}
+/** No eager I/O or DDL. Hosts issue fresh random IDs with ttlSeconds <=60.
+ * Use consume for browser activation; standalone TicketStore supports existing services.
+ * Only an acknowledged consume result permits the host to sign/set a grant cookie.
+ */
+export function createPostgresActivationStore(options) {
+    const namespace = text(options.namespace);
+    const pool = options.pool;
+    const run = work => transaction(pool, namespace, work);
+    return {
+        ...recordStores(run, namespace),
+        async consume(value, authorize) {
+            // Snapshot before acquisition waits; callers cannot retarget an in-flight consume.
+            const flowId = text(value.flowId);
+            const ticketId = text(value.ticketId);
+            const expected = { ...value.expected };
+            return run(async (client, generation) => {
+                const params = [namespace, flowId, generation];
+                const flowResult = await client.query('SELECT payload FROM artifact_host.browser_flows WHERE namespace=$1 AND flow_id=$2 AND generation=$3 FOR UPDATE', params);
+                const flow = flowResult.rows[0]?.payload;
+                if (!flow || flow.ticketId !== ticketId || flowKeys.some(key => flow[key] !== expected[key]))
+                    return undefined;
+                const ticketResult = await client.query('SELECT payload FROM artifact_host.activation_tickets WHERE namespace=$1 AND ticket_id=$2 AND generation=$3 FOR UPDATE', [namespace, ticketId, generation]);
+                const ticket = ticketResult.rows[0]?.payload;
+                if (!ticket || bindingKeys.some(key => ticket[key] !== expected[key]))
+                    return undefined;
+                // This read happens AFTER both row-lock waits; authority may wait again.
+                const live = await client.query(`SELECT 1 FROM artifact_host.browser_flows
+          WHERE namespace=$1 AND flow_id=$2 AND generation=$3 AND expires_ms>${nowSql}`, params);
+                if (live.rows.length === 0)
+                    return undefined;
+                if (await authorize({ client, namespace, ticket: Object.freeze({ ...ticket }), flow: Object.freeze({ ...flow }) }) !== true)
+                    return undefined;
+                // One visibility decision after ALL authority waits; cascade consumes the flow.
+                const consumed = await client.query(`DELETE FROM artifact_host.activation_tickets t WHERE t.namespace=$1 AND t.ticket_id=$2
+           AND t.generation=$3 AND t.expires_ms>${nowSql} AND EXISTS (
+             SELECT 1 FROM artifact_host.browser_flows f WHERE f.namespace=t.namespace
+             AND f.ticket_id=t.ticket_id AND f.flow_id=$4 AND f.generation=t.generation AND f.expires_ms>${nowSql})
+           RETURNING payload`, [namespace, ticketId, generation, flowId]);
+                return consumed.rows[0]?.payload;
+            });
+        },
+        async cleanup(limit = 100) {
+            if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+                throw new Error('invalid activation cleanup limit');
+            return run(async (client, generation) => {
+                const flows = await client.query(`WITH due AS (
+          SELECT flow_id FROM artifact_host.browser_flows WHERE namespace=$1
+          AND (expires_ms<=${nowSql} OR generation<$2) ORDER BY expires_ms,flow_id
+          LIMIT $3 FOR UPDATE SKIP LOCKED)
+          DELETE FROM artifact_host.browser_flows f USING due WHERE f.namespace=$1 AND f.flow_id=due.flow_id`, [namespace, generation, limit]);
+                const flowCount = flows.rowCount ?? 0;
+                const tickets = await client.query(`WITH due AS (
+          SELECT ticket_id FROM artifact_host.activation_tickets t WHERE namespace=$1
+          AND (expires_ms<=${nowSql} OR generation<$2)
+          AND NOT EXISTS (SELECT 1 FROM artifact_host.browser_flows f WHERE f.namespace=t.namespace AND f.ticket_id=t.ticket_id)
+          ORDER BY expires_ms,ticket_id LIMIT $3 FOR UPDATE SKIP LOCKED)
+          DELETE FROM artifact_host.activation_tickets t USING due WHERE t.namespace=$1 AND t.ticket_id=due.ticket_id`, [namespace, generation, limit - flowCount]);
+                return { flows: flowCount, tickets: tickets.rowCount ?? 0 };
+            });
+        },
+        async invalidate() {
+            await transaction(pool, namespace, async (client) => {
+                await client.query('UPDATE artifact_host.activation_namespaces SET generation=generation+1 WHERE namespace=$1', [namespace]);
+            }, true);
+        },
+    };
+}

package/dist/content/grants.d.ts

@@ -33,6 +33,8 @@ export interface TicketRecord extends TicketBinding {
     expiresAt: number;
 }
 export interface TicketStore {
+    /** Optional authoritative-clock issuance; peek/take must also deny expired records. */
+    issue?(record: Omit<TicketRecord, 'expiresAt'>, ttlMs: number): Promise<TicketRecord>;
     put(record: TicketRecord): Promise<void>;
     peek(ticketId: string): Promise<TicketRecord | undefined>;
     /** Atomically remove and return the record (single-use consumption). */

package/dist/content/grants.js

@@ -111,6 +111,10 @@ export function createTicketService(options) {
                 (input.channel !== 'stable' && input.channel !== 'pinned'))
                 throw new Error('invalid ticket: binding');
             const ticketId = ids();
+            if (options.store.issue) {
+                const record = await options.store.issue({ ...input, ticketId }, ttlMs);
+                return { ticketId: record.ticketId, expiresAt: record.expiresAt };
+            }
             const expiresAt = clock() + ttlMs;
             await options.store.put({
                 ticketId,
@@ -126,7 +130,7 @@ export function createTicketService(options) {
             const record = await options.store.peek(ticketId);
             if (record === undefined)
                 throw new Error('invalid ticket');
-            if (clock() >= record.expiresAt) {
+            if (!options.store.issue && clock() >= record.expiresAt) {
                 await options.store.remove(ticketId);
                 throw new Error('ticket expired');
             }

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.2";
+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.2';
+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.2",
+  "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",
@@ -41,6 +41,15 @@
       "types": "./dist/adapters/postgres-commit.d.ts",
       "import": "./dist/adapters/postgres-commit.js"
     },
+    "./adapters/postgres-activation": {
+      "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": {
       "types": "./dist/server/ports.d.ts",
@@ -168,6 +177,7 @@
     "l0-freeze",
     "src/contracts.ts",
     "migrations",
+    "sql",
     "docs/migration-l6.md",
     "examples/radar-commit-setup.ts",
     "README.md",

package/sql/0001_activation.sql

@@ -0,0 +1,70 @@
+-- UP-T v1. Host migration executor owns serialization, transaction and journal.
+-- Independent of the publication schema. Never run DDL on adapter construction.
+CREATE SCHEMA IF NOT EXISTS artifact_host;
+
+CREATE TABLE artifact_host.activation_namespaces (
+  namespace text PRIMARY KEY CHECK (length(namespace) BETWEEN 1 AND 256),
+  generation bigint NOT NULL DEFAULT 1 CHECK (generation > 0)
+);
+
+CREATE TABLE artifact_host.activation_tickets (
+  namespace text NOT NULL REFERENCES artifact_host.activation_namespaces(namespace),
+  generation bigint NOT NULL,
+  payload jsonb NOT NULL,
+  ticket_id text GENERATED ALWAYS AS (payload->>'ticketId') STORED NOT NULL,
+  subject_id text GENERATED ALWAYS AS (payload->>'subjectId') STORED NOT NULL,
+  artifact_id text GENERATED ALWAYS AS (payload->>'artifactId') STORED NOT NULL,
+  release_id text GENERATED ALWAYS AS (payload->>'releaseId') STORED NOT NULL,
+  channel text GENERATED ALWAYS AS (payload->>'channel') STORED NOT NULL,
+  expires_ms bigint GENERATED ALWAYS AS ((payload->>'expiresAt')::bigint) STORED NOT NULL,
+  issued_ms bigint NOT NULL DEFAULT floor(extract(epoch FROM clock_timestamp()) * 1000),
+  PRIMARY KEY (namespace, ticket_id),
+  UNIQUE (namespace, generation, ticket_id, subject_id, artifact_id, release_id, channel, expires_ms),
+  CHECK (length(ticket_id) BETWEEN 1 AND 256 AND length(subject_id) BETWEEN 1 AND 256),
+  CHECK (length(artifact_id) BETWEEN 1 AND 256 AND length(release_id) BETWEEN 1 AND 256),
+  CHECK (channel IN ('stable', 'pinned')),
+  CHECK (jsonb_typeof(payload->'expiresAt') = 'number'),
+  CHECK (expires_ms > issued_ms AND expires_ms <= issued_ms + 60000)
+);
+CREATE INDEX activation_tickets_expiry ON artifact_host.activation_tickets(namespace, expires_ms, ticket_id);
+CREATE INDEX activation_tickets_generation ON artifact_host.activation_tickets(namespace, generation, ticket_id);
+
+CREATE TABLE artifact_host.browser_flows (
+  namespace text NOT NULL,
+  generation bigint NOT NULL,
+  payload jsonb NOT NULL,
+  flow_id text GENERATED ALWAYS AS (payload->>'flowId') STORED NOT NULL,
+  ticket_id text GENERATED ALWAYS AS (payload->>'ticketId') STORED NOT NULL,
+  subject_id text GENERATED ALWAYS AS (payload->>'subjectId') STORED NOT NULL,
+  artifact_id text GENERATED ALWAYS AS (payload->>'artifactId') STORED NOT NULL,
+  release_id text GENERATED ALWAYS AS (payload->>'releaseId') STORED NOT NULL,
+  channel text GENERATED ALWAYS AS (payload->>'channel') STORED NOT NULL,
+  expires_ms bigint GENERATED ALWAYS AS ((payload->>'expiresAt')::bigint) STORED NOT NULL,
+  ticket_expires_ms bigint NOT NULL,
+  PRIMARY KEY (namespace, flow_id),
+  UNIQUE (namespace, ticket_id),
+  FOREIGN KEY (namespace, generation, ticket_id, subject_id, artifact_id, release_id, channel, ticket_expires_ms)
+    REFERENCES artifact_host.activation_tickets
+      (namespace, generation, ticket_id, subject_id, artifact_id, release_id, channel, expires_ms)
+    ON DELETE CASCADE,
+  CHECK (length(flow_id) BETWEEN 1 AND 256),
+  CHECK (expires_ms <= ticket_expires_ms),
+  CHECK (jsonb_typeof(payload->'expiresAt') = 'number'),
+  CHECK (length(payload->>'sessionId') BETWEEN 1 AND 256 AND payload->>'sessionId' IS NOT NULL),
+  CHECK (length(payload->>'policyRevision') BETWEEN 1 AND 256 AND payload->>'policyRevision' IS NOT NULL),
+  CHECK (payload->>'nonceDigest' ~ '^[0-9a-f]{64}$' AND payload->>'nonceDigest' IS NOT NULL),
+  CHECK (payload->>'profileDigest' ~ '^[0-9a-f]{64}$' AND payload->>'profileDigest' IS NOT NULL),
+  CHECK (payload->>'targetOrigin' ~ '^https://[^/]+$' AND payload->>'targetOrigin' IS NOT NULL)
+);
+CREATE INDEX browser_flows_expiry ON artifact_host.browser_flows(namespace, expires_ms, flow_id);
+CREATE INDEX browser_flows_generation ON artifact_host.browser_flows(namespace, generation, flow_id);
+
+CREATE FUNCTION artifact_host.activation_immutable() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+  RAISE EXCEPTION 'activation records are immutable' USING ERRCODE = '23000';
+END;
+$$;
+CREATE TRIGGER activation_tickets_immutable BEFORE UPDATE ON artifact_host.activation_tickets
+  FOR EACH ROW EXECUTE FUNCTION artifact_host.activation_immutable();
+CREATE TRIGGER browser_flows_immutable BEFORE UPDATE ON artifact_host.browser_flows
+  FOR EACH ROW EXECUTE FUNCTION artifact_host.activation_immutable();