@hotmeshio/long-tail 0.27.0 → 0.28.1

package/build/start/apply-report.js

@@ -1,11 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.withConfigLock = void 0;
 exports.ownedByCode = ownedByCode;
 exports.newSurfaceReport = newSurfaceReport;
 exports.recordOutcome = recordOutcome;
-exports.withConfigLock = withConfigLock;
 exports.logSurfaceReport = logSurfaceReport;
-const db_1 = require("../lib/db");
 const logger_1 = require("../lib/logger");
 /**
  * Effective ownership for one declared entry: the per-entry `reset` flag wins
@@ -26,29 +25,8 @@ function recordOutcome(report, name, outcome) {
     else
         report.dbOwned.push(name);
 }
-/**
- * Serializes multi-statement config writes (role-list replaces, escalation
- * target replaces) across concurrently booting containers. Single-statement
- * upserts are individually race-safe; the lock exists for the replace
- * transactions and keeps boot reports coherent. Distinct from the migration
- * lock so a slow migration on one container never blocks another's config
- * pass behind two locks at once.
- */
-const CONFIG_APPLY_LOCK_ID = 8675310;
-async function withConfigLock(fn) {
-    const pool = (0, db_1.getPool)();
-    const client = await pool.connect();
-    try {
-        await client.query(`SELECT pg_advisory_lock(${CONFIG_APPLY_LOCK_ID})`);
-        return await fn();
-    }
-    finally {
-        await client
-            .query(`SELECT pg_advisory_unlock(${CONFIG_APPLY_LOCK_ID})`)
-            .catch(() => { });
-        client.release();
-    }
-}
+var config_lock_1 = require("../lib/db/config-lock");
+Object.defineProperty(exports, "withConfigLock", { enumerable: true, get: function () { return config_lock_1.withConfigLock; } });
 /**
  * One boot line per surface. Warn level when orphans exist so operators see
  * "declared set no longer matches the DB" without grepping.

package/build/start/index.js

@@ -8,7 +8,9 @@ const events_1 = require("../lib/events");
 const messaging_1 = require("../lib/messaging");
 const callback_1 = require("../lib/events/callback");
 const surface_1 = require("../services/machines/surface");
+const machines_1 = require("../modules/machines");
 const roles_1 = require("../services/machines/roles");
+const registry_sync_1 = require("../services/machines/registry-sync");
 const maintenance_1 = require("../services/maintenance");
 const cron_1 = require("../services/cron");
 const mcp_1 = require("../services/mcp");
@@ -80,10 +82,18 @@ async function start(startConfig) {
     }
     const { workers, builtinMcpServerFactories } = await (0, workers_1.collectWorkers)(startConfig);
     const { adminUserId } = await (0, workers_1.startWorkers)(startConfig, workers, builtinMcpServerFactories);
-    // 5b. Machines, after the workers exist so their rows publish lifecycle events
-    const machines = startConfig.machines
-        ? surface_1.MachineSurface.start({ ...startConfig.machines, callbacks: events_1.eventRegistry.getAdapter(callback_1.CallbackEventAdapter) })
-        : null;
+    // 5b. Machines, after the workers exist so their rows publish lifecycle events.
+    // Code lines land in the registry under the configSource rules; the surface runs every line the registry holds.
+    let machines = null;
+    let unwatchLines = null;
+    if (startConfig.machines) {
+        const callbacks = events_1.eventRegistry.getAdapter(callback_1.CallbackEventAdapter);
+        const { lines } = await (0, registry_sync_1.syncDeclaredLines)(startConfig.machines.lines, (startConfig.configSource ?? 'db') === 'code');
+        machines = surface_1.MachineSurface.start({ ...startConfig.machines, lines, callbacks });
+        if (callbacks)
+            unwatchLines = (0, registry_sync_1.watchLineRegistry)(machines, callbacks);
+    }
+    (0, machines_1.registerMachineSurface)(machines);
     // 6. Start embedded server (if enabled)
     const serverEnabled = startConfig.server?.enabled !== false;
     let httpServer = null;
@@ -101,7 +111,9 @@ async function start(startConfig) {
             await new Promise((resolve) => httpServer.close(() => resolve()));
         }
         if (machines) {
+            unwatchLines?.();
             await machines.stop();
+            (0, machines_1.registerMachineSurface)(null);
         }
         if (mcp_1.mcpRegistry.hasAdapter) {
             await mcp_1.mcpRegistry.disconnect();

package/build/system/activities/knowledge.d.ts

@@ -4,6 +4,8 @@ export declare function storeKnowledge(args: {
     data: Record<string, any>;
     tags?: string[];
     replace?: boolean;
+    /** A name for the edition this write leaves current, which lookup refs may pin. */
+    label?: string;
 }): Promise<{
     id: string;
     domain: string;
@@ -75,6 +77,8 @@ export declare function appendKnowledge(args: {
     key: string;
     path: string;
     value: any;
+    /** A name for the edition this write leaves current, which lookup refs may pin. */
+    label?: string;
 }): Promise<{
     id: string;
     domain: string;

package/build/system/activities/knowledge.js

@@ -23,10 +23,23 @@ async function withClient(fn) {
         await client.end();
     }
 }
+/** Name the entry's current edition. A label already naming another edition of the entry is refused. */
+async function labelCurrentEdition(client, domain, key, version, label) {
+    try {
+        await client.query(sql_1.LABEL_KNOWLEDGE_VERSION, [domain, key, label, version]);
+    }
+    catch (err) {
+        if (err?.code === '23505')
+            throw new Error(`label "${label}" already names another edition of ${domain}/${key}`);
+        throw err;
+    }
+}
 async function storeKnowledge(args) {
     return withClient(async (client) => {
         const sql = args.replace ? sql_1.REPLACE_KNOWLEDGE : sql_1.UPSERT_KNOWLEDGE;
         const { rows } = await client.query(sql, [args.domain, args.key, JSON.stringify(args.data), args.tags || []]);
+        if (args.label)
+            await labelCurrentEdition(client, args.domain, args.key, rows[0].current_version, args.label);
         const result = { ...rows[0], updated_at: rows[0].updated_at.toISOString() };
         (0, publish_1.publishKnowledgeEvent)({ type: 'knowledge.stored', domain: args.domain, key: args.key });
         return result;
@@ -173,6 +186,8 @@ async function appendKnowledge(args) {
             initData = { [pathParts[i]]: initData };
         }
         const { rows } = await client.query(sql_1.APPEND_KNOWLEDGE, [args.domain, args.key, JSON.stringify(initData), pathArray, valueJson]);
+        if (args.label)
+            await labelCurrentEdition(client, args.domain, args.key, rows[0].current_version, args.label);
         return { ...rows[0], updated_at: rows[0].updated_at.toISOString() };
     });
 }

package/build/system/activities/sql.d.ts

@@ -6,3 +6,5 @@ export declare const LIST_DOMAINS = "\n  SELECT domain, COUNT(*)::int AS count,
 export declare const SET_KNOWLEDGE_FIELD = "\n  WITH upserted AS (\n    INSERT INTO lt_knowledge (domain, key, data, tags)\n    VALUES ($1, $2, $3::jsonb, $4)\n    ON CONFLICT (domain, key) DO UPDATE SET\n      data = jsonb_set(lt_knowledge.data, $5::text[], $6::jsonb, true),\n      tags = ARRAY(SELECT DISTINCT unnest(lt_knowledge.tags || EXCLUDED.tags)),\n      current_version = CASE\n        WHEN jsonb_set(lt_knowledge.data, $5::text[], $6::jsonb, true) IS DISTINCT FROM lt_knowledge.data\n        THEN lt_knowledge.current_version + 1\n        ELSE lt_knowledge.current_version\n      END\n    RETURNING id, domain, key, data, tags, current_version, (xmax = 0) AS created, updated_at\n  ), snapshot AS (\n    INSERT INTO lt_knowledge_versions (domain, key, version, data, tags)\n    SELECT domain, key, current_version, data, tags FROM upserted\n    ON CONFLICT (domain, key, version) DO NOTHING\n  )\n  SELECT id, domain, key, current_version, created, updated_at FROM upserted";
 export declare const REMOVE_KNOWLEDGE_FIELD = "\n  WITH updated AS (\n    UPDATE lt_knowledge\n    SET data = data #- $3::text[],\n        current_version = CASE\n          WHEN data #- $3::text[] IS DISTINCT FROM data\n          THEN current_version + 1\n          ELSE current_version\n        END\n    WHERE domain = $1 AND key = $2\n    RETURNING id, domain, key, data, tags, current_version, updated_at\n  ), snapshot AS (\n    INSERT INTO lt_knowledge_versions (domain, key, version, data, tags)\n    SELECT domain, key, current_version, data, tags FROM updated\n    ON CONFLICT (domain, key, version) DO NOTHING\n  )\n  SELECT id, domain, key, current_version, updated_at FROM updated";
 export declare const APPEND_KNOWLEDGE = "\n  WITH upserted AS (\n    INSERT INTO lt_knowledge (domain, key, data)\n    VALUES ($1, $2, $3::jsonb)\n    ON CONFLICT (domain, key) DO UPDATE SET\n      data = CASE\n        WHEN lt_knowledge.data #> $4::text[] IS NULL\n        THEN jsonb_set(lt_knowledge.data, $4::text[], jsonb_build_array($5::jsonb))\n        ELSE jsonb_set(lt_knowledge.data, $4::text[], (lt_knowledge.data #> $4::text[]) || jsonb_build_array($5::jsonb))\n      END,\n      current_version = lt_knowledge.current_version + 1\n    RETURNING id, domain, key, data, tags, current_version, updated_at\n  ), snapshot AS (\n    INSERT INTO lt_knowledge_versions (domain, key, version, data, tags)\n    SELECT domain, key, current_version, data, tags FROM upserted\n    ON CONFLICT (domain, key, version) DO NOTHING\n  )\n  SELECT id, domain, key, current_version, updated_at FROM upserted";
+/** Name an edition: the label a lookup ref may pin instead of the number. A label names one edition of an entry. */
+export declare const LABEL_KNOWLEDGE_VERSION = "\n  UPDATE lt_knowledge_versions SET label = $3\n  WHERE domain = $1 AND key = $2 AND version = $4\n  RETURNING version";

package/build/system/activities/sql.js

@@ -8,7 +8,7 @@
 // no-op writes snapshot-free). Tags-only changes never bump — the version is
 // the data's identity.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APPEND_KNOWLEDGE = exports.REMOVE_KNOWLEDGE_FIELD = exports.SET_KNOWLEDGE_FIELD = exports.LIST_DOMAINS = exports.DELETE_KNOWLEDGE = exports.GET_KNOWLEDGE = exports.REPLACE_KNOWLEDGE = exports.UPSERT_KNOWLEDGE = void 0;
+exports.LABEL_KNOWLEDGE_VERSION = exports.APPEND_KNOWLEDGE = exports.REMOVE_KNOWLEDGE_FIELD = exports.SET_KNOWLEDGE_FIELD = exports.LIST_DOMAINS = exports.DELETE_KNOWLEDGE = exports.GET_KNOWLEDGE = exports.REPLACE_KNOWLEDGE = exports.UPSERT_KNOWLEDGE = void 0;
 // Upsert knowledge entry. On conflict (domain+key), merges JSONB data at
 // the top level — new keys are added, existing keys are overwritten.
 //
@@ -130,3 +130,8 @@ exports.APPEND_KNOWLEDGE = `
     ON CONFLICT (domain, key, version) DO NOTHING
   )
   SELECT id, domain, key, current_version, updated_at FROM upserted`;
+/** Name an edition: the label a lookup ref may pin instead of the number. A label names one edition of an entry. */
+exports.LABEL_KNOWLEDGE_VERSION = `
+  UPDATE lt_knowledge_versions SET label = $3
+  WHERE domain = $1 AND key = $2 AND version = $4
+  RETURNING version`;

package/build/system/index.js

@@ -60,6 +60,7 @@ const tool_manifests_workflows_1 = require("./seed/tool-manifests-workflows");
 const tool_manifests_admin_1 = require("./seed/tool-manifests-admin");
 const tool_manifests_knowledge_1 = require("./seed/tool-manifests-knowledge");
 const tool_manifests_events_1 = require("./seed/tool-manifests-events");
+const tool_manifests_machines_1 = require("./seed/tool-manifests-machines");
 // Example connectors — loaded conditionally (not in npm package)
 let GMAIL_TOOLS = [];
 try {
@@ -296,6 +297,18 @@ exports.builtinMcpServerFactories = {
             toolManifest: tool_manifests_data_1.SCHEMA_EXCHANGE_TOOLS,
         },
     },
+    'long-tail-machines': {
+        factory: () => Promise.resolve().then(() => __importStar(require('./mcp-servers/machines'))).then((m) => m.createMachinesServer()),
+        config: {
+            description: 'The machine surface: the lines index with health, a line as its leader sees it, a wire message dry run, machine-command rows, and the registry\'s declare and retire.',
+            tags: ['machines', 'lines', 'mqtt', 'factory'],
+            category: 'Data',
+            compileHints: 'list_machine_lines answers which lines need attention; get_machine_line reads one line. ' +
+                'send_machine_command parks a machine-command row that the gateway resolves with the machine\'s reply; ' +
+                'read the row to learn the outcome. declare_machine_line and retire_machine_line change the registry and need admin.',
+            toolManifest: tool_manifests_machines_1.MACHINE_TOOLS,
+        },
+    },
     'long-tail-events': {
         factory: () => Promise.resolve().then(() => __importStar(require('./mcp-servers/events'))).then((m) => m.createEventsServer()),
         config: {

package/build/system/mcp-servers/admin/schemas.d.ts

@@ -210,14 +210,14 @@ export declare const accumulateItemSchema: z.ZodObject<{
         key?: string | undefined;
         value?: string | undefined;
         id?: string | undefined;
-        signalKey?: string | undefined;
         payload?: Record<string, any> | undefined;
+        signalKey?: string | undefined;
     }, {
         key?: string | undefined;
         value?: string | undefined;
         id?: string | undefined;
-        signalKey?: string | undefined;
         payload?: Record<string, any> | undefined;
+        signalKey?: string | undefined;
     }>>;
     initiatedBy: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -229,8 +229,8 @@ export declare const accumulateItemSchema: z.ZodObject<{
         key?: string | undefined;
         value?: string | undefined;
         id?: string | undefined;
-        signalKey?: string | undefined;
         payload?: Record<string, any> | undefined;
+        signalKey?: string | undefined;
     } | undefined;
     initiatedBy?: string | undefined;
 }, {
@@ -242,8 +242,8 @@ export declare const accumulateItemSchema: z.ZodObject<{
         key?: string | undefined;
         value?: string | undefined;
         id?: string | undefined;
-        signalKey?: string | undefined;
         payload?: Record<string, any> | undefined;
+        signalKey?: string | undefined;
     } | undefined;
     initiatedBy?: string | undefined;
 }>;
@@ -1277,14 +1277,14 @@ export declare const applyThrottleSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     appId: string;
     throttle: number;
-    scope?: string | undefined;
     topic?: string | undefined;
+    scope?: string | undefined;
     guid?: string | undefined;
 }, {
     throttle: number;
+    topic?: string | undefined;
     appId?: string | undefined;
     scope?: string | undefined;
-    topic?: string | undefined;
     guid?: string | undefined;
 }>;
 export declare const getStreamStatsSchema: z.ZodObject<{
@@ -1320,10 +1320,10 @@ export declare const listStreamMessagesSchema: z.ZodObject<{
     offset: number;
     namespace: string;
     status?: string | undefined;
+    topic?: string | undefined;
     order?: "asc" | "desc" | undefined;
     sort_by?: string | undefined;
     workflow_name?: string | undefined;
-    topic?: string | undefined;
     jid?: string | undefined;
     stream_name?: string | undefined;
     msg_type?: string | undefined;
@@ -1331,12 +1331,12 @@ export declare const listStreamMessagesSchema: z.ZodObject<{
 }, {
     source: string;
     status?: string | undefined;
+    topic?: string | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
     order?: "asc" | "desc" | undefined;
     sort_by?: string | undefined;
     workflow_name?: string | undefined;
-    topic?: string | undefined;
     jid?: string | undefined;
     namespace?: string | undefined;
     stream_name?: string | undefined;
@@ -1396,12 +1396,12 @@ export declare const interruptJobSchema: z.ZodObject<{
     topic: z.ZodString;
     app_id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
+    topic: string;
     app_id: string;
     job_id: string;
-    topic: string;
 }, {
-    job_id: string;
     topic: string;
+    job_id: string;
     app_id?: string | undefined;
 }>;
 export declare const listTopicsSchema: z.ZodObject<{
@@ -1435,15 +1435,15 @@ export declare const createTopicSchema: z.ZodObject<{
     example_payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
-    category: string;
     topic: string;
+    category: string;
     description?: string | undefined;
     tags?: string[] | undefined;
     payload_schema?: Record<string, any> | undefined;
     example_payload?: Record<string, any> | undefined;
 }, {
-    category: string;
     topic: string;
+    category: string;
     description?: string | undefined;
     tags?: string[] | undefined;
     payload_schema?: Record<string, any> | undefined;
@@ -2989,8 +2989,8 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             requireActingIdentity: z.ZodOptional<z.ZodBoolean>;
             code: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            label: string;
             verb: "resolve" | "show-detail" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "hold";
+            label: string;
             code?: string | undefined;
             confirm?: {
                 prompt: string;
@@ -3041,8 +3041,8 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             } | undefined;
             requireActingIdentity?: boolean | undefined;
         }, {
-            label: string;
             verb: "resolve" | "show-detail" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "hold";
+            label: string;
             code?: string | undefined;
             confirm?: {
                 prompt: string;
@@ -3148,6 +3148,7 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             markdown: string;
         }>>;
     }, "strip", z.ZodTypeAny, {
+        verb: "resolve" | "show-detail" | "show-list" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "accumulate" | "present" | "hold" | "fill";
         query: {
             status?: "pending" | "resolved" | "cancelled" | undefined;
             roles?: string[] | undefined;
@@ -3156,15 +3157,14 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             subtypes?: string[] | undefined;
             availability?: "available" | "claimed" | "mine" | "any" | undefined;
         };
-        verb: "resolve" | "show-detail" | "show-list" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "accumulate" | "present" | "hold" | "fill";
         subject?: {
             schemes: number[];
             facets?: Record<string, string | number | boolean> | undefined;
             claimedByOther?: "refuse" | "allow" | undefined;
         } | undefined;
         choices?: {
-            label: string;
             verb: "resolve" | "show-detail" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "hold";
+            label: string;
             code?: string | undefined;
             confirm?: {
                 prompt: string;
@@ -3282,6 +3282,7 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
         }[] | undefined;
         autoSelectSingle?: boolean | undefined;
     }, {
+        verb: "resolve" | "show-detail" | "show-list" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "accumulate" | "present" | "hold" | "fill";
         query: {
             status?: "pending" | "resolved" | "cancelled" | undefined;
             roles?: string[] | undefined;
@@ -3290,15 +3291,14 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             subtypes?: string[] | undefined;
             availability?: "available" | "claimed" | "mine" | "any" | undefined;
         };
-        verb: "resolve" | "show-detail" | "show-list" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "accumulate" | "present" | "hold" | "fill";
         subject?: {
             schemes: number[];
             facets?: Record<string, string | number | boolean> | undefined;
             claimedByOther?: "refuse" | "allow" | undefined;
         } | undefined;
         choices?: {
-            label: string;
             verb: "resolve" | "show-detail" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "hold";
+            label: string;
             code?: string | undefined;
             confirm?: {
                 prompt: string;
@@ -3442,6 +3442,7 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
     category: string;
     scheme_version: number;
     steps: {
+        verb: "resolve" | "show-detail" | "show-list" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "accumulate" | "present" | "hold" | "fill";
         query: {
             status?: "pending" | "resolved" | "cancelled" | undefined;
             roles?: string[] | undefined;
@@ -3450,15 +3451,14 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             subtypes?: string[] | undefined;
             availability?: "available" | "claimed" | "mine" | "any" | undefined;
         };
-        verb: "resolve" | "show-detail" | "show-list" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "accumulate" | "present" | "hold" | "fill";
         subject?: {
             schemes: number[];
             facets?: Record<string, string | number | boolean> | undefined;
             claimedByOther?: "refuse" | "allow" | undefined;
         } | undefined;
         choices?: {
-            label: string;
             verb: "resolve" | "show-detail" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "hold";
+            label: string;
             code?: string | undefined;
             confirm?: {
                 prompt: string;
@@ -3590,6 +3590,7 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
     category: string;
     scheme_version: number;
     steps: {
+        verb: "resolve" | "show-detail" | "show-list" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "accumulate" | "present" | "hold" | "fill";
         query: {
             status?: "pending" | "resolved" | "cancelled" | undefined;
             roles?: string[] | undefined;
@@ -3598,15 +3599,14 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             subtypes?: string[] | undefined;
             availability?: "available" | "claimed" | "mine" | "any" | undefined;
         };
-        verb: "resolve" | "show-detail" | "show-list" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "accumulate" | "present" | "hold" | "fill";
         subject?: {
             schemes: number[];
             facets?: Record<string, string | number | boolean> | undefined;
             claimedByOther?: "refuse" | "allow" | undefined;
         } | undefined;
         choices?: {
-            label: string;
             verb: "resolve" | "show-detail" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "hold";
+            label: string;
             code?: string | undefined;
             confirm?: {
                 prompt: string;

package/build/system/mcp-servers/human-queue-schemas.d.ts

@@ -11,8 +11,8 @@ export declare const escalateSchema: z.ZodObject<{
     role: string;
     subtype: string;
     type: string;
-    priority: number;
     message: string;
+    priority: number;
     schema_version?: number | undefined;
     data?: Record<string, any> | undefined;
 }, {
@@ -69,12 +69,12 @@ export declare const resolveBatchItemSchema: z.ZodObject<{
     item_key: z.ZodString;
     payload: z.ZodRecord<z.ZodString, z.ZodAny>;
 }, "strip", z.ZodTypeAny, {
-    item_key: string;
     payload: Record<string, any>;
+    item_key: string;
     escalation_id: string;
 }, {
-    item_key: string;
     payload: Record<string, any>;
+    item_key: string;
     escalation_id: string;
 }>;
 export declare const accumulateItemSchema: z.ZodObject<{
@@ -91,14 +91,14 @@ export declare const accumulateItemSchema: z.ZodObject<{
         key?: string | undefined;
         value?: string | undefined;
         id?: string | undefined;
-        signalKey?: string | undefined;
         payload?: Record<string, any> | undefined;
+        signalKey?: string | undefined;
     }, {
         key?: string | undefined;
         value?: string | undefined;
         id?: string | undefined;
-        signalKey?: string | undefined;
         payload?: Record<string, any> | undefined;
+        signalKey?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
     item_key: string;
@@ -108,8 +108,8 @@ export declare const accumulateItemSchema: z.ZodObject<{
         key?: string | undefined;
         value?: string | undefined;
         id?: string | undefined;
-        signalKey?: string | undefined;
         payload?: Record<string, any> | undefined;
+        signalKey?: string | undefined;
     } | undefined;
 }, {
     item_key: string;
@@ -119,8 +119,8 @@ export declare const accumulateItemSchema: z.ZodObject<{
         key?: string | undefined;
         value?: string | undefined;
         id?: string | undefined;
-        signalKey?: string | undefined;
         payload?: Record<string, any> | undefined;
+        signalKey?: string | undefined;
     } | undefined;
 }>;
 export declare const removeItemSchema: z.ZodObject<{

package/build/system/mcp-servers/knowledge.js

@@ -45,11 +45,12 @@ const storeSchema = zod_1.z.object({
     field: zod_1.z.string().optional().describe('RECOMMENDED. Names a specific field to set within the entry (e.g. "2026-05-09", "url", "score"). Using field is additive — it merges into existing data without clobbering other fields. Without field, the entire data object is merged at the top level, which can overwrite existing fields with the same keys. Always use field when adding to an entry that may already have data.'),
     data: zod_1.z.any().describe('The value to store. When field is provided, this can be any type (string, number, boolean, object, array) and is stored as { [field]: data }. When field is omitted, data must be a JSON object whose keys merge into existing data.'),
     tags: zod_1.z.array(zod_1.z.string()).optional().describe('Categorization tags (unioned on upsert)'),
+    label: zod_1.z.string().min(1).optional().describe('A name for the edition this write leaves current; lookup refs may pin it as their version'),
 });
 const getSchema = zod_1.z.object({
     domain: zod_1.z.string().describe('Knowledge domain'),
     key: zod_1.z.string().describe('Document key'),
-    version: zod_1.z.number().int().min(1).optional().describe('Fetch this immutable edition instead of the live entry'),
+    version: zod_1.z.union([zod_1.z.number().int().min(1), zod_1.z.string().min(1)]).optional().describe('Fetch this immutable edition, by number or by the label it carries, instead of the live entry'),
 });
 const listVersionsSchema = zod_1.z.object({
     domain: zod_1.z.string().describe('Knowledge domain'),
@@ -90,6 +91,7 @@ const appendSchema = zod_1.z.object({
     key: zod_1.z.string().describe('Document key'),
     path: zod_1.z.string().describe('JSONB path to array field (e.g. "screenshots" or "analysis.variations")'),
     value: zod_1.z.any().refine((v) => v !== undefined, 'value is required').describe('Value to append to the array'),
+    label: zod_1.z.string().min(1).optional().describe('A name for the edition this write leaves current; lookup refs may pin it as their version'),
 });
 function registerTools(server) {
     server.registerTool('store_knowledge', {
@@ -124,7 +126,7 @@ function registerTools(server) {
             dataObj = args.data;
         }
         const result = await knowledge.storeKnowledge({
-            domain: args.domain, key: args.key, data: dataObj, tags: args.tags,
+            domain: args.domain, key: args.key, data: dataObj, tags: args.tags, label: args.label,
         });
         return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     });

package/build/system/mcp-servers/machines-schemas.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export declare const listMachineLinesSchema: {
+    q: z.ZodOptional<z.ZodString>;
+    site: z.ZodOptional<z.ZodString>;
+    attention: z.ZodOptional<z.ZodBoolean>;
+    sort: z.ZodOptional<z.ZodEnum<["attention", "site", "updated"]>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+};
+export declare const getMachineLineSchema: {
+    siteId: z.ZodString;
+    lineId: z.ZodString;
+};
+export declare const inspectMachineMessageSchema: {
+    topic: z.ZodString;
+    payload: z.ZodOptional<z.ZodAny>;
+    retained: z.ZodOptional<z.ZodBoolean>;
+    siteId: z.ZodString;
+    lineId: z.ZodString;
+};
+export declare const sendMachineCommandSchema: {
+    machineId: z.ZodString;
+    op: z.ZodString;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    siteId: z.ZodString;
+    lineId: z.ZodString;
+};
+export declare const declareMachineLineSchema: {
+    definition: z.ZodRecord<z.ZodString, z.ZodAny>;
+    version: z.ZodOptional<z.ZodNumber>;
+};
+export declare const retireMachineLineSchema: {
+    siteId: z.ZodString;
+    lineId: z.ZodString;
+};

package/build/system/mcp-servers/machines-schemas.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retireMachineLineSchema = exports.declareMachineLineSchema = exports.sendMachineCommandSchema = exports.inspectMachineMessageSchema = exports.getMachineLineSchema = exports.listMachineLinesSchema = void 0;
+const zod_1 = require("zod");
+/** Zod input schemas for the machines MCP server; the manifest mirrors them as JSON schema. */
+const siteLine = {
+    siteId: zod_1.z.string().min(1).describe('Site id'),
+    lineId: zod_1.z.string().min(1).describe('Line id'),
+};
+exports.listMachineLinesSchema = {
+    q: zod_1.z.string().optional().describe('Search site, line, machine ids, processes, roles and addresses'),
+    site: zod_1.z.string().optional().describe('Only this site'),
+    attention: zod_1.z.boolean().optional().describe('Only lines with an offline machine, an active alarm or a row waiting on a person'),
+    sort: zod_1.z.enum(['attention', 'site', 'updated']).optional().describe('attention first (default), site, or recently changed'),
+    limit: zod_1.z.number().int().min(1).max(200).optional(),
+    offset: zod_1.z.number().int().min(0).optional(),
+};
+exports.getMachineLineSchema = { ...siteLine };
+exports.inspectMachineMessageSchema = {
+    ...siteLine,
+    topic: zod_1.z.string().min(1).describe('The MQTT topic the message would arrive on'),
+    payload: zod_1.z.any().optional().describe('The message body: an object is serialized as JSON, a string passes through'),
+    retained: zod_1.z.boolean().optional().describe('Whether the broker would deliver it as retained'),
+};
+exports.sendMachineCommandSchema = {
+    ...siteLine,
+    machineId: zod_1.z.string().min(1).describe('The machine on the line'),
+    op: zod_1.z.string().min(1).describe('A control op, snapshot, or an op the line\'s codec declares'),
+    args: zod_1.z.record(zod_1.z.any()).optional().describe('Arguments the op takes, such as jobId or recipe'),
+};
+exports.declareMachineLineSchema = {
+    definition: zod_1.z.record(zod_1.z.any()).describe('The line definition: siteId, lineId, machines in route order (machineId, process, cycleSec), roles, addressing'),
+    version: zod_1.z.number().int().min(1).optional().describe('The version the row is expected to be at; a mismatch is a conflict'),
+};
+exports.retireMachineLineSchema = { ...siteLine };

package/build/system/mcp-servers/machines.d.ts

@@ -0,0 +1,20 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const MACHINES_SERVER_NAME = "long-tail-machines";
+export declare const MACHINE_TOOL: {
+    readonly LIST: "list_machine_lines";
+    readonly GET: "get_machine_line";
+    readonly INSPECT: "inspect_machine_message";
+    readonly COMMAND: "send_machine_command";
+    readonly DECLARE: "declare_machine_line";
+    readonly RETIRE: "retire_machine_line";
+};
+/**
+ * The machines MCP server: the Lines index and views, a message dry run,
+ * command rows, and the registry's declare and retire, for agents.
+ */
+export declare function createMachinesServer(options?: {
+    name?: string;
+    fresh?: boolean;
+}): Promise<McpServer>;
+export declare function getMachinesServer(): McpServer | null;
+export declare function stopMachinesServer(): Promise<void>;