@hotmeshio/long-tail 0.28.0 → 0.28.1

package/build/api/files.d.ts

@@ -10,9 +10,14 @@ export declare function getFileMetadata(input: {
 export declare function deleteFile(input: {
     filePath: string;
 }): Promise<LTApiResult>;
+/**
+ * Stores the bytes with their SHA-256. A caller that names the digest it
+ * expects gets 422 when the bytes received differ, and nothing is stored.
+ */
 export declare function uploadFile(input: {
     path: string;
     buffer: Buffer;
+    sha256?: string;
 }): Promise<LTApiResult>;
 export declare function generateSignedUrl(input: {
     filePath: string;

package/build/api/files.js

@@ -5,6 +5,7 @@ exports.getFileMetadata = getFileMetadata;
 exports.deleteFile = deleteFile;
 exports.uploadFile = uploadFile;
 exports.generateSignedUrl = generateSignedUrl;
+const crypto_1 = require("crypto");
 const storage_1 = require("../lib/storage");
 const mime_1 = require("../lib/storage/mime");
 const publish_1 = require("../lib/events/publish");
@@ -46,9 +47,25 @@ async function deleteFile(input) {
         return { status: 500, error: err.message };
     }
 }
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+/**
+ * Stores the bytes with their SHA-256. A caller that names the digest it
+ * expects gets 422 when the bytes received differ, and nothing is stored.
+ */
 async function uploadFile(input) {
+    if (input.sha256 !== undefined && !SHA256_HEX.test(input.sha256)) {
+        return { status: 400, error: 'sha256 must be 64 hex characters' };
+    }
+    const sha256 = (0, crypto_1.createHash)('sha256').update(input.buffer).digest('hex');
+    if (input.sha256 && input.sha256.toLowerCase() !== sha256) {
+        return {
+            status: 422,
+            error: 'sha256 does not match the bytes received',
+            data: { error: 'sha256 does not match the bytes received', path: input.path, expected: input.sha256.toLowerCase(), actual: sha256 },
+        };
+    }
     try {
-        const result = await (0, storage_1.getStorageBackend)().write(input.path, input.buffer);
+        const result = await (0, storage_1.getStorageBackend)().write(input.path, input.buffer, { sha256 });
         const contentType = (0, mime_1.mimeFromPath)(input.path);
         (0, publish_1.publishFileEvent)({
             type: 'file.stored',
@@ -58,7 +75,7 @@ async function uploadFile(input) {
         });
         return {
             status: 200,
-            data: { path: input.path, size: result.size, content_type: contentType },
+            data: { path: input.path, size: result.size, content_type: contentType, sha256 },
         };
     }
     catch (err) {

package/build/api/knowledge.d.ts

@@ -14,7 +14,8 @@ export declare function getEntry(input: {
 export declare function getEntryVersion(input: {
     domain: string;
     key: string;
-    version: number;
+    /** An edition number, or the label an edition carries. */
+    version: number | string;
 }): Promise<LTApiResult>;
 export declare function listEntryVersions(input: {
     domain: string;
@@ -26,6 +27,7 @@ export declare function storeEntry(input: {
     data: Record<string, any>;
     tags?: string[];
     replace?: boolean;
+    label?: string;
 }): Promise<LTApiResult>;
 export declare function setField(input: {
     domain: string;

package/build/lib/db/schemas/042_knowledge_edition_labels.sql

@@ -0,0 +1,9 @@
+-- An edition may carry a label: a name a lookup ref pins instead of the
+-- version number (a catalog revision, say). A label names one edition of an
+-- entry; editions without one are reached by number or as current.
+ALTER TABLE lt_knowledge_versions
+  ADD COLUMN IF NOT EXISTS label TEXT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS lt_knowledge_versions_label_idx
+  ON lt_knowledge_versions (domain, key, label)
+  WHERE label IS NOT NULL;

package/build/lib/machines/line.d.ts

@@ -35,6 +35,7 @@ export declare function controllerId(line: LineDef): string;
 export declare function stationRole(process: string): string;
 export declare const DEFAULT_EXIT_ROLE = "line-exit";
 export declare const DEFAULT_OPERATOR_ROLE = "line-operator";
+export declare const DEFAULT_QUALITY_ROLE = "line-quality";
 /** The Long Tail role a machine resolves handoffs under. */
 export declare function machineRole(def: Pick<MachineDef, 'role' | 'process'>): string;
 /** Every station role on the line, once each, in route order. */
@@ -45,3 +46,5 @@ export declare function exitRole(line: LineDef): string;
 export declare function receiverRoles(line: LineDef): string[];
 /** The role of the person who decides failed handoffs and closes alarm and machine rows. */
 export declare function operatorRole(line: LineDef): string;
+/** The role of the people who decide units a machine finished on hold: release, rework or scrap. */
+export declare function qualityRole(line: LineDef): string;

package/build/lib/machines/line.js

@@ -5,7 +5,7 @@
  * several separated by commas.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_OPERATOR_ROLE = exports.DEFAULT_EXIT_ROLE = exports.CARRIER_ROLE = exports.ADDRESSING = void 0;
+exports.DEFAULT_QUALITY_ROLE = exports.DEFAULT_OPERATOR_ROLE = exports.DEFAULT_EXIT_ROLE = exports.CARRIER_ROLE = exports.ADDRESSING = void 0;
 exports.learnsAddress = learnsAddress;
 exports.validateLine = validateLine;
 exports.loadLine = loadLine;
@@ -20,6 +20,7 @@ exports.stationRoles = stationRoles;
 exports.exitRole = exitRole;
 exports.receiverRoles = receiverRoles;
 exports.operatorRole = operatorRole;
+exports.qualityRole = qualityRole;
 const fs_1 = require("fs");
 const protocol_1 = require("./protocol");
 /** How a line knows its machines' addresses (`LineDef.addressing`). */
@@ -109,6 +110,7 @@ function stationRole(process) {
 }
 exports.DEFAULT_EXIT_ROLE = 'line-exit';
 exports.DEFAULT_OPERATOR_ROLE = 'line-operator';
+exports.DEFAULT_QUALITY_ROLE = 'line-quality';
 /** The Long Tail role a machine resolves handoffs under. */
 function machineRole(def) {
     return def.role ?? stationRole(def.process);
@@ -129,3 +131,7 @@ function receiverRoles(line) {
 function operatorRole(line) {
     return line.roles?.operator ?? exports.DEFAULT_OPERATOR_ROLE;
 }
+/** The role of the people who decide units a machine finished on hold: release, rework or scrap. */
+function qualityRole(line) {
+    return line.roles?.quality ?? exports.DEFAULT_QUALITY_ROLE;
+}

package/build/lib/machines/protocol/codec.d.ts

@@ -20,6 +20,12 @@ export interface MachineCommand {
     attempt?: number;
     /** The command may have reached the machine before: sent earlier, or its row predates this gateway's takeover. */
     retry?: boolean;
+    /**
+     * When the command was issued, ISO 8601: the same on every send of this `cmdId`, by this gateway or the
+     * next, so a protocol that stamps a time repeats the first attempt. A dispatch or a command row takes the
+     * start of its validity round; any other command the time of its first send.
+     */
+    issuedAt?: string;
 }
 /** MQTT filters under each machine's topic, e.g. `job` or `alarm/+`. */
 export interface CodecChannels {

package/build/lib/machines/protocol/codec.js

@@ -83,7 +83,7 @@ function genericCodec(opts) {
             return receiptFrom === exports.RECEIPT_FROM.ARRIVED ? [seen] : inferReceipt(seen, receiptFrom);
         },
         encode(ident, command) {
-            return [{ topic: (0, topics_1.machineTopic)(opts.root, ident, constants_1.CHANNEL.CMD), payload: JSON.stringify((0, envelope_1.buildEnvelope)(ident, command)) }];
+            return [{ topic: (0, topics_1.machineTopic)(opts.root, ident, constants_1.CHANNEL.CMD), payload: JSON.stringify((0, envelope_1.buildEnvelope)(ident, command, { at: command.issuedAt })) }];
         },
     };
 }

package/build/lib/machines/protocol/contract.d.ts

@@ -17,3 +17,5 @@ export interface Inspection {
 }
 /** Validate one message. `retained` is the publisher's flag when the transport reports it. */
 export declare function inspectMessage(root: string, topic: string, raw: string | Buffer, retained?: boolean): Inspection;
+/** A receiver's report that it could read no id at all: a transfer failure on the read, naming no unit and no carrier. */
+export declare function isUnreadableRead(b: Record<string, any>): boolean;

package/build/lib/machines/protocol/contract.js

@@ -10,6 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.inspectMessage = inspectMessage;
+exports.isUnreadableRead = isUnreadableRead;
 const ajv_1 = __importDefault(require("ajv"));
 const constants_1 = require("./constants");
 const envelope_1 = require("./envelope");
@@ -41,7 +42,7 @@ const BODY = {
         jobs: { type: 'array', items: shape({ jobId: STR, units: { type: 'array', items: STR }, status: STR }) },
         alarms: { type: 'array', items: STR },
         cycles: INT0,
-    }),
+    }, ['bootId', 'software', 'recipe', 'cycles']),
     [topics_1.MESSAGE_KIND.JOB]: shape({
         event: oneOf(constants_1.JOB_EVENT), jobId: STR, unitId: STR, orderRef: STR, recipe: RECIPE, carrierId: STR_N, peer: STR_N,
         result: oneOf(constants_1.JOB_RESULT), reason: STR_N,
@@ -52,15 +53,15 @@ const BODY = {
         materials: { type: 'array', items: shape({ material: STR, lot: STR }) },
         startedAt: TS, endedAt: TS, durationMs: INT0, failure: oneOf(constants_1.TRANSFER_FAILURE),
         percent: { type: 'number', minimum: 0, maximum: 100 }, remainingSec: INT0, stage: STR, detail: { type: 'object' },
-    }, ['jobId', 'unitId', 'peer', 'result', 'reason', 'measurements', 'materials', 'startedAt', 'endedAt', 'durationMs', 'failure', 'percent', 'remainingSec', 'stage', 'detail']),
+    }, ['jobId', 'unitId', 'orderRef', 'peer', 'result', 'reason', 'measurements', 'materials', 'startedAt', 'endedAt', 'durationMs', 'failure', 'percent', 'remainingSec', 'stage', 'detail']),
     [topics_1.MESSAGE_KIND.ALARM]: shape({
         alarmId: STR, code: STR, level: oneOf(constants_1.LEVEL), text: STR, active: BOOL,
         raisedAt: TS, clearedAt: TS_N, clearedBy: STR_N, ackedBy: STR_N, ackedAt: TS_N,
-        zone: STR_N, autoClears: BOOL, action: STR_N, jobId: STR_N,
-    }),
+        zone: STR_N, autoClears: BOOL, action: STR_N, jobId: STR_N, needsPerson: BOOL,
+    }, ['needsPerson']),
     [topics_1.MESSAGE_KIND.TELEMETRY]: shape({ readings: { type: 'object', additionalProperties: NUM } }),
     [topics_1.MESSAGE_KIND.CMD]: shape({ cmdId: STR, op: oneOf(constants_1.OP), args: { type: 'object' } }),
-    [topics_1.MESSAGE_KIND.REPLY]: shape({ cmdId: STR, status: oneOf(constants_1.REPLY_STATUS), reason: STR, code: STR }, ['code']),
+    [topics_1.MESSAGE_KIND.REPLY]: shape({ cmdId: STR, status: oneOf(constants_1.REPLY_STATUS), reason: STR, code: STR, preparing: BOOL }, ['code', 'preparing']),
     [topics_1.MESSAGE_KIND.REPORT]: { type: 'object' },
 };
 const ajv = new ajv_1.default({ allErrors: true, strict: false });
@@ -95,6 +96,10 @@ function inspectMessage(root, topic, raw, retained) {
 }
 /** Job events a receiver may report naming only the carrier it scanned. */
 const CARRIER_EVENTS = [constants_1.JOB_EVENT.ARRIVED, constants_1.JOB_EVENT.TRANSFER_FAILED];
+/** A receiver's report that it could read no id at all: a transfer failure on the read, naming no unit and no carrier. */
+function isUnreadableRead(b) {
+    return b.event === constants_1.JOB_EVENT.TRANSFER_FAILED && b.failure === constants_1.TRANSFER_FAILURE.UNREADABLE_ID && b.unitId === undefined && typeof b.carrierId !== 'string';
+}
 function crossFieldRules(parsed, env, retained) {
     const out = [];
     const b = env.body ?? {};
@@ -105,8 +110,8 @@ function crossFieldRules(parsed, env, retained) {
     if (kind === topics_1.MESSAGE_KIND.ALARM && b.alarmId !== key)
         out.push('alarmId disagrees with the topic');
     if (kind === topics_1.MESSAGE_KIND.JOB) {
-        // A scan at a receiver may read only the carrier; every other job event names its unit and job.
-        const byCarrier = CARRIER_EVENTS.includes(b.event) && typeof b.carrierId === 'string';
+        // A scan at a receiver may read only the carrier, or nothing at all when the read failed; every other job event names its unit and job.
+        const byCarrier = CARRIER_EVENTS.includes(b.event) && (typeof b.carrierId === 'string' || isUnreadableRead(b));
         if (b.unitId === undefined && !byCarrier)
             out.push(`${b.event} without a unitId`);
         if (b.jobId === undefined && !byCarrier)

package/build/lib/machines/site/mosquitto-conf.d.ts

@@ -7,9 +7,10 @@
  * NATS, where JetStream keeps them.
  */
 import { type LineCodec } from '../protocol/codec';
-import { type Lines } from './site-conf';
+import { type LineDef } from '../line';
+import { type Lines, type TopicRoot } from './site-conf';
 export interface MosquittoConfOptions {
-    root: string;
+    root: TopicRoot;
     /** Certificate directory as the broker sees it. */
     certDir: string;
     /** Where the site NATS MQTT listener is, host:port. */
@@ -25,4 +26,7 @@ export declare function renderMosquittoConf(lines: Lines, opts: MosquittoConfOpt
  * the channels under its own name (%u), so its certificate's common name must be its address. On a line
  * that also declares addresses, a certificate named for a declared address is denied that station's channels.
  */
-export declare function renderMosquittoAcl(lines: Lines, codec: Pick<LineCodec, 'root' | 'channels' | 'topicFor'>): string;
+export type AclCodec = Pick<LineCodec, 'root' | 'channels' | 'topicFor'>;
+/** One codec for every line, or the codec of each line. */
+export type AclCodecs = AclCodec | ((line: LineDef) => AclCodec);
+export declare function renderMosquittoAcl(lines: Lines, codec: AclCodecs): string;

package/build/lib/machines/site/mosquitto-conf.js

@@ -26,7 +26,7 @@ remote_clientid ${(0, site_conf_1.bridgeId)(line)}
 cleansession false
 try_private false
 notifications false
-topic ${opts.root}/${line.siteId}/${line.lineId}/# out 1
+topic ${(0, site_conf_1.rootOf)(opts.root, line)}/${line.siteId}/${line.lineId}/# out 1
 `;
 }
 /** The broker for one line or several: one listener, one bridge per line. */
@@ -53,17 +53,12 @@ max_packet_size ${opts.maxPacketBytes ?? 262_144}
 
 ${list.map((line) => bridgeBlock(line, opts)).join('\n')}`;
 }
-/**
- * The codec's channels decide the topics: a machine writes its events and telemetry and reads its commands.
- * A station whose address the line learns has no user of its own: `pattern` rules give every certificate
- * the channels under its own name (%u), so its certificate's common name must be its address. On a line
- * that also declares addresses, a certificate named for a declared address is denied that station's channels.
- */
 function renderMosquittoAcl(lines, codec) {
     const list = (0, site_conf_1.linesOf)(lines);
     if (!list.length)
         throw new Error('renderMosquittoAcl needs at least one line');
-    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.\n\n${list.map((line) => aclRules(line, codec)).join('\n\n')}\n`;
+    const codecOf = (line) => (typeof codec === 'function' ? codec(line) : codec);
+    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.\n\n${list.map((line) => aclRules(line, codecOf(line))).join('\n\n')}\n`;
 }
 /** One line's rules: its stations, its controller, and the shadows a learning line needs. */
 function aclRules(line, codec) {

package/build/lib/machines/site/site-conf.d.ts

@@ -8,8 +8,11 @@
  * site NATS stands alone; Long Tail's escalation events stay inside Long Tail.
  */
 import { type LineDef } from '../line';
+/** One topic root for every line, or a root per line (lines on different codecs). */
+export type TopicRoot = string | ((line: LineDef) => string);
+export declare function rootOf(root: TopicRoot, line: LineDef): string;
 export interface SiteConfOptions {
-    root: string;
+    root: TopicRoot;
     gatewayUser: string;
     gatewayPassword: string;
     certDir: string;

package/build/lib/machines/site/site-conf.js

@@ -9,6 +9,7 @@
  * site NATS stands alone; Long Tail's escalation events stay inside Long Tail.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.rootOf = rootOf;
 exports.bridgeId = bridgeId;
 exports.gatewayPublish = gatewayPublish;
 exports.linesOf = linesOf;
@@ -17,6 +18,9 @@ const line_1 = require("../line");
 const protocol_1 = require("../protocol");
 const permissions_1 = require("../../messaging/nats/permissions");
 const streams_1 = require("../transport/streams");
+function rootOf(root, line) {
+    return typeof root === 'string' ? root : root(line);
+}
 const q = JSON.stringify;
 /** The machine broker's bridge identity for a line. */
 function bridgeId(line) {
@@ -44,7 +48,7 @@ function renderSiteConf(lines, opts) {
     const list = linesOf(lines);
     if (!list.length)
         throw new Error('renderSiteConf needs at least one line');
-    const baseOf = (line) => (0, protocol_1.toSubject)(`${opts.root}/${line.siteId}/${line.lineId}`);
+    const baseOf = (line) => (0, protocol_1.toSubject)(`${rootOf(opts.root, line)}/${line.siteId}/${line.lineId}`);
     const bridge = list.map((line) => [
         `    { user: ${q(`CN=${bridgeId(line)}`)}, allowed_connection_types: ["MQTT"],`,
         `      permissions: { publish: [${q(`${baseOf(line)}.>`)}], subscribe: { deny: [">"] } } }`,

package/build/lib/machines/transport/nats-bus.d.ts

@@ -17,6 +17,8 @@ export interface NatsBusOptions {
     lineId: string;
     /** The codec's topics: which subjects are durable events and which are live telemetry. */
     codec: StreamCodec;
+    /** The codecs of every line on this site, so the streams keep all their subjects. */
+    siteCodecs?: StreamCodec[];
     nakDelayMs?: number;
 }
 export declare class NatsMachineBus implements MachineBus {

package/build/lib/machines/transport/stream-bus.d.ts

@@ -3,7 +3,9 @@
  * line's durable consumer on LINE_EVENTS (replayed after a restart); telemetry
  * is read live, since it only proves a machine is alive. Commands leave through
  * an MQTT session at QoS 1 on the site broker, which queues them for a machine
- * that is away; retained machine state is read there too.
+ * that is away; retained machine state is read there too. The streams are
+ * ensured with every codec on the site, so lines on different roots share
+ * them, and a consumer the stream would feed nothing refuses to start.
  */
 import type { LTPubSub, LTStreams } from '../../../types/messaging';
 import type { MqttEndpoint } from '../../../services/machines/config';
@@ -19,6 +21,8 @@ export interface StreamBusOptions {
     lineId: string;
     /** The codec's topics: which subjects are durable events and which are live telemetry. */
     codec: StreamCodec;
+    /** The codecs of every line on this site; the streams keep all their subjects, whichever line starts last. */
+    siteCodecs?: StreamCodec[];
     nakDelayMs?: number;
 }
 export declare class StreamMachineBus implements MachineBus {

package/build/lib/machines/transport/stream-bus.js

@@ -4,7 +4,9 @@
  * line's durable consumer on LINE_EVENTS (replayed after a restart); telemetry
  * is read live, since it only proves a machine is alive. Commands leave through
  * an MQTT session at QoS 1 on the site broker, which queues them for a machine
- * that is away; retained machine state is read there too.
+ * that is away; retained machine state is read there too. The streams are
+ * ensured with every codec on the site, so lines on different roots share
+ * them, and a consumer the stream would feed nothing refuses to start.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StreamMachineBus = void 0;
@@ -23,10 +25,16 @@ class StreamMachineBus {
         return `${this.opts.controllerId}-events`;
     }
     async connect() {
-        const { streams, codec, siteId, lineId, controllerId } = this.opts;
-        for (const spec of (0, streams_1.lineStreamSpecs)(codec))
+        const { streams, codec, siteId, lineId, controllerId, siteCodecs = [] } = this.opts;
+        for (const spec of (0, streams_1.lineStreamSpecs)([codec, ...siteCodecs]))
             await streams.ensureStream(spec);
-        await streams.ensureConsumer(streams_1.LINE_STREAM.EVENTS, (0, streams_1.lineEventConsumerSpec)(codec, siteId, lineId, this.durableName));
+        const consumer = (0, streams_1.lineEventConsumerSpec)(codec, siteId, lineId, this.durableName);
+        await streams.ensureConsumer(streams_1.LINE_STREAM.EVENTS, consumer);
+        const events = await streams.describeStream(streams_1.LINE_STREAM.EVENTS);
+        const missing = events ? (0, streams_1.uncoveredSubjects)(events, consumer.filterSubjects) : consumer.filterSubjects;
+        if (missing.length) {
+            throw new Error(`${streams_1.LINE_STREAM.EVENTS} keeps nothing of ${missing.join(', ')}; the stream holds ${events?.subjects.join(', ') ?? 'nothing'}`);
+        }
         this.session = await mqtt_session_1.MqttSession.open(this.opts.mqtt, controllerId);
     }
     async consume(handler) {

package/build/lib/machines/transport/streams.d.ts

@@ -13,8 +13,16 @@ export declare const LINE_STREAM: {
 export type StreamCodec = Pick<LineCodec, 'root' | 'channels' | 'topicFor'>;
 /** An MQTT filter as a subject: levels become tokens, `+` becomes `*`, `#` becomes `>`. */
 export declare function filterToSubject(filter: string): string;
-/** The line streams, for every line under the codec's root; a root alone means the generic layout. */
-export declare function lineStreamSpecs(codec: StreamCodec | string): StreamSpec[];
+/**
+ * The site's streams: every line under each codec's root, since lines on
+ * different protocols share one site NATS. A root alone means the generic
+ * layout; several codecs give the union of their subjects, in order.
+ */
+export declare function lineStreamSpecs(codecs: StreamCodec | string | (StreamCodec | string)[]): StreamSpec[];
+/** Whether a stream subject pattern keeps everything a consumer filter would read. */
+export declare function subjectCovers(stream: string, filter: string): boolean;
+/** The consumer's filter subjects the stream keeps nothing of. */
+export declare function uncoveredSubjects(stream: Pick<StreamSpec, 'subjects'>, filters: string[]): string[];
 /** The telemetry subjects for one line, read live rather than replayed. */
 export declare function telemetrySubjects(codec: StreamCodec | string, siteId: string, lineId: string): string[];
 /**

package/build/lib/machines/transport/streams.js

@@ -8,6 +8,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LINE_STREAM = void 0;
 exports.filterToSubject = filterToSubject;
 exports.lineStreamSpecs = lineStreamSpecs;
+exports.subjectCovers = subjectCovers;
+exports.uncoveredSubjects = uncoveredSubjects;
 exports.telemetrySubjects = telemetrySubjects;
 exports.lineEventConsumerSpec = lineEventConsumerSpec;
 const codec_1 = require("../protocol/codec");
@@ -26,14 +28,39 @@ function filterToSubject(filter) {
 function subjectsFor(codec, channels, siteId, lineId) {
     return channels.map((c) => filterToSubject((0, codec_1.topicOf)(codec, { siteId, lineId }, c)));
 }
-/** The line streams, for every line under the codec's root; a root alone means the generic layout. */
-function lineStreamSpecs(codec) {
-    const c = codecOf(codec);
+/**
+ * The site's streams: every line under each codec's root, since lines on
+ * different protocols share one site NATS. A root alone means the generic
+ * layout; several codecs give the union of their subjects, in order.
+ */
+function lineStreamSpecs(codecs) {
+    const list = (Array.isArray(codecs) ? codecs : [codecs]).map(codecOf);
+    const union = (channel) => [...new Set(list.flatMap((c) => subjectsFor(c, c.channels[channel])))];
     return [
-        { name: exports.LINE_STREAM.EVENTS, subjects: subjectsFor(c, c.channels.events), maxAgeMs: 30 * DAY_MS },
-        { name: exports.LINE_STREAM.TELEMETRY, subjects: subjectsFor(c, c.channels.telemetry), maxAgeMs: 3 * DAY_MS },
+        { name: exports.LINE_STREAM.EVENTS, subjects: union('events'), maxAgeMs: 30 * DAY_MS },
+        { name: exports.LINE_STREAM.TELEMETRY, subjects: union('telemetry'), maxAgeMs: 3 * DAY_MS },
     ];
 }
+/** Whether a stream subject pattern keeps everything a consumer filter would read. */
+function subjectCovers(stream, filter) {
+    const s = stream.split('.');
+    const f = filter.split('.');
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === '>')
+            return f.length > i;
+        if (i >= f.length)
+            return false;
+        if (f[i] === '>')
+            return false;
+        if (s[i] !== '*' && s[i] !== f[i])
+            return false;
+    }
+    return s.length === f.length;
+}
+/** The consumer's filter subjects the stream keeps nothing of. */
+function uncoveredSubjects(stream, filters) {
+    return filters.filter((f) => !stream.subjects.some((s) => subjectCovers(s, f)));
+}
 /** The telemetry subjects for one line, read live rather than replayed. */
 function telemetrySubjects(codec, siteId, lineId) {
     const c = codecOf(codec);

package/build/lib/messaging/memory.js

@@ -36,6 +36,9 @@ class MemoryStreams {
         else
             this.streams.set(spec.name, { spec, messages: [], seq: 0, consumers: new Map(), wake: new Set() });
     }
+    async describeStream(name) {
+        return this.streams.get(name)?.spec ?? null;
+    }
     async ensureConsumer(stream, spec) {
         const s = this.stream(stream);
         const existing = s.consumers.get(spec.name);

package/build/lib/messaging/nats/streams.d.ts

@@ -9,6 +9,8 @@ export declare function streamConfig(spec: StreamSpec): Partial<StreamConfig>;
 export declare function consumerConfig(spec: ConsumerSpec): Partial<ConsumerConfig>;
 /** Create the stream, or update an existing one to the spec. */
 export declare function ensureStream(jsm: JetStreamManager, spec: StreamSpec): Promise<void>;
+/** The stream as JetStream holds it, or null when there is none. */
+export declare function describeStream(jsm: JetStreamManager, name: string): Promise<StreamSpec | null>;
 /** Create the consumer, or move an existing one to the spec's subjects without losing its place. */
 export declare function ensureConsumer(jsm: JetStreamManager, stream: string, spec: ConsumerSpec): Promise<void>;
 export declare function payloadOf(m: {
@@ -20,6 +22,7 @@ export declare class NatsStreams implements LTStreams {
     constructor(jsm: JetStreamManager, js: JetStreamClient);
     ensureStream(spec: StreamSpec): Promise<void>;
     ensureConsumer(stream: string, spec: ConsumerSpec): Promise<void>;
+    describeStream(name: string): Promise<StreamSpec | null>;
     append(subject: Subject, payload: string): Promise<void>;
     /** One message at a time: the next is not taken until the handler settles this one. */
     consume(stream: string, consumer: string, handler: (m: LTStreamMessage) => Promise<Delivery>, opts?: LTConsumeOptions): Promise<LTSubscription>;

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

@@ -9,6 +9,7 @@ exports.NatsStreams = void 0;
 exports.streamConfig = streamConfig;
 exports.consumerConfig = consumerConfig;
 exports.ensureStream = ensureStream;
+exports.describeStream = describeStream;
 exports.ensureConsumer = ensureConsumer;
 exports.payloadOf = payloadOf;
 const nats_1 = require("nats");
@@ -41,6 +42,18 @@ async function ensureStream(jsm, spec) {
     }
     await jsm.streams.update(spec.name, config);
 }
+/** 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 move an existing one to the spec's subjects without losing its place. */
 async function ensureConsumer(jsm, stream, spec) {
     let existing;
@@ -72,6 +85,9 @@ class NatsStreams {
     ensureConsumer(stream, spec) {
         return ensureConsumer(this.jsm, stream, spec);
     }
+    describeStream(name) {
+        return describeStream(this.jsm, name);
+    }
     async append(subject, payload) {
         await this.js.publish(subject, payload);
     }

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>;