@hotmeshio/long-tail 0.28.0 → 0.28.1

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 {

package/build/services/machines/contracts.js

@@ -6,7 +6,7 @@
  * protocol that resolves it differs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cancelCommandId = exports.controlCommandId = exports.dispatchCommandId = exports.COMMAND_STATUS = exports.signalKeys = exports.DECISION = exports.LIFECYCLE_FACET = exports.TRACE_FACET = exports.HANDOFF_ERROR = exports.itemKeys = exports.LINE_ROLE = exports.ROW_TYPE = void 0;
+exports.cancelCommandId = exports.controlCommandId = exports.dispatchCommandId = exports.COMMAND_STATUS = exports.signalKeys = exports.HOLD_DECISIONS = exports.DECISION = exports.LIFECYCLE_FACET = exports.TRACE_FACET = exports.HANDOFF_ERROR = exports.itemKeys = exports.LINE_ROLE = exports.ROW_TYPE = void 0;
 exports.arrivedUnit = arrivedUnit;
 exports.handoffProgress = handoffProgress;
 exports.handoffDecisions = handoffDecisions;
@@ -24,12 +24,16 @@ exports.ROW_TYPE = {
     CONTRACT_VIOLATION: 'contract-violation',
     /** An address claims a station the line already knows by another address, or the reverse: a person approves or rejects. */
     MACHINE_REGISTRATION: 'machine-registration',
+    /** Units a machine finished on hold wait for a quality decision: release, rework or scrap. */
+    QUALITY_HOLD: 'quality-hold',
 };
 exports.LINE_ROLE = {
     /** People who clear alarms, bring machines back and decide failed handoffs. */
     OPERATOR: line_1.DEFAULT_OPERATOR_ROLE,
     /** People who take finished units off the line: the final handoff. */
     EXIT: line_1.DEFAULT_EXIT_ROLE,
+    /** People who decide units a machine finished on hold. */
+    QUALITY: line_1.DEFAULT_QUALITY_ROLE,
     /** The gateway's own identity. */
     CONTROLLER: 'line-controller',
 };
@@ -75,6 +79,8 @@ exports.HANDOFF_ERROR = {
     SOFTWARE_UNSUPPORTED: 'software-unsupported',
     WITHDRAWN: 'withdrawn',
     CANCELLED: 'cancelled',
+    /** An arrival no open handoff into the machine expects, shown to the operator role once per machine and carrier. */
+    UNMATCHED_ARRIVAL: 'unmatched-arrival',
     ...protocol_1.TRANSFER_FAILURE,
 };
 /**
@@ -95,6 +101,10 @@ exports.DECISION = {
     RESTORED: 'restored',
     APPROVE: 'approve',
     REJECT: 'reject',
+    /** A quality decision on held units: they continue from where they are. */
+    RELEASE: 'release',
+    /** A quality decision on held units: they run again from a station on the route. */
+    REWORK: 'rework',
 };
 /**
  * Failures a retry cannot repair. Units a sender finished as not ok leave the
@@ -107,11 +117,15 @@ function handoffDecisions(errorCode) {
     const noRetry = !!errorCode && NO_RETRY.includes(errorCode);
     return noRetry ? [exports.DECISION.MANUAL, exports.DECISION.SCRAP] : [exports.DECISION.RETRY, exports.DECISION.MANUAL, exports.DECISION.SCRAP];
 }
+/** The decisions a quality role may take on units a machine finished on hold. */
+exports.HOLD_DECISIONS = [exports.DECISION.RELEASE, exports.DECISION.REWORK, exports.DECISION.SCRAP];
 /** Signal keys for the unit workflow; every attempt mints a fresh key. */
 exports.signalKeys = {
     handoff: (jobKey, step, attempt) => `handoff-${jobKey}-s${step}-a${attempt}`,
     handoffError: (jobKey, step, attempt, round = 1) => `handoff-error-${jobKey}-s${step}-a${attempt}${round > 1 ? `-r${round}` : ''}`,
     jobStop: (jobKey, step, attempt) => `job-stop-${jobKey}-s${step}-a${attempt}`,
+    hold: (jobKey, step, attempt, round = 1) => `hold-${jobKey}-s${step}-a${attempt}${round > 1 ? `-r${round}` : ''}`,
+    disposition: (jobKey, step, attempt) => `disposition-${jobKey}-s${step}-a${attempt}`,
 };
 exports.COMMAND_STATUS = { ...protocol_1.REPLY_STATUS, NO_REPLY: 'no-reply', UNSUPPORTED: 'unsupported' };
 /** A row's dispatch command in its validity round; a later round is a new command (gateway/pacing.ts dispatchWindow). */

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

@@ -36,7 +36,7 @@ export declare const OPERATOR_FORM_SCHEMA: {
     properties: {
         decision: {
             type: string;
-            enum: ("reject" | "scrap" | "retry" | "manual" | "acknowledge" | "cleared" | "restored" | "approve")[];
+            enum: ("release" | "reject" | "scrap" | "rework" | "retry" | "manual" | "acknowledge" | "cleared" | "restored" | "approve")[];
             default: "acknowledge";
             description: string;
         };
@@ -53,3 +53,28 @@ export declare const OPERATOR_FORM_SCHEMA: {
         };
     };
 };
+export declare const QUALITY_FORM_SCHEMA: {
+    title: string;
+    description: string;
+    'x-lt-order': string[];
+    required: string[];
+    properties: {
+        decision: {
+            type: string;
+            enum: ("release" | "scrap" | "rework")[];
+            default: "release";
+            description: string;
+        };
+        station: {
+            type: string;
+            default: string;
+            description: string;
+        };
+        note: {
+            type: string;
+            format: string;
+            default: string;
+            description: string;
+        };
+    };
+};

package/build/services/machines/forms.js

@@ -6,7 +6,7 @@
  * handoffs and close alarm and machine-state rows.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPERATOR_FORM_SCHEMA = exports.HANDOFF_FORM_SCHEMA = void 0;
+exports.QUALITY_FORM_SCHEMA = exports.OPERATOR_FORM_SCHEMA = exports.HANDOFF_FORM_SCHEMA = void 0;
 const contracts_1 = require("./contracts");
 exports.HANDOFF_FORM_SCHEMA = {
     title: 'Receive units',
@@ -35,3 +35,19 @@ exports.OPERATOR_FORM_SCHEMA = {
         clearedBy: { type: 'string', default: '', description: 'Who cleared it at the machine, when the machine reports it' },
     },
 };
+exports.QUALITY_FORM_SCHEMA = {
+    title: 'Quality decision',
+    description: 'Units a machine finished on hold: release them to continue, send them back to a station for rework, or scrap them.',
+    'x-lt-order': ['decision', 'station', 'note'],
+    required: ['decision'],
+    properties: {
+        decision: {
+            type: 'string',
+            enum: [contracts_1.DECISION.RELEASE, contracts_1.DECISION.REWORK, contracts_1.DECISION.SCRAP],
+            default: contracts_1.DECISION.RELEASE,
+            description: 'Release, rework or scrap',
+        },
+        station: { type: 'string', default: '', description: 'For rework: the station the units run again from; the holding station when empty' },
+        note: { type: 'string', format: 'textarea', default: '', description: 'What was found' },
+    },
+};

package/build/services/machines/gateway/actions.d.ts

@@ -18,14 +18,19 @@ export interface CreateRowInput {
     escalation_payload?: string;
 }
 export type Action = 
-/** `receivedOnAccept`: the units are already at the machine, so its acceptance completes the handoff. */
+/**
+ * `receivedOnAccept`: the units are already at the machine, so its acceptance completes the handoff.
+ * `ended`: the row already resolved; the job is sent again for units the machine still holds, and no verb touches the row.
+ */
 {
     kind: 'dispatch';
     rowId: string;
     machineId: string;
     cmdId: string;
     args: Record<string, any>;
+    issuedAt?: number;
     receivedOnAccept?: boolean;
+    ended?: boolean;
 } | {
     kind: 'command';
     machineId: string;
@@ -79,6 +84,7 @@ export type Action =
     status: string;
     reason: string;
     code?: string;
+    preparing?: boolean;
 }
 /** A machine reported the jobs it holds: answers a status query in flight. */
  | {
@@ -99,6 +105,12 @@ export type Action =
     machineId: string;
     address: string;
     reason: string;
+}
+/** Jobs a restarted machine lost that this gateway cannot send again: nothing of them is remembered. */
+ | {
+    kind: 'unrecoverable';
+    machineId: string;
+    jobs: string[];
 };
 /** Once the row holds every one of `keys`: resolve it with `payload`, or run `then` instead. */
 export interface Completion {

package/build/services/machines/gateway/admission.d.ts

@@ -4,8 +4,9 @@
  * and under a strict codec a message that breaks the contract is held for a
  * person instead of acted on.
  */
+import type { OpenRowQuery } from '../rows';
 import { type LineDef } from '../../../lib/machines/line';
-import type { Inspection } from '../../../lib/machines/protocol';
+import { type Inspection } from '../../../lib/machines/protocol';
 import { type Disposition, type InboundMessage } from '../../../lib/machines/transport';
 import type { WireAction } from '../../../types/machines-view';
 import type { Action } from './actions';
@@ -36,6 +37,8 @@ export interface AdmissionContext {
     log: GatewayLog;
     /** Send waiting handoffs that may now go out. */
     pace(): Promise<void>;
+    /** The controller's pending rows of a type, for the rows shown to people once. */
+    openRows(query: OpenRowQuery): Promise<Record<string, any>[]>;
 }
 /**
  * The station a message is from (registration.ts). A newly claimed station is
@@ -45,3 +48,14 @@ export interface AdmissionContext {
 export declare function admitSender(ctx: AdmissionContext, topic: string, raw: Inspection): Promise<Admitted | Applied>;
 /** Under a strict codec a broken message is not acted on: a person sees it on a row, once. */
 export declare function holdViolation(ctx: AdmissionContext, msg: InboundMessage, seen: Inspection): Promise<Applied>;
+/** A job arrival: a scan, or a transfer that failed on the carrier read. */
+export declare function isArrival(seen: Inspection): boolean;
+/** An arrival that read no id at all: no row can ever claim it, so it goes to a person on its first delivery. */
+export declare function isUnreadableArrival(seen: Inspection): boolean;
+/**
+ * An arrival no open handoff into the machine expects, after every delivery:
+ * a person sees it on one handoff-error row per machine and carrier, with the
+ * raw arrival, so the unit can be re-scanned or routed. Resolving the row lets
+ * the next such arrival raise one again.
+ */
+export declare function holdArrival(ctx: AdmissionContext, msg: InboundMessage, seen: Inspection): Promise<Applied>;

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

@@ -8,8 +8,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.admitSender = admitSender;
 exports.holdViolation = holdViolation;
+exports.isArrival = isArrival;
+exports.isUnreadableArrival = isUnreadableArrival;
+exports.holdArrival = holdArrival;
 const contracts_1 = require("../contracts");
 const line_1 = require("../../../lib/machines/line");
+const protocol_1 = require("../../../lib/machines/protocol");
 const transport_1 = require("../../../lib/machines/transport");
 const dispatcher_1 = require("./dispatcher");
 const log_1 = require("./log");
@@ -79,3 +83,46 @@ async function holdViolation(ctx, msg, seen) {
         return { disposition: transport_1.DISPOSITION.NAK, failed: true, actions: [] };
     }
 }
+/** A job arrival: a scan, or a transfer that failed on the carrier read. */
+function isArrival(seen) {
+    const event = seen.body?.body?.event;
+    return seen.parsed?.kind === protocol_1.MESSAGE_KIND.JOB && (event === protocol_1.JOB_EVENT.ARRIVED || event === protocol_1.JOB_EVENT.TRANSFER_FAILED);
+}
+/** An arrival that read no id at all: no row can ever claim it, so it goes to a person on its first delivery. */
+function isUnreadableArrival(seen) {
+    return seen.parsed?.kind === protocol_1.MESSAGE_KIND.JOB && (0, protocol_1.isUnreadableRead)(seen.body?.body ?? {});
+}
+/**
+ * An arrival no open handoff into the machine expects, after every delivery:
+ * a person sees it on one handoff-error row per machine and carrier, with the
+ * raw arrival, so the unit can be re-scanned or routed. Resolving the row lets
+ * the next such arrival raise one again.
+ */
+async function holdArrival(ctx, msg, seen) {
+    const { ident } = seen.parsed;
+    const body = seen.body?.body ?? {};
+    const carrierId = typeof body.carrierId === 'string' ? body.carrierId : null;
+    const unitId = typeof body.unitId === 'string' ? body.unitId : null;
+    const detail = `no handoff into ${ident.machineId} expects ${carrierId ? `carrier ${carrierId}` : 'an unreadable carrier'}`;
+    try {
+        const open = await ctx.openRows({ type: contracts_1.ROW_TYPE.HANDOFF_ERROR, role: (0, line_1.operatorRole)(ctx.line) });
+        const shown = open.find((r) => r.metadata?.errorCode === contracts_1.HANDOFF_ERROR.UNMATCHED_ARRIVAL && r.metadata?.machineId === ident.machineId && (r.metadata?.carrierId ?? null) === carrierId);
+        if (shown)
+            return { disposition: transport_1.DISPOSITION.ACK, failed: false, actions: [{ verb: 'unmatched', rowId: shown.id, detail: `${detail} (already shown to a person)` }] };
+        const [made] = await ctx.executor.apply([{ kind: 'createRow', row: {
+                    type: contracts_1.ROW_TYPE.HANDOFF_ERROR, role: (0, line_1.operatorRole)(ctx.line), priority: 2,
+                    description: `${ident.machineId} reports an arrival no handoff expects: ${carrierId ? `carrier ${carrierId}` : 'the carrier could not be read'}`,
+                    metadata: {
+                        siteId: ident.siteId, lineId: ident.lineId, machineId: ident.machineId, errorCode: contracts_1.HANDOFF_ERROR.UNMATCHED_ARRIVAL,
+                        carrierId, unitId, event: body.event, topic: msg.topic, messageId: seen.body?.id ?? null, arrival: body,
+                    },
+                    escalation_payload: msg.payload,
+                } }]);
+        return { disposition: transport_1.DISPOSITION.ACK, failed: false, actions: [{ verb: 'create-row', rowId: made?.rowId, detail }] };
+    }
+    catch (err) {
+        if (!(err instanceof dispatcher_1.GatewayStopped))
+            ctx.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { topic: msg.topic, error: err.message });
+        return { disposition: transport_1.DISPOSITION.NAK, failed: true, actions: [] };
+    }
+}