@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.41

package/dist/platform/schema/class-authoring.d.ts

@@ -1,36 +1,86 @@
-import { nodeClass as kernelNodeClass, type DirectedEdgeClass, type DirectedEdgeInput, type NodeClass, type NodeClassInput as KernelNodeClassInput, type UndirectedEdgeClass, type UndirectedEdgeInput } from '@astrale-os/kernel-dsl/v1/builder';
+import { edgeClass as kernelEdgeClass, nodeClass as kernelNodeClass, type DirectedEdgeClass, type DirectedEdgeInput, type Lazy, type NodeClass, type NodeClassInput as KernelNodeClassInput, type NodeClassPolicyInput, type Policy, type UndirectedEdgeClass, type UndirectedEdgeInput } from '@astrale-os/kernel-dsl/v1/builder';
 import { type ClassIcon } from './class-icon.js';
-/** SDK Node Class input: every author must make an explicit, admitted icon choice. */
+/**
+ * SDK Node Class input: every author must make an explicit, admitted icon choice, and every
+ * concrete Class must declare its read rule.
+ */
 export type NodeClassInput = Omit<KernelNodeClassInput, 'icon'> & {
     readonly icon: ClassIcon;
 };
+/** Who may read or traverse an Edge Class: a named Policy, or the constant `true` or `false`. */
+export type ClassReadRule = Lazy<Policy> | boolean;
+/**
+ * Who may read or traverse a Node Class: a named Policy, the constant `true` or `false`, or Policy
+ * checks over the observed Node (`self`) and fixed members (`ref(...)`), composed as the checks of
+ * an authorized callable.
+ */
+export type NodeClassReadRule = NodeClassPolicyInput;
+/**
+ * The observation rules of a concrete Class. A Node stays traversable through either rule, so a
+ * read rule other than `true` leaves every caller able to reach it, and to select its reference,
+ * until the traverse rule is declared too.
+ */
+export type DeclaredObservation<Rule = ClassReadRule> = {
+    readonly read: true;
+    readonly traverse?: Rule;
+} | {
+    readonly read: Exclude<Rule, true>;
+    readonly traverse: Rule;
+};
+/**
+ * A concrete Class declares its read rule, and its traverse rule whenever the read rule is not
+ * `true`. An abstract Class is never observed directly, so it declares neither.
+ */
+export type DeclaredReadRule<Config, Rule = ClassReadRule> = Config extends {
+    readonly abstract: true;
+} ? unknown : {
+    readonly policies: DeclaredObservation<Rule>;
+};
 /** Preserve authored input instead of serializing expanded inheritance projections in consumers. */
 export interface AuthoredNodeClass<Config extends NodeClassInput> extends ReturnType<typeof kernelNodeClass<Config>> {
 }
+type DirectedOptions = Omit<DirectedEdgeInput, 'orientation'>;
+type UndirectedOptions = Omit<UndirectedEdgeInput, 'orientation'>;
+/** The two states `defineClass` admits: abstract, or concrete with declared observation rules. */
+type Declared<Input, Rule = ClassReadRule> = (Input & {
+    readonly abstract: true;
+}) | (Input & {
+    readonly abstract: false;
+} & {
+    readonly policies: DeclaredObservation<Rule>;
+});
 type NodeInput = {
     readonly kind: 'node';
-    readonly abstract: boolean;
-} & NodeClassInput;
+} & Declared<NodeClassInput, NodeClassReadRule>;
 type DirectedInput = {
     readonly kind: 'edge';
     readonly orientation: 'directed';
-    readonly abstract: boolean;
-} & Omit<DirectedEdgeInput, 'orientation'>;
+} & Declared<DirectedOptions>;
 type UndirectedInput = {
     readonly kind: 'edge';
     readonly orientation: 'undirected';
-    readonly abstract: boolean;
-} & Omit<UndirectedEdgeInput, 'orientation'>;
+} & Declared<UndirectedOptions>;
 /**
  * Author a Node Class whose materialized configuration always carries an explicitly selected,
- * admitted SVG icon. The mapped input retains inference while expanding package-private
- * Config interface names into portable structure for downstream declaration emit.
+ * admitted SVG icon and, when concrete, a declared read rule. The mapped input retains inference
+ * while expanding package-private Config interface names into portable structure for downstream
+ * declaration emit.
  */
-export declare function nodeClass<const Config extends NodeClassInput>(config: Config & Record<Exclude<keyof Config, keyof NodeClassInput>, never>): AuthoredNodeClass<{
+export declare function nodeClass<const Config extends NodeClassInput>(config: Config & Record<Exclude<keyof Config, keyof NodeClassInput>, never> & DeclaredReadRule<Config, NodeClassReadRule>): AuthoredNodeClass<{
     [Key in keyof Config]: Key extends 'properties' | 'methods' | 'policies' ? {
         [Member in keyof NonNullable<Config[Key]>]: NonNullable<Config[Key]>[Member];
     } | Extract<Config[Key], undefined> : Key extends 'extends' ? Config[Key] extends infer Parents extends NodeClassInput['extends'] ? Parents extends readonly unknown[] ? readonly [...Parents] : Parents : never : Config[Key];
 }>;
+declare function directed<const Input extends DirectedOptions>(input: Input & Parameters<typeof kernelEdgeClass.directed<Input>>[0] & DeclaredReadRule<Input>): ReturnType<typeof kernelEdgeClass.directed<Input>>;
+declare function undirected<const Input extends UndirectedOptions>(input: Input & Parameters<typeof kernelEdgeClass.undirected<Input>>[0] & DeclaredReadRule<Input>): ReturnType<typeof kernelEdgeClass.undirected<Input>>;
+/**
+ * Author an Edge Class. A concrete Edge Class declares its read rule exactly as a Node Class
+ * does; the handle is the canonical DSL handle.
+ */
+export declare const edgeClass: Readonly<{
+    directed: typeof directed;
+    undirected: typeof undirected;
+}>;
 export declare function defineClass(config: NodeInput): NodeClass;
 export declare function defineClass(config: DirectedInput): DirectedEdgeClass;
 export declare function defineClass(config: UndirectedInput): UndirectedEdgeClass;

package/dist/platform/schema/class-authoring.js

@@ -1,20 +1,53 @@
-import { defineClass as defineKernelClass, nodeClass as kernelNodeClass, } from '@astrale-os/kernel-dsl/v1/builder';
+import { edgeClass as kernelEdgeClass, nodeClass as kernelNodeClass, } from '@astrale-os/kernel-dsl/v1/builder';
+import { assertNoUndeclaredCallerRule } from './callable-authoring.js';
 import { classIcon } from './class-icon.js';
 export function nodeClass(config) {
     if (config === undefined || config.icon === undefined) {
         throw new TypeError('Node Class icon is required; use classIcon.neutral to make an explicit neutral choice.');
     }
+    assertDeclaredReadRule('Node', config);
+    if (config.abstract !== true)
+        assertNoUndeclaredCallerRule(config.methods);
     return kernelNodeClass({
         ...config,
         icon: classIcon.svg(config.icon),
     });
 }
+function directed(input) {
+    assertDeclaredReadRule('Edge', input);
+    return kernelEdgeClass.directed(input);
+}
+function undirected(input) {
+    assertDeclaredReadRule('Edge', input);
+    return kernelEdgeClass.undirected(input);
+}
+/**
+ * Author an Edge Class. A concrete Edge Class declares its read rule exactly as a Node Class
+ * does; the handle is the canonical DSL handle.
+ */
+export const edgeClass = Object.freeze({ directed, undirected });
 export function defineClass(config) {
     if (config.kind === 'node') {
         const { kind: _, ...input } = config;
         return nodeClass(input);
     }
-    if (config.orientation === 'directed')
-        return defineKernelClass(config);
-    return defineKernelClass(config);
+    if (config.orientation === 'directed') {
+        const { kind: _, orientation: __, ...input } = config;
+        return edgeClass.directed(input);
+    }
+    const { kind: _, orientation: __, ...input } = config;
+    return edgeClass.undirected(input);
+}
+/** The authoring boundary restates the type contract for untyped and widened configurations. */
+function assertDeclaredReadRule(kind, config) {
+    if (config.abstract === true)
+        return;
+    const rule = kind === 'Node' ? 'a Policy, Policy checks, true or false' : 'a Policy, true or false';
+    const read = config.policies?.read;
+    if (read === undefined) {
+        throw new TypeError(`${kind} Class read rule is required; declare policies.read with ${rule}.`);
+    }
+    if (read !== true && config.policies?.traverse === undefined) {
+        throw new TypeError(`${kind} Class traverse rule is required when its read rule is not true; declare policies.traverse with ${rule}.`);
+    }
 }

package/dist/platform/schema/class-icon-svg.d.ts

@@ -0,0 +1,9 @@
+declare const CLASS_ICON: unique symbol;
+/** An admitted, self-contained SVG suitable for a Node Class presentation icon. */
+export type ClassIcon = string & {
+    readonly [CLASS_ICON]: true;
+};
+/** Stable empty SVG used when an author explicitly chooses to render no icon glyph. */
+export declare const NEUTRAL_CLASS_ICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"></svg>";
+export declare function admitClassIconSvg(source: string): ClassIcon;
+export {};

package/dist/platform/schema/class-icon-svg.js

@@ -0,0 +1,29 @@
+const MAX_CLASS_ICON_LENGTH = 8_000;
+const SVG_ROOT = /^<svg(?:\s[^>]*)?>[\s\S]*<\/svg>$/u;
+const SVG_ROOT_OPEN = /<svg(?:\s|>)/gu;
+const SVG_ROOT_CLOSE = /<\/svg\s*>/gu;
+const SVG_GRAPHIC = /<(?:circle|ellipse|line|path|polygon|polyline|rect)\b/iu;
+const UNSAFE_SVG = /<\s*(?:animate|discard|embed|foreignObject|iframe|image|object|script|set|style|use)\b|<!DOCTYPE\b|<!ENTITY\b|\son[a-z][\w:.-]*\s*=|(?:href|xlink:href)\s*=|javascript\s*:|url\s*\(/iu;
+/** Stable empty SVG used when an author explicitly chooses to render no icon glyph. */
+export const NEUTRAL_CLASS_ICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>';
+export function admitClassIconSvg(source) {
+    if (typeof source !== 'string') {
+        throw new TypeError('Class icon must be an inline SVG string.');
+    }
+    const value = source.trim();
+    if (Array.from(value).length > MAX_CLASS_ICON_LENGTH) {
+        throw new TypeError(`Class icon must contain at most ${MAX_CLASS_ICON_LENGTH} characters.`);
+    }
+    if (!SVG_ROOT.test(value) ||
+        (value.match(SVG_ROOT_OPEN)?.length ?? 0) !== 1 ||
+        (value.match(SVG_ROOT_CLOSE)?.length ?? 0) !== 1) {
+        throw new TypeError('Class icon must be one complete inline <svg> element.');
+    }
+    if (UNSAFE_SVG.test(value)) {
+        throw new TypeError('Class icon SVG must be self-contained and contain no executable content.');
+    }
+    if (value !== NEUTRAL_CLASS_ICON_SVG && !SVG_GRAPHIC.test(value)) {
+        throw new TypeError('Class icon SVG must contain a visible vector element.');
+    }
+    return value;
+}

package/dist/platform/schema/class-icon.d.ts

@@ -1,15 +1,10 @@
 import type { LucideIconData } from '@lucide/icons';
-declare const CLASS_ICON: unique symbol;
-/** An admitted, self-contained SVG suitable for a Node Class presentation icon. */
-export type ClassIcon = string & {
-    readonly [CLASS_ICON]: true;
-};
-/** Stable empty SVG used when an author explicitly chooses to render no icon glyph. */
-export declare const NEUTRAL_CLASS_ICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"></svg>";
+import type { ClassIcon } from './class-icon-svg.js';
+export type { ClassIcon } from './class-icon-svg.js';
+export { NEUTRAL_CLASS_ICON_SVG } from './class-icon-svg.js';
 /** Framework-neutral constructors for canonical Node Class icons. */
 export declare const classIcon: Readonly<{
     readonly neutral: ClassIcon;
     svg(source: string): ClassIcon;
     lucide(icon: LucideIconData): ClassIcon;
 }>;
-export {};

package/dist/platform/schema/class-icon.js

@@ -1,33 +1,6 @@
 import { buildLucideSvg } from '@lucide/icons/build';
-const MAX_CLASS_ICON_LENGTH = 8_000;
-const SVG_ROOT = /^<svg(?:\s[^>]*)?>[\s\S]*<\/svg>$/u;
-const SVG_ROOT_OPEN = /<svg(?:\s|>)/gu;
-const SVG_ROOT_CLOSE = /<\/svg\s*>/gu;
-const SVG_GRAPHIC = /<(?:circle|ellipse|line|path|polygon|polyline|rect)\b/iu;
-const UNSAFE_SVG = /<\s*(?:animate|discard|embed|foreignObject|iframe|image|object|script|set|style|use)\b|<!DOCTYPE\b|<!ENTITY\b|\son[a-z][\w:.-]*\s*=|(?:href|xlink:href)\s*=|javascript\s*:|url\s*\(/iu;
-/** Stable empty SVG used when an author explicitly chooses to render no icon glyph. */
-export const NEUTRAL_CLASS_ICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>';
-function svg(source) {
-    if (typeof source !== 'string') {
-        throw new TypeError('Class icon must be an inline SVG string.');
-    }
-    const value = source.trim();
-    if (Array.from(value).length > MAX_CLASS_ICON_LENGTH) {
-        throw new TypeError(`Class icon must contain at most ${MAX_CLASS_ICON_LENGTH} characters.`);
-    }
-    if (!SVG_ROOT.test(value) ||
-        (value.match(SVG_ROOT_OPEN)?.length ?? 0) !== 1 ||
-        (value.match(SVG_ROOT_CLOSE)?.length ?? 0) !== 1) {
-        throw new TypeError('Class icon must be one complete inline <svg> element.');
-    }
-    if (UNSAFE_SVG.test(value)) {
-        throw new TypeError('Class icon SVG must be self-contained and contain no executable content.');
-    }
-    if (value !== NEUTRAL_CLASS_ICON_SVG && !SVG_GRAPHIC.test(value)) {
-        throw new TypeError('Class icon SVG must contain a visible vector element.');
-    }
-    return value;
-}
+import { admitClassIconSvg as svg, NEUTRAL_CLASS_ICON_SVG } from './class-icon-svg.js';
+export { NEUTRAL_CLASS_ICON_SVG } from './class-icon-svg.js';
 function lucide(icon) {
     let source;
     try {

package/dist/platform/schema/index.d.ts

@@ -7,16 +7,18 @@ export type { StateProperty } from './state-property.js';
 export { property } from './property.js';
 export type { AuthoredProperty, PropertyOptions } from './property.js';
 export { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
-export { defineClass, nodeClass } from './class-authoring.js';
-export type { AuthoredNodeClass, NodeClassInput } from './class-authoring.js';
+export { defineClass, edgeClass, nodeClass } from './class-authoring.js';
+export type { AuthoredNodeClass, ClassReadRule, DeclaredObservation, DeclaredReadRule, NodeClassReadRule, NodeClassInput, } from './class-authoring.js';
+export { func, method } from './callable-authoring.js';
+export type { CallerRule, DeclaredCallerRule } from './callable-authoring.js';
 export { error } from './error.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFamily } from './error.js';
 export { classIcon } from './class-icon.js';
 export type { ClassIcon } from './class-icon.js';
 export type { StoredPropertyInputOf } from './property-input.js';
-export type { CallablePolicyBuilder, CallablePolicyContext, CallableProjection, AuthoredMethodProjection, AuthoredPropertyProjection, ClassIdentityProjection, ClassOwnerProjection, CoreEdge, CoreEndpoint, CoreNode, DefinedSchema, DirectedEdgeClass, ClassReferenceProjection, ClassProjection, FunctionProjection, EdgeClass, Function, Method, MethodProjection, Lazy, NodeClass, Policy, PolicyExistsContext, PolicyNodeBinder, PolicyPatternContext, Property, PropertyProjection, ResolvedDomainOfInput, View, } from '@astrale-os/kernel-dsl/v1/builder';
+export type { CallablePolicyBuilder, CallablePolicyContext, ClassRuleBuilder, ClassRuleContext, PolicyCheckContext, CallableProjection, AuthoredMethodProjection, AuthoredPropertyProjection, ClassIdentityProjection, ClassOwnerProjection, CoreEdge, CoreEndpoint, CoreNode, DefinedSchema, DirectedEdgeClass, ClassReferenceProjection, ClassProjection, FunctionProjection, EdgeClass, Function, Method, MethodProjection, Lazy, NodeClass, Policy, PolicyExistsContext, PolicyNodeBinder, PolicyPatternContext, Property, PropertyProjection, ResolvedDomainOfInput, View, } from '@astrale-os/kernel-dsl/v1/builder';
 export type { Array, Object, Value } from '@astrale-os/kernel-dsl/value';
-export type { ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PolicyObjectRef, PropertyFacet, StateTopology, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';
+export type { CallableAdmission, CallableExecution, ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PolicyObjectRef, PropertyFacet, PropertyImmutability, StateTopology, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';
 export type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
 /** Kernel-owned Schema values used by authored product Schemas and graph operations. */
 export { AuthorityOperationOrder, AuthorityOperations, AuthorityRelations, KernelRootFunctions, OperationCore, operationOf, } from '@astrale-os/kernel-core/schema';

package/dist/platform/schema/index.js

@@ -4,7 +4,8 @@ export { defineSchema } from './schema-authoring.js';
 export { stateProperty } from './state-property.js';
 export { property } from './property.js';
 export { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
-export { defineClass, nodeClass } from './class-authoring.js';
+export { defineClass, edgeClass, nodeClass } from './class-authoring.js';
+export { func, method } from './callable-authoring.js';
 export { error } from './error.js';
 export { classIcon } from './class-icon.js';
 /** Kernel-owned Schema values used by authored product Schemas and graph operations. */

package/dist/platform/schema/property.d.ts

@@ -3,6 +3,11 @@ import { type Property as CanonicalProperty, type ValueSchemaInput } from '@astr
 export interface PropertyOptions {
     readonly required?: boolean;
     readonly description?: string;
+    /**
+     * `create` freezes the value when its node or edge is created. `once` admits one write while the
+     * value is absent; neither can be changed or unset afterwards, only removed with the element.
+     */
+    readonly immutable?: 'create' | 'once';
 }
 /** Keep canonical generic inference: ordinary properties carry no state machine. */
 export type AuthoredProperty<Schema extends ValueSchemaInput, Options extends PropertyOptions = Record<never, never>> = CanonicalProperty<Schema, Options, never>;

package/dist/platform/schema/schema-authoring.d.ts

@@ -1,9 +1,8 @@
-import type { DefinedSchema, ResolvedDomainOfInput } from '@astrale-os/kernel-dsl/v1/builder';
+import type { DefinedSchema, EntrypointOf, ResolvedDomainOfInput, SchemaInput } from '@astrale-os/kernel-dsl/v1/builder';
 import type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
-import { defineSchema as kernelDefineSchema } from '@astrale-os/kernel-dsl/v1';
-type DomainSchemaInput = Parameters<typeof kernelDefineSchema>[1];
+type DomainSchemaInput = SchemaInput;
 declare const authoredGraph: unique symbol;
-/** Opaque legacy Schemas retain their witness; SDK Schemas retain authored input and edges. */
+/** Resolved Schemas retain their witness; authored Schemas retain input and dependency edges. */
 type Entry = readonly [origin: string, schema: DomainSchema] | readonly [
     origin: string,
     input: DomainSchemaInput,
@@ -34,7 +33,7 @@ type InputOf<Origin extends string, Graph extends Entry> = Extract<Graph, readon
         readonly [Alias in keyof Dependencies]: SchemaOf<Dependencies[Alias], Graph>;
     };
 } : never;
-type SchemaOf<Origin extends string, Graph extends Entry> = Extract<Graph, readonly [Origin, DomainSchema]> extends infer Legacy ? [Legacy] extends [never] ? AuthoredSchema<Origin, Graph> : Legacy extends readonly [string, infer Schema extends DomainSchema] ? Schema : never : never;
+type SchemaOf<Origin extends string, Graph extends Entry> = Extract<Graph, readonly [Origin, DomainSchema]> extends infer Resolved ? [Resolved] extends [never] ? AuthoredSchema<Origin, Graph> : Resolved extends readonly [string, infer Schema extends DomainSchema] ? Schema : never : never;
 /** Resolve a dependency graph without expanding a shared Schema at each dependency edge. */
 export interface AuthoredDomain<Origin extends string, Graph extends Entry> extends ResolvedDomainOfInput<Origin, InputOf<Origin, Graph>> {
 }
@@ -42,7 +41,15 @@ export interface AuthoredDomain<Origin extends string, Graph extends Entry> exte
 export interface AuthoredSchema<Origin extends string, Graph extends Entry> extends DefinedSchema<Origin, AuthoredDomain<Origin, Graph>> {
     readonly [authoredGraph]?: Graph;
 }
-type DefineSchema = <const Origin extends string, const Input extends DomainSchemaInput>(origin: Origin, input: Input) => string extends Origin | Extract<Dependencies<Input>[keyof Dependencies<Input>], DomainSchema>['origin'] ? DefinedSchema<Origin, ResolvedDomainOfInput<Origin, Input>> : AuthoredSchema<Origin, Extract<UniqueEntries<GraphOfInput<Origin, Input>>, Entry>>;
-/** The canonical implementation with a portable, automatically inferred declaration. */
+type DefineSchema = <const Origin extends string, const Input extends DomainSchemaInput & {
+    readonly name: string;
+}>(origin: Origin, input: Input & {
+    readonly entrypoint?: EntrypointOf<Input>;
+}) => string extends Origin | Extract<Dependencies<Input>[keyof Dependencies<Input>], DomainSchema>['origin'] ? DefinedSchema<Origin, ResolvedDomainOfInput<Origin, Input>> : AuthoredSchema<Origin, Extract<UniqueEntries<GraphOfInput<Origin, Input>>, Entry>>;
+/**
+ * The canonical implementation with a portable, automatically inferred declaration. Its type
+ * requires the Domain `name`, which the Kernel requires to install a new revision; `defineDomain`
+ * refuses an unnamed root Schema at runtime. `entrypoint` names one of the declared Views.
+ */
 export declare const defineSchema: DefineSchema;
 export {};

package/dist/platform/schema/schema-authoring.js

@@ -1,3 +1,7 @@
 import { defineSchema as kernelDefineSchema } from '@astrale-os/kernel-dsl/v1';
-/** The canonical implementation with a portable, automatically inferred declaration. */
+/**
+ * The canonical implementation with a portable, automatically inferred declaration. Its type
+ * requires the Domain `name`, which the Kernel requires to install a new revision; `defineDomain`
+ * refuses an unnamed root Schema at runtime. `entrypoint` names one of the declared Views.
+ */
 export const defineSchema = kernelDefineSchema;

package/dist/platform/versioning/dependents.d.ts

@@ -0,0 +1,18 @@
+import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import { type Version } from './version.js';
+/**
+ * The highest stable, non-yanked version of a dependent Domain whose dependencies contain the target
+ * exactly, by origin and revision: the version to install beside that dependency. Semver is never a
+ * compatibility rule; only the exact revision a release was built against is.
+ */
+export declare function compatibleDependentVersion(index: readonly {
+    readonly version: Version;
+    readonly yanked: boolean;
+    readonly dependencies: readonly {
+        readonly origin: string;
+        readonly revision: Revision;
+    }[];
+}[], target: {
+    readonly origin: string;
+    readonly revision: Revision;
+}): Version | undefined;

package/dist/platform/versioning/dependents.js

@@ -0,0 +1,15 @@
+import semver from 'semver';
+import { isStable } from './version.js';
+/**
+ * The highest stable, non-yanked version of a dependent Domain whose dependencies contain the target
+ * exactly, by origin and revision: the version to install beside that dependency. Semver is never a
+ * compatibility rule; only the exact revision a release was built against is.
+ */
+export function compatibleDependentVersion(index, target) {
+    const compatible = index
+        .filter(({ version, yanked, dependencies }) => !yanked &&
+        isStable(version) &&
+        dependencies.some(({ origin, revision }) => origin === target.origin && revision === target.revision))
+        .map(({ version }) => version);
+    return semver.rsort(compatible)[0];
+}

package/dist/platform/versioning/index.d.ts

@@ -0,0 +1,5 @@
+/** Semver policy of Domain versions, shared by `diff`, `publish` and install resolution. */
+export { compatibleDependentVersion } from './dependents.js';
+export { deploymentName } from './name.js';
+export { parseReference, resolveVersion, type Reference } from './reference.js';
+export { acceptVersion, baselineVersion, effectiveLevel, judgeVersion, minimumVersion, type BumpLevel, type PublishedVersion, type Version, type VersionVerdict, } from './version.js';

package/dist/platform/versioning/index.js

@@ -0,0 +1,5 @@
+/** Semver policy of Domain versions, shared by `diff`, `publish` and install resolution. */
+export { compatibleDependentVersion } from './dependents.js';
+export { deploymentName } from './name.js';
+export { parseReference, resolveVersion } from './reference.js';
+export { acceptVersion, baselineVersion, effectiveLevel, judgeVersion, minimumVersion, } from './version.js';

package/dist/platform/versioning/name.d.ts

@@ -0,0 +1,38 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+/**
+ * The computed, never stored, name of one deployment. A version naming its release names it
+ * (`1.5.0`); a version naming its build elsewhere names it in its environment (`1.5.0 · staging`).
+ * Otherwise its recorded commit describes it from the last release tag, like `git describe` and Go
+ * pseudo-versions (`1.4.2 + 7 commits · a1b2c3d · staging`). A modified tree suffixes the commit
+ * token with `-dirty` and keeps the base and the environment (`a1b2c3d-dirty · staging`), as
+ * `git describe --dirty` does. When several published versions name one release or build, the
+ * highest that is not yanked names it, else the highest yanked one. Every name but a release's
+ * carries its environment, and listings print the name as returned, never shortened.
+ *
+ * The deployer declares the record and anyone may read it, so only the `DeploymentCommitV1` shape
+ * enters the name. A base enters only as a canonical version, the release tag without its `v` or
+ * `<component>-v` prefix, with a non-negative integer distance. A commit whose SHA is not 40
+ * hexadecimal digits names a plain preview, and the commit token is always printed in lower case,
+ * like `git describe`. An environment outside the `defineProject` grammar is rendered as `?`, so no
+ * record can put control characters or a ` · ` of its own in the name. Likewise only canonical
+ * published versions name a deployment. A deployment named without its digests (one whose record
+ * is not admitted) is never named by a published version.
+ */
+export declare function deploymentName(deployment: {
+    readonly environment: string;
+    readonly releaseDigest?: Digest;
+    readonly buildDigest?: Digest;
+    readonly commit: {
+        readonly sha: string;
+        readonly dirty: boolean;
+        readonly base?: {
+            readonly version: string;
+            readonly distance: number;
+        };
+    } | null;
+}, publications: readonly {
+    readonly version: string;
+    readonly releaseDigest: Digest;
+    readonly buildDigest: Digest;
+    readonly yanked: boolean;
+}[]): string;

package/dist/platform/versioning/name.js

@@ -0,0 +1,58 @@
+import semver from 'semver';
+import { ENVIRONMENT_NAME } from '../../deployment/environment.js';
+import { isVersion } from './version.js';
+/** A commit as `DeploymentCommitV1` records it: the full hexadecimal SHA-1, in either case. */
+const SHA = /^[0-9a-f]{40}$/iu;
+/** Stands for an environment outside the project environment-name grammar. */
+const UNKNOWN_ENVIRONMENT = '?';
+/**
+ * The computed, never stored, name of one deployment. A version naming its release names it
+ * (`1.5.0`); a version naming its build elsewhere names it in its environment (`1.5.0 · staging`).
+ * Otherwise its recorded commit describes it from the last release tag, like `git describe` and Go
+ * pseudo-versions (`1.4.2 + 7 commits · a1b2c3d · staging`). A modified tree suffixes the commit
+ * token with `-dirty` and keeps the base and the environment (`a1b2c3d-dirty · staging`), as
+ * `git describe --dirty` does. When several published versions name one release or build, the
+ * highest that is not yanked names it, else the highest yanked one. Every name but a release's
+ * carries its environment, and listings print the name as returned, never shortened.
+ *
+ * The deployer declares the record and anyone may read it, so only the `DeploymentCommitV1` shape
+ * enters the name. A base enters only as a canonical version, the release tag without its `v` or
+ * `<component>-v` prefix, with a non-negative integer distance. A commit whose SHA is not 40
+ * hexadecimal digits names a plain preview, and the commit token is always printed in lower case,
+ * like `git describe`. An environment outside the `defineProject` grammar is rendered as `?`, so no
+ * record can put control characters or a ` · ` of its own in the name. Likewise only canonical
+ * published versions name a deployment. A deployment named without its digests (one whose record
+ * is not admitted) is never named by a published version.
+ */
+export function deploymentName(deployment, publications) {
+    const { commit } = deployment;
+    const environment = typeof deployment.environment === 'string' && ENVIRONMENT_NAME.test(deployment.environment)
+        ? deployment.environment
+        : UNKNOWN_ENVIRONMENT;
+    const release = highest(publications.filter(({ releaseDigest }) => deployment.releaseDigest !== undefined && releaseDigest === deployment.releaseDigest));
+    if (release !== undefined)
+        return release;
+    const build = highest(publications.filter(({ buildDigest }) => deployment.buildDigest !== undefined && buildDigest === deployment.buildDigest));
+    if (build !== undefined)
+        return `${build} · ${environment}`;
+    if (commit === null || typeof commit.sha !== 'string' || !SHA.test(commit.sha)) {
+        return `preview · ${environment}`;
+    }
+    const sha = `${commit.sha.slice(0, 7).toLowerCase()}${commit.dirty === true ? '-dirty' : ''}`;
+    const base = describeBase(commit.base);
+    return base === undefined ? `${sha} · ${environment}` : `${base} · ${sha} · ${environment}`;
+}
+function describeBase(base) {
+    if (base === undefined || !isVersion(base.version))
+        return undefined;
+    const { version, distance } = base;
+    if (!Number.isSafeInteger(distance) || distance < 0)
+        return undefined;
+    return distance === 0 ? version : `${version} + ${distance} commit${distance === 1 ? '' : 's'}`;
+}
+function highest(publications) {
+    const versions = (yanked) => publications
+        .filter((publication) => publication.yanked === yanked && isVersion(publication.version))
+        .map(({ version }) => version);
+    return semver.rsort(versions(false))[0] ?? semver.rsort(versions(true))[0];
+}

package/dist/platform/versioning/reference.d.ts

@@ -0,0 +1,48 @@
+import { type PublishedVersion, type Version } from './version.js';
+/**
+ * One install reference. The syntax decides: a version goes to the registry, a deployment URL is
+ * installed as is, without any lookup.
+ */
+export type Reference = {
+    readonly kind: 'url';
+    readonly url: string;
+} | {
+    readonly kind: 'exact';
+    readonly origin: string;
+    readonly version: Version;
+} | {
+    readonly kind: 'line';
+    readonly origin: string;
+    readonly line: `${number}.${number}`;
+};
+/**
+ * Parse `<origin>@<major>.<minor>.<patch>[-<pre>]`, `<origin>@<major>.<minor>` or a deployment URL.
+ * Ranges are not references: `@1`, `^1.5` and `1.5.x` are refused, since only the exact version and
+ * the highest stable version of one minor line are ever resolved. A URL with credentials is refused:
+ * `https://issues.astrale.ai@1.5.0` would otherwise name the host `1.5.0`, not a version.
+ *
+ * A deployment URL is returned as written, so it must already be the URL the Kernel fetches: one the
+ * URL parser keeps as is, up to the `/` of an empty path. Whitespace and control characters (which
+ * the parser strips), an upper-case host, a default port or a missing `//` host are refused, as are a
+ * query and a fragment, which no deployment URL carries.
+ */
+export declare function parseReference(input: string): Reference;
+/**
+ * Translate a version reference into one published version. An exact reference names any published
+ * version, a pre-release or a yanked one included (the caller warns on yanked). A line resolves to
+ * its highest stable version that is not yanked.
+ *
+ * A reference built from data rather than by `parseReference` is checked the same way: an exact
+ * version must be canonical and a line must be `<major>.<minor>`, so `1` never resolves as a major
+ * range and `1.5.3` never as an exact pin. Anything else throws a `TypeError`.
+ */
+export declare function resolveVersion(published: readonly PublishedVersion[], reference: Exclude<Reference, {
+    kind: 'url';
+}>): {
+    readonly kind: 'resolved';
+    readonly version: Version;
+    readonly yanked: boolean;
+} | {
+    readonly kind: 'unresolved';
+    readonly reason: 'unknown-version' | 'no-stable-match' | 'yanked-only';
+};