feat: harden local runtime release boundary

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release-check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm security:audit
+      - run: pnpm release:check

CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to Agent Runtime Services are documented in this file. The
+project follows Semantic Versioning after its first published release; until
+then, the `Unreleased` section is the release-candidate source of truth.
+
+## [Unreleased]
+
+### Added
+
+- `RPC-LOOPBACK-001`: fail-closed loopback validation for the local RPC server.
+- `RPC-JSONRPC-002`: JSON-RPC 2.0 parse, request, method, parameter, and internal
+  error classification.
+- `RPC-BODY-003`: a 1 MiB local RPC request-body limit enforced before dispatch.
+- `RELEASE-GATE-004`: one `pnpm release:check` command shared by contributors
+  and CI on supported Node.js versions.
+- Machine-readable and human-readable project traceability for release
+  hardening requirements.
+
+### Changed
+
+- The local RPC documentation now makes non-loopback exposure an explicit
+  human-owned architecture and security gate.
+
+### Validation Evidence
+
+- The release-candidate gate passed 116 tests across 15 test files under Node 20
+  and Node 22, plus typecheck, build, and a 21-file package dry-run.
+- The production dependency audit reported no known vulnerabilities at the time
+  of validation.
+- Two clean external consumer snapshots installed the same generated tarball:
+  one passed 51 focused integration tests plus typecheck, and one passed 8
+  focused integration tests plus typecheck.
+
+### Not Yet Proven
+
+- Real provider smoke with owner-managed credentials.
+- Acceptance in concrete domain-agent and build-agent repositories.
+- npm publication and production operation.
+
+## [0.1.0] - Unpublished baseline
+
+- Established Runtime Core and Agent Services with local JSON-RPC, model,
+  artifact, record, memory, vector, resource, secret, and provider-port
+  capabilities.
+- Added atomic record compare-and-set with fail-closed provider capability
+  negotiation.

README.md

@@ -104,11 +104,22 @@ product intent; that remains in the public narrative and [PRD.md](PRD.md).
 pnpm install
 pnpm test
 pnpm build
+pnpm release:check
 agent-runtime-services models install-volcengine-agent-plan
 agent-runtime-services secrets set --id ARK_API_KEY
 agent-runtime-services serve --host 127.0.0.1 --port 8765
 ```
 
+The P0 RPC transport is loopback-only. `serve` rejects wildcard, private-network,
+and public bind addresses before starting; non-loopback exposure requires a
+separate authenticated remote-transport contract rather than a permissive host
+flag. Requests to `/rpc` are limited to 1 MiB and use JSON-RPC 2.0 error codes.
+
+`pnpm release:check` is the shared local and CI release-candidate gate. It runs
+the complete test suite, typecheck, build, and package dry-run. A green gate is
+local validation evidence; real provider smoke, consumer acceptance, npm
+publication, and production operation remain separate owner-controlled gates.
+
 The library entrypoint is `createRuntimeServices(config)`. It exposes typed
 capabilities across two service layers:
 

README.zh-CN.md

@@ -88,11 +88,20 @@ append-only event -> extracted claim -> relationship context -> evidence-backed
 pnpm install
 pnpm test
 pnpm build
+pnpm release:check
 agent-runtime-services models install-volcengine-agent-plan
 agent-runtime-services secrets set --id ARK_API_KEY
 agent-runtime-services serve --host 127.0.0.1 --port 8765
 ```
 
+P0 RPC 传输只允许 loopback。`serve` 会在启动前拒绝通配、私网和公网绑定地址；
+非 loopback 暴露必须先建立独立且带认证的远程传输契约，不能通过放宽 host 参数实现。
+`/rpc` 请求体上限为 1 MiB，并使用 JSON-RPC 2.0 错误码。
+
+`pnpm release:check` 是本地与 CI 共用的发布候选门禁，会运行完整测试、类型检查、
+构建和 package dry-run。门禁全绿只是本地验证证据；真实 Provider smoke、消费者验收、
+npm 发布和生产运行仍是彼此独立、由 owner 控制的门禁。
+
 库入口是 `createRuntimeServices(config)`。它跨两层服务暴露类型化能力：
 
 Runtime Core：

architecture/README.md

@@ -264,6 +264,16 @@ not shared by default across projects.
 - [Memory Substrate Capability Contract](./memory-substrate-prd.md): downstream
   L1/L2 contract for append-only events, claims, relationship context,
   preserved policy metadata, and retrieval bundles.
+- [Local RPC Transport Contract](./rpc-transport-contract.md): loopback-only
+  binding, JSON-RPC error semantics, bounded request bodies, and release-gate
+  evidence for the P0 local transport.
+- [Release Readiness Contract](./release-readiness-contract.md): package
+  integrity, external-consumer compatibility, dependency security, real
+  provider smoke, and publication owner gates.
+- [Project Traceability](./project-traceability.md): human-readable mapping from
+  product requirements and formal contracts to implementation, validation, and
+  residual owner gates. The machine-readable source is
+  [`project-traceability.yaml`](./project-traceability.yaml).
 
 ## Change Rules
 

architecture/project-traceability.md

@@ -0,0 +1,49 @@
+# Project Traceability
+
+This is the human-readable companion to
+[`project-traceability.yaml`](./project-traceability.yaml). It connects current
+product intent to formal contracts, implementation, validation, and residual
+risk without treating validation as publication approval.
+
+| Requirement | Product and contract refs | Implementation | Validation | Current state |
+| --- | --- | --- | --- | --- |
+| `RPC-LOOPBACK-001` | `PRD.md`; `rpc-transport-contract.md` | `src/rpc/server.ts`, `src/cli/index.ts` | RPC contract and CLI smoke tests | Validated local |
+| `RPC-JSONRPC-002` | `PRD.md`; `rpc-transport-contract.md` | `src/rpc/server.ts` | RPC protocol matrix | Validated local |
+| `RPC-BODY-003` | `PRD.md`; `rpc-transport-contract.md` | `src/rpc/server.ts` | oversized-request regression | Validated local |
+| `RELEASE-GATE-004` | `PRD.md`; `rpc-transport-contract.md` | `package.json`, GitHub Actions | `pnpm release:check` | Validated local |
+| `PACKAGE-INTEGRITY-001` | `PRD.md`; `release-readiness-contract.md` | package metadata and packed consumer | release check and tarball acceptance | Validated local |
+| `CONSUMER-COMPATIBILITY-002` | `PRD.md`; `release-readiness-contract.md` | public library/RPC adapters | clean consumer snapshots against the tarball | Validated snapshots |
+| `DEPENDENCY-SECURITY-003` | `PRD.md`; `release-readiness-contract.md` | package and CI scripts | `pnpm security:audit` | Validated current |
+| `PROVIDER-SMOKE-004` | `PRD.md`; `release-readiness-contract.md` | operator model/resource commands | real provider smoke | Owner gate |
+| `PUBLICATION-OWNER-005` | `PRD.md`; `release-readiness-contract.md` | version, changelog, package metadata | owner approval and registry/tag evidence | Owner gate |
+
+## Residual Owner Gates
+
+- selecting internal tarball/Git distribution or npm publication;
+- real provider credentials and smoke execution;
+- acceptance in concrete domain-agent and build-agent consumers;
+- any remote, non-loopback, or MCP exposure.
+
+These gates remain open until direct evidence and owner approval exist.
+
+## Current Validation Baseline
+
+- `pnpm release:check`: 15 test files and 116 tests passed under Node 20 and
+  Node 22; typecheck, build, and the 21-file package dry-run passed.
+- `pnpm security:audit`: no known production dependency vulnerabilities at the
+  time of the check.
+- Clean consumer snapshot `4c200a13a5331cf5df213f8a73d3b9bee583983a`
+  installed the tarball and passed 51 focused integration tests plus typecheck.
+- Clean consumer snapshot `0571b678563e82ab5ec6032ff7eccb13ffc6188c`
+  installed the same tarball and passed 8 focused integration tests plus
+  typecheck.
+
+These observations are revision-specific L4 evidence. They do not cover
+uncommitted consumer work, real provider credentials, npm publication, or
+production operation.
+
+Node 22 also exposed an environment-specific residue: enabling the experimental
+`NODE_USE_ENV_PROXY` flag makes Node itself emit `EnvHttpProxyAgent` warnings on
+stderr before CLI code runs. The CI-like Node 22 matrix without that
+experimental flag passes; operators that enable it must account for Node's
+warning stream separately from Runtime Services CLI errors.

architecture/project-traceability.yaml

@@ -0,0 +1,164 @@
+schema_version: 1
+validation_baseline:
+  observed_at: 2026-07-22
+  release_candidate:
+    command: pnpm release:check
+    result: 15 test files and 116 tests passed on Node 20 and Node 22; typecheck, build, and 21-file package dry-run passed
+  dependency_security:
+    command: pnpm security:audit
+    result: no known production dependency vulnerabilities
+  packed_consumers:
+    - role: domain-agent session navigation
+      source_revision: 4c200a13a5331cf5df213f8a73d3b9bee583983a
+      installation: clean git archive installed agent-runtime-services-0.1.0.tgz
+      result: 51 focused integration tests and typecheck passed
+    - role: agent intelligence workflow
+      source_revision: 0571b678563e82ab5ec6032ff7eccb13ffc6188c
+      installation: clean git archive installed agent-runtime-services-0.1.0.tgz
+      result: 8 focused integration tests and typecheck passed
+l0_assets:
+  product_narrative:
+    primary: README.md
+    localized:
+      - README.zh-CN.md
+  formal_projection: PRD.md
+authority:
+  source_order:
+    - README.md
+    - README.zh-CN.md
+    - PRD.md
+    - architecture/project-traceability.yaml
+    - architecture/README.md
+    - architecture/rpc-transport-contract.md
+    - architecture/release-readiness-contract.md
+    - src/capabilities/registry.ts
+    - src/runtime-services.ts
+    - src/rpc/server.ts
+    - test
+requirements:
+  - id: RPC-LOOPBACK-001
+    status: validated_local
+    prd_refs:
+      - PRD.md#p0-scope
+      - PRD.md#non-goals
+      - PRD.md#owner-boundary
+    yaml_refs:
+      - architecture/rpc-transport-contract.md#rpc-loopback-001-local-trust-boundary
+    code_refs:
+      - src/rpc/server.ts
+      - src/cli/index.ts
+    validation:
+      - pnpm vitest run test/rpc.contract.test.ts
+      - pnpm vitest run test/cli-rpc-smoke.test.ts
+    residual_risk:
+      - Remote exposure remains prohibited until a separate authenticated transport contract is accepted.
+  - id: RPC-JSONRPC-002
+    status: validated_local
+    prd_refs:
+      - PRD.md#p0-scope
+    yaml_refs:
+      - architecture/rpc-transport-contract.md#rpc-jsonrpc-002-json-rpc-semantics
+    code_refs:
+      - src/rpc/server.ts
+    validation:
+      - pnpm vitest run test/rpc.contract.test.ts
+    residual_risk:
+      - Batch requests and notifications remain outside P0.
+  - id: RPC-BODY-003
+    status: validated_local
+    prd_refs:
+      - PRD.md#p0-scope
+    yaml_refs:
+      - architecture/rpc-transport-contract.md#rpc-body-003-bounded-requests
+    code_refs:
+      - src/rpc/server.ts
+    validation:
+      - pnpm vitest run test/rpc.contract.test.ts
+    residual_risk:
+      - Capability-specific payload limits remain future contract work.
+  - id: RELEASE-GATE-004
+    status: validated_local
+    prd_refs:
+      - PRD.md#downstream-chain
+      - PRD.md#owner-boundary
+    yaml_refs:
+      - architecture/rpc-transport-contract.md#release-gate-004-delivery-evidence
+    code_refs:
+      - package.json
+      - .github/workflows/ci.yml
+    validation:
+      - pnpm release:check
+    residual_risk:
+      - Real provider smoke, consumer acceptance, npm publication, and production operation require separate evidence.
+      - Node 22 with the experimental NODE_USE_ENV_PROXY flag emits runtime warnings on stderr; the CI-like matrix without that experimental flag passes.
+  - id: PACKAGE-INTEGRITY-001
+    status: validated_local
+    prd_refs:
+      - PRD.md#p0-scope
+      - PRD.md#downstream-chain
+    yaml_refs:
+      - architecture/release-readiness-contract.md#package-integrity-001
+    code_refs:
+      - package.json
+      - test/cli-rpc-smoke.test.ts
+    validation:
+      - pnpm release:check
+    residual_risk:
+      - npm publication and registry installation remain owner-controlled gates.
+  - id: CONSUMER-COMPATIBILITY-002
+    status: validated_snapshot
+    prd_refs:
+      - PRD.md#l0-problem
+      - PRD.md#p0-scope
+    yaml_refs:
+      - architecture/release-readiness-contract.md#consumer-compatibility-002
+    code_refs:
+      - examples/client-sample.ts
+      - examples/upstream-agent-sample.md
+      - test/cli-rpc-smoke.test.ts
+    validation:
+      - packed package consumer acceptance
+      - clean snapshot external consumer tests and typecheck
+    residual_risk:
+      - Tested consumer revisions do not prove future contract compatibility or product acceptance.
+  - id: DEPENDENCY-SECURITY-003
+    status: validated_current
+    prd_refs:
+      - PRD.md#owner-boundary
+    yaml_refs:
+      - architecture/release-readiness-contract.md#dependency-security-003
+    code_refs:
+      - package.json
+      - .github/workflows/ci.yml
+    validation:
+      - pnpm security:audit
+    residual_risk:
+      - Advisory results are time-sensitive and must be refreshed for each release candidate.
+  - id: PROVIDER-SMOKE-004
+    status: owner_gate
+    prd_refs:
+      - PRD.md#owner-boundary
+    yaml_refs:
+      - architecture/release-readiness-contract.md#provider-smoke-004
+    code_refs:
+      - src/cli/model-smoke.ts
+      - src/cli/resources.ts
+    validation:
+      - agent-runtime-services models smoke --module all
+      - agent-runtime-services doctor
+    residual_risk:
+      - Requires owner-managed credentials and a selected real provider configuration.
+  - id: PUBLICATION-OWNER-005
+    status: owner_gate
+    prd_refs:
+      - PRD.md#owner-boundary
+    yaml_refs:
+      - architecture/release-readiness-contract.md#publication-owner-005
+    code_refs:
+      - package.json
+      - CHANGELOG.md
+    validation:
+      - explicit owner approval
+      - registry and tag verification after publication
+    residual_risk:
+      - Package is not published and no release tag exists.