# Context Bindings

Status: first implementation slice
Date: 2026-06-19

`catalog/context-bindings.json` maps stable ontology concepts to real source-system identifiers.

It is intentionally separate from `catalog/entities.json`:

- `entities.json` says what concepts exist: `ops.card`, `engine.workflow_l1`, `engine.workflow_l2`.
- `context-bindings.json` says which concrete OPS card/project or Engine workflow/node is currently known.

## Current Seed Contexts

Active contexts currently seeded:

- OPS project `NDC PLATFORM`
- OPS card `Антология / Ontology Core`

These are real Tasker/OPS identifiers and are safe to use as the first resolver fixture.

## Current Cross-Surface Bindings

No active OPS <-> ENGINE binding is stored yet.

This is deliberate. The resolver should say:

```text
matched OPS context: yes
selected route: OPS -> ENGINE
missing binding: binding_type.ops_card_to_engine_workflow
```

That is better than pretending an Engine workflow is linked when it is not.

## Next Binding To Add

The first real productive binding should look like this, once the target Engine workflow/node is known:

```json
{
  "id": "binding.ops.<card_or_project>.engine.<workflow>",
  "typeId": "binding_type.ops_card_to_engine_workflow",
  "status": "active",
  "fromContextId": "context.ops.nodedc.ndc_platform.ontology_core_card",
  "toContextId": "context.engine.<workflow_context_id>",
  "summary": "Links OPS card/project context to the Engine workflow context."
}
```

Use the registry CLI instead of hand-editing when adding real contexts/bindings:

```text
npm run registry -- add-context --input-json examples/engine-context.example.json --dry-run
npm run registry -- add-binding --input-json examples/ops-engine-binding.example.json --dry-run
npm run registry -- import-engine-context --input-json examples/engine-workflow-manifest.example.json --dry-run
```

Remove `--dry-run` only after replacing example refs with real source-system identifiers.

Preferred workflow for ENGINE is `import-engine-context`: it generates the context id and optional OPS binding from a manifest, then validates the whole registry.

The corresponding Engine context should include at least:

```json
{
  "surface": "engine",
  "entityId": "engine.workflow_l1",
  "sourceSystem": "nodedc-engine",
  "refs": {
    "workflow_id": "...",
    "node_id": "..."
  }
}
```

If L2 runtime is known, add:

```json
{
  "runtime_workflow_id": "...",
  "runtime_instance_id": "..."
}
```

## Rules

- Do not store secrets, tokens, env values, runtime payloads, logs, dumps, or database rows here.
- Store stable identifiers only.
- Prefer explicit context IDs over free-form names.
- Keep planned bindings as `planned`; use `active` only when the target source-system refs are confirmed.