@astrale-os/kernel-dsl 0.2.0-beta.36 → 0.2.0-beta.38

package/dist/value/accept.js

@@ -1,4 +1,5 @@
 import { BoundaryError } from './error.js';
+import { includeSnapshot, retainImmutableSnapshot, reusableSnapshot, } from './immutable.optimization.js';
 import { limitsFor } from './limits.js';
 import { assertHostString } from './unicode.js';
 /**
@@ -7,9 +8,45 @@ import { assertHostString } from './unicode.js';
  * 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 unknown data into a deeply 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,
+        mode,
+        summary: mode === 'immutable' && !captured?.propertyRoots
+            ? { members: 0, depth: 0, stringBytes: 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)
@@ -30,12 +67,20 @@ function admit(input, pointer, depth, state) {
         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);
+        if (summary !== undefined) {
+            state.members += summary.members;
+            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 +88,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 };
+        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) {
@@ -92,7 +157,7 @@ function admitObject(input, pointer, depth, state) {
             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 +180,18 @@ 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);
+    }
+}
 function reflect(operation, pointer, message) {
     try {
         return operation();

package/dist/value/canonical.js

@@ -1,4 +1,4 @@
-import { accept } from './accept.js';
+import { acceptForRead } from './accept.js';
 import { BoundaryError } from './error.js';
 import { defaultLimits, limitsFor } from './limits.js';
 import { utf8Length } from './unicode.js';
@@ -6,7 +6,7 @@ const encoder = new TextEncoder();
 /** RFC 8785 canonical JSON for one admitted portable snapshot. */
 export function serialize(input, options) {
     const limits = limitsFor(options);
-    return serializeSnapshot(accept(input, options), limits.maxBytes);
+    return serializeSnapshot(acceptForRead(input, options), limits.maxBytes);
 }
 /** Serialize a trusted portable value whose default structural admission proof is still valid. */
 export function serializeAdmitted(input) {

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

@@ -0,0 +1,12 @@
+import type { Limits } from './limits.js';
+export interface SnapshotSummary {
+    members: number;
+    depth: number;
+    stringBytes: number;
+}
+export declare function isImmutableSnapshot(value: object): boolean;
+/** 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): SnapshotSummary | undefined;

package/dist/value/immutable.optimization.js

@@ -0,0 +1,28 @@
+// 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);
+}
+/** 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);
+}
+/** A failed fit must use normal admission, preserving its exact error pointer. */
+export function reusableSnapshot(value, limits, depth, members) {
+    const summary = snapshots.get(value);
+    if (summary === undefined ||
+        summary.members > limits.maxMembers - members ||
+        summary.depth > limits.maxDepth - depth ||
+        summary.stringBytes > limits.maxStringBytes)
+        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/unicode.d.ts

@@ -1,4 +1,4 @@
 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

@@ -34,6 +34,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.36",
+  "version": "0.2.0-beta.38",
   "description": "Astrale Kernel DSL - Schema authoring, inference, and IR serialization",
   "license": "Apache-2.0",
   "repository": {