@astrale-os/sdk 0.6.0-beta.35 → 0.6.0-beta.37

package/dist/execution/invocation/admission/age.js

@@ -0,0 +1,208 @@
+import { callableAddress, Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import { admissionInputFields, MAXIMUM_ADMISSION_AGE_SECONDS, } from '@astrale-os/kernel-dsl/v1/language';
+import { Path } from '../../../platform/graph/path/index.js';
+import { target as acceptTarget } from './target.js';
+/**
+ * How long reading a kept admission may take before the call asks its Kernel instead. Reads of a
+ * shared platform cache answer in single-digit milliseconds; `Function.admit` costs tens.
+ */
+export const ADMISSION_RECALL_TIMEOUT_MS = 30;
+/** Version of the key and entry encodings below; a change makes every kept admission a miss. */
+const ENCODING = 'astrale.admission/1';
+const ENTRY_FIELDS = new Set(['v', 'callable', 'receiver', 'expiresAt']);
+/**
+ * The scope of a call whose target names, before the graph is read, implementations of which one
+ * declares an admission age. Undefined otherwise: a target that names no local implementation (a
+ * callable Node id, a path ending in a traversal), only callables without an age, or a durable
+ * Workflow, which runs only as a Kernel Execution. The Path language dispatches exactly, so a named
+ * target selects one declaration; the fields are still the union over every implementation named.
+ */
+export function admissionScope(registry, call) {
+    const names = declarationsNamedBy(call.target);
+    const named = registry.implementations.filter(({ callable }) => names(callable.key));
+    if (named.every(({ callable }) => callable.admission === undefined))
+        return undefined;
+    if (named.some((implementation) => implementation.kind === 'workflow' && implementation.durable)) {
+        return undefined;
+    }
+    const fields = new Set();
+    for (const { callable } of named) {
+        for (const field of admissionInputFields(callable.policy))
+            fields.add(field);
+    }
+    return Object.freeze({
+        callables: new Set(named.map(({ callable }) => callable.key)),
+        fields: Object.freeze([...fields].sort()),
+    });
+}
+/** Whether any implementation of this registry declares an admission age. */
+export function declaresAdmissionAge(registry) {
+    return registry.implementations.some(({ callable }) => callable.admission !== undefined);
+}
+/**
+ * The cache key of one call's admission: a SHA-256 over the source Kernel, the served release, the
+ * verified principal and caller, the canonical call target (receiver included) and the input
+ * projected on the fields its Policy reads. A missing field differs from `null`, object keys are
+ * sorted at every depth, and no other part of the input enters the key.
+ */
+export async function admissionKey(scope, partition, call) {
+    const encoded = JSON.stringify([
+        ENCODING,
+        partition.kernel,
+        partition.release,
+        partition.caller?.principal ?? null,
+        partition.caller?.identity ?? null,
+        canonical(call.target),
+        projection(call.input, scope.fields),
+    ]);
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(encoded));
+    return `admission/${hex(new Uint8Array(digest))}`;
+}
+/**
+ * The target of an admission this deployment kept under `key`, while it is younger than the age it
+ * carried. A missing, expired, malformed, out-of-scope, failed or late read is a miss.
+ */
+export async function recallAdmission(cache, key, scope) {
+    const value = await boundedRead(cache, key);
+    return value === undefined ? undefined : keptTarget(value, scope, Date.now());
+}
+/**
+ * Keep a successful admission that carries an age, until `sentAt` plus that age, `sentAt` being when
+ * `Function.admit` was asked. Written in the background: the call never waits on the cache, and a
+ * cache that fails to keep it only costs a later call its admission round trip.
+ */
+export function keepAdmission(cache, key, scope, admitted, sentAt, background) {
+    if (admitted.maxAge === undefined || !scope.callables.has(admitted.target.callable))
+        return;
+    const expiresAt = sentAt + admitted.maxAge * 1000;
+    const value = JSON.stringify({
+        v: 1,
+        callable: admitted.target.callable,
+        ...(admitted.target.receiver === undefined ? {} : { receiver: admitted.target.receiver }),
+        expiresAt,
+    });
+    try {
+        background(async () => {
+            try {
+                await cache.put(key, value, expiresAt);
+            }
+            catch {
+                // A cache that cannot keep this admission leaves the next call to its Kernel.
+            }
+        });
+    }
+    catch {
+        // A Server that no longer accepts background work keeps nothing; the call is unaffected.
+    }
+}
+function keptTarget(value, scope, now) {
+    let entry;
+    try {
+        entry = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(entry) || Reflect.ownKeys(entry).some((key) => !ENTRY_FIELDS.has(key))) {
+        return undefined;
+    }
+    const { v, callable, receiver, expiresAt } = entry;
+    if (v !== 1 ||
+        typeof callable !== 'string' ||
+        !scope.callables.has(callable) ||
+        typeof expiresAt !== 'number' ||
+        !Number.isSafeInteger(expiresAt) ||
+        expiresAt <= now ||
+        expiresAt > now + MAXIMUM_ADMISSION_AGE_SECONDS * 1000) {
+        return undefined;
+    }
+    try {
+        return acceptTarget({ callable, ...(receiver === undefined ? {} : { receiver }) });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One read bounded in time; a cache error is a miss. No pending read is shared across calls. */
+async function boundedRead(cache, key) {
+    let timer;
+    const read = Promise.resolve()
+        .then(() => cache.get(key))
+        .then((value) => (typeof value === 'string' ? value : undefined), () => undefined);
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), ADMISSION_RECALL_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([read, late]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** The declarations `target` names before the graph is read, as a test on a callable key. */
+function declarationsNamedBy(target) {
+    if (typeof target !== 'string')
+        return (key) => target.callable === key;
+    let path;
+    try {
+        path = Path.parse(target);
+    }
+    catch {
+        return () => false;
+    }
+    const { anchor, steps } = path.ast;
+    const last = steps.at(-1);
+    const first = steps[0];
+    return (key) => {
+        const coordinate = callableAddress(key);
+        if (coordinate.kind === 'method') {
+            if (last?.kind !== 'method' || last.name !== coordinate.name)
+                return false;
+            if (last.dispatch === 'instance')
+                return last.class === Key.of(coordinate.owner);
+            return (anchor.kind === 'domain' &&
+                anchor.origin === coordinate.owner.origin &&
+                steps.length === 2 &&
+                first?.kind === 'projection' &&
+                first.projection.kind === 'class' &&
+                first.projection.name === coordinate.owner.name);
+        }
+        return (anchor.kind === 'domain' &&
+            anchor.origin === coordinate.origin &&
+            steps.length === 1 &&
+            first?.kind === 'projection' &&
+            first.projection.kind === 'function' &&
+            first.projection.name === coordinate.name);
+    };
+}
+/** The input on the fields a Policy reads: each present field with its value, or its name alone. */
+function projection(input, fields) {
+    if (fields.length === 0)
+        return [];
+    if (!isRecord(input))
+        return ['other'];
+    return [
+        'object',
+        ...fields.map((field) => Object.hasOwn(input, field) ? [field, canonical(input[field])] : [field]),
+    ];
+}
+/** Canonical JSON text of a portable value: object keys sorted at every depth. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const object = value;
+        return `{${Object.keys(object)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonical(object[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function isRecord(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input);
+}
+function hex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}

package/dist/execution/invocation/admission/authentication.d.ts

@@ -13,3 +13,5 @@ export type InvocationAuthentication = AnonymousInvocation | AuthenticatedInvoca
  */
 export type InvocationSessions = InvocationAuthentication['graph'];
 export declare function authentication(callable: ResolvedCallable, request: HandlerRequest, domain: Domain, authority: InvocationAuthority): Promise<InvocationAuthentication>;
+/** Verify the credential a call carries and admit the caller it proves, whatever the callable. */
+export declare function credentialAuthentication(request: HandlerRequest, domain: Domain, authority: InvocationAuthority): Promise<AuthenticatedInvocation>;

package/dist/execution/invocation/admission/authentication.js

@@ -5,10 +5,14 @@ import { protocolError } from '../result/index.js';
 import { requireVia } from './authority.js';
 const ANONYMOUS = Object.freeze({ kind: 'anonymous' });
 export async function authentication(callable, request, domain, authority) {
-    const credential = request.credential;
-    if (callable.auth === 'anonymous' && credential === undefined) {
+    if (callable.auth === 'anonymous' && request.credential === undefined) {
         return anonymous(await authority.self({ via: requireVia(request), domain, context: request.context }));
     }
+    return credentialAuthentication(request, domain, authority);
+}
+/** Verify the credential a call carries and admit the caller it proves, whatever the callable. */
+export async function credentialAuthentication(request, domain, authority) {
+    const credential = request.credential;
     if (credential === undefined) {
         throw protocolError('AUTH_MISSING', 'Authentication is required.');
     }

package/dist/execution/invocation/admission/index.d.ts

@@ -1,5 +1,6 @@
+export { ADMISSION_RECALL_TIMEOUT_MS, admissionKey, admissionScope, declaresAdmissionAge, keepAdmission, recallAdmission, type AdmissionPartition, type AdmissionScope, } from './age.js';
 export { authority, requireVia } from './authority.js';
 export type { AuthenticatedInvocation, InvocationAdmissionInput, InvocationAuthenticationInput, InvocationAuthority, InvocationSelfInput, SelfInvocation, } from './authority.js';
-export { authentication, type AnonymousInvocation, type InvocationAuthentication, type InvocationSessions, } from './authentication.js';
+export { authentication, credentialAuthentication, type AnonymousInvocation, type InvocationAuthentication, type InvocationSessions, } from './authentication.js';
 export { input } from './input.js';
-export { target, type InvocationTarget } from './target.js';
+export { admission, target, type Admission, type InvocationTarget } from './target.js';

package/dist/execution/invocation/admission/index.js

@@ -1,4 +1,5 @@
+export { ADMISSION_RECALL_TIMEOUT_MS, admissionKey, admissionScope, declaresAdmissionAge, keepAdmission, recallAdmission, } from './age.js';
 export { authority, requireVia } from './authority.js';
-export { authentication, } from './authentication.js';
+export { authentication, credentialAuthentication, } from './authentication.js';
 export { input } from './input.js';
-export { target } from './target.js';
+export { admission, target } from './target.js';

package/dist/execution/invocation/admission/target.d.ts

@@ -4,5 +4,16 @@ export interface InvocationTarget {
     readonly callable: SemanticKey.Callable;
     readonly receiver?: NodePath;
 }
+/** The source Kernel's answer to `Function.admit`. */
+export interface Admission {
+    readonly target: InvocationTarget;
+    /**
+     * How long, in seconds from when it was asked, this deployment may reuse the admission: the
+     * callable's declared admission age bounded by the Kernel cap. Absent: this call only.
+     */
+    readonly maxAge?: number;
+}
+/** Admit the `Function.admit` answer: the selected target and the admission age it carries. */
+export declare function admission(input: unknown): Admission;
 /** Admit the portable target selected by the execution Identity owner. */
 export declare function target(input: unknown): InvocationTarget;

package/dist/execution/invocation/admission/target.js

@@ -1,11 +1,25 @@
 import { callableAddress, Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import { isAdmissionMaxAge } from '@astrale-os/kernel-dsl/v1/language';
 import { NodePath as acceptNodePath } from '../../../platform/graph/path/index.js';
 import { InvocationDefect } from '../result/index.js';
+/** Admit the `Function.admit` answer: the selected target and the admission age it carries. */
+export function admission(input) {
+    const value = record(input);
+    if (Reflect.ownKeys(value).some((key) => key !== 'callable' && key !== 'receiver' && key !== 'maxAge')) {
+        invalid();
+    }
+    const { maxAge } = value;
+    if (maxAge !== undefined && !isAdmissionMaxAge(maxAge))
+        invalid();
+    const selected = target({
+        callable: value.callable,
+        ...(value.receiver === undefined ? {} : { receiver: value.receiver }),
+    });
+    return Object.freeze({ target: selected, ...(maxAge === undefined ? {} : { maxAge }) });
+}
 /** Admit the portable target selected by the execution Identity owner. */
 export function target(input) {
-    if (input === null || typeof input !== 'object' || Array.isArray(input))
-        invalid();
-    const value = input;
+    const value = record(input);
     if (!Object.hasOwn(value, 'callable') ||
         Reflect.ownKeys(value).some((key) => key !== 'callable' && key !== 'receiver') ||
         typeof value.callable !== 'string') {
@@ -25,6 +39,11 @@ export function target(input) {
     }
     return Object.freeze({ callable, ...(receiver === undefined ? {} : { receiver }) });
 }
+function record(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    return input;
+}
 function invalid() {
     throw new InvocationDefect('INVOCATION_TARGET_INVALID', 'Invocation target is invalid.');
 }

package/dist/execution/invocation/capabilities/bind.d.ts

@@ -0,0 +1,11 @@
+import type { DomainCapabilities } from '../../../application/action/index.js';
+import type { BoundClientSession } from '../../../platform/client/session/index.js';
+import type { Domain } from '../../../platform/schema/index.js';
+import type { InvocationSessions } from '../admission/index.js';
+/**
+ * Bind what code acting under `sessions` holds: self-default Kernel and graph, and dependency
+ * invokers per authority. An Action and a durable Step receive these same capabilities.
+ */
+export declare function bindCapabilities(domain: Domain, sessions: Readonly<Record<'caller' | 'self', BoundClientSession>>): DomainCapabilities;
+export declare function bindCapabilities(domain: Domain, sessions: Readonly<Record<'self', BoundClientSession>>): DomainCapabilities<Domain, 'self'>;
+export declare function bindCapabilities(domain: Domain, sessions: InvocationSessions): DomainCapabilities | DomainCapabilities<Domain, 'self'>;

package/dist/execution/invocation/capabilities/bind.js

@@ -0,0 +1,25 @@
+import { bindMutation } from '../../../application/mutation/execution/executor.js';
+import { bindQuery } from '../../../application/query/execution/executor.js';
+import { bindDependencies } from '../dependency/index.js';
+export function bindCapabilities(domain, sessions) {
+    const graph = bindGraph(sessions, domain);
+    return Object.freeze({
+        kernel: Object.freeze({ ...sessions.self, ...sessions }),
+        dependencies: bindDependencies(domain, sessions),
+        graph,
+        query: graph.self.query,
+        mutate: graph.self.mutate,
+    });
+}
+function bindGraph(sessions, domain) {
+    const bind = (client) => Object.freeze({
+        query: bindQuery(client, domain),
+        mutate: bindMutation(client, domain),
+    });
+    const self = bind(sessions.self);
+    return Object.freeze({
+        ...self,
+        ...('caller' in sessions ? { caller: bind(sessions.caller) } : {}),
+        self,
+    });
+}

package/dist/execution/invocation/capabilities/index.d.ts

@@ -0,0 +1 @@
+export { bindCapabilities } from './bind.js';

package/dist/execution/invocation/capabilities/index.js

@@ -0,0 +1 @@
+export { bindCapabilities } from './bind.js';

package/dist/execution/invocation/dispatch/context.js

@@ -1,10 +1,7 @@
-import { bindMutation } from '../../../application/mutation/execution/executor.js';
-import { bindQuery } from '../../../application/query/execution/executor.js';
-import { bindDependencies } from '../dependency/index.js';
+import { bindCapabilities } from '../capabilities/index.js';
 import { clients } from '../integration/index.js';
 export function context(request, runtime, authentication, self) {
     const sessions = authentication.graph;
-    const graph = bindGraph(sessions, runtime.loaded.domain);
     const execution = Object.freeze({
         signal: request.context.execution.signal,
         deadline: request.context.execution.deadline,
@@ -20,11 +17,7 @@ export function context(request, runtime, authentication, self) {
         input: request.call.input,
         ...(request.context.binary === undefined ? {} : { body: request.context.binary }),
         caller: authentication.caller,
-        kernel: Object.freeze({ ...sessions.self, ...sessions }),
-        dependencies: bindDependencies(runtime.loaded.domain, sessions),
-        graph,
-        query: graph.self.query,
-        mutate: graph.self.mutate,
+        ...bindCapabilities(runtime.loaded.domain, sessions),
         integrations: clients(runtime, request.context, {
             ...sessions,
             ...(authentication.caller.kind !== 'authenticated' ||
@@ -36,15 +29,3 @@ export function context(request, runtime, authentication, self) {
         ...(self === undefined ? {} : { self }),
     });
 }
-function bindGraph(sessions, domain) {
-    const bind = (client) => Object.freeze({
-        query: bindQuery(client, domain),
-        mutate: bindMutation(client, domain),
-    });
-    const self = bind(sessions.self);
-    return Object.freeze({
-        ...self,
-        ...('caller' in sessions ? { caller: bind(sessions.caller) } : {}),
-        self,
-    });
-}

package/dist/execution/invocation/handler.js

@@ -1,5 +1,6 @@
 import { createInlineWorkflowRunner } from '../../application/workflow/runner/index.js';
-import { authority } from './admission/index.js';
+import { deploymentCache } from '../cache/index.js';
+import { authority, declaresAdmissionAge } from './admission/index.js';
 import { invoke } from './invocation.js';
 import { projectError } from './result/index.js';
 /** Compose one ready semantic Handler below Kernel Server transport ownership. */
@@ -8,7 +9,7 @@ export function createHandler(input) {
         invalid();
     if (!Object.hasOwn(input, 'runtime') ||
         !Object.hasOwn(input, 'authority') ||
-        Reflect.ownKeys(input).some((key) => key !== 'runtime' && key !== 'authority' && key !== 'workflows')) {
+        Reflect.ownKeys(input).some((key) => key !== 'runtime' && key !== 'authority' && key !== 'workflows' && key !== 'cache')) {
         invalid();
     }
     const capturedAuthority = authority(input.authority);
@@ -17,6 +18,10 @@ export function createHandler(input) {
         invalid();
     }
     const capturedWorkflows = Object.freeze({ run: workflows.run.bind(workflows) });
+    // A Domain whose callables declare no admission age never reads its cache.
+    const cache = input.cache === undefined || !declaresAdmissionAge(input.runtime.loaded.registry)
+        ? undefined
+        : deploymentCache(input.cache);
     return Object.freeze({
         async dispatch(request) {
             try {
@@ -24,6 +29,7 @@ export function createHandler(input) {
                     runtime: input.runtime,
                     authority: capturedAuthority,
                     workflows: capturedWorkflows,
+                    ...(cache === undefined ? {} : { cache }),
                 });
             }
             catch (cause) {

package/dist/execution/invocation/integration/authentication.d.ts

@@ -1,5 +1,5 @@
-import type { InvocationContext } from '@astrale-os/kernel-server';
 import type { IntegrationAuthentication } from '../../../application/integration/index.js';
 import type { BoundClientSession } from '../../../platform/client/session/index.js';
-/** Capture only self mint, bounded by this invocation's verified credential horizon. */
-export declare function bindIntegrationAuthentication(context: InvocationContext, self: BoundClientSession, expiresAt?: number): IntegrationAuthentication;
+import type { Lifetime } from '../lifecycle/index.js';
+/** Capture only self mint, bounded by its lifetime and the verified credential horizon. */
+export declare function bindIntegrationAuthentication(lifetime: Lifetime, self: BoundClientSession, expiresAt?: number): IntegrationAuthentication;

package/dist/execution/invocation/integration/authentication.js

@@ -3,15 +3,15 @@ import { active } from '../lifecycle/index.js';
 import { protocolError } from '../result/index.js';
 // Match the callback resolver's reserve; a child credential cannot outlive its source.
 const TRANSPORT_RESERVE_SECONDS = 5;
-/** Capture only self mint, bounded by this invocation's verified credential horizon. */
-export function bindIntegrationAuthentication(context, self, expiresAt) {
+/** Capture only self mint, bounded by its lifetime and the verified credential horizon. */
+export function bindIntegrationAuthentication(lifetime, self, expiresAt) {
     if (expiresAt !== undefined && !Number.isFinite(expiresAt)) {
         throw new TypeError('Invalid Integration authentication expiry.');
     }
     const mint = self.auth.mint.bind(self.auth);
     return Object.freeze({
         async mint(input) {
-            active(context);
+            active(lifetime);
             if (input === null || typeof input !== 'object' || Array.isArray(input))
                 invalidInput();
             const keys = Reflect.ownKeys(input);
@@ -25,16 +25,16 @@ export function bindIntegrationAuthentication(context, self, expiresAt) {
                 ttlSeconds < 1 ||
                 ttlSeconds > 60)
                 invalidInput();
-            const horizon = Math.min(context.execution.deadline / 1000, expiresAt ?? Infinity);
+            const horizon = Math.min(lifetime.deadline / 1000, expiresAt ?? Infinity);
             const remaining = Math.floor(horizon) - Math.floor(Date.now() / 1000) - TRANSPORT_RESERVE_SECONDS;
             if (remaining < 1) {
                 throw protocolError('DEADLINE_EXCEEDED', 'Insufficient lifetime for Integration credential.');
             }
             const credential = await mint({ audience, ttlSeconds: Math.min(ttlSeconds, remaining) }, {
-                signal: context.execution.signal,
-                timeoutMs: Math.max(1, context.execution.deadline - Date.now()),
+                signal: lifetime.signal,
+                timeoutMs: Math.max(1, lifetime.deadline - Date.now()),
             });
-            active(context);
+            active(lifetime);
             // Inspect only the result of the trusted Kernel call, not a Provider-supplied token.
             // The reserve is an optimization; this absolute check is the lifetime boundary.
             const expiry = credentials.inspect(credential).claims.exp;

package/dist/execution/invocation/integration/call.js

@@ -6,11 +6,11 @@ export function calls(context, sessions = null) {
     const invoke = sessions?.caller?.invoke.bind(sessions.caller);
     const auth = sessions === null
         ? undefined
-        : bindIntegrationAuthentication(context, sessions.self, sessions.expiresAt);
+        : bindIntegrationAuthentication(context.execution, sessions.self, sessions.expiresAt);
     let sequence = 0;
     return Object.freeze({
         invoke(call) {
-            active(context);
+            active(context.execution);
             sequence += 1;
             return call.attempt({
                 callId: `${prefix}:${sequence}`,

package/dist/execution/invocation/integration/index.d.ts

@@ -1,2 +1,3 @@
+export { bindIntegrationAuthentication } from './authentication.js';
 export { calls } from './call.js';
 export { clients } from './clients.js';

package/dist/execution/invocation/integration/index.js

@@ -1,2 +1,3 @@
+export { bindIntegrationAuthentication } from './authentication.js';
 export { calls } from './call.js';
 export { clients } from './clients.js';

package/dist/execution/invocation/invocation.d.ts

@@ -1,10 +1,16 @@
 import type { HandlerRequest, HandlerResult } from '@astrale-os/kernel-server';
 import type { WorkflowRunner } from '../../application/workflow/runner/index.js';
+import type { DeploymentCache } from '../cache/index.js';
 import type { InitializedRuntime } from '../runtime/index.js';
 import type { InvocationAuthority } from './admission/index.js';
 export interface InvocationInput {
     readonly runtime: InitializedRuntime;
     readonly authority: InvocationAuthority;
     readonly workflows: WorkflowRunner;
+    /**
+     * Where admissions of callables that declare an admission age are kept for the next calls. Absent:
+     * every call is admitted by its source Kernel.
+     */
+    readonly cache?: DeploymentCache;
 }
 export declare function invoke(request: HandlerRequest, inputConfig: InvocationInput): Promise<HandlerResult>;