@onlineapps/service-common 1.1.3 → 2.0.0

package/README.md

@@ -67,6 +67,96 @@ Waits for all infrastructure services to be reported as healthy by Registry.
 - `INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME` - Maximum wait time in ms
 - `INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL` - Check interval in ms
 
+### Scoped registry — `isVisible` / `sqlVisible` and friends
+
+The single home of the registry visibility rule: *a registry row is visible to a
+caller `{tenant_id, workspace_id}` iff it is `system`, or it is owned by exactly
+that workspace.* Business services must not hand-write this predicate.
+
+Normative contract: [`api/docs/biz/30-operations/scoped-registry.md`](../../docs/biz/30-operations/scoped-registry.md).
+
+| Export | Purpose |
+|---|---|
+| `isVisible(record, ctx)` | pure predicate — works over SQL rows, Redis, config files, connector responses |
+| `filterVisible(records, ctx)` | apply the predicate to a collection |
+| `pickVisibleOne(records, ctx)` | read-time resolution; throws on 0 or >1 visible rows (no precedence, no `LIMIT 1`) |
+| `sqlVisible(alias)` | the same rule as a `WHERE` fragment, for DB pushdown |
+| `sqlVisibleParams(ctx)` | named replacements (`__vis_tid`, `__vis_wid`) for that fragment |
+| `assertScopeTriple(record)` | write-time invariant: `scope='system' ⟺ owner columns NULL` |
+| `assertUniqueInScope(existingVisible, candidate, keyFn)` | write-time collision guard — refuses a definition that would shadow a visible one |
+
+```js
+const { sqlVisible, sqlVisibleParams } = require('@onlineapps/service-common');
+
+const rows = await sequelize.query(
+  `SELECT uuid, code FROM ing_connector c WHERE ${sqlVisible('c')}`,
+  { replacements: sqlVisibleParams(ctx), type: QueryTypes.SELECT }
+);
+```
+
+The predicate is the source of truth; the SQL fragment is a pushdown
+optimization. A parity unit test evaluates the fragment in-memory with SQL
+three-valued logic and fails if the two renderings ever disagree.
+
+All helpers fail fast: a missing or non-integer `tenant_id`/`workspace_id`
+throws rather than degrading into "system rows only", which would silently hide
+a workspace's own definitions.
+
+### Registry reader — `createRegistryReader(options)`
+
+The single Redis-backed reader of Service Registry specifications. The Registry
+(`api_services_registry`) is the only writer; every consumer — infrastructure or
+business — reads the same two key shapes:
+
+| Key | Type | Content |
+|---|---|---|
+| `<keyPrefix>services` | HASH | per-service summary |
+| `<keyPrefix>service:<name>:spec` | STRING | full service specification |
+
+Normative contract: [`api/docs/biz/30-operations/registration-wire.md`](../../docs/biz/30-operations/registration-wire.md)
+§4 (storage model) and §7 (consumer contract); namespace per
+[`api/docs/standards/redis-key-contract.md`](../../docs/standards/redis-key-contract.md).
+
+```js
+const { createRegistryReader } = require('@onlineapps/service-common');
+
+const reader = createRegistryReader({
+  keyPrefix: requireEnv('REDIS_REGISTRY_KEY_PREFIX'), // REQUIRED — never assumed
+  redisUrl: requireEnv('REDIS_URL'),                  // or: client: <connected node-redis v4 client>
+  logger                                              // REQUIRED — no console fallback
+});
+await reader.connect();
+
+const op = await reader.getOperation('biz-invoicing', 'create-invoice');
+```
+
+| Export | Purpose |
+|---|---|
+| `connect()` | opens the owned connection (hard `connectTimeoutMs` ceiling), or validates an injected client |
+| `getServiceSpec(name)` | full spec, or `null` when the service is not registered |
+| `getOperation(name, key)` | one operation record, or `null` |
+| `listSummary()` | parsed `<keyPrefix>services` hash |
+| `listAll()` | `[{ name, summary, spec }]` for every summarised service |
+| `listWorkspaceScopedServices()` | `[{ name, version, description }]` for `workspaceScoped === true`, sorted by name; `version`/`description` come from `spec.metadata` (§4: `metadata` is required) |
+| `invalidateCache(name?)` | drop one service or the whole cache — for `registry.changes` listeners |
+| `close()` | quits the connection **only** when the reader created it |
+
+**Connection ownership:** pass exactly one of `redisUrl` (the reader owns and
+closes the client) or `client` (the caller owns it; `close()` never quits it).
+
+**Failure model — an outage is not a cache miss:**
+
+| Situation | Answer |
+|---|---|
+| key absent | `null`, remembered for `negativeTtlMs` (default 30 s) |
+| Redis transport error | the error **propagates** — never `null` |
+| unparseable JSON | throws, naming the key |
+| Redis unreachable at startup | `connect()` rejects after `connectTimeoutMs` (default 15 s) |
+
+`keyPrefix` and `logger` are mandatory and `ttlMs` / `negativeTtlMs` /
+`connectTimeoutMs` are validated: an invalid value throws instead of being
+silently replaced by the module default (`src/defaults.js` owns the defaults).
+
 ## Architecture
 
 This library is used by:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onlineapps/service-common",
-  "version": "1.1.3",
-  "description": "Common utilities for both infrastructure services and business services (JWT auth, Redis/Postgres clients, business errors, runtime config)",
+  "version": "2.0.0",
+  "description": "Common utilities for both infrastructure services and business services (JWT auth, Redis client, business errors, runtime config)",
   "main": "src/index.js",
   "scripts": {
     "test": "jest",

package/src/defaults.js

@@ -20,6 +20,16 @@ module.exports = {
 
   infrastructureHealthQueueWaitMaxTimeMs: 60000,
   infrastructureHealthQueueWaitCheckIntervalMs: 2000,
+
+  // registryReader in-memory cache (see ./registryReader.js).
+  // Positive entries live 5 minutes; a "service not registered" answer is
+  // remembered for 30 s only, so a fresh registration becomes visible quickly.
+  registryReaderTtlMs: 300000,
+  registryReaderNegativeTtlMs: 30000,
+  // Hard ceiling for the initial connect when the reader owns the client, so a
+  // dead Redis fails startup instead of retrying forever (same 15 s ceiling as
+  // connectRedis in ./redisClient.js).
+  registryReaderConnectTimeoutMs: 15000,
 };
 
 

package/src/errors/BusinessError.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// See: docs/standards/error-handling-contract.md
+// See: docs/biz/70-contracts/error-handling.md
 const ERROR_TYPES = {
   TRANSIENT: 'TRANSIENT',
   BUSINESS: 'BUSINESS',

package/src/errors/errorMiddleware.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// See: docs/standards/error-handling-contract.md
+// See: docs/biz/70-contracts/error-handling.md
 const { BusinessError, isBusinessError } = require('./BusinessError');
 
 function businessErrorHandler(err, req, res, next) {

package/src/index.js

@@ -17,11 +17,7 @@ const {
   createRedisClient,
   connectRedis
 } = require('./redisClient');
-const {
-  buildPostgresUrl,
-  createPostgresPool,
-  connectPostgres
-} = require('./postgresClient');
+const { createRegistryReader } = require('./registryReader');
 const {
   requireEnv,
   requireNumberEnv,
@@ -56,6 +52,18 @@ const {
   sensitiveFieldsForOperation,
   redactSensitiveDeep
 } = require('./redactSensitive');
+const {
+  isVisible,
+  filterVisible,
+  pickVisibleOne,
+  sqlVisible,
+  sqlVisibleParams,
+  assertScopeTriple,
+  assertUniqueInScope,
+  ScopedRegistryError,
+  SCOPE_SYSTEM,
+  SCOPE_WORKSPACE
+} = require('./scopedRegistry');
 
 module.exports = {
   // Infrastructure readiness utilities (used by both infrastructure and business services)
@@ -67,10 +75,9 @@ module.exports = {
   createRedisClient,
   connectRedis,
 
-  // PostgreSQL utilities (shared between services and tests)
-  buildPostgresUrl,
-  createPostgresPool,
-  connectPostgres,
+  // Service Registry reader (the one Redis-backed reader of registry specs)
+  // See: docs/biz/30-operations/registration-wire.md §4/§7
+  createRegistryReader,
 
   // Configuration helpers (NO FALLBACKS for critical infrastructure)
   requireEnv,
@@ -109,7 +116,20 @@ module.exports = {
   // See: docs/architecture/secretbox.md §8
   REDACTED_PLACEHOLDER,
   sensitiveFieldsForOperation,
-  redactSensitiveDeep
+  redactSensitiveDeep,
+
+  // Scoped-registry visibility rule (system ∪ own workspace)
+  // See: docs/biz/30-operations/scoped-registry.md
+  isVisible,
+  filterVisible,
+  pickVisibleOne,
+  sqlVisible,
+  sqlVisibleParams,
+  assertScopeTriple,
+  assertUniqueInScope,
+  ScopedRegistryError,
+  SCOPE_SYSTEM,
+  SCOPE_WORKSPACE
 };
 
 

package/src/jwt/extractTenantContext.js

@@ -18,7 +18,7 @@
  * @returns {object} { tenant_id, tenant_uuid, workspace_id, person_id, person_uuid, role }
  * @throws {Error} with .statusCode = 400, 401, or 403
  */
-// See: docs/standards/tenant-context-contract.md
+// See: docs/biz/20-tenancy/tenant-context.md
 function extractTenantContext(auth, headers, options) {
   const { requireWorkspace = true } = options || {};
 

package/src/registryReader.js

@@ -0,0 +1,355 @@
+'use strict';
+
+/**
+ * registryReader
+ * --------------
+ * The one Redis-backed reader of the Service Registry specifications.
+ *
+ * The Registry (`api_services_registry`) is the single writer; every consumer —
+ * infrastructure or business — reads the same two key shapes:
+ *
+ *   `<keyPrefix>services`              HASH   — per-service summary
+ *   `<keyPrefix>service:<name>:spec`   STRING — full service specification
+ *
+ * The prefix is NEVER assumed. It is injected by the caller (the platform value
+ * lives in REDIS_REGISTRY_KEY_PREFIX), because a reader that hardcodes a
+ * namespace cannot be pointed at a second one — not in a test, not in a second
+ * environment.
+ *
+ * Failure model (fail-fast, architecture-principles §3/§4):
+ *   - key absent            → `null`, remembered for `negativeTtlMs`
+ *   - Redis transport error → the error PROPAGATES (never `null`)
+ *   - unparseable JSON      → throws, naming the key
+ *
+ * An infrastructure outage and "this service is not registered" are different
+ * facts and must not collapse into the same answer.
+ *
+ * @see api/docs/biz/30-operations/registration-wire.md §4 Redis storage model
+ * @see api/docs/biz/30-operations/registration-wire.md §7 Consumer contract
+ * @see api/docs/standards/redis-key-contract.md — registry namespace
+ */
+
+const { createClient } = require('redis');
+const DEFAULTS = require('./defaults');
+
+const CONTEXT = '[service-common][registryReader]';
+
+function requireKeyPrefix(keyPrefix) {
+  if (typeof keyPrefix !== 'string' || keyPrefix.trim().length === 0) {
+    throw new Error(
+      `${CONTEXT} Missing required option - keyPrefix must be a non-empty string. `
+      + 'Fix: pass the registry key namespace explicitly, e.g. the value of REDIS_REGISTRY_KEY_PREFIX '
+      + `(got ${JSON.stringify(keyPrefix)}).`
+    );
+  }
+  return keyPrefix;
+}
+
+function requireLogger(logger) {
+  const missing = ['info', 'warn', 'error'].filter(
+    (method) => !logger || typeof logger[method] !== 'function'
+  );
+  if (missing.length > 0) {
+    throw new Error(
+      `${CONTEXT} Missing dependency - logger is required and must implement ${missing.join(', ')} `
+      + '(no console fallback). Fix: inject the service logger.'
+    );
+  }
+  return logger;
+}
+
+function requireTtl(value, name, fallbackDefault) {
+  if (value === undefined) return fallbackDefault;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new Error(
+      `${CONTEXT} Invalid option - ${name} must be a finite positive number of milliseconds `
+      + `(got ${JSON.stringify(value)}). Fix: omit it to use the module default, or pass a number > 0.`
+    );
+  }
+  return value;
+}
+
+function requireClientContract(client) {
+  const missing = ['get', 'hGetAll'].filter((method) => typeof client[method] !== 'function');
+  if (missing.length > 0) {
+    throw new Error(
+      `${CONTEXT} Redis client contract mismatch - injected client is missing: ${missing.join(', ')}. `
+      + 'Fix: inject a connected node-redis v4 client.'
+    );
+  }
+  return client;
+}
+
+function requireNonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      `${CONTEXT} Invalid argument - ${label} must be a non-empty string (got ${JSON.stringify(value)}).`
+    );
+  }
+  return value;
+}
+
+function parseOrThrow(raw, key, what) {
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `${CONTEXT} Corrupt registry data - ${what} at ${key} is not valid JSON (${err.message}). `
+      + 'Fix: the Registry is the single writer of this key — re-register the service.'
+    );
+  }
+}
+
+/**
+ * Create a registry reader.
+ *
+ * Exactly one connection source must be given:
+ *   - `redisUrl` — the reader creates and owns the client (closed by `close()`)
+ *   - `client`   — an already connected node-redis v4 client owned by the caller
+ *                  (`close()` never quits it)
+ *
+ * @param {object}  options
+ * @param {string}  options.keyPrefix       Registry key namespace (REQUIRED, no default)
+ * @param {string}  [options.redisUrl]      Redis connection URL
+ * @param {object}  [options.client]        Connected node-redis v4 client
+ * @param {object}  options.logger          Logger implementing info/warn/error (REQUIRED)
+ * @param {number}  [options.ttlMs]         TTL of a cached spec (default: defaults.registryReaderTtlMs)
+ * @param {number}  [options.negativeTtlMs] TTL of a cached "not registered" (default: defaults.registryReaderNegativeTtlMs)
+ * @returns {object} reader
+ */
+function createRegistryReader(options) {
+  if (!options || typeof options !== 'object') {
+    throw new Error(
+      `${CONTEXT} Missing options - createRegistryReader({ keyPrefix, redisUrl|client, logger }) is required.`
+    );
+  }
+
+  const { keyPrefix, redisUrl, client, logger, ttlMs, negativeTtlMs, connectTimeoutMs } = options;
+
+  requireKeyPrefix(keyPrefix);
+
+  const hasUrl = redisUrl !== undefined;
+  const hasClient = client !== undefined;
+  if (hasUrl === hasClient) {
+    throw new Error(
+      `${CONTEXT} Invalid connection source - pass exactly one of redisUrl or client `
+      + `(redisUrl: ${hasUrl ? 'set' : 'absent'}, client: ${hasClient ? 'set' : 'absent'}). `
+      + 'Fix: let the reader own the connection (redisUrl) or inject an existing one (client).'
+    );
+  }
+  if (hasUrl && (typeof redisUrl !== 'string' || redisUrl.trim().length === 0)) {
+    throw new Error(
+      `${CONTEXT} Invalid option - redisUrl must be a non-empty string (got ${JSON.stringify(redisUrl)}).`
+    );
+  }
+  if (hasClient) {
+    if (!client || typeof client !== 'object') {
+      throw new Error(`${CONTEXT} Invalid option - client must be a connected node-redis v4 client object.`);
+    }
+    requireClientContract(client);
+  }
+
+  const log = requireLogger(logger);
+  const positiveTtl = requireTtl(ttlMs, 'ttlMs', DEFAULTS.registryReaderTtlMs);
+  const negativeTtl = requireTtl(negativeTtlMs, 'negativeTtlMs', DEFAULTS.registryReaderNegativeTtlMs);
+  const connectTimeout = requireTtl(
+    connectTimeoutMs, 'connectTimeoutMs', DEFAULTS.registryReaderConnectTimeoutMs
+  );
+
+  const ownsClient = hasUrl;
+  let redis = hasClient ? client : null;
+  let connected = false;
+
+  /** @type {Map<string, {spec: object|null, expiresAt: number}>} */
+  const specCache = new Map();
+  let summaryCache = null;
+
+  const summaryKey = () => `${keyPrefix}services`;
+  const specKey = (serviceName) => `${keyPrefix}service:${serviceName}:spec`;
+
+  function assertConnected(method) {
+    if (!connected) {
+      throw new Error(
+        `${CONTEXT} Reader is not connected - ${method} was called before connect(). `
+        + 'Fix: await reader.connect() during service startup.'
+      );
+    }
+  }
+
+  async function connect() {
+    if (connected) return;
+
+    if (ownsClient) {
+      const created = createClient({ url: redisUrl, socket: { connectTimeout } });
+      created.on('error', (err) => {
+        log.error(`${CONTEXT} Redis client error: ${err.message}`);
+      });
+
+      // node-redis keeps retrying a refused connection forever, so the initial
+      // connect gets its own hard ceiling — startup must fail, not hang.
+      let timeoutHandle = null;
+      const deadline = new Promise((_resolve, reject) => {
+        timeoutHandle = setTimeout(() => reject(new Error(
+          `${CONTEXT} Redis connection timeout - no connection to ${redisUrl} within ${connectTimeout}ms. `
+          + 'Fix: check the Redis address and that the instance is running.'
+        )), connectTimeout);
+      });
+
+      try {
+        await Promise.race([created.connect(), deadline]);
+      } catch (err) {
+        try {
+          await created.disconnect();
+        } catch (_ignored) {
+          // The client never opened; nothing to release.
+        }
+        throw err;
+      } finally {
+        clearTimeout(timeoutHandle);
+      }
+      redis = created;
+    }
+
+    connected = true;
+    log.info(`${CONTEXT} Ready (keyPrefix="${keyPrefix}", ttl=${positiveTtl}ms, negativeTtl=${negativeTtl}ms)`);
+  }
+
+  async function getServiceSpec(serviceName) {
+    assertConnected('getServiceSpec()');
+    requireNonEmptyString(serviceName, 'serviceName');
+
+    const now = Date.now();
+    const cached = specCache.get(serviceName);
+    if (cached && cached.expiresAt > now) {
+      return cached.spec;
+    }
+
+    const key = specKey(serviceName);
+    // Transport errors propagate on purpose — see the failure model above.
+    const raw = await redis.get(key);
+
+    if (raw === null || raw === undefined) {
+      specCache.set(serviceName, { spec: null, expiresAt: now + negativeTtl });
+      return null;
+    }
+
+    const spec = parseOrThrow(raw, key, 'service spec');
+    specCache.set(serviceName, { spec, expiresAt: now + positiveTtl });
+    return spec;
+  }
+
+  async function getOperation(serviceName, operationKey) {
+    assertConnected('getOperation()');
+    requireNonEmptyString(serviceName, 'serviceName');
+    requireNonEmptyString(operationKey, 'operationKey');
+
+    const spec = await getServiceSpec(serviceName);
+    const operations = spec && spec.operations;
+    if (!operations || typeof operations !== 'object') {
+      return null;
+    }
+    if (!Object.prototype.hasOwnProperty.call(operations, operationKey)) {
+      return null;
+    }
+    return operations[operationKey];
+  }
+
+  async function listSummary() {
+    assertConnected('listSummary()');
+
+    const now = Date.now();
+    if (summaryCache && summaryCache.expiresAt > now) {
+      return summaryCache.services;
+    }
+
+    const key = summaryKey();
+    const raw = await redis.hGetAll(key);
+
+    const services = {};
+    for (const [name, json] of Object.entries(raw || {})) {
+      services[name] = parseOrThrow(json, key, `summary entry "${name}"`);
+    }
+
+    summaryCache = { services, expiresAt: now + positiveTtl };
+    return services;
+  }
+
+  async function listAll() {
+    assertConnected('listAll()');
+    const summary = await listSummary();
+    return Promise.all(
+      Object.keys(summary).map(async (name) => ({
+        name,
+        summary: summary[name],
+        spec: await getServiceSpec(name)
+      }))
+    );
+  }
+
+  async function listWorkspaceScopedServices() {
+    assertConnected('listWorkspaceScopedServices()');
+    const all = await listAll();
+
+    const scoped = [];
+    for (const { name, spec } of all) {
+      if (!spec || spec.workspaceScoped !== true) continue;
+
+      const metadata = spec.metadata;
+      const version = metadata && metadata.version;
+      const description = metadata && metadata.description;
+      if (typeof version !== 'string' || version.length === 0
+        || typeof description !== 'string' || description.length === 0) {
+        throw new Error(
+          `${CONTEXT} Invalid service spec - service "${name}" declares workspaceScoped: true but its `
+          + 'metadata block does not carry both version and description '
+          + '(registration-wire.md §4: metadata is required). Fix: correct config.json and re-register.'
+        );
+      }
+      scoped.push({ name, version, description });
+    }
+
+    scoped.sort((a, b) => a.name.localeCompare(b.name));
+    return scoped;
+  }
+
+  function invalidateCache(serviceName) {
+    if (serviceName) {
+      specCache.delete(serviceName);
+      return;
+    }
+    specCache.clear();
+    summaryCache = null;
+  }
+
+  async function close() {
+    if (ownsClient && redis && connected) {
+      try {
+        await redis.quit();
+      } catch (err) {
+        log.warn(`${CONTEXT} Redis quit error: ${err.message}`);
+      }
+      redis = null;
+    }
+    connected = false;
+    specCache.clear();
+    summaryCache = null;
+  }
+
+  return {
+    connect,
+    getServiceSpec,
+    getOperation,
+    listSummary,
+    listAll,
+    listWorkspaceScopedServices,
+    invalidateCache,
+    close,
+    get keyPrefix() { return keyPrefix; },
+    get ttlMs() { return positiveTtl; },
+    get negativeTtlMs() { return negativeTtl; },
+    get isConnected() { return connected; },
+    get cacheSize() { return specCache.size; }
+  };
+}
+
+module.exports = { createRegistryReader };

package/src/scopedRegistry/ScopedRegistryError.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * Error raised by the scoped-registry contract helpers.
+ *
+ * Message format follows ARCHITECTURE_PRINCIPLES §5:
+ *   [ScopedRegistry] Problem - Expected/Fix.
+ *
+ * `details` carries machine-readable context so a business service can map it
+ * onto its own domain error codes without re-parsing the message.
+ */
+class ScopedRegistryError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'ScopedRegistryError';
+    this.details = details;
+    Error.captureStackTrace(this, ScopedRegistryError);
+  }
+}
+
+module.exports = { ScopedRegistryError };

package/src/scopedRegistry/index.js

@@ -0,0 +1,260 @@
+'use strict';
+
+/**
+ * Scoped Registry — the one place the registry visibility rule lives.
+ *
+ * Contract: api/docs/biz/30-operations/scoped-registry.md
+ *
+ *   A registry row is visible to a caller {tenant_id, workspace_id} iff it is
+ *   `system`, or it is owned by exactly that workspace.
+ *
+ * The rule is rendered two ways: `isVisible` (pure predicate, works over any
+ * source — SQL rows, Redis, config files, connector responses) and `sqlVisible`
+ * (WHERE fragment, a pushdown optimization for DB-backed registries). The
+ * predicate is the source of truth; a parity unit test asserts the two agree.
+ *
+ * Pure module: no config, no env, no state (ARCHITECTURE_PRINCIPLES §1, §3).
+ */
+
+const { ScopedRegistryError } = require('./ScopedRegistryError');
+
+const SCOPE_SYSTEM = 'system';
+const SCOPE_WORKSPACE = 'workspace';
+const KNOWN_SCOPES = [SCOPE_SYSTEM, SCOPE_WORKSPACE];
+
+// SQL named replacements. Prefixed to avoid colliding with a caller's own
+// replacement keys in the same query.
+const PARAM_TENANT = '__vis_tid';
+const PARAM_WORKSPACE = '__vis_wid';
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Validate the caller context. Both identifiers are required integers — a
+ * missing or loosely-typed value must never degrade into "system rows only",
+ * which would silently hide a workspace's own definitions.
+ */
+function requireContext(ctx) {
+  if (!ctx || typeof ctx !== 'object') {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Missing caller context - Expected an object with integer tenant_id and workspace_id. '
+      + 'Fix: pass the ctx injected by the orchestrator.',
+      { ctx }
+    );
+  }
+  if (!Number.isInteger(ctx.tenant_id)) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Invalid caller context - tenant_id must be an integer. '
+      + `Fix: pass ctx.tenant_id from the injected tenant context (got ${JSON.stringify(ctx.tenant_id)}).`,
+      { tenant_id: ctx.tenant_id }
+    );
+  }
+  if (!Number.isInteger(ctx.workspace_id)) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Invalid caller context - workspace_id must be an integer. '
+      + `Fix: pass ctx.workspace_id from the injected tenant context (got ${JSON.stringify(ctx.workspace_id)}).`,
+      { workspace_id: ctx.workspace_id }
+    );
+  }
+  return { tenant_id: ctx.tenant_id, workspace_id: ctx.workspace_id };
+}
+
+function requireScope(record) {
+  if (!record || typeof record !== 'object') {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Missing record - Expected an object carrying scope, owner_tenant_id, owner_workspace_id. '
+      + 'Fix: pass a registry row.',
+      { record }
+    );
+  }
+  if (!KNOWN_SCOPES.includes(record.scope)) {
+    throw new ScopedRegistryError(
+      `[ScopedRegistry] Unknown scope "${record.scope}" - Expected '${SCOPE_SYSTEM}' or '${SCOPE_WORKSPACE}'. `
+      + 'Fix: correct the row, or add the new scope to the contract first.',
+      { scope: record.scope }
+    );
+  }
+  return record.scope;
+}
+
+/**
+ * The canonical visibility rule (§2.1).
+ *
+ * @param {{scope: string, owner_tenant_id: ?number, owner_workspace_id: ?number}} record
+ * @param {{tenant_id: number, workspace_id: number}} ctx
+ * @returns {boolean}
+ */
+function isVisible(record, ctx) {
+  const scope = requireScope(record);
+  const { tenant_id, workspace_id } = requireContext(ctx);
+
+  if (scope === SCOPE_SYSTEM) return true;
+
+  // A workspace row with NULL owners violates the §1.1 invariant. It is
+  // visible to nobody — matching SQL, where NULL = :tid yields NULL, not TRUE.
+  return record.owner_tenant_id === tenant_id
+      && record.owner_workspace_id === workspace_id;
+}
+
+/**
+ * Apply the rule to any in-memory collection (§2.1).
+ */
+function filterVisible(records, ctx) {
+  if (!Array.isArray(records)) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Invalid records - Expected an array of registry rows. '
+      + `Fix: pass the collection to filter (got ${typeof records}).`,
+      { records }
+    );
+  }
+  requireContext(ctx);
+  return records.filter((record) => isVisible(record, ctx));
+}
+
+/**
+ * Read-time resolution with ambiguity fail-fast (§4.B).
+ *
+ * Never applies precedence: if both a system row and a workspace row are
+ * visible for one logical lookup, that is a collision that slipped past the
+ * write-time guard, and the caller gets an error rather than a silent winner.
+ */
+function pickVisibleOne(records, ctx) {
+  const visible = filterVisible(records, ctx);
+
+  if (visible.length === 0) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] No visible record - Expected exactly one row visible to this caller. '
+      + 'Fix: check the lookup key, or register the definition for this workspace.',
+      { visibleCount: 0, tenant_id: ctx.tenant_id, workspace_id: ctx.workspace_id }
+    );
+  }
+  if (visible.length > 1) {
+    throw new ScopedRegistryError(
+      `[ScopedRegistry] Ambiguous record - ${visible.length} rows are visible for a single lookup, expected 1. `
+      + 'Fix: remove the shadowing definition; workspace rows must not overlap system ones.',
+      {
+        visibleCount: visible.length,
+        scopes: visible.map((r) => r.scope),
+        tenant_id: ctx.tenant_id,
+        workspace_id: ctx.workspace_id
+      }
+    );
+  }
+  return visible[0];
+}
+
+/**
+ * The same rule rendered as a SQL WHERE fragment (§2.2).
+ *
+ * Bind the returned fragment with `sqlVisibleParams(ctx)`. The alias is
+ * interpolated, so it is restricted to a plain identifier.
+ *
+ * @param {string} alias table alias used in the query
+ * @returns {string}
+ */
+function sqlVisible(alias) {
+  if (typeof alias !== 'string' || alias.trim() === '') {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Missing table alias - Expected a non-empty identifier. '
+      + "Fix: pass the alias used in the query, e.g. sqlVisible('c').",
+      { alias }
+    );
+  }
+  if (!IDENTIFIER.test(alias)) {
+    throw new ScopedRegistryError(
+      `[ScopedRegistry] Invalid table alias "${alias}" - Expected a plain identifier [A-Za-z_][A-Za-z0-9_]*. `
+      + 'Fix: alias the table in the query and pass that identifier.',
+      { alias }
+    );
+  }
+
+  return `(${alias}.scope = '${SCOPE_SYSTEM}' `
+    + `OR (${alias}.owner_tenant_id = :${PARAM_TENANT} AND ${alias}.owner_workspace_id = :${PARAM_WORKSPACE}))`;
+}
+
+/**
+ * Named replacements for the fragment returned by `sqlVisible` (§2.2).
+ */
+function sqlVisibleParams(ctx) {
+  const { tenant_id, workspace_id } = requireContext(ctx);
+  return { [PARAM_TENANT]: tenant_id, [PARAM_WORKSPACE]: workspace_id };
+}
+
+/**
+ * Enforce the scope triple invariant on write (§1.1):
+ * scope='system' ⟺ owner_tenant_id IS NULL AND owner_workspace_id IS NULL.
+ */
+function assertScopeTriple(record) {
+  const scope = requireScope(record);
+  const hasTenant = record.owner_tenant_id !== null && record.owner_tenant_id !== undefined;
+  const hasWorkspace = record.owner_workspace_id !== null && record.owner_workspace_id !== undefined;
+
+  if (scope === SCOPE_SYSTEM && (hasTenant || hasWorkspace)) {
+    throw new ScopedRegistryError(
+      "[ScopedRegistry] Invalid scope triple - a 'system' row must have owner_tenant_id and owner_workspace_id NULL. "
+      + "Fix: clear both owner columns, or set scope='workspace'.",
+      { scope, owner_tenant_id: record.owner_tenant_id, owner_workspace_id: record.owner_workspace_id }
+    );
+  }
+  if (scope === SCOPE_WORKSPACE && !(hasTenant && hasWorkspace)) {
+    throw new ScopedRegistryError(
+      "[ScopedRegistry] Invalid scope triple - a 'workspace' row must have both owner_tenant_id and owner_workspace_id set. "
+      + "Fix: set both owner columns, or set scope='system'.",
+      { scope, owner_tenant_id: record.owner_tenant_id, owner_workspace_id: record.owner_workspace_id }
+    );
+  }
+  return record;
+}
+
+/**
+ * Write-time collision guard (§4.A).
+ *
+ * Called with the set of rows already visible to the writer. If the candidate's
+ * business natural key is taken, registration is refused — a workspace can
+ * never persist a definition that shadows a system one.
+ *
+ * @param {Array} existingVisible rows already visible to the caller
+ * @param {Object} candidate the row about to be written
+ * @param {Function} keyFn maps a row to its business natural key
+ */
+function assertUniqueInScope(existingVisible, candidate, keyFn) {
+  if (!Array.isArray(existingVisible)) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Invalid existing set - Expected an array of rows already visible to the writer. '
+      + 'Fix: load the caller-visible set before registering.',
+      { existingVisible }
+    );
+  }
+  if (typeof keyFn !== 'function') {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Missing key function - Expected a function mapping a row to its business natural key. '
+      + "Fix: pass e.g. (r) => `${r.code}/${r.version}`.",
+      { keyFn }
+    );
+  }
+
+  const candidateKey = keyFn(candidate);
+  const occupant = existingVisible.find((row) => keyFn(row) === candidateKey);
+
+  if (occupant) {
+    throw new ScopedRegistryError(
+      `[ScopedRegistry] Range occupied - "${candidateKey}" is already defined in scope "${occupant.scope}". `
+      + 'Fix: choose a different key, or reuse the existing definition.',
+      { key: candidateKey, occupiedByScope: occupant.scope }
+    );
+  }
+  return candidate;
+}
+
+module.exports = {
+  isVisible,
+  filterVisible,
+  pickVisibleOne,
+  sqlVisible,
+  sqlVisibleParams,
+  assertScopeTriple,
+  assertUniqueInScope,
+  ScopedRegistryError,
+  SCOPE_SYSTEM,
+  SCOPE_WORKSPACE
+};

package/src/postgresClient.js

@@ -1,112 +0,0 @@
-'use strict';
-
-/**
- * PostgreSQL Client Utilities
- * 
- * Provides helper functions for building PostgreSQL connection URLs.
- *
- * NO FALLBACKS: Topology must be explicit via ENV/config. This module must not
- * embed docker-compose hostnames or credentials.
- */
-
-/**
- * Build a PostgreSQL connection URL from environment.
- *
- * @param {Object} options - Options
- * @param {Object} [options.env=process.env] - Environment variables
- * @returns {string} PostgreSQL connection URL
- */
-function buildPostgresUrl(options = {}) {
-  const env = options.env || process.env || {};
-
-  const url = env.POSTGRES_URL && typeof env.POSTGRES_URL === 'string' ? env.POSTGRES_URL.trim() : '';
-  if (url) return url;
-
-  const host = env.POSTGRES_HOST && typeof env.POSTGRES_HOST === 'string' ? env.POSTGRES_HOST.trim() : '';
-  const port = env.POSTGRES_PORT && typeof env.POSTGRES_PORT === 'string' ? env.POSTGRES_PORT.trim() : '';
-  const user = env.POSTGRES_USER && typeof env.POSTGRES_USER === 'string' ? env.POSTGRES_USER.trim() : '';
-  const password = env.POSTGRES_PASSWORD && typeof env.POSTGRES_PASSWORD === 'string' ? env.POSTGRES_PASSWORD.trim() : '';
-  const database = env.POSTGRES_DB && typeof env.POSTGRES_DB === 'string' ? env.POSTGRES_DB.trim() : '';
-
-  const anyPartsProvided = Boolean(host || port || user || password || database);
-  if (!anyPartsProvided) {
-    throw new Error(
-      '[service-common][postgres] Missing configuration - POSTGRES_URL is required, or provide all: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB.'
-    );
-  }
-
-  const missing = [];
-  if (!host) missing.push('POSTGRES_HOST');
-  if (!port) missing.push('POSTGRES_PORT');
-  if (!user) missing.push('POSTGRES_USER');
-  if (!password) missing.push('POSTGRES_PASSWORD');
-  if (!database) missing.push('POSTGRES_DB');
-  if (missing.length > 0) {
-    throw new Error(
-      `[service-common][postgres] Missing configuration - Partial PostgreSQL config provided. Missing: ${missing.join(', ')}. ` +
-        'Fix: set POSTGRES_URL or set all POSTGRES_* parts.'
-    );
-  }
-
-  // Do not attempt to do smart encoding here; POSTGRES_URL is the recommended option.
-  return `postgres://${user}:${password}@${host}:${port}/${database}`;
-}
-
-/**
- * Create a PostgreSQL connection pool
- * 
- * @param {Object} options - Options
- * @param {Object} [options.env=process.env] - Environment variables
- * @param {Object} [options.defaults] - Default connection parameters
- * @param {Object} [options.poolConfig] - Additional pool configuration (max, idleTimeoutMillis, etc.)
- * @returns {Object} PostgreSQL Pool instance
- */
-function createPostgresPool(options = {}) {
-  const { Pool } = require('pg');
-  
-  const connectionString = buildPostgresUrl({
-    env: options.env
-  });
-
-  const poolConfig = {
-    connectionString,
-    max: options.poolConfig?.max || 10,
-    idleTimeoutMillis: options.poolConfig?.idleTimeoutMillis || 30000,
-    connectionTimeoutMillis: options.poolConfig?.connectionTimeoutMillis || 2000,
-    ...options.poolConfig
-  };
-
-  return new Pool(poolConfig);
-}
-
-/**
- * Connect to PostgreSQL and test connection
- * 
- * @param {Object} pool - PostgreSQL Pool instance
- * @param {Object} logger - Logger object with info/error methods
- * @returns {Promise<void>}
- */
-async function connectPostgres(pool, logger) {
-  if (!logger) {
-    throw new Error('[service-common][postgres] Missing dependency - logger is required (no console fallback).');
-  }
-  try {
-    await pool.query('SELECT NOW()');
-    if (logger && logger.info) {
-      logger.info('[PostgreSQL] Connected');
-    }
-    return true;
-  } catch (error) {
-    if (logger && logger.error) {
-      logger.error('[PostgreSQL] Connection failed:', error);
-    }
-    throw error;
-  }
-}
-
-module.exports = {
-  buildPostgresUrl,
-  createPostgresPool,
-  connectPostgres
-};
-