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

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

@@ -0,0 +1,56 @@
+import type { DeploymentRecordV1 } from '../../address/index.js';
+/** What one operation knows it changed at a provider. */
+export type MutationKnowledge<Evidence = unknown> = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'partial';
+    readonly evidence?: Evidence;
+} | {
+    readonly kind: 'applied';
+    readonly evidence: Evidence;
+} | {
+    readonly kind: 'unknown';
+};
+/**
+ * How a deploy left the Environment's secrets on the deployment it made or reused: `bound` to a
+ * new deployment, or `updated` or left `unchanged` in place on the reused one.
+ */
+export type DeploymentSecretsState = 'bound' | 'updated' | 'unchanged';
+/**
+ * The immutable deployment of one release, ready at its URL.
+ *
+ * - `created`: a new deployment now serves the release, and the Environment's secrets are `bound`
+ *   to it.
+ * - `reused`: the deployment of this exact release (same label, build and configuration) already
+ *   existed; its own declared secrets were `updated` or left `unchanged` in place.
+ */
+export interface ReadyReleaseDeployResult {
+    readonly status: 'ready';
+    readonly state: 'created' | 'reused';
+    /** The record the deployment declares, as the host stored it. */
+    readonly record: DeploymentRecordV1;
+    /** The deployment URL, which is also the issuer of the release it serves. */
+    readonly url: string;
+    readonly secrets: {
+        readonly state: DeploymentSecretsState;
+    };
+}
+/**
+ * Where a deploy of one release stopped:
+ * - `prerequisite`: before any effect at the host (a missing tool, credential or hosting answer);
+ * - `provider`: at the host, while it created or reused the deployment;
+ * - `readiness`: the deployment exists but did not serve its release before the deadline.
+ */
+export type ReleaseDeploymentPhase = 'prerequisite' | 'provider' | 'readiness';
+/**
+ * A deploy of one release that did not reach a ready deployment. Rerunning the same deploy
+ * converges: the deployment's label is its content, so a partial or applied deployment is reused.
+ */
+export interface FailedReleaseDeployResult {
+    readonly status: 'failed';
+    readonly phase: ReleaseDeploymentPhase;
+    /** What the host may now hold of the deployment. */
+    readonly provider: MutationKnowledge;
+    readonly error: Error;
+}
+export type ReleaseDeployResult = ReadyReleaseDeployResult | FailedReleaseDeployResult;

package/dist/deployment/adapter/release/result.js

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

package/dist/deployment/address/configuration.d.ts

@@ -0,0 +1,83 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+export declare const FROZEN_CONFIGURATION_FORMAT = "astrale.deployment.configuration";
+export declare const FROZEN_CONFIGURATION_VERSION = 1;
+/**
+ * What a deploy freezes into one deployment beside its build: the author's plain variables and the
+ * execution settings, defaults resolved, the durable Workflow options it declares, and the services
+ * and dispatch namespaces it binds. It names the secrets a deployment binds, never their values,
+ * and leaves out what the host derives (the deployment URL, the build digest, the signing key). A
+ * changed variable, setting or binding is another configuration, so another address; a rotated
+ * secret is not.
+ *
+ * Its admission is canonical form only. Whether a Worker can run under it stays with the host that
+ * binds it: `encodeWorkerSettings` (`@astrale-os/adapter-cloudflare/worker`) refuses settings past
+ * the Worker bounds when the host writes `ASTRALE_SETTINGS`, before anything is uploaded, and the
+ * host's binding namespace admits the binding names.
+ */
+export interface FrozenConfigurationV1 {
+    readonly format: typeof FROZEN_CONFIGURATION_FORMAT;
+    readonly version: typeof FROZEN_CONFIGURATION_VERSION;
+    /** The author's plain variables, never secrets. */
+    readonly vars: Readonly<Record<string, string>>;
+    readonly settings: {
+        readonly maximumRequestBytes: number;
+        readonly invocationTimeoutMs: number;
+        readonly tokenExchange: false | {
+            readonly maximumLifetimeSeconds: number;
+        };
+        /** The durable Workflow options the Environment declares; absent when it declares none. */
+        readonly durableOptions?: FrozenDurableOptions;
+    };
+    readonly runtime: {
+        readonly compatibilityDate: string;
+        /** Sorted, unique. */
+        readonly compatibilityFlags: readonly string[];
+    };
+    readonly bindings: {
+        /** Sorted by name, unique; never the `ROUTER` binding, which `router` describes. */
+        readonly services: readonly {
+            readonly name: string;
+            readonly service: string;
+        }[];
+        /**
+         * Dispatch namespaces the deployment binds, sorted by binding name, unique; empty when it binds
+         * none. A binding name is a Worker binding name other than `ROUTER`, a namespace a Cloudflare
+         * dispatch namespace name. Which namespaces a deployment may bind is the host's to decide.
+         */
+        readonly dispatchNamespaces: readonly {
+            readonly name: string;
+            readonly namespace: string;
+        }[];
+        /** Names of the secrets the deployment binds, sorted, unique. */
+        readonly secrets: readonly string[];
+    };
+    readonly router: false | {
+        readonly service: string;
+        readonly hostSuffix: string;
+        readonly minLabels: number;
+    };
+}
+/**
+ * The durable Workflow options of one deployment, as declared: every field optional, each a
+ * positive integer. The SDK's durable serving bounds and defaults them when the Worker runs.
+ */
+export interface FrozenDurableOptions {
+    readonly retentionMs?: number;
+    readonly retry?: {
+        readonly initialIntervalMs?: number;
+        readonly maxAttempts?: number;
+        readonly maxIntervalMs?: number;
+    };
+    readonly stepTimeoutMs?: number;
+}
+/** A configuration before its canonical order: lists in any order, no format header. */
+export type FrozenConfigurationInput = Omit<FrozenConfigurationV1, 'format' | 'version'>;
+/** Freeze one deployment configuration in the one canonical order its digest is taken in. */
+export declare function frozenConfiguration(input: FrozenConfigurationInput): FrozenConfigurationV1;
+/**
+ * `sha256` of the canonical JSON (RFC 8785) of one exact, canonical frozen configuration. A
+ * deployment record keeps it whole; the deployment address keeps 80 bits of it with the build.
+ * It refuses a configuration that is not canonical, and checks nothing past that: a configuration
+ * it digests may still be one no Worker runs under (see `FrozenConfigurationV1`).
+ */
+export declare function configurationDigest(configuration: FrozenConfigurationV1): Digest;

package/dist/deployment/address/configuration.js

@@ -0,0 +1,262 @@
+import { json } from '@astrale-os/kernel-dsl/value';
+import { identify } from '@astrale-os/kernel-protocol/artifact';
+export const FROZEN_CONFIGURATION_FORMAT = 'astrale.deployment.configuration';
+export const FROZEN_CONFIGURATION_VERSION = 1;
+/** Service binding through which an immutable deployment reaches the instance router. */
+const ROUTER_BINDING = 'ROUTER';
+const MEDIA_TYPE = 'application/vnd.astrale.deployment-configuration+json;v=1';
+const COMPATIBILITY_DATE = /^\d{4}-\d{2}-\d{2}$/u;
+/** A Cloudflare Worker binding name. */
+const BINDING_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/u;
+/** A Cloudflare dispatch namespace name. */
+const NAMESPACE_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u;
+/** Freeze one deployment configuration in the one canonical order its digest is taken in. */
+export function frozenConfiguration(input) {
+    if (input === null || typeof input !== 'object')
+        invalid();
+    const { settings, runtime, bindings } = input;
+    if (settings === null || typeof settings !== 'object')
+        invalid();
+    if (runtime === null || typeof runtime !== 'object')
+        invalid();
+    if (bindings === null || typeof bindings !== 'object')
+        invalid();
+    if (!Array.isArray(runtime.compatibilityFlags))
+        invalid();
+    if (!Array.isArray(bindings.services) ||
+        !Array.isArray(bindings.dispatchNamespaces) ||
+        !Array.isArray(bindings.secrets)) {
+        invalid();
+    }
+    return admit({
+        format: FROZEN_CONFIGURATION_FORMAT,
+        version: FROZEN_CONFIGURATION_VERSION,
+        vars: input.vars,
+        settings: declaredSettings(settings),
+        runtime: {
+            compatibilityDate: runtime.compatibilityDate,
+            compatibilityFlags: [...runtime.compatibilityFlags].sort(compare),
+        },
+        bindings: {
+            services: [...bindings.services].sort(byName),
+            dispatchNamespaces: [...bindings.dispatchNamespaces].sort(byName),
+            secrets: [...bindings.secrets].sort(compare),
+        },
+        router: input.router,
+    });
+}
+/**
+ * `sha256` of the canonical JSON (RFC 8785) of one exact, canonical frozen configuration. A
+ * deployment record keeps it whole; the deployment address keeps 80 bits of it with the build.
+ * It refuses a configuration that is not canonical, and checks nothing past that: a configuration
+ * it digests may still be one no Worker runs under (see `FrozenConfigurationV1`).
+ */
+export function configurationDigest(configuration) {
+    return identify(json.encode(admit(configuration)), MEDIA_TYPE).digest;
+}
+function admit(input) {
+    exact(input, ['format', 'version', 'vars', 'settings', 'runtime', 'bindings', 'router']);
+    if (input.format !== FROZEN_CONFIGURATION_FORMAT ||
+        input.version !== FROZEN_CONFIGURATION_VERSION) {
+        invalid();
+    }
+    const vars = variables(input.vars);
+    exact(input.settings, ['maximumRequestBytes', 'invocationTimeoutMs', 'tokenExchange'], ['durableOptions']);
+    const { tokenExchange } = input.settings;
+    if (tokenExchange !== false)
+        exact(tokenExchange, ['maximumLifetimeSeconds']);
+    exact(input.runtime, ['compatibilityDate', 'compatibilityFlags']);
+    const { compatibilityDate } = input.runtime;
+    if (!isDate(compatibilityDate))
+        invalid();
+    exact(input.bindings, ['services', 'dispatchNamespaces', 'secrets']);
+    if (!Array.isArray(input.bindings.services))
+        invalid();
+    if (!Array.isArray(input.bindings.dispatchNamespaces))
+        invalid();
+    const services = input.bindings.services.map((binding) => {
+        exact(binding, ['name', 'service']);
+        if (binding.name === ROUTER_BINDING) {
+            throw new TypeError('Frozen configuration service bindings never include ROUTER.');
+        }
+        return Object.freeze({
+            name: stable(binding.name, 'Service binding name'),
+            service: stable(binding.service, 'Service binding target'),
+        });
+    });
+    ordered(services.map((binding) => binding.name), 'Service bindings');
+    const dispatchNamespaces = input.bindings.dispatchNamespaces.map((binding) => {
+        exact(binding, ['name', 'namespace']);
+        if (binding.name === ROUTER_BINDING) {
+            throw new TypeError('Frozen configuration dispatch namespace bindings never include ROUTER.');
+        }
+        if (typeof binding.name !== 'string' || !BINDING_NAME.test(binding.name)) {
+            throw new TypeError('Dispatch namespace binding name must be a Worker binding name.');
+        }
+        if (typeof binding.namespace !== 'string' || !NAMESPACE_NAME.test(binding.namespace)) {
+            throw new TypeError('Dispatch namespace must be a Cloudflare dispatch namespace name.');
+        }
+        return Object.freeze({ name: binding.name, namespace: binding.namespace });
+    });
+    ordered(dispatchNamespaces.map((binding) => binding.name), 'Dispatch namespace bindings');
+    const secrets = names(input.bindings.secrets, 'Secret names');
+    const router = input.router === false ? false : routerOf(input.router);
+    const bound = [
+        ...Object.keys(vars),
+        ...services.map((binding) => binding.name),
+        ...dispatchNamespaces.map((binding) => binding.name),
+        ...secrets,
+        ...(router === false ? [] : [ROUTER_BINDING]),
+    ];
+    if (new Set(bound).size !== bound.length) {
+        throw new TypeError('Frozen configuration binding names must be unique.');
+    }
+    return Object.freeze({
+        format: FROZEN_CONFIGURATION_FORMAT,
+        version: FROZEN_CONFIGURATION_VERSION,
+        vars,
+        settings: Object.freeze({
+            maximumRequestBytes: positive(input.settings.maximumRequestBytes),
+            invocationTimeoutMs: positive(input.settings.invocationTimeoutMs),
+            tokenExchange: tokenExchange === false
+                ? false
+                : Object.freeze({
+                    maximumLifetimeSeconds: positive(tokenExchange.maximumLifetimeSeconds),
+                }),
+            ...(Object.hasOwn(input.settings, 'durableOptions')
+                ? { durableOptions: durableOptionsOf(input.settings.durableOptions) }
+                : {}),
+        }),
+        runtime: Object.freeze({
+            compatibilityDate,
+            compatibilityFlags: names(input.runtime.compatibilityFlags, 'Compatibility flags'),
+        }),
+        bindings: Object.freeze({
+            services: Object.freeze(services),
+            dispatchNamespaces: Object.freeze(dispatchNamespaces),
+            secrets,
+        }),
+        router,
+    });
+}
+/** A calendar date written `YYYY-MM-DD`, as a Worker compatibility date is. */
+function isDate(input) {
+    if (typeof input !== 'string' || !COMPATIBILITY_DATE.test(input))
+        return false;
+    const time = Date.parse(`${input}T00:00:00Z`);
+    return !Number.isNaN(time) && new Date(time).toISOString().slice(0, 10) === input;
+}
+function variables(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    const entries = Reflect.ownKeys(input).map((name) => {
+        if (typeof name !== 'string')
+            invalid();
+        const value = input[name];
+        if (typeof value !== 'string')
+            invalid();
+        return [stable(name, 'Variable name'), value];
+    });
+    return Object.freeze(Object.fromEntries(entries));
+}
+/** The settings as written, without a `durableOptions` or durable field left `undefined`. */
+function declaredSettings(settings) {
+    const { durableOptions, ...rest } = settings;
+    if (durableOptions === undefined)
+        return rest;
+    const { retry, ...options } = defined(durableOptions);
+    return {
+        ...rest,
+        durableOptions: {
+            ...options,
+            ...(retry === undefined ? {} : { retry: defined(retry) }),
+        },
+    };
+}
+function defined(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+/** The declared durable options in their canonical form: sorted keys, positive integers. */
+function durableOptionsOf(input) {
+    exact(input, [], ['retentionMs', 'retry', 'stepTimeoutMs']);
+    const options = input;
+    let retry;
+    if (Object.hasOwn(options, 'retry')) {
+        exact(options.retry, [], ['initialIntervalMs', 'maxAttempts', 'maxIntervalMs']);
+        const value = options.retry;
+        retry = Object.freeze({
+            ...optional(value, 'initialIntervalMs'),
+            ...optional(value, 'maxAttempts'),
+            ...optional(value, 'maxIntervalMs'),
+        });
+    }
+    return Object.freeze({
+        ...optional(options, 'retentionMs'),
+        ...(retry === undefined ? {} : { retry }),
+        ...optional(options, 'stepTimeoutMs'),
+    });
+}
+function optional(input, key) {
+    return Object.hasOwn(input, key)
+        ? { [key]: positive(input[key]) }
+        : {};
+}
+function routerOf(input) {
+    exact(input, ['service', 'hostSuffix', 'minLabels']);
+    const router = input;
+    if (typeof router.hostSuffix !== 'string')
+        invalid();
+    if (!Number.isSafeInteger(router.minLabels) || router.minLabels < 0)
+        invalid();
+    return Object.freeze({
+        service: stable(router.service, 'Router service'),
+        hostSuffix: router.hostSuffix,
+        minLabels: router.minLabels,
+    });
+}
+function names(input, label) {
+    if (!Array.isArray(input))
+        invalid();
+    const values = input.map((value) => stable(value, label));
+    ordered(values, label);
+    return Object.freeze(values);
+}
+function ordered(values, label) {
+    for (let index = 1; index < values.length; index += 1) {
+        if (compare(values[index - 1], values[index]) >= 0) {
+            throw new TypeError(`${label} must be unique and sorted.`);
+        }
+    }
+}
+/** Exactly `keys`, plus any of `optional`, and nothing else. */
+function exact(input, keys, optionalKeys = []) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        Reflect.ownKeys(input).some((key) => typeof key !== 'string' || (!keys.includes(key) && !optionalKeys.includes(key))) ||
+        keys.some((key) => !Object.hasOwn(input, key))) {
+        invalid();
+    }
+}
+function positive(input) {
+    if (!Number.isSafeInteger(input) || input < 1)
+        invalid();
+    return input;
+}
+function stable(input, label) {
+    if (typeof input !== 'string' || input.length === 0 || input.trim() !== input) {
+        throw new TypeError(`${label} must be non-empty stable text.`);
+    }
+    return input;
+}
+function byName(left, right) {
+    return compare(String(left?.name), String(right?.name));
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalid() {
+    throw new TypeError('Frozen configuration is invalid.');
+}

package/dist/deployment/address/fingerprint.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The first 80 bits of `sha256(utf8(parts[0]) ‖ 0x00 ‖ utf8(parts[1]) ‖ …)` as 16 characters of
+ * RFC 4648 base32, lower case and unpadded. Callers admit every part first, so no part holds 0x00.
+ */
+export declare function first80(...parts: readonly string[]): string;

package/dist/deployment/address/fingerprint.js

@@ -0,0 +1,27 @@
+import { identify } from '@astrale-os/kernel-protocol/artifact';
+const encoder = new TextEncoder();
+const ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+const PREIMAGE_MEDIA_TYPE = 'application/octet-stream';
+/**
+ * The first 80 bits of `sha256(utf8(parts[0]) ‖ 0x00 ‖ utf8(parts[1]) ‖ …)` as 16 characters of
+ * RFC 4648 base32, lower case and unpadded. Callers admit every part first, so no part holds 0x00.
+ */
+export function first80(...parts) {
+    const encoded = parts.map((part) => encoder.encode(part));
+    const preimage = new Uint8Array(encoded.reduce((size, part) => size + part.byteLength, encoded.length - 1));
+    let offset = 0;
+    for (const [index, part] of encoded.entries()) {
+        if (index > 0)
+            offset += 1;
+        preimage.set(part, offset);
+        offset += part.byteLength;
+    }
+    // `sha256:` then 20 hexadecimal digits: the first 10 bytes of the hash.
+    let bits = BigInt(`0x${identify(preimage, PREIMAGE_MEDIA_TYPE).digest.slice(7, 27)}`);
+    let text = '';
+    for (let index = 0; index < 16; index += 1) {
+        text = ALPHABET[Number(bits & 31n)] + text;
+        bits >>= 5n;
+    }
+    return text;
+}

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

@@ -0,0 +1,5 @@
+export { configurationDigest, frozenConfiguration, FROZEN_CONFIGURATION_FORMAT, FROZEN_CONFIGURATION_VERSION, type FrozenConfigurationInput, type FrozenDurableOptions, type FrozenConfigurationV1, } from './configuration.js';
+export { DEPLOYMENT_LABEL, deploymentContent, deploymentLabel, deploymentUrl, parseDeploymentLabel, type DeploymentLabelParts, } from './label.js';
+export { deploymentLine, lineFingerprint, readablePart, type DeploymentLineInput, type LineAddressing, } from './line.js';
+export { acceptDeploymentRecord, DEPLOYMENT_RECORD_FORMAT, DEPLOYMENT_RECORD_VERSION, type DeploymentCommitV1, type DeploymentRecordV1, } from './record.js';
+export { acceptPlatformDeploymentSummary, encodePlatformDeploymentSummary, PLATFORM_OWNER, type DeploymentSummaryV1, type PlatformDeploymentSummaryV1, } from './summary.js';

package/dist/deployment/address/index.js

@@ -0,0 +1,5 @@
+export { configurationDigest, frozenConfiguration, FROZEN_CONFIGURATION_FORMAT, FROZEN_CONFIGURATION_VERSION, } from './configuration.js';
+export { DEPLOYMENT_LABEL, deploymentContent, deploymentLabel, deploymentUrl, parseDeploymentLabel, } from './label.js';
+export { deploymentLine, lineFingerprint, readablePart, } from './line.js';
+export { acceptDeploymentRecord, DEPLOYMENT_RECORD_FORMAT, DEPLOYMENT_RECORD_VERSION, } from './record.js';
+export { acceptPlatformDeploymentSummary, encodePlatformDeploymentSummary, PLATFORM_OWNER, } from './summary.js';

package/dist/deployment/address/label.d.ts

@@ -0,0 +1,42 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+import type { BuildDigest } from '../build/manifest.js';
+import type { FrozenConfigurationV1 } from './configuration.js';
+/**
+ * Every deployment label: an optional readable part, the 16-character line fingerprint and the
+ * 16-character content, both lower-case base32. A legacy provider name (a UUID, a stable Worker
+ * name) never matches, so one dispatcher tells the two apart by the label alone. The pattern
+ * bounds no length; `parseDeploymentLabel` also refuses a label longer than the 57 characters
+ * `deploymentLabel` can produce.
+ */
+export declare const DEPLOYMENT_LABEL: RegExp;
+export interface DeploymentLabelParts {
+    readonly line: string;
+    readonly fingerprint: string;
+    readonly content: string;
+}
+/**
+ * The 16-character content of one deployment: the first 80 bits of
+ * `sha256(utf8(buildDigest) ‖ 0x00 ‖ utf8(configurationDigest(configuration)))` in lower-case
+ * base32. It covers the build and the frozen configuration, never a secret: one address serves
+ * one release, and a changed variable gives another address.
+ */
+export declare function deploymentContent(build: BuildDigest, configuration: FrozenConfigurationV1): string;
+/** The content of a build and a full configuration digest, as a deployment record holds them. */
+export declare function contentOf(build: BuildDigest, configuration: Digest): string;
+/**
+ * The DNS label of one deployment, `<line>-<content>`: at most 57 characters, below the 63 of a
+ * DNS label.
+ */
+export declare function deploymentLabel(line: string, content: string): string;
+/**
+ * The URL of one deployment under the host's routing domain. It is the issuer of the release the
+ * deployment serves, and no other deployment ever answers at it. The label is admitted as
+ * `parseDeploymentLabel` admits it, so its host never holds a label longer than 57 characters.
+ */
+export declare function deploymentUrl(label: string, routingDomain: string): string;
+/**
+ * Split a deployment label into its line, the line fingerprint and its content. It admits exactly
+ * the labels `deploymentLabel` produces: `DEPLOYMENT_LABEL`, and at most 57 characters, so a line
+ * of at most 40.
+ */
+export declare function parseDeploymentLabel(label: string): DeploymentLabelParts;

package/dist/deployment/address/label.js

@@ -0,0 +1,80 @@
+import { configurationDigest } from './configuration.js';
+import { first80 } from './fingerprint.js';
+/**
+ * Every deployment label: an optional readable part, the 16-character line fingerprint and the
+ * 16-character content, both lower-case base32. A legacy provider name (a UUID, a stable Worker
+ * name) never matches, so one dispatcher tells the two apart by the label alone. The pattern
+ * bounds no length; `parseDeploymentLabel` also refuses a label longer than the 57 characters
+ * `deploymentLabel` can produce.
+ */
+export const DEPLOYMENT_LABEL = /^(?:[a-z0-9]+(?:-[a-z0-9]+)*-)?[a-z2-7]{16}-[a-z2-7]{16}$/u;
+const LINE = /^(?:[a-z0-9]+(?:-[a-z0-9]+)*-)?[a-z2-7]{16}$/u;
+const CONTENT = /^[a-z2-7]{16}$/u;
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+const DNS_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/u;
+const MAXIMUM_LINE_LENGTH = 40;
+/** A line, a dash and the content: below the 63 characters of a DNS label. */
+const MAXIMUM_LABEL_LENGTH = MAXIMUM_LINE_LENGTH + 17;
+const MAXIMUM_HOST_LENGTH = 253;
+/**
+ * The 16-character content of one deployment: the first 80 bits of
+ * `sha256(utf8(buildDigest) ‖ 0x00 ‖ utf8(configurationDigest(configuration)))` in lower-case
+ * base32. It covers the build and the frozen configuration, never a secret: one address serves
+ * one release, and a changed variable gives another address.
+ */
+export function deploymentContent(build, configuration) {
+    return contentOf(build, configurationDigest(configuration));
+}
+/** The content of a build and a full configuration digest, as a deployment record holds them. */
+export function contentOf(build, configuration) {
+    return first80(digest(build, 'Build digest'), digest(configuration, 'Configuration digest'));
+}
+/**
+ * The DNS label of one deployment, `<line>-<content>`: at most 57 characters, below the 63 of a
+ * DNS label.
+ */
+export function deploymentLabel(line, content) {
+    if (typeof line !== 'string' || line.length > MAXIMUM_LINE_LENGTH || !LINE.test(line)) {
+        throw new TypeError('Deployment line is invalid.');
+    }
+    if (typeof content !== 'string' || !CONTENT.test(content)) {
+        throw new TypeError('Deployment content is invalid.');
+    }
+    return `${line}-${content}`;
+}
+/**
+ * The URL of one deployment under the host's routing domain. It is the issuer of the release the
+ * deployment serves, and no other deployment ever answers at it. The label is admitted as
+ * `parseDeploymentLabel` admits it, so its host never holds a label longer than 57 characters.
+ */
+export function deploymentUrl(label, routingDomain) {
+    parseDeploymentLabel(label);
+    if (typeof routingDomain !== 'string' || !DNS_NAME.test(routingDomain)) {
+        throw new TypeError('Deployment routing domain must be a lower-case DNS name.');
+    }
+    const host = `${label}.${routingDomain}`;
+    if (host.length > MAXIMUM_HOST_LENGTH) {
+        throw new TypeError('Deployment host exceeds the length of a DNS name.');
+    }
+    return `https://${host}`;
+}
+/**
+ * Split a deployment label into its line, the line fingerprint and its content. It admits exactly
+ * the labels `deploymentLabel` produces: `DEPLOYMENT_LABEL`, and at most 57 characters, so a line
+ * of at most 40.
+ */
+export function parseDeploymentLabel(label) {
+    if (typeof label !== 'string' ||
+        label.length > MAXIMUM_LABEL_LENGTH ||
+        !DEPLOYMENT_LABEL.test(label)) {
+        throw new TypeError('Deployment label is invalid.');
+    }
+    const line = label.slice(0, -17);
+    return Object.freeze({ line, fingerprint: line.slice(-16), content: label.slice(-16) });
+}
+function digest(input, label) {
+    if (typeof input !== 'string' || !DIGEST.test(input)) {
+        throw new TypeError(`${label} is invalid.`);
+    }
+    return input;
+}

package/dist/deployment/address/line.d.ts

@@ -0,0 +1,29 @@
+/**
+ * How a line reads. Platform lines are `readable` (`agencies-staging-354iwg4avm6wdmrs`); tenant
+ * lines are `opaque`, their fingerprint alone, so a hosted address says nothing of whose code it
+ * serves. Both derive from the same inputs, never from stored state.
+ */
+export type LineAddressing = 'readable' | 'opaque';
+export interface DeploymentLineInput {
+    readonly origin: string;
+    readonly environment: string;
+    readonly addressing: LineAddressing;
+}
+/**
+ * The 16-character fingerprint of the line of `(origin, environment)`: the first 80 bits of
+ * `sha256(utf8(origin) ‖ 0x00 ‖ utf8(environment))` in lower-case base32. It alone makes a line
+ * unique; the readable part in front of it is cosmetic.
+ */
+export declare function lineFingerprint(origin: string, environment: string): string;
+/**
+ * The cosmetic part of a readable line: the first label of the origin (12 characters at most) and
+ * the environment (10 at most), lower case, each run of characters outside `[a-z0-9]` replaced by
+ * one dash and dashes removed at both edges. Neither part is ever empty: an origin label and an
+ * environment name both start with a letter or a digit.
+ */
+export declare function readablePart(origin: string, environment: string): string;
+/**
+ * The line every deployment of one origin in one environment shares: `<readable>-<fingerprint>`
+ * when readable, the fingerprint alone when opaque. At most 40 characters.
+ */
+export declare function deploymentLine(input: DeploymentLineInput): string;

package/dist/deployment/address/line.js

@@ -0,0 +1,53 @@
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import { ENVIRONMENT_NAME } from '../environment.js';
+import { first80 } from './fingerprint.js';
+/**
+ * The 16-character fingerprint of the line of `(origin, environment)`: the first 80 bits of
+ * `sha256(utf8(origin) ‖ 0x00 ‖ utf8(environment))` in lower-case base32. It alone makes a line
+ * unique; the readable part in front of it is cosmetic.
+ */
+export function lineFingerprint(origin, environment) {
+    admitLine(origin, environment);
+    return first80(origin, environment);
+}
+/**
+ * The cosmetic part of a readable line: the first label of the origin (12 characters at most) and
+ * the environment (10 at most), lower case, each run of characters outside `[a-z0-9]` replaced by
+ * one dash and dashes removed at both edges. Neither part is ever empty: an origin label and an
+ * environment name both start with a letter or a digit.
+ */
+export function readablePart(origin, environment) {
+    admitLine(origin, environment);
+    return `${normalize(origin.split('.')[0], 12)}-${normalize(environment, 10)}`;
+}
+/**
+ * The line every deployment of one origin in one environment shares: `<readable>-<fingerprint>`
+ * when readable, the fingerprint alone when opaque. At most 40 characters.
+ */
+export function deploymentLine(input) {
+    if (input === null || typeof input !== 'object') {
+        throw new TypeError('Deployment line input is invalid.');
+    }
+    const fingerprint = lineFingerprint(input.origin, input.environment);
+    if (input.addressing === 'opaque')
+        return fingerprint;
+    if (input.addressing !== 'readable') {
+        throw new TypeError('Deployment line addressing must be readable or opaque.');
+    }
+    return `${readablePart(input.origin, input.environment)}-${fingerprint}`;
+}
+function admitLine(origin, environment) {
+    if (typeof origin !== 'string' || !patterns.origin.test(origin)) {
+        throw new TypeError('Deployment origin must be a Domain origin.');
+    }
+    if (typeof environment !== 'string' || !ENVIRONMENT_NAME.test(environment)) {
+        throw new TypeError('Deployment environment must be a project environment name.');
+    }
+}
+function normalize(input, length) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '-')
+        .slice(0, length)
+        .replace(/^-+|-+$/gu, '');
+}