@labacacia/nps-sdk 1.0.0-alpha.1

package/dist/core/anchor-cache.js

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// AnchorCache — Schema cache with TTL, LRU eviction, poison detection
+// NPS-1 §5.3, §7.2, §9
+import { NcpError } from "./frame-header.js";
+/**
+ * AnchorFrame cache with:
+ * - TTL-based expiry (NPS-1 §5.3)
+ * - LRU eviction at maxSize (NPS-1 §9, default 1000)
+ * - Anchor poisoning detection (NPS-1 §7.2)
+ */
+export class AnchorCache {
+    cache = new Map();
+    maxSize;
+    getNow;
+    constructor(options) {
+        this.maxSize = options?.maxSize ?? 1000;
+        this.getNow = options?.getNow ?? (() => Date.now());
+    }
+    /**
+     * Cache an AnchorFrame.
+     *
+     * - ttl=0: frame is valid but not cached (NPS-1 §4.1)
+     * - Same anchor_id + same schema: idempotent (no-op)
+     * - Same anchor_id + different schema: NCP-ANCHOR-ID-MISMATCH (poison detection)
+     *
+     * @throws {NcpError} NCP-ANCHOR-ID-MISMATCH on anchor poisoning.
+     */
+    set(frame) {
+        // ttl=0 means use once, don't cache
+        if (frame.ttl === 0)
+            return;
+        const existing = this.cache.get(frame.anchor_id);
+        if (existing) {
+            // Poison detection: same ID, different schema
+            const existingJson = JSON.stringify(existing.frame.schema);
+            const newJson = JSON.stringify(frame.schema);
+            if (existingJson !== newJson) {
+                throw new NcpError("NCP-ANCHOR-ID-MISMATCH", `Anchor poisoning detected: anchor_id ${frame.anchor_id} received with different schema`);
+            }
+            // Same schema — idempotent, update access time
+            existing.lastAccessed = this.getNow();
+            return;
+        }
+        // LRU eviction if at capacity
+        if (this.cache.size >= this.maxSize) {
+            this.evictLru();
+        }
+        const ttlMs = (frame.ttl ?? 3600) * 1000;
+        this.cache.set(frame.anchor_id, {
+            frame,
+            expiresAt: this.getNow() + ttlMs,
+            lastAccessed: this.getNow(),
+        });
+    }
+    /**
+     * Get a cached AnchorFrame by anchor_id.
+     *
+     * @returns The cached frame, or null if not found or expired.
+     */
+    get(anchorId) {
+        const entry = this.cache.get(anchorId);
+        if (!entry)
+            return null;
+        // Check TTL expiry
+        if (this.getNow() >= entry.expiresAt) {
+            this.cache.delete(anchorId);
+            return null;
+        }
+        entry.lastAccessed = this.getNow();
+        return entry.frame;
+    }
+    /**
+     * Get a cached AnchorFrame, throwing if not found.
+     * @throws {NcpError} NCP-ANCHOR-NOT-FOUND if not in cache or expired.
+     */
+    getRequired(anchorId) {
+        const frame = this.get(anchorId);
+        if (!frame) {
+            throw new NcpError("NCP-ANCHOR-NOT-FOUND", `Schema anchor ${anchorId} not found in cache`);
+        }
+        return frame;
+    }
+    /** Current cache size. */
+    get size() {
+        return this.cache.size;
+    }
+    /** Evict the least recently accessed entry. */
+    evictLru() {
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache) {
+            if (entry.lastAccessed < oldestTime) {
+                oldestTime = entry.lastAccessed;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+        }
+    }
+}
+//# sourceMappingURL=anchor-cache.js.map

package/dist/core/anchor-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor-cache.js","sourceRoot":"","sources":["../../src/core/anchor-cache.ts"],"names":[],"mappings":"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"}

package/dist/core/cache.d.ts

@@ -0,0 +1,14 @@
+import type { AnchorFrame, FrameSchema } from "../ncp/frames.js";
+export declare class AnchorFrameCache {
+    private readonly _store;
+    clock: () => number;
+    set(frame: AnchorFrame): string;
+    get(anchorId: string): AnchorFrame | undefined;
+    getRequired(anchorId: string): AnchorFrame;
+    invalidate(anchorId: string): void;
+    get size(): number;
+    static computeAnchorId(schema: FrameSchema): string;
+    private _evictExpired;
+    private static _schemasEqual;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/core/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/core/cache.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEjE,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgE;IAGvF,KAAK,EAAE,MAAM,MAAM,CAAoB;IAIvC,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM;IAmB/B,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAU9C,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW;IAM1C,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIlC,IAAI,IAAI,IAAI,MAAM,CAGjB;IAID,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM;IAiBnD,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,MAAM,CAAC,aAAa;CAG7B"}

package/dist/core/cache.js

@@ -0,0 +1,80 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * AnchorFrameCache — in-process cache for AnchorFrame instances (NPS-1 §4.1).
+ */
+import { createHash } from "node:crypto";
+import { NpsAnchorNotFoundError, NpsAnchorPoisonError } from "./exceptions.js";
+export class AnchorFrameCache {
+    _store = new Map();
+    // Allow clock injection for testing
+    clock = () => Date.now();
+    // ── Public API ────────────────────────────────────────────────────────────
+    set(frame) {
+        const anchorId = frame.anchorId.startsWith("sha256:")
+            ? frame.anchorId
+            : AnchorFrameCache.computeAnchorId(frame.schema);
+        const existing = this._store.get(anchorId);
+        if (existing !== undefined && this.clock() < existing.expiresAt) {
+            if (!AnchorFrameCache._schemasEqual(existing.frame.schema, frame.schema)) {
+                throw new NpsAnchorPoisonError(anchorId);
+            }
+            // Same schema — idempotent; refresh TTL below
+        }
+        const ttlMs = (frame.ttl ?? 3600) * 1000;
+        const expiresAt = this.clock() + ttlMs;
+        this._store.set(anchorId, { frame, expiresAt });
+        return anchorId;
+    }
+    get(anchorId) {
+        const entry = this._store.get(anchorId);
+        if (entry === undefined)
+            return undefined;
+        if (this.clock() > entry.expiresAt) {
+            this._store.delete(anchorId);
+            return undefined;
+        }
+        return entry.frame;
+    }
+    getRequired(anchorId) {
+        const frame = this.get(anchorId);
+        if (frame === undefined)
+            throw new NpsAnchorNotFoundError(anchorId);
+        return frame;
+    }
+    invalidate(anchorId) {
+        this._store.delete(anchorId);
+    }
+    get size() {
+        this._evictExpired();
+        return this._store.size;
+    }
+    // ── Static helpers ────────────────────────────────────────────────────────
+    static computeAnchorId(schema) {
+        const sorted = [...schema.fields]
+            .map((f) => {
+            const obj = { name: f.name, type: f.type };
+            if (f.semantic !== undefined)
+                obj["semantic"] = f.semantic;
+            if (f.nullable !== undefined)
+                obj["nullable"] = f.nullable;
+            return obj;
+        })
+            .sort((a, b) => String(a["name"]).localeCompare(String(b["name"])));
+        const canonical = JSON.stringify(sorted);
+        const digest = createHash("sha256").update(canonical, "utf8").digest("hex");
+        return `sha256:${digest}`;
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    _evictExpired() {
+        const now = this.clock();
+        for (const [k, entry] of this._store) {
+            if (now > entry.expiresAt)
+                this._store.delete(k);
+        }
+    }
+    static _schemasEqual(a, b) {
+        return AnchorFrameCache.computeAnchorId(a) === AnchorFrameCache.computeAnchorId(b);
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/core/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/core/cache.ts"],"names":[],"mappings":"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"}

package/dist/core/canonical-json.d.ts

@@ -0,0 +1,12 @@
+/**
+ * JCS (RFC 8785) canonical JSON stringify.
+ * Used for AnchorFrame anchor_id computation.
+ */
+export declare function jcsStringify(obj: unknown): string;
+/**
+ * Sorted-key JSON stringify — matches Python's
+ * `json.dumps(obj, sort_keys=True, separators=(",",":"))`.
+ * Used for NIP signing.
+ */
+export declare function sortKeysStringify(obj: unknown): string;
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/core/canonical-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../../src/core/canonical-json.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAMjD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEtD"}

package/dist/core/canonical-json.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// Canonical JSON helpers — two distinct serialisation paths used in NPS.
+//
+// AnchorFrame uses JCS (RFC 8785) for anchor_id hashing → jcsStringify.
+// NIP signing uses Python-compatible sorted-key JSON → sortKeysStringify.
+import canonicalizeImport from "canonicalize";
+// `canonicalize` is a CJS module whose default export resolves to a namespace
+// under NodeNext. Cast once to the call signature its .d.ts promises.
+const canonicalize = canonicalizeImport;
+/**
+ * JCS (RFC 8785) canonical JSON stringify.
+ * Used for AnchorFrame anchor_id computation.
+ */
+export function jcsStringify(obj) {
+    const result = canonicalize(obj);
+    if (result === undefined) {
+        throw new Error("canonicalize returned undefined for input");
+    }
+    return result;
+}
+/**
+ * Sorted-key JSON stringify — matches Python's
+ * `json.dumps(obj, sort_keys=True, separators=(",",":"))`.
+ * Used for NIP signing.
+ */
+export function sortKeysStringify(obj) {
+    return JSON.stringify(sortKeys(obj));
+}
+function sortKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    if (value !== null && typeof value === "object") {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortKeys(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+//# sourceMappingURL=canonical-json.js.map

package/dist/core/canonical-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.js","sourceRoot":"","sources":["../../src/core/canonical-json.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,wEAAwE;AACxE,0EAA0E;AAE1E,OAAO,kBAAkB,MAAM,cAAc,CAAC;AAE9C,8EAA8E;AAC9E,sEAAsE;AACtE,MAAM,YAAY,GAAG,kBAEE,CAAC;AAExB;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACtD,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/codec.d.ts

@@ -0,0 +1,32 @@
+import { EncodingTier, FrameHeader, FrameType } from "./frames.js";
+import type { FrameRegistry } from "./registry.js";
+export interface NpsFrame {
+    readonly frameType: FrameType;
+    readonly preferredTier: EncodingTier;
+    toDict(): Record<string, unknown>;
+}
+export declare class Tier1JsonCodec {
+    encode(frame: NpsFrame): Uint8Array;
+    decode(frameType: FrameType, payload: Uint8Array, registry: FrameRegistry): NpsFrame;
+}
+export declare class Tier2MsgPackCodec {
+    encode(frame: NpsFrame): Uint8Array;
+    decode(frameType: FrameType, payload: Uint8Array, registry: FrameRegistry): NpsFrame;
+}
+export declare class NpsFrameCodec {
+    private readonly _registry;
+    private readonly _maxPayload;
+    private readonly _json;
+    private readonly _msgpack;
+    constructor(registry: FrameRegistry, options?: {
+        maxPayload?: number;
+    });
+    encode(frame: NpsFrame, options?: {
+        overrideTier?: EncodingTier;
+    }): Uint8Array;
+    decode(wire: Uint8Array): NpsFrame;
+    static peekHeader(wire: Uint8Array): FrameHeader;
+    private _buildFlags;
+    private _selectCodec;
+}
+//# sourceMappingURL=codec.d.ts.map

package/dist/core/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/core/codec.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,YAAY,EAEZ,WAAW,EACX,SAAS,EACV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAC;IACrC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAID,qBAAa,cAAc;IACzB,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU;IAWnC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,GAAG,QAAQ;CAYrF;AAID,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU;IAUnC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,GAAG,QAAQ;CAWrF;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;gBAExC,QAAQ,EAAE,aAAa,EAAE,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;IAO1E,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,YAAY,CAAA;KAAO,GAAG,UAAU;IAiClF,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ;IAOlC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW;IAMhD,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,YAAY;CAKrB"}

package/dist/core/codec.js

@@ -0,0 +1,119 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * NPS frame codec: Tier-1 (JSON) and Tier-2 (MsgPack) encode/decode,
+ * plus the top-level NpsFrameCodec dispatcher.
+ */
+import * as msgpack from "@msgpack/msgpack";
+import { NpsCodecError } from "./exceptions.js";
+import { DEFAULT_MAX_PAYLOAD, EncodingTier, FrameFlags, FrameHeader, } from "./frames.js";
+// ── Tier-1 JSON codec ─────────────────────────────────────────────────────────
+export class Tier1JsonCodec {
+    encode(frame) {
+        try {
+            const json = JSON.stringify(frame.toDict());
+            return new TextEncoder().encode(json);
+        }
+        catch (err) {
+            throw new NpsCodecError(`Tier-1 JSON encode failed for 0x${frame.frameType.toString(16).padStart(2, "0")}: ${String(err)}`);
+        }
+    }
+    decode(frameType, payload, registry) {
+        const cls = registry.resolve(frameType);
+        try {
+            const text = new TextDecoder().decode(payload);
+            const data = JSON.parse(text);
+            return cls.fromDict(data);
+        }
+        catch (err) {
+            throw new NpsCodecError(`Tier-1 JSON decode failed for 0x${frameType.toString(16).padStart(2, "0")}: ${String(err)}`);
+        }
+    }
+}
+// ── Tier-2 MsgPack codec ──────────────────────────────────────────────────────
+export class Tier2MsgPackCodec {
+    encode(frame) {
+        try {
+            return msgpack.encode(frame.toDict());
+        }
+        catch (err) {
+            throw new NpsCodecError(`Tier-2 MsgPack encode failed for 0x${frame.frameType.toString(16).padStart(2, "0")}: ${String(err)}`);
+        }
+    }
+    decode(frameType, payload, registry) {
+        const cls = registry.resolve(frameType);
+        try {
+            const data = msgpack.decode(payload);
+            return cls.fromDict(data);
+        }
+        catch (err) {
+            throw new NpsCodecError(`Tier-2 MsgPack decode failed for 0x${frameType.toString(16).padStart(2, "0")}: ${String(err)}`);
+        }
+    }
+}
+// ── NpsFrameCodec (dispatcher) ────────────────────────────────────────────────
+export class NpsFrameCodec {
+    _registry;
+    _maxPayload;
+    _json = new Tier1JsonCodec();
+    _msgpack = new Tier2MsgPackCodec();
+    constructor(registry, options = {}) {
+        this._registry = registry;
+        this._maxPayload = options.maxPayload ?? DEFAULT_MAX_PAYLOAD;
+    }
+    // ── Encode ────────────────────────────────────────────────────────────────
+    encode(frame, options = {}) {
+        const tier = options.overrideTier ?? frame.preferredTier;
+        const tierCodec = this._selectCodec(tier);
+        let payload;
+        try {
+            payload = tierCodec.encode(frame);
+        }
+        catch (err) {
+            if (err instanceof NpsCodecError)
+                throw err;
+            throw new NpsCodecError(`Encode failed for 0x${frame.frameType.toString(16)}.`);
+        }
+        if (payload.length > this._maxPayload) {
+            throw new NpsCodecError(`Encoded payload for 0x${frame.frameType.toString(16).padStart(2, "0")} exceeds max_frame_payload` +
+                ` (${payload.length} bytes > ${this._maxPayload}). Use StreamFrame (0x03) for large payloads.`);
+        }
+        const useExt = payload.length > DEFAULT_MAX_PAYLOAD;
+        let flags = this._buildFlags(frame, tier);
+        if (useExt)
+            flags |= FrameFlags.EXT;
+        const header = new FrameHeader(frame.frameType, flags, payload.length);
+        const headerBytes = header.toBytes();
+        const wire = new Uint8Array(headerBytes.length + payload.length);
+        wire.set(headerBytes, 0);
+        wire.set(payload, headerBytes.length);
+        return wire;
+    }
+    // ── Decode ────────────────────────────────────────────────────────────────
+    decode(wire) {
+        const header = FrameHeader.parse(wire);
+        const payload = wire.slice(header.headerSize, header.headerSize + header.payloadLength);
+        const codec = this._selectCodec(header.encodingTier);
+        return codec.decode(header.frameType, payload, this._registry);
+    }
+    static peekHeader(wire) {
+        return FrameHeader.parse(wire);
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    _buildFlags(frame, tier) {
+        let flags = tier === EncodingTier.JSON ? FrameFlags.TIER1_JSON : FrameFlags.TIER2_MSGPACK;
+        const isStreamFrame = "isLast" in frame;
+        const isFinal = !isStreamFrame || frame.isLast;
+        if (isFinal)
+            flags |= FrameFlags.FINAL;
+        return flags;
+    }
+    _selectCodec(tier) {
+        if (tier === EncodingTier.JSON)
+            return this._json;
+        if (tier === EncodingTier.MSGPACK)
+            return this._msgpack;
+        throw new NpsCodecError(`Unsupported encoding tier: 0x${tier.toString(16).padStart(2, "0")}.`);
+    }
+}
+//# sourceMappingURL=codec.js.map

package/dist/core/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/core/codec.ts"],"names":[],"mappings":"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"}

package/dist/core/codecs/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./ncp-codec.js";
+export { encodeJson, decodeJson } from "./tier1-json-codec.js";
+export { encodeMsgPack, decodeMsgPack } from "./tier2-msgpack-codec.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/codecs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/codecs/index.ts"],"names":[],"mappings":"AAEA,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/core/codecs/index.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+export * from "./ncp-codec.js";
+export { encodeJson, decodeJson } from "./tier1-json-codec.js";
+export { encodeMsgPack, decodeMsgPack } from "./tier2-msgpack-codec.js";
+//# sourceMappingURL=index.js.map

package/dist/core/codecs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/codecs/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/core/codecs/ncp-codec.d.ts

@@ -0,0 +1,39 @@
+import { EncodingTier, type FrameHeader } from "../frame-header.js";
+export interface DecodeResult {
+    /** Parsed frame header. */
+    header: FrameHeader;
+    /** Decoded payload object. */
+    payload: unknown;
+    /** Total bytes consumed (header + payload). */
+    bytesConsumed: number;
+}
+export interface EncodeOptions {
+    /** Frame type byte. */
+    frameType: number;
+    /** Encoding tier (default: JSON). */
+    tier?: EncodingTier;
+    /** Set FINAL flag. */
+    final?: boolean;
+    /** Set ENC flag. */
+    encrypted?: boolean;
+    /** Use extended header (for payloads > 64KB). */
+    extended?: boolean;
+}
+export interface CodecOptions {
+    /** Maximum frame payload in bytes (negotiated via CapsFrame). Default: 65535. */
+    maxFramePayload?: number;
+}
+/**
+ * Decode a complete NCP frame from a buffer.
+ *
+ * @returns Decoded header + payload + bytes consumed.
+ * @throws {NcpError} NCP-ENCODING-UNSUPPORTED for reserved tiers.
+ * @throws {NcpError} NCP-FRAME-PAYLOAD-TOO-LARGE if payload exceeds max.
+ * @throws {NcpError} NCP-FRAME-INCOMPLETE if buffer doesn't have enough data.
+ */
+export declare function decodeFrame(buffer: Uint8Array, options?: CodecOptions): DecodeResult;
+/**
+ * Encode a payload into a complete NCP frame (header + payload bytes).
+ */
+export declare function encodeFrame(payload: unknown, options: EncodeOptions): Uint8Array;
+//# sourceMappingURL=ncp-codec.d.ts.map

package/dist/core/codecs/ncp-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ncp-codec.d.ts","sourceRoot":"","sources":["../../../src/core/codecs/ncp-codec.ts"],"names":[],"mappings":"AAMA,OAAO,EAIL,YAAY,EAGZ,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAQ5B,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oBAAoB;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,YAAY,GACrB,YAAY,CA8Cd;AAMD;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,GACrB,UAAU,CA+CZ"}

package/dist/core/codecs/ncp-codec.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Codec — Top-level encode/decode dispatcher
+// Routes to Tier-1 JSON or Tier-2 MsgPack based on frame header flags.
+import { parseFrameHeader, writeFrameHeader, buildFlags, EncodingTier, NcpError, DEFAULT_MAX_PAYLOAD, } from "../frame-header.js";
+import { encodeJson, decodeJson } from "./tier1-json-codec.js";
+import { encodeMsgPack, decodeMsgPack } from "./tier2-msgpack-codec.js";
+// ---------------------------------------------------------------------------
+// Decode
+// ---------------------------------------------------------------------------
+/**
+ * Decode a complete NCP frame from a buffer.
+ *
+ * @returns Decoded header + payload + bytes consumed.
+ * @throws {NcpError} NCP-ENCODING-UNSUPPORTED for reserved tiers.
+ * @throws {NcpError} NCP-FRAME-PAYLOAD-TOO-LARGE if payload exceeds max.
+ * @throws {NcpError} NCP-FRAME-INCOMPLETE if buffer doesn't have enough data.
+ */
+export function decodeFrame(buffer, options) {
+    const header = parseFrameHeader(buffer);
+    const maxPayload = options?.maxFramePayload ?? DEFAULT_MAX_PAYLOAD;
+    // NCP-F-09: Validate against negotiated max_frame_payload
+    if (header.payloadLength > maxPayload) {
+        throw new NcpError("NCP-FRAME-PAYLOAD-TOO-LARGE", `Payload ${header.payloadLength} exceeds max_frame_payload ${maxPayload}`);
+    }
+    const totalSize = header.headerSize + header.payloadLength;
+    // NCP-F-05: Buffer underrun — not enough data for payload
+    if (buffer.length < totalSize) {
+        throw new NcpError("NCP-FRAME-INCOMPLETE", `Buffer has ${buffer.length} bytes but frame needs ${totalSize}`);
+    }
+    // Extract payload bytes
+    const payloadBytes = buffer.subarray(header.headerSize, header.headerSize + header.payloadLength);
+    // Route to codec by tier
+    let payload;
+    switch (header.tier) {
+        case EncodingTier.Json:
+            payload = decodeJson(payloadBytes);
+            break;
+        case EncodingTier.MsgPack:
+            payload = decodeMsgPack(payloadBytes);
+            break;
+        default:
+            // NCP-E-05: Reserved tiers (0x02, 0x03)
+            throw new NcpError("NCP-ENCODING-UNSUPPORTED", `Unsupported encoding tier: 0x${header.tier.toString(16).padStart(2, "0")}`);
+    }
+    return { header, payload, bytesConsumed: totalSize };
+}
+// ---------------------------------------------------------------------------
+// Encode
+// ---------------------------------------------------------------------------
+/**
+ * Encode a payload into a complete NCP frame (header + payload bytes).
+ */
+export function encodeFrame(payload, options) {
+    const tier = options.tier ?? EncodingTier.Json;
+    // Encode payload
+    let payloadBytes;
+    switch (tier) {
+        case EncodingTier.Json:
+            payloadBytes = encodeJson(payload);
+            break;
+        case EncodingTier.MsgPack:
+            payloadBytes = encodeMsgPack(payload);
+            break;
+        default:
+            throw new NcpError("NCP-ENCODING-UNSUPPORTED", `Unsupported encoding tier for encode: ${tier}`);
+    }
+    // Determine if extended header is needed
+    const needsExtended = options.extended || payloadBytes.length > DEFAULT_MAX_PAYLOAD;
+    const flags = buildFlags({
+        tier,
+        final: options.final,
+        encrypted: options.encrypted,
+        extended: needsExtended,
+    });
+    const header = {
+        frameType: options.frameType,
+        flags,
+        payloadLength: payloadBytes.length,
+        tier,
+        isFinal: options.final ?? false,
+        isEncrypted: options.encrypted ?? false,
+        isExtended: needsExtended,
+        headerSize: needsExtended ? 8 : 4,
+    };
+    // Write frame
+    const frame = new Uint8Array(header.headerSize + payloadBytes.length);
+    writeFrameHeader(header, frame);
+    frame.set(payloadBytes, header.headerSize);
+    return frame;
+}
+//# sourceMappingURL=ncp-codec.js.map

package/dist/core/codecs/ncp-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ncp-codec.js","sourceRoot":"","sources":["../../../src/core/codecs/ncp-codec.ts"],"names":[],"mappings":"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"}

package/dist/core/codecs/tier1-json-codec.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encode a frame payload to Tier-1 JSON bytes.
+ */
+export declare function encodeJson(payload: unknown): Uint8Array;
+/**
+ * Decode Tier-1 JSON bytes to a parsed object.
+ * @throws {NcpError} NPS-CLIENT-BAD-FRAME on malformed JSON.
+ */
+export declare function decodeJson(bytes: Uint8Array): unknown;
+//# sourceMappingURL=tier1-json-codec.d.ts.map

package/dist/core/codecs/tier1-json-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier1-json-codec.d.ts","sourceRoot":"","sources":["../../../src/core/codecs/tier1-json-codec.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAEvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAUrD"}