# Model seams

A model seam is a place where a small model may add something to a deterministic answer. There are
six. Each has a deterministic default that needs no network and no weights, a pinned policy for the
day the selected model cannot run, and a plain statement of what a model there may not do.

Nothing here is on by default. An organization gets the default on every seam until one of its
owners enables a model, and a model that has not been enabled never sees the organization's content.

## The table

| Seam | Default | Models | A model may | When the model cannot run |
| --- | --- | --- | --- | --- |
| `forecast` | `seasonal`: the hour-of-week median and MAD profile the anomaly detector already learns | `chronos2`, `toto2` | publish a forecast value with its interval; it never fires a rule | the seasonal series stands, and the answer says `model: unavailable` |
| `anomaly_second_opinion` | `none` | `tspulse` | add an advisory label beside a deterministic verdict; the verdict is returned unchanged | the deterministic verdict stands alone, labelled `secondOpinion: unavailable` |
| `sentiment` | `none` | `roberta_local` | label survey text | no label; the survey shows scores and counts only |
| `embed` | `none` | `local_open_weight` | cluster what fingerprints left over | fingerprints and template mining only; `embeddings: unavailable` |
| `pii_detect` | `regex`: the scrub's own rules and the entropy rule | `presidio_local` | add a finding or a redaction, never remove one | the regex layer stands; `ner: unavailable`, and a name finding is `not_measured`, never "no names found" |
| `injection_classify` | `none`: the deterministic scanner decides | `deberta_injection_v2` | quarantine more strings, never release one | the scanner alone decides; `classifier: unavailable` |

The policies are different on purpose and are pinned one by one in
`api/test/model-seams/unusable-policies.test.ts`. `ProviderRegistry` requires every seam to declare
its own, so a policy is a choice and never an inherited default.

## What a model never does (DNB 1)

A model never decides membership, fires an alert, resolves an issue, pages anyone or signs anything.
Every output above is data: a number with an interval, a label beside a verdict, a finding added to a
set. A forecast reaches a rule only as a stored value with its provenance; the rule's condition is a
deterministic threshold over it.

`pii_detect` and `injection_classify` are **one-way**. Whatever a model returns, the answer a caller
reads is the union of the deterministic layer's findings and the model's, and the more severe of the
two verdicts. A model that says "this is fine" about a string the scanner held changes nothing; a
model that says "quarantine" about a string the scanner passed raises it. This is enforced by a
wrapper the registry puts around every provider on those two seams, so no path to the seam skips it,
and it is proven by a property test over random provider answers.

## Where a model runs

Models run in `bucker-workers`, never in `bucker-api` or `bucker-mcp`, and never on an ingest
request. A process that has not said what it is runs no model. A model that is selected and refused
here is treated like one that cannot run: the seam's policy answers, and the run is recorded as
`refused`. The deterministic defaults and the stand-ins run anywhere.

## Open weights, behind a licence allow-list (DNB 3)

Only unmodified open weights, and only under a licence on the allow-list: Apache-2.0, MIT or
OpenMDW-or-Apache. A deny list (TimesFM 3.0, Moirai, TiRex v1, Timestral, TabPFN-2.5 and
`ibm-research` copies) wins over the allow-list. A provider whose licence is still `?` has not had
its model card read, and cannot be enabled. Today `chronos2`, `toto2` and `tspulse` carry a licence
on the allow-list; `roberta_local`, `local_open_weight`, `presidio_local` and `deberta_injection_v2`
carry `?`.

Every model provider is a contract adapter: an input schema, an output schema, a timeout, a cost
estimate, the weights file it reads and the SHA-256 that file must have. The weights are an
operator asset in the directory named by `MODEL_WEIGHTS_DIR`. If the variable is unset, the file is
missing, its hash is not the pinned one, or no inference runtime is registered, the provider is
unusable and the seam's policy answers. Nothing is ever downloaded.

A provider that would send customer content to a hosted model is unusable until an egress purpose is
registered for it. None of the six does.

## Enabling a model

`POST /orgs/:orgSlug/model-providers` with `{ "seam", "provider" }` enables a model on one seam;
`DELETE /orgs/:orgSlug/model-providers/:seam` switches it off. Both are human-only and need the
organization's `org:admin`, which only an owner holds: an agent, a service principal and a delegated
OAuth client are refused. Each writes one audit row and alerts the organization's owners.
`GET /orgs/:orgSlug/model-providers` shows every seam, its providers with licence and state, and the
last 24 hours of runs. A provider's `ready` is `null` (unknown) when the answering process is not
`bucker-workers`: the api cannot see the workers' weights or runtime, so the run counts are the
evidence there, not a guess.

## Provenance

Every call writes one `ModelRun` row: seam, provider, model id, licence, weights hash, digests of the
input and output, latency and an estimated cost, and a status (`ok`, `unavailable`, `refused` or
`error`). The row holds digests, never content. When a model's output appears in evidence the
evidence also carries a `model_output` claim naming the run; a degraded answer is marked so a
stand-in is never read as a model.
