Merge remote-tracking branch 'origin/agent/flowchain-local-alpha-research' into release/flowchain-private-testnet

Author: FlowmemoryAI

chain/BRIDGE_SECURITY_RESEARCH.md

@@ -4,6 +4,14 @@ Status: research gate, no bridge implementation
 
 The local FlowMemory devnet has no live bridge and no live Base settlement. `AnchorBatchToBasePlaceholder` only models compact anchor payloads for future review.
 
+## Relationship To FlowChain Gates
+
+| Gate | Status | Bridge meaning |
+| --- | --- | --- |
+| Local/private testnet | Local-alpha target | Bridge work is limited to no-value anchor placeholders, replay-boundary docs, and fixture checks. No asset movement. |
+| Public devnet | Later research, Blocked | Public devnet may test no-value messages only after DA, replay, finality, monitoring, and emergency controls are documented. |
+| Public L1/mainnet | Explicitly later, Blocked | Any value-bearing bridge requires independent bridge/security review, incident response drills, and an accepted production decision record. |
+
 ## Bridge Assumptions To Resolve Later
 
 Before any appchain can carry value, FlowMemory must define:

docs/DECISIONS/2026-05-13-flowchain-deployment-gates.md

@@ -0,0 +1,56 @@
+# FlowChain Deployment Gates
+
+Date: 2026-05-13
+
+## Status
+
+Accepted for research and future implementation gating.
+
+## Context
+
+FlowMemory has merged V0 launch-core contracts, crypto helpers, fixture-first services, a dashboard, a no-value local devnet prototype, and guarded Base canary evidence. The research packet also includes Noesis, Rootflow, Claude/RD, Octra, FlowMemory, and FlowChain ideas that could easily be over-scoped into a public L1, token, bridge, or proof-system project before the local object model is proven.
+
+The current Ralph loop needs builders to know what is allowed now and what is later.
+
+## Decision
+
+FlowChain work must use three deployment gates:
+
+1. **Local/private testnet**: local-alpha target. This is a no-value, second-computer-validatable package for FlowMemory object-state testing. It may harden the local runtime, API, workbench, explorer, provenance, crypto vectors, operator-vault boundary, release manifest, and smoke flow after the relevant implementation agents accept scope.
+2. **Public devnet**: later research and blocked until the local/private testnet package is reproducible, monitored, exportable/importable, and reviewed. Public devnet planning may document operator roles, DA assumptions, monitoring, reset/halt policy, and threat models. It may not introduce tokenomics.
+3. **Public L1/mainnet**: explicitly later and blocked. A production or value-bearing chain requires a separate readiness program, independent reviews, bridge/DA/security work, production verifier design, incident response, governance/upgrade policy, and explicit accepted decisions.
+
+The current research task does not authorize implementation outside `research/`, `chain/` docs, or `docs/DECISIONS/`.
+
+## Alternatives Considered
+
+- **Start public devnet work immediately**: rejected because the local/private object model, challenge/finality flow, private-state boundary, and release package are not proven.
+- **Treat the Base canary as production readiness**: rejected because the canary is V0 testing evidence only.
+- **Skip local/private testnet and choose an L1 framework now**: rejected because the project has not proven that receipt, memory, dependency, verifier, challenge, and finality objects must be native chain state.
+
+## Consequences
+
+- Builders can target a local/private no-value package without importing public-network scope.
+- Public devnet and public L1/mainnet work remain blocked behind named evidence.
+- Octra-level control-plane lessons become local acceptance criteria, not a reason to chase bridge or encrypted-coprocessor scope.
+- The master L1 question remains unresolved until local evidence proves native receipt/memory state is stronger than app-level logs on an existing chain.
+
+## Scope Boundaries
+
+This decision does not approve:
+
+- production validators or sequencers;
+- tokenomics, staking, rewards, fees, slashing, or validator economics;
+- public L1/mainnet launch planning;
+- value-bearing bridge work;
+- production encrypted compute;
+- production proof systems;
+- production Uniswap v4 hook deployment;
+- hardware validator, sequencer, DA, or bridge roles.
+
+## Follow-Ups
+
+- Use `research/flowchain-local-alpha/L1_GO_NO_GO_GATES.md` as the gate checklist.
+- Use `research/flowchain-local-alpha/OCTRA_COMPETENCY_BAR.md` for the local control-plane bar.
+- Use `research/flowchain-local-alpha/BLOCKED_AND_LATER.md` before assigning implementation work.
+- Create separate implementation issues only after the owning agents accept folder scope and tests.

docs/DECISIONS/2026-05-13-flowchain-local-alpha-control-plane-boundary.md

@@ -0,0 +1,64 @@
+# FlowChain Local Alpha Control-Plane Boundary
+
+Date: 2026-05-13
+
+## Status
+
+Accepted for research and implementation gating.
+
+## Context
+
+The Octra comparison showed that an advanced chain feels credible only when its local developer and operator control plane is coherent. FlowMemory should absorb that lesson without copying Octra's bridge, token, encrypted-coprocessor, or public-network ambitions into Local Alpha.
+
+FlowMemory already has launch-core fixtures, local verifier reports, a fixture-backed dashboard, a no-value local devnet prototype, and guarded canary evidence. The missing local-alpha surface is a unified way to inspect and operate receipts, memory lineage, artifacts, verifier reports, dependencies, challenges, finality, provenance, and releases.
+
+## Decision
+
+FlowChain Local Alpha must treat the local control plane as a requirement before public appchain or L1 work resumes.
+
+The accepted local/private surface bar is:
+
+- **Wallet/operator vault**: local encrypted boundary for operator, agent, test wallet, API, hardware, and private-reference secrets.
+- **Local API**: one versioned local interface for receipts, memory, artifacts, verifiers, challenges, dependencies, finality, devnet state, and releases.
+- **Explorer/workbench**: local UI surface that explains lineage, artifact state, verifier decisions, challenge state, dependency roots, and finality without raw JSON inspection.
+- **Devnet/runtime**: deterministic no-value runtime with reset, fixture import/export, state-root visibility, failure fixtures, and release handoff.
+- **Source/provenance**: schemas, verifier modules, generated reports, fixtures, canary artifacts, release outputs, and dashboard data identify source paths, versions, hashes, and commands.
+- **Crypto vectors**: accepted ids and hashes have deterministic vectors, negative vectors, domain separation, and replay-boundary tests before library promotion.
+- **Release packaging**: local-alpha releases include commit, hashes, reproduction commands, migration notes, known limitations, and non-claims.
+
+This decision makes those surfaces Local Alpha requirements. It does not authorize implementation in this research task.
+
+## Alternatives Considered
+
+- **Choose an L1 framework first**: rejected because framework choice is premature until the local object model and control plane prove useful.
+- **Build only a chain CLI without workbench/API requirements**: rejected because receipts, memory lineage, dependencies, and challenge/finality state must be explainable to builders and reviewers.
+- **Copy Octra's bridge/encrypted-compute ambitions**: rejected because FlowMemory's near-term edge is proof-carrying memory and receipt provenance, not broad encrypted-chain parity.
+
+## Consequences
+
+- Future local/private testnet work has concrete surface acceptance criteria.
+- Public devnet and public L1 decisions remain gated behind local evidence.
+- Operator vault and private-reference work can be scoped as local safety infrastructure, not production wallet or encrypted-compute work.
+- API, explorer, provenance, vectors, and release packaging become part of the go/no-go bar, not optional polish.
+
+## Scope Boundaries
+
+This decision does not approve:
+
+- implementation outside an explicitly assigned folder and issue;
+- production wallet or custody product work;
+- hosted production APIs;
+- public RPC;
+- public validators or sequencers;
+- tokenomics, fees, rewards, staking, or slashing;
+- bridges or value movement;
+- encrypted compute;
+- production proof systems;
+- production L1/mainnet launch planning.
+
+## Follow-Ups
+
+- Use `research/flowchain-local-alpha/OCTRA_COMPETENCY_BAR.md` as the surface checklist.
+- Use `research/flowchain-local-alpha/L1_GO_NO_GO_GATES.md` before approving implementation scope.
+- Draft separate schemas for vault, private references, challenge/finality, dependency roots, and release manifests before code work.
+- Require `git diff --check` and area-specific tests in any future implementation PR.

docs/DECISIONS/2026-05-13-flowchain-proof-private-state-boundary.md

@@ -0,0 +1,59 @@
+# FlowChain Proof And Private-State Boundary
+
+Date: 2026-05-13
+
+## Status
+
+Accepted for research and implementation gating.
+
+## Context
+
+The FlowMemory research packet contains advanced ideas: Process-Witness, SEAL/dependency privacy, Synthetic Non-Amplification, proof-carrying receipts, private evidence, encrypted compute, bridge security, and future validator/sequencer economics. These ideas matter for long-term coherence, but none of them are production-ready protocol surfaces in the current repo.
+
+FlowMemory already has V0 hashes, schemas, receipts, verifier reports, local fixtures, and a no-value devnet prototype. Those are deterministic local/test artifacts, not trustless proof systems or production private compute.
+
+## Decision
+
+FlowChain may use advanced research only as gated vocabulary until prerequisites are accepted:
+
+- **Process-Witness** remains later research. Local/private work may name process obligations and verifier-module metadata, but may not build cognitive proof circuits or claim the chain proves cognition, truth, or model correctness.
+- **SEAL/dependency privacy** remains later research. Local/private work may model dependency atoms, dependency roots, dependence classes, completeness attestations, and omitted-dependency challenges in verifier-attested form before any ZK dependence proof.
+- **Synthetic Non-Amplification** is a local-alpha invariant. Synthetic data can create hypotheses, counterexamples, challenge debt, scrutiny, or validation requirements. It must not increase empirical certainty or memory trust without real-world validation, except for formal deterministic claims checked by deterministic verifiers.
+- **Proof-carrying receipts** remain later research. Local/private work should preserve stable receipt/report hashes and public-input candidates, but production circuits, contract proof verification, and trustless receipt claims are blocked.
+- **Advanced encrypted compute** is explicitly later. FHE, MPC, TEE, encrypted coprocessors, encrypted mempools, and private inference are blocked until public/private state, key custody, leakage, DA, auditability, and incident-response requirements are reviewed.
+- **Bridge security** is explicitly later for value movement. Local work may model no-value anchor placeholders and replay boundaries only.
+- **Validator/sequencer economics** are explicitly later and blocked. Non-economic operator roles may be documented for future public devnet research; staking, rewards, fees, slashing, token mechanics, or revenue claims require a separate approved scope.
+
+## Alternatives Considered
+
+- **Implement proof systems now**: rejected because public inputs, witness formats, setup assumptions, cost model, negative vectors, and challenge semantics are not accepted.
+- **Use encrypted compute to solve privacy early**: rejected because the basic public/private data model and local vault/reference boundary must come first.
+- **Treat verifier attestations as trustless proofs**: rejected because V0 verifier reports are deterministic and replayable but remain claims.
+- **Add economics to solve public operator behavior**: rejected because tokenomics is forbidden in the current scope and would obscure missing security design.
+
+## Consequences
+
+- Local/private testnet work can stay practical: deterministic fixtures, vectors, verifier reports, private references, challenges, and provenance before advanced proofs.
+- Public devnet and L1/mainnet work cannot rely on research primitives until they have accepted specs and reviews.
+- Scientific, biological, or empirical settlement claims remain blocked until real-world evidence gates and dependency policies exist.
+- The crypto library should only accept versioned, vector-backed schemas; speculative primitives stay in research.
+
+## Scope Boundaries
+
+This decision does not authorize:
+
+- crypto implementation;
+- proof circuits;
+- production encrypted compute;
+- bridge deployment;
+- tokenomics;
+- verifier economics;
+- validator or sequencer economics;
+- production L1/mainnet launch planning.
+
+## Follow-Ups
+
+- Draft dependency atom/root schemas before any dependency proof work.
+- Draft challenge/finality transitions before any downgrade-sensitive receipt implementation.
+- Keep proof public-input candidates aligned with V0 receipt and verifier report hashes.
+- Require a separate decision record before any research primitive moves into `crypto/`, `contracts/`, `services/`, `apps/`, or `crates/`.