Scenario Authoring

Start with one real conversation: an X12 850 order and its 810 invoice

Suppose a retailer sends your company an X12 850 purchase order and your company later returns an X12 810 invoice. A scenario turns that familiar exchange into a repeatable proof that the right documents, maps, partner route, acknowledgments, timing, and business values all agree.

Maps define how documents are processed; scenarios define and prove the business conversation those maps implement. A ScenarioDefinition is the portable recipe for that conversation: who exchanges each X12 business document, which documents belong together, what order and repetition are allowed, and what evidence must pass. Tenant partners, syntax trees, mappings, and executable targets belong in a ScenarioBinding.

Scenario definitions and bindings are strict JSON documents. Their JSON Schema Draft 2020-12 contracts drive external tooling, Mapper completion and diagnostics, examples, and this generated reference. Server validation adds cross-file, tenant-ownership, conversation-rule, extracted-fact, and executable-support checks that JSON Schema cannot express alone.

Open Mapper Read as Markdown OpenAPI 3.1

One 850 → 810 example, end to end

DefinitionDescribe the reusable business conversation: the retailer sends one 850, the supplier returns one matching 810 within 30 days, both carry the same purchase-order number, the selected maps succeed, and required AS2 receipts plus accepted 997 or 999 acknowledgments exist. No tenant-specific partner or map ID appears here.
BindingConnect that recipe to this tenant's real platform resources: the retailer partner, the supplier workspace, the inbound 850 map, the outbound 810 map, the fact expressions that read each purchase-order number, and any explicitly pinned X12 syntax-tree version (the exact parsing structure used for that document). Applying the binding freezes those exact dependencies for repeatable runs.
RunStart one evaluation of the applied binding and attach the persisted 850 and 810 transactions. ModernEDI checks that the documents followed the allowed path, matched by purchase-order number, arrived in time, used the frozen dependencies, and satisfied every required check.
EvidenceInspect the durable proof: persisted transaction and map identities, transport-receipt and 997 or 999 assurance outcomes, redacted fact subjects, matching-rule and business-check results, evidence references, timestamps, and the immutable evidence report for the terminal run. Raw X12 payloads and extracted fact values remain in authorized platform and transaction views; the run and downloadable report do not copy them.

Mental model

Definition → Binding → Run → Evidence

DefinitionThe reusable recipe for an X12 business conversation: roles, document steps, allowed order and repetition, matching rules, evidence requirements, and business checks.
BindingThe tenant-specific wiring that selects the partners, workspace, maps, fact expressions, server-side execution implementation, and optional X12 syntax-tree versions used by that recipe.
RunOne timestamped evaluation of an applied binding against persisted transactions and platform evidence.
EvidenceThe durable, hash-identified record of what happened and why the run passed, failed, was cancelled, or remained inconclusive.

The signed-in Workspace API is the customer HTTP API for definitions, bindings, runs, context, operations, and evidence reports. A conversation graph is only the definition's model of actors, document steps, and directed rules; the scenario runtime is the server-side evaluator that executes supported applied bindings. Some generated OpenAPI component names begin with ScenarioGraph because they represent conversation-graph state inside a run; they remain part of the Workspace API, not a separate Graph API.

Terms used below

Plain-language glossary

Conversation graphThe actors, document steps, and directed relationship rules in a definition. It is a model of the business conversation, not a separate customer API.
ActorA business role that sends or receives documents, such as retailer, supplier, warehouse, or carrier. A binding later connects each role to a tenant partner or the tenant workspace.
StepOne kind and direction of X12 business document in the conversation, such as an inbound 850 order or outbound 810 invoice.
OccurrenceOne actual persisted document assigned to a step during a run. Two 856 shipment notices are two occurrences of the same step.
TransitionA rule connecting two steps. follows requires a matched later document; supersedes records a replacement such as a later 860 order change; cancels records a removal such as an ocean 303 cancelling a 301 booking confirmation.
FactA typed business value extracted from one document occurrence by an X12 Mapper expression, such as purchaseOrderNumber, invoiceTotal, or statusTimestamp.
CorrelationA matching rule that decides which concrete documents belong together, such as equal purchase-order numbers on an 850 and 810.
AssertionA business fact rule that must pass, such as shipped quantity equaling invoiced quantity or successive 315 status timestamps increasing.
ParameterA typed value supplied when a run starts rather than extracted from a document, such as expectedShipmentCount or cancelRequested.
Matching strategyThe rule for pairing repeated documents: by declared correlations, by observation position, or by the immediately previous occurrence in a same-step revision chain.
QuantifierThe scope of a repeated check, such as every pair must match, any pair may match, or exactly a declared number must match.
ClosureThe objective signal that no more documents are expected for one repeated step: a fixed count, the authored maximum, or a required/defaulted expected count.
CheckpointA named completion event emitted after a declared processing stage. It can trigger a branch; for example, bookingDisposition after processing a 301 can choose the 303 or 304 path.
BranchAn explicit choice between mutually exclusive next-document paths after a checkpoint, such as choosing a 303 cancellation instead of 304 shipping instructions.
Revision effectThe rule for when a superseding or cancelling document begins to apply and whether later checks keep the original document or reevaluate with the replacement or removal.
Pipeline stageOne ordered processing action for a document occurrence: prepare, map, exchange, extract facts, check evidence, or emit a checkpoint.
Runtime targetThe server-side implementation selected by a binding to prepare, map, exchange, and evaluate the scenario's document steps.
Runtime capacityThe bounded amount of durable run state a definition may require. Validate and Apply reject a definition whose worst-case structure would exceed that budget.
PublishCreate an immutable, content-hashed definition revision after validation succeeds.
ApplyCreate an immutable binding revision after ModernEDI resolves and validates its tenant-owned dependencies.

*.scenario.json

ModernEDI ScenarioDefinition v1

Download JSON Schema Open Example

Authoring workflow

Create a *.scenario.json draft in Mapper Explorer. JSON Schema supplies completion, hover help, and immediate structural diagnostics.
Run Validate to check references, X12 catalog values, closure and branch rules, typed operands, and whether the current scenario runtime can execute the definition.
Publish only after validation succeeds. Publish creates an immutable definition identity and content hash for bindings.
Create and Apply a matching *.binding.json to resolve tenant partners, mappings, adapters, and optional syntax-tree choices.
Start a scenario run with the applied binding, then inspect each occurrence, evidence item, correlation, and assertion in Implementation Verification.

Server semantic checks

Actor, step, transition, parameter, checkpoint, branch, predicate, fact, and pipeline-stage IDs are unique in their documented scopes.
Every referenced actor, step, fact, checkpoint, transition, and parameter exists, and every document step goes from one actor to a different actor. A correlation may read facts only from its two connected steps. A branch condition may read facts only from the common source step and cannot use a destination document to select itself.
An occurrence minimum cannot exceed its maximum; every repeated step has an objective closure rule; repeated-document pairing and every/any/count behavior are explicit; durations are positive and no longer than P365D. A min-zero step uses expected_count because zero observations cannot satisfy max_reached, unless every incoming follows path is branch-controlled so an unselected path supplies the no-document outcome. expected_count uses an exact integer parameter that is required at run start or has a default within the step bounds; steps sharing that parameter must have overlapping bounds.
Transaction sets exist in the X12 catalog, while 997 and 999 are represented as assurance evidence.
Ordinary next-document paths cannot loop, and every step belongs to the same connected conversation. Only supersedes with previous matching may form a same-step revision chain, and that repeated step must allow at least two occurrences; cancels identifies a distinct cancellation-document step.
Each operator receives compatible typed values from facts, run parameters, or literals; list and set elements must use one exact scalar type.
Each composed processing pipeline contains one exchange stage in valid order and at most one map and assure stage. map must be directly beside exchange; Apply requires it before exchange for an outgoing runtime mapping and after exchange for an incoming one. Every parameter named by prepare is required at run start or has a default. Every declared fact appears in exactly one extract stage. Every declared checkpoint has exactly one emitting stage, a step that emits a checkpoint can occur only once, and a branch fact is extracted before its decision checkpoint.
supersedes and cancels require a revision effect; follows forbids one. previous matching is supersedes-only, requires a step occurrence max of at least 2, and requires record for both matching and effect because the first occurrence is the initial revision. Revisions always match the unchanged observation history, cannot be branch alternatives, and cannot open or schedule a next-document path. Each branch checkpoint must be emitted by the alternatives' shared source step and must necessarily observe at least one document, so expected_count closure with occurrence min 0 is rejected. Each branch-decision round uses only steps already allowed at its start; a selected path becomes available in the next round. After branch selection, a revision affects checks only when both endpoint steps remain on the selected path. retain keeps the original document for branch conditions, follows transitions, and assertions; reevaluate uses the replacement or removal instead. A later effective time wins, and equal latest times fail with REVISION_EFFECT_CONFLICT.
The definition's combined worst-case occurrence summaries, transition pairs, checks, and compact evidence references must fit the v1 durable run-state budget. Per-step JSON Schema maxima for fact declarations and occurrences are structural ceilings, not separately available runtime quotas.

Runtime capacity

Validate and Apply conservatively estimate deterministic durable run-state growth rather than accepting each step independently. The estimate includes occurrence summaries, compact evidence references, checks, and quadratic transition-pair and revision-check growth. It does not reserve the maximum runtime value size for every declared fact; actual Mapper-derived values and evidence are checked against separate per-observation limits before persistence. A definition is rejected with runtime_capacity_exceeded when its combined structural projection exceeds the v1 durable run-state budget.

Durable run-state projection budget: 480,000 bytes.
Per-step JSON Schema fact declaration maximum: 100; this is a structural ceiling, not preallocated runtime value capacity.
Per-step JSON Schema occurrence maximum: 1000; this is a structural ceiling, not an independently available quota.
Stable compiler diagnostic: runtime_capacity_exceeded.

Example

{
  "$schema": "https://www.modernedi.com/docs/scenarios/schemas/scenario-definition-v1.schema.json",
  "apiVersion": "modernedi.com/scenario/v1",
  "kind": "ScenarioDefinition",
  "metadata": {
    "namespace": "acme",
    "key": "retail-order-invoice",
    "version": "1.0.0"
  },
  "spec": {
    "actors": [
      {
        "id": "retailer"
      },
      {
        "id": "supplier"
      }
    ],
    "steps": [
      {
        "id": "purchaseOrder",
        "fromActor": "retailer",
        "toActor": "supplier",
        "transaction": {
          "standard": "X12",
          "transactionSet": "850",
          "businessUsage": "purchase_order"
        },
        "occurrence": {
          "min": 1,
          "max": 1,
          "closure": {
            "kind": "fixed"
          }
        },
        "assurance": {
          "requirements": [
            {
              "type": "mapping_succeeded"
            }
          ]
        },
        "facts": [
          {
            "name": "purchaseOrderNumber",
            "type": "string",
            "cardinality": "one",
            "normalization": [
              "trim"
            ],
            "sensitivity": "business"
          }
        ],
        "pipeline": [
          {
            "id": "exchange",
            "kind": "exchange"
          },
          {
            "id": "extract",
            "kind": "extract",
            "facts": [
              "purchaseOrderNumber"
            ]
          },
          {
            "id": "assure",
            "kind": "assure"
          }
        ]
      },
      {
        "id": "invoice",
        "fromActor": "supplier",
        "toActor": "retailer",
        "transaction": {
          "standard": "X12",
          "transactionSet": "810",
          "businessUsage": "invoice"
        },
        "occurrence": {
          "min": 1,
          "max": 1,
          "closure": {
            "kind": "fixed"
          }
        },
        "assurance": {
          "requirements": [
            {
              "type": "transport_receipt_accepted",
              "within": "PT4H"
            },
            {
              "type": "functional_or_implementation_acknowledgment_accepted"
            }
          ]
        },
        "facts": [
          {
            "name": "purchaseOrderNumber",
            "type": "string",
            "cardinality": "one",
            "normalization": [
              "trim"
            ],
            "sensitivity": "business"
          },
          {
            "name": "invoiceTotal",
            "type": "decimal",
            "cardinality": "optional",
            "normalization": [
              "decimal_canonical"
            ],
            "sensitivity": "financial"
          }
        ],
        "pipeline": [
          {
            "id": "exchange",
            "kind": "exchange"
          },
          {
            "id": "extract",
            "kind": "extract",
            "facts": [
              "purchaseOrderNumber",
              "invoiceTotal"
            ]
          },
          {
            "id": "assure",
            "kind": "assure"
          }
        ]
      }
    ],
    "transitions": [
      {
        "id": "invoiceSettlesOrder",
        "fromStep": "purchaseOrder",
        "toStep": "invoice",
        "relationship": "follows",
        "within": "P30D",
        "correlations": [
          {
            "id": "samePurchaseOrder",
            "operator": "equal",
            "left": {
              "kind": "fact",
              "stepId": "purchaseOrder",
              "fact": "purchaseOrderNumber",
              "projection": "value"
            },
            "right": {
              "kind": "fact",
              "stepId": "invoice",
              "fact": "purchaseOrderNumber",
              "projection": "value"
            }
          }
        ],
        "matching": {
          "strategy": "correlate",
          "quantifiers": [
            {
              "kind": "every",
              "scope": "from"
            },
            {
              "kind": "every",
              "scope": "to"
            }
          ],
          "unmatched": "fail"
        }
      }
    ],
    "assertions": [
      {
        "id": "invoiceTotalExists",
        "operator": "exists",
        "left": {
          "kind": "fact",
          "stepId": "invoice",
          "fact": "invoiceTotal",
          "projection": "value"
        }
      }
    ],
    "parameters": [],
    "checkpoints": [],
    "branches": []
  }
}

Fields

Expand a shape for schema-derived field help. The Mapper shows the same descriptions on hover.

token

A stable identifier beginning with a letter and containing at most 128 letters, digits, underscores, or hyphens.

Type or allowed values: string; pattern ^[A-Za-z][A-Za-z0-9_-]{0,127}$.

namespace

A lowercase, DNS-like ownership namespace.

Type or allowed values: string; max length 253; pattern ^[a-z0-9]+(?:[.-][a-z0-9]+)*$.

artifactVersion

A trim-exact artifact version with no control characters. This versions a published definition; it is separate from apiVersion.

Type or allowed values: string; min length 1; max length 64; pattern ^(?!\s)(?!.*\s$)[^\u0000-\u001F\u007F]+$.

positiveDuration

A positive ISO 8601 duration accepted by java.time.Duration, no longer than P365D. Examples: PT30M, PT4H, P2D. The server enforces the upper bound.

Type or allowed values: string; pattern ^P(?=.+)(?!0+(?:D|T(?:0+H)?(?:0+M)?(?:0+(?:\.0+)?S)?$))(?:[0-9]+D)?(?:T(?=[0-9])(?:[0-9]+H)?(?:[0-9]+M)?(?:[0-9]+(?:\.[0-9]+)?S)?)?$.

Definition metadata

Immutable identity of a published definition. The identity tuple is namespace, key, and version; contentSha256 is computed when the definition is published.

namespace (required)Type: namespace.
key (required)Type: token. Stable definition key within the namespace.
version (required)Type: artifactVersion.

Scenario specification

The business-conversation recipe. Actors name the business roles, steps name their X12 document exchanges, and transitions state how those exchanges relate. ModernEDI also verifies unique IDs, references, a connected conversation, and the absence of ordinary transition cycles during Validate and Publish. Omitted transitions, assertions, parameters, checkpoints, or branches mean empty arrays; published JSON materializes every collection.

actors (required)Type: array of actor. Business roles participating in the conversation. Every actor ID must be unique.
steps (required)Type: array of step. Business-document exchanges. Every step ID must be unique and must reference two different declared actors.
transitionsType: array of transition. Rules connecting document steps. For example, an 810 invoice can follow its matching 850 purchase order, a later 860 can supersede an earlier order change, and an ocean 303 can cancel a matching 301 booking confirmation. Transition IDs must be unique. Except for a same-step supersedes revision chain, ordinary next-document paths cannot loop and every step must belong to one connected conversation.
assertionsType: array of assertion. Run-level facts that must hold across one or more observed step occurrences. Assertion IDs must be unique.
parametersType: array of parameter. Prepared values supplied when a run starts. Parameters declare only their semantic type, required flag, and optional default; bindings and runtime APIs supply values.
checkpointsType: array of checkpoint. Named completion events emitted after a step finishes a declared processing stage. A checkpoint can trigger a choice between allowed next steps. For example, a bookingDisposition checkpoint emitted after an X12 301 booking confirmation can choose between an X12 303 cancellation and X12 304 shipping instructions.
branchesType: array of branch. Explicit choices between allowed next-document transitions, evaluated only after a named checkpoint is emitted. For example, after an X12 301 booking confirmation emits bookingDisposition, cancelRequested=true can select the X12 303 cancellation path and otherwise can select X12 304 shipping instructions. Choices are evaluated in deterministic rounds from the steps already available at the start of that round; a destination document cannot provide the fact that selects its own path.

Actor

A business role. Bindings later connect each role to this workspace or a trading partner.

id (required)Type: token.

Step

One directed X12 business-document exchange. Functional acknowledgments (997/999) are evidence requirements, not business steps.

id (required)Type: token. Stable ID used by transitions, assertions, and bindings.
fromActor (required)Type: token. ID of the actor sending this business document.
toActor (required)Type: token. ID of the actor receiving this business document; it must differ from fromActor.
transaction (required)Type: transaction.
occurrence (required)Type: occurrence.
assuranceType: assurance.
facts (required)Type: array of factDeclaration. Typed semantic facts exposed by this step. Use an empty array when the step exposes none. Declarations name the stable ABI only; extraction provenance belongs to runtime capability and binding layers.
pipeline (required)Type: array of pipelineStage. Ordered abstract processing stages for each step occurrence. Stages describe behavior without naming mapper or transport artifacts.

Transaction

The business document carried by a step. The server verifies the transaction-set code against ModernEDI's X12 catalog.

standard (required)Type: exactly X12. Transaction standard. v1 supports X12.
transactionSet (required)Type: string; pattern ^(?!(?:997|999)$)[0-9]{3}$. Known three-digit X12 business transaction set, such as 850, 855, 856, 810, 875, 880, 940, 945, 204, 214, 300, 301, or 315. Use assurance for 997/999 acknowledgments.
businessUsage (required)Type: token. Scenario-specific semantic role, such as purchase_order, shipment_notice, or ocean_status. It is intentionally more precise than the transaction-set code.

Occurrence bounds

How many documents this step may contribute to one run and the rule that says when no more are expected. One observed document is one occurrence. For example, an 850 order can be exactly once while 856 shipment notices can repeat. The server also enforces min <= max.

min (required)Type: integer; minimum 0; maximum 1000. Minimum accepted count once a reachable step closes. Zero is a no-document outcome only when expected_count resolves to 0 or branch selection makes the step unreachable; zero alone does not close a stream.
max (required)Type: integer; minimum 1; maximum 1000. Structural per-step ceiling for authored occurrences. Validate and Apply also enforce one conservative run-state capacity budget across all steps, paired documents, checks, and durable evidence.
closureType: occurrenceClosure. The closure rule: the objective signal that no more documents are expected for this step. It may be omitted while authoring; Publish writes fixed when min equals max and max_reached otherwise. Because max_reached waits for the maximum, a min-zero unbranched step must instead use expected_count so a zero-document outcome is explicit.

Evidence requirements

Operational evidence required for each occurrence of this step. Duplicate requirement types are rejected by the server.

requirements (required)Type: array of assuranceRequirement.

Evidence requirement

One observable proof required for a step. For example, mapping_succeeded proves that the selected map ran, while functional_or_implementation_acknowledgment_accepted proves accepted 997 or 999 evidence. Outgoing mapping proof may predate the document occurrence because mapping runs immediately before exchange; receipts and acknowledgments may not. A deadline is measured from the document occurrence to the terminal evidence time, and requires that evidence's own timestamp. Terminal evidence timestamped after the run's evaluation time is invalid.

type (required)Type: mapping_succeeded, transport_receipt_accepted, interchange_acknowledgment_accepted, functional_or_implementation_acknowledgment_accepted. mapping_succeeded proves mapper execution; transport_receipt_accepted proves the AS2 receipt; interchange_acknowledgment_accepted proves TA1 acceptance; functional_or_implementation_acknowledgment_accepted proves accepted 997 or 999 evidence.
withinType: positiveDuration. Optional deadline from the business document occurrence to terminal evidence. An outgoing mapping completed before exchange satisfies the lower timing boundary, but its own source timestamp is still required; missing terminal source time cannot prove a deadline.

Transition

A rule from one document step to another. Correlations identify which actual documents belong together. follows models ordinary order, such as a matching 810 invoice after an 850 order. supersedes records a replacement, such as a later 860 order change replacing the prior 850 or 860. cancels records a removal, such as an ocean 303 cancellation for a 301 booking confirmation. Supersedes and cancels inspect every stored observation before any replacement or cancellation is applied; they do not make an otherwise unavailable next-document path available and cannot themselves be branch alternatives.

id (required)Type: token.
fromStep (required)Type: token. Predecessor step ID.
toStep (required)Type: token. Successor step ID. It may equal fromStep only for a supersedes transition that uses previous matching; cancellation is represented by a distinct cancellation-document step.
relationship (required)Type: follows, supersedes, cancels. Choose follows when a matched later document must occur at or after the earlier one, such as an 810 invoice after its 850 order. Choose supersedes when the later document replaces the matched earlier occurrence, such as an 860 order change replacing an 850 or prior 860. Choose cancels when the later document cancels the matched earlier occurrence, such as an ocean 303 cancelling a 301 booking confirmation. supersedes and cancels require effect to say when the change begins and whether later checks keep using the original document or reevaluate with the replacement/removal. Business labels such as acknowledges, reports status, or settles belong in the transition ID and prose unless an assertion or evidence requirement actually verifies them.
withinType: positiveDuration. Optional maximum elapsed time from the correlated fromStep occurrence to the toStep occurrence.
correlationsType: array of correlation. Conditions the scenario evaluator uses to pair actual source and target documents. For example, compare the purchase-order number extracted from an 850 with the purchase-order number extracted from an 810. Correlation IDs must be unique within this transition.
matching (required)Type: occurrenceMatching. Required quantification and pairing semantics for concrete occurrences; the server does not infer them from correlations.
effect (conditionally required)Type: revisionEffect. Required effective-time and downstream behavior for supersedes and cancels. Forbidden for follows.

Correlation

A condition that decides whether two actual documents belong to the same transition pair. equal can match the purchase-order number on an 850 and 810; same_set can compare their item sets; reply_link uses ModernEDI's stored reply relationship and accepts no fact operands.

id (required)Type: token.
operator (required)Type: equal, same_set, reply_link.
left (conditionally required)Type: factOperand. For fact operators, must reference the transition's fromStep.
right (conditionally required)Type: factOperand. For fact operators, must reference the transition's toStep.

Assertion

A fact rule that must hold for the run to pass. For example, exists can require every 810 invoice to expose invoiceTotal, sum_equal can compare shipped and invoiced totals, and monotonic can require successive 315 status timestamps to move forward. Binary operators require right; unary operators reject it.

id (required)Type: token.
operator (required)Type: equal, not_equal, exists, unique, same_set, subset, sum_equal, less_than_or_equal, greater_than_or_equal, monotonic.
left (required)Type: valueOperand.
right (conditionally required)Type: valueOperand.

valueType

Closed evaluator value type. list and set contain scalar values only and require elementType.

Type or allowed values: string, decimal, date, time, timestamp, boolean, list, set.

scalarType

Closed scalar type used directly or as the element type of list and set values.

Type or allowed values: string, decimal, date, time, timestamp, boolean.

factProjection

Select one declared per-occurrence fact value, aggregate values across occurrences as a list or set, or select the first/latest observed occurrence. Correlations require value.

Type or allowed values: value, list, set, first, latest.

decimalJson

A finite JSON number or exact base-10 string. The scenario evaluator normalizes scale without precision loss.

Type or allowed values: number or string; pattern ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$.

Prepared run parameter

A typed value supplied when a run starts through the Workspace UI or API, or resolved from its declared default when optional.

id (required)Type: token. Stable name used by prepare stages, expected-count closure, and parameter operands.
type (required)Type: valueType.
elementType (conditionally required)Type: scalarType. Required exactly when type is list or set.
required (required)Type: boolean. Whether the run must explicitly provide this value. A required parameter cannot also have a default.
defaultType: JSON value. Optional JSON value used when the run omits a non-required parameter.

Checkpoint declaration

A named completion event emitted by exactly one checkpoint pipeline stage after its preceding stages finish. For example, an X12 301 booking-confirmation step can emit bookingDisposition after exchange and fact extraction, allowing the run to choose the cancellation or shipping-instructions path.

id (required)Type: token.

Typed fact declaration

Stable semantic ABI for one fact exposed by a step occurrence. The binding/runtime capability separately defines extraction provenance.

name (required)Type: token. Stable fact name used by discriminated fact operands and binding-side fact sources.
type (required)Type: valueType.
elementType (conditionally required)Type: scalarType. Required exactly when type is list or set; nested collections are not supported.
cardinality (required)Type: one, optional. Presence of the typed value on each occurrence. Collection multiplicity is expressed by type list/set, never by a separate many cardinality.
normalization (required)Type: array of trim, collapse_whitespace, uppercase, lowercase, decimal_canonical. Ordered, deterministic normalization applied before typed evaluation.
sensitivity (required)Type: business, personal, financial, health, restricted. Data-handling classification carried with evidence and diagnostics.

Composed step pipeline stage

One named action in the ordered processing of an observed document. A definition says prepare, map, exchange, extract facts, check evidence, or emit a checkpoint; the binding later selects the concrete map, partner, or adapter. Keeping those artifact IDs out of the definition lets the same conversation recipe be reused by another tenant.

Variants: Prepare stage or Map stage or Exchange stage or Extract stage or Assure stage or Checkpoint stage.

Occurrence closure

The objective rule that tells a run no more documents are expected for one repeated step. fixed closes at the required fixed count; max_reached closes only at the authored maximum; expected_count closes at a required or defaulted run parameter, including an explicit zero. Branch selection supplies the no-document outcome for an unselected destination. There is no manual-close operation in v1.

Variants: Fixed closure or Maximum-reached closure or Expected-count closure.

Occurrence match quantifier

An explicit requirement over source occurrences, target occurrences, matched pairs, or matches per endpoint occurrence.

Variants: Any quantifier or Every quantifier or Exact-count quantifier.

Occurrence matching

How actual repeated documents are paired across a transition, plus what happens to documents with no match. correlate pairs documents whose declared fact or reply-link conditions pass; position pairs by observation order; previous pairs each revision with the immediately preceding occurrence of the same step, such as the second 860 order change with the first.

Variants: Correlation matching or Positional matching or Previous-occurrence matching.

Fact operand

A declared semantic fact from a concrete step occurrence.

kind (required)Type: exactly fact.
stepId (required)Type: token.
fact (required)Type: token. Name from the referenced step's facts declaration.
projection (required)Type: factProjection. How values are selected or aggregated across this step's occurrences. list/set require occurrence max greater than 1 and a scalar declared fact.

Parameter operand

A prepared run parameter usable in assertions, branch predicates, and effective-time expressions.

kind (required)Type: exactly parameter.
parameter (required)Type: token.

Typed literal operand

A closed typed JSON literal. list and set literals require scalar elementType and use a JSON array value.

kind (required)Type: exactly literal.
type (required)Type: valueType.
elementType (conditionally required)Type: scalarType.
value (required)Type: JSON value. JSON value matching type and elementType. The server performs format and exact type validation.

Value operand

Closed discriminated union used by assertions, branch predicates, and effective-time expressions.

Variants: Fact operand or Parameter operand or Typed literal operand.

Revision effective time

When a replacement or cancellation begins to govern the conversation. observed_at uses the time ModernEDI observed the later document. value uses an explicit timestamp, such as effectiveTimestamp extracted from an X12 860 order change. The value must be a timestamp, not only a date or clock time. A fact value belongs to the matched revision pair and must come from its source or later document; for a previous-matched same-step revision, it is read from the later revision occurrence.

Variants: Time ModernEDI observed the revision or Business effective timestamp.

Revision or cancellation effect

What a matched replacement or cancellation changes. Raw immutable observation history means every received document remains stored unchanged; the revision rule changes only the run's interpreted business view. A revision transition does not open a next-document path by itself. Each branch-decision round first snapshots the steps already allowed; its conditions see only active reevaluate effects whose original and later-document steps are both in that snapshot, and a chosen path becomes available only in the next round. After branch selection, a revision affects checks only when both endpoint steps remain on the selected conversation path. If several active reevaluate effects target the same original document, the later effectiveAt wins; equal latest times fail with REVISION_EFFECT_CONFLICT instead of choosing arbitrarily.

effectiveAt (required)Type: effectiveAt. When this replacement or cancellation begins to govern checks. Later active reevaluate effects take precedence for the same original document.
downstream (required)Type: retain, reevaluate. retain records the change and effective time but keeps using the original document for branch conditions, ordinary follows transitions, and assertions; for example, record an advisory 860 while later shipment checks still use the original 850. reevaluate recomputes those same consumers with the replacement or removal; for example, use the revised 860 values for later 856/810 checks, or remove a 301 booking confirmation after its 303 cancellation.
unmatched (required)Type: fail, record. Behavior when no prior effective occurrence can be revised or cancelled. previous matching requires record because the first occurrence is the initial revision and necessarily has no prior occurrence.

Branch predicate

A yes/no condition evaluated after the branch's named checkpoint is emitted. For example, after an X12 301 emits bookingDisposition, compare the cancelRequested run parameter with true to select the X12 303 path. A fact condition must read the common source step of every alternative and that fact's extract stage must precede the checkpoint; it cannot read a destination document or later pipeline evidence to make that destination eligible. Every condition sees the conversation view from the start of the decision round, so one branch cannot use evidence made available by itself or a sibling branch in that round.

id (required)Type: token.
operator (required)Type: equal, not_equal, exists, unique, same_set, subset, sum_equal, less_than_or_equal, greater_than_or_equal, monotonic.
left (required)Type: valueOperand.
right (conditionally required)Type: valueOperand.

Branch alternative

One ordinary follows transition that a branch may select, either when its conditions pass or as the explicit otherwise fallback. For example, cancelRequested=true selects the 301-to-303 follows transition; otherwise selects 301-to-304. supersedes and cancels transitions are revision records, not branch alternatives.

id (required)Type: token.
kind (required)Type: when, otherwise.
transitionId (required)Type: token. ID of a follows transition selected by this branch; supersedes and cancels transitions are not allowed.
conditions (required)Type: array of predicate. Conditions may use parameters, literals, or facts from the alternatives' shared fromStep. They cannot read a destination step to select that destination.

Explicit branch

A choice between mutually exclusive next-document paths after a named checkpoint. The checkpoint must be emitted by the alternatives' shared source step, so the decision precedes every controlled destination. The emitter must also necessarily observe at least one document; expected_count closure with occurrence min 0 cannot emit a branch checkpoint. All alternatives leave the same source step. Example: after a 301 booking confirmation emits bookingDisposition, choose the 303 cancellation path when cancelRequested=true; otherwise choose 304 shipping instructions. exactly_one must choose one path and therefore requires an otherwise fallback. at_most_one may choose no path. A round evaluates only evidence already available when that round began; its selection can make later steps available in the next round.

id (required)Type: token.
mode (required)Type: exactly_one, at_most_one.
checkpoint (required)Type: token.
alternatives (required)Type: array of branchAlternative. at_most_one accepts one or more when alternatives; exactly_one requires at least two alternatives and exactly one otherwise.

*.binding.json

ModernEDI ScenarioBinding v1

A tenant-scoped authoring binding that connects every actor and step in one immutable ScenarioDefinition to current workspace partners and executable targets. It references tenant artifacts by identity and contains no copied runtime configuration, credentials, private keys, or other secrets.

Download JSON Schema Open Example Mapper language tutorial Mapper function reference Mapper expression diagnostics API

Authoring workflow

Publish or select the exact ScenarioDefinition first; copy its namespace, key, version, and contentSha256 into spec.definition.
Bind every actor exactly once. Use one workspace endpoint and one or more current partner endpoints.
Bind every step exactly once to an evidence-constrained runtime mapping, active executable adapter, or observation-only target. Runtime-mapping and observation-only targets do not initiate exchanges.
For every semantic fact declared by a tenant-authored definition step, add one factSources entry. Its expression uses the same X12 Mapper language and functions as an incoming map's primaryKeyExtractor.
Omit syntaxTree for the easiest authoring experience when the chosen target can resolve it. Specify it only when you deliberately need an implementation-guide pin.
Run Validate, then Apply. Apply resolves current artifacts, fails closed on drift or ambiguity, and stores an immutable runtime revision.

Editor and API tooling

factSources[].source.expression is an ordinary value-returning X12 Mapper expression. It is parsed and executed by the same language engine as a mapping's primaryKeyExtractor, not by a scenario-only selector dialect.
The binding editor opens each fact source in a focused Mapper expression editor. It provides syntax-tree-aware completion, hover information, live diagnostics, and the existing searchable function reference using an explicit draft pin, a selected current runtime mapping, or the Mapper catalog's current default as an authoring preview. Apply independently resolves and freezes the exact authoritative tree.
POST /x12mapper/workspace/expression/diagnostics is the public stateless diagnostics operation for external authoring tools. It accepts one expression plus optional X12 release and transaction-set context; it never reads tenant data.
Draft diagnostics are fast authoring feedback. Scenario Validate and Apply remain authoritative for the exact tree, definition fact typing and cardinality, tenant artifacts, target authority, and bounded runtime evaluation.

Server semantic checks

The definition identity and content hash resolve to exactly one published or managed definition available to this tenant.
Actor and step IDs are unique and cover the referenced definition exactly.
Exactly one actor endpoint is the workspace and at least one is a current tenant partner.
Every runnable step must cross the tenant workspace boundary: exactly one endpoint is the workspace and the other is a bound partner. Apply rejects partner-to-partner and workspace-to-workspace steps because ModernEDI can neither operate nor authoritatively observe them.
Runtime mappings match the step direction, partner, transaction set, and resolved syntax tree. They constrain authoritative evidence from the ordinary transaction pipeline; they do not dispatch scenario documents.
Tenant-authored steps bind every declared fact exactly once. Mapper expressions are parsed and semantically validated against the resolved syntax tree before Apply, must be capable of an X12 segment or element read, and must produce concrete read provenance at runtime; value type, collection behavior, normalization, and sensitivity are taken from the definition.
Adapters are registered and cover the referenced definition and step. An adapter target may additionally pin a runtime mapping when the adapter executes the step but attached evidence must prove that exact mapping.
Apply records an immutable, fully resolved execution binding; an optional authoring syntaxTree never makes the runtime artifact ambiguous.

Runtime observation durability

X12 Mapper expressions retain their ordinary language semantics, while the typed fact values and evidence persisted for one observation are deliberately bounded. Collections may contain at most 1,000 scalar values, each string value may contain at most 4,096 UTF-8 bytes, each encoded typed value may contain at most 32,768 bytes, and the combined durable fact projection may contain at most 262,144 bytes. Fact provenance receipts, individual evidence documents, non-fact evidence count, and aggregate evidence JSON have their own documented limits. Every bound is checked before SQL persistence and returns a stable fact or observation capacity diagnostic.

Collection maximum: 1,000 scalar values.
UTF-8 text maximum per scalar: 4,096 bytes.
Encoded typed-value maximum: 32,768 bytes.
Combined durable fact projection maximum per observation: 262,144 bytes.
Fact provenance receipt maximum: 4,096 bytes.
Evidence document maximum: 8,192 bytes; at most 8 non-fact evidence documents per observation.
Combined durable evidence maximum per observation: 524,288 bytes.
Stable diagnostics: fact_value_limit_exceeded, transaction_observation_capacity_exceeded, transaction_fact_evidence_capacity_exceeded, and transaction_evidence_capacity_exceeded.

Example

{
  "$schema": "https://www.modernedi.com/docs/scenarios/schemas/scenario-binding-v1.schema.json",
  "apiVersion": "modernedi.com/scenario-binding-authoring/v1",
  "kind": "ScenarioBinding",
  "metadata": {
    "id": "retailOrderInvoice",
    "name": "Retail order to invoice"
  },
  "spec": {
    "definition": {
      "namespace": "acme",
      "key": "retail-order-invoice",
      "version": "1.0.0",
      "contentSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    },
    "environment": "production",
    "actors": [
      {
        "actorId": "retailer",
        "endpoint": {
          "kind": "partner",
          "partnerId": 42
        }
      },
      {
        "actorId": "supplier",
        "endpoint": {
          "kind": "workspace"
        }
      }
    ],
    "steps": [
      {
        "stepId": "purchaseOrder",
        "target": {
          "kind": "runtime-mapping",
          "runtimeMappingId": 101
        },
        "factSources": [
          {
            "fact": "purchaseOrderNumber",
            "source": {
              "kind": "x12-mapper-expression",
              "expression": "ST->BEG(03)"
            }
          }
        ]
      },
      {
        "stepId": "invoice",
        "syntaxTree": {
          "x12Version": "004010",
          "transactionSet": "810"
        },
        "target": {
          "kind": "runtime-mapping",
          "runtimeMappingId": 102
        },
        "factSources": [
          {
            "fact": "purchaseOrderNumber",
            "source": {
              "kind": "x12-mapper-expression",
              "expression": "ST->BIG(04)"
            }
          },
          {
            "fact": "invoiceTotal",
            "source": {
              "kind": "x12-mapper-expression",
              "expression": "ST->TDS(01)"
            }
          }
        ]
      }
    ]
  }
}

Fields

Expand a shape for schema-derived field help. The Mapper shows the same descriptions on hover.

token

A stable identifier beginning with a letter and containing at most 128 letters, digits, underscores, or hyphens.

Type or allowed values: string; pattern ^[A-Za-z][A-Za-z0-9_-]{0,127}$.

namespace

Lowercase namespace of the published ScenarioDefinition.

Type or allowed values: string; max length 253; pattern ^[a-z0-9]+(?:[.-][a-z0-9]+)*$.

artifactVersion

Exact published definition version.

Type or allowed values: string; min length 1; max length 64; pattern ^(?!\s)(?!.*\s$)[^\u0000-\u001F\u007F]+$.

Binding metadata

Editable identity and display name for this binding draft. Apply creates an immutable binding revision.

id (required)Type: token. Stable binding ID within the workspace.
name (required)Type: string; min length 1; max length 160; pattern \S. Human-readable binding name. The server trims leading and trailing whitespace when canonicalizing.

Binding specification

References one exact published definition and binds all of its actors and steps. Apply resolves and freezes authoritative artifacts for runtime use.

definition (required)Type: definitionReference.
environment (required)Type: exactly production. ModernEDI's tenant runtime environment selector. v1 runs only against the tenant production runtime; ordinary product access, workspace permissions, and applied-binding readiness govern use.
actors (required)Type: array of actorBinding. Exactly one binding for every definition actor. IDs must be unique; exactly one endpoint must be this workspace and at least one must be a current external partner.
steps (required)Type: array of stepBinding. Exactly one binding for every definition step. IDs must be unique.

Published definition reference

Exact identity and canonical content hash returned by Publish or the scenario catalog. Apply fails closed if any part differs.

namespace (required)Type: namespace.
key (required)Type: token.
version (required)Type: artifactVersion.
contentSha256 (required)Type: string; pattern ^[0-9a-f]{64}$. Lowercase SHA-256 digest of the canonical published definition.

Actor binding

Connects one definition actor to this workspace or a current trading partner.

actorId (required)Type: token. Actor ID from the referenced ScenarioDefinition.
endpoint (required)Type: endpoint.

Actor endpoint

OneOf discriminator: workspace accepts only kind; partner also requires a positive tenant partner ID.

Variants: Workspace endpoint or Partner endpoint.

Step binding

Connects one definition step to an executable or observation target and binds every declared semantic fact to an implementation-guide source. syntaxTree is optional while authoring; Apply resolves an exact authoritative syntax-tree artifact before runtime execution.

stepId (required)Type: token. Step ID from the referenced ScenarioDefinition.
syntaxTreeType: syntaxTreeReference. Optional explicit implementation-guide identity. Omit it to let Apply select the exact current syntax tree from the authoritative mapping or adapter; an applied runtime binding is always resolved and immutable.
target (required)Type: target.
factSourcesType: array of factSourceBinding. One source for every fact declared by this ScenarioDefinition step. Omission is a deliberate authoring shorthand only when the step declares no facts; canonical Apply materializes an empty array. Server validation otherwise requires exact fact-name coverage. Collection shape, element type, cardinality, normalization, and sensitivity come only from the declaration and are intentionally not duplicated here.

Fact source binding

Binds one named fact declaration to one validated X12 Mapper expression. Fact names must be unique within a step.

fact (required)Type: token. Fact name declared by this exact ScenarioDefinition step.
source (required)Type: factSource.

Fact source

One ordinary X12 Mapper expression fact source. It uses the same language and execution engine as an incoming map's primaryKeyExtractor; v1 does not define a second scenario-specific selector language. The expression must read the bound X12 document so its value has concrete provenance.

Variants: X12 Mapper expression fact source.

X12 Mapper expression fact source

Evaluates one ordinary X12 Mapper expression against the step transaction. Validate and Apply use the same parser, semantic validator, function registry, budget mechanism, and syntax-tree-aware engine as runtime mappings and primaryKeyExtractor, with scenario-specific bounded limits. Validate and Apply reject an expression that is statically incapable of reading an X12 segment or element, and runtime fails closed when the executed path produces no concrete X12 read. Scenario evidence uses that engine's element-read tracing facility; this does not imply that existing primary-key persistence emits the same trace. The ScenarioDefinition remains authoritative for value type, cardinality, normalization, and sensitivity.

kind (required)Type: exactly x12-mapper-expression. Uses ModernEDI's existing X12 Mapper expression language and engine, shared with primaryKeyExtractor.
expression (required)Type: string; min length 1; max length 16384; pattern \S. One value-returning X12 Mapper expression that reads at least one X12 segment or element. A constant-only expression cannot provide authoritative document evidence. Scalars, lists, and sets are interpreted according to the matching fact declaration; secrets and credentials must never appear here.

Syntax-tree reference

Optional authoring-time pin to an exact X12 release and transaction set. Both fields are required when this object is present.

x12Version (required)Type: string; pattern ^[Vv]?(?:00)?[1-9][0-9]{3}$. X12 release token. Apply canonicalizes accepted forms to a six-digit release such as 004010.
transactionSet (required)Type: string; pattern ^[0-9]{3}$. Known three-digit X12 transaction set. The code must match the referenced definition step.

Step target

OneOf discriminator selecting an evidence-constrained runtime mapping, a registered active executor adapter, or observation-only evidence.

Variants: Runtime mapping target or Adapter target or Observation-only target.

Executable examples

Learn from the same definitions the scenario evaluator tests

These files preserve the business semantics of backend definitions that are compiled, checked against the tenant runtime-capacity budget, and evaluated through the scenario interpreter. They cover warehouse, retail, grocery, and ocean conversations without maintaining a second documentation-only model.

The published examples use the reserved modernedi.examples namespace. Change metadata.namespace to one owned by your tenant before validating or publishing a copy.

grocery-order-to-invoiceX12 875, 856, 880; relationships follows; correlations equal; assertions subset, equal; closure fixed; matching correlate, position; quantifiers every:from, every:to, every:pairs; unmatched fail; pipeline exchange, extract; fact types string, set<string>, decimalOpen tested JSON
grocery-product-activityX12 852; assertions exists, unique; closure fixed; pipeline exchange, extract; fact types date, list<string>, list<decimal>Open tested JSON
ocean-booking-to-invoiceX12 300, 301, 303, 304, 315, 313, 312, 310; relationships supersedes, follows, cancels; correlations equal; assertions monotonic, greater_than_or_equal; closure expected_count, fixed, max_reached; matching previous, correlate, position; quantifiers every:to, every:from, exactly:pairs, any:pairs, every:pairs; unmatched record, fail; revision effects observed_at:reevaluate, observed_at:retain; pipeline exchange, extract, checkpoint; fact types string, decimal, timestamp; branches exactly_one, at_most_one; 2 checkpointsOpen tested JSON
retail-order-lifecycleX12 850, 855, 860, 865, 856, 810; relationships follows, supersedes; correlations same_set, equal; assertions monotonic, unique, sum_equal; closure fixed, expected_count; matching correlate, previous, position; quantifiers every:to, exactly:pairs, every:from; unmatched record, fail; revision effects observed_at:retain, value:reevaluate; pipeline exchange, extract; fact types string, set<string>, decimal, timestampOpen tested JSON
warehouse-outboundX12 940, 945; relationships follows; correlations equal; assertions unique, sum_equal; closure fixed, expected_count; matching correlate; quantifiers every:from, every:to, exactly:pairs; unmatched fail; pipeline exchange, extract; fact types string, decimal; 1 time windowOpen tested JSON

Signed-in Workspace API

One contract across editor and automation

This contract serves signed-in ModernEDI workspace users and browser/BFF automation acting with the same tenant session. It is intentionally separate from the public API-key Integration API. An Integration API key does not authenticate tenant routes. The one stateless Mapper expression-diagnostics operation is explicitly public and never reads or changes tenant data.

Authentication: The signed-in workspace session used by app.modernedi.com. Tenant product access and READ or OPERATE permission are enforced in addition to authentication. This is not an Integration API key.

Lifecycle resources return quoted SHA-256 ETags such as "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa". Runs return opaque revision ETags such as "scenario-run:v1:42:cnVuLTUwMDdkYmYzLWYxMTUtNGNhYy04NTMwLTE4OGZiNDMyNmM0NQ:1". Never construct or edit either form; return the latest value unchanged as the next operation's If-Match.

Download OpenAPI 3.1

GET /tenant/scenarios/catalog
Returns managed and tenant-published definitions with canonical hashes, topological order, syntax-tree readiness, and managed-adapter information. definition_only means the catalog has no single stored X12 release covering every step; syntax_tree_backed means at least one stored release covers every step but no exact ModernEDI-managed adapter is registered; executable_adapter means one exact registered managed adapter covers the definition identity, hash, and every step. These catalog labels do not decide whether a tenant-specific binding can run: Validate and Apply make that decision from the binding's exact partners, per-step syntax trees, mappings, observation targets, fact expressions, and adapters. The response is private and conditionally cacheable with its strong ETag.
Permission: READ. Headers: none. Success: 200 ScenarioCatalogResponse.
Stable error codes: none.

POST /x12mapper/workspaces/{workspaceId}/scenario-authoring/validate

Runs strict JSON parsing, JSON Schema validation, cross-file resolution, tenant-authority checks, graph checks, fact typing, and current runtime-capability checks without publishing or applying anything.

Permission: OPERATE. Headers: none. Success: 200 ScenarioValidationResponse.

Stable error codes: invalid_request.

{
  "files": [
    {
      "id": "order-invoice.scenario.json",
      "fileType": "SCENARIO_DEFINITION",
      "source": "{\n  \"$schema\": \"https://www.modernedi.com/docs/scenarios/schemas/scenario-definition-v1.schema.json\",\n  \"apiVersion\": \"modernedi.com/scenario/v1\",\n  \"kind\": \"ScenarioDefinition\",\n  \"metadata\": {\n    \"namespace\": \"acme\",\n    \"key\": \"retail-order-invoice\",\n    \"version\": \"1.0.0\"\n  },\n  \"spec\": {\n    \"actors\": [\n      {\n        \"id\": \"retailer\"\n      },\n      {\n        \"id\": \"supplier\"\n      }\n    ],\n    \"steps\": [\n      {\n        \"id\": \"purchaseOrder\",\n        \"fromActor\": \"retailer\",\n        \"toActor\": \"supplier\",\n        \"transaction\": {\n          \"standard\": \"X12\",\n          \"transactionSet\": \"850\",\n          \"businessUsage\": \"purchase_order\"\n        },\n        \"occurrence\": {\n          \"min\": 1,\n          \"max\": 1,\n          \"closure\": {\n            \"kind\": \"fixed\"\n          }\n        },\n        \"assurance\": {\n          \"requirements\": [\n            {\n              \"type\": \"mapping_succeeded\"\n            }\n          ]\n        },\n        \"facts\": [\n          {\n            \"name\": \"purchaseOrderNumber\",\n            \"type\": \"string\",\n            \"cardinality\": \"one\",\n            \"normalization\": [\n              \"trim\"\n            ],\n            \"sensitivity\": \"business\"\n          }\n        ],\n        \"pipeline\": [\n          {\n            \"id\": \"exchange\",\n            \"kind\": \"exchange\"\n          },\n          {\n            \"id\": \"extract\",\n            \"kind\": \"extract\",\n            \"facts\": [\n              \"purchaseOrderNumber\"\n            ]\n          },\n          {\n            \"id\": \"assure\",\n            \"kind\": \"assure\"\n          }\n        ]\n      },\n      {\n        \"id\": \"invoice\",\n        \"fromActor\": \"supplier\",\n        \"toActor\": \"retailer\",\n        \"transaction\": {\n          \"standard\": \"X12\",\n          \"transactionSet\": \"810\",\n          \"businessUsage\": \"invoice\"\n        },\n        \"occurrence\": {\n          \"min\": 1,\n          \"max\": 1,\n          \"closure\": {\n            \"kind\": \"fixed\"\n          }\n        },\n        \"assurance\": {\n          \"requirements\": [\n            {\n              \"type\": \"transport_receipt_accepted\",\n              \"within\": \"PT4H\"\n            },\n            {\n              \"type\": \"functional_or_implementation_acknowledgment_accepted\"\n            }\n          ]\n        },\n        \"facts\": [\n          {\n            \"name\": \"purchaseOrderNumber\",\n            \"type\": \"string\",\n            \"cardinality\": \"one\",\n            \"normalization\": [\n              \"trim\"\n            ],\n            \"sensitivity\": \"business\"\n          },\n          {\n            \"name\": \"invoiceTotal\",\n            \"type\": \"decimal\",\n            \"cardinality\": \"optional\",\n            \"normalization\": [\n              \"decimal_canonical\"\n            ],\n            \"sensitivity\": \"financial\"\n          }\n        ],\n        \"pipeline\": [\n          {\n            \"id\": \"exchange\",\n            \"kind\": \"exchange\"\n          },\n          {\n            \"id\": \"extract\",\n            \"kind\": \"extract\",\n            \"facts\": [\n              \"purchaseOrderNumber\",\n              \"invoiceTotal\"\n            ]\n          },\n          {\n            \"id\": \"assure\",\n            \"kind\": \"assure\"\n          }\n        ]\n      }\n    ],\n    \"transitions\": [\n      {\n        \"id\": \"invoiceSettlesOrder\",\n        \"fromStep\": \"purchaseOrder\",\n        \"toStep\": \"invoice\",\n        \"relationship\": \"follows\",\n        \"within\": \"P30D\",\n        \"correlations\": [\n          {\n            \"id\": \"samePurchaseOrder\",\n            \"operator\": \"equal\",\n            \"left\": {\n              \"kind\": \"fact\",\n              \"stepId\": \"purchaseOrder\",\n              \"fact\": \"purchaseOrderNumber\",\n              \"projection\": \"value\"\n            },\n            \"right\": {\n              \"kind\": \"fact\",\n              \"stepId\": \"invoice\",\n              \"fact\": \"purchaseOrderNumber\",\n              \"projection\": \"value\"\n            }\n          }\n        ],\n        \"matching\": {\n          \"strategy\": \"correlate\",\n          \"quantifiers\": [\n            {\n              \"kind\": \"every\",\n              \"scope\": \"from\"\n            },\n            {\n              \"kind\": \"every\",\n              \"scope\": \"to\"\n            }\n          ],\n          \"unmatched\": \"fail\"\n        }\n      }\n    ],\n    \"assertions\": [\n      {\n        \"id\": \"invoiceTotalExists\",\n        \"operator\": \"exists\",\n        \"left\": {\n          \"kind\": \"fact\",\n          \"stepId\": \"invoice\",\n          \"fact\": \"invoiceTotal\",\n          \"projection\": \"value\"\n        }\n      }\n    ],\n    \"parameters\": [],\n    \"checkpoints\": [],\n    \"branches\": []\n  }\n}\n"
    },
    {
      "id": "order-invoice.binding.json",
      "fileType": "SCENARIO_BINDING",
      "source": "{\n  \"$schema\": \"https://www.modernedi.com/docs/scenarios/schemas/scenario-binding-v1.schema.json\",\n  \"apiVersion\": \"modernedi.com/scenario-binding-authoring/v1\",\n  \"kind\": \"ScenarioBinding\",\n  \"metadata\": {\n    \"id\": \"retailOrderInvoice\",\n    \"name\": \"Retail order to invoice\"\n  },\n  \"spec\": {\n    \"definition\": {\n      \"namespace\": \"acme\",\n      \"key\": \"retail-order-invoice\",\n      \"version\": \"1.0.0\",\n      \"contentSha256\": \"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"\n    },\n    \"environment\": \"production\",\n    \"actors\": [\n      {\n        \"actorId\": \"retailer\",\n        \"endpoint\": {\n          \"kind\": \"partner\",\n          \"partnerId\": 42\n        }\n      },\n      {\n        \"actorId\": \"supplier\",\n        \"endpoint\": {\n          \"kind\": \"workspace\"\n        }\n      }\n    ],\n    \"steps\": [\n      {\n        \"stepId\": \"purchaseOrder\",\n        \"target\": {\n          \"kind\": \"runtime-mapping\",\n          \"runtimeMappingId\": 101\n        },\n        \"factSources\": [\n          {\n            \"fact\": \"purchaseOrderNumber\",\n            \"source\": {\n              \"kind\": \"x12-mapper-expression\",\n              \"expression\": \"ST->BEG(03)\"\n            }\n          }\n        ]\n      },\n      {\n        \"stepId\": \"invoice\",\n        \"syntaxTree\": {\n          \"x12Version\": \"004010\",\n          \"transactionSet\": \"810\"\n        },\n        \"target\": {\n          \"kind\": \"runtime-mapping\",\n          \"runtimeMappingId\": 102\n        },\n        \"factSources\": [\n          {\n            \"fact\": \"purchaseOrderNumber\",\n            \"source\": {\n              \"kind\": \"x12-mapper-expression\",\n              \"expression\": \"ST->BIG(04)\"\n            }\n          },\n          {\n            \"fact\": \"invoiceTotal\",\n            \"source\": {\n              \"kind\": \"x12-mapper-expression\",\n              \"expression\": \"ST->TDS(01)\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n"
    }
  ]
}

GET /x12mapper/workspaces/{workspaceId}/scenario-authoring/definitions
Returns definition identities and publication provenance for this tenant. The original source is intentionally represented by its canonical identity and hash.
Permission: READ. Headers: none. Success: 200 PublishedDefinitionListResponse.
Stable error codes: invalid_request.

POST /x12mapper/workspaces/{workspaceId}/scenario-authoring/definitions/publish

Publishes the exact definition source only when its canonical hash matches expectedContentSha256. Reusing an Idempotency-Key with the identical request replays the original result; reusing it for different content is a conflict.

Permission: OPERATE. Headers: Idempotency-Key (required), If-None-Match (required). Success: 200 PublishedDefinitionMutationResponse; 201 PublishedDefinitionMutationResponse.

Stable error codes: invalid_request, precondition_required, precondition_failed, definition_identity_conflict, scenario_revision_conflict, idempotency_key_conflict, content_hash_mismatch, scenario_authoring_quota_exceeded.

{
  "file": {
    "id": "order-invoice.scenario.json",
    "fileType": "SCENARIO_DEFINITION",
    "source": "{\n  \"$schema\": \"https://www.modernedi.com/docs/scenarios/schemas/scenario-definition-v1.schema.json\",\n  \"apiVersion\": \"modernedi.com/scenario/v1\",\n  \"kind\": \"ScenarioDefinition\",\n  \"metadata\": {\n    \"namespace\": \"acme\",\n    \"key\": \"retail-order-invoice\",\n    \"version\": \"1.0.0\"\n  },\n  \"spec\": {\n    \"actors\": [\n      {\n        \"id\": \"retailer\"\n      },\n      {\n        \"id\": \"supplier\"\n      }\n    ],\n    \"steps\": [\n      {\n        \"id\": \"purchaseOrder\",\n        \"fromActor\": \"retailer\",\n        \"toActor\": \"supplier\",\n        \"transaction\": {\n          \"standard\": \"X12\",\n          \"transactionSet\": \"850\",\n          \"businessUsage\": \"purchase_order\"\n        },\n        \"occurrence\": {\n          \"min\": 1,\n          \"max\": 1,\n          \"closure\": {\n            \"kind\": \"fixed\"\n          }\n        },\n        \"assurance\": {\n          \"requirements\": [\n            {\n              \"type\": \"mapping_succeeded\"\n            }\n          ]\n        },\n        \"facts\": [\n          {\n            \"name\": \"purchaseOrderNumber\",\n            \"type\": \"string\",\n            \"cardinality\": \"one\",\n            \"normalization\": [\n              \"trim\"\n            ],\n            \"sensitivity\": \"business\"\n          }\n        ],\n        \"pipeline\": [\n          {\n            \"id\": \"exchange\",\n            \"kind\": \"exchange\"\n          },\n          {\n            \"id\": \"extract\",\n            \"kind\": \"extract\",\n            \"facts\": [\n              \"purchaseOrderNumber\"\n            ]\n          },\n          {\n            \"id\": \"assure\",\n            \"kind\": \"assure\"\n          }\n        ]\n      },\n      {\n        \"id\": \"invoice\",\n        \"fromActor\": \"supplier\",\n        \"toActor\": \"retailer\",\n        \"transaction\": {\n          \"standard\": \"X12\",\n          \"transactionSet\": \"810\",\n          \"businessUsage\": \"invoice\"\n        },\n        \"occurrence\": {\n          \"min\": 1,\n          \"max\": 1,\n          \"closure\": {\n            \"kind\": \"fixed\"\n          }\n        },\n        \"assurance\": {\n          \"requirements\": [\n            {\n              \"type\": \"transport_receipt_accepted\",\n              \"within\": \"PT4H\"\n            },\n            {\n              \"type\": \"functional_or_implementation_acknowledgment_accepted\"\n            }\n          ]\n        },\n        \"facts\": [\n          {\n            \"name\": \"purchaseOrderNumber\",\n            \"type\": \"string\",\n            \"cardinality\": \"one\",\n            \"normalization\": [\n              \"trim\"\n            ],\n            \"sensitivity\": \"business\"\n          },\n          {\n            \"name\": \"invoiceTotal\",\n            \"type\": \"decimal\",\n            \"cardinality\": \"optional\",\n            \"normalization\": [\n              \"decimal_canonical\"\n            ],\n            \"sensitivity\": \"financial\"\n          }\n        ],\n        \"pipeline\": [\n          {\n            \"id\": \"exchange\",\n            \"kind\": \"exchange\"\n          },\n          {\n            \"id\": \"extract\",\n            \"kind\": \"extract\",\n            \"facts\": [\n              \"purchaseOrderNumber\",\n              \"invoiceTotal\"\n            ]\n          },\n          {\n            \"id\": \"assure\",\n            \"kind\": \"assure\"\n          }\n        ]\n      }\n    ],\n    \"transitions\": [\n      {\n        \"id\": \"invoiceSettlesOrder\",\n        \"fromStep\": \"purchaseOrder\",\n        \"toStep\": \"invoice\",\n        \"relationship\": \"follows\",\n        \"within\": \"P30D\",\n        \"correlations\": [\n          {\n            \"id\": \"samePurchaseOrder\",\n            \"operator\": \"equal\",\n            \"left\": {\n              \"kind\": \"fact\",\n              \"stepId\": \"purchaseOrder\",\n              \"fact\": \"purchaseOrderNumber\",\n              \"projection\": \"value\"\n            },\n            \"right\": {\n              \"kind\": \"fact\",\n              \"stepId\": \"invoice\",\n              \"fact\": \"purchaseOrderNumber\",\n              \"projection\": \"value\"\n            }\n          }\n        ],\n        \"matching\": {\n          \"strategy\": \"correlate\",\n          \"quantifiers\": [\n            {\n              \"kind\": \"every\",\n              \"scope\": \"from\"\n            },\n            {\n              \"kind\": \"every\",\n              \"scope\": \"to\"\n            }\n          ],\n          \"unmatched\": \"fail\"\n        }\n      }\n    ],\n    \"assertions\": [\n      {\n        \"id\": \"invoiceTotalExists\",\n        \"operator\": \"exists\",\n        \"left\": {\n          \"kind\": \"fact\",\n          \"stepId\": \"invoice\",\n          \"fact\": \"invoiceTotal\",\n          \"projection\": \"value\"\n        }\n      }\n    ],\n    \"parameters\": [],\n    \"checkpoints\": [],\n    \"branches\": []\n  }\n}\n"
  },
  "expectedContentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

GET /x12mapper/workspaces/{workspaceId}/scenario-authoring/bindings
Returns every immutable applied binding revision visible to this tenant, including the exact definition, runtime activation, authority state, and ETag.
Permission: READ. Headers: none. Success: 200 AppliedBindingListResponse.
Stable error codes: invalid_request.
GET /x12mapper/workspaces/{workspaceId}/scenario-authoring/bindings/{bindingId}
Reads one exact binding identity and returns the strong ETag required to apply the next revision.
Permission: READ. Headers: none. Success: 200 AppliedBindingResponse.
Stable error codes: invalid_request, scenario_binding_not_found.

PUT /x12mapper/workspaces/{workspaceId}/scenario-authoring/bindings/{bindingId}

Resolves the authoring document against current tenant authority, freezes exact runtime artifacts, and creates a reproducible applied revision. Use If-None-Match: * to create revision zero; use the current strong If-Match ETag for later revisions.

Permission: OPERATE. Headers: Idempotency-Key (required), If-Match, If-None-Match. Success: 200 AppliedBindingMutationResponse; 201 AppliedBindingMutationResponse.

Stable error codes: invalid_request, precondition_required, precondition_failed, etag_mismatch, authority_etag_mismatch, scenario_revision_conflict, idempotency_key_conflict, content_hash_mismatch, scenario_authoring_quota_exceeded, scenario_binding_no_change, scenario_binding_not_executable.

{
  "file": {
    "id": "order-invoice.binding.json",
    "fileType": "SCENARIO_BINDING",
    "source": "{\n  \"$schema\": \"https://www.modernedi.com/docs/scenarios/schemas/scenario-binding-v1.schema.json\",\n  \"apiVersion\": \"modernedi.com/scenario-binding-authoring/v1\",\n  \"kind\": \"ScenarioBinding\",\n  \"metadata\": {\n    \"id\": \"retailOrderInvoice\",\n    \"name\": \"Retail order to invoice\"\n  },\n  \"spec\": {\n    \"definition\": {\n      \"namespace\": \"acme\",\n      \"key\": \"retail-order-invoice\",\n      \"version\": \"1.0.0\",\n      \"contentSha256\": \"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"\n    },\n    \"environment\": \"production\",\n    \"actors\": [\n      {\n        \"actorId\": \"retailer\",\n        \"endpoint\": {\n          \"kind\": \"partner\",\n          \"partnerId\": 42\n        }\n      },\n      {\n        \"actorId\": \"supplier\",\n        \"endpoint\": {\n          \"kind\": \"workspace\"\n        }\n      }\n    ],\n    \"steps\": [\n      {\n        \"stepId\": \"purchaseOrder\",\n        \"target\": {\n          \"kind\": \"runtime-mapping\",\n          \"runtimeMappingId\": 101\n        },\n        \"factSources\": [\n          {\n            \"fact\": \"purchaseOrderNumber\",\n            \"source\": {\n              \"kind\": \"x12-mapper-expression\",\n              \"expression\": \"ST->BEG(03)\"\n            }\n          }\n        ]\n      },\n      {\n        \"stepId\": \"invoice\",\n        \"syntaxTree\": {\n          \"x12Version\": \"004010\",\n          \"transactionSet\": \"810\"\n        },\n        \"target\": {\n          \"kind\": \"runtime-mapping\",\n          \"runtimeMappingId\": 102\n        },\n        \"factSources\": [\n          {\n            \"fact\": \"purchaseOrderNumber\",\n            \"source\": {\n              \"kind\": \"x12-mapper-expression\",\n              \"expression\": \"ST->BIG(04)\"\n            }\n          },\n          {\n            \"fact\": \"invoiceTotal\",\n            \"source\": {\n              \"kind\": \"x12-mapper-expression\",\n              \"expression\": \"ST->TDS(01)\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n"
  },
  "expectedContentSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "expectedAuthorityEtag": "\"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\""
}

POST /x12mapper/workspace/expression/diagnostics
Returns tree-aware X12 Mapper diagnostics for exactly one value-returning expression. This is the fast editor/tooling check used while authoring a binding; scenario Validate remains authoritative for definition fact types, exact fact coverage, tenant artifacts, and Apply eligibility.
Permission: Public and stateless; no tenant data. Headers: none. Success: 200 MapperExpressionDiagnosticsResponse.
Stable error codes: none.
```
{
  "source": "ST->BEG(03)",
  "x12Version": "004010",
  "transactionSetId": "850"
}
```
GET /tenant/scenario-runs
Returns a bounded tenant-scoped summary of recent runs for discovery and navigation without exposing fact values or evidence payloads.
Permission: READ. Headers: none. Success: 200 ScenarioRunCollection.
Stable error codes: invalid_request, server_error.
POST /tenant/scenario-runs
Starts a durable run from exact definition and binding hashes. Optional typed parameters are checked against the definition before any operation is accepted. Registered adapter targets prepare their current runtime dependencies before the run is inserted; temporary preparation failures are retryable and return Retry-After.
Permission: OPERATE. Headers: Idempotency-Key (required). Success: 201 ScenarioRunCommandResponse.
Stable error codes: invalid_request, scenario_environment_not_executable, scenario_definition_changed, scenario_preparation_unavailable, scenario_binding_incomplete, scenario_target_executor_unavailable, idempotency_key_conflict, scenario_binding_changed, scenario_active_run_quota_exceeded, scenario_start_rate_limited, server_error.
```
{
  "definition": {
    "namespace": "acme",
    "key": "retail-order-invoice",
    "version": "1.0.0",
    "contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "environment": "production",
  "binding": {
    "id": "retailOrderInvoice",
    "revision": 0,
    "contentSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  },
  "parameters": {}
}
```
POST /tenant/implementation-verifications/test-partner-order-invoice/runs
Starts the named ModernEDI-managed test-partner order/invoice flow without asking the caller to create or select a binding. This is a deliberate guided shortcut for the exact bundled 850 to 810 conversation; every resulting run still uses the same scenario evaluator as a custom run and can be inspected through the general run routes.
Permission: OPERATE. Headers: Idempotency-Key (required). Success: 201 ScenarioRunCommandResponse.
Stable error codes: invalid_request, scenario_definition_not_executable, scenario_environment_not_executable, scenario_preparation_unavailable, scenario_binding_incomplete, idempotency_key_conflict, scenario_binding_changed, scenario_active_run_quota_exceeded, scenario_start_rate_limited, server_error.
```
{}
```
POST /tenant/test-as2-partner/warehouse-outbound/setup
Idempotently creates or refreshes the ModernEDI-owned test partner and managed X12 940 runtime mapping used by the warehouse outbound example. This prepares tenant-owned dependencies but does not publish a definition, apply a binding, or start a run. Validate and Apply an exact warehouse binding in Mapper, then start it through POST /tenant/scenario-runs.
Permission: OPERATE. Headers: none. Success: 200 WarehouseOutboundSetupResponse.
Stable error codes: none.
```
{}
```
GET /tenant/scenario-runs/{runId}
Returns the current durable revision, evidence-bearing observations, checks, outcome, and strong ETag. Sensitive fact values are redacted from the public representation.
Permission: READ. Headers: none. Success: 200 ScenarioRunViewResponse.
Stable error codes: invalid_request, scenario_run_not_found, server_error.
GET /tenant/scenario-runs/{runId}/timeline
Returns a bounded, newest-first audit timeline without idempotency hashes, attempt tokens, transient credentials, or operation result payloads. The cursor is opaque and bound to both the tenant and run.
Permission: READ. Headers: none. Success: 200 ScenarioRunTimelineResponse.
Stable error codes: invalid_request, scenario_run_not_found, server_error.
GET /tenant/scenario-runs/{runId}/evidence-report
Creates the report once from terminal durable state and thereafter returns the exact persisted canonical JSON. It records the frozen authority and redacted evidence needed to substantiate the bounded implementation-verification claim; it is not editable scenario source, raw X12, or a compliance certificate. Stable failure codes are included, while detailed failure messages remain in the run timeline so the credential-free proof stays within its fixed export bound. If a retry creates another audit record for the same successful state change, the report counts that change once and keeps its earliest record; the timeline still shows every attempt.
Permission: READ. Headers: none. Success: 200 ScenarioEvidenceReport.
Stable error codes: invalid_request, scenario_run_not_found, scenario_run_not_terminal, scenario_evidence_report_too_large, server_error.
POST /tenant/scenario-runs/{runId}/cancel
Records an actor-attributed operator cancellation as an inconclusive terminal result while preserving all evidence already gathered. Cancellation is optimistic-concurrency controlled and idempotent, and it does not interrupt a command that still owns the run. If a command stops without saving a result and its temporary ownership period expires, ModernEDI records that attempt as failed and claims cancellation as one durable change. If the abandoned command may already have affected an external system, its failed timeline entry remains available for manual reconciliation. Each run can store at most 256 command records. The initial start and all later ordinary commands share 253 records; the remaining three are held for one retry record, cancellation, and a retry of cancellation. Result documents for ordinary commands share a 32 MiB budget, with additional space held for those same three reserved records.
Permission: OPERATE. Headers: Idempotency-Key (required), If-Match (required). Success: 200 ScenarioRunCommandResponse.
Stable error codes: invalid_request, precondition_required, etag_mismatch, scenario_run_not_found, scenario_run_terminal, idempotency_key_conflict, scenario_operation_in_progress, scenario_run_operation_limit_exceeded, scenario_run_result_bytes_limit_exceeded, scenario_operation_ownership_lost, server_error.
```
{}
```
POST /tenant/scenario-runs/{runId}/advance
When runtime guidance selects a server-controlled step, this command dispatches or reconciles that step. Before external dispatch, ModernEDI prepares the current runtime dependencies and reconfirms the managed adapter target against the run's frozen binding authority. A temporary preparation outage is retryable and may return Retry-After; an incomplete or changed binding, or an unavailable target executor, rejects the command before dispatch. A failed adapter or preparation advance is durable: retry it with the current run ETag and a fresh Idempotency-Key. Reusing the failed operation's Idempotency-Key is a pure replay and never attempts preparation or dispatch again. Transient downstream rejections use scenario_adapter_dispatch_retryable; when the supplied x-api-key must be corrected they use scenario_adapter_dispatch_api_key_correction_required. The selected step and occurrence stay in structured run guidance instead of changing the stable error code. Observation-only and runtime-mapping steps still advance through the observation operation. For a waiting scenario run, the same empty-body command can safely ask the evaluator to recheck elapsed time: before every declared transition window and evidence deadline expires it returns HTTP 409 with scenario_observation_required, creates no operation, and leaves the run revision and ETag unchanged; once durable evidence reevaluation reaches a terminal outcome, it atomically persists a reevaluate_graph_clock operation and the completed run. The reevaluate_graph_clock value is the stable operation action recorded for this time-based reevaluation; it does not name another API. This time reevaluation never accepts x-api-key. The command rejects a stale ETag (optimistic concurrency), and replaying the same Idempotency-Key safely returns the original result (idempotency). x-api-key, when required by a selected adapter, is a transient Integration API credential used for that adapter operation only; it is not Workspace API authentication and is never persisted.
Permission: OPERATE. Headers: Idempotency-Key (required), If-Match (required), x-api-key. Success: 200 ScenarioRunCommandResponse.
Stable error codes: invalid_request, precondition_required, etag_mismatch, scenario_run_not_found, scenario_run_terminal, scenario_adapter_dispatch_response_invalid, scenario_adapter_dispatch_unavailable, scenario_adapter_not_ready, scenario_adapter_reply_ambiguous, scenario_adapter_transaction_ambiguous, scenario_binding_changed, scenario_binding_incomplete, scenario_observation_required, scenario_predecessor_fact_not_ready, scenario_predecessor_observation_required, scenario_preparation_unavailable, scenario_target_executor_unavailable, scenario_target_not_adapter, scenario_target_occurrence_unavailable, scenario_target_partner_authority_invalid, scenario_target_step_unavailable, scenario_adapter_dispatch_api_key_correction_required, scenario_adapter_dispatch_retryable, idempotency_key_conflict, scenario_operation_in_progress, scenario_run_operation_limit_exceeded, scenario_run_result_bytes_limit_exceeded, scenario_operation_ownership_lost, integration_api_key_required, integration_api_key_not_allowed, server_error.
```
{}
```
POST /tenant/scenario-runs/{runId}/observations
Attaches one exact tenant-visible ModernEDI transaction to an attachable runtime-mapping or observation-only occurrence. The body identifies persisted transaction metadata; raw X12 is never accepted. The transaction must carry the exact partner-configuration fingerprint frozen into the applied binding; legacy or mismatched transactions are ineligible, while acknowledgments and receipts produced under a different configuration remain pending. Repeating the same slot and transaction with the current ETag and a new Idempotency-Key re-reads trusted transaction detail, refreshes pending mapping or acknowledgment evidence, and reevaluates the graph atomically. Reusing the original key is a pure replay and does not refresh evidence. Adapter-controlled steps reject client attachment. Mapper-derived facts use ordinary X12 Mapper semantics, with dynamic durability limits enforced before SQL persistence: collections contain at most 1000 scalar values; text scalars contain at most 4096 UTF-8 bytes; one canonical typed value contains at most 32768 bytes; and one observation's facts JSON contains at most 262144 bytes. A fact provenance receipt contains at most 4096 bytes. Each evidence document contains at most 8192 bytes, with at most 8 non-fact evidence documents and 524288 bytes of aggregate evidence JSON per observation. Capacity failures use fact_value_limit_exceeded, transaction_observation_capacity_exceeded, transaction_fact_evidence_capacity_exceeded, or transaction_evidence_capacity_exceeded. fact_evaluation_timeout and fact_evaluation_busy_or_limited return HTTP 409 with retryable=true and operationStatus=failed; reload the run if needed, then retry with its current ETag and a fresh Idempotency-Key to re-read trusted transaction evidence.
Permission: OPERATE. Headers: Idempotency-Key (required), If-Match (required). Success: 200 ScenarioRunCommandResponse.
Stable error codes: invalid_request, precondition_required, etag_mismatch, scenario_run_not_found, scenario_run_terminal, observation_step_not_bound, observation_target_controlled, observation_occurrence_out_of_range, scenario_observation_identity_conflict, scenario_checkpoint_conflict, scenario_observation_attempt_expired, transaction_not_found, transaction_messageid_mismatch, transaction_transactionkey_mismatch, transaction_transaction_set_mismatch, transaction_x12_syntax_tree_version_mismatch, transaction_partner_mismatch, transaction_partner_configuration_mismatch, transaction_mapping_mismatch, transaction_timestamp_in_future, transaction_timestamp_invalid, transaction_direction_invalid, transaction_direction_mismatch, transaction_acknowledgment_timestamp_missing, binding_fact_source_missing, binding_route_not_observable, transaction_fact_extraction_failed, fact_evaluation_timeout, fact_evaluation_busy_or_limited, transaction_observation_capacity_exceeded, transaction_fact_evidence_missing, transaction_fact_evidence_inconsistent, transaction_fact_evidence_capacity_exceeded, transaction_evidence_capacity_exceeded, fact_value_limit_exceeded, transaction_observation_unavailable, idempotency_key_conflict, scenario_operation_in_progress, scenario_run_operation_limit_exceeded, scenario_run_result_bytes_limit_exceeded, scenario_operation_ownership_lost, scenario_observation_unavailable, scenario_observation_failed, scenario_observation_completion_failed, scenario_run_revision_changed, scenario_binding_changed, server_error.
```
{
  "stepId": "purchaseOrder",
  "occurrence": 1,
  "messageId": "msg-01K5QED4DP89F67V3MKRK9R5JM",
  "transactionKey": "tx-01K5QED4DP89F67V3MKRK9R5JM"
}
```
GET /tenant/scenario-context/transactions/{messageId}/{transactionKey}
Projects existing run membership and currently attachable occurrences by matching the tenant-visible persisted transaction against the exact frozen partner, direction, X12 release, transaction set, and runtime mapping authority. This read never performs fact extraction or changes a run.
Permission: READ. Headers: none. Success: 200 ScenarioTransactionContext.
Stable error codes: invalid_request, scenario_transaction_not_found, server_error.
GET /tenant/scenario-context/partners/{partnerId}
Shows every active applied binding step that freezes this partner, including non-current activation state, plus currently eligible open occurrences for active scenario runs.
Permission: READ. Headers: none. Success: 200 ScenarioPartnerContext.
Stable error codes: invalid_request, server_error.
GET /tenant/scenario-context/mappings/{mappingId}
Shows every active applied binding step that freezes this exact runtime mapping, including non-current activation state, plus currently eligible open occurrences for active scenario runs.
Permission: READ. Headers: none. Success: 200 ScenarioMappingContext.
Stable error codes: invalid_request, server_error.

Fast locally, authoritative on the server.

JSON Schema catches document shape, closed fields, constants, formats, and operator operands. Server validation additionally resolves references, tenant-owned artifacts, conversation semantics, fact types, and whether the current scenario runtime can execute the definition. Publish and Apply remain fail-closed.