feat: upgrade all consumers to new ModuleLoader API

- job/compute-service: use ModuleLoader instead of ComputeModuleLoader
- job/compute-worker: scope derivation uses entity_type || null
- job/worker: graph-complete, compute-meter, storage-meter use ModuleLoader
- packages/agentic-server: already using new API (verified)
- packages/functions-test: worker helper uses new ModuleLoader
- packages/module-loader: graph loader queries graph_execution_module,
  adds nodeStatesTable, removes all hardcoded defaults
- Remove backward-compat shims (UsageLoader, USAGE_DEFAULTS, KNOWN_TABLES)

Author: pyramation

.github/workflows/test-module-loader.yaml

@@ -54,8 +54,7 @@ jobs:
         run: pgpm admin-users bootstrap --yes
 
       - name: Install pgpm module dependencies
-        run: |
-          cd extensions/@pgpm/metaschema-modules && npm install --legacy-peer-deps && cd ../../..
+        run: cd extensions/@pgpm/metaschema-modules && pgpm install @pgpm/services
 
       - name: Generate function packages
         run: node --experimental-strip-types scripts/generate.ts

extensions/@pgpm/metaschema-modules/Makefile

@@ -1,6 +1,7 @@
 EXTENSION = metaschema-modules
-DATA = sql/metaschema-modules--0.26.5.sql
+DATA = sql/metaschema-modules--0.28.0.sql
 
 PG_CONFIG = pg_config
 PGXS := $(shell $(PG_CONFIG) --pgxs)
 include $(PGXS)
+  

extensions/@pgpm/metaschema-modules/metaschema-modules.control

@@ -1,7 +1,7 @@
 # metaschema-modules extension
 comment = 'metaschema-modules extension'
-default_version = '0.26.5'
+default_version = '0.28.0'
 module_pathname = '$libdir/metaschema-modules'
-requires = 'plpgsql,uuid-ossp,metaschema-schema,services,pgpm-verify'
+requires = 'metaschema-schema,pgpm-database-jobs,pgpm-inflection,pgpm-jwt-claims,pgpm-types,pgpm-verify,plpgsql,services,uuid-ossp'
 relocatable = false
 superuser = false

extensions/@pgpm/metaschema-modules/package.json

@@ -20,14 +20,6 @@
     "test": "jest",
     "test:watch": "jest --watch"
   },
-  "dependencies": {
-    "@pgpm/metaschema-schema": "0.28.0",
-    "@pgpm/services": "file:../services",
-    "@pgpm/verify": "0.28.0"
-  },
-  "devDependencies": {
-    "pgpm": "^4.23.2"
-  },
   "repository": {
     "type": "git",
     "url": "https://github.com/constructive-io/pgpm-modules"
@@ -36,5 +28,13 @@
   "bugs": {
     "url": "https://github.com/constructive-io/pgpm-modules/issues"
   },
-  "gitHead": "d2ab7ca810ded086eb742eb8f0ca362b6212b97e"
-}
+  "gitHead": "d2ab7ca810ded086eb742eb8f0ca362b6212b97e",
+  "dependencies": {
+    "@pgpm/metaschema-schema": "0.28.0",
+    "@pgpm/services": "0.28.0",
+    "@pgpm/verify": "0.28.0"
+  },
+  "devDependencies": {
+    "pgpm": "^4.23.2"
+  }
+}

job/compute-service/src/index.ts

@@ -12,7 +12,7 @@
  *   4. A Scheduler for cron-like scheduled jobs
  */
 
-import ComputeWorker, { ComputeModuleLoader } from '@constructive-io/compute-worker';
+import ComputeWorker, { ModuleLoader } from '@constructive-io/compute-worker';
 import poolManager from '@constructive-io/job-pg';
 import Scheduler from '@constructive-io/job-scheduler';
 import {
@@ -399,17 +399,9 @@ export const waitForComputePrereqs = async (): Promise<void> => {
       database: cfg.database,
       max: 1,
     });
-    const loader = new ComputeModuleLoader(pool, 0);
-    const config = await loader.load(databaseId);
-
-    if (config.functionModule) {
-      const { publicSchema, definitionsTable } = config.functionModule;
-      await client.query(`SELECT count(*) FROM "${publicSchema}"."${definitionsTable}" LIMIT 1`);
-    } else {
-      // Metaschema not populated — check the compute schema directly
-      log.info('function_module not in metaschema, checking constructive_compute_public directly');
-      await client.query('SELECT count(*) FROM constructive_compute_public.platform_function_definitions LIMIT 1');
-    }
+    const loader = new ModuleLoader({ pool, ttlMs: 0 });
+    const fnConfig = await loader.function.load(databaseId, null);
+    await client.query(`SELECT count(*) FROM "${fnConfig.publicSchema}"."${fnConfig.definitionsTable}" LIMIT 1`);
 
     log.info('compute prereqs satisfied (jobs table + compute module present)');
   } catch (error) {

job/compute-worker/src/billing.ts

@@ -1,13 +1,56 @@
 /**
- * BillingTracker — re-exports BillingLoader from @constructive-io/module-loader
- * under the legacy name `BillingTracker`.
+ * BillingTracker — quota checks and usage recording via billing_module.
+ *
+ * Resolves billing config dynamically via ModuleLoader. Gracefully no-ops
+ * when billing is not provisioned (standalone dev mode).
  */
 
-import { BillingLoader } from '@constructive-io/module-loader';
+import type { BillingModuleConfig } from '@constructive-io/module-loader';
+import { ModuleLoader, ModuleNotProvisionedError } from '@constructive-io/module-loader';
 import type { Pool } from 'pg';
 
-export class BillingTracker extends BillingLoader {
-  constructor(pool: Pool, databaseId: string, cacheTtlMs?: number) {
-    super(pool, databaseId, cacheTtlMs);
+export class BillingTracker {
+  private loader: ModuleLoader;
+  private pool: Pool;
+  private databaseId: string;
+
+  constructor(pool: Pool, databaseId: string) {
+    this.pool = pool;
+    this.databaseId = databaseId;
+    this.loader = new ModuleLoader({ pool });
+  }
+
+  async load(databaseId?: string): Promise<BillingModuleConfig | null> {
+    try {
+      return await this.loader.billing.load(databaseId ?? this.databaseId, null);
+    } catch (err) {
+      if (err instanceof ModuleNotProvisionedError) return null;
+      return null;
+    }
+  }
+
+  async checkQuota(entityId: string, meterSlug: string, amount = 1, databaseId?: string): Promise<boolean> {
+    const config = await this.load(databaseId);
+    if (!config) return true;
+    try {
+      const sql = `SELECT "${config.privateSchema}"."check_billing_quota"($1, $2::uuid, $3) AS allowed`;
+      const { rows } = await this.pool.query(sql, [meterSlug, entityId, amount]);
+      return rows[0]?.allowed !== false;
+    } catch {
+      return true;
+    }
+  }
+
+  async recordUsage(entityId: string, meterSlug: string, amount: number, metadata: Record<string, unknown>, databaseId?: string): Promise<void> {
+    const config = await this.load(databaseId);
+    if (!config) return;
+    try {
+      const sql = `SELECT "${config.privateSchema}"."${config.recordUsageFunction}"($1, $2::uuid, $3, $4::jsonb)`;
+      await this.pool.query(sql, [meterSlug, entityId, amount, JSON.stringify(metadata)]);
+    } catch { /* non-fatal */ }
+  }
+
+  invalidate(databaseId?: string): void {
+    this.loader.billing.invalidate(databaseId);
   }
 }

job/compute-worker/src/cache.ts

@@ -1,4 +1,23 @@
 /**
- * Re-export TtlCache from @constructive-io/module-loader.
+ * Simple TTL cache for compute-worker internal use.
  */
-export { TtlCache } from '@constructive-io/module-loader';
+interface CacheEntry<T> { value: T; expiresAt: number; }
+
+export class TtlCache<T> {
+  private store = new Map<string, CacheEntry<T>>();
+  constructor(private ttlMs: number) {}
+
+  get(key: string): T | undefined {
+    const e = this.store.get(key);
+    if (!e) return undefined;
+    if (Date.now() > e.expiresAt) { this.store.delete(key); return undefined; }
+    return e.value;
+  }
+
+  set(key: string, value: T): void {
+    this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+  }
+
+  delete(key: string): void { this.store.delete(key); }
+  clear(): void { this.store.clear(); }
+}

job/compute-worker/src/compute-log.ts

@@ -1,12 +1,12 @@
 /**
- * ComputeLogTracker — writes to the platform_compute_log table
+ * ComputeLogTracker — writes to the compute_log table
  * after every job dispatch (success or failure) and triggers
  * the usage_daily rollup.
  *
- * Gracefully no-ops if compute_log_module is not registered.
+ * Gracefully no-ops if compute_log_module is not provisioned.
  */
 
-import type { ComputeModuleLoader } from '@constructive-io/module-loader';
+import { ModuleLoader, ModuleNotProvisionedError } from '@constructive-io/module-loader';
 import { Logger } from '@pgpmjs/logger';
 import type { Pool } from 'pg';
 
@@ -28,25 +28,28 @@ export interface ComputeLogEntry {
 
 export class ComputeLogTracker {
   private pool: Pool;
-  private loader: ComputeModuleLoader;
+  private loader: ModuleLoader;
   private databaseId: string;
 
-  constructor(pool: Pool, loader: ComputeModuleLoader, databaseId: string) {
+  constructor(pool: Pool, loader: ModuleLoader, databaseId: string) {
     this.pool = pool;
     this.loader = loader;
     this.databaseId = databaseId;
   }
 
   async log(entry: ComputeLogEntry): Promise<void> {
-    const config = await this.loader.load(this.databaseId);
-    if (!config.computeLogModule) {
-      log.debug('compute_log_module not provisioned — skipping log');
-      return;
+    let cfg;
+    try {
+      cfg = await this.loader.computeLog.load(this.databaseId, null);
+    } catch (err) {
+      if (err instanceof ModuleNotProvisionedError) {
+        log.debug('compute_log_module not provisioned — skipping log');
+        return;
+      }
+      throw err;
     }
 
-    const { publicSchema, computeLogTable } = config.computeLogModule;
-    const qualifiedTable = `"${publicSchema}"."${computeLogTable}"`;
-
+    const qualifiedTable = `"${cfg.publicSchema}"."${cfg.computeLogTable}"`;
     try {
       await this.pool.query(
         `INSERT INTO ${qualifiedTable}
@@ -75,16 +78,20 @@ export class ComputeLogTracker {
   }
 
   async rollup(since?: Date): Promise<number> {
-    const config = await this.loader.load(this.databaseId);
-    if (!config.computeLogModule) {
-      log.debug('compute_log_module not provisioned — skipping rollup');
-      return 0;
+    let cfg;
+    try {
+      cfg = await this.loader.computeLog.load(this.databaseId, null);
+    } catch (err) {
+      if (err instanceof ModuleNotProvisionedError) {
+        log.debug('compute_log_module not provisioned — skipping rollup');
+        return 0;
+      }
+      throw err;
     }
 
-    const { privateSchema } = config.computeLogModule;
     try {
       const result = await this.pool.query(
-        `SELECT count(*) AS n FROM "${privateSchema}".rollup_compute_daily($1)`,
+        `SELECT count(*) AS n FROM "${cfg.privateSchema}".rollup_compute_daily($1)`,
         [since || new Date(Date.now() - 2 * 24 * 60 * 60 * 1000)]
       );
       const n = parseInt(result.rows[0]?.n ?? '0', 10);

job/compute-worker/src/discovery.ts

@@ -2,17 +2,14 @@
  * FunctionDiscovery — lazy, cached lookups against the
  * platform function definitions table.
  *
- * Schema and table names are resolved dynamically via ComputeModuleLoader
- * instead of hardcoding a specific schema. When a job arrives the worker
- * calls `resolve(taskIdentifier)`. On cache miss, a single SQL query
- * fetches the function definition and caches it for `ttlMs` (default 60 s).
+ * Schema and table names are resolved dynamically via ModuleLoader.
  */
 
-import { TtlCache } from '@constructive-io/module-loader';
-import type { ComputeModuleLoader } from '@constructive-io/module-loader';
+import { ModuleLoader } from '@constructive-io/module-loader';
 import { Logger } from '@pgpmjs/logger';
 import type { Pool } from 'pg';
 
+import { TtlCache } from './cache';
 import type { PlatformFunctionDefinition } from './types';
 
 const log = new Logger('compute:discovery');
@@ -27,75 +24,47 @@ const COLUMNS = `
 export class FunctionDiscovery {
   private cache: TtlCache<PlatformFunctionDefinition | null>;
   private pool: Pool;
-  private loader: ComputeModuleLoader;
+  private loader: ModuleLoader;
   private databaseId: string;
 
-  constructor(pool: Pool, loader: ComputeModuleLoader, databaseId: string, ttlMs = 60_000) {
+  constructor(pool: Pool, loader: ModuleLoader, databaseId: string, ttlMs = 60_000) {
     this.pool = pool;
     this.loader = loader;
     this.databaseId = databaseId;
     this.cache = new TtlCache<PlatformFunctionDefinition | null>(ttlMs);
   }
 
-  /**
-   * Lazily resolve a function definition by task_identifier.
-   * Returns null if not registered. Results are TTL-cached.
-   */
   async resolve(taskIdentifier: string): Promise<PlatformFunctionDefinition | null> {
     const cached = this.cache.get(taskIdentifier);
-    if (cached !== undefined) {
-      log.debug(`cache hit: ${taskIdentifier}`);
-      return cached;
-    }
+    if (cached !== undefined) return cached;
 
-    log.debug(`cache miss: ${taskIdentifier}, querying DB`);
     try {
-      const config = await this.loader.load(this.databaseId);
-      const publicSchema = config.functionModule?.publicSchema ?? 'constructive_compute_public';
-      const definitionsTable = config.functionModule?.definitionsTable ?? 'platform_function_definitions';
-      const sql = `SELECT ${COLUMNS} FROM "${publicSchema}"."${definitionsTable}" WHERE task_identifier = $1 LIMIT 1`;
-
+      const cfg = await this.loader.function.load(this.databaseId, null);
+      const sql = `SELECT ${COLUMNS} FROM "${cfg.publicSchema}"."${cfg.definitionsTable}" WHERE task_identifier = $1 LIMIT 1`;
       const { rows } = await this.pool.query(sql, [taskIdentifier]);
       const def = (rows[0] as PlatformFunctionDefinition) ?? null;
       this.cache.set(taskIdentifier, def);
-      if (def) {
-        log.info(`resolved function: ${def.name} (${taskIdentifier}) → ${def.service_url ?? 'no url'}`);
-      } else {
-        log.warn(`no function registered for task_identifier="${taskIdentifier}"`);
-      }
       return def;
-    } catch (err: any) {
-      log.error(`failed to resolve "${taskIdentifier}": ${err.message}`);
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log.error(`failed to resolve "${taskIdentifier}": ${msg}`);
       return null;
     }
   }
 
-  /**
-   * List all invocable function definitions.
-   * Not cached — intended for startup diagnostics / admin endpoints.
-   */
   async listInvocable(): Promise<PlatformFunctionDefinition[]> {
     try {
-      const config = await this.loader.load(this.databaseId);
-      const publicSchema = config.functionModule?.publicSchema ?? 'constructive_compute_public';
-      const definitionsTable = config.functionModule?.definitionsTable ?? 'platform_function_definitions';
-      const sql = `SELECT ${COLUMNS} FROM "${publicSchema}"."${definitionsTable}" WHERE is_invocable = true ORDER BY name`;
-
+      const cfg = await this.loader.function.load(this.databaseId, null);
+      const sql = `SELECT ${COLUMNS} FROM "${cfg.publicSchema}"."${cfg.definitionsTable}" WHERE is_invocable = true ORDER BY name`;
       const { rows } = await this.pool.query(sql);
       return rows as PlatformFunctionDefinition[];
-    } catch (err: any) {
-      log.error(`failed to list invocable functions: ${err.message}`);
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log.error(`failed to list invocable functions: ${msg}`);
       return [];
     }
   }
 
-  /** Invalidate cached entry for a specific task. */
-  invalidate(taskIdentifier: string): void {
-    this.cache.delete(taskIdentifier);
-  }
-
-  /** Clear the entire cache. */
-  invalidateAll(): void {
-    this.cache.clear();
-  }
+  invalidate(taskIdentifier: string): void { this.cache.delete(taskIdentifier); }
+  invalidateAll(): void { this.cache.clear(); }
 }