@hotmeshio/long-tail 0.11.0 → 0.12.0

package/build/api/domain.d.ts

@@ -0,0 +1,14 @@
+import type { DomainDictionary } from '../types';
+import type { LTApiResult } from '../types/sdk';
+/**
+ * The domain dictionary — read for everyone authenticated, replaced by admins.
+ * GET returns `{ doc, version, updated_at }` or `{ doc: null }` when no
+ * dictionary is registered. PUT validates references against the live
+ * registries: unknown roles/workflows → 422 with the offending names; facet
+ * warnings ride a successful response.
+ */
+export declare function getDomain(): Promise<LTApiResult>;
+export declare function putDomain(input: {
+    doc: DomainDictionary;
+    expected_version?: number;
+}): Promise<LTApiResult>;

package/build/api/domain.js

@@ -0,0 +1,76 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDomain = getDomain;
+exports.putDomain = putDomain;
+const domainService = __importStar(require("../services/domain"));
+/**
+ * The domain dictionary — read for everyone authenticated, replaced by admins.
+ * GET returns `{ doc, version, updated_at }` or `{ doc: null }` when no
+ * dictionary is registered. PUT validates references against the live
+ * registries: unknown roles/workflows → 422 with the offending names; facet
+ * warnings ride a successful response.
+ */
+async function getDomain() {
+    try {
+        const record = await domainService.getDomainDictionary();
+        return { status: 200, data: record ?? { doc: null } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function putDomain(input) {
+    try {
+        if (!input?.doc || typeof input.doc !== 'object') {
+            return { status: 400, error: 'body must be { doc, expected_version? }' };
+        }
+        const result = await domainService.putDomainDictionary(input.doc, input.expected_version);
+        if (!result.ok) {
+            if (result.reason === 'version_conflict') {
+                return { status: 409, error: 'version conflict — reload and retry' };
+            }
+            return {
+                status: 422,
+                error: 'dictionary references unknown roles/workflows',
+                data: { errors: result.errors, warnings: result.warnings },
+            };
+        }
+        return { status: 200, data: { version: result.version, warnings: result.warnings } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/escalations/cancel.js

@@ -36,6 +36,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.cancelSingleEscalation = cancelSingleEscalation;
 exports.bulkCancel = bulkCancel;
 const escalationService = __importStar(require("../../services/escalation"));
+const role_1 = require("../../services/role");
+const types_1 = require("../../services/role/types");
 const helpers_1 = require("./helpers");
 /**
  * Cancel a single escalation. The caller must hold global escalation access
@@ -60,7 +62,20 @@ async function cancelSingleEscalation(input, auth) {
         if (!cancelled) {
             return { status: 409, error: 'Escalation is not cancellable (already terminal)' };
         }
-        return { status: 200, data: { cancelled: true, escalationId: id } };
+        // Cancel semantics invert by role — surface the role's own on_cancel
+        // statement (lt_roles.properties, ROLE_PROPERTY_KEYS) so the caller reads
+        // the true effect. The bag is open: only a plain string qualifies.
+        const properties = await (0, role_1.getRoleProperties)(cancelled.role);
+        const onCancel = properties?.[types_1.ROLE_PROPERTY_KEYS.ON_CANCEL];
+        return {
+            status: 200,
+            data: {
+                cancelled: true,
+                escalationId: id,
+                role: cancelled.role,
+                ...(typeof onCancel === 'string' && onCancel ? { note: onCancel } : {}),
+            },
+        };
     }
     catch (err) {
         return { status: 500, error: err.message };

package/build/api/escalations/helpers.js

@@ -273,6 +273,9 @@ function publishBulkReassignEvents(beforeRows, targetRole) {
                 escalationId: row.id,
                 role,
                 status: 'pending',
+                // Bulk exception to the one-shape convention (see lib/events/escalation-wire.ts):
+                // these rows aren't held in full, so we publish the delta + `bulk: true`
+                // rather than fetch each row to project. Subscribers fetch by id for detail.
                 data: { from_role: row.role, to_role: targetRole, bulk: true },
             });
         }
@@ -303,6 +306,8 @@ function publishBulkClaimEvents(ids, assignedTo, knownRole) {
                 escalationId: id,
                 role: roleById.get(id) ?? '',
                 status: 'claimed',
+                // Bulk exception to the one-shape convention (see lib/events/escalation-wire.ts):
+                // delta + `bulk: true`, no per-row fetch. Subscribers fetch by id for detail.
                 data: { assigned_to: assignedTo, bulk: true },
             });
         }

package/build/lib/db/schemas/030_domain_dictionary.sql

@@ -0,0 +1,18 @@
+-- Migration 030: The domain dictionary
+--
+-- One row per deployment: the ontology that maps the operation's jargon
+-- ("printer", "reset", "kill the order") onto platform primitives (roles,
+-- queues, workflows, escalations, metadata facets). The doc holds only the
+-- SEMANTIC overlay the live registries can't express — terms, guidance,
+-- runbooks; structural facts (an entity's id facet, a role's title) are
+-- derived from lt_roles / lt_config_workflows at read time.
+--
+-- Seeded insert-if-absent from startConfig.mcp.domainDictionaryPath; edited
+-- live via PUT /api/domain. `version` backs optimistic concurrency on writes.
+
+CREATE TABLE IF NOT EXISTS lt_domain (
+  id         INT PRIMARY KEY DEFAULT 1 CHECK (id = 1),
+  doc        JSONB NOT NULL,
+  version    INT NOT NULL DEFAULT 1,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);

package/build/lib/events/escalation-wire.d.ts

@@ -0,0 +1,9 @@
+/** Scalar row columns that may ride the wire. Allowlist, not denylist. */
+export declare const WIRE_SAFE_COLUMNS: readonly ["id", "type", "subtype", "description", "status", "priority", "role", "assigned_to", "assigned_until", "workflow_id", "workflow_type", "task_queue", "origin_id", "task_id", "parent_id", "signal_key", "resolved_at", "claimed_at"];
+/** Project a committed escalation row to the wire-safe lifecycle shape. */
+export declare function projectEscalationRow(row: Record<string, any>): Record<string, any>;
+/**
+ * Build a lifecycle event's `data`: the row projection plus any verb provenance
+ * the row can't express. The single constructor every single-row publisher uses.
+ */
+export declare function escalationEventData(row: Record<string, any>, context?: Record<string, any>): Record<string, any>;

package/build/lib/events/escalation-wire.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WIRE_SAFE_COLUMNS = void 0;
+exports.projectEscalationRow = projectEscalationRow;
+exports.escalationEventData = escalationEventData;
+const types_1 = require("../../types");
+// ---------------------------------------------------------------------------
+// Escalation lifecycle event `data` — the ONE wire shape.
+//
+// CONVENTION (both publisher families converge here):
+//   A lifecycle event's `data` is the wire-safe PROJECTION of the escalation
+//   row — routing/classification scalars plus the metadata FACETS — and NEVER
+//   the heavy/sensitive JSON columns. A subscriber needing the full row fetches
+//   it by id through the authenticated read API; the pub channel is a
+//   notification surface, not a transport.
+//
+//   Dropped from the wire:
+//     • envelope / escalation_payload / resolver_payload — workflow envelope,
+//       initial payload, resolution content (e.g. mandate detail).
+//     • metadata.form_schema — a full JSON Schema some rows embed (tens of KB).
+//
+//   Kept: the scalar columns (an allowlist, so a column added later never
+//   leaks by default) and every other metadata facet (orderId, serialNumber,
+//   entity keys, schema_version, …) — the small categorical surface agent
+//   triggers filter/map on and the entity/faceted views route by.
+//
+//   Verb provenance the row can't express (cancel reason, released_by,
+//   resolved_by, reassignment from/to) rides as named fields ALONGSIDE the
+//   projection via `escalationEventData(row, context)`.
+//
+// EXCEPTION — bulk paths. `publishBulk*` operate on many rows they do not hold
+//   in full; projecting would cost one fetch per row. They publish the minimal
+//   delta plus `bulk: true` and let subscribers fetch by id. This is the only
+//   sanctioned divergence, and it is marked.
+//
+// Both the engine-mediated path (lib/events/system-events.ts) and the
+// service-mediated path (services/escalation/crud.ts) build `data` through the
+// helpers below — one definition, no drift.
+// ---------------------------------------------------------------------------
+/** Scalar row columns that may ride the wire. Allowlist, not denylist. */
+exports.WIRE_SAFE_COLUMNS = [
+    'id', 'type', 'subtype', 'description', 'status', 'priority',
+    'role', 'assigned_to', 'assigned_until',
+    'workflow_id', 'workflow_type', 'task_queue',
+    'origin_id', 'task_id', 'parent_id', 'signal_key',
+    'resolved_at', 'claimed_at',
+];
+/** Project a committed escalation row to the wire-safe lifecycle shape. */
+function projectEscalationRow(row) {
+    const out = {};
+    for (const key of exports.WIRE_SAFE_COLUMNS) {
+        if (row[key] !== undefined)
+            out[key] = row[key];
+    }
+    const metadata = row.metadata;
+    if (metadata && typeof metadata === 'object' && !Array.isArray(metadata)) {
+        // Keep the routing facets; drop only the heavy embedded resolver form def.
+        const { [types_1.ESCALATION_METADATA_KEYS.FORM_SCHEMA]: _omitFormSchema, ...facets } = metadata;
+        out.metadata = facets;
+    }
+    return out;
+}
+/**
+ * Build a lifecycle event's `data`: the row projection plus any verb provenance
+ * the row can't express. The single constructor every single-row publisher uses.
+ */
+function escalationEventData(row, context) {
+    return { ...projectEscalationRow(row), ...(context ?? {}) };
+}

package/build/lib/events/system-events.js

@@ -5,6 +5,9 @@ exports.mapSystemEvent = mapSystemEvent;
 exports.onSystemEvent = onSystemEvent;
 const index_1 = require("./index");
 const matching_1 = require("./matching");
+// The ONE wire shape — see escalation-wire.ts for the convention. The engine
+// path emits the projection with no extra verb context.
+const escalation_wire_1 = require("./escalation-wire");
 /** Verb → long-tail event status, matching the manual publishEscalationEvent convention. */
 const ESCALATION_STATUS_BY_VERB = {
     created: 'pending',
@@ -29,10 +32,11 @@ function mapSystemEvent(event) {
         const row = (event.data ?? {});
         const verb = segments[3] ?? '';
         // The SDK forms `system.escalation.{id}.{verb}`; long-tail's canonical
-        // subject carries the role as the organizing token. The committed row
-        // rides in `data`, so the role is lifted from it and the subject is
-        // rewritten to `system.escalation.{role}.{id}.{verb}` — the same shape
-        // publishEscalationEvent produces for the service-mediated path.
+        // subject carries the role as the organizing token. The SDK hands the
+        // committed row in `data`; routing fields are lifted from it and the subject
+        // is rewritten to `system.escalation.{role}.{id}.{verb}` — the same shape
+        // publishEscalationEvent produces for the service-mediated path. The row
+        // itself is projected (below) before it rides the wire.
         const role = row.role || undefined;
         return {
             type: `system.escalation.${(0, matching_1.sanitizeSubjectToken)(role)}.${segments[2]}.${verb}`,
@@ -48,7 +52,11 @@ function mapSystemEvent(event) {
             // not a column). Forward it so a consumer can tell a born-assigned,
             // system-directed hand-off (`claimed` with true) from an interactive claim.
             assignedAtCreation: event.assigned_at_creation,
-            data: row,
+            // Routing + facets only — never the heavy/sensitive JSON columns. This
+            // converges the engine-mediated path toward the thin shape the service
+            // path already publishes; a consumer needing the full row fetches it by
+            // id through the authenticated read API.
+            data: (0, escalation_wire_1.projectEscalationRow)(row),
             timestamp: event.ts,
         };
     }

package/build/lib/json-path/pick.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Dot-path projection over a JSON value — the token-efficiency primitive for
+ * large tool results (workflow exports, execution histories). `pickPaths`
+ * returns a new object holding only the requested paths, preserving their
+ * nesting; a path that does not resolve is silently omitted. Numeric segments
+ * index arrays ("timeline.0.activity").
+ */
+/** Resolve one dotted path against a value; undefined when any segment is missing. */
+export declare function resolveJsonPath(value: unknown, path: string): unknown;
+/**
+ * Project a value down to the given dot paths. Empty/absent `paths` returns
+ * the value unchanged (no projection requested).
+ */
+export declare function pickPaths<T>(value: T, paths?: string[]): T | Record<string, any>;

package/build/lib/json-path/pick.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Dot-path projection over a JSON value — the token-efficiency primitive for
+ * large tool results (workflow exports, execution histories). `pickPaths`
+ * returns a new object holding only the requested paths, preserving their
+ * nesting; a path that does not resolve is silently omitted. Numeric segments
+ * index arrays ("timeline.0.activity").
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveJsonPath = resolveJsonPath;
+exports.pickPaths = pickPaths;
+/** Resolve one dotted path against a value; undefined when any segment is missing. */
+function resolveJsonPath(value, path) {
+    const segments = path.trim().split('.').filter((s) => s.length > 0);
+    let current = value;
+    for (const segment of segments) {
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/** Set one dotted path on a target, creating intermediate objects/arrays. */
+function setJsonPath(target, path, value) {
+    const segments = path.trim().split('.').filter((s) => s.length > 0);
+    let current = target;
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        const segment = segments[i];
+        if (current[segment] == null || typeof current[segment] !== 'object') {
+            // A numeric NEXT segment means this level is an array.
+            current[segment] = /^\d+$/.test(segments[i + 1]) ? [] : {};
+        }
+        current = current[segment];
+    }
+    current[segments[segments.length - 1]] = value;
+}
+/**
+ * Project a value down to the given dot paths. Empty/absent `paths` returns
+ * the value unchanged (no projection requested).
+ */
+function pickPaths(value, paths) {
+    if (!paths || paths.length === 0)
+        return value;
+    const out = {};
+    for (const path of paths) {
+        const resolved = resolveJsonPath(value, path);
+        if (resolved !== undefined)
+            setJsonPath(out, path, resolved);
+    }
+    return out;
+}

package/build/routes/domain.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;

package/build/routes/domain.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const auth_1 = require("../modules/auth");
+const api = __importStar(require("../api/domain"));
+const router = (0, express_1.Router)();
+/**
+ * GET /api/domain
+ * The deployment's domain dictionary: `{ doc, version, updated_at }`, or
+ * `{ doc: null }` when none is registered.
+ */
+router.get('/', async (_req, res) => {
+    const result = await api.getDomain();
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * PUT /api/domain
+ * Replace the dictionary. Requires admin.
+ * Body: { doc: DomainDictionary, expected_version?: number }
+ * 422 carries { error, errors[], warnings[] }; 409 on version conflict.
+ */
+router.put('/', auth_1.requireAdmin, async (req, res) => {
+    const result = await api.putDomain(req.body ?? {});
+    const body = result.status < 300
+        ? result.data
+        : { error: result.error, ...(result.data ?? {}) };
+    res.status(result.status).json(body);
+});
+exports.default = router;

package/build/routes/index.js

@@ -37,6 +37,7 @@ const capabilities_1 = __importDefault(require("./capabilities"));
 const topics_1 = __importDefault(require("./topics"));
 const nats_credentials_1 = __importDefault(require("./nats-credentials"));
 const scan_codes_1 = __importDefault(require("./scan-codes"));
+const domain_1 = __importDefault(require("./domain"));
 const router = (0, express_1.Router)();
 // Public routes (no auth required — they handle their own auth)
 router.use('/auth', auth_2.default);
@@ -74,6 +75,7 @@ router.use('/agents', agents_1.default);
 router.use('/capabilities', capabilities_1.default);
 router.use('/topics', topics_1.default);
 router.use('/scan-codes', scan_codes_1.default);
+router.use('/domain', domain_1.default);
 const overview_1 = __importDefault(require("./overview"));
 router.use('/overview', overview_1.default);
 const diagnostics_1 = __importDefault(require("./diagnostics"));

package/build/routes/mcp-endpoint.js

@@ -39,7 +39,10 @@ router.post('/', auth_1.requireAuth, async (req, res) => {
         await transport.handleRequest(req, res, req.body);
     }
     catch (err) {
-        logger_1.loggerRegistry.error(`[lt-mcp:endpoint] error: ${err.message}`);
+        // Log the full stack, not just the message — otherwise a 500 here is
+        // undiagnosable from the deployment logs (the caller only sees a generic
+        // "Internal server error").
+        logger_1.loggerRegistry.error(`[lt-mcp:endpoint] error: ${err?.stack || err?.message || err}`);
         if (!res.headersSent) {
             res.status(500).json({
                 jsonrpc: '2.0',

package/build/services/domain/index.d.ts

@@ -0,0 +1,4 @@
+export { getDomainDictionary, getDomainIndex, domainCache, type DomainRecord } from './read';
+export { putDomainDictionary, snapshotRegistries, type PutDictionaryResult } from './write';
+export { seedDomainDictionary } from './seed';
+export { validateDictionary, type RegistrySnapshot, type DictionaryValidation } from './validate';

package/build/services/domain/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDictionary = exports.seedDomainDictionary = exports.snapshotRegistries = exports.putDomainDictionary = exports.domainCache = exports.getDomainIndex = exports.getDomainDictionary = void 0;
+var read_1 = require("./read");
+Object.defineProperty(exports, "getDomainDictionary", { enumerable: true, get: function () { return read_1.getDomainDictionary; } });
+Object.defineProperty(exports, "getDomainIndex", { enumerable: true, get: function () { return read_1.getDomainIndex; } });
+Object.defineProperty(exports, "domainCache", { enumerable: true, get: function () { return read_1.domainCache; } });
+var write_1 = require("./write");
+Object.defineProperty(exports, "putDomainDictionary", { enumerable: true, get: function () { return write_1.putDomainDictionary; } });
+Object.defineProperty(exports, "snapshotRegistries", { enumerable: true, get: function () { return write_1.snapshotRegistries; } });
+var seed_1 = require("./seed");
+Object.defineProperty(exports, "seedDomainDictionary", { enumerable: true, get: function () { return seed_1.seedDomainDictionary; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "validateDictionary", { enumerable: true, get: function () { return validate_1.validateDictionary; } });

package/build/services/domain/read.d.ts

@@ -0,0 +1,21 @@
+import type { DomainDictionary, DomainIndex } from '../../types';
+export interface DomainRecord {
+    doc: DomainDictionary;
+    version: number;
+    updated_at: string;
+}
+declare class DomainCache {
+    private record;
+    private loadedAt;
+    private loadPromise;
+    get(): Promise<DomainRecord | null>;
+    private load;
+    /** Force reload on next access. Call after writes. */
+    invalidate(): void;
+}
+export declare const domainCache: DomainCache;
+/** The dictionary, or null when none is registered (or the read failed). */
+export declare function getDomainDictionary(): Promise<DomainRecord | null>;
+/** Compact names-only index for the MCP `instructions` string. */
+export declare function getDomainIndex(): Promise<DomainIndex | null>;
+export {};

package/build/services/domain/read.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.domainCache = void 0;
+exports.getDomainDictionary = getDomainDictionary;
+exports.getDomainIndex = getDomainIndex;
+const db_1 = require("../../lib/db");
+const logger_1 = require("../../lib/logger");
+const defaults_1 = require("../../modules/defaults");
+const sql_1 = require("./sql");
+// ---------------------------------------------------------------------------
+// Read-through TTL cache (same shape as modules/ltconfig.ts): the dictionary
+// rides the MCP `instructions` of every /mcp request, so reads must be
+// in-memory between refreshes and MUST fail soft — a dead DB yields null
+// (no instructions, "no dictionary registered" tool response), never a
+// rejected request. Writes call invalidate(); other containers converge
+// within one TTL window.
+// ---------------------------------------------------------------------------
+class DomainCache {
+    constructor() {
+        this.record = null;
+        this.loadedAt = 0;
+        this.loadPromise = null;
+    }
+    async get() {
+        if (this.loadedAt && Date.now() - this.loadedAt < defaults_1.CONFIG_CACHE_TTL_MS) {
+            return this.record;
+        }
+        if (!this.loadPromise) {
+            this.loadPromise = this.load().finally(() => {
+                this.loadPromise = null;
+            });
+        }
+        return this.loadPromise;
+    }
+    async load() {
+        try {
+            const { rows } = await (0, db_1.getPool)().query(sql_1.GET_DOMAIN);
+            this.record = rows[0]
+                ? { doc: rows[0].doc, version: rows[0].version, updated_at: rows[0].updated_at }
+                : null;
+        }
+        catch (err) {
+            logger_1.loggerRegistry.warn(`[lt-domain] dictionary read failed: ${err.message}`);
+            this.record = null;
+        }
+        this.loadedAt = Date.now();
+        return this.record;
+    }
+    /** Force reload on next access. Call after writes. */
+    invalidate() {
+        this.record = null;
+        this.loadedAt = 0;
+        this.loadPromise = null;
+    }
+}
+exports.domainCache = new DomainCache();
+/** The dictionary, or null when none is registered (or the read failed). */
+async function getDomainDictionary() {
+    return exports.domainCache.get();
+}
+/** Compact names-only index for the MCP `instructions` string. */
+async function getDomainIndex() {
+    const record = await exports.domainCache.get();
+    if (!record)
+        return null;
+    const { doc } = record;
+    const terms = {};
+    for (const t of doc.terms ?? []) {
+        (terms[t.kind] ??= []).push(t.term);
+    }
+    return {
+        name: doc.name,
+        version: doc.version,
+        overview: doc.overview,
+        terms,
+        runbooks: (doc.runbooks ?? []).map((r) => r.name),
+    };
+}

package/build/services/domain/seed.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Seed the domain dictionary from a host-declared JSON file — the same
+ * insert-if-absent + drift-log contract as seedWorkflowConfig/seedMcpServer.
+ * The DB row is runtime truth: an existing row is never overwritten; a
+ * name/version mismatch against the file logs one drift warning.
+ *
+ * WARN-ONLY validation: hosts commonly seed roles after long-tail boots, so
+ * unknown references log warnings here (the PUT path enforces them hard).
+ * Never throws — a missing or malformed file must not brick boot.
+ */
+export declare function seedDomainDictionary(dictionaryPath: string): Promise<void>;

package/build/services/domain/seed.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seedDomainDictionary = seedDomainDictionary;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const db_1 = require("../../lib/db");
+const logger_1 = require("../../lib/logger");
+const validate_1 = require("./validate");
+const write_1 = require("./write");
+const read_1 = require("./read");
+const sql_1 = require("./sql");
+/**
+ * Seed the domain dictionary from a host-declared JSON file — the same
+ * insert-if-absent + drift-log contract as seedWorkflowConfig/seedMcpServer.
+ * The DB row is runtime truth: an existing row is never overwritten; a
+ * name/version mismatch against the file logs one drift warning.
+ *
+ * WARN-ONLY validation: hosts commonly seed roles after long-tail boots, so
+ * unknown references log warnings here (the PUT path enforces them hard).
+ * Never throws — a missing or malformed file must not brick boot.
+ */
+async function seedDomainDictionary(dictionaryPath) {
+    const resolved = path_1.default.isAbsolute(dictionaryPath)
+        ? dictionaryPath
+        : path_1.default.join(process.cwd(), dictionaryPath);
+    let dictionary;
+    try {
+        if (!(0, fs_1.existsSync)(resolved)) {
+            logger_1.loggerRegistry.warn(`[lt-domain] domainDictionaryPath not found: ${resolved}`);
+            return;
+        }
+        dictionary = JSON.parse((0, fs_1.readFileSync)(resolved, 'utf-8'));
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[lt-domain] dictionary file unreadable (${resolved}): ${err.message}`);
+        return;
+    }
+    try {
+        const registry = await (0, write_1.snapshotRegistries)();
+        const { errors, warnings, dictionary: derived } = (0, validate_1.validateDictionary)(dictionary, registry);
+        for (const note of [...errors, ...warnings]) {
+            logger_1.loggerRegistry.warn(`[lt-domain] dictionary seed: ${note}`);
+        }
+        const { rows } = await (0, db_1.getPool)().query(sql_1.SEED_DOMAIN, [JSON.stringify(derived)]);
+        if (rows.length > 0) {
+            read_1.domainCache.invalidate();
+            logger_1.loggerRegistry.info(`[lt-domain] dictionary seeded: ${derived.name} v${derived.version} ` +
+                `(${derived.terms?.length ?? 0} terms, ${derived.runbooks?.length ?? 0} runbooks)`);
+            return;
+        }
+        // Row already existed — drift check on name/version only (no deep diff).
+        const existing = await (0, db_1.getPool)().query(sql_1.GET_DOMAIN);
+        const doc = existing.rows[0]?.doc;
+        if (doc && (doc.name !== dictionary.name || doc.version !== dictionary.version)) {
+            logger_1.loggerRegistry.warn(`[lt-domain] dictionary drift: DB holds "${doc.name}" v${doc.version}, ` +
+                `file declares "${dictionary.name}" v${dictionary.version} — DB is runtime truth`);
+        }
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[lt-domain] dictionary seed failed: ${err.message}`);
+    }
+}