@aiwg/cli 2026.8.25 → 2026.8.27

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

@@ -0,0 +1,346 @@
+import { STORAGE_BACKEND_CONTRACT } from '../backend-contract.js';
+import { postgresBatchId, postgresPayloadDigest } from './postgres.js';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_PAYLOAD_BYTES = 1_048_576;
+const DEFAULT_PAGE_SIZE = 1000;
+export class PostgrestBackendError extends Error {
+    code;
+    retryable;
+    retryAfterMs;
+    constructor(code, message, retryable = false, retryAfterMs) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'PostgrestBackendError';
+    }
+}
+/** PostgreSQL accessMode=postgrest; not a separate storage engine. */
+export class PostgrestStorageBackend {
+    options;
+    descriptor = {
+        contract: STORAGE_BACKEND_CONTRACT,
+        backend: 'postgres-postgrest',
+        implementationVersion: '1.0.0',
+        schemaVersion: '1',
+        maturity: 'advanced',
+        capabilities: [
+            'read', 'atomic-batch', 'consistent-snapshot', 'change-cursor',
+            'tombstones', 'idempotency-keys', 'filtered-query', 'cursor-pagination',
+            'health', 'readiness', 'tenant-isolation', 'subsystem-isolation', 'tls',
+        ],
+        durability: 'replicated',
+        availability: 'remote-service',
+        isolation: 'serializable',
+        dataClass: 'canonical',
+    };
+    identity;
+    baseUrl;
+    fetchImpl;
+    timeoutMs;
+    maxPayloadBytes;
+    maxResponseBytes;
+    maxBatchSize;
+    maxPageSize;
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = normalizeBaseUrl(options.baseUrl);
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl)
+            throw new PostgrestBackendError('AIWG_POSTGREST_FETCH_UNAVAILABLE', 'fetch is unavailable');
+        this.timeoutMs = bounded(options.timeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'timeoutMs');
+        this.maxPayloadBytes = bounded(options.maxPayloadBytes, DEFAULT_MAX_PAYLOAD_BYTES, 1024, 16_777_216, 'maxPayloadBytes');
+        this.maxResponseBytes = bounded(options.maxResponseBytes, DEFAULT_MAX_PAYLOAD_BYTES, 1024, 16_777_216, 'maxResponseBytes');
+        this.maxBatchSize = bounded(options.maxBatchSize, DEFAULT_PAGE_SIZE, 1, 10_000, 'maxBatchSize');
+        this.maxPageSize = bounded(options.maxPageSize, DEFAULT_PAGE_SIZE, 1, 10_000, 'maxPageSize');
+        this.identity = {
+            backend: 'postgres-postgrest', instance: options.instance ?? this.baseUrl,
+            tenant: options.tenant, subsystem: options.subsystem, schemaVersion: '1',
+        };
+    }
+    async init() {
+        const health = await this.health();
+        if (!health.ready || health.schemaVersion !== '1') {
+            throw new PostgrestBackendError('AIWG_POSTGREST_SCHEMA_UNAVAILABLE', 'PostgREST schema/RPC contract v1 is unavailable');
+        }
+    }
+    async commitBatch(mutations) {
+        if (mutations.length === 0)
+            throw new PostgrestBackendError('AIWG_POSTGREST_EMPTY_BATCH', 'batch must contain at least one mutation');
+        if (mutations.length > this.maxBatchSize)
+            throw new PostgrestBackendError('AIWG_POSTGREST_BATCH_TOO_LARGE', `batch exceeds ${this.maxBatchSize} mutation ceiling`);
+        for (const mutation of mutations)
+            this.assertMutationIdentity(mutation);
+        return this.rpc('aiwg_commit_batch_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_batch_id: postgresBatchId(mutations),
+            p_payload_digest: postgresPayloadDigest(mutations),
+            p_mutations: mutations,
+        }, 'return=representation');
+    }
+    async get(path) {
+        return this.rpc('aiwg_get_record_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_path: path,
+        });
+    }
+    async readAll() {
+        const records = [];
+        let cursor;
+        do {
+            const page = await this.query({}, this.maxPageSize, cursor, true);
+            records.push(...page.records);
+            cursor = page.nextCursor;
+        } while (cursor);
+        return records;
+    }
+    async query(filters, limit = this.maxPageSize, cursor, includeTombstones = false) {
+        const boundedLimit = bounded(limit, this.maxPageSize, 1, this.maxPageSize, 'limit');
+        return this.rpc('aiwg_query_records_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_filters: filters,
+            p_after_path: cursor ?? null,
+            p_limit: boundedLimit,
+            p_include_tombstones: includeTombstones,
+        });
+    }
+    async snapshot() {
+        const response = await this.rpc('aiwg_snapshot_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_limit: this.maxPageSize,
+        });
+        return {
+            id: response.snapshot_id,
+            highWaterMark: response.high_water_mark,
+            cursor: response.high_water_mark,
+            records: response.records,
+        };
+    }
+    async changes(cursor) {
+        if (cursor !== undefined && !/^\d+$/.test(cursor)) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_CURSOR_INVALID', 'change cursor must be an unsigned integer');
+        }
+        const response = await this.rpc('aiwg_changes_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_after_cursor: cursor ?? '0',
+            p_limit: this.maxPageSize,
+        });
+        return {
+            records: response.records,
+            highWaterMark: response.high_water_mark,
+            ...(response.next_cursor ? { nextCursor: response.next_cursor } : {}),
+        };
+    }
+    async reloadSchemaCache() {
+        await this.rpc('aiwg_reload_schema_v1', {});
+    }
+    async health() {
+        return this.rpc('aiwg_health_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+        });
+    }
+    /** Receipt-less native JSON bulk upsert for controlled bootstrap only. */
+    async bulkBootstrapJson(rows) {
+        this.assertBootstrapCount(rows.length);
+        for (const row of rows)
+            this.assertBootstrapIdentity(row.tenant, row.subsystem);
+        return this.request('/aiwg_storage_records?on_conflict=tenant%2Csubsystem%2Cpath', {
+            method: 'POST', body: rows, prefer: 'resolution=merge-duplicates,return=representation',
+        });
+    }
+    /** Receipt-less native CSV bulk upsert for controlled bootstrap only. */
+    async bulkBootstrapCsv(csv) {
+        const parsed = parseCsv(csv);
+        const required = ['tenant', 'subsystem', 'path', 'source_revision', 'digest', 'value', 'tombstone', 'idempotency_key'];
+        for (const column of required) {
+            if (!parsed.header.includes(column))
+                throw new PostgrestBackendError('AIWG_POSTGREST_CSV_INVALID', `CSV header is missing ${column}`);
+        }
+        this.assertBootstrapCount(parsed.rows.length);
+        const tenantIndex = parsed.header.indexOf('tenant');
+        const subsystemIndex = parsed.header.indexOf('subsystem');
+        for (const row of parsed.rows)
+            this.assertBootstrapIdentity(row[tenantIndex] ?? '', row[subsystemIndex] ?? '');
+        return this.request('/aiwg_storage_records?on_conflict=tenant%2Csubsystem%2Cpath', {
+            method: 'POST', rawBody: csv, contentType: 'text/csv',
+            prefer: 'resolution=merge-duplicates,return=representation',
+        });
+    }
+    async rpc(name, body, prefer) {
+        return this.request(`/rpc/${name}`, { method: 'POST', body, ...(prefer ? { prefer } : {}) });
+    }
+    async request(pathname, options = {}) {
+        const body = options.rawBody ?? (options.body === undefined ? undefined : JSON.stringify(options.body));
+        if (body && Buffer.byteLength(body) > this.maxPayloadBytes) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_PAYLOAD_TOO_LARGE', `request exceeds ${this.maxPayloadBytes} byte ceiling`);
+        }
+        const headers = { Accept: 'application/json' };
+        if (body)
+            headers['Content-Type'] = options.contentType ?? 'application/json';
+        if (options.prefer)
+            headers.Prefer = options.prefer;
+        const authorization = this.authorization();
+        if (authorization)
+            headers.Authorization = authorization;
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${pathname}`, {
+                method: options.method ?? 'GET', headers, body,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (error) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_TRANSPORT_FAILED', error instanceof Error ? error.message : String(error), true);
+        }
+        if (response.status === 204)
+            return undefined;
+        const declaredLength = Number(response.headers.get('content-length') ?? '0');
+        if (declaredLength > this.maxResponseBytes) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_RESPONSE_TOO_LARGE', `response exceeds ${this.maxResponseBytes} byte ceiling`);
+        }
+        const responseBody = await response.text();
+        if (Buffer.byteLength(responseBody) > this.maxResponseBytes) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_RESPONSE_TOO_LARGE', `response exceeds ${this.maxResponseBytes} byte ceiling`);
+        }
+        if (!response.ok) {
+            const databaseError = parseDatabaseError(responseBody);
+            const retryable = response.status === 408 || response.status === 425 || response.status === 429 ||
+                response.status >= 500 || isRetryableDatabaseCode(databaseError.databaseCode);
+            const exposedCode = databaseError.message?.startsWith('AIWG_')
+                ? databaseError.message
+                : retryable ? 'AIWG_POSTGREST_RETRYABLE' : 'AIWG_POSTGREST_REQUEST_FAILED';
+            throw new PostgrestBackendError(exposedCode, `PostgREST request failed with HTTP ${response.status}${databaseError.databaseCode ? ` (database ${databaseError.databaseCode})` : ''}`, retryable, parseRetryAfter(response.headers.get('retry-after')));
+        }
+        try {
+            return JSON.parse(responseBody);
+        }
+        catch {
+            throw new PostgrestBackendError('AIWG_POSTGREST_RESPONSE_INVALID', 'PostgREST returned invalid JSON');
+        }
+    }
+    authorization() {
+        if (!this.options.authorizationEnv)
+            return undefined;
+        const value = process.env[this.options.authorizationEnv];
+        if (!value)
+            throw new PostgrestBackendError('AIWG_POSTGREST_CREDENTIAL_UNAVAILABLE', `authorization locator ${this.options.authorizationEnv} is not set`);
+        return value;
+    }
+    assertMutationIdentity(mutation) {
+        if (mutation.record.identity.tenant !== this.options.tenant || mutation.record.identity.subsystem !== this.options.subsystem) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_IDENTITY_MISMATCH', 'mutation identity is outside this backend tenant/subsystem');
+        }
+    }
+    assertBootstrapCount(count) {
+        if (count < 1)
+            throw new PostgrestBackendError('AIWG_POSTGREST_EMPTY_BATCH', 'bootstrap batch must contain at least one row');
+        if (count > this.maxBatchSize)
+            throw new PostgrestBackendError('AIWG_POSTGREST_BATCH_TOO_LARGE', `batch exceeds ${this.maxBatchSize} row ceiling`);
+    }
+    assertBootstrapIdentity(tenant, subsystem) {
+        if (tenant !== this.options.tenant || subsystem !== this.options.subsystem) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_IDENTITY_MISMATCH', 'bootstrap row is outside this backend tenant/subsystem');
+        }
+    }
+}
+function parseCsv(input) {
+    const output = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    for (let index = 0; index < input.length; index += 1) {
+        const character = input[index];
+        if (character === '"') {
+            if (quoted && input[index + 1] === '"') {
+                field += '"';
+                index += 1;
+            }
+            else
+                quoted = !quoted;
+        }
+        else if (character === ',' && !quoted) {
+            row.push(field);
+            field = '';
+        }
+        else if ((character === '\n' || character === '\r') && !quoted) {
+            if (character === '\r' && input[index + 1] === '\n')
+                index += 1;
+            row.push(field);
+            field = '';
+            if (row.some(value => value.length > 0))
+                output.push(row);
+            row = [];
+        }
+        else
+            field += character;
+    }
+    if (quoted)
+        throw new PostgrestBackendError('AIWG_POSTGREST_CSV_INVALID', 'CSV contains an unterminated quoted field');
+    row.push(field);
+    if (row.some(value => value.length > 0))
+        output.push(row);
+    const header = output.shift();
+    if (!header)
+        throw new PostgrestBackendError('AIWG_POSTGREST_CSV_INVALID', 'CSV must contain a header');
+    for (const candidate of output) {
+        if (candidate.length !== header.length)
+            throw new PostgrestBackendError('AIWG_POSTGREST_CSV_INVALID', 'CSV row width does not match header');
+    }
+    return { header, rows: output };
+}
+function parseDatabaseError(body) {
+    try {
+        const parsed = JSON.parse(body);
+        return {
+            ...(typeof parsed.code === 'string' ? { databaseCode: parsed.code } : {}),
+            ...(typeof parsed.message === 'string' ? { message: parsed.message } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function isRetryableDatabaseCode(code) {
+    return Boolean(code && (code === '40001' || code === '40P01' || code === '55P03' || code === '57014' || code.startsWith('08')));
+}
+function normalizeBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new PostgrestBackendError('AIWG_POSTGREST_URL_INVALID', 'baseUrl must be an absolute URL');
+    }
+    const loopback = ['localhost', '127.0.0.1', '::1'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        throw new PostgrestBackendError('AIWG_POSTGREST_TLS_REQUIRED', 'PostgREST requires HTTPS except on explicit loopback development endpoints');
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new PostgrestBackendError('AIWG_POSTGREST_URL_SECRET_FORBIDDEN', 'baseUrl cannot contain credentials, query parameters, or fragments');
+    }
+    return url.toString().replace(/\/$/, '');
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value))
+        return Math.min(Number(value) * 1000, 60_000);
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        return undefined;
+    return Math.max(0, Math.min(timestamp - Date.now(), 60_000));
+}
+function bounded(value, fallback, min, max, label) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved < min || resolved > max) {
+        throw new PostgrestBackendError('AIWG_POSTGREST_OPTION_INVALID', `${label} must be an integer from ${min} through ${max}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=postgrest.js.map

package/dist/src/storage/index.js

@@ -22,7 +22,12 @@ export { ObsidianAdapter } from './backends/obsidian.js';
 export { LogseqAdapter } from './backends/logseq.js';
 export { FortemiAdapter } from './backends/fortemi.js';
 export { STORAGE_BACKEND_CONTRACT, STORAGE_BACKEND_MATRIX, StorageCapabilityError, negotiateStorageCapabilities, } from './backend-contract.js';
-export { STORAGE_MIGRATION_PROTOCOL, MigrationProtocolError, StorageMigrationCoordinator, approvalDigest, digestRecords, validateManifest, } from './migration-protocol.js';
+export { STORAGE_MIGRATION_PROTOCOL, MigrationProtocolError, StorageMigrationCoordinator, approvalDigest, digestRecordChunks, digestRecords, validateManifest, } from './migration-protocol.js';
+export { PostgresStorageBackend, PostgresBackendError, } from './backends/postgres.js';
+export { POSTGRES_SCHEMA_VERSION, POSTGRES_SCHEMA_V1_SQL, inspectPostgresSchema, upgradePostgresSchemaV1, rollbackPostgresSchemaV1, postgresLeastPrivilegeSql, } from './backends/postgres-schema.js';
+export { PostgrestStorageBackend, PostgrestBackendError, } from './backends/postgrest.js';
+export { POSTGREST_SCHEMA_V1_SQL, installPostgrestSchemaV1, postgrestLeastPrivilegeSql } from './backends/postgrest-schema.js';
+export { STORAGE_QUALIFICATION_REPORT, StorageQualificationError, qualifyStorageBackend, verifyExactRecords, assertCurrentStorageEvidence, } from './qualification.js';
 let state = null;
 /**
  * Initialize or reset the registry for a given project root. Most