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

package/dist/tooling/cli/deploy-result.d.ts

@@ -0,0 +1,85 @@
+import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { ReleaseDigest } from '@astrale-os/kernel-protocol/release';
+import type { DeploymentCommitV1 } from '../../deployment/address/index.js';
+import type { BuildDigest, DeploymentSecretsState, ReadyReleaseDeployResult, Release } from '../../deployment/index.js';
+export type { DeploymentSecretsState } from '../../deployment/index.js';
+/**
+ * `astrale-domain deploy <environment> --json` on stdout: the one deployment the deploy made or
+ * reused, which CI installs by its URL. Progress and warnings go to stderr. It names no instance
+ * and no version: a deploy numbers nothing and installs nothing.
+ */
+export interface DeployResultV1 {
+    readonly format: 'astrale.deploy-result';
+    readonly version: 1;
+    readonly origin: string;
+    readonly environment: string;
+    /**
+     * The URL `astrale domain install <url>` takes: an immutable deployment's URL, which is also its
+     * issuer, or the public URL of a stable target.
+     */
+    readonly url: string;
+    /**
+     * The digest of the `DomainRelease` v4 the deployment serves at `release.json`. `null` for a
+     * stable target, which serves a v3 Publication and no release.
+     */
+    readonly release: {
+        readonly digest: ReleaseDigest;
+    } | null;
+    /**
+     * The build digest of the code the deployment runs, as `astrale-domain build` prints it. `null`
+     * for a stable target, which never serves a build digest.
+     */
+    readonly build: {
+        readonly digest: BuildDigest;
+    } | null;
+    readonly schema: {
+        readonly revision: Revision;
+    };
+    readonly deployment: {
+        /** `<adapter name>@<adapter version>` */
+        readonly adapter: string;
+        /**
+         * The provider script that serves this deployment: an immutable deployment's label, which is
+         * also the first label of its URL. `null` for a stable target, whose legacy adapter operations
+         * never report the script they replace.
+         */
+        readonly script: string | null;
+        /**
+         * `created`: a new immutable deployment. `reused`: the immutable deployment of this exact
+         * release already existed. `replaced`: a stable target now runs this code in place of what it
+         * ran, if anything (the legacy direct-mode path cannot tell a first deploy from a later one);
+         * only that path replaces.
+         */
+        readonly state: 'created' | 'reused' | 'replaced';
+    };
+    /**
+     * Immutable deployments only: the environment's current secrets were `bound` to a new
+     * deployment, or `updated` or left `unchanged` in place on the reused one. A deploy never writes
+     * the secrets of any other deployment.
+     */
+    readonly secrets?: {
+        readonly state: DeploymentSecretsState;
+    };
+    /**
+     * The commit the deployment was built from, as its deployment record declares it: the commit of
+     * the deploy that created it. A reused deployment keeps its record, so this can be an earlier
+     * commit than the one the deploy ran from; the label covers the release, never the commit.
+     */
+    readonly commit: DeploymentCommitV1 | null;
+}
+/**
+ * The deploy result of one immutable deployment, from the ready result of the adapter's
+ * `deployRelease`. Its release, build, Schema revision and URL are those the SDK sealed before
+ * deploying; the deployment record the adapter returned must declare exactly that release at that
+ * URL, so the result never names a release the deployment does not serve. Its commit is the
+ * record's, which a reused deployment kept from the deploy that created it.
+ */
+export declare function deployResult(input: {
+    readonly environment: string;
+    readonly adapter: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly release: Release;
+    readonly deployment: ReadyReleaseDeployResult;
+}): DeployResultV1;

package/dist/tooling/cli/deploy-result.js

@@ -0,0 +1,64 @@
+import { acceptDeploymentRecord } from '../../deployment/address/index.js';
+import { addressing, isRelease } from '../../deployment/index.js';
+const SECRETS_BY_STATE = Object.freeze({
+    created: Object.freeze(['bound']),
+    reused: Object.freeze(['updated', 'unchanged']),
+});
+/**
+ * The deploy result of one immutable deployment, from the ready result of the adapter's
+ * `deployRelease`. Its release, build, Schema revision and URL are those the SDK sealed before
+ * deploying; the deployment record the adapter returned must declare exactly that release at that
+ * URL, so the result never names a release the deployment does not serve. Its commit is the
+ * record's, which a reused deployment kept from the deploy that created it.
+ */
+export function deployResult(input) {
+    const { release, deployment } = input;
+    if (!isRelease(release))
+        throw new TypeError('Deploy result requires a sealed Release.');
+    if (deployment.status !== 'ready') {
+        throw new TypeError('Deploy result requires the ready result of deployRelease.');
+    }
+    const record = acceptDeploymentRecord(deployment.record);
+    const { document } = release;
+    expectSame('origin', record.origin, document.origin);
+    expectSame('environment', record.environment, input.environment);
+    expectSame('release digest', record.releaseDigest, document.digest);
+    expectSame('build digest', record.buildDigest, release.buildDigest);
+    expectSame('Schema revision', record.schemaRevision, document.schema.revision);
+    const url = addressing(deployment.url).issuer;
+    expectSame('URL', url, release.url);
+    if (new URL(url).hostname.split('.')[0] !== record.providerScript) {
+        throw new TypeError(`Deployment URL ${url} is not addressed by its provider script ${record.providerScript}.`);
+    }
+    const allowed = Object.hasOwn(SECRETS_BY_STATE, deployment.state)
+        ? SECRETS_BY_STATE[deployment.state]
+        : undefined;
+    if (allowed === undefined)
+        throw new TypeError('Deployment state must be created or reused.');
+    const secrets = deployment.secrets?.state;
+    if (!allowed.includes(secrets)) {
+        throw new TypeError(`A ${deployment.state} deployment has its secrets ${allowed.join(' or ')}, not ${String(secrets)}.`);
+    }
+    return Object.freeze({
+        format: 'astrale.deploy-result',
+        version: 1,
+        origin: document.origin,
+        environment: record.environment,
+        url,
+        release: Object.freeze({ digest: document.digest }),
+        build: Object.freeze({ digest: release.buildDigest }),
+        schema: Object.freeze({ revision: record.schemaRevision }),
+        deployment: Object.freeze({
+            adapter: `${input.adapter.name}@${input.adapter.version}`,
+            script: record.providerScript,
+            state: deployment.state,
+        }),
+        secrets: Object.freeze({ state: secrets }),
+        commit: record.commit,
+    });
+}
+function expectSame(member, declared, expected) {
+    if (declared !== expected) {
+        throw new TypeError(`Deployment declares ${member} ${declared}, not ${expected}.`);
+    }
+}

package/dist/tooling/cli/diff/declared.d.ts

@@ -0,0 +1,7 @@
+import type { Version } from '../../../platform/versioning/index.js';
+/**
+ * The version the author declares for the next release: `package.json` `version` in the Project
+ * directory, as release-please and `npm version` write it (tech Versioning [.21210]). No command
+ * takes a version number.
+ */
+export declare function declaredVersion(projectDir: string): Promise<Version>;

package/dist/tooling/cli/diff/declared.js

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { acceptVersion } from '../../../platform/versioning/index.js';
+/**
+ * The version the author declares for the next release: `package.json` `version` in the Project
+ * directory, as release-please and `npm version` write it (tech Versioning [.21210]). No command
+ * takes a version number.
+ */
+export async function declaredVersion(projectDir) {
+    const path = join(projectDir, 'package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (cause) {
+        throw new TypeError(`Cannot read the Domain's version: ${path} is not a readable JSON file.`, {
+            cause,
+        });
+    }
+    const version = typeof manifest === 'object' && manifest !== null && !Array.isArray(manifest)
+        ? manifest.version
+        : undefined;
+    if (typeof version !== 'string') {
+        throw new TypeError(`${path} declares no version. The Domain's version is the package.json version, for example written by npm version minor.`);
+    }
+    return acceptVersion(version);
+}

package/dist/tooling/cli/diff/index.d.ts

@@ -0,0 +1,30 @@
+import type { Build } from '../../../deployment/index.js';
+import type { DomainRegistry } from '../registry/index.js';
+export type { DiffChangeV1, DiffReportV1 } from './report.js';
+export interface DiffCommandInput {
+    readonly projectDir: string;
+    readonly build: Build;
+    /** The build digest of every distinct bundler of the Project, bundled on demand. */
+    readonly builds: () => Promise<readonly string[]>;
+    readonly identity?: string;
+    readonly json: boolean;
+    readonly signal: AbortSignal;
+}
+export interface DiffCommandDependencies {
+    readonly open: (input: {
+        readonly projectDir: string;
+        readonly identity?: string;
+        readonly signal: AbortSignal;
+    }) => Promise<DomainRegistry>;
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+}
+/**
+ * `astrale-domain diff [--as <identity>] [--json]`: the changes since the highest published stable
+ * version up to the declared one, and the smallest version they admit (tech Versioning [.72565]).
+ * On a feature branch the declared version is still the published one and the report is
+ * informational (exit 0); on a release PR an unpublished version that is too low fails (exit 1)
+ * with the [.105820] message. Reads the registry through the Astrale CLI under the caller's own
+ * credential and changes nothing.
+ */
+export declare function runDiff(input: DiffCommandInput, dependencies?: DiffCommandDependencies): Promise<number>;

package/dist/tooling/cli/diff/index.js

@@ -0,0 +1,58 @@
+import * as bundle from '@astrale-os/kernel-dsl/v1/bundle/transport';
+import { DIM, RED, RESET } from '../log.js';
+import { RegistryCliError, openDomainRegistry } from '../registry/index.js';
+import { declaredVersion } from './declared.js';
+import { diffExitCode, renderDiff } from './render.js';
+import { diffReport, publishedSchema } from './report.js';
+/**
+ * `astrale-domain diff [--as <identity>] [--json]`: the changes since the highest published stable
+ * version up to the declared one, and the smallest version they admit (tech Versioning [.72565]).
+ * On a feature branch the declared version is still the published one and the report is
+ * informational (exit 0); on a release PR an unpublished version that is too low fails (exit 1)
+ * with the [.105820] message. Reads the registry through the Astrale CLI under the caller's own
+ * credential and changes nothing.
+ */
+export async function runDiff(input, dependencies = {
+    open: openDomainRegistry,
+    stdout: (text) => void process.stdout.write(text),
+    stderr: (text) => void process.stderr.write(text),
+}) {
+    const root = input.build.schema.compiled.root;
+    let report;
+    try {
+        const declared = await declaredVersion(input.projectDir);
+        const registry = await dependencies.open({
+            projectDir: input.projectDir,
+            ...(input.identity === undefined ? {} : { identity: input.identity }),
+            signal: input.signal,
+        });
+        report = await diffReport({
+            origin: root.origin,
+            declared,
+            revision: root.revision,
+            index: await registry.index(root.origin),
+            current: () => bundle.decode(input.build.schema.bundle.bytes()).root,
+            builds: input.builds,
+            published: async (publication) => publishedSchema(await registry.bundle(root.origin, publication), publication, root.origin),
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof RegistryCliError))
+            throw cause;
+        // Nothing on stdout: a JSON consumer reads one report or nothing.
+        dependencies.stderr(`${RED}✗${RESET} Domain registry: ${cause.code}: ${cause.message}\n`);
+        return 1;
+    }
+    const rendered = renderDiff(report);
+    // With --json, stdout carries only the report and the summary moves to stderr, as for deploy.
+    const summary = input.json ? dependencies.stderr : dependencies.stdout;
+    // The sentence takes the progress mark; the member rows below it keep their indentation.
+    for (const line of rendered.summary) {
+        summary(line.startsWith('  ') ? `${line}\n` : `${DIM}›${RESET} ${line}\n`);
+    }
+    if (rendered.refusal.length > 0)
+        dependencies.stderr(`${rendered.refusal.join('\n')}\n`);
+    if (input.json)
+        dependencies.stdout(`${JSON.stringify(report, null, 2)}\n`);
+    return diffExitCode(report);
+}

package/dist/tooling/cli/diff/render.d.ts

@@ -0,0 +1,15 @@
+import type { DiffReportV1 } from './report.js';
+/**
+ * 0 when the declared version is accepted, already published (the report is then informational:
+ * a feature branch keeps the last published number until its release), or has nothing to compare
+ * with; 1 when an unpublished declared version is too low.
+ */
+export declare function diffExitCode(report: DiffReportV1): 0 | 1;
+/**
+ * The report for a person. `summary` describes the comparison; `refusal` is the [.105820] message
+ * for an unpublished version that is too low (tech Versioning), printed as an error.
+ */
+export declare function renderDiff(report: DiffReportV1): {
+    readonly summary: readonly string[];
+    readonly refusal: readonly string[];
+};

package/dist/tooling/cli/diff/render.js

@@ -0,0 +1,131 @@
+/** What a change of each level is, in the [.105820] message. */
+const NATURE = Object.freeze({
+    major: 'breaking change',
+    minor: 'addition',
+    patch: 'change',
+});
+const LEVELS = ['patch', 'minor', 'major'];
+/**
+ * 0 when the declared version is accepted, already published (the report is then informational:
+ * a feature branch keeps the last published number until its release), or has nothing to compare
+ * with; 1 when an unpublished declared version is too low.
+ */
+export function diffExitCode(report) {
+    return report.published || report.accepted ? 0 : 1;
+}
+/**
+ * The report for a person. `summary` describes the comparison; `refusal` is the [.105820] message
+ * for an unpublished version that is too low (tech Versioning), printed as an error.
+ */
+export function renderDiff(report) {
+    const subject = `${report.origin} ${report.declared}`;
+    if (report.registry === 'unregistered') {
+        return {
+            summary: [
+                `${report.origin} is not in the Domain registry, or you may not read it: nothing to compare.`,
+            ],
+            refusal: [],
+        };
+    }
+    if (report.baseline === undefined) {
+        return {
+            summary: [
+                `${subject}: no stable version up to ${report.declared} is published, nothing to compare.`,
+            ],
+            refusal: [],
+        };
+    }
+    const level = report.level;
+    const required = `at least ${report.next} (${NATURE[level]})`;
+    const rows = changeRows(report.changes, report.origin);
+    if (report.changes.length === 0) {
+        const state = report.published ? 'is published' : 'is accepted';
+        return {
+            summary: [`${subject} ${state}: no change since ${report.baseline}.`],
+            refusal: [],
+        };
+    }
+    if (report.published) {
+        return {
+            summary: [
+                `${subject} is published. The changes since ${report.baseline} need ${required}:`,
+                ...rows,
+            ],
+            refusal: [],
+        };
+    }
+    if (report.accepted) {
+        return {
+            summary: [
+                `${subject} is accepted. The changes since ${report.baseline} need ${required}:`,
+                ...rows,
+            ],
+            refusal: [],
+        };
+    }
+    // Only the changes that set the level are listed, as [.105820] lists the breaking ones.
+    const binding = report.changes.filter((change) => change.bump === level);
+    const others = report.changes.length - binding.length;
+    const declare = report.suggestion ?? report.next;
+    return {
+        summary: [],
+        refusal: [
+            `error: ${report.declared} is too low, ${NATURE[level]} since ${report.baseline}: at least ${report.next} is required`,
+            ...changeRows(binding, report.origin),
+            ...(others === 0 ? [] : [`  (and ${others} other ${others === 1 ? 'change' : 'changes'})`]),
+            level === 'major'
+                ? `Declare ${declare}, or keep the old member (expand then contract).`
+                : `Declare ${declare}.`,
+        ],
+    };
+}
+/**
+ * One line per changed member, `<kind> <name> <states> (<details>)`, in report order. A member the
+ * engine observes through several facets (a removed Method loses its existence and its signature)
+ * is one line.
+ */
+function changeRows(changes, origin) {
+    const members = new Map();
+    for (const change of changes) {
+        const key = `${change.facet === 'build' || change.facet === 'schema' ? change.facet : ''}\u0000${change.subject}`;
+        const member = members.get(key) ?? {
+            ...memberName(change, origin),
+            states: [],
+            details: [],
+            bump: 'patch',
+        };
+        if (!member.states.includes(change.state))
+            member.states.push(change.state);
+        if (change.detail !== undefined && !member.details.includes(change.detail)) {
+            member.details.push(change.detail);
+        }
+        if (LEVELS.indexOf(change.bump) > LEVELS.indexOf(member.bump))
+            member.bump = change.bump;
+        members.set(key, member);
+    }
+    const rows = [...members.values()];
+    const kindWidth = Math.max(0, ...rows.map(({ kind }) => kind.length)) + 1;
+    const nameWidth = Math.max(0, ...rows.map(({ name }) => name.length)) + 3;
+    return rows.map(({ kind, name, states, details }) => `  ${kind.padEnd(kindWidth)}${name.padEnd(nameWidth)}${states.join(', ')}${details.length === 0 ? '' : ` (${details.join('; ')})`}`);
+}
+/**
+ * `class.Project.method.archive` reads `method Project.archive`. A Key of another origin keeps
+ * its origin; a whole-Domain change names the origin.
+ */
+function memberName(change, origin) {
+    if (change.facet === 'build' || change.facet === 'schema') {
+        return { kind: change.facet, name: change.subject };
+    }
+    const separator = change.subject.indexOf(':');
+    const local = change.subject.slice(separator + 1);
+    const prefix = separator > 0 && change.subject.slice(0, separator) !== origin
+        ? `${change.subject.slice(0, separator)}:`
+        : '';
+    const member = /^class\.([^.]+)\.(property|method)\.(.+)$/u.exec(local);
+    if (member !== null)
+        return { kind: member[2], name: `${prefix}${member[1]}.${member[3]}` };
+    const dot = local.indexOf('.');
+    return dot > 0
+        ? { kind: local.slice(0, dot), name: `${prefix}${local.slice(dot + 1)}` }
+        : { kind: 'member', name: change.subject };
+}

package/dist/tooling/cli/diff/report.d.ts

@@ -0,0 +1,88 @@
+import type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
+import type { BumpLevel, Version } from '../../../platform/versioning/index.js';
+import type { RegistryIndex, RegistryPublication } from '../registry/index.js';
+/** One change since the baseline, with the level it alone requires. */
+export interface DiffChangeV1 {
+    /**
+     * The compared member's Key (`issues.astrale.ai:class.Issue.property.priority`), or the Domain's
+     * origin for a change of the whole build or Schema.
+     */
+    readonly subject: string;
+    /**
+     * The compatibility engine's facet (`method.existence`, `property.required`, …), `schema` for a
+     * new Schema revision of equivalent meaning, `build` for new code under the same revision.
+     */
+    readonly facet: string;
+    readonly state: 'missing' | 'changed' | 'added';
+    readonly bump: BumpLevel;
+    /** What differs, such as `optional → required`, when the observation says. */
+    readonly detail?: string;
+}
+/**
+ * `astrale-domain diff --json` on stdout: the version the Project declares, checked against the
+ * highest published stable version up to it (CT30).
+ */
+export interface DiffReportV1 {
+    readonly format: 'astrale.diff-report';
+    readonly version: 1;
+    readonly origin: string;
+    /** `package.json` `version`. */
+    readonly declared: string;
+    /** The declared version already names a Publication: the report is informational. */
+    readonly published: boolean;
+    /** `unregistered`: no Domain of this origin the caller may read; nothing is compared. */
+    readonly registry: 'read' | 'unregistered';
+    /** The highest published stable version up to the declared one, yanked ones included. */
+    readonly baseline?: string;
+    /** The level the changes since the baseline require. */
+    readonly level?: BumpLevel;
+    /** The level after the 0.x rule. */
+    readonly effective?: BumpLevel;
+    /** The smallest version the changes admit, a pre-release such as `2.0.0-0`. */
+    readonly minimum?: string;
+    /** The stable form of the required version, such as `2.0.0`. */
+    readonly next?: string;
+    /** For a refused pre-release, the first pre-release of the required version on its channel. */
+    readonly suggestion?: string;
+    /**
+     * The declared version reaches the minimum, or there is nothing to compare. It judges an
+     * unpublished version: a published stable one is its own baseline and is never accepted, so a
+     * consumer decides on `published || accepted`, the exit status.
+     */
+    readonly accepted: boolean;
+    /** Every change since the baseline, ordered by subject Key then observation; empty for none. */
+    readonly changes: readonly DiffChangeV1[];
+}
+export interface DiffInput {
+    readonly origin: string;
+    readonly declared: Version;
+    /**
+     * Which published versions can be the baseline (AM-23): `diff` compares with the highest stable
+     * version up to the declared one (`<=`, the default); `publish`, which never runs for a published
+     * version, with the highest one below it (`<`).
+     */
+    readonly bound?: '<' | '<=';
+    /** The Schema revision the Project builds now. */
+    readonly revision: string;
+    /** The caller's view of the registry; `undefined` when it holds no readable Domain of `origin`. */
+    readonly index: RegistryIndex | undefined;
+    /** The Schema the Project builds now. */
+    readonly current: () => DomainSchema;
+    /** The build digest of every distinct bundler; read only when the Schema revision is unchanged. */
+    readonly builds: () => Promise<readonly string[]>;
+    /** The Schema a Publication names; read only when its revision differs from the Project's. */
+    readonly published: (publication: RegistryPublication) => Promise<DomainSchema>;
+}
+/**
+ * Compare the Project with the highest published stable version up to the declared one
+ * (`baselineVersion(index, declared, '<=')`, or below it for `publish`, AM-23) and judge the declared version against the
+ * level its changes require (tech Versioning [.21507], [.106102]). The judgement always receives a
+ * level beside its baseline (AM-56): the compatibility engine's when the Schema revision changed,
+ * otherwise patch, the smallest level, which `diff` picks itself when nothing changed at all.
+ */
+export declare function diffReport(input: DiffInput): Promise<DiffReportV1>;
+/**
+ * Decode the bundle a Publication stores and admit it only as that Publication's Schema: the
+ * Domain's origin and the Publication's Schema revision.
+ */
+export declare function publishedSchema(bytes: Uint8Array, publication: RegistryPublication, origin: string): DomainSchema;

package/dist/tooling/cli/diff/report.js

@@ -0,0 +1,154 @@
+import * as bundle from '@astrale-os/kernel-dsl/v1/bundle/transport';
+import { requiredBump } from '@astrale-os/kernel-dsl/v1/schema/compatibility';
+import { revision } from '@astrale-os/kernel-dsl/v1/schema/revision';
+import { baselineVersion, judgeVersion } from '../../../platform/versioning/index.js';
+/**
+ * Compare the Project with the highest published stable version up to the declared one
+ * (`baselineVersion(index, declared, '<=')`, or below it for `publish`, AM-23) and judge the declared version against the
+ * level its changes require (tech Versioning [.21507], [.106102]). The judgement always receives a
+ * level beside its baseline (AM-56): the compatibility engine's when the Schema revision changed,
+ * otherwise patch, the smallest level, which `diff` picks itself when nothing changed at all.
+ */
+export async function diffReport(input) {
+    const identity = {
+        format: 'astrale.diff-report',
+        version: 1,
+        origin: input.origin,
+        declared: input.declared,
+    };
+    if (input.index === undefined) {
+        return Object.freeze({
+            ...identity,
+            published: false,
+            registry: 'unregistered',
+            accepted: true,
+            changes: Object.freeze([]),
+        });
+    }
+    const publications = input.index.publications;
+    const published = publications.some(({ version }) => version === input.declared);
+    // An index entry that is not a canonical version is never a baseline: `baselineVersion` keeps
+    // only canonical stable versions (AM-56), so the registry's strings need no admission here.
+    const index = publications.map(({ version, yanked }) => ({
+        version: version,
+        yanked,
+    }));
+    const baseline = baselineVersion(index, input.declared, input.bound ?? '<=');
+    if (baseline === undefined) {
+        // Without a stable version before it there is nothing to check (tech [.106102]).
+        const verdict = judgeVersion({ declared: input.declared });
+        return Object.freeze({
+            ...identity,
+            published,
+            registry: 'read',
+            accepted: verdict.accepted,
+            changes: Object.freeze([]),
+        });
+    }
+    const publication = publications.find(({ version }) => version === baseline);
+    const { level, changes } = await changesSince(publication, input);
+    const verdict = judgeVersion({ declared: input.declared, previous: baseline, level });
+    return Object.freeze({
+        ...identity,
+        published,
+        registry: 'read',
+        baseline,
+        level,
+        effective: verdict.effective,
+        minimum: verdict.minimum,
+        next: verdict.next,
+        ...(verdict.suggestion === undefined ? {} : { suggestion: verdict.suggestion }),
+        accepted: verdict.accepted,
+        changes,
+    });
+}
+/**
+ * Decode the bundle a Publication stores and admit it only as that Publication's Schema: the
+ * Domain's origin and the Publication's Schema revision.
+ */
+export function publishedSchema(bytes, publication, origin) {
+    const root = bundle.decode(bytes).root;
+    if (root.origin !== origin || revision(root) !== publication.schemaRevision) {
+        throw new TypeError(`The stored bundle of ${origin}@${publication.version} is not that Publication's Schema ${publication.schemaRevision}.`);
+    }
+    return root;
+}
+async function changesSince(publication, input) {
+    if (publication.schemaRevision !== input.revision) {
+        const required = requiredBump(await input.published(publication), input.current());
+        const changes = required.changes.map(change);
+        return {
+            level: required.level,
+            changes: Object.freeze(changes.length > 0
+                ? changes
+                : // A new revision whose meaning the engine finds equivalent, such as descriptions.
+                    [
+                        Object.freeze({
+                            subject: input.origin,
+                            facet: 'schema',
+                            state: 'changed',
+                            bump: 'patch',
+                            detail: 'same meaning',
+                        }),
+                    ]),
+        };
+    }
+    const builds = await input.builds();
+    if (builds.includes(publication.buildDigest)) {
+        // No change at all: same build digest and no row of [.21507] (AM-56).
+        return { level: 'patch', changes: Object.freeze([]) };
+    }
+    // Code only, same Schema revision ([.21507], first row).
+    return {
+        level: 'patch',
+        changes: Object.freeze([
+            Object.freeze({
+                subject: input.origin,
+                facet: 'build',
+                state: 'changed',
+                bump: 'patch',
+                detail: `${publication.buildDigest} → ${builds.length === 0 ? 'none' : builds.join(', ')}`,
+            }),
+        ]),
+    };
+}
+function change({ subject, observation, bump }) {
+    const detail = describe(observation);
+    return Object.freeze({
+        subject: subject.key,
+        facet: observation.facet,
+        // `requiredBump` lists only observations that are not equal.
+        state: observation.state,
+        bump,
+        ...(detail === undefined ? {} : { detail }),
+    });
+}
+const DETAILED_DIFFERENCES = 3;
+const VALUE_LENGTH = 40;
+/** The observation's differences in a few words: `optional → required`, `input/type: "string" → "number"`. */
+function describe(observation) {
+    const differences = observation.differences;
+    if (differences.length === 0)
+        return undefined;
+    const [first] = differences;
+    if (differences.length === 1 &&
+        first.path === '/required' &&
+        typeof first.before === 'boolean' &&
+        typeof first.after === 'boolean') {
+        return first.after ? 'optional → required' : 'required → optional';
+    }
+    const described = differences.slice(0, DETAILED_DIFFERENCES).map((difference) => {
+        const path = difference.path === '' ? '/' : difference.path.slice(1);
+        if (difference.before === undefined)
+            return `${path}: added ${value(difference.after)}`;
+        if (difference.after === undefined)
+            return `${path}: removed ${value(difference.before)}`;
+        return `${path}: ${value(difference.before)} → ${value(difference.after)}`;
+    });
+    const more = differences.length - described.length;
+    return more > 0 ? `${described.join('; ')}; ${more} more` : described.join('; ');
+}
+function value(input) {
+    const text = JSON.stringify(input) ?? String(input);
+    return text.length > VALUE_LENGTH ? `${text.slice(0, VALUE_LENGTH - 1)}…` : text;
+}