@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/orchestration/store.mjs

@@ -16,10 +16,25 @@
  * optional one. The returned store is always async-uniform so callers await it
  * regardless of backend; the filesystem and sqlite backends resolve synchronously
  * under the hood, so the default Mode-A run record is byte-for-byte unchanged.
+ *
+ * Tenant scoping (LMCP-H4, ADR-0057/A7 stage 1): the postgres backend is the
+ * one tier multiple tenants can share a physical table on, so resolveRunStore
+ * resolves the tenant context (resolveTenantContext) before constructing it
+ * and scopes every query by (project, tenant_id). Enterprise mode with no
+ * resolvable tenant id fails closed here — TenantResolutionError propagates
+ * uncaught rather than the resolver silently defaulting to a shared bucket.
+ * Filesystem/sqlite backends are already isolated per project directory and
+ * are not multi-tenant-shared, so they carry no tenant filter.
  */
 
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { createSqlClient } from '../storage/backend.mjs';
+import { resolveTenantContext } from '../tenant/context.mjs';
+import {
+  resolveStorageBackend,
+  UnregisteredStorageProviderError,
+  UnsupportedStorageProviderError,
+} from '../storage/backend-registry.mjs';
 import { saveRun as fsSaveRun, loadRun as fsLoadRun, listRuns as fsListRuns } from './run-store.mjs';
 import { sqliteAvailable, createSqliteRunStore } from './run-store-sqlite.mjs';
 import { PostgresRunStore } from './run-store-postgres.mjs';
@@ -46,8 +61,8 @@ function sqliteStore(cwd) {
   };
 }
 
-function postgresStore({ sql, project }) {
-  const store = new PostgresRunStore({ sql, project });
+function postgresStore({ sql, project, tenantId }) {
+  const store = new PostgresRunStore({ sql, project, tenantId });
   let ensured = null;
   const ready = () => {
     if (!ensured) ensured = store.ensureSchema();
@@ -61,15 +76,32 @@ function postgresStore({ sql, project }) {
   };
 }
 
-function projectKey(config, cwd) {
+/**
+ * The same project key resolveRunStore uses to scope Postgres rows —
+ * exported so other team-store consumers (trace-store.mjs, shared-memory.mjs)
+ * key their own tables identically instead of re-deriving a divergent value.
+ */
+export function projectKey(config, cwd) {
   return config?.deployment?.projectName || cwd || 'default';
 }
 
 function chooseBackend({ config, env, cwd }) {
   const explicit = String(env?.[STORE_ENV_KEY] || config?.orchestration?.store || '').trim().toLowerCase();
-  if (ORCHESTRATION_STORES.includes(explicit)) return explicit;
+  if (explicit) return resolveStorageBackend(explicit, { rootDir: cwd, env });
   const mode = getDeploymentMode(env, { cwd });
-  return mode === 'solo' ? 'filesystem' : 'postgres';
+  return resolveStorageBackend(mode === 'solo' ? 'filesystem' : 'postgres', { rootDir: cwd, env });
+}
+
+function degradedFilesystem({ requested, reason, warning, provider = null, cwd }) {
+  return {
+    store: filesystemStore(cwd),
+    backend: 'filesystem',
+    requestedBackend: requested,
+    provider,
+    degraded: true,
+    degradedReason: reason,
+    warnings: [warning],
+  };
 }
 
 /**
@@ -83,20 +115,63 @@ function chooseBackend({ config, env, cwd }) {
  */
 export function resolveRunStore({ config = {}, env = process.env, cwd = process.cwd() } = {}) {
   const warnings = [];
-  const requested = chooseBackend({ config, env, cwd });
+  let resolved;
+  try {
+    resolved = chooseBackend({ config, env, cwd });
+  } catch (err) {
+    if (err instanceof UnregisteredStorageProviderError) {
+      return degradedFilesystem({
+        cwd,
+        requested: err.backend,
+        reason: 'storage-backend-unregistered',
+        warning: `orchestration.store "${err.backend}" has no registered kind:'storage' provider; falling back to filesystem.`,
+      });
+    }
+    if (err instanceof UnsupportedStorageProviderError) {
+      return degradedFilesystem({
+        cwd,
+        requested: err.backend,
+        reason: 'storage-backend-unsupported',
+        warning: err.message,
+      });
+    }
+    throw err;
+  }
+
+  const requested = resolved.implementation;
 
   if (requested === 'sqlite') {
-    if (sqliteAvailable()) return { store: sqliteStore(cwd), backend: 'sqlite', warnings };
+    if (sqliteAvailable()) return { store: sqliteStore(cwd), backend: resolved.backend, provider: resolved.provider, warnings };
     warnings.push('orchestration.store "sqlite" requires Node >=22.5 (node:sqlite unavailable); falling back to filesystem.');
-    return { store: filesystemStore(cwd), backend: 'filesystem', warnings };
+    return {
+      store: filesystemStore(cwd),
+      backend: 'filesystem',
+      requestedBackend: resolved.backend,
+      provider: resolved.provider,
+      degraded: true,
+      degradedReason: 'sqlite-unavailable',
+      warnings,
+    };
   }
 
   if (requested === 'postgres') {
     const sql = createSqlClient(env);
-    if (sql) return { store: postgresStore({ sql, project: projectKey(config, cwd) }), backend: 'postgres', warnings };
-    warnings.push('orchestration.store "postgres" requires a reachable DATABASE_URL; falling back to filesystem.');
-    return { store: filesystemStore(cwd), backend: 'filesystem', warnings };
+    if (sql) {
+      const mode = getDeploymentMode(env, { cwd });
+      const { tenantId } = resolveTenantContext({ env, config, mode });
+      return { store: postgresStore({ sql, project: projectKey(config, cwd), tenantId }), backend: resolved.backend, provider: resolved.provider, tenantId, warnings };
+    }
+    warnings.push(`orchestration.store "${resolved.backend}" requires a reachable DATABASE_URL; falling back to filesystem.`);
+    return {
+      store: filesystemStore(cwd),
+      backend: 'filesystem',
+      requestedBackend: resolved.backend,
+      provider: resolved.provider,
+      degraded: true,
+      degradedReason: 'postgres-unavailable',
+      warnings,
+    };
   }
 
-  return { store: filesystemStore(cwd), backend: 'filesystem', warnings };
+  return { store: filesystemStore(cwd), backend: resolved.backend, provider: resolved.provider, warnings };
 }

package/lib/orchestration/trace-store.mjs

@@ -0,0 +1,125 @@
+/**
+ * lib/orchestration/trace-store.mjs — team-shared trace event persistence (LMCP-G10).
+ *
+ * emitTraceEvent (lib/worker/trace.mjs) always writes the local, append-only
+ * `.cx/traces/<date>.jsonl` shard — that stays unchanged, on every deployment
+ * mode, with no credentials required. This module is the additional,
+ * postgres-backed channel a run's lifecycle/worker trace events feed so a
+ * team member on a different machine can read the SAME trace a worker on
+ * another machine emitted — the "run/task traces -> team store" half of the
+ * A1/A6 thread-vs-store boundary (see lib/storage/shared-memory.mjs for the
+ * long-term-memory half).
+ *
+ * Solo mode (no reachable Postgres) resolves to a `kind:'none'` store whose
+ * save/list are no-ops — the local JSONL trace already covers that case, and
+ * a team-shared read path with nothing durable behind it would be a silent
+ * lie rather than a real capability.
+ *
+ * Tenant scoping (LMCP-H4, ADR-0057/A7 stage 1): every row carries a
+ * `tenant_id` column and every query filters on it, matching the run store
+ * (run-store-postgres.mjs) and shared-memory store (shared-memory.mjs).
+ * resolveTraceStore resolves the tenant context up front and fails closed —
+ * TenantResolutionError propagates uncaught — when enterprise mode has no
+ * resolvable tenant id, rather than defaulting rows into a shared 'local'
+ * bucket. Stage 2 (physical per-tenant isolation, per-tenant encryption) is
+ * explicitly deferred and not advertised; this remains one shared table with
+ * row-level tenant scoping only.
+ */
+
+import { createSqlClient } from '../storage/backend.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { resolveTenantContext } from '../tenant/context.mjs';
+
+function noneStore() {
+  return {
+    kind: 'none',
+    saveTraceEvent: async () => ({ ok: false, reason: 'no-team-store-configured' }),
+    listTeamTraces: async () => [],
+  };
+}
+
+function postgresStore(sql, defaultTenantId) {
+  let ensured = null;
+  const ready = () => {
+    if (!ensured) {
+      ensured = (async () => {
+        const { applyMigrations } = await import('../db/migrate.mjs');
+        await applyMigrations(sql);
+      })();
+    }
+    return ensured;
+  };
+
+  return {
+    kind: 'postgres',
+    tenantId: defaultTenantId,
+    async saveTraceEvent(event, { project, tenantId = defaultTenantId } = {}) {
+      if (!project) throw new Error('saveTraceEvent: project is required');
+      if (!event?.traceId || !event?.spanId) throw new Error('saveTraceEvent: event.traceId and event.spanId are required');
+      await ready();
+      await sql`
+        INSERT INTO construct_trace_events (
+          project, tenant_id, trace_id, span_id, parent_span_id, event_type, role, task_id, metadata, created_at
+        ) VALUES (
+          ${project}, ${tenantId}, ${event.traceId}, ${event.spanId}, ${event.parentSpanId || null},
+          ${event.eventType}, ${event.role || null}, ${event.taskId || null},
+          ${sql.json(event.metadata || {})}, ${event.createdAt || new Date().toISOString()}
+        )
+        ON CONFLICT (project, tenant_id, trace_id, span_id) DO NOTHING
+      `;
+      return { ok: true };
+    },
+    async listTeamTraces({ project, tenantId = defaultTenantId, traceId, limit = 100 } = {}) {
+      if (!project) throw new Error('listTeamTraces: project is required');
+      await ready();
+      const rows = traceId
+        ? await sql`
+            SELECT trace_id, span_id, parent_span_id, event_type, role, task_id, metadata, created_at
+            FROM construct_trace_events
+            WHERE project = ${project} AND tenant_id = ${tenantId} AND trace_id = ${traceId}
+            ORDER BY created_at ASC
+            LIMIT ${limit}
+          `
+        : await sql`
+            SELECT trace_id, span_id, parent_span_id, event_type, role, task_id, metadata, created_at
+            FROM construct_trace_events
+            WHERE project = ${project} AND tenant_id = ${tenantId}
+            ORDER BY created_at DESC
+            LIMIT ${limit}
+          `;
+      return rows.map((row) => ({
+        traceId: row.trace_id,
+        spanId: row.span_id,
+        parentSpanId: row.parent_span_id,
+        eventType: row.event_type,
+        role: row.role,
+        taskId: row.task_id,
+        metadata: row.metadata,
+        createdAt: row.created_at,
+      }));
+    },
+  };
+}
+
+/**
+ * resolveTraceStore(opts)
+ *
+ * `sql` accepts an injected client (matching lib/team/health.mjs's
+ * convention) so a caller — or a test backed by an in-memory fake — can
+ * supply a shared substrate directly instead of resolving one from env.
+ * Enterprise mode with no resolvable tenant id throws TenantResolutionError
+ * before any query runs (fail-closed).
+ *
+ * @param {{ env?: object, cwd?: string, config?: object, sql?: object }} [opts]
+ * @returns {{ kind: string, saveTraceEvent: Function, listTeamTraces: Function }}
+ */
+export function resolveTraceStore({ env = process.env, cwd = process.cwd(), config = null, sql = null } = {}) {
+  const mode = getDeploymentMode(env, { cwd });
+  if (mode === 'solo' && !sql) return noneStore();
+
+  const ownSql = sql || createSqlClient(env);
+  if (!ownSql) return noneStore();
+
+  const { tenantId } = resolveTenantContext({ env, config, mode });
+  return postgresStore(ownSql, tenantId);
+}

package/lib/orchestration/web-capability.mjs

@@ -17,6 +17,7 @@
  */
 
 import { getSpecialist } from '../registry/loader.mjs';
+import { resolveNonNegativeSetting } from '../env-config.mjs';
 
 const DEFAULT_MAX_USES = 5;
 const DEFAULT_MAX_RESULTS = 5;
@@ -39,11 +40,11 @@ export function resolveWebCapability({ family, env = process.env } = {}) {
     return { mode: 'governed' };
   }
   if (family === 'anthropic') {
-    const maxUses = Number(env.CONSTRUCT_WORKER_WEB_MAX_USES) || DEFAULT_MAX_USES;
+    const maxUses = resolveNonNegativeSetting(env, 'CONSTRUCT_WORKER_WEB_MAX_USES', DEFAULT_MAX_USES);
     return { mode: 'provider-native', providerTool: 'anthropic', toolType: 'web_search_20250305', maxUses };
   }
   if (family === 'openrouter') {
-    const maxResults = Number(env.CONSTRUCT_WORKER_WEB_MAX_RESULTS) || DEFAULT_MAX_RESULTS;
+    const maxResults = resolveNonNegativeSetting(env, 'CONSTRUCT_WORKER_WEB_MAX_RESULTS', DEFAULT_MAX_RESULTS);
     return {
       mode: 'provider-native',
       providerTool: 'openrouter',

package/lib/orchestration/worker-runtime.mjs

@@ -0,0 +1,162 @@
+/**
+ * lib/orchestration/worker-runtime.mjs — team worker identity + heartbeat.
+ *
+ * Durable liveness sidecar for queue leases. The module does not start a worker
+ * pool; it records lease ownership so status/doctor can distinguish live and
+ * expired workers.
+ */
+
+import os from 'node:os';
+import process from 'node:process';
+
+import { applyMigrations } from '../db/migrate.mjs';
+
+export const WORKER_ID_ENV_KEY = 'CONSTRUCT_WORKER_ID';
+export const WORKER_TTL_ENV_KEY = 'CONSTRUCT_WORKER_TTL_SECONDS';
+export const WORKER_DEFAULT_TTL_SECONDS = 120;
+
+function defaultWorkerId(env = process.env) {
+  const explicit = env?.[WORKER_ID_ENV_KEY];
+  if (explicit && String(explicit).trim()) return String(explicit).trim();
+  return `${os.hostname()}:${process.pid}`;
+}
+
+function normalizeTtl(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : WORKER_DEFAULT_TTL_SECONDS;
+}
+
+function normalizeCapabilities(capabilities = []) {
+  return Array.isArray(capabilities)
+    ? [...new Set(capabilities.map((c) => String(c).trim()).filter(Boolean))].sort()
+    : [];
+}
+
+export class WorkerRegistry {
+  constructor({ sql, project, tenantId = 'local' } = {}) {
+    if (!sql) throw new Error('WorkerRegistry: sql client is required');
+    if (!project) throw new Error('WorkerRegistry: project is required');
+    this.sql = sql;
+    this.project = project;
+    this.tenantId = tenantId;
+    this._ensured = null;
+  }
+
+  async ensureSchema() {
+    if (!this._ensured) this._ensured = applyMigrations(this.sql);
+    return this._ensured;
+  }
+
+  async register({
+    workerId,
+    env = process.env,
+    host = os.hostname(),
+    pid = process.pid,
+    capabilities = [],
+    ttlSeconds = env?.[WORKER_TTL_ENV_KEY],
+    metadata = {},
+  } = {}) {
+    await this.ensureSchema();
+    const id = workerId || defaultWorkerId(env);
+    const ttl = normalizeTtl(ttlSeconds);
+    const caps = normalizeCapabilities(capabilities);
+    await this.sql`
+      INSERT INTO construct_workers (
+        project, tenant_id, worker_id, host, pid, capabilities,
+        registered_at, heartbeat_at, lease_ttl_seconds, status, metadata
+      ) VALUES (
+        ${this.project}, ${this.tenantId}, ${id}, ${host || null}, ${Number(pid) || null},
+        ${this.sql.json(caps)}, now(), now(), ${ttl}, 'active', ${this.sql.json(metadata || {})}
+      )
+      ON CONFLICT (project, tenant_id, worker_id) DO UPDATE SET
+        host = EXCLUDED.host,
+        pid = EXCLUDED.pid,
+        capabilities = EXCLUDED.capabilities,
+        heartbeat_at = now(),
+        lease_ttl_seconds = EXCLUDED.lease_ttl_seconds,
+        status = 'active',
+        metadata = EXCLUDED.metadata
+    `;
+    return { workerId: id, project: this.project, tenantId: this.tenantId, host, pid, capabilities: caps, ttlSeconds: ttl };
+  }
+
+  async heartbeat(workerId, { ttlSeconds, renewQueue = null } = {}) {
+    if (!workerId) throw new Error('heartbeat: workerId is required');
+    await this.ensureSchema();
+    const ttl = normalizeTtl(ttlSeconds);
+    const rows = await this.sql`
+      UPDATE construct_workers
+      SET heartbeat_at = now(),
+          lease_ttl_seconds = ${ttl},
+          status = 'active'
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND worker_id = ${workerId}
+      RETURNING worker_id, heartbeat_at, lease_ttl_seconds
+    `;
+    if (!rows[0]) return { workerId, renewed: false };
+    if (renewQueue && typeof renewQueue.heartbeat === 'function') {
+      await renewQueue.heartbeat(renewQueue.itemId, { workerId, leaseSeconds: ttl });
+    }
+    return {
+      workerId,
+      renewed: true,
+      heartbeatAt: rows[0].heartbeat_at,
+      ttlSeconds: rows[0].lease_ttl_seconds,
+    };
+  }
+
+  async deregister(workerId) {
+    if (!workerId) throw new Error('deregister: workerId is required');
+    await this.ensureSchema();
+    const rows = await this.sql`
+      UPDATE construct_workers
+      SET status = 'stopped'
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND worker_id = ${workerId}
+      RETURNING worker_id
+    `;
+    return { workerId, stopped: Boolean(rows[0]) };
+  }
+
+  async list({ includeStale = true } = {}) {
+    await this.ensureSchema();
+    const rows = includeStale
+      ? await this.sql`
+          SELECT worker_id, host, pid, capabilities, registered_at, heartbeat_at,
+                 lease_ttl_seconds, status, metadata,
+                 (heartbeat_at + (lease_ttl_seconds * interval '1 second') < now()) AS stale
+          FROM construct_workers
+          WHERE project = ${this.project} AND tenant_id = ${this.tenantId}
+          ORDER BY heartbeat_at DESC, worker_id ASC
+        `
+      : await this.sql`
+          SELECT worker_id, host, pid, capabilities, registered_at, heartbeat_at,
+                 lease_ttl_seconds, status, metadata,
+                 (heartbeat_at + (lease_ttl_seconds * interval '1 second') < now()) AS stale
+          FROM construct_workers
+          WHERE project = ${this.project}
+            AND tenant_id = ${this.tenantId}
+            AND status = 'active'
+            AND heartbeat_at + (lease_ttl_seconds * interval '1 second') >= now()
+          ORDER BY heartbeat_at DESC, worker_id ASC
+        `;
+    return rows.map((row) => ({
+      workerId: row.worker_id,
+      host: row.host,
+      pid: row.pid,
+      capabilities: row.capabilities || [],
+      registeredAt: row.registered_at,
+      heartbeatAt: row.heartbeat_at,
+      ttlSeconds: row.lease_ttl_seconds,
+      status: row.status === 'active' && row.stale ? 'stale' : row.status,
+      stale: Boolean(row.stale),
+      metadata: row.metadata || {},
+    }));
+  }
+}
+
+export function createWorkerRegistry({ sql, project, tenantId } = {}) {
+  return new WorkerRegistry({ sql, project, tenantId });
+}