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

package/src/core/frame-header.ts

@@ -1,282 +0,0 @@
-// 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 enum EncodingTier {
-  /** Tier-1: UTF-8 JSON — development & compatibility. */
-  Json = 0x00,
-  /** Tier-2: MessagePack binary — production (~60% compression). */
-  MsgPack = 0x01,
-  // 0x02 = Reserved
-  // 0x03 = Reserved
-}
-
-/** Unified frame type namespace for the full NPS suite (NPS-0 §9). */
-export enum FrameType {
-  // NCP 0x01–0x0F
-  Anchor = 0x01,
-  Diff = 0x02,
-  Stream = 0x03,
-  Caps = 0x04,
-  Align = 0x05, // deprecated — use AlignStream (0x43)
-  Hello = 0x06,
-  // NWP 0x10–0x1F
-  Query = 0x10,
-  Action = 0x11,
-  Subscribe = 0x12,
-  // NIP 0x20–0x2F
-  Ident = 0x20,
-  Trust = 0x21,
-  Revoke = 0x22,
-  // NDP 0x30–0x3F
-  Announce = 0x30,
-  Resolve = 0x31,
-  Graph = 0x32,
-  // NOP 0x40–0x4F
-  Task = 0x40,
-  Delegate = 0x41,
-  Sync = 0x42,
-  AlignStream = 0x43,
-  // System 0xF0–0xFF
-  Error = 0xfe,
-}
-
-// ---------------------------------------------------------------------------
-// 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` 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(
-    public readonly code: string,
-    message: string,
-  ) {
-    super(message);
-    this.name = "NcpError";
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Parsed header
-// ---------------------------------------------------------------------------
-
-/** 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
-// ---------------------------------------------------------------------------
-
-/**
- * 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: Uint8Array,
-  opts?: { max_frame_payload?: number },
-): FrameHeader {
-  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) as EncodingTier,
-      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) as EncodingTier,
-    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: FrameHeader,
-  buffer: Uint8Array,
-): number {
-  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: {
-  tier?: EncodingTier;
-  final?: boolean;
-  encrypted?: boolean;
-  extended?: boolean;
-}): number {
-  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;
-}

package/src/core/frame-registry.ts

@@ -1,91 +0,0 @@
-// 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";
-
-// ---------------------------------------------------------------------------
-// Protocol identifier for routing
-// ---------------------------------------------------------------------------
-
-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;
-}
-
-// ---------------------------------------------------------------------------
-// Registry
-// ---------------------------------------------------------------------------
-
-/**
- * Maps frame type bytes to metadata.
- * Built once at startup, then read-only.
- */
-export class FrameRegistry {
-  private readonly map: Map<number, FrameRegistryEntry>;
-
-  constructor(entries: FrameRegistryEntry[]) {
-    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: number): FrameRegistryEntry {
-    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: number): boolean {
-    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(): FrameRegistry {
-    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 {
-  private readonly entries: FrameRegistryEntry[] = [];
-
-  add(frameType: number, name: string, protocol: Protocol): this {
-    this.entries.push({ frameType, name, protocol });
-    return this;
-  }
-
-  build(): FrameRegistry {
-    return new FrameRegistry(this.entries);
-  }
-}

package/src/core/frames.ts

@@ -1,184 +0,0 @@
-// 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 enum FrameType {
-  // NCP  0x01–0x0F
-  ANCHOR       = 0x01,
-  DIFF         = 0x02,
-  STREAM       = 0x03,
-  CAPS         = 0x04,
-  ALIGN        = 0x05, // deprecated — use AlignStream (0x43)
-  HELLO        = 0x06,
-
-  // NWP  0x10–0x1F
-  QUERY        = 0x10,
-  ACTION       = 0x11,
-
-  // NIP  0x20–0x2F
-  IDENT        = 0x20,
-  TRUST        = 0x21,
-  REVOKE       = 0x22,
-
-  // NDP  0x30–0x3F
-  ANNOUNCE     = 0x30,
-  RESOLVE      = 0x31,
-  GRAPH        = 0x32,
-
-  // NOP  0x40–0x4F
-  TASK         = 0x40,
-  DELEGATE     = 0x41,
-  SYNC         = 0x42,
-  ALIGN_STREAM = 0x43,
-
-  // Reserved / System  0xF0–0xFF
-  ERROR        = 0xFE,
-}
-
-// ── 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 enum EncodingTier {
-  JSON    = 0x00,
-  MSGPACK = 0x01,
-}
-
-// ── 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,
-} as const;
-
-// ── 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 {
-  constructor(
-    public readonly frameType: FrameType,
-    public readonly flags: number,
-    public readonly payloadLength: number,
-  ) {}
-
-  get isExtended(): boolean {
-    return (this.flags & FrameFlags.EXT) !== 0;
-  }
-
-  get headerSize(): number {
-    return this.isExtended ? EXTENDED_HEADER_SIZE : DEFAULT_HEADER_SIZE;
-  }
-
-  get encodingTier(): EncodingTier {
-    return (this.flags & 0x03) as EncodingTier;
-  }
-
-  get isFinal(): boolean {
-    return (this.flags & 0x04) !== 0;
-  }
-
-  get isEncrypted(): boolean {
-    return (this.flags & 0x08) !== 0;
-  }
-
-  // ── Parsing ───────────────────────────────────────────────────────────────
-
-  static parse(buf: Uint8Array): FrameHeader {
-    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]! as FrameType, 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]! as FrameType, flags, payloadLength);
-  }
-
-  // ── Serialisation ─────────────────────────────────────────────────────────
-
-  toBytes(): Uint8Array {
-    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(): string {
-    return `FrameHeader(frameType=0x${this.frameType.toString(16).padStart(2, "0")}, flags=0x${this.flags.toString(16).padStart(2, "0")}, payloadLength=${this.payloadLength})`;
-  }
-}

package/src/core/registry.ts

@@ -1,28 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-import { NpsFrameError } from "./exceptions.js";
-import { FrameType } from "./frames.js";
-import type { NpsFrame } from "./codec.js";
-
-export interface FrameClass {
-  fromDict(data: Record<string, unknown>): NpsFrame;
-}
-
-export class FrameRegistry {
-  private readonly _map = new Map<FrameType, FrameClass>();
-
-  register(frameType: FrameType, cls: FrameClass): void {
-    this._map.set(frameType, cls);
-  }
-
-  resolve(frameType: FrameType): FrameClass {
-    const cls = this._map.get(frameType);
-    if (cls === undefined) {
-      throw new NpsFrameError(
-        `No frame class registered for type 0x${frameType.toString(16).padStart(2, "0")}.`,
-      );
-    }
-    return cls;
-  }
-}

package/src/core/status-codes.ts

@@ -1,47 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// NPS native status codes — per spec/status-codes.md
-
-/** NPS native status code constants. */
-export const NpsStatusCodes = {
-  // Success
-  NPS_OK: "NPS-OK",
-  NPS_OK_ACCEPTED: "NPS-OK-ACCEPTED",
-  NPS_OK_NO_CONTENT: "NPS-OK-NO-CONTENT",
-
-  // Auth
-  NPS_AUTH_UNAUTHENTICATED: "NPS-AUTH-UNAUTHENTICATED",
-  NPS_AUTH_FORBIDDEN: "NPS-AUTH-FORBIDDEN",
-
-  // Client errors
-  NPS_CLIENT_BAD_FRAME: "NPS-CLIENT-BAD-FRAME",
-  NPS_CLIENT_BAD_PARAM: "NPS-CLIENT-BAD-PARAM",
-  NPS_CLIENT_NOT_FOUND: "NPS-CLIENT-NOT-FOUND",
-  NPS_CLIENT_CONFLICT: "NPS-CLIENT-CONFLICT",
-  NPS_CLIENT_GONE: "NPS-CLIENT-GONE",
-  NPS_CLIENT_UNPROCESSABLE: "NPS-CLIENT-UNPROCESSABLE",
-
-  // Server errors
-  NPS_SERVER_INTERNAL: "NPS-SERVER-INTERNAL",
-  NPS_SERVER_UNAVAILABLE: "NPS-SERVER-UNAVAILABLE",
-  NPS_SERVER_TIMEOUT: "NPS-SERVER-TIMEOUT",
-  NPS_SERVER_ENCODING_UNSUPPORTED: "NPS-SERVER-ENCODING-UNSUPPORTED",
-  NPS_SERVER_UNSUPPORTED: "NPS-SERVER-UNSUPPORTED",
-
-  // Stream
-  NPS_STREAM_SEQ_GAP: "NPS-STREAM-SEQ-GAP",
-  NPS_STREAM_NOT_FOUND: "NPS-STREAM-NOT-FOUND",
-  NPS_STREAM_LIMIT: "NPS-STREAM-LIMIT",
-
-  // Limit
-  NPS_LIMIT_RATE: "NPS-LIMIT-RATE",
-  NPS_LIMIT_BUDGET: "NPS-LIMIT-BUDGET",
-  NPS_LIMIT_PAYLOAD: "NPS-LIMIT-PAYLOAD",
-  NPS_LIMIT_EXCEEDED: "NPS-LIMIT-EXCEEDED",
-
-  // Protocol
-  NPS_PROTO_VERSION_INCOMPATIBLE: "NPS-PROTO-VERSION-INCOMPATIBLE",
-} as const;
-
-export type NpsStatusCode = (typeof NpsStatusCodes)[keyof typeof NpsStatusCodes];