Profiles, bindings, and snapshots

SkeinRank becomes easier to understand when the core runtime objects are separated.

Profile = what the terminology means
Binding = where and how that terminology is applied
Snapshot = which immutable version is safe for runtime search

These three concepts keep editing, rollout, and search behavior from being mixed together.

Quick definitions

Profile

A terminology profile is a controlled dictionary: canonical values, aliases, slots, stop lists, and review rules for one domain.

DictionaryEditable

Binding

A binding connects one profile to one Elasticsearch index, alias, or document scope. It is the main runtime search context.

Runtime contextSearch scope

Snapshot

A snapshot is the immutable profile version pinned to a binding after enrichment or rollout. Runtime search should use this stable version.

ImmutableAuditable

Job

An enrichment job is the operation that applies a binding to documents, performs dry-runs or writes, and can activate runtime snapshot state.

Dry-runRollout

Why binding is the production context

A profile alone says which dictionary to use. It does not say:

• which index or alias to search;
• which fields contain source text;
• which target field stores enrichment output;
• which discriminator/filter scopes documents;
• which snapshot is currently safe for runtime;
• which alias or rollout state is active.

A binding owns those decisions.

{
  "binding_id": 42,
  "profile": "infra_incidents",
  "index": "company_docs",
  "text_fields": ["title", "body"],
  "target_field": "skeinrank.attributes",
  "runtime_snapshot": "infra_incidents@2026-05-runtime"
}

Common mapping patterns

Pattern	How to model it	Why
1 profile → 1 index	Create one binding.	The simplest path for a single domain corpus.
1 profile → many indexes	Create one binding per index.	Each index can have its own fields, jobs, and snapshot version.
Many profiles → 1 index	Create multiple bindings to the same index and use a discriminator such as team, doc_type, or workspace_id.	One binding should stay atomic: one profile, one search context, one runtime snapshot.

Many profiles on one index

If one Elasticsearch index contains multiple domains, do not attach several profiles to the same binding. Instead, create several bindings that share the index.

binding #1: profile infra   → index company_docs → team=infra
binding #2: profile legal   → index company_docs → team=legal
binding #3: profile support → index company_docs → team=support

This keeps enrichment, rollback, snapshot audit, and runtime canonicalization predictable.

Runtime search rule

Production search should prefer a binding-aware request:

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

The binding tells SkeinRank which runtime snapshot and search scope to use. A profile-only request can still be useful for preview or local experimentation, but it is not enough to represent production search context.

Recommended operator flow

1. Create profileAdd canonical terms, aliases, slots, and guardrails.

2. Create bindingConnect one profile to one index or scoped document collection.

3. Dry-runPreview what enrichment would write without changing documents.

4. EnrichRun a job and activate or update runtime snapshot state.

5. Verify searchUse Search Playground to inspect canonical query, aliases, and hits.