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

package/src/ncp/frames.ts

@@ -1,251 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-import { EncodingTier, FrameType } from "../core/frames.js";
-import type { NpsFrame } from "../core/codec.js";
-
-// ── FrameSchema ───────────────────────────────────────────────────────────────
-
-export interface SchemaField {
-  name:      string;
-  type:      string;
-  semantic?: string;
-  nullable?: boolean;
-}
-
-export interface FrameSchema {
-  fields: readonly SchemaField[];
-}
-
-// ── AnchorFrame ───────────────────────────────────────────────────────────────
-
-export class AnchorFrame implements NpsFrame {
-  readonly frameType     = FrameType.ANCHOR;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly anchorId: string,
-    public readonly schema:   FrameSchema,
-    public readonly ttl:      number = 3600,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      anchor_id: this.anchorId,
-      schema:    { fields: this.schema.fields.map((f) => ({ ...f })) },
-      ttl:       this.ttl,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): AnchorFrame {
-    const schemaRaw = data["schema"] as { fields: SchemaField[] };
-    return new AnchorFrame(
-      data["anchor_id"] as string,
-      { fields: schemaRaw.fields },
-      (data["ttl"] as number | undefined) ?? 3600,
-    );
-  }
-}
-
-// ── JsonPatchOperation ────────────────────────────────────────────────────────
-
-export interface JsonPatchOperation {
-  op:     string;
-  path:   string;
-  value?: unknown;
-}
-
-// ── DiffFrame ─────────────────────────────────────────────────────────────────
-
-export class DiffFrame implements NpsFrame {
-  readonly frameType     = FrameType.DIFF;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly anchorRef: string,
-    public readonly baseSeq:   number,
-    public readonly patch:     readonly JsonPatchOperation[],
-    public readonly entityId?: string,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      anchor_ref: this.anchorRef,
-      base_seq:   this.baseSeq,
-      patch:      this.patch.map((p) => ({ ...p })),
-      entity_id:  this.entityId ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): DiffFrame {
-    return new DiffFrame(
-      data["anchor_ref"] as string,
-      data["base_seq"]   as number,
-      data["patch"]      as JsonPatchOperation[],
-      (data["entity_id"] as string | null) ?? undefined,
-    );
-  }
-}
-
-// ── StreamFrame ───────────────────────────────────────────────────────────────
-
-export class StreamFrame implements NpsFrame {
-  readonly frameType     = FrameType.STREAM;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly streamId:   string,
-    public readonly seq:        number,
-    public readonly isLast:     boolean,
-    public readonly data:       readonly Record<string, unknown>[],
-    public readonly anchorRef?: string,
-    public readonly windowSize?: number,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      stream_id:   this.streamId,
-      seq:         this.seq,
-      is_last:     this.isLast,
-      data:        this.data,
-      anchor_ref:  this.anchorRef  ?? null,
-      window_size: this.windowSize ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): StreamFrame {
-    return new StreamFrame(
-      data["stream_id"]   as string,
-      data["seq"]         as number,
-      data["is_last"]     as boolean,
-      data["data"]        as Record<string, unknown>[],
-      (data["anchor_ref"]  as string | null)  ?? undefined,
-      (data["window_size"] as number | null)  ?? undefined,
-    );
-  }
-}
-
-// ── CapsFrame ─────────────────────────────────────────────────────────────────
-
-export class CapsFrame implements NpsFrame {
-  readonly frameType     = FrameType.CAPS;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly anchorRef:      string,
-    public readonly count:          number,
-    public readonly data:           readonly Record<string, unknown>[],
-    public readonly nextCursor?:    string,
-    public readonly tokenEst?:      number,
-    public readonly cached?:        boolean,
-    public readonly tokenizerUsed?: string,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      anchor_ref:      this.anchorRef,
-      count:           this.count,
-      data:            this.data,
-      next_cursor:     this.nextCursor    ?? null,
-      token_est:       this.tokenEst      ?? null,
-      cached:          this.cached        ?? null,
-      tokenizer_used:  this.tokenizerUsed ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): CapsFrame {
-    return new CapsFrame(
-      data["anchor_ref"]     as string,
-      data["count"]          as number,
-      data["data"]           as Record<string, unknown>[],
-      (data["next_cursor"]    as string | null) ?? undefined,
-      (data["token_est"]      as number | null) ?? undefined,
-      (data["cached"]         as boolean | null) ?? undefined,
-      (data["tokenizer_used"] as string | null) ?? undefined,
-    );
-  }
-}
-
-// ── ErrorFrame ────────────────────────────────────────────────────────────────
-
-export class ErrorFrame implements NpsFrame {
-  readonly frameType     = FrameType.ERROR;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly status:   string,
-    public readonly error:    string,
-    public readonly message?: string,
-    public readonly details?: Record<string, unknown>,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      status:  this.status,
-      error:   this.error,
-      message: this.message ?? null,
-      details: this.details ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): ErrorFrame {
-    return new ErrorFrame(
-      data["status"]  as string,
-      data["error"]   as string,
-      (data["message"] as string | null) ?? undefined,
-      (data["details"] as Record<string, unknown> | null) ?? undefined,
-    );
-  }
-}
-
-// ── HelloFrame ────────────────────────────────────────────────────────────────
-// NPS-1 §4.6 — Native-mode handshake (0x06). Always Tier-1 JSON: encoding
-// is not yet negotiated when this frame is sent.
-
-export class HelloFrame implements NpsFrame {
-  readonly frameType     = FrameType.HELLO;
-  readonly preferredTier = EncodingTier.JSON;
-
-  static readonly DEFAULT_MAX_FRAME_PAYLOAD      = 0xFFFF;
-  static readonly DEFAULT_MAX_CONCURRENT_STREAMS = 32;
-
-  constructor(
-    public readonly npsVersion:           string,
-    public readonly supportedEncodings:   readonly string[],
-    public readonly supportedProtocols:   readonly string[],
-    public          minVersion?:          string,
-    public          agentId?:             string,
-    public          maxFramePayload:      number = HelloFrame.DEFAULT_MAX_FRAME_PAYLOAD,
-    public          extSupport:           boolean = false,
-    public          maxConcurrentStreams: number = HelloFrame.DEFAULT_MAX_CONCURRENT_STREAMS,
-    public          e2eEncAlgorithms?:    readonly string[],
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      nps_version:            this.npsVersion,
-      supported_encodings:    [...this.supportedEncodings],
-      supported_protocols:    [...this.supportedProtocols],
-      min_version:            this.minVersion ?? null,
-      agent_id:               this.agentId    ?? null,
-      max_frame_payload:      this.maxFramePayload,
-      ext_support:            this.extSupport,
-      max_concurrent_streams: this.maxConcurrentStreams,
-      e2e_enc_algorithms:     this.e2eEncAlgorithms ? [...this.e2eEncAlgorithms] : null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): HelloFrame {
-    return new HelloFrame(
-      data["nps_version"]         as string,
-      (data["supported_encodings"] as string[]) ?? [],
-      (data["supported_protocols"] as string[]) ?? [],
-      (data["min_version"]        as string | null) ?? undefined,
-      (data["agent_id"]           as string | null) ?? undefined,
-      (data["max_frame_payload"]  as number | null) ?? HelloFrame.DEFAULT_MAX_FRAME_PAYLOAD,
-      (data["ext_support"]        as boolean | null) ?? false,
-      (data["max_concurrent_streams"] as number | null) ?? HelloFrame.DEFAULT_MAX_CONCURRENT_STREAMS,
-      (data["e2e_enc_algorithms"] as string[] | null) ?? undefined,
-    );
-  }
-}

package/src/ncp/handshake.ts

@@ -1,95 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// Handshake — Version negotiation and encoding negotiation
-// NPS-1 §2.6
-
-/**
- * Parse a "major.minor" (optionally "major.minor.patch") version string into a
- * tuple of numeric components. Invalid parts become NaN which makes subsequent
- * comparisons return false in both directions (safe failure).
- */
-function parseVersion(v: string): number[] {
-  return v.split(".").map((p) => Number.parseInt(p, 10));
-}
-
-/**
- * Numeric component-wise comparison of two version strings.
- * Returns negative if a < b, zero if equal, positive if a > b.
- * Avoids the lexicographic pitfall where "0.9" > "0.10".
- */
-function compareVersions(a: string, b: string): number {
-  const partsA = parseVersion(a);
-  const partsB = parseVersion(b);
-  const len = Math.max(partsA.length, partsB.length);
-  for (let i = 0; i < len; i += 1) {
-    const x = partsA[i] ?? 0;
-    const y = partsB[i] ?? 0;
-    if (x !== y) return x - y;
-  }
-  return 0;
-}
-
-/**
- * Negotiate the session NPS version between client and server.
- *
- * Session version = numeric min of client.nps_version and server.nps_version
- * (component-wise — "0.9" < "0.10" < "1.0").
- * If the effective client minimum (min_version ?? nps_version) > server.nps_version,
- * the versions are incompatible.
- *
- * Spec: NPS-1 §2.6
- */
-export function negotiateVersion(
-  client: { nps_version: string; min_version?: string },
-  server: { nps_version: string },
-): { session_version: string; compatible: boolean; error_code?: string } {
-  const clientMin = client.min_version ?? client.nps_version;
-  const serverVersion = server.nps_version;
-
-  if (compareVersions(clientMin, serverVersion) > 0) {
-    return {
-      session_version: serverVersion,
-      compatible: false,
-      error_code: "NCP-VERSION-INCOMPATIBLE",
-    };
-  }
-
-  // Session version = component-wise min of client.nps_version and server.nps_version
-  const sessionVersion =
-    compareVersions(client.nps_version, serverVersion) <= 0
-      ? client.nps_version
-      : serverVersion;
-
-  return { session_version: sessionVersion, compatible: true };
-}
-
-/**
- * Negotiate the encoding between client and server preferred lists.
- *
- * Returns the first mutually supported encoding, preferring "msgpack" over "json".
- * Returns null if there is no intersection.
- */
-export function negotiateEncoding(
-  client: string[],
-  server: string[],
-): { encoding: string | null } {
-  const serverSet = new Set(server);
-
-  // Prefer msgpack over json (and over any other encoding)
-  if (client.includes("msgpack") && serverSet.has("msgpack")) {
-    return { encoding: "msgpack" };
-  }
-  if (client.includes("json") && serverSet.has("json")) {
-    return { encoding: "json" };
-  }
-
-  // Fall back to first intersection in client-preference order
-  for (const enc of client) {
-    if (serverSet.has(enc)) {
-      return { encoding: enc };
-    }
-  }
-
-  return { encoding: null };
-}

package/src/ncp/ncp-error-codes.ts

@@ -1,36 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// NCP Error Codes — All v0.4 protocol error codes
-// NPS-1 §6 + §7.4
-//
-// Implementation-only codes (NCP_FRAME_PARSE_ERROR, NCP_FRAME_INCOMPLETE) cover
-// wire-layer parse failures not in spec §6. See test/ncp_test_results.md spec
-// question 2 for the proposal to register them upstream.
-
-export const NCP_ERROR_CODES = {
-  // Implementation-only codes (not in spec §6 — see test_results.md spec question 2)
-  NCP_FRAME_PARSE_ERROR: "NCP-FRAME-PARSE-ERROR",
-  NCP_FRAME_INCOMPLETE: "NCP-FRAME-INCOMPLETE",
-  // NPS-RFC-0001 — native-mode preamble
-  NCP_PREAMBLE_INVALID: "NCP-PREAMBLE-INVALID",
-  // Spec-defined codes
-  NCP_FRAME_UNKNOWN_TYPE: "NCP-FRAME-UNKNOWN-TYPE",
-  NCP_FRAME_PAYLOAD_TOO_LARGE: "NCP-FRAME-PAYLOAD-TOO-LARGE",
-  NCP_FRAME_FLAGS_INVALID: "NCP-FRAME-FLAGS-INVALID",
-  NCP_ANCHOR_NOT_FOUND: "NCP-ANCHOR-NOT-FOUND",
-  NCP_ANCHOR_SCHEMA_INVALID: "NCP-ANCHOR-SCHEMA-INVALID",
-  NCP_ANCHOR_ID_MISMATCH: "NCP-ANCHOR-ID-MISMATCH",
-  NCP_ANCHOR_STALE: "NCP-ANCHOR-STALE",
-  NCP_STREAM_SEQ_GAP: "NCP-STREAM-SEQ-GAP",
-  NCP_STREAM_NOT_FOUND: "NCP-STREAM-NOT-FOUND",
-  NCP_STREAM_LIMIT_EXCEEDED: "NCP-STREAM-LIMIT-EXCEEDED",
-  NCP_STREAM_WINDOW_OVERFLOW: "NCP-STREAM-WINDOW-OVERFLOW",
-  NCP_ENCODING_UNSUPPORTED: "NCP-ENCODING-UNSUPPORTED",
-  NCP_DIFF_FORMAT_UNSUPPORTED: "NCP-DIFF-FORMAT-UNSUPPORTED",
-  NCP_VERSION_INCOMPATIBLE: "NCP-VERSION-INCOMPATIBLE",
-  NCP_ENC_NOT_NEGOTIATED: "NCP-ENC-NOT-NEGOTIATED",
-  NCP_ENC_AUTH_FAILED: "NCP-ENC-AUTH-FAILED",
-} as const;
-
-export type NcpErrorCode = typeof NCP_ERROR_CODES[keyof typeof NCP_ERROR_CODES];

package/src/ncp/ncp-patch-format.ts

@@ -1,16 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// NCP Patch Format — DiffFrame patch encoding types
-// NPS-1 §4.2
-
-export const PATCH_FORMAT = {
-  JSON_PATCH: "json_patch",
-  BINARY_BITSET: "binary_bitset",
-} as const;
-
-export type PatchFormat = typeof PATCH_FORMAT[keyof typeof PATCH_FORMAT];
-
-export function isValidPatchFormat(v: unknown): v is PatchFormat {
-  return v === PATCH_FORMAT.JSON_PATCH || v === PATCH_FORMAT.BINARY_BITSET;
-}

package/src/ncp/preamble.ts

@@ -1,79 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * NCP native-mode connection preamble — the 8-byte ASCII constant
- * `"NPS/1.0\n"` that every native-mode client MUST emit immediately
- * after the transport handshake and before its first HelloFrame.
- * Defined by NPS-RFC-0001 and NPS-1 NCP §2.6.1.
- *
- * HTTP-mode connections do not use the preamble.
- */
-
-export const PREAMBLE_LITERAL = "NPS/1.0\n";
-export const PREAMBLE_LENGTH = 8;
-export const PREAMBLE_BYTES: Uint8Array = new TextEncoder().encode(PREAMBLE_LITERAL);
-/** Validation timeout in milliseconds (NPS-RFC-0001 §4.1). */
-export const PREAMBLE_READ_TIMEOUT_MS = 10_000;
-/** Maximum delay before closing after a mismatch, in milliseconds. */
-export const PREAMBLE_CLOSE_DEADLINE_MS = 500;
-
-export const PREAMBLE_ERROR_CODE  = "NCP-PREAMBLE-INVALID";
-export const PREAMBLE_STATUS_CODE = "NPS-PROTO-PREAMBLE-INVALID";
-
-export class NcpPreambleInvalidError extends Error {
-  readonly errorCode  = PREAMBLE_ERROR_CODE;
-  readonly statusCode = PREAMBLE_STATUS_CODE;
-
-  constructor(reason: string) {
-    super(reason);
-    this.name = "NcpPreambleInvalidError";
-  }
-}
-
-/**
- * Returns `true` iff `buf` starts with the 8-byte NPS/1.0 preamble.
- * Safe to call with shorter buffers.
- */
-export function preambleMatches(buf: Uint8Array): boolean {
-  if (buf.length < PREAMBLE_LENGTH) return false;
-  for (let i = 0; i < PREAMBLE_LENGTH; i++) {
-    if (buf[i] !== PREAMBLE_BYTES[i]) return false;
-  }
-  return true;
-}
-
-/**
- * Validates a presumed-preamble buffer.
- * Returns `{ valid: true, reason: "" }` on success or `{ valid: false, reason }` on failure.
- */
-export function tryValidatePreamble(buf: Uint8Array): { valid: boolean; reason: string } {
-  if (buf.length < PREAMBLE_LENGTH) {
-    return { valid: false, reason: `short read (${buf.length}/${PREAMBLE_LENGTH} bytes); peer is not speaking NCP` };
-  }
-  if (!preambleMatches(buf)) {
-    // "NPS/" = 0x4E 0x50 0x53 0x2F
-    const isNps = buf[0] === 0x4e && buf[1] === 0x50 && buf[2] === 0x53 && buf[3] === 0x2f;
-    if (isNps) {
-      return { valid: false, reason: "future-major-version NPS preamble; close with NPS-PREAMBLE-UNSUPPORTED-VERSION diagnostic" };
-    }
-    return { valid: false, reason: "preamble mismatch; peer is not speaking NPS/1.x" };
-  }
-  return { valid: true, reason: "" };
-}
-
-/**
- * Validates a presumed-preamble buffer, throwing {@link NcpPreambleInvalidError} on mismatch.
- */
-export function validatePreamble(buf: Uint8Array): void {
-  const { valid, reason } = tryValidatePreamble(buf);
-  if (!valid) throw new NcpPreambleInvalidError(reason);
-}
-
-/**
- * Writes the preamble bytes to `writer`.
- * `writer` must expose a `write(buf: Uint8Array): void` method (e.g. Node.js `net.Socket`).
- */
-export function writePreamble(writer: { write(buf: Uint8Array): void }): void {
-  writer.write(PREAMBLE_BYTES);
-}

package/src/ncp/registry.ts

@@ -1,15 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-import { FrameRegistry } from "../core/registry.js";
-import { FrameType } from "../core/frames.js";
-import { AnchorFrame, CapsFrame, DiffFrame, ErrorFrame, HelloFrame, StreamFrame } from "./frames.js";
-
-export function registerNcpFrames(registry: FrameRegistry): void {
-  registry.register(FrameType.ANCHOR, AnchorFrame);
-  registry.register(FrameType.DIFF,   DiffFrame);
-  registry.register(FrameType.STREAM, StreamFrame);
-  registry.register(FrameType.CAPS,   CapsFrame);
-  registry.register(FrameType.HELLO,  HelloFrame);
-  registry.register(FrameType.ERROR,  ErrorFrame);
-}