@aiwg/cli 2026.8.25 → 2026.8.27

package/bin/aiwg.mjs

@@ -203,13 +203,6 @@ function maybeHandleFastHelp(args) {
   return true;
 }
 
-if (maybeHandleFastVersion(process.argv.slice(2))) {
-  process.exit(0);
-}
-if (maybeHandleFastHelp(process.argv.slice(2))) {
-  process.exit(0);
-}
-
 // Preflight: verify dist/ is built before any of the dynamic imports below
 // try to resolve files that don't exist. Without this, a missing/incomplete
 // dist/ surfaces as a raw `Cannot find module '.../dist/src/.../*.mjs'` from
@@ -240,6 +233,31 @@ function maybeWarnUnbuiltDist() {
 }
 maybeWarnUnbuiltDist();
 
+// Display a cached notice and schedule its refresh before every eligible CLI
+// path, including fast help/version, channel recovery, and later preflight
+// failures. This local-only bootstrap never waits on the registry and failures
+// are deliberately ignored so update advice cannot change command behavior.
+async function runUpdateNotifierBootstrap() {
+  try {
+    const notifierPath = path.join(packageRoot, 'dist', 'src', 'update', 'notifier.mjs');
+    const notifier = await import(pathToFileURL(notifierPath).href);
+    const activePackageRoot = notifier.resolveActivePackageRoot(packageRoot);
+    notifier.maybePrintNotice(activePackageRoot);
+    notifier.scheduleBackgroundCheck(activePackageRoot);
+  } catch {
+    // Best effort: installation/router diagnostics retain authority.
+  }
+}
+
+await runUpdateNotifierBootstrap();
+
+if (maybeHandleFastVersion(process.argv.slice(2))) {
+  process.exit(0);
+}
+if (maybeHandleFastHelp(process.argv.slice(2))) {
+  process.exit(0);
+}
+
 // Mint or inherit an invocation ID before anything else loads. Child processes
 // spawned by handlers (detached update-notifier, aiwg exec, etc.) inherit the
 // parent's ID via `AIWG_INVOCATION_ID` so their JSONL log records correlate
@@ -398,15 +416,6 @@ async function main() {
   // tag every record with it.
   await applyVerbosityFromArgs(args, routerPath);
 
-  // Update notifier: print any pending notice from the previous run's
-  // background check, then schedule the next background check. Both are
-  // non-blocking — the current command never waits on the network.
-  // Honors NO_UPDATE_NOTIFIER, CI=*, and non-TTY stderr.
-  const notifierPath = path.join(activePackageRoot, 'dist', 'src', 'update', 'notifier.mjs');
-  const { scheduleBackgroundCheck, maybePrintNotice } = await import(pathToFileURL(notifierPath).href);
-  maybePrintNotice(activePackageRoot);
-  scheduleBackgroundCheck(activePackageRoot);
-
   // Top-level cancellation controller. SIGINT / SIGTERM flip it, long-running
   // handlers plumb ctx.signal through fetches and loops so Ctrl-C cancels
   // in-flight work cleanly instead of leaving orphaned sockets and children.

package/dist/src/api/index.d.ts

@@ -9,6 +9,7 @@ export { run } from '../cli/router.js';
 export * from '../resources/index.js';
 export * from '../sessions/index.js';
 export * from '../memory/index.js';
+export * from '../storage/index.js';
 export * from '../security/threat-assessment-config.js';
 export * from '../security/artifact-verifier.js';
 export * from '../security/artifact-attestation.js';

package/dist/src/api/index.js

@@ -9,6 +9,7 @@ export { run } from '../cli/router.js';
 export * from '../resources/index.js';
 export * from '../sessions/index.js';
 export * from '../memory/index.js';
+export * from '../storage/index.js';
 export * from '../security/threat-assessment-config.js';
 export * from '../security/artifact-verifier.js';
 export * from '../security/artifact-attestation.js';

package/dist/src/artifacts/backends/graphology-backend.js

@@ -11,6 +11,7 @@
  * @source @src/artifacts/graph-backend.ts
  * @tests @test/unit/artifacts/graphology-backend.test.ts
  */
+import { compareGraphIds, pageGraphIds } from '../graph-backend.js';
 import { normalizeEdges } from '../types.js';
 import { loadFeaturePackage } from '../../features/runtime.js';
 /**
@@ -73,7 +74,15 @@ export class GraphologyBackend {
         return this.graph.getNodeAttributes(id);
     }
     nodes() {
-        return this.graph.nodes();
+        return this.graph.nodes().sort(compareGraphIds);
+    }
+    queryNodes(filters) {
+        return this.graph.nodes()
+            .filter((id) => Object.entries(filters).every(([key, value]) => this.graph.getNodeAttribute(id, key) === value))
+            .sort(compareGraphIds);
+    }
+    pageNodes(limit, after) {
+        return pageGraphIds(this.graph.nodes(), limit, after);
     }
     // --- Traversal ---
     neighbors(nodeId, direction, edgeType) {
@@ -98,7 +107,7 @@ export class GraphologyBackend {
             // Add the "other" node
             results.add(src === nodeId ? tgt : src);
         }
-        return [...results];
+        return [...results].sort(compareGraphIds);
     }
     // --- Set operations ---
     intersection(setA, setB) {

package/dist/src/artifacts/backends/json-backend.js

@@ -9,6 +9,7 @@
  * @source @src/artifacts/graph-backend.ts
  * @tests @test/unit/artifacts/graph-backend.test.ts
  */
+import { compareGraphIds, pageGraphIds } from '../graph-backend.js';
 import { normalizeEdges } from '../types.js';
 /**
  * JSON-backed graph using plain objects and JS Set operations.
@@ -52,7 +53,16 @@ export class JsonGraphBackend {
         return this.graph.get(id)?.attrs;
     }
     nodes() {
-        return [...this.graph.keys()];
+        return [...this.graph.keys()].sort(compareGraphIds);
+    }
+    queryNodes(filters) {
+        return [...this.graph]
+            .filter(([, node]) => Object.entries(filters).every(([key, value]) => node.attrs[key] === value))
+            .map(([id]) => id)
+            .sort(compareGraphIds);
+    }
+    pageNodes(limit, after) {
+        return pageGraphIds([...this.graph.keys()], limit, after);
     }
     // --- Traversal ---
     neighbors(nodeId, direction, edgeType) {
@@ -74,7 +84,7 @@ export class JsonGraphBackend {
                 }
             }
         }
-        return [...results];
+        return [...results].sort(compareGraphIds);
     }
     // --- Set operations ---
     intersection(setA, setB) {

package/dist/src/artifacts/backends/sqlite-backend.js

@@ -13,6 +13,7 @@
  * @source @src/artifacts/graph-backend.ts
  * @tests @test/unit/artifacts/sqlite-backend.test.ts
  */
+import { compareGraphIds, pageGraphIds } from '../graph-backend.js';
 import { normalizeEdges } from '../types.js';
 import { requireFeaturePackage } from '../../features/runtime.js';
 const SCHEMA_VERSION = 1;
@@ -131,23 +132,35 @@ export class SqliteGraphBackend {
         return JSON.parse(row.attrs);
     }
     nodes() {
-        return this.db.prepare('SELECT id FROM nodes').all().map((r) => r.id);
+        return this.db.prepare('SELECT id FROM nodes ORDER BY id COLLATE BINARY').all()
+            .map((r) => r.id);
     }
     queryNodes(filters) {
         const clauses = [];
         const values = [];
         if (filters.type !== undefined) {
-            clauses.push('type = ?');
-            values.push(filters.type);
+            if (filters.type === null)
+                clauses.push('type IS NULL');
+            else {
+                clauses.push('type = ?');
+                values.push(filters.type);
+            }
         }
         if (filters.phase !== undefined) {
-            clauses.push('phase = ?');
-            values.push(filters.phase);
+            if (filters.phase === null)
+                clauses.push('phase IS NULL');
+            else {
+                clauses.push('phase = ?');
+                values.push(filters.phase);
+            }
         }
         const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
-        return this.db.prepare(`SELECT id FROM nodes ${where} ORDER BY id`).all(...values)
+        return this.db.prepare(`SELECT id FROM nodes ${where} ORDER BY id COLLATE BINARY`).all(...values)
             .map((row) => row.id);
     }
+    pageNodes(limit, after) {
+        return pageGraphIds(this.nodes(), limit, after);
+    }
     // --- Traversal ---
     neighbors(nodeId, direction, edgeType) {
         const results = new Set();
@@ -171,7 +184,7 @@ export class SqliteGraphBackend {
             for (const row of rows)
                 results.add(row.target);
         }
-        return [...results];
+        return [...results].sort(compareGraphIds);
     }
     // --- Set operations (native SQL) ---
     intersection(setA, setB) {

package/dist/src/artifacts/graph-backend.js

@@ -10,6 +10,22 @@
  * @source @src/artifacts/types.ts
  * @tests @test/unit/artifacts/graph-backend.test.ts
  */
+/** SQLite BINARY collation and local backends share this UTF-8 byte order. */
+export function compareGraphIds(left, right) {
+    return Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8'));
+}
+export function pageGraphIds(ids, limit, after) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 10_000) {
+        throw new Error('graph page limit must be an integer from 1 through 10000');
+    }
+    const ordered = [...ids].sort(compareGraphIds);
+    const eligible = after === undefined ? ordered : ordered.filter(id => compareGraphIds(id, after) > 0);
+    const nodes = eligible.slice(0, limit);
+    return {
+        nodes,
+        ...(eligible.length > limit && nodes.length ? { nextCursor: nodes[nodes.length - 1] } : {}),
+    };
+}
 /**
  * Create a graph backend instance.
  *

package/dist/src/features/catalog.js

@@ -42,6 +42,17 @@ export const FEATURE_CATALOG = [
         ],
         cost: '~5 MB — native compile via node-gyp',
     },
+    {
+        name: 'postgres',
+        description: 'Advanced direct PostgreSQL canonical-storage backend',
+        packages: ['pg'],
+        packageSpecs: { pg: '8.23.0' },
+        enables: [
+            'aiwg.storage-backend/v1 direct PostgreSQL persistence',
+            'transactional migration batches, snapshots, cursors, and tombstones',
+        ],
+        cost: '~1 MB — pure JavaScript PostgreSQL client',
+    },
     {
         name: 'pty',
         description: 'PTY bridge for daemon — pass-through interactive TUIs (Claude Code, Codex, etc.)',

package/dist/src/storage/backend-contract.js

@@ -43,8 +43,17 @@ export const STORAGE_BACKEND_MATRIX = {
     sqlite: descriptor('sqlite', 'supported', [...BASELINE, 'atomic-batch', 'consistent-snapshot', 'tombstones', 'idempotency-keys', 'filtered-query', 'cursor-pagination', 'backup', 'restore'], 'wal', 'single-host', 'serializable', 'regenerable-index'),
     'fortemi-core-static': descriptor('fortemi-core-static', 'supported', ['read', 'filtered-query', 'recursive-traversal', 'set-operations'], 'filesystem', 'single-host', 'snapshot', 'static-cache'),
     'fortemi-server': descriptor('fortemi-server', 'alpha', [...BASELINE, 'filtered-query', 'health', 'tls', 'tenant-isolation'], 'replicated', 'remote-service', 'none', 'remote-persistence'),
-    'postgres-direct': descriptor('postgres-direct', 'advanced', [], 'replicated', 'remote-service', 'none', 'canonical'),
-    'postgres-postgrest': descriptor('postgres-postgrest', 'advanced', [], 'replicated', 'remote-service', 'none', 'canonical'),
+    'postgres-direct': descriptor('postgres-direct', 'advanced', [
+        ...BASELINE, 'atomic-batch', 'consistent-snapshot', 'change-cursor',
+        'tombstones', 'idempotency-keys', 'recursive-traversal', 'set-operations',
+        'filtered-query', 'cursor-pagination', 'health', 'readiness', 'telemetry',
+        'tenant-isolation', 'tls',
+    ], 'replicated', 'remote-service', 'serializable', 'canonical'),
+    'postgres-postgrest': descriptor('postgres-postgrest', 'advanced', [
+        ...BASELINE, 'atomic-batch', 'consistent-snapshot', 'change-cursor',
+        'tombstones', 'idempotency-keys', 'filtered-query', 'cursor-pagination',
+        'health', 'readiness', 'tenant-isolation', 'tls',
+    ], 'replicated', 'remote-service', 'serializable', 'canonical'),
     mysql: descriptor('mysql', 'deferred', [], 'replicated', 'remote-service', 'none', 'canonical'),
 };
 function descriptor(backend, maturity, capabilities, durability, availability, isolation, dataClass) {

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

@@ -0,0 +1,144 @@
+export const POSTGRES_SCHEMA_VERSION = 1;
+export const POSTGRES_SCHEMA_V1_SQL = `
+CREATE TABLE IF NOT EXISTS aiwg_storage_schema (
+  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
+  schema_version integer NOT NULL
+);
+INSERT INTO aiwg_storage_schema(singleton, schema_version)
+VALUES (true, 1) ON CONFLICT (singleton) DO NOTHING;
+CREATE TABLE IF NOT EXISTS aiwg_storage_records (
+  tenant text NOT NULL,
+  subsystem text NOT NULL,
+  path text NOT NULL,
+  source_revision text NOT NULL,
+  digest text NOT NULL,
+  value jsonb,
+  tombstone boolean NOT NULL DEFAULT false,
+  deleted_at timestamptz,
+  delete_reason text,
+  idempotency_key text NOT NULL,
+  change_seq bigserial NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  PRIMARY KEY (tenant, subsystem, path),
+  UNIQUE (tenant, subsystem, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS aiwg_storage_records_change
+  ON aiwg_storage_records(tenant, subsystem, change_seq, path);
+CREATE TABLE IF NOT EXISTS aiwg_storage_batch_receipts (
+  tenant text NOT NULL,
+  subsystem text NOT NULL,
+  batch_id uuid NOT NULL,
+  payload_digest text NOT NULL,
+  high_water_mark bigint NOT NULL,
+  receipt jsonb NOT NULL,
+  committed_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  PRIMARY KEY (tenant, subsystem, batch_id)
+);
+CREATE TABLE IF NOT EXISTS aiwg_storage_edges (
+  tenant text NOT NULL,
+  subsystem text NOT NULL,
+  source_path text NOT NULL,
+  target_path text NOT NULL,
+  edge_type text NOT NULL,
+  PRIMARY KEY (tenant, subsystem, source_path, target_path, edge_type)
+);
+CREATE INDEX IF NOT EXISTS aiwg_storage_edges_target
+  ON aiwg_storage_edges(tenant, subsystem, target_path, edge_type);
+`;
+const POSTGREST_FUNCTIONS = [
+    'aiwg_reload_schema_v1()',
+    'aiwg_health_v1(text,text)',
+    'aiwg_changes_v1(text,text,bigint,integer)',
+    'aiwg_snapshot_v1(text,text,integer)',
+    'aiwg_query_records_v1(text,text,jsonb,text,integer,boolean)',
+    'aiwg_get_record_v1(text,text,text)',
+    'aiwg_commit_batch_v1(text,text,uuid,text,jsonb)',
+    'aiwg_record_v1(aiwg_storage_records)',
+];
+export async function inspectPostgresSchema(client) {
+    const exists = await client.query("SELECT to_regclass('public.aiwg_storage_schema') IS NOT NULL AS exists");
+    if (!exists.rows[0]?.exists)
+        return { version: 0, records: 0, receipts: 0, edges: 0 };
+    const result = await client.query(`
+    SELECT schema_version,
+      (SELECT count(*) FROM aiwg_storage_records) AS records,
+      (SELECT count(*) FROM aiwg_storage_batch_receipts) AS receipts,
+      (SELECT count(*) FROM aiwg_storage_edges) AS edges
+    FROM aiwg_storage_schema WHERE singleton=true`);
+    const row = result.rows[0];
+    if (Number(row?.schema_version) !== 1)
+        throw new Error(`unsupported PostgreSQL storage schema ${String(row?.schema_version)}`);
+    return { version: 1, records: Number(row.records), receipts: Number(row.receipts), edges: Number(row.edges) };
+}
+/** Upgrade an empty database to v1 under a dedicated migration-role connection. */
+export async function upgradePostgresSchemaV1(client) {
+    await client.query('BEGIN');
+    try {
+        await client.query("SELECT pg_advisory_xact_lock(hashtextextended('aiwg-storage-schema',0))");
+        const before = await inspectPostgresSchema(client);
+        if (before.version === 1) {
+            await client.query('COMMIT');
+            return before;
+        }
+        await client.query(POSTGRES_SCHEMA_V1_SQL);
+        const after = await inspectPostgresSchema(client);
+        if (after.version !== 1)
+            throw new Error('PostgreSQL schema upgrade did not reach v1');
+        await client.query('COMMIT');
+        return after;
+    }
+    catch (error) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { /* preserve upgrade error */ }
+        throw error;
+    }
+}
+/**
+ * Roll v1 back to an empty schema. This is intentionally impossible without
+ * exact version and observed-count acknowledgements from a prior inspection.
+ */
+export async function rollbackPostgresSchemaV1(client, approval) {
+    if (approval.expectedVersion !== 1 || approval.allowDataLoss !== true)
+        throw new Error('explicit v1 data-loss approval is required');
+    await client.query('BEGIN');
+    try {
+        await client.query("SELECT pg_advisory_xact_lock(hashtextextended('aiwg-storage-schema',0))");
+        const before = await inspectPostgresSchema(client);
+        const observed = { records: before.records, receipts: before.receipts, edges: before.edges };
+        if (before.version !== 1 || JSON.stringify(observed) !== JSON.stringify(approval.expectedCounts)) {
+            throw new Error('schema rollback approval does not match current version/counts');
+        }
+        for (const signature of POSTGREST_FUNCTIONS)
+            await client.query(`DROP FUNCTION IF EXISTS ${signature}`);
+        await client.query('DROP TABLE aiwg_storage_edges, aiwg_storage_batch_receipts, aiwg_storage_records, aiwg_storage_schema');
+        const after = await inspectPostgresSchema(client);
+        if (after.version !== 0)
+            throw new Error('PostgreSQL schema rollback did not reach v0');
+        await client.query('COMMIT');
+        return after;
+    }
+    catch (error) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { /* preserve rollback error */ }
+        throw error;
+    }
+}
+export function postgresLeastPrivilegeSql(runtimeRole) {
+    const role = quoteIdentifier(runtimeRole);
+    return `REVOKE ALL ON aiwg_storage_records, aiwg_storage_batch_receipts, aiwg_storage_edges FROM PUBLIC;
+REVOKE ALL ON aiwg_storage_schema 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};`;
+}
+function quoteIdentifier(value) {
+    if (!value || value.length > 63 || /[\u0000-\u001f]/.test(value))
+        throw new Error('runtime role must be a printable PostgreSQL identifier up to 63 characters');
+    return `"${value.replaceAll('"', '""')}"`;
+}
+//# sourceMappingURL=postgres-schema.js.map