@digimuza/system-core 0.1.0 → 0.2.0-rc.2

package/dist/react/index.d.ts

@@ -11,11 +11,8 @@ export type SessionState = ({
 } & SessionSummary & {
     actor: NonNullable<SessionSummary["actor"]>;
 });
-type EmptySession = {
+type EmptySession = Omit<SessionSummary, "actor"> & {
     actor: null;
-    modules: ModuleState[];
-    permissions: string[];
-    flags: Record<string, boolean>;
 };
 export interface SystemProviderProps {
     /** Your exported `session` query, e.g. `api.system.session`. */
@@ -39,6 +36,12 @@ export declare function useCurrentUser(): {
 export declare function useVisibleModules(): ModuleState[];
 /** Whether the current actor holds `permission` right now (UI hint). */
 export declare function useCan(permission: string): boolean;
+/**
+ * "View as role" state: `canViewAs` for a real Super, `roleView` while a preview
+ * is active (then the rest of the session is that role's). Start and stop with
+ * the `startRoleView` / `stopRoleView` mutations.
+ */
+export declare function useRoleView(): Pick<SessionSummary, "canViewAs" | "roleView">;
 export declare function useFeatureFlag(flagId: string): boolean;
 export declare function Can(props: {
     permission: string;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC7E,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEnE,MAAM,MAAM,YAAY,GACpB,CAAC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG,YAAY,CAAC,GACtC,CAAC;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG,YAAY,CAAC,GACxC,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,cAAc,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAA;CAAE,CAAC,CAAA;AAE5F,KAAK,YAAY,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA;AAOlH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,OAAO,EAAE,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,cAAc,CAAC,CAAA;IAC/G,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,mBAAmB,+BAQxE;AAED,wBAAgB,gBAAgB,IAAI,YAAY,CAI/C;AAED,gEAAgE;AAChE,wBAAgB,cAAc;;;;;;SAG7B;AAED,6CAA6C;AAC7C,wBAAgB,iBAAiB,IAAI,WAAW,EAAE,CAEjD;AAED,wEAAwE;AACxE,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,+BAE5F;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAE5D;AAED,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC7E,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEnE,MAAM,MAAM,YAAY,GACpB,CAAC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG,YAAY,CAAC,GACtC,CAAC;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG,YAAY,CAAC,GACxC,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,cAAc,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAA;CAAE,CAAC,CAAA;AAE5F,KAAK,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,GAAG;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,CAAA;AAOnE,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,OAAO,EAAE,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,cAAc,CAAC,CAAA;IAC/G,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,mBAAmB,+BAQxE;AAED,wBAAgB,gBAAgB,IAAI,YAAY,CAI/C;AAED,gEAAgE;AAChE,wBAAgB,cAAc;;;;;;SAG7B;AAED,6CAA6C;AAC7C,wBAAgB,iBAAiB,IAAI,WAAW,EAAE,CAEjD;AAED,wEAAwE;AACxE,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,UAAU,CAAC,CAG5E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,+BAE5F;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAE5D;AAED,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,CAAA"}

package/dist/react/index.js

@@ -6,7 +6,7 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useQuery } from "convex/react";
 import { createContext, useContext, useMemo } from "react";
 import { toSystemError } from "../core/errors.js";
-const EMPTY = { actor: null, modules: [], permissions: [], flags: {} };
+const EMPTY = { actor: null, modules: [], permissions: [], flags: {}, canViewAs: false, roleView: null };
 const LOADING = { status: "loading", ...EMPTY };
 const SessionContext = createContext(null);
 /** Subscribes to the session summary; updates live when roles, modules or flags change. */
@@ -40,6 +40,15 @@ export function useVisibleModules() {
 export function useCan(permission) {
     return useSystemSession().permissions.includes(permission);
 }
+/**
+ * "View as role" state: `canViewAs` for a real Super, `roleView` while a preview
+ * is active (then the rest of the session is that role's). Start and stop with
+ * the `startRoleView` / `stopRoleView` mutations.
+ */
+export function useRoleView() {
+    const { canViewAs, roleView } = useSystemSession();
+    return { canViewAs, roleView };
+}
 export function useFeatureFlag(flagId) {
     return useSystemSession().flags[flagId] === true;
 }

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;;AACZ,yEAAyE;AACzE,2EAA2E;AAC3E,gCAAgC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAEvC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAkB,MAAM,OAAO,CAAA;AAE1E,OAAO,EAAE,aAAa,EAAoB,MAAM,mBAAmB,CAAA;AASnE,MAAM,KAAK,GAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAA;AACpF,MAAM,OAAO,GAAiB,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,CAAA;AAE7D,MAAM,cAAc,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAA;AAQ/D,2FAA2F;AAC3F,MAAM,UAAU,cAAc,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAuB;IACvE,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IAClC,MAAM,KAAK,GAAG,OAAO,CAAe,GAAG,EAAE;QACvC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,OAAO,CAAA;QACtC,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,KAAK,EAAE,CAAA;QACzD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAA;IACxD,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;IACV,OAAO,KAAC,cAAc,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAA2B,CAAA;AACpF,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,UAAU,CAAC,cAAc,CAAC,CAAA;IACtC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAA;IAClF,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc;IAC5B,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,EAAE,CAAA;IACpC,OAAO,KAAK,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;AAC9C,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,iBAAiB;IAC/B,OAAO,gBAAgB,EAAE,CAAC,OAAO,CAAA;AACnC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,MAAM,CAAC,UAAkB;IACvC,OAAO,gBAAgB,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;AAC5D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,gBAAgB,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,CAAA;AAClD,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,KAAyE;IAC3F,OAAO,4BAAG,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAI,CAAA;AACpF,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAA;AACzB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digimuza/system-core",
-  "version": "0.1.0",
+  "version": "0.2.0-rc.2",
   "description": "Shared system core for per-tenant Next.js + Convex applications: config, identity, roles, permissions, invites, API keys, feature flags, logging, tracing and audit.",
   "keywords": [
     "nextjs",
@@ -28,8 +28,7 @@
     "dist",
     "src",
     "README.md",
-    "INTEGRATION.md",
-    "CHANGELOG.md"
+    "INTEGRATION.md"
   ],
   "exports": {
     ".": {
@@ -57,6 +56,10 @@
       "types": "./dist/react/index.d.ts",
       "default": "./dist/react/index.js"
     },
+    "./finance": {
+      "types": "./dist/finance/index.d.ts",
+      "default": "./dist/finance/index.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
@@ -70,9 +73,7 @@
     "check:pack": "node scripts/check-pack.mjs",
     "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build && npm run check:pack",
     "lint": "biome lint",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "changeset publish"
+    "release:cut": "node scripts/release-cut.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -93,7 +94,6 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.6.6",
-    "@changesets/cli": "^3.0.3",
     "@edge-runtime/vm": "^5.0.0",
     "@types/node": "^26.6.6",
     "@types/react": "^19.3.0",

package/src/convex/functions.ts

@@ -28,13 +28,17 @@ import * as flags from "../core/feature-flags.js"
 import * as invites from "../core/invites.js"
 import * as mods from "../core/modules-service.js"
 import { registerCatalog } from "../core/registry.js"
+import * as roleView from "../core/role-view.js"
 import * as roles from "../core/roles.js"
 import * as users from "../core/users.js"
 import { createLogger } from "../diagnostics/logging.js"
 import { createConvexStore } from "./store.js"
 
-type Db = GenericDatabaseReader<GenericDataModel> | GenericDatabaseWriter<GenericDataModel>
-/** The subset of a Convex query/mutation ctx the system needs. */
+// `any` data model on purpose: an app's generated QueryCtx/MutationCtx (with its
+// own tables) must be assignable here without a cast.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Db = GenericDatabaseReader<any> | GenericDatabaseWriter<any>
+/** The subset of a Convex query/mutation ctx the system needs. Any app's ctx fits. */
 export interface DbCtx { db: Db; auth: Auth }
 
 export interface ConvexSystemOptions extends SystemOptions {
@@ -55,10 +59,16 @@ export interface ContextOptions { apiKey?: string | undefined; operationId?: str
 
 const OPERATION_ID = /^[A-Za-z0-9_-]{8,64}$/
 
-const defaultIdentity = (i: UserIdentity): VerifiedIdentity => {
+/**
+ * Default mapping. Convex sets `emailVerified` only for OIDC providers; custom
+ * JWT providers (WorkOS, Better Auth, most OIDC setups through customJwt) pass
+ * the claim through raw as `email_verified`, so read both.
+ */
+export const defaultIdentity = (i: UserIdentity): VerifiedIdentity => {
   const out: VerifiedIdentity = { provider: i.issuer, subject: i.subject }
-  if (i.email) out.email = i.email
-  if (i.emailVerified !== undefined) out.emailVerified = i.emailVerified
+  if (typeof i.email === "string" && i.email) out.email = i.email
+  const verified = i.emailVerified ?? (i as Record<string, unknown>).email_verified
+  if (typeof verified === "boolean") out.emailVerified = verified
   return out
 }
 
@@ -303,6 +313,19 @@ export function defineConvexSystem(options: ConvexSystemOptions = {}) {
       apiKeys.rotateApiKey(sys, actor, a.apiKeyId, { prefix: a.prefix, hash: a.hash }),
     ),
 
+    // --- Super tools: view as role -----------------------------------------------------------
+    /** `{ canViewAs, roleView }` for the caller. */
+    roleViewStatus: query({}, (sys, actor) => roleView.roleViewStatus(sys, actor)),
+    /** A real Super previews the system as `roleId`. Human sessions only; audited. */
+    startRoleView: mutationGeneric({
+      args: { roleId: v.string(), operationId: v.optional(v.string()) },
+      handler: (ctx, a) => run(ctx, { operationId: a.operationId }, (sys, actor) => roleView.startRoleView(sys, actor, a.roleId)),
+    }),
+    stopRoleView: mutationGeneric({
+      args: { operationId: v.optional(v.string()) },
+      handler: (ctx, a) => run(ctx, { operationId: a.operationId }, (sys, actor) => roleView.stopRoleView(sys, actor)),
+    }),
+
     // --- Feature flags & audit ------------------------------------------------------------
     listFeatureFlags: query({}, (sys, actor) => flags.listFlags(sys, actor)),
     setFeatureFlag: mutation({ flagId: v.string(), value: v.boolean() }, (sys, actor, a) => flags.setFlag(sys, actor, a.flagId, a.value)),

package/src/convex/index.ts

@@ -1,7 +1,7 @@
 // Convex integration: schema tables, store adapter, system functions and guards.
 export { systemTables } from "./schema.js"
 export { createConvexStore } from "./store.js"
-export { defineConvexSystem, toConvexError, type ConvexSystem, type ConvexSystemOptions, type ContextOptions, type DbCtx } from "./functions.js"
+export { defaultIdentity, defineConvexSystem, toConvexError, type ConvexSystem, type ConvexSystemOptions, type ContextOptions, type DbCtx } from "./functions.js"
 
 // Runtime-agnostic services, for custom Convex functions built on `system.context(ctx)`.
 export * from "../core/index.js"

package/src/convex/schema.ts

@@ -169,4 +169,7 @@ export const systemTables = {
   }).index("by_key", ["key"]),
 
   systemMeta: defineTable({ key: v.string(), catalogVersion: v.string(), registeredAt: v.number() }).index("by_key", ["key"]),
+
+  /** "View as role": one row per Super previewing a role (key = user ID). */
+  roleViews: defineTable({ key: v.string(), roleId: v.string(), startedAt: v.number() }).index("by_key", ["key"]),
 }

package/src/core/access.ts

@@ -74,7 +74,34 @@ export function isSuperUser(sys: SystemContext, user: UserRow | null | undefined
   return !!user && user.status === "active" && user.emailVerified && sys.superEmails.has(normalizeEmail(user.email))
 }
 
+/**
+ * The role a Super is previewing ("view as role"), or null. Only a real Super
+ * can have one; an archived or deleted role ends the preview.
+ */
+export async function activeRoleView(sys: SystemContext, user: UserRow | null | undefined): Promise<string | null> {
+  if (!user || !isSuperUser(sys, user)) return null
+  const view = await sys.store.get("roleViews", user.key)
+  if (!view) return null
+  const role = await sys.store.get("roles", view.roleId)
+  return role && !role.archived ? view.roleId : null
+}
+
+/** Super with Super rights in effect: false while previewing a role. */
+export async function isEffectiveSuperUser(sys: SystemContext, user: UserRow | null | undefined): Promise<boolean> {
+  return isSuperUser(sys, user) && !(await activeRoleView(sys, user))
+}
+
+/**
+ * Whether the actor acts as Super right now. A Super previewing a role does
+ * not: every check then treats them as a holder of that role.
+ */
 export async function isSuperActor(sys: SystemContext, actor: Actor | null): Promise<boolean> {
+  if (!actor || actor.kind !== "user") return false
+  return isEffectiveSuperUser(sys, await sys.store.get("users", actor.userId))
+}
+
+/** Super by account and deployment list, ignoring a role preview (to start or stop one). */
+export async function isRealSuperActor(sys: SystemContext, actor: Actor | null): Promise<boolean> {
   if (!actor || actor.kind !== "user") return false
   return isSuperUser(sys, await sys.store.get("users", actor.userId))
 }
@@ -123,10 +150,14 @@ type Grantee = { userId: string } | { apiKeyId: string }
 
 /** Roles currently held by a grantee (excluding archived). Includes implicit roles for users. */
 export async function heldRoleIds(sys: SystemContext, grantee: Grantee): Promise<string[]> {
-  const ids =
-    "userId" in grantee
-      ? [...(await sys.store.findBy("userRoles", "userId", grantee.userId)).map((r) => r.roleId), ...implicitRoleIds(sys)]
-      : (await sys.store.findBy("apiKeyRoles", "apiKeyId", grantee.apiKeyId)).map((r) => r.roleId)
+  let ids: string[]
+  if ("userId" in grantee) {
+    // A Super previewing a role holds exactly that role (plus implicit ones).
+    const view = await activeRoleView(sys, await sys.store.get("users", grantee.userId))
+    ids = [...(view ? [view] : (await sys.store.findBy("userRoles", "userId", grantee.userId)).map((r) => r.roleId)), ...implicitRoleIds(sys)]
+  } else {
+    ids = (await sys.store.findBy("apiKeyRoles", "apiKeyId", grantee.apiKeyId)).map((r) => r.roleId)
+  }
   const out: string[] = []
   for (const id of new Set(ids)) {
     const role = await sys.store.get("roles", id)
@@ -167,15 +198,17 @@ async function decideUnsafe(sys: SystemContext, actor: Actor | null, permission:
   if (actor.kind === "user") {
     const user = await sys.store.get("users", actor.userId)
     if (!user || user.status !== "active") return deny(permission, "account_inactive", moduleId)
-    // Active Super may use every registered module and permission, including disabled modules.
-    if (isSuperUser(sys, user)) return { allowed: true, permission, reason: "super", moduleId }
+    // Active Super may use every registered module and permission, including disabled
+    // modules, unless previewing a role: then the role's grants below apply.
+    if (await isEffectiveSuperUser(sys, user)) return { allowed: true, permission, reason: "super", moduleId }
     if (!isModuleEnabled(sys, moduleRow)) return deny(permission, "module_disabled", moduleId)
     const paths = await grantPaths(sys, { userId: user.key }, permission)
     return paths.length ? { allowed: true, permission, reason: "granted", moduleId, paths } : deny(permission, "not_granted", moduleId)
   }
 
   // Agent: active key, active owner, enabled module (no Super exception),
-  // permission through key roles AND the owner's current permission.
+  // permission through key roles AND the owner's current permission. The owner's
+  // real Super status counts here: a role preview never breaks their agents.
   const key = await sys.store.get("apiKeys", actor.apiKeyId)
   if (!key || key.ownerId !== actor.ownerId || apiKeyStatus(key, sys.now()) !== "active") return deny(permission, "key_inactive", moduleId)
   if (perm.humanOnly) return deny(permission, "human_only", moduleId)
@@ -273,7 +306,7 @@ export async function permissionsOfSubrole(sys: SystemContext, subroleId: string
 export async function entitlements(sys: SystemContext, userId: string): Promise<Set<string>> {
   const user = await sys.store.get("users", userId)
   if (!user || user.status !== "active") return new Set()
-  if (isSuperUser(sys, user)) {
+  if (await isEffectiveSuperUser(sys, user)) {
     const rows = await sys.store.all("permissions")
     return new Set(rows.filter((r) => r.status === "active" && sys.def.catalog.permissions.has(r.key)).map((r) => r.key))
   }

package/src/core/index.ts

@@ -17,3 +17,4 @@ export * from "./api-keys.js"
 export * from "./modules-service.js"
 export * from "./feature-flags.js"
 export * from "./jobs.js"
+export * from "./role-view.js"

package/src/core/modules-service.ts

@@ -11,6 +11,7 @@ import {
   type Decision,
 } from "./access.js"
 import { recordAudit } from "./audit.js"
+import { roleViewStatus, type RoleViewStatus } from "./role-view.js"
 import type { SystemContext } from "./context.js"
 import { notFound, validation } from "./errors.js"
 import { flagValue } from "./feature-flags.js"
@@ -89,14 +90,18 @@ export interface SessionSummary {
   permissions: string[]
   /** Effective flag values in modules the actor can use. */
   flags: Record<string, boolean>
+  /** The caller is a real Super and may use "view as role". */
+  canViewAs: boolean
+  /** The role a Super is previewing; then `actor.isSuper` is false and everything else is that role's. */
+  roleView: RoleViewStatus["roleView"]
 }
 
 export async function sessionSummary(sys: SystemContext, actor: Actor | null): Promise<SessionSummary> {
-  if (!actor) return { actor: null, modules: [], permissions: [], flags: {} }
+  if (!actor) return { actor: null, modules: [], permissions: [], flags: {}, canViewAs: false, roleView: null }
   let actorOut: SessionSummary["actor"]
   if (actor.kind === "user") {
     const user = await sys.store.get("users", actor.userId)
-    if (!user || user.status !== "active") return { actor: null, modules: [], permissions: [], flags: {} }
+    if (!user || user.status !== "active") return { actor: null, modules: [], permissions: [], flags: {}, canViewAs: false, roleView: null }
     actorOut = { kind: "user", userId: user.key, email: user.email, isSuper: await isSuperActor(sys, actor) }
     if (user.displayName) actorOut.displayName = user.displayName
   } else {
@@ -107,5 +112,6 @@ export async function sessionSummary(sys: SystemContext, actor: Actor | null): P
   const usable = new Set(modules.map((m) => m.id))
   const flags: Record<string, boolean> = {}
   for (const f of sys.def.catalog.flags.values()) if (usable.has(f.moduleId)) flags[f.id] = await flagValue(sys, f.id)
-  return { actor: actorOut, modules, permissions: await effectivePermissions(sys, actor), flags }
+  const view = actor.kind === "user" ? await roleViewStatus(sys, actor) : { canViewAs: false, roleView: null }
+  return { actor: actorOut, modules, permissions: await effectivePermissions(sys, actor), flags, ...view }
 }

package/src/core/role-view.ts

@@ -0,0 +1,43 @@
+// "View as role": a Super previews the system as a holder of one role. While
+// active, access decisions, entitlements, delegation and the session treat the
+// Super as that role (see access.ts). Human Super sessions only; audited.
+import { activeRoleView, isRealSuperActor, requireHuman, withOperation, type Actor } from "./access.js"
+import { recordAudit } from "./audit.js"
+import type { SystemContext } from "./context.js"
+import { forbidden, notFound, validation } from "./errors.js"
+import { PROFILE_ROLE_ID } from "./system-modules.js"
+
+export interface RoleViewStatus {
+  /** The caller is a real Super and may start a preview. */
+  canViewAs: boolean
+  roleView: { roleId: string; roleName: string } | null
+}
+
+export async function roleViewStatus(sys: SystemContext, actor: Actor | null): Promise<RoleViewStatus> {
+  if (!actor || actor.kind !== "user" || !(await isRealSuperActor(sys, actor))) return { canViewAs: false, roleView: null }
+  const roleId = await activeRoleView(sys, await sys.store.get("users", actor.userId))
+  const role = roleId ? await sys.store.get("roles", roleId) : null
+  return { canViewAs: true, roleView: role ? { roleId: role.key, roleName: role.name } : null }
+}
+
+export async function startRoleView(sys: SystemContext, actor: Actor | null, roleId: string): Promise<{ roleId: string; roleName: string }> {
+  const human = requireHuman(sys, actor)
+  if (!(await isRealSuperActor(sys, human))) throw withOperation(sys, forbidden("super_required"))
+  if (roleId === PROFILE_ROLE_ID) throw withOperation(sys, validation("profile_role", ["roleId"]))
+  const role = await sys.store.get("roles", roleId)
+  if (!role || role.archived) throw withOperation(sys, notFound())
+  const existing = await sys.store.get("roleViews", human.userId)
+  if (existing) await sys.store.patch("roleViews", human.userId, { roleId, startedAt: sys.now() })
+  else await sys.store.insert("roleViews", { key: human.userId, roleId, startedAt: sys.now() })
+  await recordAudit(sys, human, { action: "super.role_view.start", targetType: "role", targetId: roleId })
+  return { roleId, roleName: role.name }
+}
+
+export async function stopRoleView(sys: SystemContext, actor: Actor | null): Promise<{ stopped: boolean }> {
+  const human = requireHuman(sys, actor)
+  const existing = await sys.store.get("roleViews", human.userId)
+  if (!existing) return { stopped: false }
+  await sys.store.delete("roleViews", human.userId)
+  await recordAudit(sys, human, { action: "super.role_view.stop", targetType: "role", targetId: existing.roleId })
+  return { stopped: true }
+}

package/src/core/store.ts

@@ -143,6 +143,9 @@ export interface SystemOperationRow {
 
 export interface SystemMetaRow { key: string; catalogVersion: string; registeredAt: number }
 
+/** A Super previewing the system as a role. `key` is the Super's user ID. */
+export interface RoleViewRow { key: string; roleId: string; startedAt: number }
+
 export interface Tables {
   users: UserRow
   identities: IdentityRow
@@ -161,6 +164,7 @@ export interface Tables {
   auditEvents: AuditEventRow
   systemOperations: SystemOperationRow
   systemMeta: SystemMetaRow
+  roleViews: RoleViewRow
 }
 
 export type TableName = keyof Tables
@@ -184,6 +188,7 @@ export const INDEXES = {
   auditEvents: ["operationId", "actorUserId", "targetId"],
   systemOperations: [],
   systemMeta: [],
+  roleViews: [],
 } as const satisfies { [T in TableName]: readonly (keyof Tables[T] & string)[] }
 
 export type IndexField<T extends TableName> = (typeof INDEXES)[T][number] & keyof Tables[T]

package/src/finance/index.ts

@@ -0,0 +1,189 @@
+// `@digimuza/system-core/finance`: the finance business module (invoices and
+// their approval), reusable by every client app.
+//
+//   // convex/schema.ts
+//   export default defineSchema({ ...systemTables, ...financeTables })
+//   // convex/system.ts
+//   export const system = defineConvexSystem({ modules: [finance] })
+//   // convex/finance.ts
+//   export const { listInvoices, createInvoice, approveInvoice, bulkApproveInvoices } = defineFinance(system)
+//
+// Every function guards itself on the server (permission, module enabled,
+// role view) in the same transaction as the change and writes an audit event.
+import { defineTable, mutationGeneric, queryGeneric } from "convex/server"
+import type { GenericId } from "convex/values"
+import { v } from "convex/values"
+import { isFeatureEnabled, recordAudit, SystemError, type Actor } from "../core/index.js"
+import { toConvexError, type ConvexSystem } from "../convex/functions.js"
+import { defineModule, type PermissionOf } from "../modules/index.js"
+
+export const finance = defineModule({
+  id: "finance",
+  kind: "business",
+  description: "Sąskaitų peržiūra ir tvirtinimas",
+  permissions: [
+    { id: "finance:invoice:read", name: "Skaityti", description: "Peržiūrėti sąskaitas" },
+    { id: "finance:invoice:create", name: "Kurti", description: "Sukurti sąskaitą" },
+    { id: "finance:invoice:approve", name: "Tvirtinti", description: "Patvirtinti sąskaitą" },
+  ],
+  initialSubroles: [
+    { id: "finance:reader", name: "Skaitytojas", description: "Gali peržiūrėti sąskaitas", permissions: ["finance:invoice:read"] },
+    {
+      id: "finance:accountant",
+      name: "Buhalteris",
+      description: "Gali kurti, peržiūrėti ir tvirtinti sąskaitas",
+      permissions: ["finance:invoice:read", "finance:invoice:create", "finance:invoice:approve"],
+    },
+  ],
+  featureFlags: [{ id: "finance:bulk-approve", description: "Tvirtinti kelias sąskaitas vienu veiksmu", default: false }],
+})
+
+export const FinancePermissions = {
+  read: "finance:invoice:read",
+  create: "finance:invoice:create",
+  approve: "finance:invoice:approve",
+} as const satisfies Record<string, PermissionOf<typeof finance>>
+
+export const FINANCE_BULK_APPROVE_FLAG = "finance:bulk-approve"
+export const FINANCE_BULK_LIMIT = 50
+
+/** Spread into the app schema next to `systemTables`. */
+export const financeTables = {
+  invoices: defineTable({
+    number: v.string(),
+    customer: v.string(),
+    amountCents: v.number(),
+    currency: v.string(),
+    status: v.union(v.literal("draft"), v.literal("approved")),
+    createdBy: v.string(),
+    approvedBy: v.optional(v.string()),
+    approvedAt: v.optional(v.number()),
+  })
+    .index("by_number", ["number"])
+    .index("by_status", ["status"]),
+}
+
+export type InvoiceStatus = "draft" | "approved"
+
+/** Convex ID of an invoice in the app's `invoices` table. */
+export type InvoiceId = GenericId<"invoices">
+
+export interface InvoiceView {
+  id: InvoiceId
+  number: string
+  customer: string
+  amountCents: number
+  currency: string
+  status: InvoiceStatus
+  createdAt: number
+  approvedAt: number | null
+}
+
+interface InvoiceDoc {
+  _id: InvoiceId
+  _creationTime: number
+  number: string
+  customer: string
+  amountCents: number
+  currency: string
+  status: InvoiceStatus
+  approvedAt?: number
+}
+
+const view = (i: InvoiceDoc): InvoiceView => ({
+  id: i._id,
+  number: i.number,
+  customer: i.customer,
+  amountCents: i.amountCents,
+  currency: i.currency,
+  status: i.status,
+  createdAt: i._creationTime,
+  approvedAt: i.approvedAt ?? null,
+})
+
+const actorId = (a: Actor) => (a.kind === "user" ? a.userId : a.apiKeyId)
+const actorArgs = { apiKey: v.optional(v.string()), operationId: v.optional(v.string()) }
+const opts = (a: { apiKey?: string | undefined; operationId?: string | undefined }) => ({ apiKey: a.apiKey, operationId: a.operationId })
+
+function fail(code: "NOT_FOUND" | "CONFLICT" | "VALIDATION" | "FORBIDDEN", reason: string, operationId: string): never {
+  throw toConvexError(new SystemError(code, undefined, { reason, operationId }), operationId)
+}
+
+/** The module's Convex functions, bound to the app's system. Re-export them from `convex/finance.ts`. */
+export function defineFinance(system: ConvexSystem) {
+  // A loosely typed db handle: the app's schema contains `financeTables`.
+  type Db = {
+    query(t: "invoices"): {
+      withIndex(i: string, f: (q: { eq(field: string, value: unknown): unknown }) => unknown): { order(o: "asc" | "desc"): { take(n: number): Promise<InvoiceDoc[]> }; unique(): Promise<InvoiceDoc | null> }
+      order(o: "asc" | "desc"): { take(n: number): Promise<InvoiceDoc[]> }
+    }
+    get(t: "invoices", id: string): Promise<InvoiceDoc | null>
+    insert(t: "invoices", doc: Record<string, unknown>): Promise<InvoiceId>
+    patch(t: "invoices", id: string, doc: Record<string, unknown>): Promise<void>
+  }
+  const db = (ctx: { db: unknown }) => ctx.db as Db
+
+  async function approveOne(ctx: { db: unknown }, operationId: string, invoiceId: string, by: string) {
+    const invoice = await db(ctx).get("invoices", invoiceId)
+    // A missing invoice and one the caller may not see look the same.
+    if (!invoice) fail("NOT_FOUND", "invoice_not_found", operationId)
+    if (invoice!.status !== "draft") fail("CONFLICT", "invoice_not_draft", operationId)
+    await db(ctx).patch("invoices", invoiceId, { status: "approved", approvedBy: by, approvedAt: Date.now() })
+  }
+
+  return {
+    listInvoices: queryGeneric({
+      args: { ...actorArgs, status: v.optional(v.union(v.literal("draft"), v.literal("approved"))) },
+      handler: async (ctx, a): Promise<InvoiceView[]> => {
+        await system.requirePermission(ctx, FinancePermissions.read, opts(a))
+        const q = db(ctx).query("invoices")
+        const rows = a.status ? await q.withIndex("by_status", (i) => i.eq("status", a.status)).order("desc").take(100) : await q.order("desc").take(100)
+        return rows.map(view)
+      },
+    }),
+
+    createInvoice: mutationGeneric({
+      args: { ...actorArgs, number: v.string(), customer: v.string(), amountCents: v.number(), currency: v.optional(v.string()) },
+      handler: async (ctx, a): Promise<{ invoiceId: InvoiceId; operationId: string }> => {
+        const { sys, actor } = await system.requirePermission(ctx, FinancePermissions.create, opts(a))
+        const number = a.number.trim()
+        const customer = a.customer.trim()
+        if (!number || !customer || !Number.isInteger(a.amountCents) || a.amountCents <= 0) fail("VALIDATION", "invalid_invoice", sys.operationId)
+        const currency = (a.currency ?? "EUR").toUpperCase()
+        if (!/^[A-Z]{3}$/.test(currency)) fail("VALIDATION", "invalid_currency", sys.operationId)
+        const existing = await db(ctx).query("invoices").withIndex("by_number", (i) => i.eq("number", number)).unique()
+        if (existing) fail("CONFLICT", "invoice_number_taken", sys.operationId)
+        const invoiceId = await db(ctx).insert("invoices", { number, customer, amountCents: a.amountCents, currency, status: "draft", createdBy: actorId(actor) })
+        await recordAudit(sys, actor, { action: "finance.invoice.create", targetType: "invoice", targetId: invoiceId, changes: { number } })
+        return { invoiceId, operationId: sys.operationId }
+      },
+    }),
+
+    approveInvoice: mutationGeneric({
+      args: { ...actorArgs, invoiceId: v.id("invoices") },
+      handler: async (ctx, a): Promise<{ operationId: string }> => {
+        const { sys, actor } = await system.requirePermission(ctx, FinancePermissions.approve, opts(a))
+        await approveOne(ctx, sys.operationId, a.invoiceId, actorId(actor))
+        await recordAudit(sys, actor, { action: "finance.invoice.approve", targetType: "invoice", targetId: a.invoiceId })
+        return { operationId: sys.operationId }
+      },
+    }),
+
+    /** Behind the `finance:bulk-approve` flag. The flag never grants the permission. */
+    bulkApproveInvoices: mutationGeneric({
+      args: { ...actorArgs, invoiceIds: v.array(v.id("invoices")) },
+      handler: async (ctx, a): Promise<{ approved: number; operationId: string }> => {
+        const { sys, actor } = await system.requirePermission(ctx, FinancePermissions.approve, opts(a))
+        if (!(await isFeatureEnabled(sys, FINANCE_BULK_APPROVE_FLAG))) fail("FORBIDDEN", "flag_off", sys.operationId)
+        if (a.invoiceIds.length > FINANCE_BULK_LIMIT) fail("VALIDATION", "too_many", sys.operationId)
+        for (const id of a.invoiceIds) {
+          await approveOne(ctx, sys.operationId, id, actorId(actor))
+          await recordAudit(sys, actor, { action: "finance.invoice.approve", targetType: "invoice", targetId: id, changes: { bulk: true } })
+        }
+        return { approved: a.invoiceIds.length, operationId: sys.operationId }
+      },
+    }),
+  }
+}
+
+export type FinanceFunctions = ReturnType<typeof defineFinance>

package/src/react/index.tsx

@@ -13,9 +13,9 @@ export type SessionState =
   | ({ status: "anonymous" } & EmptySession)
   | ({ status: "ready" } & SessionSummary & { actor: NonNullable<SessionSummary["actor"]> })
 
-type EmptySession = { actor: null; modules: ModuleState[]; permissions: string[]; flags: Record<string, boolean> }
+type EmptySession = Omit<SessionSummary, "actor"> & { actor: null }
 
-const EMPTY: EmptySession = { actor: null, modules: [], permissions: [], flags: {} }
+const EMPTY: EmptySession = { actor: null, modules: [], permissions: [], flags: {}, canViewAs: false, roleView: null }
 const LOADING: SessionState = { status: "loading", ...EMPTY }
 
 const SessionContext = createContext<SessionState | null>(null)
@@ -59,6 +59,16 @@ export function useCan(permission: string): boolean {
   return useSystemSession().permissions.includes(permission)
 }
 
+/**
+ * "View as role" state: `canViewAs` for a real Super, `roleView` while a preview
+ * is active (then the rest of the session is that role's). Start and stop with
+ * the `startRoleView` / `stopRoleView` mutations.
+ */
+export function useRoleView(): Pick<SessionSummary, "canViewAs" | "roleView"> {
+  const { canViewAs, roleView } = useSystemSession()
+  return { canViewAs, roleView }
+}
+
 export function useFeatureFlag(flagId: string): boolean {
   return useSystemSession().flags[flagId] === true
 }