@astrale-os/sdk 0.5.0-beta.99 → 0.6.0-beta.0

package/README.md

@@ -31,12 +31,117 @@ npx -y create-astrale-domain@beta my-domain --yes
 See [the release lifecycle](docs/release.md) for package-set versioning, verification, and stable
 promotion.
 
+### Update a pnpm project
+
+```sh
+pnpm exec astrale-domain upgrade --check  # Preview; no project changes
+pnpm exec astrale-domain upgrade          # Update existing Astrale dependencies to beta
+```
+
+The command covers the workspace root and its packages, pins exact versions, and updates the
+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.
+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
+
+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:
+
+```ts
+cloudflare({
+  route: 'services-v2.example.com',
+  workerName: 'services-v2',
+  identityIssuer: 'https://services.example.com',
+  signingIdentity: '.astrale/identity.json',
+})
+```
+
+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.
+
+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.
+
+## Handler authority and dependencies
+
+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).
+
+## Node Class icons
+
+Every Node Class authored through the SDK must explicitly declare a self-contained SVG icon.
+Omission is rejected by TypeScript, at the runtime authoring boundary, and by the
+`SCH-ICON-REQUIRED` linter rule. Prefer framework-neutral Lucide data when an icon exists in that
+catalog:
+
+```typescript
+import { classIcon, nodeClass } from '@astrale-os/sdk/schema'
+import { FileText } from '@astrale-os/sdk/schema/icons'
+
+export const Article = nodeClass({
+  icon: classIcon.lucide(FileText),
+})
+```
+
+Use `classIcon.svg(source)` for a custom self-contained SVG. If no meaningful icon has been chosen,
+declare `icon: classIcon.neutral` explicitly. This stable empty SVG renders no glyph and remains
+valid; the linter emits a non-failing `SCH-ICON-NEUTRAL` warning. Bare names such as `"file-text"`,
+non-canonical empty SVGs, external references, and executable SVG content are rejected during
+Schema authoring.
+
+## Business-error declarations
+
+Declare reusable business errors in `schema/modules/<module>/errors/` through the Schema facade:
+
+```typescript
+import { error } from '@astrale-os/sdk/schema/errors'
+import { z } from 'zod'
+
+export const resourceUnavailable = error({
+  family: 'NOT_FOUND',
+  message: 'The selected resource is unavailable.',
+  details: z.strictObject({ resource: z.string() }),
+})
+```
+
+Register the declaration under a code in an Action or Workflow's options:
+`{ errors: { RESOURCE_UNAVAILABLE: resourceUnavailable } }`. Its handler can then
+`throw error('RESOURCE_UNAVAILABLE', { resource: id })` using the context factory.
+The builder validates and freezes declaration metadata while preserving exact details inference.
+Use `sdk/schema/errors` for declarations shared with handlers: this narrow entrypoint keeps the
+Schema compiler and Kernel Schema initialization out of the deployed Runtime.
+Error declarations are not yet published in the installed Kernel Schema.
+
 ## Development
 
+### 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
+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.
+
 ### Prerequisites
 
 - Node.js 26.7.0 (default) or Node.js 24; published packages remain compatible with Node.js 22+
-- pnpm 12.0.0
+- pnpm 12.1.0
 
 ### Setup
 
@@ -45,9 +150,11 @@ The repository installs autonomously from its versioned npm-only lockfile:
 ```bash
 git clone https://github.com/astrale-os/sdk.git
 cd sdk
-STANDALONE=true pnpm install --frozen-lockfile
+AGENT_HARNESSES=codex bash scripts/setup/setup.sh
 ```
 
+See [agent setup](scripts/setup/README.md) for Claude Cloud and validation.
+
 It can also be consumed as a submodule of the main Astrale workspace:
 
 ```bash
@@ -109,6 +216,62 @@ linter tool failures.
 Structured review [issues](issues/README.md) retain observation-first evidence and later governance
 attachments without becoming current contract authority.
 
+## Dataset references
+
+A Dataset can materialize a projected Node explicitly with `ref`, using its resolved local or
+direct-dependency definition:
+
+```typescript
+const demo = defineDataset(Schema, {
+  id: 'demo',
+  graph({ domain, ref }) {
+    const member = ref(domain.core.nodes.member)
+    // Repeating ref returns the same Dataset Node. node() always creates a separate identity.
+    return { member }
+  },
+})
+```
+
+`ref` uses the canonical symbolic Schema projection for Class, Function, Policy, View and Core
+facts. The Dataset's `references` table retains the explicit association between each projected
+NodePath and its Dataset Node ID through encoding and decoding. Matching properties or slugs do
+not create that association. Studio uses it when simulating `sameNode` and reference endpoints;
+a missing association makes that simulation unavailable.
+
+## Kernel publication 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.
+
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE) for details.
+
+## View host requirements
+
+A frontend route can declare the exact external origins its View needs to open:
+
+```ts
+routes: {
+  application: {
+    path: '/',
+    host: {
+      navigation: {
+        external: { origins: ['https://provider.example'] },
+      },
+    },
+  },
+}
+```
+
+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
+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).

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

@@ -1,4 +1,5 @@
 import type { Domain, ResolvedMethod, schema } from '../../platform/schema/index.js';
+import type { DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { Integrations } from '../integration/index.js';
 import type { ActionContext, ResolvedCallable } from './context.js';
 import type { ActionOutputOf } from './output.js';
@@ -15,7 +16,9 @@ type MethodValues<Class> = Class extends {
         };
     };
 } ? Values<Instance> | Values<Static> : never;
-type Executable<Callable> = Callable extends ResolvedMethod<unknown, unknown, boolean, infer Inheritance> ? Inheritance extends 'abstract' ? never : Callable : Callable;
+type Executable<Callable> = Callable extends ResolvedMethod ? Callable extends {
+    readonly executable: true;
+} ? Callable : never : Callable;
 /** Every root-owned callable implementation contract, independent of Function or Method topology. */
 export type LocalCallable<DomainValue extends Domain> = Extract<Values<DomainValue['functions']>, ResolvedCallable> | Extract<Executable<MethodValues<Values<DomainValue['classes']>>>, ResolvedCallable>;
 export type ActionAddressOf<Callable> = Callable extends {
@@ -27,13 +30,13 @@ export type ResolvedDomainOf<Schema extends schema.DomainSchema> = Extract<schem
 /** SDK Action address derived mechanically from the canonical local callable key. */
 export type ActionAddress<Schema extends schema.DomainSchema> = ActionAddressOf<LocalCallable<ResolvedDomainOf<Schema>>>;
 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> = (context: ActionContext<Callable, DomainValue, Definitions>) => Promise<ActionOutputOf<Callable>>;
+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;
 /** Sealed standalone Action awaiting canonical callable association by Runtime admission. */
-export interface ActionDefinition<Schema extends schema.DomainSchema = schema.DomainSchema, Address extends ActionAddress<Schema> = ActionAddress<Schema>, Definitions extends Integrations = Readonly<Record<never, never>>> {
+export interface ActionDefinition<Schema extends schema.DomainSchema = schema.DomainSchema, Address extends ActionAddress<Schema> = ActionAddress<Schema>, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> {
     readonly kind: 'action';
     readonly address: Address;
-    readonly run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>>;
+    readonly run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>, Errors>;
     /** Invariant type-only Schema witness; absent from emitted JavaScript. */
     readonly [ACTION_SCHEMA]: (schema: Schema) => Schema;
 }

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

@@ -1,4 +1,5 @@
 export { defineAction } from './define.js';
 export type { Action, ActionDefinition } from './action.js';
-export type { ActionContext, ActionExecution, Caller, DomainGraphExecutor, DomainGraphExecutors, } from './context.js';
+export type { ActionContext, 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

@@ -2,6 +2,8 @@ import type { AuthenticationEvidence, Grant, IdentityId } from '../../platform/a
 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 { HandlerDependencies } from '../dependency/index.js';
+import type { DeclaredErrorFactory, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { IntegrationClients, Integrations } from '../integration/index.js';
 import type { MutationExecutor } from '../mutation/index.js';
 import type { QueryExecutor } from '../query/index.js';
@@ -9,6 +11,9 @@ 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. */
+    readonly identity: IdentityId;
+    /** Identity whose credential directly authenticated this invocation. */
     readonly principal: IdentityId;
     readonly authority: Grant;
     readonly authentication: AuthenticationEvidence;
@@ -33,37 +38,35 @@ export interface DomainGraphExecutor<DomainValue extends Domain = Domain> {
     readonly query: QueryExecutor<DomainValue>;
     readonly mutate: MutationExecutor<DomainValue>;
 }
-export type DomainGraphExecutors<DomainValue extends Domain = Domain> = Readonly<Record<'caller' | 'self' | 'union', DomainGraphExecutor<DomainValue>>>;
-/** Explicit full Kernel sessions. No authority mode is selected implicitly. */
-export type DomainKernelSessions = Readonly<Record<'caller' | 'self' | 'union', BoundClientSession>>;
+export type DomainGraphExecutors<DomainValue extends Domain = Domain> = Readonly<DomainGraphExecutor<DomainValue> & Record<'caller' | 'self' | 'union', DomainGraphExecutor<DomainValue>>>;
+/** 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 client: null;
+    readonly dependencies: null;
     readonly kernel: null;
     readonly graph: null;
     readonly query?: never;
     readonly mutate?: never;
 } | {
     readonly caller: AuthenticatedCaller;
-    /** Caller-only Kernel client. Privileged Domain work must select kernel.self explicitly. */
-    readonly client: BoundClientSession;
+    readonly dependencies: HandlerDependencies<DomainValue>;
     readonly kernel: DomainKernelSessions;
     readonly graph: DomainGraphExecutors<DomainValue>;
-    /** Caller-only convenience executor. */
+    /** Convenience executor using the installed Domain authority (`graph.self`). */
     readonly query: QueryExecutor<DomainValue>;
-    /** Caller-only convenience executor. */
+    /** Convenience executor using the installed Domain authority (`graph.self`). */
     readonly mutate: MutationExecutor<DomainValue>;
 } : {
     readonly caller: AuthenticatedCaller;
-    /** Caller-only Kernel client. Privileged Domain work must select kernel.self explicitly. */
-    readonly client: BoundClientSession;
+    readonly dependencies: HandlerDependencies<DomainValue>;
     readonly kernel: DomainKernelSessions;
     readonly graph: DomainGraphExecutors<DomainValue>;
-    /** Caller-only convenience executor. */
+    /** Convenience executor using the installed Domain authority (`graph.self`). */
     readonly query: QueryExecutor<DomainValue>;
-    /** Caller-only convenience executor. */
+    /** Convenience executor using the installed Domain authority (`graph.self`). */
     readonly mutate: MutationExecutor<DomainValue>;
 };
 type SelfOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {
@@ -72,11 +75,13 @@ type SelfOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false>
     readonly self?: never;
 };
 /** Exact single-step Action context derived from one resolved callable. */
-export type ActionContext<Callable extends ResolvedCallable, DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>> = {
+export type ActionContext<Callable extends ResolvedCallable, DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> = {
     /** Exact admitted Domain retained by the Build being executed. */
     readonly domain: DomainValue;
     readonly input: CallableInputOf<Callable>;
     readonly integrations: IntegrationClients<Definitions>;
     readonly execution: ActionExecution;
+    /** Construct one implementation-declared safe business error for `throw error(...)`. */
+    readonly error: DeclaredErrorFactory<Errors>;
 } & AuthorityOf<Callable, DomainValue> & SelfOf<Callable>;
 export {};

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

@@ -1,8 +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 { 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>>) => ActionDefinition<Schema, Address, Definitions>;
+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>;
+};
 /** 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/define.js

@@ -1,12 +1,17 @@
 import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import { rememberDeclaredErrors } from '../error/index.js';
 const admittedActions = new WeakSet();
 /** Define one simple single-step implementation by its SDK Action address. */
 export function defineAction() {
-    return function define(address, run) {
+    return function define(address, optionsOrRun, possibleRun) {
         acceptActionAddress(address);
+        const options = possibleRun === undefined ? undefined : optionsOrRun;
+        const run = possibleRun ?? optionsOrRun;
         if (typeof run !== 'function')
             throw new TypeError('Action run must be a function.');
         const action = Object.freeze({ kind: 'action', address, run });
+        if (options !== undefined)
+            rememberDeclaredErrors(action, options);
         admittedActions.add(action);
         return action;
     };

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

@@ -1,4 +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, ResolvedCallable, } from './context.js';
+export type { ActionContext, ActionExecution, AnonymousCaller, AuthenticatedCaller, Caller, 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/dependency/index.d.ts

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

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

@@ -0,0 +1,26 @@
+import type { Binary, Input } from '../../platform/client/index.js';
+import type { SessionRequestOptions } from '../../platform/client/session/index.js';
+import type { NodeId } from '../../platform/graph/node/index.js';
+import type { CallableInputOf, CallableOutputOf, CallableResultOf, Domain, ResolvedMethod, KernelSchema, schema } from '../../platform/schema/index.js';
+import type { LocalCallable } from '../action/index.js';
+export type DependencyCallOptions = Pick<SessionRequestOptions, 'timeoutMs' | 'idempotencyKey'>;
+type InstanceMethodOf<D extends Domain> = Extract<LocalCallable<D>, ResolvedMethod<unknown, unknown, false>>;
+type FunctionOrStaticMethodOf<D extends Domain> = Exclude<LocalCallable<D>, ResolvedMethod<unknown, unknown, false>>;
+type DependencyInputOf<C> = C extends unknown ? unknown extends CallableInputOf<C> ? Input : [CallableInputOf<C>] extends [void] ? undefined : CallableInputOf<C> : never;
+type DependencyResultOf<C> = unknown extends CallableOutputOf<C> ? unknown : CallableResultOf<C, Binary>;
+/** One declared dependency, bound to one explicitly selected invocation authority. */
+export interface DependencyInvoker<D extends Domain> {
+    readonly invoke: {
+        <const C extends FunctionOrStaticMethodOf<D>>(select: (domain: D) => C, input: NoInfer<DependencyInputOf<C>>, options?: DependencyCallOptions): Promise<DependencyResultOf<C>>;
+        <const C extends InstanceMethodOf<D>>(select: (domain: D) => C, instance: NodeId, input: NoInfer<DependencyInputOf<C>>, options?: DependencyCallOptions): Promise<DependencyResultOf<C>>;
+    };
+}
+/**
+ * Direct Schema aliases with explicit authority selection and no default invoke.
+ * self is the executing Domain; caller forwards the incoming Grant; union combines both.
+ * The canonical Kernel is exposed through context.kernel.
+ */
+export type HandlerDependencies<D extends Domain> = Readonly<{
+    [Alias in keyof D['dependencies'] as D['dependencies'][Alias] extends schema.DomainOf<KernelSchema> ? never : Alias]: Readonly<Record<'caller' | 'self' | 'union', DependencyInvoker<Extract<D['dependencies'][Alias], Domain>>>>;
+}>;
+export {};

package/dist/application/error/error.d.ts

@@ -0,0 +1,23 @@
+import type { z } from 'zod';
+import type { DeclaredErrorDefinition } from '../../platform/schema/error.js';
+import * as value from '../../platform/value/index.js';
+export type { DeclaredErrorDefinition, DeclaredErrorFamily } from '../../platform/schema/error.js';
+export type DeclaredErrors = Readonly<Record<string, DeclaredErrorDefinition>>;
+export type NoDeclaredErrors = Readonly<Record<never, never>>;
+export interface DeclaredErrorOptions<out Errors extends DeclaredErrors = DeclaredErrors> {
+    readonly errors: Errors;
+}
+export type DeclaredErrorFactory<Errors extends DeclaredErrors> = <Code extends Extract<keyof Errors, string>>(code: Code, details: z.input<Errors[Code]['details']>) => Error;
+interface DeclaredErrorRecord {
+    readonly definition: object;
+    readonly code: string;
+    readonly family: DeclaredErrorDefinition['family'];
+    readonly message: string;
+    readonly details: value.Object;
+}
+/** Retain one implementation-local expected-error contract without publishing it in the Schema. */
+export declare function rememberDeclaredErrors(definition: object, input: unknown): void;
+/** Create a receiver-free factory closed over one admitted Action or Workflow definition. */
+export declare function declaredErrorFactory<Errors extends DeclaredErrors>(definition: object): DeclaredErrorFactory<Errors>;
+/** Return admitted evidence only when the error belongs to the active implementation. */
+export declare function declaredErrorOf(input: unknown, definition: object): DeclaredErrorRecord | undefined;

package/dist/application/error/error.js

@@ -0,0 +1,87 @@
+import { acceptErrorDefinition } from '../../platform/schema/error.js';
+import * as value from '../../platform/value/index.js';
+const MAXIMUM_DECLARED_ERRORS = 32;
+const MAXIMUM_DETAILS_BYTES = 16 * 1024;
+const CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,127}$/u;
+const declarations = new WeakMap();
+const errors = new WeakMap();
+class BusinessError extends Error {
+    name = 'BusinessError';
+    constructor(code) {
+        super(`Declared business error ${code}.`);
+    }
+}
+/** Retain one implementation-local expected-error contract without publishing it in the Schema. */
+export function rememberDeclaredErrors(definition, input) {
+    if (!isRecord(input) || Reflect.ownKeys(input).some((key) => key !== 'errors'))
+        invalidOptions();
+    if (!isRecord(input.errors))
+        invalidOptions();
+    const entries = Object.entries(input.errors);
+    if (entries.length > MAXIMUM_DECLARED_ERRORS) {
+        throw new TypeError(`An implementation may declare at most ${MAXIMUM_DECLARED_ERRORS} errors.`);
+    }
+    const accepted = new Map();
+    for (const [code, candidate] of entries) {
+        if (!CODE_PATTERN.test(code))
+            throw new TypeError(`Declared error code ${JSON.stringify(code)} is invalid.`);
+        accepted.set(code, acceptErrorDefinition(candidate, `Declared error ${JSON.stringify(code)}`));
+    }
+    declarations.set(definition, accepted);
+}
+/** Create a receiver-free factory closed over one admitted Action or Workflow definition. */
+export function declaredErrorFactory(definition) {
+    return ((code, input) => {
+        const declaration = declarations.get(definition)?.get(code);
+        if (declaration === undefined) {
+            throw new TypeError(`Business error ${JSON.stringify(code)} is not declared by this implementation.`);
+        }
+        const parsed = declaration.details.safeParse(input);
+        if (!parsed.success) {
+            throw new TypeError(`Business error ${code} details are invalid.`, { cause: parsed.error });
+        }
+        let details;
+        try {
+            const accepted = value.accept(parsed.data, { limits: { maxBytes: MAXIMUM_DETAILS_BYTES } });
+            value.json.encode(accepted, { limits: { maxBytes: MAXIMUM_DETAILS_BYTES } });
+            if (!isRecord(accepted))
+                throw new TypeError('Details must be an object.');
+            details = freezeValue(accepted);
+        }
+        catch (cause) {
+            throw new TypeError(`Business error ${code} details must be a bounded portable object.`, {
+                cause,
+            });
+        }
+        const error = new BusinessError(code);
+        errors.set(error, Object.freeze({
+            definition,
+            code,
+            family: declaration.family,
+            message: declaration.message,
+            details,
+        }));
+        return error;
+    });
+}
+/** Return admitted evidence only when the error belongs to the active implementation. */
+export function declaredErrorOf(input, definition) {
+    if (!(input instanceof Error))
+        return undefined;
+    const record = errors.get(input);
+    return record?.definition === definition ? record : undefined;
+}
+function isRecord(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input);
+}
+function freezeValue(input) {
+    return Object.freeze(Object.fromEntries(Object.entries(input).map(([key, nested]) => [key, freezeNestedValue(nested)])));
+}
+function freezeNestedValue(input) {
+    if (Array.isArray(input))
+        return Object.freeze(input.map(freezeNestedValue));
+    return isRecord(input) ? freezeValue(input) : input;
+}
+function invalidOptions() {
+    throw new TypeError('Action or Workflow options must contain exactly an errors object.');
+}

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

@@ -0,0 +1,2 @@
+export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, NoDeclaredErrors, } from './error.js';
+export { declaredErrorFactory, declaredErrorOf, rememberDeclaredErrors } from './error.js';

package/dist/application/error/index.js

@@ -0,0 +1 @@
+export { declaredErrorFactory, declaredErrorOf, rememberDeclaredErrors } from './error.js';

package/dist/application/index.d.ts

@@ -1,9 +1,9 @@
 export { defineApplication, isApplication } from './define.js';
 export type { ApplicationInput } from './define.js';
 export { requirements } from './requirements/index.js';
-export type { AuthorityRequirements, AuthorityRequirementsInput, ClassOperation, ClassRequirement, ClassRequirementInput, FunctionRequirementTarget, Requirements, RequirementsInput, } from './requirements/index.js';
+export type { AuthorityRequirements, AuthorityRequirementsInput, ClassOperation, ClassRequirement, ClassRequirementInput, CoreRequirement, CoreRequirementInput, FunctionRequirementTarget, Requirements, RequirementsInput, } from './requirements/index.js';
 export { route, routes } from './routes/index.js';
 export type { Route, RouteInput, RouteTarget, Routes } from './routes/index.js';
 export { defineFrontend, external, vite } from './view/index.js';
-export type { Frontend, FrontendInput, FrontendSource, IframeRequirements } from './view/index.js';
+export type { Frontend, FrontendInput, FrontendSource, IframeRequirements, ViewHostRequirements, } from './view/index.js';
 export type { Application, ApplicationIdentity, RuntimeOfApplication, SchemaOfApplication, SchemaOfRuntime, } from './application.js';

package/dist/application/integration/authentication.d.ts

@@ -0,0 +1,10 @@
+import type { MintedCredential } from '../../platform/auth/index.js';
+export interface IntegrationMintInput {
+    readonly audience: string;
+    /** Maximum requested lifetime, in whole seconds, from 1 through 60. */
+    readonly ttlSeconds: number;
+}
+/** Invocation-bound authentication as the executing Domain, never the caller. */
+export interface IntegrationAuthentication {
+    mint(input: IntegrationMintInput): Promise<MintedCredential>;
+}

package/dist/application/integration/authentication.typecheck.js

@@ -0,0 +1,18 @@
+async function provider(execution) {
+    // @ts-expect-error An anonymous invocation has no auth capability.
+    await execution.auth.mint({ audience: 'admin', ttlSeconds: 60 });
+    if (execution.auth === undefined)
+        return;
+    await execution.auth.mint({ audience: 'admin', ttlSeconds: 60 });
+    // @ts-expect-error Providers cannot register identities.
+    execution.auth.register({});
+    // @ts-expect-error Providers cannot delegate authority.
+    execution.auth.delegate({});
+    // @ts-expect-error Providers cannot supply a Grant.
+    execution.auth.mint({ audience: 'admin', ttlSeconds: 60, grant: {} });
+    // @ts-expect-error The destination audience is mandatory.
+    const invalid = { ttlSeconds: 60 };
+    return invalid;
+}
+void provider;
+export {};

package/dist/application/integration/client.d.ts

@@ -1,4 +1,5 @@
 import type { BoundClientSession } from '../../platform/client/session/index.js';
+import type { IntegrationAuthentication } from './authentication.js';
 import type { IntegrationClients, Integrations } from './integration.js';
 import type { IntegrationReplayDecision } from './operation.js';
 import type { Providers } from './provider.js';
@@ -7,6 +8,7 @@ export interface IntegrationCallCoordinates {
     readonly signal: AbortSignal;
     readonly deadline: number;
     readonly invoke?: BoundClientSession['invoke'];
+    readonly auth?: IntegrationAuthentication;
 }
 export interface IntegrationAttempt<Output> {
     readonly integration: string;

package/dist/application/integration/client.js

@@ -78,8 +78,12 @@ function admitCoordinates(input) {
     if (input === null || typeof input !== 'object' || Array.isArray(input))
         invalidCoordinates();
     const keys = Reflect.ownKeys(input);
-    if ((keys.length !== 3 && keys.length !== 4) ||
-        !keys.every((key) => key === 'callId' || key === 'signal' || key === 'deadline' || key === 'invoke') ||
+    if (!['callId', 'signal', 'deadline'].every((key) => Object.hasOwn(input, key)) ||
+        !keys.every((key) => key === 'callId' ||
+            key === 'signal' ||
+            key === 'deadline' ||
+            key === 'invoke' ||
+            key === 'auth') ||
         typeof input.callId !== 'string' ||
         input.callId.length === 0 ||
         input.callId.trim() !== input.callId ||
@@ -88,13 +92,26 @@ function admitCoordinates(input) {
         (input.invoke !== undefined && typeof input.invoke !== 'function')) {
         invalidCoordinates();
     }
+    const auth = input.auth === undefined ? undefined : admitAuthentication(input.auth);
     return Object.freeze({
         callId: input.callId,
         signal: input.signal,
         deadline: input.deadline,
         ...(input.invoke === undefined ? {} : { invoke: input.invoke }),
+        ...(auth === undefined ? {} : { auth }),
     });
 }
+function admitAuthentication(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        Reflect.ownKeys(input).length !== 1 ||
+        !Object.hasOwn(input, 'mint') ||
+        typeof input.mint !== 'function') {
+        invalidCoordinates();
+    }
+    return Object.freeze({ mint: input.mint.bind(input) });
+}
 function invalidCoordinates() {
     throw new TypeError('Integration call coordinates are invalid.');
 }

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

@@ -5,3 +5,4 @@ export type { DefineIntegration, ProviderBinding } from './define.js';
 export type { IntegrationClient, IntegrationClients, IntegrationDefinition, Integrations, } from './integration.js';
 export type { IntegrationExecution, IntegrationInput, IntegrationOperation, IntegrationOperations, IntegrationOutput, IntegrationReplay, IntegrationReplayDecision, } from './operation.js';
 export type { Provider, ProviderImplementation, Providers } from './provider.js';
+export type { IntegrationAuthentication, IntegrationMintInput } from './authentication.js';

package/dist/application/integration/operation.d.ts

@@ -1,4 +1,5 @@
 import type { BoundClientSession } from '../../platform/client/session/index.js';
+import type { IntegrationAuthentication } from './authentication.js';
 declare const INTEGRATION_OPERATION: unique symbol;
 export type IntegrationReplayDecision = {
     readonly kind: 'safe';
@@ -20,6 +21,8 @@ export interface IntegrationExecution {
     readonly idempotencyKey?: string;
     /** Exact caller-bound invocation capability; absent for an anonymous invocation. */
     readonly invoke?: BoundClientSession['invoke'];
+    /** Domain-self transport authentication; absent for an anonymous invocation. */
+    readonly auth?: IntegrationAuthentication;
 }
 export interface IntegrationOperation<Input = unknown, Output = unknown> {
     readonly replay: IntegrationReplay<Input>;