@labacacia/nps-sdk 1.0.0-alpha.3 → 1.0.0-alpha.4

package/dist/core/codecs/ncp-codec.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Codec — Top-level encode/decode dispatcher
+// Routes to Tier-1 JSON or Tier-2 MsgPack based on frame header flags.
+import { parseFrameHeader, writeFrameHeader, buildFlags, EncodingTier, NcpError, DEFAULT_MAX_PAYLOAD, } from "../frame-header.js";
+import { encodeJson, decodeJson } from "./tier1-json-codec.js";
+import { encodeMsgPack, decodeMsgPack } from "./tier2-msgpack-codec.js";
+// ---------------------------------------------------------------------------
+// Decode
+// ---------------------------------------------------------------------------
+/**
+ * Decode a complete NCP frame from a buffer.
+ *
+ * @returns Decoded header + payload + bytes consumed.
+ * @throws {NcpError} NCP-ENCODING-UNSUPPORTED for reserved tiers.
+ * @throws {NcpError} NCP-FRAME-PAYLOAD-TOO-LARGE if payload exceeds max.
+ * @throws {NcpError} NCP-FRAME-INCOMPLETE if buffer doesn't have enough data.
+ */
+export function decodeFrame(buffer, options) {
+    const header = parseFrameHeader(buffer);
+    const maxPayload = options?.maxFramePayload ?? DEFAULT_MAX_PAYLOAD;
+    // NCP-F-09: Validate against negotiated max_frame_payload
+    if (header.payloadLength > maxPayload) {
+        throw new NcpError("NCP-FRAME-PAYLOAD-TOO-LARGE", `Payload ${header.payloadLength} exceeds max_frame_payload ${maxPayload}`);
+    }
+    const totalSize = header.headerSize + header.payloadLength;
+    // NCP-F-05: Buffer underrun — not enough data for payload
+    if (buffer.length < totalSize) {
+        throw new NcpError("NCP-FRAME-INCOMPLETE", `Buffer has ${buffer.length} bytes but frame needs ${totalSize}`);
+    }
+    // Extract payload bytes
+    const payloadBytes = buffer.subarray(header.headerSize, header.headerSize + header.payloadLength);
+    // Route to codec by tier
+    let payload;
+    switch (header.tier) {
+        case EncodingTier.Json:
+            payload = decodeJson(payloadBytes);
+            break;
+        case EncodingTier.MsgPack:
+            payload = decodeMsgPack(payloadBytes);
+            break;
+        default:
+            // NCP-E-05: Reserved tiers (0x02, 0x03)
+            throw new NcpError("NCP-ENCODING-UNSUPPORTED", `Unsupported encoding tier: 0x${header.tier.toString(16).padStart(2, "0")}`);
+    }
+    return { header, payload, bytesConsumed: totalSize };
+}
+// ---------------------------------------------------------------------------
+// Encode
+// ---------------------------------------------------------------------------
+/**
+ * Encode a payload into a complete NCP frame (header + payload bytes).
+ */
+export function encodeFrame(payload, options) {
+    const tier = options.tier ?? EncodingTier.Json;
+    // Encode payload
+    let payloadBytes;
+    switch (tier) {
+        case EncodingTier.Json:
+            payloadBytes = encodeJson(payload);
+            break;
+        case EncodingTier.MsgPack:
+            payloadBytes = encodeMsgPack(payload);
+            break;
+        default:
+            throw new NcpError("NCP-ENCODING-UNSUPPORTED", `Unsupported encoding tier for encode: ${tier}`);
+    }
+    // Determine if extended header is needed
+    const needsExtended = options.extended || payloadBytes.length > DEFAULT_MAX_PAYLOAD;
+    const flags = buildFlags({
+        tier,
+        final: options.final,
+        encrypted: options.encrypted,
+        extended: needsExtended,
+    });
+    const header = {
+        frameType: options.frameType,
+        flags,
+        payloadLength: payloadBytes.length,
+        tier,
+        isFinal: options.final ?? false,
+        isEncrypted: options.encrypted ?? false,
+        isExtended: needsExtended,
+        headerSize: needsExtended ? 8 : 4,
+    };
+    // Write frame
+    const frame = new Uint8Array(header.headerSize + payloadBytes.length);
+    writeFrameHeader(header, frame);
+    frame.set(payloadBytes, header.headerSize);
+    return frame;
+}
+//# sourceMappingURL=ncp-codec.js.map

package/dist/core/codecs/ncp-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ncp-codec.js","sourceRoot":"","sources":["../../../src/core/codecs/ncp-codec.ts"],"names":[],"mappings":"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"}

package/dist/core/codecs/tier1-json-codec.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// Tier-1 JSON Codec — UTF-8 JSON encode/decode
+// NPS-1 §8
+import { NcpError } from "../frame-header.js";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * Encode a frame payload to Tier-1 JSON bytes.
+ */
+export function encodeJson(payload) {
+    return encoder.encode(JSON.stringify(payload));
+}
+/**
+ * Decode Tier-1 JSON bytes to a parsed object.
+ * @throws {NcpError} NPS-CLIENT-BAD-FRAME on malformed JSON.
+ */
+export function decodeJson(bytes) {
+    const text = decoder.decode(bytes);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new NcpError("NPS-CLIENT-BAD-FRAME", "Malformed JSON payload");
+    }
+}
+//# sourceMappingURL=tier1-json-codec.js.map

package/dist/core/codecs/tier1-json-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier1-json-codec.js","sourceRoot":"","sources":["../../../src/core/codecs/tier1-json-codec.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,+CAA+C;AAC/C,WAAW;AAEX,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAClC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,sBAAsB,EACtB,wBAAwB,CACzB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/codecs/tier2-msgpack-codec.js

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// Tier-2 MsgPack Codec — Binary encode/decode
+// NPS-1 §8
+import { encode, decode } from "@msgpack/msgpack";
+import { NcpError } from "../frame-header.js";
+/**
+ * Encode a frame payload to Tier-2 MsgPack bytes.
+ */
+export function encodeMsgPack(payload) {
+    return encode(payload);
+}
+/**
+ * Decode Tier-2 MsgPack bytes to a parsed object.
+ * @throws {NcpError} NPS-CLIENT-BAD-FRAME on malformed MsgPack.
+ */
+export function decodeMsgPack(bytes) {
+    try {
+        return decode(bytes);
+    }
+    catch {
+        throw new NcpError("NPS-CLIENT-BAD-FRAME", "Malformed MsgPack payload");
+    }
+}
+//# sourceMappingURL=tier2-msgpack-codec.js.map

package/dist/core/codecs/tier2-msgpack-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier2-msgpack-codec.js","sourceRoot":"","sources":["../../../src/core/codecs/tier2-msgpack-codec.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,8CAA8C;AAC9C,WAAW;AAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAY,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,sBAAsB,EACtB,2BAA2B,CAC5B,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/crypto-provider.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// CryptoProvider interface — async crypto abstraction for Node + browser.
+// NPS-3 §10 / Q10 resolution in nps-ts-sdk-step7-plan.
+//
+// Implementations (NodeCryptoProvider, WebCryptoProvider) land at P3
+// alongside NIP tests. This file is structural scaffold only.
+export {};
+//# sourceMappingURL=crypto-provider.js.map

package/dist/core/crypto-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-provider.js","sourceRoot":"","sources":["../../src/core/crypto-provider.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,0EAA0E;AAC1E,uDAAuD;AACvD,EAAE;AACF,qEAAqE;AACrE,8DAA8D"}

package/dist/core/exceptions.js

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NPS exception hierarchy — ported from nps_sdk/core/exceptions.py
+// NPS-1 §6
+/** Base class for all NPS SDK errors. */
+export class NpsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NpsError";
+    }
+}
+/** Frame parse or structural error. */
+export class NpsFrameError extends NpsError {
+    constructor(message) {
+        super(message);
+        this.name = "NpsFrameError";
+    }
+}
+/** Encode or decode error. */
+export class NpsCodecError extends NpsError {
+    constructor(message) {
+        super(message);
+        this.name = "NpsCodecError";
+    }
+}
+/** Anchor cache miss — requested anchor ID not found. */
+export class NpsAnchorNotFoundError extends NpsError {
+    anchorId;
+    constructor(anchorId, message) {
+        super(message ?? `Anchor not found: ${anchorId}`);
+        this.name = "NpsAnchorNotFoundError";
+        this.anchorId = anchorId;
+    }
+}
+/** Anchor ID collision — same ID but different schema content. */
+export class NpsAnchorPoisonError extends NpsError {
+    anchorId;
+    constructor(anchorId, message) {
+        super(message ?? `Anchor poison detected: ${anchorId}`);
+        this.name = "NpsAnchorPoisonError";
+        this.anchorId = anchorId;
+    }
+}
+/** Stream-level error (sequence gap, unknown stream ID, etc.). */
+export class NpsStreamError extends NpsError {
+    constructor(message) {
+        super(message);
+        this.name = "NpsStreamError";
+    }
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/core/exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../src/core/exceptions.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,mEAAmE;AACnE,WAAW;AAEX,yCAAyC;AACzC,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,uCAAuC;AACvC,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,8BAA8B;AAC9B,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,yDAAyD;AACzD,MAAM,OAAO,sBAAuB,SAAQ,QAAQ;IACzC,QAAQ,CAAS;IAC1B,YAAY,QAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,OAAO,IAAI,qBAAqB,QAAQ,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,OAAO,oBAAqB,SAAQ,QAAQ;IACvC,QAAQ,CAAS;IAC1B,YAAY,QAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,OAAO,IAAI,2BAA2B,QAAQ,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,OAAO,cAAe,SAAQ,QAAQ;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF"}

package/dist/core/frame-header.js

@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Frame Header — Binary parse/write for NPS wire format
+// NPS-1 Neural Communication Protocol §3.1, §3.2
+// ---------------------------------------------------------------------------
+// Enums
+// ---------------------------------------------------------------------------
+/** Wire encoding tier (NPS-1 §3.2, flags bits 0-1). */
+export var EncodingTier;
+(function (EncodingTier) {
+    /** Tier-1: UTF-8 JSON — development & compatibility. */
+    EncodingTier[EncodingTier["Json"] = 0] = "Json";
+    /** Tier-2: MessagePack binary — production (~60% compression). */
+    EncodingTier[EncodingTier["MsgPack"] = 1] = "MsgPack";
+    // 0x02 = Reserved
+    // 0x03 = Reserved
+})(EncodingTier || (EncodingTier = {}));
+/** Unified frame type namespace for the full NPS suite (NPS-0 §9). */
+export var FrameType;
+(function (FrameType) {
+    // NCP 0x01–0x0F
+    FrameType[FrameType["Anchor"] = 1] = "Anchor";
+    FrameType[FrameType["Diff"] = 2] = "Diff";
+    FrameType[FrameType["Stream"] = 3] = "Stream";
+    FrameType[FrameType["Caps"] = 4] = "Caps";
+    FrameType[FrameType["Align"] = 5] = "Align";
+    FrameType[FrameType["Hello"] = 6] = "Hello";
+    // NWP 0x10–0x1F
+    FrameType[FrameType["Query"] = 16] = "Query";
+    FrameType[FrameType["Action"] = 17] = "Action";
+    FrameType[FrameType["Subscribe"] = 18] = "Subscribe";
+    // NIP 0x20–0x2F
+    FrameType[FrameType["Ident"] = 32] = "Ident";
+    FrameType[FrameType["Trust"] = 33] = "Trust";
+    FrameType[FrameType["Revoke"] = 34] = "Revoke";
+    // NDP 0x30–0x3F
+    FrameType[FrameType["Announce"] = 48] = "Announce";
+    FrameType[FrameType["Resolve"] = 49] = "Resolve";
+    FrameType[FrameType["Graph"] = 50] = "Graph";
+    // NOP 0x40–0x4F
+    FrameType[FrameType["Task"] = 64] = "Task";
+    FrameType[FrameType["Delegate"] = 65] = "Delegate";
+    FrameType[FrameType["Sync"] = 66] = "Sync";
+    FrameType[FrameType["AlignStream"] = 67] = "AlignStream";
+    // System 0xF0–0xFF
+    FrameType[FrameType["Error"] = 254] = "Error";
+})(FrameType || (FrameType = {}));
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default (compact) header size in bytes. */
+export const DEFAULT_HEADER_SIZE = 4;
+/** Extended header size in bytes (EXT=1). */
+export const EXTENDED_HEADER_SIZE = 8;
+/** Maximum payload in default mode (64 KiB − 1). */
+export const DEFAULT_MAX_PAYLOAD = 0xffff;
+/** Maximum payload in extended mode (4 GiB − 1). */
+export const EXTENDED_MAX_PAYLOAD = 0xffffffff;
+// Flag bit positions (NPS-1 §3.2)
+const TIER_MASK = 0x03; // bits 0-1
+const FINAL_BIT = 0x04; // bit 2
+const ENC_BIT = 0x08; // bit 3
+const RESERVED_MASK = 0x70; // bits 4-6
+const EXT_BIT = 0x80; // bit 7
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+/** NCP protocol error with machine-readable error code. */
+export class NcpError extends Error {
+    code;
+    // `code` accepts NcpErrorCode constants (preferred) as well as NPS status
+    // strings that are not NCP-prefixed (e.g. "NPS-CLIENT-CONFLICT") for cases
+    // where the spec delegates to NPS-level codes without assigning an NCP code.
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "NcpError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Parse
+// ---------------------------------------------------------------------------
+/**
+ * Parse a frame header from the start of the buffer.
+ * Reads 2 bytes first to determine EXT, then reads remaining bytes.
+ *
+ * @throws {NcpError} NCP-FRAME-FLAGS-INVALID if reserved bits 4-6 are non-zero.
+ * @throws {NcpError} NCP-FRAME-PARSE-ERROR if buffer is too small.
+ * @throws {NcpError} NCP-FRAME-PAYLOAD-TOO-LARGE if opts.max_frame_payload is set and exceeded.
+ */
+export function parseFrameHeader(buffer, opts) {
+    if (buffer.length < 2) {
+        throw new NcpError("NCP-FRAME-PARSE-ERROR", `Buffer too small to read frame type and flags: need >= 2 bytes, got ${buffer.length}`);
+    }
+    const frameType = buffer[0];
+    const flags = buffer[1];
+    // Validate reserved bits (NPS-1 §3.2: bits 4-6 MUST be 0)
+    if ((flags & RESERVED_MASK) !== 0) {
+        throw new NcpError("NCP-FRAME-FLAGS-INVALID", "Reserved flag bits 4-6 must be zero");
+    }
+    const isExtended = (flags & EXT_BIT) !== 0;
+    if (isExtended) {
+        if (buffer.length < EXTENDED_HEADER_SIZE) {
+            throw new NcpError("NCP-FRAME-PARSE-ERROR", `Buffer too small for extended header: need ${EXTENDED_HEADER_SIZE} bytes, got ${buffer.length}`);
+        }
+        const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+        const payloadLength = view.getUint32(2, false); // big-endian
+        if (opts?.max_frame_payload !== undefined &&
+            payloadLength > opts.max_frame_payload) {
+            throw new NcpError("NCP-FRAME-PAYLOAD-TOO-LARGE", `Payload length ${payloadLength} exceeds max_frame_payload ${opts.max_frame_payload}`);
+        }
+        return {
+            frameType,
+            flags,
+            payloadLength,
+            tier: (flags & TIER_MASK),
+            isFinal: (flags & FINAL_BIT) !== 0,
+            isEncrypted: (flags & ENC_BIT) !== 0,
+            isExtended: true,
+            headerSize: EXTENDED_HEADER_SIZE,
+        };
+    }
+    // Default 4-byte header
+    if (buffer.length < DEFAULT_HEADER_SIZE) {
+        throw new NcpError("NCP-FRAME-PARSE-ERROR", `Buffer too small for header: need ${DEFAULT_HEADER_SIZE} bytes, got ${buffer.length}`);
+    }
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    const payloadLength = view.getUint16(2, false); // big-endian
+    if (opts?.max_frame_payload !== undefined &&
+        payloadLength > opts.max_frame_payload) {
+        throw new NcpError("NCP-FRAME-PAYLOAD-TOO-LARGE", `Payload length ${payloadLength} exceeds max_frame_payload ${opts.max_frame_payload}`);
+    }
+    return {
+        frameType,
+        flags,
+        payloadLength,
+        tier: (flags & TIER_MASK),
+        isFinal: (flags & FINAL_BIT) !== 0,
+        isEncrypted: (flags & ENC_BIT) !== 0,
+        isExtended: false,
+        headerSize: DEFAULT_HEADER_SIZE,
+    };
+}
+// ---------------------------------------------------------------------------
+// Write
+// ---------------------------------------------------------------------------
+/**
+ * Write a frame header into the buffer.
+ * @returns Number of bytes written (4 or 8).
+ * @throws {Error} if buffer is too small.
+ */
+export function writeFrameHeader(header, buffer) {
+    const size = header.isExtended ? EXTENDED_HEADER_SIZE : DEFAULT_HEADER_SIZE;
+    if (buffer.length < size) {
+        throw new Error(`Destination buffer must be at least ${size} bytes, got ${buffer.length}`);
+    }
+    buffer[0] = header.frameType;
+    buffer[1] = header.flags;
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    if (header.isExtended) {
+        view.setUint32(2, header.payloadLength, false); // big-endian
+        buffer[6] = 0; // reserved
+        buffer[7] = 0; // reserved
+    }
+    else {
+        view.setUint16(2, header.payloadLength, false); // big-endian
+    }
+    return size;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Build a flags byte from individual options. */
+export function buildFlags(options) {
+    let flags = (options.tier ?? EncodingTier.Json) & TIER_MASK;
+    if (options.final)
+        flags |= FINAL_BIT;
+    if (options.encrypted)
+        flags |= ENC_BIT;
+    if (options.extended)
+        flags |= EXT_BIT;
+    return flags;
+}
+//# sourceMappingURL=frame-header.js.map

package/dist/core/frame-header.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-header.js","sourceRoot":"","sources":["../../src/core/frame-header.ts"],"names":[],"mappings":"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"}

package/dist/core/frame-registry.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Frame Registry — Maps frame type bytes to protocol identifiers
+// NPS-0 §9 Unified frame namespace
+import { FrameType, NcpError } from "./frame-header.js";
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+/**
+ * Maps frame type bytes to metadata.
+ * Built once at startup, then read-only.
+ */
+export class FrameRegistry {
+    map;
+    constructor(entries) {
+        this.map = new Map(entries.map((e) => [e.frameType, e]));
+    }
+    /**
+     * Resolve a frame type byte to its registry entry.
+     * @throws {NcpError} NCP-FRAME-UNKNOWN-TYPE if not registered.
+     */
+    resolve(frameType) {
+        const entry = this.map.get(frameType);
+        if (!entry) {
+            throw new NcpError("NCP-FRAME-UNKNOWN-TYPE", `No entry registered for frame type 0x${frameType.toString(16).padStart(2, "0")}`);
+        }
+        return entry;
+    }
+    /** Check if a frame type is registered. */
+    has(frameType) {
+        return this.map.has(frameType);
+    }
+    /**
+     * Create a registry pre-populated with all NCP core frames.
+     * Upper-layer protocols can extend via the builder.
+     */
+    static createDefault() {
+        return new FrameRegistryBuilder()
+            .add(FrameType.Anchor, "AnchorFrame", "ncp")
+            .add(FrameType.Diff, "DiffFrame", "ncp")
+            .add(FrameType.Stream, "StreamFrame", "ncp")
+            .add(FrameType.Caps, "CapsFrame", "ncp")
+            .add(FrameType.Align, "AlignFrame", "ncp") // deprecated
+            .add(FrameType.Hello, "HelloFrame", "ncp")
+            .add(FrameType.Error, "ErrorFrame", "system")
+            .build();
+    }
+}
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+export class FrameRegistryBuilder {
+    entries = [];
+    add(frameType, name, protocol) {
+        this.entries.push({ frameType, name, protocol });
+        return this;
+    }
+    build() {
+        return new FrameRegistry(this.entries);
+    }
+}
+//# sourceMappingURL=frame-registry.js.map

package/dist/core/frame-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-registry.js","sourceRoot":"","sources":["../../src/core/frame-registry.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,qEAAqE;AACrE,mCAAmC;AAEnC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAiBxD,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,OAAO,aAAa;IACP,GAAG,CAAkC;IAEtD,YAAY,OAA6B;QACvC,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,SAAiB;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,QAAQ,CAChB,wBAAwB,EACxB,wCAAwC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAClF,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2CAA2C;IAC3C,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,aAAa;QAClB,OAAO,IAAI,oBAAoB,EAAE;aAC9B,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC;aAC3C,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC;aACvC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC;aAC3C,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC;aACvC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC,aAAa;aACvD,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC;aACzC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,CAAC;aAC5C,KAAK,EAAE,CAAC;IACb,CAAC;CACF;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,MAAM,OAAO,oBAAoB;IACd,OAAO,GAAyB,EAAE,CAAC;IAEpD,GAAG,CAAC,SAAiB,EAAE,IAAY,EAAE,QAAkB;QACrD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK;QACH,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/core/frames.js

@@ -0,0 +1,154 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * NPS wire-level frame primitives: FrameType, FrameFlags, EncodingTier, FrameHeader.
+ */
+import { NpsFrameError } from "./exceptions.js";
+// ── FrameType ────────────────────────────────────────────────────────────────
+/** Unified frame byte namespace for the full NPS suite (NPS-0 §9). */
+export var FrameType;
+(function (FrameType) {
+    // NCP  0x01–0x0F
+    FrameType[FrameType["ANCHOR"] = 1] = "ANCHOR";
+    FrameType[FrameType["DIFF"] = 2] = "DIFF";
+    FrameType[FrameType["STREAM"] = 3] = "STREAM";
+    FrameType[FrameType["CAPS"] = 4] = "CAPS";
+    FrameType[FrameType["ALIGN"] = 5] = "ALIGN";
+    FrameType[FrameType["HELLO"] = 6] = "HELLO";
+    // NWP  0x10–0x1F
+    FrameType[FrameType["QUERY"] = 16] = "QUERY";
+    FrameType[FrameType["ACTION"] = 17] = "ACTION";
+    // NIP  0x20–0x2F
+    FrameType[FrameType["IDENT"] = 32] = "IDENT";
+    FrameType[FrameType["TRUST"] = 33] = "TRUST";
+    FrameType[FrameType["REVOKE"] = 34] = "REVOKE";
+    // NDP  0x30–0x3F
+    FrameType[FrameType["ANNOUNCE"] = 48] = "ANNOUNCE";
+    FrameType[FrameType["RESOLVE"] = 49] = "RESOLVE";
+    FrameType[FrameType["GRAPH"] = 50] = "GRAPH";
+    // NOP  0x40–0x4F
+    FrameType[FrameType["TASK"] = 64] = "TASK";
+    FrameType[FrameType["DELEGATE"] = 65] = "DELEGATE";
+    FrameType[FrameType["SYNC"] = 66] = "SYNC";
+    FrameType[FrameType["ALIGN_STREAM"] = 67] = "ALIGN_STREAM";
+    // Reserved / System  0xF0–0xFF
+    FrameType[FrameType["ERROR"] = 254] = "ERROR";
+})(FrameType || (FrameType = {}));
+// ── EncodingTier ─────────────────────────────────────────────────────────────
+/**
+ * Wire encoding tier, stored in the lower 2 bits of the flags byte (NPS-1 §3.2).
+ * 0x00 = Tier-1 JSON — human-readable; development / compatibility.
+ * 0x01 = Tier-2 MsgPack — binary, ~60 % smaller; production default.
+ */
+export var EncodingTier;
+(function (EncodingTier) {
+    EncodingTier[EncodingTier["JSON"] = 0] = "JSON";
+    EncodingTier[EncodingTier["MSGPACK"] = 1] = "MSGPACK";
+})(EncodingTier || (EncodingTier = {}));
+// ── FrameFlags ───────────────────────────────────────────────────────────────
+/**
+ * Flags byte in the NPS frame header (NPS-1 §3.2).
+ * Bit layout (LSB = bit 0):
+ *   Bits 0–1 (T0,T1) : Encoding tier
+ *   Bit 2  (FINAL)   : Last chunk of a StreamFrame; non-stream frames MUST set this
+ *   Bit 3  (ENC)     : Payload encrypted
+ *   Bits 4–6 (RSV)   : Reserved — sender MUST write 0
+ *   Bit 7  (EXT)     : Extended 8-byte header
+ */
+export const FrameFlags = {
+    NONE: 0x00,
+    TIER1_JSON: 0x00,
+    TIER2_MSGPACK: 0x01,
+    FINAL: 0x04,
+    ENCRYPTED: 0x08,
+    EXT: 0x80,
+};
+// ── Constants ─────────────────────────────────────────────────────────────────
+export const DEFAULT_HEADER_SIZE = 4;
+export const EXTENDED_HEADER_SIZE = 8;
+export const DEFAULT_MAX_PAYLOAD = 0xffff; // 65 535 bytes
+export const EXTENDED_MAX_PAYLOAD = 0xffffffff; // 4 GiB - 1
+// ── FrameHeader ──────────────────────────────────────────────────────────────
+/**
+ * NPS frame header, present at the start of every wire message (NPS-1 §3.1).
+ *
+ * Default (4 bytes, EXT=0):
+ *   Byte 0   : FrameType
+ *   Byte 1   : Flags
+ *   Byte 2–3 : PayloadLength (big-endian uint16)
+ *
+ * Extended (8 bytes, EXT=1):
+ *   Byte 0   : FrameType
+ *   Byte 1   : Flags (bit 7 = 1)
+ *   Byte 2–3 : Reserved (must be 0)
+ *   Byte 4–7 : PayloadLength (big-endian uint32)
+ */
+export class FrameHeader {
+    frameType;
+    flags;
+    payloadLength;
+    constructor(frameType, flags, payloadLength) {
+        this.frameType = frameType;
+        this.flags = flags;
+        this.payloadLength = payloadLength;
+    }
+    get isExtended() {
+        return (this.flags & FrameFlags.EXT) !== 0;
+    }
+    get headerSize() {
+        return this.isExtended ? EXTENDED_HEADER_SIZE : DEFAULT_HEADER_SIZE;
+    }
+    get encodingTier() {
+        return (this.flags & 0x03);
+    }
+    get isFinal() {
+        return (this.flags & 0x04) !== 0;
+    }
+    get isEncrypted() {
+        return (this.flags & 0x08) !== 0;
+    }
+    // ── Parsing ───────────────────────────────────────────────────────────────
+    static parse(buf) {
+        if (buf.length < 2) {
+            throw new NpsFrameError(`Buffer too small to read frame type and flags: need >= 2 bytes, got ${buf.length}.`);
+        }
+        const flags = buf[1];
+        const ext = (flags & FrameFlags.EXT) !== 0;
+        if (ext) {
+            if (buf.length < EXTENDED_HEADER_SIZE) {
+                throw new NpsFrameError(`Buffer too small for extended frame header: need ${EXTENDED_HEADER_SIZE} bytes, got ${buf.length}.`);
+            }
+            const view = new DataView(buf.buffer, buf.byteOffset);
+            const payloadLength = view.getUint32(4, false); // big-endian
+            return new FrameHeader(buf[0], flags, payloadLength);
+        }
+        if (buf.length < DEFAULT_HEADER_SIZE) {
+            throw new NpsFrameError(`Buffer too small for frame header: need ${DEFAULT_HEADER_SIZE} bytes, got ${buf.length}.`);
+        }
+        const view = new DataView(buf.buffer, buf.byteOffset);
+        const payloadLength = view.getUint16(2, false); // big-endian
+        return new FrameHeader(buf[0], flags, payloadLength);
+    }
+    // ── Serialisation ─────────────────────────────────────────────────────────
+    toBytes() {
+        if (this.isExtended) {
+            const buf = new Uint8Array(EXTENDED_HEADER_SIZE);
+            const view = new DataView(buf.buffer);
+            view.setUint8(0, this.frameType);
+            view.setUint8(1, this.flags);
+            view.setUint16(2, 0, false); // reserved
+            view.setUint32(4, this.payloadLength, false);
+            return buf;
+        }
+        const buf = new Uint8Array(DEFAULT_HEADER_SIZE);
+        const view = new DataView(buf.buffer);
+        view.setUint8(0, this.frameType);
+        view.setUint8(1, this.flags);
+        view.setUint16(2, this.payloadLength, false);
+        return buf;
+    }
+    toString() {
+        return `FrameHeader(frameType=0x${this.frameType.toString(16).padStart(2, "0")}, flags=0x${this.flags.toString(16).padStart(2, "0")}, payloadLength=${this.payloadLength})`;
+    }
+}
+//# sourceMappingURL=frames.js.map