@baruk/core 0.1.0 → 0.3.0

package/dist/entitlements/decision.js

@@ -0,0 +1,196 @@
+import { normalizeEntitlementSource, sourcePrecedence } from './sources.js';
+import { isStandingOk } from './standing.js';
+/**
+ * Decision API canônica (contrato 1.0.0 — ENTITLEMENTS_CONTRACT_SPEC_2026-07-27.md
+ * §8-§10, §14). EXTENSÃO/facade sobre `deriveEntitlements`/`hasActiveEntitlement`
+ * (`derive.ts`, intactas) — pura, determinística, sem DB/rede/NestJS/mvb. Todos
+ * os fatos externos (standing, limites, uso, flag operacional) são injetados
+ * pelo consumidor via `EntitlementContext` — nunca resolvidos aqui.
+ */
+export const ENTITLEMENTS_CONTRACT_VERSION = '1.0.0';
+/** `moduleCode` normalizado para comparação (trim + lowercase) — §4. Não reescreve os dados persistidos. */
+function normalizeModuleCodeKey(moduleCode) {
+    return moduleCode.trim().toLowerCase();
+}
+function isValidModuleCode(moduleCode) {
+    return /^[a-z][a-z0-9_-]{1,63}$/i.test(moduleCode.trim());
+}
+function isRecordActiveNow(e, now) {
+    if (!e.active)
+        return false;
+    if (e.expiresAt != null && e.expiresAt < now)
+        return false;
+    return true;
+}
+function isExplicitDeny(e) {
+    // BETA é alias legado de MANUAL (§5). O deny explícito deve ser alias-invariante:
+    // avaliar a fonte NORMALIZADA (canonical), nunca o valor bruto persistido — do
+    // contrário um grant BETA + `metadata.deny` escaparia do deny e concederia acesso.
+    return normalizeEntitlementSource(e.source).canonical === 'MANUAL' && e.metadata?.deny === true;
+}
+/** Entitlements ativos do subject, isolados por tenant (nunca vaza entre tenants) — §7/§11. */
+export function getEffectiveEntitlements(subject, ctx) {
+    if (!subject.tenantId)
+        return [];
+    return ctx.entitlements.filter((e) => e.tenantId === subject.tenantId && isRecordActiveNow(e, ctx.now));
+}
+/** Composição pura de limite declarado + uso injetado — sem medir, sem enforcement (§14). */
+export function getLimits(subject, moduleCode, ctx) {
+    if (!subject.tenantId || !ctx.grantedLimits?.length)
+        return [];
+    const key = normalizeModuleCodeKey(moduleCode);
+    return ctx.grantedLimits
+        .filter((g) => normalizeModuleCodeKey(g.moduleCode) === key)
+        .map((definition) => {
+        const usage = ctx.usage?.find((u) => normalizeModuleCodeKey(u.moduleCode) === key && u.limitKey === definition.limitKey);
+        if (definition.value == null) {
+            return { definition, usage, remaining: null };
+        }
+        if (!usage) {
+            return { definition, usage: undefined, remaining: undefined };
+        }
+        return { definition, usage, remaining: definition.value - usage.consumed };
+    });
+}
+/**
+ * Decisão completa e explicável (formaliza `AccessDecision{allowed,reason}` do
+ * mvb, adicionando `reasonCode` estável). Ordem de avaliação (§7/§10/§11):
+ * tenant context → deny explícito → entitlement (ativo/expirado/ausente) →
+ * standing → limite consumível esgotado → flag operacional → allow.
+ */
+export function explainDecision(subject, moduleCode, ctx) {
+    const base = {
+        moduleCode,
+        tenantId: subject.tenantId,
+        standing: ctx.standing,
+        policyVersion: ENTITLEMENTS_CONTRACT_VERSION,
+        evaluatedAt: ctx.now,
+    };
+    if (!subject.tenantId || !subject.tenantId.trim()) {
+        return {
+            ...base,
+            allowed: false,
+            reasonCode: 'TENANT_CONTEXT_MISSING',
+            reason: 'tenantId ausente ou vazio — decisão fina nunca cruza tenants',
+            sources: [],
+            effectiveUntil: null,
+        };
+    }
+    if (!isValidModuleCode(moduleCode)) {
+        return {
+            ...base,
+            allowed: false,
+            reasonCode: 'ENTITLEMENT_MISSING',
+            reason: `moduleCode inválido: "${moduleCode}"`,
+            sources: [],
+            effectiveUntil: null,
+        };
+    }
+    // Tenant isolation: só registros do próprio tenant influenciam a decisão (§11).
+    const key = normalizeModuleCodeKey(moduleCode);
+    const tenantRecords = ctx.entitlements.filter((e) => e.tenantId === subject.tenantId);
+    const matching = tenantRecords.filter((e) => normalizeModuleCodeKey(e.moduleCode) === key);
+    const deny = matching.find((e) => isExplicitDeny(e) && isRecordActiveNow(e, ctx.now));
+    if (deny) {
+        return {
+            ...base,
+            allowed: false,
+            reasonCode: 'EXPLICIT_DENY',
+            reason: 'override MANUAL nega explicitamente este módulo',
+            sources: ['MANUAL'],
+            effectiveUntil: deny.expiresAt,
+        };
+    }
+    // FAIL_OPEN_PRIVILEGED: fato explícito injetado (nunca inferido) — ainda assim
+    // respeita um deny explícito (checado acima), mas ignora ausência/expiração.
+    if (ctx.failOpenPrivileged) {
+        return {
+            ...base,
+            allowed: true,
+            reasonCode: 'FAIL_OPEN_PRIVILEGED',
+            reason: 'fail-open: subject privilegiado (fato injetado pelo consumidor)',
+            sources: [],
+            effectiveUntil: null,
+        };
+    }
+    const active = matching.filter((e) => isRecordActiveNow(e, ctx.now));
+    if (active.length === 0) {
+        const hadAnyRecord = matching.length > 0;
+        return {
+            ...base,
+            allowed: false,
+            reasonCode: hadAnyRecord ? 'ENTITLEMENT_EXPIRED' : 'ENTITLEMENT_MISSING',
+            reason: hadAnyRecord
+                ? 'entitlement encontrado mas expirado/inativo'
+                : 'nenhum entitlement para este módulo',
+            sources: [],
+            effectiveUntil: null,
+        };
+    }
+    const normalizedSources = active.map((e) => normalizeEntitlementSource(e.source));
+    const winner = normalizedSources.reduce((best, cur) => sourcePrecedence(cur) < sourcePrecedence(best) ? cur : best);
+    const canonicalSources = Array.from(new Set(normalizedSources
+        .filter((s) => s.canonical != null)
+        .map((s) => s.canonical)));
+    const hasUnboundedGrant = active.some((e) => e.expiresAt == null);
+    const effectiveUntil = hasUnboundedGrant
+        ? null
+        : active.reduce((min, e) => (min == null || e.expiresAt < min ? e.expiresAt : min), null);
+    if (!isStandingOk(ctx.standing)) {
+        return {
+            ...base,
+            allowed: false,
+            reasonCode: 'SUBSCRIPTION_BLOCKED',
+            reason: ctx.standing.reasonCode === 'SUBSCRIPTION_RESTRICTED'
+                ? 'standing restrito'
+                : 'standing bloqueado',
+            sources: canonicalSources,
+            effectiveUntil,
+        };
+    }
+    if (ctx.standing.accessLevel === 'RESTRICTED') {
+        return {
+            ...base,
+            allowed: false,
+            reasonCode: 'SUBSCRIPTION_RESTRICTED',
+            reason: 'standing restrito: módulo bloqueado para read/core-only',
+            sources: canonicalSources,
+            effectiveUntil,
+        };
+    }
+    const limits = getLimits(subject, moduleCode, ctx);
+    const exhausted = limits.find((l) => l.definition.value != null && l.remaining != null && l.remaining <= 0);
+    if (exhausted) {
+        return {
+            ...base,
+            allowed: false,
+            reasonCode: 'LIMIT_REACHED',
+            reason: `limite "${exhausted.definition.limitKey}" esgotado`,
+            sources: canonicalSources,
+            effectiveUntil,
+        };
+    }
+    if (ctx.operationalFlag === false) {
+        return {
+            ...base,
+            allowed: false,
+            reasonCode: 'FEATURE_DISABLED_OPERATIONALLY',
+            reason: 'kill-switch operacional desabilitado para este módulo',
+            sources: canonicalSources,
+            effectiveUntil,
+        };
+    }
+    return {
+        ...base,
+        allowed: true,
+        reasonCode: 'ENTITLEMENT_ACTIVE',
+        reason: `allowed via ${winner.canonical ?? 'unknown source'}`,
+        sources: canonicalSources,
+        effectiveUntil,
+    };
+}
+/** Facade booleana — composição de `explainDecision` (§8). */
+export function can(subject, moduleCode, ctx) {
+    return explainDecision(subject, moduleCode, ctx).allowed;
+}
+//# sourceMappingURL=decision.js.map

package/dist/entitlements/decision.js.map

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

package/dist/entitlements/derive.d.ts

@@ -0,0 +1,30 @@
+import type { EntitlementRecord, EntitlementSource } from './types.js';
+/**
+ * Derivação PURA de entitlements a partir do conjunto-alvo de módulos de uma
+ * Offer aceita. Espelha a disciplina do subscription-billing: idempotente
+ * (reaplicar o mesmo alvo é no-op de conteúdo), nunca apaga (downgrade
+ * desativa — `active: false` —, não remove o registro).
+ */
+export interface TargetModuleGrant {
+    moduleCode: string;
+    source: EntitlementSource;
+    /** null = concessão sem expiração (ex.: módulo do plano, enquanto a assinatura estiver ativa). */
+    expiresAt: string | null;
+}
+export interface DeriveEntitlementsInput {
+    tenantId: string;
+    subscriptionId: string | null;
+    /** O conjunto de módulos que DEVEM estar ativos agora (da Offer aceita + concessões de cupom/campanha). */
+    targetGrants: TargetModuleGrant[];
+    current: EntitlementRecord[];
+    now: string;
+}
+/**
+ * Resolve o próximo estado de entitlements: ativa o que está no alvo (preserva
+ * `grantedAt` original se já existia), desativa (soft-disable) o que não está
+ * mais no alvo. Concessões expiradas (`expiresAt < now`) nunca entram ativas.
+ */
+export declare function deriveEntitlements(input: DeriveEntitlementsInput): EntitlementRecord[];
+/** True se o tenant tem o módulo ativo agora (lookup rápido, mesmo padrão do `manga-verde-bi/access`). */
+export declare function hasActiveEntitlement(entitlements: EntitlementRecord[], moduleCode: string, now: string): boolean;
+//# sourceMappingURL=derive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/entitlements/derive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,kGAAkG;IAClG,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2GAA2G;IAC3G,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,iBAAiB,EAAE,CA8BtF;AAED,0GAA0G;AAC1G,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,iBAAiB,EAAE,EACjC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAKT"}

package/dist/entitlements/derive.js

@@ -0,0 +1,42 @@
+/**
+ * Resolve o próximo estado de entitlements: ativa o que está no alvo (preserva
+ * `grantedAt` original se já existia), desativa (soft-disable) o que não está
+ * mais no alvo. Concessões expiradas (`expiresAt < now`) nunca entram ativas.
+ */
+export function deriveEntitlements(input) {
+    const { tenantId, subscriptionId, targetGrants, current, now } = input;
+    const currentByModule = new Map(current.map((e) => [e.moduleCode, e]));
+    const targetCodes = new Set(targetGrants.map((g) => g.moduleCode));
+    const next = [];
+    for (const grant of targetGrants) {
+        const isExpired = grant.expiresAt != null && grant.expiresAt < now;
+        const existing = currentByModule.get(grant.moduleCode);
+        next.push({
+            tenantId,
+            subscriptionId,
+            moduleCode: grant.moduleCode,
+            source: grant.source,
+            active: !isExpired,
+            expiresAt: grant.expiresAt,
+            grantedAt: existing?.grantedAt ?? now,
+            metadata: existing?.metadata,
+        });
+    }
+    // Módulos que o tenant tinha e não estão mais no alvo → soft-disable (nunca remove o registro).
+    for (const existing of current) {
+        if (!targetCodes.has(existing.moduleCode)) {
+            next.push({ ...existing, active: false });
+        }
+    }
+    return next;
+}
+/** True se o tenant tem o módulo ativo agora (lookup rápido, mesmo padrão do `manga-verde-bi/access`). */
+export function hasActiveEntitlement(entitlements, moduleCode, now) {
+    const e = entitlements.find((x) => x.moduleCode === moduleCode);
+    if (!e || !e.active)
+        return false;
+    if (e.expiresAt != null && e.expiresAt < now)
+        return false;
+    return true;
+}
+//# sourceMappingURL=derive.js.map

package/dist/entitlements/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../src/entitlements/derive.ts"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA8B;IAC/D,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;IACvE,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IAEnE,MAAM,IAAI,GAAwB,EAAE,CAAC;IAErC,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC;QACnE,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,CAAC;YACR,QAAQ;YACR,cAAc;YACd,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,CAAC,SAAS;YAClB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,GAAG;YACrC,QAAQ,EAAE,QAAQ,EAAE,QAAQ;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,gGAAgG;IAChG,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC/B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,oBAAoB,CAClC,YAAiC,EACjC,UAAkB,EAClB,GAAW;IAEX,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC;IAChE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,CAAC,CAAC,SAAS,IAAI,IAAI,IAAI,CAAC,CAAC,SAAS,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/entitlements/index.d.ts

@@ -0,0 +1,10 @@
+export type { EntitlementSource, EntitlementRecord } from './types.js';
+export type { TargetModuleGrant, DeriveEntitlementsInput } from './derive.js';
+export { deriveEntitlements, hasActiveEntitlement } from './derive.js';
+export { CANONICAL_ENTITLEMENT_SOURCES, LEGACY_SOURCE_ALIAS, normalizeEntitlementSource, sourcePrecedence, } from './sources.js';
+export type { NormalizedSource } from './sources.js';
+export { normalizeSubscriptionStanding, isStandingOk } from './standing.js';
+export type { AccessLevel, SubscriptionStanding } from './standing.js';
+export { ENTITLEMENTS_CONTRACT_VERSION, can, explainDecision, getEffectiveEntitlements, getLimits, } from './decision.js';
+export type { ReasonCode, EntitlementSubject, EntitlementContext, DecisionResult, LimitDefinition, GrantedLimit, UsageSnapshot, LimitView, } from './decision.js';
+//# 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":"AAEA,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAIvE,OAAO,EACL,6BAA6B,EAC7B,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,6BAA6B,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC5E,YAAY,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EACL,6BAA6B,EAC7B,GAAG,EACH,eAAe,EACf,wBAAwB,EACxB,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,aAAa,EACb,SAAS,GACV,MAAM,eAAe,CAAC"}

package/dist/entitlements/index.js

@@ -0,0 +1,7 @@
+export { deriveEntitlements, hasActiveEntitlement } from './derive.js';
+// Contrato canônico 1.0.0 (P2 — Core Contract Alignment, ENTITLEMENTS_CONTRACT_SPEC_2026-07-27.md).
+// Extensão aditiva: deriveEntitlements/hasActiveEntitlement acima permanecem intactas.
+export { CANONICAL_ENTITLEMENT_SOURCES, LEGACY_SOURCE_ALIAS, normalizeEntitlementSource, sourcePrecedence, } from './sources.js';
+export { normalizeSubscriptionStanding, isStandingOk } from './standing.js';
+export { ENTITLEMENTS_CONTRACT_VERSION, can, explainDecision, getEffectiveEntitlements, getLimits, } from './decision.js';
+//# sourceMappingURL=index.js.map

package/dist/entitlements/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entitlements/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEvE,oGAAoG;AACpG,uFAAuF;AACvF,OAAO,EACL,6BAA6B,EAC7B,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,6BAA6B,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE5E,OAAO,EACL,6BAA6B,EAC7B,GAAG,EACH,eAAe,EACf,wBAAwB,EACxB,SAAS,GACV,MAAM,eAAe,CAAC"}

package/dist/entitlements/sources.d.ts

@@ -0,0 +1,30 @@
+import type { EntitlementSource } from './types.js';
+/**
+ * Fontes canônicas (contrato 1.0.0 — ENTITLEMENTS_CONTRACT_SPEC_2026-07-27.md §5).
+ * Superset das 6 já existentes em `types.ts` — nenhuma removida, nenhuma renomeada.
+ */
+export declare const CANONICAL_ENTITLEMENT_SOURCES: readonly EntitlementSource[];
+/** Alias legado (mvb `Entitlement.source = 'BETA'`) — nunca reescrito em massa. */
+export declare const LEGACY_SOURCE_ALIAS = "BETA";
+export interface NormalizedSource {
+    /** Valor bruto como persistido (ex.: `"BETA"`, `"PLAN"`, ou algo desconhecido). */
+    raw: string;
+    /** Fonte canônica após aplicar o alias `BETA → MANUAL`; `null` se `raw` for desconhecido. */
+    canonical: EntitlementSource | null;
+    /** true se `raw` não é canônico nem o alias legado — honrado, mas com precedência mínima. */
+    isUnknown: boolean;
+    /** Preservado apenas quando `raw` era o alias legado (`legacySource: "BETA"`). */
+    legacySource?: string;
+}
+/**
+ * Normaliza uma fonte bruta (persistida) para o conjunto canônico.
+ * - `BETA` → `MANUAL` + `legacySource: "BETA"` (compat, sem migração destrutiva).
+ * - Valor canônico → passthrough.
+ * - Valor desconhecido (forward-compat) → `canonical: null`, `isUnknown: true`; o
+ *   grant continua sendo honrado se `active`, mas nunca finge ser uma fonte
+ *   canônica — evita ganhar autoridade por acidente (§5/§10 da Contract Spec).
+ */
+export declare function normalizeEntitlementSource(raw: string): NormalizedSource;
+/** Precedência de uma fonte normalizada — menor valor = mais forte; desconhecida = mínima. */
+export declare function sourcePrecedence(source: NormalizedSource): number;
+//# sourceMappingURL=sources.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../src/entitlements/sources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,iBAAiB,EAOrE,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAoB1C,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,6FAA6F;IAC7F,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,6FAA6F;IAC7F,SAAS,EAAE,OAAO,CAAC;IACnB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAQxE;AAED,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAMjE"}

package/dist/entitlements/sources.js

@@ -0,0 +1,55 @@
+/**
+ * Fontes canônicas (contrato 1.0.0 — ENTITLEMENTS_CONTRACT_SPEC_2026-07-27.md §5).
+ * Superset das 6 já existentes em `types.ts` — nenhuma removida, nenhuma renomeada.
+ */
+export const CANONICAL_ENTITLEMENT_SOURCES = [
+    'PLAN',
+    'ADDON',
+    'COUPON',
+    'CAMPAIGN',
+    'MANUAL',
+    'FEATURE_FLAG',
+];
+/** Alias legado (mvb `Entitlement.source = 'BETA'`) — nunca reescrito em massa. */
+export const LEGACY_SOURCE_ALIAS = 'BETA';
+/**
+ * Ordem de precedência canônica, maior→menor (§10): `MANUAL > FEATURE_FLAG >
+ * ADDON > CAMPAIGN/COUPON > PLAN`. `CAMPAIGN` e `COUPON` são o mesmo nível
+ * (grupo "CAMPAIGN/COUPON" no contrato) — nunca uma prevalece sobre a outra
+ * por precedência; ambas concedem, ambas aparecem em `sources`. Índice menor
+ * = mais forte.
+ */
+const PRECEDENCE_TIERS = [
+    ['MANUAL'],
+    ['FEATURE_FLAG'],
+    ['ADDON'],
+    ['CAMPAIGN', 'COUPON'],
+    ['PLAN'],
+];
+/** Fonte desconhecida (forward-compat) recebe esta precedência — mínima, abaixo de PLAN. */
+const UNKNOWN_SOURCE_PRECEDENCE = PRECEDENCE_TIERS.length;
+/**
+ * Normaliza uma fonte bruta (persistida) para o conjunto canônico.
+ * - `BETA` → `MANUAL` + `legacySource: "BETA"` (compat, sem migração destrutiva).
+ * - Valor canônico → passthrough.
+ * - Valor desconhecido (forward-compat) → `canonical: null`, `isUnknown: true`; o
+ *   grant continua sendo honrado se `active`, mas nunca finge ser uma fonte
+ *   canônica — evita ganhar autoridade por acidente (§5/§10 da Contract Spec).
+ */
+export function normalizeEntitlementSource(raw) {
+    if (raw === LEGACY_SOURCE_ALIAS) {
+        return { raw, canonical: 'MANUAL', isUnknown: false, legacySource: LEGACY_SOURCE_ALIAS };
+    }
+    if (CANONICAL_ENTITLEMENT_SOURCES.includes(raw)) {
+        return { raw, canonical: raw, isUnknown: false };
+    }
+    return { raw, canonical: null, isUnknown: true };
+}
+/** Precedência de uma fonte normalizada — menor valor = mais forte; desconhecida = mínima. */
+export function sourcePrecedence(source) {
+    if (source.isUnknown || source.canonical == null)
+        return UNKNOWN_SOURCE_PRECEDENCE;
+    const tierIdx = PRECEDENCE_TIERS.findIndex((tier) => tier.includes(source.canonical));
+    return tierIdx === -1 ? UNKNOWN_SOURCE_PRECEDENCE : tierIdx;
+}
+//# sourceMappingURL=sources.js.map

package/dist/entitlements/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../src/entitlements/sources.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAiC;IACzE,MAAM;IACN,OAAO;IACP,QAAQ;IACR,UAAU;IACV,QAAQ;IACR,cAAc;CACf,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,gBAAgB,GAA8C;IAClE,CAAC,QAAQ,CAAC;IACV,CAAC,cAAc,CAAC;IAChB,CAAC,OAAO,CAAC;IACT,CAAC,UAAU,EAAE,QAAQ,CAAC;IACtB,CAAC,MAAM,CAAC;CACT,CAAC;AAEF,4FAA4F;AAC5F,MAAM,yBAAyB,GAAG,gBAAgB,CAAC,MAAM,CAAC;AAa1D;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,IAAI,GAAG,KAAK,mBAAmB,EAAE,CAAC;QAChC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,CAAC;IAC3F,CAAC;IACD,IAAK,6BAAmD,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACvE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,GAAwB,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACxE,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACnD,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACvD,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,IAAI,IAAI;QAAE,OAAO,yBAAyB,CAAC;IACnF,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CACjD,IAA0B,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAmB,CAAC,CACjE,CAAC;IACF,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9D,CAAC"}

package/dist/entitlements/standing.d.ts

@@ -0,0 +1,22 @@
+import type { ReasonCode } from './decision.js';
+/**
+ * Standing canônico (contrato 1.0.0 — ENTITLEMENTS_CONTRACT_SPEC_2026-07-27.md §6).
+ * Entitlements NÃO possui o lifecycle de assinatura — apenas consome esta
+ * projeção (`accessLevel`), injetada pelo consumidor via `ctx.standing`.
+ */
+export type AccessLevel = 'FULL' | 'RESTRICTED' | 'BLOCKED';
+export interface SubscriptionStanding {
+    accessLevel: AccessLevel;
+    /** Status normalizado, tal como recebido do consumidor (mvb ou core), para explicabilidade. */
+    statusCanonical: string;
+    reasonCode: ReasonCode;
+}
+/**
+ * Normaliza um status de assinatura (mvb ou core) para o `SubscriptionStanding`
+ * canônico. Puro — nenhuma máquina de estados, nenhum I/O. Status desconhecido
+ * (incluindo ausente/vazio) → BLOCKED (fail-closed, §6 da Contract Spec).
+ */
+export declare function normalizeSubscriptionStanding(status: string | null | undefined): SubscriptionStanding;
+/** `standingOk` — mesma regra já usada pelo mvb (`accessLevel !== 'BLOCKED'`), ratificada no contrato. */
+export declare function isStandingOk(standing: SubscriptionStanding): boolean;
+//# sourceMappingURL=standing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"standing.d.ts","sourceRoot":"","sources":["../../src/entitlements/standing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,WAAW,CAAC;IACzB,+FAA+F;IAC/F,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,UAAU,CAAC;CACxB;AAuBD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC,oBAAoB,CAOtB;AAED,0GAA0G;AAC1G,wBAAgB,YAAY,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAEpE"}

package/dist/entitlements/standing.js

@@ -0,0 +1,38 @@
+/**
+ * Mapeamento status → accessLevel (mvb 7 valores + core 5 valores).
+ * Desconhecido → BLOCKED (fail-closed — regra de segurança, nunca afrouxa por omissão).
+ */
+const STATUS_TO_STANDING = {
+    // mvb (SubscriptionStatus do Prisma) + core (subscription-billing) — case-sensitive, ambos os vocabulários.
+    TRIALING: { accessLevel: 'FULL', reasonCode: 'ENTITLEMENT_ACTIVE' },
+    trialing: { accessLevel: 'FULL', reasonCode: 'ENTITLEMENT_ACTIVE' },
+    ACTIVE: { accessLevel: 'FULL', reasonCode: 'ENTITLEMENT_ACTIVE' },
+    active: { accessLevel: 'FULL', reasonCode: 'ENTITLEMENT_ACTIVE' },
+    PAST_DUE: { accessLevel: 'FULL', reasonCode: 'ENTITLEMENT_ACTIVE' },
+    past_due: { accessLevel: 'FULL', reasonCode: 'ENTITLEMENT_ACTIVE' },
+    RESTRICTED: { accessLevel: 'RESTRICTED', reasonCode: 'SUBSCRIPTION_RESTRICTED' },
+    SUSPENDED: { accessLevel: 'BLOCKED', reasonCode: 'SUBSCRIPTION_BLOCKED' },
+    CANCELED: { accessLevel: 'BLOCKED', reasonCode: 'SUBSCRIPTION_BLOCKED' },
+    canceled: { accessLevel: 'BLOCKED', reasonCode: 'SUBSCRIPTION_BLOCKED' },
+    EXPIRED: { accessLevel: 'BLOCKED', reasonCode: 'SUBSCRIPTION_BLOCKED' },
+    paused: { accessLevel: 'BLOCKED', reasonCode: 'SUBSCRIPTION_BLOCKED' },
+    NONE: { accessLevel: 'BLOCKED', reasonCode: 'SUBSCRIPTION_BLOCKED' },
+};
+/**
+ * Normaliza um status de assinatura (mvb ou core) para o `SubscriptionStanding`
+ * canônico. Puro — nenhuma máquina de estados, nenhum I/O. Status desconhecido
+ * (incluindo ausente/vazio) → BLOCKED (fail-closed, §6 da Contract Spec).
+ */
+export function normalizeSubscriptionStanding(status) {
+    const key = status ?? 'NONE';
+    const mapped = STATUS_TO_STANDING[key];
+    if (!mapped) {
+        return { accessLevel: 'BLOCKED', statusCanonical: key, reasonCode: 'SUBSCRIPTION_BLOCKED' };
+    }
+    return { accessLevel: mapped.accessLevel, statusCanonical: key, reasonCode: mapped.reasonCode };
+}
+/** `standingOk` — mesma regra já usada pelo mvb (`accessLevel !== 'BLOCKED'`), ratificada no contrato. */
+export function isStandingOk(standing) {
+    return standing.accessLevel !== 'BLOCKED';
+}
+//# sourceMappingURL=standing.js.map

package/dist/entitlements/standing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standing.js","sourceRoot":"","sources":["../../src/entitlements/standing.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,MAAM,kBAAkB,GAAyE;IAC/F,4GAA4G;IAC5G,QAAQ,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,EAAE;IACnE,QAAQ,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,EAAE;IACnE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,EAAE;IACjE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,EAAE;IACjE,QAAQ,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,EAAE;IACnE,QAAQ,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,EAAE;IACnE,UAAU,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,yBAAyB,EAAE;IAChF,SAAS,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,sBAAsB,EAAE;IACzE,QAAQ,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,sBAAsB,EAAE;IACxE,QAAQ,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,sBAAsB,EAAE;IACxE,OAAO,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,sBAAsB,EAAE;IACvE,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,sBAAsB,EAAE;IACtE,IAAI,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,sBAAsB,EAAE;CACrE,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAiC;IAEjC,MAAM,GAAG,GAAG,MAAM,IAAI,MAAM,CAAC;IAC7B,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,EAAE,sBAAsB,EAAE,CAAC;IAC9F,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;AAClG,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,YAAY,CAAC,QAA8B;IACzD,OAAO,QAAQ,CAAC,WAAW,KAAK,SAAS,CAAC;AAC5C,CAAC"}

package/dist/entitlements/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Entitlements (finos) — contrato canônico (Track A1, RFC-CAPABILITY-
+ * COMMERCIAL-CATALOG-001 §6). Domínio PURO — sem DB, sem `Date.now()` interno.
+ *
+ * Distinção dura (nunca confundir — achado Reality-First, §25 do modelo):
+ * - Entitlement FINO (este módulo) = "o tenant contratou o módulo X" — deriva
+ *   da Offer/Subscription, é o que este pacote resolve.
+ * - Entitlement GROSSO (`product`/`tenant_product`, já em produção no
+ *   `baruk-platform`, migração `0010_product_entitlements.sql`) = "o tenant
+ *   pode abrir este PRODUTO" (IAM). É uma camada DIFERENTE, anterior a esta —
+ *   o Hub bloqueia o produto pelo grosso; DENTRO do produto, o fino decide
+ *   quais módulos/capacidades aparecem. Este módulo nunca substitui aquele.
+ */
+export type EntitlementSource = 'PLAN' | 'ADDON' | 'COUPON' | 'CAMPAIGN' | 'MANUAL' | 'FEATURE_FLAG';
+export interface EntitlementRecord {
+    tenantId: string;
+    subscriptionId: string | null;
+    moduleCode: string;
+    source: EntitlementSource;
+    active: boolean;
+    /** Concessões temporárias (ex.: cupom free_module_period) expiram; PLAN normalmente não. */
+    expiresAt: string | null;
+    grantedAt: string;
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/entitlements/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,iBAAiB,GAC3B,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,4FAA4F;IAC5F,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC"}

package/dist/entitlements/types.js

@@ -0,0 +1,15 @@
+/**
+ * Entitlements (finos) — contrato canônico (Track A1, RFC-CAPABILITY-
+ * COMMERCIAL-CATALOG-001 §6). Domínio PURO — sem DB, sem `Date.now()` interno.
+ *
+ * Distinção dura (nunca confundir — achado Reality-First, §25 do modelo):
+ * - Entitlement FINO (este módulo) = "o tenant contratou o módulo X" — deriva
+ *   da Offer/Subscription, é o que este pacote resolve.
+ * - Entitlement GROSSO (`product`/`tenant_product`, já em produção no
+ *   `baruk-platform`, migração `0010_product_entitlements.sql`) = "o tenant
+ *   pode abrir este PRODUTO" (IAM). É uma camada DIFERENTE, anterior a esta —
+ *   o Hub bloqueia o produto pelo grosso; DENTRO do produto, o fino decide
+ *   quais módulos/capacidades aparecem. Este módulo nunca substitui aquele.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/entitlements/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/entitlements/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}