@astrale-domains/shell 0.1.0-beta.11 → 0.1.0-beta.13

package/README.md

@@ -1,59 +1,66 @@
 # Shell Domain
 
-Shell is the minimal Kernel-native application plane. Its durable model is one `User` interface,
-the concrete `User`, `Group`, `Space`, and `Application` Node Classes, eight relationships, five
-Policies, two Functions, seven Methods, five Kernel View declarations, and four deterministic Core
-nodes.
+Shell is the minimal Kernel-native application plane. Its durable model is the concrete `User`,
+`Group`, and `Space` Node Classes, five relationships, four Policies, two Functions, six Methods,
+four Kernel View declarations, and three deterministic Core nodes.
 
-The `ensureUser` Function is the Shell-owned identity genesis boundary. It idempotently provisions an
-externally identified `User`, their personal `Space`, and both ownership/default relationships under
-the installed Shell Domain's authority. `ensureAdministrator` idempotently assigns one existing User
-to Shell's administrator Group. Both keep product mutation under Shell authority while allowing an
-authenticated genesis operator to request the transition.
+Identity registration and Shell business setup are separate boundaries. A real external user first
+creates a local key and self-provisions that key as the exact Shell `User` Class. The CLI journey is:
+
+```sh
+astrale identity create alice
+astrale identity register alice \
+  --class /:shell.astrale.ai:class.User \
+  --props '{"shell.astrale.ai:class.User.property.displayName":"Alice"}' \
+  --as <root> -i <instance>
+```
+
+Under the current public contract, Root submits the self-proven registration for each Shell User;
+it does not author that User's Shell memberships or Space facts. Root calls `setupAdmin` only to
+converge the first administrator, using the exact registered issuer and subject returned by
+`identity register`. After that, an authenticated Shell administrator calls `setupMember` or
+`setupAdmin` for subsequent registered Users. Both setup Functions are authorized by
+`maySetupUsers` against membership in the Core Administrators Group.
+They converge the User profile, personal Space, ownership/default facts, Members membership, and—only
+for `setupAdmin`—Administrators membership. They do not create credentials, grant humans dynamic
+`can_*` authority, infer identity from a local CLI name, or replace self-proven registration.
 
 The Methods are:
 
-- Group: `assignUser`, `unassignUser`;
-- Space: `addUser`, `removeUser`, `setDefault`; and
-- Application: `install`, `uninstall`.
+- User: `resolveHome`;
+- Group: `assignUser`, `unassignUser`; and
+- Space: `addUser`, `removeUser`, `setDefault`.
 
-Installation authors the `admin`, `member`, `default-space`, and `shell` Core. An authenticated genesis
-operator may invoke `ensureUser`, but cannot mutate Shell Classes directly. The remote handler performs
-the atomic identity provisioning as Shell, then callers assign the User explicitly to a Group. Shell
-infers no authority from email, claims, path spelling, or creation order.
+Installation authors the `admin`, `member`, and `default-space` Core nodes. Shell infers no authority
+from email, claims, path spelling, creation order, or a successful handler-local boolean.
 
 ## Source ownership
 
 - `schema/` owns the complete Domain contract, public Method values, Policies, relationships, DSL
   Views, and Core graph;
-- `rules/` owns synchronous classifications, decisions, normalization, and result projection;
-- `queries/` owns canonical single and composite graph observations plus explicit bounded continuation
-  pagination when a business observation requires the complete set;
-- `mutations/` owns canonical atomic graph changes and their expected rejection evidence;
-- `workflows/` owns replay-shaped multi-step business journeys and unknown-outcome recovery;
-- `functions/` binds the Function and each Method to a rule, workflow, or direct operation;
-- `utils/` owns only the shared graph-endpoint and bounded-query mechanics used by independent
-  submodules; and
-- root `tests/` owns cross-layer and system evidence, while each semantic submodule owns focused
-  evidence in `__tests__/`.
+- `queries/` owns canonical graph observations through the invocation-bound Query executor;
+- `mutations/` owns canonical graph changes and exact preconditions;
+- `actions/` owns the single-operation `User.resolveHome` implementation;
+- `workflows/` owns setup, Group membership, and Space access/default journeys plus
+  unknown-outcome observation; and
+- each semantic owner keeps focused evidence in its own `__tests__/` directory, while root tests
+  remain reserved for cross-layer or physical evidence.
 
 No current responsibility earns a `states/`, `capabilities/`, `integrations/`, `migrations/`,
-`views/`, `ui/`, or root `scripts/` source layer. DSL View declarations remain in Schema; a future
-frontend projection or UI must establish its own concrete responsibility before adding those layers.
+`views/`, or `ui/` source layer. DSL View declarations remain in Schema; a future frontend
+projection or UI must establish its own concrete responsibility before adding those layers.
 
-Shell never re-declares shared metadata properties. `Group` and `Space` currently name `K.Named`
-and `K.Descriptable` in their `implements` lists because the current DSL makes only `K.Node`
-intrinsic and Core-property admission otherwise rejects `name` and `description`. Removing those
-interface references awaits the recorded Kernel authoring-default decision; no timestamps are
-authored by Shell.
+Shell never re-declares shared metadata properties. `Group` and `Space` name `K.Named` and
+`K.Descriptable` in their `implements` lists because those Kernel Classes own the admitted
+`name` and `description` properties; no timestamps are authored by Shell.
 
 ## Execution and evidence
 
-`ShellDomain` is the complete remote product implementation. Its exact handler map proves that the
-genesis Functions and all seven Methods are served from the same immutable publication. The handlers use
-the SDK's canonical Auth, Query, Mutation, Result, Workflow, and Step contracts. `ensureUser` relies on
-the Kernel provision operation's stable idempotency key; the SDK's current inline Step runner does not
-claim process-restart replay on its own.
+`application.ts` and `runtime.ts` form the complete remote product implementation. Runtime admission
+is exhaustive: `User.resolveHome` is one Action, and both setup Functions plus all five mutating
+Methods are Workflows. They use the SDK's canonical Auth, Query, Mutation, Result, Workflow, and Step
+contracts. Named Workflow steps describe semantic operations but do not claim process-restart
+durability, exactly-once execution, compensation, or crash recovery.
 
 The executable contract lives in Shell's semantic source, public facades, and tests. Product
 decisions, journeys, legacy disposition, dependency gates, and qualification evidence live in
@@ -65,7 +72,21 @@ application descriptor from `@astrale-domains/shell/application` and the runtime
 `@astrale-domains/shell/runtime`, so bundling the remote runtime does not traverse the build-only
 schema facade.
 
-The source, deterministic Knowledge linter, TypeScript package, unit/cross-layer tests, and remote Shell
-contract are qualified locally. Installed-instance, released-package, browser, and live
-credential journeys are separate evidence levels and are not claimed here. Shell does not broker
-authentication tokens; standard Domain token exchange is owned by Protocol, Server, and SDK.
+### Publication boundary
+
+`@astrale-domains/shell` is an executable platform package and a deliberate exception to the normal
+Domain publication product. It publishes the remote Shell application and runtime needed by platform
+Worker deployments through the explicit `./application` and `./runtime` subpaths, while its root remains
+Schema-only. Its build therefore compiles the explicit roots in `tsconfig.package.json` and applies
+Shell-owned checks to the emitted platform closure. Tarball qualification then verifies the exact
+exports, isolated entrypoints, absence of source maps, and an install using only public npm
+dependencies.
+
+The generic `astrale-domain package` command remains Schema-only and exposes only the Domain root plus
+package metadata. This Shell exception must not be copied to ordinary product Domains or used to
+weaken that SDK contract. Deployment consumers must use the explicit executable subpaths so a linked
+schema import cannot traverse Shell's private application or runtime implementation.
+
+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.

package/dist/actions/index.d.ts

@@ -0,0 +1 @@
+export * from './user/index.js';

package/dist/actions/user/index.d.ts

@@ -0,0 +1 @@
+export { resolveHomeAction } from './resolve-home.js';

package/dist/actions/user/resolve-home.d.ts

@@ -0,0 +1,3 @@
+import { type ActionDefinition } from '@astrale-os/sdk/action';
+import type { ShellSchema } from '#schema';
+export declare const resolveHomeAction: ActionDefinition<typeof ShellSchema, 'User.resolveHome'>;