@hotmeshio/long-tail 0.20.0 → 0.21.0

package/dashboard/dist/assets/resolver-payload-m9AGKZ3a.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolver-payload-m9AGKZ3a.js","sources":["../../../types/validation.ts","../../src/components/escalation/ErrorsPanel.tsx","../../../shared/form-validation/x-lt-require-any.ts","../../../shared/form-validation/x-lt-require-sum.ts","../../../shared/form-validation/validate-resolver-payload.ts","../../src/lib/resolver-payload.ts"],"sourcesContent":["/**\n * Canonical validation-error shapes — one vocabulary across every surface.\n *\n * When server-side resolver schema enforcement rejects a payload, the API\n * layer returns status 422 with `LTValidationErrorBody` as the response body.\n * The same body shape flows to every consumer:\n *   - HTTP routes serialize it as the JSON response body\n *   - SDK callers receive it as `result.data` (with `result.code` set)\n *   - MCP resolve tools return it as the tool's JSON error content\n *   - the CLI prints the violation list beneath the error line\n *   - the dashboard maps `violations` into the same errors panel the\n *     pre-submission pass feeds\n */\n\n/** Machine-readable error codes carried on error envelopes and bodies. */\nexport const LT_ERROR_CODES = {\n  /** The resolver payload failed the role's enforced form schema. */\n  SCHEMA_VALIDATION: 'schema_validation',\n} as const;\n\nexport type LTErrorCode = (typeof LT_ERROR_CODES)[keyof typeof LT_ERROR_CODES];\n\n/**\n * One field-level violation — the same `{ field, message }` pair the dashboard\n * validation panel renders. Bulk surfaces add `escalationId` so a violation is\n * attributable to the row that produced it.\n */\nexport interface LTFieldViolation {\n  field: string;\n  message: string;\n  escalationId?: string;\n}\n\n/** The 422 response body for a schema-validation rejection. */\nexport interface LTValidationErrorBody {\n  /** Human-readable summary, e.g. \"resolverPayload failed schema validation (2 violations)\". */\n  error: string;\n  code: typeof LT_ERROR_CODES.SCHEMA_VALIDATION;\n  /** Every field-level violation, in schema property order. */\n  violations: LTFieldViolation[];\n  /** The role whose enforced schema rejected the payload; null for a workflow input schema. */\n  role: string | null;\n  /** The schema version validated against; null when the role's live (unversioned) schema applied. */\n  schemaVersion: number | null;\n  /** The workflow whose input_schema rejected the data (invoke surface only). */\n  workflowType?: string;\n}\n\n/** Narrow an unknown response body to the canonical validation-error shape. */\nexport function isValidationErrorBody(body: unknown): body is LTValidationErrorBody {\n  return (\n    typeof body === 'object' && body !== null\n    && (body as Record<string, unknown>).code === LT_ERROR_CODES.SCHEMA_VALIDATION\n    && Array.isArray((body as Record<string, unknown>).violations)\n  );\n}\n","import { AlertCircle } from 'lucide-react';\nimport { deriveFieldLabel } from '../../lib/derive-field-label';\nimport type { FieldError } from '../../lib/field-validator';\n\n/**\n * The form's issue list. Each row names the field through its schema title\n * and, on click, scrolls to and focuses the input carrying that\n * data-field-key. Shared by the escalation side panel and the invoke panel.\n */\nexport function ErrorsPanel({ errors, schema }: { errors: FieldError[]; schema?: Record<string, unknown> | null }) {\n  const focusField = (field: string) => {\n    const el = document.querySelector<HTMLElement>(`[data-field-key=\"${field}\"]`);\n    if (!el) return;\n    el.scrollIntoView({ behavior: 'smooth', block: 'center' });\n    el.focus({ preventScroll: true });\n  };\n\n  if (errors.length === 0) {\n    return <p className=\"text-xs text-text-tertiary italic\">No errors to display.</p>;\n  }\n\n  return (\n    <div className=\"space-y-1\" role=\"alert\" aria-live=\"polite\">\n      <p className=\"text-2xs font-semibold uppercase tracking-wider text-status-error mb-4\">\n        {errors.length} {errors.length === 1 ? 'issue' : 'issues'} to resolve\n      </p>\n      <div className=\"space-y-1.5\">\n        {errors.map(({ field, message }) => (\n          <button\n            key={field}\n            onClick={() => focusField(field)}\n            className=\"w-full text-left flex items-start gap-3 px-3 py-2.5 rounded hover:bg-status-error/5 transition-colors group\"\n          >\n            <AlertCircle className=\"w-3.5 h-3.5 mt-0.5 shrink-0 text-status-error/60 group-hover:text-status-error transition-colors\" />\n            <div>\n              <p className=\"text-2xs font-semibold text-text-primary leading-snug\">\n                {deriveFieldLabel(field, (schema?.properties as Record<string, Record<string, unknown>> | undefined)?.[field])}\n              </p>\n              <p className=\"text-2xs text-text-tertiary group-hover:text-text-secondary transition-colors leading-snug mt-0.5\">\n                {message}\n              </p>\n            </div>\n          </button>\n        ))}\n      </div>\n      <p className=\"text-2xs text-text-quaternary mt-4 px-3\">\n        Click an issue to scroll to and focus the field.\n      </p>\n    </div>\n  );\n}\n","/**\n * x-lt-require-any — \"at least one of this set\" as a root-schema token. A\n * form_schema declares groups of field names; a submission passes when every\n * group has a value in at least one member. The canonical case: a Left\n * quantity and a Right quantity where either satisfies, but blank-both fails.\n *\n *   x-lt-require-any   string[][] — e.g. [[\"left_quantity\", \"right_quantity\"]]\n *\n * Visibility rules compose: a member hidden by its `x-lt-showIf` (or naming\n * no schema property) can neither satisfy the group nor be demanded of the\n * submitter, and a group whose members are ALL hidden is waived. `false` and\n * `0` are answers; `''`, null, and undefined are not.\n */\n\nexport const X_LT_REQUIRE_ANY = 'x-lt-require-any';\n\n/**\n * The schema's require-any groups. Malformed declarations (non-array token,\n * non-array groups, non-string members) read as no groups — a bad token never\n * bricks submission.\n */\nexport function readRequireAnyGroups(\n  schema: Record<string, unknown> | null | undefined,\n): string[][] {\n  const raw = schema?.[X_LT_REQUIRE_ANY];\n  if (!Array.isArray(raw)) return [];\n  return raw\n    .filter((group): group is unknown[] => Array.isArray(group))\n    .map((group) => group.filter((m): m is string => typeof m === 'string' && m.length > 0))\n    .filter((group) => group.length > 0);\n}\n\n/** Present = an actual answer: `false` and `0` count; `''`/null/undefined do not. */\nexport function hasRequireAnyValue(value: unknown): boolean {\n  if (value === undefined || value === null) return false;\n  if (typeof value === 'string') return value.trim().length > 0;\n  return true;\n}\n","/**\n * x-lt-require-sum — \"these quantities must total at least N\" as a\n * root-schema token. Where x-lt-require-any asks that one member carry any\n * answer (so a count defaulting to `0` vacuously satisfies it), require-sum\n * reads the members as numbers and demands their sum reach a minimum. The\n * canonical case: a Left quantity and a Right quantity that both default to\n * `0`, where at least one side must be positive.\n *\n *   x-lt-require-sum   { fields: string[], minimum?: number }[]\n *                      — e.g. [{ \"fields\": [\"left_quantity\", \"right_quantity\"] }]\n *\n * `minimum` defaults to 1. Numbers contribute their value and numeric strings\n * coerce (the same reading as dynamic bounds); everything else contributes 0.\n * Visibility rules compose the same way as require-any: a member hidden by\n * its `x-lt-showIf` (or naming no schema property) contributes nothing and is\n * not demanded, and a group whose members are ALL hidden is waived.\n */\n\nexport const X_LT_REQUIRE_SUM = 'x-lt-require-sum';\n\nexport interface RequireSumGroup {\n  fields: string[];\n  minimum: number;\n}\n\n/**\n * The schema's require-sum groups. Malformed declarations (non-array token,\n * groups without a fields array, non-string members, non-numeric minimum)\n * read as no groups — a bad token never bricks submission.\n */\nexport function readRequireSumGroups(\n  schema: Record<string, unknown> | null | undefined,\n): RequireSumGroup[] {\n  const raw = schema?.[X_LT_REQUIRE_SUM];\n  if (!Array.isArray(raw)) return [];\n  const groups: RequireSumGroup[] = [];\n  for (const entry of raw) {\n    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;\n    const { fields, minimum } = entry as Record<string, unknown>;\n    if (!Array.isArray(fields)) continue;\n    const members = fields.filter((m): m is string => typeof m === 'string' && m.length > 0);\n    if (members.length === 0) continue;\n    if (minimum !== undefined && typeof minimum !== 'number') continue;\n    groups.push({ fields: members, minimum: typeof minimum === 'number' ? minimum : 1 });\n  }\n  return groups;\n}\n\n/** A member's numeric contribution: numbers as-is, numeric strings coerced, all else 0. */\nexport function requireSumContribution(value: unknown): number {\n  if (typeof value === 'number' && Number.isFinite(value)) return value;\n  if (typeof value === 'string' && value.trim() !== '') {\n    const n = Number(value);\n    if (!Number.isNaN(n)) return n;\n  }\n  return 0;\n}\n","/**\n * The full pre-submission validation pass over a resolver form schema — the\n * same pass on both sides of the wire. The dashboard runs it on the flat form\n * values before submitting; the API layer runs it on the submitted (bound,\n * nested) payload by inverting x-lt-bind first. Because both entry points\n * funnel into one loop, a payload that passes the client panel passes the\n * server gate, and a 422's violation list is exactly what the panel shows.\n *\n * Semantics per field:\n *   - x-lt-showIf-hidden fields are skipped entirely (a field the submitter\n *     cannot see never blocks submission)\n *   - required (schema.required membership), with checklist/empty-object rules\n *   - declared-type check (string/number/integer/boolean/array/object)\n *   - enum membership\n *   - x-lt-require-all against the checklist items resolved from context\n *   - static + dynamic bounds (minimum/x-lt-minimum, lengths, patterns)\n *\n * Root-level x-lt-require-any groups run after the per-field pass: each group\n * needs a value in at least one visible member (all-hidden groups are waived).\n * x-lt-require-sum groups follow the same visibility rules but read members\n * as numbers: the group's visible members must sum to at least its minimum.\n *\n * The showIf/`resolver.*` domain is always the FLAT form representation, so a\n * condition like `resolver.approved` reads the same on both sides.\n */\nimport { type FieldError, validateField } from './field-validator';\nimport { evaluateShowIf, type ShowIfContext } from './x-lt-show-if';\nimport { mapPayloadToForm } from './x-lt-bind';\nimport { readRequireAnyGroups, hasRequireAnyValue } from './x-lt-require-any';\nimport { readRequireSumGroups, requireSumContribution } from './x-lt-require-sum';\n\nexport type { FieldError } from './field-validator';\n\n/**\n * The escalation-surface context the pass evaluates showIf conditions and\n * dynamic constraints against. `resolver` is supplied by the pass itself\n * (the flat form values under validation) — callers provide the rest.\n */\nexport type ResolverValidationContext = Omit<ShowIfContext, 'resolver' | 'input'>;\n\n/**\n * Validate FLAT form values against the form schema. This is the dashboard's\n * entry point (the values the user edits, keyed by field name).\n */\nexport function validateResolverForm(\n  schema: Record<string, unknown> | null | undefined,\n  formValues: Record<string, unknown>,\n  ctx?: ResolverValidationContext | null,\n): FieldError[] {\n  if (!schema) return [];\n  const properties = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;\n  const required = new Set((schema.required as string[] | undefined) ?? []);\n  const liveCtx: ShowIfContext = {\n    ...(ctx ?? {}),\n    resolver: formValues as Record<string, unknown>,\n    input: formValues as Record<string, unknown>,\n  };\n\n  const errors: FieldError[] = [];\n  for (const [field, fieldSchema] of Object.entries(properties)) {\n    if (!evaluateShowIf(fieldSchema['x-lt-showIf'], liveCtx)) continue;\n    const err = validateField(\n      formValues[field],\n      fieldSchema,\n      required.has(field),\n      true,\n      liveCtx as Record<string, unknown>,\n    );\n    if (err) errors.push({ field, message: err });\n  }\n\n  // Require-any groups: at least one VISIBLE member per group carries a value.\n  // A member hidden by showIf (or naming no property) can neither satisfy nor\n  // be demanded; an all-hidden group is waived.\n  for (const group of readRequireAnyGroups(schema)) {\n    const visible = group.filter(\n      (k) => properties[k] && evaluateShowIf(properties[k]['x-lt-showIf'], liveCtx),\n    );\n    if (visible.length === 0) continue;\n    if (visible.some((k) => hasRequireAnyValue(formValues[k]))) continue;\n    const titles = visible.map((k) => (properties[k].title as string | undefined) ?? k);\n    errors.push({\n      field: visible[0],\n      message: `Enter a value for at least one of: ${titles.join(', ')}`,\n    });\n  }\n\n  // Require-sum groups: the numeric values of VISIBLE members must total at\n  // least the group's minimum. A `0` is a real number here — unlike\n  // require-any, defaulted-zero quantities do not satisfy the group.\n  for (const group of readRequireSumGroups(schema)) {\n    const visible = group.fields.filter(\n      (k) => properties[k] && evaluateShowIf(properties[k]['x-lt-showIf'], liveCtx),\n    );\n    if (visible.length === 0) continue;\n    const total = visible.reduce((sum, k) => sum + requireSumContribution(formValues[k]), 0);\n    if (total >= group.minimum) continue;\n    const titles = visible.map((k) => (properties[k].title as string | undefined) ?? k);\n    errors.push({\n      field: visible[0],\n      message: `Combined value of ${titles.join(', ')} must be at least ${group.minimum}`,\n    });\n  }\n  return errors;\n}\n\n/**\n * Validate a SUBMITTED resolver payload (the bound, nested shape the workflow\n * consumes) against the form schema. This is the API layer's entry point: the\n * payload is inverted through each field's x-lt-bind path back to the flat\n * form representation, then run through the same pass the client uses.\n */\nexport function validateResolverPayload(\n  schema: Record<string, unknown> | null | undefined,\n  payload: Record<string, unknown>,\n  ctx?: ResolverValidationContext | null,\n): FieldError[] {\n  if (!schema) return [];\n  const formValues = mapPayloadToForm(payload, schema as Record<string, any>);\n  return validateResolverForm(schema, formValues, ctx);\n}\n","import { mapFormToPayload } from './x-lt-bind';\nimport { validateResolverForm, type FieldError } from './field-validator';\nimport type { ShowIfContext } from './x-lt-show-if';\n\nexport interface ResolverPayloadResult {\n  /** The resolver payload ready to submit — null when the JSON is unparseable or validation failed. */\n  payload: Record<string, unknown> | null;\n  /** Field errors against the embedded _form_schema (empty when the form is valid). */\n  errors: FieldError[];\n  /** Set when the edited JSON string itself is malformed. */\n  parseError: string | null;\n}\n\n/**\n * Build the resolver payload from the form's edited JSON string.\n *\n * 1. Parse the JSON — a malformed string yields `parseError`.\n * 2. Validate every visible field against the embedded `_form_schema` — hidden\n *    fields (x-lt-showIf falsy against the live context) are skipped, matching\n *    the server's enforcement pass. Any failures yield `errors`.\n * 3. Strip the UI-only schema and map flat form fields into their nested shape\n *    via x-lt-bind — the payload IS the payload.\n *\n * The single path shared by the footer's Submit button and the submit-on-claim\n * shortcut, so both produce identical payloads and identical error lists.\n */\nexport function buildResolverPayload(\n  json: string,\n  context?: ShowIfContext,\n): ResolverPayloadResult {\n  let parsed: Record<string, unknown>;\n  try {\n    parsed = JSON.parse(json) as Record<string, unknown>;\n  } catch {\n    return { payload: null, errors: [], parseError: 'Invalid JSON' };\n  }\n\n  const schema = parsed._form_schema as Record<string, unknown> | undefined;\n  if (schema) {\n    const errors = validateResolverForm(schema, parsed, context);\n    if (errors.length > 0) return { payload: null, errors, parseError: null };\n  }\n\n  const { _form_schema, ...formValues } = parsed;\n  return {\n    payload: mapFormToPayload(formValues, schema as Record<string, any> | undefined),\n    errors: [],\n    parseError: null,\n  };\n}\n"],"names":["LT_ERROR_CODES","isValidationErrorBody","body","ErrorsPanel","errors","schema","focusField","field","el","jsx","jsxs","message","AlertCircle","deriveFieldLabel","_a","X_LT_REQUIRE_ANY","readRequireAnyGroups","raw","group","m","hasRequireAnyValue","value","X_LT_REQUIRE_SUM","readRequireSumGroups","groups","entry","fields","minimum","members","requireSumContribution","n","validateResolverForm","formValues","ctx","properties","required","liveCtx","fieldSchema","evaluateShowIf","err","validateField","visible","k","titles","sum","buildResolverPayload","json","context","parsed","_form_schema","mapFormToPayload"],"mappings":"iNAeO,MAAMA,EAAiB,CAE5B,kBAAmB,mBACrB,EA+BO,SAASC,EAAsBC,EAA8C,CAClF,OACE,OAAOA,GAAS,UAAYA,IAAS,MACjCA,EAAiC,OAASF,EAAe,mBAC1D,MAAM,QAASE,EAAiC,UAAU,CAEjE,CC9CO,SAASC,EAAY,CAAE,OAAAC,EAAQ,OAAAC,GAA6E,CACjH,MAAMC,EAAcC,GAAkB,CACpC,MAAMC,EAAK,SAAS,cAA2B,oBAAoBD,CAAK,IAAI,EACvEC,IACLA,EAAG,eAAe,CAAE,SAAU,SAAU,MAAO,SAAU,EACzDA,EAAG,MAAM,CAAE,cAAe,EAAA,CAAM,EAClC,EAEA,OAAIJ,EAAO,SAAW,EACbK,EAAAA,IAAC,IAAA,CAAE,UAAU,oCAAoC,SAAA,wBAAqB,SAI5E,MAAA,CAAI,UAAU,YAAY,KAAK,QAAQ,YAAU,SAChD,SAAA,CAAAC,EAAAA,KAAC,IAAA,CAAE,UAAU,yEACV,SAAA,CAAAN,EAAO,OAAO,IAAEA,EAAO,SAAW,EAAI,QAAU,SAAS,aAAA,EAC5D,EACAK,EAAAA,IAAC,MAAA,CAAI,UAAU,cACZ,SAAAL,EAAO,IAAI,CAAC,CAAE,MAAAG,EAAO,QAAAI,CAAA,IAAQ,OAC5BD,OAAAA,EAAAA,KAAC,SAAA,CAEC,QAAS,IAAMJ,EAAWC,CAAK,EAC/B,UAAU,8GAEV,SAAA,CAAAE,EAAAA,IAACG,EAAA,CAAY,UAAU,kGAAA,CAAmG,SACzH,MAAA,CACC,SAAA,CAAAH,EAAAA,IAAC,IAAA,CAAE,UAAU,wDACV,SAAAI,EAAiBN,GAAQO,EAAAT,GAAA,YAAAA,EAAQ,aAAR,YAAAS,EAA6EP,EAAM,CAAA,CAC/G,EACAE,EAAAA,IAAC,IAAA,CAAE,UAAU,oGACV,SAAAE,CAAA,CACH,CAAA,CAAA,CACF,CAAA,CAAA,EAZKJ,CAAA,EAcR,EACH,EACAE,EAAAA,IAAC,IAAA,CAAE,UAAU,0CAA0C,SAAA,kDAAA,CAEvD,CAAA,EACF,CAEJ,CCpCO,MAAMM,EAAmB,mBAOzB,SAASC,EACdX,EACY,CACZ,MAAMY,EAAMZ,GAAA,YAAAA,EAASU,GACrB,OAAK,MAAM,QAAQE,CAAG,EACfA,EACJ,OAAQC,GAA8B,MAAM,QAAQA,CAAK,CAAC,EAC1D,IAAKA,GAAUA,EAAM,OAAQC,GAAmB,OAAOA,GAAM,UAAYA,EAAE,OAAS,CAAC,CAAC,EACtF,OAAQD,GAAUA,EAAM,OAAS,CAAC,EAJL,CAAA,CAKlC,CAGO,SAASE,EAAmBC,EAAyB,CAC1D,OAA2BA,GAAU,KAAa,GAC9C,OAAOA,GAAU,SAAiBA,EAAM,KAAA,EAAO,OAAS,EACrD,EACT,CCnBO,MAAMC,EAAmB,mBAYzB,SAASC,EACdlB,EACmB,CACnB,MAAMY,EAAMZ,GAAA,YAAAA,EAASiB,GACrB,GAAI,CAAC,MAAM,QAAQL,CAAG,QAAU,CAAA,EAChC,MAAMO,EAA4B,CAAA,EAClC,UAAWC,KAASR,EAAK,CACvB,GAAI,CAACQ,GAAS,OAAOA,GAAU,UAAY,MAAM,QAAQA,CAAK,EAAG,SACjE,KAAM,CAAE,OAAAC,EAAQ,QAAAC,CAAA,EAAYF,EAC5B,GAAI,CAAC,MAAM,QAAQC,CAAM,EAAG,SAC5B,MAAME,EAAUF,EAAO,OAAQP,GAAmB,OAAOA,GAAM,UAAYA,EAAE,OAAS,CAAC,EACnFS,EAAQ,SAAW,IACnBD,IAAY,QAAa,OAAOA,GAAY,UAChDH,EAAO,KAAK,CAAE,OAAQI,EAAS,QAAS,OAAOD,GAAY,SAAWA,EAAU,EAAG,EACrF,CACA,OAAOH,CACT,CAGO,SAASK,EAAuBR,EAAwB,CAC7D,GAAI,OAAOA,GAAU,UAAY,OAAO,SAASA,CAAK,EAAG,OAAOA,EAChE,GAAI,OAAOA,GAAU,UAAYA,EAAM,KAAA,IAAW,GAAI,CACpD,MAAMS,EAAI,OAAOT,CAAK,EACtB,GAAI,CAAC,OAAO,MAAMS,CAAC,EAAG,OAAOA,CAC/B,CACA,MAAO,EACT,CCZO,SAASC,EACd1B,EACA2B,EACAC,EACc,CACd,GAAI,CAAC5B,EAAQ,MAAO,CAAA,EACpB,MAAM6B,EAAc7B,EAAO,YAAc,CAAA,EACnC8B,EAAW,IAAI,IAAK9B,EAAO,UAAqC,CAAA,CAAE,EAClE+B,EAAyB,CAC7B,GAAIH,GAAO,CAAA,EACX,SAAUD,EACV,MAAOA,CAAA,EAGH5B,EAAuB,CAAA,EAC7B,SAAW,CAACG,EAAO8B,CAAW,IAAK,OAAO,QAAQH,CAAU,EAAG,CAC7D,GAAI,CAACI,EAAeD,EAAY,aAAa,EAAGD,CAAO,EAAG,SAC1D,MAAMG,EAAMC,EACVR,EAAWzB,CAAK,EAChB8B,EACAF,EAAS,IAAI5B,CAAK,EAClB,GACA6B,CAAA,EAEEG,GAAKnC,EAAO,KAAK,CAAE,MAAAG,EAAO,QAASgC,EAAK,CAC9C,CAKA,UAAWrB,KAASF,EAAqBX,CAAM,EAAG,CAChD,MAAMoC,EAAUvB,EAAM,OACnBwB,GAAMR,EAAWQ,CAAC,GAAKJ,EAAeJ,EAAWQ,CAAC,EAAE,aAAa,EAAGN,CAAO,CAAA,EAG9E,GADIK,EAAQ,SAAW,GACnBA,EAAQ,KAAMC,GAAMtB,EAAmBY,EAAWU,CAAC,CAAC,CAAC,EAAG,SAC5D,MAAMC,EAASF,EAAQ,IAAKC,GAAOR,EAAWQ,CAAC,EAAE,OAAgCA,CAAC,EAClFtC,EAAO,KAAK,CACV,MAAOqC,EAAQ,CAAC,EAChB,QAAS,sCAAsCE,EAAO,KAAK,IAAI,CAAC,EAAA,CACjE,CACH,CAKA,UAAWzB,KAASK,EAAqBlB,CAAM,EAAG,CAChD,MAAMoC,EAAUvB,EAAM,OAAO,OAC1BwB,GAAMR,EAAWQ,CAAC,GAAKJ,EAAeJ,EAAWQ,CAAC,EAAE,aAAa,EAAGN,CAAO,CAAA,EAI9E,GAFIK,EAAQ,SAAW,GACTA,EAAQ,OAAO,CAACG,EAAKF,IAAME,EAAMf,EAAuBG,EAAWU,CAAC,CAAC,EAAG,CAAC,GAC1ExB,EAAM,QAAS,SAC5B,MAAMyB,EAASF,EAAQ,IAAKC,GAAOR,EAAWQ,CAAC,EAAE,OAAgCA,CAAC,EAClFtC,EAAO,KAAK,CACV,MAAOqC,EAAQ,CAAC,EAChB,QAAS,qBAAqBE,EAAO,KAAK,IAAI,CAAC,qBAAqBzB,EAAM,OAAO,EAAA,CAClF,CACH,CACA,OAAOd,CACT,CC9EO,SAASyC,EACdC,EACAC,EACuB,CACvB,IAAIC,EACJ,GAAI,CACFA,EAAS,KAAK,MAAMF,CAAI,CAC1B,MAAQ,CACN,MAAO,CAAE,QAAS,KAAM,OAAQ,CAAA,EAAI,WAAY,cAAA,CAClD,CAEA,MAAMzC,EAAS2C,EAAO,aACtB,GAAI3C,EAAQ,CACV,MAAMD,EAAS2B,EAAqB1B,EAAQ2C,EAAQD,CAAO,EAC3D,GAAI3C,EAAO,OAAS,EAAG,MAAO,CAAE,QAAS,KAAM,OAAAA,EAAQ,WAAY,IAAA,CACrE,CAEA,KAAM,CAAE,aAAA6C,EAAc,GAAGjB,CAAA,EAAegB,EACxC,MAAO,CACL,QAASE,EAAiBlB,EAAY3B,CAAyC,EAC/E,OAAQ,CAAA,EACR,WAAY,IAAA,CAEhB"}

package/docs/compilation.md

@@ -1,152 +0,0 @@
-# The Compilation Pipeline
-
-Every AI-driven execution carries cost. An LLM reasons through each step, selects tools, interprets results, and decides what to do next. It works, but it is slow, non-deterministic, and consumes tokens on every run.
-
-Long Tail records what the LLM did, extracts the pattern, and compiles it into a deterministic workflow. The next time the same problem appears, it runs without an LLM — no reasoning, no token cost, same result.
-
-This guide follows a single query through the full lifecycle: dynamic execution, compilation, deterministic replay, and automatic routing. All steps take place in the dashboard's **Pipeline Designer** page (sidebar: **MCP Workflows → Pipeline Designer**).
-
----
-
-## The Dynamic Execution
-
-Open **Pipeline Designer** from the sidebar. The page lists previous MCP query runs and provides a prompt field to start a new one. Describe what you need in natural language — for example, "Log into the dashboard, discover all navigation pages, and screenshot each one." Optionally constrain which MCP tool tags to search.
-
-When the query is submitted, the `mcpQuery` workflow starts. It discovers available tools by tag (GIN-indexed full-text search), then enters an agentic loop: the LLM selects a tool, calls it, reads the result, and decides the next step. Every tool call is checkpointed by the workflow engine. If the process crashes mid-execution, it resumes from the last checkpoint — no work is lost, no step runs twice.
-
-The run appears in the **Pipeline Designer** list once it completes. Click into it to open the **Compilation Wizard**.
-
----
-
-## The Compilation Wizard
-
-The wizard has six steps, shown as numbered circles in a sticky bar at the top of the page. Each step represents one stage of converting the dynamic execution into a deployable deterministic workflow:
-
-1. **Describe**
-2. **Discover**
-3. **Compile**
-4. **Deploy**
-5. **Test**
-6. **Verify**
-
-Steps unlock sequentially — you must complete each before advancing.
-
-### 1. Describe
-
-**Subtitle:** *Dynamic LLM-orchestrated execution — the discovery run*
-
-The first panel displays what the LLM produced: the input envelope on the left and the structured output on the right. Duration is shown. This is the reference point — whatever the compiled workflow produces will be compared against it.
-
-### 2. Discover
-
-**Subtitle:** *Activity swimlane showing tool calls and their durations*
-
-A swimlane visualization of the execution. Each row is an MCP server, each block is a tool call, positioned on a time axis. The pattern is visible at a glance: the LLM logged in, extracted navigation links, then looped through each page to capture a screenshot.
-
-### 3. Compile
-
-**Subtitle:** *Define the deterministic workflow tool from this execution*
-
-The workflow needs an identity. This panel presents a form with:
-
-- **Namespace** — a required alphanumeric identifier for the workflow's application scope.
-- **Tool Name** — the workflow's MCP tool name for discovery. This is how other agents and workflows will find and invoke it.
-- **Description** — auto-generated from the execution trace. Editable.
-- **Tags** — suggested from the execution trace. Add or remove tags to control discoverability.
-
-An optional **Refine compilation** toggle reveals a feedback textarea where you can provide additional instructions to the compiler.
-
-Clicking **Compile Pipeline** triggers the five-stage compilation pipeline:
-
-1. **Extract** — parse the execution trace into an ordered step sequence
-2. **Analyze** — detect iteration patterns (the screenshot loop), classify inputs as dynamic (user-provided) or fixed (implementation detail)
-3. **Compile** — an LLM produces a blueprint with data-flow edges and session threading, guided by per-server **compile hints** stored in the database (e.g., which output fields to use as transform sources, how to thread browser session handles)
-4. **Build** — generate a deterministic YAML DAG with activity wiring
-5. **Validate** — check for missing wiring, lost session handles, broken iteration boundaries
-
-Once compilation succeeds, the panel switches to a read-only view showing the workflow name, status badge, namespace, topic, description, activity pipeline chain, and tags.
-
-### 4. Deploy
-
-**Subtitle:** *Review configuration, input/output schemas, and YAML definition*
-
-The deploy panel displays the compiled YAML definition, input schema, and output schema. The YAML encodes the DAG: each step names an MCP tool, declares its inputs (either from the user's request or from a prior step's output), and specifies data-flow edges.
-
-Two toggle buttons are available:
-
-- **Recompile with Feedback** — provide notes to the compiler and regenerate the YAML.
-- **Manual Edit** — directly edit the YAML, schemas, or activity manifest.
-
-A version history panel on the right tracks all edits. The step label changes from "Deploy" to "Redeploy" when the workflow is already active.
-
-Clicking **Deploy & Activate** registers the workflow as a live MCP tool — tagged for discovery, versioned, invocable by any agent, workflow, or API call.
-
-### 5. Test
-
-**Header:** *Compare Runs*
-
-The test panel runs the compiled workflow and compares it against the original dynamic execution. Two columns show:
-
-- **Left — Original MCP Query**: the dynamic LLM-orchestrated run with its input, output, and duration.
-- **Right — Compiled Pipeline Run**: the deterministic run with its input, output, and duration. A dropdown allows selecting from multiple test runs.
-
-Click **Run Test** to invoke the compiled workflow with the original input. An invocation modal appears with the pre-populated input schema.
-
-The difference is structural:
-
-| | Dynamic (LLM) | Deterministic |
-|---|---|---|
-| **Tool calls** | N (LLM selects each) | 1 pipeline (pre-wired DAG) |
-| **LLM usage** | Every step | Route + input extraction only |
-| **Determinism** | Varies per run | Identical every time |
-
-The deterministic path is faster because the LLM is used only at the edges — routing the request and extracting structured inputs from the prompt. The DAG itself executes tool calls directly with pre-wired data flow. No per-step reasoning, no tool selection, no interpretation.
-
-### 6. Verify
-
-**Header:** *End-to-End Verification*
-
-The final panel confirms end-to-end routing. The original prompt is pre-filled in an editable textarea on the left. Click **Submit** to send it through the `mcpQueryRouter` — the same entry point any future request would use. A **Reset to original** button restores the prompt if you modify it.
-
-The right column shows the result: a status badge, confidence percentage (when the deterministic path is used), and the full output in a JSON viewer. A **RouterProgressTracker** displays real-time routing progress during execution.
-
-The router performs full-text search and tag matching to find candidate workflows, then uses an LLM judge to confirm scope. When confidence exceeds the threshold, the request goes straight to the compiled workflow.
-
-```
-User prompt → Router → Discovery (FTS + tags) → LLM Judge
-                 │                                    │
-                 │  confidence ≥ 0.7                  │  no match
-                 ▼                                    ▼
-            Deterministic                          Dynamic
-        (compiled DAG, no LLM)                  (agentic loop)
-```
-
----
-
-## How It Accumulates
-
-The first time a problem appears, the dynamic path runs. An LLM reasons through it — slow and expensive, but it works.
-
-The wizard compiles the solution into a deterministic pipeline. A human reviews the DAG, adjusts if needed, and deploys.
-
-Every subsequent occurrence is routed automatically. A single LLM call extracts structured inputs from the prompt, then the DAG executes without further reasoning.
-
-Each compiled workflow is itself a discoverable MCP tool. Other workflows and agents can invoke it. Solutions compose. The inventory of deterministic pathways grows with every problem the system solves, and the fraction of requests that require LLM reasoning shrinks.
-
-The dynamic path remains for genuinely new problems. But the long tail gets shorter.
-
----
-
-## Compilation from Source Code
-
-The Pipeline Designer compiles from execution traces — the dynamic path. But there's a second entry point: compiling directly from source code.
-
-If you've written a durable workflow using the durable workflow API (`proxyActivities`, `sleep`, `condition`, `startChild`), you can compile it to a YAML DAG without executing it first. The `ltc` CLI reads your TypeScript source, extracts the orchestration structure, and produces an equivalent DAG that runs without replay overhead.
-
-```bash
-ltc compile workflows/assembly-line.ts
-```
-
-The source is the spec. The compiled YAML is the optimized execution. Both live in the repo.
-
-See the [Compiler Guide](compiler.md) for the full walkthrough.

package/docs/compiler.md

@@ -1,311 +0,0 @@
-# The Workflow Compiler
-
-You wrote a durable workflow. It works. `proxyActivities`, `sleep`, `condition` — the durable API is productive and familiar. But under the hood, the durable engine replays the entire workflow function on every wake-up. Sleep three times in a ten-step workflow? Steps 1–3 replay on wake one. Steps 1–6 replay on wake two. Steps 1–9 replay on wake three. The replay is deterministic — it skips completed activities — but the function still executes from the top every time.
-
-The compiled YAML DAG does the same work without replay. Each step fires exactly once. State flows explicitly between activities through input mappings. No function re-execution, no replay loop, no wasted cycles.
-
-`ltc` is the compiler. It reads your TypeScript source and produces an equivalent YAML DAG. Write procedural because it's productive. Run the DAG because it's fast.
-
----
-
-## The Analogy
-
-`tsc` compiles TypeScript to JavaScript. You write in the language that's expressive. You run the artifact that's efficient. The source is authoritative — you edit it, test it, review it. The compiled output is what actually executes.
-
-`ltc` does the same for workflows:
-
-```
-  TypeScript source       ltc compile        YAML DAG
-  (developer-friendly) ──────────────────→ (execution-optimized)
-
-  assembly-line.ts     →   assembly-line.compiled.yaml
-```
-
-The `.ts` file is the spec. The `.compiled.yaml` is the optimized execution. Both live in the repo. A reviewer reads both side-by-side and traces every line of orchestration logic to its DAG equivalent.
-
----
-
-## Quick Start
-
-```bash
-npm install -g @hotmeshio/long-tail
-export ANTHROPIC_API_KEY=sk-ant-...
-
-ltc compile workflows/basic-echo/index.ts
-```
-
-Output:
-
-```
-  ✓ index.ts → workflows/basic-echo/index.compiled.yaml
-    1 activities · 2 inputs (message, sleepSeconds) · topic: basic.echo
-
-  Compiled 1 workflow in 18.1s
-```
-
-The compiled YAML appears adjacent to the source file.
-
----
-
-## Before and After
-
-### The source (procedural)
-
-```typescript
-import { Durable } from '@hotmeshio/hotmesh';
-import * as activities from './activities';
-
-const { echo } = Durable.workflow.proxyActivities<typeof activities>({
-  activities,
-});
-
-export async function basicEcho(envelope: LTEnvelope): Promise<any> {
-  const { message = 'Hello, Long Tail!', sleepSeconds = 1 } = envelope.data;
-
-  // 1. Durable sleep — the engine replays to this point on wake-up
-  await Durable.workflow.sleep(`${sleepSeconds} seconds`);
-
-  // 2. Activity call — replayed as a no-op if already completed
-  const echoResult = await echo({ message });
-
-  return {
-    type: 'return' as const,
-    data: { ...echoResult, sleepSeconds, userId: envelope.lt?.userId },
-  };
-}
-```
-
-This function executes three times: once on initial invocation, once when the sleep timer fires, and once when the echo activity completes. Each time, the engine replays from the top, skipping completed steps. For a two-step workflow this is fine. For a twenty-step workflow with multiple sleeps, the replay cost compounds.
-
-### The compiled output (DAG)
-
-```yaml
-app:
-  id: longtail
-  version: '1'
-  graphs:
-    - subscribes: basic.echo
-      expire: 300
-      input:
-        schema:
-          type: object
-          properties:
-            message:
-              type: string
-              default: 'Hello, Long Tail!'
-            sleepSeconds:
-              type: number
-              default: 1
-      activities:
-        trigger_m7qz:
-          type: trigger
-          output:
-            schema:
-              type: object
-              properties:
-                message: { type: string }
-                sleepSeconds: { type: number }
-
-        delay_m7qz:
-          type: hook
-          sleep: '{trigger_m7qz.output.data.sleepSeconds}'
-
-        echo_m7qz:
-          type: worker
-          topic: basic.echo
-          input:
-            maps:
-              message: '{trigger_m7qz.output.data.message}'
-              workflowName: echo
-
-      transitions:
-        trigger_m7qz:
-          - to: delay_m7qz
-        delay_m7qz:
-          - to: echo_m7qz
-```
-
-### The mapping
-
-| TypeScript | YAML | What happens |
-|---|---|---|
-| `envelope.data` destructuring | `trigger` activity with input schema | Inputs declared as typed schema with defaults |
-| `Durable.workflow.sleep(N)` | `hook` activity with `sleep` field | Engine sets a timer; no replay on wake |
-| `await echo({ message })` | `worker` activity with input `maps` | Worker fires once; result stored in job hash |
-| `return { data: ... }` | `job.maps` on the final activity | Output fields plucked from activity results |
-
-Each step executes exactly once. The `sleep` hook pauses the DAG. When the timer fires, execution resumes at `echo_m7qz` — not from the top of the function.
-
----
-
-## Discovery
-
-Point `ltc` at a directory and it finds workflow files automatically:
-
-```bash
-ltc compile examples/workflows/ --dry-run
-```
-
-```
-  Found 10 workflows:
-
-  ● assembly-line/index.ts
-    Function: assemblyLine  ·  HotMesh Durable
-    Control flow: startChild, condition
-
-  ● basic-echo/index.ts
-    Function: basicEcho  ·  HotMesh Durable
-    Activities: echo
-    Control flow: sleep
-
-  ● basic-signal/index.ts
-    Function: basicSignal  ·  HotMesh Durable
-    Activities: ltCreateEscalation, processApproval
-    Control flow: conditional
-
-  ● kitchen-sink/index.ts
-    Function: kitchenSink  ·  HotMesh Durable
-    Activities: greet, fetchData, transformData, notifyComplete
-    Control flow: sleep, executeLT
-```
-
-### What the scanner looks for
-
-| Pattern | Classification |
-|---|---|
-| `proxyActivities` / `Durable.workflow.proxyActivities` | HotMesh Durable workflow |
-| `@temporalio/workflow` import | Temporal workflow |
-| `sleep`, `condition`, `signal` | Control flow primitives |
-| `startChild`, `executeChild`, `executeLT` | Composition (parent workflow) |
-| Exported async function | Workflow entry point |
-
-Files in `node_modules/`, `build/`, `dist/`, and test files (`*.test.ts`, `*.spec.ts`) are excluded.
-
----
-
-## How Compilation Works
-
-The compiler is not an AST parser. It uses the LLM to translate orchestration logic, grounded by structural metadata extracted from the source.
-
-1. **Read source** — file or inline string
-2. **Extract metadata** — lightweight regex extraction: activity names, durable primitives, envelope fields, import paths, control flow markers (loops, Promise.all, conditionals, escalation)
-3. **Resolve activities** — if the source imports activity modules, the compiler reads them too and includes them in the LLM context
-4. **LLM translation** — the source code, extracted metadata, and the full HotMesh YAML specification are sent to the LLM. Temperature 0. Up to 3 retry attempts on parse failure.
-5. **Fix patterns** — known LLM anti-patterns in YAML pipe expressions are corrected deterministically
-
-The metadata extraction is intentionally lightweight — regex, not a TypeScript AST. It gives the LLM structural hints (which functions are activities, which primitives are used) without requiring `ts-morph` or the TypeScript compiler API as a dependency.
-
----
-
-## Composition
-
-When a workflow uses `startChild` or `executeChild`, the compiler resolves the child workflow source through imports and compiles children first (leaf-first ordering). The parent's compiled YAML references each child by topic using the `await` activity type — the same mechanism used by the Pipeline Designer's Plan Build mode.
-
-```
-parent.ts  ──→  parent.compiled.yaml
-  └─ startChild(worker)
-       └─ worker.ts  ──→  worker.compiled.yaml
-```
-
-All compiled workflows in the same composition share the same `app.id` namespace, enabling cross-graph invocation.
-
----
-
-## Three Surfaces
-
-The compiler is the same function regardless of how you invoke it.
-
-### CLI
-
-```bash
-ltc compile workflows/assembly-line.ts
-ltc compile src/workflows/ --dry-run
-ltc compile --model claude-sonnet-4-6
-```
-
-### HTTP API
-
-```bash
-curl -X POST http://localhost:3000/api/yaml-workflows/from-durable \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "source": "export async function basicEcho(envelope) { ... }",
-    "workflow_name": "basicEcho",
-    "name": "basic_echo"
-  }'
-```
-
-### SDK
-
-```typescript
-import { createClient } from '@hotmeshio/long-tail/sdk';
-
-const lt = createClient({ auth: { userId: 'system' } });
-
-const result = await lt.yamlWorkflows.compileDurable({
-  source: fs.readFileSync('workflows/assembly-line.ts', 'utf-8'),
-  workflow_name: 'assemblyLine',
-  name: 'assembly_line',
-});
-```
-
-The CLI writes `.compiled.yaml` files to disk. The HTTP and SDK surfaces store the compiled workflow in the database and return the record. All three use the same underlying `compileDurableToYaml()` function.
-
----
-
-## Configuration
-
-| Variable | Default | Description |
-|---|---|---|
-| `ANTHROPIC_API_KEY` | — | Required for Claude models |
-| `OPENAI_API_KEY` | — | Required for OpenAI models |
-| `LT_LLM_MODEL_PRIMARY` | `claude-sonnet-4-6` | Model used for compilation |
-| `LT_LLM_BASE_URL` | — | Custom endpoint for OpenAI-compatible models |
-
-The CLI loads `.env` automatically if present in the current directory.
-
----
-
-## CLI Reference
-
-```
-Usage: ltc compile [options] [target]
-
-Compile durable TypeScript workflows to YAML DAGs
-
-Arguments:
-  target                  File or directory to compile (default: current directory)
-
-Options:
-  --dry-run               Show discovered workflows without compiling
-  -o, --output <dir>      Output directory (default: adjacent to source file)
-  --model <model>         LLM model to use (default: claude-sonnet-4-6)
-  --function <name>       Workflow function name (auto-detected if omitted)
-  -h, --help              Display help
-```
-
-### Examples
-
-```bash
-# Compile a single file
-ltc compile workflows/basic-echo/index.ts
-
-# Scan and compile all workflows in a directory
-ltc compile src/workflows/
-
-# Compile everything in the current directory
-ltc compile
-
-# Preview what would be compiled
-ltc compile examples/workflows/ --dry-run
-
-# Use a specific model
-ltc compile workflows/complex.ts --model claude-opus-4-6
-
-# Write output to a separate directory
-ltc compile workflows/ -o compiled/
-
-# Compile a specific function from a multi-export file
-ltc compile workflows/multi.ts --function assemblyLine
-```

package/docs/contributing.md

@@ -1,56 +0,0 @@
-# Contributing
-
-## Running the Demo
-
-The repository includes a working server with example workflows (`reviewContent`, `kitchenSink`, `basicEcho`, and more), Postgres, NATS, and a React dashboard.
-
-### Prerequisites
-
-- [Docker](https://docs.docker.com/get-docker/)
-
-### Run
-
-```bash
-git clone https://github.com/hotmeshio/long-tail.git
-cd long-tail
-docker compose up
-```
-
-Postgres, NATS, the API server, and the dashboard start together. The dashboard is built during the Docker image build and served as static assets. Migrations run automatically.
-
-Default ports are `3000` (API), `5432` (Postgres), `4222`/`8222` (NATS). Override any of them:
-
-```bash
-LT_PORT=3001 LT_PG_PORT=5433 LT_NATS_PORT=4223 docker compose up
-```
-
-## Testing
-
-```bash
-# Start Postgres and NATS
-docker compose up -d postgres nats
-
-# Run all tests
-npm test
-
-# Run workflow tests
-npm run test:workflows
-```
-
-## Development Setup
-
-1. Fork the repository and clone your fork
-2. Install dependencies: `npm install`
-3. Start infrastructure: `docker compose up -d postgres nats`
-4. Run tests to verify your setup: `npm test`
-
-## Pull Requests
-
-- Create a feature branch from `main`
-- Keep changes focused — one concern per PR
-- Add or update tests for any new behavior
-- Run `npm test` before submitting
-
-## Issues
-
-Report bugs and request features at [github.com/hotmeshio/long-tail/issues](https://github.com/hotmeshio/long-tail/issues).