@labacacia/nps-sdk 1.0.0-alpha.6 → 1.0.0-alpha.8

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.d.ts

@@ -0,0 +1,87 @@
+/** Wire encoding tier (NPS-1 §3.2, flags bits 0-1). */
+export declare enum EncodingTier {
+    /** Tier-1: UTF-8 JSON — development & compatibility. */
+    Json = 0,
+    /** Tier-2: MessagePack binary — production (~60% compression). */
+    MsgPack = 1
+}
+/** Unified frame type namespace for the full NPS suite (NPS-0 §9). */
+export declare enum FrameType {
+    Anchor = 1,
+    Diff = 2,
+    Stream = 3,
+    Caps = 4,
+    Align = 5,// deprecated — use AlignStream (0x43)
+    Hello = 6,
+    Query = 16,
+    Action = 17,
+    Subscribe = 18,
+    Ident = 32,
+    Trust = 33,
+    Revoke = 34,
+    Announce = 48,
+    Resolve = 49,
+    Graph = 50,
+    Task = 64,
+    Delegate = 65,
+    Sync = 66,
+    AlignStream = 67,
+    Error = 254
+}
+/** Default (compact) header size in bytes. */
+export declare const DEFAULT_HEADER_SIZE = 4;
+/** Extended header size in bytes (EXT=1). */
+export declare const EXTENDED_HEADER_SIZE = 8;
+/** Maximum payload in default mode (64 KiB − 1). */
+export declare const DEFAULT_MAX_PAYLOAD = 65535;
+/** Maximum payload in extended mode (4 GiB − 1). */
+export declare const EXTENDED_MAX_PAYLOAD = 4294967295;
+/** NCP protocol error with machine-readable error code. */
+export declare class NcpError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Parsed frame header. */
+export interface FrameHeader {
+    /** Raw frame type byte. */
+    frameType: number;
+    /** Raw flags byte. */
+    flags: number;
+    /** Payload length in bytes. */
+    payloadLength: number;
+    /** Encoding tier extracted from flags bits 0-1. */
+    tier: EncodingTier;
+    /** True when FINAL flag (bit 2) is set. */
+    isFinal: boolean;
+    /** True when ENC flag (bit 3) is set. */
+    isEncrypted: boolean;
+    /** True when EXT flag (bit 7) is set — 8-byte header. */
+    isExtended: boolean;
+    /** Header size in bytes (4 or 8). */
+    headerSize: number;
+}
+/**
+ * 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 declare function parseFrameHeader(buffer: Uint8Array, opts?: {
+    max_frame_payload?: number;
+}): FrameHeader;
+/**
+ * Write a frame header into the buffer.
+ * @returns Number of bytes written (4 or 8).
+ * @throws {Error} if buffer is too small.
+ */
+export declare function writeFrameHeader(header: FrameHeader, buffer: Uint8Array): number;
+/** Build a flags byte from individual options. */
+export declare function buildFlags(options: {
+    tier?: EncodingTier;
+    final?: boolean;
+    encrypted?: boolean;
+    extended?: boolean;
+}): number;
+//# sourceMappingURL=frame-header.d.ts.map

package/dist/core/frame-header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-header.d.ts","sourceRoot":"","sources":["../../src/core/frame-header.ts"],"names":[],"mappings":"AAUA,uDAAuD;AACvD,oBAAY,YAAY;IACtB,wDAAwD;IACxD,IAAI,IAAO;IACX,kEAAkE;IAClE,OAAO,IAAO;CAGf;AAED,sEAAsE;AACtE,oBAAY,SAAS;IAEnB,MAAM,IAAO;IACb,IAAI,IAAO;IACX,MAAM,IAAO;IACb,IAAI,IAAO;IACX,KAAK,IAAO,CAAE,sCAAsC;IACpD,KAAK,IAAO;IAEZ,KAAK,KAAO;IACZ,MAAM,KAAO;IACb,SAAS,KAAO;IAEhB,KAAK,KAAO;IACZ,KAAK,KAAO;IACZ,MAAM,KAAO;IAEb,QAAQ,KAAO;IACf,OAAO,KAAO;IACd,KAAK,KAAO;IAEZ,IAAI,KAAO;IACX,QAAQ,KAAO;IACf,IAAI,KAAO;IACX,WAAW,KAAO;IAElB,KAAK,MAAO;CACb;AAMD,8CAA8C;AAC9C,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,6CAA6C;AAC7C,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,oDAAoD;AACpD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,oDAAoD;AACpD,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAa/C,2DAA2D;AAC3D,qBAAa,QAAS,SAAQ,KAAK;aAKf,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAMD,2BAA2B;AAC3B,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,IAAI,EAAE,YAAY,CAAC;IACnB,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,WAAW,EAAE,OAAO,CAAC;IACrB,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAC;IACpB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,EAClB,IAAI,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,GACpC,WAAW,CA6Fb;AAMD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,UAAU,GACjB,MAAM,CA0BR;AAMD,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,OAAO,EAAE;IAClC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,MAAM,CAMT"}

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.d.ts

@@ -0,0 +1,35 @@
+export type Protocol = "ncp" | "nwp" | "nip" | "ndp" | "nop" | "system";
+export interface FrameRegistryEntry {
+    /** Frame type byte. */
+    frameType: number;
+    /** Human-readable name. */
+    name: string;
+    /** Protocol this frame belongs to. */
+    protocol: Protocol;
+}
+/**
+ * Maps frame type bytes to metadata.
+ * Built once at startup, then read-only.
+ */
+export declare class FrameRegistry {
+    private readonly map;
+    constructor(entries: FrameRegistryEntry[]);
+    /**
+     * Resolve a frame type byte to its registry entry.
+     * @throws {NcpError} NCP-FRAME-UNKNOWN-TYPE if not registered.
+     */
+    resolve(frameType: number): FrameRegistryEntry;
+    /** Check if a frame type is registered. */
+    has(frameType: number): boolean;
+    /**
+     * Create a registry pre-populated with all NCP core frames.
+     * Upper-layer protocols can extend via the builder.
+     */
+    static createDefault(): FrameRegistry;
+}
+export declare class FrameRegistryBuilder {
+    private readonly entries;
+    add(frameType: number, name: string, protocol: Protocol): this;
+    build(): FrameRegistry;
+}
+//# sourceMappingURL=frame-registry.d.ts.map

package/dist/core/frame-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-registry.d.ts","sourceRoot":"","sources":["../../src/core/frame-registry.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;AAExE,MAAM,WAAW,kBAAkB;IACjC,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAMD;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkC;gBAE1C,OAAO,EAAE,kBAAkB,EAAE;IAIzC;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB;IAW9C,2CAA2C;IAC3C,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI/B;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,aAAa;CAWtC;AAMD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAK9D,KAAK,IAAI,aAAa;CAGvB"}

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.d.ts

@@ -0,0 +1,82 @@
+/** Unified frame byte namespace for the full NPS suite (NPS-0 §9). */
+export declare enum FrameType {
+    ANCHOR = 1,
+    DIFF = 2,
+    STREAM = 3,
+    CAPS = 4,
+    ALIGN = 5,// deprecated — use AlignStream (0x43)
+    HELLO = 6,
+    QUERY = 16,
+    ACTION = 17,
+    SUBSCRIBE = 18,
+    IDENT = 32,
+    TRUST = 33,
+    REVOKE = 34,
+    ANNOUNCE = 48,
+    RESOLVE = 49,
+    GRAPH = 50,
+    TASK = 64,
+    DELEGATE = 65,
+    SYNC = 66,
+    ALIGN_STREAM = 67,
+    ERROR = 254
+}
+/**
+ * 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 declare enum EncodingTier {
+    JSON = 0,
+    MSGPACK = 1
+}
+/**
+ * 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 declare const FrameFlags: {
+    readonly NONE: 0;
+    readonly TIER1_JSON: 0;
+    readonly TIER2_MSGPACK: 1;
+    readonly FINAL: 4;
+    readonly ENCRYPTED: 8;
+    readonly EXT: 128;
+};
+export declare const DEFAULT_HEADER_SIZE = 4;
+export declare const EXTENDED_HEADER_SIZE = 8;
+export declare const DEFAULT_MAX_PAYLOAD = 65535;
+export declare const EXTENDED_MAX_PAYLOAD = 4294967295;
+/**
+ * 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 declare class FrameHeader {
+    readonly frameType: FrameType;
+    readonly flags: number;
+    readonly payloadLength: number;
+    constructor(frameType: FrameType, flags: number, payloadLength: number);
+    get isExtended(): boolean;
+    get headerSize(): number;
+    get encodingTier(): EncodingTier;
+    get isFinal(): boolean;
+    get isEncrypted(): boolean;
+    static parse(buf: Uint8Array): FrameHeader;
+    toBytes(): Uint8Array;
+    toString(): string;
+}
+//# sourceMappingURL=frames.d.ts.map

package/dist/core/frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/core/frames.ts"],"names":[],"mappings":"AAWA,sEAAsE;AACtE,oBAAY,SAAS;IAEnB,MAAM,IAAa;IACnB,IAAI,IAAe;IACnB,MAAM,IAAa;IACnB,IAAI,IAAe;IACnB,KAAK,IAAc,CAAE,sCAAsC;IAC3D,KAAK,IAAc;IAGnB,KAAK,KAAc;IACnB,MAAM,KAAa;IACnB,SAAS,KAAU;IAGnB,KAAK,KAAc;IACnB,KAAK,KAAc;IACnB,MAAM,KAAa;IAGnB,QAAQ,KAAW;IACnB,OAAO,KAAY;IACnB,KAAK,KAAc;IAGnB,IAAI,KAAe;IACnB,QAAQ,KAAW;IACnB,IAAI,KAAe;IACnB,YAAY,KAAO;IAGnB,KAAK,MAAc;CACpB;AAID;;;;GAIG;AACH,oBAAY,YAAY;IACtB,IAAI,IAAU;IACd,OAAO,IAAO;CACf;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU;;;;;;;CAOb,CAAC;AAIX,eAAO,MAAM,mBAAmB,IAAK,CAAC;AACtC,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,mBAAmB,QAAU,CAAC;AAC3C,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAI/C;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;aAEJ,SAAS,EAAE,SAAS;aACpB,KAAK,EAAE,MAAM;aACb,aAAa,EAAE,MAAM;gBAFrB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM;IAGvC,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,YAAY,IAAI,YAAY,CAE/B;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAID,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,UAAU,GAAG,WAAW;IAiC1C,OAAO,IAAI,UAAU;IAkBrB,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/core/frames.js

@@ -0,0 +1,155 @@
+// 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";
+    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["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

package/dist/core/frames.js.map

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