@zlink-systems/stream-wire 0.29.1 → 0.30.1

package/LICENSE

@@ -1,105 +1,202 @@
-# Functional Source License, Version 1.1, ALv2 Future License
 
-## Abbreviation
-
-FSL-1.1-ALv2
-
-## Notice
-
-Copyright 2026 ZLink Systems
-
-## Terms and Conditions
-
-### Licensor ("We")
-
-The party offering the Software under these Terms and Conditions.
-
-### The Software
-
-The "Software" is each version of the software that we make available under
-these Terms and Conditions, as indicated by our inclusion of these Terms and
-Conditions with the Software.
-
-### License Grant
-
-Subject to your compliance with this License Grant and the Patents,
-Redistribution and Trademark clauses below, we hereby grant you the right to
-use, copy, modify, create derivative works, publicly perform, publicly display
-and redistribute the Software for any Permitted Purpose identified below.
-
-### Permitted Purpose
-
-A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
-means making the Software available to others in a commercial product or
-service that:
-
-1. substitutes for the Software;
-
-2. substitutes for any other product or service we offer using the Software
-   that exists as of the date we make the Software available; or
-
-3. offers the same or substantially similar functionality as the Software.
-
-Permitted Purposes specifically include using the Software:
-
-1. for your internal use and access;
-
-2. for non-commercial education;
-
-3. for non-commercial research; and
-
-4. in connection with professional services that you provide to a licensee
-   using the Software in accordance with these Terms and Conditions.
-
-### Patents
-
-To the extent your use for a Permitted Purpose would necessarily infringe our
-patents, the license grant above includes a license under our patents. If you
-make a claim against any party that the Software infringes or contributes to
-the infringement of any patent, then your patent license to the Software ends
-immediately.
-
-### Redistribution
-
-The Terms and Conditions apply to all copies, modifications and derivatives of
-the Software.
-
-If you redistribute any copies, modifications or derivatives of the Software,
-you must include a copy of or a link to these Terms and Conditions and not
-remove any copyright notices provided in or with the Software.
-
-### Disclaimer
-
-THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
-PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
-
-IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
-SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
-EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
-
-### Trademarks
-
-Except for displaying the License Details and identifying us as the origin of
-the Software, you have no right under these Terms and Conditions to use our
-trademarks, trade names, service marks or product names.
-
-## Grant of Future License
-
-We hereby irrevocably grant you an additional license to use the Software under
-the Apache License, Version 2.0 that is effective on the second anniversary of
-the date we make the Software available. On or after that date, you may use the
-Software under the Apache License, Version 2.0, in which case the following
-will apply:
-
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use
-this file except in compliance with the License.
-
-You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed
-under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-CONDITIONS OF ANY KIND, either express or implied. See the License for the
-specific language governing permissions and limitations under the License.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/esm/internal/framework-json-v1.d.ts

@@ -0,0 +1,7 @@
+import type { ZLinkJsonSchema } from './json-contract';
+export declare const FRAMEWORK_JSON_V1_PROFILE = "framework-json-v1";
+export interface FrameworkJsonParseOptions {
+    readonly rejectPropertyName?: (name: string) => boolean;
+}
+export declare function stringifyFrameworkJsonV1(value: unknown, schema?: ZLinkJsonSchema, replacer?: (this: unknown, key: string, value: unknown) => unknown): string;
+export declare function parseFrameworkJsonV1(text: string, options?: FrameworkJsonParseOptions, schema?: ZLinkJsonSchema, reviver?: (this: unknown, key: string, value: unknown) => unknown): unknown;

package/dist/esm/internal/json-contract.d.ts

@@ -0,0 +1,47 @@
+/** Describes the fields accepted by the default framework-json-v1 serializer. */
+export type ZLinkJsonSchema = {
+    readonly type: 'boolean';
+} | {
+    readonly type: 'string';
+} | {
+    readonly type: 'number';
+} | {
+    readonly type: 'int32';
+} | {
+    readonly type: 'uint32';
+} | {
+    readonly type: 'int64';
+} | {
+    readonly type: 'uint64';
+} | {
+    readonly type: 'bytes';
+} | {
+    readonly type: 'enum';
+    readonly names: readonly string[];
+} | {
+    readonly type: 'nullable';
+    readonly value: ZLinkJsonSchema;
+} | {
+    readonly type: 'array';
+    readonly items: ZLinkJsonSchema;
+} | {
+    readonly type: 'record';
+    readonly values: ZLinkJsonSchema;
+} | {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, ZLinkJsonSchema>>;
+    readonly required: readonly string[];
+    /** Unknown properties are ignored during decoding unless this is false. */
+    readonly additionalProperties?: boolean;
+};
+/**
+ * Describes the request and optional reply fields carried under one packet
+ * name by the default JSON serializer.
+ */
+export interface ZLinkPacketJsonContract {
+    readonly payload: ZLinkJsonSchema;
+    readonly reply?: ZLinkJsonSchema;
+}
+export declare function defineZLinkPacketJsonContract(packetName: string, contract: ZLinkPacketJsonContract): ZLinkPacketJsonContract;
+export declare function readZLinkPacketJsonContract(packetName: string): ZLinkPacketJsonContract | undefined;
+export declare function isPrototypeKey(name: string): boolean;

package/dist/esm/internal/json.d.ts

@@ -0,0 +1,4 @@
+/** @internal Shared JSON profile; not an application codec registration API. */
+export * from './framework-json-v1';
+export * from './json-contract';
+export * from './packet-json-contract';

package/dist/esm/internal/packet-json-contract.d.ts

@@ -0,0 +1,15 @@
+import type { ZLinkPacketJsonContract } from './json-contract';
+export declare const ZLINK_DECORATOR_METADATA: unique symbol;
+export interface ZLinkDecoratorMetadata {
+    readonly kind: string;
+    readonly packetName?: string;
+    readonly groupName?: string;
+    readonly methodName?: string;
+    readonly meshName?: string;
+    readonly channelName?: string;
+    readonly topic?: string;
+    readonly jsonContract?: ZLinkPacketJsonContract;
+}
+export declare function readZLinkDecoratorMetadata(target: object): readonly ZLinkDecoratorMetadata[];
+export declare function readFrameworkPacketJsonContract(type: object, explicitPacketName?: string): ZLinkPacketJsonContract | undefined;
+export declare function normalizePacketName(value: unknown): string | undefined;

package/dist/internal/framework-json-v1.d.ts

@@ -0,0 +1,7 @@
+import type { ZLinkJsonSchema } from './json-contract';
+export declare const FRAMEWORK_JSON_V1_PROFILE = "framework-json-v1";
+export interface FrameworkJsonParseOptions {
+    readonly rejectPropertyName?: (name: string) => boolean;
+}
+export declare function stringifyFrameworkJsonV1(value: unknown, schema?: ZLinkJsonSchema, replacer?: (this: unknown, key: string, value: unknown) => unknown): string;
+export declare function parseFrameworkJsonV1(text: string, options?: FrameworkJsonParseOptions, schema?: ZLinkJsonSchema, reviver?: (this: unknown, key: string, value: unknown) => unknown): unknown;

package/dist/internal/framework-json-v1.js

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRAMEWORK_JSON_V1_PROFILE = void 0;
+exports.stringifyFrameworkJsonV1 = stringifyFrameworkJsonV1;
+exports.parseFrameworkJsonV1 = parseFrameworkJsonV1;
+exports.FRAMEWORK_JSON_V1_PROFILE = 'framework-json-v1';
+const SIGNED_64_MIN = -(1n << 63n);
+const UNSIGNED_64_MAX = (1n << 64n) - 1n;
+function stringifyFrameworkJsonV1(value, schema, replacer) {
+    if (value === undefined || typeof value === 'function' || typeof value === 'symbol') {
+        throw new TypeError('framework-json-v1 payload is not a JSON value.');
+    }
+    const encoded = JSON.stringify(value, replacer === undefined
+        ? frameworkJsonV1Replacer
+        : function (key, item) {
+            const transformed = replacer.call(this, key, item);
+            return frameworkJsonV1Replacer.call({ [key]: transformed }, key, transformed);
+        });
+    if (schema !== undefined) {
+        validateFrameworkJsonV1Value(JSON.parse(encoded), schema, '$', false);
+    }
+    return encoded;
+}
+//  Module-level so JSON.stringify does not allocate a fresh closure per
+//  encoded message. On the root call `this` is the {'': value} wrapper, so
+//  this[key] resolves the raw (pre-toJSON) source for every key including ''.
+function frameworkJsonV1Replacer(key, item) {
+    const source = this[key];
+    if (typeof source === 'number' && !Number.isFinite(source)) {
+        throw new TypeError('framework-json-v1 only accepts finite JSON numbers.');
+    }
+    if (typeof source === 'bigint') {
+        if (source < SIGNED_64_MIN || source > UNSIGNED_64_MAX) {
+            throw new RangeError('framework-json-v1 64-bit integer is outside the supported range.');
+        }
+        return source.toString(10);
+    }
+    if (source instanceof Uint8Array) {
+        return encodeBase64(source);
+    }
+    if (source instanceof Date) {
+        throw new TypeError('framework-json-v1 does not implicitly encode Date values.');
+    }
+    if (typeof source === 'object' &&
+        source !== null &&
+        typeof source.toJSON === 'function') {
+        throw new TypeError('framework-json-v1 does not implicitly invoke custom toJSON methods.');
+    }
+    return item;
+}
+function parseFrameworkJsonV1(text, options = {}, schema, reviver) {
+    if (text.charCodeAt(0) === 0xfeff) {
+        throw new SyntaxError('framework-json-v1 does not allow a UTF-8 BOM.');
+    }
+    new JsonPropertyScanner(text, options).scan();
+    const parsed = JSON.parse(text, reviver);
+    return schema === undefined ? parsed : validateFrameworkJsonV1Value(parsed, schema, '$', true);
+}
+//  Sticky pattern shared across scans; matching happens synchronously so the
+//  mutable lastIndex never crosses calls.
+const NUMBER_TOKEN_PATTERN = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/uy;
+const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
+const INT32_MIN = -2_147_483_648;
+const INT32_MAX = 2_147_483_647;
+const UINT32_MAX = 4_294_967_295;
+function validateFrameworkJsonV1Value(value, schema, path, decode) {
+    switch (schema.type) {
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                schemaFailure(path, 'a boolean');
+            return value;
+        case 'string':
+            if (typeof value !== 'string')
+                schemaFailure(path, 'a string');
+            return value;
+        case 'number':
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                schemaFailure(path, 'a finite number');
+            return value;
+        case 'int32':
+            if (!Number.isInteger(value) ||
+                value < INT32_MIN ||
+                value > INT32_MAX) {
+                schemaFailure(path, 'an int32 JSON number');
+            }
+            return value;
+        case 'uint32':
+            if (!Number.isInteger(value) || value < 0 || value > UINT32_MAX) {
+                schemaFailure(path, 'a uint32 JSON number');
+            }
+            return value;
+        case 'int64':
+            return validateDecimalInteger(value, path, true, decode);
+        case 'uint64':
+            return validateDecimalInteger(value, path, false, decode);
+        case 'bytes': {
+            if (typeof value !== 'string' || !BASE64_PATTERN.test(value)) {
+                schemaFailure(path, 'padded RFC 4648 base64');
+            }
+            const bytes = decodeBase64(value);
+            if (encodeBase64(bytes) !== value)
+                schemaFailure(path, 'canonical padded RFC 4648 base64');
+            return decode ? Uint8Array.from(bytes) : value;
+        }
+        case 'enum':
+            if (typeof value !== 'string' || !schema.names.includes(value)) {
+                schemaFailure(path, `one of ${schema.names.join(', ')}`);
+            }
+            return value;
+        case 'nullable':
+            return value === null
+                ? null
+                : validateFrameworkJsonV1Value(value, schema.value, path, decode);
+        case 'array':
+            if (!Array.isArray(value))
+                schemaFailure(path, 'an array');
+            return value.map((item, index) => validateFrameworkJsonV1Value(item, schema.items, `${path}[${index}]`, decode));
+        case 'record': {
+            if (!isJsonObject(value))
+                schemaFailure(path, 'an object');
+            const result = {};
+            for (const [name, item] of Object.entries(value)) {
+                result[name] = validateFrameworkJsonV1Value(item, schema.values, `${path}.${name}`, decode);
+            }
+            return decode ? result : value;
+        }
+        case 'object': {
+            if (!isJsonObject(value))
+                schemaFailure(path, 'an object');
+            const input = value;
+            for (const name of schema.required) {
+                if (!Object.prototype.hasOwnProperty.call(input, name)) {
+                    throw new TypeError(`framework-json-v1 required property '${path}.${name}' is missing.`);
+                }
+            }
+            const result = {};
+            for (const [name, item] of Object.entries(input)) {
+                const propertySchema = schema.properties[name];
+                if (propertySchema === undefined) {
+                    if (schema.additionalProperties === false) {
+                        throw new TypeError(`framework-json-v1 property '${path}.${name}' is not allowed.`);
+                    }
+                    continue;
+                }
+                result[name] = validateFrameworkJsonV1Value(item, propertySchema, `${path}.${name}`, decode);
+            }
+            return decode ? result : value;
+        }
+    }
+}
+function validateDecimalInteger(value, path, signed, decode) {
+    if (typeof value !== 'string' || !/^(?:0|[1-9][0-9]*|-[1-9][0-9]*)$/u.test(value)) {
+        schemaFailure(path, signed ? 'a canonical int64 decimal string' : 'a canonical uint64 decimal string');
+    }
+    const parsed = BigInt(value);
+    const minimum = signed ? SIGNED_64_MIN : 0n;
+    const maximum = signed ? (1n << 63n) - 1n : UNSIGNED_64_MAX;
+    if (parsed < minimum || parsed > maximum)
+        schemaFailure(path, signed ? 'an int64 value' : 'a uint64 value');
+    return decode ? parsed : value;
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function schemaFailure(path, expected) {
+    throw new TypeError(`framework-json-v1 value '${path}' must be ${expected}.`);
+}
+class JsonPropertyScanner {
+    text;
+    options;
+    index = 0;
+    constructor(text, options) {
+        this.text = text;
+        this.options = options;
+    }
+    scan() {
+        this.skipWhitespace();
+        this.scanValue();
+        this.skipWhitespace();
+        if (this.index !== this.text.length)
+            this.fail('trailing data');
+    }
+    scanValue() {
+        this.skipWhitespace();
+        const token = this.text[this.index];
+        if (token === '{')
+            return this.scanObject();
+        if (token === '[')
+            return this.scanArray();
+        if (token === '"') {
+            this.scanString();
+            return;
+        }
+        if (token === 't')
+            return this.scanLiteral('true');
+        if (token === 'f')
+            return this.scanLiteral('false');
+        if (token === 'n')
+            return this.scanLiteral('null');
+        this.scanNumber();
+    }
+    scanObject() {
+        this.index++;
+        this.skipWhitespace();
+        if (this.text[this.index] === '}') {
+            this.index++;
+            return;
+        }
+        const properties = new Set();
+        for (;;) {
+            this.skipWhitespace();
+            if (this.text[this.index] !== '"')
+                this.fail('object property name');
+            const property = this.scanString();
+            if (properties.has(property)) {
+                throw new SyntaxError(`framework-json-v1 duplicate property '${property}'.`);
+            }
+            properties.add(property);
+            if (this.options.rejectPropertyName?.(property) === true) {
+                throw new SyntaxError(`framework-json-v1 property '${property}' is not allowed.`);
+            }
+            this.skipWhitespace();
+            if (this.text[this.index] !== ':')
+                this.fail("':' after object property");
+            this.index++;
+            this.scanValue();
+            this.skipWhitespace();
+            const delimiter = this.text[this.index++];
+            if (delimiter === '}')
+                return;
+            if (delimiter !== ',')
+                this.fail("',' or '}' after object property");
+        }
+    }
+    scanArray() {
+        this.index++;
+        this.skipWhitespace();
+        if (this.text[this.index] === ']') {
+            this.index++;
+            return;
+        }
+        for (;;) {
+            this.scanValue();
+            this.skipWhitespace();
+            const delimiter = this.text[this.index++];
+            if (delimiter === ']')
+                return;
+            if (delimiter !== ',')
+                this.fail("',' or ']' after array item");
+        }
+    }
+    scanString() {
+        const start = this.index++;
+        let sawEscape = false;
+        for (;;) {
+            if (this.index >= this.text.length)
+                this.fail('unterminated string');
+            const character = this.text[this.index++];
+            if (character === '"') {
+                //  Without escapes the token content is verbatim; the outer
+                //  JSON.parse pass still rejects any raw control characters.
+                return sawEscape
+                    ? JSON.parse(this.text.slice(start, this.index))
+                    : this.text.slice(start + 1, this.index - 1);
+            }
+            if (character === '\\') {
+                sawEscape = true;
+                if (this.index >= this.text.length)
+                    this.fail('unterminated escape');
+                const escaped = this.text[this.index++];
+                if (escaped === 'u')
+                    this.index += 4;
+            }
+        }
+    }
+    scanLiteral(value) {
+        if (!this.text.startsWith(value, this.index))
+            this.fail(value);
+        this.index += value.length;
+    }
+    scanNumber() {
+        NUMBER_TOKEN_PATTERN.lastIndex = this.index;
+        const match = NUMBER_TOKEN_PATTERN.exec(this.text);
+        if (match === null)
+            this.fail('JSON value');
+        if (!Number.isFinite(Number(match[0]))) {
+            throw new TypeError('framework-json-v1 only accepts finite JSON numbers.');
+        }
+        this.index += match[0].length;
+    }
+    skipWhitespace() {
+        for (;;) {
+            const code = this.text.charCodeAt(this.index);
+            if (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d) {
+                this.index += 1;
+                continue;
+            }
+            return;
+        }
+    }
+    fail(expected) {
+        throw new SyntaxError(`framework-json-v1 expected ${expected} at offset ${this.index}.`);
+    }
+}
+const BASE64_STRING_CHUNK_BYTES = 8192;
+function encodeBase64(bytes) {
+    let binary = '';
+    for (let offset = 0; offset < bytes.length; offset += BASE64_STRING_CHUNK_BYTES) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_STRING_CHUNK_BYTES));
+    }
+    return btoa(binary);
+}
+function decodeBase64(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}

package/dist/internal/json-contract.d.ts

@@ -0,0 +1,47 @@
+/** Describes the fields accepted by the default framework-json-v1 serializer. */
+export type ZLinkJsonSchema = {
+    readonly type: 'boolean';
+} | {
+    readonly type: 'string';
+} | {
+    readonly type: 'number';
+} | {
+    readonly type: 'int32';
+} | {
+    readonly type: 'uint32';
+} | {
+    readonly type: 'int64';
+} | {
+    readonly type: 'uint64';
+} | {
+    readonly type: 'bytes';
+} | {
+    readonly type: 'enum';
+    readonly names: readonly string[];
+} | {
+    readonly type: 'nullable';
+    readonly value: ZLinkJsonSchema;
+} | {
+    readonly type: 'array';
+    readonly items: ZLinkJsonSchema;
+} | {
+    readonly type: 'record';
+    readonly values: ZLinkJsonSchema;
+} | {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, ZLinkJsonSchema>>;
+    readonly required: readonly string[];
+    /** Unknown properties are ignored during decoding unless this is false. */
+    readonly additionalProperties?: boolean;
+};
+/**
+ * Describes the request and optional reply fields carried under one packet
+ * name by the default JSON serializer.
+ */
+export interface ZLinkPacketJsonContract {
+    readonly payload: ZLinkJsonSchema;
+    readonly reply?: ZLinkJsonSchema;
+}
+export declare function defineZLinkPacketJsonContract(packetName: string, contract: ZLinkPacketJsonContract): ZLinkPacketJsonContract;
+export declare function readZLinkPacketJsonContract(packetName: string): ZLinkPacketJsonContract | undefined;
+export declare function isPrototypeKey(name: string): boolean;

package/dist/internal/json-contract.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineZLinkPacketJsonContract = defineZLinkPacketJsonContract;
+exports.readZLinkPacketJsonContract = readZLinkPacketJsonContract;
+exports.isPrototypeKey = isPrototypeKey;
+const MAX_CONTRACT_SCHEMA_DEPTH = 64;
+const ZLINK_PACKET_JSON_CONTRACTS = Symbol.for('@zlink-systems/framework:packet-json-contracts');
+function defineZLinkPacketJsonContract(packetName, contract) {
+    if (packetName.trim().length === 0) {
+        throw new TypeError('ZLink packet name must not be empty.');
+    }
+    const runtimeContract = contract;
+    if (typeof runtimeContract !== 'object' || runtimeContract === null) {
+        throw new TypeError('ZLink packet JSON contract must be an object.');
+    }
+    const normalizedContract = runtimeContract;
+    const normalized = Object.freeze({
+        payload: normalizeJsonSchema(normalizedContract.payload, new Set(), 0),
+        ...(normalizedContract.reply === undefined
+            ? {}
+            : { reply: normalizeJsonSchema(normalizedContract.reply, new Set(), 0) })
+    });
+    const contracts = packetJsonContracts();
+    const current = contracts.get(packetName);
+    if (current !== undefined && canonicalContract(current) !== canonicalContract(normalized)) {
+        throw new TypeError(`ZLink packet '${packetName}' has conflicting JSON contracts in one process.`);
+    }
+    if (current !== undefined)
+        return current;
+    contracts.set(packetName, normalized);
+    return normalized;
+}
+function readZLinkPacketJsonContract(packetName) {
+    return packetJsonContracts().get(packetName);
+}
+function normalizeJsonSchema(schema, parents, depth) {
+    // Keep the runtime boundary defensive for JavaScript callers even though
+    // the TypeScript signature describes the accepted shape.
+    const runtimeSchema = schema;
+    if (typeof runtimeSchema !== 'object' ||
+        runtimeSchema === null ||
+        depth > MAX_CONTRACT_SCHEMA_DEPTH) {
+        throw new TypeError(`ZLink packet JSON schema must be an acyclic object with at most ${MAX_CONTRACT_SCHEMA_DEPTH} levels.`);
+    }
+    const normalizedSchema = runtimeSchema;
+    if (parents.has(normalizedSchema))
+        throw new TypeError('ZLink packet JSON schema must not contain a cycle.');
+    const nextParents = new Set(parents).add(normalizedSchema);
+    switch (normalizedSchema.type) {
+        case 'boolean':
+        case 'string':
+        case 'number':
+        case 'int32':
+        case 'uint32':
+        case 'int64':
+        case 'uint64':
+        case 'bytes':
+            return Object.freeze({ type: normalizedSchema.type });
+        case 'enum': {
+            if (!Array.isArray(normalizedSchema.names) ||
+                normalizedSchema.names.length === 0 ||
+                normalizedSchema.names.some((name) => typeof name !== 'string' || name.length === 0)) {
+                throw new TypeError('ZLink packet enum schema requires non-empty string names.');
+            }
+            if (new Set(normalizedSchema.names).size !== normalizedSchema.names.length) {
+                throw new TypeError('ZLink packet enum schema names must be unique.');
+            }
+            return Object.freeze({ type: 'enum', names: Object.freeze([...normalizedSchema.names]) });
+        }
+        case 'nullable':
+            return Object.freeze({
+                type: 'nullable',
+                value: normalizeJsonSchema(normalizedSchema.value, nextParents, depth + 1)
+            });
+        case 'array':
+            return Object.freeze({
+                type: 'array',
+                items: normalizeJsonSchema(normalizedSchema.items, nextParents, depth + 1)
+            });
+        case 'record':
+            return Object.freeze({
+                type: 'record',
+                values: normalizeJsonSchema(normalizedSchema.values, nextParents, depth + 1)
+            });
+        case 'object': {
+            const runtimeProperties = normalizedSchema.properties;
+            if (typeof runtimeProperties !== 'object' ||
+                runtimeProperties === null ||
+                Array.isArray(runtimeProperties)) {
+                throw new TypeError('ZLink packet object schema properties must be an object.');
+            }
+            if (!Array.isArray(normalizedSchema.required) ||
+                normalizedSchema.required.some((name) => typeof name !== 'string' || name.length === 0)) {
+                throw new TypeError('ZLink packet object schema required must contain property names.');
+            }
+            if (normalizedSchema.additionalProperties !== undefined &&
+                typeof normalizedSchema.additionalProperties !== 'boolean') {
+                throw new TypeError('ZLink packet object schema additionalProperties must be boolean.');
+            }
+            const properties = {};
+            for (const [name, property] of Object.entries(runtimeProperties)) {
+                if (isPrototypeKey(name)) {
+                    throw new TypeError(`ZLink packet JSON property '${name}' is not allowed.`);
+                }
+                properties[name] = normalizeJsonSchema(property, nextParents, depth + 1);
+            }
+            if (new Set(normalizedSchema.required).size !== normalizedSchema.required.length) {
+                throw new TypeError('ZLink packet JSON required properties must be unique.');
+            }
+            for (const name of normalizedSchema.required) {
+                if (isPrototypeKey(name)) {
+                    throw new TypeError(`ZLink packet JSON property '${name}' is not allowed.`);
+                }
+                if (!Object.prototype.hasOwnProperty.call(properties, name)) {
+                    throw new TypeError(`ZLink packet JSON required property '${name}' has no property schema.`);
+                }
+            }
+            return Object.freeze({
+                type: 'object',
+                properties: Object.freeze(properties),
+                required: Object.freeze([...normalizedSchema.required]),
+                ...(normalizedSchema.additionalProperties === undefined
+                    ? {}
+                    : { additionalProperties: normalizedSchema.additionalProperties })
+            });
+        }
+    }
+    throw new TypeError(`ZLink packet JSON schema type '${String(normalizedSchema.type)}' is not supported.`);
+}
+function packetJsonContracts() {
+    const root = globalThis;
+    let contracts = root[ZLINK_PACKET_JSON_CONTRACTS];
+    if (contracts === undefined) {
+        contracts = new Map();
+        Object.defineProperty(root, ZLINK_PACKET_JSON_CONTRACTS, {
+            configurable: false,
+            enumerable: false,
+            value: contracts,
+            writable: false
+        });
+    }
+    return contracts;
+}
+function canonicalContract(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalContract).join(',')}]`;
+    if (typeof value !== 'object' || value === null)
+        return JSON.stringify(value);
+    return `{${Object.entries(value)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonicalContract(item)}`)
+        .join(',')}}`;
+}
+function isPrototypeKey(name) {
+    return name === '__proto__' || name === 'prototype' || name === 'constructor';
+}

package/dist/internal/json.d.ts

@@ -0,0 +1,4 @@
+/** @internal Shared JSON profile; not an application codec registration API. */
+export * from './framework-json-v1';
+export * from './json-contract';
+export * from './packet-json-contract';

package/dist/internal/json.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/** @internal Shared JSON profile; not an application codec registration API. */
+__exportStar(require("./framework-json-v1"), exports);
+__exportStar(require("./json-contract"), exports);
+__exportStar(require("./packet-json-contract"), exports);

package/dist/internal/packet-json-contract.d.ts

@@ -0,0 +1,15 @@
+import type { ZLinkPacketJsonContract } from './json-contract';
+export declare const ZLINK_DECORATOR_METADATA: unique symbol;
+export interface ZLinkDecoratorMetadata {
+    readonly kind: string;
+    readonly packetName?: string;
+    readonly groupName?: string;
+    readonly methodName?: string;
+    readonly meshName?: string;
+    readonly channelName?: string;
+    readonly topic?: string;
+    readonly jsonContract?: ZLinkPacketJsonContract;
+}
+export declare function readZLinkDecoratorMetadata(target: object): readonly ZLinkDecoratorMetadata[];
+export declare function readFrameworkPacketJsonContract(type: object, explicitPacketName?: string): ZLinkPacketJsonContract | undefined;
+export declare function normalizePacketName(value: unknown): string | undefined;

package/dist/internal/packet-json-contract.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLINK_DECORATOR_METADATA = void 0;
+exports.readZLinkDecoratorMetadata = readZLinkDecoratorMetadata;
+exports.readFrameworkPacketJsonContract = readFrameworkPacketJsonContract;
+exports.normalizePacketName = normalizePacketName;
+exports.ZLINK_DECORATOR_METADATA = Symbol.for('@zlink-systems/framework:decorator');
+function readZLinkDecoratorMetadata(target) {
+    if (!Object.prototype.hasOwnProperty.call(target, exports.ZLINK_DECORATOR_METADATA)) {
+        return [];
+    }
+    return target[exports.ZLINK_DECORATOR_METADATA];
+}
+function readFrameworkPacketJsonContract(type, explicitPacketName) {
+    const expectedPacketName = normalizePacketName(explicitPacketName);
+    for (const metadata of readZLinkDecoratorMetadata(type)) {
+        if (metadata.kind === 'packet' &&
+            metadata.jsonContract !== undefined &&
+            (expectedPacketName === undefined ||
+                normalizePacketName(metadata.packetName) === expectedPacketName)) {
+            return metadata.jsonContract;
+        }
+    }
+    return undefined;
+}
+function normalizePacketName(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zlink-systems/stream-wire",
-  "version": "0.29.1",
-  "license": "SEE LICENSE IN LICENSE",
+  "version": "0.30.1",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/zlink-systems/zlink.git",
@@ -16,7 +16,8 @@
     "dist/index.d.ts",
     "dist/lz4-pickle.js",
     "dist/lz4-pickle.d.ts",
-    "LICENSE"
+    "LICENSE",
+    "dist/internal"
   ],
   "exports": {
     ".": {
@@ -24,6 +25,17 @@
       "import": "./dist/esm/index.mjs",
       "require": "./dist/index.js",
       "default": "./dist/esm/index.mjs"
+    },
+    "./internal/json": {
+      "types": "./dist/internal/json.d.ts",
+      "default": "./dist/internal/json.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "internal/json": [
+        "dist/internal/json.d.ts"
+      ]
     }
   }
 }