Entitlements and Operational Limits

PixService treats an entitlement as an organization-wide ceiling, never as a user or group grant. A user still needs an ordinary permission assignment from a protected-owner, direct-user, group, invitation, migration, or shared-resource source. The organization's exact immutable entitlement version can only narrow that ordinary result.

Use GET /v1/permissions/catalog as the source of truth for capability and operational-limit metadata. Use GET /v1/orgs/{organizationId}/entitlements for the organization's current exact version and ceilings, and GET /v1/orgs/{organizationId}/usage for authorized usage detail.

Distinguish assignments from ceilings

An assignment stores an ordinary binary or tiered value such as None, Read, Write, or Allow. None resets inheritance for that one principal; it does not deny a positive value contributed by another principal or origin.

Unavailable belongs only to an entitlement ceiling. It is not a valid assignment value. A ceiling never fills in a missing ACL and never becomes a group or direct-user assignment. When an existing assignment is above the current ceiling, the assignment remains stored and inspectable but is dormant. Current-user introspection reports the separate ordinary value, entitlement ceiling, final value, and blockedByEntitlement state.

Persisted assignment scopes are Organization, Cluster, and Location, with an optional canonical document path where the catalog permits one. Bundle, Document, Job, and similar IDs are evaluation contexts: PixService resolves them to their owning organization, Cluster, Location, and path instead of creating an ACL for an individual object.

Follow the evaluation order

For one requested context, PixService evaluates access in this order:

1. Resolve the active organization membership shell and the caller's exact credential. The shell exposes no protected product data by itself.
2. Load the direct-user, protected-owner, active-group, workflow, migration, and documented legacy Contributor sources that apply to the context.
3. Resolve organization, Cluster, Location, and longest matching literal path inheritance independently for each principal.
4. Cap each principal's ordinary result with the organization's exact entitlement-version ceiling.
5. Apply ClusterView and LocationView visibility gates from that same principal. Visibility from one group cannot activate a child grant from a different group.
6. Combine the surviving principals additively. For tiered values, Write > Read > None; binary values combine when any surviving principal supplies Allow.
7. Intersect the result with the personal access token's current organization and capability maxima, if the request uses a PAT.
8. Evaluate non-ACL prerequisites such as deployment availability, storage, current Cluster/Location capacity, UTC-month Job capacity, lifetime Job capacity, and idempotency.

This order is why a tier cannot grant missing access, one principal cannot borrow another principal's visibility, and spare operational capacity cannot replace a missing capability.

Treat definition names as display data

Entitlement definitions and their display names do not contain hardcoded behavior. PixAtlas Lite, PixAtlas, PixAtlas Pro, PixAtlas Free, PixAtlas Unlimited, and a custom definition such as Acme Enterprise all use the same complete typed matrix. Runtime authorization does not branch on the definition key, name, display order, or whether the definition was seeded or created later.

The billing deployment preserves the exact PixAtlas Unlimited seed, publishes or reuses a PixAtlas Pro version, and adopts the reviewed production PixAtlas Free identity. The seeded Pro policy uses the current Unlimited ceilings and enables integrated chat and Whiteboards while keeping PersonalAccessTokensUse unavailable. It permits Unlimited Clusters, Locations, Bundle storage, and organization-lifetime Jobs, with ten Jobs per UTC month and 500 GiB default Document storage. The €99 monthly billing Price binds to that exact Pro version. Free is the exact future-organization creation default. Existing organizations keep their exact current pins and are grandfathered separately; changing the default never rewrites them. These are ordinary stored version and pin rows, and runtime behavior does not derive from the words “Free,” “Pro,” or “Unlimited.”

For example, an administrator can publish a Bundle-oriented version whose OrganizationDocuments, ClusterDocuments, and LocationDocuments ceilings are Unavailable, whose IntegratedChatUse ceilings are Unavailable, and whose LocationBundles ceiling is Write. Required visibility and execution dependencies must still be usable; publication warnings identify ineffective combinations, while runtime action dependencies remain mandatory.

A reviewed Free version currently stores ordinary version data including:

• MaxClustersPerOrganization = Finite(1)
• MaxLocationsPerOrganization = Finite(1)
• JobsPerOrganizationLifetime = Finite(5)

It also stores 10 GiB default Document storage, 50 GiB default Bundle storage, and Unlimited Jobs per UTC month. Those values can change only through a later immutable published version; they are not inferred from the word "Free." A custom enterprise definition can use any other complete, descriptor-valid matrix without a code change.

Understand the typed operational limits

Every published version contains explicit values for these code-owned keys:

• DefaultDocumentStorageBytes and DefaultBundleStorageBytes account for durable bytes plus active reservations in separate organization pools. An organization override may inherit the version default, set a finite byte value, or be explicitly Unlimited.
• MaxClustersPerOrganization counts current durable Clusters plus active create reservations across the organization.
• MaxLocationsPerOrganization counts current durable Locations across every Cluster plus active create reservations.
• JobsPerUtcMonth counts accepted logical Jobs in the UTC calendar month.
• JobsPerOrganizationLifetime counts accepted logical Jobs for the lifetime of the organization and never resets.

Cluster and Location limits are current-count capacity, not lifetime creation counters. A committed deletion releases the exact current capacity it removed. Lowering a limit below current use preserves existing resources and their otherwise-authorized read, update, and delete operations, but blocks additional creation until usage falls below the limit or policy changes.

A newly accepted top-level logical Job creates one immutable charge that contributes exactly once to both the monthly and lifetime ledgers. Validation failures do not charge. Retry attempts, worker retries, cancellation, failure, and Job deletion do not add a second charge and do not refund either limit. Only the monthly ledger has a reset boundary.

Storage reductions follow the same preserve-existing rule. Existing bytes stay available to otherwise-authorized readers and can be deleted, while positive byte additions remain blocked until capacity is available. Upload issuance and security-sensitive finalization both recheck the applicable permission, path, destination, and storage state.

Use immutable versions and explicit organization pins

Administrators edit a complete mutable draft, validate it against the captured catalog, inspect its diff and warnings, and publish an immutable version. Publishing does not move an organization automatically. An immediate or future-UTC transition explicitly selects an exact target version and previews capability, dormant-assignment, principal, storage, Cluster, Location, monthly Job, and lifetime Job impact.

Only one pending transition may exist for an organization. Transition commands use expected-source versions and idempotency so a stale scheduler or operator cannot overwrite newer state. Retiring a version prevents new selection while preserving historical references and an already-active pin until its existing expiry. Changing the default exact version affects only organizations created afterward; it does not rewrite existing pins.

Entitlement expiry takes effect at validUntilUtc without waiting for a scheduler write. The next protected operation fails closed at that boundary. An idempotent detector later records audit and outbox state for projection reconciliation.

Plan for synchronous and asynchronous consistency

Protected reads, mutations, requester-bound finalization, and result retrieval apply current authorization synchronously. Permission and policy mutations also commit an outbox event and increment organization versions used by search, chat, realtime, notification, directory, and other derived surfaces.

The default operational objectives are 30 seconds for a change that may revoke access and 120 seconds for general asynchronous propagation. These objectives are deployment configuration and do not delay the next synchronous decision. Failed consumers retain retryable or dead-lettered work rather than treating a partially updated projection as converged.

Presigned storage URLs are the unavoidable bounded exception. PixService rechecks current authorization before issuing or refreshing a URL, but object storage cannot revoke a URL already returned to a client. It may remain usable until its expiry. The deployment default is 15 minutes and startup accepts only values from 1 through 60 minutes; request a new URL only when the client is ready to transfer.