@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/lib/icon-search.ts

@@ -0,0 +1,65 @@
+/**
+ * Icon-name search for the definition icon picker (spec section 4.5:
+ * "searchable lucide grid").
+ *
+ * The grid searches the platform's SHARED lucide registry
+ * (`@open-mercato/ui/backend/icons/lucideRegistry`) rather than the full lucide
+ * export: that registry is generated from the icon names actually used across
+ * the repo and is already in every backend page's chunk through `AppShell`, so
+ * the picker adds no icons to the bundle at all. Importing `lucide-react`
+ * wholesale would have pulled well over a thousand components into the editor
+ * chunk for a field that stores one string.
+ *
+ * PURE: string in, strings out — no React, no icon components.
+ */
+
+/** Enough to fill the grid without rendering a thousand buttons at once. */
+export const ICON_SEARCH_RESULT_LIMIT = 120
+
+function normalizeIconQuery(query: string): string {
+  return query.trim().toLowerCase().replace(/[\s_]+/g, '-')
+}
+
+/**
+ * Normalize an author-entered icon value to the registry's kebab-case key.
+ *
+ * The field has always been free text, so stored values are a mix of
+ * `ShoppingCart`, `shopping-cart` and `lucide:shopping-cart`. Matching them all
+ * is what lets an existing definition open with its icon selected instead of
+ * looking unset.
+ */
+export function normalizeIconName(value: string | null | undefined): string {
+  if (!value) return ''
+  const trimmed = value.trim()
+  if (!trimmed) return ''
+  const withoutPrefix = trimmed.startsWith('lucide:') ? trimmed.slice('lucide:'.length) : trimmed
+  if (!withoutPrefix) return ''
+  if (!/[-_\s]/.test(withoutPrefix) && /[A-Z]/.test(withoutPrefix)) {
+    return withoutPrefix
+      .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+      .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+      .toLowerCase()
+  }
+  return withoutPrefix.replace(/[_\s]+/g, '-').replace(/-+/g, '-').toLowerCase()
+}
+
+/**
+ * Filter icon names by query, ranking a prefix match above a substring match so
+ * typing "cart" surfaces `cart` before `shopping-cart`. Names are compared
+ * pairwise for ordering — never an uncompared sort on a shared array (#3620).
+ */
+export function filterIconNames(
+  names: readonly string[],
+  query: string,
+  limit: number = ICON_SEARCH_RESULT_LIMIT,
+): string[] {
+  const normalized = normalizeIconQuery(query)
+  if (!normalized) return names.slice(0, limit)
+  const prefixMatches: string[] = []
+  const substringMatches: string[] = []
+  for (const name of names) {
+    if (name.startsWith(normalized)) prefixMatches.push(name)
+    else if (name.includes(normalized)) substringMatches.push(name)
+  }
+  return [...prefixMatches, ...substringMatches].slice(0, limit)
+}

package/src/modules/workflows/lib/insert-at-cursor.ts

@@ -0,0 +1,53 @@
+/**
+ * Workflows Module - cursor-aware text insertion (spec
+ * 2026-07-26-workflows-ux-redesign.md section 3.5, step 3.2).
+ *
+ * Pure helper shared by the variable picker: given the current value of a
+ * text control and a selection range, produce the value with the insertion
+ * spliced in and the cursor position immediately after it. Works identically
+ * for `<input>` and `<textarea>` — the element-facing wrapper only reads
+ * `selectionStart`/`selectionEnd`, degrading to append-at-end when the
+ * element is missing or does not expose a selection (e.g. non-text inputs).
+ */
+
+export interface CursorInsertionResult {
+  value: string
+  cursor: number
+}
+
+export function insertAtCursor(
+  currentValue: string,
+  insertion: string,
+  selectionStart: number | null,
+  selectionEnd: number | null,
+): CursorInsertionResult {
+  const length = currentValue.length
+  const clamp = (position: number) => Math.min(Math.max(position, 0), length)
+  const start = selectionStart === null ? length : clamp(selectionStart)
+  const end = selectionEnd === null ? start : Math.max(clamp(selectionEnd), start)
+  const value = `${currentValue.slice(0, start)}${insertion}${currentValue.slice(end)}`
+  return { value, cursor: start + insertion.length }
+}
+
+export interface CursorInsertionTarget {
+  selectionStart: number | null
+  selectionEnd: number | null
+}
+
+export function insertAtElementCursor(
+  element: CursorInsertionTarget | null,
+  currentValue: string,
+  insertion: string,
+): CursorInsertionResult {
+  if (element === null) return insertAtCursor(currentValue, insertion, null, null)
+  let selectionStart: number | null = null
+  let selectionEnd: number | null = null
+  try {
+    selectionStart = element.selectionStart
+    selectionEnd = element.selectionEnd
+  } catch {
+    selectionStart = null
+    selectionEnd = null
+  }
+  return insertAtCursor(currentValue, insertion, selectionStart, selectionEnd)
+}

package/src/modules/workflows/lib/instance-date-filter.ts

@@ -0,0 +1,56 @@
+/**
+ * Run-list date filtering (spec §8.3: "Run list: filters by definition, status,
+ * correlationKey, date") — PURE.
+ *
+ * The filter bar's date-range control emits calendar days (`yyyy-MM-dd`), not
+ * instants, so `to` has to cover the WHOLE day or "started on the 3rd" silently
+ * excludes everything after midnight. Callers may also pass a full ISO
+ * timestamp, which is taken verbatim.
+ *
+ * An unparseable value is an ERROR, never a silently dropped filter: handing
+ * `new Date('garbage')` to the ORM is an Invalid Date, and a query built from
+ * one answers nothing while looking like it answered something.
+ */
+
+const CALENDAR_DAY = /^\d{4}-\d{2}-\d{2}$/
+
+export type DateBoundaryResult =
+  | { ok: true; value: Date | null }
+  | { ok: false; error: string }
+
+function parseBoundary(raw: string | null | undefined, edge: 'start' | 'end'): DateBoundaryResult {
+  if (raw === null || raw === undefined || raw === '') return { ok: true, value: null }
+  const normalized = CALENDAR_DAY.test(raw)
+    ? `${raw}${edge === 'start' ? 'T00:00:00.000Z' : 'T23:59:59.999Z'}`
+    : raw
+  const parsed = new Date(normalized)
+  if (Number.isNaN(parsed.getTime())) {
+    return { ok: false, error: `Invalid date value: ${raw}` }
+  }
+  return { ok: true, value: parsed }
+}
+
+export type StartedAtRangeResult =
+  | { ok: true; range: { $gte?: Date; $lte?: Date } | null }
+  | { ok: false; error: string }
+
+export function buildStartedAtRange(
+  from: string | null | undefined,
+  to: string | null | undefined
+): StartedAtRangeResult {
+  const parsedFrom = parseBoundary(from, 'start')
+  if (!parsedFrom.ok) return { ok: false, error: parsedFrom.error }
+  const parsedTo = parseBoundary(to, 'end')
+  if (!parsedTo.ok) return { ok: false, error: parsedTo.error }
+
+  if (!parsedFrom.value && !parsedTo.value) return { ok: true, range: null }
+
+  if (parsedFrom.value && parsedTo.value && parsedFrom.value.getTime() > parsedTo.value.getTime()) {
+    return { ok: false, error: 'startedFrom must not be after startedTo' }
+  }
+
+  const range: { $gte?: Date; $lte?: Date } = {}
+  if (parsedFrom.value) range.$gte = parsedFrom.value
+  if (parsedTo.value) range.$lte = parsedTo.value
+  return { ok: true, range }
+}

package/src/modules/workflows/lib/interpolation-pipeline.ts

@@ -0,0 +1,351 @@
+/**
+ * Workflows Module - interpolation pipeline grammar (spec
+ * 2026-07-26-workflows-ux-redesign.md section 3.6, Phase 2b).
+ *
+ * Pure, dependency-free parser and evaluator for the pill transform pipeline
+ * inside `{{ }}` interpolation tokens: `path | fn(args) | fn2(...)`. No React,
+ * no ORM, no DI container, no registry imports — the module must stay loadable
+ * from the browser bundle and from the runtime engine alike
+ * (`interpolation-pipeline-import-boundary.test.ts` guards this).
+ *
+ * Grammar:
+ * - The token text between `{{` and `}}` splits on top-level `|` characters
+ *   (pipes inside quoted strings or parentheses are literal). The first
+ *   segment is the lookup path (trimmed, exactly as the legacy interpolator
+ *   treats it); every following segment is one transform call.
+ * - A transform call is `name` or `name(arg, arg2, ...)` where `name` matches
+ *   `[A-Za-z_][A-Za-z0-9_]*` and each argument is a JSON-ish literal: a
+ *   single- or double-quoted string (backslash escapes), a number, `true`,
+ *   `false`, or `null`. No arbitrary expressions, no eval.
+ * - A pipe-free token parses to `{ path, transforms: [] }`, keeping legacy
+ *   tokens byte-identical in behavior.
+ *
+ * The transform table is fixed and every entry is a pure function; evaluation
+ * either succeeds with a value or fails with a typed error (`unknown-transform`,
+ * `invalid-args`, `invalid-input`) that the caller maps to lenient
+ * pass-through or strict failure.
+ */
+
+export type WorkflowInterpolationMode = 'strict' | 'lenient'
+
+export function resolveDefinitionInterpolationMode(
+  definitionData: unknown,
+): WorkflowInterpolationMode | undefined {
+  if (!definitionData || typeof definitionData !== 'object') return undefined
+  const mode = (definitionData as { interpolation?: unknown }).interpolation
+  return mode === 'strict' || mode === 'lenient' ? mode : undefined
+}
+
+export type TransformArg = string | number | boolean | null
+
+export interface ParsedTransform {
+  name: string
+  args: TransformArg[]
+}
+
+export interface ParsedInterpolationToken {
+  path: string
+  transforms: ParsedTransform[]
+}
+
+export type InterpolationTokenParseResult =
+  | { ok: true; path: string; transforms: ParsedTransform[] }
+  | { ok: false; error: string }
+
+export type TransformErrorCode = 'unknown-transform' | 'invalid-args' | 'invalid-input'
+
+export interface TransformError {
+  code: TransformErrorCode
+  transform: string
+  message: string
+}
+
+export type TransformApplyResult =
+  | { ok: true; value: unknown }
+  | { ok: false; error: TransformError }
+
+const TRANSFORM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+function splitTopLevel(input: string, separator: string): string[] | null {
+  const segments: string[] = []
+  let current = ''
+  let depth = 0
+  let quote: string | null = null
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index]
+    if (quote !== null) {
+      current += char
+      if (char === '\\' && index + 1 < input.length) {
+        current += input[index + 1]
+        index += 1
+      } else if (char === quote) {
+        quote = null
+      }
+      continue
+    }
+    if (char === "'" || char === '"') {
+      quote = char
+      current += char
+      continue
+    }
+    if (char === '(') depth += 1
+    if (char === ')') {
+      depth -= 1
+      if (depth < 0) return null
+    }
+    if (char === separator && depth === 0) {
+      segments.push(current)
+      current = ''
+      continue
+    }
+    current += char
+  }
+  if (quote !== null || depth !== 0) return null
+  segments.push(current)
+  return segments
+}
+
+function parseLiteralArg(raw: string): { ok: true; value: TransformArg } | { ok: false } {
+  if (!raw) return { ok: false }
+  const first = raw[0]
+  if ((first === "'" || first === '"') && raw.length >= 2 && raw.endsWith(first)) {
+    const body = raw.slice(1, -1)
+    let value = ''
+    for (let index = 0; index < body.length; index += 1) {
+      const char = body[index]
+      if (char === '\\' && index + 1 < body.length) {
+        value += body[index + 1]
+        index += 1
+        continue
+      }
+      if (char === first) return { ok: false }
+      value += char
+    }
+    return { ok: true, value }
+  }
+  if (raw === 'true') return { ok: true, value: true }
+  if (raw === 'false') return { ok: true, value: false }
+  if (raw === 'null') return { ok: true, value: null }
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return { ok: true, value: Number(raw) }
+  return { ok: false }
+}
+
+function parseTransformSegment(
+  segment: string,
+): { ok: true; transform: ParsedTransform } | { ok: false; error: string } {
+  const trimmed = segment.trim()
+  if (!trimmed) return { ok: false, error: 'empty transform segment' }
+  const parenIndex = trimmed.indexOf('(')
+  if (parenIndex === -1) {
+    if (!TRANSFORM_NAME_PATTERN.test(trimmed)) {
+      return { ok: false, error: `invalid transform name "${trimmed}"` }
+    }
+    return { ok: true, transform: { name: trimmed, args: [] } }
+  }
+  const name = trimmed.slice(0, parenIndex).trim()
+  if (!TRANSFORM_NAME_PATTERN.test(name)) {
+    return { ok: false, error: `invalid transform name "${name}"` }
+  }
+  if (!trimmed.endsWith(')')) {
+    return { ok: false, error: `unterminated arguments for transform "${name}"` }
+  }
+  const argsSource = trimmed.slice(parenIndex + 1, -1).trim()
+  if (!argsSource) return { ok: true, transform: { name, args: [] } }
+  const rawArgs = splitTopLevel(argsSource, ',')
+  if (rawArgs === null) {
+    return { ok: false, error: `unbalanced arguments for transform "${name}"` }
+  }
+  const args: TransformArg[] = []
+  for (const rawArg of rawArgs) {
+    const trimmedArg = rawArg.trim()
+    const parsedArg = parseLiteralArg(trimmedArg)
+    if (!parsedArg.ok) {
+      return { ok: false, error: `invalid argument "${trimmedArg}" for transform "${name}"` }
+    }
+    args.push(parsedArg.value)
+  }
+  return { ok: true, transform: { name, args } }
+}
+
+export function parseInterpolationToken(token: string): InterpolationTokenParseResult {
+  const segments = splitTopLevel(token, '|')
+  if (segments === null) {
+    return { ok: false, error: 'unbalanced quotes or parentheses in interpolation token' }
+  }
+  const path = segments[0].trim()
+  if (!path) return { ok: false, error: 'empty interpolation path' }
+  const transforms: ParsedTransform[] = []
+  for (const segment of segments.slice(1)) {
+    const parsed = parseTransformSegment(segment)
+    if (!parsed.ok) return { ok: false, error: parsed.error }
+    transforms.push(parsed.transform)
+  }
+  return { ok: true, path, transforms }
+}
+
+function invalidArgs(transform: string, message: string): TransformApplyResult {
+  return { ok: false, error: { code: 'invalid-args', transform, message } }
+}
+
+function invalidInput(transform: string, message: string): TransformApplyResult {
+  return { ok: false, error: { code: 'invalid-input', transform, message } }
+}
+
+function coerceText(value: unknown): string | null {
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  return null
+}
+
+function toDateValue(value: unknown): Date | null {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+  if (typeof value === 'number' || (typeof value === 'string' && value.trim() !== '')) {
+    const parsed = new Date(value)
+    return Number.isNaN(parsed.getTime()) ? null : parsed
+  }
+  return null
+}
+
+function padDatePart(part: number, length: number): string {
+  return String(part).padStart(length, '0')
+}
+
+function formatDate(date: Date, format: string): string {
+  return format.replace(/yyyy|SSS|MM|dd|HH|mm|ss/g, (token) => {
+    switch (token) {
+      case 'yyyy':
+        return padDatePart(date.getUTCFullYear(), 4)
+      case 'MM':
+        return padDatePart(date.getUTCMonth() + 1, 2)
+      case 'dd':
+        return padDatePart(date.getUTCDate(), 2)
+      case 'HH':
+        return padDatePart(date.getUTCHours(), 2)
+      case 'mm':
+        return padDatePart(date.getUTCMinutes(), 2)
+      case 'ss':
+        return padDatePart(date.getUTCSeconds(), 2)
+      case 'SSS':
+        return padDatePart(date.getUTCMilliseconds(), 3)
+      default:
+        return token
+    }
+  })
+}
+
+type TransformImpl = (value: unknown, args: TransformArg[]) => TransformApplyResult
+
+function textTransform(name: string, apply: (text: string) => string): TransformImpl {
+  return (value, args) => {
+    if (args.length !== 0) return invalidArgs(name, 'expects no arguments')
+    const text = coerceText(value)
+    if (text === null) return invalidInput(name, 'value is not text')
+    return { ok: true, value: apply(text) }
+  }
+}
+
+function affixTransform(name: string, combine: (text: string, affix: string) => string): TransformImpl {
+  return (value, args) => {
+    if (args.length !== 1) return invalidArgs(name, 'expects exactly one argument')
+    const affix = coerceText(args[0])
+    if (affix === null) return invalidArgs(name, 'argument must be text')
+    const text = coerceText(value)
+    if (text === null) return invalidInput(name, 'value is not text')
+    return { ok: true, value: combine(text, affix) }
+  }
+}
+
+const transformTable: Record<string, TransformImpl> = {
+  date: (value, args) => {
+    if (args.length > 1 || (args.length === 1 && typeof args[0] !== 'string')) {
+      return invalidArgs('date', 'expects an optional format string')
+    }
+    const date = toDateValue(value)
+    if (date === null) return invalidInput('date', 'value is not a date')
+    if (args.length === 0) return { ok: true, value: date.toISOString() }
+    return { ok: true, value: formatDate(date, args[0] as string) }
+  },
+  number: (value, args) => {
+    if (args.length > 2) return invalidArgs('number', 'expects at most decimals and locale')
+    const decimals = args[0]
+    if (
+      args.length >= 1 &&
+      (typeof decimals !== 'number' || !Number.isInteger(decimals) || decimals < 0 || decimals > 20)
+    ) {
+      return invalidArgs('number', 'decimals must be an integer between 0 and 20')
+    }
+    const locale = args[1]
+    if (args.length === 2 && typeof locale !== 'string') {
+      return invalidArgs('number', 'locale must be a string')
+    }
+    const numeric =
+      typeof value === 'number'
+        ? value
+        : typeof value === 'string' && value.trim() !== ''
+          ? Number(value)
+          : Number.NaN
+    if (!Number.isFinite(numeric)) return invalidInput('number', 'value is not a finite number')
+    if (args.length === 0) return { ok: true, value: String(numeric) }
+    if (args.length === 1) return { ok: true, value: numeric.toFixed(decimals as number) }
+    try {
+      const formatter = new Intl.NumberFormat(locale as string, {
+        minimumFractionDigits: decimals as number,
+        maximumFractionDigits: decimals as number,
+      })
+      return { ok: true, value: formatter.format(numeric) }
+    } catch {
+      return invalidArgs('number', `unknown locale "${String(locale)}"`)
+    }
+  },
+  upper: textTransform('upper', (text) => text.toUpperCase()),
+  lower: textTransform('lower', (text) => text.toLowerCase()),
+  title: textTransform('title', (text) =>
+    text.toLowerCase().replace(/(^|\s)(\S)/g, (_match, boundary: string, letter: string) => `${boundary}${letter.toUpperCase()}`),
+  ),
+  concat: affixTransform('concat', (text, suffix) => `${text}${suffix}`),
+  prepend: affixTransform('prepend', (text, prefix) => `${prefix}${text}`),
+  default: (value, args) => {
+    if (args.length !== 1) return invalidArgs('default', 'expects exactly one value')
+    const isEmpty = value === undefined || value === null || value === ''
+    return { ok: true, value: isEmpty ? args[0] : value }
+  },
+  pick: (value, args) => {
+    if (args.length !== 1 || (typeof args[0] !== 'string' && typeof args[0] !== 'number')) {
+      return invalidArgs('pick', 'expects a field name or index')
+    }
+    const key = args[0]
+    if (Array.isArray(value)) {
+      const index = typeof key === 'number' ? key : Number(key)
+      return { ok: true, value: Number.isInteger(index) ? value[index] : undefined }
+    }
+    if (value !== null && typeof value === 'object') {
+      return { ok: true, value: (value as Record<string, unknown>)[String(key)] }
+    }
+    return invalidInput('pick', 'value is not an object or array')
+  },
+}
+
+export const interpolationTransformNames: readonly string[] = Object.freeze(
+  Object.keys(transformTable),
+)
+
+export function applyTransforms(value: unknown, transforms: ParsedTransform[]): TransformApplyResult {
+  let current: unknown = value
+  for (const transform of transforms) {
+    const impl = transformTable[transform.name]
+    if (!impl) {
+      return {
+        ok: false,
+        error: {
+          code: 'unknown-transform',
+          transform: transform.name,
+          message: `unknown transform "${transform.name}"`,
+        },
+      }
+    }
+    const result = impl(current, transform.args)
+    if (!result.ok) return result
+    current = result.value
+  }
+  return { ok: true, value: current }
+}

package/src/modules/workflows/lib/ledger-drag.ts

@@ -0,0 +1,61 @@
+/**
+ * Workflows Module - drag-a-field-into-a-parameter transfer contract (spec
+ * 2026-07-26-workflows-ux-redesign.md section 3.5: "click and drag are both
+ * first-class").
+ *
+ * A ledger row in the Input data panel carries TWO payloads:
+ * - `text/plain` = the ready-to-paste `{{path}}` pill, so dropping onto ANY
+ *   `<input>`/`<textarea>` works through the browser's native text drop even
+ *   where this module has no handler at all;
+ * - a private MIME carrying the BARE path, so template-capable fields can
+ *   intercept the drop, insert at the caret through `insertAtElementCursor`,
+ *   and choose their own insert mode (mapping cells take bare paths).
+ *
+ * Pure and DOM-free: it reads a minimal `DataTransfer` shape, so both the drag
+ * payload and the drop insertion are unit-testable without a real drag gesture.
+ */
+
+import { insertAtElementCursor, type CursorInsertionResult, type CursorInsertionTarget } from './insert-at-cursor'
+
+export const LEDGER_PATH_MIME = 'application/x-om-ledger-path'
+
+export type LedgerInsertMode = 'template' | 'bare'
+
+export interface LedgerDragDataTransfer {
+  getData: (type: string) => string
+  setData: (type: string, value: string) => void
+  types?: ReadonlyArray<string>
+}
+
+export function ledgerInsertionText(path: string, insertMode: LedgerInsertMode): string {
+  return insertMode === 'bare' ? path : `{{${path}}}`
+}
+
+/** Writes both payloads for a dragged ledger row. */
+export function writeLedgerDragPayload(dataTransfer: LedgerDragDataTransfer, path: string): void {
+  dataTransfer.setData('text/plain', ledgerInsertionText(path, 'template'))
+  dataTransfer.setData(LEDGER_PATH_MIME, path)
+}
+
+/** The dragged ledger path, or null when the drag did not come from the panel. */
+export function readLedgerDragPath(dataTransfer: LedgerDragDataTransfer | null | undefined): string | null {
+  if (!dataTransfer) return null
+  if (Array.isArray(dataTransfer.types) && !dataTransfer.types.includes(LEDGER_PATH_MIME)) return null
+  const path = dataTransfer.getData(LEDGER_PATH_MIME)
+  return typeof path === 'string' && path.length > 0 ? path : null
+}
+
+/**
+ * Resolves what a drop should write into a text control. Returns null when the
+ * payload is not a ledger path, leaving the browser's native handling intact.
+ */
+export function resolveLedgerDrop(
+  dataTransfer: LedgerDragDataTransfer | null | undefined,
+  target: CursorInsertionTarget | null,
+  currentValue: string,
+  insertMode: LedgerInsertMode = 'template',
+): CursorInsertionResult | null {
+  const path = readLedgerDragPath(dataTransfer)
+  if (path === null) return null
+  return insertAtElementCursor(target, currentValue, ledgerInsertionText(path, insertMode))
+}

package/src/modules/workflows/lib/ledger-entry-display.ts

@@ -0,0 +1,89 @@
+/**
+ * Workflows Module - shared ledger-entry presentation helpers (spec
+ * 2026-07-26-workflows-ux-redesign.md sections 3.5 / 5).
+ *
+ * The variable picker popover and the Input data panel list the SAME ledger:
+ * entries grouped by producer kind in a fixed reading order, each with a
+ * truncated sample snippet. Pure — no React, no DOM — so both surfaces stay in
+ * sync and the grouping/formatting rules are unit-testable on their own.
+ */
+
+import type { LedgerEntry, LedgerSourceKind } from './context-ledger'
+
+/** Producer groups, ordered from "closest to the author's intent" outward. */
+export const LEDGER_GROUP_ORDER: ReadonlyArray<LedgerSourceKind> = [
+  'contextSchema',
+  'trigger',
+  'userTask',
+  'activity',
+  'setVariable',
+  'asyncResult',
+  'invokeAgent',
+  'signal',
+  'join',
+  'subWorkflow',
+]
+
+export const LEDGER_SAMPLE_MAX_LENGTH = 40
+
+export interface FormattedLedgerSample {
+  text: string
+  numeric: boolean
+}
+
+export interface LedgerEntryGroup {
+  kind: LedgerSourceKind
+  entries: LedgerEntry[]
+}
+
+export function formatLedgerSample(sample: unknown): FormattedLedgerSample | null {
+  if (sample === undefined) return null
+  const numeric = typeof sample === 'number'
+  let text: string
+  if (typeof sample === 'string') {
+    text = sample
+  } else {
+    try {
+      text = JSON.stringify(sample) ?? String(sample)
+    } catch {
+      text = String(sample)
+    }
+  }
+  if (text.length > LEDGER_SAMPLE_MAX_LENGTH) {
+    text = `${text.slice(0, LEDGER_SAMPLE_MAX_LENGTH - 1)}…`
+  }
+  return { text, numeric }
+}
+
+export function groupLedgerEntries(entries: LedgerEntry[]): LedgerEntryGroup[] {
+  const byKind = new Map<LedgerSourceKind, LedgerEntry[]>()
+  for (const entry of entries) {
+    const list = byKind.get(entry.source.kind) ?? []
+    list.push(entry)
+    byKind.set(entry.source.kind, list)
+  }
+  const groups: LedgerEntryGroup[] = []
+  for (const kind of LEDGER_GROUP_ORDER) {
+    const list = byKind.get(kind)
+    if (list && list.length > 0) groups.push({ kind, entries: list })
+  }
+  return groups
+}
+
+/**
+ * The `'*'` wildcard entries are unnamed whole-payload spreads: there is no
+ * path to insert, so no listing offers them.
+ */
+export function insertableLedgerEntries(entries: ReadonlyArray<LedgerEntry> | undefined): LedgerEntry[] {
+  return (entries ?? []).filter((entry) => entry.path !== '*')
+}
+
+export function readLedgerSampleAtPath(data: unknown, path: string): unknown {
+  const segments = path.split('.').filter((segment) => segment.length > 0)
+  let cursor: unknown = data
+  for (const segment of segments) {
+    if (typeof cursor !== 'object' || cursor === null || Array.isArray(cursor)) return undefined
+    cursor = (cursor as Record<string, unknown>)[segment]
+  }
+  return cursor
+}