@aiwg/cli 2026.8.20 → 2026.8.26

package/dist/src/storage/backends/postgres.js

@@ -0,0 +1,468 @@
+import { createHash } from 'node:crypto';
+import { loadFeaturePackage } from '../../features/runtime.js';
+import { STORAGE_BACKEND_CONTRACT, } from '../backend-contract.js';
+import { POSTGRES_SCHEMA_V1_SQL } from './postgres-schema.js';
+const SCHEMA_VERSION = '1';
+const DEFAULT_POOL_MAX = 10;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_LOCK_TIMEOUT_MS = 5_000;
+const DEFAULT_IDLE_TRANSACTION_TIMEOUT_MS = 30_000;
+export class PostgresBackendError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'PostgresBackendError';
+    }
+}
+/**
+ * Advanced canonical backend for aiwg.storage-backend/v1.
+ *
+ * A checked-out client owns every transaction. Record effects, the durable
+ * idempotency receipt, and its high-water mark commit together. The class is
+ * asynchronous by design and does not implement the legacy synchronous
+ * GraphBackend interface.
+ */
+export class PostgresStorageBackend {
+    options;
+    descriptor = {
+        contract: STORAGE_BACKEND_CONTRACT,
+        backend: 'postgres-direct',
+        implementationVersion: '1.0.0',
+        schemaVersion: SCHEMA_VERSION,
+        maturity: 'advanced',
+        capabilities: [
+            'read', 'atomic-batch', 'consistent-snapshot', 'change-cursor',
+            'tombstones', 'idempotency-keys', 'recursive-traversal', 'set-operations',
+            'filtered-query', 'cursor-pagination', 'health', 'readiness', 'telemetry',
+            'tenant-isolation', 'subsystem-isolation', 'tls',
+        ],
+        durability: 'replicated',
+        availability: 'remote-service',
+        isolation: 'serializable',
+        dataClass: 'canonical',
+    };
+    identity;
+    pool;
+    ownsPool;
+    statementTimeoutMs;
+    lockTimeoutMs;
+    idleTransactionTimeoutMs;
+    constructor(options) {
+        this.options = options;
+        validateIdentity(options.tenant, 'tenant');
+        validateIdentity(options.subsystem, 'subsystem');
+        this.pool = options.pool;
+        this.ownsPool = !options.pool;
+        this.statementTimeoutMs = bounded(options.statementTimeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'statementTimeoutMs');
+        this.lockTimeoutMs = bounded(options.lockTimeoutMs, DEFAULT_LOCK_TIMEOUT_MS, 1, 600_000, 'lockTimeoutMs');
+        this.idleTransactionTimeoutMs = bounded(options.idleTransactionTimeoutMs, DEFAULT_IDLE_TRANSACTION_TIMEOUT_MS, 1, 600_000, 'idleTransactionTimeoutMs');
+        this.identity = {
+            backend: 'postgres-direct',
+            instance: options.instance ?? 'default',
+            tenant: options.tenant,
+            subsystem: options.subsystem,
+            schemaVersion: SCHEMA_VERSION,
+        };
+    }
+    async init() {
+        if (!this.pool)
+            this.pool = await createPool(this.options);
+        if (this.options.schemaMode !== 'migrate') {
+            const schema = await this.runQuery('SELECT schema_version FROM aiwg_storage_schema WHERE singleton = true');
+            if (Number(schema.rows[0]?.schema_version) !== 1) {
+                throw new PostgresBackendError('AIWG_POSTGRES_SCHEMA_UNAVAILABLE', 'PostgreSQL storage schema v1 is unavailable; initialize it with the separate migration role');
+            }
+            return;
+        }
+        await this.withTransaction(async (client) => {
+            await client.query(POSTGRES_SCHEMA_V1_SQL);
+            const schema = await client.query('SELECT schema_version FROM aiwg_storage_schema WHERE singleton = true');
+            if (Number(schema.rows[0]?.schema_version) !== 1) {
+                throw new PostgresBackendError('AIWG_POSTGRES_SCHEMA_UNSUPPORTED', 'PostgreSQL storage schema is not version 1');
+            }
+        });
+    }
+    async commitBatch(mutations) {
+        if (mutations.length === 0)
+            throw new PostgresBackendError('AIWG_POSTGRES_EMPTY_BATCH', 'batch must contain at least one mutation');
+        const batchId = postgresBatchId(mutations);
+        const payloadDigest = postgresPayloadDigest(mutations);
+        return this.withTransaction(async (client) => {
+            const prior = await client.query(`SELECT payload_digest, receipt FROM aiwg_storage_batch_receipts
+         WHERE tenant=$1 AND subsystem=$2 AND batch_id=$3`, [this.options.tenant, this.options.subsystem, batchId]);
+            if (prior.rows[0]) {
+                if (prior.rows[0].payload_digest !== payloadDigest) {
+                    throw new PostgresBackendError('AIWG_POSTGRES_IDEMPOTENCY_CONFLICT', 'batch id was reused with different mutations');
+                }
+                return prior.rows[0].receipt;
+            }
+            const recordReceipts = [];
+            let highWaterMark = '0';
+            for (const mutation of mutations) {
+                this.assertMutationIdentity(mutation);
+                const tombstone = mutation.operation === 'delete' || Boolean(mutation.record.tombstone);
+                const result = await client.query(`INSERT INTO aiwg_storage_records
+             (tenant, subsystem, path, source_revision, digest, value, tombstone,
+              deleted_at, delete_reason, idempotency_key)
+           VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7,$8,$9,$10)
+           ON CONFLICT (tenant, subsystem, path) DO UPDATE SET
+             source_revision=EXCLUDED.source_revision, digest=EXCLUDED.digest,
+             value=EXCLUDED.value, tombstone=EXCLUDED.tombstone,
+             deleted_at=EXCLUDED.deleted_at, delete_reason=EXCLUDED.delete_reason,
+             idempotency_key=EXCLUDED.idempotency_key,
+             change_seq=nextval(pg_get_serial_sequence('aiwg_storage_records','change_seq')),
+             updated_at=clock_timestamp()
+           WHERE $11::text IS NULL OR aiwg_storage_records.source_revision=$11
+           RETURNING tenant, subsystem, path, source_revision, digest, value,
+                     tombstone, deleted_at, delete_reason, change_seq`, [
+                    this.options.tenant, this.options.subsystem, mutation.record.identity.path,
+                    mutation.record.sourceRevision, mutation.record.digest,
+                    JSON.stringify(mutation.record.value ?? null), tombstone,
+                    mutation.record.tombstone?.deletedAt ?? null,
+                    mutation.record.tombstone?.reason ?? null, mutation.idempotencyKey,
+                    mutation.expectedRevision ?? null,
+                ]);
+                if (result.rowCount !== 1 || !result.rows[0]) {
+                    throw new PostgresBackendError('AIWG_POSTGRES_REVISION_CONFLICT', `revision conflict for ${mutation.record.identity.path}`, true);
+                }
+                highWaterMark = String(result.rows[0].change_seq);
+                recordReceipts.push({
+                    identity: mutation.record.identity,
+                    sourceRevision: mutation.record.sourceRevision,
+                    digest: mutation.record.digest,
+                });
+            }
+            const receipt = { batchId, committed: true, highWaterMark, recordReceipts };
+            await client.query(`INSERT INTO aiwg_storage_batch_receipts
+           (tenant, subsystem, batch_id, payload_digest, high_water_mark, receipt)
+         VALUES ($1,$2,$3,$4,$5,$6::jsonb)`, [this.options.tenant, this.options.subsystem, batchId, payloadDigest, highWaterMark, JSON.stringify(receipt)]);
+            return receipt;
+        });
+    }
+    async get(path) {
+        const result = await this.runQuery(`SELECT tenant, subsystem, path, source_revision, digest, value,
+              tombstone, deleted_at, delete_reason, change_seq
+       FROM aiwg_storage_records WHERE tenant=$1 AND subsystem=$2 AND path=$3`, [this.options.tenant, this.options.subsystem, path]);
+        return result.rows[0] ? recordFromRow(result.rows[0]) : null;
+    }
+    async readAll() {
+        const result = await this.runQuery(`SELECT tenant, subsystem, path, source_revision, digest, value,
+              tombstone, deleted_at, delete_reason, change_seq
+       FROM aiwg_storage_records WHERE tenant=$1 AND subsystem=$2 ORDER BY path`, [this.options.tenant, this.options.subsystem]);
+        return result.rows.map((recordFromRow));
+    }
+    async query(filters, limit = 100, cursor) {
+        const boundedLimit = bounded(limit, 100, 1, 10_000, 'limit');
+        const result = await this.runQuery(`SELECT tenant, subsystem, path, source_revision, digest, value,
+              tombstone, deleted_at, delete_reason, change_seq
+       FROM aiwg_storage_records
+       WHERE tenant=$1 AND subsystem=$2 AND tombstone=false
+         AND value @> $3::jsonb AND ($4::text IS NULL OR path > $4)
+       ORDER BY path LIMIT $5`, [this.options.tenant, this.options.subsystem, JSON.stringify(filters), cursor ?? null, boundedLimit + 1]);
+        const hasMore = result.rows.length > boundedLimit;
+        const rows = result.rows.slice(0, boundedLimit);
+        return {
+            records: rows.map((recordFromRow)),
+            ...(hasMore ? { nextCursor: rows.at(-1)?.path } : {}),
+        };
+    }
+    async snapshot() {
+        const lease = await this.openSnapshotLease();
+        try {
+            const records = [];
+            let cursor;
+            do {
+                const page = await lease.readPage(cursor, 10_000);
+                records.push(...page.records);
+                cursor = page.nextCursor;
+            } while (cursor);
+            return { id: lease.id, highWaterMark: lease.highWaterMark, cursor: lease.cursor, records };
+        }
+        finally {
+            await lease.close();
+        }
+    }
+    /** Hold an exported PostgreSQL snapshot open while parallel consumers page it. */
+    async openSnapshotLease() {
+        const exporter = await this.requiredPool().connect();
+        let closed = false;
+        try {
+            await exporter.query('BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY');
+            const snapshot = await exporter.query('SELECT pg_export_snapshot() AS snapshot');
+            const highWater = await exporter.query(`SELECT COALESCE(MAX(change_seq),0)::text AS high_water_mark FROM aiwg_storage_records
+         WHERE tenant=$1 AND subsystem=$2`, [this.options.tenant, this.options.subsystem]);
+            const id = snapshot.rows[0].snapshot;
+            const highWaterMark = highWater.rows[0].high_water_mark;
+            return {
+                id,
+                highWaterMark,
+                cursor: highWaterMark,
+                readPage: (cursor, limit) => this.readSnapshotPage(id, cursor, limit),
+                close: async () => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    try {
+                        await exporter.query('COMMIT');
+                    }
+                    finally {
+                        exporter.release(false);
+                    }
+                },
+            };
+        }
+        catch (error) {
+            try {
+                await exporter.query('ROLLBACK');
+            }
+            catch { /* preserve original error */ }
+            exporter.release(true);
+            throw classifyPostgresError(error);
+        }
+    }
+    async readSnapshotPage(snapshotId, cursor, limit = 1000) {
+        if (!/^[0-9A-Fa-f-]+$/.test(snapshotId)) {
+            throw new PostgresBackendError('AIWG_POSTGRES_SNAPSHOT_INVALID', 'exported snapshot identifier is malformed');
+        }
+        const boundedLimit = bounded(limit, 1000, 1, 10_000, 'limit');
+        const client = await this.requiredPool().connect();
+        let failed = false;
+        try {
+            await client.query('BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY');
+            await client.query(`SET TRANSACTION SNAPSHOT '${snapshotId}'`);
+            const result = await client.query(`SELECT tenant, subsystem, path, source_revision, digest, value,
+                tombstone, deleted_at, delete_reason, change_seq
+         FROM aiwg_storage_records
+         WHERE tenant=$1 AND subsystem=$2 AND ($3::text IS NULL OR path > $3)
+         ORDER BY path LIMIT $4`, [this.options.tenant, this.options.subsystem, cursor ?? null, boundedLimit + 1]);
+            await client.query('COMMIT');
+            const hasMore = result.rows.length > boundedLimit;
+            const rows = result.rows.slice(0, boundedLimit);
+            return { records: rows.map((recordFromRow)), ...(hasMore ? { nextCursor: rows.at(-1)?.path } : {}), snapshot: snapshotId };
+        }
+        catch (error) {
+            failed = true;
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch { /* preserve original error */ }
+            throw classifyPostgresError(error);
+        }
+        finally {
+            client.release(failed);
+        }
+    }
+    async changes(cursor) {
+        const after = parseCursor(cursor);
+        const result = await this.runQuery(`SELECT tenant, subsystem, path, source_revision, digest, value,
+              tombstone, deleted_at, delete_reason, change_seq
+       FROM aiwg_storage_records
+       WHERE tenant=$1 AND subsystem=$2 AND change_seq > $3
+       ORDER BY change_seq, path LIMIT 1001`, [this.options.tenant, this.options.subsystem, after]);
+        const page = result.rows.slice(0, 1000);
+        const highWaterMark = String(page.at(-1)?.change_seq ?? after);
+        return {
+            records: page.map((recordFromRow)),
+            ...(result.rows.length > 1000 ? { nextCursor: highWaterMark } : {}),
+            highWaterMark,
+        };
+    }
+    async replaceEdges(sourcePath, edges) {
+        await this.withTransaction(async (client) => {
+            await client.query('DELETE FROM aiwg_storage_edges WHERE tenant=$1 AND subsystem=$2 AND source_path=$3', [this.options.tenant, this.options.subsystem, sourcePath]);
+            for (const edge of [...edges].sort((a, b) => `${a.type}\0${a.targetPath}`.localeCompare(`${b.type}\0${b.targetPath}`))) {
+                await client.query(`INSERT INTO aiwg_storage_edges(tenant,subsystem,source_path,target_path,edge_type)
+           VALUES ($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING`, [this.options.tenant, this.options.subsystem, sourcePath, edge.targetPath, edge.type]);
+            }
+        });
+    }
+    async traverse(path, direction, maxDepth, edgeType) {
+        const depth = bounded(maxDepth, 10, 1, 100, 'maxDepth');
+        const from = direction === 'out' ? 'source_path' : 'target_path';
+        const to = direction === 'out' ? 'target_path' : 'source_path';
+        const result = await this.runQuery(`
+      WITH RECURSIVE walk(path, depth, visited) AS (
+        SELECT $3::text, 0, ARRAY[$3::text]
+        UNION ALL
+        SELECT edge.${to}, walk.depth + 1, walk.visited || edge.${to}
+        FROM walk JOIN aiwg_storage_edges edge
+          ON edge.tenant=$1 AND edge.subsystem=$2 AND edge.${from}=walk.path
+        WHERE walk.depth < $4 AND ($5::text IS NULL OR edge.edge_type=$5)
+          AND NOT edge.${to}=ANY(walk.visited)
+      )
+      SELECT path, MIN(depth)::int AS depth FROM walk WHERE depth > 0
+      GROUP BY path ORDER BY depth, path`, [this.options.tenant, this.options.subsystem, path, depth, edgeType ?? null]);
+        return result.rows;
+    }
+    async setOperation(operation, left, right) {
+        const sqlOperation = operation === 'union' ? 'UNION' : operation === 'intersection' ? 'INTERSECT' : 'EXCEPT';
+        const result = await this.runQuery(`SELECT unnest($1::text[]) AS path ${sqlOperation} SELECT unnest($2::text[]) AS path ORDER BY path`, [left, right]);
+        return result.rows.map(row => row.path);
+    }
+    async health() {
+        const result = await this.runQuery(`
+      SELECT current_setting('server_version') AS server_version,
+             (SELECT schema_version FROM aiwg_storage_schema WHERE singleton=true) AS schema_version,
+             COALESCE((SELECT MAX(change_seq) FROM aiwg_storage_records WHERE tenant=$1 AND subsystem=$2),0)::text AS high_water_mark`, [this.options.tenant, this.options.subsystem]);
+        const row = result.rows[0];
+        return { healthy: true, ready: Number(row.schema_version) === 1, serverVersion: row.server_version, schemaVersion: String(row.schema_version), highWaterMark: row.high_water_mark };
+    }
+    metrics() {
+        const pool = this.requiredPool();
+        return { total: pool.totalCount ?? 0, idle: pool.idleCount ?? 0, waiting: pool.waitingCount ?? 0 };
+    }
+    async withMigrationLock(operation) {
+        return this.withTransaction(async (client) => {
+            const key = advisoryKey(this.options.tenant, this.options.subsystem);
+            await client.query('SELECT pg_advisory_xact_lock($1)', [key]);
+            return operation();
+        });
+    }
+    async close() {
+        if (this.ownsPool && this.pool)
+            await this.pool.end();
+        this.pool = undefined;
+    }
+    async withTransaction(operation, isolation = 'SERIALIZABLE') {
+        const client = await this.requiredPool().connect();
+        let failed = false;
+        try {
+            await client.query(`BEGIN ISOLATION LEVEL ${isolation}`);
+            await client.query(`SET LOCAL statement_timeout = '${this.statementTimeoutMs}ms'`);
+            await client.query(`SET LOCAL lock_timeout = '${this.lockTimeoutMs}ms'`);
+            await client.query(`SET LOCAL idle_in_transaction_session_timeout = '${this.idleTransactionTimeoutMs}ms'`);
+            const result = await operation(client);
+            await client.query('COMMIT');
+            return result;
+        }
+        catch (error) {
+            failed = true;
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch { /* preserve original error */ }
+            throw classifyPostgresError(error);
+        }
+        finally {
+            client.release(failed);
+        }
+    }
+    assertMutationIdentity(mutation) {
+        const identity = mutation.record.identity;
+        if (identity.tenant !== this.options.tenant || identity.subsystem !== this.options.subsystem) {
+            throw new PostgresBackendError('AIWG_POSTGRES_IDENTITY_MISMATCH', 'mutation identity is outside this backend tenant/subsystem');
+        }
+    }
+    requiredPool() {
+        if (!this.pool)
+            throw new PostgresBackendError('AIWG_POSTGRES_NOT_INITIALIZED', 'call init() before using the PostgreSQL backend');
+        return this.pool;
+    }
+    async runQuery(text, values) {
+        try {
+            return await this.requiredPool().query(text, values);
+        }
+        catch (error) {
+            throw classifyPostgresError(error);
+        }
+    }
+}
+async function createPool(options) {
+    const envName = options.connectionStringEnv ?? 'AIWG_POSTGRES_URL';
+    const connectionString = process.env[envName];
+    if (!connectionString) {
+        throw new PostgresBackendError('AIWG_POSTGRES_CREDENTIAL_UNAVAILABLE', `PostgreSQL connection locator ${envName} is not set`);
+    }
+    if (options.ssl === undefined) {
+        throw new PostgresBackendError('AIWG_POSTGRES_TLS_REQUIRED', 'PostgreSQL remote connections require explicit ssl=require or ssl=verify-full');
+    }
+    if (options.ssl === 'disable' && !isLoopbackPostgresUrl(connectionString)) {
+        throw new PostgresBackendError('AIWG_POSTGRES_TLS_REQUIRED', 'ssl=disable is limited to explicit loopback development endpoints');
+    }
+    const pg = await loadFeaturePackage('pg');
+    const defaultExport = pg.default;
+    const Pool = (pg.Pool ?? defaultExport?.Pool);
+    if (!Pool)
+        throw new PostgresBackendError('AIWG_POSTGRES_DRIVER_INVALID', 'optional pg package does not export Pool');
+    return new Pool({
+        connectionString,
+        max: bounded(options.maxConnections, DEFAULT_POOL_MAX, 1, 100, 'maxConnections'),
+        connectionTimeoutMillis: bounded(options.connectionTimeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'connectionTimeoutMs'),
+        statement_timeout: bounded(options.statementTimeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'statementTimeoutMs'),
+        application_name: options.applicationName ?? 'aiwg',
+        ssl: options.ssl === 'disable' ? false : { rejectUnauthorized: options.ssl === 'verify-full' },
+    });
+}
+function isLoopbackPostgresUrl(connectionString) {
+    try {
+        const host = new URL(connectionString).hostname;
+        return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    }
+    catch {
+        return false;
+    }
+}
+function recordFromRow(row) {
+    return {
+        identity: { tenant: row.tenant, subsystem: row.subsystem, path: row.path },
+        sourceRevision: row.source_revision,
+        digest: row.digest,
+        ...(row.tombstone
+            ? { tombstone: { deletedAt: new Date(row.deleted_at ?? 0).toISOString(), ...(row.delete_reason ? { reason: row.delete_reason } : {}) } }
+            : { value: row.value }),
+    };
+}
+export function postgresBatchId(mutations) {
+    const digest = createHash('sha256').update(mutations.map(item => item.idempotencyKey).join('\0')).digest('hex');
+    return `${digest.slice(0, 8)}-${digest.slice(8, 12)}-4${digest.slice(13, 16)}-8${digest.slice(17, 20)}-${digest.slice(20, 32)}`;
+}
+export function postgresPayloadDigest(value) {
+    return createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => `${JSON.stringify(key)}:${stableStringify(child)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function advisoryKey(tenant, subsystem) {
+    return BigInt.asIntN(64, BigInt(`0x${createHash('sha256').update(`${tenant}\0${subsystem}`).digest('hex').slice(0, 16)}`)).toString();
+}
+function parseCursor(cursor) {
+    if (cursor === undefined)
+        return '0';
+    if (!/^\d+$/.test(cursor))
+        throw new PostgresBackendError('AIWG_POSTGRES_CURSOR_INVALID', 'change cursor must be an unsigned integer');
+    return cursor;
+}
+function validateIdentity(value, label) {
+    if (!value || value.length > 200 || /[\u0000-\u001f]/.test(value)) {
+        throw new PostgresBackendError('AIWG_POSTGRES_IDENTITY_INVALID', `${label} must be a non-empty printable identifier`);
+    }
+}
+function bounded(value, fallback, min, max, label) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved < min || resolved > max) {
+        throw new PostgresBackendError('AIWG_POSTGRES_OPTION_INVALID', `${label} must be an integer from ${min} through ${max}`);
+    }
+    return resolved;
+}
+function classifyPostgresError(error) {
+    if (error instanceof PostgresBackendError)
+        return error;
+    const code = typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : '';
+    if (['40001', '40P01', '55P03', '57014', '57P01', '57P02', '57P03', '08000', '08003', '08006', '08001'].includes(code)) {
+        return new PostgresBackendError('AIWG_POSTGRES_RETRYABLE', `retryable PostgreSQL failure (${code})`, true);
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+//# sourceMappingURL=postgres.js.map

package/dist/src/storage/backends/postgrest-schema.js

@@ -0,0 +1,192 @@
+/** Versioned security-invoker RPC surface used by the PostgREST transport. */
+export const POSTGREST_SCHEMA_V1_SQL = String.raw `
+CREATE OR REPLACE FUNCTION aiwg_record_v1(r aiwg_storage_records)
+RETURNS jsonb LANGUAGE sql STABLE AS $$
+  SELECT jsonb_strip_nulls(jsonb_build_object(
+    'identity', jsonb_build_object('tenant', r.tenant, 'subsystem', r.subsystem, 'path', r.path),
+    'sourceRevision', r.source_revision, 'digest', r.digest,
+    'value', CASE WHEN r.tombstone THEN NULL ELSE r.value END,
+    'tombstone', CASE WHEN r.tombstone THEN jsonb_strip_nulls(jsonb_build_object(
+      'deletedAt', to_char(r.deleted_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'),
+      'reason', r.delete_reason)) ELSE NULL END));
+$$;
+
+CREATE OR REPLACE FUNCTION aiwg_commit_batch_v1(
+  p_tenant text, p_subsystem text, p_batch_id uuid,
+  p_payload_digest text, p_mutations jsonb
+) RETURNS jsonb LANGUAGE plpgsql SECURITY INVOKER AS $$
+DECLARE
+  m jsonb; prior aiwg_storage_batch_receipts%ROWTYPE;
+  changed aiwg_storage_records%ROWTYPE; receipts jsonb := '[]'::jsonb;
+  high_water bigint := 0; result jsonb;
+BEGIN
+  IF jsonb_typeof(p_mutations) <> 'array' OR jsonb_array_length(p_mutations)=0 THEN
+    RAISE EXCEPTION USING ERRCODE='22023', MESSAGE='AIWG_POSTGREST_EMPTY_BATCH';
+  END IF;
+  PERFORM pg_advisory_xact_lock(hashtextextended(p_tenant || chr(31) || p_subsystem || chr(31) || p_batch_id::text, 0));
+  SELECT * INTO prior FROM aiwg_storage_batch_receipts
+    WHERE tenant=p_tenant AND subsystem=p_subsystem AND batch_id=p_batch_id FOR UPDATE;
+  IF FOUND THEN
+    IF prior.payload_digest <> p_payload_digest THEN
+      RAISE EXCEPTION USING ERRCODE='23505', MESSAGE='AIWG_POSTGREST_IDEMPOTENCY_CONFLICT';
+    END IF;
+    RETURN prior.receipt;
+  END IF;
+  FOR m IN SELECT value FROM jsonb_array_elements(p_mutations) LOOP
+    IF m#>>'{record,identity,tenant}' <> p_tenant OR m#>>'{record,identity,subsystem}' <> p_subsystem THEN
+      RAISE EXCEPTION USING ERRCODE='42501', MESSAGE='AIWG_POSTGREST_IDENTITY_MISMATCH';
+    END IF;
+    INSERT INTO aiwg_storage_records
+      (tenant,subsystem,path,source_revision,digest,value,tombstone,deleted_at,delete_reason,idempotency_key)
+    VALUES (p_tenant,p_subsystem,m#>>'{record,identity,path}',m#>>'{record,sourceRevision}',
+      m#>>'{record,digest}',m#>'{record,value}',
+      (m->>'operation'='delete' OR m#>'{record,tombstone}' IS NOT NULL),
+      NULLIF(m#>>'{record,tombstone,deletedAt}','')::timestamptz,
+      m#>>'{record,tombstone,reason}',m->>'idempotencyKey')
+    ON CONFLICT (tenant,subsystem,path) DO UPDATE SET
+      source_revision=EXCLUDED.source_revision,digest=EXCLUDED.digest,value=EXCLUDED.value,
+      tombstone=EXCLUDED.tombstone,deleted_at=EXCLUDED.deleted_at,
+      delete_reason=EXCLUDED.delete_reason,idempotency_key=EXCLUDED.idempotency_key,
+      change_seq=nextval(pg_get_serial_sequence('aiwg_storage_records','change_seq')),
+      updated_at=clock_timestamp()
+    WHERE m->>'expectedRevision' IS NULL
+       OR aiwg_storage_records.source_revision=m->>'expectedRevision'
+    RETURNING * INTO changed;
+    IF NOT FOUND THEN
+      RAISE EXCEPTION USING ERRCODE='P0001', MESSAGE='AIWG_POSTGREST_REVISION_CONFLICT';
+    END IF;
+    high_water := changed.change_seq;
+    receipts := receipts || jsonb_build_array(jsonb_build_object(
+      'identity',jsonb_build_object('tenant',changed.tenant,'subsystem',changed.subsystem,'path',changed.path),
+      'sourceRevision',changed.source_revision,'digest',changed.digest));
+  END LOOP;
+  result := jsonb_build_object('batchId',p_batch_id::text,'committed',true,
+    'highWaterMark',high_water::text,'recordReceipts',receipts);
+  INSERT INTO aiwg_storage_batch_receipts
+    (tenant,subsystem,batch_id,payload_digest,high_water_mark,receipt)
+    VALUES (p_tenant,p_subsystem,p_batch_id,p_payload_digest,high_water,result);
+  RETURN result;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION aiwg_get_record_v1(p_tenant text,p_subsystem text,p_path text)
+RETURNS jsonb LANGUAGE sql STABLE SECURITY INVOKER AS $$
+  SELECT aiwg_record_v1(r) FROM aiwg_storage_records r
+  WHERE r.tenant=p_tenant AND r.subsystem=p_subsystem AND r.path=p_path;
+$$;
+
+CREATE OR REPLACE FUNCTION aiwg_query_records_v1(
+  p_tenant text,p_subsystem text,p_filters jsonb DEFAULT '{}'::jsonb,
+  p_after_path text DEFAULT NULL,p_limit integer DEFAULT 1000,
+  p_include_tombstones boolean DEFAULT false
+) RETURNS jsonb LANGUAGE plpgsql STABLE SECURITY INVOKER AS $$
+DECLARE result jsonb;
+BEGIN
+  IF p_limit<1 OR p_limit>10000 THEN RAISE EXCEPTION USING ERRCODE='22023',MESSAGE='AIWG_POSTGREST_LIMIT_INVALID'; END IF;
+  WITH page AS (SELECT r.* FROM aiwg_storage_records r
+    WHERE r.tenant=p_tenant AND r.subsystem=p_subsystem
+      AND (p_include_tombstones OR NOT r.tombstone)
+      AND (r.value @> p_filters OR (r.tombstone AND p_filters='{}'::jsonb))
+      AND (p_after_path IS NULL OR r.path>p_after_path)
+    ORDER BY r.path LIMIT p_limit+1),
+  kept AS (SELECT * FROM page ORDER BY path LIMIT p_limit)
+  SELECT jsonb_build_object('records',COALESCE(jsonb_agg(aiwg_record_v1(k) ORDER BY k.path),'[]'::jsonb),
+    'nextCursor',CASE WHEN (SELECT count(*) FROM page)>p_limit THEN max(k.path) END)
+    INTO result FROM kept k;
+  RETURN jsonb_strip_nulls(result);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION aiwg_snapshot_v1(p_tenant text,p_subsystem text,p_limit integer DEFAULT 1000)
+RETURNS jsonb LANGUAGE plpgsql STABLE SECURITY INVOKER AS $$
+DECLARE record_count bigint; high_water bigint;
+BEGIN
+  IF p_limit<1 OR p_limit>10000 THEN RAISE EXCEPTION USING ERRCODE='22023',MESSAGE='AIWG_POSTGREST_LIMIT_INVALID'; END IF;
+  SELECT count(*),COALESCE(max(change_seq),0) INTO record_count,high_water
+    FROM aiwg_storage_records WHERE tenant=p_tenant AND subsystem=p_subsystem;
+  IF record_count>p_limit THEN RAISE EXCEPTION USING ERRCODE='54000',MESSAGE='AIWG_POSTGREST_SNAPSHOT_CEILING'; END IF;
+  RETURN jsonb_build_object('snapshot_id',txid_current()::text,'high_water_mark',high_water::text,
+    'records',COALESCE((SELECT jsonb_agg(aiwg_record_v1(r) ORDER BY r.path)
+      FROM aiwg_storage_records r WHERE r.tenant=p_tenant AND r.subsystem=p_subsystem),'[]'::jsonb));
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION aiwg_changes_v1(
+  p_tenant text,p_subsystem text,p_after_cursor bigint DEFAULT 0,p_limit integer DEFAULT 1000
+) RETURNS jsonb LANGUAGE plpgsql STABLE SECURITY INVOKER AS $$
+DECLARE result jsonb;
+BEGIN
+  IF p_limit<1 OR p_limit>10000 THEN RAISE EXCEPTION USING ERRCODE='22023',MESSAGE='AIWG_POSTGREST_LIMIT_INVALID'; END IF;
+  WITH page AS (SELECT r.* FROM aiwg_storage_records r
+    WHERE r.tenant=p_tenant AND r.subsystem=p_subsystem AND r.change_seq>p_after_cursor
+    ORDER BY r.change_seq,r.path LIMIT p_limit+1),
+  kept AS (SELECT * FROM page ORDER BY change_seq,path LIMIT p_limit)
+  SELECT jsonb_build_object('records',COALESCE(jsonb_agg(aiwg_record_v1(k) ORDER BY k.change_seq,k.path),'[]'::jsonb),
+    'high_water_mark',COALESCE(max(k.change_seq),p_after_cursor)::text,
+    'next_cursor',CASE WHEN (SELECT count(*) FROM page)>p_limit THEN max(k.change_seq)::text END)
+    INTO result FROM kept k;
+  RETURN jsonb_strip_nulls(result);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION aiwg_health_v1(p_tenant text,p_subsystem text)
+RETURNS jsonb LANGUAGE sql STABLE SECURITY INVOKER AS $$
+  SELECT jsonb_build_object('healthy',true,'ready',s.schema_version=1,
+    'schemaVersion',s.schema_version::text,
+    'highWaterMark',COALESCE((SELECT max(change_seq) FROM aiwg_storage_records
+      WHERE tenant=p_tenant AND subsystem=p_subsystem),0)::text,
+    'accessMode','postgrest','engine','postgres')
+  FROM aiwg_storage_schema s WHERE singleton=true;
+$$;
+
+CREATE OR REPLACE FUNCTION aiwg_reload_schema_v1()
+RETURNS void LANGUAGE plpgsql VOLATILE SECURITY INVOKER AS $$
+BEGIN PERFORM pg_notify('pgrst','reload schema'); END;
+$$;
+`;
+/** Install with a migration-role connection; runtime requesters need only EXECUTE/table DML grants. */
+export async function installPostgrestSchemaV1(client) {
+    await client.query('BEGIN');
+    try {
+        await client.query(POSTGREST_SCHEMA_V1_SQL);
+        await client.query('COMMIT');
+        await client.query("NOTIFY pgrst, 'reload schema'");
+    }
+    catch (error) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { /* preserve installation error */ }
+        throw error;
+    }
+}
+/** Generate the requester-role grants and JWT-claim RLS policies for v1. */
+export function postgrestLeastPrivilegeSql(requesterRole) {
+    const role = quoteIdentifier(requesterRole);
+    const predicate = `(tenant=current_setting('request.jwt.claims',true)::jsonb->>'tenant' AND subsystem=current_setting('request.jwt.claims',true)::jsonb->>'subsystem')`;
+    return `REVOKE ALL ON aiwg_storage_records, aiwg_storage_batch_receipts, aiwg_storage_edges FROM PUBLIC;
+REVOKE ALL ON ALL FUNCTIONS IN SCHEMA public FROM PUBLIC;
+GRANT USAGE ON SCHEMA public TO ${role};
+GRANT SELECT, INSERT, UPDATE, DELETE ON aiwg_storage_records, aiwg_storage_batch_receipts, aiwg_storage_edges TO ${role};
+GRANT SELECT ON aiwg_storage_schema TO ${role};
+GRANT USAGE, SELECT ON SEQUENCE aiwg_storage_records_change_seq_seq TO ${role};
+GRANT EXECUTE ON FUNCTION aiwg_record_v1(aiwg_storage_records), aiwg_commit_batch_v1(text,text,uuid,text,jsonb), aiwg_get_record_v1(text,text,text), aiwg_query_records_v1(text,text,jsonb,text,integer,boolean), aiwg_snapshot_v1(text,text,integer), aiwg_changes_v1(text,text,bigint,integer), aiwg_health_v1(text,text), aiwg_reload_schema_v1() TO ${role};
+ALTER TABLE aiwg_storage_records ENABLE ROW LEVEL SECURITY;
+ALTER TABLE aiwg_storage_records FORCE ROW LEVEL SECURITY;
+ALTER TABLE aiwg_storage_batch_receipts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE aiwg_storage_batch_receipts FORCE ROW LEVEL SECURITY;
+ALTER TABLE aiwg_storage_edges ENABLE ROW LEVEL SECURITY;
+ALTER TABLE aiwg_storage_edges FORCE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS aiwg_records_tenant_v1 ON aiwg_storage_records;
+CREATE POLICY aiwg_records_tenant_v1 ON aiwg_storage_records FOR ALL TO ${role} USING ${predicate} WITH CHECK ${predicate};
+DROP POLICY IF EXISTS aiwg_receipts_tenant_v1 ON aiwg_storage_batch_receipts;
+CREATE POLICY aiwg_receipts_tenant_v1 ON aiwg_storage_batch_receipts FOR ALL TO ${role} USING ${predicate} WITH CHECK ${predicate};
+DROP POLICY IF EXISTS aiwg_edges_tenant_v1 ON aiwg_storage_edges;
+CREATE POLICY aiwg_edges_tenant_v1 ON aiwg_storage_edges FOR ALL TO ${role} USING ${predicate} WITH CHECK ${predicate};`;
+}
+function quoteIdentifier(value) {
+    if (!value || value.length > 63 || /[\u0000-\u001f]/.test(value))
+        throw new Error('requester role must be a printable PostgreSQL identifier up to 63 characters');
+    return `"${value.replaceAll('"', '""')}"`;
+}
+//# sourceMappingURL=postgrest-schema.js.map