@hotmeshio/long-tail 0.11.1 → 0.12.0

package/build/services/domain/sql.js

@@ -0,0 +1,29 @@
+"use strict";
+// ─── Domain dictionary queries ──────────────────────────────────────────────
+// One row per deployment (lt_domain, id=1). Reads are whole-doc; writes are
+// whole-doc with optimistic concurrency on `version`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEED_DOMAIN = exports.UPSERT_DOMAIN = exports.GET_DOMAIN = void 0;
+exports.GET_DOMAIN = `
+  SELECT doc, version, updated_at FROM lt_domain WHERE id = 1`;
+/**
+ * Upsert the dictionary in ONE statement. When the caller supplies an
+ * expected version ($2 non-null), the update applies only if the stored
+ * version matches — zero rows back means a concurrent writer won (409).
+ * A null $2 is last-write-wins. Fresh inserts always succeed at version 1.
+ */
+exports.UPSERT_DOMAIN = `
+  INSERT INTO lt_domain (id, doc, version, updated_at)
+  VALUES (1, $1::jsonb, 1, NOW())
+  ON CONFLICT (id) DO UPDATE
+    SET doc = EXCLUDED.doc,
+        version = lt_domain.version + 1,
+        updated_at = NOW()
+    WHERE $2::int IS NULL OR lt_domain.version = $2::int
+  RETURNING version`;
+/** Seed: first writer wins; an existing row is left untouched. */
+exports.SEED_DOMAIN = `
+  INSERT INTO lt_domain (id, doc, version, updated_at)
+  VALUES (1, $1::jsonb, 1, NOW())
+  ON CONFLICT (id) DO NOTHING
+  RETURNING version`;

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

@@ -0,0 +1,29 @@
+import type { DomainDictionary } from '../../types';
+/**
+ * Reference validation for the domain dictionary — pure, registry-injected.
+ *
+ * Roles and workflows are HARD registries: an unknown reference is an error
+ * (the PUT path rejects with 422; the boot seed downgrades errors to warnings
+ * because hosts may seed roles after long-tail boots). Facet keys are
+ * DATA-derived — a legitimate facet may simply have no rows yet — so unknown
+ * facets are always warnings. Entity terms without an explicit idFacet get one
+ * DERIVED from their role's entity_facet.
+ */
+/** The minimal live-registry snapshot the validator compares against. */
+export interface RegistrySnapshot {
+    roles: Array<{
+        role: string;
+        entity_facet: string | null;
+    }>;
+    workflowTypes: string[];
+    facetKeys: string[];
+}
+export interface DictionaryValidation {
+    /** Unknown role/workflow references — reject on write, warn at seed. */
+    errors: string[];
+    /** Unknown facet keys and other non-fatal notes. */
+    warnings: string[];
+    /** The dictionary with derived fields filled (entity idFacet). */
+    dictionary: DomainDictionary;
+}
+export declare function validateDictionary(dictionary: DomainDictionary, registry: RegistrySnapshot): DictionaryValidation;

package/build/services/domain/validate.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDictionary = validateDictionary;
+const KINDS = new Set(['entity', 'role', 'workflow', 'facet', 'action', 'rule']);
+function rolesOf(term) {
+    const out = [];
+    if (term.maps_to?.role)
+        out.push(term.maps_to.role);
+    if (term.maps_to?.roles)
+        out.push(...term.maps_to.roles);
+    return out;
+}
+function validateDictionary(dictionary, registry) {
+    const errors = [];
+    const warnings = [];
+    const knownRoles = new Map(registry.roles.map((r) => [r.role, r]));
+    const knownWorkflows = new Set(registry.workflowTypes);
+    const knownFacets = new Set(registry.facetKeys);
+    if (!dictionary.name || !dictionary.overview) {
+        errors.push('dictionary requires name and overview');
+    }
+    const terms = (dictionary.terms ?? []).map((t) => {
+        const at = `terms["${t.term}"]`;
+        if (!KINDS.has(t.kind)) {
+            errors.push(`${at}: unknown kind "${t.kind}"`);
+        }
+        for (const role of rolesOf(t)) {
+            if (!knownRoles.has(role)) {
+                errors.push(`${at}: role "${role}" is not a live role`);
+            }
+        }
+        if (t.maps_to?.workflow && !knownWorkflows.has(t.maps_to.workflow)) {
+            errors.push(`${at}: workflow "${t.maps_to.workflow}" is not a registered workflow`);
+        }
+        if (t.maps_to?.facet && !knownFacets.has(t.maps_to.facet)) {
+            warnings.push(`${at}: facet "${t.maps_to.facet}" is not (yet) a known metadata facet`);
+        }
+        // Derive the entity's id facet from its role's entity_facet when omitted.
+        if (t.kind === 'entity' && !t.idFacet) {
+            const derived = rolesOf(t)
+                .map((role) => knownRoles.get(role)?.entity_facet)
+                .find((f) => !!f);
+            if (derived)
+                return { ...t, idFacet: derived };
+            warnings.push(`${at}: entity has no idFacet and none derivable from its roles`);
+        }
+        return t;
+    });
+    return { errors, warnings, dictionary: { ...dictionary, terms } };
+}

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

@@ -0,0 +1,23 @@
+import type { DomainDictionary } from '../../types';
+import { type RegistrySnapshot } from './validate';
+/** Snapshot the live registries the validator compares against. */
+export declare function snapshotRegistries(): Promise<RegistrySnapshot>;
+export type PutDictionaryResult = {
+    ok: true;
+    version: number;
+    warnings: string[];
+} | {
+    ok: false;
+    reason: 'invalid';
+    errors: string[];
+    warnings: string[];
+} | {
+    ok: false;
+    reason: 'version_conflict';
+};
+/**
+ * Replace the dictionary (whole-doc PUT). Unknown role/workflow references
+ * reject; facet warnings return alongside success. `expectedVersion` arms
+ * optimistic concurrency — omit for last-write-wins.
+ */
+export declare function putDomainDictionary(dictionary: DomainDictionary, expectedVersion?: number): Promise<PutDictionaryResult>;

package/build/services/domain/write.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotRegistries = snapshotRegistries;
+exports.putDomainDictionary = putDomainDictionary;
+const db_1 = require("../../lib/db");
+const role_1 = require("../role");
+const config_1 = require("../config");
+const queries_1 = require("../escalation/queries");
+const validate_1 = require("./validate");
+const read_1 = require("./read");
+const sql_1 = require("./sql");
+/** Snapshot the live registries the validator compares against. */
+async function snapshotRegistries() {
+    const [roles, configs, facetKeys] = await Promise.all([
+        (0, role_1.listRolesWithDetails)(),
+        (0, config_1.listWorkflowConfigs)(),
+        (0, queries_1.listFacetKeys)({ global: true }),
+    ]);
+    return {
+        roles: roles.map((r) => ({ role: r.role, entity_facet: r.entity_facet })),
+        workflowTypes: configs.map((c) => c.workflow_type),
+        facetKeys,
+    };
+}
+/**
+ * Replace the dictionary (whole-doc PUT). Unknown role/workflow references
+ * reject; facet warnings return alongside success. `expectedVersion` arms
+ * optimistic concurrency — omit for last-write-wins.
+ */
+async function putDomainDictionary(dictionary, expectedVersion) {
+    const registry = await snapshotRegistries();
+    const { errors, warnings, dictionary: derived } = (0, validate_1.validateDictionary)(dictionary, registry);
+    if (errors.length)
+        return { ok: false, reason: 'invalid', errors, warnings };
+    const { rows } = await (0, db_1.getPool)().query(sql_1.UPSERT_DOMAIN, [
+        JSON.stringify(derived),
+        expectedVersion ?? null,
+    ]);
+    if (rows.length === 0)
+        return { ok: false, reason: 'version_conflict' };
+    read_1.domainCache.invalidate();
+    return { ok: true, version: rows[0].version, warnings };
+}

package/build/services/escalation/crud.js

@@ -26,6 +26,7 @@ exports.claimByMetadata = claimByMetadata;
 exports.resolveByMetadataAtomic = resolveByMetadataAtomic;
 const db_1 = require("../../lib/db");
 const publish_1 = require("../../lib/events/publish");
+const escalation_wire_1 = require("../../lib/events/escalation-wire");
 const client_1 = require("./client");
 const queries_1 = require("./queries");
 const map_1 = require("./map");
@@ -76,7 +77,7 @@ async function createEscalation(input) {
         escalationId: escalation.id,
         role: escalation.role,
         status: 'pending',
-        data: { type: input.type, role: input.role },
+        data: (0, escalation_wire_1.escalationEventData)(escalation),
     });
     return escalation;
 }
@@ -100,7 +101,7 @@ async function claimEscalation(id, userId, durationMinutes = 30) {
         escalationId: escalation.id,
         role: escalation.role,
         status: 'claimed',
-        data: { assigned_to: userId },
+        data: (0, escalation_wire_1.escalationEventData)(escalation),
     });
     return { escalation, isExtension: result.isExtension };
 }
@@ -141,7 +142,7 @@ async function resolveEscalation(id, resolverPayload, metadata, assertClaim, res
         escalationId: escalation.id,
         role: escalation.role,
         status: 'resolved',
-        data: {},
+        data: (0, escalation_wire_1.escalationEventData)(escalation),
     });
     return escalation;
 }
@@ -175,7 +176,7 @@ async function resolveEscalationsByIds(ids, resolverPayload, metadata) {
             escalationId: escalation.id,
             role: escalation.role,
             status: 'resolved',
-            data: {},
+            data: (0, escalation_wire_1.escalationEventData)(escalation),
         });
     }
     return records;
@@ -215,7 +216,7 @@ async function resolveEscalationsAllOrNone(items, metadata, assertAssignee, reso
             escalationId: escalation.id,
             role: escalation.role,
             status: 'resolved',
-            data: {},
+            data: (0, escalation_wire_1.escalationEventData)(escalation),
         });
     }
     return { ok: true, escalations: records };
@@ -283,7 +284,7 @@ async function cancelEscalation(id) {
         escalationId: cancelled.id,
         role: cancelled.role,
         status: 'cancelled',
-        data: { reason: 'workflow_terminated' },
+        data: (0, escalation_wire_1.escalationEventData)(cancelled, { reason: 'workflow_terminated' }),
     });
     return cancelled;
 }
@@ -343,7 +344,7 @@ async function releaseEscalation(id, userId) {
         escalationId: released.id,
         role: released.role,
         status: 'released',
-        data: { released_by: userId },
+        data: (0, escalation_wire_1.escalationEventData)(released, { released_by: userId }),
     });
     return released;
 }
@@ -391,7 +392,7 @@ async function escalateToRole(id, targetRole) {
             escalationId: escalation.id,
             role,
             status: 'pending',
-            data: { from_role: fromRole, to_role: escalation.role },
+            data: (0, escalation_wire_1.escalationEventData)(escalation, { from_role: fromRole, to_role: escalation.role }),
         });
     }
     return escalation;
@@ -433,11 +434,14 @@ async function getEscalationsByWorkflowId(workflowId) {
 async function cancelEscalationsByWorkflowId(workflowId) {
     await (0, client_1.ensureEscalationCompatView)();
     const pool = (0, db_1.getPool)();
+    // RETURNING * so each cancelled row publishes the SAME wire projection as the
+    // single-row cancel path (escalationEventData strips the heavy JSON columns);
+    // no extra query — the UPDATE already returns the rows.
     const { rows } = await pool.query(`UPDATE public.hmsh_escalations
         SET status = 'cancelled', updated_at = NOW()
       WHERE workflow_id = $1
         AND status = 'pending'
-      RETURNING id, workflow_id, workflow_type, task_queue, role`, [workflowId]);
+      RETURNING *`, [workflowId]);
     for (const row of rows) {
         publishEscalationChange({
             type: 'escalation.cancelled',
@@ -448,7 +452,7 @@ async function cancelEscalationsByWorkflowId(workflowId) {
             escalationId: row.id,
             role: row.role || '',
             status: 'cancelled',
-            data: { reason: 'workflow_terminated' },
+            data: (0, escalation_wire_1.escalationEventData)(row, { reason: 'workflow_terminated' }),
         });
     }
     return rows.length;
@@ -536,7 +540,7 @@ async function claimByMetadata(key, value, userId, durationMinutes = 30, metadat
         escalationId: escalation.id,
         role: escalation.role,
         status: 'claimed',
-        data: { assigned_to: userId },
+        data: (0, escalation_wire_1.escalationEventData)(escalation),
     });
     return {
         escalation,
@@ -597,7 +601,7 @@ async function resolveByMetadataAtomic(key, value, userId, resolverPayload, meta
             escalationId: escalation.id,
             role: escalation.role,
             status: 'resolved',
-            data: { resolved_by: userId },
+            data: (0, escalation_wire_1.escalationEventData)(escalation, { resolved_by: userId }),
         });
         return { outcome: 'resolved', escalation };
     }

package/build/services/mcp/db-server/schemas.d.ts

@@ -34,8 +34,8 @@ export declare const findEscalationsSchema: z.ZodObject<{
     role?: string | undefined;
     status?: "pending" | "resolved" | undefined;
     type?: string | undefined;
-    limit?: number | undefined;
     priority?: number | undefined;
+    limit?: number | undefined;
 }>;
 export declare const getProcessSummarySchema: z.ZodObject<{
     workflow_type: z.ZodOptional<z.ZodString>;

package/build/services/mcp/external-server.js

@@ -11,6 +11,36 @@ exports.createUnifiedMcpServer = createUnifiedMcpServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const logger_1 = require("../../lib/logger");
 const system_1 = require("../../system");
+const domain_1 = require("../domain");
+/**
+ * The MCP `instructions` string. When a domain dictionary is registered,
+ * carries its overview + a compact names-only index and points the agent at
+ * `get_domain_context` for detail. The full ontology stays behind that tool —
+ * only this lightweight index rides every session's context. The dictionary
+ * read is TTL-cached and fails soft (null → no instructions).
+ */
+async function buildInstructions() {
+    const index = await (0, domain_1.getDomainIndex)();
+    if (!index)
+        return undefined;
+    const kindLines = Object.entries(index.terms)
+        .filter(([, names]) => names && names.length)
+        .map(([kind, names]) => `${kind}: ${names.join(', ')}`);
+    const lines = [
+        `# ${index.name} (v${index.version})`,
+        '',
+        index.overview,
+        '',
+        '## Deployment dictionary',
+        ...kindLines,
+        index.runbooks.length ? `runbooks: ${index.runbooks.join(', ')}` : '',
+        '',
+        'Call `get_domain_context` (topic + optional name) before acting on anything ' +
+            'whose meaning is deployment-specific — cancel/terminate semantics invert by ' +
+            'role, and an entity\'s id facet + roles come from its entry.',
+    ];
+    return lines.filter((l) => l !== '').join('\n');
+}
 // ── Shipped server allowlist ─────────────────────────────────────────────────
 // Only these servers are exposed via the /mcp endpoint.
 // Example servers (playwright, gmail, image-tools) are excluded.
@@ -89,7 +119,7 @@ function isToolAllowed(toolName, serverName, exposure, callerScopes) {
  * the McpServer wrapper and tool registrations are fresh (pure in-memory).
  */
 async function createUnifiedMcpServer(exposure, callerScopes) {
-    const unified = new mcp_js_1.McpServer({ name: 'long-tail', version: '1.0.0' });
+    const unified = new mcp_js_1.McpServer({ name: 'long-tail', version: '1.0.0' }, { instructions: await buildInstructions() });
     const registered = new Set();
     for (const [name] of Object.entries(system_1.builtinMcpServerFactories)) {
         if (!isServerAllowed(name, exposure))

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

@@ -82,6 +82,8 @@ export declare function getRoleFormSchema(role: string): Promise<Record<string,
  * to surface expected keys before any data exists.
  */
 export declare function getRoleMetadataSchema(role: string): Promise<Record<string, any> | null>;
+/** The role's `properties` bag (incl. the reserved ROLE_PROPERTY_KEYS). One PK read. */
+export declare function getRoleProperties(role: string): Promise<Record<string, any> | null>;
 /**
  * Delete a role. Returns an error message if the role is referenced.
  */

package/build/services/role/index.js

@@ -17,6 +17,7 @@ exports.listRoleListSchemaVersions = listRoleListSchemaVersions;
 exports.getRoleListSchema = getRoleListSchema;
 exports.getRoleFormSchema = getRoleFormSchema;
 exports.getRoleMetadataSchema = getRoleMetadataSchema;
+exports.getRoleProperties = getRoleProperties;
 exports.deleteRole = deleteRole;
 const db_1 = require("../../lib/db");
 const user_1 = require("../user");
@@ -238,6 +239,12 @@ async function getRoleMetadataSchema(role) {
     const { rows } = await pool.query(sql_1.GET_ROLE_METADATA_SCHEMA, [role]);
     return rows[0]?.metadata_schema ?? null;
 }
+/** The role's `properties` bag (incl. the reserved ROLE_PROPERTY_KEYS). One PK read. */
+async function getRoleProperties(role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLE_PROPERTIES, [role]);
+    return rows[0]?.properties ?? null;
+}
 /**
  * Delete a role. Returns an error message if the role is referenced.
  */

package/build/services/role/sql.d.ts

@@ -68,6 +68,7 @@ export declare const GET_ROLE_FORM_SCHEMA = "\n  SELECT form_schema FROM lt_role
  */
 export declare const LIST_ENFORCING_ROLES = "\n  SELECT role FROM lt_roles WHERE enforce_schema";
 export declare const GET_ROLE_METADATA_SCHEMA = "\n  SELECT metadata_schema FROM lt_roles WHERE role = $1";
+export declare const GET_ROLE_PROPERTIES = "\n  SELECT properties FROM lt_roles WHERE role = $1";
 export declare const GET_ROLE_UPSTREAMS = "\n  SELECT upstream_role FROM lt_role_upstreams WHERE role = $1 ORDER BY upstream_role";
 export declare const LIST_ROLE_SCHEMA_VERSIONS = "\n  SELECT\n    s.version,\n    s.form_schema IS NOT NULL     AS has_form_schema,\n    s.metadata_schema IS NOT NULL AS has_metadata_schema,\n    s.change_summary,\n    s.created_at,\n    s.version = r.current_schema_version AS is_current\n  FROM lt_role_schemas s\n  JOIN lt_roles r ON r.role = s.role\n  WHERE s.role = $1\n  ORDER BY s.version DESC";
 export declare const GET_ROLE_SCHEMA_VERSION = "\n  SELECT s.role, s.version, s.form_schema, s.metadata_schema,\n         s.change_summary, s.created_at, r.current_schema_version AS latest_version\n  FROM lt_role_schemas s\n  JOIN lt_roles r ON r.role = s.role\n  WHERE s.role = $1 AND s.version = $2";

package/build/services/role/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Escalation chain queries ───────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_LIST_SCHEMA_CURRENT = exports.GET_ROLE_LIST_SCHEMA_VERSION = exports.LIST_ROLE_LIST_SCHEMA_VERSIONS = exports.GET_ROLE_SCHEMA_CURRENT = exports.GET_ROLE_SCHEMA_VERSION = exports.LIST_ROLE_SCHEMA_VERSIONS = exports.GET_ROLE_UPSTREAMS = exports.GET_ROLE_METADATA_SCHEMA = exports.LIST_ENFORCING_ROLES = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
+exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_LIST_SCHEMA_CURRENT = exports.GET_ROLE_LIST_SCHEMA_VERSION = exports.LIST_ROLE_LIST_SCHEMA_VERSIONS = exports.GET_ROLE_SCHEMA_CURRENT = exports.GET_ROLE_SCHEMA_VERSION = exports.LIST_ROLE_SCHEMA_VERSIONS = exports.GET_ROLE_UPSTREAMS = exports.GET_ROLE_PROPERTIES = exports.GET_ROLE_METADATA_SCHEMA = exports.LIST_ENFORCING_ROLES = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
 exports.GET_ESCALATION_TARGETS = `
   SELECT target_role
   FROM lt_config_role_escalations
@@ -168,6 +168,8 @@ exports.LIST_ENFORCING_ROLES = `
   SELECT role FROM lt_roles WHERE enforce_schema`;
 exports.GET_ROLE_METADATA_SCHEMA = `
   SELECT metadata_schema FROM lt_roles WHERE role = $1`;
+exports.GET_ROLE_PROPERTIES = `
+  SELECT properties FROM lt_roles WHERE role = $1`;
 exports.GET_ROLE_UPSTREAMS = `
   SELECT upstream_role FROM lt_role_upstreams WHERE role = $1 ORDER BY upstream_role`;
 // ─── Versioned role schemas ─────────────────────────────────────────────────

package/build/services/role/types.d.ts

@@ -3,6 +3,21 @@ export interface EscalationChain {
     source_role: string;
     target_role: string;
 }
+/**
+ * Reserved keys inside `lt_roles.properties` — the role's verb semantics for
+ * the domain dictionary. Everything else in the bag is user-owned. Values are
+ * plain strings; readers type-guard (the bag is open, PATCH can write anything).
+ *
+ *  - ON_CANCEL: what cancel MEANS for this row class, imperative
+ *    (e.g. "reset — the dispatcher re-mints the attempt").
+ *  - ON_TIMEOUT: expiry semantics for this row class.
+ *  - WORKED_BY: who works this queue ("humans at the dashboard" | "machines" | "both").
+ */
+export declare const ROLE_PROPERTY_KEYS: {
+    readonly ON_CANCEL: "on_cancel";
+    readonly ON_TIMEOUT: "on_timeout";
+    readonly WORKED_BY: "worked_by";
+};
 export interface RoleDetail {
     role: string;
     title: string | null;
@@ -17,7 +32,8 @@ export interface RoleDetail {
      * and creation-time metadata validation.
      */
     metadata_schema: Record<string, any> | null;
-    /** Free-form user-owned bag. No reserved keys — use for icons, colors, tags, etc. */
+    /** Free-form user-owned bag (icons, colors, tags, …), plus the reserved
+     *  domain-semantics keys in ROLE_PROPERTY_KEYS (on_cancel, on_timeout, worked_by). */
     properties: Record<string, any>;
     ops_visible: boolean;
     /**

package/build/services/role/types.js

@@ -1,3 +1,19 @@
 "use strict";
 /** Type definitions for the role and escalation chain service. */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_PROPERTY_KEYS = void 0;
+/**
+ * Reserved keys inside `lt_roles.properties` — the role's verb semantics for
+ * the domain dictionary. Everything else in the bag is user-owned. Values are
+ * plain strings; readers type-guard (the bag is open, PATCH can write anything).
+ *
+ *  - ON_CANCEL: what cancel MEANS for this row class, imperative
+ *    (e.g. "reset — the dispatcher re-mints the attempt").
+ *  - ON_TIMEOUT: expiry semantics for this row class.
+ *  - WORKED_BY: who works this queue ("humans at the dashboard" | "machines" | "both").
+ */
+exports.ROLE_PROPERTY_KEYS = {
+    ON_CANCEL: 'on_cancel',
+    ON_TIMEOUT: 'on_timeout',
+    WORKED_BY: 'worked_by',
+};

package/build/start/workers.js

@@ -273,6 +273,12 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
     await seedSystemTopics();
     if (startConfig.topics?.length)
         await seedConfigTopics(startConfig.topics);
+    // Seed the domain dictionary (every container, workers or not) — insert-if-
+    // absent with warn-only reference validation; the DB row is runtime truth.
+    if (startConfig.mcp?.domainDictionaryPath) {
+        const { seedDomainDictionary } = await Promise.resolve().then(() => __importStar(require('../services/domain')));
+        await seedDomainDictionary(startConfig.mcp.domainDictionaryPath);
+    }
     // Seed example topics when examples are enabled
     if (startConfig.examples) {
         try {

package/build/system/mcp-servers/admin/domain-context.d.ts

@@ -0,0 +1,14 @@
+/**
+ * get_domain_context — the deployment's domain dictionary, merged with live
+ * platform state so an agent can translate domain speech into primitive calls.
+ *
+ * The dictionary (lt_domain, TTL-cached) holds the semantic overlay: jargon
+ * terms mapped to roles/workflows/facets/verbs, guidance, runbooks. This tool
+ * JOINS it with the live registries at call time — role entries carry the live
+ * row's title/description/entity_facet plus its properties verb semantics
+ * (on_cancel/on_timeout/worked_by); workflow entries carry the live config;
+ * entity entries carry the id facet derived from their role. References to
+ * since-removed roles/workflows are annotated, never thrown. Read-safe.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDomainContextTools(server: McpServer): void;