@hotmeshio/long-tail 0.28.0 → 0.28.2

package/build/lib/messaging/nats/streams.js

@@ -1,20 +1,27 @@
 "use strict";
 /**
  * Durable streams on JetStream. A spec becomes a file-backed stream or an
- * explicit-ack durable consumer; ensuring either is safe on every boot, and an
- * existing consumer keeps its position while its subjects follow the spec.
+ * explicit-ack durable consumer; ensuring either is safe on every boot and
+ * from several lines at once. An existing consumer keeps its position while
+ * its subjects match the spec; one whose subjects changed is made again, since
+ * a position in another protocol's messages means nothing to this one.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NatsStreams = void 0;
 exports.streamConfig = streamConfig;
 exports.consumerConfig = consumerConfig;
 exports.ensureStream = ensureStream;
+exports.describeStream = describeStream;
 exports.ensureConsumer = ensureConsumer;
+exports.describeConsumer = describeConsumer;
 exports.payloadOf = payloadOf;
 const nats_1 = require("nats");
 const constants_1 = require("../constants");
 const DEFAULT_ACK_WAIT_MS = 30_000;
 const DEFAULT_NAK_DELAY_MS = 1_000;
+/** Consumer events after which the consumer delivers nothing more: its stream or itself is gone, or the server fell silent. */
+const CONSUMER_LOST = new Set(['consumer_deleted', 'consumer_not_found', 'stream_not_found', 'heartbeats_missed']);
+const sameSubjects = (a = [], b = []) => [...a].sort().join('|') === [...b].sort().join('|');
 function streamConfig(spec) {
     return { name: spec.name, subjects: spec.subjects, max_age: (0, nats_1.nanos)(spec.maxAgeMs), storage: nats_1.StorageType.File };
 }
@@ -27,7 +34,11 @@ function consumerConfig(spec) {
         filter_subjects: spec.filterSubjects,
     };
 }
-/** Create the stream, or update an existing one to the spec. */
+/**
+ * Create the stream, or update an existing one to the spec. Two lines may
+ * ensure the same stream at once: the create that loses the race finds the
+ * stream in use and updates it instead.
+ */
 async function ensureStream(jsm, spec) {
     const config = streamConfig(spec);
     try {
@@ -36,12 +47,35 @@ async function ensureStream(jsm, spec) {
     catch (err) {
         if (!/stream not found/i.test(err?.message ?? ''))
             throw err;
-        await jsm.streams.add(config);
-        return;
+        try {
+            await jsm.streams.add(config);
+            return;
+        }
+        catch (added) {
+            if (!/already in use/i.test(added?.message ?? ''))
+                throw added;
+        }
     }
     await jsm.streams.update(spec.name, config);
 }
-/** Create the consumer, or move an existing one to the spec's subjects without losing its place. */
+/** The stream as JetStream holds it, or null when there is none. */
+async function describeStream(jsm, name) {
+    try {
+        const info = await jsm.streams.info(name);
+        return { name, subjects: info.config.subjects ?? [], maxAgeMs: Math.round((info.config.max_age ?? 0) / 1_000_000) };
+    }
+    catch (err) {
+        if (/stream not found/i.test(err?.message ?? ''))
+            return null;
+        throw err;
+    }
+}
+/**
+ * Create the consumer, or keep an existing one whose subjects match the spec,
+ * position and all. One whose subjects differ is deleted and made again at
+ * the stream's newest message, since its old position was in another
+ * protocol's messages.
+ */
 async function ensureConsumer(jsm, stream, spec) {
     let existing;
     try {
@@ -53,10 +87,22 @@ async function ensureConsumer(jsm, stream, spec) {
         await jsm.consumers.add(stream, consumerConfig(spec));
         return;
     }
-    const want = [...spec.filterSubjects].sort();
-    const have = [...(existing.config.filter_subjects ?? [])].sort();
-    if (want.join('|') !== have.join('|'))
-        await jsm.consumers.update(stream, spec.name, { filter_subjects: spec.filterSubjects });
+    if (sameSubjects(spec.filterSubjects, existing.config.filter_subjects))
+        return;
+    await jsm.consumers.delete(stream, spec.name);
+    await jsm.consumers.add(stream, consumerConfig(spec));
+}
+/** The consumer as JetStream holds it, or null when there is none. */
+async function describeConsumer(jsm, stream, name) {
+    try {
+        const info = await jsm.consumers.info(stream, name);
+        return { name, filterSubjects: info.config.filter_subjects ?? (info.config.filter_subject ? [info.config.filter_subject] : []) };
+    }
+    catch (err) {
+        if (/consumer not found|stream not found/i.test(err?.message ?? ''))
+            return null;
+        throw err;
+    }
 }
 function payloadOf(m) {
     return Buffer.from(m.data).toString('utf8');
@@ -72,6 +118,12 @@ class NatsStreams {
     ensureConsumer(stream, spec) {
         return ensureConsumer(this.jsm, stream, spec);
     }
+    describeStream(name) {
+        return describeStream(this.jsm, name);
+    }
+    describeConsumer(stream, name) {
+        return describeConsumer(this.jsm, stream, name);
+    }
     async append(subject, payload) {
         await this.js.publish(subject, payload);
     }
@@ -79,6 +131,15 @@ class NatsStreams {
     async consume(stream, consumer, handler, opts = {}) {
         const nakDelayMs = opts.nakDelayMs ?? DEFAULT_NAK_DELAY_MS;
         const messages = await (await this.js.consumers.get(stream, consumer)).consume();
+        // The consumer's own status: once its stream or itself is gone, or the server fell silent, the reader is told.
+        void (async () => {
+            for await (const status of await messages.status()) {
+                if (!CONSUMER_LOST.has(String(status.type)))
+                    continue;
+                opts.onLost?.(String(status.type));
+                return;
+            }
+        })().catch(() => { });
         void (async () => {
             for await (const m of messages) {
                 const delivery = await handler({ subject: m.subject, payload: payloadOf(m), deliveries: m.info.deliveryCount })

package/build/lib/storage/local.d.ts

@@ -32,10 +32,12 @@ export declare class LocalStorageBackend implements StorageBackend {
         directories: string[];
         nextToken?: string;
     }>;
+    /** The digest is read from the file itself, so it is always the stored bytes' own. */
     getMetadata(key: string): Promise<{
         size: number;
         modified_at: string;
         content_type: string;
+        sha256: string;
     }>;
     getSignedUrl(key: string, expiresInSeconds: number): Promise<string>;
 }

package/build/lib/storage/local.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalStorageBackend = void 0;
+const crypto_1 = require("crypto");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
@@ -168,6 +169,7 @@ class LocalStorageBackend {
             nextToken: hasMore ? String(offset + limit) : undefined,
         };
     }
+    /** The digest is read from the file itself, so it is always the stored bytes' own. */
     async getMetadata(key) {
         const resolved = resolveAndValidate(key);
         if (!fs.existsSync(resolved)) {
@@ -178,6 +180,7 @@ class LocalStorageBackend {
             size: stat.size,
             modified_at: stat.mtime.toISOString(),
             content_type: (0, mime_1.mimeFromPath)(key),
+            sha256: (0, crypto_1.createHash)('sha256').update(fs.readFileSync(resolved)).digest('hex'),
         };
     }
     async getSignedUrl(key, expiresInSeconds) {

package/build/lib/storage/s3.d.ts

@@ -1,4 +1,4 @@
-import type { StorageBackend } from './types';
+import type { StorageBackend, WriteOptions } from './types';
 export declare class S3StorageBackend implements StorageBackend {
     private client;
     private signingClient;
@@ -6,7 +6,7 @@ export declare class S3StorageBackend implements StorageBackend {
     private bucketReady;
     constructor();
     private ensureBucket;
-    write(key: string, data: Buffer): Promise<{
+    write(key: string, data: Buffer, options?: WriteOptions): Promise<{
         ref: string;
         size: number;
     }>;
@@ -42,6 +42,7 @@ export declare class S3StorageBackend implements StorageBackend {
         size: number;
         modified_at: string;
         content_type: string;
+        sha256?: string;
     }>;
     getSignedUrl(key: string, expiresInSeconds: number): Promise<string>;
 }

package/build/lib/storage/s3.js

@@ -39,6 +39,8 @@ const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const client_s3_1 = require("@aws-sdk/client-s3");
 const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
+/** The object metadata key the digest is kept under. */
+const SHA256_METADATA = 'sha256';
 const mime_1 = require("./mime");
 const STAGING_DIR = path.join(os.tmpdir(), 'lt-staging');
 class S3StorageBackend {
@@ -91,12 +93,13 @@ class S3StorageBackend {
             }
         }
     }
-    async write(key, data) {
+    async write(key, data, options) {
         await this.bucketReady;
         await this.client.send(new client_s3_1.PutObjectCommand({
             Bucket: this.bucket,
             Key: normalizeKey(key),
             Body: data,
+            ...(options?.sha256 ? { Metadata: { [SHA256_METADATA]: options.sha256 } } : {}),
         }));
         return { ref: key, size: data.length };
     }
@@ -222,10 +225,12 @@ class S3StorageBackend {
             Bucket: this.bucket,
             Key: normalizeKey(key),
         }));
+        const sha256 = resp.Metadata?.[SHA256_METADATA];
         return {
             size: resp.ContentLength || 0,
             modified_at: resp.LastModified?.toISOString() || new Date().toISOString(),
             content_type: resp.ContentType || (0, mime_1.mimeFromPath)(key),
+            ...(sha256 ? { sha256 } : {}),
         };
     }
     async getSignedUrl(key, expiresInSeconds) {

package/build/lib/storage/types.d.ts

@@ -1,6 +1,10 @@
+export interface WriteOptions {
+    /** The SHA-256 of `data`, hex, kept with the object. */
+    sha256?: string;
+}
 export interface StorageBackend {
     /** Write data to storage. Returns the key and size. */
-    write(key: string, data: Buffer): Promise<{
+    write(key: string, data: Buffer, options?: WriteOptions): Promise<{
         ref: string;
         size: number;
     }>;
@@ -53,6 +57,8 @@ export interface StorageBackend {
         size: number;
         modified_at: string;
         content_type: string;
+        /** The object's SHA-256, hex, when the backend knows it. */
+        sha256?: string;
     }>;
     /** Generate a time-limited signed URL for unauthenticated file access. */
     getSignedUrl(key: string, expiresInSeconds: number): Promise<string>;

package/build/routes/file-browser.js

@@ -128,6 +128,7 @@ router.get('/download/{*filePath}', auth_1.requireBuilder, async (req, res) => {
  * POST /api/file-browser/upload
  * Upload a file to storage.
  * Query: ?path=images/photo.png (target path including filename)
+ *        &sha256=<hex> (optional; the upload is refused with 422 when the bytes differ)
  * Body: raw file bytes (Content-Type should match the file type)
  */
 router.post('/upload', auth_1.requireBuilder, async (req, res) => {
@@ -146,7 +147,8 @@ router.post('/upload', auth_1.requireBuilder, async (req, res) => {
                 res.status(400).json({ error: 'Empty file body' });
                 return;
             }
-            const result = await api.uploadFile({ path: targetPath, buffer });
+            const sha256 = typeof req.query.sha256 === 'string' ? req.query.sha256 : undefined;
+            const result = await api.uploadFile({ path: targetPath, buffer, sha256 });
             res.status(result.status).json(result.data ?? { error: result.error });
         }
         catch (err) {

package/build/routes/knowledge.js

@@ -74,8 +74,8 @@ router.get('/entries', async (req, res) => {
 /**
  * GET /api/knowledge/entry
  * Get a single knowledge entry — the live edition, or an immutable snapshot
- * when ?version=N is present.
- * Query: ?domain=...&key=...&version=N
+ * when ?version=N (or ?version=<label>) is present.
+ * Query: ?domain=...&key=...&version=N|label
  */
 router.get('/entry', async (req, res) => {
     const domain = req.query.domain;
@@ -85,9 +85,10 @@ router.get('/entry', async (req, res) => {
         return;
     }
     if (req.query.version !== undefined) {
-        const version = Number(req.query.version);
-        if (!Number.isInteger(version) || version < 1) {
-            res.status(400).json({ error: 'version must be a positive integer' });
+        const raw = String(req.query.version);
+        const version = /^[1-9][0-9]*$/.test(raw) ? Number(raw) : raw;
+        if (version === '' || version === 'current') {
+            res.status(400).json({ error: 'version must be a positive integer or an edition label' });
             return;
         }
         const result = await api.getEntryVersion({ domain, key, version });

package/build/routes/machines.js

@@ -42,6 +42,8 @@ const registry_1 = require("../services/machines/registry");
 const registry_sync_1 = require("../services/machines/registry-sync");
 const line_index_1 = require("../services/machines/line-index");
 const topics_1 = require("../lib/machines/protocol/topics");
+const browser_view_1 = require("../lib/events/browser-view");
+const wire_window_1 = require("../services/machines/gateway/wire-window");
 const router = (0, http_1.Router)();
 /**
  * The machine surface for the dashboard's Lines view. Reads and the dry run
@@ -170,6 +172,37 @@ router.get('/lines/:siteId/:lineId', auth_1.requireRoleManager, (req, res) => {
     };
     res.status(200).json(body);
 });
+/** The event as this viewer reads it: builders see the payload, everyone else the record without it. */
+function wireForViewer(event, builder) {
+    if (builder)
+        return event;
+    const { payload: _payload, ...rest } = event;
+    return rest;
+}
+router.get('/lines/:siteId/:lineId/wire', auth_1.requireRoleManager, async (req, res) => {
+    const { surface, siteId, lineId, line } = lineOf(req);
+    if (!surface || !line) {
+        res.status(404).json({ error: surface ? `no line ${siteId}/${lineId}` : NO_LINES });
+        return;
+    }
+    const { direction, kind } = req.query;
+    if (direction !== undefined && !(0, wire_window_1.isWireDirection)(direction)) {
+        res.status(400).json({ error: 'direction must be in or out' });
+        return;
+    }
+    if (kind !== undefined && !(0, wire_window_1.isWireKind)(kind)) {
+        res.status(400).json({ error: 'kind is not a wire kind' });
+        return;
+    }
+    const query = {
+        limit: queryInt(req.query.limit), machine: queryString(req.query.machine), since: queryString(req.query.since),
+        ...(direction !== undefined ? { direction } : {}), ...(kind !== undefined ? { kind } : {}),
+    };
+    const events = surface.wire(siteId, lineId, query);
+    const viewer = await (0, browser_view_1.viewerFor)(req.auth?.userId);
+    const body = { siteId, lineId, leading: events !== null, events: (events ?? []).map((e) => wireForViewer(e, viewer.builder)) };
+    res.status(200).json(body);
+});
 router.post('/lines/:siteId/:lineId/inspect', auth_1.requireRoleManager, (req, res) => {
     const { surface, siteId, lineId, line } = lineOf(req);
     if (!surface || !line) {

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

@@ -2,15 +2,17 @@ export * from './lookup-cache';
 export * from './lookup-refs';
 export interface KnowledgeVersionMeta {
     version: number;
+    label: string | null;
     change_summary: string | null;
     created_at: string;
     is_current: boolean;
 }
-/** The immutable snapshot at (domain, key, version), uncached full shape. */
-export declare function getKnowledgeVersion(domain: string, key: string, version: number): Promise<{
+/** The immutable snapshot at (domain, key, version), by number or by the edition's label; uncached full shape. */
+export declare function getKnowledgeVersion(domain: string, key: string, version: number | string): Promise<{
     domain: string;
     key: string;
     version: number;
+    label: string | null;
     data: Record<string, unknown>;
     tags: string[];
     created_at: string;

package/build/services/knowledge/index.js

@@ -22,19 +22,24 @@ exports.listKnowledgeVersions = listKnowledgeVersions;
  * writes produce, and resolves escalation lookup refs against them.
  */
 const db_1 = require("../../lib/db");
+const lookup_cache_1 = require("./lookup-cache");
 const sql_1 = require("./sql");
 __exportStar(require("./lookup-cache"), exports);
 __exportStar(require("./lookup-refs"), exports);
-/** The immutable snapshot at (domain, key, version), uncached full shape. */
+/** The immutable snapshot at (domain, key, version), by number or by the edition's label; uncached full shape. */
 async function getKnowledgeVersion(domain, key, version) {
     const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.GET_KNOWLEDGE_VERSION, [domain, key, version]);
+    const number = typeof version === 'string' ? await (0, lookup_cache_1.editionOfLabel)(domain, key, version) : version;
+    if (number === null)
+        return null;
+    const { rows } = await pool.query(sql_1.GET_KNOWLEDGE_VERSION, [domain, key, number]);
     if (!rows[0])
         return null;
     return {
         domain: rows[0].domain,
         key: rows[0].key,
         version: rows[0].version,
+        label: rows[0].label ?? null,
         data: rows[0].data ?? {},
         tags: rows[0].tags ?? [],
         created_at: rows[0].created_at.toISOString(),
@@ -46,6 +51,7 @@ async function listKnowledgeVersions(domain, key) {
     const { rows } = await pool.query(sql_1.LIST_KNOWLEDGE_VERSIONS, [domain, key]);
     return rows.map((r) => ({
         version: r.version,
+        label: r.label ?? null,
         change_summary: r.change_summary ?? null,
         created_at: r.created_at.toISOString(),
         is_current: r.is_current === true,

package/build/services/knowledge/lookup-cache.d.ts

@@ -10,6 +10,8 @@ export interface ResolvedLookup {
     version: number | null;
     /** The ref follows the newest edition rather than pinning one. */
     current?: true;
+    /** The ref pins an edition by this label. */
+    label?: string;
     as?: string;
     data: Record<string, unknown> | null;
     missing?: boolean;
@@ -25,6 +27,12 @@ export declare function resolveRefEdition(ref: EscalationLookupRef, asOf?: strin
     version: number;
     snapshot: KnowledgeSnapshot;
 } | null>;
+/**
+ * The edition a label names, or, for a label that is a whole number no edition
+ * carries, that edition's number. Null when the label names nothing; that is
+ * never cached, so a label given later becomes visible.
+ */
+export declare function editionOfLabel(domain: string, key: string, label: string): Promise<number | null>;
 /**
  * Resolve a metadata `lookups` array into the form-context `lookup` domain:
  * { [as ?? key]: data }. Returns null when there is nothing to resolve, so

package/build/services/knowledge/lookup-cache.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getKnowledgeSnapshot = getKnowledgeSnapshot;
 exports.resolveRefEdition = resolveRefEdition;
+exports.editionOfLabel = editionOfLabel;
 exports.resolveLookupContext = resolveLookupContext;
 exports.resolveLookupRefs = resolveLookupRefs;
 /**
@@ -18,6 +19,8 @@ const sql_1 = require("./sql");
 const SNAPSHOT_CACHE_MAX_ENTRIES = 256;
 // Map preserves insertion order — delete+set on read keeps it LRU.
 const snapshotCache = new Map();
+// A label names one edition for good, so the number it resolves to is kept too.
+const labelCache = new Map();
 function remember(cacheKey, snapshot) {
     snapshotCache.set(cacheKey, snapshot);
     while (snapshotCache.size > SNAPSHOT_CACHE_MAX_ENTRIES) {
@@ -52,7 +55,9 @@ async function getKnowledgeSnapshot(domain, key, version) {
  */
 async function resolveRefEdition(ref, asOf) {
     if (!(0, escalation_1.isCurrentLookupRef)(ref)) {
-        const version = ref.version;
+        const version = (0, escalation_1.isLabelLookupRef)(ref) ? await editionOfLabel(ref.domain, ref.key, ref.version) : ref.version;
+        if (version === null)
+            return null;
         const snapshot = await getKnowledgeSnapshot(ref.domain, ref.key, version);
         return snapshot ? { version, snapshot } : null;
     }
@@ -71,6 +76,26 @@ async function resolveRefEdition(ref, asOf) {
     remember(cacheKey, snapshot);
     return { version, snapshot };
 }
+/**
+ * The edition a label names, or, for a label that is a whole number no edition
+ * carries, that edition's number. Null when the label names nothing; that is
+ * never cached, so a label given later becomes visible.
+ */
+async function editionOfLabel(domain, key, label) {
+    const cacheKey = `${domain} ${key} #${label}`;
+    const hit = labelCache.get(cacheKey);
+    if (hit !== undefined)
+        return hit;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_KNOWLEDGE_VERSION_BY_LABEL, [domain, key, label]);
+    if (rows[0]) {
+        const version = Number(rows[0].version);
+        labelCache.set(cacheKey, version);
+        while (labelCache.size > SNAPSHOT_CACHE_MAX_ENTRIES)
+            labelCache.delete(labelCache.keys().next().value);
+        return version;
+    }
+    return /^[1-9][0-9]*$/.test(label) ? Number(label) : null;
+}
 /** Structural check for one ref — malformed entries in stored metadata are skipped, not fatal. */
 function isLookupRef(ref) {
     if (!ref || typeof ref !== 'object')
@@ -78,7 +103,7 @@ function isLookupRef(ref) {
     const r = ref;
     return typeof r.domain === 'string' && r.domain.length > 0
         && typeof r.key === 'string' && r.key.length > 0
-        && ((0, escalation_1.isCurrentLookupRef)(r) || (typeof r.version === 'number' && Number.isInteger(r.version) && r.version >= 1))
+        && ((0, escalation_1.isCurrentLookupRef)(r) || (0, escalation_1.isLabelLookupRef)(r) || (typeof r.version === 'number' && Number.isInteger(r.version) && r.version >= 1))
         && (r.as === undefined || (typeof r.as === 'string' && r.as.length > 0));
 }
 /**
@@ -112,12 +137,14 @@ async function resolveLookupRefs(refs, asOf) {
         if (!isLookupRef(ref))
             continue;
         const current = (0, escalation_1.isCurrentLookupRef)(ref);
+        const label = (0, escalation_1.isLabelLookupRef)(ref) ? ref.version : undefined;
         const edition = await resolveRefEdition(ref, asOf);
         resolved.push({
             domain: ref.domain,
             key: ref.key,
-            version: edition?.version ?? (current ? null : ref.version),
+            version: edition?.version ?? (current || label !== undefined ? null : ref.version),
             ...(current ? { current: true } : {}),
+            ...(label !== undefined ? { label } : {}),
             ...(ref.as ? { as: ref.as } : {}),
             data: edition ? edition.snapshot.data : null,
             ...(edition ? {} : { missing: true }),

package/build/services/knowledge/lookup-refs.js

@@ -21,7 +21,7 @@ async function describeMissingLookupRefs(refs) {
         const where = versions.length
             ? `editions: ${versions.map((v) => `v${v}`).join(', ')}`
             : `no knowledge entry ${ref.domain}/${ref.key}`;
-        const named = (0, escalation_1.isCurrentLookupRef)(ref) ? 'current' : `v${ref.version}`;
+        const named = (0, escalation_1.isCurrentLookupRef)(ref) ? 'current' : (0, escalation_1.isLabelLookupRef)(ref) ? `label ${JSON.stringify(ref.version)}` : `v${ref.version}`;
         problems.push(`Lookup ref ${ref.domain}/${ref.key} ${named} names no edition (${where})`);
     }
     return problems;

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

@@ -1,4 +1,6 @@
-export declare const GET_KNOWLEDGE_VERSION = "\n  SELECT domain, key, version, data, tags, change_summary, created_at\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2 AND version = $3";
-export declare const LIST_KNOWLEDGE_VERSIONS = "\n  SELECT v.version, v.change_summary, v.created_at,\n         (v.version = k.current_version) AS is_current\n  FROM lt_knowledge_versions v\n  JOIN lt_knowledge k ON k.domain = v.domain AND k.key = v.key\n  WHERE v.domain = $1 AND v.key = $2\n  ORDER BY v.version DESC";
+export declare const GET_KNOWLEDGE_VERSION = "\n  SELECT domain, key, version, label, data, tags, change_summary, created_at\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2 AND version = $3";
+/** The edition a label names, when one does. */
+export declare const GET_KNOWLEDGE_VERSION_BY_LABEL = "\n  SELECT version\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2 AND label = $3";
+export declare const LIST_KNOWLEDGE_VERSIONS = "\n  SELECT v.version, v.label, v.change_summary, v.created_at,\n         (v.version = k.current_version) AS is_current\n  FROM lt_knowledge_versions v\n  JOIN lt_knowledge k ON k.domain = v.domain AND k.key = v.key\n  WHERE v.domain = $1 AND v.key = $2\n  ORDER BY v.version DESC";
 /** The newest edition, or the newest created at or before $3 when it is set. */
 export declare const GET_LATEST_KNOWLEDGE_VERSION = "\n  SELECT version, data, tags\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2\n    AND ($3::timestamptz IS NULL OR created_at <= $3)\n  ORDER BY version DESC\n  LIMIT 1";

package/build/services/knowledge/sql.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET_LATEST_KNOWLEDGE_VERSION = exports.LIST_KNOWLEDGE_VERSIONS = exports.GET_KNOWLEDGE_VERSION = void 0;
+exports.GET_LATEST_KNOWLEDGE_VERSION = exports.LIST_KNOWLEDGE_VERSIONS = exports.GET_KNOWLEDGE_VERSION_BY_LABEL = exports.GET_KNOWLEDGE_VERSION = void 0;
 exports.GET_KNOWLEDGE_VERSION = `
-  SELECT domain, key, version, data, tags, change_summary, created_at
+  SELECT domain, key, version, label, data, tags, change_summary, created_at
   FROM lt_knowledge_versions
   WHERE domain = $1 AND key = $2 AND version = $3`;
+/** The edition a label names, when one does. */
+exports.GET_KNOWLEDGE_VERSION_BY_LABEL = `
+  SELECT version
+  FROM lt_knowledge_versions
+  WHERE domain = $1 AND key = $2 AND label = $3`;
 exports.LIST_KNOWLEDGE_VERSIONS = `
-  SELECT v.version, v.change_summary, v.created_at,
+  SELECT v.version, v.label, v.change_summary, v.created_at,
          (v.version = k.current_version) AS is_current
   FROM lt_knowledge_versions v
   JOIN lt_knowledge k ON k.domain = v.domain AND k.key = v.key

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

@@ -42,6 +42,8 @@ export interface MachineLineConfig {
     progressStep: number;
     /** Telemetry messages are published as wire events too; off by default, since they are read live and many. */
     wireTelemetry: boolean;
+    /** How many of the line's last wire events the leader keeps for GET .../wire. */
+    wireWindow: number;
     ltBaseUrl: string;
 }
 type Env = Record<string, string | undefined>;

package/build/services/machines/config.js

@@ -75,6 +75,7 @@ function loadMachineLineConfig(env = process.env) {
         lifecycle: oneOf('MACHINE_LIFECYCLE', env.MACHINE_LIFECYCLE || SWITCH.OFF, Object.values(SWITCH)) === SWITCH.ON,
         progressStep: percentStep(env, 'MACHINE_PROGRESS_STEP', 25),
         wireTelemetry: oneOf('MACHINE_WIRE_TELEMETRY', env.MACHINE_WIRE_TELEMETRY || SWITCH.OFF, Object.values(SWITCH)) === SWITCH.ON,
+        wireWindow: Math.max(1, int(env, 'MACHINE_WIRE_WINDOW', 500)),
         ltBaseUrl: env.LT_BASE_URL ?? 'http://localhost:3000',
     };
     if (transport === exports.MACHINE_TRANSPORT.NATS) {

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

@@ -16,12 +16,16 @@ export declare const ROW_TYPE: {
     readonly CONTRACT_VIOLATION: "contract-violation";
     /** An address claims a station the line already knows by another address, or the reverse: a person approves or rejects. */
     readonly MACHINE_REGISTRATION: "machine-registration";
+    /** Units a machine finished on hold wait for a quality decision: release, rework or scrap. */
+    readonly QUALITY_HOLD: "quality-hold";
 };
 export declare const LINE_ROLE: {
     /** People who clear alarms, bring machines back and decide failed handoffs. */
     readonly OPERATOR: "line-operator";
     /** People who take finished units off the line: the final handoff. */
     readonly EXIT: "line-exit";
+    /** People who decide units a machine finished on hold. */
+    readonly QUALITY: "line-quality";
     /** The gateway's own identity. */
     readonly CONTROLLER: "line-controller";
 };
@@ -116,6 +120,8 @@ export declare const HANDOFF_ERROR: {
     readonly SOFTWARE_UNSUPPORTED: "software-unsupported";
     readonly WITHDRAWN: "withdrawn";
     readonly CANCELLED: "cancelled";
+    /** An arrival no open handoff into the machine expects, shown to the operator role once per machine and carrier. */
+    readonly UNMATCHED_ARRIVAL: "unmatched-arrival";
 };
 export type HandoffErrorCode = typeof HANDOFF_ERROR[keyof typeof HANDOFF_ERROR];
 /** A material lot a machine consumed for a unit. */
@@ -172,6 +178,10 @@ export declare const DECISION: {
     readonly RESTORED: "restored";
     readonly APPROVE: "approve";
     readonly REJECT: "reject";
+    /** A quality decision on held units: they continue from where they are. */
+    readonly RELEASE: "release";
+    /** A quality decision on held units: they run again from a station on the route. */
+    readonly REWORK: "rework";
 };
 export type Decision = typeof DECISION[keyof typeof DECISION];
 /** The decisions an operator may take on a failed handoff; retry only while every unit is still at the sender. */
@@ -180,11 +190,19 @@ export interface OperatorResolution {
     decision: Decision;
     note?: string;
 }
+/** The decisions a quality role may take on units a machine finished on hold. */
+export declare const HOLD_DECISIONS: readonly Decision[];
+export interface QualityResolution extends OperatorResolution {
+    /** For `rework`: the station the units run again from; the holding station when absent. */
+    station?: string;
+}
 /** Signal keys for the unit workflow; every attempt mints a fresh key. */
 export declare const signalKeys: {
     handoff: (jobKey: string, step: number, attempt: number) => string;
     handoffError: (jobKey: string, step: number, attempt: number, round?: number) => string;
     jobStop: (jobKey: string, step: number, attempt: number) => string;
+    hold: (jobKey: string, step: number, attempt: number, round?: number) => string;
+    disposition: (jobKey: string, step: number, attempt: number) => string;
 };
 /** Metadata on a machine-command row. */
 export interface CommandFacets {