@hotmeshio/long-tail 0.5.11 → 0.6.0

package/build/api/users.d.ts

@@ -6,6 +6,7 @@ import type { LTRoleType } from '../types';
  * @param input.role — filter by role name
  * @param input.roleType — filter by role type (superadmin, admin, member)
  * @param input.status — filter by user status
+ * @param input.search — free-text match on display name, email, or external_id
  * @param input.limit — maximum number of users to return
  * @param input.offset — number of users to skip for pagination
  * @returns `{ status: 200, data: User[] }` on success
@@ -14,6 +15,7 @@ export declare function listUsers(input: {
     role?: string;
     roleType?: LTRoleType;
     status?: string;
+    search?: string;
     limit?: number;
     offset?: number;
 }): Promise<LTApiResult>;
@@ -47,6 +49,8 @@ export declare function createUser(input: {
     roles?: {
         role: string;
         type: string;
+        read_scope?: string;
+        write_scope?: string;
     }[];
     metadata?: Record<string, any>;
 }): Promise<LTApiResult>;
@@ -103,6 +107,8 @@ export declare function addUserRole(input: {
     id: string;
     role: string;
     type: string;
+    read_scope?: string;
+    write_scope?: string;
 }): Promise<LTApiResult>;
 /**
  * Remove a role from a user. Requires admin privileges.

package/build/api/users.js

@@ -48,6 +48,7 @@ const userService = __importStar(require("../services/user"));
  * @param input.role — filter by role name
  * @param input.roleType — filter by role type (superadmin, admin, member)
  * @param input.status — filter by user status
+ * @param input.search — free-text match on display name, email, or external_id
  * @param input.limit — maximum number of users to return
  * @param input.offset — number of users to skip for pagination
  * @returns `{ status: 200, data: User[] }` on success
@@ -105,6 +106,17 @@ async function createUser(input) {
                         error: 'Each role must have a role name and type (superadmin, admin, member)',
                     };
                 }
+                if (r.read_scope !== undefined && !userService.isValidReadScope(r.read_scope)) {
+                    return { status: 400, error: 'read_scope must be self or all' };
+                }
+                if (r.write_scope !== undefined && !userService.isValidWriteScope(r.write_scope)) {
+                    return { status: 400, error: 'write_scope must be none, self, or all' };
+                }
+                const read = (r.read_scope ?? userService.DEFAULT_READ_SCOPE);
+                const write = (r.write_scope ?? userService.DEFAULT_WRITE_SCOPE);
+                if (!userService.isValidScopePair(read, write)) {
+                    return { status: 400, error: 'write_scope=all requires read_scope=all' };
+                }
             }
         }
         const user = await userService.createUser({
@@ -201,7 +213,23 @@ async function addUserRole(input) {
         if (!userService.isValidRoleType(input.type)) {
             return { status: 400, error: 'type must be superadmin, admin, or member' };
         }
-        const result = await userService.addUserRole(input.id, input.role, input.type);
+        // Work-surface scope (optional; defaults to all/all = full worker). Only
+        // meaningful for `member`; admin/superadmin normalize to all/all.
+        if (input.read_scope !== undefined && !userService.isValidReadScope(input.read_scope)) {
+            return { status: 400, error: 'read_scope must be self or all' };
+        }
+        if (input.write_scope !== undefined && !userService.isValidWriteScope(input.write_scope)) {
+            return { status: 400, error: 'write_scope must be none, self, or all' };
+        }
+        const read = (input.read_scope ?? userService.DEFAULT_READ_SCOPE);
+        const write = (input.write_scope ?? userService.DEFAULT_WRITE_SCOPE);
+        if (!userService.isValidScopePair(read, write)) {
+            return { status: 400, error: 'write_scope=all requires read_scope=all (cannot act on what you cannot see)' };
+        }
+        const result = await userService.addUserRole(input.id, input.role, input.type, {
+            read_scope: read,
+            write_scope: write,
+        });
         return { status: 201, data: result };
     }
     catch (err) {

package/build/api/workflows/invocation.d.ts

@@ -23,12 +23,16 @@ export declare function invokeWorkflow(input: {
  *
  * Returns the HotMesh status code (0 = completed, 1 = running).
  * Resolves the workflow handle via task record or worker registry.
+ * `appId` selects the namespace for the job-entity fallback so a child
+ * running in another app resolves instead of 404ing against `durable`.
  *
  * @param input.workflowId — HotMesh workflow ID
+ * @param input.appId — HotMesh namespace for resolution (default: durable)
  * @returns `{ status: 200, data: { workflowId, status } }` or 404
  */
 export declare function getWorkflowStatus(input: {
     workflowId: string;
+    appId?: string;
 }): Promise<LTApiResult>;
 /**
  * Get the result of a completed workflow.
@@ -37,10 +41,12 @@ export declare function getWorkflowStatus(input: {
  * payload when complete. Never blocks — always returns immediately.
  *
  * @param input.workflowId — HotMesh workflow ID
+ * @param input.appId — HotMesh namespace for resolution (default: durable)
  * @returns `{ status: 200, data: { workflowId, result } }` or 202 if running
  */
 export declare function getWorkflowResult(input: {
     workflowId: string;
+    appId?: string;
 }): Promise<LTApiResult>;
 /**
  * Terminate a running workflow.

package/build/api/workflows/invocation.js

@@ -87,13 +87,16 @@ async function invokeWorkflow(input, auth) {
  *
  * Returns the HotMesh status code (0 = completed, 1 = running).
  * Resolves the workflow handle via task record or worker registry.
+ * `appId` selects the namespace for the job-entity fallback so a child
+ * running in another app resolves instead of 404ing against `durable`.
  *
  * @param input.workflowId — HotMesh workflow ID
+ * @param input.appId — HotMesh namespace for resolution (default: durable)
  * @returns `{ status: 200, data: { workflowId, status } }` or 404
  */
 async function getWorkflowStatus(input) {
     try {
-        const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId);
+        const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId, input.appId);
         const client = (0, workers_1.createClient)();
         const handle = await client.workflow.getHandle(resolved.taskQueue, resolved.workflowName, input.workflowId);
         const status = await handle.status();
@@ -115,11 +118,12 @@ async function getWorkflowStatus(input) {
  * payload when complete. Never blocks — always returns immediately.
  *
  * @param input.workflowId — HotMesh workflow ID
+ * @param input.appId — HotMesh namespace for resolution (default: durable)
  * @returns `{ status: 200, data: { workflowId, result } }` or 202 if running
  */
 async function getWorkflowResult(input) {
     try {
-        const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId);
+        const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId, input.appId);
         const client = (0, workers_1.createClient)();
         const handle = await client.workflow.getHandle(resolved.taskQueue, resolved.workflowName, input.workflowId);
         const status = await handle.status();

package/build/bin/ltc.js

@@ -120,6 +120,13 @@ escCmd.command('list')
     .option('--status <status>', 'Filter by status (pending, resolved, cancelled)')
     .option('--role <role>', 'Filter by role')
     .option('--limit <n>', 'Max results')
+    .option('--facets <json>', 'Required metadata facets, JSON object (metadata @>), e.g. \'{"filament":"pla"}\'')
+    .option('--block <json>', 'Exclude rows containing ANY of these facet sets, JSON array')
+    .option('--range <json>', 'Numeric ranges over facets, JSON array e.g. \'[{"facet":"confidence","op":"<=","value":0.7}]\'')
+    .option('--exists <json>', 'Metadata keys that must be present, JSON array of strings')
+    .option('--roles <json>', 'Restrict to these roles, JSON array (narrows within scope)')
+    .option('--available <bool>', 'true = unclaimed/expired only; false = held now')
+    .option('--order-by <json>', 'Sort keys, JSON array e.g. \'[{"field":"metadata.confidence","numeric":true,"direction":"asc"}]\'')
     .option('--json', 'JSON output')
     .option('-q, --quiet', 'IDs only')
     .action(wrap(esc.listEscalations));
@@ -153,6 +160,39 @@ escCmd.command('resolve-by-meta <key> <value>')
     .option('--assignee <external_id>', 'Resolve on behalf of user (external_id)')
     .option('--meta <json>', 'Merge metadata (JSON object)')
     .action(wrap(esc.resolveByMetadata));
+escCmd.command('resolve-by-ids <ids...>')
+    .description('Resolve a set of escalations by id')
+    .requiredOption('--payload <json>', 'Resolver payload (JSON string)')
+    .option('--metadata <json>', 'Merge metadata (JSON object)')
+    .action(wrap(esc.resolveByIds));
+escCmd.command('search-facets')
+    .description('Item-level faceted search over a pond (role-scoped)')
+    .requiredOption('--role <role>', 'Pond role to search')
+    .option('--status <status>', 'Filter by status')
+    .option('--available', 'Only available (unclaimed/expired)')
+    .option('--facets <json>', 'Required facets (JSON object)')
+    .option('--limit <n>', 'Max results')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'IDs only')
+    .action(wrap(esc.searchByFacets));
+escCmd.command('claim-groups')
+    .description('Batch-claim complete origin groups in priority order')
+    .requiredOption('--role <role>', 'Pond role to claim from')
+    .option('--facets <json>', 'Required facets (JSON object)')
+    .option('--limit <n>', 'Max groups to claim')
+    .option('--duration <minutes>', 'Claim duration in minutes')
+    .option('--size-facet <key>', 'Metadata facet declaring group size')
+    .option('--json', 'JSON output')
+    .action(wrap(esc.claimGroups));
+escCmd.command('claim-by-facets')
+    .description('Batch-claim individual rows matching facets')
+    .requiredOption('--role <role>', 'Pond role to claim from')
+    .option('--facets <json>', 'Required facets (JSON object)')
+    .option('--limit <n>', 'Max rows to claim')
+    .option('--duration <minutes>', 'Claim duration in minutes')
+    .option('--all-or-none', 'Claim all matched rows or none')
+    .option('--json', 'JSON output')
+    .action(wrap(esc.claimByFacets));
 // ── Workflows ────────────────────────────────────────────────────────────
 const wfCmd = commander_1.program.command('workflows').alias('wf').description('Manage durable workflows');
 wfCmd.command('list')

package/build/lib/cli/commands/escalations.d.ts

@@ -4,6 +4,13 @@ interface ListOptions {
     limit?: string;
     json?: boolean;
     quiet?: boolean;
+    facets?: string;
+    block?: string;
+    range?: string;
+    exists?: string;
+    roles?: string;
+    available?: string;
+    orderBy?: string;
 }
 export declare function listEscalations(opts: ListOptions): Promise<void>;
 export declare function getEscalation(id: string, opts: {
@@ -27,4 +34,33 @@ export declare function resolveByMetadata(key: string, value: string, opts: {
     assignee?: string;
     meta?: string;
 }): Promise<void>;
+export declare function resolveByIds(ids: string[], opts: {
+    payload: string;
+    metadata?: string;
+}): Promise<void>;
+export declare function searchByFacets(opts: {
+    role: string;
+    status?: string;
+    available?: boolean;
+    facets?: string;
+    limit?: string;
+    json?: boolean;
+    quiet?: boolean;
+}): Promise<void>;
+export declare function claimGroups(opts: {
+    role: string;
+    facets?: string;
+    limit?: string;
+    duration?: string;
+    sizeFacet?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function claimByFacets(opts: {
+    role: string;
+    facets?: string;
+    limit?: string;
+    duration?: string;
+    allOrNone?: boolean;
+    json?: boolean;
+}): Promise<void>;
 export {};

package/build/lib/cli/commands/escalations.js

@@ -11,6 +11,10 @@ exports.resolveEscalation = resolveEscalation;
 exports.findByMetadata = findByMetadata;
 exports.claimByMetadata = claimByMetadata;
 exports.resolveByMetadata = resolveByMetadata;
+exports.resolveByIds = resolveByIds;
+exports.searchByFacets = searchByFacets;
+exports.claimGroups = claimGroups;
+exports.claimByFacets = claimByFacets;
 const picocolors_1 = __importDefault(require("picocolors"));
 const client_1 = require("../client");
 const format_1 = require("../format");
@@ -30,6 +34,22 @@ async function listEscalations(opts) {
         params.set('role', opts.role);
     if (opts.limit)
         params.set('limit', opts.limit);
+    // Faceted query elements travel as JSON-encoded query params (the route JSON-parses
+    // them). parseJsonOption validates the input and throws a friendly error on bad JSON.
+    if (opts.facets)
+        params.set('facets', JSON.stringify(parseJsonOption('--facets', opts.facets)));
+    if (opts.block)
+        params.set('block', JSON.stringify(parseJsonOption('--block', opts.block)));
+    if (opts.range)
+        params.set('range', JSON.stringify(parseJsonOption('--range', opts.range)));
+    if (opts.exists)
+        params.set('exists', JSON.stringify(parseJsonOption('--exists', opts.exists)));
+    if (opts.roles)
+        params.set('roles', JSON.stringify(parseJsonOption('--roles', opts.roles)));
+    if (opts.orderBy)
+        params.set('orderBy', JSON.stringify(parseJsonOption('--order-by', opts.orderBy)));
+    if (opts.available != null)
+        params.set('available', opts.available);
     const data = await (0, client_1.apiFetch)(`/escalations?${params}`);
     (0, format_1.output)(data, data.escalations || [], COLUMNS, opts);
 }
@@ -107,3 +127,81 @@ async function resolveByMetadata(key, value, opts) {
     });
     console.log(`\n  ${picocolors_1.default.green('✓')} Resolved by ${key}=${value}\n`);
 }
+// --- Faceted routing commands -----------------------------------------------
+function parseJsonOption(label, raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON for ${label}: ${raw}`);
+    }
+}
+async function resolveByIds(ids, opts) {
+    const resolverPayload = parseJsonOption('--payload', opts.payload);
+    const body = { ids, resolverPayload };
+    if (opts.metadata)
+        body.metadata = parseJsonOption('--metadata', opts.metadata);
+    const data = await (0, client_1.apiFetch)('/escalations/resolve-by-ids', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    console.log(`\n  ${picocolors_1.default.green('✓')} Resolved ${data.resolved} escalation(s)\n`);
+}
+async function searchByFacets(opts) {
+    const query = { role: opts.role };
+    if (opts.status)
+        query.status = opts.status;
+    if (opts.available)
+        query.available = true;
+    if (opts.facets)
+        query.facets = parseJsonOption('--facets', opts.facets);
+    if (opts.limit)
+        query.limit = parseInt(opts.limit, 10);
+    const data = await (0, client_1.apiFetch)('/escalations/search-by-facets', {
+        method: 'POST',
+        body: JSON.stringify(query),
+    });
+    (0, format_1.output)(data, data.escalations || [], COLUMNS, opts);
+}
+async function claimGroups(opts) {
+    const query = { role: opts.role };
+    if (opts.facets)
+        query.facets = parseJsonOption('--facets', opts.facets);
+    const body = { query };
+    if (opts.limit)
+        body.limit = parseInt(opts.limit, 10);
+    if (opts.duration)
+        body.durationMinutes = parseInt(opts.duration, 10);
+    if (opts.sizeFacet)
+        body.sizeFacet = opts.sizeFacet;
+    const data = await (0, client_1.apiFetch)('/escalations/claim-groups', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    console.log(`\n  ${picocolors_1.default.green('✓')} Claimed ${data.groups?.length || 0} group(s)\n`);
+}
+async function claimByFacets(opts) {
+    const query = { role: opts.role };
+    if (opts.facets)
+        query.facets = parseJsonOption('--facets', opts.facets);
+    const body = { query };
+    if (opts.limit)
+        body.limit = parseInt(opts.limit, 10);
+    if (opts.duration)
+        body.durationMinutes = parseInt(opts.duration, 10);
+    if (opts.allOrNone)
+        body.allOrNone = true;
+    const data = await (0, client_1.apiFetch)('/escalations/claim-by-facets', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    console.log(`\n  ${picocolors_1.default.green('✓')} Claimed ${data.claimed?.length || 0} escalation(s)\n`);
+}

package/build/lib/db/schemas/001_schema.sql

@@ -99,11 +99,16 @@ CREATE OR REPLACE TRIGGER lt_users_updated_at
 -- ─── lt_user_roles ───────────────────────────────────────────────────────────
 
 CREATE TABLE IF NOT EXISTS lt_user_roles (
-  user_id    UUID NOT NULL REFERENCES lt_users(id) ON DELETE CASCADE,
-  role       TEXT NOT NULL REFERENCES lt_roles(role),
-  type       TEXT NOT NULL DEFAULT 'member' CHECK (type IN ('superadmin', 'admin', 'member')),
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  PRIMARY KEY (user_id, role)
+  user_id     UUID NOT NULL REFERENCES lt_users(id) ON DELETE CASCADE,
+  role        TEXT NOT NULL REFERENCES lt_roles(role),
+  type        TEXT NOT NULL DEFAULT 'member' CHECK (type IN ('superadmin', 'admin', 'member')),
+  -- Work-surface scope (orthogonal to `type`, ignored for admin/superadmin).
+  -- read governs search, write governs claim/ack/delete. write ⊆ read.
+  read_scope  TEXT NOT NULL DEFAULT 'all' CHECK (read_scope IN ('self', 'all')),
+  write_scope TEXT NOT NULL DEFAULT 'all' CHECK (write_scope IN ('none', 'self', 'all')),
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (user_id, role),
+  CONSTRAINT chk_lt_user_roles_scope CHECK (NOT (write_scope = 'all' AND read_scope = 'self'))
 );
 
 CREATE INDEX IF NOT EXISTS idx_lt_user_roles_type ON lt_user_roles (type);

package/build/lib/db/schemas/012_lt_tasks_workflow_id_unique.sql

@@ -0,0 +1,20 @@
+-- ─── 012: lt_tasks.workflow_id uniqueness ─────────────────────────────────────
+-- A task is 1:1 with its workflow_id. Every createTask caller keys the row by a
+-- deterministic workflow_id (orchestrator childWorkflowId, interceptor
+-- wf.workflowId, escalation triage-<id>), and createTask runs inside a
+-- proxyActivity with retry { maximumAttempts: 3 }. Without a unique constraint a
+-- retry — or a re-driven triage saga — double-inserts a task row. The unique
+-- index lets createTask use ON CONFLICT (workflow_id) so retries converge instead
+-- of duplicating, matching how HotMesh upserts the sibling job by (workflowId, app_id).
+
+-- Collapse any pre-existing duplicates, keeping the most recent row per workflow_id
+-- (tie-break on id so exactly one survives and the unique index can be built).
+DELETE FROM lt_tasks a
+USING lt_tasks b
+WHERE a.workflow_id = b.workflow_id
+  AND (a.created_at < b.created_at
+       OR (a.created_at = b.created_at AND a.id < b.id));
+
+-- Replace the non-unique lookup index with a unique one (it still serves lookups).
+DROP INDEX IF EXISTS idx_lt_tasks_workflow_id;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_lt_tasks_workflow_id ON lt_tasks (workflow_id);

package/build/lib/db/schemas/013_role_scope.sql

@@ -0,0 +1,37 @@
+-- ─── lt_user_roles: read/write work-surface scope ──────────────────────────
+--
+-- Open roles split the worker capability into two orthogonal axes so that
+-- one-time and limited-surface users are first-class:
+--
+--   read_scope  (self | all)        → governs SEARCH (which items appear)
+--   write_scope (none | self | all) → governs CLAIM / ACK / DELETE
+--
+-- `self` = escalations assigned to the user (assigned_to = userId); `all` = the
+-- whole role queue. The only constraint is write ⊆ read (you cannot act on what
+-- you cannot see). `type` (member/admin/superadmin) is unchanged — it remains the
+-- management/global tier, and admin/superadmin ignore scope (always act on all).
+--
+-- Existing rows default to ('all','all') = today's `member` behavior, so this is
+-- backward compatible with zero data backfill. Idempotent: no-op on fresh installs
+-- where 001_schema.sql already created the columns and the named constraint.
+
+ALTER TABLE lt_user_roles
+  ADD COLUMN IF NOT EXISTS read_scope  TEXT NOT NULL DEFAULT 'all'
+    CHECK (read_scope IN ('self', 'all'));
+
+ALTER TABLE lt_user_roles
+  ADD COLUMN IF NOT EXISTS write_scope TEXT NOT NULL DEFAULT 'all'
+    CHECK (write_scope IN ('none', 'self', 'all'));
+
+-- write ⊆ read: cannot act on the whole queue while only reading your own.
+-- Guarded so a re-run (or a fresh install where 001 already added it) is a no-op.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'chk_lt_user_roles_scope'
+  ) THEN
+    ALTER TABLE lt_user_roles
+      ADD CONSTRAINT chk_lt_user_roles_scope
+      CHECK (NOT (write_scope = 'all' AND read_scope = 'self'));
+  END IF;
+END $$;

package/build/modules/features.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Runtime feature flags surfaced to the dashboard via /api/settings.
+ *
+ * These gate UI affordances (nav entries, routes) that some deployments want to
+ * hide. Defaults are permissive (everything on); a deployment opts OUT through
+ * the `features` block of the `start()` config. The dashboard reads the resolved
+ * flags from `settings.features` and hides the corresponding nav item + route.
+ */
+export interface FeatureFlags {
+    /**
+     * Show the DB Maintenance admin page (nav entry + route).
+     * Default: true. Set `features.dbMaintenance: false` in start config to hide it.
+     */
+    dbMaintenance: boolean;
+}
+/** Merge a partial set of flags from the start config. Unspecified flags keep their default. */
+export declare function configureFeatureFlags(patch?: Partial<FeatureFlags>): void;
+/** The resolved feature flags reported to the dashboard. */
+export declare function getFeatureFlags(): FeatureFlags;

package/build/modules/features.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureFeatureFlags = configureFeatureFlags;
+exports.getFeatureFlags = getFeatureFlags;
+const DEFAULT_FLAGS = {
+    dbMaintenance: true,
+};
+let flags = { ...DEFAULT_FLAGS };
+/** Merge a partial set of flags from the start config. Unspecified flags keep their default. */
+function configureFeatureFlags(patch) {
+    flags = { ...DEFAULT_FLAGS, ...(patch ?? {}) };
+}
+/** The resolved feature flags reported to the dashboard. */
+function getFeatureFlags() {
+    return { ...flags };
+}

package/build/modules/version.d.ts

@@ -7,10 +7,15 @@
  */
 export declare const HOTMESH_VERSION: string;
 /**
- * The long-tail app version. Read from the root package.json at runtime via the
- * process working directory (which is the app root in both dev and the Docker
- * image, where CMD runs `node build/index.js` from /app). A static
- * `../package.json` import would resolve to build/package.json after compile —
- * a path the Dockerfile does not copy — so this reads from cwd instead.
+ * The long-tail package version.
+ *
+ * Resolved from long-tail's OWN package.json by walking up from this module's
+ * directory to the first package.json named `@hotmeshio/long-tail`. Reading
+ * `process.cwd()/package.json` is wrong when long-tail is consumed as a
+ * dependency (e.g. mounted as a NestJS module) — cwd is then the HOST app's
+ * root, so it reported the host's version. The upward walk resolves correctly in
+ * dev (source tree), the standalone Docker image (`/app`), and under
+ * `node_modules/@hotmeshio/long-tail`. A static `../package.json` import can't be
+ * used: post-compile it resolves to `build/package.json`, which is not shipped.
  */
 export declare const LONG_TAIL_VERSION: string;

package/build/modules/version.js

@@ -15,20 +15,36 @@ const package_json_1 = __importDefault(require("@hotmeshio/hotmesh/package.json"
  * node_modules), and resolveJsonModule handles the static import at compile time.
  */
 exports.HOTMESH_VERSION = package_json_1.default.version ?? 'unknown';
+const LONG_TAIL_PACKAGE_NAME = '@hotmeshio/long-tail';
 /**
- * The long-tail app version. Read from the root package.json at runtime via the
- * process working directory (which is the app root in both dev and the Docker
- * image, where CMD runs `node build/index.js` from /app). A static
- * `../package.json` import would resolve to build/package.json after compile —
- * a path the Dockerfile does not copy — so this reads from cwd instead.
+ * The long-tail package version.
+ *
+ * Resolved from long-tail's OWN package.json by walking up from this module's
+ * directory to the first package.json named `@hotmeshio/long-tail`. Reading
+ * `process.cwd()/package.json` is wrong when long-tail is consumed as a
+ * dependency (e.g. mounted as a NestJS module) — cwd is then the HOST app's
+ * root, so it reported the host's version. The upward walk resolves correctly in
+ * dev (source tree), the standalone Docker image (`/app`), and under
+ * `node_modules/@hotmeshio/long-tail`. A static `../package.json` import can't be
+ * used: post-compile it resolves to `build/package.json`, which is not shipped.
  */
 exports.LONG_TAIL_VERSION = readLongTailVersion();
 function readLongTailVersion() {
-    try {
-        const raw = (0, fs_1.readFileSync)((0, path_1.resolve)(process.cwd(), 'package.json'), 'utf8');
-        return JSON.parse(raw).version ?? 'unknown';
-    }
-    catch {
-        return 'unknown';
+    let dir = __dirname;
+    const { root } = (0, path_1.parse)(dir);
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        try {
+            const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(dir, 'package.json'), 'utf8'));
+            if (pkg.name === LONG_TAIL_PACKAGE_NAME)
+                return pkg.version ?? 'unknown';
+        }
+        catch {
+            /* no readable package.json here — keep walking up */
+        }
+        if (dir === root)
+            break;
+        dir = (0, path_1.dirname)(dir);
     }
+    return 'unknown';
 }

package/build/routes/diagnostics.js

@@ -37,19 +37,32 @@ const express_1 = require("express");
 const api = __importStar(require("../api/diagnostics"));
 const auth_1 = require("../modules/auth");
 const router = (0, express_1.Router)();
+const VALID_SECTIONS = new Set(['events', 'streams']);
+/** Parse a comma-separated `include` query param into the recognized heavy sections. */
+function parseInclude(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return undefined;
+    const sections = raw.split(',').map((s) => s.trim()).filter((s) => VALID_SECTIONS.has(s));
+    return sections.length > 0 ? sections : undefined;
+}
 /**
  * GET /api/diagnostics/jobs/:workflowId
- * Full diagnosis for a single workflow job.
+ * Compact diagnosis for a single workflow job — the verdict only by default
+ * (status, idle time, stream counts, escalation, findings).
  *
  * Query params:
  *   app_id     — HotMesh namespace (default: durable)
- *   max_events — cap on events returned (most recent kept; default: 500)
+ *   max_events — cap on events returned when included (most recent kept; default: 500)
+ *   include    — comma-separated heavy sections to add: events, streams
+ *   verbosity  — 'summary' (default, verdict only) or 'full' (events + streams)
  */
 router.get('/jobs/:workflowId', auth_1.requireAdmin, async (req, res) => {
     const result = await api.diagnose({
         workflowId: req.params.workflowId,
         appId: typeof req.query.app_id === 'string' ? req.query.app_id : undefined,
         maxEvents: req.query.max_events ? Number(req.query.max_events) : undefined,
+        include: parseInclude(req.query.include),
+        verbosity: req.query.verbosity === 'full' ? 'full' : undefined,
     });
     res.status(result.status).json(result.data ?? { error: result.error });
 });

package/build/routes/escalations/facets.d.ts

@@ -0,0 +1,7 @@
+import { Router } from 'express';
+/**
+ * Faceted-routing HTTP surface — pond search + batch claim. Each operation targets a
+ * single pond `role` and is RBAC-scoped to it (the api layer enforces the gate). These
+ * mirror the SDK `escalations.searchByFacets / claimGroups / claimByFacets`.
+ */
+export declare function registerFacetRoutes(router: Router): void;