chain-insights 0.58.3 → 0.58.4

package/README.md

@@ -159,8 +159,8 @@ Entry points:
 - `src/index.ts` — library exports.
 
 Full architecture docs: [docs/architecture/](docs/architecture/ARCHITECTURE.md),
-including C4 diagrams, [data contracts](docs/architecture/data-contracts.md),
-and [operating rules](docs/architecture/operating-rules.md).
+the contracts the code keeps in [Development](docs/development.md#contracts-the-code-keeps),
+and the repository rules in [Contributing](docs/contributing.md#repository-rules).
 
 ### Graph Access
 
@@ -442,10 +442,10 @@ Product docs:
 
 Architecture depth:
 
-- [docs/architecture/](docs/architecture/ARCHITECTURE.md) — index, C4
-  diagrams, context, containers, components.
-- [Data contracts](docs/architecture/data-contracts.md) — tool surface,
-  search limits, endpoint rules, shared-graph model.
-- [Operating rules](docs/architecture/operating-rules.md) — repo
-  invariants, findings rules, CI gotchas.
+- [docs/architecture/](docs/architecture/ARCHITECTURE.md) — the component
+  diagram, containers, one doc per source module.
+- [Contracts the code keeps](docs/development.md#contracts-the-code-keeps) —
+  tool surface, argument allowlists, endpoint rules, shared-graph model.
+- [Repository rules](docs/contributing.md#repository-rules) — invariants,
+  CI gotchas, documentation rules.
 - [docs/acceptance/](docs/acceptance/) — per-component acceptance evidence.

package/docs/contributing.md

@@ -53,6 +53,76 @@ npm run release:check
 git diff --check
 ```
 
+## Repository rules
+### Repository Invariants
+
+- `AGENTS.md` and `CLAUDE.md` are twin files kept byte-identical. Edit both
+  together, or neither.
+- Every PR that changes tracked files must bump `package.json`,
+  `package-lock.json`, and `CHANGELOG.md`. Enforced by
+  `npm run release:check` (`scripts/check-release-gate.mjs`) in
+  `verify.yml` on pull requests.
+- This is a **public** repo. No private repository names, local workspace
+  paths, internal planning catalogs, private deployment details, or
+  org-only workflow names in tracked files. Use the name
+  "Chain Insights Graph" for the graph layer.
+- Public workflow network support is one network: robinhood. The wallet
+  pays on Base mainnet as the payment chain only — not a graph-support
+  claim.
+- Node 22 or newer is required (`package.json` engines). CI installs with
+  `npm ci --ignore-scripts`.
+
+### Data And Findings Invariants
+
+- Address labels are served by the Chain Insights Graph backend, never
+  written by this CLI.
+
+### Development Workflow Rules
+
+- `npm run build` is not plain compilation. It also copies wallet MCP-proxy
+  assets to `dist/assets`. Skipping it stales the packaged assets. See the
+  `dist/` trap in [development.md](development.md).
+- `package.json` `files[]` ships `bin`, `dist`, `skills` and `docs/*.md`.
+  Adding a skill or doc changes the published tarball.
+  `verify.yml` runs `npm pack` and lists contents.
+- npm overrides pin `ws` to 8.21.0 (`package.json`).
+
+### CI Gotchas
+
+- `verify.yml` runs on every pull request and every push to `main`, on the
+  self-hosted `chainswarm-runner` runners. Its three tiers are the files
+  under `ci/` (`t1.sh`, `lint.sh`, `build.sh`), so `bash ci/t1.sh` runs the
+  same gate locally.
+- Repo CI has a release gate blocking non-release PRs and a secret scan
+  flagging `0x{64}` hex. Avoid committing 64-hex strings.
+- UATs expecting unprefixed tool names (`address_risk`, `trace_funds`, …)
+  are stale. Those names are deliberately hidden, and
+  `assertPublicMcpToolName()` throws with a suggested `aml_*` / `meta_*`
+  replacement.
+- Backend big-query memory limits can surface as generic timeout-like
+  errors on archive queries. Do not diagnose these as proxy bugs.
+
+### Method Ownership (Reference, Do Not Restate)
+
+- Inspector / ACP surface audits (tools/list, prompts/list, prefixed-name
+  sync): internal maintainer tooling, not part of this package.
+- ACP release method: internal maintainer tooling.
+- Real local UAT against the GraphRAG MCP: internal maintainer tooling.
+- npm release testing: internal maintainer tooling.
+- Graph serving tiers and sync detail: internal system knowledge, not this
+  repo.
+
+### Documentation Rules
+
+- Keep docs product-first and user-workflow-first: install → configure graph
+  access → run AML tools.
+- Localhost endpoints are fine in debugging docs. Private paths are not.
+- The shipped product skill under `skills/` is `chain-insights-cypher`.
+  It is a separate product surface
+  packaged into the npm tarball and enforced by
+  `tests/skills-contract.test.ts`. A capability no skill mentions is
+  invisible to agents — keep the skill in step with any change.
+
 ## Release Discipline
 
 Every PR to `main` must:

package/docs/development.md

@@ -73,8 +73,94 @@ npm install -g .
 cia --version
 ```
 
+## Contracts the code keeps
+The contracts Chain Insights exposes and consumes. Every statement here
+names the source file it was verified against.
+
+### Public MCP Tool Surface
+
+- The canonical public tool surface is the prefixed set `graph_*` /
+  `meta_*` / `wallet_*`.
+- `visibleRemoteTools()` in `src/mcp/tool-visibility.ts` hides unprefixed
+  backend names (`address_risk`, `trace_victim_funds`, `trace_suspect_funds`,
+  `trace_deposit_sources`, `trace_funds`, `track_funds`,
+  `network_capabilities`, `usage_status`, `balance`, `topup`, `help`,
+  `address_connection_risk` and the retired exchange-flows tool) via
+  `HIDDEN_REMOTE_TOOL_NAMES`. They never surface publicly. So does
+  `aml_address_risk`, hidden until its verdict is fixed.
+- Local tools live in `src/mcp/proxy.ts` (`LOCAL_TOOL_NAMES`):
+  `meta_network_capabilities`, `meta_schema`, `meta_rules`, `meta_help`,
+  `meta_usage_status`, `meta_subscription_status`, `wallet_balance`,
+  `wallet_topup`, and `graph_expand`, which only the view calls
+  (`APP_ONLY_LOCAL_TOOL_NAMES`).
+- `meta_schema` (`src/mcp/graph-schema.ts`) builds the live graph schema of one
+  network from the catalog statements of the graph endpoint (`CALL db.labels()`,
+  `CALL db.relationshipTypes()`, `CALL db.propertyKeys()`, `SHOW INDEXES`), a
+  sample of the main kinds and the published capabilities. It returns
+  `chain-insights.graph-schema.v1`, and keeps it on disk for 24 hours
+  (`src/mcp/graph-schema-cache.ts`).
+- `meta_network_capabilities` repeats GraphRAG's advertised networks
+  (`mirrorGraphNetworkCapabilities` in `src/mcp/capabilities.ts`). CIA
+  preserves the tool status advertised for each network. It does not add
+  tools that the network did not advertise. It also repeats the blocks a
+  network publishes about its layers exactly as sent: `layers`,
+  `chain_admission`, `topology_admission` and `facts_admission`. A block the
+  server did not send stays absent, never empty. The limits of a layer are read
+  from these blocks, never written into a skill.
+
+#### Tool Argument Contracts
+
+- `PUBLIC_MCP_TOOL_REQUIRED_ARGS` / `PUBLIC_MCP_TOOL_ALLOWED_ARGS` in
+  `src/mcp/tool-visibility.ts` define the public arg contract. Examples:
+  `graph_query` requires query + network; `graph_query_batch` alone allows
+  `per_query_timeout_seconds`; both allow `time_scope`.
+- An argument absent from the allowlist is silently stripped by
+  `normalizeRemoteToolArguments`. Every new tunable arg must be added here
+  and to the numeric-argument set in `src/mcp/call-args.ts` the moment it
+  appears on a tool schema.
+
+### Endpoint Configuration
+
+Precedence for the Chain Insights Graph endpoint:
+
+1. `CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT` environment variable.
+2. Legacy `GRAPH_MCP_ENDPOINT` environment variable.
+3. Saved `graphMcpEndpoint` config value.
+4. Default `https://mcp.chain-insights.ai/`.
+
+Validation (`validateMcpEndpoint` in `src/config/mcp-endpoint.ts`):
+
+- `http://` only for loopback or Kubernetes `*.svc.cluster.local` service DNS.
+- Other remote hosts must use `https://`.
+- No credentials, query string, or fragment in the URL.
+
+The MCP proxy uses stateless operation by default. It returns tool results to
+the caller and does not create local investigation files.
+
+### Shared-Graph Model
+
+The public surface exposes **one network** (`robinhood`, see Public MCP
+Tool Surface). Address space details are a chain property, not a separate
+query network.
+
+Consequences:
+
+- The `network` argument to `graph_query` selects the graph, not the address
+  subset. `network` is also a property of every node and relationship on
+  `USE topology`, `USE facts` and `USE chain`. Its value is the query's
+  `network`, it is computed and never stored, and only a `:Chain` node (the far
+  side of a bridge) stores its own, which names the remote chain. A filter on
+  `network` narrows nothing. Anchor a query on an address instead.
+- `USE facts` carries `network` on its rows and endpoints too, with no view
+  column behind it. Facts serves `Address` only as a `TRANSFER` endpoint, so a
+  single-node `MATCH (a:Address)` is refused. Facts serves no kind label.
+
+Verify against the live stack before restating it. Query-side detail:
+[graph-query-compatibility.md](graph-query-compatibility.md).
+
 ## More Developer Docs
 
 - Contributor workflow: `docs/contributing.md`
 - Debugging and UAT: `docs/debugging.md`
 - Graph tool contracts: `docs/graph-tools.md`
+- Architecture index: `docs/architecture/ARCHITECTURE.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chain-insights",
-  "version": "0.58.3",
+  "version": "0.58.4",
   "description": "AML investigation CLI and MCP proxy for blockchain risk screening and Chain Insights Graph access",
   "homepage": "https://chain-insights.ai",
   "repository": {
@@ -50,8 +50,7 @@
     "dist",
     "skills",
     "!skills/rbmk-*",
-    "docs/*.md",
-    "docs/images"
+    "docs/*.md"
   ],
   "scripts": {
     "build": "tsdown && mkdir -p dist/assets dist/apps && cp -r src/wallet/mcp-proxy/assets/* dist/assets/ && cp src/mcp/apps/claude-view.html dist/apps/",