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

package/tests/ncp/frames.test.ts

@@ -1,359 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// NCP Test Cases — Frame types + Tier-1 JSON codec
-// Covers: NCP-E-01, E-03, NCP-A-01 to A-04, NCP-C-01 to C-04, NCP-D-01 to D-04
-// Source: test/ncp_test_cases.md §2, §3
-
-import { describe, it, expect } from "vitest";
-import { NcpError } from "../../src/core/frame-header.js";
-import { encodeJson, decodeJson } from "../../src/core/codecs/tier1-json-codec.js";
-import {
-  computeAnchorId,
-  validateAnchorFrame,
-  type AnchorFrame,
-  type FrameSchema,
-} from "../../src/ncp/frames/anchor-frame.js";
-import { validateCapsFrame, type CapsFrame } from "../../src/ncp/frames/caps-frame.js";
-import { validateDiffSeq, type DiffFrame } from "../../src/ncp/frames/diff-frame.js";
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const testSchema: FrameSchema = {
-  fields: [
-    { name: "id", type: "uint64", semantic: "entity.id" },
-    { name: "name", type: "string", semantic: "entity.label" },
-    { name: "price", type: "decimal", semantic: "commerce.price.usd" },
-    { name: "stock", type: "uint64", semantic: "commerce.inventory.count" },
-  ],
-};
-
-function makeValidAnchor(): AnchorFrame {
-  const anchor_id = computeAnchorId(testSchema);
-  return { frame: "0x01", anchor_id, schema: testSchema, ttl: 3600 };
-}
-
-// ===========================================================================
-// Group 2: Encoding Tiers (Tier-1 JSON)
-// ===========================================================================
-
-describe("Group 2: Encoding — Tier-1 JSON", () => {
-  // -----------------------------------------------------------------------
-  // NCP-E-01: Tier-1 JSON (Valid)
-  // Spec: §3.2, §8 — Flags T0/T1 = 00
-  // -----------------------------------------------------------------------
-  it("NCP-E-01: encodes and decodes valid JSON payload", () => {
-    const anchor = makeValidAnchor();
-    const bytes = encodeJson(anchor);
-    const decoded = decodeJson(bytes) as AnchorFrame;
-
-    expect(decoded.frame).toBe("0x01");
-    expect(decoded.anchor_id).toBe(anchor.anchor_id);
-    expect(decoded.schema.fields).toHaveLength(4);
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-E-03: Tier-1 JSON (Malformed)
-  // Spec: §3.2, §8 — Invalid JSON → NPS-CLIENT-BAD-FRAME
-  // -----------------------------------------------------------------------
-  it("NCP-E-03: rejects malformed JSON payload", () => {
-    const bad = new TextEncoder().encode('{"frame":"0x01", "anchor_id":');
-    expect(() => decodeJson(bad)).toThrow(NcpError);
-
-    try {
-      decodeJson(bad);
-    } catch (e) {
-      expect((e as NcpError).code).toBe("NPS-CLIENT-BAD-FRAME");
-    }
-  });
-});
-
-// ===========================================================================
-// Group 3.1: AnchorFrame (0x01)
-// ===========================================================================
-
-describe("Group 3.1: AnchorFrame", () => {
-  // -----------------------------------------------------------------------
-  // NCP-A-01: Valid Anchor
-  // Spec: §4.1 — anchor_id = SHA-256(JCS(schema))
-  // -----------------------------------------------------------------------
-  it("NCP-A-01: computes correct anchor_id via JCS + SHA-256", () => {
-    const anchor_id = computeAnchorId(testSchema);
-
-    expect(anchor_id).toMatch(/^sha256:[a-f0-9]{64}$/);
-
-    // Same schema produces same ID (deterministic)
-    expect(computeAnchorId(testSchema)).toBe(anchor_id);
-  });
-
-  it("NCP-A-01: different field order produces same anchor_id (JCS normalises)", () => {
-    const schemaA: FrameSchema = {
-      fields: [
-        { name: "id", type: "uint64" },
-        { name: "name", type: "string" },
-      ],
-    };
-    const schemaB: FrameSchema = {
-      fields: [
-        { name: "name", type: "string" },
-        { name: "id", type: "uint64" },
-      ],
-    };
-
-    // NOTE: JCS sorts object keys, but array order is preserved.
-    // Different field ORDER in the array produces different hashes.
-    // Only different key ORDER within objects is normalised.
-    const idA = computeAnchorId(schemaA);
-    const idB = computeAnchorId(schemaB);
-
-    // Array order matters — these are different schemas
-    expect(idA).not.toBe(idB);
-  });
-
-  it("NCP-A-01: validates and caches valid anchor frame", () => {
-    const anchor = makeValidAnchor();
-    expect(() => validateAnchorFrame(anchor)).not.toThrow();
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-A-02: Anchor ID Mismatch
-  // Spec: §4.1 — Provided anchor_id != SHA-256(JCS(schema))
-  // -----------------------------------------------------------------------
-  it("NCP-A-02: rejects anchor with wrong anchor_id", () => {
-    const anchor: AnchorFrame = {
-      frame: "0x01",
-      anchor_id: "sha256:0000000000000000000000000000000000000000000000000000000000000000",
-      schema: testSchema,
-      ttl: 3600,
-    };
-
-    expect(() => validateAnchorFrame(anchor)).toThrow(NcpError);
-    try {
-      validateAnchorFrame(anchor);
-    } catch (e) {
-      expect((e as NcpError).code).toBe("NCP-ANCHOR-SCHEMA-INVALID");
-    }
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-A-03: Anchor Poisoning — tested in Step 7 (AnchorCache)
-  // -----------------------------------------------------------------------
-
-  // -----------------------------------------------------------------------
-  // NCP-A-04: Invalid Schema Field
-  // Spec: §4.1 — Unsupported type (e.g. "tensor")
-  // -----------------------------------------------------------------------
-  it("NCP-A-04: rejects schema with unsupported field type", () => {
-    const badSchema: FrameSchema = {
-      fields: [
-        { name: "id", type: "uint64" },
-        { name: "embedding", type: "tensor" }, // not in valid types
-      ],
-    };
-    const anchor_id = computeAnchorId(badSchema);
-    const anchor: AnchorFrame = {
-      frame: "0x01",
-      anchor_id,
-      schema: badSchema,
-    };
-
-    expect(() => validateAnchorFrame(anchor)).toThrow(NcpError);
-    try {
-      validateAnchorFrame(anchor);
-    } catch (e) {
-      expect((e as NcpError).code).toBe("NCP-ANCHOR-SCHEMA-INVALID");
-    }
-  });
-
-  it("NCP-A-04: accepts all valid field types", () => {
-    const allTypes: FrameSchema = {
-      fields: [
-        { name: "a", type: "string" },
-        { name: "b", type: "uint64" },
-        { name: "c", type: "int64" },
-        { name: "d", type: "decimal" },
-        { name: "e", type: "bool" },
-        { name: "f", type: "timestamp" },
-        { name: "g", type: "bytes" },
-        { name: "h", type: "object" },
-        { name: "i", type: "array" },
-      ],
-    };
-    const anchor_id = computeAnchorId(allTypes);
-    const anchor: AnchorFrame = { frame: "0x01", anchor_id, schema: allTypes };
-    expect(() => validateAnchorFrame(anchor)).not.toThrow();
-  });
-
-  // NCP-A-05 and NCP-A-06 — tested in Step 7 (AnchorCache)
-});
-
-// ===========================================================================
-// Group 3.4: CapsFrame (0x04)
-// ===========================================================================
-
-describe("Group 3.4: CapsFrame", () => {
-  // -----------------------------------------------------------------------
-  // NCP-C-01: Empty Data
-  // Spec: §4.4 — count=0, data=[] is valid
-  // -----------------------------------------------------------------------
-  it("NCP-C-01: accepts empty data with count=0", () => {
-    const caps: CapsFrame = {
-      frame: "0x04",
-      anchor_ref: "sha256:abc123",
-      count: 0,
-      data: [],
-    };
-    expect(() => validateCapsFrame(caps)).not.toThrow();
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-C-02: Count Mismatch
-  // Spec: §4.4 — count MUST equal len(data)
-  // -----------------------------------------------------------------------
-  it("NCP-C-02: rejects count mismatch", () => {
-    const caps: CapsFrame = {
-      frame: "0x04",
-      anchor_ref: "sha256:abc123",
-      count: 3,
-      data: [{ id: 1 }, { id: 2 }], // 2 items but count says 3
-    };
-    expect(() => validateCapsFrame(caps)).toThrow(NcpError);
-
-    try {
-      validateCapsFrame(caps);
-    } catch (e) {
-      expect((e as NcpError).code).toBe("NPS-CLIENT-BAD-FRAME");
-    }
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-C-03: Cursor Handling
-  // Spec: §4.4 — Base64-URL next_cursor
-  // -----------------------------------------------------------------------
-  it("NCP-C-03: preserves Base64-URL cursor in round-trip", () => {
-    const caps: CapsFrame = {
-      frame: "0x04",
-      anchor_ref: "sha256:abc123",
-      count: 2,
-      data: [{ id: 1001 }, { id: 1002 }],
-      next_cursor: "eyJpZCI6MTAwM30", // {"id":1003}
-    };
-    expect(() => validateCapsFrame(caps)).not.toThrow();
-
-    const bytes = encodeJson(caps);
-    const decoded = decodeJson(bytes) as CapsFrame;
-    expect(decoded.next_cursor).toBe("eyJpZCI6MTAwM30");
-
-    // Decode the cursor
-    const cursorData = JSON.parse(
-      Buffer.from(decoded.next_cursor!, "base64url").toString(),
-    );
-    expect(cursorData.id).toBe(1003);
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-C-04: Token Budget Hint
-  // Spec: §4.4 — token_est is informational
-  // -----------------------------------------------------------------------
-  it("NCP-C-04: preserves token_est in round-trip", () => {
-    const caps: CapsFrame = {
-      frame: "0x04",
-      anchor_ref: "sha256:abc123",
-      count: 1,
-      data: [{ id: 1 }],
-      token_est: 180,
-    };
-    const bytes = encodeJson(caps);
-    const decoded = decodeJson(bytes) as CapsFrame;
-    expect(decoded.token_est).toBe(180);
-  });
-});
-
-// ===========================================================================
-// Group 3.2: DiffFrame (0x02)
-// ===========================================================================
-
-describe("Group 3.2: DiffFrame", () => {
-  // -----------------------------------------------------------------------
-  // NCP-D-01: Valid Patch
-  // Spec: §4.2 — RFC 6902 JSON Patch applied to anchor data
-  // -----------------------------------------------------------------------
-  it("NCP-D-01: round-trips valid DiffFrame with JSON patch", () => {
-    const diff: DiffFrame = {
-      frame: "0x02",
-      anchor_ref: "sha256:abc123",
-      base_seq: 42,
-      patch_format: "json_patch",
-      entity_id: "product:1001",
-      patch: [
-        { op: "replace", path: "/price", value: 299.0 },
-        { op: "replace", path: "/stock", value: 48 },
-      ],
-    };
-
-    const bytes = encodeJson(diff);
-    const decoded = decodeJson(bytes) as DiffFrame;
-
-    expect(decoded.anchor_ref).toBe("sha256:abc123");
-    expect(decoded.base_seq).toBe(42);
-    expect(decoded.patch).toHaveLength(2);
-    expect(decoded.patch[0]!.op).toBe("replace");
-    expect(decoded.patch[0]!.value).toBe(299.0);
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-D-02: Sequence Gap
-  // Spec: §4.2 — base_seq must match receiver's current sequence
-  // -----------------------------------------------------------------------
-  it("NCP-D-02: rejects sequence gap", () => {
-    const diff: DiffFrame = {
-      frame: "0x02",
-      anchor_ref: "sha256:abc123",
-      base_seq: 3,
-      patch: [{ op: "replace", path: "/price", value: 100 }],
-    };
-    const currentSeq = 5;
-
-    expect(() => validateDiffSeq(diff, currentSeq)).toThrow(NcpError);
-    try {
-      validateDiffSeq(diff, currentSeq);
-    } catch (e) {
-      expect((e as NcpError).code).toBe("NCP-STREAM-SEQ-GAP");
-    }
-  });
-
-  it("NCP-D-02: accepts matching sequence", () => {
-    const diff: DiffFrame = {
-      frame: "0x02",
-      anchor_ref: "sha256:abc123",
-      base_seq: 5,
-      patch: [{ op: "replace", path: "/price", value: 100 }],
-    };
-    expect(() => validateDiffSeq(diff, 5)).not.toThrow();
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-D-03: Patch Target Invalid
-  // Spec: §4.2 — Patch path not in schema
-  // NOTE: Full validation requires schema context. Tested with fast-json-patch
-  //       at integration level. Here we verify the DiffFrame structure.
-  // -----------------------------------------------------------------------
-  it("NCP-D-03: DiffFrame preserves patch paths for validation", () => {
-    const diff: DiffFrame = {
-      frame: "0x02",
-      anchor_ref: "sha256:abc123",
-      base_seq: 0,
-      patch: [{ op: "replace", path: "/nonexistent_field", value: 42 }],
-    };
-
-    const bytes = encodeJson(diff);
-    const decoded = decodeJson(bytes) as DiffFrame;
-    expect(decoded.patch[0]!.path).toBe("/nonexistent_field");
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-D-04: Missing Ref — tested in Step 7 (AnchorCache lookup)
-  // -----------------------------------------------------------------------
-});

package/tests/ncp/framing.test.ts

@@ -1,233 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// NCP Test Cases — Group 1: Framing & Header (NCP-F-01 to NCP-F-07)
-// Source: test/ncp_test_cases.md §1
-
-import { describe, it, expect } from "vitest";
-import {
-  parseFrameHeader,
-  writeFrameHeader,
-  buildFlags,
-  EncodingTier,
-  FrameType,
-  NcpError,
-  DEFAULT_HEADER_SIZE,
-  EXTENDED_HEADER_SIZE,
-} from "../../src/core/frame-header.js";
-
-describe("Group 1: Framing & Header", () => {
-  // -----------------------------------------------------------------------
-  // NCP-F-01: Standard Header (Valid)
-  // Spec: §3.1 — Default 4-byte header
-  // -----------------------------------------------------------------------
-  it("NCP-F-01: decodes standard 4-byte header", () => {
-    // AnchorFrame (0x01), flags=0x00 (JSON, no flags), payload=32 bytes
-    const buf = new Uint8Array([0x01, 0x00, 0x00, 0x20]);
-    const h = parseFrameHeader(buf);
-
-    expect(h.frameType).toBe(FrameType.Anchor);
-    expect(h.tier).toBe(EncodingTier.Json);
-    expect(h.isFinal).toBe(false);
-    expect(h.isEncrypted).toBe(false);
-    expect(h.isExtended).toBe(false);
-    expect(h.payloadLength).toBe(32);
-    expect(h.headerSize).toBe(DEFAULT_HEADER_SIZE);
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-F-02: Extended Header (Valid)
-  // Spec: §3.1 — Extended 8-byte header (EXT=1)
-  // -----------------------------------------------------------------------
-  it("NCP-F-02: decodes extended 8-byte header with EXT=1", () => {
-    // AnchorFrame, EXT=1 (0x80), payload=65536 (just over default max)
-    const buf = new Uint8Array([0x01, 0x80, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00]);
-    const h = parseFrameHeader(buf);
-
-    expect(h.frameType).toBe(FrameType.Anchor);
-    expect(h.isExtended).toBe(true);
-    expect(h.payloadLength).toBe(65536);
-    expect(h.headerSize).toBe(EXTENDED_HEADER_SIZE);
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-F-03: EXT Flag Mismatch (Low)
-  // Spec: §3.1, §3.3 — EXT=1 with small payload is valid but inefficient
-  // -----------------------------------------------------------------------
-  it("NCP-F-03: accepts EXT=1 with small payload (inefficient but valid)", () => {
-    // Extended header, payload=100 bytes (well under 64KB)
-    const buf = new Uint8Array([0x01, 0x80, 0x00, 0x00, 0x00, 0x64, 0x00, 0x00]);
-    const h = parseFrameHeader(buf);
-
-    expect(h.isExtended).toBe(true);
-    expect(h.payloadLength).toBe(100);
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-F-04: EXT Flag Mismatch (High) — NCP-FRAME-PAYLOAD-TOO-LARGE
-  // NOTE: This test belongs at the codec level (Step 5). Default header
-  //       uint16 maxes at 65535 — can't physically express > 64KB.
-  //       Codec validates payload against negotiated max_frame_payload.
-  // -----------------------------------------------------------------------
-
-  // -----------------------------------------------------------------------
-  // NCP-F-05: Buffer Underrun
-  // Spec: §3.1 — Incomplete data
-  // -----------------------------------------------------------------------
-  it("NCP-F-05: errors when buffer too small for header", () => {
-    // Only 1 byte — need at least 2 for type + flags
-    expect(() => parseFrameHeader(new Uint8Array([0x01]))).toThrow(NcpError);
-  });
-
-  it("NCP-F-05: errors when buffer too small for default header", () => {
-    // 3 bytes — need 4 for default header
-    expect(() => parseFrameHeader(new Uint8Array([0x01, 0x00, 0x00]))).toThrow(
-      NcpError,
-    );
-  });
-
-  it("NCP-F-05: errors when buffer too small for extended header", () => {
-    // 4 bytes with EXT=1 — need 8
-    expect(() =>
-      parseFrameHeader(new Uint8Array([0x01, 0x80, 0x00, 0x00])),
-    ).toThrow(NcpError);
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-F-06: Buffer Overrun
-  // Spec: §3.1 — Extra bytes are buffered for next frame
-  // -----------------------------------------------------------------------
-  it("NCP-F-06: parses header from oversized buffer", () => {
-    // 4-byte header + 250 extra bytes — header parses, remainder ignored
-    const buf = new Uint8Array(254);
-    buf[0] = 0x01; // AnchorFrame
-    buf[1] = 0x00; // no flags
-    buf[2] = 0x00;
-    buf[3] = 0x64; // payload = 100
-
-    const h = parseFrameHeader(buf);
-    expect(h.payloadLength).toBe(100);
-    // Codec would read buf[4..104] as payload, buffer buf[104..] for next frame
-  });
-
-  // -----------------------------------------------------------------------
-  // NCP-F-07: Reserved Flags Non-Zero
-  // Spec: §3.2 — Bits 4-6 MUST be 0
-  // -----------------------------------------------------------------------
-  it("NCP-F-07: rejects non-zero reserved flag bits (bit 4)", () => {
-    const buf = new Uint8Array([0x01, 0x10, 0x00, 0x20]); // bit 4 set
-    expect(() => parseFrameHeader(buf)).toThrow(NcpError);
-  });
-
-  it("NCP-F-07: rejects non-zero reserved flag bits (bit 5)", () => {
-    const buf = new Uint8Array([0x01, 0x20, 0x00, 0x20]); // bit 5 set
-    expect(() => parseFrameHeader(buf)).toThrow(NcpError);
-  });
-
-  it("NCP-F-07: rejects non-zero reserved flag bits (bit 6)", () => {
-    const buf = new Uint8Array([0x01, 0x40, 0x00, 0x20]); // bit 6 set
-    expect(() => parseFrameHeader(buf)).toThrow(NcpError);
-  });
-
-  it("NCP-F-07: error code is NCP-FRAME-FLAGS-INVALID", () => {
-    const buf = new Uint8Array([0x01, 0x20, 0x00, 0x20]);
-    try {
-      parseFrameHeader(buf);
-      expect.unreachable("should have thrown");
-    } catch (e) {
-      expect(e).toBeInstanceOf(NcpError);
-      expect((e as NcpError).code).toBe("NCP-FRAME-FLAGS-INVALID");
-    }
-  });
-
-  // -----------------------------------------------------------------------
-  // Additional: Round-trip, ENC flag, write validation
-  // -----------------------------------------------------------------------
-  it("round-trips default header", () => {
-    const flags = buildFlags({ tier: EncodingTier.MsgPack, final: true });
-    const original = {
-      frameType: FrameType.Caps,
-      flags,
-      payloadLength: 1024,
-      tier: EncodingTier.MsgPack,
-      isFinal: true,
-      isEncrypted: false,
-      isExtended: false,
-      headerSize: DEFAULT_HEADER_SIZE,
-    };
-
-    const buf = new Uint8Array(DEFAULT_HEADER_SIZE);
-    writeFrameHeader(original, buf);
-    const parsed = parseFrameHeader(buf);
-
-    expect(parsed.frameType).toBe(original.frameType);
-    expect(parsed.payloadLength).toBe(original.payloadLength);
-    expect(parsed.tier).toBe(EncodingTier.MsgPack);
-    expect(parsed.isFinal).toBe(true);
-  });
-
-  it("round-trips extended header", () => {
-    const flags = buildFlags({ tier: EncodingTier.Json, extended: true });
-    const original = {
-      frameType: FrameType.Stream,
-      flags,
-      payloadLength: 100_000,
-      tier: EncodingTier.Json,
-      isFinal: false,
-      isEncrypted: false,
-      isExtended: true,
-      headerSize: EXTENDED_HEADER_SIZE,
-    };
-
-    const buf = new Uint8Array(EXTENDED_HEADER_SIZE);
-    writeFrameHeader(original, buf);
-    const parsed = parseFrameHeader(buf);
-
-    expect(parsed.frameType).toBe(original.frameType);
-    expect(parsed.payloadLength).toBe(100_000);
-    expect(parsed.isExtended).toBe(true);
-  });
-
-  it("detects ENC flag", () => {
-    const flags = buildFlags({ encrypted: true });
-    const buf = new Uint8Array([0x01, flags, 0x00, 0x20]);
-    const h = parseFrameHeader(buf);
-    expect(h.isEncrypted).toBe(true);
-  });
-
-  it("write errors on undersized buffer", () => {
-    const h = {
-      frameType: FrameType.Anchor,
-      flags: 0x00,
-      payloadLength: 32,
-      tier: EncodingTier.Json,
-      isFinal: false,
-      isEncrypted: false,
-      isExtended: false,
-      headerSize: DEFAULT_HEADER_SIZE,
-    };
-    expect(() => writeFrameHeader(h, new Uint8Array(2))).toThrow();
-  });
-
-  it("extended header reserved bytes are zero", () => {
-    const flags = buildFlags({ extended: true });
-    const h = {
-      frameType: FrameType.Anchor,
-      flags,
-      payloadLength: 70_000,
-      tier: EncodingTier.Json,
-      isFinal: false,
-      isEncrypted: false,
-      isExtended: true,
-      headerSize: EXTENDED_HEADER_SIZE,
-    };
-
-    const buf = new Uint8Array(EXTENDED_HEADER_SIZE);
-    buf[6] = 0xff; // pre-fill to prove write zeros
-    buf[7] = 0xff;
-    writeFrameHeader(h, buf);
-
-    expect(buf[6]).toBe(0);
-    expect(buf[7]).toBe(0);
-  });
-});