@beignet/core 0.0.13 → 0.0.15

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @beignet/core
 
+## 0.0.15
+
+### Patch Changes
+
+- 73a682a: Make the type-preserving curried route-group form the canonical Beignet route
+  API across generated apps, docs, READMEs, and examples. `beignet doctor` now
+  warns when feature route groups use the direct generic form, and the direct
+  overload is deprecated because TypeScript erases per-route contract output
+  checks there.
+- 2a02469: Add `createErrorReportingHooks(...)` for capturing unexpected HTTP failures
+  through `ctx.ports.errorReporter`, and wire generated apps to install the hook
+  with a no-op local reporter by default.
+- 7d3c980: Add provider-neutral inbound webhook definitions, verifiers, HMAC verification, memory test verifier, and a generic Next.js webhook route adapter.
+
+## 0.0.14
+
+### Patch Changes
+
+- 0b106c3: Add first-class error reporting primitives and a Sentry-backed error reporting
+  provider.
+- 6828442: Add first-class feature flag primitives, an OpenFeature-backed flags provider,
+  and devtools support for flag evaluation, exposure, and tracking events.
+- edf5ddc: Add first-class entitlement primitives for product access checks, devtools-ready entitlement decision observation, and doctor checks for entitlement wiring drift. Generated billing slices expose a billing-backed entitlements port.
+- bcd3864: Add lease-backed lock primitives and a Redis-backed locks provider.
+- d51a35f: Add the provider-neutral payments port, memory payments adapter, Stripe payments provider, Next.js payment webhook route helper, `beignet make payments`, and first-class payments devtools view.
+- 655c101: Add keyed authorization batch checks and best-effort policy decision observation, plus a first-class devtools watcher/view for policy decision events.
+- bcd3864: Add a provider-neutral search port, memory adapter, and Meilisearch provider.
+
 ## 0.0.13
 
 ### Patch Changes

package/README.md

@@ -8,8 +8,9 @@
 
 This package provides Beignet's framework primitives: contracts, server runtime,
 typed client, use cases, ports, domain helpers, app errors, config, events,
-idempotency, outbox, mail, notifications, schedules, uploads, pagination helpers,
-testing helpers, and OpenAPI generation.
+idempotency, locks, outbox, mail, notifications, payments, search, webhooks,
+feature flags, error reporting, schedules, uploads, entitlements, pagination
+helpers, testing helpers, and OpenAPI generation.
 
 ## Installation
 
@@ -43,18 +44,24 @@ name the framework area they depend on.
 | `@beignet/core/config` | Environment config validation |
 | `@beignet/core/contracts` | HTTP contract builders, types, path helpers, and contract metadata |
 | `@beignet/core/domain` | Entities, value objects, and domain events |
+| `@beignet/core/entitlements` | Product access decision types, helpers, and static entitlement adapter |
+| `@beignet/core/error-reporting` | Error reporting port, memory adapter, no-op adapter, and helpers |
 | `@beignet/core/errors` | Error catalogs and response helpers |
 | `@beignet/core/events` | Events and listeners |
+| `@beignet/core/flags` | Feature flag definitions, FlagsPort, memory/static adapters, and helpers |
 | `@beignet/core/idempotency` | Retry-safe command, webhook, and job primitives |
 | `@beignet/core/jobs` | Job definitions, retry policies, and inline job dispatch |
+| `@beignet/core/locks` | Lease-backed LocksPort, memory adapter, memory provider, and helpers |
 | `@beignet/core/mail` | Mail port, memory mailer, and memory mailer provider |
 | `@beignet/core/notifications` | Notification definitions, dispatchers, inline notifications provider, mail channels, and test adapters |
 | `@beignet/core/openapi` | OpenAPI generation |
 | `@beignet/core/outbox` | Durable event and job outbox |
+| `@beignet/core/payments` | Payments port, memory payments adapter, and memory payments provider |
 | `@beignet/core/pagination` | Offset/cursor page types, normalizers, and result helpers |
 | `@beignet/core/ports` | App-facing ports, auth, audit, policies, cache, storage, logging, and redaction |
 | `@beignet/core/ports/testing` | Port and policy test helpers |
 | `@beignet/core/providers` | Provider lifecycle and instrumentation primitives |
+| `@beignet/core/search` | Search index definitions, SearchPort, memory adapter, memory provider, and helpers |
 | `@beignet/core/schedules` | Schedule primitives |
 | `@beignet/core/server` | Framework-agnostic server runtime and hook helpers |
 | `@beignet/core/server-only` | Static lint marker for modules that must stay out of client bundles |
@@ -63,6 +70,7 @@ name the framework area they depend on.
 | `@beignet/core/tracing` | Dependency-free W3C trace context primitives |
 | `@beignet/core/uploads` | Upload definitions, router, signer port, and test signer |
 | `@beignet/core/uploads/client` | Browser upload client for server and direct uploads |
+| `@beignet/core/webhooks` | Inbound webhook definitions, verifiers, memory test verifier, and HMAC verifier |
 
 ## Durable failure language
 
@@ -177,6 +185,189 @@ Replace `createMemoryMailerProvider(...)` with a real mail provider such as
 keep the inline notifications provider and run it from jobs or listeners, or
 replace it with an app-owned dispatcher when delivery needs custom semantics.
 
+## Entitlements
+
+Use `@beignet/core/entitlements` for product access decisions derived from
+app-owned billing or plan state. The resolver maps durable app state to
+allow/deny decisions; `requireEntitlement(...)` enforces the decision from a
+use case and throws a framework-owned 403 by default.
+
+```typescript
+import {
+  createEntitlements,
+  type EntitlementDecisionObserver,
+  requireEntitlement,
+} from "@beignet/core/entitlements";
+
+function createBillingEntitlements(
+  billing: BillingRepository,
+  recordDecision?: EntitlementDecisionObserver,
+) {
+  return createEntitlements({
+    async inspect(input) {
+      const account = await billing.findByTenantId(input.subject.id);
+      return account?.status === "active";
+    },
+    onDecision: recordDecision,
+  });
+}
+
+await requireEntitlement(ctx, {
+  entitlement: "todos.create",
+  subject: { type: "tenant", id: tenantId },
+});
+```
+
+`onDecision` is diagnostic only. Observer errors are ignored and cannot change
+the entitlement result.
+
+## Feature flags
+
+Use `@beignet/core/flags` for typed feature flag definitions and
+provider-neutral evaluation. Flags always carry a default value, and provider
+failures return that default instead of throwing into product workflows.
+
+```typescript
+import { defineFlag, defineFlags } from "@beignet/core/flags";
+
+export const billingFlags = defineFlags({
+  newCheckout: defineFlag.boolean("billing.new-checkout", {
+    default: false,
+  }),
+});
+
+const enabled = await ctx.ports.flags.evaluate(billingFlags.newCheckout, {
+  context: {
+    targetingKey: ctx.actor.id,
+    tenant: ctx.tenant,
+    requestId: ctx.requestId,
+  },
+});
+```
+
+Plain evaluation does not record exposure. Call `recordExposure(...)`
+explicitly when a user actually sees or can be affected by the flagged
+behavior. Use `createMemoryFlags(...)` or `createStaticFlags(...)` in tests, or
+install `@beignet/provider-flags-openfeature` for production providers.
+String and number flags widen to `string` and `number` by default; pass a
+generic when an app wants a closed variant union.
+
+## Error reporting
+
+Use `@beignet/core/error-reporting` for provider-neutral exception and message
+capture. The port accepts severity, tags, user, contexts, extra metadata, and
+request/trace correlation IDs.
+
+```typescript
+import { createMemoryErrorReporter } from "@beignet/core/error-reporting";
+import { createErrorReportingHooks } from "@beignet/core/server";
+import type { AppContext } from "@/app-context";
+
+await ctx.ports.errorReporter.captureException(error, {
+  level: "error",
+  requestId: ctx.requestId,
+  traceId: ctx.traceId,
+  tags: { feature: "billing" },
+});
+
+const errorReporter = createMemoryErrorReporter();
+
+export const hooks = [createErrorReportingHooks<AppContext>()];
+```
+
+Use `createMemoryErrorReporter(...)` in tests, `createNoopErrorReporter()` when
+an app needs a bound port without capture, and
+`createErrorReportingHooks(...)` in `server/index.ts` to capture unexpected HTTP
+failures without changing response mapping. Install
+`@beignet/provider-error-reporting-sentry` for production providers.
+
+## Locks and leases
+
+Use `@beignet/core/locks` for provider-neutral lease-backed lock coordination.
+Locks prevent overlapping schedules, singleton jobs, cache stampedes, and short
+critical sections across multiple workers or servers.
+
+```typescript
+import { createMemoryLocks } from "@beignet/core/locks";
+
+await ctx.ports.locks.withLease(
+  "schedule:daily-report",
+  { ttlMs: 60_000, waitMs: 0 },
+  async ({ lease }) => {
+    await runDailyReport(ctx, { fencingToken: lease.fencingToken });
+  },
+);
+
+const locks = createMemoryLocks();
+```
+
+Use `createMemoryLocks(...)` in tests, `createMemoryLocksProvider()` for local
+provider wiring, or install `@beignet/provider-locks-redis` for production
+leases.
+
+## Search
+
+Use `@beignet/core/search` for provider-neutral search index definitions,
+document indexing, and querying searchable read models.
+
+```typescript
+import { defineSearchIndex } from "@beignet/core/search";
+
+const issueSearchIndex = defineSearchIndex("issues", {
+  searchableAttributes: ["key", "title", "description"],
+  filterableAttributes: ["tenantId", "status"],
+  sortableAttributes: ["createdAt"],
+});
+
+await ctx.ports.search.indexDocuments(issueSearchIndex, issueDocument);
+
+const results = await ctx.ports.search.search(issueSearchIndex, {
+  query: "billing",
+  filters: { tenantId },
+  sort: ["createdAt:desc"],
+  limit: 20,
+});
+```
+
+Use `createMemorySearch(...)` in tests, `createMemorySearchProvider()` for local
+provider wiring, or install `@beignet/provider-search-meilisearch` for
+production search.
+
+## Webhooks
+
+Use `@beignet/core/webhooks` for provider-neutral inbound webhook definitions,
+raw-body verification, typed event payload catalogs, and test verifiers.
+
+```typescript
+import {
+  createHmacWebhookVerifier,
+  defineWebhook,
+} from "@beignet/core/webhooks";
+import { z } from "zod";
+
+export const issueWebhook = defineWebhook("issues.provider", {
+  provider: "provider",
+  events: {
+    "issue.created": z.object({
+      id: z.string(),
+      type: z.literal("issue.created"),
+      issueId: z.string(),
+    }),
+  },
+  verifier: createHmacWebhookVerifier({
+    secret: process.env.PROVIDER_WEBHOOK_SECRET ?? "",
+    signatureHeader: "x-provider-signature",
+    signaturePrefix: "sha256=",
+  }),
+});
+```
+
+Use `createMemoryWebhookVerifier(...)` in tests and `createWebhookRoute(...)`
+from `@beignet/next` to expose raw-body webhook routes in Next.js apps. Use a
+provider package such as `@beignet/provider-webhooks-github` or
+`@beignet/provider-webhooks-stripe` when a vendor has signature semantics beyond
+the generic HMAC verifier.
+
 ## Provider metadata
 
 Reusable provider packages should declare static metadata in `package.json`
@@ -665,6 +856,11 @@ await tester.assertMatrix([
   },
 ]);
 
+const permissions = await tester.gate.canMany(activity, {
+  publish: ["posts.publish", post],
+});
+expect(permissions.publish).toBe(true);
+
 assertAuditEntry(audit.entries, {
   action: "posts.publish",
   actorId: "user_1",

package/dist/entitlements/index.d.ts

@@ -0,0 +1,234 @@
+/**
+ * @beignet/core/entitlements
+ *
+ * Provider-neutral product access primitives for Beignet applications.
+ */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Stable app-defined capability key, such as "issues.create".
+ */
+export type EntitlementKey = string;
+/**
+ * Principal whose product access is being checked.
+ */
+export type EntitlementSubject = {
+    /**
+     * App-defined subject type, commonly "tenant" or "account".
+     */
+    type: string;
+    /**
+     * Stable subject identifier.
+     */
+    id: string;
+};
+/**
+ * Input for checking whether a subject has access to a capability.
+ */
+export type EntitlementCheckInput<TKey extends EntitlementKey = EntitlementKey> = {
+    /**
+     * Capability being checked.
+     */
+    entitlement: TKey;
+    /**
+     * Tenant, account, or other app-owned subject whose product access is checked.
+     */
+    subject: EntitlementSubject;
+};
+/**
+ * An entitlement decision that allows the capability.
+ */
+export type EntitlementAllowedDecision = {
+    allowed: true;
+};
+/**
+ * An entitlement decision that denies the capability.
+ */
+export type EntitlementDeniedDecision = {
+    allowed: false;
+    reason?: string;
+    code?: string;
+    details?: unknown;
+};
+/**
+ * Normalized entitlement decision.
+ */
+export type EntitlementDecision = EntitlementAllowedDecision | EntitlementDeniedDecision;
+/**
+ * Value an entitlement resolver may return.
+ */
+export type EntitlementResolverResult = boolean | EntitlementDecision;
+/**
+ * Entitlement port method that produced a decision.
+ */
+export type EntitlementDecisionSource = "can" | "inspect" | "require";
+/**
+ * Optional context for entitlement checks.
+ */
+export type EntitlementCheckOptions<TContext = unknown> = {
+    /**
+     * Application context used for the check. Observers can use this to copy
+     * request correlation fields without coupling the resolver to app context.
+     */
+    ctx?: TContext;
+    /**
+     * Source to report to observers. Port methods set this automatically.
+     */
+    source?: EntitlementDecisionSource;
+};
+/**
+ * App-facing product access port.
+ */
+export type EntitlementsPort<TKey extends EntitlementKey = EntitlementKey, TContext = unknown> = {
+    /**
+     * Return only whether the capability is allowed.
+     */
+    can(input: EntitlementCheckInput<TKey>, options?: EntitlementCheckOptions<TContext>): Promise<boolean>;
+    /**
+     * Return the full allow/deny decision without throwing.
+     */
+    inspect(input: EntitlementCheckInput<TKey>, options?: EntitlementCheckOptions<TContext>): Promise<EntitlementDecision>;
+};
+/**
+ * Function that decides whether an entitlement is granted.
+ */
+export type EntitlementResolver<TKey extends EntitlementKey = EntitlementKey> = (input: EntitlementCheckInput<TKey>) => MaybePromise<EntitlementResolverResult>;
+/**
+ * Best-effort entitlement decision observation emitted by an entitlements port.
+ *
+ * Observers are diagnostic only. They do not participate in entitlement
+ * control flow and thrown/rejected observer errors are ignored.
+ */
+export type EntitlementDecisionObservation<TContext = unknown, TKey extends EntitlementKey = EntitlementKey> = {
+    /**
+     * Port helper that produced the decision.
+     */
+    source: EntitlementDecisionSource;
+    /**
+     * Application context passed by the caller, when available.
+     */
+    ctx?: TContext;
+    /**
+     * Capability being evaluated.
+     */
+    entitlement: TKey;
+    /**
+     * Subject whose product access is checked.
+     */
+    subject: EntitlementSubject;
+    /**
+     * Normalized decision, when resolver evaluation returned normally.
+     */
+    decision?: EntitlementDecision;
+    /**
+     * Error thrown by the resolver, when evaluation failed.
+     */
+    error?: unknown;
+    /**
+     * Resolver duration, excluding observer work.
+     */
+    durationMs: number;
+    /**
+     * Correlation fields copied from the context when present.
+     */
+    requestId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    traceparent?: string;
+};
+/**
+ * Best-effort observer called after each entitlement decision or resolver
+ * error.
+ */
+export type EntitlementDecisionObserver<TContext = unknown, TKey extends EntitlementKey = EntitlementKey> = (observation: EntitlementDecisionObservation<TContext, TKey>) => MaybePromise<void>;
+/**
+ * Options for `createEntitlements(...)`.
+ */
+export type CreateEntitlementsOptions<TKey extends EntitlementKey = EntitlementKey, TContext = unknown> = {
+    /**
+     * Resolver that maps app-owned product state to an entitlement decision.
+     */
+    inspect: EntitlementResolver<TKey>;
+    /**
+     * Optional best-effort observer for entitlement decisions.
+     *
+     * This hook is diagnostic only: it cannot change decisions or thrown errors.
+     */
+    onDecision?: EntitlementDecisionObserver<TContext, TKey>;
+};
+/**
+ * Static grant map keyed by subject key.
+ */
+export type StaticEntitlementGrantMap<TKey extends EntitlementKey = EntitlementKey> = Record<string, readonly TKey[]>;
+/**
+ * Options for `createStaticEntitlements(...)`.
+ */
+export type CreateStaticEntitlementsOptions<TKey extends EntitlementKey = EntitlementKey, TContext = unknown> = {
+    /**
+     * Granted capabilities keyed by subject. The default key is
+     * `${subject.type}:${subject.id}`.
+     */
+    grants: StaticEntitlementGrantMap<TKey>;
+    /**
+     * Optional subject key mapper.
+     */
+    subjectKey?: (subject: EntitlementSubject) => string;
+    /**
+     * Default denial decision fields.
+     */
+    denied?: Omit<EntitlementDeniedDecision, "allowed">;
+    /**
+     * Optional best-effort observer for entitlement decisions.
+     */
+    onDecision?: EntitlementDecisionObserver<TContext, TKey>;
+};
+/**
+ * Options accepted by `requireEntitlement(...)`.
+ */
+export type RequireEntitlementOptions<TKey extends EntitlementKey = EntitlementKey> = {
+    /**
+     * Create the error to throw instead of the framework default.
+     */
+    error?: (decision: EntitlementDeniedDecision, input: EntitlementCheckInput<TKey>) => unknown;
+};
+/**
+ * Context shape consumed by `requireEntitlement(...)`.
+ */
+export type EntitlementsContext<TKey extends EntitlementKey = EntitlementKey> = {
+    ports: {
+        entitlements: EntitlementsPort<TKey>;
+    };
+};
+/**
+ * Error thrown by `requireEntitlement(...)` when product access is denied.
+ */
+export declare class EntitlementRequiredError extends Error {
+    readonly code: string;
+    readonly status = 403;
+    readonly details?: unknown;
+    readonly entitlement: string;
+    readonly subject: EntitlementSubject;
+    constructor(input: EntitlementCheckInput, decision?: EntitlementDeniedDecision);
+}
+/**
+ * Create an explicit allow decision.
+ */
+export declare function allowEntitlement(): EntitlementAllowedDecision;
+/**
+ * Create an explicit deny decision.
+ */
+export declare function denyEntitlement(reasonOrDecision?: string | Omit<EntitlementDeniedDecision, "allowed">): EntitlementDeniedDecision;
+/**
+ * Create an entitlement port from an app-owned resolver.
+ */
+export declare function createEntitlements<TKey extends EntitlementKey = EntitlementKey, TContext = unknown>(options: CreateEntitlementsOptions<TKey, TContext>): EntitlementsPort<TKey, TContext>;
+/**
+ * Create a static entitlement port for tests, starters, and simple apps.
+ */
+export declare function createStaticEntitlements<TKey extends EntitlementKey = EntitlementKey, TContext = unknown>(options: CreateStaticEntitlementsOptions<TKey, TContext>): EntitlementsPort<TKey, TContext>;
+/**
+ * Require an entitlement or throw a framework-owned 403 error.
+ */
+export declare function requireEntitlement<TKey extends EntitlementKey = EntitlementKey>(ctx: EntitlementsContext<TKey>, input: EntitlementCheckInput<TKey>, options?: RequireEntitlementOptions<TKey>): Promise<EntitlementAllowedDecision>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/entitlements/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entitlements/index.ts"],"names":[],"mappings":"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"}

package/dist/entitlements/index.js

@@ -0,0 +1,172 @@
+/**
+ * @beignet/core/entitlements
+ *
+ * Provider-neutral product access primitives for Beignet applications.
+ */
+/**
+ * Error thrown by `requireEntitlement(...)` when product access is denied.
+ */
+export class EntitlementRequiredError extends Error {
+    code;
+    status = 403;
+    details;
+    entitlement;
+    subject;
+    constructor(input, decision = denyEntitlement()) {
+        super(decision.reason ??
+            `Entitlement "${input.entitlement}" is required for this action.`);
+        this.name = "EntitlementRequiredError";
+        this.code = decision.code ?? "ENTITLEMENT_REQUIRED";
+        this.details = decision.details;
+        this.entitlement = input.entitlement;
+        this.subject = input.subject;
+    }
+}
+/**
+ * Create an explicit allow decision.
+ */
+export function allowEntitlement() {
+    return { allowed: true };
+}
+/**
+ * Create an explicit deny decision.
+ */
+export function denyEntitlement(reasonOrDecision) {
+    if (typeof reasonOrDecision === "string") {
+        return { allowed: false, reason: reasonOrDecision };
+    }
+    return {
+        allowed: false,
+        ...reasonOrDecision,
+    };
+}
+/**
+ * Create an entitlement port from an app-owned resolver.
+ */
+export function createEntitlements(options) {
+    const observeDecision = createDecisionObserver(options.onDecision);
+    async function evaluate(input, checkOptions) {
+        const startedAt = entitlementNow();
+        try {
+            const decision = normalizeEntitlementDecision(await options.inspect(input));
+            observeDecision({
+                source: checkOptions?.source ?? "inspect",
+                ctx: checkOptions?.ctx,
+                entitlement: input.entitlement,
+                subject: input.subject,
+                decision,
+                durationMs: entitlementNow() - startedAt,
+            });
+            return decision;
+        }
+        catch (error) {
+            observeDecision({
+                source: checkOptions?.source ?? "inspect",
+                ctx: checkOptions?.ctx,
+                entitlement: input.entitlement,
+                subject: input.subject,
+                error,
+                durationMs: entitlementNow() - startedAt,
+            });
+            throw error;
+        }
+    }
+    return {
+        async can(input, checkOptions) {
+            return (await evaluate(input, { ...checkOptions, source: "can" }))
+                .allowed;
+        },
+        inspect(input, checkOptions) {
+            return evaluate(input, {
+                ...checkOptions,
+                source: checkOptions?.source ?? "inspect",
+            });
+        },
+    };
+}
+/**
+ * Create a static entitlement port for tests, starters, and simple apps.
+ */
+export function createStaticEntitlements(options) {
+    const subjectKey = options.subjectKey ?? defaultSubjectKey;
+    return createEntitlements({
+        inspect(input) {
+            const granted = options.grants[subjectKey(input.subject)] ?? [];
+            if (granted.includes(input.entitlement))
+                return allowEntitlement();
+            return denyEntitlement({
+                reason: `Entitlement "${input.entitlement}" is not granted.`,
+                code: "ENTITLEMENT_NOT_GRANTED",
+                details: {
+                    entitlement: input.entitlement,
+                    subject: input.subject,
+                },
+                ...options.denied,
+            });
+        },
+        onDecision: options.onDecision,
+    });
+}
+/**
+ * Require an entitlement or throw a framework-owned 403 error.
+ */
+export async function requireEntitlement(ctx, input, options) {
+    const decision = await ctx.ports.entitlements.inspect(input, {
+        ctx,
+        source: "require",
+    });
+    if (decision.allowed)
+        return decision;
+    throw options?.error
+        ? options.error(decision, input)
+        : new EntitlementRequiredError(input, decision);
+}
+function normalizeEntitlementDecision(result) {
+    if (typeof result === "boolean") {
+        return result ? allowEntitlement() : denyEntitlement();
+    }
+    return result;
+}
+function entitlementNow() {
+    return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function contextStringField(ctx, field) {
+    if (!ctx || typeof ctx !== "object")
+        return undefined;
+    const value = ctx[field];
+    return typeof value === "string" ? value : undefined;
+}
+function enrichObservation(observation) {
+    return {
+        ...observation,
+        requestId: contextStringField(observation.ctx, "requestId"),
+        traceId: contextStringField(observation.ctx, "traceId"),
+        spanId: contextStringField(observation.ctx, "spanId"),
+        parentSpanId: contextStringField(observation.ctx, "parentSpanId"),
+        traceparent: contextStringField(observation.ctx, "traceparent"),
+    };
+}
+function isPromiseLike(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+function createDecisionObserver(observer) {
+    return (observation) => {
+        if (!observer)
+            return;
+        try {
+            const result = observer(enrichObservation(observation));
+            if (isPromiseLike(result)) {
+                Promise.resolve(result).catch(() => undefined);
+            }
+        }
+        catch {
+            // Observers are diagnostic only and must not affect entitlement checks.
+        }
+    };
+}
+function defaultSubjectKey(subject) {
+    return `${subject.type}:${subject.id}`;
+}
+//# sourceMappingURL=index.js.map