Skip to content

README.md

Latest commit

 

History

History
215 lines (174 loc) · 7.51 KB

README.md

File metadata and controls

215 lines (174 loc) · 7.51 KB
Raw

Wenyan

Wenyan is monorepo implementing the Wenyan runtime architecture.

Genesis Docs

If you want to understand the architectural rationale and design principles behind Wenyan, start with the genesis docs:

Packages

  • packages/server (@andrey-kokoev/wenyan-server) - Cloudflare Hono server
  • packages/shared (@andrey-kokoev/wenyan-shared) - compatibility/shared facade
  • packages/core (@andrey-kokoev/wenyan-core) - schemas, envelope types, state transitions, bootstrap/law schemas
  • packages/actor (@andrey-kokoev/wenyan-actor) - law-driven actor permission helpers
  • packages/seal (@andrey-kokoev/wenyan-seal) - seal chain primitives and verification
  • packages/archive (@andrey-kokoev/wenyan-archive) - append-only archive repository API + law/genre lookup
  • packages/pipeline (@andrey-kokoev/wenyan-pipeline) - Caoni/Shenfu/Pizhun stages + law resolver
  • packages/gateway (@andrey-kokoev/wenyan-gateway) - gateway routes and Tongzheng Si input filter
  • packages/channel (@andrey-kokoev/wenyan-channel) - reliable local broadcast channel
  • packages/gossip (@andrey-kokoev/wenyan-gossip) - SWIM/Plumtree-style consort gossip primitives
  • packages/crdt (@andrey-kokoev/wenyan-crdt) - CRDT reconciliation for legislative conflicts
  • packages/consensus (@andrey-kokoev/wenyan-consensus) - PBFT lifecycle for constitutional consensus
  • packages/bridge (@andrey-kokoev/wenyan-bridge) - foreign protocol bridge runtime (standalone Node)
  • packages/imperial-works (@andrey-kokoev/wenyan-imperial-works) - role hierarchy, emergency routing, and construction anomaly rules
  • packages/mobile-foreman (@andrey-kokoev/wenyan-mobile-foreman) - PWA offline foreman queue and sync primitives
  • packages/benchmark (@andrey-kokoev/wenyan-benchmark) - deterministic toy/stress benchmark harness
  • packages/genesis (@andrey-kokoev/wenyan-genesis) - explicit genesis bootstrap (createEmptyOffice, applyGenesis)
  • packages/cli (@andrey-kokoev/wenyan-cli) - wenyan CLI for --init, draft, submit, status, query, stream, imperialworks, mobile sync
  • packages/tests - shared fixtures used by server tests

Storage adapters

  • sqlite adapter (local Dang'an)
  • cloudflare adapter (D1-backed Dang'an)

Law In Dang'an

  • Runtime law/config for admission/appointment/classification/routing/protocol/regulation is resolved from archived genre: "edict" documents.
  • Genre schema registry is archived as sealed genre: "ti_definition" documents.
  • Static filesystem config is bootstrap-only (wenyan.toml): archive engine/path, genesis identity/key, gateway bind, and optional law cache tuning.
  • Runtime is strict fail-closed: missing/ambiguous/invalid law and undefined genres are rejected.

Runtime endpoints

  • POST /api/wenyan/messages (enqueue-only, returns 202 Accepted)
  • GET /api/wenyan/messages/:id
  • GET /api/wenyan/messages?state=...
  • GET /api/wenyan/stream (SSE)
  • GET /api/wenyan/stream/replay?since=... (JSON polling replay)
  • GET /api/wenyan/mesh/status
  • POST /api/wenyan/mesh/join
  • POST /api/wenyan/mesh/sync
  • GET /api/wenyan/mesh/merkle-root

Read endpoints enforce JWT actor authentication when access_control law requires it. Header spoofing via x-wenyan-actor-* is disabled by default.

Bridge runtime (standalone):

  • wenyan bridge run [--config wenyan.toml]
  • wenyan bridge status [--config wenyan.toml]
  • wenyan bridge sync --adapter <id> [--config wenyan.toml]
  • wenyan bridge dry-run --adapter <id> --file payload.json [--config wenyan.toml]

Configuration

  • wenyan.toml
  • wenyan.toml.example

Minimal shape:

[archive]
engine = "sqlite"
path = "./wenyan.dang'an"

[genesis]
node_id = "11111111-1111-4111-8111-111111111111"
genesis_key = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="

[gateway.listen]
host = "127.0.0.1"
port = 8787

[auth]
jwt_issuer = "wenyan.local"
jwt_audience = "wenyan-gateway"
jwt_alg = "HS256"
jwt_secret = "change-this-secret"
allow_header_actor = false

[law]
mode = "strict"

[distributed]
mode = "single"
node_id = "node-a"
bind_gossip = "127.0.0.1:7946"
seeds = []
fanout = 3
suspicion_timeout_ms = 5000

[consensus]
kind = "none"
replica_set = []
constitutional_threshold = 3
view_change_timeout_ms = 5000
allow_single_replica = false

[bridge]
enabled = false
mode = "standalone"

[bridge.sync]
mode = "hybrid"
poll_interval_ms = 1000
batch_size = 100

Commands

  • pnpm install
  • pnpm dev (server local on 8787)
  • pnpm dev:remote (remote Worker preview)
  • pnpm dev:server:local (server only, local wrangler)
  • pnpm dev:server:remote (server only, remote wrangler)
  • pnpm typecheck
  • pnpm test
  • pnpm build
  • pnpm security:audit
  • pnpm security:fuzz
  • pnpm sbom:generate
  • pnpm docs:api
  • pnpm benchmark:toy:check
  • pnpm benchmark:stress
  • wenyan --join gossip://seed:7946
  • wenyan sync --peer gossip://seed:7946
  • wenyan mesh status
  • wenyan bridge run --config wenyan.toml
  • wenyan imperialworks init|status|ceremony --workers <n> --days <n>
  • wenyan imperialworks emergency --site <id> --severity <level>
  • wenyan mobile sync --node <minister-node>

Installation From GitHub Packages

Authenticate npm for the @andrey-kokoev scope:

export GITHUB_TOKEN=YOUR_GITHUB_TOKEN
cat > ~/.npmrc <<'EOF'
@andrey-kokoev:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
EOF

Install packages:

npm install @andrey-kokoev/wenyan-core @andrey-kokoev/wenyan-cli @andrey-kokoev/wenyan-gateway

Installation From npmjs

Install public npmjs packages:

npm install @wenyan2/wenyan-core @wenyan2/wenyan-cli @wenyan2/wenyan-gateway

Published packages in v1.x (both registries, different scopes):

  • @andrey-kokoev/wenyan-core
  • @andrey-kokoev/wenyan-actor
  • @andrey-kokoev/wenyan-seal
  • @andrey-kokoev/wenyan-archive
  • @andrey-kokoev/wenyan-pipeline
  • @andrey-kokoev/wenyan-gateway
  • @andrey-kokoev/wenyan-channel
  • @andrey-kokoev/wenyan-gossip
  • @andrey-kokoev/wenyan-crdt
  • @andrey-kokoev/wenyan-consensus
  • @andrey-kokoev/wenyan-bridge
  • @andrey-kokoev/wenyan-genesis
  • @andrey-kokoev/wenyan-cli
  • @wenyan2/wenyan-core
  • @wenyan2/wenyan-actor
  • @wenyan2/wenyan-seal
  • @wenyan2/wenyan-archive
  • @wenyan2/wenyan-pipeline
  • @wenyan2/wenyan-gateway
  • @wenyan2/wenyan-channel
  • @wenyan2/wenyan-gossip
  • @wenyan2/wenyan-crdt
  • @wenyan2/wenyan-consensus
  • @wenyan2/wenyan-bridge
  • @wenyan2/wenyan-genesis
  • @wenyan2/wenyan-cli

Release Runbook (GitHub Packages)

  1. Bump versions as needed in workspace package manifests.
  2. Push changes to main.
  3. Create and push tag: vX.Y.Z.
  4. Verify deploy docs are current:
    • docs/deploy/quickstart.md
    • docs/deploy/production.md
    • docs/deploy/enterprise.md
  5. Verify release validation commands pass locally (pnpm -r typecheck, pnpm -r test, pnpm -r build, pnpm security:audit, pnpm benchmark:toy:check).
  6. Publish to GitHub Packages: pnpm publish:github (or pnpm publish:github:dry-run).
  7. Publish npmjs mirror scope: pnpm publish:npmjs (or pnpm publish:npmjs:dry-run).
  8. Confirm packages appear in GitHub repository Packages section and npmjs for @wenyan2.