@finchip.ai/foga 0.0.0-stage → 0.6.0-alpha.5

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Gary Yang (FinChip)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,21 @@
+Finch OG Agent (FOGA)
+Copyright 2026 Gary Yang (FinChip)
+
+This product includes compiled artifacts (artifacts/bundle.json) built from the following
+reference implementations, which are not modified by this project and remain under their
+own licenses:
+
+  skill-token-standard      (ERC-8338)  CC0-1.0   https://github.com/garyyang-finchip/skill-token-standard
+  task-token-standard       (ERC-8414)  CC0-1.0   https://github.com/garyyang-finchip/task-token-standard
+  kya-standard              (ERC-8419)  CC0-1.0   https://github.com/garyyang-finchip/kya-standard
+  aid-standard              (ERC-8434)  CC0-1.0   https://github.com/garyyang-finchip/aid-standard
+  acd-framework             (ERC-8436)  CC0-1.0   https://github.com/garyyang-finchip/acd-framework
+  ard-onchain-framework     (ERC-8444)  CC0-1.0, with Apache-2.0 material vendored upstream from the ards-project
+                                                  https://github.com/garyyang-finchip/ard-onchain-framework
+  swarm-ai-framework        (ERC-8447)  CC0-1.0   https://github.com/garyyang-finchip/swarm-ai-framework
+  aifi-unit-framework       (ERC-8454)  CC0-1.0   https://github.com/garyyang-finchip/aifi-unit-framework
+  agent-safety-framework    (ERC-8468)  CC0-1.0   https://github.com/garyyang-finchip/agent-safety-framework
+  ai-dispute-resolution     (ERC-8471)  CC0-1.0   https://github.com/garyyang-finchip/ai-dispute-resolution
+
+The exact commits are recorded in vendor/LOCK.json. The Groth16 verifier compiled from
+kya-standard's companion circuit is generated code (snarkjs) distributed with that repository.

package/README.md

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+# Finch OG Agent (FOGA)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+FOGA is a reference autonomous agent built on ten Ethereum ERC drafts written by the same author:
+
+| ERC | Title | Role in a cell |
+|---|---|---|
+| ERC-8338 | Token-Bound Executable Skills | what a cell can execute (hash-verified skill packages) |
+| ERC-8414 | Token-Bound Task Tenders | the work a cell takes or offers (escrowed tenders) |
+| ERC-8419 | Know-Your-Agent (KYA) Framework | how a cell proves facts about itself (attested and ZK-proved assertions) |
+| ERC-8434 | Agent Identity (AID) | the address-anchored identity and liveness of a cell |
+| ERC-8436 | Agent Collective Decision Framework (ACDF) | how cells decide together (authorized K-of-N decisions with finality) |
+| ERC-8444 | Agentic Resource Discovery (ARD) Onchain | how cells, skills and tasks are found |
+| ERC-8447 | Swarm AI Framework (SAI) | how cells organize into purpose-bound swarms |
+| ERC-8454 | AIFi Unit Framework (AUF) | the economic boundary and measurement of a cell or swarm |
+| ERC-8468 | Agent Safety Framework (ASF) | the safety specifications a cell adopts and the interventions it must honor |
+| ERC-8471 | AI Dispute Resolution Framework (ADRF) | how claims about a cell's conduct are filed, ruled on and enacted |
+
+ERC-8004 (Trustless Agents) is a required dependency: ERC-8419, ERC-8434 and ERC-8447 bind to its Identity Registry.
+
+The project delivers three things from one kernel: the **Finch OG Agent** (the first running instance), the **FOGA node software** anyone can run with their own identity, model and wallet, and a **public access layer** (MCP, A2A, HTTP/CLI). It is built in phases; this repository has completed **Phase 2c: the genesis on a public chain**, on top of the Phase 2 genesis (T0–T9) and the Phase 1 world layer.
+
+## Status: Phase 3c done — Loop D, the unscripted run (3c); Phase 3b done — the node served over MCP and HTTP; Phase 3a done — the kernel hardened and turned into a node with a capability catalog; Phase 2c done
+
+**3c (0.6.0-alpha.4, 2026-11-02).** A model in the loop, and the acceptance that looks at records rather than words. `src/node/runner.ts` is the node's loop with a model: each tick perceives through the read capabilities, hands the situation and the catalog as tools to the model, carries out what it proposes — reads at once, acts through `Catalog.invoke` where the three checks decide and a refusal goes back so the model can revise once — and records the tick by hash (the decision records carry the model and the hashes of its request and answer; the journal the hash of the whole transcript; the text never). Limits bound a tick (12 tool calls, 2 acts) and a day (the model's calls, counted in the store). Two adapters on one interface: `anthropic` (the Messages API over `fetch`, the key in the environment, the model name in the configuration) and `stub` (a deterministic decision table that also proposes, once, a tender above the budget so the evidence shows the gate closing). `foga node run` is the embedded node — server, watchers, runner — on the operator key alone. `foga demo --loop-d` (`src/demo/loop-d.ts`) is the unscripted run: a new cell with fresh keys, an independent demander process minting cases a–f in a seeded order (two tenders to take, four to refuse at `skill`, `policy`, `verifier`, and one met during the guardian's suspension), the node killed after its first submission and restarted, the HTTP entrance used beside the runner (the same request answered once, the same job under another request a conflict, three mints at once of which the third is refused at `budget` before anything is sent), and an evidence file with every record, the cases' outcomes and a scan of every transaction the operator key signed. `foga doctor --loop-d` judges it beside layer 5: every operation under an allowed decision, refusals that broadcast nothing, the four budget books, the operator's transactions all at the account and allow-listed, the cases as expected, the recovery, the entrances, and — given two runs — the same outcomes from the stub and a real model. The slice also closed a race the run exposed: the catalog's decision section now runs one act at a time per node and a job reserves the value it will move from its decision. `test/loop-d.test.ts` (anvil, under a minute) and `test/model.test.ts` are the gate; CI runs Loop D on the world the genesis ran on. docs/loop-d.md.
+
+**3b (0.6.0-alpha.3, 2026-11-02).** The catalog gets its second and third entrances. `src/mcp/server.ts` builds one MCP server per caller from the catalog with the official TypeScript SDK v2: the tool list is what the caller may see and do (a write capability is up to three tools over one handler — `<name>` acts, `<name>_simulate` runs every check and sends nothing, `<name>_build` returns the calls for the caller's own account — with static annotations), results are `structuredContent` under the capability's output schema, a refused act is a tool error carrying the gate, the reason and the decision record's id, an ineligible pre-check an ordinary `eligible: false`; resources for the world, the cell, the policy, the FOGA-Cell-v1 specification and the compatibility matrix; one prompt. Both protocol eras are served on both transports — the 2026-07-28 revision (`server/discover`, no session) as the main path and the 2025-era `initialize` handshake in stateless form — and `foga node mcp` serves a local client over stdio (the operator with the key, a build-level local user without). `src/http/server.ts` is the HTTP entrance on `node:http`: `/mcp` over Streamable HTTP, `POST /api/<capability>`, the health and front pages, the public without a credential (reads and builds) and `Authorization: Bearer <key>` for a grant the operator minted with `foga node key new` (stored as its hash alone); the edge checks Host, Origin, body size, content type and a per-address rate, maps permission refusals to 403 and business refusals to `200 {ok: false, gate, reason, decisionId}`. `foga node serve` runs it with the watchers beside it. The gate of the slice is `test/mcp.test.ts`: on anvil, the reference client pinned to 2026-07-28, in legacy mode and in auto mode, over HTTP and stdio — the public's tools, the key holder walking a tender from pre-check to settlement with the reward reaching the account, idempotency and conflict on the wire, every edge refusal. `scripts/pack-smoke.mjs` (a CI step) installs the npm tarball in a clean directory and runs the packaged CLI and MCP server from there; `package.json` carries `mcpName` and `server.json` the registry manifest for the publication in 3d. docs/mcp.md.
+
+**3a-2 (0.6.0-alpha.2, 2026-11-02).** The kernel becomes a node other agents can call. `src/tools/` is the capability catalog — 28 capabilities on the Loop D path, each declaring its action (read, build, act, admin), the visibility of its data (public, caller, operator) and whose act it is — and `Catalog.invoke` is the one place authorization happens: call permission, business authorization through the policy engine (anchor and binding, skill held and offered, reward and deadlines, acceptance authority, budget), wallet permission by simulating the account's own gate; every attempt to act, allowed or refused, is a decision record naming the gate. Jobs are the business unit and operations the chain writes under them; the same job is answered once, a failed one with its failure, the same job under another request as a conflict. `src/node/` is the runtime: one `cell.config.json`, the node over the kernel holding the operator key alone, `foga cell init` (a cell's birth from its config, T1 for one cell), `foga cell migrate` (the move to a new revision-2 account, T9 for one cell), the watchers (heartbeat, tender discovery, settlement, safety). The CLI (`foga cell …`, `foga node …`) is generated from the catalog. The gate of the slice is `test/node-cli.test.ts`: on anvil, through the CLI and without the genesis script, a cell is born, mints its skills and meets the seven Loop D cases — two tenders taken and settled, five refused at the right gate (skill, policy, verifier, safety during a suspension and allowed after the resume, budget) — then moves to a new account. docs/node.md.
+
+**3a-1 (0.6.0-alpha.1, 2026-11-02).** Phase 3 turns the kernel into a node other agents can call, and its first slice gives the kernel what a public service needs and a scenario driver did not: `FogaCellAccount` revision 2 — the operator may call only what the owner allow-listed, never an asset-moving selector, and signs for the account only when enabled and the gate is satisfied; a node holds one key, its cell's operator, and refuses an environment from which any other role could be derived (`foga keys export`, `foga keys check`); the transaction manager counts fee replacements on the row so the limit holds across restarts, caps fees, runs one signer's operations one at a time, binds a key to the hash of its request (another request under the same key is a conflict), and answers a failed operation with its failure until it is retried explicitly; jobs sit beside operations in the store; the skill worker runs both executors out of process under Node's permission model. All of it is tested offline against an in-process chain (`test/tx-semantics.test.ts`) and by the genesis on anvil, which now opens each cell's scope itself (193 operations, 166 checks). docs/kernel.md, docs/cell-account.md, docs/design-memo.md (section 9) and the changelog have the detail; what 3a-2 to 3d add is in the memo.
+
+**The Sepolia run (0.5.0, 2026-11-01).** World `sepolia-11155111-20261101T043153Z`: the 35 upstream reference deployments attached, 15 contracts added from the bundle by W, the official ERC-8004 registry. The genesis T0–T9 ran from the project's EC2 against a public RPC: 203 operations in blocks 12038641–12040082, three cells born (ERC-8004 agents 11255–11257), A's skills minted and run for B's tender, the swarm formed and paid on a council-judged tender, the dispute refunded by the escrow, the guardian's stop enforced at the gate, the measurements asserted, A's identity moved to A-prime. The doctor on the completed world: Pass 234, Fail 1 (the ARD fixture registry's known older source), Unknown 2, all eleven standards Pass on layer 5. The three files are committed: `deployments/sepolia.example.json` (the world), `deployments/sepolia.genesis.example.json` (the evidence: checks, facts, per-step evidence, the journal of the whole run including its resumes) and `deployments/sepolia.doctor.example.json`. What the run taught — a public RPC cluster's nodes disagree for a second after every block, Sepolia's repriced gas schedule charges 4.4 times anvil's figures (586 M gas for world and genesis), a replay must read the chain at its head — is in docs/genesis.md ("The Sepolia run"), docs/kernel.md and the 0.5.0 changelog; the gas budgets of the roles are now the measured Sepolia figures with a margin.
+
+Built for 2c (0.5.0-alpha.1 to alpha.9):
+
+- **The same scenario on a public chain.** `foga world deploy` on the Sepolia config attaches the upstream reference deployments and adds, from the same bundle, what their records do not provide at the locked revision (the ERC-8471 stack, deployed upstream at revision 3 which a revision-4 escrow cannot be bound to, and the two ERC-8447 eligibility modules never deployed upstream), with W as deployer. Cells keep their liveness in two ERC-8434 registries where the world names a backing one (Sepolia's ARD agent kind is anchored to ARD's own fixture registry). T7 makes an anchor STALE by shortening its own liveness window and waiting, the same way on every chain.
+- **Twelve keys from one phrase, one treasury.** `foga keys new` writes a BIP-39 phrase outside the repository and prints the role addresses; only W is funded by hand — before every step W tops up each role below half its floor (a gas budget measured on Sepolia, priced at the chain's current fee) and gives each cell its capital at birth. `foga genesis preflight` prints the plan, the escrow's admin, the proving material and the waits, and sends nothing; `foga world deploy` checks the deployer's balance before the first deployment.
+- **Public-chain transaction handling.** Public endpoints are polled every 4 s; a transaction still pending after the 120 s receipt wait is replaced under the same nonce with fees raised by a third, up to three times, and a resumed run recognizes whichever of an operation's transactions was mined. Every state read is pinned to the highest block the kernel has seen, so a node of the RPC cluster that has not imported the last block answers with an error that is retried, never with stale state.
+- **Rehearsed before it is run.** CI builds an attach-mode world on anvil from a deployed local one (`scripts/attach-rehearsal.mjs`: address book attached, 15 contracts added by `foga world deploy`, a second AIDRegistry as backing registry), runs the preflight, the genesis T0–T9 and the doctor on it: 171 checks, all eleven standards Pass. The public timing profile (about fifty minutes of waiting over T5–T7) and the Sepolia runbook are in docs/genesis.md, "Running on a public chain".
+
+From 2b (0.4.0-alpha.1):
+
+- **The predicate-pattern ZK path.** FOGA's own circuit `kya_predicate_count_v1` (8 record slots, source set of depth 16) proves "at least K task-completion records about me, signed by a source of the committed set, are Accepted inside a window" without revealing the records; `Groth16PredicateKYAVerifierAdapter` admits it as scheme `S_pred`. A proves its first completion at the end of T3; a false predicate (K = 2 with one completion) is refused by the adapter, a flipped result bit by the verifier, replays and stale epochs by the registry. The proving material is built locally by a deterministic development ceremony (`npm run zk:predicate`; CI rebuilds it on a cache miss and checks the committed verifier against it). docs/zk.md.
+- **T6 — dispute.** C buys a run of A's skill through the world's ERC-8471 service escrow, bound in T0 to FOGA-Service-v1; A publishes v2 and delivers it against terms committing v1; C files; the declared-version verifier answers the formal question, FOGA-Council the judged one through the bridge; the ruling is Final Sustained and the escrow enacts the refund once. A control call committed to v2 settles and is released.
+- **T7 — safety.** The guardian suspends A; a transaction sent around the kernel fails on chain at the account's gate; the allow-listed de-risk withdrawal passes; the operator's direct submission is accepted by the chain but not attributable to the cell; a fresh binding does not escape the intervener's standing stop; after `resume` A works again; a STALE anchor stops commitment-class calls until the next heartbeat.
+- **T8 — measurement.** E registers `foga.realized-net-cash-flow/1` and asserts observation receipts for cell A and for the swarm: settled inflows inside each boundary, gas as the cost, unobservable items as missing, never a value; a deterministic resolver recomputes them from the chain and fails a receipt that counts the swarm's tender for A or cites an unregistered method.
+- **T9 — succession.** A moves its ERC-8004 agent to A-prime through its account: A turns STALE, A-prime takes the binding over, A retires naming its successor, A-prime publishes a new record and document, the skill follows and its record is adopted again by recommitment; standing, swarm seat, unit and binding are not inherited.
+- **Doctor layer 5.** `foga doctor --genesis <evidence.json>` turns the genesis checks into per-standard verdicts; the demo runs it after the genesis.
+- 187 operations, 166 checks, all green on anvil in about 100 s (five Groth16 proofs); every step resumes after an injected crash, and a replayed run re-checks what still holds and records the rest as skipped.
+
+From 2a-2 (0.3.0-alpha.1):
+
+- **T4 — organization.** W tenders a judged task; B forms a swarm bound to it (coordinator and two workers under a composite eligibility: registered ERC-8004 agent, ACTIVE anchor, attested standing ≥ 2); A and C join through their accounts; the swarm account is bound; the swarm becomes an AUF unit containing the members' units at pinned versions. A stranger's join is refused; a revoked assertion suspends a member on challenge and a fresh one reinstates it.
+- **T5 — governance.** The swarm account submits the `finch-extract-verify` report (deterministic path over a pinned fixture); the FOGA-Council (three judges, two decide) accepts it through FOGA's instance of the upstream `ACDFTaskTenderAdapter`; the workers amend the charter through the `SwarmDecisionAdapter`; a second case ends without a decision and the tender's own `claimUnjudged` pays after the window; the swarm concludes ACHIEVED. Wrong-round ballots, non-judge ballots, premature or repeated execution are refused.
+- **The credential-pattern ZK path.** A's standing is also proved in zero knowledge: W's attestor signs a credential over A's commitment, A proves it for this registry and epoch (Groth16, `kya-public-v1`), and FOGA's own `Groth16KYAVerifierAdapter` admits it as issuer of record. Replayed, re-targeted and stale-epoch proofs are refused. The prover lives in `prover/`, a sub-package over the upstream prover (`npm run zk:install`).
+- 125 operations, 89 checks, all green on anvil in about 40 s; every step resumes after an injected crash.
+
+From 2a-1 (0.2.0):
+
+- **FogaCellAccount** (`contracts/src/FogaCellAccount.sol`, 15 Foundry tests). The body of a cell: anchor, ERC-8004 owner, asset holder, fulfiller, adopter, subject and controller in one contract account, with the ERC-8468 execution gate (no path around it), owner/operator/guardian/recovery roles, operator scope (expiry, daily value cap), an AID-state gate for commitment-class selectors, ERC-1271 and the token receiver hooks. docs/cell-account.md.
+- **foga-core** (`src/core/`). One module per ERC — views, calldata builders, event decoders — plus RFC 8785 canonicalization and a byte-exact port of the ERC-8338 DAG-CBOR packager (verified against the upstream vectors).
+- **foga-kernel** (`src/kernel/`). An operation store on `node:sqlite`, a transaction manager that sends each keyed operation exactly once and recovers by hash and nonce after a crash, cells driven through their accounts, facts, evidence and a revert decoder across every ABI. docs/kernel.md.
+- **The genesis, T0–T3** (`src/genesis/`, `foga genesis run`). World registrations (two KYA schemes, the FOGA-Cell-v1 safety specification); three cells born with their bindings, ERC-8004 identities, AID anchors and documents, attested standing, ARD records and AUF units; two real skill packages minted by A; a hashlock tender from B that A discovers, pre-checks, fulfils in an isolated worker, settles and is paid for. 73 operations, 50 checks, all green on anvil; the memo's loop-C cases (crash after submit, crash before broadcast, duplicate run, reset chain) are reproduced in CI. docs/genesis.md.
+
+From Phase 1, unchanged in substance:
+
+- **Locked sources.** `vendor/LOCK.json` pins the ten reference implementations by commit. `foga vendor sync` materializes them; nothing is modified downstream.
+- **One artifact bundle.** `foga build` compiles all ten with their own compiler settings (five profiles on solc 0.8.24, three on 0.8.30, two solc-js repositories mirrored on 0.8.28) into `artifacts/bundle.json`: ABIs, creation and runtime bytecode, link and immutable references, compiler metadata, ERC-165 ids computed from the AST and cross-checked against the upstream vectors (all published ids match). `foga build --verify` rebuilds and proves the hash.
+- **One-command world.** `foga world deploy` deploys the whole stack in dependency order — 47 contracts including external libraries and the ERC-8471 module router — and registers the four ARD kinds. Local worlds use `contracts/src/Identity8004Stub.sol` as a clearly labeled stand-in for the ERC-8004 Identity Registry; public worlds attach the official registry.
+- **The doctor.** `foga doctor` reports five layers per contract — chain and code, interfaces, version match, configuration and permissions, semantic validation — with the verdicts Pass / Fail / Unknown / Not tested / Not applicable. Layers 1–4 probe the chain; layer 5 reads the genesis evidence. A doctor run can be exported as a JSON-RPC probe plan and replayed from results collected elsewhere, so a report never depends on which machine can reach which RPC.
+- **Sepolia address book.** `worlds/sepolia.json` records every upstream reference deployment at its deployed revision, including the three seams the inventory found (docs/version-lock.md); the completed world and the doctor's report on it are the 2c files above.
+
+What is next: 3d closes Phase 3 — A2A, the documents, `foga quickstart`, the npm and registry publication, the OG instance's move to a revision-2 account with public endpoints and a real model's Loop D run on Sepolia; Phase 4 the hosted node and payments. The design is in docs/design-memo.md.
+
+## Quick start
+
+Three ways in, from most to least demanding:
+
+```bash
+# 1. Full reproduction (needs git, Node >= 22 and Foundry):
+npm ci
+npm run vendor:sync          # fetch the ten repositories at the locked commits
+npm run bundle:verify        # rebuild artifacts/bundle.json and compare its hash
+npm run test:contracts       # Foundry tests for FogaCellAccount and the ERC-8004 stand-in
+npm run zk:install           # proving libraries for the ZK paths (prover/, separate from the kernel's dependencies)
+npm run zk:predicate         # build FOGA's predicate circuit and its development proving key (10-60 min, once; optional)
+npm run demo:genesis         # anvil + world deploy + doctor + genesis T0-T9 + doctor layer 5, all local
+
+# 2. World and genesis only (Node >= 22 and Foundry's anvil, no Solidity build; the ZK paths are left out without their material):
+npm ci && npm run demo:genesis
+
+# 3. Containers (Docker with Compose):
+docker compose up --build     # anvil + world + doctor + genesis; outputs land in ./deployments
+```
+
+The genesis against a running node, step by step:
+
+```bash
+npm run foga -- world deploy --world worlds/local.json --rpc http://127.0.0.1:8545 --out deployments/local.json
+npm run foga -- genesis run --world deployments/local.json --rpc http://127.0.0.1:8545 --until T9
+npm run foga -- genesis status --world deployments/local.json         # the operation store
+npm run foga -- doctor --world deployments/local.json --genesis deployments/local.genesis.json   # layer 5 from the evidence
+```
+
+Interrupt and resume (the same command again replays what was done and continues). `demo --keep` leaves its anvil running in the background and returns:
+
+```bash
+npm run foga -- demo --keep --genesis T2                                                           # chain, world, doctor, T0-T2
+npm run foga -- genesis run --world deployments/local.json --until T9 --crash-after T3.A.submit   # exits 75 after the submit is broadcast
+npm run foga -- genesis run --world deployments/local.json --until T9                              # recovers the submit by hash, settles, carries on
+```
+
+Against a running node:
+
+```bash
+npm run foga -- world deploy --world worlds/local.json --rpc http://127.0.0.1:8545 --out deployments/local.json
+npm run foga -- doctor --world deployments/local.json --rpc http://127.0.0.1:8545 --out deployments/local.doctor.json
+```
+
+Against Sepolia (needs an RPC that the machine can reach). The read-only doctor on the attached address book:
+
+```bash
+FOGA_RPC_URL=$SEPOLIA_RPC_URL npm run foga -- doctor --world worlds/sepolia.json --attach --out deployments/sepolia.doctor.json
+```
+
+The genesis there — one phrase for the twelve roles, W funded by hand, the world completed from the bundle, the preflight, then the run (1.5–2.5 h with the public windows; the same command resumes an interrupted run):
+
+```bash
+npm run foga -- keys new                                   # writes ~/.foga/genesis.mnemonic, prints the addresses; fund W
+export FOGA_MNEMONIC_FILE=~/.foga/genesis.mnemonic
+npm run foga -- world deploy --world worlds/sepolia.json --rpc $SEPOLIA_RPC_URL
+npm run foga -- genesis preflight --world deployments/sepolia.json --rpc $SEPOLIA_RPC_URL
+npm run foga -- genesis run --world deployments/sepolia.json --rpc $SEPOLIA_RPC_URL --until T9
+npm run foga -- doctor --world deployments/sepolia.json --rpc $SEPOLIA_RPC_URL --genesis deployments/sepolia.genesis.json
+```
+
+Or in two steps through any relay that has an RPC — export the plan here, collect results there, evaluate anywhere:
+
+```bash
+npm run foga -- doctor --world worlds/sepolia.json --attach --export-probe sepolia.probe.json
+node scripts/relay.mjs $SEPOLIA_RPC_URL sepolia.probe.json > sepolia.results.json
+npm run foga -- doctor --world worlds/sepolia.json --attach --import-results sepolia.results.json --out deployments/sepolia.doctor.json
+```
+
+Offline builds: if the machine cannot reach the solc binary mirror, download the three static binaries from the Solidity GitHub releases with `scripts/install-solc.sh` and export `FOGA_SOLC_DIR`.
+
+Older Linux (Amazon Linux 2 and 2023, CentOS 7, Debian 11, …): the regular Foundry binaries need glibc 2.35 and fail with ``version `GLIBC_2.35' not found``. `scripts/install-foundry.sh` installs the statically linked build of the pinned release (v1.7.1) into `~/.foga/foundry`; export `FOGA_FOUNDRY_DIR=~/.foga/foundry` for `foga demo`, or put that directory first on `PATH` to use its anvil, forge and cast everywhere.
+
+## Layout
+
+```
+artifacts/           bundle.json (+ .sha256): the compiled ten-ERC stack and FOGA's contracts, committed and CI-verified
+build/               build profiles per repository and the README-published interface ids
+contracts/           FOGA's own contracts: FogaCellAccount, Identity8004Stub (local stand-in), zk/ (the predicate verifier and its KYA adapter), Foundry tests
+deployments/         world files, doctor reports, genesis evidence (local outputs are gitignored; examples are kept)
+prover/              the ZK proving sub-package: run.cjs bridge (credential and predicate proofs), build-predicate.mjs (the development ceremony), its own dependencies
+zk/                  circuits/ (kya_predicate_count_v1.circom) and build/ (verification_key.json committed; the proving key is rebuilt locally)
+docker/, docker-compose.yml
+docs/                design memo, compatibility matrix, version lock, build, world, doctor, cell account, kernel, genesis, zk, node, mcp, loop-d; examples/ (client configurations)
+scenarios/skills/    the two ERC-8338 skill packages of the genesis: foga-probe, finch-extract-verify
+scenarios/fixtures/  the pinned document finch-extract-verify works on in T5 and T7
+scripts/             install-solc.sh, install-foundry.sh, relay.mjs, pack-smoke.mjs (the npm tarball run from a clean install)
+src/                 TypeScript: build/ (vendor + bundle), world/ (plan + deploy), doctor/ (probe + evaluate),
+                     core/ (foga-core: one module per ERC incl. acdf, adrf and swarm, measure, canonicalization, DAG-CBOR packager),
+                     kernel/ (store, transaction manager, cell, kernel), genesis/ (roles, operator scope, probe, extract, skill worker, zk, scenario T0-T3, t3-zk, t4..t9, runner),
+                     tools/ (the capability catalog: types, catalog, read, tenders, identity, admin), node/ (config, keys, node, policy, init, migrate, watchers),
+                     mcp/ (the MCP server built from the catalog), http/ (the HTTP API, MCP over Streamable HTTP, API keys),
+                     node/runner.ts and node/model/ (the runner, the stub and anthropic adapters), demo/ (the Loop D demander, orchestration and evidence),
+                     cli.ts, cli-cell.ts (foga cell / foga node)
+test/                unit tests: bytecode and interface ids, skill packages, canonicalization, operation store, transaction semantics against an in-process chain (mock-chain.ts), keys, policy gates, catalog, cell config, swarm/ACDF vectors, extractor, measurement resolver, doctor layer 5; node-cli.test.ts (the Loop D cases through the CLI on anvil), mcp.test.ts (the entrances over MCP and HTTP on anvil; helpers/anvil-cell.ts births the cell), model.test.ts (the stub's table, the Anthropic adapter against a stand-in API, the Loop D verdicts), loop-d.test.ts (the unscripted run with the stub on anvil)
+vendor/              LOCK.json (sources are materialized here and gitignored)
+worlds/              world configs: local.json (deploy), sepolia.json (attach)
+```
+
+## Commands
+
+```
+foga vendor sync | verify
+foga build [--verify] [--solc-dir <dir>] [--only <repo,repo>]
+foga bundle info
+foga world deploy --world <config> [--rpc <url>] [--out <file>] [--resume] [--gas-multiplier <x>] [--allow-chain-mismatch]
+foga world attach --world <config> [--out <file>]
+foga doctor --world <world|config> [--attach] [--rpc <url>] [--out <report>] [--export-probe <file>] [--import-results <file>] [--genesis <evidence>]
+foga probe relay-script
+foga genesis run --world <world> [--rpc <url>] [--until T0..T9] [--store <file>] [--out <evidence>] [--zk auto|require|skip] [--crash-after <key>] [--crash-before <key>]
+foga genesis status --world <world> [--store <file>]
+foga keys new [--out <file>] | show | export --role <role> [--out <file>] | check
+foga demo [--port <n>] [--keep] [--genesis <T0..T9>]
+foga cell list [--public] | schema <capability>
+foga cell new --name <cell> --world <world.json> --store <ops.sqlite> --owner <addr> --operator <addr> --guardian <addr> --out <cell.config.json>
+foga cell init --config <cell.config.json> [--capital-wei <n>]          (owner key)
+foga cell migrate --config <cell.config.json> --to <new.config.json> [--operator <addr>]   (owner key)
+foga cell <capability> --config <cell.config.json> [--mode simulate|build|act] [--<field> <value> ...] [--json '<input>']
+foga node tick | watch --config <cell.config.json> [--interval <s>]      (operator key alone)
+foga node mcp --config <cell.config.json>                                 MCP over stdio (= foga mcp; the operator with FOGA_OPERATOR_KEY[_FILE], reads and builds without)
+foga node serve --config <cell.config.json> [--listen <host:port>] [--no-watch]   the HTTP API, /mcp over Streamable HTTP, /healthz, the watchers
+foga node key new --config <cell.config.json> --id <id> [--level read|build|act] [--visibility public|caller|operator] [--note <text>]
+foga node run --config <cell.config.json> [--model stub|anthropic] [--listen <host:port> | --no-http] [--interval <s>] [--once | --ticks <n>] [--transcripts <dir>]
+                                                                          the embedded node: server, watchers and the runner (operator key alone)
+foga demo --loop-d [--model stub|anthropic] [--model-name <name>] [--seed <n>] [--no-recovery]   anvil, the world, then Loop D judged by the doctor
+foga loop-d run --world <world.json> --rpc <url> [--dir <dir>] [--out <evidence.json>] [--model] [--model-name] [--seed] [--no-recovery]
+foga doctor [--world <world.json>] --loop-d <evidence.json> [--compare <evidence2.json>] [--out <report.json>]
+```
+
+During development the CLI runs from source with `npm run foga -- <args>`; `npm run build` compiles it to `dist/` for the `foga` binary.
+
+## Principles
+
+- The ten reference implementations are used as they are. Gaps found while composing them go back upstream as separate changes; FOGA keeps no forks.
+- Compile conditions are never changed by FOGA, only orchestrated. The bundle records compiler, settings, source hashes and build inputs so anyone can rebuild it.
+- A world file names its chain, its bundle hash, its deployment batch and, for forks, the source block, so two local chain-id-31337 worlds cannot be confused.
+- Every claim the doctor makes carries one of five verdicts; a green ERC-165 probe is never presented as full compatibility.
+- A cell acts only through its account, and the account acts only through its gate. The kernel sends every operation once, records it before broadcasting it, and asks the chain before retrying.
+
+## License
+
+Apache-2.0 for the code in this repository. The compiled artifacts in `artifacts/bundle.json` are built from the upstream repositories, which are CC0-1.0 (ARD material vendored upstream is Apache-2.0); see NOTICE.