@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/doc/reference/result-file-cache.md

@@ -0,0 +1,166 @@
+# Local result file cache
+
+Current source, 2026-11-04: [unified cache management](../runbooks/local-cache.md)
+includes text/file display, both durable result stores and saved Provider source.
+The output APIs below remain supported through the shared store. Controlled binary
+verification passed; actual paid binary-service acceptance is a separate gate.
+
+Implemented and verified within the private scope on 2026-11-02. See the
+closeout (private historical evidence; not distributed) for controlled tests,
+participant restart/unlock and unverified environments.
+This is an optional local Runtime interface, not a Provider wire requirement.
+
+## Operations
+
+All routes are authenticated POSTs on the existing loopback Runtime with its
+existing caller credential. Download requires exactly one saved Order with a verified
+local result matching its original service/request. Listing and removing cached files
+remain possible even when the original result file is missing or damaged. No Wallet signature, new payment, Provider service execution
+or receipt confirmation is part of these operations.
+
+| Route | JSON fields | Result |
+| --- | --- | --- |
+| `/files/cache` | `orderId`, `fileKey`, `url`; optional `filename`, `sha256` | Download/reuse metadata, including generated local path when available |
+| `/files/list` | `orderId`; optional `offset`, `limit` (1–100) | Saved file metadata for this Order |
+| `/files/remove` | `orderId`, `fileKey`, `confirmed: true` | Delete local copy and retain metadata with removed state |
+
+The installed Runtime client exports `cacheResultFile`, `listResultFiles`, and
+`removeResultFile`. Skill authors select a file URL explicitly; Runtime does not
+inspect arbitrary business output for links or force a new output schema.
+
+```js
+import {loadRuntimeConnection, cacheResultFile, listResultFiles}
+  from './runtime-client.mjs'; // Installed User client module, not a copied implementation.
+const connection = await loadRuntimeConnection();
+const file = await cacheResultFile(connection, {
+  orderId, fileKey: 'report', url: reportUrl, filename: 'report.pdf',
+  // sha256: expectedDigest, // Optional expected digest from your delivery contract.
+});
+const files = await listResultFiles(connection, orderId);
+```
+
+Skill bootstrap code must resolve the installed User client through the saved local
+connection as it already does. The illustrative import above denotes that installed
+module; it is not a requirement to bundle transport or copy credentials into Skills.
+Use `./run orders files ORDER_ID` to list copies and
+`./run orders files ORDER_ID remove FILE_KEY` to remove one after terminal confirmation.
+Listings show up to 100 entries, newest first; use `./run orders files ORDER_ID list 2`
+for the second page. Runtime must be running; Wallet unlock is not needed. `confirmed: true` is an explicit operation acknowledgement, not an
+OS isolation or cryptographic owner approval. Agents have the local caller boundary.
+
+`fileKey` is 1–80 ASCII letters/digits/dots/underscores/hyphens and identifies one
+file within the Order. Reuse the same key for retry. An expired URL may be replaced only when the
+record already has a known local or expected digest; downloaded bytes must still
+match that digest. Preserve the original optional `sha256` argument. Without any
+known digest, use the original URL or explicitly select a different file key;
+Runtime cannot establish that a newly supplied link contains the original bytes. Display filenames never form filesystem paths.
+URLs, query credentials and file contents are not returned in routine metadata or
+logged. Available metadata contains size, SHA-256, generated path, timestamp,
+transport (http/https), and integrity description. Inspect the state before using a
+path. The file is never executed, extracted, or rendered by Runtime.
+
+## Transfer and integrity
+
+HTTP and HTTPS are supported, including explicit ports. HTTP is unencrypted;
+metadata reports its transport. Neither transport alone proves delivery correctness.
+Source URLs may differ from the Provider service endpoint.
+
+DNS answers are validated; allowed addresses are tried in order and pinned to each
+connection. Up to five redirects are revalidated hop by hop; HTTPS-to-HTTP
+downgrade is refused. Direct HTTP remains supported.
+Private, loopback, link-local/metadata and reserved destinations are denied by
+default. Embedded URL credentials are refused. Identity transfer is requested;
+gzip, deflate and Brotli responses are decoded with both transfer and decoded-byte
+limits. Unknown HTTP encodings are rejected; this does not restrict archive file formats. Caller/Wallet credentials are never forwarded. Optional signed query URLs
+remain only in private metadata; protect cache backups accordingly.
+
+An operator may set `AGENTPAY_USER_FILE_CACHE_PRIVATE_ORIGINS` to a JSON array of at
+most 16 exact origins, e.g. `["http://127.0.0.1:8123"]`, in the Runtime environment
+for controlled private fixtures. Only that scheme/host/port is excepted; DNS is still
+pinned. Only loopback/RFC1918/ULA destinations qualify for this exception; metadata
+link-local and reserved addresses remain blocked. No wildcard/all-private-network
+option exists. Default is `[]`; the installer does not enable an exception.
+
+Transfers stream to private temporary files, enforce the actual byte limit even
+without Content-Length. Default total transfer timeout is 15 minutes, configurable
+up to 24 hours. Connection/header attempts are capped at 10 seconds each within
+that total budget. These are local resource limits, not Provider delivery deadlines. No partial file is marked
+available. After restart, the first cache operation validates completed bytes with a durable
+digest and finishes publication where possible; other interrupted transfers are
+marked failed and their owned partial bytes removed. Retrying restarts only the download; no
+byte-range append or automatic background network retry is implemented.
+
+An optional expected SHA-256 must match. Otherwise the digest records local bytes
+only. A Skill-supplied digest is not itself evidence from Settlement. Metadata uses
+`expected_digest_matched` or `local_digest_only`; neither is an evidence-binding
+claim. Reuse rechecks the saved file hash, size and permissions. Listing shows saved
+metadata and does not reread/hash every binary. If a previously downloaded URL later
+serves different bytes, retry cannot silently replace the known digest. Original
+links may expire; refreshing one is separate from buying/executing the service.
+
+## Storage, limits and cleanup
+
+Storage is under `runtime/invocations.json.files/` in selected User data. Index and
+binary files are owner-private (0600); directory is 0700. Generated SHA-256 storage
+names derive from Order ID/file key. Files and index updates are fsynced and published
+atomically. Metadata stores state/timestamps, source and integrity; it retains
+removed/failed records. Local backup contains private result data and URLs.
+
+Default limits: 100 MiB/file, 512 MiB shared input/output file bytes, 20 non-removed records per request or Order,
+2 concurrent transfers, 10,000 retained history records and 8 MiB metadata.
+Removed copies free byte capacity and per-Order slots. Removed history remains
+bounded separately: at its cap, new keys stop with FILE_HISTORY_LIMIT; existing
+keys remain reusable. History is not silently deleted. Operators can raise the
+record cap (up to 100,000), subject to the metadata byte cap.
+
+Prefer `./run cache settings` to inspect/change limits live. `./run cache settings`
+also shows saved limits and the optional settings path:
+`runtime/invocations.json.file-cache-settings.json` under selected User data.
+Create an owner-private (0600) JSON file containing only the overrides needed:
+
+```json
+{"singleBytes":209715200,"totalBytes":1073741824,"timeoutMs":3600000}
+```
+
+Other keys are `filesPerResult`, `concurrent`, and `records`. Values must be positive
+integers; singleBytes cannot exceed totalBytes; totalBytes is capped at 1 TiB,
+concurrent at 16, records at 100,000 and timeoutMs at 86,400,000. Manual file edits require Runtime restart (`./run service restart` also locks Wallet);
+`./run cache settings KEY VALUE` applies changes live without that restart. Invalid optional cache settings
+fail file operations without stopping Runtime's Order recovery. Limits cannot be
+supplied by a Skill in route requests.
+
+URL transfers reserve the maximum file size; local inputs reserve their checked
+file size. Reservations subtract already-written partial or published bytes;
+actual stored bytes also count. A small file may still require one full-size slot.
+Cache ownership uses `fs-native-extensions` 1.5.3 through a small file-lock adapter.
+Each Runtime retains a descriptor for the empty `owner.lock` file in the cache
+folder. OS locks release on process exit/crash; the file itself remains and must
+not be deleted/replaced while Runtime is running. There are no heartbeat timers,
+PID-reuse assumptions or extra ports. Multiple handles in one process share a queue.
+
+The pinned package ships Node prebuilds for Linux, macOS and Windows x64/ARM64;
+this host verified Linux x64 with Node 22.22.3 using installation scripts disabled,
+without compilation. The lock adapter no longer rejects other OSes. This is not a
+claim that all User filesystem permissions, startup or CLI operations have been
+ported/tested on Windows/macOS/mobile. Actual supported environments remain subject
+to platform acceptance. Network/shared-filesystem locking is not validated.
+
+If the native binding is unavailable, file operations fail with
+`FILE_CACHE_LOCK_UNAVAILABLE`; they never silently skip locking. Reinstall the
+locked User dependencies with `npm ci` and restart Runtime; if the error persists,
+report the Node/OS/architecture to support. Runtime startup and Order recovery do
+not load this optional native binding. A lock file left after a crash is normal:
+do not manually delete it to recover. Full uninstall still stops services first.
+
+Removal first persists deletion intent, then deletes bytes and records completion;
+restart finishes interrupted deletion. Removal retains history and does not cancel/refund an Order or remove structured
+results. Cache-full never evicts original data. The existing confirmed all-local-data
+uninstall removes this subdirectory with User data. Back up the complete User data
+folder privately to retain pending/verified results, files, history and signed URLs;
+key/Policy backup alone cannot restore file contents.
+
+Tests use controlled streams, default HTTP/HTTPS clients with normal certificate
+validation, actual SIGKILL transfer recovery, and two
+maintained business payloads through Runtime. They are not production network or
+live paid acceptance, and do not establish that an arbitrary Provider can retain or
+reissue files indefinitely.

package/doc/reference/runtime-address-recovery.md

@@ -0,0 +1,42 @@
+# Runtime address and original-request recovery
+
+Implemented recovery boundary; participant and real-network scope remain in TODO.
+A local Runtime URL is transport location, not purchase identity. Historical records
+that included an address are retained for guarded lookup rather than silently reset.
+
+## Existing-only recovery
+
+Treat loopback Runtime URL as a connection location. Preserve service/profile/input,
+caller request ID, original orderRequestId, authorization scope and any known Order
+ID as recovery evidence. Do not add a machine ID or bind nickname to an installation.
+
+Before allowing a changed destination, inspect the original request through the
+authenticated local interface. Do not create state during this check. Continuing a
+recovered request must atomically require that original invocation still exists and
+matches: a separate successful preflight alone cannot protect against state removal
+before execution. Missing, mismatched or ambiguous history stops paid continuation.
+The new Runtime may not silently call begin's create branch for a recovery request.
+
+Default selection must find old records independently of the changed port. Preserve
+historical records and block ambiguity; do not overwrite legacy keys or silently
+choose one of multiple candidate requests. Valid local verified results can be read
+without restarting a purchase. Explicit new-purchase intent remains separate.
+
+A truly never-submitted request needs a separately justified creation path; absence
+of a local Order ID is not proof that it never reached Runtime. A lost-history
+reinstall requires original-order reconciliation, not blind URL replacement.
+
+## Required regression coverage
+
+Same history/new port; same Wallet/missing history; changed service/input/scope;
+legacy address-keyed selection; multiple candidates; concurrent selection; crash
+between lookup and execution; saved result reuse. In every recovery failure assert
+zero new prepare/sign/fund calls. Use two maintained business payloads. No old
+Policy, Order, commitment or service profile is rewritten.
+
+## Related input snapshots
+
+The approved [Skill input/output persistence plan](skill-input-output-cache.md) adds
+request-scoped file snapshots without changing the existing-only recovery requirement.
+Implement and verify these together at the invocation boundary; cached files alone
+do not prove that another Runtime retains the original financial history.

package/doc/reference/runtime-result-cache.md

@@ -0,0 +1,157 @@
+# Runtime result records and file caching
+
+Date: 2026-11-02. All three implementation loops are complete within the
+recorded private scope (private historical evidence; not distributed), including
+participant restart/unlock. This plan introduces no new Provider output protocol.
+
+
+## Goal and existing behavior
+
+Preserve a paid service's original result across Runtime/Agent interruption without
+buying or executing the service again. Separate payment status, delivery evidence,
+local result availability and downloaded file availability.
+
+The initial verified-result store used `runtime/invocations.json.results/` and saved
+only after evidence verification. Implemented loop 1 now saves a bounded pending
+record first, then verifies and promotes it; local recovery distinguishes missing,
+pending, invalid and old-format results. Loop 2 keeps binaries and transfer metadata
+separate. See the current file-cache reference for implemented behavior and limits.
+A JSON containing a URL is not a local copy of that file.
+
+An initial pending-JSON draft was paused while this layered plan was approved.
+Loop 1 now implements structured result persistence under that plan; it does not
+implement file downloads. Current pending records use a separate private
+`runtime/invocations.json.pending-results/` directory and retain the candidate
+alongside the verified copy. Each record is capped at 2 MiB, matching the existing
+result read limit. Automatic eviction and binary-file quota belong to loop 2.
+
+## Boundaries
+
+- User Runtime owns private local storage and recovery orchestration. Wallet keeps
+  its existing bounded signing/read authority. Settlement stores hashes/usage and
+  delivery evidence, not private output or downloaded files. Market is not a result
+  hosting service. No contract, SQL or shared Provider wire change is required by
+  this plan.
+- Keep Provider output format and existing output-hash semantics application-owned.
+  Do not scan arbitrary output strings for URLs, invent business-specific adapters,
+  require file descriptors in every response, or change what existing receipts mean.
+- A Skill explicitly requests caching of selected files through a generic local
+  interface. This interface is an opt-in local feature, not a new prerequisite for
+  a Provider to accept Orders. The implemented local API is documented in
+  [the file-cache reference](../reference/result-file-cache.md); it is not a Provider wire change.
+- Private contents, download tokens and signed URLs never appear in status/help,
+  routine logs, Market, or Settlement. Local OS ownership is the protection boundary;
+  this is not isolation from another process running as the same OS user.
+- Cache state never authorizes payment, confirms receipt, changes dispute deadlines,
+  proves service quality, or automatically creates a replacement purchase.
+
+## Storage and separate states
+
+Keep the existing verified-record format and location. Add separate pending result
+storage and file storage under the selected User data directory, with private owner
+permissions. Paths/names supplied by the Provider must not determine filesystem
+paths; use generated internal identifiers. Original human filenames are metadata.
+
+| Layer | States and meaning |
+| --- | --- |
+| Financial Order | Existing authenticated Settlement state; never inferred from cache |
+| Result record | Missing; pending evidence; verified; invalid; older format not verifiable |
+| File | Not downloaded; downloading; available locally; interrupted/failed; removed locally |
+| File integrity | Local digest recorded; expected digest matched, if provided; evidence binding verified only when the existing delivery contract supports it |
+
+Do not label an old-format result as absent if bytes exist. Do not label a local
+hash as Provider authenticity: a digest computed after download proves only local
+integrity unless independently bound to the agreed original evidence. A verified
+structured result may coexist with undownloaded/expired file links. No implicit
+"all files complete" claim is possible for unknown application-owned output.
+
+Result records contain the original invocation/Order identity and service binding,
+verification state and timestamps. File metadata references the original result,
+local generated file identity, display filename, actual size, digest, source and
+transfer state. Avoid putting binary content/base64 blobs in result JSON.
+
+## Result receipt and restart
+
+1. Validate Provider response shape, size, identity and output integrity using the
+   existing service contract. Save the bounded result as pending before waiting for
+   Settlement's evidence. Do not return it as a successful verified delivery yet.
+2. Verify original Order/service/request, output hash and usage against authenticated
+   Settlement evidence using the original Policy scope. Revocation or unavailable
+   authority stays a visible blocker; no Safe-only lookup or rebinding workaround.
+3. Atomically promote the result to verified, then return it. Crash between promotion
+   and response must return the same saved result on retry. Conflicting candidates
+   never silently overwrite the original. Avoid comparing mutable disclosure fields
+   as if they were immutable delivery content.
+4. Startup/background recovery may verify saved pending results using bounded reads;
+   it must not invoke Provider service execution, submit payment or confirm receipt.
+   Explicit same-request resume can use this pending copy before considering service
+   execution. Existing financial closure still governs all service/mutation actions.
+5. Corruption, disk-full, partial writes, concurrent recovery and unknown legacy
+   formats must fail visibly and preserve original history. Persisted pending state
+   must be included in orphan/history checks and limits. Unverified files never
+   become ordinary verified results merely because an Order was paid out.
+
+When no result was durably received (for example the process dies before receiving
+the response), local caching cannot solve that loss. Original Provider retrieval,
+its permissions and applicable support deadlines remain the recovery route.
+
+## File transfer
+
+- Skill calls a bounded, authenticated local cache operation for an explicitly
+  selected result/file. Do not reuse the payment or generic signing interface.
+- Support HTTP and HTTPS; record whether the source transport is encrypted. Validate destination resolution and redirects, including private,
+  loopback, link-local and metadata endpoints; prevent DNS rebinding/redirect bypass.
+  Controlled private rehearsal fixtures require explicit narrow configuration,
+  never a global private-network bypass.
+- No arbitrary filesystem writes, automatic unpacking, execution, previewing active
+  content, or forwarding Wallet/Runtime tokens to remote sources. Arbitrary remote
+  authentication headers are not an initial feature. Keep any permitted signed URL
+  private; redirect changes must not leak credentials.
+- Stream to a temporary file, cap actual bytes even without Content-Length, enforce
+  deadlines/concurrency and reserve quota before writing. Match a supplied expected
+  hash where applicable, then fsync and atomically publish. Partial bytes are not an
+  available result. Leave original identity intact after timeout/network failure.
+- Initial restart recovery may retry only the file transfer. Byte-range continuation
+  is optional: use it only with reliable validators preventing mixed file versions;
+  otherwise restart the download rather than append blindly. Never invoke the paid
+  service again to refresh an expired link.
+- If the URL expired or content changed, retain the failure and original metadata.
+  Requesting an original file again is distinct from rerunning the service. No claim
+  that every Provider can reissue URLs or retain outputs indefinitely.
+
+## Capacity and cleanup
+
+Implement bounded total file bytes, single-file bytes, per-result file count and
+concurrent transfers. Implemented defaults and configuration names are documented in the
+[file-cache reference](../reference/result-file-cache.md); the cache is bounded. Account for
+concurrent reservations, interrupted temporary files and disk-full failures.
+
+Do not automatically evict Order history, evidence metadata or pending result records
+to make room. At the limit, stop new file downloads with a clear action. Initial
+cleanup is deliberate: show scope/size, confirm, delete only selected local file
+copies, and retain metadata marked removed locally. Protect in-flight writes and
+use locks/atomic transitions so cleanup cannot publish a deleted transfer as ready.
+Later automatic retention requires its own explicit policy. Uninstall's existing
+confirmed all-local-data removal includes this storage. Backup guidance must explain
+that restoring keys/Policy alone does not restore private result/file copies.
+
+## UX and implementation loops
+
+1. **Result preservation:** pending → evidence verification → verified; read-only
+   restart recovery; accurate missing/invalid/legacy/pending messages in status,
+   orders and details. Keep structured results general. Verify crash boundaries,
+   wrong evidence, revoked Policy, disk errors and concurrent same-request resume
+   with at least two maintained business payloads through one Runtime.
+2. **File cache:** finalize the local Skill client interface and limits; implement
+   metadata + streaming file storage, safe downloads, interruption/retry, quota and
+   deliberate cleanup. Test maintained text/binary fixtures, malicious destinations,
+   redirects, changed downloads, large/unknown-length streams and cleanup races.
+3. **Integration and acceptance:** document Skill-author usage and local CLI access;
+   distinguish original Order status, record verification and file availability.
+   Integrate uninstall/backup/info. Participant tests use official controlled fixtures,
+   preserve original Policy/history and avoid third-party Skills. No new purchase is
+   needed merely to inspect existing cache. Report source tests separately from
+   real-process and human acceptance.
+
+The loops above were completed in sequence; see the closeout for their evidence. Neither a JSON placeholder
+nor mocked downloads constitute acceptance of durable binary file recovery.

package/doc/reference/runtime-startup-recovery.md

@@ -0,0 +1,141 @@
+# Runtime startup self-check and Order recovery
+
+Status: source implementation and isolated verification completed on 2026-10-24;
+participant restart/unlock and legacy settled-Order reconciliation were reported.
+Full login/reboot and missing-result restoration are not established. See verification and limits (private historical evidence; not distributed).
+The source review table below records the pre-change findings.
+This plan precedes discussion of `./run update`; it does not authorize real funds,
+new Orders, deletion of participant history, or widening Wallet authority.
+
+## Required behavior
+
+Start Runtime's safely configured local listener before asynchronous Order checks.
+A historical business record, locked Wallet, unavailable network or old routing
+format must not cause a restart loop. Report separately: process liveness,
+self-check progress, Wallet availability/lock/Policy state, and purchase readiness.
+An authenticated status view explains blockers and the next action without exposing
+private input/output, signatures or credentials. Public health remains minimal.
+
+This is not permission to listen without caller authentication, bind publicly,
+overwrite a live socket/port, or ignore unsafe installation ownership. If the
+listener itself cannot safely start (occupied port, missing/unsafe authentication
+material), the CLI must explain repair; do not claim that every configuration can
+produce a running HTTP server. Wallet capability failure may disable Wallet actions
+without disabling an otherwise safely authenticated status listener.
+
+Run local checks first, then reconcile eligible historical Orders in a bounded
+background queue. Self-check does not prepare an Order, sign/submit a payment,
+request service authorization, execute a Provider request, confirm receipt, cancel
+an Order, or revoke/change Policy. These remain existing explicit invocation or
+administrative flows. The existing Settlement workers own automatic closure/refund.
+
+## Two independent outcomes
+
+A financial terminal state (Released, Refunded or Cancelled) is separate from
+verified local result availability. Delivered is not financial finality. A cached
+result does not establish payout; payout does not establish that the client saved
+or received the output. Store observations with source, identity and observed-at
+epoch time; retain original invocation/request/Order identities and replay fences.
+These are local projections, not new Protocol enums or rewritten wire states.
+
+## Recovery matrix
+
+| Observed condition | Startup self-check / permitted recovery | Purchase boundary and user action |
+| --- | --- | --- |
+| No history in a genuinely new installation | Complete local inventory; inspect Wallet/configuration | Normal readiness still required. Missing history in a previously used installation is not proof of a new installation. |
+| Wallet missing, stopped, locked or unbound | Keep Runtime available; expose specific dependency status; retry after dependency changes | No payment without Wallet's existing checks. Prompt start/unlock/setup as appropriate. Never save an unlock secret. |
+| Settlement/network unavailable or maintenance | Keep last observation explicitly stale; retry boundedly with backoff | Do not claim finality or replay a payment. Unresolved affected calls wait. |
+| Valid current history and verified cached result | Validate result binding; separately reconcile financial status | Same-call result reuse needs no new payment; report any pending financial check separately. |
+| Invocation exists, no saved Order ID | Preserve orderRequestId and commitmentNonce; inspect what read APIs can establish | Lost prepare response may still mean an Order exists. Self-check must not call prepare as a substitute for read. Only original explicit resume may use its established idempotent path. |
+| Signed payload saved, payment outcome unknown | Read original Order/funding evidence using saved identity | Neither paymentSubmitted false nor a timeout proves no funding. No replacement Order, nonce or signature generated by self-check. |
+| Funded, not yet accepted | Observe acceptance/closure/deadlines | Do not cancel because Provider briefly goes offline. Existing user cancellation and Settlement timeout rules apply. |
+| Accepted, still executing | Observe original Order and deadline | No new service execution in background. Resume original request explicitly; accepted service deadline remains authoritative. |
+| Delivered, payout pending | Track finalization/refund/closure observations separately from output cache | No startup receipt acknowledgement or accelerated payout. |
+| Released, verified result saved | Persist verified financial observation; retain result and request replay fence | Same request returns existing result where its format is supported; no purchase. |
+| Released, result absent or incompatible | Record settled transaction and unavailable/unverified result separately | Do not rerun the service or fabricate output. Existing Provider result retrieval may be used only if supported by the original contract and authorization; otherwise explain limitation. |
+| Refunded or Cancelled | Persist verified terminal observation, preserve request identities and any valid result evidence | Same request stays terminal, not a fresh purchase; refunds do not restore cumulative Policy spend. |
+| Legacy routing record | Preserve original bytes, IDs and binding; reconcile independently of current call routing where authoritative identity is available | No automatic routingVersion addition or coercion into new service context. Known request stays fenced; terminal history need not block unrelated new calls once scope is safely known. |
+| Corrupt/unknown schema, conflicting IDs, unsafe file or write failure | Preserve source; report repair needed; isolate only if records can be reliably identified | If affected scope is unknown, pause all new paid calls while status stays available. Never replace unreadable state with an empty store. |
+| Order not found, chain/Factory/Policy/deployment changed | Keep unresolved; require matching original deployment and identity evidence | A 404 or wrong current deployment does not mean unpaid. Do not silently query new deployment as if it owned the old Order. |
+| Local and authoritative observations conflict, or finality is insufficient | Preserve evidence and mark pending/review; recheck matching source | Do not pick a convenient terminal result or release replay protection. |
+
+## Identity, authority and scope
+
+Use Wallet's formal `readSettlementOrder` IPC and Settlement's Buyer-scoped read
+endpoint; a normal User never reads server SQL or operator files. Today that HTTP
+read requires a signed authentication request. Wallet locked means remote checks
+wait for unlock; do not bypass authentication or add anonymous Order disclosure.
+Signing a read authentication request is not payment signing.
+
+Match Order ID, Buyer, chain, original Vault/Factory/Policy when available, service
+reference and request hash. Persist only verified observations. For historical
+records whose deployment facts cannot be recovered reliably, report the gap rather
+than guessing. Optional independent chain verification must use the exact original
+identity and existing finality policy; changing chain rules is outside this plan.
+
+The participant's one legacy Order has independently observed Released state and
+zero Vault balance on private Anvil. This proves the scoped chain observation,
+not client result availability or a fresh Settlement database reconciliation.
+Do not hard-code that Order or the reference random service into implementation.
+
+Until initial inventory establishes a trustworthy replay boundary, block new paid
+calls. After inventory, isolate known affected requests; allow unrelated requests
+only when duplicate-payment scope is reliably bounded and normal Wallet/Settlement
+readiness passes. Global pause remains valid for unreadable/conflicting history.
+An explicit new user request (`--force`) is not an automatic recovery fallback.
+
+## Concurrency, persistence and scheduling
+
+- One self-check scheduler per Runtime; bounded batch/concurrency and timeouts,
+  capped retry backoff with jitter. Wake on restart and dependency recovery;
+  no unbounded timers, pending promises or frequent polls of confirmed terminal Orders.
+- Serialize background observations with foreground invocation updates. A stale
+  read must not overwrite a newer outcome; merge observation metadata without
+  mutating immutable request/Order/payment identities.
+- Persist recovery observations atomically and durably. Crash during checking,
+  writing or restart resumes the same work. No archival or format migration that
+  opens a window for a known invocation ID to become a new purchase.
+- Do not remove replay fences/results on terminal detection or introduce indefinite
+  new copies of private payloads. Any archive schema/retention change is reviewed
+  separately; preserve existing source history in the first implementation.
+- Stop scheduling on shutdown and bound outstanding calls. Status counts distinguish
+  checked, waiting on dependency, unsettled and needs-review; no misleading all-clear
+  based solely on an empty queue or a successful `/health` response.
+
+## Source review: existing coverage and gaps
+
+| Component / source | Existing behavior | Required work |
+| --- | --- | --- |
+| User `src/index.mjs` startup | Calls requireCurrentRouting before server.listen; initial Wallet credential failures also exit | Decouple safe listener from business checks and expose authenticated readiness/status. |
+| User `src/invocation-store.mjs` | Whole-document validation, durable IDs and atomic saves; legacy mismatch fences repeats | Add read-only inventory and bounded isolation without weakening begin/update checks; choose storage evolution explicitly. |
+| User `src/invocation-result.mjs` | Independently persisted verified results; binding checks | Keep output status distinct from money; inspect cached-result conflicts without erasing records. |
+| User `src/index.mjs` invocation path | Reads original Order on active recovery; saves result before HTTP success; no background reconciliation | Add independent read-only scheduler and serialize observations with invocation writes. |
+| User `src/order-closure.mjs` | Fences cancellation/refund/closure; does not treat Released as result availability | Define terminal financial classification for background work; preserve valid cached output. Review Released-without-result continuation explicitly. |
+| Wallet `src/ipc.ts`, `src/settlement-http.ts` | Bounded authenticated Order reads; signing requires unlock | Reuse current authority; expose waiting-for-unlock clearly. No generic signing or new secrets. |
+| Settlement `src/agentpay-order-preparation-store.mjs` | Buyer-scoped Order projection, deadlines, closure/finalization and delivery evidence | Verify existing projection covers legacy/terminal reads. Read-by-orderRequestId and old-Policy access are gaps to assess, not assumed supported or newly authorized endpoints. |
+| User lifecycle/status and installer | systemd supervision, lock status, preserved settings; no complete upgrade inventory | Add readiness presentation and preflight before disruptive upgrade actions. Defer update orchestration until this recovery loop is closed. |
+
+## Implementation and acceptance order
+
+1. **Safe startup and local inventory.** Separate liveness/readiness, retain replay
+   fences, classify legacy/corrupt/current records and dependency failures. Test
+   the actual process starts with a valid secure listener despite old history;
+   affected/unknown-scope paid calls are fenced and state bytes remain unchanged.
+2. **Read-only Order reconciliation.** Use formal authenticated reads, independent
+   financial/result observations, durable writes, bounded retries and concurrency.
+   Test all matrix branches including absent Order ID, wrong identity, locked Wallet,
+   maintenance, incomplete funding, terminal state and conflicting cache. Any shared
+   API/storage change requires consumer review before implementation.
+3. **Recovery and upgrade handoff.** Present actionable status in `./run status`
+   and install/setup; verify restart during scans/writes, race with active calls,
+   repeated restarts and no duplicate payment. Preserve known request IDs through
+   any approved legacy handling. Use maintained fixtures with at least two business
+   payloads and official connectivity material only.
+4. **Participant acceptance.** Re-read the supplied desktop record, reconcile with
+   matching authority, and verify Runtime stays running, old request cannot trigger
+   a new purchase, and Wallet lock/unlock does not restart Runtime. Additional paid
+   acceptance needs explicit scope; do not rerun connectivity purchase automatically.
+
+Each loop gets focused tests and evidence before the next. Mock tests do not prove
+real process restart, chain settlement or participant usability. `./run update`
+remains a subsequent design discussion, not part of this implementation approval.

package/doc/reference/skill-input-output-cache.md

@@ -0,0 +1,93 @@
+# Skill glue and shared input/output persistence
+
+Implemented design reference. Current release/participant gates are tracked in
+[TODO](../TODO.md); this document is not new deployment or payment authorization.
+
+## Responsibilities
+
+The editable Skill is glue: it validates application input, explicitly identifies
+input/output files and adapts application data to its Provider interface. The
+installed User client owns common persistence and recovery. Runtime continues to
+own the existing bounded payment, service authorization and delivery verification
+path. This work does not move those operations into arbitrary Skill callbacks.
+
+Shared caching does not impose a common Provider business payload or result
+format. Input remains supported bounded JSON, including arrays and nested data;
+it is not necessarily text. Binary data belongs in separate files, not an enlarged
+JSON/base64 payload. Only hashes and existing required metadata reach Settlement;
+private content remains local or travels to the selected Provider.
+
+## Invocation lifecycle
+
+1. Validate input and select/preserve the original request ID. Persist explicit
+   file declarations and preparation state before copying files or submitting a
+   paid invocation. An incomplete snapshot cannot be mistaken for a file-free call.
+2. Save JSON using the existing checkpoint mechanism. Snapshot only files the
+   Skill explicitly declares; ordinary strings, paths and URLs are not instructions
+   to read or fetch. Record a stable file key, size and content digest. Write files
+   durably before marking the complete input snapshot ready.
+3. Application adaptation consumes the saved copies, not mutable original paths.
+   Preserve the exact final business request used for its existing request hash.
+   Provider-specific upload/reference construction must not be silently invented
+   by the common client. A changed or expired upload reference is not permission
+   to change an already submitted business request or create another Order.
+4. Continue through the existing Runtime payment/invocation path. Before the first
+   network submission, durably record that submission may occur; a crash or missing
+   local Order ID is not proof of non-payment.
+5. Retain the existing verified structured-result persistence. A Skill explicitly
+   selects output files for the existing Order-scoped cache. Cache/download failure
+   is distinct from paid service failure: retain the verified result and retry
+   caching only, without invoking the paid service again or confirming receipt.
+6. Resume by original request identity and saved inputs. A valid saved result can
+   be read without requiring its original input files to remain available. A resume
+   that still needs input bytes must stop if their snapshot is missing or corrupt.
+
+Inputs are request-scoped because an Order may not exist yet. Outputs keep their
+existing Order/evidence scope. Do not invent Order IDs for input caching or change
+delivery hash rules to match cache digests. Runtime URLs are connection locations;
+port changes do not create new request or file identities. The separate
+[address recovery plan](runtime-address-recovery.md) still requires atomic
+existing-only continuation when recovering potentially submitted requests.
+
+## Retry and storage boundaries
+
+- Repeating a matching invocation selects its existing snapshot before reading
+  mutable sources. An edited/deleted original file does not replace saved bytes.
+  Deliberately using new input remains an explicit new request; `--force` retains
+  its existing additional-purchase meaning and never bypasses Policy limits.
+- A missing snapshot after possible submission is a recovery problem, not a reason
+  to reconstruct from changed files. Legacy JSON-only requests remain JSON-only;
+  never infer missing file declarations from historical strings.
+- Use bounded streaming, private local storage, atomic manifests and the existing
+  portable locking approach where appropriate. Do not introduce Linux-only process
+  identity checks or another lock protocol just for this feature.
+- Reuse download validation for explicitly declared URL sources; do not assume
+  HTTPS-only Providers. Do not forward Wallet, Runtime or platform credentials to
+  file hosts. Do not follow symlinks or automatically inspect unrelated local files.
+- Input and output usage must both be visible and bounded. Reusing numeric defaults
+  does not establish a shared quota unless accounting actually includes both stores.
+  Final limits and CLI presentation must be documented with implementation.
+- Never automatically evict inputs needed by unresolved requests. Explicit deletion
+  must explain loss of local recovery, retain request/digest history, and prevent
+  future retries from silently substituting fresh input. Cache cleanup is not Order
+  cancellation. Existing uninstall confirmation covers deletion of local data.
+
+## Implementation sequence and acceptance
+
+The user changed the sequence to **cache foundation first**. The detailed
+[local cache design](local-cache-foundation.md) owns storage and management.
+
+1. Review existing storage; specify shared layout, formats, quotas, crash states,
+   cleanup and management. No payment/Skill integration in this loop.
+2. Implement the shared file store and management commands; reuse existing output
+   capabilities instead of running separate input/output storage engines.
+3. Verify the foundation with maintained arbitrary-byte fixtures, large streams,
+   concurrent operations, disk failures, process interruption and cleanup races.
+4. Attach input snapshots and existing verified results to request recovery;
+   implement address-independent original-record selection and atomic existing-only
+   continuation. Missing history must never create replacement purchases.
+5. Update editable templates and common Skill-client hooks, then verify two business
+   payloads through the same Runtime. Output-download retries must not repeat paid
+   execution. Participant deployment follows review and controlled verification.
+
+No services, policies, stored purchases or public APIs are changed by this plan.

package/doc/reference/wallet-identity-policy-history.md

@@ -0,0 +1,23 @@
+# Wallet identity and Policy history
+
+Market display identity is network + Module + Safe + execution address (delegate).
+The nickname belongs to that identity. Several individually verified Policies may
+be attached, but each remains the access boundary for its own Orders. Same-key
+copies with the same tuple are one Wallet, not separately verified machines.
+
+User keeps one active local spending Policy and preserves original request scopes.
+`./run market connect` proves the current Policy; renewal can continue connection
+to the same Wallet. Failure to connect does not undo a successful on-chain renewal
+or authorize recreating a Policy. Connection receipts are local metadata, not proof
+of live website access.
+
+Spending expiry, revocation and Module disablement stop the applicable new payments.
+Original Order reads/support use their original verified scope and Order-specific
+rules/deadlines; retaining history does not grant a different key access. Never
+merge by Safe or nickname alone. Historical read verification does not change the
+active binding or authorize a new purchase.
+
+Use [Market connection](../runbooks/market-connection.md), [renewal](../runbooks/policy-renewal.md)
+and [backup/restore](../runbooks/wallet-identity.md) for current user procedures.
+Account grouping is not a revocation mechanism: consult
+[emergency stop](../runbooks/emergency-payment-stop.md) for a compromised key.