@happyvertical/smrt-features 0.51.18 → 0.51.20

package/AGENTS.md

@@ -8,6 +8,9 @@ Code-first feature flag system with global, app-level, and tenant-hierarchy reso
 - `FeatureOverride` (`_smrt_feature_overrides` table) — runtime override state, scoped by `(featureKey, scopeType, scopeId)`
 - `FeatureResolver` — resolves the effective state of a feature in a given context, walking the scope chain
 - `FeatureSyncService` — keeps `_smrt_feature_definitions` in sync with code-registered defaults at boot
+- `FeatureOverrideService` — the only write path; asks a host-supplied authorizer before every write and fails closed (#3013)
+- `FeatureSettingsService` — read/write helper for a management screen: `listFeatureSettings()` returns one row per definition (definition fields, `effectiveEnabled`, `globalEffect`, `tenantEffect`), `setFeatureOverride()` refuses unknown keys and scopes the resolver never reads back, then delegates to `FeatureOverrideService` (#3052)
+- `./svelte` subpath — `FeatureSettingsPanel`, the presentational management panel (#3052)
 
 ## Resolution chain (priority high → low)
 
@@ -24,6 +27,20 @@ Code-first feature flag system with global, app-level, and tenant-hierarchy reso
 - Overrides are write-time validated against the matching definition (effect must be a known `FeatureOverrideEffect`, scope must be valid for the definition's `allowedScopes`)
 - Tenant-hierarchy resolution is an optional integration wired by dependency injection (`FeatureTenantHierarchyProvider`), not a static dependency — `smrt-features` never imports `@happyvertical/smrt-users`. Without a configured provider, tenant-hierarchy resolution falls back to a flat tenant scope. (The consumer that wants hierarchy installs `smrt-users` itself and supplies the provider; `smrt-users` is a dev-only dependency here for tests.)
 
+## Management UI (`./svelte`)
+
+- Built like every other Svelte-shipping package here (`smrt-tenancy`/`smrt-personas` are the closest models): `vite build --mode library && svelte-package -i src/svelte -o dist/svelte`, an `./svelte` export with a `svelte` condition, `svelte` as an **optional** peer dependency — plus `scripts/prune-svelte-package-artifacts.js` (as `smrt-content` does), because `svelte-package` otherwise copies `__tests__/` and `*.test.*` into the published `dist/svelte`. The root export stays Svelte-free so server-only consumers are unaffected.
+- `FeatureSettingsPanel` is presentational: rows and callbacks in, no fetching, no authorization. `src/svelte/types.ts` deliberately imports nothing from `smrt-core` or the `@smrt()` models, so the browser bundle stays thin; `FeatureSettingsRow` is structurally assignable to `FeatureSettingsView`.
+- Each row is its own `<form>`, so `formAction` gives a working screen with no client JS; `onSave` intercepts the submit instead and reads the row's values straight off the form. The global column is opt-in (`showGlobal` / `globalEditable`) because most apps have no platform-admin tier.
+- Two invariants the selects have to keep, both regression-tested. (1) The tenant column's *Default* option must never name the code default: the tenant scope inherits the global override and, with a `FeatureTenantHierarchyProvider`, ancestor tenants' overrides too, so `defaultEnabled` would tell an operator the opposite of what choosing it does. `inheritedOptionLabel()` names `FeatureSettingsView.inheritedEnabled` when the row carries it and says "Default (inherited)" otherwise; `FeatureSettingsService` sets it only where it is exactly knowable (no tenant override → inherited is the effective state), never derived from `globalEffect`. The global column does name the code default — nothing sits above global. (2) The rows remount on `contextKey ?? features`, so an unsaved choice cannot survive a reload or a tenant switch and be submitted against the new rows.
+- Writes validate the **scope shape** before the authorizer runs: `scopeType` must be `global` or `tenant`, a global write must use `GLOBAL_FEATURE_SCOPE_ID`, and a tenant id must be non-blank and already trimmed. A host authorizer cannot catch this — `scopeType: 'global'` with someone else's tenant id reads as an ordinary global write to an authorizer that only gates the global scope — and the resolver looks rows up by the exact `(featureKey, scopeType, scopeId)` triple, so a row written elsewhere is invisible state, not a setting.
+- **Authorization stays with the consumer.** `FeatureSettingsService` reads are unfiltered and every write goes through `FeatureOverrideService`; constructing the settings service without an `authorize` option makes it read-only (writes fail closed). Never add an authorization decision to this package — hosts differ, and the generated surfaces are closed precisely so that decision has to be theirs.
+- `vitest.config.ts` runs two projects because the halves need incompatible resolution: `server` (node, `smrtVitestPlugin`) and `svelte` (jsdom, `@sveltejs/vite-plugin-svelte`, `conditions: ['browser']`). The browser condition would send `smrt-core` to its browser build, so it must not be global.
+
+## Feature keys are persisted identifiers
+
+Overrides are stored keyed by the exact `featureKey` string and the resolver looks them up by that string. **Renaming a key orphans every existing override and silently reverts all tenants to the definition default.** Treat a shipped key as immutable; a rename needs a data migration over `_smrt_feature_overrides.feature_key`, not an edit. Renaming the owning package is the usual trigger — keep the old key namespace and let `packageName` track the new package.
+
 ## Integration with `@happyvertical/smrt-users`
 
 When `smrt-users` is present, `FeatureResolver` uses it to walk the tenant hierarchy (parent → grandparent → root). Configure via `FeatureTenantHierarchyProvider`. Without it, tenant lookup is single-level.

package/README.md

@@ -70,6 +70,158 @@ const service = new FeatureOverrideService(overrides, (request) =>
 await service.setOverride(key, 'tenant', session.tenantId, FeatureOverrideEffect.ENABLE);
 ```
 
+## Management UI
+
+The package ships the settings screen so consuming apps do not each rebuild
+it: `FeatureSettingsService` (root export) produces the rows, and
+`FeatureSettingsPanel` (the `./svelte` subpath) renders them. The root export
+stays Svelte-free, so a server-only consumer is unaffected; `svelte` is an
+optional peer dependency.
+
+### Consumer recipe
+
+**1. Declare the definitions in code.** Feature toggles are declared on the
+`@smrt()` decorator of the class they belong to:
+
+```typescript
+@smrt({
+  features: {
+    drafts: { defaultEnabled: false, label: 'Invoice drafts', description: 'Save invoices as drafts before sending.' },
+  },
+})
+export class Invoice extends SmrtObject {}
+```
+
+**2. Sync them at startup**, so `_smrt_feature_definitions` matches code:
+
+```typescript
+await new FeatureSyncService(dbOptions).syncDefinitions();
+```
+
+**3. Load the rows in your server load.** The load is where *your*
+permission check lives — the package makes no authorization decision:
+
+```typescript
+// src/routes/settings/features/+page.server.ts
+export async function load(event) {
+  const auth = requirePermission(event, APP_PERMISSIONS.tenantAdmin);
+  const settings = await FeatureSettingsService.create(dbOptions);
+  return {
+    tenantId: auth.tenantId,
+    features: await settings.listFeatureSettings({
+      tenantId: auth.tenantId,
+      packageName: '@your/app',
+    }),
+  };
+}
+```
+
+`listFeatureSettings()` returns one `FeatureSettingsRow` per definition —
+the definition fields, `effectiveEnabled` as `FeatureResolver` resolves it
+for that tenant, and `globalEffect` / `tenantEffect` for the raw override row
+at each level. The row is structurally assignable to the panel's
+`FeatureSettingsView`, so no mapping step is needed.
+
+**4. Render the panel:**
+
+```svelte
+<script lang="ts">
+  import { FeatureSettingsPanel } from '@happyvertical/smrt-features/svelte';
+  let { data, form } = $props();
+</script>
+
+<FeatureSettingsPanel
+  features={data.features}
+  tenantLabel="Shop"
+  contextKey={data.tenantId}
+  formAction="?/saveFeature"
+  message={form?.message}
+  error={form?.error}
+/>
+```
+
+The panel is presentational: it takes rows and callbacks, fetches nothing and
+authorizes nothing. Each row renders label, description, key, effective state
+and a **Default / Enable / Disable** control, where *Default* removes the
+override row and returns the feature to whatever the level above resolves to.
+Pass `showGlobal` (and `globalEditable`) only if your app has a platform-admin
+tier; apps without one omit the column entirely. Supply `onSave` instead of
+`formAction` to drive it from a client handler.
+
+Two details worth knowing:
+
+- The tenant column's *Default* option never names the code default, because
+  the tenant scope inherits — from the global override, and, when a
+  `FeatureTenantHierarchyProvider` is configured, from ancestor tenants too. It
+  names the inherited state when the row carries `inheritedEnabled` (the helper
+  sets it whenever it is exactly knowable, i.e. when the tenant has no override
+  of its own) and otherwise reads "Default (inherited)". The global column's
+  *Default* does name the code default, because the global scope inherits
+  nothing.
+- Unsaved edits are discarded whenever `contextKey` changes, or, when you omit
+  it, whenever `features` is replaced with a new array. Pass the tenant id as
+  `contextKey` so a half-made choice for one tenant can never be submitted
+  against another's rows.
+
+**5. Wire the write with your own permission check.** `setFeatureOverride()`
+refuses any key without a definition and any scope the resolver would never
+read back — an unknown `scopeType`, a global write under anything but
+`GLOBAL_FEATURE_SCOPE_ID`, or a blank/untrimmed tenant id — then delegates to
+`FeatureOverrideService`, which asks your authorizer and fails closed:
+
+```typescript
+export const actions = {
+  saveFeature: async (event) => {
+    const auth = requirePermission(event, APP_PERMISSIONS.tenantAdmin);
+    const form = await event.request.formData();
+    const settings = await FeatureSettingsService.create(dbOptions, {
+      // Your decision, bound to this caller. Returning anything but `true` denies.
+      authorize: (request) =>
+        request.scopeType === 'tenant' && request.scopeId === auth.tenantId,
+    });
+
+    try {
+      await settings.setTenantFeatureOverride(
+        String(form.get('featureKey') ?? ''),
+        auth.tenantId,
+        featureOverrideEffectFromValue(form.get('tenantEffect')),
+      );
+    } catch (error) {
+      if (error instanceof UnknownFeatureKeyError) return fail(400, { error: 'Unknown feature.' });
+      if (error instanceof InvalidFeatureScopeError) return fail(400, { error: 'Invalid scope.' });
+      if (error instanceof FeatureOverrideAuthorizationError) return fail(403, { error: 'Not permitted.' });
+      throw error;
+    }
+    return { message: 'Feature overrides saved.' };
+  },
+};
+```
+
+Constructing the service **without** an `authorize` option makes it
+read-only: every write then fails closed with
+`FeatureOverrideAuthorizationError`. That is the right shape for a load
+function.
+
+### What the consumer still owns
+
+- the route, its navigation entry, and the page shell;
+- the permission check on both the load and the action;
+- the `authorize` callback (this package never decides who may write);
+- resolving the session's `tenantId` — a tenant id from the URL or a form
+  field is a selector, not authorization;
+- calling `FeatureSyncService` at startup.
+
+### Feature keys are persisted identifiers
+
+Overrides are stored keyed by the exact `featureKey` string and resolved by
+that string at runtime. **Renaming a key orphans every existing override**,
+silently reverting all tenants to the definition default — the change looks
+harmless in a diff and shows up as flags mysteriously resetting. Treat a key
+as immutable once shipped. A rename needs a data migration that rewrites
+`_smrt_feature_overrides.feature_key`, not an edit. (Renaming the owning
+package is the usual way this happens: keep the old key namespace and let
+`packageName` track the new package.)
+
 ## Documentation
 
 - See [`AGENTS.md`](./AGENTS.md) for package-internal patterns

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/feature-definition.d.ts

@@ -0,0 +1,18 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { FeatureDefinitionOptions, FeatureMetadata } from './types.js';
+export declare class FeatureDefinition extends SmrtObject {
+    featureKey: string;
+    packageName: string;
+    qualifiedClassName: string;
+    className: string;
+    localId: string;
+    defaultEnabled: boolean;
+    label: string;
+    description: string;
+    metadata: string;
+    visibility: string;
+    constructor(options?: FeatureDefinitionOptions);
+    getMetadata(): FeatureMetadata;
+    setMetadata(metadata: FeatureMetadata | null): void;
+}
+//# sourceMappingURL=feature-definition.d.ts.map

package/dist/feature-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-definition.d.ts","sourceRoot":"","sources":["../src/feature-definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG5E,qBASa,iBAAkB,SAAQ,UAAU;IAC/C,UAAU,EAAE,MAAM,CAAM;IACxB,WAAW,EAAE,MAAM,CAAM;IACzB,kBAAkB,EAAE,MAAM,CAAM;IAChC,SAAS,EAAE,MAAM,CAAM;IACvB,OAAO,EAAE,MAAM,CAAM;IACrB,cAAc,EAAE,OAAO,CAAS;IAChC,KAAK,EAAE,MAAM,CAAM;IACnB,WAAW,EAAE,MAAM,CAAM;IACzB,QAAQ,EAAE,MAAM,CAAM;IACtB,UAAU,EAAE,MAAM,CAAY;gBAElB,OAAO,GAAE,wBAA6B;IAuBlD,WAAW,IAAI,eAAe;IAI9B,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI;CAGpD"}

package/dist/feature-definitions.d.ts

@@ -0,0 +1,13 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { FeatureDefinition } from './feature-definition.js';
+import { FeatureDefinitionSeed } from './types.js';
+export declare class FeatureDefinitionCollection extends SmrtCollection<FeatureDefinition> {
+    static readonly _itemClass: typeof FeatureDefinition;
+    findByFeatureKey(featureKey: string): Promise<FeatureDefinition | null>;
+    findByPackageName(packageName: string): Promise<FeatureDefinition[]>;
+    upsertDefinition(seed: FeatureDefinitionSeed): Promise<{
+        definition: FeatureDefinition;
+        status: 'created' | 'updated' | 'unchanged';
+    }>;
+}
+//# sourceMappingURL=feature-definitions.d.ts.map

package/dist/feature-definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-definitions.d.ts","sourceRoot":"","sources":["../src/feature-definitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD,qBAAa,2BAA4B,SAAQ,cAAc,CAAC,iBAAiB,CAAC;IAChF,MAAM,CAAC,QAAQ,CAAC,UAAU,2BAAqB;IAEzC,gBAAgB,CACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAQ9B,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAMpE,gBAAgB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC;QAC3D,UAAU,EAAE,iBAAiB,CAAC;QAC9B,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;KAC7C,CAAC;CAyCH"}

package/dist/feature-override-service.d.ts

@@ -0,0 +1,41 @@
+import { FeatureOverride } from './feature-override.js';
+import { FeatureOverrideCollection } from './feature-overrides.js';
+import { FeatureOverrideEffect, FeatureScopeType } from './types.js';
+/** One override write the host must authorize before it runs (#3013). */
+export interface FeatureOverrideWriteRequest {
+    operation: 'set' | 'remove';
+    featureKey: string;
+    scopeType: FeatureScopeType;
+    scopeId: string;
+    /** Present for `set`. */
+    effect?: FeatureOverrideEffect;
+}
+/**
+ * The host's explicit authorization decision for one override write. Return
+ * `true` only when the current caller may write that exact scope; anything
+ * else denies.
+ */
+export type FeatureOverrideAuthorizer = (request: FeatureOverrideWriteRequest) => boolean | Promise<boolean>;
+/** Thrown when the authorizer does not return `true`. Nothing is written. */
+export declare class FeatureOverrideAuthorizationError extends Error {
+    readonly request: FeatureOverrideWriteRequest;
+    readonly status = 403;
+    constructor(request: FeatureOverrideWriteRequest);
+}
+/**
+ * Authorized write path for feature overrides (#3013). Override rows are
+ * authorization state for every scope and `FeatureOverride` is not
+ * tenant-scoped, so generated surfaces are closed. Hosts that let callers
+ * change flags construct this service with an authorizer bound to the
+ * current caller and write through it; every write asks the authorizer
+ * first and fails closed.
+ */
+export declare class FeatureOverrideService {
+    private readonly overrides;
+    private readonly authorize;
+    constructor(overrides: FeatureOverrideCollection, authorize: FeatureOverrideAuthorizer);
+    setOverride(featureKey: string, scopeType: FeatureScopeType, scopeId: string, effect: FeatureOverrideEffect): Promise<FeatureOverride>;
+    removeOverride(featureKey: string, scopeType: FeatureScopeType, scopeId: string): Promise<boolean>;
+    private require;
+}
+//# sourceMappingURL=feature-override-service.d.ts.map

package/dist/feature-override-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-override-service.d.ts","sourceRoot":"","sources":["../src/feature-override-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE1E,yEAAyE;AACzE,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,OAAO,EAAE,2BAA2B,KACjC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,6EAA6E;AAC7E,qBAAa,iCAAkC,SAAQ,KAAK;IAE9C,QAAQ,CAAC,OAAO,EAAE,2BAA2B;IADzD,QAAQ,CAAC,MAAM,OAAO;gBACD,OAAO,EAAE,2BAA2B;CAM1D;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAsB;IAE/B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,SAAS,EAAE,yBAAyB,EACpC,SAAS,EAAE,yBAAyB;IAGjD,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,eAAe,CAAC;IAWrB,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC;YAKL,OAAO;CAStB"}

package/dist/feature-override.d.ts

@@ -0,0 +1,13 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { FeatureOverrideEffect, FeatureOverrideOptions, FeatureScopeType } from './types.js';
+export declare class FeatureOverride extends SmrtObject {
+    featureKey: string;
+    scopeType: FeatureScopeType;
+    scopeId: string;
+    effect: FeatureOverrideEffect;
+    constructor(options?: FeatureOverrideOptions);
+    isInherit(): boolean;
+    isEnabled(): boolean;
+    isDisabled(): boolean;
+}
+//# sourceMappingURL=feature-override.d.ts.map

package/dist/feature-override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-override.d.ts","sourceRoot":"","sources":["../src/feature-override.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EACL,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EAEtB,MAAM,YAAY,CAAC;AAUpB,qBAOa,eAAgB,SAAQ,UAAU;IAC7C,UAAU,EAAE,MAAM,CAAM;IACxB,SAAS,EAAE,gBAAgB,CAAY;IACvC,OAAO,EAAE,MAAM,CAA2B;IAC1C,MAAM,EAAE,qBAAqB,CAAiC;gBAElD,OAAO,GAAE,sBAA2B;IAShD,SAAS,IAAI,OAAO;IAIpB,SAAS,IAAI,OAAO;IAIpB,UAAU,IAAI,OAAO;CAGtB"}

package/dist/feature-overrides.d.ts

@@ -0,0 +1,16 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { FeatureOverride } from './feature-override.js';
+import { FeatureOverrideEffect, FeatureScopeType } from './types.js';
+export declare class FeatureOverrideCollection extends SmrtCollection<FeatureOverride> {
+    static readonly _itemClass: typeof FeatureOverride;
+    findByFeatureKey(featureKey: string): Promise<FeatureOverride[]>;
+    findByFeatureAndScope(featureKey: string, scopeType: FeatureScopeType, scopeId: string): Promise<FeatureOverride | null>;
+    getGlobalOverride(featureKey: string): Promise<FeatureOverride | null>;
+    getTenantOverride(featureKey: string, tenantId: string): Promise<FeatureOverride | null>;
+    getOverrideMap(featureKey: string, scopeType: FeatureScopeType, scopeIds: string[]): Promise<Map<string, FeatureOverride>>;
+    setOverride(featureKey: string, scopeType: FeatureScopeType, scopeId: string, effect: FeatureOverrideEffect): Promise<FeatureOverride>;
+    setGlobalOverride(featureKey: string, effect: FeatureOverrideEffect): Promise<FeatureOverride>;
+    setTenantOverride(featureKey: string, tenantId: string, effect: FeatureOverrideEffect): Promise<FeatureOverride>;
+    removeOverride(featureKey: string, scopeType: FeatureScopeType, scopeId: string): Promise<boolean>;
+}
+//# sourceMappingURL=feature-overrides.d.ts.map

package/dist/feature-overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-overrides.d.ts","sourceRoot":"","sources":["../src/feature-overrides.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAEtB,MAAM,YAAY,CAAC;AAEpB,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,eAAe,CAAC;IAC5E,MAAM,CAAC,QAAQ,CAAC,UAAU,yBAAmB;IAEvC,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAMhE,qBAAqB,CACzB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAQ5B,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAQtE,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAI5B,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAiBlC,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,eAAe,CAAC;IAuBrB,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,eAAe,CAAC;IASrB,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,eAAe,CAAC;IAIrB,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC;CAcpB"}

package/dist/feature-resolver.d.ts

@@ -0,0 +1,18 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { FeatureResolutionContext, FeatureResolverOptions, FeatureTargetConstructor } from './types.js';
+export declare class FeatureResolver {
+    private readonly options;
+    private readonly resolverOptions;
+    private featureDefinitions;
+    private featureOverrides;
+    private initializationPromise;
+    private tenantHierarchyPromise;
+    constructor(options?: SmrtClassOptions, resolverOptions?: FeatureResolverOptions);
+    isEnabled(featureKey: string, context?: FeatureResolutionContext): Promise<boolean>;
+    isEnabledFor(classOrInstance: object | FeatureTargetConstructor, localId: string, context?: FeatureResolutionContext): Promise<boolean>;
+    private ensureInitialized;
+    private resolveBaseState;
+    private applyOverride;
+    private getTenantHierarchy;
+}
+//# sourceMappingURL=feature-resolver.d.ts.map

package/dist/feature-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-resolver.d.ts","sourceRoot":"","sources":["../src/feature-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIjE,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAI9B,MAAM,YAAY,CAAC;AAMpB,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,kBAAkB,CAA+B;IACzD,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,qBAAqB,CAA8B;IAC3D,OAAO,CAAC,sBAAsB,CACvB;gBAGL,OAAO,GAAE,gBAAqB,EAC9B,eAAe,GAAE,sBAA2B;IAMxC,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,OAAO,CAAC;IAqDb,YAAY,CAChB,eAAe,EAAE,MAAM,GAAG,wBAAwB,EAClD,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,OAAO,CAAC;YAKL,iBAAiB;YAejB,gBAAgB;IAiB9B,OAAO,CAAC,aAAa;YAcP,kBAAkB;CAUjC"}

package/dist/feature-settings.d.ts

@@ -0,0 +1,209 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { FeatureDefinitionCollection } from './feature-definitions.js';
+import { FeatureOverride } from './feature-override.js';
+import { FeatureOverrideAuthorizer } from './feature-override-service.js';
+import { FeatureOverrideCollection } from './feature-overrides.js';
+import { FeatureResolver } from './feature-resolver.js';
+import { FeatureMetadata, FeatureOverrideEffect, FeatureResolverOptions, FeatureScopeType } from './types.js';
+/**
+ * One feature, rendered for a management screen: the code-owned definition,
+ * the value that is actually in effect for the requested tenant, and the raw
+ * override row at each scope level so the UI can show *why* it is in effect.
+ *
+ * Structurally assignable to the presentational `FeatureSettingsView` consumed
+ * by `@happyvertical/smrt-features/svelte`, so a server load can hand its rows
+ * straight to `FeatureSettingsPanel` without a mapping step.
+ */
+export interface FeatureSettingsRow {
+    /**
+     * The persisted identifier. Renaming it orphans every existing override —
+     * see the warning on {@link FeatureSettingsService}.
+     */
+    featureKey: string;
+    /** Human label from the definition; may be empty. */
+    label: string;
+    /** Human description from the definition; may be empty. */
+    description: string;
+    /** Owning package, as synced from the manifest. */
+    packageName: string;
+    /** Qualified `package:Class` name of the feature's target. */
+    qualifiedClassName: string;
+    /** Unqualified class name of the feature's target. */
+    className: string;
+    /** Class-local feature id. */
+    localId: string;
+    /** Definition visibility marker (`public` unless the seed says otherwise). */
+    visibility: string;
+    /** Parsed definition metadata. */
+    metadata: FeatureMetadata;
+    /** The code-owned default, used when no override applies. */
+    defaultEnabled: boolean;
+    /**
+     * What {@link FeatureResolver} resolves for the requested context — the
+     * value the application actually behaves by.
+     */
+    effectiveEnabled: boolean;
+    /** Effect of the global override row, or `null` when there is none. */
+    globalEffect: FeatureOverrideEffect | null;
+    /**
+     * Effect of the override row for the requested tenant, or `null` when there
+     * is none (or when no `tenantId` was requested).
+     */
+    tenantEffect: FeatureOverrideEffect | null;
+    /**
+     * What this feature resolves to for the requested tenant with **no override
+     * of its own** — the state that removing the tenant override would produce,
+     * which is what a management UI must name on its "back to Default" control.
+     *
+     * `null` when no `tenantId` was requested — nothing tenant-inherited was
+     * computed, and the global state is not an answer to a question about a
+     * tenant — and `null` when the tenant holds an override of its own, because
+     * then the inherited state depends on the levels above this tenant, which a
+     * configured `FeatureTenantHierarchyProvider` extends to ancestor tenants'
+     * overrides. It is reported only for a requested tenant with no override of
+     * its own, where the inherited state *is* the effective state. Rows that
+     * leave it `null` get the neutral "Default (inherited)" label in the panel,
+     * never a claim about a state nothing computed.
+     */
+    inheritedEnabled: boolean | null;
+}
+/** Selection for {@link FeatureSettingsService.listFeatureSettings}. */
+export interface ListFeatureSettingsOptions {
+    /**
+     * Tenant whose overrides and effective values to report. Omit for a
+     * global-only view.
+     */
+    tenantId?: string;
+    /** Restrict to one owning package (the usual case for an app's own screen). */
+    packageName?: string;
+    /**
+     * Restrict to an explicit allowlist of keys. Keys with no definition are
+     * simply absent from the result — this filters, it does not validate.
+     */
+    featureKeys?: string[];
+}
+/** One override write requested through {@link FeatureSettingsService}. */
+export interface SetFeatureOverrideRequest {
+    featureKey: string;
+    scopeType: FeatureScopeType;
+    scopeId: string;
+    /**
+     * `INHERIT` removes the override row at that scope, returning the feature to
+     * whatever the next level up resolves to.
+     */
+    effect: FeatureOverrideEffect;
+}
+/**
+ * Thrown when a write names a `featureKey` that has no {@link FeatureDefinition}
+ * row. Nothing is written.
+ *
+ * This is the generalized form of the per-app "is this one of my keys?" guard
+ * every consumer would otherwise hand-roll to keep a form post from creating an
+ * override for an arbitrary string.
+ */
+export declare class UnknownFeatureKeyError extends Error {
+    readonly featureKey: string;
+    readonly status = 400;
+    constructor(featureKey: string);
+}
+/**
+ * Thrown when a write names a scope the resolver would never read back: an
+ * unknown `scopeType`, a global write under anything but
+ * {@link GLOBAL_FEATURE_SCOPE_ID}, or a tenant write with a blank or untrimmed
+ * `scopeId`. Nothing is written.
+ *
+ * `FeatureOverride` rows are looked up by the exact `(featureKey, scopeType,
+ * scopeId)` triple, so a row stored under a scope nothing queries is invisible
+ * state: it never takes effect, and it silently reappears if the scope naming
+ * is ever corrected.
+ */
+export declare class InvalidFeatureScopeError extends Error {
+    readonly scopeType: string;
+    readonly scopeId: string;
+    readonly status = 400;
+    constructor(scopeType: string, scopeId: string, reason: string);
+}
+/** Options for {@link FeatureSettingsService.create}. */
+export interface FeatureSettingsServiceOptions {
+    /**
+     * The host's authorization decision for each override write, bound to the
+     * current caller. **Omitting it makes the service read-only**: every write
+     * then fails closed with `FeatureOverrideAuthorizationError`. This
+     * package never decides who may write.
+     */
+    authorize?: FeatureOverrideAuthorizer;
+    /** Forwarded to {@link FeatureResolver} (e.g. the tenant-hierarchy loader). */
+    resolver?: FeatureResolverOptions;
+}
+/**
+ * Coerce an untrusted value (a form field, a query parameter, a JSON body) to a
+ * {@link FeatureOverrideEffect}. Anything unrecognized — including `null` and
+ * `undefined` — becomes `INHERIT`, i.e. "back to the default", which is the
+ * safe reading of a value the host could not parse.
+ */
+export declare function featureOverrideEffectFromValue(value: unknown): FeatureOverrideEffect;
+/**
+ * Read and write side of a feature-flag management screen, so consumers do not
+ * re-derive the row shape or the unknown-key guard.
+ *
+ * **Authorization stays with the consumer.** This service makes no
+ * authorization decision of its own: reads are unfiltered, and every write is
+ * delegated to {@link FeatureOverrideService}, which asks the host-supplied
+ * {@link FeatureOverrideAuthorizer} first and fails closed. Call it only from
+ * server code that has already established who the caller is. See
+ * `packages/features/README.md` for the consumer recipe.
+ *
+ * **Feature keys are persisted identifiers.** Overrides are stored keyed by the
+ * exact `featureKey` string and resolved by that string at runtime. Renaming a
+ * key orphans every existing override, silently reverting all tenants to the
+ * definition default. Treat a key as immutable once shipped; a rename needs a
+ * data migration, not an edit.
+ */
+export declare class FeatureSettingsService {
+    private readonly definitions;
+    private readonly overrides;
+    private readonly resolver;
+    private readonly writes;
+    constructor(definitions: FeatureDefinitionCollection, overrides: FeatureOverrideCollection, resolver: FeatureResolver, authorize?: FeatureOverrideAuthorizer);
+    /**
+     * Build a service over the given database options.
+     *
+     * @param options - SMRT database options, as passed to any collection.
+     * @param serviceOptions - Host authorizer and resolver wiring. Omit
+     *   `authorize` for a read-only (load-function) service.
+     */
+    static create(options?: SmrtClassOptions, serviceOptions?: FeatureSettingsServiceOptions): Promise<FeatureSettingsService>;
+    /**
+     * One {@link FeatureSettingsRow} per matching definition, ordered by owning
+     * package, then label, then key, so a rendered list is stable across loads.
+     *
+     * Makes no authorization decision — the caller has already decided that this
+     * principal may see this tenant's flags.
+     */
+    listFeatureSettings(options?: ListFeatureSettingsOptions): Promise<FeatureSettingsRow[]>;
+    /** The single row for one key, or `null` when no definition owns that key. */
+    getFeatureSetting(featureKey: string, tenantId?: string): Promise<FeatureSettingsRow | null>;
+    /**
+     * Apply one override change.
+     *
+     * Refuses any `featureKey` without a {@link FeatureDefinition} row and any
+     * scope the resolver would never read back, then delegates to
+     * {@link FeatureOverrideService} so the host authorizer decides whether this
+     * caller may write this scope. `INHERIT` removes the row.
+     *
+     * @returns the stored override, or `null` when the row was removed (or was
+     *   already absent).
+     * @throws {UnknownFeatureKeyError} when the key has no definition.
+     * @throws {InvalidFeatureScopeError} when the scope is not one the resolver reads.
+     * @throws `FeatureOverrideAuthorizationError` when the authorizer declines.
+     */
+    setFeatureOverride(request: SetFeatureOverrideRequest): Promise<FeatureOverride | null>;
+    /** {@link setFeatureOverride} for the global scope. */
+    setGlobalFeatureOverride(featureKey: string, effect: FeatureOverrideEffect): Promise<FeatureOverride | null>;
+    /** {@link setFeatureOverride} for one tenant. */
+    setTenantFeatureOverride(featureKey: string, tenantId: string, effect: FeatureOverrideEffect): Promise<FeatureOverride | null>;
+    private assertKnownFeatureKey;
+    private loadDefinitions;
+    private toRow;
+}
+//# sourceMappingURL=feature-settings.d.ts.map

package/dist/feature-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-settings.d.ts","sourceRoot":"","sources":["../src/feature-settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EACL,KAAK,yBAAyB,EAE/B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EAEtB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,QAAQ,EAAE,eAAe,CAAC;IAC1B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,YAAY,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC3C;;;OAGG;IACH,YAAY,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC3C;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAAC;CAClC;AAED,wEAAwE;AACxE,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,2EAA2E;AAC3E,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAEnC,QAAQ,CAAC,UAAU,EAAE,MAAM;IADvC,QAAQ,CAAC,MAAM,OAAO;gBACD,UAAU,EAAE,MAAM;CAIxC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAG/C,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM;IAH1B,QAAQ,CAAC,MAAM,OAAO;gBAEX,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM;CAKjB;AAED,yDAAyD;AACzD,MAAM,WAAW,6BAA6B;IAC5C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CACnC;AAID;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,qBAAqB,CAMvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAsB;IAI/B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;gBAG7B,WAAW,EAAE,2BAA2B,EACxC,SAAS,EAAE,yBAAyB,EACpC,QAAQ,EAAE,eAAe,EAC1C,SAAS,CAAC,EAAE,yBAAyB;IAQvC;;;;;;OAMG;WACU,MAAM,CACjB,OAAO,GAAE,gBAAqB,EAC9B,cAAc,GAAE,6BAAkC,GACjD,OAAO,CAAC,sBAAsB,CAAC;IAalC;;;;;;OAMG;IACG,mBAAmB,CACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAQhC,8EAA8E;IACxE,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAKrC;;;;;;;;;;;;;OAaG;IACG,kBAAkB,CACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAiBlC,uDAAuD;IACjD,wBAAwB,CAC5B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IASlC,iDAAiD;IAC3C,wBAAwB,CAC5B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;YASpB,qBAAqB;YAWrB,eAAe;YAef,KAAK;CA+BpB"}

package/dist/feature-sync.d.ts

@@ -0,0 +1,17 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { SmartObjectManifest } from '@happyvertical/smrt-core/manifest';
+import { FeatureSyncResult, SyncDefinitionsOptions, SyncManifestOptions } from './types.js';
+export declare class FeatureSyncService {
+    private readonly options;
+    private featureDefinitions;
+    private initializationPromise;
+    constructor(options?: SmrtClassOptions);
+    syncDefinitions(options?: SyncDefinitionsOptions): Promise<FeatureSyncResult>;
+    syncManifest(manifest: SmartObjectManifest, options?: SyncManifestOptions): Promise<FeatureSyncResult>;
+    private ensureInitialized;
+    private collectDefinitionsFromRegistrations;
+    private collectTouchedPackagesFromRegistrations;
+    private collectRegistrations;
+    private applyDefinitions;
+}
+//# sourceMappingURL=feature-sync.d.ts.map

package/dist/feature-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-sync.d.ts","sourceRoot":"","sources":["../src/feature-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAE7E,OAAO,KAAK,EAEV,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AASpB,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,kBAAkB,CAA+B;IACzD,OAAO,CAAC,qBAAqB,CAA8B;gBAE/C,OAAO,GAAE,gBAAqB;IAIpC,eAAe,CACnB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,iBAAiB,CAAC;IAcvB,YAAY,CAChB,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,iBAAiB,CAAC;YAWf,iBAAiB;IAY/B,OAAO,CAAC,mCAAmC;IAY3C,OAAO,CAAC,uCAAuC;IAmB/C,OAAO,CAAC,oBAAoB;YA6Bd,gBAAgB;CA0D/B"}