Skip to main content

Registering a feature and its probe

A feature's state in Vagaris is derived, never stored. There is no status field to set: the answer is computed from what has been observed about the feature, and the strongest thing that can be observed is a probe assertion — the result of the server running a registered probe against the real surface.

vagaris feature register is how a feature gets that probe.

Why a claim is not enough​

You can tell Vagaris what you believe with feature claims. A claim is recorded honestly as a claim: it enters at the last rung of the precedence ladder, and its confidence is capped below a probe assertion's. That is deliberate. A verification system whose subject can write its own verification is a formality, so no executor may write an assertion — not a seat, not CI, not an operator's script. Only the server's probe runner writes one, and only by observing.

Registering a probe is therefore not a way to assert something. It is a way to hand the server a question it can ask repeatedly on your behalf.

The positive control is not optional​

This is the single most load-bearing field in a probe, and the command refuses to store one without it.

A probe that comes back "not present" is produced identically by two completely different facts: the feature is genuinely absent, or the instrument could never have found it. An unauthenticated body greps to nothing. A wrong host 404s. A dead runner times out. Without a control asserted to pass in the same breath, one broken instrument writes ABSENT across the estate, and every one of those rows then reads as evidence.

So the runner executes the control first. If the control fails, it records a finding about the instrument and no assertion about the feature at all — because "we could not observe" is a different fact from "it is not there", and collapsing them is exactly what the control exists to prevent.

Registering​

vagaris feature register \
  --catalogue-id VOI-021 \
  --title "Provider/model/voice configuration" \
  --source "the catalogue row this came from" \
  --probe-url https://app.example.com/v1/settings/voice \
  --probe-expect-status 401 \
  --probe-control-url https://app.example.com/api/session \
  --probe-control-expect-status 200 \
  --probe-on-pass API_ONLY \
  --probe-on-fail ABSENT

That example is worth reading twice, because the expectation is a 401 rather than a 200.

A protected endpoint answering 401 is evidence the endpoint exists. A 404 would be evidence it does not. The probe is not testing whether you can authenticate — it is discriminating deployed from not deployed, and the 401 is the discriminating answer. The control (/api/session → 200) proves the host was reachable and the instrument worked, so the 401 means what it appears to mean.

Where a status alone cannot discriminate — the classic case being a 200 that renders an error page — add --probe-expect-body-regex (and --probe-control-expect-body-regex for the control).

For the whole probe as one object, including anything the flags do not expose:

vagaris feature register --catalogue-id VOI-021 --title … --source … --probe-file ./probe.json

--probe-file and the --probe-* flags are mutually exclusive. A file plus overrides would be two authorities for one object, and the loser would be silent.

Re-registering​

Re-registering the same catalogue id is the same feature, not a duplicate, and the route merges rather than replaces — but the merge covers the ops fields only, and it is worth knowing exactly which ones.

Safe to omit (absent means unchanged): probe, vendor_org_id, visibility, source_hash, and the lifecycle — a second register does not wipe a probe it does not mention and does not downgrade a ratified feature back to candidate.

Always sent, so always overwritten: --title and --source are required by the contract, and confidence is a column rather than an ops field, so it is written on every register whether or not you named it. Omitting --confidence therefore sets it to the default 0.6 — including over a higher stored value. If the feature already carries a confidence you care about, pass it explicitly.

So when you are only attaching a probe to a feature that already exists, read it first and pass back what it carries: vagaris feature show <id> prints the title, source and confidence.

Running it​

vagaris feature verify <id>       # the server runs the probe, control first
vagaris feature evidence <id>     # what has been observed, claimed and found
vagaris feature recompute <id> --target <maturity>

verify is refused for agent actors: an agent may register a feature, and a registered feature carries a probe, so the URL the server would later fetch can be an agent's choice. Both the probe URL and the control URL are checked against the fleet SSRF policy before any request, and a rejection takes the instrument-finding path rather than becoming an assertion — "we refused to look" is a statement about the runner, exactly as "we could not reach it" is, and neither is a state of the feature.

Registering without a probe​

Perfectly legitimate, and most catalogue rows have none. Omit every --probe-* flag and the feature is registered with its edges and provenance and no probe. Absence here is a choice, not an omission — the command does not invent one.