tracking: user-rooted multi-tenancy and hierarchical principal resource accounting

Outcome

Complete production multi-tenancy for standalone Astrid using the same identity and authority model as the Universal Substrate.

UserUid is the tenant/root resource owner. Every agent, service, application, and Oracle principal derives from exactly one user through the canonical ownership graph. A user may directly own capsules, state, devices, surfaces, and other admitted resources; a user does not implicitly require or receive a Linux Realm.

Principals remain isolated execution authorities with their own capsule selection, mutable state, secrets, receipts, leases, quotas, and lifecycle. Immutable capsule and Realm artifacts may be physically cached once, but mutable runtime state and authority are never shared merely because the bytes are identical.

Parent: #1564. Related durable ownership/projection work: #1710.

September 2026 reconciliation

This issue originated in April and its earlier design/state inventory became stale. The following work has since landed:

• per-principal profiles and quota configuration (#663);
• per-invocation quota enforcement (#666);
• principal-scoped allowances, capabilities, overlays, and connection accounting (#668);
• capability/group enforcement on management operations (#670);
• agent lifecycle, quota, group, and capability management APIs (#672);
• cross-capsule per-principal CPU enforcement (#819);
• separation of immutable capsule artifacts from authority-scoped resident runtimes (#1486).

Current PrincipalProfile::Quotas carries per-principal memory, invocation timeout, IPC throughput, background-process, persistent-storage, CPU-fuel, and in-flight-call ceilings. CPU accounting is aggregated per principal. Memory reporting is currently a per-principal peak and the main WASM memory ceiling remains per Store rather than a complete live tenant total.

Astrid also has a hierarchical ResidentMemoryAuthority whose logical charges consume ancestor subtree allowances. That mechanism is not yet wired to production UserUid -> PrincipalUid provisioning across the kernel, and it does not establish hierarchical CPU, storage, IPC, process, Realm, or device accounting.

Therefore the current implementation is per-principal, not yet a complete user-envelope hierarchy.

Corrected architecture

1. UserUid is the resource-accounting root and durable tenant identity.
2. Each executable principal has exactly one canonical owning user. Paths, aliases, Linux UIDs, session labels, and caller payloads never mint this relationship.
3. A principal receives a bounded allocation beneath its user's envelope.
4. CPU, resident memory, persistent storage, IPC, process, concurrency, Realm, surface, and device usage is charged to the acting principal and rolled up to the owning user.
5. Admission fails when either the principal allocation or any owning-user envelope is exhausted.
6. A user can directly own and use resources without a Linux Realm. A Realm is an optional admitted resource for a principal, not the definition of a user or home.
7. Agents belonging to the same user do not automatically share homes, capsules, secrets, receipts, Realm overlays, or capabilities. Sharing requires explicit governed authority.
8. Disconnected or multi-host execution uses bounded reservations/leases so the same user allocation cannot be double-spent.
9. Principal deletion, user deletion, transfer, expiry, logout, crash, and recovery preserve accounting and cannot orphan or resurrect charged resources.
10. Immutable artifacts may be shared physically; resident runtime instances may be pooled only when the design proves that no principal-owned mutable state or authority crosses the boundary.

The old requirement that one mutable WASM Store/capsule instance must be shared across all principals is withdrawn. Efficient artifact/component reuse is desirable, but it is subordinate to principal isolation and honest resource attribution.

Remaining work

• Bind production principal provisioning to the canonical UserUid -> PrincipalUid ownership relationship.
• Register that ancestry in each enforceable resource authority rather than maintaining an unrelated quota tree.
• Extend user-envelope enforcement beyond logical resident memory to CPU, storage, IPC, process/concurrency, Realm, device, and surface admission.
• Report direct-principal usage and aggregate user/subtree usage from the same authoritative ledgers.
• Define reservation, handoff, recovery, and revocation semantics for disconnected and multi-host execution.
• Complete per-principal audit attribution (#675), usage reporting (#687), and human-owned/principal-private/fleet projection semantics (#1710) without inventing a second identity graph.
• Preserve explicit monotonic delegation under #656; a child principal or voucher cannot exceed its issuer and owning-user envelopes.

Exit gate

1. Two users, each with multiple agent principals, run concurrently without cross-user or cross-agent state, authority, or accounting leakage.
2. Each agent is admitted under exactly one UserUid; forged aliases, paths, payload identities, and Linux credentials cannot change ancestry.
3. A user-level CPU, memory, storage, IPC, process/concurrency, Realm, and device ceiling is enforced across all descendant principals.
4. A principal's own ceiling is enforced even when its user has remaining capacity; a user ceiling is enforced even when an individual principal has remaining capacity.
5. Usage reports reconcile direct principal charges, descendant subtotals, and the user total against the same live ledgers.
6. A user with no Linux Realm can own state, capsules, devices, and surfaces normally. Adding or removing a Realm does not change identity ancestry.
7. Shared immutable artifacts do not create shared mutable state. Cross-principal cache/runtime reuse passes hostile residual-state tests.
8. Multi-host reservations prevent double-spend and recover conservatively after partition, crash, expiry, and handoff.
9. User/principal deletion and transfer drain or reassign every charged lease without resurrection.
10. Hosted and standalone implementations pass the same user/principal accounting and isolation corpus.

Claim boundary

Success establishes user-rooted multi-tenancy and hierarchical resource accounting. It does not by itself establish Linux Realm implementation, physical-host support, public hosting certification, billing, a graphical shell, or a release.

Current status

Parked during Astrid/AOS 2026.9.0 preparation. Re-pin exact os/universal, reconcile landed ownership/resource work, and freeze the production ancestry wiring before staffing implementation.