Add runtime-backed FlowChain RPC e2e

Author: FlowmemoryAI

docs/FLOWCHAIN_CONTROL_PLANE_API.md

@@ -53,6 +53,11 @@ devnet/local/intake/transactions.ndjson
 devnet/local/intake/bridge-observations.ndjson
 ```
 
+`transaction_submit` can also be asked to forward a valid local devnet transaction
+into the active Rust runtime state with `runtimeSubmit: true` or
+`runtimeSubmitMode: "direct"`. That mode is still local-only, but it proves the
+RPC can drive the same state file that block production reads.
+
 All JSON-RPC responses and local intake payloads are scanned for private-key, mnemonic, seed phrase, RPC credential, API key, and webhook-shaped material.
 
 ## JSON-RPC Envelope
@@ -289,11 +294,16 @@ Params:
     },
     "signature": "0x..."
   },
-  "submittedBy": "local-operator"
+  "submittedBy": "local-operator",
+  "runtimeSubmit": true
 }
 ```
 
-Accepts signed local test transaction envelopes only. Plain `transaction`, `tx`, or `txs` params are rejected. The method rejects secret-shaped material and appends an intake row to `devnet/local/intake/transactions.ndjson`. It does not broadcast to a public chain.
+Accepts signed local test transaction envelopes only. Plain `transaction`, `tx`,
+or `txs` params are rejected. The method rejects secret-shaped material and
+appends an intake row to `devnet/local/intake/transactions.ndjson`. With
+`runtimeSubmit` enabled, the contained devnet `tx` is also submitted directly to
+the active local Rust runtime state. It does not broadcast to a public chain.
 
 ### `mempool_list`
 

docs/agent-goals/production-l1-live-chain/README.md

@@ -1,4 +1,4 @@
-# FlowChain Production L1 Live-Chain Goal Pack
+# FlowChain Guardrailed Live-Chain Build Goal Pack
 
 Status: copy-ready `/goal` prompts for agents building FlowChain from the
 current local/private runtime and capped owner pilot into a complete runnable
@@ -62,4 +62,3 @@ Launcher:
 ```powershell
 powershell -ExecutionPolicy Bypass -File .\infra\scripts\launch-production-l1-live-chain-goals.ps1 -DryRun
 ```
-

fixtures/bridge/local-runtime-bridge-handoff.json

@@ -1,6 +1,6 @@
 {
   "schema": "flowmemory.bridge_runtime_handoff.v0",
-  "handoffId": "0x29cf06d9ffbfff9538a38f5055122f0c8801df516b70d2d2a2bd0937cd1dea9f",
+  "handoffId": "0x78dd7a25f55ab00e62fad047f9f7b5e39233b47163e85b3a57b5b1867c735829",
   "generatedAt": "2026-05-13T00:00:00.000Z",
   "mode": "mock",
   "productionReady": false,
@@ -74,7 +74,7 @@
   "withdrawalIntents": [
     {
       "schema": "flowmemory.bridge_withdrawal_intent.v0",
-      "withdrawalIntentId": "0x6ae5f8a744eb711ef791e5c5b9b6e01b94a84e3fa668ce67484040e8fe564ffa",
+      "withdrawalIntentId": "0x7183c023e4fdec83362cfcf1d195bc97fad6ad3f3abc4a1af320c3354315b3aa",
       "creditId": "0xff3efb8221533cfc836bffbcee10bdd2d7d4a5615efce9516574245a3b7d74a6",
       "depositId": "0x7e3a7f7ab7dc9b07d762c1f2fce315cf0c08f1a7e854b4dbcb2359efcb9cb269",
       "sourceChainId": 84532,
@@ -123,9 +123,9 @@
   "releaseEvidences": [
     {
       "schema": "flowmemory.bridge_release_evidence.v0",
-      "releaseEvidenceId": "0x486e8abfce6246093c96114e1af34cb3c8c1afd9646766a584b2dee8296c2d97",
+      "releaseEvidenceId": "0xf0f06391f74c94c8331b684073967e28946adca4e3ecd7a7f2b27eece495fe23",
       "generatedAt": "2026-05-13T00:00:00.000Z",
-      "withdrawalIntentId": "0x6ae5f8a744eb711ef791e5c5b9b6e01b94a84e3fa668ce67484040e8fe564ffa",
+      "withdrawalIntentId": "0x7183c023e4fdec83362cfcf1d195bc97fad6ad3f3abc4a1af320c3354315b3aa",
       "creditId": "0xff3efb8221533cfc836bffbcee10bdd2d7d4a5615efce9516574245a3b7d74a6",
       "depositId": "0x7e3a7f7ab7dc9b07d762c1f2fce315cf0c08f1a7e854b4dbcb2359efcb9cb269",
       "sourceChainId": 84532,
@@ -142,7 +142,7 @@
         "recipient": "0x4444444444444444444444444444444444444444",
         "token": "0x3333333333333333333333333333333333333333",
         "amount": "20000000",
-        "evidenceHash": "0x871d7552d22b7e2d0d1dfef570a8bcecccd11afef217a71dca1a37aae02ccb3a",
+        "evidenceHash": "0x7009968cfb7edf56372f45f0f5659238c124551b4a8773b2b86f0acf7643ae3e",
         "broadcast": false
       },
       "operatorNote": "Pilot release evidence only. Review before any separate release-authority transaction; this relayer does not broadcast.",
@@ -188,7 +188,7 @@
     {
       "phase": "withdrawal_requested",
       "status": "requested",
-      "objectId": "0x6ae5f8a744eb711ef791e5c5b9b6e01b94a84e3fa668ce67484040e8fe564ffa",
+      "objectId": "0x7183c023e4fdec83362cfcf1d195bc97fad6ad3f3abc4a1af320c3354315b3aa",
       "title": "Withdrawal requested",
       "summary": "Test-mode local-to-Base withdrawal intent recorded with no broadcast or real release."
     }
@@ -250,9 +250,9 @@
     },
     {
       "sectionKey": "transactions",
-      "id": "0x6ae5f8a744eb711ef791e5c5b9b6e01b94a84e3fa668ce67484040e8fe564ffa",
+      "id": "0x7183c023e4fdec83362cfcf1d195bc97fad6ad3f3abc4a1af320c3354315b3aa",
       "kind": "Bridge withdrawal intent",
-      "title": "0x6ae5f8a744eb711ef791e5c5b9b6e01b94a84e3fa668ce67484040e8fe564ffa",
+      "title": "0x7183c023e4fdec83362cfcf1d195bc97fad6ad3f3abc4a1af320c3354315b3aa",
       "summary": "Test-mode withdrawal intent recorded; no mainnet or real-funds release is broadcast.",
       "status": "pending",
       "facts": [
@@ -273,7 +273,7 @@
           "value": "test_record_only"
         }
       ],
-      "rawRef": "0x6ae5f8a744eb711ef791e5c5b9b6e01b94a84e3fa668ce67484040e8fe564ffa"
+      "rawRef": "0x7183c023e4fdec83362cfcf1d195bc97fad6ad3f3abc4a1af320c3354315b3aa"
     }
   ],
   "limitations": [

services/control-plane/README.md

@@ -120,11 +120,11 @@ The loader reads local runtime state first, then committed deterministic outputs
 
 If the launch-core fixture is missing, the loader rebuilds the in-memory view from indexer/verifier outputs or the raw fixture receipts and artifact resolver. It does not fetch from live RPC or write production state.
 
-`transaction_submit` accepts signed local test transaction envelopes only and writes them to `devnet/local/intake/transactions.ndjson` by default. `bridge_observation_submit` writes bridge-agent observations to `devnet/local/intake/bridge-observations.ndjson`. These files are local runtime intake, not committed fixtures.
+`transaction_submit` accepts signed local test transaction envelopes only and writes them to `devnet/local/intake/transactions.ndjson` by default. When called with `runtimeSubmit: true` or `runtimeSubmitMode: "direct"`, it also forwards the contained devnet transaction into the active Rust runtime state file so `mempool_list`, block production, transaction reads, account reads, and balance reads can see it. `bridge_observation_submit` writes bridge-agent observations to `devnet/local/intake/bridge-observations.ndjson`. These files are local runtime intake, not committed fixtures.
 
 `npm run control-plane:smoke` runs an in-process JSON-RPC client over the complete local lifecycle surface: RPC discovery/readiness, health, node status, peers, chain status, real-value pilot status/list/status methods, blocks, transactions, mempool, accounts, balances, tokens, token balances, pools, LP positions, swaps, product-flow status, faucet events, wallet public metadata, rootfields, agents, models, work receipts, artifact availability, verifier modules, verifier reports, memory cells, challenges, finality, bridge observations, bridge deposits, bridge credits, withdrawals, provenance, and raw JSON.
 
-`npm run flowchain:rpc:e2e` verifies the FlowChain-native JSON-RPC discovery and readiness methods, required method coverage, no-secret report boundary, and writes `devnet/local/rpc-e2e/flowchain-rpc-e2e-report.json`. It intentionally reports public RPC readiness as blocked until the explicit public RPC deployment inputs are configured.
+`npm run flowchain:rpc:e2e` verifies the FlowChain-native JSON-RPC discovery and readiness methods, required method coverage, no-secret report boundary, runtime-backed transaction submission, mempool visibility, block/transaction/account/balance/token-balance/provenance reads, and restart continuity. It writes `devnet/local/rpc-e2e/flowchain-rpc-e2e-report.json` and intentionally reports public RPC readiness as blocked until the explicit public RPC deployment inputs are configured.
 
 `npm run flowchain:real-value-pilot:control-dashboard` verifies that the API exposes the capped owner-testing pilot lifecycle, rejects secret-shaped material, and that the dashboard source renders the pilot evidence and next operator command without browser secret storage. The root `flowchain:real-value-pilot:e2e` command is the upstream final HQ pilot gate and depends on proof commands from multiple owner branches.
 

services/control-plane/src/methods.ts

@@ -1,9 +1,10 @@
-import { appendFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
-import { dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 
 import { canonicalJson, findSecret, keccak256Hex } from "../../shared/src/index.ts";
 import { invalidParams, methodNotFound, objectNotFound, secretRejected } from "./errors.ts";
-import { loadControlPlaneState, resolveControlPlanePath } from "./fixture-state.ts";
+import { loadControlPlaneState, repoRoot, resolveControlPlanePath } from "./fixture-state.ts";
 import {
   bridgeLiveReadiness,
   pilotCapStatus,
@@ -354,6 +355,12 @@ function appendNdjson(path: string, row: JsonObject): void {
   appendFileSync(resolved, `${JSON.stringify(row)}\n`);
 }
 
+function writeJson(path: string, value: JsonObject): void {
+  const resolved = resolveControlPlanePath(path);
+  mkdirSync(dirname(resolved), { recursive: true });
+  writeFileSync(resolved, `${JSON.stringify(value, null, 2)}\n`);
+}
+
 function txIntakeRows(state: LoadedControlPlaneState): JsonObject[] {
   const rows = readNdjson(state.paths.txIntakePath);
   return rows.length > 0 ? rows : state.txIntake;
@@ -462,6 +469,24 @@ function nodeAccountRows(state: LoadedControlPlaneState): JsonObject[] {
       localOnly: true,
     });
   }
+  for (const [balanceId, value] of Object.entries(devnetLocalTestUnitBalances(state))) {
+    const balance = asJsonObject(value) ?? {};
+    const accountId = stringValue(balance.accountId) ?? balanceId;
+    if (rows.some((row) => row.accountId === accountId || row.keyReferenceId === accountId)) {
+      continue;
+    }
+    rows.push({
+      schema: "flowmemory.control_plane.account.v0",
+      accountId,
+      accountType: "local_test_unit_balance",
+      owner: stringValue(balance.owner) ?? null,
+      balance: stringValue(balance.units) ?? stringValue(balance.amountUnits) ?? "0",
+      noValue: true,
+      metadata: balance,
+      source: "local-devnet:localTestUnitBalances",
+      localOnly: true,
+    });
+  }
   if (rows.length === 0) {
     rows.push({
       schema: "flowmemory.control_plane.account.v0",
@@ -765,7 +790,8 @@ function tokenBalanceRows(state: LoadedControlPlaneState): JsonObject[] {
     return {
       schema: "flowmemory.control_plane.token_balance.v0",
       balanceId,
-      accountId: stringValue(balance.owner) ?? stringValue(balance.accountId) ?? balanceId,
+      accountId: stringValue(balance.accountId) ?? balanceId,
+      owner: stringValue(balance.owner) ?? null,
       tokenId: "local-test-unit",
       amount: stringValue(balance.units) ?? stringValue(balance.amountUnits) ?? "0",
       status: "projected_local_unit",
@@ -1873,13 +1899,114 @@ function signedEnvelopeForSubmit(params: JsonObject): JsonObject {
   return envelope;
 }
 
+function transactionFromSignedEnvelope(envelope: JsonObject): JsonObject {
+  const transaction = asJsonObject(envelope.tx) ?? asJsonObject(envelope.transaction) ?? asJsonObject(envelope.payload);
+  if (transaction === null) {
+    throw invalidParams("signed envelope must include tx/transaction/payload");
+  }
+  return transaction;
+}
+
+function runtimeSubmitMode(params: JsonObject): "off" | "direct" {
+  const mode = optionalString(params, "runtimeSubmitMode");
+  if (mode !== undefined && mode !== "direct" && mode !== "off") {
+    throw invalidParams("runtimeSubmitMode must be direct or off", {
+      allowed: ["direct", "off"],
+    });
+  }
+  if (mode === "direct") {
+    return "direct";
+  }
+  if (mode === "off") {
+    return "off";
+  }
+  return optionalBoolean(params, "runtimeSubmit") || optionalBoolean(params, "forwardToRuntime")
+    ? "direct"
+    : "off";
+}
+
+function safeFileId(value: string): string {
+  return value.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120);
+}
+
+function submitEnvelopeToRuntime(
+  state: LoadedControlPlaneState,
+  signedEnvelope: JsonObject,
+  intakeId: string,
+  submittedBy: string,
+): JsonObject {
+  const tx = transactionFromSignedEnvelope(signedEnvelope);
+  const runtimeDir = resolve(dirname(resolveControlPlanePath(state.paths.txIntakePath)), "runtime-submit");
+  const fixturePath = resolve(runtimeDir, `${safeFileId(intakeId)}.json`);
+  writeJson(fixturePath, {
+    schema: "flowmemory.control_plane.runtime_submit_fixture.v0",
+    tx,
+  });
+
+  const statePath = resolveControlPlanePath(state.paths.localDevnetPath);
+  const nodeDir = resolve(dirname(statePath), "node");
+  const args = [
+    "run",
+    "--manifest-path",
+    "crates/flowmemory-devnet/Cargo.toml",
+    "--",
+    "--state",
+    statePath,
+    "--node-dir",
+    nodeDir,
+    "submit-tx",
+    "--tx-file",
+    fixturePath,
+    "--authorized-by",
+    submittedBy,
+    "--direct",
+  ];
+  const result = spawnSync("cargo", args, {
+    cwd: repoRoot(),
+    encoding: "utf8",
+    windowsHide: true,
+  });
+
+  if (result.error !== undefined) {
+    throw invalidParams("runtime submit failed before cargo started", {
+      error: result.error.message,
+    });
+  }
+  if (result.status !== 0) {
+    throw invalidParams("runtime submit rejected the signed transaction payload", {
+      status: result.status,
+      stderr: result.stderr.trim().slice(0, 1200),
+    });
+  }
+
+  let queued: JsonValue = [];
+  try {
+    const parsed = JSON.parse(result.stdout) as JsonObject;
+    queued = asJsonArray(parsed.queued);
+  } catch {
+    queued = [];
+  }
+
+  return {
+    schema: "flowmemory.control_plane.runtime_submit_result.v0",
+    mode: "direct",
+    queued,
+    statePath,
+    nodeDir,
+    fixturePath,
+    status: "queued_in_runtime_state",
+    localOnly: true,
+  };
+}
+
 function transactionSubmit(params: JsonValue | undefined, context: ControlPlaneContext): JsonValue {
   const state = stateFor(context);
   const objectParams = asObjectParams(params, "transaction_submit");
   const signedEnvelope = signedEnvelopeForSubmit(objectParams);
+  const submittedBy = optionalString(objectParams, "submittedBy") ?? "local-control-plane";
   const intakePayload: JsonObject = {
     signedEnvelope,
-    submittedBy: optionalString(objectParams, "submittedBy") ?? "local-control-plane",
+    submittedBy,
   };
   const finding = findSecret(intakePayload);
   if (finding !== null) {
@@ -1898,14 +2025,19 @@ function transactionSubmit(params: JsonValue | undefined, context: ControlPlaneC
     localOnly: true,
   };
   appendNdjson(state.paths.txIntakePath, row);
+  const runtimeMode = runtimeSubmitMode(objectParams);
+  const runtimeSubmission = runtimeMode === "direct"
+    ? submitEnvelopeToRuntime(state, signedEnvelope, intakeId, submittedBy)
+    : null;
   return {
     schema: "flowmemory.control_plane.transaction_submit_result.v0",
     accepted: true,
     intakeId,
     txId: row.txId,
     status: row.status,
-    forwardedTo: "local-file-intake",
+    forwardedTo: runtimeSubmission === null ? "local-file-intake" : "local-runtime-state",
     runtimeIntakePath: state.paths.txIntakePath,
+    runtimeSubmission,
     localOnly: true,
   };
 }
@@ -1957,7 +2089,7 @@ function balanceGet(params: JsonValue | undefined, context: ControlPlaneContext)
   return {
     schema: "flowmemory.control_plane.balance.v0",
     accountId: account.accountId,
-    amount: "0",
+    amount: stringValue(account.balance) ?? "0",
     unit: "no-value-local-credit",
     noValue: true,
     localOnly: true,