@astrale-os/kernel-protocol 0.5.0-beta.7 → 0.5.0-beta.71

package/dist/schema/installation/introspection/result.d.ts

@@ -1,34 +1,107 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { introspection } from '@astrale-os/kernel-core/schema';
-import type { bundle } from '@astrale-os/kernel-dsl/v1';
-import type { Ref } from '../../../artifact/index.js';
-import type { Publication } from '../../../publication/index.js';
-import type { PublicationRequirements } from '../../../publication/index.js';
+import type { bundle, Key, Revision } from '@astrale-os/kernel-dsl/v1';
+import type { BuildDigest, ReleaseDigest } from '../../../release/index.js';
+import type { Publication, PublicationRef, PublicationRequirements } from '../../../release/legacy/index.js';
 export type Digest = `sha256:${string}`;
-export type Source = {
-    readonly kind: 'builtin';
-    readonly bundle: Ref;
-} | {
-    readonly kind: 'local';
-    readonly artifact: Ref;
-    readonly bundle: Ref;
-} | {
-    readonly kind: 'remote';
-    readonly publication: Publication;
-};
-export interface Installation {
-    readonly state: 'installed' | 'ready' | 'removing';
-    readonly target: Digest;
-    readonly source: Source;
-    readonly bundle: bundle.Bundle;
-    readonly readiness: Digest | null;
+/** Lightweight proof of one exact ready installed Domain generation. */
+export interface DomainInfo {
+    readonly origin: Key.Origin;
+    readonly revision: Revision;
+    readonly generation: Digest;
+    /**
+     * Installed Publication reference: the pinned document's own for a legacy pin, the reference of
+     * the frozen v3 projection for a v4 pin.
+     *
+     * @deprecated Successor: `DomainInfo.release`, the installed `ReleaseRef`, emitted by the
+     * breaking release (AM-1).
+     */
+    readonly publication: PublicationRef | null;
+    readonly readiness: Digest;
     readonly capabilities: {
         readonly requested: PublicationRequirements['capabilities'];
         readonly materialized: PublicationRequirements['capabilities'];
     };
+    readonly bindings: Publication['bindings'];
+}
+/** Explicit complete Bundle observed coherently with its ready Domain generation. */
+export interface DomainBundle {
+    readonly domain: DomainInfo;
+    readonly bundle: bundle.Bundle;
+}
+/**
+ * How one ready Domain generation binds one dependency of its exact closure: `exact` when the
+ * pinned revision is the one the Kernel serves, `retained` when the Kernel serves another revision
+ * and keeps the pinned one as inactive context admitted by unchanged meaning.
+ */
+export interface DependencyBinding {
+    readonly origin: Key.Origin;
+    readonly pinned: Revision;
+    readonly active: Revision;
+    readonly binding: 'exact' | 'retained';
+}
+/** The origin-ordered dependency bindings observed coherently with a ready Domain generation. */
+export interface DomainDependencies {
+    readonly domain: DomainInfo;
+    readonly dependencies: readonly DependencyBinding[];
+}
+/**
+ * What one installation pins, one meaning per variant: a `DomainRelease` v4 by its release digest
+ * beside the build digest it runs, or a legacy v2/v3 Publication by its strong ETag.
+ */
+export type InstalledPin = ReleasePin | LegacyPin;
+/** A `DomainRelease` v4 pin: its release digest beside the build digest it runs. */
+interface ReleasePin {
+    readonly kind: 'release';
+    readonly release: ReleaseDigest;
+    readonly build: BuildDigest;
+}
+/**
+ * A legacy v2/v3 Publication pin: its document version and strong ETag.
+ *
+ * @deprecated Successor: the `release` pin. Short-term consumer: the installations that still pin
+ * a v2/v3 Publication, such as the astrale Host's v3 installs until Shell is republished as a
+ * release. Deleted, with its codec branch, in the separate breaking release that deletes
+ * `runtime/schema/installation/source/legacy/`, once no installation pins a v2/v3 Publication
+ * (the conditions of `protocol/release/legacy/index.ts`).
+ */
+interface LegacyPin {
+    readonly kind: 'legacy';
+    readonly document: 2 | 3;
+    readonly etag: Digest;
+}
+/**
+ * The issuer of a release one installation replaced, as the Kernel records it: accepted while its
+ * work drains, and listed until a later consented install re-pins or prunes it, drained or not.
+ */
+export interface InFlightIssuer {
+    readonly issuer: IssuerId;
+    /** Pinned document digest of the replaced release. */
+    readonly release: Digest;
+    /** UTC millisecond ISO 8601 instant of the activation commit that replaced it. */
+    readonly replacedAt: string;
+}
+/** One ready installation the Kernel pins to a deployment, as its caller can read it. */
+export interface InstalledRelease {
+    readonly origin: Key.Origin;
+    readonly revision: Revision;
+    /** Issuer of the installation's Domain principal. */
+    readonly issuer: IssuerId;
+    /** The deployment URL, an HTTP(S) origin, the Kernel discovered the pinned document at. */
+    readonly url: string;
+    readonly pin: InstalledPin;
+    /** Issuer-ordered, distinct, never the current issuer. */
+    readonly inFlight: readonly InFlightIssuer[];
 }
-export type ResultFor<Input extends introspection.Introspection> = Pick<Installation, Extract<keyof Input['select'], keyof Installation>> | null;
+export type ResultFor<Input extends introspection.Introspection> = Input extends {
+    readonly kind: 'installed';
+} ? readonly InstalledRelease[] : Input extends {
+    readonly kind: 'bundle';
+} ? DomainBundle : Input extends {
+    readonly kind: 'dependencies';
+} ? DomainDependencies : DomainInfo;
 export interface Limits {
     readonly maximumPublicationBytes: number;
     readonly maximumBundleBytes: number;
 }
-//# sourceMappingURL=result.d.ts.map
+export {};

package/dist/schema/installation/introspection/result.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=result.js.map

package/dist/schema/installation/legacy/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Read-only decoders for the schema evidence of Hosts older than beta.127: MessagePack
+ * installation v1 (`application/vnd.astrale.schema-installation.v1+msgpack`) and introspection v2
+ * (`application/vnd.astrale.schema-introspection.v2+msgpack`). Each decodes its bytes into the same
+ * wire value as the canonical JSON evidence and admits it with the canonical checks, so it returns
+ * exactly the canonical `InstallResult` and introspection results. Nothing here encodes: Servers
+ * emit only the canonical JSON evidence.
+ *
+ * @deprecated Use `installation.decode` / `installation.introspection.decode` with their
+ * `MEDIA_TYPE`, the JSON evidence every Host from beta.127 serves.
+ *
+ * Short-term consumers, all through `@astrale-os/kernel-client` `SchemaApi`, which selects these
+ * decoders by the received media type:
+ * - Admin managing the 1Pact Host (Kernel beta.117) and the astrale Hosts on beta.121 and beta.126
+ *   (`schema.inspect` before every Manager call, child `install`/`inspect`, `bundle` reads);
+ * - the CLI used by 1Pact developers, and `adapter-astrale` 0.5.0-beta.148, which runs
+ *   `astrale introspect` before every 1Pact deploy (`introspect`, `view`,
+ *   `domain install --direct`, cold-cache `call`);
+ * - the Console back-office (`schema.bundle` of every installed Domain);
+ * - SDK Project tooling (`pnpm dev`, the Environment installation reconcile), which runs
+ *   `astrale introspect` and `astrale domain install --direct` through that same CLI against our
+ *   beta.121 and beta.126 Hosts.
+ *
+ * Removal, in a separate breaking release: once no supported Host is older than beta.127 (the
+ * 1Pact Host upgraded; astrale-01, shared-01 and admin-users replaced or upgraded). Then delete, in
+ * the same PR:
+ * - this folder with its tests, golden evidence and laws, its `legacy/` entry in
+ *   `../.spec/layout.ts`, and the `./schema/installation/legacy` subpaths (source and `dist`) of
+ *   `protocol/package.json` with the `schema/installation/legacy/**` include of
+ *   `protocol/tsconfig.json`;
+ * - the legacy media-type branches of `client/schema/schema.ts` and
+ *   `client/schema/introspection.ts`, and `client/schema/__tests__/legacy-evidence.test.ts`;
+ * - the legacy paragraphs of `client/schema/.spec/architecture.md` and
+ *   `../.spec/architecture.md`;
+ * - the package-private exports of `../codec.ts` (`accept`) and `../introspection/codec.ts`
+ *   (`acceptEvidence`, `admitLimits`, `admitRequest`), which return to module scope.
+ */
+export { MEDIA_TYPE, decode } from './installation.js';
+export * as introspection from './introspection.js';

package/dist/schema/installation/legacy/index.js

@@ -0,0 +1,39 @@
+/**
+ * Read-only decoders for the schema evidence of Hosts older than beta.127: MessagePack
+ * installation v1 (`application/vnd.astrale.schema-installation.v1+msgpack`) and introspection v2
+ * (`application/vnd.astrale.schema-introspection.v2+msgpack`). Each decodes its bytes into the same
+ * wire value as the canonical JSON evidence and admits it with the canonical checks, so it returns
+ * exactly the canonical `InstallResult` and introspection results. Nothing here encodes: Servers
+ * emit only the canonical JSON evidence.
+ *
+ * @deprecated Use `installation.decode` / `installation.introspection.decode` with their
+ * `MEDIA_TYPE`, the JSON evidence every Host from beta.127 serves.
+ *
+ * Short-term consumers, all through `@astrale-os/kernel-client` `SchemaApi`, which selects these
+ * decoders by the received media type:
+ * - Admin managing the 1Pact Host (Kernel beta.117) and the astrale Hosts on beta.121 and beta.126
+ *   (`schema.inspect` before every Manager call, child `install`/`inspect`, `bundle` reads);
+ * - the CLI used by 1Pact developers, and `adapter-astrale` 0.5.0-beta.148, which runs
+ *   `astrale introspect` before every 1Pact deploy (`introspect`, `view`,
+ *   `domain install --direct`, cold-cache `call`);
+ * - the Console back-office (`schema.bundle` of every installed Domain);
+ * - SDK Project tooling (`pnpm dev`, the Environment installation reconcile), which runs
+ *   `astrale introspect` and `astrale domain install --direct` through that same CLI against our
+ *   beta.121 and beta.126 Hosts.
+ *
+ * Removal, in a separate breaking release: once no supported Host is older than beta.127 (the
+ * 1Pact Host upgraded; astrale-01, shared-01 and admin-users replaced or upgraded). Then delete, in
+ * the same PR:
+ * - this folder with its tests, golden evidence and laws, its `legacy/` entry in
+ *   `../.spec/layout.ts`, and the `./schema/installation/legacy` subpaths (source and `dist`) of
+ *   `protocol/package.json` with the `schema/installation/legacy/**` include of
+ *   `protocol/tsconfig.json`;
+ * - the legacy media-type branches of `client/schema/schema.ts` and
+ *   `client/schema/introspection.ts`, and `client/schema/__tests__/legacy-evidence.test.ts`;
+ * - the legacy paragraphs of `client/schema/.spec/architecture.md` and
+ *   `../.spec/architecture.md`;
+ * - the package-private exports of `../codec.ts` (`accept`) and `../introspection/codec.ts`
+ *   (`acceptEvidence`, `admitLimits`, `admitRequest`), which return to module scope.
+ */
+export { MEDIA_TYPE, decode } from './installation.js';
+export * as introspection from './introspection.js';

package/dist/schema/installation/legacy/installation.d.ts

@@ -0,0 +1,9 @@
+import type { InstallResult } from '../result.js';
+/** @deprecated Read-only: Hosts older than beta.127 serve this; current Hosts serve `installation.MEDIA_TYPE`. */
+export declare const MEDIA_TYPE: 'application/vnd.astrale.schema-installation.v1+msgpack';
+/**
+ * Decode version-one (MessagePack) installation evidence into the canonical result.
+ *
+ * @deprecated Read-only; use `installation.decode` with `installation.MEDIA_TYPE`.
+ */
+export declare function decode(bytes: Uint8Array, maximumBytes: number): Promise<InstallResult>;

package/dist/schema/installation/legacy/installation.js

@@ -0,0 +1,28 @@
+import { accept as acceptValue, defaultLimits } from '@astrale-os/kernel-dsl/value';
+import { accept } from '../codec.js';
+import { decode as decodeMessagePack } from './msgpack.js';
+/** @deprecated Read-only: Hosts older than beta.127 serve this; current Hosts serve `installation.MEDIA_TYPE`. */
+export const MEDIA_TYPE = 'application/vnd.astrale.schema-installation.v1+msgpack';
+/**
+ * Decode version-one (MessagePack) installation evidence into the canonical result.
+ *
+ * @deprecated Read-only; use `installation.decode` with `installation.MEDIA_TYPE`.
+ */
+export async function decode(bytes, maximumBytes) {
+    if (!(bytes instanceof Uint8Array) ||
+        !Number.isSafeInteger(maximumBytes) ||
+        maximumBytes < 1 ||
+        bytes.byteLength > maximumBytes) {
+        throw new TypeError('Schema installation evidence is invalid or exceeds its bound.');
+    }
+    let value;
+    try {
+        value = acceptValue(decodeMessagePack(bytes, defaultLimits.maxDepth), {
+            limits: { maxBytes: maximumBytes },
+        });
+    }
+    catch (cause) {
+        throw new TypeError('Schema installation evidence is malformed.', { cause });
+    }
+    return accept(value);
+}

package/dist/schema/installation/legacy/introspection.d.ts

@@ -0,0 +1,10 @@
+import type { introspection } from '@astrale-os/kernel-core/schema';
+import type { Limits, ResultFor } from '../introspection/result.js';
+/** @deprecated Read-only: Hosts older than beta.127 serve this; current Hosts serve `introspection.MEDIA_TYPE`. */
+export declare const MEDIA_TYPE: 'application/vnd.astrale.schema-introspection.v2+msgpack';
+/**
+ * Decode version-two (MessagePack) introspection evidence into the canonical result.
+ *
+ * @deprecated Read-only; use `introspection.decode` with `introspection.MEDIA_TYPE`.
+ */
+export declare function decode<Input extends introspection.Introspection>(input: Input, bytes: Uint8Array, limits: Limits): Promise<ResultFor<Input>>;

package/dist/schema/installation/legacy/introspection.js

@@ -0,0 +1,70 @@
+import { accept as acceptValue, defaultLimits } from '@astrale-os/kernel-dsl/value';
+import { acceptEvidence, admitLimits, admitRequest } from '../introspection/codec.js';
+import { decode as decodeMessagePack } from './msgpack.js';
+/** @deprecated Read-only: Hosts older than beta.127 serve this; current Hosts serve `introspection.MEDIA_TYPE`. */
+export const MEDIA_TYPE = 'application/vnd.astrale.schema-introspection.v2+msgpack';
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+/**
+ * Decode version-two (MessagePack) introspection evidence into the canonical result.
+ *
+ * @deprecated Read-only; use `introspection.decode` with `introspection.MEDIA_TYPE`.
+ */
+export async function decode(input, bytes, limits) {
+    const request = admitRequest(input);
+    if (!(bytes instanceof Uint8Array))
+        invalid('Schema introspection evidence must be binary.');
+    admitLimits(request, limits);
+    // Version two carried the Bundle as raw bytes: no escaping allowance.
+    const maximumEvidenceBytes = limits.maximumPublicationBytes +
+        (request.kind === 'bundle' ? limits.maximumBundleBytes : 0) +
+        4_096;
+    if (bytes.byteLength > maximumEvidenceBytes) {
+        invalid('Schema introspection evidence exceeds its declared bounds.');
+    }
+    let wire;
+    try {
+        wire = decodeMessagePack(bytes, defaultLimits.maxDepth);
+    }
+    catch (cause) {
+        throw new TypeError('Schema introspection evidence is malformed.', { cause });
+    }
+    if (request.kind === 'bundle')
+        wire = bundleAsText(wire);
+    let decoded;
+    try {
+        decoded = acceptValue(wire, {
+            limits: {
+                maxBytes: maximumEvidenceBytes,
+                ...(request.kind === 'bundle' ? { maxStringBytes: limits.maximumBundleBytes } : {}),
+            },
+        });
+    }
+    catch (cause) {
+        throw new TypeError('Schema introspection evidence is malformed.', { cause });
+    }
+    return acceptEvidence(request, decoded, limits);
+}
+/**
+ * Version two carried the Bundle as the UTF-8 bytes of its canonical JSON; the current wire value
+ * carries that JSON as text. Translate only that field; every other check stays canonical.
+ */
+function bundleAsText(wire) {
+    if (wire === null || typeof wire !== 'object' || Array.isArray(wire))
+        return wire;
+    if (!Object.hasOwn(wire, 'bundle'))
+        return wire;
+    const { bundle } = wire;
+    if (!(bundle instanceof Uint8Array))
+        invalid('Bundle evidence is invalid or exceeds its bound.');
+    let text;
+    try {
+        text = utf8.decode(bundle);
+    }
+    catch (cause) {
+        throw new TypeError('Installed Domain Bundle is invalid.', { cause });
+    }
+    return { ...wire, bundle: text };
+}
+function invalid(message) {
+    throw new TypeError(message);
+}

package/dist/schema/installation/legacy/msgpack.d.ts

@@ -0,0 +1 @@
+export declare function decode(bytes: Uint8Array, maximumDepth: number): unknown;

package/dist/schema/installation/legacy/msgpack.js

@@ -0,0 +1,143 @@
+/**
+ * Frozen, read-only MessagePack decoder for the schema evidence of Hosts older than beta.127.
+ *
+ * It reads the families that msgpackr 2.0.5 `pack` (`useRecords: false`) wrote for that evidence:
+ * nil, booleans, integers, floats, strings, binary, arrays and string-keyed maps. Extension types
+ * (msgpackr records and `undefined`, timestamps, structured clones) never occur in it and are
+ * rejected, as are truncated input, trailing bytes, invalid UTF-8, non-string or duplicate map keys,
+ * integers outside the safe range, and nesting deeper than `maximumDepth`. It never encodes.
+ */
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+export function decode(bytes, maximumDepth) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let position = 0;
+    const take = (length) => {
+        if (length > bytes.byteLength - position)
+            malformed('is truncated');
+        const start = position;
+        position += length;
+        return start;
+    };
+    const u8 = () => bytes[take(1)];
+    const u16 = () => view.getUint16(take(2));
+    const u32 = () => view.getUint32(take(4));
+    const text = (length) => {
+        const start = take(length);
+        return utf8.decode(bytes.subarray(start, start + length));
+    };
+    const binary = (length) => {
+        const start = take(length);
+        return bytes.slice(start, start + length);
+    };
+    const entries = (count, width) => {
+        // Every entry occupies at least one byte per item: refuse counts the input cannot hold.
+        if (count * width > bytes.byteLength - position)
+            malformed('declares more entries than it holds');
+    };
+    const nested = (depth) => {
+        if (depth >= maximumDepth)
+            malformed(`nests deeper than ${maximumDepth} containers`);
+        return depth + 1;
+    };
+    const array = (count, depth) => {
+        entries(count, 1);
+        const output = [];
+        for (let index = 0; index < count; index += 1)
+            output.push(value(depth));
+        return output;
+    };
+    const map = (count, depth) => {
+        entries(count, 2);
+        const output = {};
+        for (let index = 0; index < count; index += 1) {
+            const key = value(depth);
+            if (typeof key !== 'string')
+                malformed('has a non-string map key');
+            if (Object.hasOwn(output, key))
+                malformed('has a duplicate map key');
+            Object.defineProperty(output, key, {
+                value: value(depth),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+        return output;
+    };
+    const integer = (input) => {
+        const output = Number(input);
+        if (!Number.isSafeInteger(output))
+            malformed('holds an integer outside the safe range');
+        return output;
+    };
+    function value(depth) {
+        const head = u8();
+        if (head <= 0x7f)
+            return head;
+        if (head >= 0xe0)
+            return head - 0x100;
+        if (head <= 0x8f)
+            return map(head & 0x0f, nested(depth));
+        if (head <= 0x9f)
+            return array(head & 0x0f, nested(depth));
+        if (head <= 0xbf)
+            return text(head & 0x1f);
+        switch (head) {
+            case 0xc0:
+                return null;
+            case 0xc2:
+                return false;
+            case 0xc3:
+                return true;
+            case 0xc4:
+                return binary(u8());
+            case 0xc5:
+                return binary(u16());
+            case 0xc6:
+                return binary(u32());
+            case 0xca:
+                return view.getFloat32(take(4));
+            case 0xcb:
+                return view.getFloat64(take(8));
+            case 0xcc:
+                return u8();
+            case 0xcd:
+                return u16();
+            case 0xce:
+                return u32();
+            case 0xcf:
+                return integer(view.getBigUint64(take(8)));
+            case 0xd0:
+                return view.getInt8(take(1));
+            case 0xd1:
+                return view.getInt16(take(2));
+            case 0xd2:
+                return view.getInt32(take(4));
+            case 0xd3:
+                return integer(view.getBigInt64(take(8)));
+            case 0xd9:
+                return text(u8());
+            case 0xda:
+                return text(u16());
+            case 0xdb:
+                return text(u32());
+            case 0xdc:
+                return array(u16(), nested(depth));
+            case 0xdd:
+                return array(u32(), nested(depth));
+            case 0xde:
+                return map(u16(), nested(depth));
+            case 0xdf:
+                return map(u32(), nested(depth));
+            default:
+                return malformed(`uses the unsupported type 0x${head.toString(16)}`);
+        }
+    }
+    const output = value(0);
+    if (position !== bytes.byteLength)
+        malformed('has trailing bytes');
+    return output;
+}
+function malformed(reason) {
+    throw new TypeError(`MessagePack evidence ${reason}.`);
+}

package/dist/schema/installation/result.d.ts

@@ -0,0 +1,9 @@
+import type { InstallReceipt } from '@astrale-os/kernel-core/schema/kernel/syscalls/contracts';
+import type { DomainInfo } from './introspection/index.js';
+export type InstallResult = {
+    readonly changed: true;
+    readonly receipt: InstallReceipt;
+} | {
+    readonly changed: false;
+    readonly domains: readonly [DomainInfo, ...DomainInfo[]];
+};

package/dist/schema/installation/result.js

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