# Feature flags

Bucker keeps its own copy of the feature flags your connected vendors hold, so you and your agents read one list across vendors, with the vendor's version beside each flag and the evidence of what the flag did beside it. This page covers the mirror and what reads it. It is read-only: nothing here changes a flag at a vendor.

## What is mirrored

A flag vendor is connected through [Connections](connections.md) with a read-only key. The first vendor is PostHog. For every flag Bucker keeps:

| Kept | Meaning |
| --- | --- |
| Key and vendor | The flag's key and which vendor holds it. |
| State per environment | `on`, `off` or `unknown`, normalised across vendors. PostHog has one environment per project, which Bucker names `default`. |
| Vendor version | The vendor's own version token. A vendor that states none gets a digest of the flag's content, so a change still reads as a new version. |
| Rule summary | One shape for every vendor: each rule's kind (`rollout`, `attribute`, `segment`), the attributes and operators it tests, the segment as `id@version`, the percentage and the variant it serves. |
| Variants | Each variant's key and share. |
| Payload digests | A digest per payload. The payload itself is never read into storage. |
| Version history | Every version Bucker has seen, kept 400 days (the current one is kept however old it is), so a vendor that cannot rebuild history still has one here. |

**Targeting values stay out.** A condition that lists user keys, email addresses, identifiers or more than ten values keeps a count and keyed digests, never the values. A short list for an attribute that names no person (`country in DE, FR`, `plan = team`) is kept, because "who is in this rollout" is the question a reader asks. A value that looks like a credential is digested too. The digest key is derived from the deployment's secret, so a stored digest cannot be checked against a guessed address offline; two versions of one list still compare equal or different.

**Everything a vendor wrote is untrusted text**: flag keys, variant keys, attribute names, values, segment references and version tokens. Bucker bounds and cleans it, an MCP response declares every such field untrusted, and the dashboard renders it as text, never as markup or a link.

## When it is read

- **A 5-minute poll** reads every active, project-scoped flag connection through its read adapter, within the vendor's rate budget (PostHog: 480 requests a minute). A pass over an unchanged vendor writes nothing but a timestamp.
- **A flip webhook** for a flag re-reads that flag in the same request. It never fails or holds the delivery: a refresh that cannot run is the poll's to catch, and refreshes are limited to one per connection every ten seconds.
- **A vendor that says "slow down", is down or fails mid-listing** is the answer, not an error: Bucker writes what it read, archives nothing and marks nothing, and the next pass continues.
- **At most 10,000 flags are mirrored per connection.** When a vendor holds more, the list says so (`limits.atCap`).

The mirror is behind the `pillar.flag_mirror.enabled` operator switch and is **off until an operator turns it on**. With it off nothing is read and nothing is written.

A connection must name a project. An organization-wide connection cannot say which Bucker project a vendor project belongs to, so it is not mirrored.

## Ghosts, orphans and stale flags

| Mark | Meaning |
| --- | --- |
| Ghost | A key evaluated in your telemetry that no connected vendor holds (a flag deleted upstream but still in code). |
| Orphan | A vendor flag with no evaluation in the last 30 days. |
| Stale | Derived when read: a declared expiry that passed, an orphan, a flag serving everyone, or a flag that can serve no one. |

Both marks are **lower bounds**. Only evaluations that rode on an error event are recorded today, so "never evaluated" means "never seen on an error". No flag is called an orphan when no evaluation was observed at all, and no key is called a ghost while an active flag connection exists that Bucker has not read (an organization-wide one, or one not yet synced). Ghost rows are capped at 1,000 per project: the key in an event comes from a public DSN, so anyone can report one.

## Reading it

**Dashboard.** `/org/<org>/<project>/flags` lists the flags with state, vendor, marks, staleness and when each was last read; opening a flag shows its rules, variants, segments, payload digests, versions and the issues that evaluated it. Filters live in the URL, so a link can carry them, and the Ask panel compiles "stale flags in production" or "flags changed in the last hour" to those filters and shows them before anything runs (a closed phrase table, no model).

**REST.** `GET /orgs/:org/projects/:project/flags` (filters: `provider`, `environment`, `state`, `purpose`, `owner`, `stale`, `debt`, `mark`, `changeStatus`, `changedSince`; `limit`, `cursor`) and `GET /orgs/:org/projects/:project/flags/:key` (`provider`, `include`, `versionsCursor`). Both need `project:read`.

`environment` accepts a name, or `production` / `non_production` as the project marked its environments (an environment nobody described counts as production).

**MCP.** `flags_list` and `flag_get`, in the `flags` toolset, need `project:read`. `flags_list` rows carry `latestChange` (the newest governed change's status, act and class) and filter by `changeStatus`. `flags_list` is bounded to about 3,000 tokens with a cursor; `flag_get` to about 2,500, cut in steps (fewer rules and versions, then counts only) and saying when it cut. Both state their evidence: how fresh the copy is, what was scanned, and why an empty answer is empty.

`flag_get` takes `include` blocks:

| Block | Today |
| --- | --- |
| `evaluations` | Variant, error, session and span evidence per variant. Needs `event:read`; without it the block is withheld and says why. The read is recorded in the query log. |
| `changes` | The flag's governed changes, newest first: the act, the class, the status, the vendor versions, when each was filed, applied or verified. Never a rule, a condition or a payload. |
| `receipts`, `readiness`, `lifecycle`, `environments`, `payload`, `import`, `exposures` | `not_available` until the card that builds each ships. Never an empty object that reads as "none configured". |

Filters whose data has not been built yet (`finding`, `readiness`, `drift`, `receiptOutcome`, `importRun`) match nothing and are named in `unavailableFilters`.

## Changing a flag at the vendor

A person (or an approved plan) can change a flag at PostHog or LaunchDarkly. Bucker never changes a flag with the credential it reads with: a **write credential** is a second, separate key on the same connection (Settings, Connections, add an `apply` credential), entered by a person with the connections permission. A connection with only a read credential cannot change anything, and the answer says the `apply` credential is missing.

What it does, in this order:

1. **Applies exactly what was approved.** The plan on the change is what is sent; a plan that differs from the stored one is refused.
2. **Re-reads the vendor before writing.** If the flag's version (for LaunchDarkly, the environment's version) has moved since the plan was made, or the audience (segment) the plan was pinned to has been edited, the change ends **stale** and nothing is sent. PostHog writes carry the flag's `version` as the vendor's own precondition. LaunchDarkly has no atomic precondition on a semantic patch, so its window is the instant between the re-read and the write.
3. **Resolves "disable" safely.** The vendor is switched off only when the value it serves while off *is* the safe variant a person confirmed. Otherwise Bucker adds a rule in front that serves the safe variant to everyone, because off would serve something nobody called safe. A flag with no confirmed safe variant is refused.
4. **Files into the vendor's own queue where it has one.** A PostHog write on a protected flag answers "approval required" with a change request; a LaunchDarkly plan that names the queue files an approval request. Bucker records the change as **filed** with the vendor's request id, then follows it every five minutes until the vendor says **applied**, **rejected**, **expired** or **stale**. It never approves, applies or re-files for the vendor, and a request still pending after 30 days is no longer followed.
5. **Records and audits.** `flag.change.filed`, `flag.change.applied` and `flag.change.reverted` carry the vendor request id and a checksum of what was sent and what undoes it, never a rule or a targeting value.

PostHog: enable, disable, a release condition's rollout percentage, a rule serving one variant to everyone, and scheduled enables and disables. A scheduled "serve one variant to everyone" is refused: PostHog adds a scheduled condition after the existing ones, and the first matching condition wins, so it would not reach everyone. LaunchDarkly: the same immediate changes, as semantic patch instructions per environment (no scheduled changes). On LaunchDarkly a rule cannot outrank individually targeted contexts, which the vendor evaluates before any rule, so a "serve the safe variant to everyone" rule does not reach a context targeted individually; the flag's own off switch does. The adapters hold no endpoint that deletes, creates a flag, mints a key, reads billing or reviews an approval.

The mitigation kill switch and variant pin reach LaunchDarkly through the same code (the provider named `launchdarkly`), keep their expiry and automatic revert, and are stopped by the same `flags.write` switch as every other agent flag change. A pin narrowed to one segment is refused rather than widened to everyone. An agent's request is refused, before any vendor call, while that surface is switched off. The `openfeature-flagd` provider writes nothing: flagd has no management API, so it emits a flagd definition, with its inverse and expiry, for you to load.

Not built yet: creating a flag at the vendor (a governed `flags_create` declares the flag in Bucker only), archiving a vendor's flag, applying a rules, variants, payload or segment change, Unleash, Statsig, GrowthBook and Datadog Flags.

## Changing a flag through Bucker (governed)

An agent or a person can propose a change to a flag, and Bucker derives what the change *is* from the difference between the flag's state and the state it would be in, never from a word in the request. Nothing the request carries can name how many subjects it reaches: Bucker **measures** the audience, from its own exposure counts or from the environment's session count and the rollout percentages, and shows it as a fraction with its basis (`bucker_exposure:24h`, `bucker_sessions:24h`). When it cannot measure, the audience is shown as **not measured**, and an unmeasured audience counts as wide.

| Change | Act | Class | What else |
| --- | --- | --- | --- |
| Serve every subject the confirmed safe variant | `flag.disable` | Sensitive, always asks | 120 minutes by default, 12 hours at most; approved under `deploy_hotfix` |
| Lower a rollout percentage | `flag.narrow` | Sensitive in production; the table says Elevated in an environment a person marked non-production, but the registry's floor for the act keeps it Sensitive | Refused on a flag with an experiment (running, or imported and not archived); 120 minutes by default |
| Raise a rollout, turn a flag on, serve one variant to everyone | `flag.widen` | Elevated outside production in the table (the registry's floor is Sensitive), Sensitive in production with an ask for every step, **Critical and denied by default at 100 % of production subjects** | 24 hours, then it narrows itself back; above 5 % of measured subjects (or any unmeasured audience) the flag's owner, the owner team or an organization admin must be among the approvers |
| Rules, variants, payload, holdout, ramp | `flag.update` | Elevated, Sensitive in production | Classified and previewed here, **not applied** by Bucker |
| Owner, purpose, expiry, review date, safe variant | `flag_lifecycle.update` | Derived from the diff: Elevated when it fills a missing field, moves a date earlier or withdraws a confirmation; **Sensitive** when it names, changes or confirms the safe variant, moves a date later or clears it, changes or clears the owner, or sets purpose `ops` or `permission` | See [Lifecycle and flag debt](#lifecycle-and-flag-debt): only a person's decision confirms a safe variant |
| Declare a new flag | `flag.create` | Elevated for a key no app evaluated through that vendor in 30 days, Sensitive otherwise | Off in every environment; at most 20 per caller, project and day. Creating it *at the vendor* is not built: the flag is a declaration the mirror adopts when the vendor has the key |
| Edit a segment | `segment.update` | The widest class of the live flags it feeds; Critical when two or more live production flags share it | Classified and previewed, **not applied** |

**Production is a human's marker.** An environment the mirror has seen and nobody has marked counts as production. Only an organization **owner** (the holder of `org:admin`; an ADMIN member is refused) can mark one non-production (`PUT /orgs/:org/projects/:project/flags/environments`, or the card on the flags page); an agent, a service and an OAuth client cannot, and no tool exists for it.

**The chain.** Every change is previewed first (`flag_change_preview`, valid 15 minutes), then asked: a person's yes is bound to the plan's digest and to the vendor version it was made against. A flag moved by anyone, a person at the vendor included, between the yes and the apply is never changed: the apply ends `TARGET_CHANGED`, and the provider re-reads the vendor and ends `STALE` if it moved since Bucker last saw it. A freeze that denies changes stops `flag.widen` and `flag.update` and never `flag.narrow` or `flag.disable`; switching off the `flags.write` surface stops an agent's change of every kind. A change that has been applied carries its stored before-state: `operation_revert` applies it (a widening asks again), and the window's end asks rather than restoring by itself. A narrowing is restored only when its trigger has cleared (the linked issue resolved in a release, or, for a partial narrowing, the verifier calling the cohort healthy); otherwise the restore is **held**, the reason is recorded and the owners are told. Verification watches the project's error count for 60 minutes after the change.

**REST.** `POST .../flags/preview` (what a change would be; a read, and for a caller who may propose, the planned operation a write cites), `POST .../flags/changes` (the governed write: `202` with a decision path when it asks; the freeze and the `flags.write` switch are judged for the act the change derives, so a freeze refuses a person's widening at this door and never anyone's disable or narrowing), `GET` and `PUT .../flags/environments`. **MCP.** `flags_update`, `flags_create` (both held until the OAuth security review: `flags:write` is outside the live token ceiling) and `flag_change_preview` (`project:read`).

## Lifecycle and flag debt

Every flag can carry an **owner**, a **purpose**, an **expiry** (or a review date) and a **safe variant**, so that staleness is a deadline someone declared and not a guess from silence. Mirrored flags get their owner defaulted (the project's ownership rules, then CODEOWNERS, then the connection's creator) and a person is expected to declare the rest within 14 days of the flag's first sighting; the flag's lifecycle block says what is still missing and whether that window has passed.

| Purpose | Ends | Safe variant |
| --- | --- | --- |
| `release` | 30 days after it reaches everyone | off, for a boolean flag |
| `experiment` | the experiment's end plus 14 days | off, for a boolean flag |
| `ops` | reviewed every 180 days, never exempt | required |
| `permission` | reviewed every 365 days | required |
| `remote_config` | reviewed every 365 days | not asked |
| `migration` | 60 days after it was declared | not asked |

When no date was declared, the purpose's default period (from the day the lifecycle was declared) is the deadline; a declared date outranks it.

**The safe variant is a claim a person confirms.** A defaulted or agent-written one is `unconfirmed` and counts as **absent**: `flag.disable` is refused for want of a confirmed variant, and nothing may narrow the flag toward it. Setting or confirming one is always Sensitive: the decision a person makes (their own request on the flags page, where the organization lets a person's request stand; otherwise the approval they decide) is what confirms it, and an agent's request that policy allowed confirms nothing, and neither does a request made through MCP, an OAuth client or a personal access token, whoever's credential it is. The flags page has the one click that asks for the confirmation.

**The rule set `flag-staleness/1`** (registered as the `flag_debt` detector, in shadow). Each rule answers `hit`, `clear` or `not_checked`, with its reason; `not_checked` is never `clear`.

| Rule | Hit when |
| --- | --- |
| `expired` | a declared expiry or review date has passed, or the purpose's default period has |
| `fully_rolled` | one variant serves every subject in **every** production environment, and has for 30 days (a 50/50 split is two variants) |
| `zero` | 0 % everywhere for 30 days |
| `dormant` | no exposure for 30 days; `not_checked` until the project's exposure coverage has been recording for 30 days and still is |
| `unchanged` | no new version for 60 days at 100 % or 0 % |
| `orphaned` | the declared owner is no longer a member of the organization |
| `ghost` | evaluated in telemetry and present in no connected vendor |

**Debt.** A hit on `expired`, `fully_rolled`, `zero`, `dormant` or `orphaned` opens one debt per flag and rule (except that a flag whose purpose is `ops`, `permission` or `remote_config` owes nothing for `fully_rolled` or `zero`, its normal state: it owes its review date instead) with an owner (the declared owner, else the defaulted one, else an organization owner; never someone who left) and a due date 14 days out. The flags scheduler sweeps hourly: OPEN becomes OVERDUE on the due date, and an overdue debt raises an ordinary issue, `FlagDebtOverdue`, fingerprinted on the flag key and assigned to the owner, again no more than every 24 hours. A debt clears when its rule reads clear (never on `not_checked`) or the flag is removed. Only a person with project `admin` writes a debt off (`POST .../flags/debt/:id/write-off`, with a reason of at least 20 characters): no tool, no agent and no OAuth client can, and the sweep never re-opens a rule that was written off. The digest lists each owner's overdue flag debt.

**Reading it.** `flags_list` and `GET .../flags` filter `stale`, `debt`, `purpose` and `owner` and show the declared expiry, whether the safe variant is confirmed and when a debt is due; `flag_get` with `include: [lifecycle]` (also `GET .../flags/:key?include=lifecycle`) adds the declared lifecycle with its gaps, every rule's verdict and the flag's debts. **REST.** `PATCH .../flags/:key/lifecycle` is a person's door, for their own signed-in session only (no agent, OAuth client, personal access token or org token; an agent edits a lifecycle through `flags_update`); it answers `202` with a decision path when the class asks.

## What it does not do

It does not call a vendor from a read, or read a person's data. A copy is as old as its `lastSyncedAt`: it is never presented as live. Changing a flag is a governed act described above; reading never changes one.
