Binding runtime context

A profile defines terminology. A binding defines where and how that terminology is applied. A snapshot defines the immutable version that runtime consumers should use.

Profile = what the terminology means
Binding = where and how that terminology is applied
Snapshot = which immutable version is safe to serve

Runtime calls should prefer a binding because the binding pins search scope, policy, and snapshot version.

Why profiles are not enough

A profile can tell SkeinRank that k8s maps to kubernetes or that pg may map to postgresql. It cannot fully answer production runtime questions such as:

• Which index or alias should be searched?
• Which text fields should be read?
• Which target field stores enrichment output?
• Which filter or discriminator scopes the documents?
• Which snapshot version is active?
• Which ambiguous alias interpretation is safe in this context?

A binding owns those runtime decisions.

Recommended request shape

Production runtime calls should use binding_id when available:

{
  "binding_id": 42,
  "query": "k8s pg timeout",
  "size": 10
}

The application can map product UI scopes to bindings:

Application scope	SkeinRank binding	Runtime behavior
Infra incidents	infra_incidents_prod	pg can resolve to PostgreSQL.
Docs platform	docs_platform_prod	pg can resolve to page.
Product analytics	product_analytics_prod	pg can resolve to product group.

Common binding patterns

1 profile → 1 index

The simplest path. Create one binding and pin one runtime snapshot for that corpus.

1 profile → many indexes

Create one binding per index because each index may use different fields, rollout state, or snapshot version.

Many profiles → 1 index

Create multiple scoped bindings using a discriminator such as team, doc_type, or workspace_id.

All search

Fan out across multiple bindings and merge results, or add a router layer that selects candidate bindings.

Profile-only mode

Profile-only requests are still useful for preview, tests, local experimentation, dictionary linting, or documentation examples. They should not be the default production integration because they do not encode runtime scope.

Use this rule:

Profile-only mode = preview / development
Binding-aware mode = production runtime

Runtime guarantees

Binding-aware runtime gives operators a stronger guarantee:

same binding + same snapshot + same query = reproducible canonical context

That guarantee is what makes rollback, evidence review, and search regression testing possible.