@astrale-os/sdk 0.5.0-beta.2 → 0.5.0-beta.21

package/dist/deployment/release/invocation.js

@@ -0,0 +1,33 @@
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import * as routes from '@astrale-os/kernel-protocol/routes';
+const PREFIX = '/releases/';
+const SUFFIX = '/invoke';
+/** Stable invocation path for one exact Schema revision. */
+export function invocationPath(revision) {
+    if (!patterns.revision.test(revision))
+        throw new TypeError('Schema revision is invalid.');
+    return `${PREFIX}${encodeURIComponent(revision)}${SUFFIX}`;
+}
+/** Read an exact revision endpoint; unrelated paths are not release requests. */
+export function requestedRevision(pathname) {
+    if (!pathname.startsWith(PREFIX) || !pathname.endsWith(SUFFIX))
+        return undefined;
+    const encoded = pathname.slice(PREFIX.length, -SUFFIX.length);
+    let revision;
+    try {
+        revision = decodeURIComponent(encoded);
+    }
+    catch {
+        return undefined;
+    }
+    return patterns.revision.test(revision) && invocationPath(revision) === pathname
+        ? revision
+        : undefined;
+}
+/** Reserved response for an exact Schema revision that is no longer available. */
+export function releaseUnavailable() {
+    return new Response(null, {
+        status: routes.HTTP_ROUTE_RELEASE_UNAVAILABLE_STATUS,
+        headers: routes.releaseUnavailableHeaders(),
+    });
+}

package/dist/deployment/release/publication/callables.d.ts

@@ -0,0 +1,4 @@
+import * as publication from '@astrale-os/kernel-protocol/publication';
+import type { Build } from '../../build/index.js';
+import type { Addressing } from '../addressing.js';
+export declare function callables(build: Build, addressing: Addressing): readonly publication.CallableBinding[];

package/dist/deployment/release/publication/callables.js

@@ -0,0 +1,8 @@
+import * as publication from '@astrale-os/kernel-protocol/publication';
+import { invocationPath } from '../invocation.js';
+export function callables(build, addressing) {
+    const endpoint = publication.acceptInvocationEndpoints({
+        http: new URL(invocationPath(build.schema.compiled.root.revision), addressing.issuer).href,
+    });
+    return Object.freeze(build.callables.map((callable) => Object.freeze({ callable, endpoint })));
+}

package/dist/deployment/release/publication/index.d.ts

@@ -0,0 +1,6 @@
+export { callables } from './callables.js';
+export { manifest } from './manifest.js';
+export { requirements } from './requirements.js';
+export { routes } from './routes.js';
+export { BUNDLE_PATH, seal, type SealedPublication } from './seal.js';
+export { views } from './views.js';

package/dist/deployment/release/publication/index.js

@@ -0,0 +1,6 @@
+export { callables } from './callables.js';
+export { manifest } from './manifest.js';
+export { requirements } from './requirements.js';
+export { routes } from './routes.js';
+export { BUNDLE_PATH, seal } from './seal.js';
+export { views } from './views.js';

package/dist/deployment/release/publication/manifest.d.ts

@@ -0,0 +1,3 @@
+import type * as publication from '@astrale-os/kernel-protocol/publication';
+import type { Build } from '../../build/index.js';
+export declare function manifest(build: Build): publication.Manifest | undefined;

package/dist/deployment/release/publication/manifest.js

@@ -0,0 +1,5 @@
+export function manifest(build) {
+    return build.frontend === undefined
+        ? undefined
+        : Object.freeze({ entrypoint: build.frontend.entrypoint });
+}

package/dist/deployment/release/publication/requirements.d.ts

@@ -0,0 +1,3 @@
+import type * as publication from '@astrale-os/kernel-protocol/publication';
+import type { Build } from '../../build/index.js';
+export declare function requirements(build: Build): publication.PublicationRequirements;

package/dist/deployment/release/publication/requirements.js

@@ -0,0 +1,3 @@
+export function requirements(build) {
+    return build.requirements;
+}

package/dist/deployment/release/publication/routes.d.ts

@@ -0,0 +1,4 @@
+import * as protocolRoutes from '@astrale-os/kernel-protocol/routes';
+import type { Build } from '../../build/index.js';
+import type { Addressing } from '../addressing.js';
+export declare function routes(build: Build, addressing: Addressing): ReturnType<typeof protocolRoutes.place>;

package/dist/deployment/release/publication/routes.js

@@ -0,0 +1,4 @@
+import * as protocolRoutes from '@astrale-os/kernel-protocol/routes';
+export function routes(build, addressing) {
+    return protocolRoutes.place(build.routes, addressing.issuer);
+}

package/dist/deployment/release/publication/seal.d.ts

@@ -0,0 +1,11 @@
+import * as publication from '@astrale-os/kernel-protocol/publication';
+import * as protocolRoutes from '@astrale-os/kernel-protocol/routes';
+import type { Build } from '../../build/index.js';
+import type { Addressing } from '../addressing.js';
+export declare const BUNDLE_PATH: '/.well-known/astrale/domain.bundle.json';
+export declare const DELIVERY_PATH: '/install';
+export interface SealedPublication {
+    readonly publication: publication.Publication;
+    readonly routes: protocolRoutes.Table;
+}
+export declare function seal(build: Build, addressing: Addressing): SealedPublication;

package/dist/deployment/release/publication/seal.js

@@ -0,0 +1,40 @@
+import { load as loadCompiledSchema } from '@astrale-os/kernel-dsl/v1/compiled/loader';
+import * as publication from '@astrale-os/kernel-protocol/publication';
+import * as protocolRoutes from '@astrale-os/kernel-protocol/routes';
+import { callables } from './callables.js';
+import { manifest } from './manifest.js';
+import { requirements } from './requirements.js';
+import { routes } from './routes.js';
+import { views } from './views.js';
+export const BUNDLE_PATH = '/.well-known/astrale/domain.bundle.json';
+export const DELIVERY_PATH = '/install';
+export function seal(build, addressing) {
+    const root = build.schema.compiled.root;
+    const selectedManifest = manifest(build);
+    const sealed = publication.seal({
+        format: 'astrale.domain.publication',
+        version: 2,
+        origin: root.origin,
+        identity: { issuer: addressing.issuer, subject: root.origin },
+        schema: {
+            revision: root.revision,
+            bundle: {
+                href: new URL(BUNDLE_PATH, addressing.issuer).href,
+                ref: build.schema.bundle.ref,
+            },
+        },
+        requirements: requirements(build),
+        ...(selectedManifest === undefined ? {} : { manifest: selectedManifest }),
+        bindings: {
+            callables: callables(build, addressing),
+            views: views(build, addressing),
+        },
+        delivery: publication.placeDelivery({ path: DELIVERY_PATH, authentication: { kind: 'public' } }, addressing.issuer, new URL(BUNDLE_PATH, addressing.issuer).href),
+        routes: routes(build, addressing),
+    });
+    const domain = loadCompiledSchema(build.schema.compiled);
+    return Object.freeze({
+        publication: sealed,
+        routes: protocolRoutes.bind(build.routes, sealed, domain),
+    });
+}

package/dist/deployment/release/publication/views.d.ts

@@ -0,0 +1,4 @@
+import type * as publication from '@astrale-os/kernel-protocol/publication';
+import type { Build } from '../../build/index.js';
+import type { Addressing } from '../addressing.js';
+export declare function views(build: Build, addressing: Addressing): readonly publication.ViewBinding[];

package/dist/deployment/release/publication/views.js

@@ -0,0 +1,12 @@
+export function views(build, addressing) {
+    if (build.frontend === undefined)
+        return Object.freeze([]);
+    const base = build.frontend.source.kind === 'external'
+        ? `${build.frontend.source.origin}/`
+        : `${addressing.issuer.replace(/\/+$/u, '')}/`;
+    return Object.freeze(build.frontend.routes.map((route) => Object.freeze({
+        view: route.view,
+        href: new URL(route.path.replace(/^\//u, ''), base).href,
+        handshake: route.handshake,
+    })));
+}

package/dist/deployment/release/release.d.ts

@@ -0,0 +1,11 @@
+import type * as publication from '@astrale-os/kernel-protocol/publication';
+import type * as routes from '@astrale-os/kernel-protocol/routes';
+import type { Build } from '../build/index.js';
+import type { Addressing } from './addressing.js';
+export interface Release<BuildValue extends Build = Build> {
+    readonly kind: 'release';
+    readonly build: BuildValue;
+    readonly addressing: Addressing;
+    readonly publication: publication.Publication;
+    readonly routes: routes.Table;
+}

package/dist/deployment/release/release.js

@@ -0,0 +1 @@
+export {};

package/dist/deployment/release/runtime.d.ts

@@ -0,0 +1,3 @@
+export { assemble } from './assemble.js';
+export { addressing } from './addressing.js';
+export { releaseUnavailable, requestedRevision } from './invocation.js';

package/dist/deployment/release/runtime.js

@@ -0,0 +1,3 @@
+export { assemble } from './assemble.js';
+export { addressing } from './addressing.js';
+export { releaseUnavailable, requestedRevision } from './invocation.js';

package/dist/deployment/runtime/admission.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedRuntimeReference } from './resolve.js';
+/** Prove that a resolved module exports the exact Runtime captured by an Application. */
+export declare function admit<RuntimeValue extends object>(application: {
+    readonly runtime: RuntimeValue;
+}, resolved: ResolvedRuntimeReference): RuntimeValue;

package/dist/deployment/runtime/admission.js

@@ -0,0 +1,11 @@
+import { isResolvedRuntimeReference } from './resolve.js';
+/** Prove that a resolved module exports the exact Runtime captured by an Application. */
+export function admit(application, resolved) {
+    if (!isResolvedRuntimeReference(resolved)) {
+        throw new TypeError('Resolved Runtime reference is not admitted.');
+    }
+    if (resolved.runtime !== application.runtime) {
+        throw new TypeError('Runtime module default export differs from the Application Runtime.');
+    }
+    return application.runtime;
+}

package/dist/deployment/runtime/index.d.ts

@@ -0,0 +1,3 @@
+export { admit } from './admission.js';
+export { isRuntimeReference, runtime, type RuntimeReference } from './reference.js';
+export { isResolvedRuntimeReference, resolve, type ResolvedRuntimeReference, type RuntimeModuleLoader, } from './resolve.js';

package/dist/deployment/runtime/index.js

@@ -0,0 +1,3 @@
+export { admit } from './admission.js';
+export { isRuntimeReference, runtime } from './reference.js';
+export { isResolvedRuntimeReference, resolve, } from './resolve.js';

package/dist/deployment/runtime/reference.d.ts

@@ -0,0 +1,7 @@
+export interface RuntimeReference {
+    readonly kind: 'runtime-reference';
+    readonly path: string;
+}
+/** Capture one stable Runtime module coordinate relative to the deployment configuration. */
+export declare function runtime(path: string): RuntimeReference;
+export declare function isRuntimeReference(input: unknown): input is RuntimeReference;

package/dist/deployment/runtime/reference.js

@@ -0,0 +1,16 @@
+const references = new WeakSet();
+/** Capture one stable Runtime module coordinate relative to the deployment configuration. */
+export function runtime(path) {
+    if (typeof path !== 'string' ||
+        path.length === 0 ||
+        path.trim() !== path ||
+        path.includes('\0')) {
+        throw new TypeError('Runtime path must be a non-empty stable module coordinate.');
+    }
+    const reference = Object.freeze({ kind: 'runtime-reference', path });
+    references.add(reference);
+    return reference;
+}
+export function isRuntimeReference(input) {
+    return input !== null && typeof input === 'object' && references.has(input);
+}

package/dist/deployment/runtime/resolve.d.ts

@@ -0,0 +1,10 @@
+import type { Runtime } from '../../application/runtime/index.js';
+import type { RuntimeReference } from './reference.js';
+export type RuntimeModuleLoader = (path: string) => unknown | Promise<unknown>;
+export interface ResolvedRuntimeReference {
+    readonly reference: RuntimeReference;
+    readonly runtime: Runtime;
+}
+/** Load and admit the one default Runtime exported by a referenced module. */
+export declare function resolve(reference: RuntimeReference, load: RuntimeModuleLoader): Promise<ResolvedRuntimeReference>;
+export declare function isResolvedRuntimeReference(input: unknown): input is ResolvedRuntimeReference;

package/dist/deployment/runtime/resolve.js

@@ -0,0 +1,29 @@
+import { isRuntime } from '../../application/runtime/index.js';
+import { isRuntimeReference } from './reference.js';
+const resolvedReferences = new WeakSet();
+/** Load and admit the one default Runtime exported by a referenced module. */
+export async function resolve(reference, load) {
+    if (!isRuntimeReference(reference)) {
+        throw new TypeError('Runtime reference must be created by runtime(path).');
+    }
+    if (typeof load !== 'function')
+        throw new TypeError('Runtime module loader must be a function.');
+    const loaded = await load(reference.path);
+    if (loaded === null ||
+        typeof loaded !== 'object' ||
+        Array.isArray(loaded) ||
+        !Object.hasOwn(loaded, 'default') ||
+        Object.keys(loaded).some((key) => key !== 'default')) {
+        throw new TypeError('Runtime module must export exactly one default Runtime.');
+    }
+    const runtime = Reflect.get(loaded, 'default');
+    if (!isRuntime(runtime)) {
+        throw new TypeError('Runtime module default export is not an admitted Runtime.');
+    }
+    const resolved = Object.freeze({ reference, runtime });
+    resolvedReferences.add(resolved);
+    return resolved;
+}
+export function isResolvedRuntimeReference(input) {
+    return input !== null && typeof input === 'object' && resolvedReferences.has(input);
+}

package/dist/deployment/verify/index.d.ts

@@ -0,0 +1,3 @@
+export { preflight as verifyPreflight } from './preflight/index.js';
+export type { PreflightInput } from './preflight/index.js';
+export { readiness as verifyReadiness, verifyDeployment } from './readiness/index.js';

package/dist/deployment/verify/index.js

@@ -0,0 +1,2 @@
+export { preflight as verifyPreflight } from './preflight/index.js';
+export { readiness as verifyReadiness, verifyDeployment } from './readiness/index.js';

package/dist/deployment/verify/preflight/artifact.d.ts

@@ -0,0 +1,6 @@
+import type { ArtifactSource, PreparedArtifact } from '../../adapter/prepare/index.js';
+import type { Build } from '../../build/index.js';
+import type { ResolvedRuntimeReference } from '../../runtime/index.js';
+/** Detach preparation output and bind it to the exact Build and resolved Runtime identity. */
+export declare function artifact<const BuildValue extends Build>(build: BuildValue, runtime: ResolvedRuntimeReference, source: ArtifactSource): PreparedArtifact<BuildValue>;
+export declare function isPreparedArtifact(input: unknown): input is PreparedArtifact;

package/dist/deployment/verify/preflight/artifact.js

@@ -0,0 +1,122 @@
+import { identify } from '@astrale-os/kernel-protocol/artifact';
+import { isAddressing } from '../../release/index.js';
+import { admit as admitRuntime } from '../../runtime/index.js';
+const MEDIA_TYPE = 'application/vnd.astrale.prepared-artifact+octet-stream;v=1';
+const admittedArtifacts = new WeakSet();
+/** Detach preparation output and bind it to the exact Build and resolved Runtime identity. */
+export function artifact(build, runtime, source) {
+    admitRuntime({ runtime: build.runtime }, runtime);
+    const admitted = admitSource(source);
+    const digest = identify(evidenceBytes(build, admitted), MEDIA_TYPE).digest;
+    const files = Object.freeze(admitted.files.map(prepareFile));
+    const prepared = Object.freeze({
+        kind: 'prepared-artifact',
+        build,
+        digest,
+        entrypoint: admitted.entrypoint,
+        files,
+        addressing: admitted.addressing,
+    });
+    admittedArtifacts.add(prepared);
+    return prepared;
+}
+function prepareFile(file) {
+    const content = new Uint8Array(file.content);
+    return Object.freeze({ path: file.path, bytes: () => new Uint8Array(content) });
+}
+export function isPreparedArtifact(input) {
+    return input !== null && typeof input === 'object' && admittedArtifacts.has(input);
+}
+function admitSource(source) {
+    if (source === null || typeof source !== 'object' || Array.isArray(source))
+        invalid();
+    if (Reflect.ownKeys(source).some((key) => key !== 'entrypoint' && key !== 'files' && key !== 'addressing')) {
+        invalid();
+    }
+    const entrypoint = path(source.entrypoint, 'Artifact entrypoint');
+    if (!Array.isArray(source.files) || source.files.length === 0) {
+        throw new TypeError('Artifact files must be a non-empty array.');
+    }
+    const paths = new Set();
+    const files = source.files.map((file, index) => {
+        if (file === null || typeof file !== 'object' || Array.isArray(file))
+            invalid();
+        if (Reflect.ownKeys(file).some((key) => key !== 'path' && key !== 'content') ||
+            !(file.content instanceof Uint8Array)) {
+            invalid();
+        }
+        const selected = path(file.path, `Artifact file ${index}`);
+        if (paths.has(selected))
+            throw new TypeError(`Artifact file ${selected} is duplicated.`);
+        paths.add(selected);
+        return Object.freeze({ path: selected, content: new Uint8Array(file.content) });
+    });
+    files.sort((left, right) => compare(left.path, right.path));
+    if (!paths.has(entrypoint))
+        throw new TypeError('Artifact entrypoint file is absent.');
+    const addressing = admitPlan(source.addressing);
+    return Object.freeze({ entrypoint, files: Object.freeze(files), addressing });
+}
+function admitPlan(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    if (input.kind === 'configured') {
+        if (Reflect.ownKeys(input).some((key) => key !== 'kind' && key !== 'addressing'))
+            invalid();
+        if (!isAddressing(input.addressing)) {
+            throw new TypeError('Configured artifact Addressing is not admitted.');
+        }
+        return Object.freeze({ kind: 'configured', addressing: input.addressing });
+    }
+    if (input.kind === 'provider-assigned') {
+        if (Reflect.ownKeys(input).some((key) => key !== 'kind' && key !== 'claim'))
+            invalid();
+        if (typeof input.claim !== 'string' ||
+            input.claim.length === 0 ||
+            input.claim.trim() !== input.claim) {
+            throw new TypeError('Provider-assigned Addressing claim must be a non-empty stable string.');
+        }
+        return Object.freeze({ kind: 'provider-assigned', claim: input.claim });
+    }
+    return invalid();
+}
+function evidenceBytes(build, source) {
+    const encoder = new TextEncoder();
+    const chunks = [
+        encoder.encode(JSON.stringify({
+            origin: build.schema.compiled.root.origin,
+            revision: build.schema.compiled.root.revision,
+            bundle: build.schema.bundle.ref.digest,
+            entrypoint: source.entrypoint,
+            addressing: source.addressing.kind === 'configured'
+                ? { kind: 'configured', issuer: source.addressing.addressing.issuer }
+                : source.addressing,
+        })),
+    ];
+    for (const file of source.files) {
+        chunks.push(encoder.encode(`\0${file.path}\0${file.content.byteLength}\0`), file.content);
+    }
+    const bytes = new Uint8Array(chunks.reduce((size, chunk) => size + chunk.byteLength, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function path(input, label) {
+    if (typeof input !== 'string' ||
+        input.length === 0 ||
+        input.startsWith('/') ||
+        input.includes('\\') ||
+        input.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new TypeError(`${label} must be a contained relative POSIX path.`);
+    }
+    return input;
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalid() {
+    throw new TypeError('Artifact source is invalid.');
+}

package/dist/deployment/verify/preflight/build.d.ts

@@ -0,0 +1,2 @@
+import type { Build } from '../../build/index.js';
+export declare function build<BuildValue extends Build>(input: BuildValue): BuildValue;

package/dist/deployment/verify/preflight/build.js

@@ -0,0 +1,6 @@
+import { isBuild } from '../../build/index.js';
+export function build(input) {
+    if (!isBuild(input))
+        throw new TypeError('Preflight requires an admitted Build.');
+    return input;
+}

package/dist/deployment/verify/preflight/index.d.ts

@@ -0,0 +1,13 @@
+import type { ArtifactSource, PreparedArtifact } from '../../adapter/prepare/index.js';
+import type { Build } from '../../build/index.js';
+import type { ResolvedRuntimeReference } from '../../runtime/index.js';
+export { artifact, isPreparedArtifact } from './artifact.js';
+export { build } from './build.js';
+export { publication } from './publication.js';
+export interface PreflightInput<BuildValue extends Build = Build> {
+    readonly build: BuildValue;
+    readonly runtime: ResolvedRuntimeReference;
+    readonly source: ArtifactSource;
+}
+/** Admit exact deployment material before any provider mutation. */
+export declare function preflight<const BuildValue extends Build>(input: PreflightInput<BuildValue>): PreparedArtifact<BuildValue>;

package/dist/deployment/verify/preflight/index.js

@@ -0,0 +1,13 @@
+import { artifact } from './artifact.js';
+import { build as verifyBuild } from './build.js';
+import { publication as verifyPublication } from './publication.js';
+export { artifact, isPreparedArtifact } from './artifact.js';
+export { build } from './build.js';
+export { publication } from './publication.js';
+/** Admit exact deployment material before any provider mutation. */
+export function preflight(input) {
+    verifyBuild(input.build);
+    const prepared = artifact(input.build, input.runtime, input.source);
+    verifyPublication(prepared);
+    return prepared;
+}

package/dist/deployment/verify/preflight/publication.d.ts

@@ -0,0 +1,4 @@
+import type { PreparedArtifact } from '../../adapter/prepare/index.js';
+import type { Release } from '../../release/index.js';
+/** Verify locally assemblable Publication evidence before any provider mutation. */
+export declare function publication(artifact: PreparedArtifact): Release | undefined;

package/dist/deployment/verify/preflight/publication.js

@@ -0,0 +1,14 @@
+import { load as loadCompiledSchema } from '@astrale-os/kernel-dsl/v1/compiled/loader';
+import { publication as protocolPublication, routes } from '@astrale-os/kernel-protocol';
+import { assemble } from '../../release/index.js';
+/** Verify locally assemblable Publication evidence before any provider mutation. */
+export function publication(artifact) {
+    if (artifact.addressing.kind !== 'configured')
+        return undefined;
+    const release = assemble(artifact.build, artifact.addressing.addressing);
+    const admitted = protocolPublication.accept(release.publication);
+    protocolPublication.verifyBundleBytes(admitted, artifact.build.schema.bundle.bytes());
+    const domain = loadCompiledSchema(artifact.build.schema.compiled);
+    routes.verifyTable(release.routes, admitted, domain);
+    return release;
+}

package/dist/deployment/verify/readiness/deployment.d.ts

@@ -0,0 +1,3 @@
+import type { DeployResult, PreparedArtifact } from '../../adapter/index.js';
+/** Admit adapter-reported progress without changing its mutation knowledge. */
+export declare function verifyDeployment(artifact: PreparedArtifact, input: DeployResult): DeployResult;