@labacacia/nps-sdk 1.0.0-alpha.1

package/tests/core.test.ts

@@ -0,0 +1,327 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_HEADER_SIZE,
+  EXTENDED_HEADER_SIZE,
+  FrameFlags,
+  FrameHeader,
+  FrameType,
+  EncodingTier,
+  NpsCodecError,
+  NpsFrameError,
+  NpsAnchorNotFoundError,
+  NpsAnchorPoisonError,
+  NpsFrameCodec,
+  Tier1JsonCodec,
+  Tier2MsgPackCodec,
+  FrameRegistry,
+  AnchorFrameCache,
+} from "../src/core/index.js";
+import { AnchorFrame, CapsFrame, DiffFrame, ErrorFrame, StreamFrame } from "../src/ncp/frames.js";
+import { registerNcpFrames } from "../src/ncp/registry.js";
+import { createDefaultRegistry, createFullRegistry } from "../src/setup.js";
+
+// ── FrameHeader ───────────────────────────────────────────────────────────────
+
+describe("FrameHeader", () => {
+  it("parses a default (4-byte) header", () => {
+    const buf = new Uint8Array([0x01, 0x05, 0x00, 0x0A]); // ANCHOR, FINAL|JSON, length=10
+    const h   = FrameHeader.parse(buf);
+    expect(h.frameType).toBe(FrameType.ANCHOR);
+    expect(h.isFinal).toBe(true);
+    expect(h.payloadLength).toBe(10);
+    expect(h.isExtended).toBe(false);
+    expect(h.headerSize).toBe(DEFAULT_HEADER_SIZE);
+  });
+
+  it("parses an extended (8-byte) header", () => {
+    const buf  = new Uint8Array(8);
+    const view = new DataView(buf.buffer);
+    view.setUint8(0, FrameType.CAPS);
+    view.setUint8(1, FrameFlags.EXT | FrameFlags.TIER2_MSGPACK | FrameFlags.FINAL);
+    view.setUint16(2, 0, false);         // reserved
+    view.setUint32(4, 100_000, false);   // payload length
+    const h = FrameHeader.parse(buf);
+    expect(h.isExtended).toBe(true);
+    expect(h.headerSize).toBe(EXTENDED_HEADER_SIZE);
+    expect(h.payloadLength).toBe(100_000);
+  });
+
+  it("round-trips default header via toBytes()", () => {
+    const h    = new FrameHeader(FrameType.ANCHOR, FrameFlags.FINAL | FrameFlags.TIER2_MSGPACK, 42);
+    const back = FrameHeader.parse(h.toBytes());
+    expect(back.frameType).toBe(FrameType.ANCHOR);
+    expect(back.payloadLength).toBe(42);
+  });
+
+  it("round-trips extended header via toBytes()", () => {
+    const h    = new FrameHeader(FrameType.CAPS, FrameFlags.EXT | FrameFlags.FINAL | FrameFlags.TIER1_JSON, 70_000);
+    const back = FrameHeader.parse(h.toBytes());
+    expect(back.isExtended).toBe(true);
+    expect(back.payloadLength).toBe(70_000);
+  });
+
+  it("throws NpsFrameError for buffer too small", () => {
+    expect(() => FrameHeader.parse(new Uint8Array([0x01]))).toThrow(NpsFrameError);
+  });
+
+  it("throws NpsFrameError for extended header with short buffer", () => {
+    const buf = new Uint8Array([0x01, FrameFlags.EXT, 0x00, 0x00]); // EXT but only 4 bytes
+    expect(() => FrameHeader.parse(buf)).toThrow(NpsFrameError);
+  });
+
+  it("exposes encoding tier", () => {
+    const h = new FrameHeader(FrameType.ANCHOR, FrameFlags.TIER2_MSGPACK | FrameFlags.FINAL, 0);
+    expect(h.encodingTier).toBe(EncodingTier.MSGPACK);
+  });
+});
+
+// ── Exceptions ────────────────────────────────────────────────────────────────
+
+describe("Exceptions", () => {
+  it("NpsAnchorNotFoundError carries anchorId", () => {
+    const err = new NpsAnchorNotFoundError("sha256:abc");
+    expect(err.anchorId).toBe("sha256:abc");
+    expect(err).toBeInstanceOf(NpsAnchorNotFoundError);
+  });
+
+  it("NpsAnchorPoisonError carries anchorId", () => {
+    const err = new NpsAnchorPoisonError("sha256:abc");
+    expect(err.anchorId).toBe("sha256:abc");
+  });
+});
+
+// ── FrameRegistry ─────────────────────────────────────────────────────────────
+
+describe("FrameRegistry", () => {
+  it("resolves a registered frame class", () => {
+    const r = createDefaultRegistry();
+    const cls = r.resolve(FrameType.ANCHOR);
+    expect(cls).toBe(AnchorFrame);
+  });
+
+  it("throws NpsFrameError for unknown frame type", () => {
+    const r = new FrameRegistry();
+    expect(() => r.resolve(FrameType.ANCHOR)).toThrow(NpsFrameError);
+  });
+
+  it("createFullRegistry registers all 5 protocols", () => {
+    const r = createFullRegistry();
+    for (const ft of [
+      FrameType.ANCHOR, FrameType.QUERY, FrameType.IDENT,
+      FrameType.ANNOUNCE, FrameType.TASK,
+    ]) {
+      expect(() => r.resolve(ft)).not.toThrow();
+    }
+  });
+});
+
+// ── AnchorFrameCache ──────────────────────────────────────────────────────────
+
+describe("AnchorFrameCache", () => {
+  const makeSchema = (fields = [{ name: "id", type: "uint64" }]) => ({ fields });
+
+  it("computeAnchorId is deterministic", () => {
+    const s = makeSchema();
+    expect(AnchorFrameCache.computeAnchorId(s)).toBe(AnchorFrameCache.computeAnchorId(s));
+    expect(AnchorFrameCache.computeAnchorId(s)).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+
+  it("computeAnchorId is field-order independent", () => {
+    const s1 = { fields: [{ name: "a", type: "string" }, { name: "b", type: "uint64" }] };
+    const s2 = { fields: [{ name: "b", type: "uint64" }, { name: "a", type: "string" }] };
+    expect(AnchorFrameCache.computeAnchorId(s1)).toBe(AnchorFrameCache.computeAnchorId(s2));
+  });
+
+  it("set + get roundtrip", () => {
+    const cache  = new AnchorFrameCache();
+    const schema = makeSchema();
+    const aid    = AnchorFrameCache.computeAnchorId(schema);
+    const frame  = new AnchorFrame(aid, schema, 3600);
+    cache.set(frame);
+    expect(cache.get(aid)).toBe(frame);
+  });
+
+  it("getRequired returns frame when present", () => {
+    const cache  = new AnchorFrameCache();
+    const schema = makeSchema();
+    const aid    = AnchorFrameCache.computeAnchorId(schema);
+    const frame  = new AnchorFrame(aid, schema, 3600);
+    cache.set(frame);
+    expect(cache.getRequired(aid)).toBe(frame);
+  });
+
+  it("getRequired throws when missing", () => {
+    const cache = new AnchorFrameCache();
+    expect(() => cache.getRequired("sha256:" + "0".repeat(64))).toThrow(NpsAnchorNotFoundError);
+  });
+
+  it("get returns undefined after TTL expiry", () => {
+    const cache  = new AnchorFrameCache();
+    let   now    = 0;
+    cache.clock  = () => now;
+    const schema = makeSchema();
+    const aid    = AnchorFrameCache.computeAnchorId(schema);
+    cache.set(new AnchorFrame(aid, schema, 10));
+    now = 11_000;  // 11 seconds later
+    expect(cache.get(aid)).toBeUndefined();
+  });
+
+  it("idempotent set with same schema", () => {
+    const cache  = new AnchorFrameCache();
+    const schema = makeSchema();
+    const aid    = AnchorFrameCache.computeAnchorId(schema);
+    const frame  = new AnchorFrame(aid, schema, 3600);
+    cache.set(frame);
+    cache.set(frame);
+    expect(cache.size).toBe(1);
+  });
+
+  it("poison detection raises NpsAnchorPoisonError", () => {
+    const cache   = new AnchorFrameCache();
+    const schemaA = makeSchema([{ name: "id", type: "uint64" }]);
+    const schemaB = makeSchema([{ name: "price", type: "decimal" }]);
+    const aid     = AnchorFrameCache.computeAnchorId(schemaA);
+    cache.set(new AnchorFrame(aid, schemaA, 3600));
+    expect(() => cache.set(new AnchorFrame(aid, schemaB, 3600))).toThrow(NpsAnchorPoisonError);
+  });
+
+  it("invalidate removes entry", () => {
+    const cache  = new AnchorFrameCache();
+    const schema = makeSchema();
+    const aid    = AnchorFrameCache.computeAnchorId(schema);
+    cache.set(new AnchorFrame(aid, schema, 3600));
+    cache.invalidate(aid);
+    expect(cache.get(aid)).toBeUndefined();
+  });
+
+  it("size evicts expired entries", () => {
+    const cache  = new AnchorFrameCache();
+    let   now    = 0;
+    cache.clock  = () => now;
+    const s1 = makeSchema([{ name: "id", type: "uint64" }]);
+    const s2 = makeSchema([{ name: "x",  type: "string"  }]);
+    cache.set(new AnchorFrame(AnchorFrameCache.computeAnchorId(s1), s1, 100));
+    cache.set(new AnchorFrame(AnchorFrameCache.computeAnchorId(s2), s2, 1));
+    now = 2_000; // s2 expired
+    expect(cache.size).toBe(1);
+  });
+});
+
+// ── NpsFrameCodec ─────────────────────────────────────────────────────────────
+
+describe("NpsFrameCodec — NCP round-trips", () => {
+  const registry = createDefaultRegistry();
+  const codec    = new NpsFrameCodec(registry);
+  const aid      = "sha256:" + "a".repeat(64);
+  const schema   = { fields: [{ name: "id", type: "uint64" }, { name: "name", type: "string" }] };
+
+  it("encodes/decodes AnchorFrame (MsgPack)", () => {
+    const frame = new AnchorFrame(aid, schema, 3600);
+    const out   = codec.decode(codec.encode(frame)) as AnchorFrame;
+    expect(out).toBeInstanceOf(AnchorFrame);
+    expect(out.anchorId).toBe(aid);
+    expect(out.ttl).toBe(3600);
+  });
+
+  it("encodes/decodes AnchorFrame (JSON override)", () => {
+    const frame = new AnchorFrame(aid, schema, 7200);
+    const wire  = codec.encode(frame, { overrideTier: EncodingTier.JSON });
+    const out   = codec.decode(wire) as AnchorFrame;
+    expect(out.ttl).toBe(7200);
+  });
+
+  it("encodes/decodes DiffFrame", () => {
+    const frame = new DiffFrame(aid, 3, [{ op: "replace", path: "/name", value: "Bob" }], "ent:1");
+    const out   = codec.decode(codec.encode(frame)) as DiffFrame;
+    expect(out).toBeInstanceOf(DiffFrame);
+    expect(out.baseSeq).toBe(3);
+    expect(out.patch[0]?.op).toBe("replace");
+    expect(out.entityId).toBe("ent:1");
+  });
+
+  it("encodes/decodes StreamFrame — non-final clears FINAL flag", () => {
+    const frame = new StreamFrame("s-1", 0, false, [{ id: 1 }]);
+    const wire  = codec.encode(frame);
+    expect(NpsFrameCodec.peekHeader(wire).isFinal).toBe(false);
+    const out = codec.decode(wire) as StreamFrame;
+    expect(out.isLast).toBe(false);
+  });
+
+  it("encodes/decodes StreamFrame — final sets FINAL flag", () => {
+    const frame = new StreamFrame("s-1", 1, true, [{ id: 2 }], aid, 10);
+    const wire  = codec.encode(frame);
+    expect(NpsFrameCodec.peekHeader(wire).isFinal).toBe(true);
+    const out = codec.decode(wire) as StreamFrame;
+    expect(out.isLast).toBe(true);
+    expect(out.windowSize).toBe(10);
+  });
+
+  it("encodes/decodes CapsFrame", () => {
+    const frame = new CapsFrame(aid, 2, [{ id: 1 }, { id: 2 }], "cursor:X", 100, true, "cl100k");
+    const out   = codec.decode(codec.encode(frame)) as CapsFrame;
+    expect(out).toBeInstanceOf(CapsFrame);
+    expect(out.count).toBe(2);
+    expect(out.nextCursor).toBe("cursor:X");
+    expect(out.tokenizerUsed).toBe("cl100k");
+  });
+
+  it("encodes/decodes ErrorFrame", () => {
+    const frame = new ErrorFrame("NPS-SERVER-INTERNAL", "NCP-ANCHOR-NOT-FOUND", "missing anchor", { ref: aid });
+    const out   = codec.decode(codec.encode(frame)) as ErrorFrame;
+    expect(out).toBeInstanceOf(ErrorFrame);
+    expect(out.status).toBe("NPS-SERVER-INTERNAL");
+    expect(out.message).toBe("missing anchor");
+  });
+
+  it("peekHeader decodes only the header", () => {
+    const frame  = new AnchorFrame(aid, schema);
+    const wire   = codec.encode(frame);
+    const header = NpsFrameCodec.peekHeader(wire);
+    expect(header.frameType).toBe(FrameType.ANCHOR);
+  });
+
+  it("throws NpsCodecError for unsupported tier", () => {
+    // @ts-expect-error intentional bad value
+    expect(() => codec["_selectCodec"](0x02)).toThrow(NpsCodecError);
+  });
+
+  it("throws NpsCodecError when payload exceeds maxPayload", () => {
+    const tiny  = new NpsFrameCodec(registry, { maxPayload: 5 });
+    const frame = new AnchorFrame(aid, schema);
+    expect(() => tiny.encode(frame)).toThrow(NpsCodecError);
+  });
+
+  it("sets EXT flag when payload > 64 KiB", () => {
+    const large  = new NpsFrameCodec(registry, { maxPayload: 200_000 });
+    const bigData = Array.from({ length: 400 }, (_, i) => ({ id: i, name: "x".repeat(200) }));
+    const frame   = new CapsFrame(aid, bigData.length, bigData);
+    const wire    = large.encode(frame, { overrideTier: EncodingTier.JSON });
+    expect(NpsFrameCodec.peekHeader(wire).isExtended).toBe(true);
+  });
+
+  it("Tier-1 JSON encode error wraps as NpsCodecError", () => {
+    const j = new Tier1JsonCodec();
+    const bad = { frameType: FrameType.ANCHOR, preferredTier: EncodingTier.JSON, toDict: () => ({ v: BigInt(1) }) };
+    // @ts-expect-error intentional bad frame
+    expect(() => j.encode(bad)).toThrow(NpsCodecError);
+  });
+
+  it("Tier-1 JSON decode error wraps as NpsCodecError", () => {
+    const j = new Tier1JsonCodec();
+    expect(() => j.decode(FrameType.ANCHOR, new Uint8Array([0xff, 0xfe]), registry)).toThrow(NpsCodecError);
+  });
+
+  it("Tier-2 MsgPack decode error wraps as NpsCodecError", () => {
+    const m = new Tier2MsgPackCodec();
+    // \xc1 is always-invalid in MsgPack
+    expect(() => m.decode(FrameType.ANCHOR, new Uint8Array([0xc1, 0xff, 0x00]), registry)).toThrow(NpsCodecError);
+  });
+
+  it("throws NpsFrameError for unknown frame type", () => {
+    const wire = new Uint8Array([0x99, FrameFlags.FINAL | FrameFlags.TIER1_JSON, 0x00, 0x02, 0x7b, 0x7d]);
+    expect(() => codec.decode(wire)).toThrow();
+  });
+});

package/tests/ncp/diff-binary-bitset.test.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — NCP-D-05 through D-10: DiffFrame patch_format
+// Source: test/ncp_test_cases.md §3.2
+
+import { describe, it, expect } from "vitest";
+import { NcpError, EncodingTier } from "../../src/core/frame-header.js";
+import {
+  validateDiffFrame,
+  type DiffFrame,
+} from "../../src/ncp/frames/diff-frame.js";
+
+function makeJsonPatchFrame(overrides?: Partial<DiffFrame>): DiffFrame {
+  return {
+    frame: "0x02",
+    anchor_ref: "sha256:abc123",
+    base_seq: 0,
+    patch: [{ op: "replace", path: "/name", value: "updated" }],
+    ...overrides,
+  };
+}
+
+describe("NCP-D: DiffFrame patch_format", () => {
+  // -----------------------------------------------------------------------
+  // NCP-D-05: Default patch_format (json_patch)
+  // patch_format omitted on Tier-1 JSON frame → treat as json_patch → Success
+  // -----------------------------------------------------------------------
+  it("NCP-D-05: omitted patch_format on Tier-1 passes validation", () => {
+    const frame = makeJsonPatchFrame();
+    expect(frame.patch_format).toBeUndefined();
+    expect(() => validateDiffFrame(frame, EncodingTier.Json)).not.toThrow();
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-D-06: Explicit patch_format=json_patch
+  // json_patch on Tier-1 or Tier-2 → Success
+  // -----------------------------------------------------------------------
+  it("NCP-D-06: explicit patch_format=json_patch on Tier-1 passes", () => {
+    const frame = makeJsonPatchFrame({ patch_format: "json_patch" });
+    expect(() => validateDiffFrame(frame, EncodingTier.Json)).not.toThrow();
+  });
+
+  it("NCP-D-06: explicit patch_format=json_patch on Tier-2 passes", () => {
+    const frame = makeJsonPatchFrame({ patch_format: "json_patch" });
+    expect(() => validateDiffFrame(frame, EncodingTier.MsgPack)).not.toThrow();
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-D-07: binary_bitset on Tier-2 (supported)
+  // patch_format=binary_bitset on Tier-2 MsgPack → Success
+  // -----------------------------------------------------------------------
+  it("NCP-D-07: binary_bitset on Tier-2 MsgPack passes", () => {
+    const frame: DiffFrame = {
+      ...makeJsonPatchFrame(),
+      patch_format: "binary_bitset",
+      patch: new Uint8Array([0b00000011, 0x01, 0x05]), // bitset + packed values
+    };
+    expect(() => validateDiffFrame(frame, EncodingTier.MsgPack)).not.toThrow();
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-D-08: binary_bitset on Tier-1 (protocol forbids)
+  // Expected: NCP-DIFF-FORMAT-UNSUPPORTED
+  // -----------------------------------------------------------------------
+  it("NCP-D-08: binary_bitset on Tier-1 JSON throws NCP-DIFF-FORMAT-UNSUPPORTED", () => {
+    const frame = makeJsonPatchFrame({ patch_format: "binary_bitset" });
+    expect(() => validateDiffFrame(frame, EncodingTier.Json)).toThrow(NcpError);
+    try {
+      validateDiffFrame(frame, EncodingTier.Json);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-DIFF-FORMAT-UNSUPPORTED");
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-D-09: binary_bitset when receiver opted out
+  // Simulated as Tier-1 (non-Tier-2) → NCP-DIFF-FORMAT-UNSUPPORTED
+  // -----------------------------------------------------------------------
+  it("NCP-D-09: binary_bitset when receiver opted out (non-Tier-2) throws NCP-DIFF-FORMAT-UNSUPPORTED", () => {
+    const frame = makeJsonPatchFrame({ patch_format: "binary_bitset" });
+    // Receiver did not advertise binary_bitset support — simulated as JSON tier
+    expect(() => validateDiffFrame(frame, EncodingTier.Json)).toThrow(NcpError);
+    try {
+      validateDiffFrame(frame, EncodingTier.Json);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-DIFF-FORMAT-UNSUPPORTED");
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-D-10: Unknown patch_format
+  // patch_format="some_future_format" → NCP-DIFF-FORMAT-UNSUPPORTED
+  // -----------------------------------------------------------------------
+  it("NCP-D-10: unknown patch_format throws NCP-DIFF-FORMAT-UNSUPPORTED", () => {
+    // Cast to bypass TypeScript type check for runtime test
+    const frame = makeJsonPatchFrame({
+      patch_format: "some_future_format" as unknown as "json_patch",
+    });
+    expect(() => validateDiffFrame(frame, EncodingTier.Json)).toThrow(NcpError);
+    try {
+      validateDiffFrame(frame, EncodingTier.Json);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-DIFF-FORMAT-UNSUPPORTED");
+    }
+  });
+});

package/tests/ncp/e2e-enc-reject.test.ts

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — NCP-E2E-01, E2E-02, E2E-03: E2E Encryption (Option A — reject ENC=1)
+// Source: test/ncp_test_cases.md §8
+//
+// Option A conformance: TypeScript implementation rejects frames with ENC=1.
+// Full AES-256-GCM / ChaCha20-Poly1305 is deferred to a future Option B iteration.
+
+import { describe, it, expect } from "vitest";
+import { NcpError, buildFlags, EncodingTier, parseFrameHeader } from "../../src/core/frame-header.js";
+
+/**
+ * Check if a frame's ENC flag is set and throw NCP-ENC-NOT-NEGOTIATED
+ * if the session has no negotiated e2e_enc_algorithms.
+ */
+function checkEncFlag(
+  flags: number,
+  sessionEncAlgorithms: string[],
+): void {
+  const ENC_BIT = 0x08;
+  if ((flags & ENC_BIT) !== 0 && sessionEncAlgorithms.length === 0) {
+    throw new NcpError(
+      "NCP-ENC-NOT-NEGOTIATED",
+      "Frame has ENC=1 but no e2e_enc_algorithms were negotiated",
+    );
+  }
+}
+
+describe("NCP-E2E: E2E Encryption Option A (reject ENC=1)", () => {
+  // -----------------------------------------------------------------------
+  // NCP-E2E-01: ENC=0 Default
+  // Frame with ENC=0 after handshake without e2e_enc_algorithms → Success
+  // -----------------------------------------------------------------------
+  it("NCP-E2E-01: ENC=0 frame with no negotiated algorithms is accepted", () => {
+    const flags = buildFlags({ tier: EncodingTier.Json, encrypted: false });
+    expect(() => checkEncFlag(flags, [])).not.toThrow();
+  });
+
+  it("NCP-E2E-01: ENC=0 flag is clear in default flags", () => {
+    const flags = buildFlags({ tier: EncodingTier.Json });
+    const ENC_BIT = 0x08;
+    expect(flags & ENC_BIT).toBe(0);
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-E2E-02: ENC=1 Without Negotiation
+  // Any frame with ENC=1 when session's e2e_enc_algorithms is empty
+  // → NCP-ENC-NOT-NEGOTIATED (frame dropped; no decryption attempted)
+  // -----------------------------------------------------------------------
+  it("NCP-E2E-02: ENC=1 frame without negotiated algorithms throws NCP-ENC-NOT-NEGOTIATED", () => {
+    const flags = buildFlags({ tier: EncodingTier.Json, encrypted: true });
+    expect(() => checkEncFlag(flags, [])).toThrow(NcpError);
+    try {
+      checkEncFlag(flags, []);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-ENC-NOT-NEGOTIATED");
+    }
+  });
+
+  it("NCP-E2E-02: ENC=1 flag is set when encrypted=true", () => {
+    const flags = buildFlags({ tier: EncodingTier.Json, encrypted: true });
+    const ENC_BIT = 0x08;
+    expect(flags & ENC_BIT).not.toBe(0);
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-E2E-03: HelloFrame Omitted e2e_enc_algorithms; later frame has ENC=1
+  // → NCP-ENC-NOT-NEGOTIATED
+  // -----------------------------------------------------------------------
+  it("NCP-E2E-03: HelloFrame without e2e_enc_algorithms → later ENC=1 frame rejected", () => {
+    // Session built from HelloFrame that omitted e2e_enc_algorithms
+    const sessionAlgorithms: string[] = []; // as set by session from HelloFrame
+
+    const flags = buildFlags({ tier: EncodingTier.Json, encrypted: true });
+    expect(() => checkEncFlag(flags, sessionAlgorithms)).toThrow(NcpError);
+    try {
+      checkEncFlag(flags, sessionAlgorithms);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-ENC-NOT-NEGOTIATED");
+    }
+  });
+
+  it("NCP-E2E-03: parseFrameHeader correctly exposes isEncrypted flag", () => {
+    const buf = new Uint8Array(4);
+    buf[0] = 0x06; // HelloFrame type
+    buf[1] = buildFlags({ tier: EncodingTier.Json, encrypted: true });
+    buf[2] = 0x00; // payload length high byte
+    buf[3] = 0x00; // payload length low byte
+    const header = parseFrameHeader(buf);
+    expect(header.isEncrypted).toBe(true);
+  });
+});

package/tests/ncp/err-error-frame.test.ts

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — NCP-ERR-01, NCP-ERR-02, NCP-ERR-03: ErrorFrame (0xFE)
+// Source: test/ncp_test_cases.md §3.5, §3.6
+
+import { describe, it, expect } from "vitest";
+import { isErrorFrame, type ErrorFrame } from "../../src/ncp/frames/error-frame.js";
+import { NCP_ERROR_CODES } from "../../src/ncp/ncp-error-codes.js";
+
+describe("NCP-ERR: ErrorFrame (0xFE)", () => {
+  // -----------------------------------------------------------------------
+  // NCP-ERR-01: Standard Error
+  // Spec: §4.7 — ErrorFrame carries NPS status + protocol error + message
+  // -----------------------------------------------------------------------
+  it("NCP-ERR-01: parses standard error with status, error, and message", () => {
+    const raw: ErrorFrame = {
+      frame: "0xFE",
+      status: "NPS-CLIENT-NOT-FOUND",
+      error: "NCP-ANCHOR-NOT-FOUND",
+      message: "Schema anchor not found in cache, please resend AnchorFrame",
+    };
+
+    expect(isErrorFrame(raw)).toBe(true);
+    expect(raw.status).toBe("NPS-CLIENT-NOT-FOUND");
+    expect(raw.error).toBe("NCP-ANCHOR-NOT-FOUND");
+    expect(raw.message).toContain("Schema anchor not found");
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-ERR-02: Nested Details
+  // Spec: §4.7 — details object contains structured data
+  // -----------------------------------------------------------------------
+  it("NCP-ERR-02: parses error with nested details object", () => {
+    const raw: ErrorFrame = {
+      frame: "0xFE",
+      status: "NPS-CLIENT-NOT-FOUND",
+      error: "NCP-ANCHOR-NOT-FOUND",
+      message: "Schema not found",
+      details: {
+        anchor_ref: "sha256:a3f9b2c1d4e5f6789012345678901234567890abcdef1234567890abcdef12",
+        retry_after_ms: 5000,
+      },
+    };
+
+    expect(isErrorFrame(raw)).toBe(true);
+    expect(raw.details).toBeDefined();
+    expect(raw.details!.anchor_ref).toBe(
+      "sha256:a3f9b2c1d4e5f6789012345678901234567890abcdef1234567890abcdef12",
+    );
+    expect(raw.details!.retry_after_ms).toBe(5000);
+  });
+
+  it("NCP-ERR-02: handles version incompatible error with server details", () => {
+    const raw: ErrorFrame = {
+      frame: "0xFE",
+      status: "NPS-PROTO-VERSION-INCOMPATIBLE",
+      error: "NCP-VERSION-INCOMPATIBLE",
+      message: "No compatible NPS version",
+      details: {
+        server_version: "0.4",
+        client_min_version: "0.5",
+      },
+    };
+
+    expect(isErrorFrame(raw)).toBe(true);
+    expect(raw.details!.server_version).toBe("0.4");
+    expect(raw.details!.client_min_version).toBe("0.5");
+  });
+
+  // -----------------------------------------------------------------------
+  // Type guard edge cases
+  // -----------------------------------------------------------------------
+  it("type guard rejects non-error objects", () => {
+    expect(isErrorFrame(null)).toBe(false);
+    expect(isErrorFrame({})).toBe(false);
+    expect(isErrorFrame({ frame: "0x01" })).toBe(false);
+    expect(isErrorFrame({ frame: "0xFE" })).toBe(false); // missing status + error
+    expect(isErrorFrame({ frame: "0xFE", status: "NPS-CLIENT-NOT-FOUND" })).toBe(false);
+  });
+
+  it("type guard accepts minimal valid error", () => {
+    expect(
+      isErrorFrame({
+        frame: "0xFE",
+        status: "NPS-CLIENT-BAD-FRAME",
+        error: "NCP-FRAME-UNKNOWN-TYPE",
+      }),
+    ).toBe(true);
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-ERR-03: v0.4 Error Code Roundtrip
+  // Spec: §3.6 — ErrorFrame carrying each of the 6 new v0.4 codes decodes cleanly
+  // New codes: NCP-ANCHOR-STALE, NCP-DIFF-FORMAT-UNSUPPORTED, NCP-VERSION-INCOMPATIBLE,
+  //            NCP-STREAM-WINDOW-OVERFLOW, NCP-ENC-NOT-NEGOTIATED, NCP-ENC-AUTH-FAILED
+  // -----------------------------------------------------------------------
+  describe("NCP-ERR-03: v0.4 error code roundtrip", () => {
+    const v04Codes: Array<{ code: string; status: string; description: string }> = [
+      {
+        code: NCP_ERROR_CODES.NCP_ANCHOR_STALE,
+        status: "NPS-CLIENT-CONFLICT",
+        description: "Anchor is stale; server has a newer version",
+      },
+      {
+        code: NCP_ERROR_CODES.NCP_DIFF_FORMAT_UNSUPPORTED,
+        status: "NPS-CLIENT-BAD-FRAME",
+        description: "patch_format=binary_bitset not supported on this tier",
+      },
+      {
+        code: NCP_ERROR_CODES.NCP_VERSION_INCOMPATIBLE,
+        status: "NPS-PROTO-VERSION-INCOMPATIBLE",
+        description: "No compatible NPS version between client and server",
+      },
+      {
+        code: NCP_ERROR_CODES.NCP_STREAM_WINDOW_OVERFLOW,
+        status: "NPS-STREAM-LIMIT",
+        description: "Sender exceeded flow-control window",
+      },
+      {
+        code: NCP_ERROR_CODES.NCP_ENC_NOT_NEGOTIATED,
+        status: "NPS-CLIENT-BAD-FRAME",
+        description: "ENC=1 set but no encryption algorithms were negotiated",
+      },
+      {
+        code: NCP_ERROR_CODES.NCP_ENC_AUTH_FAILED,
+        status: "NPS-CLIENT-BAD-FRAME",
+        description: "E2E encryption auth-tag verification failed",
+      },
+    ];
+
+    for (const { code, status, description } of v04Codes) {
+      it(`roundtrips ErrorFrame with error="${code}"`, () => {
+        const raw: ErrorFrame = {
+          frame: "0xFE",
+          status,
+          error: code,
+          message: description,
+        };
+
+        // Encodes cleanly (type guard accepts)
+        expect(isErrorFrame(raw)).toBe(true);
+
+        // Decodes cleanly (fields preserved)
+        expect(raw.frame).toBe("0xFE");
+        expect(raw.status).toBe(status);
+        expect(raw.error).toBe(code);
+        expect(raw.message).toBe(description);
+      });
+    }
+  });
+});