For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Feature flags

What it does

The packages/flags cartridge³⁶ evaluates typed flags. A flag declares its name, schema¹⁷, default, owner, and removal date.¶

Handlers request the Flags service¹⁶ from core. The Config adapter¹⁹ reads deployment configuration. The memory adapter supplies rules and writable values for tests.¶

The KV adapter owns its namespace through Alchemy. Missing KV values use Config values or declared defaults.¶

• listFlags lists names, owners, and removal dates.¶
• getFlag evaluates one flag for an optional subject.¶
• Allow-lists select a value for named subjects.¶
• Percentage rules use a stable hash of the flag name and subject.¶
• The first matching rule wins. Missing subjects use the default.¶

EVENTS_ENABLED defaults to false and stays deploy-time Config. Live KV writes cannot change this flag.¶

EVENTS_IDENTITY_MODE defaults to daily. The Worker reads its live value for each captured request. Config keeps the existing environment keys and boolean spellings. An empty KV namespace preserves Config behavior.¶

Invalid Config stops initialization. A failed KV read returns a typed error with its configured fallback recorded.¶

Previews use Config and declare no flags namespace. The production Worker and content backend read KV.¶

Alchemy still selects analytics resources during deployment. See Analytics¹⁸ for capture and identity behavior.¶

The standard

• Flag values pass their declared schemas.¶
• Every declaration names an owner and a removeBy date.¶
• Lint rejects declarations without a literal removal date.¶
• The flags build rejects expired registered events flags with a typed repair message.¶
• Each subject keeps its rollout bucket when the rollout percentage changes.¶
• The lifecycle permits declared → rollingOut → on → removed.¶
• Declared Effect¹⁷ actors record lifecycle transitions. Removed flags stay removed.¶
• Each capability²¹ shares its contract²¹ across surfaces. JSON encoding is required for getFlag.¶

setFlag is an approval-gated capability on the CLI. The CLI accepts --yes or asks for interactive approval. Its default composition has no live writer and returns a named error.¶

The CLI records local-cli as a channel label. Its caller has no authenticated person identity.¶

The public Worker, RPC readers, and read-only sandbox expose no flag writes. A live operator write surface²³ and listFlagChanges remain future work.¶

Each available-store attempt records its caller, flag, observed old value, requested value, time, and outcome. The journal stores an immutable Pending key before the approval gate. A separate completion key records success, denial, failure, or interruption. Both keys share an attempt id.¶

Missing completion means Pending with an unknown result. A failed completion write returns a typed error; the flag may have changed. Audit storage failures block only writes. Config and default journals use composition-local memory.¶

KV changes may take 60 seconds or more to reach another location. The observed old value may be stale. KV cannot commit a flag value and its audit outcome in one transaction. Unique journal keys avoid its one-write-per-second limit on each key.¶

Writes to the same flag can still hit that limit and return a typed error.¶

The lifecycle journal is scoped memory, with no durable state between processes.¶

How to check

1. Run pnpm --filter @rat-stack/flags test for rollout properties, generated write histories, audit failures, and lifecycle histories.¶
2. Run pnpm --filter @rat-stack/core exec vitest run test/patterns-rule.test.ts for the removal-date fence³⁹.¶
3. Run pnpm turbo run check test build --concurrency=1 for the full gate.¶
4. Inspect the deployment plan. Adding live flags declares one KV namespace and updates its Worker bindings²³.¶

To remove the cartridge³⁶:¶

1. Replace apps/site/src/flags.ts with core imports.¶
2. Export flagsLayer = Flags.defaults(eventFlags) and liveFlagsLayer = flagsLayer.¶
3. Remove the package dependency and its directory.¶

Callers keep their typed defaults. The CLI retains its named read-only failure.¶

Last changed 2026-10-11 in 11edf67. Source on GitHub. Change log.