The label and the row share a facet

The physical worldScanSDKtarget_facetscanSchemesconditionalmetadata facets

A scheme names the metadata facet a label's target matches, so a printed code finds its row by the same value the workflow stamped.

The situation

Every physical item has a label, and every item in flight has a row that represents it. The label needs to find the row with no lookup table in between, and the row needs to stay findable however many queues it passes through.

The recipe

The workflow stamps the identifying value as a metadata facet when it parks the row:

const packed = await conditional<{ outcome: string }>(`pack-${serialNumber}`, {
  role: 'packing',
  description: `Pack carton ${serialNumber}`,
  metadata: { serialNumber, orderId, state: 'packed' },
});

The scheme declares which facet its targets resolve against:

scanSchemes: [{
  version: 12,
  name: 'Carton serial',
  target_facet: 'serialNumber',
  encoding: 'fixed',
  target_length: 8,
  rules: [{ category: '1', name: 'Locate',
            steps: [{ query: { roles: ['packing'] }, verb: 'show-detail' }] }],
}],

A label printed 12110000042 parses as scheme 12, rule 1, target 10000042, and the step finds the row whose serialNumber is 10000042. The scan is the join. encoding is delimited (text such as 12:1:SN-123, for Code 128, QR or DataMatrix), fixed (digits only, for UPC-style labels) or gtin (manufacturer barcodes as printed on products).

The guarantee

Resolution is metadata equality on the scheme’s facet, case-sensitive, inside the caller’s read scope. Facets commit with the row in the same checkpoint, so a row is findable from its first visible moment. Every mutating verb stamps scanScheme, scanCategory, scanActionName and scannedAt on the row it touches, so scan-driven transitions stay queryable. See Scan codes.

The physical world