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

package/doc/overview.md

@@ -0,0 +1,153 @@
+English | [中文版](./overview.cn.md)
+
+# `@labacacia/nps-sdk` — API Reference Overview
+
+[![npm](https://img.shields.io/npm/v/@labacacia/nps-sdk)](https://www.npmjs.com/package/@labacacia/nps-sdk)
+
+The NPS TypeScript SDK is a dual-format (ESM + CJS) port of the .NET reference
+implementation. This document is the entry point for the per-module API
+references — each protocol has its own file below.
+
+---
+
+## Package layout
+
+```
+@labacacia/nps-sdk
+├── /           # root: VERSION, createDefaultRegistry, createFullRegistry
+├── /core       # Wire primitives: FrameHeader, codecs, AnchorCache, errors
+├── /ncp        # NCP frames + handshake + stream manager
+├── /nwp        # NWP frames + async NwpClient
+├── /nip        # NIP frames + NipIdentity (Ed25519)
+├── /ndp        # NDP frames + InMemoryNdpRegistry + validator
+└── /nop        # NOP frames + TaskDag model + NopClient
+```
+
+## Reference documents
+
+| Subpath | Module | Reference |
+|---------|--------|-----------|
+| —                       | Root helpers & registry factories     | this file |
+| `@labacacia/nps-sdk/core` | Frame header, codec, anchor cache, exceptions | [`nps-sdk.core.md`](./nps-sdk.core.md) |
+| `@labacacia/nps-sdk/ncp`  | NCP frame set (`AnchorFrame`, `DiffFrame`, `StreamFrame`, `CapsFrame`, `ErrorFrame`, `HelloFrame`) | [`nps-sdk.ncp.md`](./nps-sdk.ncp.md) |
+| `@labacacia/nps-sdk/nwp`  | `QueryFrame`, `ActionFrame`, `NwpClient` | [`nps-sdk.nwp.md`](./nps-sdk.nwp.md) |
+| `@labacacia/nps-sdk/nip`  | `IdentFrame`, `TrustFrame`, `RevokeFrame`, `NipIdentity` | [`nps-sdk.nip.md`](./nps-sdk.nip.md) |
+| `@labacacia/nps-sdk/ndp`  | `AnnounceFrame`, `ResolveFrame`, `GraphFrame`, registry, validator | [`nps-sdk.ndp.md`](./nps-sdk.ndp.md) |
+| `@labacacia/nps-sdk/nop`  | Task DAG, `TaskFrame`, `DelegateFrame`, `SyncFrame`, `AlignStreamFrame`, `NopClient` | [`nps-sdk.nop.md`](./nps-sdk.nop.md) |
+
+---
+
+## Install
+
+```bash
+npm install @labacacia/nps-sdk
+```
+
+Requires **Node.js 18+** (for Web Crypto) or a modern browser with native
+`crypto.subtle`.
+
+---
+
+## Root module
+
+```typescript
+import { VERSION, createDefaultRegistry, createFullRegistry } from "@labacacia/nps-sdk";
+```
+
+- `VERSION` — SDK version constant.
+- `createDefaultRegistry()` — new `FrameRegistry` with NCP frames only
+  (`ANCHOR`, `DIFF`, `STREAM`, `CAPS`, `ERROR`).
+- `createFullRegistry()` — new `FrameRegistry` with all five protocols
+  (NCP + NWP + NIP + NDP + NOP) pre-registered. Use this when decoding
+  arbitrary frames.
+
+```typescript
+const registry = createFullRegistry();
+```
+
+---
+
+## Minimal end-to-end example
+
+```typescript
+import { NwpClient, QueryFrame, ActionFrame } from "@labacacia/nps-sdk/nwp";
+
+const client = new NwpClient("http://node.example.com:17433");
+
+// Paginated query
+const caps = await client.query(
+  new QueryFrame("sha256:<anchor-id>", { active: true }, 50),
+);
+console.log(caps.count, caps.data);
+
+// Streaming query
+for await (const chunk of client.stream(new QueryFrame("sha256:<anchor-id>"))) {
+  console.log(chunk.seq, chunk.data);
+  if (chunk.isLast) break;
+}
+
+// Action invocation
+const result = await client.invoke(
+  new ActionFrame("summarise", { maxTokens: 500 }),
+);
+```
+
+---
+
+## Encoding tiers
+
+Every frame has a `preferredTier`. MsgPack is the production default; JSON
+tier stays available for diagnostics.
+
+| Tier | `EncodingTier` value | Description |
+|------|---------------------|-------------|
+| Tier-1 JSON    | `0x00` | UTF-8 JSON. Development & compatibility. |
+| Tier-2 MsgPack | `0x01` | MessagePack binary. **Production default** — ~60% smaller. |
+
+```typescript
+import { EncodingTier } from "@labacacia/nps-sdk/core";
+import { NpsFrameCodec } from "@labacacia/nps-sdk/core";
+
+const codec = new NpsFrameCodec(createFullRegistry());
+const wire  = codec.encode(frame, { overrideTier: EncodingTier.JSON });
+```
+
+---
+
+## Async conventions
+
+- All network-facing clients (`NwpClient`, `NopClient`) return `Promise<T>`.
+- Streaming uses `AsyncGenerator<StreamFrame>` — consume with
+  `for await (const chunk of …) { … }`.
+- Clients do **not** require explicit dispose — the underlying `fetch`
+  owns connection lifecycle.
+
+---
+
+## Error hierarchy
+
+```
+Error
+└── NpsError                       from "@labacacia/nps-sdk/core"
+    ├── NpsFrameError              — header parse / structural error
+    ├── NpsCodecError              — encode/decode failure
+    ├── NpsAnchorNotFoundError     — anchor not in cache
+    ├── NpsAnchorPoisonError       — anchor_id / schema mismatch
+    └── NpsStreamError             — stream seq gap / unknown stream id
+```
+
+`NcpError` (from `@labacacia/nps-sdk/core`) is a separate protocol-level
+error carrying a machine-readable `code` (e.g. `NCP-ANCHOR-NOT-FOUND`,
+`NCP-STREAM-SEQ-GAP`).
+
+---
+
+## Reference specs
+
+| Module | Spec |
+|--------|------|
+| `core` + `ncp` | [NPS-1 NCP v0.4](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-1-NCP.md) |
+| `nwp`          | [NPS-2 NWP v0.4](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-2-NWP.md) |
+| `nip`          | [NPS-3 NIP v0.2](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-3-NIP.md) |
+| `ndp`          | [NPS-4 NDP v0.2](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-4-NDP.md) |
+| `nop`          | [NPS-5 NOP v0.3](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-5-NOP.md) |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@labacacia/nps-sdk",
-  "version": "1.0.0-alpha.1",
-  "description": "TypeScript SDK for the Neural Protocol Suite (NPS)",
+  "version": "1.0.0-alpha.2",
+  "description": "TypeScript SDK for the Neural Protocol Suite (NPS) — NCP, NWP, NIP, NDP, NOP",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,6 +17,22 @@
     "./ncp": {
       "import": "./dist/ncp/index.js",
       "types": "./dist/ncp/index.d.ts"
+    },
+    "./nwp": {
+      "import": "./dist/nwp/index.js",
+      "types": "./dist/nwp/index.d.ts"
+    },
+    "./nip": {
+      "import": "./dist/nip/index.js",
+      "types": "./dist/nip/index.d.ts"
+    },
+    "./ndp": {
+      "import": "./dist/ndp/index.js",
+      "types": "./dist/ndp/index.d.ts"
+    },
+    "./nop": {
+      "import": "./dist/nop/index.js",
+      "types": "./dist/nop/index.d.ts"
     }
   },
   "scripts": {
@@ -27,8 +43,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/labacacia/nps.git",
-    "directory": "impl/typescript"
+    "url": "https://github.com/labacacia/NPS-sdk-ts.git"
   },
   "license": "Apache-2.0",
   "engines": {
@@ -36,6 +51,8 @@
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.0.0",
+    "@noble/ed25519": "^2.1.0",
+    "@noble/hashes": "^1.4.0",
     "canonicalize": "^2.0.0",
     "fast-json-patch": "^3.1.1"
   },

package/src/core/frames.ts

@@ -17,6 +17,7 @@ export enum FrameType {
   STREAM       = 0x03,
   CAPS         = 0x04,
   ALIGN        = 0x05, // deprecated — use AlignStream (0x43)
+  HELLO        = 0x06,
 
   // NWP  0x10–0x1F
   QUERY        = 0x10,

package/src/core/index.ts

@@ -1,10 +1,42 @@
+// Copyright 2026 INNO LOTUS PTY LTD
 // SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-export * from "./frame-header.js";
-export * from "./frame-registry.js";
-export * from "./anchor-cache.js";
+//
+// @labacacia/nps-sdk/core — public re-exports for NCP wire primitives.
+//
+// This module exposes the shipped OOP codec API used by NWP / NOP / NIP / NDP
+// clients. The parallel functional API under ./codecs/ and ./frame-header.js
+// remains importable by direct path but is not re-exported here to avoid
+// symbol collisions (both files define FrameType / EncodingTier / FrameHeader).
+
+// ── Frame primitives (OOP) ────────────────────────────────────────────────────
+export {
+  FrameType,
+  EncodingTier,
+  FrameFlags,
+  FrameHeader,
+  DEFAULT_HEADER_SIZE,
+  EXTENDED_HEADER_SIZE,
+  DEFAULT_MAX_PAYLOAD,
+  EXTENDED_MAX_PAYLOAD,
+} from "./frames.js";
+
+// ── Codec (OOP) ───────────────────────────────────────────────────────────────
+export {
+  Tier1JsonCodec,
+  Tier2MsgPackCodec,
+  NpsFrameCodec,
+} from "./codec.js";
+export type { NpsFrame } from "./codec.js";
+
+// ── Registry (OOP) ────────────────────────────────────────────────────────────
+export { FrameRegistry } from "./registry.js";
+export type { FrameClass } from "./registry.js";
+
+// ── Anchor cache (OOP) ────────────────────────────────────────────────────────
+export { AnchorFrameCache } from "./cache.js";
+
+// ── Exceptions / Status / Canonical JSON ──────────────────────────────────────
 export * from "./exceptions.js";
 export * from "./status-codes.js";
 export { jcsStringify, sortKeysStringify } from "./canonical-json.js";
 export type { CryptoProvider } from "./crypto-provider.js";
-export * from "./codecs/index.js";

package/src/index.ts

@@ -7,4 +7,4 @@
 //   import { ... } from "@labacacia/nps-sdk/core"
 //   import { ... } from "@labacacia/nps-sdk/ncp"
 
-export const VERSION = "0.1.0";
+export const VERSION = "1.0.0-alpha.2";

package/src/ncp/frames.ts

@@ -197,3 +197,55 @@ export class ErrorFrame implements NpsFrame {
     );
   }
 }
+
+// ── HelloFrame ────────────────────────────────────────────────────────────────
+// NPS-1 §4.6 — Native-mode handshake (0x06). Always Tier-1 JSON: encoding
+// is not yet negotiated when this frame is sent.
+
+export class HelloFrame implements NpsFrame {
+  readonly frameType     = FrameType.HELLO;
+  readonly preferredTier = EncodingTier.JSON;
+
+  static readonly DEFAULT_MAX_FRAME_PAYLOAD      = 0xFFFF;
+  static readonly DEFAULT_MAX_CONCURRENT_STREAMS = 32;
+
+  constructor(
+    public readonly npsVersion:           string,
+    public readonly supportedEncodings:   readonly string[],
+    public readonly supportedProtocols:   readonly string[],
+    public          minVersion?:          string,
+    public          agentId?:             string,
+    public          maxFramePayload:      number = HelloFrame.DEFAULT_MAX_FRAME_PAYLOAD,
+    public          extSupport:           boolean = false,
+    public          maxConcurrentStreams: number = HelloFrame.DEFAULT_MAX_CONCURRENT_STREAMS,
+    public          e2eEncAlgorithms?:    readonly string[],
+  ) {}
+
+  toDict(): Record<string, unknown> {
+    return {
+      nps_version:            this.npsVersion,
+      supported_encodings:    [...this.supportedEncodings],
+      supported_protocols:    [...this.supportedProtocols],
+      min_version:            this.minVersion ?? null,
+      agent_id:               this.agentId    ?? null,
+      max_frame_payload:      this.maxFramePayload,
+      ext_support:            this.extSupport,
+      max_concurrent_streams: this.maxConcurrentStreams,
+      e2e_enc_algorithms:     this.e2eEncAlgorithms ? [...this.e2eEncAlgorithms] : null,
+    };
+  }
+
+  static fromDict(data: Record<string, unknown>): HelloFrame {
+    return new HelloFrame(
+      data["nps_version"]         as string,
+      (data["supported_encodings"] as string[]) ?? [],
+      (data["supported_protocols"] as string[]) ?? [],
+      (data["min_version"]        as string | null) ?? undefined,
+      (data["agent_id"]           as string | null) ?? undefined,
+      (data["max_frame_payload"]  as number | null) ?? HelloFrame.DEFAULT_MAX_FRAME_PAYLOAD,
+      (data["ext_support"]        as boolean | null) ?? false,
+      (data["max_concurrent_streams"] as number | null) ?? HelloFrame.DEFAULT_MAX_CONCURRENT_STREAMS,
+      (data["e2e_enc_algorithms"] as string[] | null) ?? undefined,
+    );
+  }
+}

package/src/ncp/registry.ts

@@ -3,12 +3,13 @@
 
 import { FrameRegistry } from "../core/registry.js";
 import { FrameType } from "../core/frames.js";
-import { AnchorFrame, CapsFrame, DiffFrame, ErrorFrame, StreamFrame } from "./frames.js";
+import { AnchorFrame, CapsFrame, DiffFrame, ErrorFrame, HelloFrame, StreamFrame } from "./frames.js";
 
 export function registerNcpFrames(registry: FrameRegistry): void {
   registry.register(FrameType.ANCHOR, AnchorFrame);
   registry.register(FrameType.DIFF,   DiffFrame);
   registry.register(FrameType.STREAM, StreamFrame);
   registry.register(FrameType.CAPS,   CapsFrame);
+  registry.register(FrameType.HELLO,  HelloFrame);
   registry.register(FrameType.ERROR,  ErrorFrame);
 }