@lp-labs/sync-protocol-kit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @lp-labs/sync-protocol-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Validate versioned synchronization envelopes and exchange acknowledgements, cursors, and
+capability descriptions. This is a local data contract only: it does not provide transport,
+storage, authentication, ordering, retry, conflict resolution, or delivery semantics.
+
+## Install and quick start
+
+```sh
+npm install @lp-labs/sync-protocol-kit
+```
+
+```js
+import { validateSyncEnvelope, negotiateCapabilities } from '@lp-labs/sync-protocol-kit';
+
+const local = {
+  versions: [1],
+  features: ['batch', 'cursor-resume'],
+  maxBatchSize: 100,
+  acknowledgements: true,
+  cursors: true,
+};
+const peerMessage = validateSyncEnvelope({
+  protocol: 'lp-sync',
+  version: 1,
+  id: 'hello-1',
+  kind: 'hello',
+  payload: { capabilities: local },
+});
+console.log(peerMessage.kind, negotiateCapabilities(local, local));
+```
+
+## API and types
+
+- `validateSyncEnvelope(value, limits?)` validates and detaches one `hello`, `changes`, `ack`, or
+  `cursor` envelope.
+- `parseSyncEnvelope(text, limits?)` parses bounded JSON text and validates it.
+- `serializeSyncEnvelope(envelope, limits?)` validates before serializing.
+- `negotiateCapabilities(local, remote)` selects a common advertised version, feature intersection,
+  minimum batch size, and mutually supported acknowledgement/cursor flags.
+- `SyncProtocolError` carries codes including `INVALID_ENVELOPE`, `INVALID_CAPABILITIES`,
+  `INVALID_PAYLOAD`, `UNSUPPORTED_VERSION`, `NO_COMMON_VERSION`, and `LIMIT_EXCEEDED`.
+- Types: `JsonValue`, `SyncCapabilities`, `SyncPayload`, `SyncPayloadByKind`, `SyncEnvelope`,
+  `SyncLimits`, and `NegotiatedCapabilities`.
+
+Envelope version 1 has a fixed protocol tag, bounded ID, kind, and kind-specific payload:
+capabilities for `hello`, a cursor and JSON change list for `changes`, an accepted/rejected
+message reference for `ack`, or a stream token (possibly null) for `cursor`. Rejected acknowledgments
+may include a reason; accepted ones may not. Capability lists reject duplicates.
+Advertised capability versions describe the peers' application-level sync contract; this kit itself
+validates only the version-1 envelope wrapper and does not implement other envelope versions.
+
+Default bounds are 1 MiB UTF-8 envelope text, JSON depth 32, 10,000 nodes, 100,000 characters per
+string, 1,000 changes per batch, and 64 capability entries. Override per call with `SyncLimits`.
+The conformance fixtures under `tests/fixtures` document accepted and rejected examples; they are
+not an external standard or a claim of interoperability. No runtime or peer dependencies are used.
+Validation and serialization are linear in the bounded envelope JSON size; capability negotiation
+is linear in the peer capability list sizes.
+
+## Module formats and customization
+
+ESM, CommonJS, and TypeScript declarations are included. CommonJS:
+`const { parseSyncEnvelope } = require('@lp-labs/sync-protocol-kit')`. Keep application message
+schemas and transport policy outside this package, and version your payload contracts independently.
+There are no runtime or peer dependencies; TypeScript and Prettier are development-only.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,60 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface SyncCapabilities {
+    readonly versions: readonly number[];
+    readonly features: readonly string[];
+    readonly maxBatchSize: number;
+    readonly acknowledgements: boolean;
+    readonly cursors: boolean;
+}
+export interface SyncPayloadByKind {
+    readonly hello: {
+        readonly capabilities: SyncCapabilities;
+    };
+    readonly changes: {
+        readonly cursor: string | null;
+        readonly changes: readonly JsonValue[];
+    };
+    readonly ack: {
+        readonly messageId: string;
+        readonly accepted: boolean;
+        readonly cursor?: string;
+        readonly reason?: string;
+    };
+    readonly cursor: {
+        readonly stream: string;
+        readonly token: string | null;
+    };
+}
+export type SyncPayload = SyncPayloadByKind[keyof SyncPayloadByKind];
+export type SyncEnvelope<K extends keyof SyncPayloadByKind = keyof SyncPayloadByKind> = K extends keyof SyncPayloadByKind ? {
+    readonly protocol: 'lp-sync';
+    readonly version: 1;
+    readonly id: string;
+    readonly kind: K;
+    readonly payload: SyncPayloadByKind[K];
+} : never;
+export interface SyncLimits {
+    readonly maxBytes?: number;
+    readonly maxDepth?: number;
+    readonly maxNodes?: number;
+    readonly maxStringLength?: number;
+    readonly maxBatchSize?: number;
+    readonly maxCapabilities?: number;
+}
+export interface NegotiatedCapabilities {
+    readonly version: number;
+    readonly features: readonly string[];
+    readonly maxBatchSize: number;
+    readonly acknowledgements: boolean;
+    readonly cursors: boolean;
+}
+export declare class SyncProtocolError extends Error {
+    readonly code: 'INVALID_ENVELOPE' | 'INVALID_CAPABILITIES' | 'INVALID_PAYLOAD' | 'UNSUPPORTED_VERSION' | 'NO_COMMON_VERSION' | 'LIMIT_EXCEEDED';
+    constructor(code: SyncProtocolError['code'], message: string);
+}
+export declare function validateSyncEnvelope(input: unknown, inputLimits?: SyncLimits): SyncEnvelope;
+export declare function parseSyncEnvelope(text: string, limits?: SyncLimits): SyncEnvelope;
+export declare function serializeSyncEnvelope(envelope: SyncEnvelope, limits?: SyncLimits): string;
+export declare function negotiateCapabilities(local: SyncCapabilities, remote: SyncCapabilities): NegotiatedCapabilities;

package/dist/cjs/index.js

@@ -0,0 +1,333 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncProtocolError = void 0;
+exports.validateSyncEnvelope = validateSyncEnvelope;
+exports.parseSyncEnvelope = parseSyncEnvelope;
+exports.serializeSyncEnvelope = serializeSyncEnvelope;
+exports.negotiateCapabilities = negotiateCapabilities;
+class SyncProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SyncProtocolError';
+        this.code = code;
+    }
+}
+exports.SyncProtocolError = SyncProtocolError;
+const envelopeFields = new Set(['protocol', 'version', 'id', 'kind', 'payload']);
+const defaults = {
+    maxBytes: 1_048_576,
+    maxDepth: 32,
+    maxNodes: 10_000,
+    maxStringLength: 100_000,
+    maxBatchSize: 1_000,
+    maxCapabilities: 64,
+};
+function isRecord(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+function limitsOf(input = {}) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        (Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null)) {
+        throw new SyncProtocolError('LIMIT_EXCEEDED', 'Sync limits must be a plain record.');
+    }
+    const allowed = new Set([
+        'maxBytes',
+        'maxDepth',
+        'maxNodes',
+        'maxStringLength',
+        'maxBatchSize',
+        'maxCapabilities',
+    ]);
+    for (const key of Reflect.ownKeys(input)) {
+        const descriptor = typeof key === 'string' ? Object.getOwnPropertyDescriptor(input, key) : undefined;
+        if (!descriptor ||
+            !allowed.has(key) ||
+            !descriptor.enumerable ||
+            !('value' in descriptor)) {
+            throw new SyncProtocolError('LIMIT_EXCEEDED', 'Sync limits contain unknown fields.');
+        }
+    }
+    const limits = {
+        maxBytes: input.maxBytes ?? defaults.maxBytes,
+        maxDepth: input.maxDepth ?? defaults.maxDepth,
+        maxNodes: input.maxNodes ?? defaults.maxNodes,
+        maxStringLength: input.maxStringLength ?? defaults.maxStringLength,
+        maxBatchSize: input.maxBatchSize ?? defaults.maxBatchSize,
+        maxCapabilities: input.maxCapabilities ?? defaults.maxCapabilities,
+    };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < (name === 'maxDepth' ? 0 : 1)) {
+            throw new SyncProtocolError('LIMIT_EXCEEDED', `${name} must be a valid safe integer.`);
+        }
+    }
+    return limits;
+}
+function record(value, allowed, required, label) {
+    if (!isRecord(value))
+        throw new SyncProtocolError('INVALID_ENVELOPE', `${label} must be a plain record.`);
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = typeof key === 'string' ? Object.getOwnPropertyDescriptor(value, key) : undefined;
+        if (!descriptor ||
+            !allowed.has(key) ||
+            !descriptor.enumerable ||
+            !('value' in descriptor)) {
+            throw new SyncProtocolError('INVALID_ENVELOPE', `${label} has unknown or non-data fields.`);
+        }
+    }
+    if (required.some((key) => !Object.hasOwn(value, key))) {
+        throw new SyncProtocolError('INVALID_ENVELOPE', `${label} is missing required fields.`);
+    }
+}
+function boundedText(value, label, maximum) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > maximum) {
+        throw new SyncProtocolError('INVALID_PAYLOAD', `${label} must be a non-empty bounded string.`);
+    }
+}
+function arrayValues(input, label, maximum) {
+    if (!Array.isArray(input) || input.length > maximum) {
+        throw new SyncProtocolError('LIMIT_EXCEEDED', `${label} must be a bounded array.`);
+    }
+    const result = [];
+    for (let index = 0; index < input.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(input, String(index));
+        if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', `${label} must be a dense data array.`);
+        }
+        result.push(descriptor.value);
+    }
+    for (const key of Reflect.ownKeys(input)) {
+        if (key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key))) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', `${label} cannot have extra properties.`);
+        }
+    }
+    return result;
+}
+function jsonCopy(input, limits, budget = { nodes: 0, bytes: 0 }) {
+    const active = new Set();
+    const visit = (value, depth) => {
+        budget.nodes += 1;
+        if (budget.nodes > limits.maxNodes || depth > limits.maxDepth) {
+            throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload exceeds configured JSON capacity.');
+        }
+        if (value === null ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && Number.isFinite(value))) {
+            budget.bytes += new TextEncoder().encode(JSON.stringify(value)).byteLength;
+            if (budget.bytes > limits.maxBytes) {
+                throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload exceeds byte capacity.');
+            }
+            return value;
+        }
+        if (typeof value === 'string') {
+            if (value.length > limits.maxStringLength) {
+                throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload string exceeds configured capacity.');
+            }
+            budget.bytes += new TextEncoder().encode(JSON.stringify(value)).byteLength;
+            if (budget.bytes > limits.maxBytes) {
+                throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload exceeds byte capacity.');
+            }
+            return value;
+        }
+        if (typeof value !== 'object' || active.has(value)) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload must be finite JSON without cycles.');
+        }
+        active.add(value);
+        if (Array.isArray(value)) {
+            budget.bytes += 2;
+            const result = [];
+            for (let index = 0; index < value.length; index += 1) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                if (!descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+                    throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload arrays must be dense data arrays.');
+                }
+                if (index > 0)
+                    budget.bytes += 1;
+                result.push(visit(descriptor.value, depth + 1));
+            }
+            for (const key of Reflect.ownKeys(value)) {
+                if (key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key))) {
+                    throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload arrays cannot have extra properties.');
+                }
+            }
+            active.delete(value);
+            return result;
+        }
+        if (!isRecord(value)) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload objects must be plain records.');
+        }
+        const result = {};
+        budget.bytes += 2;
+        let fieldIndex = 0;
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string')
+                throw new SyncProtocolError('INVALID_PAYLOAD', 'Symbols are not JSON fields.');
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor.enumerable || !('value' in descriptor)) {
+                throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload objects must contain data fields.');
+            }
+            if (fieldIndex > 0)
+                budget.bytes += 1;
+            budget.bytes += new TextEncoder().encode(JSON.stringify(key)).byteLength + 1;
+            fieldIndex += 1;
+            if (budget.bytes > limits.maxBytes) {
+                throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload exceeds byte capacity.');
+            }
+            Object.defineProperty(result, key, {
+                value: visit(descriptor.value, depth + 1),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+        active.delete(value);
+        return result;
+    };
+    return visit(input, 0);
+}
+function validateCapabilities(input, limits) {
+    record(input, new Set(['versions', 'features', 'maxBatchSize', 'acknowledgements', 'cursors']), ['versions', 'features', 'maxBatchSize', 'acknowledgements', 'cursors'], 'Capabilities');
+    const capabilities = input;
+    const versionsInput = arrayValues(capabilities.versions, 'versions', limits.maxCapabilities);
+    const featuresInput = arrayValues(capabilities.features, 'features', limits.maxCapabilities);
+    if (versionsInput.length === 0 ||
+        !Number.isSafeInteger(capabilities.maxBatchSize) ||
+        capabilities.maxBatchSize < 1 ||
+        capabilities.maxBatchSize > limits.maxBatchSize ||
+        typeof capabilities.acknowledgements !== 'boolean' ||
+        typeof capabilities.cursors !== 'boolean') {
+        throw new SyncProtocolError('INVALID_CAPABILITIES', 'Capability values are invalid or exceed limits.');
+    }
+    const versions = versionsInput.map((version) => {
+        if (!Number.isSafeInteger(version) || version < 1) {
+            throw new SyncProtocolError('INVALID_CAPABILITIES', 'Supported versions must be positive integers.');
+        }
+        return version;
+    });
+    const features = featuresInput.map((feature) => {
+        boundedText(feature, 'feature', 128);
+        return feature;
+    });
+    if (new Set(versions).size !== versions.length || new Set(features).size !== features.length) {
+        throw new SyncProtocolError('INVALID_CAPABILITIES', 'Capability lists cannot contain duplicates.');
+    }
+    return {
+        versions,
+        features,
+        maxBatchSize: capabilities.maxBatchSize,
+        acknowledgements: capabilities.acknowledgements,
+        cursors: capabilities.cursors,
+    };
+}
+function validatePayload(kind, input, limits) {
+    if (!isRecord(input))
+        throw new SyncProtocolError('INVALID_PAYLOAD', 'Envelope payload must be a plain record.');
+    if (kind === 'hello') {
+        record(input, new Set(['capabilities']), ['capabilities'], 'Hello payload');
+        return { capabilities: validateCapabilities(input.capabilities, limits) };
+    }
+    if (kind === 'changes') {
+        record(input, new Set(['cursor', 'changes']), ['cursor', 'changes'], 'Changes payload');
+        if (input.cursor !== null)
+            boundedText(input.cursor, 'cursor', limits.maxStringLength);
+        const changes = arrayValues(input.changes, 'changes', limits.maxBatchSize);
+        const budget = { nodes: 0, bytes: 2 + Math.max(0, changes.length - 1) };
+        return {
+            cursor: input.cursor,
+            changes: changes.map((change) => jsonCopy(change, limits, budget)),
+        };
+    }
+    if (kind === 'ack') {
+        record(input, new Set(['messageId', 'accepted', 'cursor', 'reason']), ['messageId', 'accepted'], 'Acknowledgement payload');
+        boundedText(input.messageId, 'messageId', limits.maxStringLength);
+        if (typeof input.accepted !== 'boolean') {
+            throw new SyncProtocolError('INVALID_PAYLOAD', 'accepted must be a boolean.');
+        }
+        if (input.cursor !== undefined)
+            boundedText(input.cursor, 'cursor', limits.maxStringLength);
+        if (input.reason !== undefined)
+            boundedText(input.reason, 'reason', limits.maxStringLength);
+        if (input.accepted && input.reason !== undefined) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', 'Accepted acknowledgements cannot include a rejection reason.');
+        }
+        return {
+            messageId: input.messageId,
+            accepted: input.accepted,
+            ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+            ...(input.reason === undefined ? {} : { reason: input.reason }),
+        };
+    }
+    if (kind === 'cursor') {
+        record(input, new Set(['stream', 'token']), ['stream', 'token'], 'Cursor payload');
+        boundedText(input.stream, 'stream', limits.maxStringLength);
+        if (input.token !== null)
+            boundedText(input.token, 'token', limits.maxStringLength);
+        return { stream: input.stream, token: input.token };
+    }
+    throw new SyncProtocolError('INVALID_ENVELOPE', 'Envelope kind is not supported.');
+}
+function validateSyncEnvelope(input, inputLimits = {}) {
+    const limits = limitsOf(inputLimits);
+    record(input, envelopeFields, ['protocol', 'version', 'id', 'kind', 'payload'], 'Sync envelope');
+    if (input.protocol !== 'lp-sync') {
+        throw new SyncProtocolError('INVALID_ENVELOPE', 'Unsupported protocol identifier.');
+    }
+    if (input.version !== 1)
+        throw new SyncProtocolError('UNSUPPORTED_VERSION', 'Envelope version is not supported.');
+    boundedText(input.id, 'id', 256);
+    if (!['hello', 'changes', 'ack', 'cursor'].includes(input.kind)) {
+        throw new SyncProtocolError('INVALID_ENVELOPE', 'Envelope kind is not supported.');
+    }
+    const envelope = {
+        protocol: 'lp-sync',
+        version: 1,
+        id: input.id,
+        kind: input.kind,
+        payload: validatePayload(input.kind, input.payload, limits),
+    };
+    if (new TextEncoder().encode(JSON.stringify(envelope)).byteLength > limits.maxBytes) {
+        throw new SyncProtocolError('LIMIT_EXCEEDED', 'Envelope exceeds configured byte capacity.');
+    }
+    return envelope;
+}
+function parseSyncEnvelope(text, limits = {}) {
+    const safeLimits = limitsOf(limits);
+    if (typeof text !== 'string')
+        throw new SyncProtocolError('INVALID_ENVELOPE', 'Input must be JSON text.');
+    if (text.length > safeLimits.maxBytes ||
+        new TextEncoder().encode(text).byteLength > safeLimits.maxBytes) {
+        throw new SyncProtocolError('LIMIT_EXCEEDED', 'Envelope exceeds configured byte capacity.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SyncProtocolError('INVALID_ENVELOPE', 'Input is not valid JSON.');
+    }
+    return validateSyncEnvelope(parsed, limits);
+}
+function serializeSyncEnvelope(envelope, limits = {}) {
+    return JSON.stringify(validateSyncEnvelope(envelope, limits));
+}
+function negotiateCapabilities(local, remote) {
+    const limits = limitsOf();
+    const safeLocal = validateCapabilities(local, limits);
+    const safeRemote = validateCapabilities(remote, limits);
+    const common = safeLocal.versions.filter((version) => safeRemote.versions.includes(version));
+    if (common.length === 0) {
+        throw new SyncProtocolError('NO_COMMON_VERSION', 'Peers have no shared protocol version.');
+    }
+    return {
+        version: Math.max(...common),
+        features: safeLocal.features.filter((feature) => safeRemote.features.includes(feature)).sort(),
+        maxBatchSize: Math.min(safeLocal.maxBatchSize, safeRemote.maxBatchSize),
+        acknowledgements: safeLocal.acknowledgements && safeRemote.acknowledgements,
+        cursors: safeLocal.cursors && safeRemote.cursors,
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,60 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface SyncCapabilities {
+    readonly versions: readonly number[];
+    readonly features: readonly string[];
+    readonly maxBatchSize: number;
+    readonly acknowledgements: boolean;
+    readonly cursors: boolean;
+}
+export interface SyncPayloadByKind {
+    readonly hello: {
+        readonly capabilities: SyncCapabilities;
+    };
+    readonly changes: {
+        readonly cursor: string | null;
+        readonly changes: readonly JsonValue[];
+    };
+    readonly ack: {
+        readonly messageId: string;
+        readonly accepted: boolean;
+        readonly cursor?: string;
+        readonly reason?: string;
+    };
+    readonly cursor: {
+        readonly stream: string;
+        readonly token: string | null;
+    };
+}
+export type SyncPayload = SyncPayloadByKind[keyof SyncPayloadByKind];
+export type SyncEnvelope<K extends keyof SyncPayloadByKind = keyof SyncPayloadByKind> = K extends keyof SyncPayloadByKind ? {
+    readonly protocol: 'lp-sync';
+    readonly version: 1;
+    readonly id: string;
+    readonly kind: K;
+    readonly payload: SyncPayloadByKind[K];
+} : never;
+export interface SyncLimits {
+    readonly maxBytes?: number;
+    readonly maxDepth?: number;
+    readonly maxNodes?: number;
+    readonly maxStringLength?: number;
+    readonly maxBatchSize?: number;
+    readonly maxCapabilities?: number;
+}
+export interface NegotiatedCapabilities {
+    readonly version: number;
+    readonly features: readonly string[];
+    readonly maxBatchSize: number;
+    readonly acknowledgements: boolean;
+    readonly cursors: boolean;
+}
+export declare class SyncProtocolError extends Error {
+    readonly code: 'INVALID_ENVELOPE' | 'INVALID_CAPABILITIES' | 'INVALID_PAYLOAD' | 'UNSUPPORTED_VERSION' | 'NO_COMMON_VERSION' | 'LIMIT_EXCEEDED';
+    constructor(code: SyncProtocolError['code'], message: string);
+}
+export declare function validateSyncEnvelope(input: unknown, inputLimits?: SyncLimits): SyncEnvelope;
+export declare function parseSyncEnvelope(text: string, limits?: SyncLimits): SyncEnvelope;
+export declare function serializeSyncEnvelope(envelope: SyncEnvelope, limits?: SyncLimits): string;
+export declare function negotiateCapabilities(local: SyncCapabilities, remote: SyncCapabilities): NegotiatedCapabilities;

package/dist/esm/index.js

@@ -0,0 +1,325 @@
+export class SyncProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SyncProtocolError';
+        this.code = code;
+    }
+}
+const envelopeFields = new Set(['protocol', 'version', 'id', 'kind', 'payload']);
+const defaults = {
+    maxBytes: 1_048_576,
+    maxDepth: 32,
+    maxNodes: 10_000,
+    maxStringLength: 100_000,
+    maxBatchSize: 1_000,
+    maxCapabilities: 64,
+};
+function isRecord(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+function limitsOf(input = {}) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        (Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null)) {
+        throw new SyncProtocolError('LIMIT_EXCEEDED', 'Sync limits must be a plain record.');
+    }
+    const allowed = new Set([
+        'maxBytes',
+        'maxDepth',
+        'maxNodes',
+        'maxStringLength',
+        'maxBatchSize',
+        'maxCapabilities',
+    ]);
+    for (const key of Reflect.ownKeys(input)) {
+        const descriptor = typeof key === 'string' ? Object.getOwnPropertyDescriptor(input, key) : undefined;
+        if (!descriptor ||
+            !allowed.has(key) ||
+            !descriptor.enumerable ||
+            !('value' in descriptor)) {
+            throw new SyncProtocolError('LIMIT_EXCEEDED', 'Sync limits contain unknown fields.');
+        }
+    }
+    const limits = {
+        maxBytes: input.maxBytes ?? defaults.maxBytes,
+        maxDepth: input.maxDepth ?? defaults.maxDepth,
+        maxNodes: input.maxNodes ?? defaults.maxNodes,
+        maxStringLength: input.maxStringLength ?? defaults.maxStringLength,
+        maxBatchSize: input.maxBatchSize ?? defaults.maxBatchSize,
+        maxCapabilities: input.maxCapabilities ?? defaults.maxCapabilities,
+    };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < (name === 'maxDepth' ? 0 : 1)) {
+            throw new SyncProtocolError('LIMIT_EXCEEDED', `${name} must be a valid safe integer.`);
+        }
+    }
+    return limits;
+}
+function record(value, allowed, required, label) {
+    if (!isRecord(value))
+        throw new SyncProtocolError('INVALID_ENVELOPE', `${label} must be a plain record.`);
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = typeof key === 'string' ? Object.getOwnPropertyDescriptor(value, key) : undefined;
+        if (!descriptor ||
+            !allowed.has(key) ||
+            !descriptor.enumerable ||
+            !('value' in descriptor)) {
+            throw new SyncProtocolError('INVALID_ENVELOPE', `${label} has unknown or non-data fields.`);
+        }
+    }
+    if (required.some((key) => !Object.hasOwn(value, key))) {
+        throw new SyncProtocolError('INVALID_ENVELOPE', `${label} is missing required fields.`);
+    }
+}
+function boundedText(value, label, maximum) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > maximum) {
+        throw new SyncProtocolError('INVALID_PAYLOAD', `${label} must be a non-empty bounded string.`);
+    }
+}
+function arrayValues(input, label, maximum) {
+    if (!Array.isArray(input) || input.length > maximum) {
+        throw new SyncProtocolError('LIMIT_EXCEEDED', `${label} must be a bounded array.`);
+    }
+    const result = [];
+    for (let index = 0; index < input.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(input, String(index));
+        if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', `${label} must be a dense data array.`);
+        }
+        result.push(descriptor.value);
+    }
+    for (const key of Reflect.ownKeys(input)) {
+        if (key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key))) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', `${label} cannot have extra properties.`);
+        }
+    }
+    return result;
+}
+function jsonCopy(input, limits, budget = { nodes: 0, bytes: 0 }) {
+    const active = new Set();
+    const visit = (value, depth) => {
+        budget.nodes += 1;
+        if (budget.nodes > limits.maxNodes || depth > limits.maxDepth) {
+            throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload exceeds configured JSON capacity.');
+        }
+        if (value === null ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && Number.isFinite(value))) {
+            budget.bytes += new TextEncoder().encode(JSON.stringify(value)).byteLength;
+            if (budget.bytes > limits.maxBytes) {
+                throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload exceeds byte capacity.');
+            }
+            return value;
+        }
+        if (typeof value === 'string') {
+            if (value.length > limits.maxStringLength) {
+                throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload string exceeds configured capacity.');
+            }
+            budget.bytes += new TextEncoder().encode(JSON.stringify(value)).byteLength;
+            if (budget.bytes > limits.maxBytes) {
+                throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload exceeds byte capacity.');
+            }
+            return value;
+        }
+        if (typeof value !== 'object' || active.has(value)) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload must be finite JSON without cycles.');
+        }
+        active.add(value);
+        if (Array.isArray(value)) {
+            budget.bytes += 2;
+            const result = [];
+            for (let index = 0; index < value.length; index += 1) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                if (!descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+                    throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload arrays must be dense data arrays.');
+                }
+                if (index > 0)
+                    budget.bytes += 1;
+                result.push(visit(descriptor.value, depth + 1));
+            }
+            for (const key of Reflect.ownKeys(value)) {
+                if (key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key))) {
+                    throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload arrays cannot have extra properties.');
+                }
+            }
+            active.delete(value);
+            return result;
+        }
+        if (!isRecord(value)) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload objects must be plain records.');
+        }
+        const result = {};
+        budget.bytes += 2;
+        let fieldIndex = 0;
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string')
+                throw new SyncProtocolError('INVALID_PAYLOAD', 'Symbols are not JSON fields.');
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor.enumerable || !('value' in descriptor)) {
+                throw new SyncProtocolError('INVALID_PAYLOAD', 'Payload objects must contain data fields.');
+            }
+            if (fieldIndex > 0)
+                budget.bytes += 1;
+            budget.bytes += new TextEncoder().encode(JSON.stringify(key)).byteLength + 1;
+            fieldIndex += 1;
+            if (budget.bytes > limits.maxBytes) {
+                throw new SyncProtocolError('LIMIT_EXCEEDED', 'Payload exceeds byte capacity.');
+            }
+            Object.defineProperty(result, key, {
+                value: visit(descriptor.value, depth + 1),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+        active.delete(value);
+        return result;
+    };
+    return visit(input, 0);
+}
+function validateCapabilities(input, limits) {
+    record(input, new Set(['versions', 'features', 'maxBatchSize', 'acknowledgements', 'cursors']), ['versions', 'features', 'maxBatchSize', 'acknowledgements', 'cursors'], 'Capabilities');
+    const capabilities = input;
+    const versionsInput = arrayValues(capabilities.versions, 'versions', limits.maxCapabilities);
+    const featuresInput = arrayValues(capabilities.features, 'features', limits.maxCapabilities);
+    if (versionsInput.length === 0 ||
+        !Number.isSafeInteger(capabilities.maxBatchSize) ||
+        capabilities.maxBatchSize < 1 ||
+        capabilities.maxBatchSize > limits.maxBatchSize ||
+        typeof capabilities.acknowledgements !== 'boolean' ||
+        typeof capabilities.cursors !== 'boolean') {
+        throw new SyncProtocolError('INVALID_CAPABILITIES', 'Capability values are invalid or exceed limits.');
+    }
+    const versions = versionsInput.map((version) => {
+        if (!Number.isSafeInteger(version) || version < 1) {
+            throw new SyncProtocolError('INVALID_CAPABILITIES', 'Supported versions must be positive integers.');
+        }
+        return version;
+    });
+    const features = featuresInput.map((feature) => {
+        boundedText(feature, 'feature', 128);
+        return feature;
+    });
+    if (new Set(versions).size !== versions.length || new Set(features).size !== features.length) {
+        throw new SyncProtocolError('INVALID_CAPABILITIES', 'Capability lists cannot contain duplicates.');
+    }
+    return {
+        versions,
+        features,
+        maxBatchSize: capabilities.maxBatchSize,
+        acknowledgements: capabilities.acknowledgements,
+        cursors: capabilities.cursors,
+    };
+}
+function validatePayload(kind, input, limits) {
+    if (!isRecord(input))
+        throw new SyncProtocolError('INVALID_PAYLOAD', 'Envelope payload must be a plain record.');
+    if (kind === 'hello') {
+        record(input, new Set(['capabilities']), ['capabilities'], 'Hello payload');
+        return { capabilities: validateCapabilities(input.capabilities, limits) };
+    }
+    if (kind === 'changes') {
+        record(input, new Set(['cursor', 'changes']), ['cursor', 'changes'], 'Changes payload');
+        if (input.cursor !== null)
+            boundedText(input.cursor, 'cursor', limits.maxStringLength);
+        const changes = arrayValues(input.changes, 'changes', limits.maxBatchSize);
+        const budget = { nodes: 0, bytes: 2 + Math.max(0, changes.length - 1) };
+        return {
+            cursor: input.cursor,
+            changes: changes.map((change) => jsonCopy(change, limits, budget)),
+        };
+    }
+    if (kind === 'ack') {
+        record(input, new Set(['messageId', 'accepted', 'cursor', 'reason']), ['messageId', 'accepted'], 'Acknowledgement payload');
+        boundedText(input.messageId, 'messageId', limits.maxStringLength);
+        if (typeof input.accepted !== 'boolean') {
+            throw new SyncProtocolError('INVALID_PAYLOAD', 'accepted must be a boolean.');
+        }
+        if (input.cursor !== undefined)
+            boundedText(input.cursor, 'cursor', limits.maxStringLength);
+        if (input.reason !== undefined)
+            boundedText(input.reason, 'reason', limits.maxStringLength);
+        if (input.accepted && input.reason !== undefined) {
+            throw new SyncProtocolError('INVALID_PAYLOAD', 'Accepted acknowledgements cannot include a rejection reason.');
+        }
+        return {
+            messageId: input.messageId,
+            accepted: input.accepted,
+            ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+            ...(input.reason === undefined ? {} : { reason: input.reason }),
+        };
+    }
+    if (kind === 'cursor') {
+        record(input, new Set(['stream', 'token']), ['stream', 'token'], 'Cursor payload');
+        boundedText(input.stream, 'stream', limits.maxStringLength);
+        if (input.token !== null)
+            boundedText(input.token, 'token', limits.maxStringLength);
+        return { stream: input.stream, token: input.token };
+    }
+    throw new SyncProtocolError('INVALID_ENVELOPE', 'Envelope kind is not supported.');
+}
+export function validateSyncEnvelope(input, inputLimits = {}) {
+    const limits = limitsOf(inputLimits);
+    record(input, envelopeFields, ['protocol', 'version', 'id', 'kind', 'payload'], 'Sync envelope');
+    if (input.protocol !== 'lp-sync') {
+        throw new SyncProtocolError('INVALID_ENVELOPE', 'Unsupported protocol identifier.');
+    }
+    if (input.version !== 1)
+        throw new SyncProtocolError('UNSUPPORTED_VERSION', 'Envelope version is not supported.');
+    boundedText(input.id, 'id', 256);
+    if (!['hello', 'changes', 'ack', 'cursor'].includes(input.kind)) {
+        throw new SyncProtocolError('INVALID_ENVELOPE', 'Envelope kind is not supported.');
+    }
+    const envelope = {
+        protocol: 'lp-sync',
+        version: 1,
+        id: input.id,
+        kind: input.kind,
+        payload: validatePayload(input.kind, input.payload, limits),
+    };
+    if (new TextEncoder().encode(JSON.stringify(envelope)).byteLength > limits.maxBytes) {
+        throw new SyncProtocolError('LIMIT_EXCEEDED', 'Envelope exceeds configured byte capacity.');
+    }
+    return envelope;
+}
+export function parseSyncEnvelope(text, limits = {}) {
+    const safeLimits = limitsOf(limits);
+    if (typeof text !== 'string')
+        throw new SyncProtocolError('INVALID_ENVELOPE', 'Input must be JSON text.');
+    if (text.length > safeLimits.maxBytes ||
+        new TextEncoder().encode(text).byteLength > safeLimits.maxBytes) {
+        throw new SyncProtocolError('LIMIT_EXCEEDED', 'Envelope exceeds configured byte capacity.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SyncProtocolError('INVALID_ENVELOPE', 'Input is not valid JSON.');
+    }
+    return validateSyncEnvelope(parsed, limits);
+}
+export function serializeSyncEnvelope(envelope, limits = {}) {
+    return JSON.stringify(validateSyncEnvelope(envelope, limits));
+}
+export function negotiateCapabilities(local, remote) {
+    const limits = limitsOf();
+    const safeLocal = validateCapabilities(local, limits);
+    const safeRemote = validateCapabilities(remote, limits);
+    const common = safeLocal.versions.filter((version) => safeRemote.versions.includes(version));
+    if (common.length === 0) {
+        throw new SyncProtocolError('NO_COMMON_VERSION', 'Peers have no shared protocol version.');
+    }
+    return {
+        version: Math.max(...common),
+        features: safeLocal.features.filter((feature) => safeRemote.features.includes(feature)).sort(),
+        maxBatchSize: Math.min(safeLocal.maxBatchSize, safeRemote.maxBatchSize),
+        acknowledgements: safeLocal.acknowledgements && safeRemote.acknowledgements,
+        cursors: safeLocal.cursors && safeRemote.cursors,
+    };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/sync-protocol-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Versioned synchronization message contracts, validation, and capability negotiation.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": "\u003e=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build \u0026\u0026 node scripts/check-types.mjs",
+    "test": "npm run build \u0026\u0026 node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}