@astrale-os/kernel-dsl 0.2.0-beta.8 → 1.0.0-beta.1

package/dist/value/accept.js

@@ -1,15 +1,53 @@
 import { BoundaryError } from './error.js';
+import { includeSnapshot, retainImmutableSnapshot, reusableSnapshot, } from './immutable.optimization.js';
 import { limitsFor } from './limits.js';
-import { assertHostString } from './unicode.js';
+import { assertHostString, canonicalPrimitiveBytes } from './unicode.js';
 /**
  * Admit an unknown host value and return a detached portable snapshot.
  *
  * Every source property is obtained from one descriptor snapshot. Accessors are never invoked.
  */
 export function accept(input, options) {
-    const state = { active: new WeakSet(), limits: limitsFor(options), members: 0 };
+    return snapshot(input, options, 'copy');
+}
+/** Admit a canonically byte-bounded immutable snapshot; owned subtrees may be shared. */
+export function acceptImmutable(input, options) {
+    const captured = { propertyRoots: false };
+    const value = snapshot(input, options, 'immutable', captured);
+    if (value !== null && typeof value === 'object') {
+        retainImmutableSnapshot(value, captured.summary);
+    }
+    return value;
+}
+/** Admit a read-only snapshot, sharing owned immutable subtrees without freezing new wrappers. */
+export function acceptForRead(input, options) {
+    return snapshot(input, options, 'read');
+}
+/**
+ * Private PropertyValues owner seam. Retain immediate recursive values, not the enclosing
+ * dictionary: its canonical coordinates are re-admitted by the Property owner on every use.
+ */
+export function acceptPropertyRoot(input) {
+    return snapshot(input, undefined, 'immutable', { propertyRoots: true });
+}
+function snapshot(input, options, mode, captured) {
+    const state = {
+        active: new WeakSet(),
+        limits: limitsFor(options),
+        members: 0,
+        bytes: mode === 'immutable' && !captured?.propertyRoots ? 0 : undefined,
+        mode,
+        summary: mode === 'immutable' && !captured?.propertyRoots
+            ? { members: 0, depth: 0, stringBytes: 0, canonicalBytes: 0 }
+            : undefined,
+        summaryDepth: 0,
+        propertyRoots: captured?.propertyRoots ?? false,
+    };
     try {
-        return admit(input, '', 0, state);
+        const value = admit(input, '', 0, state);
+        if (captured !== undefined)
+            captured.summary = state.summary;
+        return value;
     }
     catch (error) {
         if (error instanceof BoundaryError)
@@ -18,8 +56,10 @@ export function accept(input, options) {
     }
 }
 function admit(input, pointer, depth, state) {
-    if (input === null || typeof input === 'boolean')
+    if (input === null || typeof input === 'boolean') {
+        addCanonicalBytes(state, input === false ? 5 : 4, pointer);
         return input;
+    }
     if (typeof input === 'number') {
         if (!Number.isFinite(input)) {
             throw new BoundaryError('VALUE_NUMBER', 'Expected a finite IEEE-754 binary64 number', pointer);
@@ -27,15 +67,26 @@ function admit(input, pointer, depth, state) {
         if (Object.is(input, -0)) {
             throw new BoundaryError('VALUE_NUMBER', 'Negative zero is outside portable JSON', pointer);
         }
+        if (state.summary !== undefined || state.bytes !== undefined)
+            addCanonicalBytes(state, canonicalPrimitiveBytes(input), pointer);
         return input;
     }
     if (typeof input === 'string') {
-        assertHostString(input, pointer, state.limits.maxStringBytes);
+        admitString(input, pointer, state);
         return input;
     }
     if (typeof input !== 'object') {
         throw new BoundaryError('VALUE_TYPE', 'Expected a portable value', pointer);
     }
+    if (state.mode !== 'copy' && !(state.propertyRoots && depth === 0)) {
+        const summary = reusableSnapshot(input, state.limits, depth, state.members, state.bytes);
+        if (summary !== undefined) {
+            state.members += summary.members;
+            chargeCanonicalBytes(state, summary.canonicalBytes, pointer);
+            includeSnapshot(state.summary, summary, depth - state.summaryDepth);
+            return input;
+        }
+    }
     if (state.active.has(input)) {
         throw new BoundaryError('VALUE_CYCLE', 'Cyclic object graphs are not portable values', pointer);
     }
@@ -43,13 +94,33 @@ function admit(input, pointer, depth, state) {
         throw new BoundaryError('VALUE_LIMIT', `Container depth exceeds the ${state.limits.maxDepth}-level limit`, pointer);
     }
     state.active.add(input);
+    const parent = state.summary;
+    const parentDepth = state.summaryDepth;
+    const propertyRoot = state.mode === 'immutable' && state.propertyRoots && depth === 1;
+    if (propertyRoot) {
+        state.summary = { members: 0, depth: 0, stringBytes: 0, canonicalBytes: 0 };
+        state.summaryDepth = depth;
+    }
+    if (state.summary !== undefined) {
+        state.summary.depth = Math.max(state.summary.depth, depth + 1 - state.summaryDepth);
+    }
     try {
-        return reflect(() => Array.isArray(input), pointer, 'Cannot inspect the host value brand')
+        const output = reflect(() => Array.isArray(input), pointer, 'Cannot inspect the host value brand')
             ? admitArray(input, pointer, depth + 1, state)
             : admitObject(input, pointer, depth + 1, state);
+        if (state.mode === 'immutable') {
+            Object.freeze(output);
+            if (propertyRoot) {
+                retainImmutableSnapshot(output, state.summary);
+                includeSnapshot(parent, state.summary, depth - parentDepth);
+            }
+        }
+        return output;
     }
     finally {
         state.active.delete(input);
+        state.summary = parent;
+        state.summaryDepth = parentDepth;
     }
 }
 function admitArray(input, pointer, depth, state) {
@@ -64,6 +135,9 @@ function admitArray(input, pointer, depth, state) {
     if (keys.length !== size + 1 || keys.some((key) => typeof key === 'symbol')) {
         throw new BoundaryError('VALUE_ARRAY', 'Expected a dense Array with no symbol or non-index properties', pointer);
     }
+    // Every portable item needs at least one byte; refuse before the detached Array allocation.
+    requireCanonicalRoom(state, size === 0 ? 2 : size * 2 + 1, pointer);
+    addCanonicalBytes(state, 2 + Math.max(0, size - 1), pointer);
     const output = Array.from({ length: size }, () => null);
     for (let index = 0; index < size; index += 1) {
         const name = String(index);
@@ -86,13 +160,14 @@ function admitObject(input, pointer, depth, state) {
     const descriptors = reflect(() => Object.getOwnPropertyDescriptors(input), pointer, 'Cannot snapshot Object descriptors');
     const keys = Reflect.ownKeys(descriptors);
     addMembers(state, keys.length, pointer);
+    addCanonicalBytes(state, 2 + Math.max(0, keys.length - 1) + keys.length, pointer);
     const output = {};
     for (const key of keys) {
         if (typeof key === 'symbol') {
             throw new BoundaryError('VALUE_OBJECT', 'Portable Objects cannot have symbol members', pointer);
         }
         const memberPointer = child(pointer, key);
-        assertHostString(key, memberPointer, state.limits.maxStringBytes);
+        admitString(key, memberPointer, state);
         const descriptor = ownDescriptor(descriptors, key);
         if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor)) {
             throw new BoundaryError('VALUE_OBJECT', 'Object members must be enumerable data properties', memberPointer);
@@ -115,10 +190,34 @@ function ownDescriptor(descriptors, name) {
 }
 function addMembers(state, count, pointer) {
     state.members += count;
+    if (state.summary !== undefined)
+        state.summary.members += count;
     if (state.members > state.limits.maxMembers) {
         throw new BoundaryError('VALUE_LIMIT', `Value exceeds the ${state.limits.maxMembers}-member limit`, pointer);
     }
 }
+function admitString(value, pointer, state) {
+    const bytes = assertHostString(value, pointer, state.limits.maxStringBytes);
+    if (state.summary !== undefined) {
+        state.summary.stringBytes = Math.max(state.summary.stringBytes, bytes);
+    }
+    if (state.summary !== undefined || state.bytes !== undefined)
+        addCanonicalBytes(state, canonicalPrimitiveBytes(value), pointer);
+}
+function requireCanonicalRoom(state, bytes, pointer) {
+    if (state.bytes !== undefined && bytes > state.limits.maxBytes - state.bytes)
+        throw new BoundaryError('VALUE_LIMIT', `Canonical JSON exceeds the ${state.limits.maxBytes}-byte limit`, pointer);
+}
+function chargeCanonicalBytes(state, bytes, pointer) {
+    requireCanonicalRoom(state, bytes, pointer);
+    if (state.bytes !== undefined)
+        state.bytes += bytes;
+}
+function addCanonicalBytes(state, bytes, pointer) {
+    chargeCanonicalBytes(state, bytes, pointer);
+    if (state.summary !== undefined)
+        state.summary.canonicalBytes += bytes;
+}
 function reflect(operation, pointer, message) {
     try {
         return operation();

package/dist/value/canonical.d.ts

@@ -1,4 +1,7 @@
+import type { Value } from './types.js';
 import { type Options } from './limits.js';
 /** RFC 8785 canonical JSON for one admitted portable snapshot. */
 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;

package/dist/value/canonical.js

@@ -1,14 +1,30 @@
-import { accept } from './accept.js';
+import { acceptForRead } from './accept.js';
 import { BoundaryError } from './error.js';
-import { limitsFor } from './limits.js';
-import { utf8Length } from './unicode.js';
+import { immutableSnapshotBytes } from './immutable.optimization.js';
+import { defaultLimits, limitsFor } from './limits.js';
+import { canonicalPrimitiveBytes, utf8Length } from './unicode.js';
 const encoder = new TextEncoder();
 /** RFC 8785 canonical JSON for one admitted portable snapshot. */
 export function serialize(input, options) {
     const limits = limitsFor(options);
-    const output = serializeValue(accept(input, options));
-    if (utf8Length(output, limits.maxBytes) > limits.maxBytes) {
-        throw new BoundaryError('VALUE_LIMIT', `Canonical JSON exceeds the ${limits.maxBytes}-byte limit`);
+    return serializeSnapshot(acceptForRead(input, options), limits.maxBytes);
+}
+/** Serialize a trusted portable value whose default structural admission proof is still valid. */
+export function serializeAdmitted(input) {
+    return serializeSnapshot(input, defaultLimits.maxBytes);
+}
+function serializeSnapshot(input, maxBytes) {
+    const bytes = input !== null && typeof input === 'object'
+        ? immutableSnapshotBytes(input)
+        : canonicalPrimitiveBytes(input);
+    if (bytes !== undefined && bytes > maxBytes)
+        throw new BoundaryError('VALUE_LIMIT', `Canonical JSON exceeds the ${maxBytes}-byte limit`);
+    const output = serializeValue(input);
+    // Scalar text uses at most three UTF-8 bytes per UTF-16 code unit, including JSON escapes.
+    if (bytes === undefined &&
+        output.length > maxBytes / 3 &&
+        utf8Length(output, maxBytes) > maxBytes) {
+        throw new BoundaryError('VALUE_LIMIT', `Canonical JSON exceeds the ${maxBytes}-byte limit`);
     }
     return output;
 }

package/dist/value/immutable.optimization.d.ts

@@ -0,0 +1,15 @@
+import type { Limits } from './limits.js';
+export interface SnapshotSummary {
+    members: number;
+    depth: number;
+    stringBytes: number;
+    canonicalBytes: number;
+}
+export declare function isImmutableSnapshot(value: object): boolean;
+/** Exact complete representation size, only for roots retained by this admission owner. */
+export declare function immutableSnapshotBytes(value: object): number | undefined;
+/** Called only after admission has constructed and deeply frozen this container. */
+export declare function retainImmutableSnapshot(value: object, summary: SnapshotSummary): void;
+export declare function includeSnapshot(parent: SnapshotSummary | undefined, child: SnapshotSummary, depth: number): void;
+/** A failed fit must use normal admission, preserving its exact error pointer. */
+export declare function reusableSnapshot(value: object, limits: Limits, depth: number, members: number, bytes: number | undefined): SnapshotSummary | undefined;

package/dist/value/immutable.optimization.js

@@ -0,0 +1,34 @@
+// Only admission-owned, deeply immutable snapshots enter this table. A frozen
+// caller object is not a proof. Weak identity ownership retains no caller data.
+const snapshots = new WeakMap();
+export function isImmutableSnapshot(value) {
+    return snapshots.has(value);
+}
+/** Exact complete representation size, only for roots retained by this admission owner. */
+export function immutableSnapshotBytes(value) {
+    return snapshots.get(value)?.canonicalBytes;
+}
+/** Called only after admission has constructed and deeply frozen this container. */
+export function retainImmutableSnapshot(value, summary) {
+    if (!snapshots.has(value))
+        snapshots.set(value, summary);
+}
+export function includeSnapshot(parent, child, depth) {
+    if (parent === undefined)
+        return;
+    parent.members += child.members;
+    parent.depth = Math.max(parent.depth, depth + child.depth);
+    parent.stringBytes = Math.max(parent.stringBytes, child.stringBytes);
+    parent.canonicalBytes += child.canonicalBytes;
+}
+/** A failed fit must use normal admission, preserving its exact error pointer. */
+export function reusableSnapshot(value, limits, depth, members, bytes) {
+    const summary = snapshots.get(value);
+    if (summary === undefined ||
+        summary.members > limits.maxMembers - members ||
+        summary.depth > limits.maxDepth - depth ||
+        summary.stringBytes > limits.maxStringBytes ||
+        (bytes !== undefined && summary.canonicalBytes > limits.maxBytes - bytes))
+        return undefined;
+    return summary;
+}

package/dist/value/index.d.ts

@@ -1,5 +1,5 @@
 /** Portable values shared by the DSL and kernel contracts. */
-export { accept } from './accept.js';
+export { accept, acceptForRead, acceptImmutable } from './accept.js';
 export { equal } from './equal.js';
 export { BoundaryError, DecodeError } from './error.js';
 export type { BoundaryErrorCode, DecodeErrorCode } from './error.js';

package/dist/value/index.js

@@ -1,5 +1,5 @@
 /** Portable values shared by the DSL and kernel contracts. */
-export { accept } from './accept.js';
+export { accept, acceptForRead, acceptImmutable } from './accept.js';
 export { equal } from './equal.js';
 export { BoundaryError, DecodeError } from './error.js';
 export { defaultLimits } from './limits.js';

package/dist/value/json.d.ts

@@ -1,3 +1,3 @@
-export { encode, serialize } from './canonical.js';
+export { 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 } from './canonical.js';
+export { encode, serialize, serializeAdmitted } from './canonical.js';
 export { decode } from './decode.js';
 export { DecodeError } from './error.js';

package/dist/value/limits.d.ts

@@ -1,5 +1,5 @@
 export interface Limits {
-    /** Maximum UTF-8 size accepted from or emitted to a wire boundary. */
+    /** Maximum wire UTF-8 size, also bounding the complete canonical immutable capture. */
     readonly maxBytes: number;
     /** Maximum number of nested Array/Object containers, with a root container at depth one. */
     readonly maxDepth: number;

package/dist/value/unicode.d.ts

@@ -1,4 +1,7 @@
+import type { Primitive } from './types.js';
+/** Exact canonical scalar spelling after the same owner has established portable input. */
+export declare function canonicalPrimitiveBytes(value: Primitive): number;
 export declare function utf8Length(value: string, max?: number): number;
-export declare function assertHostString(value: string, pointer: string, maxBytes: number): void;
+export declare function assertHostString(value: string, pointer: string, maxBytes: number): number;
 export declare function assertDecodedString(value: string, offset: number, maxBytes: number): void;
 export declare function assertSourceString(value: string, maxBytes: number): void;

package/dist/value/unicode.js

@@ -1,4 +1,31 @@
 import { BoundaryError, DecodeError } from './error.js';
+/** Exact canonical scalar spelling after the same owner has established portable input. */
+export function canonicalPrimitiveBytes(value) {
+    if (typeof value !== 'string') {
+        if (typeof value === 'number')
+            return JSON.stringify(value).length;
+        return value === false ? 5 : 4;
+    }
+    let bytes = 2;
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit < 0x20)
+            bytes += unit === 8 || unit === 9 || unit === 10 || unit === 12 || unit === 13 ? 2 : 6;
+        else if (unit === 0x22 || unit === 0x5c)
+            bytes += 2;
+        else if (unit <= 0x7f)
+            bytes += 1;
+        else if (unit <= 0x7ff)
+            bytes += 2;
+        else if (isHighSurrogate(unit)) {
+            bytes += 4;
+            index += 1;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
 export function utf8Length(value, max = Number.MAX_SAFE_INTEGER) {
     let bytes = 0;
     for (let index = 0; index < value.length; index += 1) {
@@ -34,6 +61,7 @@ export function assertHostString(value, pointer, maxBytes) {
     if (length > maxBytes) {
         throw new BoundaryError('VALUE_LIMIT', `String exceeds the ${maxBytes}-byte UTF-8 limit`, pointer);
     }
+    return length;
 }
 export function assertDecodedString(value, offset, maxBytes) {
     if (value.includes('\u0000')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-dsl",
-  "version": "0.2.0-beta.8",
+  "version": "1.0.0-beta.1",
   "description": "Astrale Kernel DSL - Schema authoring, inference, and IR serialization",
   "license": "Apache-2.0",
   "repository": {
@@ -43,6 +43,10 @@
       "types": "./dist/v1/compiled/index.d.ts",
       "import": "./dist/v1/compiled/index.js"
     },
+    "./v1/compiled/generated": {
+      "types": "./dist/v1/compiled/generated.d.ts",
+      "import": "./dist/v1/compiled/generated.js"
+    },
     "./v1/compiled/loader": {
       "types": "./dist/v1/compiled/loader/index.d.ts",
       "import": "./dist/v1/compiled/loader/index.js"
@@ -55,10 +59,22 @@
       "types": "./dist/v1/language/index.d.ts",
       "import": "./dist/v1/language/index.js"
     },
+    "./v1/language/state": {
+      "types": "./dist/v1/language/state/index.d.ts",
+      "import": "./dist/v1/language/state/index.js"
+    },
     "./v1/schema": {
       "types": "./dist/v1/schema/index.d.ts",
       "import": "./dist/v1/schema/index.js"
     },
+    "./v1/schema/compatibility": {
+      "types": "./dist/v1/schema/compatibility/api.d.ts",
+      "import": "./dist/v1/schema/compatibility/api.js"
+    },
+    "./v1/schema/fingerprint": {
+      "types": "./dist/v1/schema/fingerprint.d.ts",
+      "import": "./dist/v1/schema/fingerprint.js"
+    },
     "./v1/schema/revision": {
       "types": "./dist/v1/schema/revision.d.ts",
       "import": "./dist/v1/schema/revision.js"
@@ -87,7 +103,7 @@
     "ajv": "^8.20.0",
     "re2js": "2.8.6",
     "typescript": "~6.0.3",
-    "vitest": "^4.1.10",
+    "vitest": "^5.0.1",
     "yaml": "2.9.0"
   },
   "scripts": {
@@ -97,11 +113,10 @@
     "generate:value-schema-validator": "node scripts/generate-value-schema-meta-validator.mjs",
     "layout:check": "node scripts/check-layout.mjs",
     "spec:typecheck": "tsgo --noEmit -p tsconfig.spec.json",
-    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.types.json",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.types.json && tsgo -p tsconfig.workers.json",
     "test": "pnpm run conformance && pnpm run layout:check && vitest run",
     "test:file": "vitest run",
     "test:semantic-lock": "pnpm run conformance && pnpm run layout:check && vitest run",
-    "test:watch": "vitest",
-    "preinstall": "node -e \"try{require('./.check-workspace.cjs')}catch{}\""
+    "test:watch": "vitest"
   }
 }

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

@@ -1,29 +0,0 @@
-import type { Key as SemanticKey } from '../../addressing/index.js';
-import type { Revision } from '../../addressing/index.js';
-import type { DomainSchema } from '../model/schema.js';
-import { Key } from '../../addressing/index.js';
-export type DependencyMeaningChangeKind = 'missing' | 'changed';
-export type MeaningFingerprint = `sha256:${string}`;
-export interface DependencyMeaningChange {
-    readonly key: SemanticKey;
-    readonly kind: DependencyMeaningChangeKind;
-    readonly sourceFingerprint: MeaningFingerprint;
-    readonly targetFingerprint?: MeaningFingerprint;
-}
-export interface DependencyMeaningComparison {
-    readonly version: 1;
-    readonly dependency: Key.Origin;
-    readonly source: Revision;
-    readonly target: Revision;
-    readonly footprint: readonly SemanticKey[];
-    readonly changes: readonly DependencyMeaningChange[];
-    readonly fingerprint: MeaningFingerprint;
-}
-/**
- * Compare the exact V1 meaning one accepted Domain used from a retained dependency with a
- * candidate revision of that same dependency origin. This operation is pure and makes no
- * lifecycle-compatibility decision.
- */
-export declare function compareDependencyMeaning(dependent: DomainSchema, target: DomainSchema): DependencyMeaningComparison;
-/** Compare one explicit non-empty source member surface and its reachable V1 meaning. */
-export declare function compareMemberMeaning(source: DomainSchema, target: DomainSchema, roots: readonly [SemanticKey, ...SemanticKey[]]): DependencyMeaningComparison;