@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/doc/reference/local-cache-foundation.md

@@ -0,0 +1,176 @@
+# Unified local cache foundation
+
+Status, 2026-11-04: foundation and shared-client integration implemented. See
+latest payment/file evidence (private historical evidence; not distributed),
+neutrality resolution (private historical evidence; not distributed) and
+[current usage](../runbooks/local-cache.md). Historical 61-test foundation evidence
+is separate from subsequent runs. Paid binary-service participant acceptance is not
+claimed. Text view does not change durable request/Order identities or cleanup rules.
+Related: [Skill integration](skill-input-output-cache.md),
+[current output cache](../reference/result-file-cache.md).
+
+## Existing code and reuse decision
+
+`file-cache.mjs` already supplies private streaming storage, atomic index updates,
+digest checks and Order-scoped output records. `file-download.mjs` owns HTTP/HTTPS
+streaming, DNS/redirect checks and transfer bounds. `file-cache-owner.mjs` owns a
+portable OS lock, loaded only for file operations. `file-cache-settings.mjs` owns
+limits. Extend/extract these into one store; do not duplicate them for input files.
+
+Current limitations found by inspection:
+
+- Every record requires an Order ID and URL; an input may precede an Order and come
+  from a local file. Current file count is per Order, not per request.
+- Only Order-scoped list/download/remove exist; no global summary, export or cleanup
+  preview. Configuration currently requires manually editing private JSON.
+- A crash after marking a record removed but before unlink can leave physical bytes.
+  A failed index commit after publishing a binary can leave unaccounted-to-metadata
+  bytes. Physical usage is counted today, but repair/cleanup needs explicit states.
+- Directory scanning and full-index parsing occur per operation; new management
+  listings must stay bounded and must not hash every binary just to display usage.
+- Current total quota covers file-cache bytes, not existing JSON request/result
+  history. A unified screen must not misleadingly describe this as total User data.
+
+## File compatibility and identity
+
+Store arbitrary bytes: text in any encoding, images, media, PDFs, archives, model
+files and unknown formats. No format whitelist, automatic extraction, rendering,
+transcoding or execution. MIME, Unicode display name and extension are descriptive;
+control characters must be escaped in terminal output. Physical names are generated
+identifiers, never filenames, source URLs or caller paths. Zero-byte files are valid.
+
+Local import accepts an explicitly selected regular file, not a device, FIFO or
+recursive directory. Stream from a checked handle and detect ordinary source changes
+while copying. This cannot guarantee an atomic view of a concurrently modified source:
+callers must provide stable files; the saved bytes and digest define the snapshot.
+Do not hard-link source files: future writes must not mutate the snapshot. Directory
+packaging and Provider-specific uploads remain Skill responsibilities.
+
+Use a record identity derived from purpose (input/output), original request ID or
+Order ID, and file key. Digest describes bytes, not ownership or payment authority.
+No cross-request deduplication/refcounts in the first implementation: it complicates
+cleanup and reference integrity for little demonstrated benefit. Equal bytes may
+have independent copies. Runtime endpoint/port never enters record identity.
+
+## Storage and upgrade
+
+Keep the existing managed root, `runtime/invocations.json.files/`, so existing outputs
+do not require copying large files. Preserve existing output storage IDs and bytes.
+Add input record namespace and a versioned index with explicit scope/purpose; retain
+one writer lock and one quota account for both. No fake Order IDs for input entries.
+No new database or background cache service is required.
+
+Existing client JSON checkpoints and verified structured results stay where they
+are; the cache manager does not duplicate or reinterpret them. Display their relation
+where available, but do not delete financial/checkpoint history through file cleanup.
+
+Before activation, a bounded one-time index upgrade validates old records and writes
+new metadata atomically under the store lock. It must not require a running Wallet,
+chain calls, byte re-download or new request. Unsupported/corrupt metadata blocks
+file mutations with a concrete diagnostic, not an empty replacement index. Do not
+keep dual writing or two active schema implementations. Failure leaves recoverable
+old metadata; deployment must coordinate stopping old writers. Inspect actual saved
+state before any operator migration; no data migration is executed by this document.
+
+## Record and transfer state
+
+A record includes versioned scope, file key, display name, optional MIME/source,
+expected and observed digest, byte count, created/updated Unix-millisecond timestamps,
+state and safe failure code. Local paths and signed source URLs are private metadata;
+routine listings/logs omit source credentials. Output provenance remains distinct
+from local digest verification; a digest alone does not prove paid delivery.
+
+Persist `writing` with a unique staging identity before creating partial bytes.
+Write to a private temporary file, stream/hash, fsync, publish complete bytes, then
+commit `available` metadata. Readers never consume partial bytes. Publishing errors
+leave a recoverable record; retries reconcile published bytes before replacement.
+Store mutation serializes only metadata/reservations, not entire network transfers.
+Concurrent operations on the same record return busy/reuse, not duplicate writers.
+
+Use `deleting` before removing bytes, then `removed` after durable removal. Restart
+finishes interrupted deletion idempotently. A quota slot is not free until bytes are
+actually removed. Failed or missing/corrupt copies retain their identity/digest.
+An interrupted write is not available; remove only its owned staging files and retry
+explicitly. No silent network transfer or service execution during startup repair.
+
+Unrecognized files or corrupt metadata must not trigger recursive deletion. Account
+for their physical occupancy and report them for inspection. Recovery scans happen
+once under the writer lock; normal lists use bounded metadata pagination. Verify
+hashes on reuse/export, not every display refresh. Portable OS locking is reused;
+network-filesystem and untested OS support must not be claimed.
+
+## Limits and resource accounting
+
+Start from existing configurable defaults: 100 MiB per file, 512 MiB total managed
+file storage, 20 active files per input request or output Order, 2 transfers, 10,000
+retained records, 8 MiB index bound and 15-minute transfer deadline. These are resource
+limits, not format restrictions or Provider service deadlines. Increasing a limit
+must be possible through the management command within documented supported bounds.
+
+Charge input and output binaries, staging bytes and other physical files in the
+managed directory; expose metadata overhead and transfer reservations separately.
+Never double-count written staging bytes and their reservation. Known sizes reserve
+bounded declared space; unknown sizes conservatively reserve the per-file ceiling.
+Enforce actual streamed bytes even when a source lies about length. Disk ENOSPC or
+permission failure must leave recoverable state and not stop Order reconciliation.
+Export copies consume destination disk space outside the managed quota.
+
+Lowering a cap below current use retains data, reports over-limit and blocks new
+allocation; it must not make old records unreadable or prohibit cleanup. Metadata
+limit stops creating records, not listing/removal. Settings updates are atomic and
+validated; avoid restarting/locking Wallet just to change file-cache limits.
+
+## Management and cleanup
+
+Implemented unified entry:
+
+| Command | Behavior |
+| --- | --- |
+| `./run cache` | Managed bytes, input/output split, reserved space, limits, problems |
+| `./run cache list` | Paginated records; filters for purpose, state, request/Order |
+| `./run cache details ID` | Scope, file, integrity, timestamps, state and next action |
+| `./run cache export ID PATH` | Verify and copy; never execute or overwrite silently |
+| `./run cache clean` | Preview candidates and bytes, then deliberate confirmation |
+| `./run cache settings` | Show/update validated resource limits |
+
+CLI talks to the existing authenticated Runtime when running. When stopped, a local
+management session must acquire the same OS lock; never race a live Runtime or read
+a half-written index. Do not introduce another daemon/port. A capability marker or
+shared dispatcher must prevent a failed HTTP request from causing unsafe offline
+fallback. A held lock means retry through the owning Runtime, not delete the lock.
+
+Preserve existing `/files/*` and installed-client behavior as adapters over the same
+store during integration. The current entry is `./run orders files ORDER_ID`; legacy flat aliases are not
+retained. New generic storage primitives must not expose arbitrary
+path reads through an unauthenticated web route. Local import/export authority stays
+within the existing local caller/OS boundary; not a claim of filesystem isolation.
+
+Automatic cleanup is restricted to known abandoned temporary files and incomplete
+deletions. Do not add age-based result eviction in the first implementation. Explicit
+clean excludes active transfers and recovery-needed input. Unknown/unreconciled
+requests remain protected. New input defaults to protected. Recovery integration releases protection only
+after verifying a durable delivered result for its original request; no guessed
+terminal states. Failed release checks retain protection.
+
+Confirmation reports files and bytes, warns that original links may no longer work,
+and says payments/Order history are unchanged. Revalidate eligibility under lock at
+delete time; an old preview cannot delete a newly protected or replaced entry. Delete
+exact approved identities/generations, not a fresh broad query after confirmation.
+Retain removed metadata; metadata-cap exhaustion gives a concrete limit-setting action.
+Full-data uninstall retains its existing explicit confirmation and stop-services step.
+
+## Verification gates before invocation integration
+
+- Arbitrary-byte equality for empty, Unicode text, image/PDF/archive-like and binary
+  fixtures. No execution, parsing or business-specific branches.
+- Bounded memory streaming with large maintained fixtures; deceptive lengths,
+  limits, ENOSPC/write failures, raised/lowered limits and shared input/output quota.
+- Actual competing processes, transfer interruption, publication/index failure,
+  deletion crash and restart repair; existing output upgrade without byte rewriting.
+- Corrupt/missing records, unsafe paths, export collisions, unknown files and source
+  changes. No destructive blanket cleanup or replacement purchase.
+- Clean-preview race, active/protected inputs, pagination, friendly CLI output and
+  settings changes. Cache operations make zero Wallet signing/Order-creation calls.
+
+Only after this gate passes attach input readiness and output declarations to Skill
+calls. Actual paid acceptance and other-platform checks remain separate evidence.

package/doc/reference/local-safe-owner-ui.md

@@ -0,0 +1,25 @@
+# Local Safe owner approval boundary
+
+`owner-approval-server.mjs` serves a temporary loopback page for a fixed public
+operation plan. `web/owner-approval.js` connects an injected browser owner wallet,
+checks the selected network/Safe and obtains the required Safe approvals/execution.
+It does not hold the local Session Key or obtain Wallet administrator capability.
+
+The terminal and page share the same saved operation identity. The page verifies
+execution receipts/effects; the terminal independently checks chain state before
+binding or advancing. Changed nonce, conflicting draft, incomplete signature count
+or unknown effect must preserve the original plan for reconciliation.
+
+Source supports sequential single-owner and multisig approval mechanics. The recorded
+private MetaMask journey used one owner. Multi-owner, interrupted-signature and
+portable-page participant acceptance remain separate gates. Supported Safe versions
+are checked explicitly, not inferred from chain ID.
+
+Headless users can forward the printed loopback port. Portable export contains a
+fixed public plan and local server, not RPC credentials, keys or local tokens.
+Browser RPC reachability/CORS must still be verified. Do not expose the temporary
+approval service publicly or allow arbitrary transaction input.
+
+See [user instructions](../runbooks/safe-owner-web.md),
+[signer/deployment settings](public-deployment-settings.md) and
+[emergency stop](../runbooks/emergency-payment-stop.md).

package/doc/reference/local-update.md

@@ -0,0 +1,18 @@
+# Local software repair
+
+Current operation: [update and uninstall runbook](../runbooks/local-update.md).
+
+User resolves its exact Wallet dependency through public package exports. Repair
+checks package versions and fingerprints User src/scripts and Wallet lib/bin, then
+refreshes managed service paths under the installer lock. Existing client connection
+URLs and caller credentials must match before a client-module path can be refreshed.
+A mismatch stops preparation rather than rewriting transaction identity.
+
+Installation checkpoints live in XDG state storage; old source-install checkpoints
+are read to preserve a custom data-directory selection. Deployment settings are
+copied into private User data only when no canonical file exists. Neither path
+changes keys, Policies, requests or recovery records.
+
+A successful managed restart loads the reviewed installed package. Package metadata
+alone does not identify a previously running daemon. Explicit version negotiation
+remains planned; this implementation does not claim arbitrary-version compatibility.

package/doc/reference/multi-service-runtime.md

@@ -0,0 +1,119 @@
+# Local multi-service Runtime contract
+
+Current local interface; the Protocol dependency is pinned in package.json. This is a local
+User interface, never a public platform listener. One Runtime routes many services
+without installing a global active package for each call. The caller credential
+is local and distinct from Wallet's Agent IPC capability. Wallet retains the key.
+
+## Service reference and trust
+
+A manifest's service object uses agentpay.service-reference.v1 with skillId,
+profileHash, profile and adapter. Protocol's normalizeServiceReference verifies
+profileHash over the exact canonical public profile: Provider/service identity,
+controlled MCP/payment endpoints, seller, network and asset. References have no
+price or actual usage fields. Wallet/Settlement/Module independently enforce
+Registry qualification and bounded authorization; a matching profile hash alone
+does not grant admission or certify quality.
+
+The common agentpay.json.v1 transport carries Protocol invocation/result metadata
+and application-owned JSON. Runtime has no business-specific adapter. Runtime does
+not download or execute caller-provided adapter code. Arbitrary HTTP, binary or
+streaming APIs need an explicit integration; JSON may contain application-level
+artifact references, whose actual bytes need their own business validation.
+
+## Local endpoints
+
+All POSTs require Authorization: Bearer <local caller credential>. Reject before
+parsing or touching Wallet when authentication fails.
+
+POST /services/check accepts exactly {service}. It verifies the reference and
+returns Runtime identity, the normalized reference, orderCreated=false and
+purchaseReadinessChecked=false. It performs no Order, Wallet signature, online
+qualification, balance or Quote reservation. Never describe it as payment readiness.
+
+POST /services/invoke uses an Idempotency-Key and exactly:
+
+```json
+{
+  "version": "agentpay.runtime-call.v1",
+  "service": "<the complete service-reference object>",
+  "request": {"text": "your private business input"},
+  "requestedMaxUsageUnits": "1"
+}
+```
+
+The service field above is an object, abbreviated as a string only in this
+illustration. Input is bounded JSON: 256 KiB, depth 32. Requested usage is a
+positive integer string and an upper bound, not a price or actual meter. The
+local AGENTPAY_USER_MAX_REQUEST_USAGE_UNITS cap defaults to 1000000. Settlement
+also constrains preparation by the authoritative Quote and Wallet's Policy.
+Unknown top-level fields, including caller prices or payout overrides, fail.
+
+Runtime hashes the canonical private input, prepares through Wallet, compares the
+Order tuple/provider/network/asset/seller/usage with the profile before signing,
+then uses the existing narrow commitment/payment/service-ready flow. It forwards
+private JSON only to the bound Provider payment endpoint, refusing redirects.
+Provider result orderId/requestHash/outputHash/usage must match the invocation and
+accepted Settlement delivery evidence. Output hash verifies bytes, not quality.
+
+The result version is agentpay.runtime-result.v1, with orderId, requestHash,
+service {skillId, profileHash}, JSON output, outputHash, usageUnits,
+deliveryEvidenceVerified, confirmationRequired, finalization and deadlines.
+Settlement deadlines remain epoch milliseconds, with frozen chain-seconds fields
+preserved by existing normalizers. Do not recompute schedules locally.
+
+## Durable recovery
+
+The existing invocation store remains one serialized ledger, with per-call
+serviceBinding and routingVersion on new generic entries. The same Idempotency-Key
+cannot switch service, adapter, input or usage cap; old random entry identifiers
+are not reinterpreted. Startup retains older requests for read-only reconciliation and explicit review.
+They cannot create replacement purchases. Current entries are checked against their
+own reference on every begin.
+
+Verified results are fsynced before HTTP success under <state-file>.results,
+owner-held mode 0600 in a 0700 directory. The Runtime returns saved output after
+restart without another Wallet/Provider call. The shared client separately retains
+request checkpoints and verified output. Neither layer stores Service Authorization
+plaintext. Signed payment recovery material keeps its existing private boundary.
+
+Default calls recover the matching current request or reuse its verified result.
+--force explicitly starts another independent request, preserving old records.
+Adapter/usage edits are not silently considered new intent: the old full binding
+rejects the change unless explicitly forced. Force never bypasses Policy or Quote
+checks. When several unfinished forced requests make recovery ambiguous, stop;
+select a recorded identifier diagnostically. After a forced request succeeds,
+default repeats reuse that result rather than unexpectedly funding older work.
+
+Runtime has no selected service and does not load active-skill.json at startup.
+That retained filename is only the official test material checkpoint. Its legacy
+selection format must not be treated as general Runtime configuration. New test
+checkpoints record routingVersion; older test requests pause for explicit recovery
+review and are never reinterpreted as new generic purchases. The old random route
+is removed. Deployment must gate on pending older requests and update User/Agent,
+matching types and official package together. No silent state reset is allowed.
+
+The invocation ledger is owned by one Runtime process. Multiple processes must
+not share its state file. The result is a delivery-time snapshot, not a continuously
+updated finalization/payout status.
+
+## Packaging and release
+
+Use the publisher template: change package metadata, copy a registered Provider
+reference, edit local validateRequest, business JSON and result.output handling.
+Validate business input before any payment; Protocol JSON bounds are not a domain
+schema. The shared User client does transport, credentials and recovery. A Skill
+calling several services retains each step's input and resumes earlier paid steps.
+All eligible calls share the existing bounded Policy; no new owner signature is
+required merely because another qualified service is used.
+
+The maintained template is published by AgentPay Agent and discovered by Market.
+User's official executable test package has an independently pinned digest; template
+availability does not authorize replacing that package. See
+[official package maintenance](../runbooks/official-test-package.md).
+Actual harness discovery and scoped deployed purchases need separate acceptance;
+component tests with simulated Wallet evidence are not that.
+
+Older routing records are preserved and shown for review without preventing the
+Runtime process from starting. Invalid/corrupt history can still block paid activity.
+Do not reset state or create replacement purchases to bypass an unresolved record.

package/doc/reference/npm-integration-verification.md

@@ -0,0 +1,67 @@
+# User npm integration verification — 2026-11-07
+
+User 0.3.0 candidate consumes public Wallet 0.3.0 and Protocol 0.14.3 through
+public exports. No sibling source or Wallet compiler is required. User remains
+private/unpublished. No participant service or private data changed.
+
+## Checks completed
+
+- Independent source copy with npm dependencies and no sibling Wallet: 366 tests
+  passed, no failures/skips. Real process and IPC checks are included; remote
+  platform/payment behavior uses controlled fixtures, not real financial acceptance.
+- Final legacy data-location and repair-lock regressions, including local-update
+  tests: 21 passed. A competing installer and conflicting connection stop before
+  service changes.
+- Packed User installed into a separate consumer directory: `agentpay help` worked;
+  installed preparation and exact Wallet version checks passed without invoking a
+  compiler or package manager. No source lockfile was needed.
+- Real Wallet/Runtime started from the installed artifact: health answered, duplicate
+  Wallet startup was rejected, restart remained locked and preserved its encrypted
+  key. These two installed-package tests passed.
+- Package allowlist includes runtime, public docs and licenses; no tests, private
+  state, credentials, sibling source or source lockfile. Git whitespace checks passed.
+
+## Implementation boundaries
+
+Installation state uses XDG state storage. Setup configuration is stored with
+private User data; old source checkpoints preserve custom data-directory selection.
+A new npm installation cannot discover arbitrary old source directories: provide
+AGENTPAY_USER_DATA_DIR when moving an old custom installation.
+
+Repair checks exact installed versions, holds the installer lock across service
+changes and updates only recognized managed units. Client-module relocation requires
+matching Runtime URL and caller credential. Uninstall keeps data by default;
+explicit --delete-data requires destructive confirmation. Neither renews permissions
+nor creates purchases.
+
+## Still required
+
+Participant setup/upgrade/restart/uninstall acceptance, running-daemon version
+negotiation, User npm/OIDC publication and Market guidance. Package metadata alone
+does not identify a previously running daemon; current repair performs a managed
+restart and readiness checks. No systemd login, browser, real-network or production
+acceptance is claimed. Exact pins remain until compatibility ranges are designed.
+
+## Review corrections and npm update
+
+Relocation previously failed inside service preparation despite a permissive outer
+preflight. Repair preparation now checks a relocation without writing it; only the
+post-stop phase updates the client-module path. The real autostart script was tested
+with old unit/client paths and a controlled systemctl command. Explicit purge now
+removes matching legacy checkpoints/setup files so subsequent setup cannot reimport
+them; unrelated source installation scope is not deleted.
+
+After these corrections, the independent suite passed 374 tests. Final focused
+checks passed 35, including cancellation, -f, installed-file changes during consent,
+source-link rejection, install/repair failure, lock contention and retained data.
+
+A real npm global installation under a temporary prefix was replaced from local
+0.3.0 and 0.3.1 candidate tarballs. A new Node process loaded the new repair/version
+and retained the private fixture. Neither candidate was published. Registry metadata,
+systemd/readiness and official download were controlled in this check: it proves
+artifact replacement and process handoff, not live platform/paid or login acceptance.
+The existing official-package tests cover pinned digest rejection and preservation.
+
+The updater follows npm's [install](https://docs.npmjs.com/cli/v11/commands/npm-install/)
+and [view](https://docs.npmjs.com/cli/v11/commands/npm-view/) command interfaces.
+A released-version registry upgrade and participant recovery still need acceptance.

package/doc/reference/onboarding-writing.md

@@ -0,0 +1,48 @@
+# Onboarding writing rules
+
+Confirmed with the User on 2026-10-06 through review of the English terminal
+setup demo. Apply these rules to user onboarding documents, terminal prompts
+and future Market guidance. They describe presentation, not new authorization
+or protocol requirements.
+
+## One action at a time
+
+- Explain what the current step accomplishes and why it is needed.
+- Keep the main screen focused on the current decision. Put technical addresses,
+  generated identifiers and transaction data behind an explicit `details` action.
+- Place relevant reminders immediately before the operation they concern.
+- State exactly what to enter; quote literal commands and give useful examples.
+- Explain amounts with a named currency and duration in days from now.
+- Before a permission or paid test, explain its scope, cost and effect, then ask
+  for agreement. Normal eligible purchases still use the existing bounded Policy
+  without another owner signature per Order.
+
+## Visual structure and recovery
+
+- Separate each step with a consistent divider and a short title.
+- Label action menus `> Choose an action`.
+- Prefix the recommended action with `*` and retain `← next step`.
+- Make progress labels agree with available actions and the completed steps.
+- On invalid input, show allowed inputs and stay at the current prompt.
+- Explain whether `q` cancels a step, returns to a menu or exits the program.
+- Resume completed work without unnecessarily repeating it. State persistence
+  limits: current demo progress survives only within the same process.
+
+## Complete the first-use loop
+
+Guide initialization → authorization → binding → startup → local checks →
+official random Skill installation and connectivity test → explicit completion.
+After the test passes, direct the user to Market to choose other Skills.
+The test completion screen need not display the random number.
+
+Current demo cost is explicitly an example: 0.001 demo USDC. Real integration
+must display the validated current quote before test agreement; this example
+is not a configured or guaranteed service price.
+
+Clearly distinguish preview, simulation and executed operations. The demo
+passes no real authorization, starts no process, installs no package and makes
+no payment. Real onboarding must use actual command/API results. Write guides
+against delivered scripts; mark remaining integrations explicitly.
+
+English prompts and Linux with Node are the current scope. Browser opening
+is not required; multilingual guidance and macOS verification remain deferred.

package/doc/reference/original-order-recovery.md

@@ -0,0 +1,97 @@
+# Original-Policy and missing-Order recovery — 2026-11-02
+
+## Scope
+
+Runtime starts even when history needs review. Background recovery only performs
+bounded authenticated reads; it cannot prepare Orders, submit payment, confirm
+receipt, invoke a Provider, or replace the current Policy.
+
+New invocation records save recoveryScope (network, Module, Safe, Policy ID) before
+Order preparation. Existing records are never assigned the current Policy merely
+because their original scope is missing. Existing saved payment metadata can
+supply its original Policy/Safe/network; the configured Module remains pinned and
+Wallet independently checks the on-chain Policy delegate against its local key.
+Different network/Module/Safe, revocation, future activation or unavailable key
+cannot be bypassed. Expiry alone permits bounded historical order.read requests.
+
+## Interfaces
+
+Wallet agent IPC readSettlementOrder accepts exactly one of orderId or
+orderRequestId and an optional recoveryScope. No historical payment/action method
+is added. Wallet obtains chain identity and Policy terms via its configured RPC,
+signs order.read for the original Policy, and leaves policy.json unchanged.
+
+Settlement order.read accepts exactly one selector. Request lookup uses existing
+preparation rows scoped by Safe/Policy and joins Orders constrained by Module,
+network and chain. It returns found=false with the original request ID, or found=true
+with the ordinary buyer Order projection. Missing rows never trigger prepare().
+The signed payload hash binds the chosen selector. Original orderId reads remain
+unchanged. Auth, nonce consumption and expiry/revocation rules are retained.
+
+Runtime validates returned request ID, request hash, service identity and any
+saved payment commitment before attaching a recovered Order ID. The attachment
+uses a compare-and-set under the local store lock so a foreground update is not
+overwritten. A later scan reads its financial state. A missing lookup is not proof
+of no on-chain payment; absent original scope and network errors stay distinct.
+Original history is retained. New foreground preparations also pass expectedScope
+to Wallet to prevent creating the original request under a different current Policy.
+
+## Verification and deployment boundary
+
+Controlled tests cover historical signing without rebinding, wrong key/revoked/
+foreign scope, read-only request selection, unavailable reads, response mismatch,
+concurrent attachment, and two business payloads through the common Runtime path.
+Wallet TypeScript compiles to a separate temporary build; live dist is untouched.
+No SQL schema or contract changes. Deploy Settlement + Wallet + User together, then
+restart ordinary-user services and unlock in the terminal. Participant checks of
+original history were checked on 2026-11-02: revoked original Policy and missing
+original scope remain explicit review. Local archive acceptance remains pending.
+No actual purchase is needed for this acceptance.
+
+An existing request lacking both an Order ID and original Policy may still require
+manual investigation; this implementation does not fabricate its authorization.
+
+## Inspect and mark local records
+
+```sh
+./run orders list
+./run orders details <ORDER_OR_REQUEST_ID>
+./run orders status <ORDER_OR_REQUEST_ID>
+./run orders archive <ORDER_OR_REQUEST_ID>
+./run orders unarchive <ORDER_OR_REQUEST_ID>
+```
+
+`status` keeps Order warnings brief and directs users to `orders`. The local list
+shows saved status and a readable warning for each record, followed by details and
+archive/unarchive commands. Unknown payment is never presented as unpaid.
+
+`orders` includes unfinished requests with no saved Order ID. Use a full ID or an
+unambiguous prefix (at least 10 hexadecimal characters after `0x`). `details` is
+also the default action: it works offline while Wallet is locked. `status` performs
+an authenticated read and needs an unlocked Wallet; it does not initiate payment.
+
+Archive asks for a short review note and confirmation. It hides only the warning
+matching the saved record and check result. A changed state or problem is shown
+again. Notes live in `runtime/invocations.json.reviews.json`, beside the unchanged
+invocation history. Unarchive restores the reminder and records the action.
+
+Archive does not cancel an Order, prove payment/nonpayment, revoke authorization,
+remove history, or stop work already in flight. It prevents further preparation or
+payment submission for that archived request. Background read-only checks continue.
+Do not create a replacement request to recover an unknown payment. Notes must not
+contain secrets. Concurrent note updates fail closed; if a process is interrupted
+while writing, preserve the files and ask support to inspect the review lock before
+retrying. Do not delete invocation history to clear a warning.
+
+## Pending structured result persistence
+
+A received, structurally valid Provider result is saved privately in
+`runtime/invocations.json.pending-results/` before evidence polling. It cannot be
+returned as a verified result until authenticated original-Order identity, output
+hash and usage checks pass. Background recovery can perform this read-only promotion;
+foreground same-request resume uses the saved copy before service/payment actions.
+No service execution or new payment is used to promote a pending copy. An unavailable or mismatched original authorization remains a blocker;
+spending expiry/revocation alone does not create replacement-purchase permission. Missing evidence retries with pending
+state; mismatch/storage failure preserves the candidate and a distinct warning.
+Verified records retain the existing `.results/` format. Both copies remain locally;
+this loop does not implement automatic eviction or download files referenced by URL.

package/doc/reference/private-anvil-onboarding-config.example.json

@@ -0,0 +1,18 @@
+{
+  "mode": "private-anvil",
+  "chainId": 31337,
+  "source": "operator-reviewed private Anvil deployment",
+  "rpcUrl": "http://127.0.0.1:8547",
+  "module": "REPLACE_WITH_DEPLOYED_MODULE_ADDRESS",
+  "token": "REPLACE_WITH_DEPLOYED_TOKEN_ADDRESS",
+  "factory": "REPLACE_WITH_DEPLOYED_FACTORY_ADDRESS",
+  "registry": "REPLACE_WITH_DEPLOYED_REGISTRY_ADDRESS",
+  "tokenDecimals": 6,
+  "tokenSymbol": "USDC",
+  "ownerAddress": "REPLACE_WITH_TEST_SAFE_OWNER_ADDRESS",
+  "settlementUrl": "http://127.0.0.1:6572",
+  "runtimeUrl": "http://127.0.0.1:6490",
+  "marketBundleMetadataUrl": "http://127.0.0.1:6583/skills/bundles/REPLACE_WITH_MARKET_SERVICE_ID/metadata",
+  "bundleSha256": "REPLACE_WITH_PUBLISHED_BUNDLE_SHA256",
+  "maxUsageUnits": 1
+}

package/doc/reference/public-deployment-settings.md

@@ -0,0 +1,56 @@
+# Public deployment settings and owner signer
+
+## Public facts
+
+User settings published by Market retain the existing fields: mode, chainId,
+source, rpcUrl, settlementUrl, module, token, factory, registry, tokenDecimals,
+tokenSymbol and the official-test metadata URL/digest/usage fields.
+Supported mode labels are private-anvil and production; neither chooses a signer.
+chainId must be a positive safe integer. HTTPS and loopback HTTP are permitted;
+URL credentials, queries and fragments are rejected. Token decimals are 0–36.
+Addresses must be valid nonzero EVM addresses. No participant Safe, owner, secret
+or ownerSigner is accepted in the public User settings.
+
+Provider settings retain network as eip155:<chainId> and assetAddress rather than
+renaming their existing wire fields. Their numeric network and token constraints
+match User settings. The Provider no longer defaults missing network to 31337.
+This aligns the role-specific projections; it does not add a Protocol wire version
+or claim the deployment scripts already generate one authoritative manifest.
+
+Official package metadata remains release-pinned by User. Accepting another
+network configuration never authorizes a substituted executable package.
+
+## Local signer selection
+
+Owner signing is selected independently of network:
+- external: prepare operations for the Safe owner; never call an unlocked test account.
+- anvil: explicit private test adapter; still requires chain 31337 and loopback HTTP.
+  The adapter also verifies the actual RPC chain and single-owner test Safe.
+
+The initial private guide asks for this choice (default external) and saves it in
+its local settings. When the participant confirms owner operations, it persists
+runtime/owner-signer.json inside the User data directory as a private file:
+`{"version":1,"kind":"external"}` or `{"version":1,"kind":"anvil"}`.
+Renew/revoke read this local choice. AGENTPAY_OWNER_SIGNER can explicitly override
+it for the current process. No record means external; existing installations are
+not silently opted into test signing based on chain ID.
+
+For an existing private installation with no saved selection, an operator may use
+`AGENTPAY_OWNER_SIGNER=anvil ./run policy renew` (or revoke) only when that actual
+authorization change is intended. Do not run either command merely to configure
+the signer. No local Wallet Policy/key/history is changed by reading the selection.
+
+## Implemented approval and remaining acceptance
+
+The common setup runner accepts configured EVM networks and uses the same draft,
+plan, chain checks and Wallet binding. Its historical module/local settings filename
+is retained for checkpoint continuity. External approval serves a temporary local
+website for an injected owner wallet, with a portable export fallback. Setup, renewal
+and revocation retain their operation plans and check actual chain effects before
+continuing. An external signer can be selected on Anvil. See
+[browser approval](../runbooks/safe-owner-web.md) for execution and recovery.
+Single-owner private Anvil acceptance does not prove multisig, headless recovery or
+public-network readiness; those acceptance gates remain in [TODO](../TODO.md).
+
+The official test package/network map is still private-only. Another network pauses
+before that package installation after retaining its verified authorization.

package/doc/reference/random-skill-contract.md

@@ -0,0 +1,18 @@
+# Official random-service test example
+
+The random service is the maintained post-setup payment connectivity example. Its
+business input/output belongs to the reference Skill and Provider, not Runtime's
+common protocol. Runtime accepts per-call service references and business JSON;
+see [common invocation contract](multi-service-runtime.md).
+
+The official test uses a release-pinned package digest from User. Market can supply
+public download metadata but cannot replace trusted executable bytes. A new paid
+test requires explicit quote confirmation; an interrupted test resumes its original
+request. Normal startup, Orders, cache and Policy management do not require this
+service to be selected globally.
+
+The editable reference implementation is published in
+[AgentPay Agent](https://github.com/c4rO-0/agentpay-agent). User's local test fixtures
+are controlled copies for development, not a source of trusted production packages.
+See [official package maintenance](../runbooks/official-test-package.md) and
+[Skill author integration](../runbooks/runtime-skill-client.md).