@labacacia/nps-sdk 1.0.0-alpha.1

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

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// AnchorFrame (0x01) — Schema anchor for global reference
+// NPS-1 §4.1
+
+import { createHash } from "node:crypto";
+// canonicalize ships CJS with TS `export default` — NodeNext resolves as namespace
+import canonicalizeDefault from "canonicalize";
+const canonicalize = canonicalizeDefault as unknown as (input: unknown) => string | undefined;
+import { NcpError } from "../../core/frame-header.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+const VALID_FIELD_TYPES = [
+  "string", "uint64", "int64", "decimal", "bool",
+  "timestamp", "bytes", "object", "array",
+] as const;
+
+export type SchemaFieldType = (typeof VALID_FIELD_TYPES)[number];
+
+export interface SchemaField {
+  name: string;
+  type: string;
+  semantic?: string;
+  nullable?: boolean;
+}
+
+export interface FrameSchema {
+  fields: SchemaField[];
+}
+
+export interface AnchorFrame {
+  frame: string;
+  anchor_id: string;
+  schema: FrameSchema;
+  ttl?: number;
+}
+
+// ---------------------------------------------------------------------------
+// anchor_id computation (RFC 8785 JCS + SHA-256)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute anchor_id from schema using RFC 8785 JCS canonicalization + SHA-256.
+ * Format: "sha256:{64 lowercase hex chars}"
+ */
+export function computeAnchorId(schema: FrameSchema): string {
+  const canonical = canonicalize(schema);
+  if (!canonical) {
+    throw new NcpError("NCP-ANCHOR-SCHEMA-INVALID", "Schema cannot be canonicalized");
+  }
+  const hash = createHash("sha256").update(canonical).digest("hex");
+  return `sha256:${hash}`;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an AnchorFrame.
+ * @throws {NcpError} NCP-ANCHOR-SCHEMA-INVALID if anchor_id doesn't match or schema is invalid.
+ */
+export function validateAnchorFrame(frame: AnchorFrame): void {
+  // Validate schema field types
+  for (const field of frame.schema.fields) {
+    if (!VALID_FIELD_TYPES.includes(field.type as SchemaFieldType)) {
+      throw new NcpError(
+        "NCP-ANCHOR-SCHEMA-INVALID",
+        `Unsupported field type "${field.type}" for field "${field.name}". ` +
+          `Valid types: ${VALID_FIELD_TYPES.join(", ")}`,
+      );
+    }
+  }
+
+  // Validate anchor_id matches computed hash
+  const expected = computeAnchorId(frame.schema);
+  if (frame.anchor_id !== expected) {
+    throw new NcpError(
+      "NCP-ANCHOR-SCHEMA-INVALID",
+      `anchor_id mismatch: expected ${expected}, got ${frame.anchor_id}`,
+    );
+  }
+}

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

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// CapsFrame (0x04) — Capsule response envelope
+// NPS-1 §4.4
+
+import { NcpError } from "../../core/frame-header.js";
+import {
+  computeAnchorId,
+  type AnchorFrame,
+  type FrameSchema,
+} from "./anchor-frame.js";
+
+export interface CapsFrameInlineAnchor {
+  anchor_id: string;
+  schema: FrameSchema;
+  ttl?: number;
+}
+
+export interface CapsFrame {
+  frame: string;
+  anchor_ref: string;
+  count: number;
+  data: unknown[];
+  next_cursor?: string | null;
+  token_est?: number;
+  tokenizer_used?: string;
+  cached?: boolean;
+  inline_anchor?: CapsFrameInlineAnchor;
+}
+
+/**
+ * Validate a CapsFrame.
+ *
+ * Checks:
+ * - count matches data.length (NPS-CLIENT-BAD-FRAME)
+ * - if inline_anchor present, recomputes anchor_id and validates match (NCP-ANCHOR-SCHEMA-INVALID)
+ *
+ * @throws {NcpError} NPS-CLIENT-BAD-FRAME if count doesn't match data length.
+ * @throws {NcpError} NCP-ANCHOR-SCHEMA-INVALID if inline_anchor.anchor_id doesn't match schema.
+ */
+export function validateCapsFrame(frame: CapsFrame): void {
+  if (frame.count !== frame.data.length) {
+    throw new NcpError(
+      "NPS-CLIENT-BAD-FRAME",
+      `CapsFrame count mismatch: count=${frame.count}, data.length=${frame.data.length}`,
+    );
+  }
+
+  if (frame.inline_anchor !== undefined) {
+    const computed = computeAnchorId(frame.inline_anchor.schema);
+    if (frame.inline_anchor.anchor_id !== computed) {
+      throw new NcpError(
+        "NCP-ANCHOR-SCHEMA-INVALID",
+        `inline_anchor anchor_id mismatch: expected ${computed}, got ${frame.inline_anchor.anchor_id}`,
+      );
+    }
+  }
+}

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

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// DiffFrame (0x02) — Incremental data patch
+// NPS-1 §4.2
+
+import { NcpError, EncodingTier } from "../../core/frame-header.js";
+import { isValidPatchFormat, type PatchFormat } from "../ncp-patch-format.js";
+
+export interface JsonPatchOperation {
+  op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+  path: string;
+  value?: unknown;
+  from?: string;
+}
+
+export interface DiffFrame {
+  frame: string;
+  anchor_ref: string;
+  base_seq: number;
+  patch_format?: PatchFormat;
+  patch: JsonPatchOperation[] | Uint8Array;
+  entity_id?: string;
+}
+
+/**
+ * Validate DiffFrame base_seq against current sequence.
+ * @throws {NcpError} NCP-STREAM-SEQ-GAP if sequences don't match.
+ */
+export function validateDiffSeq(frame: DiffFrame, currentSeq: number): void {
+  if (frame.base_seq !== currentSeq) {
+    throw new NcpError(
+      "NCP-STREAM-SEQ-GAP",
+      `DiffFrame base_seq=${frame.base_seq} does not match current seq=${currentSeq}`,
+    );
+  }
+}
+
+/**
+ * Validate DiffFrame patch_format against the encoding tier.
+ *
+ * binary_bitset is only supported on Tier-2 (MsgPack) frames.
+ * Unknown patch_format values are also rejected.
+ *
+ * @throws {NcpError} NCP-DIFF-FORMAT-UNSUPPORTED if binary_bitset on non-Tier-2,
+ *   or if patch_format is an unknown value.
+ */
+export function validateDiffFrame(
+  frame: DiffFrame,
+  encodingTier: EncodingTier | number,
+): void {
+  const fmt = frame.patch_format;
+
+  // Unknown patch_format
+  if (fmt !== undefined && !isValidPatchFormat(fmt)) {
+    throw new NcpError(
+      "NCP-DIFF-FORMAT-UNSUPPORTED",
+      `Unknown patch_format "${String(fmt)}"`,
+    );
+  }
+
+  // binary_bitset requires Tier-2 MsgPack
+  if (fmt === "binary_bitset" && encodingTier !== EncodingTier.MsgPack) {
+    throw new NcpError(
+      "NCP-DIFF-FORMAT-UNSUPPORTED",
+      "patch_format=binary_bitset requires Tier-2 MsgPack encoding",
+    );
+  }
+}

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

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// ErrorFrame (0xFE) — Unified error frame for all NPS protocol layers
+// NPS-1 §4.7
+
+/** Unified error frame shared across all NPS protocol layers. */
+export interface ErrorFrame {
+  /** Fixed value "0xFE". */
+  frame: string;
+  /** NPS status code, e.g. "NPS-CLIENT-NOT-FOUND". */
+  status: string;
+  /** Protocol-level error code, e.g. "NCP-ANCHOR-NOT-FOUND". */
+  error: string;
+  /** Human-readable error description. */
+  message?: string;
+  /** Structured error details (e.g. anchor_ref, stream_id). */
+  details?: Record<string, unknown>;
+}
+
+/** Type guard for ErrorFrame. */
+export function isErrorFrame(obj: unknown): obj is ErrorFrame {
+  if (typeof obj !== "object" || obj === null) return false;
+  const o = obj as Record<string, unknown>;
+  return o.frame === "0xFE" && typeof o.status === "string" && typeof o.error === "string";
+}

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

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// HelloFrame (0x06) — Native-mode client handshake
+// NPS-1 §4.6
+
+import { NcpError } from "../../core/frame-header.js";
+
+export interface HelloFrame {
+  frame: string;
+  nps_version: string;
+  min_version?: string;
+  supported_encodings: string[];
+  supported_protocols: string[];
+  agent_id?: string;
+  max_frame_payload?: number;
+  ext_support?: boolean;
+  max_concurrent_streams?: number;
+  e2e_enc_algorithms?: string[];
+}
+
+/**
+ * Validate a HelloFrame.
+ *
+ * Required fields: nps_version, supported_encodings (non-empty), supported_protocols (non-empty).
+ *
+ * @throws {NcpError} NPS-CLIENT-BAD-FRAME if any required field is missing or empty.
+ */
+export function validateHelloFrame(frame: HelloFrame): void {
+  if (!frame.nps_version) {
+    throw new NcpError(
+      "NPS-CLIENT-BAD-FRAME",
+      "HelloFrame missing required field: nps_version",
+    );
+  }
+
+  if (!frame.supported_encodings || frame.supported_encodings.length === 0) {
+    throw new NcpError(
+      "NPS-CLIENT-BAD-FRAME",
+      "HelloFrame missing required field: supported_encodings (must be non-empty)",
+    );
+  }
+
+  if (!frame.supported_protocols || frame.supported_protocols.length === 0) {
+    throw new NcpError(
+      "NPS-CLIENT-BAD-FRAME",
+      "HelloFrame missing required field: supported_protocols (must be non-empty)",
+    );
+  }
+}

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

@@ -0,0 +1,35 @@
+// 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

@@ -0,0 +1,199 @@
+// 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

@@ -0,0 +1,95 @@
+// 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

@@ -0,0 +1,12 @@
+// 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

@@ -0,0 +1,34 @@
+// 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

@@ -0,0 +1,16 @@
+// 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;
+}