{"id":50968337,"url":"https://github.com/protocol-wealth/pwplan-core","last_synced_at":"2026-06-18T23:01:43.995Z","repository":{"id":361296889,"uuid":"1253925358","full_name":"Protocol-Wealth/pwplan-core","owner":"Protocol-Wealth","description":"Protocol Wealth Open Source Planning Suite","archived":false,"fork":false,"pushed_at":"2026-06-16T01:43:51.000Z","size":336,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-16T03:20:38.446Z","etag":null,"topics":["agent-tools","ai","ai-agent","ai-agents","cashflow-analysis","cfp","compliance","financial-analytics","governance","mcp","open-source","planning","regulated-finance","retirement","retirement-calculator","retirement-planning"],"latest_commit_sha":null,"homepage":"https://protocolwealthllc.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Protocol-Wealth.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T00:27:13.000Z","updated_at":"2026-06-16T01:43:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Protocol-Wealth/pwplan-core","commit_stats":null,"previous_names":["protocol-wealth/pwplan-core"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Protocol-Wealth/pwplan-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protocol-Wealth%2Fpwplan-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protocol-Wealth%2Fpwplan-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protocol-Wealth%2Fpwplan-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protocol-Wealth%2Fpwplan-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Protocol-Wealth","download_url":"https://codeload.github.com/Protocol-Wealth/pwplan-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Protocol-Wealth%2Fpwplan-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34510287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","ai","ai-agent","ai-agents","cashflow-analysis","cfp","compliance","financial-analytics","governance","mcp","open-source","planning","regulated-finance","retirement","retirement-calculator","retirement-planning"],"created_at":"2026-06-18T23:01:39.447Z","updated_at":"2026-06-18T23:01:43.988Z","avatar_url":"https://github.com/Protocol-Wealth.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pwplan-core\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Patent Pending](https://img.shields.io/badge/Patent-Pending-orange.svg)](https://patentcenter.uspto.gov/applications/64082241)\n[![OIN Member](https://img.shields.io/badge/OIN-Member-green.svg)](https://openinventionnetwork.com)\n[![GitHub stars](https://img.shields.io/github/stars/Protocol-Wealth/pwplan-core?style=social)](https://github.com/Protocol-Wealth/pwplan-core/stargazers)\n\n**Open-source, regime-adaptive financial planning — a privacy-first thin UI.**\nThe third member of the `-core` family alongside\n[`pwos-core`](https://github.com/Protocol-Wealth) and\n[`nexus-core`](https://github.com/Protocol-Wealth). Anyone can self-host it; it\nships zero quantitative or compliance logic of its own.\n\n\u003e Software, not investment advice. Outputs are projections, not guarantees.\n\u003e Not affiliated with, and does not endorse, any third-party tool.\n\n## The idea: a thin UI that never sees identity\n\npwplan-core takes in **de-identified planning variables** (age, not date of\nbirth; no name), processes and analyzes them, and renders results. The engine\ncontract is **PII-free by construction** — see\n[`src/contract/planning.ts`](src/contract/planning.ts). There is no field for a\nname, DOB, SSN, email, or address anywhere, and `planning.test.ts` fails the\nbuild if one is ever added.\n\nThat single invariant is what lets the same UI safely target two backends.\n\n## Two deployments, one UI\n\nSelected by `VITE_PLANNING_BACKEND`:\n\n```\nOPEN REFERENCE (anyone)                   PW PRODUCTION (private)\n  VITE_PLANNING_BACKEND=nexus-mcp           VITE_PLANNING_BACKEND=pw-api\n+---------------------------+             +---------------------------+\n|  pwplan-core (thin UI)    |             |  pwplan-core UI pattern   |\n|                           |             |  → pwos.app/plan, /chat   |\n+-------------+-------------+             +-------------+-------------+\n              | de-identified                          | de-id + opaque\n              | planning vars                          | subjectRef (auth)\n              v                                        v\n+---------------------------+             +---------------------------+\n|  nexus-core MCP           |             |  pw-api  (private)        |\n|  (nexusmcp.site)          |             |  client context +         |\n|  public quant surface     |             |  subjectRef→identity map  |\n+---------------------------+             +-------------+-------------+\n                                                        | server-to-server\n                                                        v\n                                          +---------------------------+\n                                          |  nexus-core (internal)    |\n                                          |  client request NEVER     |\n                                          |  hits the public endpoint |\n                                          +---------------------------+\n```\n\n- **nexus-mcp** — browser talks directly to the nexus-core MCP gateway. No\n  client to protect; you bring your own de-identified data. The self-host /\n  demo path, and all this OSS repo ever uses.\n- **pw-api** — Protocol Wealth production, implemented in a **private fork** of\n  this repo (not this codebase). Requests route through authenticated pw-api,\n  which holds client context and the pseudonym→identity mapping and calls nexus\n  server-to-server. Shown here only to explain why the gateway is\n  backend-agnostic; the open build never targets it.\n\nClient↔run correlation uses an opaque `subjectRef` carried as a transport\nheader, never derived from identity and never in the math payload. In the open\ndemo it is just an optional token; in the private fork, pw-api maps it back to a\nclient behind auth (for Reg S-P / Rule 17a-4 books-and-records). pwplan-core and\nnexus only ever see the token, never an identity.\n\n## Compliance scope (read this)\n\n**This open-source repo is demo / case-study tooling.** It is built to be pointed\nat the public nexus-core engine with **de-identified or fully fake client data**:\nenter ages, balances, and allocations — never names, DOB, SSNs, emails, phones, or\naddresses. Two things keep that safe:\n\n- **PII-free contract by construction** — there is no field anywhere in\n  [`src/contract/planning.ts`](src/contract/planning.ts) that can carry identity;\n  `planning.test.ts` fails the build if one is added.\n- **A structural tripwire** — `assertNoPII`\n  ([`src/lib/compliance.ts`](src/lib/compliance.ts)) is a small, always-on,\n  dependency-free guard that throws if an identity-shaped key ever reaches the\n  dispatch path. It never redacts, transforms, or stores anything.\n\n**Out of scope for this repo:** real PII de-identification, books-and-records\naudit logging, and any pw-api integration. Those belong to a **private fork**\nthat syncs into pw-api and integrates the pwos-core compliance packages. If you\nare wiring this into a regulated production environment, that is a separate\nexercise — follow the [`pwos-core`](https://github.com/Protocol-Wealth)\nguidelines; this repo intentionally ships none of it. The `pw-api` value of\n`VITE_PLANNING_BACKEND` exists only so that private fork stays a low-diff sync;\nthis OSS build never reaches pw-api.\n\n## Quickstart\n\n```bash\ngit clone https://github.com/Protocol-Wealth/pwplan-core.git\ncd pwplan-core\nnpm install\nnpm run dev\n# Runs against the public nexus-core MCP demo (https://nexusmcp.site) out of the\n# box — no .env needed. Bring de-identified / fake-client data only.\n# To point elsewhere: cp .env.example .env.local and set VITE_PLANNING_GATEWAY_URL.\n```\n\n## Engine contract\n\n`PLANNING_CONTRACT_VERSION` is the wire contract both pwplan-core and the engine\npin. Breaking changes are a major bump and a coordinated release. The client\nthrows `ContractMismatchError` on drift.\n\nThe contract covers **16 planning tools**, **all surfaced in the UI** — fifteen as\ntabs plus the `capital_market_assumptions` control inside the Monte Carlo tab.\n\n| Tool                         | Purpose                                               | UI         |\n| ---------------------------- | ----------------------------------------------------- | ---------- |\n| `monte_carlo_decumulation`   | Path simulation with tax-aware spend-down             | tab        |\n| `glide_path`                 | Target equity weight by age                           | tab        |\n| `tax_aware_withdrawal`       | Per-year withdrawal ordering + RMD                    | tab        |\n| `roth_conversion`            | Convert-now vs. leave-pre-tax after-tax comparison    | tab        |\n| `sequence_of_returns_stress` | Ordering effect on a fixed return set                 | tab        |\n| `rmd`                        | Required minimum distribution (Uniform Lifetime)      | tab        |\n| `tax_bracket_headroom`       | Marginal bracket + room to the next rate (Roth-fill)  | tab        |\n| `social_security_claiming`   | Benefit by claim age 62–70 + breakeven ages           | tab        |\n| `regime_conditioned_swr`     | Base SWR adjusted for the live macro regime           | tab        |\n| `correlation_matrix`         | Real-data return correlations (shrinkage optional)    | tab        |\n| `regime_return_generator`    | Live regime + transition matrix + path cache key      | tab        |\n| `portfolio_xray`             | Regime-aware structural diagnostics + findings        | tab        |\n| `fire`                       | FIRE / Coast-FIRE number + years to independence      | tab        |\n| `risk_metrics`               | Sharpe / Sortino / drawdown / VaR for a return series | tab        |\n| `rebalance`                  | Drift + self-financing trades to target weights       | tab        |\n| `capital_market_assumptions` | Real returns / vols / λ / correlations                | MC control |\n\n## Stack\n\nReact 19 · Vite 6 · Tailwind v4 · TypeScript · Zustand. nexus gateway / pw-api\non GCP Cloud Run; Cloudflare at the edge.\n\n## Working with Claude Code\n\nThis repo is built primarily by Claude Code. Governance lives in\n[`CLAUDE.md`](CLAUDE.md) (operating rules and invariants) and three memory files\nthe agent maintains as it works: [`CURRENT-STATE.md`](CURRENT-STATE.md) (what\nexists now), [`CHANGELOG.md`](CHANGELOG.md) (history), and\n[`ROADMAP.md`](ROADMAP.md) (what is next). These are committed on purpose; they\nare how a stateless CLI keeps continuity across sessions. Start a session by\nreading CLAUDE.md.\n\n## Patent \u0026 IP\n\n**Patent Pending** — USPTO Application #64/082,241 (PW-PROV-003)\n\"Privacy-by-Construction Financial Planning System with PII-Free Compute Plane,\nOpaque Subject References, and Regime-Adaptive Projection for Regulated Financial\nAdvisory Services\"\n\n- [Patent disclosure](https://protocolwealthllc.com/patent) · [USPTO Patent Center](https://patentcenter.uspto.gov/applications/64082241) · [Figure 1 — system drawing (PDF)](docs/PW-PROV-003-FIG1.pdf)\n- Applicant: Protocol Wealth, LLC\n- Inventor: Nicholas Rygiel\n- Filed: June 4, 2026\n- Status: Patent Pending (provisional; 12-month conversion deadline 2027-06-04)\n\nThe architecture relied on by this project — a privacy-by-construction\nfinancial-planning system in which the planning compute plane never receives PII\nby construction (opaque subject references and non-identifying derived\nattributes), with regime-adaptive projection, separating a public PII-free\ncompute plane from a firm-side production plane — is filed **defensively** under\nApache-2.0. The Apache-2.0 patent grant (Section 3) confers an automatic,\nperpetual, royalty-free patent license to all users, with a retaliation clause\nthat terminates that grant for any party initiating patent litigation over the\nWork.\n\n**Open Invention Network (OIN) Member** — Protocol Wealth LLC is a member of the\nOpen Invention Network (OIN). See [NOTICE](NOTICE) for the full posture.\n\n## License\n\nApache-2.0 with a defensive patent posture. See [LICENSE](LICENSE) and\n[NOTICE](NOTICE). Protocol Wealth LLC is a member of the Open Invention Network\n(OIN). Leverage it freely alongside pwos-core and nexus-core.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotocol-wealth%2Fpwplan-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprotocol-wealth%2Fpwplan-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotocol-wealth%2Fpwplan-core/lists"}