@astrale-os/kernel-protocol 0.5.0-beta.55 → 0.5.0-beta.56

package/dist/invocation/index.d.ts

@@ -12,7 +12,7 @@ export { admitTrace, MAXIMUM_TRACEPARENT_BYTES, MAXIMUM_TRACESTATE_BYTES, MAXIMU
 export { acceptRouting, type Refresh, type Routing, type Via } from './routing.js';
 export { acceptSchemaTarget, type SchemaTarget } from './schema.js';
 export { decodeResponse, type ErrorResponse, type Response, type ResponseContext, type SuccessResponse, } from './response.js';
-export { SCHEMA_REVISION_MISMATCH, SERVICE_CANDIDATE_INVALID, SERVICE_TRUST_REQUIRED, SERVICE_UNAVAILABLE, serviceErrorOf, type SchemaRevisionMismatchDetails, type SchemaRevisionMismatchReason, type ServiceCandidateInvalidDetails, type ServiceCandidateInvalidReason, type ServiceErrorPayload, type ServiceReason, type ServiceTrustRequiredDetails, type ServiceTrustRequiredReason, type ServiceUnavailableDetails, type ServiceUnavailableReason, } from './service-reason.js';
+export { CALLABLE_FINGERPRINT_MISMATCH, SCHEMA_REVISION_MISMATCH, SERVICE_CANDIDATE_INVALID, SERVICE_TRUST_REQUIRED, SERVICE_UNAVAILABLE, serviceErrorOf, type CallableFingerprintMismatchDetails, type CallableFingerprintMismatchReason, type SchemaRevisionMismatchDetails, type SchemaRevisionMismatchReason, type ServiceCandidateInvalidDetails, type ServiceCandidateInvalidReason, type ServiceErrorPayload, type ServiceReason, type ServiceTrustRequiredDetails, type ServiceTrustRequiredReason, type ServiceUnavailableDetails, type ServiceUnavailableReason, } from './service-reason.js';
 export { decodeStale, stale, type Stale } from './stale-route.js';
 export { decodeStreamFrame, type StreamEndFrame, type StreamErrorFrame, type StreamFrame, type StreamItemFrame, type StreamStartFrame, } from './stream.js';
 export { Target, targetPath, acceptCall, type Call } from './target.js';

package/dist/invocation/index.js

@@ -12,7 +12,7 @@ export { admitTrace, MAXIMUM_TRACEPARENT_BYTES, MAXIMUM_TRACESTATE_BYTES, MAXIMU
 export { acceptRouting } from './routing.js';
 export { acceptSchemaTarget } from './schema.js';
 export { decodeResponse, } from './response.js';
-export { SCHEMA_REVISION_MISMATCH, SERVICE_CANDIDATE_INVALID, SERVICE_TRUST_REQUIRED, SERVICE_UNAVAILABLE, serviceErrorOf, } from './service-reason.js';
+export { CALLABLE_FINGERPRINT_MISMATCH, SCHEMA_REVISION_MISMATCH, SERVICE_CANDIDATE_INVALID, SERVICE_TRUST_REQUIRED, SERVICE_UNAVAILABLE, serviceErrorOf, } from './service-reason.js';
 export { decodeStale, stale } from './stale-route.js';
 export { decodeStreamFrame, } from './stream.js';
 export { Target, targetPath, acceptCall } from './target.js';

package/dist/invocation/schema.d.ts

@@ -1,9 +1,16 @@
 import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
 import type { Sha256Digest } from '../publication/index.js';
-/** Source-Kernel precondition for the active Schema Registration selected by one invocation. */
+/**
+ * Source-Kernel precondition for one invocation: the exact installed artifact target, the Schema
+ * revision, or the fingerprint of the callable meaning the static consumer compiled against.
+ */
 export type SchemaTarget = {
     readonly target: Sha256Digest;
-} | {
+}
+/** @deprecated Pin the callable meaning with `fingerprint`; revision pinning will be removed. */
+ | {
     readonly revision: Revision;
+} | {
+    readonly fingerprint: Sha256Digest;
 };
 export declare function acceptSchemaTarget(input: unknown): SchemaTarget;

package/dist/invocation/schema.js

@@ -1,17 +1,18 @@
 import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
 import { digest, exactFields, invalid, portableObject } from './admission.js';
-const FIELDS = new Set(['target', 'revision']);
+const FIELDS = new Set(['target', 'revision', 'fingerprint']);
 export function acceptSchemaTarget(input) {
     const object = portableObject(input, 'schema target');
     exactFields(object, FIELDS, 'schema target');
-    const hasTarget = Object.hasOwn(object, 'target');
-    const hasRevision = Object.hasOwn(object, 'revision');
-    if (hasTarget === hasRevision) {
-        invalid('schema target must contain exactly one of target or revision');
+    if ([...FIELDS].filter((field) => Object.hasOwn(object, field)).length !== 1) {
+        invalid('schema target must contain exactly one of target, revision or fingerprint');
     }
-    if (hasTarget) {
+    if (Object.hasOwn(object, 'target')) {
         return Object.freeze({ target: digest(object.target, 'schema target.target') });
     }
+    if (Object.hasOwn(object, 'fingerprint')) {
+        return Object.freeze({ fingerprint: digest(object.fingerprint, 'schema target.fingerprint') });
+    }
     if (typeof object.revision !== 'string' || !patterns.revision.test(object.revision)) {
         invalid('schema target.revision must be a Schema revision');
     }

package/dist/invocation/service-reason.d.ts

@@ -1,18 +1,28 @@
 import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
 import type { Object as ValueObject } from '@astrale-os/kernel-dsl/value';
-import { type Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
 import type { ErrorPayload, ErrorReason } from '../errors/index.js';
+import type { Sha256Digest } from '../publication/index.js';
 import { CODES } from '../errors/index.js';
+/** @deprecated Emitted only for the deprecated revision pin; fingerprint pins report CALLABLE_FINGERPRINT_MISMATCH. */
 export declare const SCHEMA_REVISION_MISMATCH: 'SCHEMA_REVISION_MISMATCH';
+export declare const CALLABLE_FINGERPRINT_MISMATCH: 'CALLABLE_FINGERPRINT_MISMATCH';
 export declare const SERVICE_TRUST_REQUIRED: 'SERVICE_TRUST_REQUIRED';
 export declare const SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE';
 export declare const SERVICE_CANDIDATE_INVALID: 'SERVICE_CANDIDATE_INVALID';
+/** @deprecated Detail shape of the deprecated revision pin conflict. */
 export type SchemaRevisionMismatchDetails = ValueObject & {
     readonly origin: Key.Origin;
     readonly expectedRevision: Revision;
     readonly installedRevision: Revision;
 };
+export type CallableFingerprintMismatchDetails = ValueObject & {
+    readonly origin: Key.Origin;
+    readonly callable: Key.Callable;
+    readonly expectedFingerprint: Sha256Digest;
+    readonly installedFingerprint: Sha256Digest;
+};
 export type ServiceTrustRequiredDetails = ValueObject & {
     readonly origin: Key.Origin;
     readonly installedIssuer: IssuerId;
@@ -25,14 +35,16 @@ export type ServiceUnavailableDetails = ValueObject & {
 export type ServiceCandidateInvalidDetails = ValueObject & {
     readonly origin: Key.Origin;
 };
+/** @deprecated Detail shape of the deprecated revision pin conflict. */
 export type SchemaRevisionMismatchReason = ErrorReason<typeof SCHEMA_REVISION_MISMATCH, SchemaRevisionMismatchDetails>;
+export type CallableFingerprintMismatchReason = ErrorReason<typeof CALLABLE_FINGERPRINT_MISMATCH, CallableFingerprintMismatchDetails>;
 export type ServiceTrustRequiredReason = ErrorReason<typeof SERVICE_TRUST_REQUIRED, ServiceTrustRequiredDetails>;
 export type ServiceUnavailableReason = ErrorReason<typeof SERVICE_UNAVAILABLE, ServiceUnavailableDetails>;
 export type ServiceCandidateInvalidReason = ErrorReason<typeof SERVICE_CANDIDATE_INVALID, ServiceCandidateInvalidDetails>;
-export type ServiceReason = SchemaRevisionMismatchReason | ServiceTrustRequiredReason | ServiceUnavailableReason | ServiceCandidateInvalidReason;
+export type ServiceReason = SchemaRevisionMismatchReason | CallableFingerprintMismatchReason | ServiceTrustRequiredReason | ServiceUnavailableReason | ServiceCandidateInvalidReason;
 export type ServiceErrorPayload = (Omit<ErrorPayload, 'code' | 'data'> & {
     readonly code: typeof CODES.CONFLICT;
-    readonly data: SchemaRevisionMismatchReason | ServiceTrustRequiredReason;
+    readonly data: SchemaRevisionMismatchReason | CallableFingerprintMismatchReason | ServiceTrustRequiredReason;
 }) | (Omit<ErrorPayload, 'code' | 'data'> & {
     readonly code: typeof CODES.BACKEND_UNAVAILABLE;
     readonly data: ServiceUnavailableReason | ServiceCandidateInvalidReason;

package/dist/invocation/service-reason.js

@@ -1,8 +1,10 @@
 import { AuthValueError } from '@astrale-os/kernel-core/auth/error';
 import { accept as acceptIssuer } from '@astrale-os/kernel-core/auth/issuer';
-import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import { Key, patterns } from '@astrale-os/kernel-dsl/v1/addressing';
 import { CODES, reasonOf } from '../errors/index.js';
+/** @deprecated Emitted only for the deprecated revision pin; fingerprint pins report CALLABLE_FINGERPRINT_MISMATCH. */
 export const SCHEMA_REVISION_MISMATCH = 'SCHEMA_REVISION_MISMATCH';
+export const CALLABLE_FINGERPRINT_MISMATCH = 'CALLABLE_FINGERPRINT_MISMATCH';
 export const SERVICE_TRUST_REQUIRED = 'SERVICE_TRUST_REQUIRED';
 export const SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE';
 export const SERVICE_CANDIDATE_INVALID = 'SERVICE_CANDIDATE_INVALID';
@@ -16,6 +18,10 @@ export function serviceErrorOf(input) {
             return input.code === CODES.CONFLICT && schemaRevisionMismatchDetails(reason.details)
                 ? input
                 : undefined;
+        case CALLABLE_FINGERPRINT_MISMATCH:
+            return input.code === CODES.CONFLICT && callableFingerprintMismatchDetails(reason.details)
+                ? input
+                : undefined;
         case SERVICE_TRUST_REQUIRED:
             return input.code === CODES.CONFLICT && serviceTrustDetails(reason.details)
                 ? input
@@ -38,6 +44,15 @@ function schemaRevisionMismatchDetails(input) {
         isRevision(input.expectedRevision) &&
         isRevision(input.installedRevision));
 }
+function callableFingerprintMismatchDetails(input) {
+    return (exact(input, ['origin', 'callable', 'expectedFingerprint', 'installedFingerprint']) &&
+        isOrigin(input.origin) &&
+        typeof input.callable === 'string' &&
+        Key.is(input.callable) &&
+        Key.origin(input.callable) === input.origin &&
+        isDigest(input.expectedFingerprint) &&
+        isDigest(input.installedFingerprint));
+}
 function serviceTrustDetails(input) {
     return (exact(input, ['origin', 'installedIssuer', 'candidateIssuer']) &&
         isOrigin(input.origin) &&
@@ -60,6 +75,9 @@ function isOrigin(input) {
 function isRevision(input) {
     return typeof input === 'string' && patterns.revision.test(input);
 }
+function isDigest(input) {
+    return typeof input === 'string' && /^sha256:[0-9a-f]{64}$/u.test(input);
+}
 function isIssuer(input) {
     if (typeof input !== 'string')
         return false;

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

@@ -1,6 +1,8 @@
 import type { introspection } from '@astrale-os/kernel-core/schema';
-import type { DomainInfo, Limits, ResultFor } from './result.js';
+import type { DomainDependencies, DomainInfo, Limits, ResultFor } from './result.js';
 export declare const MEDIA_TYPE: 'application/vnd.astrale.schema-introspection.v2+msgpack';
 export declare function encode<Input extends introspection.Introspection>(input: Input, result: ResultFor<Input>): Promise<Uint8Array>;
 export declare function decode<Input extends introspection.Introspection>(input: Input, bytes: Uint8Array, limits: Limits): Promise<ResultFor<Input>>;
+/** Admit dependency bindings: origin-ordered, one per origin, each label agreeing with its revisions. */
+export declare function acceptDomainDependencies(input: unknown): DomainDependencies;
 export declare function acceptDomainInfo(input: unknown): DomainInfo;

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

@@ -11,7 +11,9 @@ export async function encode(input, result) {
     const request = admitRequest(input);
     const wire = request.kind === 'bundle'
         ? encodeDomainBundle(result)
-        : encodeDomainInfo(result);
+        : request.kind === 'dependencies'
+            ? encodeDomainDependencies(result)
+            : encodeDomainInfo(result);
     proveRequestedOrigin(request, result);
     // Non-literal specifiers keep msgpackr's Node-typed declarations out of consumers (see codecs/msgpack.ts).
     const { pack } = await import('msgpackr/pack');
@@ -40,17 +42,66 @@ export async function decode(input, bytes, limits) {
     }
     const result = (request.kind === 'bundle'
         ? decodeDomainBundle(decoded, limits.maximumBundleBytes)
-        : acceptDomainInfo(decoded));
+        : request.kind === 'dependencies'
+            ? acceptDomainDependencies(decoded)
+            : acceptDomainInfo(decoded));
     proveRequestedOrigin(request, result);
     return result;
 }
 function proveRequestedOrigin(request, result) {
-    const origin = request.kind === 'bundle'
-        ? result.domain.origin
-        : result.origin;
+    const origin = request.kind === 'inspect'
+        ? result.origin
+        : result.domain.origin;
     if (origin !== request.origin)
         invalid('Schema introspection evidence does not match the requested origin.');
 }
+function encodeDomainDependencies(input) {
+    const admitted = acceptDomainDependencies(input);
+    return Object.freeze({
+        domain: encodeDomainInfo(admitted.domain),
+        dependencies: admitted.dependencies.map((binding) => ({ ...binding })),
+    });
+}
+/** Admit dependency bindings: origin-ordered, one per origin, each label agreeing with its revisions. */
+export function acceptDomainDependencies(input) {
+    const value = record(input, 'Domain dependencies result');
+    exact(value, ['dependencies', 'domain'], 'Domain dependencies result');
+    const domain = acceptDomainInfo(value.domain);
+    if (!Array.isArray(value.dependencies))
+        invalid('Domain dependency bindings are invalid.');
+    const dependencies = value.dependencies.map(acceptDependencyBinding);
+    for (const [index, binding] of dependencies.entries()) {
+        const previous = dependencies[index - 1];
+        if (previous !== undefined && previous.origin >= binding.origin) {
+            invalid('Domain dependency bindings must be origin-ordered and unique.');
+        }
+        if (binding.origin === domain.origin)
+            invalid('Domain dependency bindings cannot name the Domain.');
+    }
+    return Object.freeze({ domain, dependencies: Object.freeze(dependencies) });
+}
+function acceptDependencyBinding(input) {
+    const value = record(input, 'Domain dependency binding');
+    exact(value, ['active', 'binding', 'origin', 'pinned'], 'Domain dependency binding');
+    if (typeof value.origin !== 'string' || !patterns.origin.test(value.origin)) {
+        invalid('Domain dependency binding origin is invalid.');
+    }
+    if (typeof value.pinned !== 'string' || !patterns.revision.test(value.pinned)) {
+        invalid('Domain dependency binding pinned revision is invalid.');
+    }
+    if (typeof value.active !== 'string' || !patterns.revision.test(value.active)) {
+        invalid('Domain dependency binding active revision is invalid.');
+    }
+    const expected = value.pinned === value.active ? 'exact' : 'retained';
+    if (value.binding !== expected)
+        invalid('Domain dependency binding label is invalid.');
+    return Object.freeze({
+        origin: value.origin,
+        pinned: value.pinned,
+        active: value.active,
+        binding: expected,
+    });
+}
 function encodeDomainBundle(input) {
     exact(input, ['bundle', 'domain'], 'Domain Bundle result');
     const admittedDomain = acceptDomainInfo(input.domain);
@@ -172,7 +223,7 @@ function capabilities(input) {
 function admitRequest(input) {
     const value = record(input, 'Schema introspection request');
     exact(value, ['kind', 'origin'], 'Schema introspection request');
-    if (value.kind !== 'inspect' && value.kind !== 'bundle') {
+    if (value.kind !== 'inspect' && value.kind !== 'bundle' && value.kind !== 'dependencies') {
         invalid('Schema introspection kind is invalid.');
     }
     if (typeof value.origin !== 'string' || !patterns.origin.test(value.origin)) {

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

@@ -1,2 +1,2 @@
-export { MEDIA_TYPE, acceptDomainInfo, decode, encode } from './codec.js';
-export type { Digest, DomainBundle, DomainInfo, Limits, ResultFor } from './result.js';
+export { MEDIA_TYPE, acceptDomainDependencies, acceptDomainInfo, decode, encode } from './codec.js';
+export type { DependencyBinding, Digest, DomainBundle, DomainDependencies, DomainInfo, Limits, ResultFor, } from './result.js';

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

@@ -1 +1 @@
-export { MEDIA_TYPE, acceptDomainInfo, decode, encode } from './codec.js';
+export { MEDIA_TYPE, acceptDomainDependencies, acceptDomainInfo, decode, encode } from './codec.js';

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

@@ -20,9 +20,27 @@ export interface DomainBundle {
     readonly domain: DomainInfo;
     readonly bundle: bundle.Bundle;
 }
+/**
+ * How one ready Domain generation binds one dependency of its exact closure: `exact` when the
+ * pinned revision is the one the Kernel serves, `retained` when the Kernel serves another revision
+ * and keeps the pinned one as inactive context admitted by unchanged meaning.
+ */
+export interface DependencyBinding {
+    readonly origin: Key.Origin;
+    readonly pinned: Revision;
+    readonly active: Revision;
+    readonly binding: 'exact' | 'retained';
+}
+/** The origin-ordered dependency bindings observed coherently with a ready Domain generation. */
+export interface DomainDependencies {
+    readonly domain: DomainInfo;
+    readonly dependencies: readonly DependencyBinding[];
+}
 export type ResultFor<Input extends introspection.Introspection> = Input extends {
     readonly kind: 'bundle';
-} ? DomainBundle : DomainInfo;
+} ? DomainBundle : Input extends {
+    readonly kind: 'dependencies';
+} ? DomainDependencies : DomainInfo;
 export interface Limits {
     readonly maximumPublicationBytes: number;
     readonly maximumBundleBytes: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-protocol",
-  "version": "0.5.0-beta.55",
+  "version": "0.5.0-beta.56",
   "description": "Portable Astrale invocation, publication, installation, routing, and issuer protocols",
   "license": "Apache-2.0",
   "repository": {
@@ -137,8 +137,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.49",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.34",
+    "@astrale-os/kernel-core": "0.9.0-beta.50",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.35",
     "@noble/hashes": "2.3.0"
   },
   "devDependencies": {