Separate identity-only pilot custody foundation

docs/real-xmr-pilot-deployment.md

@@ -18,6 +18,19 @@ The independent private chain uses a fixed pilot genesis time and its own determ
 
 This stack does **not** connect to the operator's Monero daemon, create real Monero deposit addresses, scan a wallet, approve real credits, construct or relay withdrawals, or settle NFT sales against active consensus. Having a full node supplies only the blockchain daemon; it is not a Wallet-RPC service, watch-only deposit wallet, or spending wallet. Deposit enrollment and withdrawal request flags remain rejected outside the mainnet profile, and mainnet remains separately gated. Do not expose the service publicly or solicit funds.
 
+### Pilot custody identity groundwork (schema v10)
+
+Schema v10 adds an immutable, identity-only binding with separate fields for the Wikideck market network/chain (`wikideck-randomx-pilot-1` and the pilot chain ID), Monero network (`mainnet`), custodian UUID, policy version and initialization time. It intentionally does not widen the existing allocation or withdrawal table constraints, initialize the mock sandbox's `custody_meta` identity, create addresses, grant runtime privileges, or enable any HTTP funding routes.
+
+Use a **separate fresh custody database** for this identity exercise. The existing pilot Compose database contains mock sandbox custody and is not eligible; importing or reinterpreting its mock journals as Monero liabilities is prohibited. An operator migration is explicitly gated; identity initialization also refuses populated financial, mock, observer, allocation, credit, release or withdrawal tables.
+
+After an operator creates/provisions a distinct empty database and its schema-owner connection, the CLI workflow is:
+
+1. With the `pilot` profile selected, run `custody:db migrate-pilot-schema` with `WIKIDECK_PILOT_SCHEMA_MIGRATION=explicit-pilot-schema-migration-only`.
+2. Run `custody:db initialize-pilot-custody-identity <CUSTODIAN_UUID>` with `WIKIDECK_PILOT_MODE=private-mock-only`, `WIKIDECK_PILOT_CUSTODY_IDENTITY=initialize-pilot-custody-v1`, and `WIKIDECK_PILOT_CUSTODY_OPERATIONS=identity-only-no-funds`.
+
+The schema migration does not grant runtime roles. The identity command is one-time and replay-idempotent only for the same pilot chain and custodian. The CLI refuses other custody actions on the pilot profile; mainnet keeps its existing separate controls. This is groundwork only: no customer deposits, financial posting, withdrawal intent or send is enabled by these commands.
+
 ### Reusing the operator-hosted daemon
 
 The next integration should point the observer/gateway to the existing daemon rather than deploy or synchronize another one. An operator-triggered, read-only `get_info` probe is now available as a first connectivity check. It checks the expected Monero network, synchronized/local height, and daemon status; it does not open a wallet or provide a financial proof. The probe is opt-in and does not run on app startup.

docs/real-xmr-pilot-plan.md

@@ -7,9 +7,11 @@ Updated: 2026-10-22. Implementation plan for a private, operator-supervised func
 - **Step 1 started; mock-only foundation implemented.** Added a distinct `pilot` profile with its own network/genesis identity, explicit private-mock-only startup opt-in, separate local ledger/market/custody paths and browser wallet database, and a loopback-bound PostgreSQL sandbox stack. Setup and limits are in [the pilot deployment guide](real-xmr-pilot-deployment.md). Testnet v6 and mainnet candidate identities/gates were left intact.
 - **Operator infrastructure update:** a Monero full node is hosted on the operator's network and is intended to be reused; the pilot does not need to deploy or synchronize another daemon. Its network mode, RPC reachability from the pilot host/container, authentication/transport boundary and sync health still need verification. This does not provide Wallet-RPC, deposit observation, address allocation or a spending wallet.
 - **Next integration slice implemented:** added an operator-triggered, read-only `monerod get_info` probe, opt-in Compose check service, and mocked regression coverage. The Linux test image builds and focused probe/deployment tests pass (6/6). The probe validates expected Mainnet/Stagenet identity and synchronization, but has not been run against the operator's node because its private endpoint/configuration has not been provided. It does not enable wallet access, addresses, deposits, or credits. See [the probe setup and security boundary](real-xmr-pilot-deployment.md).
+- **Pilot identity/schema slice implemented:** schema v10 additively records a separate identity binding `wikideck-randomx-pilot-1` + current pilot chain ID to Monero `mainnet`, with an immutable `identity-only` activation status. Explicit pilot-only schema-migration and identity-initialization CLI actions require exact no-funds acknowledgements, reject non-pilot profiles, and refuse any target DB with pre-existing mock/financial/deposit data. No runtime roles/grants or deposit/withdrawal routes were added. Existing v1-v9 migration definitions/digests remain unchanged.
+- **Validation:** serial offline suite passed (latest run exited 0); PostgreSQL integration suite passed 42/42, including v1/v2 upgrades through v10, one-time pilot identity/replay/mismatch checks, dirty-database rejection, and no role access to the identity table. The isolated pilot identity operation itself requires a separate fresh database and has not been run outside disposable tests.
 - **Step 1 is not complete.** The current pilot stack does not connect to that external daemon and still has no Wallet-RPC gateway, observer, real-fund deposit or withdrawal path. It is useful for isolated UI/mock-flow work only and must not receive funds.
 - **Validation:** pilot-specific network/startup/storage/Compose tests pass (10/10); pilot runtime Docker image builds. The attempted serial full offline suite had one native RandomX HTTP peer-gossip convergence failure in `tests/api.test.ts`; the other reported tests passed. Treat full-suite status as not yet clean and rerun after the next increment.
-- **Steps 2–5:** not started. Existing deposit/withdrawal APIs still require the separately gated mainnet profile; sale-lock transactions remain candidate-only and are not accepted by active consensus.
+- **Steps 2–5:** not started. Existing deposit/withdrawal APIs still require the separately gated mainnet profile; the new pilot record is identity metadata only. Sale-lock transactions remain candidate-only and are not accepted by active consensus.
 
 ## Finish line
 
@@ -22,7 +24,7 @@ Use the existing pooled-custody architecture, PostgreSQL accounting, native Mone
 ## Reuse what exists
 
 - Exact atomic-XMR prices and fee calculations.
-- PostgreSQL schema v9 and accounting/reorg records.
+- PostgreSQL schema v10 and accounting/reorg records.
 - Signed deposit enrollment, observation worker and reviewed credit/release commands.
 - Signed balance reads and withdrawal reservation/cancellation APIs.
 - Marketplace/custody UI and executable sale-lock/accounting models.
@@ -43,7 +45,7 @@ One Linux host, one authoritative market writer, one treasury tool/worker, fixed
 - Add one pilot deployment definition using existing Docker patterns: app, PostgreSQL, observer and private Wallet-RPC gateway. Reuse the operator-hosted full node over a verified private network connection; do not add a duplicate daemon service. Connect the observer/watch-only wallet and separate spending wallet explicitly. Keep daemon and Wallet-RPC endpoints private, authenticated and unavailable from the public Internet; supply credentials through protected files/secrets, not checked-in Compose values.
 - Include schema initialization, role grants and required configuration in a short setup procedure. Keep spending keys outside the web app and Wallet RPC off the public Internet.
 
-**Progress:** A separate mock-only pilot network/profile, launch opt-in, profile-isolated local storage, PostgreSQL Compose deployment and setup guide now exist. An opt-in read-only daemon probe is implemented to verify private connectivity and `get_info` health from the Compose network; it still needs the operator's protected endpoint config and a successful real-node run. It does not connect the observer or Wallet-RPC. Wallet roles and all real-fund integrations remain outstanding. See [pilot deployment status and startup](real-xmr-pilot-deployment.md).
+**Progress:** A separate mock-only pilot network/profile, launch opt-in, profile-isolated local storage, PostgreSQL deployment, and opt-in read-only daemon probe now exist. The probe awaits the operator's protected endpoint config. Additive schema v10 and a pilot-only CLI bind the separate Wikideck pilot chain to Monero Mainnet in a fresh identity-only database; this grants no runtime access and cannot be used to enroll or credit deposits. Observer/Wallet-RPC roles and all real-fund integrations remain outstanding. See [pilot deployment status and startup](real-xmr-pilot-deployment.md).
 
 **Result:** start the stack, open the UI, create two wallets and obtain a test card; verify the hosted daemon's intended network, synchronization and private RPC reachability from the pilot runtime. Do not start a duplicate daemon. Prepare the watch-only/observer and separately controlled spending-wallet services while application development proceeds. A Stagenet rehearsal still requires a Stagenet daemon endpoint; an operator's Mainnet daemon cannot substitute for it.
 
@@ -118,4 +120,4 @@ Keep the functional essentials: signed authorization, correct network binding, p
 
 ## Next coding task
 
-**Run the read-only daemon check from the pilot Compose network once its protected endpoint config is available, then design the pilot's separate Wikideck-chain/Monero-mainnet financial identity and schema/role contract before connecting deposits.** No duplicate daemon is planned. Existing observer/deposit contracts are mainnet-specific, so do not simply enable their flags on the pilot. Keep the deployment mock-only until network binding, reviewed credit, actual withdrawal execution, recovery, and sale settlement are connected. Continue with the operator treasury tool and active sale-lock settlement as parallel implementation tracks where the identity contract permits. Completion means a buyer purchasing a card and the seller receiving withdrawable XMR—not another scaffold or release checklist.
+**Next: verify the pilot identity contract on its dedicated database, then design a separate pilot deposit request/observation adapter and migration/role boundaries without enabling HTTP enrollment.** Run the read-only daemon check when the protected endpoint config is available; no duplicate daemon is planned. Existing observer/deposit contracts are mainnet-Wikideck-specific, so do not simply enable their flags on the pilot. Keep deployment mock-only until network binding, reviewed credit, actual withdrawal execution, recovery, and sale settlement are connected. Continue treasury execution and active sale-lock settlement as parallel tracks once their shared identity boundary is defined. Completion means a buyer purchasing a card and the seller receiving withdrawable XMR—not another scaffold or release checklist.