@hotmeshio/long-tail 0.28.0 → 0.28.1

package/build/services/machines/gateway/state.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GatewayState = exports.ROW_END = exports.DISPATCH_STATE = void 0;
+const jobs_1 = require("./jobs");
 const project_1 = require("./project");
 const trace_1 = require("./trace");
 /**
@@ -44,6 +45,10 @@ class GatewayState {
         this.holdDispatch = false;
         /** Units at each machine that arrived and have not left: machine → unit → job. */
         this.held = new Map();
+        /** Jobs sent and taken, by machine: job → the row that sent it, kept while the machine holds the job's units. */
+        this.sentJobs = new Map();
+        /** Jobs whose units left each machine since its last snapshot: they ended, a snapshot without them lost nothing. */
+        this.endedJobs = new Map();
         this.openRows = new Map();
         this.closedRows = new Map();
         this.alarms = new Map();
@@ -75,13 +80,17 @@ class GatewayState {
         this.openRows.set(row.id, existing
             ? {
                 ...row, dispatch: existing.dispatch, trace: (0, trace_1.mergeTrace)(row.trace, existing.trace), arrivals: existing.arrivals,
-                dueAt: existing.dueAt, noted: existing.noted ?? row.noted,
+                dueAt: existing.dueAt, noted: existing.noted ?? row.noted, awaitingReady: existing.awaitingReady,
             }
             : row);
     }
     get(id) {
         return this.openRows.get(id);
     }
+    /** A row that ended, while the gateway still remembers it. */
+    closedRow(id) {
+        return this.closedRows.get(id);
+    }
     close(id, ended = exports.ROW_END.RESOLVED) {
         const row = this.openRows.get(id);
         if (!row)
@@ -115,7 +124,53 @@ class GatewayState {
         this.held.get(machineId).set(unitId, jobId);
     }
     letGo(machineId, unitId) {
-        this.held.get(machineId)?.delete(unitId);
+        const units = this.held.get(machineId);
+        const jobId = units?.get(unitId);
+        units?.delete(unitId);
+        if (jobId === undefined || [...units.values()].includes(jobId))
+            return;
+        this.sentJobs.get(machineId)?.delete(jobId);
+        if (!this.endedJobs.has(machineId))
+            this.endedJobs.set(machineId, new Set());
+        this.endedJobs.get(machineId).add(jobId);
+    }
+    /** A job the machine took, remembered by its row while the machine holds the job's units. */
+    rememberSent(machineId, jobId, rowId) {
+        if (!this.sentJobs.has(machineId))
+            this.sentJobs.set(machineId, new Map());
+        this.sentJobs.get(machineId).set(jobId, rowId);
+    }
+    /**
+     * After a restart, the jobs the machine lost: those its units are held under
+     * or its last snapshot listed, that the new snapshot lacks and no open row
+     * will send again. `resend` names the rows remembered for them; `unknown`
+     * the jobs nothing is remembered for.
+     */
+    lostAfterReboot(machineId, listed) {
+        const link = this.links.get(machineId);
+        const before = new Set(this.heldAt(machineId));
+        for (const job of link?.jobs ?? [])
+            if (typeof job?.jobId === 'string')
+                before.add(job.jobId);
+        const ended = this.endedJobs.get(machineId) ?? new Set();
+        const sendsAgain = new Set();
+        for (const row of this.openRows.values()) {
+            if (row.toMachine === machineId)
+                for (const job of (0, jobs_1.dispatchJobs)(row.jobId, row.units, this.unitsPerDispatch))
+                    sendsAgain.add(job.jobId);
+        }
+        const resend = [];
+        const unknown = [];
+        for (const jobId of before) {
+            if (listed.has(jobId) || ended.has(jobId) || sendsAgain.has(jobId))
+                continue;
+            const row = this.closedRows.get(this.sentJobs.get(machineId)?.get(jobId) ?? '');
+            if (row)
+                resend.push({ jobId, row });
+            else
+                unknown.push(jobId);
+        }
+        return { resend, unknown };
     }
     /** The job a unit arrived under at `machineId`, while it is still there. */
     heldJob(machineId, unitId) {
@@ -127,14 +182,18 @@ class GatewayState {
     heldUnitsAt(machineId) {
         return [...(this.held.get(machineId)?.entries() ?? [])].map(([unitId, jobId]) => ({ unitId, jobId }));
     }
-    /** Keep only units whose job the machine still lists (its snapshot). */
+    /** Keep only units whose job the machine still lists (its snapshot); a job it no longer lists is over. */
     keepHeld(machineId, jobIds) {
+        this.endedJobs.delete(machineId);
         const units = this.held.get(machineId);
         if (!units)
             return;
-        for (const [unitId, jobId] of units)
-            if (!jobIds.has(jobId))
-                units.delete(unitId);
+        for (const [unitId, jobId] of units) {
+            if (jobIds.has(jobId))
+                continue;
+            units.delete(unitId);
+            this.sentJobs.get(machineId)?.delete(jobId);
+        }
     }
     /** Keep a sender's finished record until its row is known, so an arrival cannot close the row without it. */
     rememberFinish(machineId, unitId, body) {
@@ -268,6 +327,8 @@ class GatewayState {
             retainedAlarms: this.retainedAlarms, readingRetained: this.readingRetained, takenAt: this.takenAt, progressStep: this.progressStep, holdDispatch: this.holdDispatch,
         });
         copyInto(this.held, copy.held, (units) => new Map(units));
+        copyInto(this.sentJobs, copy.sentJobs, (jobs) => new Map(jobs));
+        copyInto(this.endedJobs, copy.endedJobs, (jobs) => new Set(jobs));
         copyInto(this.openRows, copy.openRows, (row) => ({ ...row, units: [...row.units], ...(row.noted ? { noted: [...row.noted] } : {}) }));
         copyInto(this.closedRows, copy.closedRows, (row) => ({ ...row }));
         copyInto(this.alarms, copy.alarms, (track) => ({ ...track, ...(track.noted ? { noted: [...track.noted] } : {}) }));

package/build/services/machines/gateway/wire-window.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The last wire events of a line, kept by its leader so a client reads the
+ * tape over HTTP instead of the event stream. A ring of a fixed size; reads
+ * are newest first and may narrow by machine, direction, kind and time.
+ */
+import type { WireDirection, WireEvent, WireKind, WireWindowQuery } from '../../../types/machines-view';
+export declare const DEFAULT_WIRE_WINDOW = 500;
+export declare const MAX_WIRE_PAGE = 500;
+export declare class WireWindow {
+    readonly size: number;
+    private readonly events;
+    private head;
+    private count;
+    constructor(size?: number);
+    push(event: WireEvent): void;
+    /** Newest first, narrowed by the query, at most `limit` (the window's size when absent). */
+    read(query?: WireWindowQuery): WireEvent[];
+    get length(): number;
+}
+export declare function isWireDirection(v: unknown): v is WireDirection;
+export declare function isWireKind(v: unknown): v is WireKind;

package/build/services/machines/gateway/wire-window.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * The last wire events of a line, kept by its leader so a client reads the
+ * tape over HTTP instead of the event stream. A ring of a fixed size; reads
+ * are newest first and may narrow by machine, direction, kind and time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WireWindow = exports.MAX_WIRE_PAGE = exports.DEFAULT_WIRE_WINDOW = void 0;
+exports.isWireDirection = isWireDirection;
+exports.isWireKind = isWireKind;
+exports.DEFAULT_WIRE_WINDOW = 500;
+exports.MAX_WIRE_PAGE = 500;
+class WireWindow {
+    constructor(size = exports.DEFAULT_WIRE_WINDOW) {
+        this.size = size;
+        this.events = [];
+        this.head = 0;
+        this.count = 0;
+        if (!Number.isInteger(size) || size < 1)
+            throw new Error(`a wire window keeps at least one event (got ${size})`);
+    }
+    push(event) {
+        this.events[this.head] = event;
+        this.head = (this.head + 1) % this.size;
+        if (this.count < this.size)
+            this.count += 1;
+    }
+    /** Newest first, narrowed by the query, at most `limit` (the window's size when absent). */
+    read(query = {}) {
+        const limit = Math.min(Math.max(1, query.limit ?? this.size), exports.MAX_WIRE_PAGE);
+        const out = [];
+        for (let i = 1; i <= this.count && out.length < limit; i++) {
+            const event = this.events[(this.head - i + this.size) % this.size];
+            if (matches(event, query))
+                out.push(event);
+        }
+        return out;
+    }
+    get length() {
+        return this.count;
+    }
+}
+exports.WireWindow = WireWindow;
+function matches(event, q) {
+    if (q.machine && event.machineId !== q.machine)
+        return false;
+    if (q.direction && event.direction !== q.direction)
+        return false;
+    if (q.kind && event.kind !== q.kind)
+        return false;
+    if (q.since && event.at <= q.since)
+        return false;
+    return true;
+}
+function isWireDirection(v) {
+    return v === 'in' || v === 'out';
+}
+const KINDS = ['presence', 'snapshot', 'job', 'alarm', 'telemetry', 'report', 'cmd', 'reply', 'receipt', 'unknown'];
+function isWireKind(v) {
+    return typeof v === 'string' && KINDS.includes(v);
+}

package/build/services/machines/gateway/wire.js

@@ -165,6 +165,7 @@ function plannedAction(a) {
         case 'watchOffline': return { verb: 'none', detail: `watching ${a.machineId} for an offline row` };
         case 'settleReply': return { verb: 'ack', detail: `${a.status} ${a.cmdId}` };
         case 'settleSnapshot': return { verb: 'ack', detail: `${a.machineId} holds ${count(a.jobIds.length, 'job')}` };
+        case 'unrecoverable': return { verb: 'none', detail: `${a.machineId} lost ${a.jobs.join(', ')}; nothing remembered to send again` };
         case 'bindAddress': return { verb: 'ack', detail: `bind ${a.machineId} to ${a.address}` };
         case 'refuseBinding': return { verb: 'refuse', detail: a.reason };
     }

package/build/services/machines/roles.d.ts

@@ -1,10 +1,11 @@
 /**
  * The roles a line needs, as code-owned role declarations: one station role
  * per process (a machine resolves the handoffs into it), the exit role (a
- * person receives finished units) and the operator role (a person decides
- * failed handoffs and closes alarm and machine rows). Each role owns its
- * form; only the operator role enforces it on the server, because handoff
- * rows also collect machine records the gateway already validates.
+ * person receives finished units), the operator role (a person decides
+ * failed handoffs and closes alarm and machine rows) and the quality role
+ * (a person decides units finished on hold). Each role owns its form; the
+ * operator and quality roles enforce it on the server, since handoff rows
+ * also collect machine records the gateway already validates.
  */
 import type { LTRoleConfig } from '../../types/startup';
 import { type LineDef } from '../../lib/machines/line';

package/build/services/machines/roles.js

@@ -2,10 +2,11 @@
 /**
  * The roles a line needs, as code-owned role declarations: one station role
  * per process (a machine resolves the handoffs into it), the exit role (a
- * person receives finished units) and the operator role (a person decides
- * failed handoffs and closes alarm and machine rows). Each role owns its
- * form; only the operator role enforces it on the server, because handoff
- * rows also collect machine records the gateway already validates.
+ * person receives finished units), the operator role (a person decides
+ * failed handoffs and closes alarm and machine rows) and the quality role
+ * (a person decides units finished on hold). Each role owns its form; the
+ * operator and quality roles enforce it on the server, since handoff rows
+ * also collect machine records the gateway already validates.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.machineRoleConfigs = machineRoleConfigs;
@@ -44,6 +45,14 @@ function machineRoleConfigs(line) {
             enforce_schema: true,
             ...BOARD,
         },
+        {
+            role: (0, line_1.qualityRole)(line),
+            title: 'Line quality',
+            description: 'Units a machine finished on hold: release, rework or scrap.',
+            form_schema: forms_1.QUALITY_FORM_SCHEMA,
+            enforce_schema: true,
+            ...BOARD,
+        },
     ];
 }
 /** The host's declarations first; line roles only where the host declared none. */

package/build/services/machines/select.d.ts

@@ -16,9 +16,10 @@ export type LineMessaging = Pick<typeof messagingRegistry, 'streams' | 'pubsub'>
 /**
  * The gateway's view of every machine on the line. With `nats`, events are read
  * from Long Tail's messaging streams; MACHINE_SITE_NATS_URL instead names a NATS
- * server of the site's own, which the bus connects to itself.
+ * server of the site's own, which the bus connects to itself. `siteCodecs` are
+ * the codecs of every line on the site, so the streams keep all their subjects.
  */
-export declare function createMachineBus(config: MachineLineConfig, line: LineDef, codec?: LineCodec, messaging?: LineMessaging): MachineBus;
+export declare function createMachineBus(config: MachineLineConfig, line: LineDef, codec?: LineCodec, messaging?: LineMessaging, siteCodecs?: LineCodec[]): MachineBus;
 /** Long Tail's escalation events for the gateway; `in-process` needs the running instance's callback adapter. */
 export declare function createEscalationFeed(config: MachineLineConfig, line: LineDef, callbacks?: CallbackEventAdapter): EscalationFeed;
 /** One MQTT link per simulated machine; machines speak MQTT in every networked mode. */

package/build/services/machines/select.js

@@ -33,12 +33,13 @@ function defaultCodec(config, line) {
 /**
  * The gateway's view of every machine on the line. With `nats`, events are read
  * from Long Tail's messaging streams; MACHINE_SITE_NATS_URL instead names a NATS
- * server of the site's own, which the bus connects to itself.
+ * server of the site's own, which the bus connects to itself. `siteCodecs` are
+ * the codecs of every line on the site, so the streams keep all their subjects.
  */
-function createMachineBus(config, line, codec = defaultCodec(config, line), messaging = messaging_1.messagingRegistry) {
+function createMachineBus(config, line, codec = defaultCodec(config, line), messaging = messaging_1.messagingRegistry, siteCodecs = []) {
     switch (config.transport) {
         case config_1.MACHINE_TRANSPORT.NATS: {
-            const where = { mqtt: mqttOf(config), controllerId: (0, line_1.controllerId)(line), siteId: line.siteId, lineId: line.lineId, codec };
+            const where = { mqtt: mqttOf(config), controllerId: (0, line_1.controllerId)(line), siteId: line.siteId, lineId: line.lineId, codec, siteCodecs };
             if (config.siteNatsUrl) {
                 return new nats_bus_1.NatsMachineBus({ natsUrl: config.siteNatsUrl, user: config.siteNatsUser, password: config.siteNatsPassword, ...where });
             }

package/build/services/machines/surface.d.ts

@@ -11,7 +11,7 @@ import type { CallbackEventAdapter } from '../../lib/events/callback';
 import { type LineDef } from '../../lib/machines/line';
 import { type LineCodec } from '../../lib/machines/protocol';
 import type { InboundMessage } from '../../lib/machines/transport';
-import type { InspectResult, LineSummary, LineView } from '../../types/machines-view';
+import type { InspectResult, LineSummary, LineView, WireEvent, WireWindowQuery } from '../../types/machines-view';
 import { type MachineLineConfig } from './config';
 import { type GatewayLog } from './gateway/log';
 import type { HandoffRowAdapter } from './rows';
@@ -23,8 +23,12 @@ export interface MachineSurfaceOptions {
     callbacks?: CallbackEventAdapter;
     log?: GatewayLog;
     codec?: LineCodec;
+    /** A codec for one line, keyed `<siteId>/<lineId>`; every other line uses `codec`. */
+    codecs?: Record<string, LineCodec>;
     rows?: HandoffRowAdapter;
 }
+/** The codec a line runs on: its own, the surface's, or the generic line protocol. */
+export declare function codecFor(opts: Pick<MachineSurfaceOptions, 'codec' | 'codecs'>, config: MachineLineConfig, line: LineDef): LineCodec;
 /** A message to dry-run against a line. */
 export type WireProbe = Pick<InboundMessage, 'topic' | 'payload' | 'retained'>;
 /** What settings and the API read of the surface. */
@@ -35,6 +39,8 @@ export interface LineSurface {
     describeLine(siteId: string, lineId: string): LineView | null;
     /** A dry run of one message; null when this replica is not leading the line. */
     inspect(siteId: string, lineId: string, probe: WireProbe): InspectResult | null;
+    /** The leader's last wire events, newest first; null when this replica is not leading the line. */
+    wire(siteId: string, lineId: string, query?: WireWindowQuery): WireEvent[] | null;
     /** The declared line, or undefined. */
     findLine(siteId: string, lineId: string): LineDef | undefined;
     /** The ops a machine-command row on this line may ask for. */
@@ -65,8 +71,11 @@ export declare class MachineSurface implements LineSurface {
     describeLines(): LineSummary[];
     describeLine(siteId: string, lineId: string): LineView | null;
     inspect(siteId: string, lineId: string, probe: WireProbe): InspectResult | null;
+    wire(siteId: string, lineId: string, query?: WireWindowQuery): WireEvent[] | null;
     findLine(siteId: string, lineId: string): LineDef | undefined;
     commandOps(siteId: string, lineId: string): string[];
+    /** The codecs every line on a site runs, so one site's streams keep all their subjects. */
+    codecsOnSite(siteId: string): LineCodec[];
     private begin;
     private run;
 }

package/build/services/machines/surface.js

@@ -10,6 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MachineSurface = void 0;
+exports.codecFor = codecFor;
 exports.surfaceConfig = surfaceConfig;
 exports.summarizeLine = summarizeLine;
 exports.commandOpsOf = commandOpsOf;
@@ -23,6 +24,10 @@ const log_1 = require("./gateway/log");
 const identities_1 = require("./identities");
 const leadership_1 = require("./leadership");
 const select_1 = require("./select");
+/** The codec a line runs on: its own, the surface's, or the generic line protocol. */
+function codecFor(opts, config, line) {
+    return opts.codecs?.[keyOf(line.siteId, line.lineId)] ?? opts.codec ?? (0, select_1.defaultCodec)(config, line);
+}
 /** Inside Long Tail the gateway reads escalation events in process. */
 function surfaceConfig(env) {
     const transport = env.MACHINE_TRANSPORT;
@@ -51,15 +56,18 @@ function commandOpsOf(codec) {
     return [...new Set([...protocol_1.CONTROL_OPS, protocol_1.OP.SNAPSHOT, ...(0, protocol_1.declaredRowOps)(codec)])];
 }
 class LineRun {
-    constructor(line, config, opts, log) {
+    constructor(line, config, opts, log, 
+    /** The codecs of every line on this line's site, read when the gateway starts. */
+    siteCodecs = () => []) {
         this.line = line;
         this.config = config;
         this.opts = opts;
         this.log = log;
+        this.siteCodecs = siteCodecs;
         this.ready = false;
         this.stopped = false;
         this.leadership = new leadership_1.LineLeadership(`lt-machine-line:${line.siteId}/${line.lineId}`);
-        this.codec = opts.codec ?? (0, select_1.defaultCodec)(config, line);
+        this.codec = codecFor(opts, config, line);
     }
     start() {
         const where = { site: this.line.siteId, line: this.line.lineId };
@@ -96,7 +104,7 @@ class LineRun {
         };
         const { config, line, codec } = this;
         this.gateway = new gateway_1.MachineGateway({
-            bus: (0, select_1.createMachineBus)(config, line, codec),
+            bus: (0, select_1.createMachineBus)(config, line, codec, undefined, this.siteCodecs()),
             codec,
             rows: this.opts.rows,
             feed: (0, select_1.createEscalationFeed)(config, line, this.opts.callbacks),
@@ -108,6 +116,7 @@ class LineRun {
                 topicRoot: config.topicRoot, replyTimeoutMs: config.replyTimeoutMs, dispatchAttempts: config.dispatchAttempts,
                 offlineDebounceMs: config.offlineDebounceMs, dispatchTtlMs: config.dispatchTtlMs, quietMs: config.quietMs,
                 receiptDelayMs: config.receiptDelayMs, lifecycle: config.lifecycle, progressStep: config.progressStep, wireTelemetry: config.wireTelemetry,
+                wireWindow: config.wireWindow,
             },
         });
         await this.gateway.start();
@@ -162,6 +171,9 @@ class MachineSurface {
     inspect(siteId, lineId, probe) {
         return this.run(siteId, lineId)?.leader()?.inspect(probe) ?? null;
     }
+    wire(siteId, lineId, query = {}) {
+        return this.run(siteId, lineId)?.leader()?.window.read(query) ?? null;
+    }
     findLine(siteId, lineId) {
         return this.run(siteId, lineId)?.line;
     }
@@ -169,8 +181,12 @@ class MachineSurface {
         const run = this.run(siteId, lineId);
         return run ? commandOpsOf(run.codec) : [];
     }
+    /** The codecs every line on a site runs, so one site's streams keep all their subjects. */
+    codecsOnSite(siteId) {
+        return [...new Set([...this.runs.values()].filter((run) => run.line.siteId === siteId).map((run) => run.codec))];
+    }
     begin(line) {
-        const run = new LineRun(line, this.config, this.opts, (0, log_1.composeLogs)(this.log, (0, log_1.eventsLog)(line)));
+        const run = new LineRun(line, this.config, this.opts, (0, log_1.composeLogs)(this.log, (0, log_1.eventsLog)(line)), () => this.codecsOnSite(line.siteId));
         this.runs.set(keyOf(line.siteId, line.lineId), run);
         run.start();
     }

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/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) }] };
     });