@astrale-domains/shell 0.1.5 → 0.1.7

package/README.md

@@ -1,77 +1,80 @@
 # Shell Domain
 
-Shell owns two concrete Identity classes, User and Group, the member_of_group relation,
-the admin/member/applications/view-only Core groups, the Namespace class and its alias relation, the
-view_access relation, the `views` Core Namespace, three static methods, one User method, three Namespace methods, two Domain functions, and one
-application View, which is its entrypoint. The Schema names the Domain `Shell`. There is no Space, setup function, personal home, or public repair method.
+Shell owns the account of each person (`User`), their groups (`Group`), its Roles (`Role`: the
+profiles `workspace.member` ⊂ `workspace.admin` and the atomic `user.reader`, `user.writer`,
+`group.reader`, `group.writer`, `directory.provisioner`), the Views an account without a profile
+lands on (`view_access`), the instance Namespaces and their aliases, and one application View, its
+entrypoint. All authority comes from Kernel Roles, held directly or through groups by Kernel
+`extends_with`; a directory may provide accounts and groups. The design, its laws and its
+amendments are in [`docs/design/accounts-and-roles.md`](../docs/design/accounts-and-roles.md);
+each law's enforcement and test are in [`docs/accounts/laws.tsv`](../docs/accounts/laws.tsv), each
+scenario's evidence in [`docs/accounts/scenarios.tsv`](../docs/accounts/scenarios.tsv).
+
+The model before Roles is kept for its callers under `legacy/` folders, listed in
+[`legacy/LEDGER.md`](./legacy/LEDGER.md) by the method of [`docs/legacy.md`](../docs/legacy.md); it
+is described in [`docs/legacy/shell-domain-before-roles.md`](../docs/legacy/shell-domain-before-roles.md).
 
 ## Contracts
 
-| Static method | Input | Output |
-| --- | --- | --- |
-| User.invite | `{ user: UserPath, email: string }` | `{ invitationId, user, state }` |
-| Group.assignMember | `{ member: UserPath \| GroupPath, group: GroupPath }` | `{}` |
-| Group.unassignMember | Same | `{}` |
-
-| User method | Input | Output |
-| --- | --- | --- |
-| User.recordProfile | `{ email?: string, displayName?: string }` | `{}` |
-
-An account records the email and display name it signs in with, so the directory can name it, in
-`claimedEmail` and `claimedName`: named apart from the `email` or `displayName` a Domain extending
-User declares for its own profile. Its
-`isSelf` Policy admits the account itself alone, and Shell writes, with its own authority, only what
-changed; an email is kept in lower case. The values come from the account, not from its identity
-provider: they name it for display and decide nothing. The GUI records them at each sign-in.
-
-| Namespace method | Input | Output |
-| --- | --- | --- |
-| Namespace.link | `{ name: string, target: NodePath }` | `{}` |
-| Namespace.unlink | `{ name: string }` | `{}` |
-| Namespace.rename | `{ name: string, to: string }` | `{}` |
-
-| Domain function | Input | Output |
-| --- | --- | --- |
-| listEntrypoints | `{}` | `{ entrypoints: { origin, name, view }[] }` |
-| assignViews | `{ assignments: { identity, set?, unset? }[] }` | `{}` |
-
-listEntrypoints reads, with Shell's own authority, every Kernel `of_domain` locator whose View has
-an outgoing `entrypoint` Edge, and returns one entry per Domain in origin order: its origin, the
-`name` of its Domain Node, and the key of its entrypoint View. A Domain without an entrypoint is
-not listed. Shell requires `read` on Kernel `Domain` and `of_domain`, and `traverse` on `entrypoint`
-and `View`. Its `usesFunction` Policy admits any caller whose composed profile holds `can_use`
-on the Function, so holding the capability is enough.
+| Method | Called on | Admitted | Input | Output |
+| --- | --- | --- | --- | --- |
+| `User.create` | static | `user.writer` | `{ email, name, givenName?, familyName?, attributes? }` | `{ user, created }` |
+| `User.invite` | static | `user.writer` | `{ user, profile?: 'member' \| 'admin' }` | `{ invitationId, user, state }` |
+| `User.update` | the account | `user.writer` | `{ name?, email?, givenName?, familyName?, icon?, attributes? }` | `{}` |
+| `User.updateProfile` | the account | its holder | `{ name?, icon? }` | `{}` |
+| `User.deactivate`, `User.reactivate`, `User.delete` | the account | `user.writer` | `{}` | `{}` |
+| `User.provision` | static | `directory.provisioner` | `{ directory, externalId, email, name, givenName?, familyName?, active }` | `{ user, created, adopted }` |
+| `User.deprovision` | static | `directory.provisioner` | `{ directory, externalId }` | `{}` |
+| `Group.create` | static | `group.writer` | `{ name, description?, icon?, attributes? }` | `{ group }` |
+| `Group.update`, `Group.delete` | the group | `group.writer` | `{ name?, description?, icon?, attributes? }`, `{}` | `{}` |
+| `Group.assignMember`, `Group.unassignMember` | static | `group.writer`, `directory.provisioner` | `{ member, group }` (`@NodeId` paths) | `{}` |
+| `Group.provision` | static | `directory.provisioner` | `{ directory, externalId, name }` | `{ group, created }` |
+| `Group.deprovision` | static | `directory.provisioner` | `{ directory, externalId }` | `{}` |
+| `disconnectDirectory` | function | `directory.provisioner` | `{ directory }` | `{ users, groups }` |
+
+Refusals (`reason.code`, family): `USER_EMAIL_INVALID` (VALIDATION_ERROR); `USER_NOT_FOUND`,
+`GROUP_NOT_FOUND` (NOT_FOUND); `USER_EMAIL_TAKEN`, `USER_DIRECTORY_MANAGED`,
+`USER_ADMINISTRATOR_PROTECTED`, `USER_LAST_ADMINISTRATOR`, `USER_ACTIVE`, `USER_SUSPENDED`,
+`PROFILE_NOT_HELD`, `GROUP_DIRECTORY_MANAGED`, `GROUP_NOT_DIRECTORY_MANAGED`,
+`GROUP_ROLE_PROTECTED` (details `{ role }`), `GROUP_MEMBERSHIP_CYCLE`, `DIRECTORY_CONFLICT`
+(details `{ user }`), `ACCOUNT_CHANGED`, `GROUP_CHANGED` (CONFLICT); the membership
+methods keep `INVALID_GROUP_MEMBERSHIP_REFERENCE`, `GROUP_MEMBERSHIP_ENDPOINTS_UNAVAILABLE`,
+`GROUP_MEMBERSHIP_CONFLICT`, `GROUP_MEMBERSHIP_UNCONFIRMED`, and invite `INVITATION_CONFLICT`,
+`INVITATION_REJECTED`. The SDK has no FORBIDDEN business family: a law that forbids a change for
+the state of an account, a group or its caller answers CONFLICT.
+
+User and Group declare no write rule: only their methods write them, with Shell's authority, after
+the laws the Kernel cannot state (U1–U6, G2–G4). A Domain that needs accounts asks `user.writer`
+(and `user.reader`) in its release for itself, `requirements({ roles: [{ role: S.core.nodes['user.writer'], members: [requirements.domain] }] })`,
+links its record to the account by an Edge of its own, and tests its own Roles with its own
+`hasRole` Policy. Every write keeps `frozen` = `suspended` or `directoryActive === false` (U2): the
+Kernel refuses to authenticate a frozen account.
+
+## Invitation
+
+`User.invite` grants the profile (`extends_with` to `profile.<name>`), then asks Admin to send the
+invitation through Shell's enrollment Integration, which carries `{ user, email, profile, requestId,
+requestedBy }`: the email is the account's own. Its Provider mints an invocation-bound Shell proof
+for its configured HTTPS ingress audience. A returned pending invitation does not prove email
+delivery or completed registration. Admin binds the first sign-in of the verified email to the
+account (U8).
+
+## Release
+
+`domain.ts` declares Roles and scopes. `workspace.admin` grants every Shell Role and the grantable
+Kernel Roles (R2); the bundle member ⊂ admin and the atomic Roles are release members (AM1);
+member holds Kernel `writer`, admin Kernel `admin`; no profile holds Kernel `reader`, which admin
+grants to whoever only opens its Views (AM10); Shell itself holds
+Kernel `authority.reader`, `graph.reader` and `graph.writer`. Installing it requires an installer
+that grants every Role it binds: Root.
 
-The workspace opens only once listEntrypoints answers, so every profile that admits a person to
-the workspace holds it. Administrators and members hold both listEntrypoints and View.resolve
-directly (a Core Edge cannot author Kernel `extends_with`): an invited person, whom Admin assigns
-to Core member, can open the workspace. The Core `applications` Group carries the same two
-capabilities for Identities outside Members, and `query`: the `/v/<name>` page reads its Path with
-a Query under the visitor's own rights, so read rules still decide what it sees. Share them
-dynamically with
-`Group.assignMember({ member: identity, group: applications })`, which composes the profile through
-`extends_with`; `unassignMember` withdraws it.
-
-User extends Kernel.Identity and owns only optional creationKey correlation.
-Concrete business classes may declare their own displayName/email; Shell never reads or writes them.
-Group extends Kernel.Identity, Named and Descriptable. Authentication remains the
-Kernel-owned, write-once iss/sub binding. Invitation email is explicit input, not a User property.
-
-| Operation | Schema Policy alternatives, in addition to Kernel admission |
-| --- | --- |
-| invite | Core admin membership AND Shell-owned concrete User class; or ownership of the User's concrete class |
-| assignMember / unassignMember | Core admin membership AND Shell-owned concrete Group class; or ownership of the Group's concrete class |
+## View access
 
-ownsClass follows instance_of → concrete class → of_domain → caller. It does not
-infer ownership from an email, a subclass name, or ownership of an ancestor class.
-A Domain cannot assign its Employee to Core member merely by owning Employee. Admin's invitation
-orchestration retains that responsibility. A Group's owner may manage any admitted User or Group in that Group.
-administersShellClass connects Core admin membership and concrete ownership in one Policy pattern;
-it does not treat inheritance from Shell as ownership. These are callable restrictions, not an
-isolation boundary against Root/Manager or the existing broad administrator Kernel profile.
-With Kernel Host beta94 or newer, an external caller needs callable authority through its own
-identity composition AND a passing callable Policy. Declare exact foreign methods in the calling
-Domain's requirements; can_use no longer bypasses the Policy. Root and exact owner exceptions remain.
+**A View given to an Identity decides where it lands, never what it reads.** `view_access` runs
+from any Identity — an account, a group, a Role — to one Kernel View; each end detaches with its
+Node. An admin writes it by a Mutation; an admin, or the Edge's audience and its members, read it.
+A visitor's landing is its own Query (`@astrale-os/shell`): `workspace.member` opens the workspace; anyone else, reading
+with Kernel `reader`, the Views it holds.
 
 ## Namespaces and aliases
 
@@ -111,99 +114,8 @@ sealed refusals:
 | `MUTATION_PRECONDITION_FAILED` (the alias Edge exists, is gone, or carries another name) | `TARGET_ALREADY_ALIASED` | `NAME_NOT_FOUND` | `NAME_NOT_FOUND` |
 | `MUTATION_LOCATOR_INVALID` (the target Path reaches no Node, or the target was deleted) | `TARGET_NOT_FOUND` | `NAME_NOT_FOUND` | `NAME_NOT_FOUND` |
 
-Every other failure propagates. Core admin holds the three methods, `read` and `traverse` on
-Namespace, and every operation on alias. Administration follows `administersShellClass` on the
-Namespace, as for Groups.
-
-## View access
-
-**A View given to an account decides where it lands, never what it reads.** `view_access` runs from
-a User or a Group to one Kernel View. The Core group `view-only` limits its members to the Views
-they hold, directly or through a group they are a direct member of; membership in `view-only` and
-in Core `admin` counts the same way. Everyone else, and every administrator, opens the workspace as
-before. Nothing else changes: the View's own Domain still
-guards every Node it shows, and `View.resolve` and `listEntrypoints` answer as before.
-
-| Fact | Who writes it | How |
-| --- | --- | --- |
-| `view_access(holder → View)` | Core admin | `assignViews`, or a Mutation that creates or deletes the Edge. It carries no property. |
-| `member_of_group(user → view-only)` | Core admin | `Group.assignMember` / `Group.unassignMember`. |
-
-`view_access` declares `read: true` and `traverse: true`, as `alias` does. Its target is a
-Class Shell does not own, so it detaches when its View is deleted, by a Mutation or by a release
-that removes the View. Clients read a visitor's access with its own Queries
-(`shell.views.access()`): never a read function. A Shell release without `view-only` limits no one.
-
-`assignViews` takes, for each identity (a User or a Group, by `@NodeId`), the Views to give
-(`set`) and to withdraw (`unset`), by `@NodeId`. It reads the identities' `view_access` Edges and
-writes only what differs, in one Mutation guarded by that read, with Shell's own authority: a View
-already given or already withdrawn costs nothing, and a concurrent change refuses the whole write
-(`VIEW_ACCESS_CONFLICT`). An identity listed twice gets both lists; one View both given and
-withdrawn is refused. One call changes at most 40 identities and 20 Views per list. Core admin
-holds it, and may share `can_use` on it. It never changes `view-only`: whether an identity opens the workspace stays its
-membership, which `Group.assignMember` changes.
-
-To limit an invited person to one View: invite them, assign them to `view-only`, give them the
-View with `assignViews`, and give the View an alias in `views` so `/v/<name>` opens it.
-
-## Flows
-
-```text
-Domain creates Employee extending User → unregistered, no group
-Direct credential-evidenced Register → same node authenticates, still no group
-User.invite → provider authentication → Admin ingress → WorkOS/login
-            → Admin Register on that same node → member assignment → completed
-Group.assignMember → member_of_group + Kernel.extends_with in one atomic mutation
-Group.unassignMember → remove both edges in one atomic mutation
-```
-
-The invitation flow is coordinated by Admin, not by an Employee callback. Shell's Integration
-carries only user/email/requestId/requestedBy. Its Provider mints an invocation-bound Shell
-proof for its configured HTTPS ingress audience; target/sourceProof are not business inputs.
-A returned pending invitation does not prove email delivery or completed registration.
-
-`assignMember({ member: A, group: B })` adds A to B. A and its current and future members inherit
-B's authority. Groups can have several parents; Kernel rejects self-membership and cycles in the
-same transaction as both membership edges. The target Group's manager authorizes this delegation;
-the child Group's managers can subsequently change the population that inherits it.
-
-`unassignMember` removes only that direct pair. Another membership path can preserve effective
-access. Queries of `member_of_group` continue to return direct facts; Policy evaluation expands
-the caller's identity composition. Shell must be able to traverse both concrete endpoint Classes,
-including a foreign Group used as the member.
-
-Membership methods converge both edges, including an observed partial membership.
-After an uncertain mutation response they re-read the pair; an unconfirmed outcome remains
-explicitly unconfirmed. This is not a global repair scan or an exactly-once guarantee.
-
-A Team class extending Group can carry a business permission edge to Project. Membership
-composition lets an Employee, as caller, inherit Team's authority; the protected Project Policy is
-still evaluated by Kernel. Removing composition removes that authority path. Installed
-Kernel E2E evidence, not a handler test, qualifies this behavior.
-
-## Installation and View
-
-The Shell principal requests all Kernel root functions, the required extends_with operations,
-and the declared grant/revoke authority. Core admin receives the full declared Shell profile,
-including invite, recordProfile, assignMember, unassignMember, link, unlink, rename and assignViews
-so humans inheriting admin can call those methods. Core member receives Download, Introspect, Query,
-Mutate, View.resolve, listEntrypoints and recordProfile, not blanket class-read grants. Core applications receives listEntrypoints,
-View.resolve and Query.
-The Domain definition's requirements, including Core Identity capabilities in requirements.core, are owned by domain.ts and materialized by installation,
-never by invitation handlers.
-
-The sole application entrypoint uses the Vite React frontend at /, composed with
-`@astrale-os/shell-react` and `@astrale-os/ui`. It administers the instance under the caller's own
-session, in three tabs. **Access** lists users, then groups: whether each opens the whole OS or only its Views (two spelled-out options
-over its `view-only` membership; an administrator always does, a Core group is decided by its role)
-and, through a picker, the installed Views given to it. **Groups** lists the groups and the direct
-members of the chosen one, to add or remove. **Addresses** lists the installed Views and the name
-`/v/<name>` each opens at, to give, rename or remove through `Namespace.link`, `rename` and `unlink`;
-a name the Namespace would refuse, or one another View has, is refused beside the field before it is
-sent. Every change applies at once and comes back with a
-message when the Kernel refuses it. A user shows its recorded display name and email, or its concrete
-class when it recorded none, never a guessed foreign profile. Every read is a Query under the
-caller's rights; the screen proxies no privileged read.
+Every other failure propagates. `workspace.admin` holders call the three methods, and write `alias`
+Edges by their own Mutations too.
 
 ## Versions
 
@@ -224,7 +136,7 @@ release.
 
 Each declaration, Query and Mutation has its own semantic file. Layer roots are facades;
 functions own orchestration, integrations/providers own external effects, views/ui own the
-directory surface. Runtime has one default export and binds the three static Workflows.
+directory surface. Runtime has one default export and binds every handler.
 The Dataset is referenced lazily by the root astrale.config.ts.
 
 Domain authors import Schema from @astrale-domains/shell; platform workers use the explicit
@@ -252,15 +164,3 @@ schema import cannot traverse Shell's private application or runtime implementat
 Source, package, and deterministic test qualification remain distinct from installed-instance,
 released-package, browser, and live-credential evidence. Shell does not broker authentication
 tokens; standard Domain token exchange is owned by Protocol, Server, and SDK.
-
-### Breaking membership API migration
-
-`Group.assignMember` / `Group.unassignMember` replace `assignUser` / `unassignUser` without aliases.
-Callers must change `{ user, group }` to `{ member, group }` and declare the new exact callable
-requirements. The `member_of_group` Class key is preserved; its source role is now `member` and
-accepts User or Group families. Existing User memberships remain valid.
-
-Rebuild and install all affected Schema dependents as one coherent revision closure. Admin bootstrap
-and invitation completion must use the new API when this Shell revision is installed. A downgrade
-to the User-only contract requires handling any Group-to-Group facts first. Validate public admission,
-foreign endpoint traversal, and deployed revisions during the coordinated release.