@hotmeshio/long-tail 0.27.0 → 0.28.1

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

package/build/modules/machines.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The running machine surface, for settings and the machines API. Set by
+ * start() when the config declares lines; absent otherwise, so a deployment
+ * without machines serves no lines and no Lines view.
+ */
+import type { LineSurface } from '../services/machines/surface';
+export declare function registerMachineSurface(next: LineSurface | null): void;
+export declare function getMachineSurface(): LineSurface | null;

package/build/modules/machines.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * The running machine surface, for settings and the machines API. Set by
+ * start() when the config declares lines; absent otherwise, so a deployment
+ * without machines serves no lines and no Lines view.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMachineSurface = registerMachineSurface;
+exports.getMachineSurface = getMachineSurface;
+let surface = null;
+function registerMachineSurface(next) {
+    surface = next;
+}
+function getMachineSurface() {
+    return surface;
+}

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/index.js

@@ -40,6 +40,7 @@ const nats_credentials_1 = __importDefault(require("./nats-credentials"));
 const scan_codes_1 = __importDefault(require("./scan-codes"));
 const domain_1 = __importDefault(require("./domain"));
 const announcements_1 = __importDefault(require("./announcements"));
+const machines_1 = __importDefault(require("./machines"));
 const router = (0, http_1.Router)();
 // Public routes (no auth required — they handle their own auth)
 router.use('/auth', auth_2.default);
@@ -80,6 +81,7 @@ router.use('/topics', topics_1.default);
 router.use('/scan-codes', scan_codes_1.default);
 router.use('/domain', domain_1.default);
 router.use('/announcements', announcements_1.default);
+router.use('/machines', machines_1.default);
 const overview_1 = __importDefault(require("./overview"));
 router.use('/overview', overview_1.default);
 const diagnostics_1 = __importDefault(require("./diagnostics"));

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.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;

package/build/routes/machines.js

@@ -0,0 +1,253 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const http_1 = require("../lib/http");
+const escalationsApi = __importStar(require("../api/escalations"));
+const auth_1 = require("../modules/auth");
+const machines_1 = require("../modules/machines");
+const commands_1 = require("../services/machines/commands");
+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
+ * take the ops tier (superadmin, admin type, or engineer); declaring and
+ * retiring a line takes an administrator. A command is a row parked on the
+ * machine's role as the caller, so that role's write access decides, exactly
+ * as it does for any row created through the API.
+ */
+const NO_LINES = 'no machine lines are declared';
+const NOT_LEADING = 'this replica is not leading the line';
+function lineOf(req) {
+    const surface = (0, machines_1.getMachineSurface)();
+    const siteId = String(req.params.siteId);
+    const lineId = String(req.params.lineId);
+    const line = surface?.findLine(siteId, lineId);
+    return { surface, siteId, lineId, line };
+}
+const SORTS = new Set(['attention', 'site', 'updated']);
+/** The longest search a person types; anything past it is cut, never an error. */
+const QUERY_MAX_CHARS = 200;
+function queryString(v) {
+    return typeof v === 'string' && v.trim() ? v.trim().slice(0, QUERY_MAX_CHARS) : undefined;
+}
+/** The line a path names, when both tokens could name a line at all. */
+function pathLine(req) {
+    const siteId = req.params.siteId;
+    const lineId = req.params.lineId;
+    return (0, topics_1.isTopicLevel)(siteId) && (0, topics_1.isTopicLevel)(lineId) ? { siteId, lineId } : null;
+}
+function queryBoolean(v) {
+    return v === 'true' ? true : v === 'false' ? false : undefined;
+}
+function queryInt(v) {
+    const n = typeof v === 'string' ? Number(v) : NaN;
+    return Number.isFinite(n) ? n : undefined;
+}
+router.get('/lines', auth_1.requireRoleManager, async (req, res) => {
+    const surface = (0, machines_1.getMachineSurface)();
+    if (!surface) {
+        res.status(404).json({ error: NO_LINES });
+        return;
+    }
+    const sort = queryString(req.query.sort);
+    if (sort && !SORTS.has(sort)) {
+        res.status(400).json({ error: `sort must be one of ${[...SORTS].join(', ')}` });
+        return;
+    }
+    const query = {
+        q: queryString(req.query.q), site: queryString(req.query.site), attention: queryBoolean(req.query.attention),
+        sort: sort, limit: queryInt(req.query.limit), offset: queryInt(req.query.offset),
+    };
+    const [page, sites] = await Promise.all([(0, registry_1.listLines)(query), (0, registry_1.listSites)()]);
+    const body = {
+        lines: page.lines.map((record) => (0, line_index_1.toLineIndexRow)(surface, record)),
+        total: page.total, sites, limit: page.limit, offset: page.offset,
+    };
+    res.status(200).json(body);
+});
+router.put('/lines/:siteId/:lineId', auth_1.requireAdmin, async (req, res) => {
+    const surface = (0, machines_1.getMachineSurface)();
+    if (!surface) {
+        res.status(404).json({ error: NO_LINES });
+        return;
+    }
+    const named = pathLine(req);
+    if (!named) {
+        res.status(400).json({ error: 'siteId and lineId must be topic levels' });
+        return;
+    }
+    const { siteId, lineId } = named;
+    const definition = req.body?.definition;
+    if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
+        res.status(400).json({ error: 'definition is required' });
+        return;
+    }
+    if (definition.siteId !== siteId || definition.lineId !== lineId) {
+        res.status(400).json({ error: `definition must be for ${siteId}/${lineId}` });
+        return;
+    }
+    const version = req.body?.version;
+    if (version !== undefined && !(Number.isInteger(version) && version >= 1)) {
+        res.status(400).json({ error: 'version must be a whole number of at least 1' });
+        return;
+    }
+    try {
+        const record = await (0, registry_sync_1.declareLine)(surface, definition, version);
+        const stored = (await (0, registry_1.getLineWithHealth)(siteId, lineId)) ?? { ...record, health: (0, line_index_1.emptyLineHealth)(record.definition.machines.length) };
+        res.status(200).json({ line: (0, line_index_1.toLineIndexRow)(surface, stored) });
+    }
+    catch (err) {
+        if (err instanceof registry_1.LineVersionConflict) {
+            res.status(409).json({ error: err.message });
+            return;
+        }
+        res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+    }
+});
+router.delete('/lines/:siteId/:lineId', auth_1.requireAdmin, async (req, res) => {
+    const surface = (0, machines_1.getMachineSurface)();
+    if (!surface) {
+        res.status(404).json({ error: NO_LINES });
+        return;
+    }
+    const named = pathLine(req);
+    if (!named) {
+        res.status(404).json({ error: 'no such line' });
+        return;
+    }
+    const { siteId, lineId } = named;
+    const record = await (0, registry_sync_1.retireLine)(surface, siteId, lineId);
+    if (!record) {
+        res.status(404).json({ error: `no line ${siteId}/${lineId}` });
+        return;
+    }
+    res.status(204).end();
+});
+router.get('/lines/:siteId/:lineId', auth_1.requireRoleManager, (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 body = {
+        ...(surface.describeLine(siteId, lineId) ?? { siteId, lineId, leading: false }),
+        summary: (0, line_index_1.lineSummaryOf)(surface, siteId, lineId, line),
+    };
+    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) {
+        res.status(404).json({ error: surface ? `no line ${siteId}/${lineId}` : NO_LINES });
+        return;
+    }
+    const topic = req.body?.topic;
+    if (typeof topic !== 'string' || !topic) {
+        res.status(400).json({ error: 'topic is required' });
+        return;
+    }
+    const result = surface.inspect(siteId, lineId, { topic, payload: (0, line_index_1.wirePayloadOf)(req.body?.payload), retained: req.body?.retained === true });
+    if (!result) {
+        res.status(409).json({ error: NOT_LEADING });
+        return;
+    }
+    res.status(200).json(result);
+});
+router.post('/lines/:siteId/:lineId/machines/:machineId/commands', 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 machineId = String(req.params.machineId);
+    if (!line.machines.some((m) => m.machineId === machineId)) {
+        res.status(404).json({ error: `no machine ${machineId} on ${siteId}/${lineId}` });
+        return;
+    }
+    const op = req.body?.op;
+    const ops = surface.commandOps(siteId, lineId);
+    if (typeof op !== 'string' || !ops.includes(op)) {
+        res.status(400).json({ error: `op must be one of ${ops.join(', ')}` });
+        return;
+    }
+    const args = req.body?.args;
+    if (args !== undefined && (!args || typeof args !== 'object' || Array.isArray(args))) {
+        res.status(400).json({ error: 'args must be an object' });
+        return;
+    }
+    const result = await escalationsApi.createEscalation((0, commands_1.commandRow)((0, commands_1.commandTarget)(line, machineId), op, args ?? {}), req.auth);
+    if (result.status !== 201) {
+        res.status(result.status).json({ error: result.error });
+        return;
+    }
+    res.status(201).json({ rowId: result.data.id });
+});
+exports.default = router;

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 }),