@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.40

package/README.md

@@ -1,10 +1,13 @@
 # SDK
 
-Schema-first SDK for authoring and deploying Astrale Applications. The public surface separates
+Schema-first SDK for authoring and deploying Astrale Domains. The public surface separates
 single-step Actions, explicit multi-step Workflows, provider-neutral Integrations, concrete Providers, graph
-authoring, Application composition, Deployment, and Execution without exposing DSL callable
+authoring, Domain composition, Deployment, and Execution without exposing DSL callable
 topology in implementation files.
 
+The Domain name and optional View entrypoint belong to its root Schema. See
+[the Schema authoring contract](docs/domain-schema-migration.md).
+
 [![CI](https://github.com/astrale-os/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/astrale-os/sdk/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
@@ -17,7 +20,7 @@ npm install @astrale-os/sdk
 ```
 
 Zod schemas cross the SDK and Kernel compiler boundary by runtime identity. The SDK therefore
-declares one exact, non-optional Zod peer. If an Application declares Zod directly, it must use the
+declares one exact, non-optional Zod peer. If a Domain declares Zod directly, it must use the
 same exact version rather than a range; a second physical Zod runtime is not an admitted authoring
 environment.
 
@@ -42,41 +45,43 @@ The command covers the workspace root and its packages, pins exact versions, and
 lockfile through pnpm. Use `--channel latest` to select that tag instead. Missing tags and local,
 catalog, or aliased dependencies are left unchanged and reported; peers and overrides are not edited.
 For an older SDK without this command, start with `pnpm dlx @astrale-os/sdk@beta upgrade`.
-Stop development watchers first, then run the project's checks and validate on development.
+Run the project's checks and validate on development.
 Nothing is committed or deployed. A Shell update also requires checking the installed Shell revision.
 Rerunning an upgrade synchronizes installation even when the manifest versions are already current.
 
-## Move a runtime without changing its Domain identity
+## Immutable deployments
 
-A Domain issuer is retained across installation upgrades. To deploy a new Cloudflare runtime for
-selected instances, keep the existing signing identity and issuer while selecting a new public origin:
+A deployment serves one `DomainRelease` v4 at its immutable URL, which is also its issuer.
+`assemble(build, buildDigest, url)` seals the document from the exact Build and running bytes.
+Cloudflare deployments require a dispatch namespace; `astrale()` hosts them on Admin's Services.
+Install the URL printed by `astrale-domain deploy` on each intended instance.
 
-```ts
-cloudflare({
-  route: 'services-v2.example.com',
-  workerName: 'services-v2',
-  identityIssuer: 'https://services.example.com',
-  signingIdentity: '.astrale/identity.json',
-})
-```
+## Handler authority and dependencies
 
-The new Publication places its Bundle, Delivery, callables, Views and routes at the new origin.
-Install that public URL on each intended instance. The Kernel verifies its Delivery against the
-retained issuer's keys and preserves the Domain installation identity and owned data. Keep the
-original issuer discovery endpoints and keys available; unadopted instances continue to use their
-previous bindings. Deployment readiness checks the exact new Worker version separately from issuer
-discovery. No uninstall or identity rotation is involved.
+Handlers use Domain self authority for `kernel`, `graph`, `query`, and `mutate`.
+`dependencies.directory.caller.invoke(d => d.functions.lookup, input)` calls a direct declared
+dependency on behalf of the incoming caller Identity; `.self` calls it as the executing Domain.
+Explicit `caller` or `self` authority is also available on `kernel` and `graph`; the former
+handler `client` is removed. A call to an `auth: 'anonymous'` callable that carries no credential
+has no caller: its handler acts as the Domain alone, without the `caller` selections. See
+[the API and migration guide](docs/handler-dependencies.md).
 
-At the provider-neutral release boundary, use
-`addressing('https://services.example.com', { publicUrl: 'https://services-v2.example.com' })`.
-The one-argument form continues to use the issuer as the public URL.
+## Durable Workflows
 
-## Handler authority and dependencies
+A callable declared with `execution: { durable: true }` is implemented by `defineWorkflow` and runs
+on the Kernel's workflow engine: a call returns its `K.Execution` at once, and the run survives
+restarts with journaled Steps, durable timers and signals. Serve it with `serve({ durable })`. See
+[the durable Workflow guide](docs/durable-workflows.md).
+
+## Admission age
 
-Authenticated handlers use Domain self authority for `kernel`, `graph`, `query`, and `mutate`.
-`dependencies.directory.invoke(d => d.functions.lookup, input)` calls a direct declared dependency
-with the incoming caller Grant. Explicit authority remains on `kernel` and `graph`; the former
-handler `client` is removed. See [the API and migration guide](docs/handler-dependencies.md).
+A callable declared with `admission: { maxAge: <seconds> }` (1 to 300) lets its deployment reuse an
+admission the source Kernel granted, for the same Kernel, caller, target and Policy-read input fields,
+while it is younger than that age: such a call skips its `Function.admit` round trip. Revocation then
+reaches it within that age. Credential verification, the release pin and input validation still run
+on every call. Admissions are kept in the deployment cache, `serve({ cache })`: a memory cache by
+default, the Cache API on Cloudflare, and none with `cache: false`. See
+[the admission age guide](docs/admission-age.md).
 
 ## Node Class icons
 
@@ -100,6 +105,66 @@ valid; the linter emits a non-failing `SCH-ICON-NEUTRAL` warning. Bare names suc
 non-canonical empty SVGs, external references, and executable SVG content are rejected during
 Schema authoring.
 
+## Read rules and caller rules
+
+Every concrete Class authored through the SDK declares who may read it, and every executable
+`authorized` callable declares who may call it. Omission is rejected by TypeScript and at the
+runtime authoring boundary. A rule is a predicate on the caller: a Policy, or its constant value
+`true` or `false`.
+
+```typescript
+import { classIcon, func, nodeClass } from '@astrale-os/sdk/schema'
+import { FileText, Lock } from '@astrale-os/sdk/schema/icons'
+import { z } from 'zod'
+
+export const Article = nodeClass({
+  icon: classIcon.lucide(FileText),
+  policies: { read: true },
+})
+
+export const Secret = nodeClass({
+  icon: classIcon.lucide(Lock),
+  policies: { read: false, traverse: false },
+})
+
+export const purge = func({
+  auth: 'authorized',
+  policy: false,
+  input: z.strictObject({}),
+  output: z.boolean(),
+})
+```
+
+A Class rule judges the caller, which passes by owning the Class's installation or by the rule,
+never by a capability it holds. When a Domain acts for a caller, the Domain must also hold its own
+right on the Class (the capability its requirements declare, or ownership), whatever the rule; an
+Identity acting for itself delegates nothing and meets no such ceiling. A callable reads the same
+way, with `can_use` (or ownership) as the right of its ceiling. `true` admits every Identity of the
+instance, never an anonymous request.
+
+| Declared | Caller is admitted when |
+| --- | --- |
+| Class `read: true` | always |
+| Class `read: false` | it is the owning installation |
+| Class `read: aPolicy` | ownership or the Policy |
+| Callable `policy: false` | it is Root or the owning installation |
+| Callable `policy: true` | always |
+| Callable `policy: checks` | Root, ownership, or the checks |
+
+- `read: true` and `policy: false` are what an absent rule already meant. Writing them changes
+  neither the compiled Schema nor its revision.
+- An excluded caller stays denied: `true` holds only for a caller whose live composition is not
+  denied.
+- `read` governs values, `traverse` governs reachability: a Node is reachable, and its reference
+  selectable, when either rule admits the caller. A Class whose `read` is not `true` must
+  therefore declare `traverse` as well: `traverse: false` hides that its Nodes exist,
+  `traverse: true` keeps them reachable for every caller. Beside `read: true`, `traverse` stays
+  optional.
+- An abstract Class declares no rule. An abstract Method declares its caller rule only where a
+  concrete Class executes it.
+- `read: false`, `traverse: false` and `policy: true` need a Kernel that knows the two constants.
+  Earlier Kernels refuse such a Schema at installation.
+
 ## Business-error declarations
 
 Declare reusable business errors in `schema/modules/<module>/errors/` through the Schema facade:
@@ -128,19 +193,28 @@ Error declarations are not yet published in the installed Kernel Schema.
 ### Core Identity requirements
 
 Use `requirements({ core: [{ subject, functions, classes, authority }] })` to declare capabilities
-for an Identity in the Application's local Core. `subject` is the resolved Core Node; each entry
+for an Identity in the Domain's local Core. `subject` is the resolved Core Node; each entry
 must request at least one capability. The top-level `functions`, `classes`, and `authority` members
 describe capabilities for the Domain principal.
 
-This replaces `requirements.profiles`. Rename that property to `core` and imported
-`CapabilityProfileRequirement` / `CapabilityProfileRequirementInput` types to `CoreRequirement` /
-`CoreRequirementInput`. Builds emit `requirements.capabilities.core`; new releases use Publication
-v3 and require a Kernel that supports it. That Kernel can restore historical v2 Publications and
-installation ledgers without changing their existing authority or integrity evidence.
+Builds emit `requirements.capabilities.core`; the release declares those requirements for the
+Domain principal and local Core identities. Installation verifies the Release and its exact Bundle.
+
+### Durable schema installations
+
+`schema.install()` and `schema.uninstall()` return an Execution id and its status; `result` is
+present only after successful completion. They wait at most `waitMs` (110 s by default) for the
+outcome; `waitMs: 0` returns at once. Keep the `execution` id to continue observing it through
+`schema.installation.status()` or `schema.installation.result()` from a new Client session.
+Uninstalls have the corresponding `schema.uninstallation` methods, and `session.execution` drives
+any Execution, a durable call's included: `session.execution.result(run, { waitMs })` waits for
+its outcome across as many requests as the wait takes.
+The Client decodes the Kernel’s `kind: execution` call result before reading the durable status.
+An admitted or pending Execution is not proof that the schema change completed.
 
 ### Prerequisites
 
-- Node.js 26.7.0 (default) or Node.js 24; published packages remain compatible with Node.js 22+
+- Node.js 26.7.0 (default) or Node.js 24; published packages require Node.js 24 or later
 - pnpm 12.1.0
 
 ### Setup
@@ -253,13 +327,12 @@ NodePath and its Dataset Node ID through encoding and decoding. Matching propert
 not create that association. Studio uses it when simulating `sameNode` and reference endpoints;
 a missing association makes that simulation unavailable.
 
-## Kernel publication discovery
+## Kernel release discovery
 
-Use `session.publication()` when a consumer needs the intrinsic Kernel's published identity or
-endpoints without its schema bundle or Views. It revalidates through the Client's existing issuer,
-URL, size, and ETag checks. Concurrent publication and snapshot observations share acquisition;
-cancelling one observer does not cancel another. `session.snapshot()` remains the complete,
-coherent Publication, bundle, and View catalog observation.
+Use `session.release()` for the intrinsic Kernel's Release without its schema bundle or Views.
+It revalidates issuer, URL, size and ETag. Concurrent release and snapshot observations share
+acquisition; cancelling one observer does not cancel another. `session.snapshot()` returns one
+coherent Release, Bundle and View catalog observation.
 
 ## Headless scripts and Domain callables
 
@@ -272,30 +345,33 @@ evaluated against the caller. Kernel callables, including graph reads and writes
 credential.
 
 ```ts
-import { connect, createSessionCredentialProvider } from '@astrale-os/sdk/client/session'
+import { connect, credentials } from '@astrale-os/sdk/client/session'
 
 const session = connect({
   url: 'https://instance.example/api',
-  auth: createSessionCredentialProvider({
-    ttlSeconds: 60,
-    // Return { credential, expiresAt } with expiresAt in Unix milliseconds.
-    mint: (signal) => mintSourceCredential(signal),
-  }),
-  exchange: {},
+  // A fixed `astrale token`; pass a mint instead, `credentials((signal) => fetchToken(signal))`,
+  // for a script that outlives it.
+  auth: credentials(token),
+  exchange: { mode: 'auto' },
 })
 
 await session.call({ target: '/:orders.example:class.Order:create', input }) // Domain callable
 await session.graph.get('@order-id') // Kernel callable: the source credential
 ```
 
-- **Hold the source in a provider.** Domain credentials are cached per source credential, so a
-  `resolve` that returns a new token on every call also exchanges on every call. The provider also
-  lets the Session renew a source that is too close to expiry to feed a Domain credential.
-- **Lifetimes.** `exchange.ttlSeconds` (default 300) must exceed the provider's `ttlSeconds` plus a
-  5-second settlement skew. A Domain credential never outlives its source.
+- **Hold the source in `credentials`.** It takes a fixed credential (a compact JWT whose `exp` is
+  its expiry), a mint returning a JWT or `{ credential, expiresAt }` in Unix milliseconds, or options
+  (`ttlSeconds`, default 60; `mint`; `initial`; `onChange`). Domain credentials are cached per source
+  credential, so a `resolve` that returns a new token on every call also exchanges on every call.
+  With a mint, `credentials` also lets the Session renew a source that is too close to expiry to
+  feed a Domain credential; a fixed credential fails once it no longer covers a call.
+- **Lifetimes.** In `exchange: { mode: 'auto', ttlSeconds }`, `ttlSeconds` (default 300) must exceed
+  the `ttlSeconds` of `credentials` plus a 5-second settlement skew. A Domain credential never outlives its
+  source. `exchange: { mode: 'source' }` keeps the source credential for every Call and takes no
+  `ttlSeconds`; an empty `{}` or a bare `{ ttlSeconds }` is rejected.
 - **Reading as a Domain.** To call Kernel callables as a Domain, for example to read Shell-owned
   Classes, feed a second Session from an explicit exchange:
-  `createSessionCredentialProvider({ ttlSeconds: 60, mint: (signal) => session.exchange(shellIssuer, { signal }) })`.
+  `credentials((signal) => session.exchange(shellIssuer, { signal }))`.
   `session.exchange(issuer)` caches nothing.
 - **Current identity.** Use `session.auth.whoami()`; `@self` is a CLI shorthand.
 - **Failures.** A failed exchange raises `ExchangeError` from `@astrale-os/sdk/client`. Its
@@ -305,14 +381,68 @@ await session.graph.get('@order-id') // Kernel callable: the source credential
 
 | Credential presented | Principal | Kernel callable | Domain callable reached by Policy |
 | --- | --- | --- | --- |
-| Source credential (minted or key) | the identity | ✅ | ❌ `2004`, unless the identity holds `can_use` on it through a Group |
+| Source credential (minted or key) | the identity | ✅ | ✅ the identity acts for itself: the Policy alone decides |
 | Session with `exchange` | the declaring Domain, for Domain callables | ✅ with the source credential | ✅ Policy evaluated against the identity |
 | `session.exchange(issuer)` held by a second Session | that Domain | ✅ as that Domain | only what that Domain may use |
 
+## Deployment addresses
+
+`@astrale-os/sdk/deployment/address` derives the one immutable URL of a deployment,
+`https://<line>-<content>.<routingDomain>`, from its inputs alone. Whoever deploys and whoever
+hosts compute it with the same pure, runtime-safe functions, so a host can refuse an address it
+did not derive.
+
+- **Line.** `deploymentLine({ origin, environment, addressing })` is shared by every deployment of
+  an origin in an environment. Its 16-character fingerprint, the first 80 bits of
+  `sha256(origin ‖ 0x00 ‖ environment)` in base32, makes it unique. A `readable` line (platform
+  Domains) prefixes it with a cosmetic part, so `agencies.example.com` in `staging` gives
+  `agencies-staging-354iwg4avm6wdmrs`. An `opaque` line (tenant Domains) is the fingerprint alone.
+- **Content.** `deploymentContent(buildDigest, configuration)` covers the build and the
+  `FrozenConfigurationV1`: the plain variables and execution settings (with the durable Workflow
+  options, when declared), the services and dispatch namespaces it binds, and the names of the
+  bound secrets, never their values. A changed variable or binding gives another URL, and a rotated
+  secret keeps the URL. `configurationDigest` gives the full digest that a deployment record keeps. It checks
+  canonical form only: the host refuses settings no Worker runs under when it encodes
+  `ASTRALE_SETTINGS` (`encodeWorkerSettings`), before it uploads anything.
+- **Label.** `deploymentLabel(line, content)` is at most 57 characters. `DEPLOYMENT_LABEL`
+  recognizes it, never a legacy UUID or stable Worker name, and `parseDeploymentLabel` splits it
+  and refuses anything longer than 57 characters.
+- **Record.** `acceptDeploymentRecord` admits a `DeploymentRecordV1` only when its provider
+  script is the label that its own fields derive. A host admits the record a deploy declares with
+  it before storing it, so every stored record decodes.
+
+```ts
+import {
+  deploymentContent,
+  deploymentLabel,
+  deploymentLine,
+  deploymentUrl,
+} from '@astrale-os/sdk/deployment/address'
+
+const line = deploymentLine({ origin, environment, addressing: 'opaque' })
+const url = deploymentUrl(deploymentLabel(line, deploymentContent(build, configuration)), routingDomain)
+```
+
+`@astrale-os/sdk/deployment/address/vectors` holds the conformance vectors: Worker uploads and
+configurations with the manifest, build digest, label and URL each one gives. Every host that
+recomputes an address tests against them.
+
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE) for details.
 
+## Domain icon
+
+```ts
+import { classIcon } from '@astrale-os/sdk/schema'
+import { Building2 } from '@astrale-os/sdk/schema/icons'
+
+export const domain = defineDomain({ schema, runtime, icon: classIcon.lucide(Building2) })
+```
+
+The release publishes the icon as `manifest.logo`. Use `classIcon.svg(...)` for a self-contained
+inline SVG, or omit `icon` and the release carries no manifest.
+
 ## View host requirements
 
 A frontend route can declare the exact external origins its View needs to open:
@@ -330,11 +460,14 @@ routes: {
 }
 ```
 
-These requirements are publication metadata, so changing them updates the publication ETag without
-changing the Application's business Schema. They require the `shell` handshake. Origins must use
+These requirements belong to the Release, so changing them updates its digest without
+changing the Domain's business Schema. They require the `shell` handshake. Origins must use
 HTTPS without credentials, paths, queries, fragments, or wildcards; authoring normalizes and sorts
 them. Supporting hosts admit them per mount and execute the existing `browser.openExternal`
 intent. Nested Views cannot expand their parent's grant.
 
 For the unified authentication facade and coordinated consumer update, see
 [the Auth API migration guide](docs/auth-api-migration.md).
+
+The authored composition formerly called an Application is now a Domain definition: see
+[the Domain definition migration guide](docs/domain-definition-migration.md).

package/dist/application/action/action.d.ts

@@ -29,6 +29,12 @@ export type ActionAddressOf<Callable> = Callable extends {
 export type ResolvedDomainOf<Schema extends schema.DomainSchema> = Extract<schema.DomainOf<Schema>, Domain>;
 /** SDK Action address derived mechanically from the canonical local callable key. */
 export type ActionAddress<Schema extends schema.DomainSchema> = ActionAddressOf<LocalCallable<ResolvedDomainOf<Schema>>>;
+/** Address of a callable an Action may implement: a durable callable needs a Workflow. */
+export type ImmediateActionAddress<Schema extends schema.DomainSchema> = ActionAddressOf<Exclude<LocalCallable<ResolvedDomainOf<Schema>>, {
+    readonly execution: {
+        readonly durable: true;
+    };
+}>>;
 export type CallableAtAddress<Schema extends schema.DomainSchema, Address extends string> = LocalCallable<ResolvedDomainOf<Schema>> extends infer Callable ? Callable extends unknown ? ActionAddressOf<Callable> extends Address ? Callable : never : never : never;
 export type Action<Callable extends ResolvedCallable, Definitions extends Integrations = Readonly<Record<never, never>>, DomainValue extends Domain = Domain, Errors extends DeclaredErrors = NoDeclaredErrors> = (context: ActionContext<Callable, DomainValue, Definitions, Errors>) => Promise<ActionOutputOf<Callable>>;
 declare const ACTION_SCHEMA: unique symbol;

package/dist/application/action/authoring.d.ts

@@ -1,5 +1,5 @@
 export { defineAction } from './define.js';
 export type { Action, ActionDefinition } from './action.js';
-export type { ActionContext, ActionExecution, Caller, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, } from './context.js';
+export type { ActionContext, ActionBinaryInput, ActionExecution, Caller, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, } from './context.js';
 export type { ActionBinary, ActionOutputOf } from './output.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from '../error/index.js';

package/dist/application/action/context.d.ts

@@ -1,7 +1,7 @@
-import type { AuthenticationEvidence, Grant, IdentityId } from '../../platform/auth/index.js';
+import type { AuthenticationEvidence, IdentityId } from '../../platform/auth/index.js';
 import type { BoundClientSession } from '../../platform/client/session/index.js';
 import type { NodeId } from '../../platform/graph/node/index.js';
-import type { CallableInputOf, Domain, ResolvedFunction, ResolvedMethod } from '../../platform/schema/index.js';
+import type { CallableInputOf, CallableInputModeOf, Domain, ResolvedFunction, ResolvedMethod } from '../../platform/schema/index.js';
 import type { HandlerDependencies } from '../dependency/index.js';
 import type { DeclaredErrorFactory, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { IntegrationClients, Integrations } from '../integration/index.js';
@@ -11,11 +11,10 @@ export type ResolvedCallable = ResolvedFunction | ResolvedMethod;
 /** Bearer-free caller evidence established before an Action or Workflow runs. */
 export interface AuthenticatedCaller {
     readonly kind: 'authenticated';
-    /** Exact effective caller Identity. Access fails when authority is compound. */
+    /** The one Identity whose authority this invocation exercises: ownership and attribution. */
     readonly identity: IdentityId;
-    /** Identity whose credential directly authenticated this invocation. */
+    /** Executor whose credential directly authenticated this invocation (for example this Domain). */
     readonly principal: IdentityId;
-    readonly authority: Grant;
     readonly authentication: AuthenticationEvidence;
 }
 export interface AnonymousCaller {
@@ -34,41 +33,58 @@ export interface ActionExecution {
         body(): Uint8Array;
     };
 }
+/** One admitted, single-consumer binary Function request body. */
+export interface ActionBinaryInput {
+    readonly body: ReadableStream<Uint8Array>;
+    readonly length: number;
+}
+type BinaryInputOf<Callable> = CallableInputModeOf<Callable> extends 'binary' ? {
+    readonly body: ActionBinaryInput;
+} : {
+    readonly body?: never;
+};
 export interface DomainGraphExecutor<DomainValue extends Domain = Domain> {
     readonly query: QueryExecutor<DomainValue>;
     readonly mutate: MutationExecutor<DomainValue>;
 }
-export type DomainGraphExecutors<DomainValue extends Domain = Domain> = Readonly<DomainGraphExecutor<DomainValue> & Record<'caller' | 'self' | 'union', DomainGraphExecutor<DomainValue>>>;
+/** Whose authority one Kernel call exercises: the incoming caller's or the installed Domain's. */
+export type AuthorityMode = 'caller' | 'self';
+/**
+ * One value per authority the code may act under. `self` exists in every invocation; `caller`
+ * exists only when the call carried a credential, so it is absent from a call that carried none.
+ */
+export type AuthoritySelection<Value, Authority extends AuthorityMode = AuthorityMode> = Readonly<Record<Authority, Value> & {
+    readonly [Absent in Exclude<AuthorityMode, Authority>]?: never;
+}>;
+export type DomainGraphExecutors<DomainValue extends Domain = Domain, Authority extends AuthorityMode = AuthorityMode> = Readonly<DomainGraphExecutor<DomainValue> & AuthoritySelection<DomainGraphExecutor<DomainValue>, Authority>>;
 /** Self-default Kernel session with one level of explicit authority selection. */
-export type DomainKernelSessions = Readonly<BoundClientSession & Record<'caller' | 'self' | 'union', BoundClientSession>>;
-type AuthorityOf<Callable, DomainValue extends Domain> = Callable extends {
-    readonly auth: 'anonymous';
-} ? {
-    readonly caller: AnonymousCaller;
-    readonly dependencies: null;
-    readonly kernel: null;
-    readonly graph: null;
-    readonly query?: never;
-    readonly mutate?: never;
-} | {
-    readonly caller: AuthenticatedCaller;
-    readonly dependencies: HandlerDependencies<DomainValue>;
-    readonly kernel: DomainKernelSessions;
-    readonly graph: DomainGraphExecutors<DomainValue>;
+export type DomainKernelSessions<Authority extends AuthorityMode = AuthorityMode> = Readonly<BoundClientSession & AuthoritySelection<BoundClientSession, Authority>>;
+/**
+ * What code acting under `Authority` holds toward the Kernel and its dependencies, with the
+ * installed Domain authority by default. An Action and a durable Step receive the same capabilities.
+ */
+export interface DomainCapabilities<DomainValue extends Domain = Domain, Authority extends AuthorityMode = AuthorityMode> {
+    readonly dependencies: HandlerDependencies<DomainValue, Authority>;
+    readonly kernel: DomainKernelSessions<Authority>;
+    readonly graph: DomainGraphExecutors<DomainValue, Authority>;
     /** Convenience executor using the installed Domain authority (`graph.self`). */
     readonly query: QueryExecutor<DomainValue>;
     /** Convenience executor using the installed Domain authority (`graph.self`). */
     readonly mutate: MutationExecutor<DomainValue>;
-} : {
+}
+/**
+ * A call to an `anonymous` callable that carries no credential has no caller, and its handler acts
+ * as the installed Domain alone. Every other call also selects its authenticated caller.
+ */
+type AuthorityOf<Callable, DomainValue extends Domain> = Callable extends {
+    readonly auth: 'anonymous';
+} ? ({
+    readonly caller: AnonymousCaller;
+} & DomainCapabilities<DomainValue, 'self'>) | ({
     readonly caller: AuthenticatedCaller;
-    readonly dependencies: HandlerDependencies<DomainValue>;
-    readonly kernel: DomainKernelSessions;
-    readonly graph: DomainGraphExecutors<DomainValue>;
-    /** Convenience executor using the installed Domain authority (`graph.self`). */
-    readonly query: QueryExecutor<DomainValue>;
-    /** Convenience executor using the installed Domain authority (`graph.self`). */
-    readonly mutate: MutationExecutor<DomainValue>;
-};
+} & DomainCapabilities<DomainValue, AuthorityMode>) : {
+    readonly caller: AuthenticatedCaller;
+} & DomainCapabilities<DomainValue, AuthorityMode>;
 type SelfOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {
     readonly self: NodeId;
 } : {
@@ -83,5 +99,5 @@ export type ActionContext<Callable extends ResolvedCallable, DomainValue extends
     readonly execution: ActionExecution;
     /** Construct one implementation-declared safe business error for `throw error(...)`. */
     readonly error: DeclaredErrorFactory<Errors>;
-} & AuthorityOf<Callable, DomainValue> & SelfOf<Callable>;
+} & AuthorityOf<Callable, DomainValue> & SelfOf<Callable> & BinaryInputOf<Callable>;
 export {};

package/dist/application/action/define.d.ts

@@ -1,12 +1,12 @@
 import type { schema } from '../../platform/schema/index.js';
 import type { DeclaredErrorOptions, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { Integrations } from '../integration/index.js';
-import type { Action, ActionAddress, ActionDefinition, CallableAtAddress, ResolvedDomainOf } from './action.js';
+import type { Action, ActionDefinition, CallableAtAddress, ImmediateActionAddress, ResolvedDomainOf } from './action.js';
 import type { ResolvedCallable } from './context.js';
 /** Define one simple single-step implementation by its SDK Action address. */
 export declare function defineAction<Schema extends schema.DomainSchema, Definitions extends Integrations = Readonly<Record<never, never>>>(): {
-    <const Address extends ActionAddress<Schema>>(address: Address, run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>, NoDeclaredErrors>): ActionDefinition<Schema, Address, Definitions, NoDeclaredErrors>;
-    <const Address extends ActionAddress<Schema>, const Errors extends DeclaredErrors>(address: Address, options: DeclaredErrorOptions<Errors>, run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>, Errors>): ActionDefinition<Schema, Address, Definitions, Errors>;
+    <const Address extends ImmediateActionAddress<Schema>>(address: Address, run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>, NoDeclaredErrors>): ActionDefinition<Schema, Address, Definitions, NoDeclaredErrors>;
+    <const Address extends ImmediateActionAddress<Schema>, const Errors extends DeclaredErrors>(address: Address, options: DeclaredErrorOptions<Errors>, run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>, Errors>): ActionDefinition<Schema, Address, Definitions, Errors>;
 };
 /** True only for an Action produced by defineAction in this SDK package root. */
 export declare function isAction(input: unknown): input is ActionDefinition;

package/dist/application/action/index.d.ts

@@ -1,5 +1,5 @@
 export { defineAction, isAction } from './define.js';
 export type { Action, ActionAddress, ActionAddressOf, ActionDefinition, CallableAtAddress, LocalCallable, ResolvedDomainOf, } from './action.js';
-export type { ActionContext, ActionExecution, AnonymousCaller, AuthenticatedCaller, Caller, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, ResolvedCallable, } from './context.js';
+export type { ActionContext, ActionBinaryInput, ActionExecution, AnonymousCaller, AuthenticatedCaller, AuthorityMode, AuthoritySelection, Caller, DomainCapabilities, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, ResolvedCallable, } from './context.js';
 export type { ActionBinary, ActionOutputOf } from './output.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from '../error/index.js';

package/dist/application/define.d.ts

@@ -1,16 +1,18 @@
-import type { schema } from '../platform/schema/index.js';
-import type { Application } from './application.js';
+import type { ClassIcon, schema } from '../platform/schema/index.js';
+import type { DomainDefinition } from './domain.js';
 import type { Requirements } from './requirements/index.js';
 import type { Routes } from './routes/index.js';
 import type { Runtime } from './runtime/index.js';
 import type { Frontend } from './view/index.js';
-export interface ApplicationInput<Schema extends schema.DomainSchema, RuntimeValue extends Runtime<Schema>, FrontendValue extends Frontend<Schema> | undefined, RoutesValue extends Routes | undefined, RequirementsValue extends Requirements | undefined> {
+export interface DomainDefinitionInput<Schema extends schema.DomainSchema, RuntimeValue extends Runtime<Schema>, FrontendValue extends Frontend<Schema> | undefined, RoutesValue extends Routes | undefined, RequirementsValue extends Requirements | undefined> {
     readonly schema: Schema;
     readonly runtime: RuntimeValue;
     readonly frontend?: FrontendValue;
     readonly routes?: RoutesValue;
     readonly requirements?: RequirementsValue;
+    /** The application's icon, made with `classIcon.svg(...)` or `classIcon.lucide(...)`. */
+    readonly icon?: ClassIcon;
 }
-/** Capture one inert authored Application without resolving, compiling, loading, or deploying it. */
-export declare function defineApplication<const Schema extends schema.DomainSchema, const RuntimeValue extends Runtime<Schema>, const FrontendValue extends Frontend<Schema> | undefined = undefined, const RoutesValue extends Routes | undefined = undefined, const RequirementsValue extends Requirements | undefined = undefined>(input: ApplicationInput<Schema, RuntimeValue, FrontendValue, RoutesValue, RequirementsValue>): Application<Schema, RuntimeValue, FrontendValue, RoutesValue, RequirementsValue>;
-export declare function isApplication(input: unknown): input is Application;
+/** Capture one inert authored Domain without resolving, compiling, loading, or deploying it. */
+export declare function defineDomain<const Schema extends schema.DomainSchema, const RuntimeValue extends Runtime<Schema>, const FrontendValue extends Frontend<Schema> | undefined = undefined, const RoutesValue extends Routes | undefined = undefined, const RequirementsValue extends Requirements | undefined = undefined>(input: DomainDefinitionInput<Schema, RuntimeValue, FrontendValue, RoutesValue, RequirementsValue>): DomainDefinition<Schema, RuntimeValue, FrontendValue, RoutesValue, RequirementsValue>;
+export declare function isDomainDefinition(input: unknown): input is DomainDefinition;

package/dist/application/define.js

@@ -1,40 +1,54 @@
+import { admitClassIconSvg } from '../platform/schema/class-icon-svg.js';
 import { isRequirements } from './requirements/index.js';
 import { isRoutes } from './routes/index.js';
 import { isRuntime } from './runtime/index.js';
 import { isFrontend } from './view/index.js';
-const admittedApplications = new WeakSet();
-/** Capture one inert authored Application without resolving, compiling, loading, or deploying it. */
-export function defineApplication(input) {
+const admittedDomainDefinitions = new WeakSet();
+/** Capture one inert authored Domain without resolving, compiling, loading, or deploying it. */
+export function defineDomain(input) {
     if (input === null || typeof input !== 'object' || Array.isArray(input))
         invalid();
-    const allowed = new Set(['schema', 'runtime', 'frontend', 'routes', 'requirements']);
+    const allowed = new Set([
+        'schema',
+        'runtime',
+        'frontend',
+        'routes',
+        'requirements',
+        'icon',
+    ]);
     if (Reflect.ownKeys(input).some((key) => !allowed.has(key)))
         invalid();
+    if (typeof input.schema?.name !== 'string') {
+        throw new TypeError(`Domain Schema ${String(input.schema?.origin)} must declare its name: defineSchema(origin, { name, ... }).`);
+    }
     if (!isRuntime(input.runtime))
-        throw new TypeError('Application Runtime is not admitted.');
+        throw new TypeError('Domain Runtime is not admitted.');
     if (input.frontend !== undefined &&
         (!isFrontend(input.frontend) || input.frontend.schema !== input.schema)) {
-        throw new TypeError('Application Frontend is not admitted for its exact Schema.');
+        throw new TypeError('Domain Frontend is not admitted for its exact Schema.');
     }
     if (input.routes !== undefined && !isRoutes(input.routes)) {
-        throw new TypeError('Application routes are not admitted.');
+        throw new TypeError('Domain routes are not admitted.');
     }
     if (input.requirements !== undefined && !isRequirements(input.requirements)) {
-        throw new TypeError('Application requirements are not admitted.');
+        throw new TypeError('Domain requirements are not admitted.');
     }
-    const application = Object.freeze({
+    // The same admission as a Node Class icon: one self-contained inline SVG.
+    const icon = input.icon === undefined ? undefined : admitClassIconSvg(input.icon);
+    const domain = Object.freeze({
         schema: input.schema,
         runtime: input.runtime,
         ...(input.frontend === undefined ? {} : { frontend: input.frontend }),
         ...(input.routes === undefined ? {} : { routes: input.routes }),
         ...(input.requirements === undefined ? {} : { requirements: input.requirements }),
+        ...(icon === undefined ? {} : { icon }),
     });
-    admittedApplications.add(application);
-    return application;
+    admittedDomainDefinitions.add(domain);
+    return domain;
 }
-export function isApplication(input) {
-    return input !== null && typeof input === 'object' && admittedApplications.has(input);
+export function isDomainDefinition(input) {
+    return input !== null && typeof input === 'object' && admittedDomainDefinitions.has(input);
 }
 function invalid() {
-    throw new TypeError('Application definition may contain only schema, runtime, frontend, routes, and requirements.');
+    throw new TypeError('Domain definition may contain only schema, runtime, frontend, routes, requirements, and icon.');
 }

package/dist/application/dependency/index.d.ts

@@ -1 +1 @@
-export type { DependencyCallOptions, DependencyInvoker, HandlerDependencies } from './invoker.js';
+export type { DependencyBinaryCallOptions, DependencyCallOptions, DependencyInvoker, HandlerDependencies, } from './invoker.js';