@selvajs/platform 0.16.1-beta.2 → 0.17.0

package/README.md

@@ -1,6 +1,6 @@
 # @selvajs/platform
 
-Pure TypeScript interfaces that define Selva's contract with its backends. No runtime dependencies on a specific database, storage, or auth service — every concrete adapter (local filesystem, Supabase, Azure, ...) lives in its own package and implements these interfaces.
+Pure TypeScript interfaces defining Selva's contract with its backends — no runtime dependency on a specific database, storage, or auth service. Concrete adapters (local filesystem, Supabase, Azure, ...) live in their own packages and implement these interfaces.
 
 This README is the contract. Read it before writing an adapter.
 
@@ -8,20 +8,21 @@ This README is the contract. Read it before writing an adapter.
 
 ## Interfaces at a glance
 
-| Interface                  | Purpose                                                                           | Scoped by `RequestContext`?                                          |
-| -------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `IAuthProvider`            | Verify tokens, manage users, issue sessions. Optional `passwordAuth?` capability. | No — the auth provider produces the identity that fills the context. |
-| `IPlatformPermissionStore` | Per-user platform permissions; owns the sole-`instance_admin` invariant.          | Yes — every method.                                                  |
-| `IUserProfileStore`        | Per-user profile (display name, starred definitions, recent runs).                | Yes — adapters scope by `ctx.userId`.                                |
-| `IOrgStore`                | Orgs and org memberships.                                                         | Yes — every method.                                                  |
-| `IProjectStore`            | Projects and project memberships.                                                 | Yes — every method.                                                  |
-| `IDefinitionStore`         | Definition metadata records + version history.                                    | Yes — every method.                                                  |
-| `IShareLinkStore`          | Per-definition anonymous-access tokens.                                           | Yes — every method.                                                  |
-| `IInviteStore`             | Pending org-membership invitations.                                               | Yes — every method.                                                  |
-| `IComputeServerStore`      | Global + per-org compute-server config.                                           | No — not tenant-scoped.                                              |
-| `IStorageProvider`         | Path-based blob storage. Authorization is the caller's responsibility.            | No — callers pass already-authorized paths.                          |
-
-`IDataProvider` composes every store: `{ orgs, projects, definitions, computeServer, invites, shareLinks, userProfile, permissions }`. An adapter typically implements one class per store and aggregates them.
+| Interface                    | Purpose                                                                           | Scoped by `RequestContext`?                                          |
+| ---------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `IAuthProvider`              | Verify tokens, manage users, issue sessions. Optional `passwordAuth?` capability. | No — the auth provider produces the identity that fills the context. |
+| `IPlatformPermissionStore`   | Per-user platform permissions; owns the sole-`instance_admin` invariant.          | Yes — every method.                                                  |
+| `IUserProfileStore`          | Per-user profile (display name, starred definitions, recent runs).                | Yes — adapters scope by `ctx.userId`.                                |
+| `IOrgStore`                  | Orgs and org memberships.                                                         | Yes — every method.                                                  |
+| `IProjectStore`              | Projects and project memberships.                                                 | Yes — every method.                                                  |
+| `IPlatformProjectGrantStore` | Instance-admin-managed grants onto `platform`-visibility projects.                | Yes — every method.                                                  |
+| `IDefinitionStore`           | Definition metadata records + version history.                                    | Yes — every method.                                                  |
+| `IShareLinkStore`            | Per-definition anonymous-access tokens.                                           | Yes — every method.                                                  |
+| `IInviteStore`               | Pending org-membership invitations.                                               | Yes — every method.                                                  |
+| `IComputeServerStore`        | Global + per-org compute-server config.                                           | No — not tenant-scoped.                                              |
+| `IStorageProvider`           | Path-based blob storage. Authorization is the caller's responsibility.            | No — callers pass already-authorized paths.                          |
+
+`IDataProvider` composes every store, plus optional `auditQuery` / `events` hooks and lifecycle methods `ensureUser` and `onUserDeleted`. An adapter typically implements one class per store and aggregates them.
 
 ---
 
@@ -38,15 +39,15 @@ This README is the contract. Read it before writing an adapter.
 
 ## Transaction ordering rules
 
-Providers are two-phase: a metadata store (`IDataProvider`) and a blob store (`IStorageProvider`). They have no shared transaction. The consumer's orchestration layer (`DefinitionService` in `@selvajs/selva`) composes them with fixed ordering so partial failure is recoverable.
+Providers are two-phase: a metadata store (`IDataProvider`) and a blob store (`IStorageProvider`) with no shared transaction. `DefinitionService` (`@selvajs/server/definitions`) composes them with fixed ordering so partial failure is recoverable.
 
-**Create — metadata-first with `pending` → `ready`:**
+**Create — metadata-first, `pending` → `draft`:**
 
 1. Write the record with `status: 'pending'`.
 2. Upload the blob.
-3. Flip `status` to `'ready'`.
+3. `attachInitialVersion` flips `status` to `'draft'`.
 
-List queries filter `'pending'` by default (`ListOptions.includePending` opts in). If step 2 fails, the record stays `'pending'` and is invisible to consumers.
+List queries filter `'pending'` and `'archived'` by default (`DefinitionListOptions.includePending` / `includeArchived` opt in). If step 2 fails, the record stays `'pending'` and is invisible to consumers.
 
 **Delete — blob-first:**
 
@@ -55,10 +56,6 @@ List queries filter `'pending'` by default (`ListOptions.includePending` opts in
 
 If step 2 fails, a retry re-deletes blobs (no-op) and succeeds.
 
-**Update-file — best-effort, retry-safe:**
-
-Archive current → append history → write new → prune history. These are four separate writes, so a crash can leave the sequence half-done. That is survivable because re-running the same update from the start lands on the same end state — each step either has already happened or still needs to, and repeating one is harmless.
-
 ---
 
 ## A minimal adapter
@@ -69,19 +66,19 @@ import type {
 	DefinitionRecord,
 	DefinitionRecordPatch,
 	RequestContext,
-	ListOptions,
+	DefinitionListOptions,
 	Page
 } from '@selvajs/platform';
 
 export class MyDefinitionStore implements IDefinitionStore {
-	async list(ctx: RequestContext, opts?: ListOptions): Promise<Page<DefinitionRecord>> {
+	async list(ctx: RequestContext, opts?: DefinitionListOptions): Promise<Page<DefinitionRecord>> {
 		// Filter by ctx.actingOrgId; exclude status='pending' unless opts.includePending.
 	}
 	// ... etc
 }
 ```
 
-Wire it into a `SelvaConfig` via `defineConfig({ auth, data, storage })`. `data` is an `IDataProvider` that composes every store (orgs, projects, definitions, invites, share-links, compute server, user profile, platform permissions).
+Wire it into a `SelvaConfig` via `defineConfig({ auth, data, storage })`. `data` is an `IDataProvider` composing every store.
 
 ---
 
@@ -99,7 +96,7 @@ runDefinitionStoreConformance({
 });
 ```
 
-The suites cover `ctx` scoping, `pending` filtering, `includePending` opt-in, history pruning, and `ProviderError` shapes. They do not cover performance or concurrency.
+The suites cover `ctx` scoping, `pending` filtering, `includePending` opt-in, and `ProviderError` shapes. They do not cover performance or concurrency.
 
 ---
 
@@ -111,7 +108,7 @@ Throw `ProviderError` for user-facing failures (`new ProviderError('...', 404)`)
 
 ## Data privacy
 
-User identity, credentials, and personal data are owned by the auth provider. Selva stores session tokens that carry no information themselves, plus user IDs and authorization metadata. What a deployment holds and who is responsible for it: [Providers](https://github.com/VektorNode/selva/blob/main/docs/self-hosting/providers/overview.md) and [Security & Limits](https://github.com/VektorNode/selva/blob/main/docs/self-hosting/concepts/security-and-limits.md).
+Identity and credentials belong to whichever `IAuthProvider` is configured — for Supabase that's a separate service; for the local provider, Selva itself is the auth provider and holds credentials on disk. This package's own stores hold only opaque session data, user IDs, and authorization metadata. Details: [Providers](https://github.com/VektorNode/selva/blob/main/docs/self-hosting/providers/overview.md) and [Security & Limits](https://github.com/VektorNode/selva/blob/main/docs/self-hosting/concepts/security-and-limits.md).
 
 ---
 

package/dist/access/rules.d.ts

@@ -22,30 +22,27 @@ export interface ProjectAccessInput {
      * admins — so the feature can be hidden silently without deleting data.
      */
     enablePlatformProjects: boolean;
-    /**
-     * Grants for `platform`-visibility projects. Pass an empty array for
-     * non-platform projects — the rule only consults this for `platform`.
-     */
+    /** Grants for `platform`-visibility projects; empty for non-platform ones. */
     platformGrants: readonly PlatformProjectGrant[];
-    /** `ctx.actingOrgId` — used to match org grants on platform projects. */
+    /** `ctx.actingOrgId` — matches org grants on platform projects. */
     actingOrgId: string | null;
-    /** `ctx.userId` — used to match user grants on platform projects. */
+    /** `ctx.userId` — matches user grants on platform projects. */
     userId: string;
 }
 /**
- * Authenticated-user view rule. Anonymous access is delivered via share-link
- * tokens — the route resolves a valid token before this rule runs.
+ * Authenticated-user view rule. Anonymous access goes through share-link
+ * tokens instead — the route resolves a valid token before this runs.
  *
- * For `platform` projects: `instance_admin` always passes; otherwise any
- * grant (view-only or canSolve) satisfies view access.
+ * Platform projects: `instance_admin` always passes; otherwise any grant
+ * (view-only or canSolve) satisfies view access.
  */
 export declare function canView(input: ProjectAccessInput): boolean;
 /**
- * For non-platform projects: same as `canView` today — kept distinct for
- * future cost gating.
+ * Non-platform projects: same as `canView` — kept as a separate function so
+ * cost gating can diverge from view access later.
  *
- * For `platform` projects: `instance_admin` always passes; a view-only grant
- * satisfies `canView` but NOT `canSolve` — the grant must have `canSolve=true`.
+ * Platform projects: `instance_admin` always passes; a view-only grant
+ * satisfies `canView` but not `canSolve` — the grant needs `canSolve: true`.
  */
 export declare function canSolve(input: ProjectAccessInput): boolean;
 /**
@@ -92,11 +89,11 @@ export interface ReclaimAccessInput {
     actingOrgId: string | null;
 }
 /**
- * Org leadership escape hatch. Reclaim adds the actor as co-owner; it does
- * NOT demote the existing owner. Tenancy must match.
+ * Org leadership escape hatch: adds the actor as co-owner without demoting
+ * the existing owner. Tenancy must match.
  *
- * Platform projects cannot be reclaimed — `instance_admin` always has
- * management access to them without needing the Reclaim mechanism.
+ * Platform projects can't be reclaimed — `instance_admin` already has
+ * management access to them.
  */
 export declare function canReclaim(input: ReclaimAccessInput): boolean;
 export interface CreateProjectAccessInput {
@@ -106,22 +103,19 @@ export interface CreateProjectAccessInput {
     targetOrgId: string;
 }
 /**
- * Owner/admin can always create. A `member` needs `manage_projects` org
+ * Owner/admin can always create; a `member` needs `manage_projects` org
  * permission. Tenancy is enforced.
  *
- * Platform projects (`visibility='platform'`) are created via the admin API
- * and gated on `instance_admin` — this rule is not consulted for them.
+ * Platform projects (`visibility: 'platform'`) go through the admin API,
+ * gated on `instance_admin` — this rule isn't consulted for them.
  */
 export declare function canCreateProject(input: CreateProjectAccessInput): boolean;
 /**
- * Pre-flight check for project-owner removal. Pure function over already-
- * loaded membership rows so route handlers can call it after `canManage`.
+ * Pre-flight check for project-owner removal, run after `canManage`.
  *
  * - `ok` — proceed
- * - `sole_owner` — last owner; route surfaces 409 + suggests reclaim
+ * - `sole_owner` — last owner; route surfaces 409 and suggests reclaim
  * - `needs_confirm` — owner-on-owner removal without `?confirm=true`
- *
- * Non-owner targets always return `ok`.
  */
 export type OwnerRemovalCheck = 'ok' | 'sole_owner' | 'needs_confirm';
 export interface OwnerRemovalInput {

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

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

package/dist/access/rules.js

@@ -3,7 +3,7 @@
  * adapters. Mutating store methods MUST re-enforce the same predicate
  * independently (RLS in SQL, code in local/JSON).
  *
- * `instance_admin` bypass is NOT baked into rule bodies — wrap calls with
+ * `instance_admin` bypass is not baked into rule bodies — wrap calls with
  * `withAdminBypass` at the call site.
  */
 function isInstanceAdmin(platformPermissions) {
@@ -15,11 +15,11 @@ export function withAdminBypass(platformPermissions, rule) {
     return rule();
 }
 /**
- * Authenticated-user view rule. Anonymous access is delivered via share-link
- * tokens — the route resolves a valid token before this rule runs.
+ * Authenticated-user view rule. Anonymous access goes through share-link
+ * tokens instead — the route resolves a valid token before this runs.
  *
- * For `platform` projects: `instance_admin` always passes; otherwise any
- * grant (view-only or canSolve) satisfies view access.
+ * Platform projects: `instance_admin` always passes; otherwise any grant
+ * (view-only or canSolve) satisfies view access.
  */
 export function canView(input) {
     const { project, member, orgMember, allowCrossOrgPublic, enablePlatformProjects, platformPermissions, platformGrants, actingOrgId, userId } = input;
@@ -42,11 +42,11 @@ export function canView(input) {
     return false;
 }
 /**
- * For non-platform projects: same as `canView` today — kept distinct for
- * future cost gating.
+ * Non-platform projects: same as `canView` — kept as a separate function so
+ * cost gating can diverge from view access later.
  *
- * For `platform` projects: `instance_admin` always passes; a view-only grant
- * satisfies `canView` but NOT `canSolve` — the grant must have `canSolve=true`.
+ * Platform projects: `instance_admin` always passes; a view-only grant
+ * satisfies `canView` but not `canSolve` — the grant needs `canSolve: true`.
  */
 export function canSolve(input) {
     const { project, enablePlatformProjects, platformPermissions, platformGrants, actingOrgId, userId } = input;
@@ -124,11 +124,11 @@ export function canEditDefinition(input) {
     return false;
 }
 /**
- * Org leadership escape hatch. Reclaim adds the actor as co-owner; it does
- * NOT demote the existing owner. Tenancy must match.
+ * Org leadership escape hatch: adds the actor as co-owner without demoting
+ * the existing owner. Tenancy must match.
  *
- * Platform projects cannot be reclaimed — `instance_admin` always has
- * management access to them without needing the Reclaim mechanism.
+ * Platform projects can't be reclaimed — `instance_admin` already has
+ * management access to them.
  */
 export function canReclaim(input) {
     const { project, orgMember, actingOrgId } = input;
@@ -142,11 +142,11 @@ export function canReclaim(input) {
     return role === 'owner' || role === 'admin';
 }
 /**
- * Owner/admin can always create. A `member` needs `manage_projects` org
+ * Owner/admin can always create; a `member` needs `manage_projects` org
  * permission. Tenancy is enforced.
  *
- * Platform projects (`visibility='platform'`) are created via the admin API
- * and gated on `instance_admin` — this rule is not consulted for them.
+ * Platform projects (`visibility: 'platform'`) go through the admin API,
+ * gated on `instance_admin` — this rule isn't consulted for them.
  */
 export function canCreateProject(input) {
     const { orgMember, orgPermissions, actingOrgId, targetOrgId } = input;

package/dist/access/rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/access/rules.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AAEH,SAAS,eAAe,CAAC,mBAAkD;IAC1E,OAAO,mBAAmB,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,eAAe,CAC9B,mBAAkD,EAClD,IAAmB;IAEnB,IAAI,eAAe,CAAC,mBAAmB,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,OAAO,IAAI,EAAE,CAAC;AACf,CAAC;AA8BD;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,KAAyB;IAChD,MAAM,EACL,OAAO,EACP,MAAM,EACN,SAAS,EACT,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,MAAM,EACN,GAAG,KAAK,CAAC;IACV,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAE3B,IAAI,OAAO,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QACvC,IAAI,CAAC,sBAAsB;YAAE,OAAO,KAAK,CAAC;QAC1C,IAAI,eAAe,CAAC,mBAAmB,CAAC;YAAE,OAAO,IAAI,CAAC;QACtD,OAAO,cAAc,CAAC,IAAI,CACzB,CAAC,CAAC,EAAE,EAAE,CACL,CAAC,CAAC,CAAC,WAAW,KAAK,MAAM,IAAI,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC;YACpD,CAAC,CAAC,CAAC,WAAW,KAAK,KAAK,IAAI,CAAC,CAAC,SAAS,KAAK,WAAW,CAAC,CACzD,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,MAAM,KAAK,IAAI,CAAC;IAC7D,IAAI,OAAO,CAAC,UAAU,KAAK,KAAK;QAAE,OAAO,SAAS,KAAK,IAAI,CAAC;IAC5D,IAAI,OAAO,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC;IAC5F,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAyB;IACjD,MAAM,EACL,OAAO,EACP,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,MAAM,EACN,GAAG,KAAK,CAAC;IACV,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAE3B,IAAI,OAAO,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QACvC,IAAI,CAAC,sBAAsB;YAAE,OAAO,KAAK,CAAC;QAC1C,IAAI,eAAe,CAAC,mBAAmB,CAAC;YAAE,OAAO,IAAI,CAAC;QACtD,OAAO,cAAc,CAAC,IAAI,CACzB,CAAC,CAAC,EAAE,EAAE,CACL,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,CAAC,CAAC,WAAW,KAAK,MAAM,IAAI,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC;gBACpD,CAAC,CAAC,CAAC,WAAW,KAAK,KAAK,IAAI,CAAC,CAAC,SAAS,KAAK,WAAW,CAAC,CAAC,CAC3D,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,KAAyB;IAChD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,GAAG,KAAK,CAAC;IAC/E,IAAI,OAAO,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;QACxC,IAAI,CAAC,sBAAsB;YAAE,OAAO,KAAK,CAAC;QAC1C,OAAO,eAAe,CAAC,mBAAmB,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,MAAM,EAAE,IAAI,KAAK,OAAO,IAAI,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAC;AAC9D,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,SAAS,CAAC,KAAyB;IAClD,IAAI,KAAK,CAAC,OAAO,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC,sBAAsB;YAAE,OAAO,KAAK,CAAC;QAChD,OAAO,eAAe,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,OAAO,CAAC;AACvC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,sBAAsB,CAAC,KAAyB;IAC/D,IAAI,KAAK,CAAC,OAAO,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC,sBAAsB;YAAE,OAAO,KAAK,CAAC;QAChD,OAAO,eAAe,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,OAAO,CAAC;AACvC,CAAC;AAMD;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAA4B;IACvE,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC;IACnC,OAAO,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,CAAC;AAC7C,CAAC;AAgBD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA4B;IAC7D,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,GACzF,KAAK,CAAC;IACP,IAAI,CAAC,OAAO,IAAI,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAE1C,IAAI,OAAO,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QACvC,IAAI,CAAC,sBAAsB;YAAE,OAAO,KAAK,CAAC;QAC1C,OAAO,eAAe,CAAC,mBAAmB,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,MAAM,EAAE,IAAI,KAAK,OAAO,IAAI,MAAM,EAAE,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvE,IAAI,OAAO,CAAC,gBAAgB,IAAI,MAAM,KAAK,UAAU,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE3E,OAAO,KAAK,CAAC;AACd,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAyB;IACnD,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAClD,IAAI,CAAC,OAAO,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,OAAO,CAAC,UAAU,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,WAAW,KAAK,OAAO,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAChD,MAAM,IAAI,GAAG,SAAS,EAAE,IAAI,CAAC;IAC7B,OAAO,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,CAAC;AAC7C,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA+B;IAC/D,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IACtE,IAAI,WAAW,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,IAAI,GAAG,SAAS,EAAE,IAAI,CAAC;IAC7B,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,IAAI,KAAK,QAAQ,IAAI,cAAc,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAAE,OAAO,IAAI,CAAC;IACjF,OAAO,KAAK,CAAC;AACd,CAAC;AAoBD,MAAM,UAAU,iBAAiB,CAAC,KAAwB;IACzD,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAC/C,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IAC7E,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,YAAY,CAAC;IACzC,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,OAAO,eAAe,CAAC;IAC7C,OAAO,IAAI,CAAC;AACb,CAAC"}
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/access/rules.ts"],"names":[],"mappings":"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"}