@labacacia/nps-sdk 1.0.0-alpha.1

package/tests/core/anchor-cache.test.ts

@@ -0,0 +1,242 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — AnchorCache
+// Covers: NCP-A-03, A-05, A-06, NCP-CA-01 to CA-05
+// Source: test/ncp_test_cases.md §3.1, §4
+
+import { describe, it, expect } from "vitest";
+import { NcpError } from "../../src/core/frame-header.js";
+import { AnchorCache } from "../../src/core/anchor-cache.js";
+import {
+  computeAnchorId,
+  type AnchorFrame,
+  type FrameSchema,
+} from "../../src/ncp/frames/anchor-frame.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const schemaA: FrameSchema = {
+  fields: [
+    { name: "id", type: "uint64" },
+    { name: "name", type: "string" },
+  ],
+};
+
+const schemaB: FrameSchema = {
+  fields: [
+    { name: "id", type: "uint64" },
+    { name: "price", type: "decimal" },
+  ],
+};
+
+function makeAnchor(schema: FrameSchema, ttl?: number): AnchorFrame {
+  return {
+    frame: "0x01",
+    anchor_id: computeAnchorId(schema),
+    schema,
+    ttl: ttl ?? 3600,
+  };
+}
+
+// ===========================================================================
+// NCP-A-03: Anchor Poisoning
+// ===========================================================================
+
+describe("NCP-A-03: Anchor Poisoning", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §7.2 — Same anchor_id with different schema → NCP-ANCHOR-ID-MISMATCH
+  // -----------------------------------------------------------------------
+  it("detects anchor poisoning (same ID, different schema)", () => {
+    const cache = new AnchorCache();
+    const anchor = makeAnchor(schemaA);
+    cache.set(anchor);
+
+    // Craft a poisoned frame: same anchor_id but different schema
+    const poisoned: AnchorFrame = {
+      frame: "0x01",
+      anchor_id: anchor.anchor_id, // same ID
+      schema: schemaB, // different schema!
+      ttl: 3600,
+    };
+
+    expect(() => cache.set(poisoned)).toThrow(NcpError);
+    try {
+      cache.set(poisoned);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-ANCHOR-ID-MISMATCH");
+    }
+  });
+
+  it("allows idempotent set with same schema", () => {
+    const cache = new AnchorCache();
+    const anchor = makeAnchor(schemaA);
+    cache.set(anchor);
+    expect(() => cache.set(anchor)).not.toThrow(); // same schema — fine
+    expect(cache.size).toBe(1);
+  });
+});
+
+// ===========================================================================
+// NCP-A-05: Zero TTL
+// ===========================================================================
+
+describe("NCP-A-05: Zero TTL", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §4.1 — ttl=0 means don't cache, use once
+  // -----------------------------------------------------------------------
+  it("does not cache frames with ttl=0", () => {
+    const cache = new AnchorCache();
+    const anchor = makeAnchor(schemaA, 0); // ttl=0
+    cache.set(anchor);
+
+    expect(cache.size).toBe(0);
+    expect(cache.get(anchor.anchor_id)).toBeNull();
+  });
+});
+
+// ===========================================================================
+// NCP-A-06: TTL Expiry
+// ===========================================================================
+
+describe("NCP-A-06: TTL Expiry", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §5.3 — Expired anchors return not-found
+  // -----------------------------------------------------------------------
+  it("expires anchors after TTL", () => {
+    let now = 1000;
+    const cache = new AnchorCache({ getNow: () => now });
+
+    const anchor = makeAnchor(schemaA, 1); // ttl=1 second
+    cache.set(anchor);
+
+    // Still valid
+    expect(cache.get(anchor.anchor_id)).not.toBeNull();
+
+    // Advance time past TTL
+    now = 3000; // 2 seconds later
+    expect(cache.get(anchor.anchor_id)).toBeNull();
+  });
+
+  it("getRequired throws NCP-ANCHOR-NOT-FOUND after expiry", () => {
+    let now = 1000;
+    const cache = new AnchorCache({ getNow: () => now });
+
+    const anchor = makeAnchor(schemaA, 1);
+    cache.set(anchor);
+
+    now = 3000;
+    expect(() => cache.getRequired(anchor.anchor_id)).toThrow(NcpError);
+    try {
+      cache.getRequired(anchor.anchor_id);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-ANCHOR-NOT-FOUND");
+    }
+  });
+});
+
+// ===========================================================================
+// Group 4: Schema Caching
+// ===========================================================================
+
+describe("Group 4: Schema Caching", () => {
+  // -----------------------------------------------------------------------
+  // NCP-CA-01: Cache Hit
+  // Spec: §5.3 — anchor_ref already in local cache
+  // -----------------------------------------------------------------------
+  it("NCP-CA-01: returns cached schema on hit", () => {
+    const cache = new AnchorCache();
+    const anchor = makeAnchor(schemaA);
+    cache.set(anchor);
+
+    const result = cache.get(anchor.anchor_id);
+    expect(result).not.toBeNull();
+    expect(result!.anchor_id).toBe(anchor.anchor_id);
+    expect(result!.schema.fields).toHaveLength(2);
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-CA-02: Cache Miss (Local)
+  // Spec: §5.4 — Unknown anchor_ref → trigger fetch
+  // -----------------------------------------------------------------------
+  it("NCP-CA-02: returns null for unknown anchor_ref", () => {
+    const cache = new AnchorCache();
+    expect(cache.get("sha256:unknown")).toBeNull();
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-CA-03: Cache Miss (Server)
+  // Spec: §5.4.2 — Server returns NCP-ANCHOR-NOT-FOUND
+  // -----------------------------------------------------------------------
+  it("NCP-CA-03: getRequired throws NCP-ANCHOR-NOT-FOUND for unknown ref", () => {
+    const cache = new AnchorCache();
+    expect(() => cache.getRequired("sha256:fabricated")).toThrow(NcpError);
+    try {
+      cache.getRequired("sha256:fabricated");
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-ANCHOR-NOT-FOUND");
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-CA-04: LRU Eviction
+  // Spec: §9 — Cache limit 1000, LRU eviction
+  // -----------------------------------------------------------------------
+  it("NCP-CA-04: evicts LRU entry when cache is full", () => {
+    let now = 1000;
+    const cache = new AnchorCache({ maxSize: 3, getNow: () => now });
+
+    // Fill cache with 3 entries at different times
+    const anchors = Array.from({ length: 3 }, (_, i) => {
+      const schema: FrameSchema = {
+        fields: [{ name: `field_${i}`, type: "string" }],
+      };
+      return makeAnchor(schema);
+    });
+    now = 1000; cache.set(anchors[0]!);
+    now = 2000; cache.set(anchors[1]!);
+    now = 3000; cache.set(anchors[2]!);
+    expect(cache.size).toBe(3);
+
+    // Access first anchor to make it most recently used
+    now = 4000;
+    cache.get(anchors[0]!.anchor_id);
+
+    // Add 4th entry — should evict anchors[1] (lastAccessed=2000, the oldest)
+    now = 5000;
+    const newSchema: FrameSchema = {
+      fields: [{ name: "field_new", type: "string" }],
+    };
+    const newAnchor = makeAnchor(newSchema);
+    cache.set(newAnchor);
+
+    expect(cache.size).toBe(3);
+    expect(cache.get(anchors[0]!.anchor_id)).not.toBeNull(); // still here (accessed at 4000)
+    expect(cache.get(anchors[1]!.anchor_id)).toBeNull(); // evicted (LRU at 2000)
+    expect(cache.get(newAnchor.anchor_id)).not.toBeNull(); // newly added
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-CA-05: Schema Update
+  // Spec: §5.4.1 — Same name, different anchor_id can coexist
+  // -----------------------------------------------------------------------
+  it("NCP-CA-05: stores multiple schema versions by anchor_id", () => {
+    const cache = new AnchorCache();
+
+    // v1
+    const anchorV1 = makeAnchor(schemaA);
+    cache.set(anchorV1);
+
+    // v2 (different schema → different anchor_id)
+    const anchorV2 = makeAnchor(schemaB);
+    cache.set(anchorV2);
+
+    // Both should coexist
+    expect(cache.get(anchorV1.anchor_id)).not.toBeNull();
+    expect(cache.get(anchorV2.anchor_id)).not.toBeNull();
+    expect(anchorV1.anchor_id).not.toBe(anchorV2.anchor_id);
+    expect(cache.size).toBe(2);
+  });
+});

package/tests/core/codec.test.ts

@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — Codec dispatcher + MsgPack
+// Covers: NCP-F-04, F-09, NCP-E-02, E-04, E-05, E-06
+// Source: test/ncp_test_cases.md §1, §2
+
+import { describe, it, expect } from "vitest";
+import { EncodingTier, FrameType, NcpError } from "../../src/core/frame-header.js";
+import { encodeFrame, decodeFrame } from "../../src/core/codecs/ncp-codec.js";
+import { computeAnchorId, type FrameSchema } from "../../src/ncp/frames/anchor-frame.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const testSchema: FrameSchema = {
+  fields: [
+    { name: "id", type: "uint64" },
+    { name: "name", type: "string" },
+  ],
+};
+
+// ===========================================================================
+// NCP-F-04: EXT Flag Mismatch (High) — payload exceeds default max
+// ===========================================================================
+
+describe("NCP-F-04 / NCP-F-09: Payload size enforcement", () => {
+  // -----------------------------------------------------------------------
+  // NCP-F-09: Max Payload Enforced
+  // Spec: §3.3 — Negotiated max_frame_payload
+  // -----------------------------------------------------------------------
+  it("NCP-F-09: rejects payload exceeding negotiated max", () => {
+    // Encode a small frame, then decode with a tiny max
+    const frame = encodeFrame(
+      { frame: "0x01", anchor_id: "sha256:abc", schema: testSchema },
+      { frameType: FrameType.Anchor },
+    );
+
+    expect(() => decodeFrame(frame, { maxFramePayload: 10 })).toThrow(NcpError);
+    try {
+      decodeFrame(frame, { maxFramePayload: 10 });
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-FRAME-PAYLOAD-TOO-LARGE");
+    }
+  });
+
+  it("NCP-F-09: accepts payload within negotiated max", () => {
+    const frame = encodeFrame(
+      { frame: "0x01", data: "small" },
+      { frameType: FrameType.Anchor },
+    );
+    expect(() => decodeFrame(frame, { maxFramePayload: 65535 })).not.toThrow();
+  });
+
+  // NCP-F-04: The codec auto-upgrades to extended header for large payloads
+  it("NCP-F-04: auto-extends header for payload > 64KB", () => {
+    const largeData = { frame: "0x03", data: "x".repeat(70_000) };
+    const frame = encodeFrame(largeData, { frameType: FrameType.Stream });
+
+    // Should have used extended header
+    expect(frame[1]! & 0x80).toBe(0x80); // EXT bit set
+
+    // Decode with large enough max
+    const result = decodeFrame(frame, { maxFramePayload: 0xffffffff });
+    expect((result.payload as { data: string }).data).toHaveLength(70_000);
+  });
+});
+
+// ===========================================================================
+// NCP-E-02: Tier-2 MsgPack (Valid)
+// ===========================================================================
+
+describe("NCP-E-02 / E-04: Tier-2 MsgPack", () => {
+  // -----------------------------------------------------------------------
+  // NCP-E-02: Tier-2 MsgPack (Valid)
+  // Spec: §3.2, §8 — Flags T0/T1 = 01
+  // -----------------------------------------------------------------------
+  it("NCP-E-02: round-trips frame via MsgPack encoding", () => {
+    const anchor = {
+      frame: "0x01",
+      anchor_id: computeAnchorId(testSchema),
+      schema: testSchema,
+      ttl: 3600,
+    };
+
+    const encoded = encodeFrame(anchor, {
+      frameType: FrameType.Anchor,
+      tier: EncodingTier.MsgPack,
+    });
+    const result = decodeFrame(encoded);
+
+    expect(result.header.tier).toBe(EncodingTier.MsgPack);
+    const decoded = result.payload as typeof anchor;
+    expect(decoded.frame).toBe("0x01");
+    expect(decoded.ttl).toBe(3600);
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-E-04: Tier-2 MsgPack (Malformed)
+  // Spec: §3.2, §8 — Invalid MsgPack → NPS-CLIENT-BAD-FRAME
+  // -----------------------------------------------------------------------
+  it("NCP-E-04: rejects malformed MsgPack payload", () => {
+    // Craft a frame with MsgPack tier flag but garbage payload
+    const header = new Uint8Array([
+      FrameType.Anchor, // frame type
+      0x01, // flags: Tier-2 MsgPack
+      0x00,
+      0x04, // payload length: 4
+    ]);
+    const garbage = new Uint8Array([0xff, 0xfe, 0xfd, 0xfc]);
+    const frame = new Uint8Array(header.length + garbage.length);
+    frame.set(header);
+    frame.set(garbage, header.length);
+
+    expect(() => decodeFrame(frame)).toThrow(NcpError);
+    try {
+      decodeFrame(frame);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NPS-CLIENT-BAD-FRAME");
+    }
+  });
+});
+
+// ===========================================================================
+// NCP-E-05: Reserved Tier
+// ===========================================================================
+
+describe("NCP-E-05: Reserved encoding tier", () => {
+  // -----------------------------------------------------------------------
+  // NCP-E-05: Reserved Tier (T3/T4)
+  // Spec: §3.2, §8 — T0/T1 = 10 or 11 → NCP-ENCODING-UNSUPPORTED
+  // -----------------------------------------------------------------------
+  it("NCP-E-05: rejects reserved encoding tier 0x02", () => {
+    // Craft header with tier bits = 10 (0x02)
+    const header = new Uint8Array([
+      FrameType.Anchor,
+      0x02, // flags: tier = 10 (reserved)
+      0x00,
+      0x02, // payload: 2 bytes
+    ]);
+    const payload = new Uint8Array([0x80, 0x00]); // dummy
+    const frame = new Uint8Array(header.length + payload.length);
+    frame.set(header);
+    frame.set(payload, header.length);
+
+    expect(() => decodeFrame(frame)).toThrow(NcpError);
+    try {
+      decodeFrame(frame);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-ENCODING-UNSUPPORTED");
+    }
+  });
+
+  it("NCP-E-05: rejects reserved encoding tier 0x03", () => {
+    const header = new Uint8Array([
+      FrameType.Anchor,
+      0x03, // flags: tier = 11 (reserved)
+      0x00,
+      0x02,
+    ]);
+    const payload = new Uint8Array([0x80, 0x00]);
+    const frame = new Uint8Array(header.length + payload.length);
+    frame.set(header);
+    frame.set(payload, header.length);
+
+    expect(() => decodeFrame(frame)).toThrow(NcpError);
+    try {
+      decodeFrame(frame);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-ENCODING-UNSUPPORTED");
+    }
+  });
+});
+
+// ===========================================================================
+// NCP-E-06: Encoding Switch
+// ===========================================================================
+
+describe("NCP-E-06: Mid-session encoding switch", () => {
+  // -----------------------------------------------------------------------
+  // NCP-E-06: Encoding Switch
+  // Spec: §8 — Different frames MAY use different tiers
+  // -----------------------------------------------------------------------
+  it("NCP-E-06: decodes JSON then MsgPack frames back-to-back", () => {
+    const data = { frame: "0x04", anchor_ref: "sha256:abc", count: 0, data: [] };
+
+    const jsonFrame = encodeFrame(data, {
+      frameType: FrameType.Caps,
+      tier: EncodingTier.Json,
+    });
+    const msgpackFrame = encodeFrame(data, {
+      frameType: FrameType.Caps,
+      tier: EncodingTier.MsgPack,
+    });
+
+    const result1 = decodeFrame(jsonFrame);
+    expect(result1.header.tier).toBe(EncodingTier.Json);
+    expect((result1.payload as { count: number }).count).toBe(0);
+
+    const result2 = decodeFrame(msgpackFrame);
+    expect(result2.header.tier).toBe(EncodingTier.MsgPack);
+    expect((result2.payload as { count: number }).count).toBe(0);
+  });
+});

package/tests/core/frame-registry.test.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — NCP-F-08: Unknown Frame Type
+// Source: test/ncp_test_cases.md §1
+
+import { describe, it, expect } from "vitest";
+import { FrameType, NcpError } from "../../src/core/frame-header.js";
+import { FrameRegistry } from "../../src/core/frame-registry.js";
+
+describe("NCP-F-08: Unknown Frame Type", () => {
+  const registry = FrameRegistry.createDefault();
+
+  // -----------------------------------------------------------------------
+  // NCP-F-08: Unknown Frame Type
+  // Spec: §2.3 — Frame type routing table
+  // -----------------------------------------------------------------------
+  it("rejects unregistered frame type 0x88", () => {
+    expect(() => registry.resolve(0x88)).toThrow(NcpError);
+    try {
+      registry.resolve(0x88);
+      expect.unreachable("should have thrown");
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-FRAME-UNKNOWN-TYPE");
+    }
+  });
+
+  it("resolves registered NCP frame types", () => {
+    expect(registry.resolve(FrameType.Anchor).name).toBe("AnchorFrame");
+    expect(registry.resolve(FrameType.Diff).name).toBe("DiffFrame");
+    expect(registry.resolve(FrameType.Stream).name).toBe("StreamFrame");
+    expect(registry.resolve(FrameType.Caps).name).toBe("CapsFrame");
+    expect(registry.resolve(FrameType.Hello).name).toBe("HelloFrame");
+    expect(registry.resolve(FrameType.Error).name).toBe("ErrorFrame");
+  });
+
+  it("resolves protocol for frame types", () => {
+    expect(registry.resolve(FrameType.Anchor).protocol).toBe("ncp");
+    expect(registry.resolve(FrameType.Error).protocol).toBe("system");
+  });
+
+  it("has() returns false for unregistered types", () => {
+    expect(registry.has(0x88)).toBe(false);
+    expect(registry.has(FrameType.Anchor)).toBe(true);
+  });
+});