Skip to content
emergent engineering

cmi5 Conformance Suite Runbook

Intent

Section titled “Intent”

Run conform-ed-backed cmi5 verification lanes against the Emergent system under test, with Emergent owning only the adapter bridge.

These lanes are intentionally separate from bun run validate and are intended for explicit conformance checks.

Current Scope

Section titled “Current Scope”
  • Primary lane logic runs in conform-ed runner images.
  • Emergent provides only an adapter bridge process that maps conform-ed’s cmi5 adapter contract to Emergent workflow APIs.
  • Two supported entry points remain in emergent:
    • test:cmi5:conformance for the conform-ed external lane.
    • test:cmi5:catapult for the conform-ed CATAPULT-style lane.

Prerequisites

Section titled “Prerequisites”
  • Bring up the local Emergent cmi5 stack (postgres, api, content-runtime, lrs) on the expected host ports.
  • Ensure the database schema is migrated before running either lane.
  • Ensure a conform-ed cmi5 runner image is available (default: ghcr.io/conform-ed/cmi5-runner:latest). Emergent does not require a local conform-ed checkout for these lanes; it talks to the published runner image through Podman Compose.

Local Execution

Section titled “Local Execution”

Run the conform-ed external lane against the Emergent adapter bridge:

Terminal window
bun run test:cmi5:conformance

Run the conform-ed CATAPULT-style lane:

Terminal window
bun run test:cmi5:catapult

Forward lane options to the underlying conform-ed entrypoint via --:

Terminal window
bun run test:cmi5:catapult -- --target runtime

Useful environment overrides:

  • CONFORM_ED_CMI5_RUNNER_IMAGE to pin runner image tags.
  • EMERGENT_CMI5_ADAPTER_BRIDGE_PORT to change bridge port (default 4501).
  • EMERGENT_CMI5_ADAPTER_BRIDGE_TOKEN to set adapter auth token.

If you are using this repository without a sibling conform-ed workspace, set CONFORM_ED_CMI5_RUNNER_IMAGE to the published tag or digest you want to test and run the same commands.

Environment Model

Section titled “Environment Model”

The emergent adapter bridge expects these upstream origins by default:

  • API host port: http://127.0.0.1:4301
  • H5P runtime host port: http://127.0.0.1:4312
  • LRS host port: http://127.0.0.1:4311

Adjust bridge environment variables only when your stack uses non-default origins.

Next Expansion Steps

Section titled “Next Expansion Steps”
  1. Move remaining shared lane orchestration and threshold validation into conform-ed runner scripts.
  2. Collapse emergent wrapper scripts into a single thin launcher with explicit lane selection.
  3. Add adapter-bridge focused tests in emergent, and keep generic cmi5 matrix coverage in conform-ed.