@astrale-os/kernel-dsl 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/v1/schema/compatibility/model.d.ts

@@ -46,7 +46,7 @@ export interface Usage {
     readonly key?: Key;
     readonly relation: ReferenceSite | 'member' | 'abstract' | 'selection' | 'capability';
 }
-export type Facet = 'class.reference' | 'class.inherit' | 'class.composition' | 'class.properties' | 'class.endpoints' | 'property' | 'property.required' | 'method.existence' | 'method.object' | 'method.inheritance' | 'method.signature' | 'function.existence' | 'function.signature' | 'policy' | 'view' | 'core';
+export type Facet = 'class.reference' | 'class.inherit' | 'class.composition' | 'class.properties' | 'class.endpoints' | 'class.inheritance' | 'property' | 'property.required' | 'method.existence' | 'method.object' | 'method.inheritance' | 'method.signature' | 'function.existence' | 'function.signature' | 'policy' | 'view' | 'core';
 /** A fact about a compared facet, including unchanged facets. No admission decision is implied. */
 export interface Observation {
     readonly id: string;
@@ -81,8 +81,9 @@ export interface Assessment {
  * meaning evidence never records whether capabilities were declared. A referenced or inherited Class
  * that loses an effective Property (`class.properties`) raises structure to version 4 and meaning to
  * version 2, and structure is version 4 too when it records that a dependent Policy lost what it
- * relies on (`method.object`, `class.endpoints`). Those facts are recorded only on such a loss, so
- * every other comparison, every compatible one included, keeps its bytes.
+ * relies on (`method.object`, `class.endpoints`) or that a Class the dependent extends became final
+ * (`class.inheritance`). Those facts are recorded only on such a loss, so every other comparison,
+ * every compatible one included, keeps its bytes.
  */
 export interface ComparisonEvidence {
     readonly kind: 'structure' | 'meaning';

package/dist/v1/schema/compatibility/structure/index.js

@@ -12,8 +12,9 @@ export function analyzeStructure(context) {
         ...result,
         compatible: result.assessments.every(({ satisfied }) => satisfied),
         // Each version adds one requirement policy and applies only when its fact is present: 3 a
-        // declared capability root, 4 a lost effective Property of a reached Class or a failed Policy
-        // reliance, facts recorded only when they fail. Without one, evidence keeps its version-2 bytes.
+        // declared capability root, 4 a lost effective Property of a reached Class, a failed Policy
+        // reliance or a refused extension, facts recorded only when they fail. Without one, evidence
+        // keeps its version-2 bytes.
         evidence: evidenceOf({
             kind: 'structure',
             version: recordsFailureOnlyFact(result.assessments)
@@ -27,13 +28,14 @@ export function analyzeStructure(context) {
 }
 /**
  * The facts structure records only when they fail: a referenced or inherited Class that lost an
- * effective Property, and what a dependent Policy relies on (a Method object, a matched Edge's
- * endpoints).
+ * effective Property, what a dependent Policy relies on (a Method object, a matched Edge's
+ * endpoints), and a Class the dependent extends that became final.
  */
 const FAILURE_ONLY_FACETS = new Set([
     'class.properties',
     'method.object',
     'class.endpoints',
+    'class.inheritance',
 ]);
 function recordsFailureOnlyFact(assessments) {
     return assessments.some(({ requirement }) => FAILURE_ONLY_FACETS.has(requirement.kind));

package/dist/v1/schema/compatibility/structure/requirements.js

@@ -1,5 +1,6 @@
 import { Key } from '../../../addressing/index.js';
-import { compareAddedProperties, compareLostProperties } from '../comparators/classes.js';
+import { inheritanceOf } from '../../../language/class/inheritance.js';
+import { compareAddedProperties, compareLostProperties, inheritanceMeaning, } from '../comparators/classes.js';
 import { compareFacet } from '../comparators/index.js';
 import { fingerprintMeaning } from '../comparators/values.js';
 import { contextInvalid } from '../context.js';
@@ -73,6 +74,7 @@ export function compareRequirements({ context, report, }) {
             compareLostProperties({ pair, report });
     }
     compareReliance({ context, report });
+    compareExtension({ context, report });
 }
 /**
  * What a dependent Policy relies on is recorded only when it fails: a Method it names that is gone
@@ -95,3 +97,29 @@ function compareReliance({ context, report, }) {
         report.record({ pair, facet, before, after, requirement: { kind: facet } });
     }
 }
+/**
+ * A Class one of the dependent's own Classes extends must still admit it: the dependent is refused
+ * once the compared origin declares that Class `'final'`. The fact is recorded only when it fails,
+ * like a Policy reliance, so a compatible comparison keeps its evidence bytes.
+ */
+function compareExtension({ context, report, }) {
+    for (const reference of context.roots) {
+        if (reference.usage.relation !== 'extends')
+            continue;
+        if (Key.origin(reference.coordinate.key) !== context.source.origin)
+            continue;
+        const pair = context.pair(reference.coordinate);
+        if (pair.source?.kind !== 'class' || pair.target?.kind !== 'class')
+            continue;
+        if (pair.target.analysis.declaration.inheritance !== 'final')
+            continue;
+        report.note(reference);
+        report.record({
+            pair,
+            facet: 'class.inheritance',
+            before: inheritanceMeaning(inheritanceOf(pair.source.analysis.declaration)),
+            after: inheritanceMeaning('final'),
+            requirement: { kind: 'class.inheritance' },
+        });
+    }
+}

package/dist/v1/schema/compatibility/versioning/surface.d.ts

@@ -1,7 +1,7 @@
 import type { Report } from '../report.js';
 import type { ComparisonContext } from '../scope.js';
 /**
- * Compare inherited contracts and newly imposed obligations on existing Classes.
+ * Compare inherited contracts, newly imposed obligations and who may extend existing Classes.
  * Obligations are reported at their declaring Method: changed signatures retain their comparison;
  * an unchanged obligation newly inherited by a Class is added and unsatisfied.
  */

package/dist/v1/schema/compatibility/versioning/surface.js

@@ -1,10 +1,11 @@
+import { inheritanceOf } from '../../../language/class/inheritance.js';
 import { methodInheritance } from '../comparators/callables.js';
-import { compareAddedProperties } from '../comparators/classes.js';
+import { compareAddedProperties, inheritanceMeaning } from '../comparators/classes.js';
 import { compareFacet } from '../comparators/index.js';
 import { fingerprintMeaning } from '../comparators/values.js';
 import { classCoordinate, methodCoordinate } from '../coordinate.js';
 /**
- * Compare inherited contracts and newly imposed obligations on existing Classes.
+ * Compare inherited contracts, newly imposed obligations and who may extend existing Classes.
  * Obligations are reported at their declaring Method: changed signatures retain their comparison;
  * an unchanged obligation newly inherited by a Class is added and unsatisfied.
  */
@@ -25,6 +26,7 @@ export function compareSurface({ context, report, }) {
             requirement: { kind: 'class.inherit' },
         });
         compareAddedProperties({ context, pair, report });
+        compareExtension({ pair, report });
         for (const [key, method] of source.analysis.requirements)
             if (!established.has(key))
                 established.set(key, method);
@@ -54,6 +56,27 @@ export function compareSurface({ context, report, }) {
             });
     }
 }
+/**
+ * A changed inheritance is observed on its Class, and is major when the Class was `'open'` or
+ * becomes `'final'`. Closing an `'open'` Class withdraws what its declaration granted other Domains;
+ * acceptance refuses a subclass of a `'final'` Class of any Domain and admits one of another
+ * Domain's `'internal'` Class (DV-CLASS-INHERITANCE), so finalizing that Class can refuse a dependent.
+ */
+function compareExtension({ pair, report, }) {
+    if (pair.source?.kind !== 'class' || pair.target?.kind !== 'class')
+        return;
+    const before = inheritanceOf(pair.source.analysis.declaration);
+    const after = inheritanceOf(pair.target.analysis.declaration);
+    if (before === after)
+        return;
+    report.record({
+        pair,
+        facet: 'class.inheritance',
+        before: inheritanceMeaning(before),
+        after: inheritanceMeaning(after),
+        requirement: { kind: 'class.inheritance', satisfied: before !== 'open' && after !== 'final' },
+    });
+}
 function changed({ before, after }) {
     return (before === undefined ||
         after === undefined ||

package/dist/v1/schema/diagnostic.d.ts

@@ -1,4 +1,4 @@
-export type SchemaDiagnosticCode = 'DM_CAPABILITY_INVALID' | 'DM_MEMBER_ROOT_INVALID' | 'DM_DEPENDENCY_CONTEXT_INVALID' | 'DM_DEPENDENCY_NOT_RETAINED' | 'DM_MEANING_INCONSISTENT' | 'DM_MEMBER_ORIGIN_MISMATCH' | 'DV_ACCEPTANCE_CONTEXT' | 'DV_CALLABLE_AUTH' | 'DV_CALLABLE_IO' | 'DV_CALLABLE_POLICY_AUTH' | 'DV_CLASS_ABSTRACT' | 'DV_CLASS_ACYCLIC' | 'DV_CLASS_KIND' | 'DV_CORE_EDGE_CLASS' | 'DV_CORE_EDGE_CONSTRAINTS' | 'DV_CORE_EDGE_KEY' | 'DV_CORE_EDGE_PROPERTIES' | 'DV_CORE_NODE_CLASS' | 'DV_CORE_NODE_PROPERTIES' | 'DV_CORE_REF' | 'DV_DATA_COMPOSITION' | 'DV_DEPENDENCY_ACYCLIC' | 'DV_DEPENDENCY_DIRECT' | 'DV_DEPENDENCY_EXACT' | 'DV_DEPENDENCY_LIMITS' | 'DV_DEPENDENCY_REVISION_COHERENCE' | 'DV_DEPENDENCY_UNIQUE' | 'DV_EDGE_ACCEPTS' | 'DV_EDGE_CLASS_COMPOSITION' | 'DV_EDGE_CONSTRAINT' | 'DV_EDGE_FOREIGN_MINIMUM' | 'DV_EDGE_ROLE' | 'DV_EDGE_UNDIRECTED' | 'DV_ENTRYPOINT' | 'DV_JSON_VALUE' | 'DV_METHOD_ABSTRACT' | 'DV_METHOD_COMPOSITION' | 'DV_PROPERTY_AUTO' | 'DV_PROPERTY_COMPOSITION' | 'DV_PROPERTY_IMMUTABLE' | 'DV_PROPERTY_STATE' | 'DV_REF_RESOLVES' | 'DV_VALUE_SCHEMA' | 'PL_BUDGET' | 'PL_COMPOSITION' | 'PL_CONNECTIVITY' | 'PL_REF' | 'PL_REPEAT' | 'PL_TARGET' | 'PL_TYPING' | 'PL_USE' | 'PL_VARIABLE_SCOPE' | 'STRUCTURE_ABSTRACT_POLICY' | 'STRUCTURE_CALLABLE_POLICY_AUTH' | 'STRUCTURE_DUPLICATE_ITEM' | 'STRUCTURE_EDGE_ORIENTATION' | 'STRUCTURE_FORMAT' | 'STRUCTURE_INVALID' | 'STRUCTURE_KEY' | 'STRUCTURE_MAXIMUM' | 'STRUCTURE_MINIMUM' | 'STRUCTURE_MULTIPLE' | 'STRUCTURE_REQUIRED' | 'STRUCTURE_TYPE' | 'STRUCTURE_UNION' | 'STRUCTURE_UNKNOWN_FIELD' | 'STRUCTURE_VALUE' | 'UNSUPPORTED_DOCUMENT_FORMAT' | 'UNSUPPORTED_DSL_VERSION';
+export type SchemaDiagnosticCode = 'DM_CAPABILITY_INVALID' | 'DM_MEMBER_ROOT_INVALID' | 'DM_DEPENDENCY_CONTEXT_INVALID' | 'DM_DEPENDENCY_NOT_RETAINED' | 'DM_MEANING_INCONSISTENT' | 'DM_MEMBER_ORIGIN_MISMATCH' | 'DV_ACCEPTANCE_CONTEXT' | 'DV_CALLABLE_ADMISSION' | 'DV_CALLABLE_AUTH' | 'DV_CALLABLE_IO' | 'DV_CALLABLE_POLICY_AUTH' | 'DV_CLASS_ABSTRACT' | 'DV_CLASS_ACYCLIC' | 'DV_CLASS_INHERITANCE' | 'DV_CLASS_KIND' | 'DV_CORE_EDGE_CLASS' | 'DV_CORE_EDGE_CONSTRAINTS' | 'DV_CORE_EDGE_KEY' | 'DV_CORE_EDGE_PROPERTIES' | 'DV_CORE_NODE_CLASS' | 'DV_CORE_NODE_PROPERTIES' | 'DV_CORE_REF' | 'DV_DATA_COMPOSITION' | 'DV_DEPENDENCY_ACYCLIC' | 'DV_DEPENDENCY_DIRECT' | 'DV_DEPENDENCY_EXACT' | 'DV_DEPENDENCY_LIMITS' | 'DV_DEPENDENCY_REVISION_COHERENCE' | 'DV_DEPENDENCY_UNIQUE' | 'DV_EDGE_ACCEPTS' | 'DV_EDGE_CLASS_COMPOSITION' | 'DV_EDGE_CONSTRAINT' | 'DV_EDGE_FOREIGN_MINIMUM' | 'DV_EDGE_ROLE' | 'DV_EDGE_UNDIRECTED' | 'DV_ENTRYPOINT' | 'DV_JSON_VALUE' | 'DV_METHOD_ABSTRACT' | 'DV_METHOD_COMPOSITION' | 'DV_PROPERTY_AUTO' | 'DV_PROPERTY_COMPOSITION' | 'DV_PROPERTY_IMMUTABLE' | 'DV_PROPERTY_STATE' | 'DV_REF_RESOLVES' | 'DV_VALUE_SCHEMA' | 'PL_BUDGET' | 'PL_COMPOSITION' | 'PL_CONNECTIVITY' | 'PL_REF' | 'PL_REPEAT' | 'PL_TARGET' | 'PL_TYPING' | 'PL_USE' | 'PL_VARIABLE_SCOPE' | 'STRUCTURE_ABSTRACT_POLICY' | 'STRUCTURE_CALLABLE_POLICY_AUTH' | 'STRUCTURE_DUPLICATE_ITEM' | 'STRUCTURE_EDGE_ORIENTATION' | 'STRUCTURE_FORMAT' | 'STRUCTURE_INVALID' | 'STRUCTURE_KEY' | 'STRUCTURE_MAXIMUM' | 'STRUCTURE_MINIMUM' | 'STRUCTURE_MULTIPLE' | 'STRUCTURE_REQUIRED' | 'STRUCTURE_TYPE' | 'STRUCTURE_UNION' | 'STRUCTURE_UNKNOWN_FIELD' | 'STRUCTURE_VALUE' | 'UNSUPPORTED_DOCUMENT_FORMAT' | 'UNSUPPORTED_DSL_VERSION';
 export interface SchemaDiagnostic<out Code extends SchemaDiagnosticCode = SchemaDiagnosticCode> {
     readonly code: Code;
     readonly pointer: string;

package/dist/v1/schema/normalization/domain.js

@@ -61,6 +61,7 @@ function canonicalizeClass(value) {
         ref: value.ref,
         kind: value.kind,
         abstract: value.abstract,
+        ...(value.inheritance === undefined ? {} : { inheritance: value.inheritance }),
         extends: [...value.extends].sort(compareDefinitionRefs),
         properties: mapRecord(value.properties, canonicalizeProperty),
     };
@@ -80,6 +81,7 @@ function canonicalizeClass(value) {
             endpoints: canonicalizeDirectedEndpoints(value.endpoints),
             policies: value.policies,
             constraints: value.constraints,
+            ...(value.unique === undefined ? {} : { unique: value.unique }),
         }
         : {
             ...base,
@@ -115,6 +117,8 @@ function canonicalizeCallable(value) {
         output: canonicalizeCallableOutput(value.output),
         // Ordinary execution has one canonical form, so existing revisions never move.
         ...(value.execution?.durable === true ? { execution: { durable: true } } : {}),
+        // Absence is the one spelling of a call admitted afresh; validation refuses any other.
+        ...(value.admission === undefined ? {} : { admission: { maxAge: value.admission.maxAge } }),
     };
     return value.auth === 'authorized'
         ? {

package/dist/v1/schema/validation/callable.d.ts

@@ -1,4 +1,4 @@
 import type { SchemaDiagnostic } from '../diagnostic.js';
 import type { DomainSchemaIR } from '../model/schema.js';
-/** Validate the execution modifier of every local Function and Node Method. */
+/** Validate the execution modifier and admission age of every local Function and Node Method. */
 export declare function validateCallables(schema: DomainSchemaIR): readonly SchemaDiagnostic[];

package/dist/v1/schema/validation/callable.js

@@ -1,10 +1,13 @@
+import { isAdmissionMaxAge, MAXIMUM_ADMISSION_AGE_SECONDS, } from '../../language/callable/admission.js';
 import { isBinaryInput } from '../../language/callable/model/callable.js';
 import { diagnostic } from '../diagnostic.js';
-/** Validate the execution modifier of every local Function and Node Method. */
+/** Validate the execution modifier and admission age of every local Function and Node Method. */
 export function validateCallables(schema) {
     const diagnostics = [];
     for (const [name, declaration] of Object.entries(schema.functions)) {
-        validateExecution(declaration, `/functions/${escapePointer(name)}`, diagnostics);
+        const pointer = `/functions/${escapePointer(name)}`;
+        validateExecution(declaration, pointer, diagnostics);
+        validateAdmission(declaration, pointer, diagnostics);
     }
     for (const [name, declaration] of Object.entries(schema.classes)) {
         if (declaration.kind !== 'node')
@@ -12,10 +15,22 @@ export function validateCallables(schema) {
         for (const [method, value] of Object.entries(declaration.methods)) {
             const pointer = `/classes/${escapePointer(name)}/methods/${escapePointer(method)}`;
             validateExecution(value, pointer, diagnostics);
+            validateAdmission(value, pointer, diagnostics);
         }
     }
     return Object.freeze(diagnostics);
 }
+/**
+ * An admission age is a whole number of seconds within the language ceiling. It has no zero
+ * spelling: an absent admission age is the one canonical form of a call admitted afresh.
+ */
+function validateAdmission(declaration, pointer, diagnostics) {
+    if (declaration.admission === undefined)
+        return;
+    if (isAdmissionMaxAge(declaration.admission.maxAge))
+        return;
+    diagnostics.push(diagnostic('DV_CALLABLE_ADMISSION', `${pointer}/admission/maxAge`, `An admission age is an integer number of seconds from 1 to ${MAXIMUM_ADMISSION_AGE_SECONDS}; omit it to admit every call afresh.`));
+}
 /**
  * An Execution records its initiating caller and its admitted input, from which the run is
  * resubmitted, and retains one portable outcome. A durable callable therefore needs a known caller,

package/dist/v1/schema/validation/class.js

@@ -87,9 +87,15 @@ function validateFacet(environment, declaration, pointer, diagnostics) {
         return;
     for (const [name, method] of Object.entries(declaration.methods)) {
         const methodPointer = `${pointer}/methods/${escapePointer(name)}`;
-        if (!isMethodExecutable(declaration, method) && method.policy !== undefined) {
+        if (isMethodExecutable(declaration, method))
+            continue;
+        if (method.policy !== undefined) {
             diagnostics.push(diagnostic('DV_METHOD_ABSTRACT', `${methodPointer}/policy`, 'Abstract Methods cannot have a Policy.'));
         }
+        // An admission age qualifies the admission of an executable declaration, like its Policy.
+        if (method.admission !== undefined) {
+            diagnostics.push(diagnostic('DV_METHOD_ABSTRACT', `${methodPointer}/admission`, 'Abstract Methods cannot have an admission age.'));
+        }
     }
 }
 function validateParents(environment, owner, ownerKind, parents, diagnostics) {
@@ -103,6 +109,9 @@ function validateParents(environment, owner, ownerKind, parents, diagnostics) {
         if (target.ref.kind !== 'class' || target.declaration.kind !== ownerKind) {
             diagnostics.push(diagnostic('DV_CLASS_KIND', pointer, `${formatDefinitionRef(owner)} cannot extend different-kind Class ${formatDefinitionRef(parent)}.`, formatDefinitionRef(parent)));
         }
+        else if (target.declaration.inheritance === 'final') {
+            diagnostics.push(diagnostic('DV_CLASS_INHERITANCE', pointer, `${formatDefinitionRef(owner)} cannot extend final Class ${formatDefinitionRef(parent)}.`, formatDefinitionRef(parent)));
+        }
     }
 }
 function validateEdgeContract(environment, owner, declaration, diagnostics) {

package/dist/v1/schema/validation/domain.structure.js

@@ -98,6 +98,9 @@ const edgeConstraintsSchema = strictObject({
     noSelf: literal(true).optional(),
     acyclic: literal(true).optional(),
 });
+// A tuple names the source and the slug. No tuple is spelled by the absence of the field, never by
+// an empty list: one spelling per meaning, one revision.
+const edgeUniqueSchema = uniqueArray(tuple([literal('source'), literal('slug')])).min(1);
 const policyPatternSubjectSchema = strictObject({ kind: literal('subject') });
 const policyPatternObjectSchema = strictObject({ kind: literal('object') });
 const policyPatternSourceSchema = strictObject({ kind: literal('source') });
@@ -195,11 +198,16 @@ const valueFunctionInputSchema = jsonSchemaSchema.refine((value) => typeof value
 const callableExecutionSchema = strictObject({
     durable: boolean(),
 });
+// Its range is language meaning, refused by callable validation with DV_CALLABLE_ADMISSION.
+const callableAdmissionSchema = strictObject({
+    maxAge: number(),
+});
 const callableShape = {
     description: descriptionSchema.optional(),
     input: jsonSchemaSchema,
     output: callableOutputSchema,
     execution: callableExecutionSchema.optional(),
+    admission: callableAdmissionSchema.optional(),
     auth: enumeration(['anonymous', 'authenticated', 'authorized']),
     policy: union([literal(true), policyCheckExpressionSchema]).optional(),
 };
@@ -228,10 +236,13 @@ const edgeClassPoliciesSchema = strictObject({
     read: classPolicySchema.optional(),
     traverse: classPolicySchema.optional(),
 });
+// The default `'internal'` is the absence of the field: one spelling per meaning, one revision.
+const inheritanceSchema = enumeration(['open', 'final']);
 const nodeClassSchema = strictObject({
     ref: classRefSchema,
     kind: literal('node'),
     abstract: boolean(),
+    inheritance: inheritanceSchema.optional(),
     description: descriptionSchema.optional(),
     extends: uniqueArray(classRefSchema),
     properties: propertyRecordSchema,
@@ -244,10 +255,12 @@ const edgeClassShape = {
     ref: classRefSchema,
     kind: literal('edge'),
     abstract: boolean(),
+    inheritance: inheritanceSchema.optional(),
     description: descriptionSchema.optional(),
     extends: uniqueArray(classRefSchema),
     properties: propertyRecordSchema,
     constraints: edgeConstraintsSchema,
+    unique: edgeUniqueSchema.optional(),
 };
 const edgeClassSchema = strictObject({
     ...edgeClassShape,
@@ -257,14 +270,22 @@ const edgeClassSchema = strictObject({
 }).superRefine(validateEdgeOrientationShape);
 const classDeclarationSchema = discriminatedUnion('kind', [nodeClassSchema, edgeClassSchema]);
 function validateEdgeOrientationShape(value, context) {
-    if ((value.orientation === 'undirected') === Array.isArray(value.endpoints))
-        return;
-    context.addIssue({
-        code: 'custom',
-        path: ['endpoints'],
-        message: `${value.orientation} Edge endpoints have the wrong structural shape.`,
-        params: { structureCode: 'STRUCTURE_EDGE_ORIENTATION' },
-    });
+    if ((value.orientation === 'undirected') !== Array.isArray(value.endpoints)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['endpoints'],
+            message: `${value.orientation} Edge endpoints have the wrong structural shape.`,
+            params: { structureCode: 'STRUCTURE_EDGE_ORIENTATION' },
+        });
+    }
+    if (value.orientation === 'undirected' && value.unique !== undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['unique'],
+            message: 'Only a directed Edge Class declares unique tuples.',
+            params: { structureCode: 'STRUCTURE_EDGE_ORIENTATION' },
+        });
+    }
 }
 const functionDefinitionSchema = strictObject({
     ref: functionRefSchema,

package/dist/value/canonical.d.ts

@@ -5,3 +5,8 @@ export declare function serialize(input: unknown, options?: Options): string;
 /** Serialize a trusted portable value whose default structural admission proof is still valid. */
 export declare function serializeAdmitted(input: Value): string;
 export declare function encode(input: unknown, options?: Options): Uint8Array;
+/**
+ * The UTF-8 byte length of a trusted Value's canonical JSON, `encode(input).byteLength`: an
+ * admission-owned immutable root counted its bytes when it was admitted, so it is not serialized.
+ */
+export declare function byteLength(input: Value): number;

package/dist/value/canonical.js

@@ -31,6 +31,18 @@ function serializeSnapshot(input, maxBytes) {
 export function encode(input, options) {
     return encoder.encode(serialize(input, options));
 }
+/**
+ * The UTF-8 byte length of a trusted Value's canonical JSON, `encode(input).byteLength`: an
+ * admission-owned immutable root counted its bytes when it was admitted, so it is not serialized.
+ */
+export function byteLength(input) {
+    if (input !== null && typeof input === 'object') {
+        const bytes = immutableSnapshotBytes(input);
+        if (bytes !== undefined)
+            return bytes;
+    }
+    return utf8Length(serializeAdmitted(input));
+}
 function serializeValue(value) {
     if (value === null)
         return 'null';

package/dist/value/json.d.ts

@@ -1,3 +1,3 @@
-export { encode, serialize, serializeAdmitted } from './canonical.js';
+export { byteLength, encode, serialize, serializeAdmitted } from './canonical.js';
 export { decode } from './decode.js';
 export { DecodeError } from './error.js';

package/dist/value/json.js

@@ -1,3 +1,3 @@
-export { encode, serialize, serializeAdmitted } from './canonical.js';
+export { byteLength, encode, serialize, serializeAdmitted } from './canonical.js';
 export { decode } from './decode.js';
 export { DecodeError } from './error.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-dsl",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "description": "Astrale Kernel DSL - Schema authoring, inference, and IR serialization",
   "license": "Apache-2.0",
   "repository": {