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

package/dist/ncp/index.cjs

@@ -1,188 +1,388 @@
 'use strict';
 
-// src/ncp/frames.ts
-var AnchorFrame = class _AnchorFrame {
-  constructor(anchorId, schema, ttl = 3600) {
-    this.anchorId = anchorId;
-    this.schema = schema;
-    this.ttl = ttl;
-  }
-  anchorId;
-  schema;
-  ttl;
-  frameType = 1 /* ANCHOR */;
-  preferredTier = 1 /* MSGPACK */;
-  toDict() {
-    return {
-      anchor_id: this.anchorId,
-      schema: { fields: this.schema.fields.map((f) => ({ ...f })) },
-      ttl: this.ttl
-    };
+var crypto = require('crypto');
+var canonicalizeDefault = require('canonicalize');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var canonicalizeDefault__default = /*#__PURE__*/_interopDefault(canonicalizeDefault);
+
+// src/ncp/frames/anchor-frame.ts
+
+// src/core/frame-header.ts
+var NcpError = class 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(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "NcpError";
+  }
+  code;
+};
+
+// src/ncp/frames/anchor-frame.ts
+var canonicalize = canonicalizeDefault__default.default;
+var VALID_FIELD_TYPES = [
+  "string",
+  "uint64",
+  "int64",
+  "decimal",
+  "bool",
+  "timestamp",
+  "bytes",
+  "object",
+  "array"
+];
+function computeAnchorId(schema) {
+  const canonical = canonicalize(schema);
+  if (!canonical) {
+    throw new NcpError("NCP-ANCHOR-SCHEMA-INVALID", "Schema cannot be canonicalized");
+  }
+  const hash = crypto.createHash("sha256").update(canonical).digest("hex");
+  return `sha256:${hash}`;
+}
+function validateAnchorFrame(frame) {
+  for (const field of frame.schema.fields) {
+    if (!VALID_FIELD_TYPES.includes(field.type)) {
+      throw new NcpError(
+        "NCP-ANCHOR-SCHEMA-INVALID",
+        `Unsupported field type "${field.type}" for field "${field.name}". Valid types: ${VALID_FIELD_TYPES.join(", ")}`
+      );
+    }
+  }
+  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}`
+    );
   }
-  static fromDict(data) {
-    const schemaRaw = data["schema"];
-    return new _AnchorFrame(
-      data["anchor_id"],
-      { fields: schemaRaw.fields },
-      data["ttl"] ?? 3600
+}
+
+// src/ncp/frames/caps-frame.ts
+function validateCapsFrame(frame) {
+  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 !== void 0) {
+    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}`
+      );
+    }
+  }
+}
+
+// src/ncp/ncp-patch-format.ts
+var PATCH_FORMAT = {
+  JSON_PATCH: "json_patch",
+  BINARY_BITSET: "binary_bitset"
 };
-var DiffFrame = class _DiffFrame {
-  constructor(anchorRef, baseSeq, patch, entityId) {
-    this.anchorRef = anchorRef;
-    this.baseSeq = baseSeq;
-    this.patch = patch;
-    this.entityId = entityId;
-  }
-  anchorRef;
-  baseSeq;
-  patch;
-  entityId;
-  frameType = 2 /* DIFF */;
-  preferredTier = 1 /* MSGPACK */;
-  toDict() {
-    return {
-      anchor_ref: this.anchorRef,
-      base_seq: this.baseSeq,
-      patch: this.patch.map((p) => ({ ...p })),
-      entity_id: this.entityId ?? null
-    };
+function isValidPatchFormat(v) {
+  return v === PATCH_FORMAT.JSON_PATCH || v === PATCH_FORMAT.BINARY_BITSET;
+}
+
+// src/ncp/frames/diff-frame.ts
+function validateDiffSeq(frame, currentSeq) {
+  if (frame.base_seq !== currentSeq) {
+    throw new NcpError(
+      "NCP-STREAM-SEQ-GAP",
+      `DiffFrame base_seq=${frame.base_seq} does not match current seq=${currentSeq}`
+    );
   }
-  static fromDict(data) {
-    return new _DiffFrame(
-      data["anchor_ref"],
-      data["base_seq"],
-      data["patch"],
-      data["entity_id"] ?? void 0
+}
+function validateDiffFrame(frame, encodingTier) {
+  const fmt = frame.patch_format;
+  if (fmt !== void 0 && !isValidPatchFormat(fmt)) {
+    throw new NcpError(
+      "NCP-DIFF-FORMAT-UNSUPPORTED",
+      `Unknown patch_format "${String(fmt)}"`
     );
   }
-};
-var StreamFrame = class _StreamFrame {
-  constructor(streamId, seq, isLast, data, anchorRef, windowSize) {
-    this.streamId = streamId;
-    this.seq = seq;
-    this.isLast = isLast;
-    this.data = data;
-    this.anchorRef = anchorRef;
-    this.windowSize = windowSize;
-  }
-  streamId;
-  seq;
-  isLast;
-  data;
-  anchorRef;
-  windowSize;
-  frameType = 3 /* STREAM */;
-  preferredTier = 1 /* MSGPACK */;
-  toDict() {
-    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
-    };
+  if (fmt === "binary_bitset" && encodingTier !== 1 /* MsgPack */) {
+    throw new NcpError(
+      "NCP-DIFF-FORMAT-UNSUPPORTED",
+      "patch_format=binary_bitset requires Tier-2 MsgPack encoding"
+    );
+  }
+}
+
+// src/ncp/frames/error-frame.ts
+function isErrorFrame(obj) {
+  if (typeof obj !== "object" || obj === null) return false;
+  const o = obj;
+  return o.frame === "0xFE" && typeof o.status === "string" && typeof o.error === "string";
+}
+
+// src/ncp/frames/hello-frame.ts
+function validateHelloFrame(frame) {
+  if (!frame.nps_version) {
+    throw new NcpError(
+      "NPS-CLIENT-BAD-FRAME",
+      "HelloFrame missing required field: nps_version"
+    );
   }
-  static fromDict(data) {
-    return new _StreamFrame(
-      data["stream_id"],
-      data["seq"],
-      data["is_last"],
-      data["data"],
-      data["anchor_ref"] ?? void 0,
-      data["window_size"] ?? void 0
+  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)"
     );
   }
-};
-var CapsFrame = class _CapsFrame {
-  constructor(anchorRef, count, data, nextCursor, tokenEst, cached, tokenizerUsed) {
-    this.anchorRef = anchorRef;
-    this.count = count;
-    this.data = data;
-    this.nextCursor = nextCursor;
-    this.tokenEst = tokenEst;
-    this.cached = cached;
-    this.tokenizerUsed = tokenizerUsed;
-  }
-  anchorRef;
-  count;
-  data;
-  nextCursor;
-  tokenEst;
-  cached;
-  tokenizerUsed;
-  frameType = 4 /* CAPS */;
-  preferredTier = 1 /* MSGPACK */;
-  toDict() {
-    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
-    };
+  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)"
+    );
   }
-  static fromDict(data) {
-    return new _CapsFrame(
-      data["anchor_ref"],
-      data["count"],
-      data["data"],
-      data["next_cursor"] ?? void 0,
-      data["token_est"] ?? void 0,
-      data["cached"] ?? void 0,
-      data["tokenizer_used"] ?? void 0
+}
+
+// src/ncp/frames/stream-frame.ts
+var 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;
+function validateStreamFrame(frame) {
+  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`
     );
   }
+}
+
+// src/ncp/ncp-error-codes.ts
+var 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"
 };
-var ErrorFrame = class _ErrorFrame {
-  constructor(status, error, message, details) {
-    this.status = status;
-    this.error = error;
-    this.message = message;
-    this.details = details;
-  }
-  status;
-  error;
-  message;
-  details;
-  frameType = 254 /* ERROR */;
-  preferredTier = 1 /* MSGPACK */;
-  toDict() {
+
+// src/ncp/handshake.ts
+function parseVersion(v) {
+  return v.split(".").map((p) => Number.parseInt(p, 10));
+}
+function compareVersions(a, b) {
+  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;
+}
+function negotiateVersion(client, server) {
+  const clientMin = client.min_version ?? client.nps_version;
+  const serverVersion = server.nps_version;
+  if (compareVersions(clientMin, serverVersion) > 0) {
     return {
-      status: this.status,
-      error: this.error,
-      message: this.message ?? null,
-      details: this.details ?? null
+      session_version: serverVersion,
+      compatible: false,
+      error_code: "NCP-VERSION-INCOMPATIBLE"
     };
   }
-  static fromDict(data) {
-    return new _ErrorFrame(
-      data["status"],
-      data["error"],
-      data["message"] ?? void 0,
-      data["details"] ?? void 0
-    );
+  const sessionVersion = compareVersions(client.nps_version, serverVersion) <= 0 ? client.nps_version : serverVersion;
+  return { session_version: sessionVersion, compatible: true };
+}
+function negotiateEncoding(client, server) {
+  const serverSet = new Set(server);
+  if (client.includes("msgpack") && serverSet.has("msgpack")) {
+    return { encoding: "msgpack" };
   }
-};
-
-// src/ncp/registry.ts
-function registerNcpFrames(registry) {
-  registry.register(1 /* ANCHOR */, AnchorFrame);
-  registry.register(2 /* DIFF */, DiffFrame);
-  registry.register(3 /* STREAM */, StreamFrame);
-  registry.register(4 /* CAPS */, CapsFrame);
-  registry.register(254 /* ERROR */, ErrorFrame);
+  if (client.includes("json") && serverSet.has("json")) {
+    return { encoding: "json" };
+  }
+  for (const enc of client) {
+    if (serverSet.has(enc)) {
+      return { encoding: enc };
+    }
+  }
+  return { encoding: null };
 }
 
-exports.AnchorFrame = AnchorFrame;
-exports.CapsFrame = CapsFrame;
-exports.DiffFrame = DiffFrame;
-exports.ErrorFrame = ErrorFrame;
-exports.StreamFrame = StreamFrame;
-exports.registerNcpFrames = registerNcpFrames;
+// src/ncp/stream-manager.ts
+var StreamManager = class {
+  streams = /* @__PURE__ */ new Map();
+  outgoing = /* @__PURE__ */ new Map();
+  maxConcurrent;
+  constructor(options) {
+    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) {
+    let stream = this.streams.get(frame.stream_id);
+    if (!stream) {
+      if (frame.seq !== 0) {
+        throw new NcpError(
+          NCP_ERROR_CODES.NCP_STREAM_NOT_FOUND,
+          `Unknown stream_id ${frame.stream_id} \u2014 first frame must have seq=0`
+        );
+      }
+      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);
+    }
+    if (stream.completed) {
+      throw new NcpError(
+        "NPS-CLIENT-CONFLICT",
+        `Stream ${frame.stream_id} is already completed \u2014 cannot reuse stream_id`
+      );
+    }
+    if (frame.seq !== stream.expectedSeq) {
+      if (frame.seq < stream.expectedSeq) {
+        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;
+    if (frame.error_code) {
+      stream.completed = true;
+      stream.errorCode = frame.error_code;
+      return true;
+    }
+    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) {
+    let out = this.outgoing.get(frame.stream_id);
+    if (!out) {
+      out = {
+        streamId: frame.stream_id,
+        remainingWindow: void 0,
+        paused: false
+      };
+      this.outgoing.set(frame.stream_id, out);
+    }
+    if (frame.seq === 0 && frame.window_size !== void 0) {
+      out.remainingWindow = frame.window_size;
+      return;
+    }
+    if (out.remainingWindow !== void 0) {
+      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, newSize) {
+    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) {
+    return this.outgoing.get(streamId)?.paused ?? false;
+  }
+  /** Get reassembled data for a completed stream. */
+  getData(streamId) {
+    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) {
+    return this.streams.get(streamId)?.errorCode;
+  }
+  /** Number of active (non-completed) streams. */
+  get activeCount() {
+    let count = 0;
+    for (const s of this.streams.values()) {
+      if (!s.completed) count++;
+    }
+    return count;
+  }
+};
+
+exports.NCP_ERROR_CODES = NCP_ERROR_CODES;
+exports.PATCH_FORMAT = PATCH_FORMAT;
+exports.StreamManager = StreamManager;
+exports.computeAnchorId = computeAnchorId;
+exports.isErrorFrame = isErrorFrame;
+exports.isValidPatchFormat = isValidPatchFormat;
+exports.negotiateEncoding = negotiateEncoding;
+exports.negotiateVersion = negotiateVersion;
+exports.validateAnchorFrame = validateAnchorFrame;
+exports.validateCapsFrame = validateCapsFrame;
+exports.validateDiffFrame = validateDiffFrame;
+exports.validateDiffSeq = validateDiffSeq;
+exports.validateHelloFrame = validateHelloFrame;
+exports.validateStreamFrame = validateStreamFrame;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map