@fayz-ai/core 0.8.1 → 0.8.3

package/dist/access/denial.d.ts

@@ -0,0 +1,21 @@
+import type { DenyReason } from './engine';
+/** Where a denied tenant goes to upgrade — the conversational UpgradeModal. */
+export declare const UPGRADE_URL = "/settings/subscription";
+export interface AgentDenialLimit {
+    key: string;
+    max: number;
+    used: number;
+}
+export interface AgentDenial {
+    allowed: false;
+    reason: DenyReason;
+    /** Present when `reason === 'limit'`. */
+    limit?: AgentDenialLimit;
+    upgradeUrl: string;
+}
+export type AgentGuardResult = {
+    allowed: true;
+} | AgentDenial;
+/** Build a denial with the canonical upgrade URL attached. */
+export declare function agentDenial(reason: DenyReason, limit?: AgentDenialLimit): AgentDenial;
+//# sourceMappingURL=denial.d.ts.map

package/dist/access/denial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"denial.d.ts","sourceRoot":"","sources":["../../src/access/denial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAU1C,+EAA+E;AAC/E,eAAO,MAAM,WAAW,2BAA2B,CAAA;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,KAAK,CAAA;IACd,MAAM,EAAE,UAAU,CAAA;IAClB,yCAAyC;IACzC,KAAK,CAAC,EAAE,gBAAgB,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,MAAM,gBAAgB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG,WAAW,CAAA;AAE9D,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,WAAW,CAErF"}

package/dist/access/engine.d.ts

@@ -0,0 +1,63 @@
+import type { PermissionProfile, PermissionAction } from '../types/permissions';
+import type { Plan } from '../types/billing';
+/** Why an access request was denied. `limit` only occurs on guarded writes. */
+export type DenyReason = 'role' | 'plan' | 'limit';
+export interface AccessDecision {
+    allowed: boolean;
+    reason?: DenyReason;
+}
+/** The minimal subject a decision needs — a projection of any richer session. */
+export interface AccessSubject {
+    /** Effective RBAC profile — the previewed role during impersonation. */
+    profile: PermissionProfile | null;
+    /** The tenant's currently-active plan. */
+    plan: Plan | null;
+}
+/**
+ * The org owner has every permission implicitly. Owner is represented by the
+ * canonical role id `owner` across adapters (see org/adapters/supabase.ts
+ * buildPermissionProfiles, which also grants owner all catalog perms, and the
+ * mock adapter's `owner` fallback). We match by id first, falling back to the
+ * (possibly localized) name for safety.
+ */
+export declare function isOwnerProfile(profile: PermissionProfile): boolean;
+/**
+ * The single role-side permission check. The plan axis composes ON TOP of it in
+ * {@link resolveAccess} instead of reimplementing owner-bypass / `manage`
+ * semantics.
+ */
+export declare function profileHasPermission(profile: PermissionProfile | null, feature: string, action?: string): boolean;
+/**
+ * Does the current plan entitle `feature`? A plan gates a feature ONLY with an
+ * explicit `false`; absent means "not gated by this plan" (allowed). This keeps
+ * entitlements additive and safe: a feature the plan has never heard of stays
+ * open rather than silently locking.
+ */
+export declare function isEntitledByPlan(plan: Plan | null, feature: string): boolean;
+/**
+ * The single access decision: role FIRST, then plan.
+ *
+ * 1. Role — reuses `profileHasPermission` (owner bypass + `manage` semantics
+ *    live there, and impersonation composes for free because `profile` is the
+ *    previewed role). Denied → `{ allowed:false, reason:'role' }`.
+ * 2. Plan — even the owner does NOT bypass the plan: upgrading is the tenant's
+ *    decision, not a role power. Denied → `{ allowed:false, reason:'plan' }`.
+ */
+export declare function resolveAccess(subject: AccessSubject, feature: string, action?: PermissionAction): AccessDecision;
+/**
+ * Pure numeric side of a limit: given the plan cap, whether a countable
+ * declaration exists, and the current usage, derive the limit math. Unlimited
+ * when there's no declaration to count, no cap on the plan, or the cap is `-1`.
+ */
+export declare function resolveLimit(params: {
+    cap: number | undefined;
+    hasDeclaration: boolean;
+    used: number;
+}): {
+    max: number;
+    used: number;
+    remaining: number;
+    atLimit: boolean;
+    unlimited: boolean;
+};
+//# sourceMappingURL=engine.d.ts.map

package/dist/access/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/access/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAe5C,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAElD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACjC,0CAA0C;IAC1C,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAElE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,GAAG,IAAI,EACjC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAeT;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,gBAAgB,GACxB,cAAc,CAQhB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IACxG,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,OAAO,CAAA;CACnB,CAOA"}

package/dist/access/index.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+// src/access/engine.ts
+function isOwnerProfile(profile) {
+  return profile.id === "owner" || profile.name?.toLowerCase() === "owner";
+}
+function profileHasPermission(profile, feature, action) {
+  if (!profile) return true;
+  if (isOwnerProfile(profile)) return true;
+  const actions = profile.grants[feature];
+  if (!actions) return false;
+  if (!action) return actions.length > 0;
+  return actions.includes(action) || actions.includes("manage");
+}
+function isEntitledByPlan(plan, feature) {
+  return plan?.entitlements?.features?.[feature] !== false;
+}
+function resolveAccess(subject, feature, action) {
+  if (!profileHasPermission(subject.profile, feature, action)) {
+    return { allowed: false, reason: "role" };
+  }
+  if (!isEntitledByPlan(subject.plan, feature)) {
+    return { allowed: false, reason: "plan" };
+  }
+  return { allowed: true };
+}
+function resolveLimit(params) {
+  const { cap, hasDeclaration, used } = params;
+  const unlimited = !hasDeclaration || cap === void 0 || cap === -1;
+  const max = unlimited ? Infinity : cap;
+  const remaining = unlimited ? Infinity : Math.max(0, max - used);
+  const atLimit = !unlimited && used >= max;
+  return { max, used, remaining, atLimit, unlimited };
+}
+
+// src/access/denial.ts
+var UPGRADE_URL = "/settings/subscription";
+function agentDenial(reason, limit) {
+  return { allowed: false, reason, ...limit ? { limit } : {}, upgradeUrl: UPGRADE_URL };
+}
+
+// src/access/limits.ts
+function mergeLimitDeclarations(...layers) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const layer of layers) {
+    for (const decl of layer ?? []) byKey.set(decl.key, decl);
+  }
+  return Array.from(byKey.values());
+}
+
+exports.UPGRADE_URL = UPGRADE_URL;
+exports.agentDenial = agentDenial;
+exports.isEntitledByPlan = isEntitledByPlan;
+exports.isOwnerProfile = isOwnerProfile;
+exports.mergeLimitDeclarations = mergeLimitDeclarations;
+exports.profileHasPermission = profileHasPermission;
+exports.resolveAccess = resolveAccess;
+exports.resolveLimit = resolveLimit;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/access/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/access/engine.ts","../../src/access/denial.ts","../../src/access/limits.ts"],"names":[],"mappings":";;;AAuCO,SAAS,eAAe,OAAA,EAAqC;AAClE,EAAA,OAAO,QAAQ,EAAA,KAAO,OAAA,IAAW,OAAA,CAAQ,IAAA,EAAM,aAAY,KAAM,OAAA;AACnE;AAOO,SAAS,oBAAA,CACd,OAAA,EACA,OAAA,EACA,MAAA,EACS;AACT,EAAA,IAAI,CAAC,SAAS,OAAO,IAAA;AAMrB,EAAA,IAAI,cAAA,CAAe,OAAO,CAAA,EAAG,OAAO,IAAA;AAEpC,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,MAAA,CAAO,OAAO,CAAA;AACtC,EAAA,IAAI,CAAC,SAAS,OAAO,KAAA;AAErB,EAAA,IAAI,CAAC,MAAA,EAAQ,OAAO,OAAA,CAAQ,MAAA,GAAS,CAAA;AAErC,EAAA,OAAO,QAAQ,QAAA,CAAS,MAAM,CAAA,IAAK,OAAA,CAAQ,SAAS,QAAQ,CAAA;AAC9D;AAQO,SAAS,gBAAA,CAAiB,MAAmB,OAAA,EAA0B;AAC5E,EAAA,OAAO,IAAA,EAAM,YAAA,EAAc,QAAA,GAAW,OAAO,CAAA,KAAM,KAAA;AACrD;AAWO,SAAS,aAAA,CACd,OAAA,EACA,OAAA,EACA,MAAA,EACgB;AAChB,EAAA,IAAI,CAAC,oBAAA,CAAqB,OAAA,CAAQ,OAAA,EAAS,OAAA,EAAS,MAAM,CAAA,EAAG;AAC3D,IAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,MAAA,EAAQ,MAAA,EAAO;AAAA,EAC1C;AACA,EAAA,IAAI,CAAC,gBAAA,CAAiB,OAAA,CAAQ,IAAA,EAAM,OAAO,CAAA,EAAG;AAC5C,IAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,MAAA,EAAQ,MAAA,EAAO;AAAA,EAC1C;AACA,EAAA,OAAO,EAAE,SAAS,IAAA,EAAK;AACzB;AAOO,SAAS,aAAa,MAAA,EAM3B;AACA,EAAA,MAAM,EAAE,GAAA,EAAK,cAAA,EAAgB,IAAA,EAAK,GAAI,MAAA;AACtC,EAAA,MAAM,SAAA,GAAY,CAAC,cAAA,IAAkB,GAAA,KAAQ,UAAa,GAAA,KAAQ,EAAA;AAClE,EAAA,MAAM,GAAA,GAAM,YAAY,QAAA,GAAW,GAAA;AACnC,EAAA,MAAM,YAAY,SAAA,GAAY,QAAA,GAAW,KAAK,GAAA,CAAI,CAAA,EAAG,MAAM,IAAI,CAAA;AAC/D,EAAA,MAAM,OAAA,GAAU,CAAC,SAAA,IAAa,IAAA,IAAQ,GAAA;AACtC,EAAA,OAAO,EAAE,GAAA,EAAK,IAAA,EAAM,SAAA,EAAW,SAAS,SAAA,EAAU;AACpD;;;AC7GO,IAAM,WAAA,GAAc;AAmBpB,SAAS,WAAA,CAAY,QAAoB,KAAA,EAAuC;AACrF,EAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,MAAA,EAAQ,GAAI,KAAA,GAAQ,EAAE,KAAA,EAAM,GAAI,EAAC,EAAI,UAAA,EAAY,WAAA,EAAY;AACxF;;;ACvBO,SAAS,0BACX,MAAA,EACiB;AACpB,EAAA,MAAM,KAAA,uBAAY,GAAA,EAA8B;AAChD,EAAA,KAAA,MAAW,SAAS,MAAA,EAAQ;AAC1B,IAAA,KAAA,MAAW,IAAA,IAAQ,SAAS,EAAC,QAAS,GAAA,CAAI,IAAA,CAAK,KAAK,IAAI,CAAA;AAAA,EAC1D;AACA,EAAA,OAAO,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,MAAA,EAAQ,CAAA;AAClC","file":"index.cjs","sourcesContent":["import type { PermissionProfile, PermissionAction } from '../types/permissions'\nimport type { Plan } from '../types/billing'\n\n// ---------------------------------------------------------------------------\n// The access engine — the ONE implementation of the role × plan × limit\n// decision, shared by every runtime that gates anything:\n//\n//   - browser (saas AccessProvider / PermissionsProvider re-export from here)\n//   - headless client-plane (saas access/headless.ts)\n//   - the Fayz broker (server-side agent authorization imports this package)\n//\n// Hard constraint: this module (and everything under core/src/access) must stay\n// free of React, zustand and supabase — pure functions over plain data — so the\n// exact same code runs in Node/edge. Guarded by scripts/check-access-purity.mjs.\n// ---------------------------------------------------------------------------\n\n/** Why an access request was denied. `limit` only occurs on guarded writes. */\nexport type DenyReason = 'role' | 'plan' | 'limit'\n\nexport interface AccessDecision {\n  allowed: boolean\n  reason?: DenyReason\n}\n\n/** The minimal subject a decision needs — a projection of any richer session. */\nexport interface AccessSubject {\n  /** Effective RBAC profile — the previewed role during impersonation. */\n  profile: PermissionProfile | null\n  /** The tenant's currently-active plan. */\n  plan: Plan | null\n}\n\n/**\n * The org owner has every permission implicitly. Owner is represented by the\n * canonical role id `owner` across adapters (see org/adapters/supabase.ts\n * buildPermissionProfiles, which also grants owner all catalog perms, and the\n * mock adapter's `owner` fallback). We match by id first, falling back to the\n * (possibly localized) name for safety.\n */\nexport function isOwnerProfile(profile: PermissionProfile): boolean {\n  return profile.id === 'owner' || profile.name?.toLowerCase() === 'owner'\n}\n\n/**\n * The single role-side permission check. The plan axis composes ON TOP of it in\n * {@link resolveAccess} instead of reimplementing owner-bypass / `manage`\n * semantics.\n */\nexport function profileHasPermission(\n  profile: PermissionProfile | null,\n  feature: string,\n  action?: string,\n): boolean {\n  if (!profile) return true\n\n  // Owner bypass: never lock the owner out, even if the RBAC catalog is empty\n  // or still loading. Because permission checks read the *effective* profile,\n  // an owner previewing a non-owner role correctly loses this bypass — the\n  // preview stays honest.\n  if (isOwnerProfile(profile)) return true\n\n  const actions = profile.grants[feature]\n  if (!actions) return false\n\n  if (!action) return actions.length > 0\n\n  return actions.includes(action) || actions.includes('manage')\n}\n\n/**\n * Does the current plan entitle `feature`? A plan gates a feature ONLY with an\n * explicit `false`; absent means \"not gated by this plan\" (allowed). This keeps\n * entitlements additive and safe: a feature the plan has never heard of stays\n * open rather than silently locking.\n */\nexport function isEntitledByPlan(plan: Plan | null, feature: string): boolean {\n  return plan?.entitlements?.features?.[feature] !== false\n}\n\n/**\n * The single access decision: role FIRST, then plan.\n *\n * 1. Role — reuses `profileHasPermission` (owner bypass + `manage` semantics\n *    live there, and impersonation composes for free because `profile` is the\n *    previewed role). Denied → `{ allowed:false, reason:'role' }`.\n * 2. Plan — even the owner does NOT bypass the plan: upgrading is the tenant's\n *    decision, not a role power. Denied → `{ allowed:false, reason:'plan' }`.\n */\nexport function resolveAccess(\n  subject: AccessSubject,\n  feature: string,\n  action?: PermissionAction,\n): AccessDecision {\n  if (!profileHasPermission(subject.profile, feature, action)) {\n    return { allowed: false, reason: 'role' }\n  }\n  if (!isEntitledByPlan(subject.plan, feature)) {\n    return { allowed: false, reason: 'plan' }\n  }\n  return { allowed: true }\n}\n\n/**\n * Pure numeric side of a limit: given the plan cap, whether a countable\n * declaration exists, and the current usage, derive the limit math. Unlimited\n * when there's no declaration to count, no cap on the plan, or the cap is `-1`.\n */\nexport function resolveLimit(params: { cap: number | undefined; hasDeclaration: boolean; used: number }): {\n  max: number\n  used: number\n  remaining: number\n  atLimit: boolean\n  unlimited: boolean\n} {\n  const { cap, hasDeclaration, used } = params\n  const unlimited = !hasDeclaration || cap === undefined || cap === -1\n  const max = unlimited ? Infinity : cap\n  const remaining = unlimited ? Infinity : Math.max(0, max - used)\n  const atLimit = !unlimited && used >= max\n  return { max, used, remaining, atLimit, unlimited }\n}\n","import type { DenyReason } from './engine'\n\n// ---------------------------------------------------------------------------\n// The structured denial an AGENT surface returns instead of failing silently\n// (docs/ENTITLEMENTS.md § \"Superfície de agentes de IA\"). One shape for every\n// executor — FAB client-plane, the Fayz broker, and the pool RPCs (which emit\n// its jsonb mirror in their `denial` field) — so the model can explain the\n// denial and offer the upgrade path conversationally.\n// ---------------------------------------------------------------------------\n\n/** Where a denied tenant goes to upgrade — the conversational UpgradeModal. */\nexport const UPGRADE_URL = '/settings/subscription'\n\nexport interface AgentDenialLimit {\n  key: string\n  max: number\n  used: number\n}\n\nexport interface AgentDenial {\n  allowed: false\n  reason: DenyReason\n  /** Present when `reason === 'limit'`. */\n  limit?: AgentDenialLimit\n  upgradeUrl: string\n}\n\nexport type AgentGuardResult = { allowed: true } | AgentDenial\n\n/** Build a denial with the canonical upgrade URL attached. */\nexport function agentDenial(reason: DenyReason, limit?: AgentDenialLimit): AgentDenial {\n  return { allowed: false, reason, ...(limit ? { limit } : {}), upgradeUrl: UPGRADE_URL }\n}\n","import type { LimitDeclaration } from '../types/entitlements'\n\n/**\n * The 4-layer limit-declaration merge, extracted so the browser AccessProvider\n * and the manifest derivation (`fayz manifest emit`) resolve the EXACT same\n * final set: core built-ins < entity-derived < plugin `declaredLimits` < app\n * overrides. Later layers win by key. Pure: pass the layers in, get the merge\n * out — deriving a declaration FROM an entity stays at the call site.\n */\nexport function mergeLimitDeclarations(\n  ...layers: Array<LimitDeclaration[] | undefined>\n): LimitDeclaration[] {\n  const byKey = new Map<string, LimitDeclaration>()\n  for (const layer of layers) {\n    for (const decl of layer ?? []) byKey.set(decl.key, decl)\n  }\n  return Array.from(byKey.values())\n}\n"]}

package/dist/access/index.d.ts

@@ -0,0 +1,6 @@
+export { isOwnerProfile, profileHasPermission, isEntitledByPlan, resolveAccess, resolveLimit, } from './engine';
+export type { DenyReason, AccessDecision, AccessSubject } from './engine';
+export { UPGRADE_URL, agentDenial } from './denial';
+export type { AgentDenial, AgentDenialLimit, AgentGuardResult } from './denial';
+export { mergeLimitDeclarations } from './limits';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/access/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAEzE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AACnD,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAE/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA"}

package/dist/access/index.js

@@ -0,0 +1,51 @@
+// src/access/engine.ts
+function isOwnerProfile(profile) {
+  return profile.id === "owner" || profile.name?.toLowerCase() === "owner";
+}
+function profileHasPermission(profile, feature, action) {
+  if (!profile) return true;
+  if (isOwnerProfile(profile)) return true;
+  const actions = profile.grants[feature];
+  if (!actions) return false;
+  if (!action) return actions.length > 0;
+  return actions.includes(action) || actions.includes("manage");
+}
+function isEntitledByPlan(plan, feature) {
+  return plan?.entitlements?.features?.[feature] !== false;
+}
+function resolveAccess(subject, feature, action) {
+  if (!profileHasPermission(subject.profile, feature, action)) {
+    return { allowed: false, reason: "role" };
+  }
+  if (!isEntitledByPlan(subject.plan, feature)) {
+    return { allowed: false, reason: "plan" };
+  }
+  return { allowed: true };
+}
+function resolveLimit(params) {
+  const { cap, hasDeclaration, used } = params;
+  const unlimited = !hasDeclaration || cap === void 0 || cap === -1;
+  const max = unlimited ? Infinity : cap;
+  const remaining = unlimited ? Infinity : Math.max(0, max - used);
+  const atLimit = !unlimited && used >= max;
+  return { max, used, remaining, atLimit, unlimited };
+}
+
+// src/access/denial.ts
+var UPGRADE_URL = "/settings/subscription";
+function agentDenial(reason, limit) {
+  return { allowed: false, reason, ...limit ? { limit } : {}, upgradeUrl: UPGRADE_URL };
+}
+
+// src/access/limits.ts
+function mergeLimitDeclarations(...layers) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const layer of layers) {
+    for (const decl of layer ?? []) byKey.set(decl.key, decl);
+  }
+  return Array.from(byKey.values());
+}
+
+export { UPGRADE_URL, agentDenial, isEntitledByPlan, isOwnerProfile, mergeLimitDeclarations, profileHasPermission, resolveAccess, resolveLimit };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/access/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/access/engine.ts","../../src/access/denial.ts","../../src/access/limits.ts"],"names":[],"mappings":";AAuCO,SAAS,eAAe,OAAA,EAAqC;AAClE,EAAA,OAAO,QAAQ,EAAA,KAAO,OAAA,IAAW,OAAA,CAAQ,IAAA,EAAM,aAAY,KAAM,OAAA;AACnE;AAOO,SAAS,oBAAA,CACd,OAAA,EACA,OAAA,EACA,MAAA,EACS;AACT,EAAA,IAAI,CAAC,SAAS,OAAO,IAAA;AAMrB,EAAA,IAAI,cAAA,CAAe,OAAO,CAAA,EAAG,OAAO,IAAA;AAEpC,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,MAAA,CAAO,OAAO,CAAA;AACtC,EAAA,IAAI,CAAC,SAAS,OAAO,KAAA;AAErB,EAAA,IAAI,CAAC,MAAA,EAAQ,OAAO,OAAA,CAAQ,MAAA,GAAS,CAAA;AAErC,EAAA,OAAO,QAAQ,QAAA,CAAS,MAAM,CAAA,IAAK,OAAA,CAAQ,SAAS,QAAQ,CAAA;AAC9D;AAQO,SAAS,gBAAA,CAAiB,MAAmB,OAAA,EAA0B;AAC5E,EAAA,OAAO,IAAA,EAAM,YAAA,EAAc,QAAA,GAAW,OAAO,CAAA,KAAM,KAAA;AACrD;AAWO,SAAS,aAAA,CACd,OAAA,EACA,OAAA,EACA,MAAA,EACgB;AAChB,EAAA,IAAI,CAAC,oBAAA,CAAqB,OAAA,CAAQ,OAAA,EAAS,OAAA,EAAS,MAAM,CAAA,EAAG;AAC3D,IAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,MAAA,EAAQ,MAAA,EAAO;AAAA,EAC1C;AACA,EAAA,IAAI,CAAC,gBAAA,CAAiB,OAAA,CAAQ,IAAA,EAAM,OAAO,CAAA,EAAG;AAC5C,IAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,MAAA,EAAQ,MAAA,EAAO;AAAA,EAC1C;AACA,EAAA,OAAO,EAAE,SAAS,IAAA,EAAK;AACzB;AAOO,SAAS,aAAa,MAAA,EAM3B;AACA,EAAA,MAAM,EAAE,GAAA,EAAK,cAAA,EAAgB,IAAA,EAAK,GAAI,MAAA;AACtC,EAAA,MAAM,SAAA,GAAY,CAAC,cAAA,IAAkB,GAAA,KAAQ,UAAa,GAAA,KAAQ,EAAA;AAClE,EAAA,MAAM,GAAA,GAAM,YAAY,QAAA,GAAW,GAAA;AACnC,EAAA,MAAM,YAAY,SAAA,GAAY,QAAA,GAAW,KAAK,GAAA,CAAI,CAAA,EAAG,MAAM,IAAI,CAAA;AAC/D,EAAA,MAAM,OAAA,GAAU,CAAC,SAAA,IAAa,IAAA,IAAQ,GAAA;AACtC,EAAA,OAAO,EAAE,GAAA,EAAK,IAAA,EAAM,SAAA,EAAW,SAAS,SAAA,EAAU;AACpD;;;AC7GO,IAAM,WAAA,GAAc;AAmBpB,SAAS,WAAA,CAAY,QAAoB,KAAA,EAAuC;AACrF,EAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,MAAA,EAAQ,GAAI,KAAA,GAAQ,EAAE,KAAA,EAAM,GAAI,EAAC,EAAI,UAAA,EAAY,WAAA,EAAY;AACxF;;;ACvBO,SAAS,0BACX,MAAA,EACiB;AACpB,EAAA,MAAM,KAAA,uBAAY,GAAA,EAA8B;AAChD,EAAA,KAAA,MAAW,SAAS,MAAA,EAAQ;AAC1B,IAAA,KAAA,MAAW,IAAA,IAAQ,SAAS,EAAC,QAAS,GAAA,CAAI,IAAA,CAAK,KAAK,IAAI,CAAA;AAAA,EAC1D;AACA,EAAA,OAAO,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,MAAA,EAAQ,CAAA;AAClC","file":"index.js","sourcesContent":["import type { PermissionProfile, PermissionAction } from '../types/permissions'\nimport type { Plan } from '../types/billing'\n\n// ---------------------------------------------------------------------------\n// The access engine — the ONE implementation of the role × plan × limit\n// decision, shared by every runtime that gates anything:\n//\n//   - browser (saas AccessProvider / PermissionsProvider re-export from here)\n//   - headless client-plane (saas access/headless.ts)\n//   - the Fayz broker (server-side agent authorization imports this package)\n//\n// Hard constraint: this module (and everything under core/src/access) must stay\n// free of React, zustand and supabase — pure functions over plain data — so the\n// exact same code runs in Node/edge. Guarded by scripts/check-access-purity.mjs.\n// ---------------------------------------------------------------------------\n\n/** Why an access request was denied. `limit` only occurs on guarded writes. */\nexport type DenyReason = 'role' | 'plan' | 'limit'\n\nexport interface AccessDecision {\n  allowed: boolean\n  reason?: DenyReason\n}\n\n/** The minimal subject a decision needs — a projection of any richer session. */\nexport interface AccessSubject {\n  /** Effective RBAC profile — the previewed role during impersonation. */\n  profile: PermissionProfile | null\n  /** The tenant's currently-active plan. */\n  plan: Plan | null\n}\n\n/**\n * The org owner has every permission implicitly. Owner is represented by the\n * canonical role id `owner` across adapters (see org/adapters/supabase.ts\n * buildPermissionProfiles, which also grants owner all catalog perms, and the\n * mock adapter's `owner` fallback). We match by id first, falling back to the\n * (possibly localized) name for safety.\n */\nexport function isOwnerProfile(profile: PermissionProfile): boolean {\n  return profile.id === 'owner' || profile.name?.toLowerCase() === 'owner'\n}\n\n/**\n * The single role-side permission check. The plan axis composes ON TOP of it in\n * {@link resolveAccess} instead of reimplementing owner-bypass / `manage`\n * semantics.\n */\nexport function profileHasPermission(\n  profile: PermissionProfile | null,\n  feature: string,\n  action?: string,\n): boolean {\n  if (!profile) return true\n\n  // Owner bypass: never lock the owner out, even if the RBAC catalog is empty\n  // or still loading. Because permission checks read the *effective* profile,\n  // an owner previewing a non-owner role correctly loses this bypass — the\n  // preview stays honest.\n  if (isOwnerProfile(profile)) return true\n\n  const actions = profile.grants[feature]\n  if (!actions) return false\n\n  if (!action) return actions.length > 0\n\n  return actions.includes(action) || actions.includes('manage')\n}\n\n/**\n * Does the current plan entitle `feature`? A plan gates a feature ONLY with an\n * explicit `false`; absent means \"not gated by this plan\" (allowed). This keeps\n * entitlements additive and safe: a feature the plan has never heard of stays\n * open rather than silently locking.\n */\nexport function isEntitledByPlan(plan: Plan | null, feature: string): boolean {\n  return plan?.entitlements?.features?.[feature] !== false\n}\n\n/**\n * The single access decision: role FIRST, then plan.\n *\n * 1. Role — reuses `profileHasPermission` (owner bypass + `manage` semantics\n *    live there, and impersonation composes for free because `profile` is the\n *    previewed role). Denied → `{ allowed:false, reason:'role' }`.\n * 2. Plan — even the owner does NOT bypass the plan: upgrading is the tenant's\n *    decision, not a role power. Denied → `{ allowed:false, reason:'plan' }`.\n */\nexport function resolveAccess(\n  subject: AccessSubject,\n  feature: string,\n  action?: PermissionAction,\n): AccessDecision {\n  if (!profileHasPermission(subject.profile, feature, action)) {\n    return { allowed: false, reason: 'role' }\n  }\n  if (!isEntitledByPlan(subject.plan, feature)) {\n    return { allowed: false, reason: 'plan' }\n  }\n  return { allowed: true }\n}\n\n/**\n * Pure numeric side of a limit: given the plan cap, whether a countable\n * declaration exists, and the current usage, derive the limit math. Unlimited\n * when there's no declaration to count, no cap on the plan, or the cap is `-1`.\n */\nexport function resolveLimit(params: { cap: number | undefined; hasDeclaration: boolean; used: number }): {\n  max: number\n  used: number\n  remaining: number\n  atLimit: boolean\n  unlimited: boolean\n} {\n  const { cap, hasDeclaration, used } = params\n  const unlimited = !hasDeclaration || cap === undefined || cap === -1\n  const max = unlimited ? Infinity : cap\n  const remaining = unlimited ? Infinity : Math.max(0, max - used)\n  const atLimit = !unlimited && used >= max\n  return { max, used, remaining, atLimit, unlimited }\n}\n","import type { DenyReason } from './engine'\n\n// ---------------------------------------------------------------------------\n// The structured denial an AGENT surface returns instead of failing silently\n// (docs/ENTITLEMENTS.md § \"Superfície de agentes de IA\"). One shape for every\n// executor — FAB client-plane, the Fayz broker, and the pool RPCs (which emit\n// its jsonb mirror in their `denial` field) — so the model can explain the\n// denial and offer the upgrade path conversationally.\n// ---------------------------------------------------------------------------\n\n/** Where a denied tenant goes to upgrade — the conversational UpgradeModal. */\nexport const UPGRADE_URL = '/settings/subscription'\n\nexport interface AgentDenialLimit {\n  key: string\n  max: number\n  used: number\n}\n\nexport interface AgentDenial {\n  allowed: false\n  reason: DenyReason\n  /** Present when `reason === 'limit'`. */\n  limit?: AgentDenialLimit\n  upgradeUrl: string\n}\n\nexport type AgentGuardResult = { allowed: true } | AgentDenial\n\n/** Build a denial with the canonical upgrade URL attached. */\nexport function agentDenial(reason: DenyReason, limit?: AgentDenialLimit): AgentDenial {\n  return { allowed: false, reason, ...(limit ? { limit } : {}), upgradeUrl: UPGRADE_URL }\n}\n","import type { LimitDeclaration } from '../types/entitlements'\n\n/**\n * The 4-layer limit-declaration merge, extracted so the browser AccessProvider\n * and the manifest derivation (`fayz manifest emit`) resolve the EXACT same\n * final set: core built-ins < entity-derived < plugin `declaredLimits` < app\n * overrides. Later layers win by key. Pure: pass the layers in, get the merge\n * out — deriving a declaration FROM an entity stays at the call site.\n */\nexport function mergeLimitDeclarations(\n  ...layers: Array<LimitDeclaration[] | undefined>\n): LimitDeclaration[] {\n  const byKey = new Map<string, LimitDeclaration>()\n  for (const layer of layers) {\n    for (const decl of layer ?? []) byKey.set(decl.key, decl)\n  }\n  return Array.from(byKey.values())\n}\n"]}

package/dist/access/limits.d.ts

@@ -0,0 +1,10 @@
+import type { LimitDeclaration } from '../types/entitlements';
+/**
+ * The 4-layer limit-declaration merge, extracted so the browser AccessProvider
+ * and the manifest derivation (`fayz manifest emit`) resolve the EXACT same
+ * final set: core built-ins < entity-derived < plugin `declaredLimits` < app
+ * overrides. Later layers win by key. Pure: pass the layers in, get the merge
+ * out — deriving a declaration FROM an entity stays at the call site.
+ */
+export declare function mergeLimitDeclarations(...layers: Array<LimitDeclaration[] | undefined>): LimitDeclaration[];
+//# sourceMappingURL=limits.d.ts.map

package/dist/access/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/access/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE7D;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,MAAM,EAAE,KAAK,CAAC,gBAAgB,EAAE,GAAG,SAAS,CAAC,GAC/C,gBAAgB,EAAE,CAMpB"}

package/dist/address/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * An address as a postal service knows it: everything except the parts only the
+ * resident can supply (number, complement).
+ *
+ * Field names mirror ShippingAddressInput in @fayz-ai/shop so the value crosses
+ * from lookup to checkout to the order with no translation step in between.
+ */
+export interface PostalAddress {
+    postalCode: string;
+    street: string;
+    district: string;
+    city: string;
+    state: string;
+    country: string;
+    /** IBGE municipality code when the source provides one — useful for tax later. */
+    cityCode?: string;
+}
+/** Where a postal code is resolved. Implementations must not throw for a
+ *  well-formed code that simply does not exist — that is `null`, not an error. */
+export interface PostalLookupProvider {
+    lookup(postalCode: string): Promise<PostalAddress | null>;
+}
+/** Keep only digits. */
+export declare function normalizePostalCode(value: string): string;
+/** '01310100' | '01310-100' -> '01310-100'. Partial input formats progressively. */
+export declare function formatPostalCode(value: string): string;
+/** A Brazilian CEP is exactly eight digits. */
+export declare function isValidPostalCode(value: string): boolean;
+/** Drop the cache. Exposed for tests and for a "wrong address?" escape hatch. */
+export declare function clearPostalCache(): void;
+/**
+ * ViaCEP (https://viacep.com.br). Free, no key, CORS-enabled.
+ *
+ * The trap: an unknown CEP does NOT come back as 404. ViaCEP answers HTTP 200
+ * with `{"erro": true}` (and, on some deploys, the string "true"), so checking
+ * response.ok alone yields an address of empty strings that silently overwrites
+ * whatever the shopper had typed. Both shapes are treated as "not found".
+ */
+export declare function createViaCepProvider(options?: {
+    fetcher?: typeof fetch;
+}): PostalLookupProvider;
+export declare function setPostalLookupProvider(provider: PostalLookupProvider | null): void;
+export declare function getPostalLookupProvider(): PostalLookupProvider;
+/**
+ * Resolve a postal code to an address, through the cache.
+ *
+ * Returns null for a code that is malformed or does not exist; throws only when
+ * the lookup itself failed (offline, provider down), so a caller can tell
+ * "no such CEP" from "we could not check right now" and say the right thing.
+ */
+export declare function lookupPostalCode(postalCode: string): Promise<PostalAddress | null>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/address/index.ts"],"names":[],"mappings":"AAcA;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;kFACkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;CAC1D;AAED,wBAAwB;AACxB,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD;AA2CD,iFAAiF;AACjF,wBAAgB,gBAAgB,IAAI,IAAI,CAOvC;AAgBD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;CAAE,GAAG,oBAAoB,CAwB/F;AAUD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAEnF;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAG9D;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAUxF"}