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

package/CHANGELOG.cn.md

@@ -0,0 +1,181 @@
+[English Version](./CHANGELOG.md) | 中文版
+
+# 变更日志 —— TypeScript SDK (`@labacacia/nps-sdk`)
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+在 NPS 达到 v1.0 稳定版之前，套件内所有仓库同步使用同一个预发布版本号。
+
+---
+
+## [1.0.0-alpha.13] —— 2026-06-03
+
+### 新增
+
+- **NCP v0.8 — `NopFrame`（0x07）**：新增 keepalive/心跳帧类；`HelloFrame.pingIntervalMs`（默认 `0`）；新增 `NCP_KEEPALIVE_TIMEOUT` / `NCP_REKEY_REQUIRED` 错误码。
+- **NWP v0.14 — manifest 版本化**：`manifest_version` 改为 `uint32` 单调递增计数器；新增 `manifest_updated_at`（ISO 8601）；`X-NWM-Version` 响应头常量。
+- **NIP v0.10 — `node_roles`**：`IdentFrameOptions.nodeRoles` / `IdentFrame.nodeRoles`（`readonly string[] | null`）；新增 `CERT_NODE_ROLES_MISMATCH` 错误码。
+- **NDP v0.9 — spawn schema + 心跳**：`AnnounceFrame.spawn_spec_ref` 改为结构化 `Record<string,unknown>` 对象；`AnnounceFrame.heartbeat_interval_ms`（默认 `60000`）；新增 `NDP_ANNOUNCE_STALE` 错误码。
+- **NOP v0.7 — 结果 TTL**：`TaskFrame.resultTtlSeconds`（默认 `3600`）；新增 `NOP_TASK_RESULT_EXPIRED` / `NOP_STREAM_NAK_UNRESOLVABLE` 错误码。
+
+### 套件同步
+
+本版本跟进 NPS 套件 `v1.0.0-alpha.13`。NCP v0.8 / NWP v0.14 / NIP v0.10 / NDP v0.9 / NOP v0.7。
+
+---
+
+## [1.0.0-alpha.8] —— 2026-05-28
+
+### 套件同步
+
+本版本跟进 NPS 套件 `v1.0.0-alpha.8`。
+
+套件 alpha.8 亮点：.NET SDK 落地 RFC-0005 `ReputationPolicyEvaluator`；
+cgn_limit 预执行拦截；RFC-0002 与 RFC-0005 晋级为 Accepted。
+
+---
+
+## [1.0.0-alpha.7] —— 2026-05-17
+
+### 新增
+
+- **`nip/reputation-client.ts` — `ReputationLogClient`（NPS-RFC-0004 Phase 2）**：基于 fetch 的声誉日志 operator 完整客户端。`submitEntry`、`queryEntries`、`getSth`、`getProof`、`getGossipSth`。`verifyInclusion` 使用 `@noble/hashes/sha256` 在本地执行 RFC 9162 §2.1.3.2 Merkle audit-path 验证。`signEntry` / `verifyEntry` 使用 `@noble/ed25519` 签名验证条目。Wire 类型：`ReputationLogEntry`、`SignedTreeHead`、`InclusionProof`、`ObservationWindow`。`AnchorTopologyError` 携带 `nwpErrorCode` + `npsStatus`。30 条回归测试。从 `@labacacia/nps-sdk/nip` 重新导出。
+
+- **`nwp/anchor-client.ts` — `AnchorNodeClient`（NPS-CR-0002）**：基于 fetch 的 Anchor Node 拓扑查询客户端。`getSnapshot`（topology.snapshot）和 `subscribe` async generator（topology.stream NDJSON）。判别联合类型 `TopologyEvent`，包含 `member_joined`、`member_left`、`member_updated`、`anchor_state`、`resync_required` 五种 kind。`AnchorTopologyError` 处理协议错误。24 条回归测试。
+
+### 跟随套件
+
+本次跟随 NPS 套件 `v1.0.0-alpha.7`。
+
+---
+
+## [1.0.0-alpha.6] —— 2026-05-14
+
+### 变更
+
+- **`nip/x509/oids.ts` — IANA PEN 65715（Breaking，CR-0004）**：`LAB_ACACIA_PEN_ARC` 从 `"1.3.6.1.4.1.99999"` 更新为 `"1.3.6.1.4.1.65715"`。在临时弧下签发的证书必须吊销并重新签发。
+
+- **`nwp/index.ts` — 移除 `NwpErrorCodes` 重导出（Breaking）**：从桶文件中移除了 `export * as NwpErrorCodes from "./error-codes.js"`。如需使用，请直接从 `@labacacia/nps-sdk/nwp/error-codes` 导入。
+
+- **版本升级至 `1.0.0-alpha.6`** —— 与 NPS 套件 alpha.6 版本同步。
+
+---
+
+## [1.0.0-alpha.5] —— 2026-05-01
+
+### 新增
+
+- **NWP 错误码常量** —— 新增 `NwpErrorCodes` 命名空间，从 `@labacacia/nps-sdk/nwp` 导出，包含全部 30 个 NWP wire 错误码（auth、query、action、task、subscribe、infrastructure、manifest、topology、reserved-type）。此前版本均未提供。
+- **`NpsStatusCodes.NPS_SERVER_UNSUPPORTED`** —— 在 `src/core/status-codes.ts` 新增状态码 `"NPS-SERVER-UNSUPPORTED"`（HTTP 501），符合 spec/status-codes.md alpha.5 更新。
+- **`NDP.resolveWithDns` —— DNS TXT 回退解析** —— 新增 `InMemoryNdpRegistry.resolveWithDns(target, resolver?)`，当内存注册表无匹配时回退查询 `_nps-node.{host}` TXT 记录（NPS-4 §5）。新增 `DnsTxtLookup` 接口 + `SystemDnsTxtLookup`（Node.js `dns.promises`）；`parseNpsTxtRecord` + `extractHostFromTarget` 从 `@labacacia/nps-sdk/ndp` 导出。测试数：284 → 294。
+
+### 变更
+
+- **`AssuranceLevel.fromWire("")` 返回 `Anonymous`** —— `if (wire == null)` 改为 `if (!wire)`，使 `""` 返回 `Anonymous` 而非 `Unknown`（spec §5.1.1 向后兼容修复）。
+- **版本升至 `1.0.0-alpha.5`** —— 与 NPS 套件 alpha.5 同步。
+
+### 修复
+
+- **`REPUTATION_GOSSIP_FORK` / `REPUTATION_GOSSIP_SIG_INVALID`** —— 向 `src/nip/error-codes.ts` 新增两个 NIP 声誉 gossip 错误码（RFC-0004 Phase 3）。
+
+---
+
+## [1.0.0-alpha.4] —— 2026-04-30
+
+### 新增
+
+- **NPS-RFC-0001 Phase 2 —— NCP 连接前导（TypeScript helper 跟进）。**
+  `src/ncp/preamble.ts` 暴露 `writePreamble(stream)` /
+  `readPreamble(stream)`，往返字面量 `b"NPS/1.0\n"` 哨兵；
+  `tests/ncp/preamble.test.ts` 覆盖。让 TypeScript SDK 与 .NET /
+  Python / Go / Java 在 alpha.4 的 preamble helper 持平。
+- **NPS-RFC-0002 Phase A/B —— X.509 NID 证书 + ACME `agent-01`
+  （TypeScript 端口）。** 新增 `src/nip/` 子模块：
+  - `nip/x509/` —— X.509 NID 证书 builder + verifier
+    （`x509.Builder`、`x509.Verifier`）。
+  - `nip/acme/` —— ACME `agent-01` 客户端 + 服务端参考实现
+    （`AcmeServer`、`AcmeClient`）；按 NPS-RFC-0002 Phase B 的 JWS
+    签名 wire 包络。
+  - `nip/assurance-level.ts` —— Agent 身份保证等级
+    （`anonymous` / `attested` / `verified`），承接 NPS-RFC-0003。
+  - `nip/cert-format.ts` —— IdentFrame `cert_format` 判别器
+    （`v1` Ed25519 vs. `x509`）。
+  - `nip/error-codes.ts` —— NIP 错误码命名空间。
+  - `nip/verifier.ts` —— dual-trust IdentFrame 验证器（v1 + X.509）。
+- 20 个新测试覆盖 preamble 往返、X.509 签发 + 解析、dual-trust 验证、
+  ACME agent-01 全流程。总数：284 tests 全绿（alpha.3 时 264）。
+
+### 变更
+
+- 分发版本升至 `1.0.0-alpha.4`。
+- `src/nip/frames.ts` —— IdentFrame wire 形状扩展，可携带可选的
+  `cert_format` 判别器 + `x509_chain` 字段，与 v1 Ed25519 字段并存。
+  alpha.3 写出的 v1 IdentFrame 仍可被 alpha.4 验签。
+
+### npm 发布说明
+
+- 本仓库 / tag 是 `@labacacia/nps-sdk` `1.0.0-alpha.4` 的权威参考。
+  延续 alpha.3 的情况，npm publish 可能需要带 2FA-bypass 的 granular
+  access token —— 如果 npm registry 上的版本暂时落后于本仓库 tag，
+  以 tag 为准；下一次 registry cut 后 `npm install` 即可解析到本
+  commit。
+
+### 套件级 alpha.4 要点
+
+- **NPS-RFC-0002 X.509 + ACME** —— 完整跨 SDK 端口波（.NET / Java /
+  Python / TypeScript / Go / Rust）。
+- **NPS-CR-0002 —— Anchor Node topology 查询** —— `topology.snapshot`
+  / `topology.stream`（.NET 参考 + L2 conformance）。TypeScript 消费
+  侧 helper 后续版本跟进。
+- **`nps-registry` SQLite 实仓** + **`nps-ledger` Phase 2**
+  （RFC 9162 Merkle + STH + inclusion proof）已在 daemon 仓库交付。
+
+---
+
+## [1.0.0-alpha.3] —— 2026-04-25
+
+### Changed
+
+- 版本升级至 `1.0.0-alpha.3`，与 NPS `v1.0.0-alpha.3` 套件同步。本次 TypeScript SDK 无功能变更。
+- 264 tests, ≥98% 覆盖率仍全绿。
+
+### 套件级 alpha.3 要点（各语言 helper 在 alpha.4 跟进）
+
+- **NPS-RFC-0001 —— NCP 连接前导**（Accepted）。原生模式连接现以字面量 `b"NPS/1.0\n"`（8 字节）开头。.NET SDK 已落地参考实现；TypeScript helper 在 alpha.4 跟进。
+- **NPS-RFC-0003 —— Agent 身份保证等级**（Accepted）。NIP IdentFrame 与 NWM 新增三态 `assurance_level`（`anonymous`/`attested`/`verified`）。.NET 参考类型已落地；TypeScript 同步在 alpha.4。
+- **NPS-RFC-0004 —— NID 声誉日志（CT 风格）**（Accepted）。append-only Merkle 日志条目结构发布；.NET 参考签名器已落地（并以 `nps-ledger` daemon Phase 1 形态发布）。TypeScript helper 在 alpha.4 跟进。
+- **NPS-CR-0001 —— Anchor / Bridge 节点拆分。** 旧的 "Gateway Node" 角色更名为 **Anchor Node**；"NPS↔外部协议翻译" 单独成为 **Bridge Node** 类型。AnnounceFrame 新增 `node_kind` / `cluster_anchor` / `bridge_protocols`。源代码层面变更落在 `spec/` + .NET 参考实现。
+- **6 个 NPS 常驻 daemon。** NPS-Dev 新建 `daemons/` 目录，定义 `npsd` / `nps-runner` / `nps-gateway` / `nps-registry` / `nps-cloud-ca` / `nps-ledger`；其中 `npsd` 提供 L1 功能性参考实现，其余为 Phase 1 骨架。
+
+---
+
+## [1.0.0-alpha.2] —— 2026-04-19
+
+### Fixed
+
+- **`NpsFrameCodec is not a constructor`** —— `src/core/index.ts` 现显式从 `./codec.js`、`./registry.js`、`./cache.js` 重新导出随包提供的 OOP API（`NpsFrameCodec`、`Tier1JsonCodec`、`Tier2MsgPackCodec`、`FrameRegistry`、`AnchorFrameCache`）。`./codecs/` 下的并行函数式 API 仍可通过直接路径导入，但不再自动导出（与类 API 在 `FrameType` / `EncodingTier` / `FrameHeader` 上冲突）。
+- **缺失的 Ed25519 运行时依赖** —— `@noble/ed25519` 和 `@noble/hashes` 现已声明为运行时依赖。此前已被 `src/nip/identity.ts` 和 `src/ndp/validator.ts` import 但 `package.json` 未声明，导致 npm 消费者安装失败。
+
+### Added
+
+- **HelloFrame（NCP 0x06）** —— `src/ncp/frames.ts` 新增 `HelloFrame` 类（snake_case toDict/fromDict），在 `ncp/registry.ts` 中注册。`FrameType.HELLO = 0x06` 加入枚举。
+- **subpath exports** —— `package.json` 的 `exports` 映射新增 `./nwp`、`./nip`、`./ndp`、`./nop`（此前仅声明 `.`、`./core`、`./ncp`，但 README 已示例使用全部六个）。
+
+### Changed
+
+- Node 引擎要求升级到 `>=22.0.0`。
+- 264 测试全绿（此前为 158 通过 + 5 个文件失败 + 1 个测试失败）。
+
+### 涵盖模块
+
+- core / ncp / nwp / nip / ndp / nop
+
+---
+
+## [1.0.0-alpha.1] —— 2026-04-10
+
+作为 NPS 套件 `v1.0.0-alpha.1` 的一部分首次公开 alpha。
+
+[1.0.0-alpha.7]: https://github.com/labacacia/NPS-sdk-ts/releases/tag/v1.0.0-alpha.7
+[1.0.0-alpha.2]: https://github.com/LabAcacia/nps/releases/tag/v1.0.0-alpha.2
+[1.0.0-alpha.1]: https://github.com/LabAcacia/nps/releases/tag/v1.0.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,234 @@
+English | [中文版](./CHANGELOG.cn.md)
+
+# Changelog — TypeScript SDK (`@labacacia/nps-sdk`)
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Until NPS reaches v1.0 stable, every repository in the suite is synchronized to the same pre-release version tag.
+
+---
+
+## [1.0.0-alpha.13] — 2026-06-03
+
+### Added
+
+- **NCP v0.8 — `NopFrame` (0x07)**: New keepalive/heartbeat frame class; `HelloFrame.pingIntervalMs` (`number`, default `0`); `NCP_KEEPALIVE_TIMEOUT` / `NCP_REKEY_REQUIRED` error codes.
+- **NWP v0.14 — manifest versioning**: `manifest_version` changed to `uint32` monotonic counter; `manifest_updated_at` (ISO 8601); `X-NWM-Version` response header constant.
+- **NIP v0.10 — `node_roles`**: `IdentFrameOptions.nodeRoles` / `IdentFrame.nodeRoles` (`readonly string[] | null`); `CERT_NODE_ROLES_MISMATCH` error code.
+- **NDP v0.9 — spawn schema + heartbeat**: `AnnounceFrame.spawn_spec_ref` changed to structured `Record<string,unknown>` object (NdpSpawnSpecRef); `AnnounceFrame.heartbeat_interval_ms` (`number`, default `60000`); `NDP_ANNOUNCE_STALE` error code.
+- **NOP v0.7 — result TTL**: `TaskFrame.resultTtlSeconds` (`number`, default `3600`); `NOP_TASK_RESULT_EXPIRED` / `NOP_STREAM_NAK_UNRESOLVABLE` error codes.
+
+### Tracking the suite
+
+This release tracks NPS suite `v1.0.0-alpha.13`. NCP v0.8 / NWP v0.14 / NIP v0.10 / NDP v0.9 / NOP v0.7.
+
+---
+
+## [1.0.0-alpha.11] — 2026-05-31
+
+### Added
+
+- **NWP — `SubscribeFrame` CR-0006** (Breaking rewrite): Changed from class to interface; wire format updated — `subscriptionId` (UUID v4), `filter` (`Record<string,unknown>?`), `heartbeatIntervalMs` (`number?`), `maxEvents` (`number?`), `cursor` (`string?`). `subscribeFrameToNpsFrame()` / `subscribeFrameFromDict()` standalone helpers. **Wire breaking change vs alpha.8–10.**
+- **NOP — AlignStream ack/NAK**: `AlignStreamFrame` gains `ackSeq` and `nakSeq` (`number?`) for NOP v0.6 sliding-window acknowledgement.
+- **NOP — Saga compensation**: `TaskFrame.compensationPolicy`; `DelegateFrame.targetClusterAnchor`; `AggregateStrategy.WEIGHTED_FIRST_K` / `MERGE_ALL`.
+- **NDP — `GraphFrame` §5** (Breaking rewrite): `NdpGraphNode`, `NdpGraphEdge` interfaces; `GraphFrame` with `graphId`, `nodes`, `edges`, `ttl`, `metadata`. Max 256 nodes / 1024 edges.
+- **NDP — `SecurityProfile`**: `LOCAL_DEV` / `ORG_PRIVATE` / `PUBLIC_FEDERATED` const.
+- **NIP — `IdentFrame.ocspStaple`**: base64url DER OCSP response field; `IdentReputationPolicyHint` interface.
+
+### Tracking the suite
+
+This release tracks NPS suite `v1.0.0-alpha.11`. NCP v0.7 / NWP v0.13 / NIP v0.9 / NDP v0.8 / NOP v0.6.
+
+---
+
+## [1.0.0-alpha.10] — 2026-05-28
+
+### Added
+
+- **NOP — Saga compensation**: `DagNode` interface with `compensateAction` / `compensateParamsMapping`; `TaskState.COMPENSATING` / `COMPENSATED`; `CompensationPolicy` object.
+- **NDP — `SecurityProfile`**: `LOCAL_DEV` / `ORG_PRIVATE` / `PUBLIC_FEDERATED` const.
+- **NIP — `IdentReputationPolicyHint`**: Reputation policy hint interface; `IdentMetadata` interface.
+
+### Tracking the suite
+
+This release tracks NPS suite `v1.0.0-alpha.10`.
+
+---
+
+## [1.0.0-alpha.9] — 2026-05-28
+
+### Added
+
+- **NWP — `SubscribeFrame` (0x12)**: Initial `SubscribeFrame` class (pre-CR-0006 format — replaced in alpha.11).
+- **NWP — `ReputationPolicy` / `RepOutcome`**: RFC-0005 reputation types.
+
+### Tracking the suite
+
+This release tracks NPS suite `v1.0.0-alpha.9`.
+
+---
+
+## [1.0.0-alpha.8] — 2026-05-28
+
+### Tracking the suite
+
+This release tracks NPS suite `v1.0.0-alpha.8`.
+
+Suite highlights: RFC-0005 `ReputationPolicyEvaluator` in .NET SDK; cgn_limit
+pre-execution enforcement; RFC-0002 and RFC-0005 promoted to Accepted.
+
+---
+
+## [1.0.0-alpha.7] — 2026-05-17
+
+### Added
+
+- **`nip/reputation-client.ts` — `ReputationLogClient` (NPS-RFC-0004 Phase 2)**: Full fetch-based client for the reputation-log operator API. `submitEntry`, `queryEntries`, `getSth`, `getProof`, `getGossipSth`. `verifyInclusion` performs RFC 9162 §2.1.3.2 Merkle audit-path verification locally using `@noble/hashes/sha256`. `signEntry` / `verifyEntry` sign and verify entries with `@noble/ed25519`. Wire types: `ReputationLogEntry`, `SignedTreeHead`, `InclusionProof`, `ObservationWindow`. `AnchorTopologyError` carries `nwpErrorCode` + `npsStatus`. 30 regression tests. Re-exported from `@labacacia/nps-sdk/nip`.
+
+- **`nwp/anchor-client.ts` — `AnchorNodeClient` (NPS-CR-0002)**: Fetch-based client for Anchor Node topology queries. `getSnapshot` (topology.snapshot) and `subscribe` async generator (topology.stream NDJSON). Discriminated-union `TopologyEvent` with kinds: `member_joined`, `member_left`, `member_updated`, `anchor_state`, `resync_required`. `AnchorTopologyError` for protocol errors. 24 regression tests.
+
+### Tracking the suite
+
+This release tracks NPS suite `v1.0.0-alpha.7`.
+
+---
+
+## [1.0.0-alpha.6] — 2026-05-14
+
+### Changed
+
+- **`nip/x509/oids.ts` — IANA PEN 65715 (Breaking, CR-0004)**: `LAB_ACACIA_PEN_ARC` updated from `"1.3.6.1.4.1.99999"` to `"1.3.6.1.4.1.65715"`. Certificates issued under the provisional arc must be revoked and re-issued.
+
+- **`nwp/index.ts` — `NwpErrorCodes` re-export removed (Breaking)**: `export * as NwpErrorCodes from "./error-codes.js"` removed from the barrel. Import directly from `@labacacia/nps-sdk/nwp/error-codes` if needed.
+
+- **Version bump to `1.0.0-alpha.6`** — synchronized with NPS suite alpha.6 release.
+
+---
+
+## [1.0.0-alpha.5] — 2026-05-01
+
+### Added
+
+- **NWP error code constants** — new `NwpErrorCodes` namespace exported from `@labacacia/nps-sdk/nwp` with all 30 NWP wire error codes (auth, query, action, task, subscribe, infrastructure, manifest, topology, reserved-type). Missing from previous releases.
+- **`NpsStatusCodes.NPS_SERVER_UNSUPPORTED`** — new status code `"NPS-SERVER-UNSUPPORTED"` (HTTP 501) in `src/core/status-codes.ts`, per spec/status-codes.md alpha.5 update.
+- **`NDP.resolveWithDns` — DNS TXT fallback resolution** — new `InMemoryNdpRegistry.resolveWithDns(target, resolver?)` falls back to `_nps-node.{host}` TXT record lookup (NPS-4 §5) when no in-memory entry matches. New `DnsTxtLookup` interface + `SystemDnsTxtLookup` (Node.js `dns.promises`); `parseNpsTxtRecord` + `extractHostFromTarget` helpers exported from `@labacacia/nps-sdk/ndp`. Tests: 284 → 294.
+
+### Changed
+
+- **`AssuranceLevel.fromWire("")` returns `Anonymous`** — `if (wire == null)` changed to `if (!wire)` so `""` returns `Anonymous` instead of `Unknown` (spec §5.1.1 backward-compat fix).
+- **Version bump to `1.0.0-alpha.5`** — synchronized with NPS suite alpha.5 release.
+
+### Fixed
+
+- **`REPUTATION_GOSSIP_FORK` / `REPUTATION_GOSSIP_SIG_INVALID`** — two new NIP reputation gossip error codes added to `src/nip/error-codes.ts` (RFC-0004 Phase 3).
+
+---
+
+## [1.0.0-alpha.4] — 2026-04-30
+
+### Added
+
+- **NPS-RFC-0001 Phase 2 — NCP connection preamble (TypeScript helper
+  parity).** `src/ncp/preamble.ts` exposes `writePreamble(stream)` and
+  `readPreamble(stream)` round-tripping the literal `b"NPS/1.0\n"`
+  sentinel; matched by `tests/ncp/preamble.test.ts`. Brings TypeScript
+  in line with the .NET / Python / Go / Java preamble helpers shipped
+  at alpha.4.
+- **NPS-RFC-0002 Phase A/B — X.509 NID certificates + ACME `agent-01`
+  (TypeScript port).** New surface under `src/nip/`:
+  - `nip/x509/` — X.509 NID certificate builder + verifier
+    (`x509.Builder`, `x509.Verifier`).
+  - `nip/acme/` — ACME `agent-01` client + server reference
+    (`AcmeServer`, `AcmeClient`); JWS-signed wire envelope per
+    NPS-RFC-0002 Phase B.
+  - `nip/assurance-level.ts` — agent identity assurance levels
+    (`anonymous` / `attested` / `verified`) per NPS-RFC-0003.
+  - `nip/cert-format.ts` — IdentFrame `cert_format` discriminator
+    (`v1` Ed25519 vs. `x509`).
+  - `nip/error-codes.ts` — NIP error code namespace strings.
+  - `nip/verifier.ts` — dual-trust IdentFrame verifier (v1 + X.509).
+- 20 new tests covering preamble round-trip, X.509 issuance + parsing,
+  dual-trust verification, and ACME agent-01 round-trip. Total: 284
+  tests green (was 264 at alpha.3).
+
+### Changed
+
+- Distribution version bumped to `1.0.0-alpha.4`.
+- `src/nip/frames.ts` — IdentFrame wire shape extended with optional
+  `cert_format` discriminator + `x509_chain` field alongside the
+  existing v1 Ed25519 fields. v1 IdentFrames written by alpha.3
+  consumers continue to verify unchanged.
+
+### Note: npm publish status
+
+- This repo / tag is the canonical `1.0.0-alpha.4` reference for
+  `@labacacia/nps-sdk`. As at the alpha.3 ship cycle, npm publish
+  may require a granular access token with 2FA-bypass enabled — if
+  the registry version lags this repo's tag, the tag is the
+  authoritative artifact and `npm install` against the next
+  registry cut will resolve to this commit.
+
+### Suite-wide highlights at alpha.4
+
+- **NPS-RFC-0002 X.509 + ACME** — full cross-SDK port wave (.NET /
+  Java / Python / TypeScript / Go / Rust). Servers can now issue
+  dual-trust IdentFrames (v1 Ed25519 + X.509 leaf cert chained to a
+  self-signed root) and self-onboard NIDs over ACME's `agent-01`
+  challenge type.
+- **NPS-CR-0002 — Anchor Node topology queries** — `topology.snapshot`
+  / `topology.stream` query types (.NET reference + L2 conformance
+  suite). TypeScript consumer-side helpers planned for a later
+  release.
+- **`nps-registry` SQLite-backed real registry** + **`nps-ledger`
+  Phase 2** (RFC 9162 Merkle + STH + inclusion proofs) shipped in the
+  daemon repos.
+
+---
+
+## [1.0.0-alpha.3] — 2026-04-25
+
+### Changed
+
+- Version bump to `1.0.0-alpha.3` for suite-wide synchronization with the NPS `v1.0.0-alpha.3` release. No functional changes in the TypeScript SDK at this milestone.
+- 264 tests, ≥98% coverage still green.
+
+### Suite-wide highlights at alpha.3 (per-language helpers planned for alpha.4)
+
+- **NPS-RFC-0001 — NCP connection preamble** (Accepted). Native-mode connections now begin with the literal `b"NPS/1.0\n"` (8 bytes). Reference helper landed in the .NET SDK; TypeScript helper deferred to alpha.4.
+- **NPS-RFC-0003 — Agent identity assurance levels** (Accepted). NIP IdentFrame and NWM gain a tri-state `assurance_level` (`anonymous`/`attested`/`verified`). Reference types landed in .NET; TypeScript parity deferred to alpha.4.
+- **NPS-RFC-0004 — NID reputation log (CT-style)** (Accepted). Append-only Merkle log entry shape published; reference signer landed in .NET (and shipped as the `nps-ledger` daemon Phase 1). TypeScript helpers deferred to alpha.4.
+- **NPS-CR-0001 — Anchor / Bridge node split.** The legacy "Gateway Node" role is renamed to **Anchor Node**; the "translate NPS↔external protocol" role is now its own **Bridge Node** type. AnnounceFrame gained `node_kind` / `cluster_anchor` / `bridge_protocols`. Source-of-truth changes are in `spec/` + the .NET reference implementation.
+- **6 NPS resident daemons.** New `daemons/` tree in NPS-Dev defines `npsd` / `nps-runner` / `nps-gateway` / `nps-registry` / `nps-cloud-ca` / `nps-ledger`; `npsd` ships an L1-functional reference and the rest ship as Phase 1 skeletons.
+
+---
+
+## [1.0.0-alpha.2] — 2026-04-19
+
+### Fixed
+
+- **`NpsFrameCodec is not a constructor`** — `src/core/index.ts` now explicitly re-exports the shipped OOP API (`NpsFrameCodec`, `Tier1JsonCodec`, `Tier2MsgPackCodec`, `FrameRegistry`, `AnchorFrameCache`) from `./codec.js`, `./registry.js`, `./cache.js`. The parallel functional API under `./codecs/` remains reachable by direct path but is no longer auto-exported (it collided on `FrameType` / `EncodingTier` / `FrameHeader`).
+- **Missing Ed25519 runtime deps** — `@noble/ed25519` and `@noble/hashes` are now declared as runtime dependencies. Previously imported by `src/nip/identity.ts` and `src/ndp/validator.ts` but not listed in `package.json`, causing install failures for npm consumers.
+
+### Added
+
+- **HelloFrame (NCP 0x06)** — new `HelloFrame` class in `src/ncp/frames.ts` with snake_case toDict/fromDict, registered in `ncp/registry.ts`. `FrameType.HELLO = 0x06` added to the enum.
+- **Subpath exports** — `package.json` `exports` map now includes `./nwp`, `./nip`, `./ndp`, `./nop` (previously only `.`, `./core`, `./ncp` were declared even though README documented all six).
+
+### Changed
+
+- Node engine requirement raised to `>=22.0.0`.
+- 264 tests green (up from 158 previously passing + 5 file failures + 1 test failure).
+
+### Covered modules
+
+- core / ncp / nwp / nip / ndp / nop
+
+---
+
+## [1.0.0-alpha.1] — 2026-04-10
+
+First public alpha as part of the NPS suite `v1.0.0-alpha.1` release.
+
+[1.0.0-alpha.7]: https://github.com/labacacia/NPS-sdk-ts/releases/tag/v1.0.0-alpha.7
+[1.0.0-alpha.2]: https://github.com/LabAcacia/nps/releases/tag/v1.0.0-alpha.2
+[1.0.0-alpha.1]: https://github.com/LabAcacia/nps/releases/tag/v1.0.0-alpha.1

package/README.cn.md

@@ -0,0 +1,163 @@
+[English Version](./README.md) | 中文版
+
+# @labacacia/nps-sdk — TypeScript / Node.js
+
+面向 **Neural Protocol Suite (NPS)** 的 TypeScript SDK —— 为 AI Agent 设计的协议族。
+属 [LabAcacia](https://github.com/LabAcacia) / INNO LOTUS PTY LTD 开源生态。
+
+## 状态
+
+**v1.0.0-alpha.13 — RFC-0002 跨 SDK 端口波（第三棒）** · 5 个协议 · 271 个测试 · 覆盖率 ≥ 98%
+
+> npm registry 说明：`@labacacia/nps-sdk@1.0.0-alpha.11` 已 deprecated，因为发布到 npm 的 tarball 缺少 `dist/`。该问题已在 `1.0.0-alpha.13` 修复——请安装 `@labacacia/nps-sdk@alpha`（`alpha` dist-tag 现已指向 `1.0.0-alpha.13`）。
+
+| 协议 | 类 | 状态 |
+|------|----|------|
+| NCP — Neural Communication Protocol | 帧、编解码器 | ✅ |
+| NWP — Neural Web Protocol | `NwpClient` | ✅ |
+| NIP — Neural Identity Protocol | `NipIdentity`、`NipIdentVerifier`（RFC-0002 §8.1 双信任）、`AssuranceLevel`（RFC-0003）、`nip.x509` + `nip.acme` | ✅ |
+| NDP — Neural Discovery Protocol | `InMemoryNdpRegistry`、`NdpAnnounceValidator` | ✅ |
+| NOP — Neural Orchestration Protocol | `NopClient` | ✅ |
+
+**早期新增** —— 完整的 NPS-RFC-0002 X.509 + ACME `agent-01` NID 证书原语：
+
+- `nip.x509` —— `issueLeaf` / `issueRoot` / `verify`（基于 `@peculiar/x509` + 原生 Web Crypto Ed25519）。
+- `nip.acme` —— `AcmeClient` + 进程内 `AcmeServer` + JWS / messages helpers（RFC 8555 + RFC 8037 EdDSA）。
+- `IdentFrame` 扩展非破坏性可选构造参数 `assuranceLevel` / `certFormat` / `certChain`；v1 verifier 忽略新字段。
+
+## 安装
+
+```bash
+npm install @labacacia/nps-sdk@alpha
+```
+
+> **对等依赖：** Node.js 22+
+
+## 快速开始
+
+### NWP —— 查询节点
+
+```typescript
+import { NwpClient, QueryFrame } from "@labacacia/nps-sdk/nwp";
+
+const client = new NwpClient("http://node.example.com:17433");
+const caps   = await client.query(new QueryFrame("sha256:<anchor-id>", { active: true }, 20));
+console.log(caps.count, caps.data);
+```
+
+### NWP —— 流式结果
+
+```typescript
+for await (const chunk of client.stream(new QueryFrame("sha256:<anchor-id>"))) {
+  console.log(chunk.seq, chunk.data);
+}
+```
+
+### NWP —— 调用 Action
+
+```typescript
+import { ActionFrame } from "@labacacia/nps-sdk/nwp";
+
+const result = await client.invoke(new ActionFrame("summarise", { maxTokens: 500 }));
+```
+
+### NIP —— Ed25519 身份
+
+```typescript
+import { NipIdentity } from "@labacacia/nps-sdk/nip";
+
+// 生成并持久化
+const id = NipIdentity.generate();
+id.save("./my-key.json", process.env.KEY_PASS!);
+
+// 加载并签名
+const loaded = NipIdentity.load("./my-key.json", process.env.KEY_PASS!);
+const sig    = loaded.sign({ action: "announce", nid: "urn:nps:node:example.com:data" });
+const ok     = loaded.verify({ action: "announce", nid: "urn:nps:node:example.com:data" }, sig);
+```
+
+### NDP —— 注册表和签名校验
+
+```typescript
+import { InMemoryNdpRegistry, NdpAnnounceValidator } from "@labacacia/nps-sdk/ndp";
+import { AnnounceFrame } from "@labacacia/nps-sdk/ndp";
+
+const registry  = new InMemoryNdpRegistry();
+const validator = new NdpAnnounceValidator();
+validator.registerPublicKey(nid, identity.pubKeyString);
+
+registry.announce(frame);
+const resolved = registry.resolve("nwp://example.com/data/items");
+```
+
+### NOP —— 提交并等待任务
+
+```typescript
+import { NopClient, TaskFrame } from "@labacacia/nps-sdk/nop";
+
+const client = new NopClient("http://orchestrator.example.com:17433");
+const dag    = {
+  nodes: [{ id: "classify", action: "classify-text", agent: "urn:nps:node:ml.example.com:classifier" }],
+  edges: [],
+};
+
+const taskId = await client.submit(new TaskFrame("my-task-1", dag));
+const status = await client.wait(taskId, { timeoutMs: 30_000 });
+console.log(status.state, status.aggregatedResult);
+```
+
+## 包导出
+
+```typescript
+import { ... } from "@labacacia/nps-sdk";           // 全部
+import { ... } from "@labacacia/nps-sdk/core";       // codec、帧、registry、cache
+import { ... } from "@labacacia/nps-sdk/ncp";        // AnchorFrame、CapsFrame、StreamFrame、HelloFrame、…
+import { ... } from "@labacacia/nps-sdk/nwp";        // NwpClient、QueryFrame、ActionFrame
+import { ... } from "@labacacia/nps-sdk/nip";        // NipIdentity、IdentFrame、TrustFrame、RevokeFrame
+import { ... } from "@labacacia/nps-sdk/ndp";        // InMemoryNdpRegistry、NdpAnnounceValidator、AnnounceFrame、…
+import { ... } from "@labacacia/nps-sdk/nop";        // NopClient、NopTaskStatus、TaskFrame、…
+```
+
+## NCP 编解码
+
+编解码层支持双 Tier 编码和对线上字节的直接操作：
+
+```typescript
+import { NpsFrameCodec, EncodingTier } from "@labacacia/nps-sdk/core";
+import { createDefaultRegistry } from "@labacacia/nps-sdk";
+
+const codec = new NpsFrameCodec(createDefaultRegistry());
+
+// 编码（默认 MsgPack）
+const wire = codec.encode(frame);
+
+// 编码为 JSON（调试 / 互操作）
+const json = codec.encode(frame, { overrideTier: EncodingTier.JSON });
+
+// 解码
+const decoded = codec.decode(wire);
+
+// 仅读取帧头，不解码 payload
+const header = NpsFrameCodec.peekHeader(wire);
+console.log(header.frameType, header.isExtended, header.payloadLength);
+```
+
+## 开发
+
+```bash
+# 安装
+npm install
+
+# 测试
+npm test
+
+# 测试 + 覆盖率
+npm run test -- --coverage
+
+# 构建（ESM + CJS）
+npm run build
+```
+
+## 许可证
+
+Apache 2.0 —— 详见 [LICENSE](https://github.com/labacacia/NPS-Dev/blob/main/LICENSE)。

package/README.md

@@ -1,3 +1,5 @@
+English | [中文版](./README.cn.md)
+
 # @labacacia/nps-sdk — TypeScript / Node.js
 
 TypeScript SDK for the **Neural Protocol Suite** (NPS) — a protocol suite designed for AI Agents.  
@@ -5,23 +7,31 @@ Part of the [LabAcacia](https://github.com/LabAcacia) / INNO LOTUS PTY LTD open-
 
 ## Status
 
-**v0.1.0 — Phase 2** · 5 protocols · 139 tests · ≥ 98% coverage
+**v1.0.0-alpha.13 — RFC-0002 cross-SDK port (third language)** · 5 protocols · 271 tests · ≥ 98% coverage
+
+> npm registry note: `@labacacia/nps-sdk@1.0.0-alpha.11` was deprecated because its published tarball omitted `dist/`. That is fixed in `1.0.0-alpha.13` — install `@labacacia/nps-sdk@alpha` (the `alpha` dist-tag now resolves to `1.0.0-alpha.13`).
 
 | Protocol | Class | Status |
 |----------|-------|--------|
 | NCP — Neural Communication Protocol | Framing, codec | ✅ |
 | NWP — Neural Web Protocol | `NwpClient` | ✅ |
-| NIP — Neural Identity Protocol | `NipIdentity` | ✅ |
+| NIP — Neural Identity Protocol | `NipIdentity`, `NipIdentVerifier` (RFC-0002 §8.1 dual-trust), `AssuranceLevel` (RFC-0003), `nip.x509` + `nip.acme` | ✅ |
 | NDP — Neural Discovery Protocol | `InMemoryNdpRegistry`, `NdpAnnounceValidator` | ✅ |
 | NOP — Neural Orchestration Protocol | `NopClient` | ✅ |
 
+**Earlier additions** — Full NPS-RFC-0002 X.509 + ACME `agent-01` NID certificate primitives:
+
+- `nip.x509` — `issueLeaf` / `issueRoot` / `verify` (built on `@peculiar/x509` + native Web Crypto Ed25519).
+- `nip.acme` — `AcmeClient` + in-process `AcmeServer` + JWS / message helpers (RFC 8555 + EdDSA per RFC 8037).
+- `IdentFrame` extended with non-breaking `assuranceLevel` / `certFormat` / `certChain` constructor options; v1 verifiers ignore the new fields.
+
 ## Installation
 
 ```bash
-npm install @labacacia/nps-sdk
+npm install @labacacia/nps-sdk@alpha
 ```
 
-> **Peer requirement:** Node.js 18+
+> **Peer requirement:** Node.js 22+
 
 ## Quick Start
 
@@ -101,7 +111,7 @@ console.log(status.state, status.aggregatedResult);
 ```typescript
 import { ... } from "@labacacia/nps-sdk";           // everything
 import { ... } from "@labacacia/nps-sdk/core";       // codec, frames, registry, cache
-import { ... } from "@labacacia/nps-sdk/ncp";        // AnchorFrame, CapsFrame, StreamFrame, …
+import { ... } from "@labacacia/nps-sdk/ncp";        // AnchorFrame, CapsFrame, StreamFrame, HelloFrame, …
 import { ... } from "@labacacia/nps-sdk/nwp";        // NwpClient, QueryFrame, ActionFrame
 import { ... } from "@labacacia/nps-sdk/nip";        // NipIdentity, IdentFrame, TrustFrame, RevokeFrame
 import { ... } from "@labacacia/nps-sdk/ndp";        // InMemoryNdpRegistry, NdpAnnounceValidator, AnnounceFrame, …
@@ -150,4 +160,4 @@ node node_modules/tsup/dist/cli-default.js
 
 ## License
 
-Apache 2.0 — see [LICENSE](../../LICENSE)
+Apache 2.0 — see [LICENSE](https://github.com/labacacia/NPS-Dev/blob/main/LICENSE)