@ultimat3/flags 29.4.0 → 30.0.0

package/CLAUDE.md

@@ -80,7 +80,7 @@ what lets `policy` (tier 2) call it from inside a predicate.
   an inherited function, and a non-string id never reaches `bucketOf`. Same rule for the targeting
   map, which is why the loop is `for…in` + `Object.hasOwn` and not `Object.entries`.
 - **Every app-supplied string in a `fix:` goes through `JSON.stringify`, and a subject kind becomes
-  a computed key.** A `bank-integration` kind is not a valid identifier, so `{ bank-integration: … }`
+  a computed key.** A `payments-provider` kind is not a valid identifier, so `{ payments-provider: … }`
   would be a fix that does not parse — axiom 4 wants an instruction that runs. Pinned by
   `errors.test.ts` running the generated snippet through `new Function`.
 - **An unknown key throws.** Answering `false` is a branch that never runs and never says so.

package/README.md

@@ -2,6 +2,19 @@
 
 Feature flags: permanent switches, and temporary ones that cannot be forgotten.
 
+`bun add @ultimat3/flags` · guide: [Feature Flags](https://github.com/developerz-ai/ultimate/wiki/Feature-Flags)
+
+```ts
+import { defineFlag } from '@ultimat3/flags';
+
+export const dunning = defineFlag({
+  kind: 'permanent',
+  key: 'billing.dunning-emails',
+  description: 'ops kill switch for dunning email delivery',
+  targeting: { default: true },
+});
+```
+
 Feature flags are normally a bad trade — N flags are 2^N states nothing tested. This package takes
 the trade only on terms that bound the exponent: every flag declares which of two kinds it is, and
 a `temporary` flag carries an expiry it cannot be declared without. Past that date, every

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@ultimat3/flags",
-  "version": "29.4.0",
+  "version": "30.0.0",
   "description": "Feature flags: permanent switches, and temporary ones that cannot be forgotten",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "feature-flags",
+    "flags",
+    "toggles"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Feature-Flags",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -32,6 +41,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.4.0"
+    "@ultimat3/core": "30.0.0"
   }
 }

package/src/errors.ts

@@ -94,8 +94,8 @@ export const flagSubjectRequired = (init: {
     code: 'X_FLAG_SUBJECT_REQUIRED',
     cause: `${init.key} decides by the "${init.kind}" subject (targeting.${init.via}) but the evaluation context carries no ${init.kind} id for actor "${init.actorId}", so there is nothing to decide about`,
     // Every app-supplied string goes through JSON.stringify, and the kind becomes a COMPUTED key:
-    // a `bank-integration` kind — the realistic shape, next to treasury's `bank_integration:` ids
-    // — is not a valid identifier, so `{ bank-integration: … }` would hand the reader a fix that
+    // a `payments-provider` kind — the realistic shape, next to one adopter's `<kind>:<name>` ids
+    // — is not a valid identifier, so `{ payments-provider: … }` would hand the reader a fix that
     // does not parse. Axiom 4: an instruction that cannot be run is not one.
     fix:
       init.kind === 'org'

package/src/evaluate.ts

@@ -6,7 +6,7 @@ import type { Actor } from '@ultimat3/core';
 import { flagExpired } from './errors';
 import type { Flag } from './flag';
 import { flagFor } from './registry';
-import { flagsClock, reportOnce } from './runtime';
+import { flagsClock, recordEvaluation, reportOnce } from './runtime';
 import type { FlagSubjects } from './subject';
 import { evaluateTargeting } from './targeting';
 
@@ -51,5 +51,5 @@ export function isEnabled(
 ): boolean {
   const flag = flagFor(key);
   reportIfOverdue(flag);
-  return evaluateTargeting(flag.key, flag.targeting, actor, subjects);
+  return recordEvaluation(flag.key, evaluateTargeting(flag.key, flag.targeting, actor, subjects));
 }

package/src/runtime.ts

@@ -8,7 +8,7 @@
 // caught failure, while a flag is evaluated on every request.
 
 import type { Clock, UltimateError } from '@ultimat3/core';
-import { finiteCount, reportError, systemClock } from '@ultimat3/core';
+import { finiteCount, recordFailureFact, reportError, systemClock } from '@ultimat3/core';
 
 /**
  * One hour. Small enough that an overdue flag shows up the same day, large enough that a flag read
@@ -81,6 +81,15 @@ export function reportOnce(key: string, build: () => UltimateError): boolean {
   return true;
 }
 
+/**
+ * What an evaluation answered, into the failure buffer when a captured call is in flight — so
+ * `x repro` replays the branch the failing request took. Off, one `undefined` check in core.
+ */
+export function recordEvaluation(key: string, on: boolean): boolean {
+  recordFailureFact({ kind: 'flag', key, value: on });
+  return on;
+}
+
 /** Test-only, and the counterpart to every other reset in the framework. */
 export function resetFlagReporting(): void {
   clock = systemClock;