@davidlee49/launchgate 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,407 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# launchgate
+
+Hide work in progress from the public while you keep seeing it. Kill a shipped
+feature without a redeploy. No platform, no service, no database required.
+
+Design of record: [adr/0001-launch-gate-design.md](adr/0001-launch-gate-design.md).
+
+```ts
+import { defineFlags, createResolver, envOverride, cookieOverride, envDefault } from "@davidlee49/launchgate";
+
+export const flags = defineFlags({
+  newPricingPage: {
+    fallback: false,
+    description: "Rebuilt pricing page — hidden until launch",
+    overridable: true,
+    byEnv: { development: true },
+  },
+});
+
+export const gate = createResolver({
+  flags,
+  sources: [
+    envOverride(),                                  // 1. kill switch
+    cookieOverride({ secret: process.env.FLAG_SECRET! }), // 2. you, on the live site
+    envDefault({ env: process.env.NODE_ENV! }),     // 4. per-environment default
+  ],
+  onError: (error, { flag, source }) => console.error("launchgate", flag, source, error),
+});
+
+if (await gate.resolve("newPricingPage", { cookie })) { /* … */ }
+```
+
+## How resolution works
+
+An **ordered list of sources**; each answers with a value or `undefined`
+(*undecided — ask the next one*); the first definite answer wins. The flag's
+`fallback` is terminal, so it can't be forgotten.
+
+| # | Source | Purpose |
+| --- | --- | --- |
+| 0 | `retired` | Not a source. A retired flag answers with its recorded disposition and the chain never starts. |
+| 1 | `envOverride()` | `FLAG_NEW_PRICING_PAGE=off`. The kill switch. |
+| 2 | `cookieOverride({ secret })` | Signed per-visitor token — how you see hidden work in production. |
+| 3 | *yours* | Allowlist, grant, opt-in, entitlement. Usually a database read. |
+| 4 | `envDefault({ env })` | The registry's `byEnv` value. Preview deployments are just a different `env`. |
+| — | `fallback` | Terminal, always present. |
+
+`false` is a decision. `undefined` is not. That three-valued fall-through is the
+whole mechanic — and there is no traversal: no flag ever consults another flag.
+
+### Two invariants
+
+- **`envOverride` sits above `cookieOverride`.** A flag forced on by a cookie
+  must not survive the attempt to kill it.
+- **`cookieOverride` honours only `overridable: true` flags.** A visitor must
+  never force a flag with real consequences.
+
+### Failure is per flag, not global
+
+Every source call is wrapped. A source that throws **aborts to that flag's
+`fallback`** and reports through `onError` — it does not fall through, so there
+is exactly one degraded answer per flag and it's declared next to the flag.
+
+That value is per flag because polarity differs: a WIP gate's safe state is
+`false`, but a kill switch on a year-old feature's safe state is `true` — failing
+*that* one closed would take down working functionality because a database
+blipped.
+
+## Retiring a flag
+
+A release toggle is temporary by definition, and so is the feature behind it
+eventually. `retired` is the terminal state of both:
+
+```ts
+collections: {
+  fallback: true,
+  description: "Collections — retired 2026-08-29, code awaiting deletion",
+  retired: { since: "2026-08-29", value: false },
+},
+```
+
+It resolves to `value` and **consults no source at all** — not `envOverride`,
+which outranks everything else. That is the point rather than an optimisation: a
+retirement is a decision someone committed to git, so the only way to reverse it
+is to revert the commit. A forgotten `FLAG_COLLECTIONS=on` secret or an override
+cookie an engineer is still holding must not be able to reopen it, or the
+registry stops describing what the system actually does.
+
+Note `value` is *not* `fallback`. `fallback` is where a **failure** lands; a
+retirement isn't a failure, and a feature whose safe-on-failure state is `true`
+still retires to `false`. Declaring it separately is also the disposition record
+Unleash makes you supply when completing a flag — the cleanup PR needs to know
+which branch of the code survives, and `value: "v1"` on a dynamic-config flag
+says exactly that.
+
+**Keep the entry.** Retirement archives, it doesn't delete — Unleash's rule, for
+Unleash's reason: while the key is in the registry it cannot be reused by a new
+feature (a duplicate key is a type error), so a stale override can never attach
+to something it was never about. Delete the entry *last*, once the components,
+the routes, and the API handlers are gone.
+
+### The clock
+
+```ts
+const { problems, warnings } = auditRegistry(flags, { today, retiredAfterDays: 40 });
+```
+
+Retired code that nobody deletes is the same debt as a stale release flag, seen
+from the other end, so it gets the same 40-day budget. `auditRegistry` audits
+only what the library owns — the retirement shape and its age. Your own
+lifecycle vocabulary is yours to check; merge the two reports and print them
+together in one build step.
+
+This is deliberately a *build* step. LaunchDarkly ships `find-code-refs` to
+crawl a customer's repository, because a SaaS control plane can't see the code
+and can only warn on a dashboard. A registry that lives in the repo doesn't need
+the scanner: it can fail the build instead.
+
+## Flags aren't only booleans
+
+```ts
+renderPipeline: {
+  fallback: "v1" as "v1" | "v2",
+  description: "Which render pipeline a submitted job uses",
+}
+```
+
+`FLAG_RENDER_PIPELINE=v2` and cookie overrides carry the value. Booleans are the
+common case, not the only one.
+
+> **Typing note.** `fallback: false` is widened back to `boolean` for you.
+> Strings and numbers keep what you declare, which is why the `as "v1" | "v2"`
+> above gives you a checked union.
+
+## Custom sources
+
+A source is `{ name, decide(flag, ctx) }`. Return a value to decide, `undefined`
+to pass:
+
+```ts
+const orgGrant: Source = {
+  name: "orgGrant",
+  async decide({ key }, ctx) {
+    if (!ctx.targetingKey) return undefined;
+    const row = await db.grantFor(ctx.targetingKey, key);
+    return row?.enabled;         // undefined when there's no row — undecided
+  },
+};
+```
+
+Conjunctions ("entitled **and** opted in") are a *requirement* source: return the
+off-value, or `undefined` to stay out of the way. The chain stays first-wins.
+
+## Gating routes
+
+Flags answer "is this on". `createRouteGate` answers the question a web app
+actually asks — **"may this path be served"** — from two lists you supply:
+
+```ts
+const gate = createRouteGate({
+  resolver: launch,
+  routes: { workflows: ["/workflows"], network: ["/network", "/api/network"] },
+  allow:   ["/", "/assets", "/api/assets"],   // the launched surface
+  unlisted: "deny",
+});
+
+await gate.isPermitted("/workflows", { cookie });   // middleware
+await gate.revealedPrefixes({ cookie });            // to filter nav server-side
+```
+
+The allowlist is checked **first**, so a launched route short-circuits and
+resolves no flags at all.
+
+`unlisted` has no default, because it is the whole safety posture and the two
+answers fail very differently:
+
+- `"deny"` — a route added tomorrow is hidden until someone lists it. It 404s
+  loudly, and safely. Right for an app with unlaunched surfaces in the tree.
+- `"allow"` — a new route ships the moment it exists, and forgetting to flag
+  work in progress leaks it silently.
+
+A flag that is **off** denies its paths under either posture; `unlisted` only
+decides paths nothing has an opinion about.
+
+**It throws at construction** if a prefix is both allowed and flagged. That flag
+could never change anything — the allowlist would serve the path regardless — and
+a dead launch gate is precisely the bug you cannot afford to discover late.
+
+`matchesPrefix(pathname, prefixes)` is exported standalone for client-side nav
+filtering, so the menu can't disagree with the router.
+
+## Storage-backed flags
+
+For projects that want to flip a flag per tenant without a deploy. `subjectStore`
+owns the semantics; you own the SQL — any database, any client:
+
+```ts
+const store = subjectStore({
+  // One read for the whole registry. `load: async (subject, key) => …` is the
+  // per-flag alternative when a batch query is awkward.
+  loadAll: async (subject) => {
+    const rows = await db.overridesFor(subject);      // (subject_id, flag_key, override)
+    return Object.fromEntries(rows.map((r) => [r.flag_key, { override: r.override, optedIn: r.opted_in }]));
+  },
+  requiresOptIn: (flag) => flag.def.selfServe === true,
+});
+
+createResolver({
+  flags,
+  sources: [
+    envOverride(),
+    store.kill,           // 1. a 'disabled' row — outranks the cookie
+    cookieOverride({ secret }),
+    store.requireOptIn,   // 3a. veto anything the tenant hasn't switched on
+    store.grant,          // 3b. an 'enabled' row
+    envDefault({ env }),
+  ],
+});
+```
+
+Three sources, one storage read: they share a cache keyed on the `EvaluationContext`
+object, which is per request, so a request pays one `load` per flag no matter how
+many of the three are in the chain. Swap `load` for `loadAll` and the whole
+registry costs one read instead of one per flag — see **Bootstrapping a client** below.
+
+`'disabled'` and `'enabled'` are one row but two sources because they belong in
+**different slots** — a per-tenant kill has to outrank a visitor cookie for the
+same reason the env kill switch does, while a grant sits below it. `requireOptIn`
+sits ahead of `grant` because it must be able to veto an entitlement decided by a
+*later* source (a plan lookup, a stage rule) — a veto that runs after the
+decision it's vetoing never fires.
+
+Project-specific policy stays yours. Hang your own fields on a flag def (`stage`,
+`tier`, `owner`) and read them in your own source — the registry keeps their real
+types.
+
+> There is no `launchgate/postgres` subpath. Once the interface is a `load`
+> function, nothing Postgres-specific is left to ship.
+
+## Bootstrapping a client
+
+`resolveAll(ctx)` evaluates the whole registry at once — LaunchDarkly's
+`allFlagsState()` pattern. Resolve on the server, hand the map down, and the UI
+never flickers because it never had to ask:
+
+```ts
+const enabled = await gate.resolveAll(await requestContext({ targetingKey: orgId }));
+// → { newPricingPage: true, network: false, renderPipeline: "v2" }
+```
+
+Every flag shares the one context object, which is the cache key
+`subjectStore` uses — so with `loadAll` the whole registry costs **one** read.
+
+> Pass the **values**, never the registry. Flag keys name unshipped work, and a
+> viewer who can't see a surface shouldn't learn its name from the payload.
+
+## Testing
+
+```ts
+import { withFlags } from "@davidlee49/launchgate";
+
+const gate = withFlags(flags, { newPricingPage: true });
+```
+
+Answers from a fixed map, falls back for anything unset. Use it instead of
+standing up real sources — flags multiply a test matrix, and that's only
+tolerable if pinning a value is one line.
+
+## Minting an override token
+
+```ts
+import { signOverrides } from "@davidlee49/launchgate";
+
+const token = await signOverrides({ newPricingPage: true }, secret);
+// set it as the `lg_override` cookie
+```
+
+HMAC-SHA256 over Web Crypto, so the same build runs on Cloudflare Workers and
+Node 18+. Tampered or foreign-signed tokens are silently *undecided* — hostile
+input falls through the normal chain rather than pushing the flag anywhere.
+
+## What this deliberately isn't
+
+- **Not experimentation.** No assignment, no exposure logging, no metrics. At the
+  scale this is built for, statistical inference is noise with a dashboard.
+- **Not entitlements.** Those derive from a *contract*. Put billing truth in a
+  flag store and it has no transactional relationship to the subscription, so a
+  downgrade and a flag flip can disagree — and a stale-flag sweep deletes revenue
+  logic that looked like dead state. Supply an entitlement source instead.
+- **Not a circuit breaker.** Failing over to a backup provider is a machine
+  decision made in seconds from observed health; as a flag, a human has to notice
+  the outage first. A flag may say whether the alternative path is *permitted to
+  exist* — it must never *choose* it.
+
+> A flag records a decision a person made. A circuit breaker records a fact the
+> system observed.
+
+## Next.js
+
+```sh
+pnpm add @davidlee49/launchgate   # `next` is an optional peer dependency
+```
+
+```ts
+// app/flag-override/route.ts   ← NOT app/__flags/: see the trap below
+import { createOverrideRoute } from "@davidlee49/launchgate/next";
+import { gate } from "@/flags";
+
+export const { GET } = createOverrideRoute({
+  resolver: gate,
+  secret: process.env.FLAG_SECRET!,
+  accessToken: process.env.FLAG_ACCESS_TOKEN!,   // presented as ?token=, never the signing secret
+});
+```
+
+**If your app has an auth gate, exclude this route from it.** Inside the matcher
+it redirects to your login page and the cookie is never set — the mechanic
+silently does nothing. Its `?token=` is its authorization, and working logged-out
+is the point.
+
+Then `GET /flag-override?token=…&flag=newHomepage&value=on` sets the cookie,
+`&value=off` flips it, omitting `value` clears that flag, and `&clear=1` drops
+all of them. A wrong token gets a 404, not a 401 — an unadvertised route should
+stay unadvertised.
+
+Read a flag in a page or handler:
+
+```ts
+import { requestContext, requireFlag } from "@davidlee49/launchgate/next";
+
+const on = await gate.resolve("newHomepage", await requestContext());     // page
+const blocked = await requireFlag(gate, "network", { targetingKey: orgId }); // handler → 404
+```
+
+### Static rendering — measured, not guessed
+
+`requestContext()` calls `cookies()`, and that **opts the page into dynamic
+rendering**. Verified against Next 16.3.1 by reading `next build`'s route table:
+
+| Page | How it reads the flag | Build classification |
+| --- | --- | --- |
+| `/hidden` | `requestContext()` in the page | **ƒ Dynamic** |
+| `/home` → `/variants/v1`,`/v2` | proxy reads the cookie and rewrites | **○ Static** (all three) |
+
+- **Already-dynamic page** (anything authenticated): just call
+  `requestContext()`. The dynamic cost is already paid.
+- **Page that must stay static** (marketing, landing, docs): don't read the flag
+  in the page. Author the variants as separate routes and rewrite in `proxy.ts`:
+
+```ts
+// proxy.ts  (Next 16's rename of middleware.ts)
+import { NextResponse, type NextRequest } from "next/server";
+import { readOverrides } from "@davidlee49/launchgate";
+
+export async function proxy(request: NextRequest) {
+  const token = request.cookies.get("lg_override")?.value;
+  const overrides = token ? await readOverrides(token, process.env.FLAG_SECRET!) : undefined;
+  const variant = overrides?.newHomepage === true ? "v2" : "v1";
+  return NextResponse.rewrite(new URL(`/variants/${variant}`, request.url));
+}
+
+export const config = { matcher: "/home" };
+```
+
+There is no third option. Resolving in the proxy and forwarding a request header
+doesn't help: the page then calls `headers()`, which opts it into dynamic
+rendering just the same. Forwarding moves the read, not the cost.
+
+> **Trap.** A route handler under a `_`-prefixed directory — `app/__flags/route.ts`
+> — **never registers**. `_` marks a private folder in the App Router, excluded
+> from routing silently, with no build error and no 404 in the route table. Mount
+> the override route at a normal path.
+
+## Async work
+
+Resolve at submission and **stamp the value into the job payload**. A job
+enqueued Monday and run Wednesday must use Monday's value, or you get a job
+that's half one behaviour and half the other — and under a deterministic workflow
+engine, a replay failure. Downstream services get resolved values, not a flag
+client. Records produced by gated code should carry their own provenance rather
+than being re-interpreted through the current flag value.
+
+## Install
+
+```sh
+pnpm add @davidlee49/launchgate
+```
+
+Published to npm as a public package (scoped: the bare name `launchgate` is
+taken on the registry). The repo is private; the tarball is the built `dist/`.
+
+## Releasing
+
+1. Bump `version` in `package.json`.
+2. `pnpm publish` — `prepublishOnly` runs `pnpm check` (typecheck, tests, build),
+   so an unbuilt or failing tree never ships. `dist/` is not committed; the
+   registry holds it.
+3. `git tag vX.Y.Z && git push origin main vX.Y.Z`.
+4. Consumers bump the version range and `pnpm install`. A published version is
+   immutable: a fix is a new version, never a re-tag.
+
+## Development
+
+```sh
+pnpm install
+pnpm check     # tsc --noEmit && vitest run
+```

package/dist/chunk-34MIJ7KP.js

@@ -0,0 +1,99 @@
+// src/signing.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function b64urlFromBytes(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function bytesFromB64url(value) {
+  const b64 = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+var keyCache = /* @__PURE__ */ new Map();
+function hmacKey(secret) {
+  let key = keyCache.get(secret);
+  if (!key) {
+    key = crypto.subtle.importKey(
+      "raw",
+      encoder.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    keyCache.set(secret, key);
+  }
+  return key;
+}
+async function signature(payload, secret) {
+  const key = await hmacKey(secret);
+  const signed = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  return b64urlFromBytes(new Uint8Array(signed));
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function isFlagValue(value) {
+  return typeof value === "boolean" || typeof value === "string" || typeof value === "number" && Number.isFinite(value);
+}
+async function signOverrides(overrides, secret) {
+  const payload = b64urlFromBytes(encoder.encode(JSON.stringify(overrides)));
+  return `${payload}.${await signature(payload, secret)}`;
+}
+async function readOverrides(token, secret) {
+  const split = token.lastIndexOf(".");
+  if (split < 1) return void 0;
+  const payload = token.slice(0, split);
+  const provided = token.slice(split + 1);
+  let expected;
+  try {
+    expected = await signature(payload, secret);
+  } catch {
+    return void 0;
+  }
+  if (!timingSafeEqual(provided, expected)) return void 0;
+  try {
+    const parsed = JSON.parse(decoder.decode(bytesFromB64url(payload)));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return void 0;
+    }
+    const overrides = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (isFlagValue(value)) overrides[key] = value;
+    }
+    return overrides;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/sources/cookie.ts
+var DEFAULT_OVERRIDE_COOKIE = "lg_override";
+function cookieOverride(options) {
+  const { secret } = options;
+  const cookieName = options.cookieName ?? DEFAULT_OVERRIDE_COOKIE;
+  return {
+    name: "cookieOverride",
+    async decide({ key, def }, ctx) {
+      if (!def.overridable) return void 0;
+      const token = ctx.cookie?.(cookieName);
+      if (!token) return void 0;
+      const overrides = await readOverrides(token, secret);
+      return overrides?.[key];
+    }
+  };
+}
+
+export {
+  signOverrides,
+  readOverrides,
+  DEFAULT_OVERRIDE_COOKIE,
+  cookieOverride
+};

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import { S as Source, F as FlagValue, a as FlagMeta, E as EvaluationContext, b as FlagRegistry, R as Resolver, c as FlagValueOf } from './resolver-B2cstRTq.js';
+export { C as Context, D as Decision, d as FlagDef, e as ResolvedFlags, f as ResolverOptions, g as Retirement, h as SourceErrorInfo, i as createResolver, j as defineFlags } from './resolver-B2cstRTq.js';
+
+interface EnvOverrideOptions {
+    /** How to read an environment variable. Defaults to `process.env` where it exists. */
+    read?: (name: string) => string | undefined;
+    /** Variable-name prefix. Default `FLAG_`. */
+    prefix?: string;
+}
+/**
+ * Slot 1 — the operator override, whose primary use is the kill switch.
+ *
+ * `FLAG_NEW_HOMEPAGE=off` forces a flag off; any value the flag's type accepts
+ * forces that value. This sits **above** `cookieOverride` deliberately: a flag
+ * forced on by a visitor cookie must not survive the attempt to kill it.
+ *
+ * An unparseable value throws, which aborts to the flag's fallback and reports
+ * through `onError` — an operator typo is loud rather than silently ignored.
+ */
+declare function envOverride(options?: EnvOverrideOptions): Source;
+interface EnvDefaultOptions {
+    /** The current environment name, matched against each flag's `byEnv`. */
+    env: string | (() => string);
+}
+/**
+ * Slot 4 — the registry's per-environment value, e.g. `byEnv: { development: true }`.
+ *
+ * This is also the whole of "preview deployments": a preview host is just a
+ * different `env` with different values, needing no runtime machinery.
+ */
+declare function envDefault(options: EnvDefaultOptions): Source;
+
+declare const DEFAULT_OVERRIDE_COOKIE = "lg_override";
+interface CookieOverrideOptions {
+    /** Secret for the HMAC. Must not be readable by the client. */
+    secret: string;
+    /** Cookie holding the signed token. Default `lg_override`. */
+    cookieName?: string;
+}
+/**
+ * Slot 2 — the signed per-visitor override: how the author sees hidden work on
+ * the real production site, with no account and no database.
+ *
+ * Honours **only** flags declaring `overridable: true`. A visitor must never be
+ * able to force a flag with real consequences — harmless while flags are
+ * cosmetic, load-bearing the day a project puts an entitlement source in slot 3.
+ *
+ * A missing, malformed, or tampered token is *undecided*, not an error: hostile
+ * input should fall through to the normal chain, not push the flag to its
+ * fallback.
+ */
+declare function cookieOverride(options: CookieOverrideOptions): Source;
+
+/**
+ * What storage knows about one subject and one flag.
+ *
+ * `override` is written only by the platform side. `'disabled'` is the per-subject
+ * kill switch, `'enabled'` the grant (beta cohort, comp, early access) — and they
+ * sit in *different* slots of the chain, which is why they are one row but two
+ * sources.
+ */
+interface SubjectState {
+    override?: "enabled" | "disabled";
+    /** Grant a specific value rather than `true`. For value-typed flags. */
+    value?: FlagValue;
+    /** Has the subject switched it on themselves? */
+    optedIn?: boolean;
+    /**
+     * Projects may return their own fields alongside these and read them back via
+     * `store.state()` — impartire's loader returns the org's `is_platform` here so
+     * its stage policy shares this read instead of issuing a second query.
+     */
+    [projectField: string]: unknown;
+}
+type LoadSubjectState = (subject: string, key: string, flag: FlagMeta) => Promise<SubjectState | undefined> | SubjectState | undefined;
+/**
+ * Every flag's state for one subject, in one read. Keys absent from the result
+ * are treated as "no row", exactly as `load` returning `undefined` is.
+ */
+type LoadAllSubjectState = (subject: string) => Promise<Map<string, SubjectState> | Record<string, SubjectState>> | Map<string, SubjectState> | Record<string, SubjectState>;
+interface SubjectStoreOptions {
+    /** Per-flag read. Supply this, `loadAll`, or both. */
+    load?: LoadSubjectState;
+    /**
+     * Batch read for the whole registry. When present it is preferred, and one
+     * subject costs **one** read per request however many flags resolve — which
+     * is what makes `resolver.resolveAll()` affordable. Without it, evaluating
+     * N flags means N reads.
+     */
+    loadAll?: LoadAllSubjectState;
+    /**
+     * Flags the subject must switch on for themselves — entitlement alone isn't
+     * enough. Default: none.
+     */
+    requiresOptIn?: (flag: FlagMeta) => boolean;
+}
+interface SubjectStore {
+    /** Slot 1, beside `envOverride`. A per-subject kill outranks a visitor cookie. */
+    kill: Source;
+    /** Slot 3a. Vetoes a flag the subject hasn't switched on. */
+    requireOptIn: Source;
+    /** Slot 3b. The platform's grant. */
+    grant: Source;
+    /**
+     * The cached read, for a project's own policy source. Sharing it is what keeps
+     * a bespoke rule from costing an extra query.
+     */
+    state(flag: FlagMeta, ctx: EvaluationContext): Promise<SubjectState | undefined>;
+}
+/**
+ * Three sources over one storage read.
+ *
+ * They share a cache keyed on the `EvaluationContext` object, which is per request, so a
+ * request pays **one** load per flag however many of the three are in the chain —
+ * the alternative being the same row fetched three times. Supply `loadAll` and
+ * the whole registry collapses to one read as well, which is what makes
+ * `resolver.resolveAll()` affordable.
+ *
+ * The library owns the semantics; you own the SQL. `load` returns whatever your
+ * schema says; a row shape of `(subject_id, flag_key, override)` is all this needs.
+ */
+declare function subjectStore(options: SubjectStoreOptions): SubjectStore;
+
+/**
+ * Registry hygiene, checked at build time rather than watched on a dashboard.
+ *
+ * LaunchDarkly ships `find-code-refs` — a scanner that crawls a customer's repo
+ * so the SaaS control plane can warn that an archived key still appears in code.
+ * That tool exists to buy back something a code-first registry has for free: the
+ * flags *are* source, so their hygiene is a build step, and a build step can
+ * fail rather than warn. This is that build step.
+ *
+ * It audits only what the library owns — the retirement clock and the shape of
+ * a `Retirement`. A project's own lifecycle vocabulary (impartire's `stage`, a
+ * `since` stamp on unreleased work, an owner field) is audited by the project,
+ * which knows what those mean; merge the two reports and print them together.
+ */
+interface AuditOptions {
+    /** Defaults to now. Injectable so the age checks are testable. */
+    today?: Date;
+    /**
+     * How long retired code may sit undeleted before the report warns.
+     *
+     * 40 days by default, matching Unleash's documented expected lifetime for a
+     * release flag: retirement is the same debt seen from the other end, and a
+     * budget nobody picked is a budget nobody keeps.
+     */
+    retiredAfterDays?: number;
+}
+interface AuditReport {
+    /** Registry defects. A consumer should fail the build on these. */
+    problems: string[];
+    /** Debt worth seeing every run, but not worth blocking a merge. */
+    warnings: string[];
+}
+declare function auditRegistry(flags: FlagRegistry, options?: AuditOptions): AuditReport;
+
+/**
+ * Prefix match: exact, or a path segment below it.
+ *
+ * `"/"` matches only `"/"` — it falls out of the general rule rather than needing
+ * a special case, because no real pathname starts with `"//"`.
+ *
+ * Exported standalone because nav filtering usually runs in a client component,
+ * where the rule must be identical to the server's or the menu and the router
+ * disagree.
+ */
+declare function matchesPrefix(pathname: string, prefixes: readonly string[]): boolean;
+interface RouteGateOptions<T extends FlagRegistry> {
+    resolver: Resolver<T>;
+    /** Flag key → the path prefixes it reveals. A flag may reveal several. */
+    routes: Partial<Record<keyof T & string, readonly string[]>>;
+    /**
+     * Paths served regardless of any flag — the launched surface. Omit for an
+     * app whose routes are all either public or flagged.
+     */
+    allow?: readonly string[];
+    /**
+     * What to do with a path that is neither allowed nor covered by a flag.
+     *
+     * Required, with no default, because it is the whole safety posture and the
+     * two answers fail in very different ways. `"deny"` means a route added
+     * tomorrow is hidden until someone lists it — it 404s loudly and safely.
+     * `"allow"` means it ships publicly the moment it exists, and forgetting to
+     * flag work in progress leaks it silently.
+     */
+    unlisted: "deny" | "allow";
+}
+interface RouteGate {
+    /** May this path be served right now? */
+    isPermitted(pathname: string, ctx?: EvaluationContext): Promise<boolean>;
+    /** Prefixes currently revealed by a flag. For filtering nav server-side. */
+    revealedPrefixes(ctx?: EvaluationContext): Promise<string[]>;
+    /** Everything servable right now — `allow` plus whatever is revealed. */
+    permittedPrefixes(ctx?: EvaluationContext): Promise<string[]>;
+}
+/**
+ * Turns "which flags are on" into "which paths may be served".
+ *
+ * The app supplies two lists — what is launched, and which flag hides what. This
+ * owns the policy: check the allowlist first (so a launched route costs no flag
+ * resolution at all), then ask the flags.
+ *
+ * **Throws at construction** if a prefix is both allowed and flagged. That flag
+ * could never change anything, because the allowlist would already be letting
+ * the path through — a silent no-op that is very hard to spot by reading, and
+ * exactly the kind of thing a launch gate must not have.
+ */
+declare function createRouteGate<T extends FlagRegistry>(options: RouteGateOptions<T>): RouteGate;
+
+/**
+ * Mints the signed token that `cookieOverride` reads. Lives in the core rather
+ * than the framework adapter so an adapter is only cookie plumbing.
+ */
+declare function signOverrides(overrides: Record<string, FlagValue>, secret: string): Promise<string>;
+/** Verifies and parses a token. Returns `undefined` for anything not genuinely signed. */
+declare function readOverrides(token: string, secret: string): Promise<Record<string, FlagValue> | undefined>;
+
+type FlagValues<T extends FlagRegistry> = Partial<{
+    [K in keyof T]: FlagValueOf<T, K>;
+}>;
+/**
+ * A resolver that answers from a fixed map, falling back to each flag's declared
+ * `fallback` for keys left unset.
+ *
+ * Use this in consumers' tests instead of standing up real sources: flags
+ * multiply a test matrix, and the multiplication is only tolerable if pinning a
+ * value is one line.
+ */
+declare function withFlags<T extends FlagRegistry>(flags: T, values?: FlagValues<T>): Resolver<T>;
+
+export { type AuditOptions, type AuditReport, type CookieOverrideOptions, DEFAULT_OVERRIDE_COOKIE, type EnvDefaultOptions, type EnvOverrideOptions, EvaluationContext, FlagMeta, FlagRegistry, FlagValue, type FlagValues, type LoadAllSubjectState, type LoadSubjectState, Resolver, type RouteGate, type RouteGateOptions, Source, type SubjectState, type SubjectStore, type SubjectStoreOptions, auditRegistry, cookieOverride, createRouteGate, envDefault, envOverride, matchesPrefix, readOverrides, signOverrides, subjectStore, withFlags };

package/dist/index.js

@@ -0,0 +1,274 @@
+import {
+  DEFAULT_OVERRIDE_COOKIE,
+  cookieOverride,
+  readOverrides,
+  signOverrides
+} from "./chunk-34MIJ7KP.js";
+
+// src/resolver.ts
+function defineFlags(flags) {
+  return flags;
+}
+function createResolver(options) {
+  const { flags, sources, onError } = options;
+  async function resolve(key, ctx = {}) {
+    const def = flags[key];
+    if (!def) throw new Error(`launchgate: unknown flag "${key}"`);
+    if (def.retired) return def.retired.value;
+    const meta = { key, def };
+    for (const source of sources) {
+      let decision;
+      try {
+        decision = await source.decide(meta, ctx);
+      } catch (error) {
+        onError?.(error, { flag: key, source: source.name });
+        return def.fallback;
+      }
+      if (decision === void 0) continue;
+      if (typeof decision !== typeof def.fallback) {
+        onError?.(
+          new TypeError(
+            `launchgate: source "${source.name}" answered ${typeof decision} for flag "${key}", which is ${typeof def.fallback}`
+          ),
+          { flag: key, source: source.name }
+        );
+        return def.fallback;
+      }
+      return decision;
+    }
+    return def.fallback;
+  }
+  async function resolveAll(ctx = {}) {
+    const keys = Object.keys(flags);
+    const values = await Promise.all(keys.map((key) => resolve(key, ctx)));
+    return Object.fromEntries(
+      keys.map((key, i) => [key, values[i]])
+    );
+  }
+  return { flags, resolve, resolveAll };
+}
+
+// src/sources/env.ts
+function envName(key) {
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toUpperCase();
+}
+function parseAs(raw, fallback, variable) {
+  const trimmed = raw.trim();
+  if (typeof fallback === "boolean") {
+    const v = trimmed.toLowerCase();
+    if (v === "on" || v === "true" || v === "1" || v === "yes") return true;
+    if (v === "off" || v === "false" || v === "0" || v === "no") return false;
+    throw new Error(
+      `launchgate: ${variable}="${raw}" is not on/off for a boolean flag`
+    );
+  }
+  if (typeof fallback === "number") {
+    const n = Number(trimmed);
+    if (!Number.isFinite(n)) {
+      throw new Error(`launchgate: ${variable}="${raw}" is not a number`);
+    }
+    return n;
+  }
+  return trimmed;
+}
+function defaultRead(name) {
+  const proc = globalThis.process;
+  return proc?.env?.[name];
+}
+function envOverride(options = {}) {
+  const read = options.read ?? defaultRead;
+  const prefix = options.prefix ?? "FLAG_";
+  return {
+    name: "envOverride",
+    decide({ key, def }) {
+      const variable = prefix + envName(key);
+      const raw = read(variable);
+      if (raw === void 0 || raw === "") return void 0;
+      return parseAs(raw, def.fallback, variable);
+    }
+  };
+}
+function envDefault(options) {
+  const { env } = options;
+  return {
+    name: "envDefault",
+    decide({ def }) {
+      const current = typeof env === "function" ? env() : env;
+      return def.byEnv?.[current];
+    }
+  };
+}
+
+// src/sources/subject.ts
+function offValue(flag) {
+  return typeof flag.def.fallback === "boolean" ? false : flag.def.fallback;
+}
+function subjectStore(options) {
+  const { load, loadAll, requiresOptIn } = options;
+  if (!load && !loadAll) {
+    throw new Error("launchgate: subjectStore needs `load` or `loadAll`");
+  }
+  const caches = /* @__PURE__ */ new WeakMap();
+  function read(flag, ctx, subject) {
+    let cache = caches.get(ctx);
+    if (!cache) {
+      cache = { perFlag: /* @__PURE__ */ new Map(), batch: /* @__PURE__ */ new Map() };
+      caches.set(ctx, cache);
+    }
+    if (loadAll) {
+      let batched = cache.batch.get(subject);
+      if (!batched) {
+        batched = Promise.resolve(loadAll(subject)).then(
+          (result) => result instanceof Map ? result : new Map(Object.entries(result))
+        );
+        cache.batch.set(subject, batched);
+      }
+      return batched.then((states) => states.get(flag.key));
+    }
+    const cacheKey = `${subject}\0${flag.key}`;
+    let pending = cache.perFlag.get(cacheKey);
+    if (!pending) {
+      pending = Promise.resolve(load(subject, flag.key, flag));
+      cache.perFlag.set(cacheKey, pending);
+    }
+    return pending;
+  }
+  function source(name, decide, applies = () => true) {
+    return {
+      name,
+      async decide(flag, ctx) {
+        if (!ctx.targetingKey || !applies(flag)) return void 0;
+        const state = await read(flag, ctx, ctx.targetingKey);
+        return state ? decide(state, flag) : decide({}, flag);
+      }
+    };
+  }
+  return {
+    state: async (flag, ctx) => ctx.targetingKey ? read(flag, ctx, ctx.targetingKey) : void 0,
+    kill: source(
+      "subjectKill",
+      (state, flag) => state.override === "disabled" ? offValue(flag) : void 0
+    ),
+    requireOptIn: source(
+      "subjectOptIn",
+      (state, flag) => state.optedIn ? void 0 : offValue(flag),
+      (flag) => requiresOptIn?.(flag) === true
+    ),
+    grant: source("subjectGrant", (state, flag) => {
+      if (state.override !== "enabled") return void 0;
+      if (state.value !== void 0) return state.value;
+      return typeof flag.def.fallback === "boolean" ? true : void 0;
+    })
+  };
+}
+
+// src/audit.ts
+var DATE = /^\d{4}-\d{2}-\d{2}$/;
+function auditRegistry(flags, options = {}) {
+  const { today = /* @__PURE__ */ new Date(), retiredAfterDays = 40 } = options;
+  const problems = [];
+  const warnings = [];
+  for (const [key, def] of Object.entries(flags)) {
+    const retired = def.retired;
+    if (!retired) continue;
+    if (typeof retired.value !== typeof def.fallback) {
+      problems.push(
+        `flag "${key}" is retired to a ${typeof retired.value} but its fallback is ${typeof def.fallback}. Every evaluation would return the wrong type.`
+      );
+    }
+    if (def.overridable) {
+      warnings.push(
+        `"${key}" is retired but still declares \`overridable\`. Retirement outranks the override cookie, so it can no longer be revealed that way \u2014 drop the field.`
+      );
+    }
+    if (!DATE.test(retired.since)) {
+      problems.push(
+        `flag "${key}" is retired with since: "${retired.since}", which is not YYYY-MM-DD. The date is the cleanup clock, so an unparseable one silently stops it.`
+      );
+      continue;
+    }
+    const days = Math.floor(
+      (today.getTime() - (/* @__PURE__ */ new Date(`${retired.since}T00:00:00Z`)).getTime()) / 864e5
+    );
+    if (days > retiredAfterDays) {
+      warnings.push(
+        `"${key}" has been retired for ${days} days (budget ${retiredAfterDays}).
+      Its doors are dark and its code is dead: delete the components, the
+      routes, then the registry entry. Retiring is a state, not a resting place.`
+      );
+    }
+  }
+  return { problems, warnings };
+}
+
+// src/route-gate.ts
+function matchesPrefix(pathname, prefixes) {
+  return prefixes.some(
+    (prefix) => pathname === prefix || pathname.startsWith(prefix + "/")
+  );
+}
+function createRouteGate(options) {
+  const { resolver, routes, allow = [], unlisted } = options;
+  const entries = Object.entries(routes);
+  for (const [key, prefixes] of entries) {
+    for (const prefix of prefixes) {
+      if (allow.includes(prefix)) {
+        throw new Error(
+          `launchgate: "${prefix}" is both allowed and gated by flag "${key}". The allowlist would serve it whatever the flag says, so the flag is dead.`
+        );
+      }
+    }
+    if (!(key in resolver.flags)) {
+      throw new Error(`launchgate: routes reference unknown flag "${key}"`);
+    }
+  }
+  async function revealedPrefixes(ctx = {}) {
+    const revealed = await Promise.all(
+      entries.map(
+        async ([key, prefixes]) => await resolver.resolve(key, ctx) ? prefixes : []
+      )
+    );
+    return revealed.flat();
+  }
+  return {
+    revealedPrefixes,
+    async permittedPrefixes(ctx) {
+      return [...allow, ...await revealedPrefixes(ctx)];
+    },
+    async isPermitted(pathname, ctx) {
+      if (matchesPrefix(pathname, allow)) return true;
+      if (matchesPrefix(pathname, await revealedPrefixes(ctx))) return true;
+      const flagged = entries.flatMap(([, prefixes]) => prefixes);
+      if (matchesPrefix(pathname, flagged)) return false;
+      return unlisted === "allow";
+    }
+  };
+}
+
+// src/testing.ts
+function withFlags(flags, values = {}) {
+  return createResolver({
+    flags,
+    sources: [
+      {
+        name: "withFlags",
+        decide: ({ key }) => values[key]
+      }
+    ]
+  });
+}
+export {
+  DEFAULT_OVERRIDE_COOKIE,
+  auditRegistry,
+  cookieOverride,
+  createResolver,
+  createRouteGate,
+  defineFlags,
+  envDefault,
+  envOverride,
+  matchesPrefix,
+  readOverrides,
+  signOverrides,
+  subjectStore,
+  withFlags
+};

package/dist/next/index.d.ts

@@ -0,0 +1,42 @@
+import { NextResponse } from 'next/server';
+import { b as FlagRegistry, R as Resolver, E as EvaluationContext } from '../resolver-B2cstRTq.js';
+
+/**
+ * Builds an `EvaluationContext` that reads cookies from the incoming request.
+ *
+ * **This opts the caller into dynamic rendering** — `cookies()` always does. On
+ * a page that is already dynamic (anything authenticated) that costs nothing; on
+ * a page you need statically rendered, don't call it, and see `staticVariant`
+ * in the README instead.
+ */
+declare function requestContext(extra?: EvaluationContext): Promise<EvaluationContext>;
+/**
+ * Route-handler guard. 404, not 403: a feature you don't have shouldn't
+ * advertise its own existence.
+ *
+ *   const gate = await requireFlag(resolver, "network", { targetingKey: orgId });
+ *   if (gate) return gate;
+ */
+declare function requireFlag<T extends FlagRegistry, K extends keyof T & string>(resolver: Resolver<T>, key: K, ctx?: EvaluationContext): Promise<NextResponse | null>;
+interface OverrideRouteOptions<T extends FlagRegistry> {
+    resolver: Resolver<T>;
+    /** HMAC secret. Same value `cookieOverride` was given. Never appears in a URL. */
+    secret: string;
+    /** Shared secret presented as `?token=` to use this route. Must differ from `secret`. */
+    accessToken: string;
+    cookieName?: string;
+    /** Cookie lifetime in seconds. Default 30 days. */
+    maxAge?: number;
+}
+/**
+ * `GET /__flags?token=…&flag=newHomepage&value=on` — sets the signed override
+ * cookie, so you see hidden work on the real production site with no account and
+ * no database. `&clear=1` drops everything; omitting `value` clears one flag.
+ *
+ * Mount it at a path you don't advertise, and give it a real `accessToken`.
+ */
+declare function createOverrideRoute<T extends FlagRegistry>(options: OverrideRouteOptions<T>): {
+    GET: (request: Request) => Promise<NextResponse>;
+};
+
+export { type OverrideRouteOptions, createOverrideRoute, requestContext, requireFlag };

package/dist/next/index.js

@@ -0,0 +1,102 @@
+import {
+  DEFAULT_OVERRIDE_COOKIE,
+  readOverrides,
+  signOverrides
+} from "../chunk-34MIJ7KP.js";
+
+// src/next/index.ts
+import { cookies } from "next/headers";
+import { NextResponse } from "next/server";
+async function requestContext(extra = {}) {
+  const jar = await cookies();
+  return { ...extra, cookie: (name) => jar.get(name)?.value };
+}
+async function requireFlag(resolver, key, ctx) {
+  const value = await resolver.resolve(key, ctx);
+  return value === false || value === void 0 ? NextResponse.json({ error: "Not found" }, { status: 404 }) : null;
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function parseAs(raw, fallback) {
+  if (typeof fallback === "boolean") {
+    const v = raw.trim().toLowerCase();
+    if (v === "on" || v === "true" || v === "1") return true;
+    if (v === "off" || v === "false" || v === "0") return false;
+    return void 0;
+  }
+  if (typeof fallback === "number") {
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : void 0;
+  }
+  return raw;
+}
+function createOverrideRoute(options) {
+  const { resolver, secret, accessToken } = options;
+  const cookieName = options.cookieName ?? DEFAULT_OVERRIDE_COOKIE;
+  const maxAge = options.maxAge ?? 60 * 60 * 24 * 30;
+  async function GET(request) {
+    const url = new URL(request.url);
+    const token = url.searchParams.get("token") ?? "";
+    if (!timingSafeEqual(token, accessToken)) {
+      return NextResponse.json({ error: "Not found" }, { status: 404 });
+    }
+    const jar = await cookies();
+    const current = jar.get(cookieName)?.value;
+    let overrides = (current ? await readOverrides(current, secret) : void 0) ?? {};
+    if (url.searchParams.get("clear") !== null) {
+      overrides = {};
+    } else {
+      const key = url.searchParams.get("flag");
+      if (!key) {
+        return NextResponse.json({ error: "flag is required" }, { status: 400 });
+      }
+      const def = resolver.flags[key];
+      if (!def) {
+        return NextResponse.json({ error: `unknown flag "${key}"` }, { status: 400 });
+      }
+      if (!def.overridable) {
+        return NextResponse.json(
+          { error: `flag "${key}" is not overridable` },
+          { status: 400 }
+        );
+      }
+      const raw = url.searchParams.get("value");
+      if (raw === null) {
+        delete overrides[key];
+      } else {
+        const value = parseAs(raw, def.fallback);
+        if (value === void 0) {
+          return NextResponse.json(
+            { error: `"${raw}" is not a valid value for "${key}"` },
+            { status: 400 }
+          );
+        }
+        overrides[key] = value;
+      }
+    }
+    const body = { overrides };
+    const response = NextResponse.json(body);
+    if (Object.keys(overrides).length === 0) {
+      response.cookies.delete(cookieName);
+    } else {
+      response.cookies.set(cookieName, await signOverrides(overrides, secret), {
+        httpOnly: true,
+        sameSite: "lax",
+        secure: url.protocol === "https:",
+        path: "/",
+        maxAge
+      });
+    }
+    return response;
+  }
+  return { GET };
+}
+export {
+  createOverrideRoute,
+  requestContext,
+  requireFlag
+};

package/dist/resolver-B2cstRTq.d.ts

@@ -0,0 +1,161 @@
+/** What a flag can resolve to. Boolean is the common case, not the only one (Decision 1). */
+type FlagValue = boolean | string | number;
+/**
+ * A flag's retirement — the terminal state of its lifecycle (Decision 11).
+ *
+ * Presence is the retirement: a def carrying this resolves to `value` and **no
+ * source is consulted**, not the env kill switch and not a signed override
+ * cookie. That ordering is the point. A retirement is a decision someone
+ * committed to git, so the only way to reverse it is to revert the commit —
+ * never a leftover `FLAG_X=on` secret or a cookie an engineer is still holding.
+ *
+ * The entry **stays in the registry** after retirement, which is Unleash's
+ * archive-rather-than-delete rule and buys the same property: the key cannot be
+ * silently reused by a new feature (a duplicate key in the registry literal is
+ * a type error), so a stale override can never attach to something it was never
+ * about. Delete the entry only once its code is gone.
+ */
+interface Retirement<T extends FlagValue = FlagValue> {
+    /**
+     * When retirement was decided, `YYYY-MM-DD`. Required, because the clock is
+     * the whole point: retired code that nobody deletes is the flag debt this
+     * state exists to make visible. `auditRegistry` warns once it is older than
+     * the budget.
+     */
+    since: string;
+    /**
+     * What every evaluation returns from now on — and the *disposition record*:
+     * Unleash makes you declare an outcome when completing a flag, because the
+     * cleanup PR has to know which branch of the code survives. `false` retires a
+     * feature outright; `"v1"` on a dynamic-config flag says v1 is what the code
+     * keeps.
+     */
+    value: T;
+}
+interface FlagDef<T extends FlagValue = FlagValue> {
+    /**
+     * The value used when no source decides, and when a source throws.
+     *
+     * Per flag, never global (Decision 3): a work-in-progress gate's safe state is
+     * `false`, but a kill switch on a year-old feature's safe state is `true` —
+     * failing that one closed would take down working functionality because a
+     * database blipped.
+     */
+    fallback: T;
+    /** Why this flag exists. Greppability plus this line is the whole flag-debt mitigation. */
+    description: string;
+    /** May a signed visitor cookie force this flag? Default false — see `cookieOverride`. */
+    overridable?: boolean;
+    /** Per-environment value, consulted by the `envDefault` source. */
+    byEnv?: Record<string, T>;
+    /**
+     * Retired: resolve to `retired.value` and consult no source at all. See
+     * `Retirement` — this outranks every source, including the kill switch.
+     */
+    retired?: Retirement<T>;
+    /**
+     * Projects may hang their own fields here — a stage, a tier, an owner — and
+     * read them back inside a custom source. The registry keeps their real types
+     * (`flags.network.stage` is a `string`); only the erased view a `Source` sees
+     * widens to `unknown`.
+     */
+    [projectField: string]: unknown;
+}
+type FlagRegistry = Record<string, FlagDef>;
+/**
+ * The type a flag resolves to.
+ *
+ * `fallback: false` infers as the *literal* `false` rather than `boolean`,
+ * because `boolean` is itself `true | false` and TypeScript preserves a literal
+ * whose contextual type contains it. Left alone, every boolean flag would be
+ * unable to hold the opposite value. Strings and numbers do not have this
+ * problem (their contextual types are not literal unions), so they keep whatever
+ * the author declared — which is what makes `fallback: "v1" as "v1" | "v2"` work.
+ */
+type FlagValueOf<T extends FlagRegistry, K extends keyof T> = T[K]["fallback"] extends boolean ? boolean : T[K]["fallback"];
+/**
+ * Data a source may target on. Named for OpenFeature's evaluation context, and
+ * `targetingKey` is its field — the CNCF spec every major SDK implements, so
+ * this reads as a familiar dialect rather than a private vocabulary.
+ *
+ * `targetingKey` is **optional** by design, where OpenFeature makes it merely
+ * conventional: an anonymous visitor to a static site has none, and a launch
+ * gate must still resolve for them.
+ */
+interface EvaluationContext {
+    /** Who is being evaluated — a user id, org id, device id. Absent for anonymous visitors. */
+    targetingKey?: string;
+    /** Reads a request cookie. Supplied by a framework adapter; absent means "no cookies here". */
+    cookie?: (name: string) => string | undefined;
+    /** Anything else a project-supplied source needs. */
+    [key: string]: unknown;
+}
+/** @deprecated Renamed to `EvaluationContext` in 0.3.0 to match OpenFeature. */
+type Context = EvaluationContext;
+/** A source's answer. `undefined` means *undecided — ask the next source* (Decision 2). */
+type Decision = FlagValue | undefined;
+interface FlagMeta {
+    key: string;
+    def: FlagDef;
+}
+/**
+ * One link in the resolution chain. Sources are typed against `unknown` values
+ * rather than the registry's inferred types (Decision 8) — the call site keeps
+ * its types, the four built-in sources give theirs up.
+ */
+interface Source {
+    /** Reported to `onError` when this source throws. */
+    readonly name: string;
+    decide(flag: FlagMeta, ctx: Context): Decision | Promise<Decision>;
+}
+interface SourceErrorInfo {
+    flag: string;
+    source: string;
+}
+
+/**
+ * Declares a project's flags. Identity at runtime; it exists to infer each flag's
+ * value type so `resolve()` is typed at the call site.
+ *
+ * The registry lives in the project that reads the flags, not in a table and not
+ * in library config (Decision 4): flags ship with the code they gate, so deleting
+ * one is a pull request and a key nobody reads is visibly dead.
+ */
+declare function defineFlags<T extends FlagRegistry>(flags: T): T;
+interface ResolverOptions<T extends FlagRegistry> {
+    flags: T;
+    /**
+     * Consulted in order; the first definite answer wins. Recommended ordering:
+     * `envOverride` (kill switch), `cookieOverride`, project sources (grants,
+     * opt-in, entitlement), `envDefault`. The flag's `fallback` is terminal and is
+     * not a source, so it cannot be left out.
+     */
+    sources: Source[];
+    /** Called when a source throws or answers with the wrong type. */
+    onError?: (error: unknown, info: SourceErrorInfo) => void;
+}
+/** Every flag in a registry, evaluated. */
+type ResolvedFlags<T extends FlagRegistry> = {
+    [K in keyof T]: FlagValueOf<T, K>;
+};
+interface Resolver<T extends FlagRegistry> {
+    resolve<K extends keyof T & string>(key: K, ctx?: EvaluationContext): Promise<FlagValueOf<T, K>>;
+    /**
+     * Evaluate the whole registry at once — LaunchDarkly's `allFlagsState()`
+     * pattern: resolve server-side, hand the map to the client, and the UI never
+     * flickers because it never had to ask.
+     *
+     * Resolution is concurrent and shares the context object, so subject-backed
+     * sources hit their per-request cache; with `subjectStore({ loadAll })` the
+     * whole registry costs one read.
+     *
+     * Pass the **values** to a client, never the registry — flag keys name
+     * unshipped work, and a viewer who can't see a surface shouldn't learn its
+     * name from the payload.
+     */
+    resolveAll(ctx?: EvaluationContext): Promise<ResolvedFlags<T>>;
+    readonly flags: T;
+}
+declare function createResolver<T extends FlagRegistry>(options: ResolverOptions<T>): Resolver<T>;
+
+export { type Context as C, type Decision as D, type EvaluationContext as E, type FlagValue as F, type Resolver as R, type Source as S, type FlagMeta as a, type FlagRegistry as b, type FlagValueOf as c, type FlagDef as d, type ResolvedFlags as e, type ResolverOptions as f, type Retirement as g, type SourceErrorInfo as h, createResolver as i, defineFlags as j };

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@davidlee49/launchgate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "description": "A launch-gate library: hide work in progress, kill a shipped feature, no platform required.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.js"
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4",
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@types/react": "^19.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=15"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidlee49/launchgate.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check": "tsc --noEmit && vitest run && tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }