@labacacia/nps-sdk 1.0.0-alpha.1 → 1.0.0-alpha.13

package/src/ncp/frames/stream-frame.ts

@@ -1,35 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// StreamFrame (0x03) — Streaming data chunks with flow control
-// NPS-1 §4.3
-
-import { NcpError } from "../../core/frame-header.js";
-
-export interface StreamFrame {
-  frame: string;
-  stream_id: string;
-  seq: number;
-  is_last: boolean;
-  anchor_ref?: string;
-  data: unknown[];
-  window_size?: number;
-  error_code?: string;
-}
-
-// UUID v4 format: xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx
-const UUID_V4_RE =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
-/**
- * Validate stream_id is a valid UUID v4.
- * @throws {NcpError} NPS-CLIENT-BAD-FRAME if stream_id is not a valid UUID v4.
- */
-export function validateStreamFrame(frame: StreamFrame): void {
-  if (!UUID_V4_RE.test(frame.stream_id)) {
-    throw new NcpError(
-      "NPS-CLIENT-BAD-FRAME",
-      `stream_id "${frame.stream_id}" is not a valid UUID v4`,
-    );
-  }
-}

package/src/ncp/frames.ts

@@ -1,199 +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,
-    );
-  }
-}

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/index.ts

@@ -1,12 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-export * from "./frames/anchor-frame.js";
-export * from "./frames/caps-frame.js";
-export * from "./frames/diff-frame.js";
-export * from "./frames/error-frame.js";
-export * from "./frames/hello-frame.js";
-export * from "./frames/stream-frame.js";
-export * from "./ncp-error-codes.js";
-export * from "./ncp-patch-format.js";
-export * from "./handshake.js";
-export * from "./stream-manager.js";

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

@@ -1,34 +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",
-  // 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/registry.ts

@@ -1,14 +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, 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.ERROR,  ErrorFrame);
-}

package/src/ncp/stream-manager.ts

@@ -1,212 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// StreamManager — Concurrent stream tracking, sequence validation, flow control
-// NPS-1 §4.3, §7.3
-
-import { NcpError } from "../core/frame-header.js";
-import { NCP_ERROR_CODES } from "./ncp-error-codes.js";
-import type { StreamFrame } from "./frames/stream-frame.js";
-
-interface ActiveStream {
-  streamId: string;
-  expectedSeq: number;
-  chunks: unknown[][];
-  completed: boolean;
-  errorCode?: string;
-}
-
-interface OutgoingStream {
-  streamId: string;
-  remainingWindow: number | undefined; // undefined = no flow control
-  paused: boolean;
-}
-
-/**
- * Manages concurrent StreamFrame streams.
- *
- * - Tracks active streams by stream_id
- * - Validates sequential seq numbers
- * - Enforces max concurrent stream limit (NPS-1 §7.3, default 32)
- * - Detects early termination via error_code
- * - Enforces window-based flow control on outgoing streams (NCP-S-07–11)
- */
-export class StreamManager {
-  private readonly streams = new Map<string, ActiveStream>();
-  private readonly outgoing = new Map<string, OutgoingStream>();
-  private readonly maxConcurrent: number;
-
-  constructor(options?: { maxConcurrent?: number }) {
-    this.maxConcurrent = options?.maxConcurrent ?? 32;
-  }
-
-  /**
-   * Receive a StreamFrame chunk.
-   *
-   * @returns true if stream is complete (is_last=true or error_code set).
-   * @throws {NcpError} NCP-STREAM-LIMIT-EXCEEDED if too many concurrent streams.
-   * @throws {NcpError} NCP-STREAM-NOT-FOUND if frame.seq > 0 for a stream that was never opened.
-   * @throws {NcpError} NPS-CLIENT-CONFLICT if the stream_id was already completed (stream-id reuse; see test_cases NCP-S-04).
-   * @throws {NcpError} NCP-STREAM-SEQ-GAP if sequence number is not expected.
-   */
-  receive(frame: StreamFrame): boolean {
-    let stream = this.streams.get(frame.stream_id);
-
-    if (!stream) {
-      // A stream is opened only by seq=0. Any other seq on an unknown stream_id
-      // means the opener was never seen (NCP-S-13: unknown stream_id).
-      if (frame.seq !== 0) {
-        throw new NcpError(
-          NCP_ERROR_CODES.NCP_STREAM_NOT_FOUND,
-          `Unknown stream_id ${frame.stream_id} — first frame must have seq=0`,
-        );
-      }
-
-      // New stream — check concurrent limit
-      if (this.streams.size >= this.maxConcurrent) {
-        throw new NcpError(
-          NCP_ERROR_CODES.NCP_STREAM_LIMIT_EXCEEDED,
-          `Max concurrent streams (${this.maxConcurrent}) exceeded`,
-        );
-      }
-
-      stream = {
-        streamId: frame.stream_id,
-        expectedSeq: 0,
-        chunks: [],
-        completed: false,
-      };
-      this.streams.set(frame.stream_id, stream);
-    }
-
-    // Reject writes to completed streams. Per test_cases NCP-S-04, the spec does
-    // not assign a dedicated NCP code for stream-id reuse; interim mapping uses
-    // the NPS-level NPS-CLIENT-CONFLICT until a spec-side code is added.
-    if (stream.completed) {
-      throw new NcpError(
-        "NPS-CLIENT-CONFLICT",
-        `Stream ${frame.stream_id} is already completed — cannot reuse stream_id`,
-      );
-    }
-
-    // Sequence validation
-    if (frame.seq !== stream.expectedSeq) {
-      // Duplicate detection — same seq as last accepted
-      if (frame.seq < stream.expectedSeq) {
-        // Ignore duplicate (idempotent)
-        return false;
-      }
-      throw new NcpError(
-        NCP_ERROR_CODES.NCP_STREAM_SEQ_GAP,
-        `Expected seq ${stream.expectedSeq}, got ${frame.seq} on stream ${frame.stream_id}`,
-      );
-    }
-
-    stream.chunks.push(frame.data);
-    stream.expectedSeq = frame.seq + 1;
-
-    // Early termination via error_code
-    if (frame.error_code) {
-      stream.completed = true;
-      stream.errorCode = frame.error_code;
-      return true;
-    }
-
-    // Normal completion
-    if (frame.is_last) {
-      stream.completed = true;
-      return true;
-    }
-
-    return false;
-  }
-
-  /**
-   * Send a StreamFrame on an outgoing stream, enforcing window-based flow control.
-   *
-   * - seq=0 with window_size initialises remainingWindow (no decrement for opening frame).
-   * - Subsequent sends decrement remainingWindow when flow control is active.
-   * - Throws NCP-STREAM-WINDOW-OVERFLOW when remainingWindow === 0.
-   *
-   * @throws {NcpError} NCP-STREAM-WINDOW-OVERFLOW if window is exhausted.
-   */
-  send(frame: StreamFrame): void {
-    let out = this.outgoing.get(frame.stream_id);
-
-    if (!out) {
-      out = {
-        streamId: frame.stream_id,
-        remainingWindow: undefined,
-        paused: false,
-      };
-      this.outgoing.set(frame.stream_id, out);
-    }
-
-    // Opening frame: initialise window from window_size if provided.
-    if (frame.seq === 0 && frame.window_size !== undefined) {
-      out.remainingWindow = frame.window_size;
-      return; // opening frame does not consume a window slot
-    }
-
-    // Flow control check for subsequent frames.
-    if (out.remainingWindow !== undefined) {
-      if (out.remainingWindow === 0) {
-        throw new NcpError(
-          NCP_ERROR_CODES.NCP_STREAM_WINDOW_OVERFLOW,
-          `Window exhausted on stream ${frame.stream_id}`,
-        );
-      }
-      out.remainingWindow -= 1;
-    }
-  }
-
-  /**
-   * Update the send window for a stream.
-   *
-   * Called when a reverse-direction StreamFrame arrives with data=[] and window_size set.
-   * Replaces remainingWindow with new_size. Sets paused=true when new_size === 0.
-   */
-  updateWindow(streamId: string, newSize: number): void {
-    let out = this.outgoing.get(streamId);
-    if (!out) {
-      out = {
-        streamId,
-        remainingWindow: newSize,
-        paused: newSize === 0,
-      };
-      this.outgoing.set(streamId, out);
-      return;
-    }
-    out.remainingWindow = newSize;
-    out.paused = newSize === 0;
-  }
-
-  /**
-   * Returns true when the outgoing stream is paused (window=0 was received).
-   * Resumes (returns false) once a non-zero window update arrives.
-   */
-  isPaused(streamId: string): boolean {
-    return this.outgoing.get(streamId)?.paused ?? false;
-  }
-
-  /** Get reassembled data for a completed stream. */
-  getData(streamId: string): unknown[] | null {
-    const stream = this.streams.get(streamId);
-    if (!stream || !stream.completed) return null;
-    return stream.chunks.flat();
-  }
-
-  /** Get error code if stream terminated with error. */
-  getError(streamId: string): string | undefined {
-    return this.streams.get(streamId)?.errorCode;
-  }
-
-  /** Number of active (non-completed) streams. */
-  get activeCount(): number {
-    let count = 0;
-    for (const s of this.streams.values()) {
-      if (!s.completed) count++;
-    }
-    return count;
-  }
-}