xytara 3.1.8 → 3.1.10

package/README.md

@@ -1,1228 +1,112 @@
-# xytara
-
-`xytara` is the runtime and payment layer for the public two-repo stack.
-
-> New to the code? Read [`ARCHITECTURE.md`](ARCHITECTURE.md) first. It separates
-> the small execution-and-settlement engine (~9,300 lines) from the large
-> machine-readable breadth catalog, so the real runtime is legible in one sitting.
-
-It exists to let agents, developers, and systems:
-
-- discover tasks and workflows
-- quote work before execution
-- pay through supported payment paths
-- fund reusable balances and credits
-- execute tasks and workflows
-- dispatch runtime work
-- receive deliverables
-- inspect usage, metering, and lifecycle state
-- reconcile payment and settlement outcomes
-- inspect lifecycle state
-- operate through summaries and dashboards
-- review disputes, refunds, and remediation flows
-- integrate third-party adapters
-- emit proof-compatible facts for `xoonya` verification
-
-This repo is the runtime layer. It does not define base proof semantics. It references and emits proof-compatible facts, while `xoonya` owns canonical proof.
-
-The 10-phase public program is now complete. `xytara` is in terminal closeout posture rather than active milestone build posture.
-
-## Public Boundary
-
-The public adoption story is intentionally simple:
-
-- install
-- discover
-- quote
-- pay or spend credits
-- execute
-- receive deliverables
-- hand off to `xoonya` when proof or review is needed
-
-Public docs and package surfaces should help builders integrate and pay for useful work. Real treasury destinations, custody details, and operator-only controls belong in private runtime configuration and operator handling, not in public marketing surfaces.
-
-## Universal Runtime Shape
-
-`xytara` is intended to be usable from:
-
-- CLI and terminal
-- direct API calls
-- chat and agent environments that can issue HTTP calls
-- browsers and hosted checkout flows
-- operating-system or service wrappers
-- partner systems that need to add adapters or registry integrations
-
-The shortest public runtime loop is:
-
-- discover
-- quote
-- pay or spend credits
-- execute
-- receive deliverables
-- inspect results and economic state
-- hand off into `xoonya` when proof or review is required
-
-The frozen runtime-side fact model for that loop is documented in:
-
-- [XYTARA_EXECUTION_TRUTH_MODEL.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/XYTARA_EXECUTION_TRUTH_MODEL.md)
-- [XT1_EXECUTION_TRUTH_STANDARD.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/XT1_EXECUTION_TRUTH_STANDARD.md)
-- [OPERATIONAL_RECEIPT_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/OPERATIONAL_RECEIPT_CONTRACT.md)
-- [MACHINE_IDENTITY_REGISTRY_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/MACHINE_IDENTITY_REGISTRY_CONTRACT.md)
-- [CRYPTO_AGILITY_MATRIX.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/CRYPTO_AGILITY_MATRIX.md)
-- [AUTHORITY_BINDING_LIFECYCLE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/AUTHORITY_BINDING_LIFECYCLE_CONTRACT.md)
-- [PUBLIC_SURFACE_POLICY_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/PUBLIC_SURFACE_POLICY_CONTRACT.md)
-- [OFFLINE_VERIFIABILITY_AND_RECOVERY_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/OFFLINE_VERIFIABILITY_AND_RECOVERY_CONTRACT.md)
-- [ADAPTER_CERTIFICATION_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/ADAPTER_CERTIFICATION_CONTRACT.md)
-- [TRUST_PORTABILITY_BOUNDARY_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/TRUST_PORTABILITY_BOUNDARY_CONTRACT.md)
-- [SIGNED_AUDIT_PROVENANCE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/SIGNED_AUDIT_PROVENANCE_CONTRACT.md)
-
-`XT1` is the coined public name for the `xytara` execution-truth standard, just as `XNYA` is the coined public name for the `xoonya` native proof primitive.
-
-Machine-readable execution-truth surfaces:
-
-- `GET /v1/xt1`
-- `GET /v1/xt1/summary`
-- `GET /v1/execution-truth`
-- `GET /v1/execution-truth/summary`
-
-The frozen multi-surface default-path model for `3.0.0` closeout is documented in:
-
-- [XYTARA_DEFAULT_PATH_MODEL.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/XYTARA_DEFAULT_PATH_MODEL.md)
-
-Machine-readable default-path surfaces:
-
-- `GET /v1/default-path`
-- `GET /v1/default-path/summary`
-- `GET /v1/default-path/:surface_id`
-
-The frozen payment-and-rail claim model for `3.0.0` closeout is documented in:
-
-- [XYTARA_PAYMENT_RAIL_TRUTH_MODEL.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/XYTARA_PAYMENT_RAIL_TRUTH_MODEL.md)
-
-Machine-readable payment-and-rail truth surfaces:
-
-- `GET /v1/payment-rail-truth`
-- `GET /v1/payment-rail-truth/summary`
-- `GET /v1/payment-rail-truth/:profile_id`
-
-The frozen adapter-and-protocol claim model for `3.0.0` closeout is documented in:
-
-- [XYTARA_ADAPTER_PROTOCOL_TRUTH_MODEL.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/XYTARA_ADAPTER_PROTOCOL_TRUTH_MODEL.md)
-
-Machine-readable adapter-and-protocol truth surfaces:
-
-- `GET /v1/adapter-protocol-truth`
-- `GET /v1/adapter-protocol-truth/summary`
-- `GET /v1/adapter-protocol-truth/:profile_id`
-
-The public autonomous-entry model for outside agents is documented in:
-
-- [XYTARA_AUTONOMOUS_ENTRY_MODEL.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/XYTARA_AUTONOMOUS_ENTRY_MODEL.md)
-
-Machine-readable autonomous-entry surfaces:
-
-- `GET /v1/autonomous-entry`
-- `GET /v1/autonomous-entry/summary`
-- `GET /v1/autonomous-entry/:profile_id`
-
-The current runtime breadth already includes:
-
-- discovery and workflow lookup
-- pricing and quote generation
-- direct machine payment
-- credits, grants, entitlements, and delegated spend
-- execution, result packages, and delivery
-- usage metering and account economics
-- hosted checkout and runtime-bridge dispatch surfaces
-- disputes, refunds, and remediation
-- activity ledger, reconciliation, and treasury-control visibility
-- adapter registration, review, and promotion surfaces
-
-It also already carries broader first-class runtime lanes for:
-
-- framework integrations such as `langchain`, `langgraph`, `semantic_kernel`, `autogen`, `crewai`, and `llamaindex`
-- machine and agent protocol fronts such as `mcp`, `a2a`, `a2c`, `acp`, `grpc`, `mqtt`, `kafka`, `nats`, `ros2`, and `webhook_event_bus`
-- identity and registry posture such as `erc8004`, registry identity, attestation refs, and anchor refs
-- operator and observability posture such as telemetry, provenance, artifact distribution, shared signals, feature control, pricing telemetry, and registry-side export surfaces
-
-If you want the broadest machine-readable census for these already-core runtime lanes, inspect:
-
-- `GET /v1/integration-matrix`
-- `GET /v1/telemetry`
-- `GET /v1/provenance`
-- `GET /v1/artifact-distribution`
-- `GET /v1/shared-signals`
-- `GET /v1/feature-control`
-- `GET /v1/adapter-certification`
-- `GET /v1/trust-portability-boundary`
-- `GET /v1/signed-audit-provenance`
-
-## One-Line After Install
-
-If you only run two commands after install, use:
-
-- `xytara start-here`
-- `xytara first-run`
-- `xytara first-run --run-quote --account ACCOUNT_REF --pretty`
-- `xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty`
-- `xytara release --summary`
-
-If you want the shortest machine-readable discovery path, inspect:
-
-- `GET /v1/providers`
-- `GET /v1/frameworks`
-- `GET /v1/protocols`
-- `GET /v1/integration-matrix`
-- `GET /v1/telemetry`
-- `GET /v1/provenance`
-- `GET /v1/adapter-certification`
-- `GET /v1/trust-portability-boundary`
-- `GET /v1/signed-audit-provenance`
-
-If you are working on shared evidence, inspect the operational receipt contract pack:
-
-- `buildOperationalReceiptContractPack()`
-- `summarizeOperationalReceiptContractPack()`
-
-If you are working on machine identity, inspect the registry contract pack:
-
-- `buildMachineIdentityRegistryContractPack()`
-- `summarizeMachineIdentityRegistryContractPack()`
-
-If you are working on crypto agility, inspect the matrix pack:
-
-- `buildCryptoAgilityMatrixPack()`
-- `summarizeCryptoAgilityMatrixPack()`
-
-If you are working on binding lifecycle, inspect the lifecycle pack:
-
-- `buildAuthorityBindingLifecycleContractPack()`
-- `summarizeAuthorityBindingLifecycleContractPack()`
-
-If you are working on public route policy, inspect the surface policy pack:
-
-- `buildPublicSurfacePolicyContractPack()`
-- `summarizePublicSurfacePolicyContractPack()`
-
-If you are working on offline recovery, inspect the recovery pack:
-
-- `buildOfflineVerifiabilityRecoveryContractPack()`
-- `summarizeOfflineVerifiabilityRecoveryContractPack()`
-
-If you are working on adapter certification, inspect the certification pack:
-
-- `buildAdapterCertificationContractPack()`
-- `summarizeAdapterCertificationContractPack()`
-
-If you are working on trust portability boundaries, inspect the boundary pack:
-
-- `buildTrustPortabilityBoundaryContractPack()`
-- `summarizeTrustPortabilityBoundaryContractPack()`
-
-If you are working on signed audit and provenance, inspect the audit/provenance pack:
-
-- `buildSignedAuditProvenanceContractPack()`
-- `summarizeSignedAuditProvenanceContractPack()`
-
-## Start Here
-
-If you are new to the public stack, use this order:
-
-1. read [START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/START_HERE.md)
-2. run `node examples/quickstart.js`
-3. run `npm run verify:all`
-4. use [FINAL_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/FINAL_CONTRACT.md) and [SERVICE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/SERVICE_CONTRACT.md) as the durable public contract
-
-If you are reading the GitHub repo and want deeper product context beyond the npm starter path, continue with:
-
-- [WHY_XYTARA_XOONYA.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/WHY_XYTARA_XOONYA.md)
-- [PARTNER_READY_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/PARTNER_READY_PATH.md)
-
-If you want one concrete cross-repo adoption story, start with:
-
-- [CARRIED_HANDOFF_DEMO.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/CARRIED_HANDOFF_DEMO.md)
-
-If you want the shortest neutral external-adoption bundle, continue with:
-
-- [PARTNER_READY_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/PARTNER_READY_PATH.md)
-- [PUBLIC_DEMO_SCRIPT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/PUBLIC_DEMO_SCRIPT.md)
-- [EXAMPLE_PATHS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/EXAMPLE_PATHS.md)
-- `node examples/partner_launch_walkthrough.js`
-
-If you are building adapters, continue with:
-
-- [ADAPTER_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/ADAPTER_START_HERE.md)
-- [ADAPTER_PROMOTION_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/ADAPTER_PROMOTION_START_HERE.md)
-- [ADAPTER_PARTNER_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/ADAPTER_PARTNER_PATH.md)
-- [SOFT_LAUNCH_KIT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/SOFT_LAUNCH_KIT.md)
-- [OUTREACH_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/OUTREACH_START_HERE.md)
-- [OUTREACH_MESSAGES.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/OUTREACH_MESSAGES.md)
-- [adapters/AUTHORING_GUIDE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/AUTHORING_GUIDE.md)
-- [adapters/ONBOARDING_POSTURE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/ONBOARDING_POSTURE.md)
-- [adapters/THIRD_PARTY_SUBMISSION_PROCESS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/THIRD_PARTY_SUBMISSION_PROCESS.md)
-
-The fastest copy-and-adapt third-party starter now lives under:
-
-- `adapters/examples/minimal-third-party-execution-adapter.manifest.json`
-- `adapters/examples/minimal-third-party-execution-adapter.js`
-- `adapters/examples/minimal-third-party-execution-registration.record.json`
-- `adapters/examples/minimal-third-party-execution.certification-pack.json`
-- `adapters/examples/minimal-third-party-execution.submission-bundle.json`
-- `adapters/examples/langgraph-reference-execution-adapter.manifest.json`
-- `adapters/examples/langgraph-reference-execution-adapter.js`
-- `adapters/examples/langchain-reference-execution-adapter.manifest.json`
-- `adapters/examples/langchain-reference-execution-adapter.js`
-
-If you are wiring treasury, settlement, or payment activation, continue with:
-
-- [REAL_PAYMENT_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/REAL_PAYMENT_SETUP.md)
-- [BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md)
-
-Production treasury and multi-rail payment activation are now centralized in `REAL_PAYMENT_SETUP.md` plus your private treasury source of truth outside the repos.
-
-If you want one private operator page that rolls up release posture, treasury landing, runtime activity, delivery, settlement readiness, and linked proof-facing health, use:
-
-- `GET /v1/business-cockpit`
-- `GET /v1/business-cockpit/summary`
-- `GET /business-cockpit`
-
-Those surfaces are private and are intended to be opened with the same operator bearer token used for other protected runtime views.
-
-If you are wiring external checkout or hosted funding paths, continue with:
-
-- [HUMAN_CHECKOUT_AND_RUNTIME_BRIDGE_PATTERN.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/HUMAN_CHECKOUT_AND_RUNTIME_BRIDGE_PATTERN.md)
-- [RUNTIME_BRIDGE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/RUNTIME_BRIDGE_CONTRACT.md)
-- [HOSTED_CHECKOUT_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/HOSTED_CHECKOUT_CONTRACT.md)
-- [CHECKOUT_TO_CREDITS_AND_DISPATCH_PLAN.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/CHECKOUT_TO_CREDITS_AND_DISPATCH_PLAN.md)
-
-If you want the broader already-core runtime continuity layers, continue with:
-
-- [OPERATOR_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/OPERATOR_START_HERE.md)
-- [GO_LIVE_OPERATOR_PACK.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/GO_LIVE_OPERATOR_PACK.md)
-- [PRODUCTION_MANUAL_CLOSEOUT_SEQUENCE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/PRODUCTION_MANUAL_CLOSEOUT_SEQUENCE.md)
-
-## Production Path
-
-The intended production-facing default path is now:
-
-1. discover a capability
-2. preview or quote the transaction path
-3. spend existing credits first when the caller prefers the reusable account path
-4. fall back to direct machine payment when credits are not available or not preferred
-5. execute through the default machine path
-6. inspect the transaction-side result and lifecycle state
-7. hand the result into `xoonya`
-8. review and run the proof-side completion path
-
-The machine-facing execution surface now also supports a first-class reusable balance posture:
-
-- set `payment_preference: "credits_first"` on `POST /v1/commands/execute` when the caller wants to spend existing account credits before requesting a fresh payment
-- default spend posture is `open_spend`: if the funded caller can pay, `xytara` should spend and execute without extra runtime ceremony
-- bounded spend posture is optional and only applies when the caller intentionally uses an `agent_id` and/or `budget_id`
-- inspect account credit state with `GET /v1/economics/accounts/:account_id/credit-balance`
-- inspect deterministic usage metering state with `GET /v1/economics/accounts/:account_id/metering-summary`, `GET /v1/economics/accounts/:account_id/usage-meters`, and `GET /v1/economics/accounts/:account_id/usage-meters/:usage_meter_id`
-- expect reconciliation and operator-export surfaces to carry the same metering trail for audit visibility
-- export a canonical cross-repo economic handoff bundle with `POST /v1/economics/handoff-bundles/economic-consequence`
-- expect `POST /v1/transaction-center/result-packages/export` and result-package continuation export/prepare surfaces to auto-carry that same canonical economic bundle whenever the execution path spent credits and produced a deterministic usage meter
-- inspect pack-backed entitlement pools with `GET /v1/economics/accounts/:account_id/entitlements` and `GET /v1/economics/accounts/:account_id/entitlements/summary`
-- inspect low-balance and replenishment posture with `GET /v1/economics/accounts/:account_id/entitlements/replenishment-summary`
-- inspect one pool's replenishment view with `GET /v1/economics/accounts/:account_id/entitlements/:entitlement_id/replenishment-view`
-- inspect effective account spend posture with `GET /v1/economics/accounts/:account_id/policy-pack`
-- inspect effective agent spend posture with `GET /v1/economics/accounts/:account_id/agents/:agent_id/policy-view`
-- preflight a proposed credit spend with `POST /v1/economics/rails/credits/preview-spend`
-- record explicit bounded credit consumption with `POST /v1/economics/rails/credits/consume`
-- issue externally verified top-up grants with `POST /v1/credit-bridge/grants`
-- inspect externally issued grants with `GET /v1/credit-bridge/grants` and `GET /v1/credit-bridge/grants/:grant_id`
-- discover reusable funding posture through `GET /v1/credit-packs`, `GET /v1/credit-packs/summary`, and `GET /v1/credit-pack?ref=<pack_id>`
-- external grant callers can now fund a named public pack such as `credits.agent`, and `xytara` will validate and record that pack identity directly
-
-The SDK now exposes the same posture directly for agent callers:
-
-- `client.getCreditPackSummary()`
-- `client.getCreditBalance(accountId)`
-- `client.previewUsageMetering({ account_id, task_ref?, workflow_ref?, units? })`
-- `client.getUsageMeteringSummary(accountId)`
-- `client.listUsageMeters(accountId)`
-- `client.getUsageMeter(usageMeterId, accountId?)`
-- `client.exportEconomicConsequenceHandoffBundle({ account_id, usage_meter_id, credit_spend_id, meter_profile_ref? })`
-- `client.listEntitlements(accountId)`
-- `client.getEntitlementSummary(accountId)`
-- `client.getEntitlement(entitlementId, accountId?)`
-- `client.getEntitlementReplenishmentSummary(accountId)`
-- `client.getEntitlementReplenishmentView(entitlementId, accountId?)`
-- `client.updateEntitlementReplenishmentPreference(entitlementId, payload, accountId?)`
-- `client.previewCreditSpend({ account_id, task_ref, units, agent_id?, budget_id? })`
-- `client.getCreditSpendPolicyPack(accountId)`
-- `client.getAgentCreditSpendPolicyView(agentId, accountId?)`
-- `client.executeWithCreditsFirst(payload, options?)`
-
-The runtime now also supports a bounded delegated spend path for repeat-use automation:
-
-- issue a spend credential through `POST /v1/account-auth/spend-credentials`
-- use that credential as `authorization: Bearer <spend_credential>`
-- optionally bind the credential to a `pack_id` or `entitlement_id` when spend should stay inside one value pool
-- execute through the same `credits_first` path without sharing broad operator secrets
-- revoke it through `POST /v1/account-auth/spend-credentials/:credential_id/revoke`
-
-SDK helpers now include:
-
-- `client.createSpendCredential(payload, { bearerToken })`
-- `client.listSpendCredentials(filters?, { bearerToken? })`
-- `client.getSpendCredential(credentialId, { bearerToken? })`
-- `client.revokeSpendCredential(credentialId, payload, { bearerToken })`
-- `client.executeWithSpendCredential(payload, { spendToken })`
-
-This keeps one-off usage and repeat usage on the same public spine:
-
-- direct pay when the caller is using the stack once
-- credit balance when the caller is already funded and wants low-friction repeat execution
-- optional agent and budget controls can still bound that spend without changing the execution surface
-
-It also keeps the external funding boundary clean:
-
-- an external merchant-facing system can verify a purchase and issue a bounded credit grant into `xytara`
-- `xytara` records the granted value and consumes it during later runtime operations
-- the runtime does not need to absorb provider-specific checkout semantics to support repeat usage
-- in production, `POST /v1/credit-bridge/grants` should normally be protected with `XYTARA_CREDIT_BRIDGE_BEARER_TOKEN`
-
-The first external checkout convenience path now follows a parallel narrow route:
-
-1. create hosted purchase intent
-2. create checkout session
-3. normalize payment success
-4. issue credits or entitlement
-5. dispatch through the runtime path when needed
-6. converge back into the same `xytara` and `xoonya` spine
-
-The first direct hosted execution path now also has a public runtime dispatch surface:
-
-- `POST /v1/runtime-bridge/dispatch`
-- `GET /v1/runtime-bridge/dispatches`
-- `GET /v1/runtime-bridge/dispatches/:request_id`
-
-The hosted payment side is intentionally asymmetric:
-
-- pay-in should be simple and fast
-- execution and delivery should follow immediately after valid payment
-- refund or reversal requests should enter review first
-- no autonomous payout path should exist outside explicit operator review and completion
-
-The operator shell now also carries hosted checkout visibility so purchase, dispatch, and refund-review load can be monitored from the same public control surface.
-
-The rest of this README explains the full surface area and milestone trail, but the public starting posture should now be understandable from that one default path.
-
-For release-grade adoption posture, inspect:
-
-- `GET /v1/release-pack`
-- `GET /v1/release-pack/summary`
-- `GET /v1/release-pack/comparison`
-- `GET /v1/release-pack/comparison/summary`
-- `GET /v1/release-pack/adoption`
-- `GET /v1/release-pack/adoption/summary`
-- `GET /v1/release-pack/scenarios`
-- `GET /v1/release-pack/scenarios/summary`
-- `GET /v1/release-pack/launch`
-- `GET /v1/release-pack/launch/summary`
-- `GET /v1/release-manifest`
-- `GET /v1/release-manifest/summary`
-- `GET /v1/release-notes`
-- `GET /v1/release-notes/summary`
-- `GET /v1/release-center`
-- `GET /v1/release-center/summary`
-- `GET /v1/release-history`
-- `GET /v1/release-history/summary`
-- `GET /v1/adapter-pack`
-- `GET /v1/adapter-pack/summary`
-- `GET /v1/adapter-promotion`
-- `GET /v1/adapter-promotion/summary`
-- `GET /v1/adapter-partners`
-- `GET /v1/adapter-partners/summary`
-- `GET /v1/soft-launch`
-- `GET /v1/soft-launch/summary`
-- `GET /v1/outreach-copy`
-- `GET /v1/outreach-copy/summary`
-- `GET /v1/outreach-targets`
-- `GET /v1/outreach-targets/summary`
-- `GET /v1/outreach-messages`
-- `GET /v1/outreach-messages/summary`
-- `GET /v1/phases`
-- `GET /v1/phases/summary`
-- `GET /v1/phases/phase-1`
-- `GET /v1/phases/phase-1/summary`
-- `GET /v1/publish-plan`
-- `GET /v1/publish-plan/summary`
-- `GET /v1/ecosystem-entry`
-- `GET /v1/ecosystem-entry/summary`
-- `GET /v1/launch-narrative`
-- `GET /v1/launch-narrative/summary`
-- `GET /v1/outreach-proof`
-- `GET /v1/outreach-proof/summary`
-- `GET /v1/announcement-pack`
-- `GET /v1/announcement-pack/summary`
-- `GET /v1/release-candidate`
-- `GET /v1/release-candidate/summary`
-- `xytara-release --summary`
-- `xytara-release --comparison --summary`
-- `xytara-release --adoption --summary`
-- `xytara-release --scenarios --summary`
-- `xytara-release --launch --summary`
-- `xytara-release --manifest --summary`
-- `xytara-release --notes --summary`
-- `xytara-release --center --summary`
-- `xytara-release --history --summary`
-- `xytara-release --adapters --summary`
-- `xytara-release --adapter-promotion --summary`
-- `xytara-release --adapter-partners --summary`
-- `xytara-release --soft-launch --summary`
-- `xytara-release --outreach-copy --summary`
-- `xytara-release --outreach-targets --summary`
-- `xytara-release --outreach-messages --summary`
-- `xytara-release --phases --summary`
-- `xytara-release --phase-1 --summary`
-- `xytara-release --ecosystem --summary`
-- `xytara-release --narrative --summary`
-- `xytara-release --outreach-proof --summary`
-- `xytara-release --announcement --summary`
-- `xytara-release --candidate --summary`
-
-These surfaces package the current machine-commerce value story, first-contact CLI path, default transaction posture, catalog/task-pack coverage, credit-pack posture, and integration/settlement breadth into one machine-readable launch boundary.
-
-## Commerce Loop
-
-The public product loop is:
-
-1. discover
-2. quote
-3. pay
-4. execute
-5. deliver
-6. inspect
-7. prove
-
-The package and service surfaces both follow that model.
-
-The current built-in catalog now covers a broader first-party `1.4.0` kernel than the original narrow seed, including:
-
-- trust and receipt validation/handoff tasks
-- runtime consequence tasks
-- jobs, credits, and policy tasks
-- first-party `a2a` negotiation and commit tasks
-- first-party `a2c` session and task-pack preview tasks
-- identity attestation and registry-link tasks
-- registry and anchoring tasks
-- discovery, admission, and settlement tasks
-- an initial built-in `mcp` adapter task
-
-The current restoration phase also starts carrying grouped public workflows for:
-
-- `a2a` settlement negotiation
-- `a2c` tooling/session flow
-- identity registry plus anchoring flow
-- registry pack bundling plus anchoring flow
-
-The current built-in settlement posture also now reflects the canonical first-party center of gravity across:
-
-- `ethereum_evm`
-- `bsv_teranode`
-- `solana`
-- `proton_xpr`
-- `antelope_eosio`
-
-The economic artifact posture is also now more explicit across the default machine loop:
-
-- quotes carry normalized `payment`, `settlement`, and `treasury` state
-- executed transactions and receipts carry the same normalized economic objects
-- payment-ledger entries preserve linked payment / settlement / treasury outcomes
-- the default first-party economic path is easier to inspect without provider-shaped logic
-
-The same artifacts now also expose a normalized `default_path` object so the bundled economic center of gravity is visible as data instead of being inferred indirectly.
-
-The package and service also expose a default transaction center surface so the out-of-the-box path is easier to inspect directly:
-
-- default protocol lane: `mcp`
-- default payment protocol: `x402`
-- default settlement center: built-in chain settlement with `bsv_teranode` as the native default across the canonical bundled settlement modes
-- default treasury landing posture: account treasury destination by settlement mode
-
-That same default center is also reflected in direct helper paths for default MCP usage, so the default path can be previewed or quoted without repeating the full integration-selection story each time.
-
-The `1.6.0` convergence line starts broadening that same default path into grouped first-party entry packs:
-
-- `default.mcp.tool.invoke`
-- `default.a2c.tooling.run`
-- `default.identity.anchor.run`
-
-These default packs are intended to make the public machine loop easier to consume as grouped first-party paths instead of only as low-level primitives.
-
-The package and service now also expose:
-
-- default transaction economics visibility
-- default transaction task-pack catalog, summary, and detail routes
-- direct SDK helpers for default task-pack preview, quote, and invoke
-
-The next `1.6.0` carry also adds guided default loops on top of those packs:
-
-- default loop catalog and detail routes
-- direct loop-run service surface
-- SDK helpers that return bundled result-set, linked-record, activity, and economics summaries together
-
-That means the first-party path is easier to both run and inspect without manually stitching together monitor, receipt, delivery, and payment-ledger helpers after execution.
-
-The current `1.7.0` line starts widening that surface into real grouped transaction classes:
-
-- transaction-class pack catalog, summary, and detail routes
-- grouped transaction-class run routes for first-party commerce classes
-- proof-handoff summaries that make the next step into `xoonya` more obvious from transaction outputs
-
-This is the first step beyond “clear default loop” toward “broader useful machine-commerce classes plus clearer commerce-to-proof follow-through.”
-
-The current `1.8.0` line starts filling a thinner part of the interaction spine before committed execution:
-
-- grouped pre-commit pack catalog, summary, and detail routes
-- grouped pre-commit run routes for negotiation, admission, and commit-readiness posture
-- readiness summaries that make the next committed transaction surface more explicit
-
-This is intended to make the protocol-entry to committed-transaction transition feel more like one composable machine spine instead of a set of disconnected route families.
-
-The same `1.8.0` line also starts exposing grouped interaction spine paths that compose:
-
-- pre-commit readiness
-- committed execution
-- proof-aware handoff posture
-
-as one clearer cross-layer machine path instead of making callers stitch the layers together manually.
-
-The current `1.9.0` line starts hardening the output side of that spine into cleaner extension seams:
-
-- interaction result-package catalog, summary, and detail routes
-- direct result-package run surfaces derived from grouped spine paths
-- seam summaries that classify execution/consequence, payment/settlement/treasury, and proof-handoff carry together
-- result-package export surfaces that produce a portable handoff bundle for proof-side follow-through
-
-This is intended to make grouped spine outputs easier to treat as stable artifacts and future adapter-ready boundaries instead of one-off route responses.
-
-The current `1.10.0` line starts building on that by exposing reusable continuation templates on top of result packages:
-
-- result-package continuation catalog, summary, and detail routes
-- direct continuation run surfaces that preserve the default next proof path
-- continuation preparation surfaces that emit proof-ready request templates
-- continuation preparation summary surfaces that expose the stable prepared-artifact view directly
-- continuation summaries that make the default transaction-to-proof bridge explicit instead of inferred
-- prepared continuation artifacts that classify the preserved execution, economic, and proof-facing context that survives into proof-native follow-through
-- extension-seam summaries that distinguish stable carry from future adapter-ready boundary points on that durable path
-- reusable-default summaries that expose the stable prepared artifact as a clearer default follow-through pattern
-- reusable-default template surfaces that package that same default path into a direct proof-side review request
-- extension-template surfaces that turn the durable transaction-side artifact into a reusable proof-side extension-review request
-
-This is intended to make the public stack easier to compose after grouped execution, not just easier to inspect.
-
-The current `1.14.0` line starts hardening that reusable path into a clearer public composition contract:
-
-- prepared-artifact composition-contract summaries
-- composition-contract template surfaces for proof-side contract review
-- compact composition-contract bundles for direct transaction-side contract reuse
-- clearer public contract ids across the reusable-default continuation path
-
-This is intended to make the transaction-side continuation path easier to treat as a stable public contract instead of only a strong reusable default.
-
-The current `1.15.0` line starts turning that same contract path into a clearer adapter-ready public bridge:
-
-- prepared-artifact bridge summaries on top of the composition-contract continuation path
-- bridge template surfaces that package the next proof-side review request directly
-- compact bridge bundles for direct transaction-side bridge reuse
-- compact bridge-carry surfaces for direct transaction-side bridge reuse
-
-This is intended to make the transaction-side continuation path easier to hand across a stable adapter-ready bridge instead of treating bridge preparation as an implicit follow-on concern.
-
-The current `1.16.0` line starts turning that bridge into a clearer stable public handoff contract:
-
-- prepared-artifact handoff summaries on top of the bridge path
-- direct handoff template surfaces for proof-side handoff continuity review
-- compact handoff bundles for direct transaction-side handoff reuse
-- compact handoff-carry surfaces for direct transaction-side handoff reuse
-
-This is intended to make the transaction-side continuation path easier to treat as a stable handoff contract instead of only a well-described bridge.
-
-The current `1.17.0` line starts turning that stable handoff contract into a clearer adapter-consumable handoff surface:
-
-- adapter-consumable handoff-surface summaries on top of prepared handoff artifacts
-- direct handoff-surface template routes for proof-side intake review
-- compact handoff-surface bundles for direct adapter-facing reuse
-- clearer adapter-facing handoff-surface ids and stable consumable carry
-
-This is intended to make the transaction-side continuation path easier to consume directly as a stable adapter-facing handoff surface instead of only a well-described handoff contract.
-
-The current `1.18.0` line starts turning that adapter-consumable handoff surface into a clearer adapter-usable handoff package:
-
-- adapter-usable handoff-package summaries on top of prepared handoff artifacts
-- compact handoff-package bundles for direct adapter-facing use
-- default handoff-package summaries for the next proof-side follow-through
-- clearer adapter-facing handoff-package ids and stable usable carry
-
-This is intended to make the transaction-side continuation path easier to use directly as a stable public handoff package instead of only a surface that still needs extra glue logic.
-
-The current `1.19.0` line starts turning that adapter-usable handoff package into a clearer adapter-ready execution package:
-
-- execution-package summaries on top of the default handoff-package path
-- compact execution-package bundles for direct adapter-facing execution posture
-- default execution-package summaries for the next proof-side execution run posture
-- clearer execution-package ids and stable execution-ready carry
-
-This is intended to make the transaction-side continuation path easier to execute against directly as a stable public package instead of only a package that still needs execution glue.
-
-The current `1.20.0` line starts turning that adapter-ready execution package into a clearer adapter-operable execution contract:
-
-- execution-contract summaries on top of the default execution-package path
-- compact execution-contract bundles for direct adapter-facing operation posture
-- default execution-contract summaries for the next proof-side execution-contract run posture
-- clearer execution-contract ids and stable operable carry
-
-This is intended to make the transaction-side continuation path easier to operate against repeatedly as a stable public contract instead of only a package that is execution-ready by posture.
-
-The current `1.21.0` line starts turning that adapter-operable execution contract into a clearer adapter-stable operating contract:
-
-- operating-contract summaries on top of the default execution-contract path
-- compact operating-contract bundles for direct adapter-facing stable operation posture
-- default operating-contract summaries for the next proof-side operating-contract run posture
-- clearer operating-contract ids and stable recurring operating carry
-
-This is intended to make the transaction-side continuation path easier to depend on repeatedly as a durable public operating contract instead of only a contract that is operable in the moment.
-
-The current `1.22.0` line starts turning that adapter-stable operating contract into a clearer adapter-reliable operating interface:
-
-- operating-interface summaries on top of the default operating-contract path
-- compact operating-interface bundles for direct adapter-facing reliable interface posture
-- default operating-interface summaries for the next proof-side operating-interface run posture
-- clearer operating-interface ids and stable reliable interface carry
-
-This is intended to make the transaction-side continuation path easier to rely on operationally as a durable public interface instead of only a stable operating contract shape.
-
-The current `1.23.0` line starts turning that adapter-reliable operating interface into a clearer adapter-integrable operating path:
-
-- operating-integration summaries on top of the default operating-interface path
-- compact operating-integration bundles for direct adapter-facing integration posture
-- default operating-integration summaries for the next proof-side operating-integration run posture
-- clearer operating-integration ids and stable integrable carry
-
-This is intended to make the transaction-side continuation path easier to plug into adapters directly as a durable public operating path instead of only a reliable interface shape.
-
-The current `1.24.0` line starts turning that adapter-integrable operating path into a clearer adapter-ready default path:
-
-- operating-path summaries on top of the default operating-integration path
-- compact operating-path bundles for direct adapter-facing default-path posture
-- default operating-path summaries for the next proof-side operating-path run posture
-- clearer operating-path ids and stable default-path carry
-
-This is intended to make the transaction-side continuation path easier to use as the obvious first public adapter path instead of only a path that is integrable with a little extra coordination.
-
-The current `1.25.0` line starts turning that adapter-ready default path into a clearer adapter-complete default path:
-
-- complete-default-path summaries on top of the default operating-path path
-- compact complete-default-path bundles for direct adapter-facing complete-path posture
-- default complete-default-path summaries for the next proof-side complete-default-path run posture
-- clearer complete-default-path ids and stable complete-path carry
-
-This is intended to make the transaction-side continuation path easier to adopt as the complete public default path an outside builder can use without needing private interpretation.
-
-The current `1.26.0` line finalizes that public shape into a cleaner production-ready package:
-
-- a publishable [START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/START_HERE.md) onboarding path
-- clearer top-level README entry points for the default production flow
-- publishable contract and terminology docs carried in the package tarball
-- naming cleanup that keeps the public story anchored to `xytara` and `xoonya`
-
-This is intended to make the public transaction-side package feel like a finished production-facing product instead of a strong stack that still assumes milestone-history context.
-
-## Package Surface
-
-The SDK is broad, but it stays organized into a few repeatable families instead of one-off surfaces.
-
-The main families are:
-
-- discovery and catalog
-- schemas, templates, and validation
-- quotes, previews, execution, and wait flows
-- records, operations, and operator summaries
-- inspection, reconciliation, and export helpers
-
-The intended usage style is simple:
-
-- use raw getters when you need exact records
-- use summary/list helpers when you need compact high-signal state
-
-## Adapter Model
-
-Adapter support is now a first-class public surface.
-
-Core contract files:
-
-- [adapter-manifest.schema.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/adapter-manifest.schema.json)
-- [integration-registration-record.schema.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/integration-registration-record.schema.json)
-- [integration-certification-pack.schema.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/integration-certification-pack.schema.json)
-- [integration-submission-bundle.schema.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/integration-submission-bundle.schema.json)
-- [integration-submission-bundle-set.schema.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/integration-submission-bundle-set.schema.json)
-- [interfaces.js](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/interfaces.js)
-
-Builder-facing docs:
-
-- [AUTHORING_GUIDE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/AUTHORING_GUIDE.md)
-- [THIRD_PARTY_SUBMISSION_PROCESS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/THIRD_PARTY_SUBMISSION_PROCESS.md)
-- [ONBOARDING_POSTURE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/ONBOARDING_POSTURE.md)
-
-Reference examples:
-
-- built-in class examples:
-  [example-execution-adapter.manifest.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/examples/example-execution-adapter.manifest.json),
-  [example-execution-adapter.js](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/examples/example-execution-adapter.js),
-  [example-settlement-adapter.manifest.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/examples/example-settlement-adapter.manifest.json),
-  [example-settlement-adapter.js](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/examples/example-settlement-adapter.js)
-- staged third-party artifact examples:
-  protocol, identity, and settlement registration/certification/submission-bundle examples live under [adapters/examples](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/adapters/examples)
-
-Current adapter tooling exposes:
-
-- `ADAPTER_INTERFACE_VERSION`
-- `validateAdapterImplementation(...)`
-
-Initial certification starts with:
-
-```bash
-npm run verify:adapters
-```
-
-The LangGraph and LangChain reference adapters are local contract adapters. They normalize framework-style graph, chain, checkpoint, trace, and context payloads and emit proof-compatible execution facts. They do not claim live external framework-provider execution.
-
-The current seed freezes the starter contract for:
-
-- adapter identity
-- adapter class
-- registration posture
-- certification posture
-- compatibility
-- health contract
-- idempotency contract
-- failure contract
-- proof contract
-
-The current onboarding path is now documented for third parties:
-
-1. choose adapter class
-2. build manifest against the schema
-3. implement the interface contract
-4. certify locally with `npm run verify:adapters`
-5. declare registration and certification posture
-6. promote through explicit runtime registration
-
-Third-party integrations scale through one stable pattern:
-
-- manifest declares registration posture
-- manifest declares certification posture
-- certification runs locally first
-- promotion produces a normalized registration record
-- runtime registration remains an explicit product action
-- discovery can later surface maturity and trust without changing runtime contracts
-
-Discovery can represent non-bundled staged examples in the same normalized view:
-
-- built-in integrations can appear as `unregistered` but production-default
-- staged third-party integrations can appear as `staging_registered`
-- registration state stays separate from proof and commerce semantics
-
-The registry model now also has an explicit ingestion path:
-
-- adapter manifest defines the adapter contract
-- registration record defines promotion state
-- certification pack defines submitted verification evidence
-- submission bundle groups the reusable submission artifact
-- registry ingestion helper normalizes the runnable integration view
-
-The package surface also supports registry snapshot/export helpers, so multiple imported integrations can be packaged together without inventing a one-off format every time.
-
-Submission bundles can be exported back into a bundle set and then turned into a normalized registry snapshot.
-
-The same artifact model also produces thin review summaries:
-
-- submission bundles can be summarized for reviewer/operator inspection
-- submission bundle sets can be summarized as one staged review package
-- registry snapshots can be summarized as a review-ready state report
-
-That keeps inspection aligned with the real integration artifacts instead of inventing a parallel control-plane format.
-
-The intended posture is:
-
-- built-in certified integrations can be production-default
-- staged third-party integrations can be discoverable and reviewable
-- staged third-party integrations should normally require explicit selection
-- discoverable does not mean default
-
-The promotion-readiness layer now makes that posture explicit as review data:
-
-- review-ready means an integration is staged and inspectable
-- default-eligible means it is allowed to participate in default selection
-- production-default-ready means its certification, maturity, bundled posture, and selection posture all line up
-- blockers are returned as data instead of being left implicit
-
-That distinction matters as the registry grows.
-
-The promotion-action preview layer now builds on top of that readiness data without introducing mutation:
-
-- action previews stay read-only
-- current posture and resulting posture are both visible
-- requested action validity is explicit
-- blockers and blocker categories remain inspectable as data
-- the preview layer explains what would change before any future control-plane work exists
-
-There is also a small repo-local registry CLI for reviewer/operator use when working from a cloned `xytara` repository:
-
-- `node scripts/registry_cli.js validate-bundle --example protocol`
-- `node scripts/registry_cli.js validate-bundle --example identity`
-- `node scripts/registry_cli.js validate-bundle --example settlement`
-- `node scripts/registry_cli.js export-bundle-set`
-- `node scripts/registry_cli.js export-snapshot`
-- `node scripts/registry_cli.js review-bundle --example protocol`
-- `node scripts/registry_cli.js review-bundle --example identity`
-- `node scripts/registry_cli.js review-bundle-set`
-- `node scripts/registry_cli.js review-snapshot`
-- `node scripts/registry_cli.js promotion-readiness --integration partner.protocol.acme_mcp`
-- `node scripts/registry_cli.js promotion-action-preview --integration partner.protocol.acme_mcp --action complete_certification`
-- `node scripts/registry_cli.js promotion-action-set --integration partner.protocol.acme_mcp`
-- `node scripts/registry_cli.js promotion-action-set-summary --source third_party_example --bundled false`
-
-## Integration Selection
-
-`xytara` now treats integration selection as an explicit part of the commerce contract.
-
-Callers can provide:
-
-- `integration_id`
-- `integration_ids`
-- `integration_context`
-- `protocol`
-- `payment_protocol`
-- settlement preferences
-
-Selection precedence is:
-
-1. validate explicitly requested integrations
-2. resolve protocol and payment protocol hints
-3. resolve task-backed execution and identity integrations
-4. resolve settlement integration from the requested settlement mode
-5. reject the request if an explicit integration is unknown or incompatible
-
-This keeps the model stable as more integrations are added:
-
-- explicit overrides must be valid
-- defaults remain predictable
-- defaults only come from integrations that explicitly opt into default selection
-- explicit requests only constrain the relevant adapter class
-- protocol and settlement translation never redefine commerce semantics
-
-## Quickstart
-
-Run:
-
-```bash
-node examples/quickstart.js
-```
-
-For a direct one-line machine run against a live service, use the bundled CLI:
-
-```bash
-xytara first-run --run-quote --account ACCOUNT_REF --pretty
-```
-
-The quickstart exercises:
-
-- health and catalog
-- discovery summaries and filters
-- restored `a2a`, `a2c`, and identity catalog families
-- staged-vs-default integration posture
-- submission bundle-set export
-- pricing, schema, and template access
-- validation
-- quote and execution flows
-- dedicated `mcp` invocation flow
-- named `a2a` negotiation and commit lanes
-- named `a2c` session and pack-preview lanes
-- named identity attestation preview and registry-link lanes
-- named registry-pack bundle and anchoring-pack preview lanes
-- grouped `a2a`, `a2c`, identity-anchor, and registry-pack-anchor convenience flows
-- named runtime, admission, registry, and anchoring task lanes
-- named trust and receipt-handoff lanes
-- lifecycle and operator helpers
-- service-backed client usage
-
-## Service Surface
-
-Run:
-
-```bash
-npm start
-```
-
-Then in another shell:
-
-```bash
-curl http://127.0.0.1:4320/v1/catalog/summary
-curl http://127.0.0.1:4320/v1/operations/dashboard
-curl http://127.0.0.1:4320/v1/operations/attention-records
-curl -X POST http://127.0.0.1:4320/v1/trust/handoffs/emit ^
-  -H "content-type: application/json" ^
-  -H "authorization: Bearer demo-api-key" ^
-  -d "{\"subject_id\":\"subject-1\",\"execution_ref\":\"exec-1\"}"
-curl -X POST http://127.0.0.1:4320/v1/admission/preview ^
-  -H "content-type: application/json" ^
-  -H "authorization: Bearer demo-api-key" ^
-  -d "{\"source_zone_id\":\"zone-a\",\"target_zone_id\":\"zone-b\"}"
-curl -X POST http://127.0.0.1:4320/v1/a2a/negotiate ^
-  -H "content-type: application/json" ^
-  -H "authorization: Bearer demo-api-key" ^
-  -d "{\"counterparty_agent_id\":\"agent-counterparty-1\",\"task_pack_ref\":\"pack.a2a.demo\",\"negotiation_mode\":\"quote_then_commit\"}"
-curl -X POST http://127.0.0.1:4320/v1/a2c/packs/preview ^
-  -H "content-type: application/json" ^
-  -H "authorization: Bearer demo-api-key" ^
-  -d "{\"agent_id\":\"agent-demo\",\"pack_ref\":\"pack.tools.research\"}"
-curl -X POST http://127.0.0.1:4320/v1/identity/attest/preview ^
-  -H "content-type: application/json" ^
-  -H "authorization: Bearer demo-api-key" ^
-  -d "{\"subject_id\":\"subject-identity-1\",\"registry_scope\":\"registry.identity.default\"}"
-curl -X POST http://127.0.0.1:4320/v1/registry/packs/bundle ^
-  -H "content-type: application/json" ^
-  -H "authorization: Bearer demo-api-key" ^
-  -d "{\"pack_ref\":\"pack.registry.identity\",\"subject_ids\":[\"subject-identity-1\",\"subject-identity-2\"]}"
-curl -X POST http://127.0.0.1:4320/v1/a2a/flows/settlement ^
-  -H "content-type: application/json" ^
-  -H "authorization: Bearer demo-api-key" ^
-  -d "{\"counterparty_agent_id\":\"agent-counterparty-1\",\"task_pack_ref\":\"pack.a2a.demo\",\"negotiation_mode\":\"quote_then_commit\",\"negotiation_id\":\"negotiation-flow-1\",\"intent_id\":\"intent-a2a-flow-1\"}"
-curl -X POST http://127.0.0.1:4320/v1/identity/flows/anchor ^
-  -H "content-type: application/json" ^
-  -H "authorization: Bearer demo-api-key" ^
-  -d "{\"subject_id\":\"subject-identity-1\",\"registry_scope\":\"registry.identity.default\",\"record_type\":\"identity_attestation\",\"registry_record_id\":\"registry-record-identity-1\",\"commitment_hash\":\"commitment-identity-1\"}"
-curl -X POST http://127.0.0.1:4320/v1/mcp/tools/invoke ^
-  -H "content-type: application/json" ^
-  -H "authorization: Bearer demo-api-key" ^
-  -d "{\"tool_name\":\"zones.lookup\",\"arguments\":{\"zone_id\":\"zone-1\"}}"
-curl -X POST http://127.0.0.1:4320/v1/payment-quotes ^
-  -H "content-type: application/json" ^
-  -d "{\"command\":\"quickstart\",\"task_ref\":\"trust.verify\",\"body\":{\"subject_id\":\"subject-1\"}}"
-```
-
-Environment example:
-
-- [`.env.example`](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/.env.example)
-
-Production payment note:
-
-- `XYTARA_PAYMENT_VERIFICATION_MODE` defaults to `local_signed` (verifiable signed payment acceptance); `presence` must be opted into explicitly and only accepts plain header presence for local development
-- operator write surfaces (`/v1/economics/*` ledger mutations, `/v1/agent-accounts`, `/v1/operator-shell/admin-pack`, `/v1/credit-bridge/grants`, business cockpit) fail closed with `operator_auth_not_configured` until `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` and `XYTARA_CREDIT_BRIDGE_BEARER_TOKEN` are set; send `Authorization: Bearer <token>`; query-string tokens are not accepted
-- provide buyer wallet verification material through `XYTARA_WALLET_REGISTRY_JSON` or `XYTARA_WALLET_REGISTRY_PATH`
-- set `XYTARA_TREASURY_DESTINATION_ID` and related treasury env vars so accepted payments land in your merchant treasury posture instead of the default local account placeholder
-- built-in `x402` is the admission lane; real external payout/custody still depends on the payment rail and treasury destination you configure behind that lane
-- for native BSV/Teranode live follow-through, set `XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE` to `observe` or `arc`
-- use `XYTARA_BSV_ARC_RPC_URL` plus optional ARC RPC auth envs when the live runtime needs ARC submission; legacy `XYTARA_BSV_TERANODE_RPC_*` aliases remain accepted
-- use `XYTARA_BSV_TERANODE_OBSERVER_URL` if you want to override the default live observer base
-
-Primary service routes:
-
-- `GET /health`
-- `GET /v1/catalog`
-- `GET /v1/catalog/summary`
-- `GET /v1/catalog/task?ref=<task_ref_or_alias>`
-- `GET /v1/catalog/workflows`
-- `GET /v1/catalog/workflow?ref=<workflow_ref_or_alias>`
-- `GET /v1/integrations`
-- `GET /v1/integrations/summary`
-- `GET /v1/integrations/classes`
-- `GET /v1/integrations/protocols`
-- `GET /v1/integrations/settlement-modes`
-- `GET /v1/integrations/promotion-readiness`
-- `GET /v1/integrations/:integration_id/promotion-readiness`
-- `GET /v1/integrations/promotion-actions`
-- `GET /v1/integrations/:integration_id/promotion-actions`
-- `POST /v1/integrations/promotion-actions/preview`
-- `POST /v1/integrations/review/submission-bundle`
-- `POST /v1/integrations/review/submission-bundle-set`
-- `POST /v1/integrations/review/registry-snapshot`
-- `POST /v1/payment-quotes`
-- `POST /v1/trust/handoffs/emit`
-- `POST /v1/trust/handoffs/validate`
-- `POST /v1/execution-receipts/handoffs/emit`
-- `POST /v1/execution-receipts/handoffs/validate`
-- `POST /v1/receipt-ledger/handoffs/emit`
-- `POST /v1/receipt-ledger/handoffs/validate`
-- `POST /v1/admission/preview`
-- `POST /v1/a2a/negotiate`
-- `POST /v1/a2a/commit`
-- `POST /v1/a2a/flows/settlement`
-- `POST /v1/a2c/sessions/open`
-- `POST /v1/a2c/packs/preview`
-- `POST /v1/a2c/flows/tooling`
-- `POST /v1/identity/attest/preview`
-- `POST /v1/identity/registry/link`
-- `POST /v1/identity/flows/anchor`
-- `POST /v1/runtime/emit`
-- `POST /v1/runtime/anchor`
-- `POST /v1/runtime/emit-anchor`
-- `POST /v1/registry/register`
-- `POST /v1/registry/packs/bundle`
-- `POST /v1/registry/packs/anchor`
-- `POST /v1/anchoring/submit`
-- `POST /v1/anchoring/packs/preview`
-- `GET /v1/coordination-center`
-- `GET /v1/coordination-center/summary`
-- `GET /v1/zones`
-- `GET /v1/zones/compatibility-profiles`
-- `GET /v1/zones/:zoneId/constitution`
-- `POST /v1/coordination-center/interpretation-handoff/validate`
-- `POST /v1/coordination-center/handshake-preview`
-- `POST /v1/coordination-center/cross-zone-preview`
-- `POST /v1/coordination-center/admission-case-projection`
-- `POST /v1/coordination-center/admission-case-bundle`
-- `POST /v1/coordination-center/operator-view`
-- `POST /v1/coordination-center/admin-view`
-- `POST /v1/coordination-center/admission-ops-pack`
-- `POST /v1/coordination-center/admission-workflow-pack`
-- `POST /v1/coordination-center/coordination-pack`
-- `POST /v1/coordination-center/review-link`
-- `GET /v1/coordination-center/zones-dashboard`
-- `POST /v1/coordination-center/zones-dashboard-pack`
-- `POST /v1/mcp/tools/invoke`
-- `GET /v1/payment-quotes`
-- `GET /v1/payment-quotes/:quote_id`
-- `POST /v1/commands/execute`
-- `POST /x402/commands/execute`
-- `POST /x402/mcp/tools/invoke`
-- `GET /v1/governed-transactions`
-- `GET /v1/governed-transactions/:transaction_id`
-- `GET /v1/receipts`
-- `GET /v1/receipts/:receipt_id`
-- `GET /v1/payment-ledger`
-- `GET /v1/payment-ledger/:payment_id`
-- `GET /v1/payment-ledger/:payment_id/operator-pack`
-- `GET /v1/deliveries`
-- `GET /v1/deliveries/:delivery_id`
-- `GET /v1/disputes`
-- `POST /v1/disputes`
-- `GET /v1/disputes/:dispute_id`
-- `POST /v1/disputes/:dispute_id/actions`
-- `GET /v1/refunds`
-- `POST /v1/refunds`
-- `GET /v1/refunds/:refund_id`
-- `POST /v1/refunds/:refund_id/actions`
-- `POST /v1/remediation-tickets`
-- `GET /v1/remediation-tickets`
-- `GET /v1/remediation-tickets/:ticket_id`
-- `POST /v1/remediation-tickets/:ticket_id/actions`
-- `GET /v1/reconciliation-report`
-- `GET /v1/operator-export-pack`
-- `GET /v1/operations/dashboard`
-- `GET /v1/operations/attention-records`
-- `GET /v1/runtime/durability`
-- `GET /v1/operator-shell`
-- `GET /v1/operator-shell/summary`
-- `POST /v1/operator-shell/summary`
-- `POST /v1/operator-shell/workflow-pack`
-- `POST /v1/operator-shell/admin-pack`
-- `GET /v1/agent-accounts`
-- `POST /v1/agent-accounts`
-- `GET /v1/agent-accounts/:account_id`
-- `POST /v1/economics/budgets`
-- `POST /v1/economics/budgets/:budget_id/status`
-- `POST /v1/economics/agents`
-- `POST /v1/economics/agents/:agent_id/status`
-- `POST /v1/economics/receipts`
-- `POST /v1/economics/receipts/:receipt_id/lifecycle`
-- `POST /v1/economics/receipts/:receipt_id/operator-action`
-- `POST /v1/economics/allocations/mint`
-- `POST /v1/economics/allocations/reverse`
-- `POST /v1/economics/rails/credits/preview`
-- `POST /v1/economics/rails/credits/apply`
-- `POST /v1/economics/receipt-ledger/validate`
-- `POST /v1/economics/interpretation-handoff`
-- `POST /v1/economics/markets/preview`
-- `POST /v1/economics/markets/workflow-pack`
-- `POST /v1/economics/markets/signoff-pack`
-- `POST /v1/economics/markets/coordination-pack`
-- `GET /v1/economics/accounts/:account_id/budgets`
-- `GET /v1/economics/accounts/:account_id/agents`
-- `GET /v1/economics/accounts/:account_id/receipts`
-- `GET /v1/economics/accounts/:account_id`
-- `GET /v1/economics/accounts/:account_id/operator-view`
-- `GET /v1/economics/accounts/:account_id/operator-dashboard`
-- `GET /v1/economics/accounts/:account_id/treasury-summary`
-- `GET /v1/economics/accounts/:account_id/ledger-export`
-- `GET /v1/economics/accounts/:account_id/treasury-drilldown`
-- `GET /v1/economics/accounts/:account_id/reconciliation-pack`
-- `GET /v1/economics/accounts/:account_id/treasury-workflow-pack`
-- `GET /v1/economics/accounts/:account_id/treasury-signoff-pack`
-- `GET /v1/economics/accounts/:account_id/policy-summary`
-- `GET /v1/economics/accounts/:account_id/rail-summary`
-- `GET /v1/economics/accounts/:account_id/rail-workflow-pack`
-- `GET /v1/economics/accounts/:account_id/rail-signoff-pack`
-- `POST /v1/economics/jobs/:job_id/operator-action`
-- `GET /v1/economics/evidence/receipts/:receipt_ref`
-- `GET /v1/economics/evidence/jobs/:job_id`
-- `GET /v1/economics/integration/jobs/:job_id`
-- `GET /v1/settlement/bsv-teranode/readiness`
-- `GET /v1/settlement/bsv-teranode/:settlement_id/operator-pack`
-
-The Wave C coordination carry-over line adds a bounded coordination center on top of the public transaction spine:
-
-- zone discovery, compatibility profiles, and constitution lookup
-- interpretation-handoff validation and cross-zone handshake preview
-- cross-zone admission-case projection and portable case-bundle export
-- coordination operator/admin views plus explicit review-linkage into governance and proof follow-through
-- admission ops/workflow packs, coordination packs, and zones dashboard packaging
-
-The Wave D adapter-breadth line broadens the bundled public integration surface as well:
-
-- additional built-in protocol surfaces for `a2a`, `acp`, `mqtt`, `grpc`, `kafka`, `nats`, and `ros2`
-- additional built-in execution-front surfaces for `langchain`, `langgraph`, `semantic_kernel`, `autogen`, `crewai`, and `llamaindex`
-- broader bundled payment and identity breadth through `mpp` and `erc8004`-oriented public integration surfaces
-
-The Wave F shell carry-over line adds a bounded operator shell inside public `xytara`:
-
-- self-serve agent account issuance for the public runtime path
-- a unified operator shell summary across operations, economics, and coordination
-- explicit runtime durability visibility for snapshot-backed recovery posture
-- explicit native BSV/Teranode readiness visibility for merchant identity, transport, and verification posture
-- compact workflow/admin shell exports that point cleanly into proof-side follow-through when needed
-
-This keeps the public product centered on `naxytra` while preserving the useful operator-shell capability directly inside `xytara` instead of splitting it into a separate surface.
-
-The durability and native-settlement readiness surfaces are also intended to make the remaining production boundary explicit:
-
-- `/v1/runtime/durability` exposes whether runtime snapshots are enabled, whether a recoverable snapshot exists yet, and any current durability blockers
-- `/v1/settlement/bsv-teranode/readiness` exposes whether merchant identity, transport, verification mode, and runtime mode are production-ready, plus the next manual inputs still required
-- `/v1/payment-ledger/:payment_id/operator-pack` and `/v1/settlement/bsv-teranode/:settlement_id/operator-pack` collapse payment, settlement, treasury, proof, and economic-consequence carry into one operator-facing pack so direct-pay and funded-runtime paths are easier to inspect without stitching raw records together
-
-If you use grants, entitlements, or usage metering in deployed `xytara`, `XYTARA_STATE_FILE` should point at persistent disk rather than ephemeral container storage. Otherwise those economics records will reset across restart.
-
-If your host does not provide persistent disk, use the Supabase-backed runtime state path documented in [SUPABASE_RUNTIME_STATE_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xytara/SUPABASE_RUNTIME_STATE_SETUP.md).
-
-## Verification
-
-Local verification commands:
-
-- `npm run verify:package`
-- `npm run verify:adapters`
-- `npm run verify:tooling`
-- `npm run verify:examples`
-- `npm run verify:service`
-- `npm run verify:all`
-
-The current verification covers:
-
-- package exports and helper breadth
-- adapter manifest and implementation conformance
-- registry bundle tooling behavior
-- quickstart behavior
-- service-route behavior
-- preserved operator/reporting surfaces
-
-## Control Files
-
-- `FINAL_CONTRACT.md`
-- `TERMINOLOGY.md`
-- `SERVICE_CONTRACT.md`
-
+# xytara
+
+[![smithery badge](https://smithery.ai/badge/naxytra/xytara-mcp-executor)](https://smithery.ai/servers/naxytra/xytara-mcp-executor)
+
+**x402 pay-per-call agent-commerce runtime** — the payment and execution layer of the naxytra
+machine stack. An agent discovers a capability, pays once with x402 (gasless USDC on Base), and gets
+a real deliverable, with settlement and revenue reconciled on-chain. The proof-side half is
+[xoonya](https://naxytra.com/xoonya).
+
+## Proven live on Base mainnet
+
+All demonstrated end to end on Base mainnet (provider-payout transactions are publicly verifiable —
+see **Proof** below):
+
+- **Open settling provider network** — a paid x402 call routes to an independently-registered
+  execution provider, returns a real deliverable, and splits revenue on-chain (reconciled ledger,
+  platform keeps the remainder).
+- **Automated on-chain provider payouts** — a key-less runtime dispatches to an external signer that
+  sends USDC on Base; reconciled, idempotent, double-pay-safe.
+- **Cryptographic bounded delegated spend** — a stolen bearer token cannot spend; each spend requires
+  a fresh ed25519 signature bound to the exact account, amount, and task.
+- **Pay-per-call MCP** — 17 deterministic tools at a public endpoint, no API keys, no account.
+
+## Pay-per-call MCP (the easy on-ramp)
+
+The public MCP executor is a genuine pay-per-call endpoint:
+
+```
+endpoint:   https://xytara-mcp-executor.onrender.com/mcp
+tools/list  -> free (17 deterministic tools)
+tools/call  -> 402 Payment Required with a price
+            -> sign ONE gasless USDC authorization (x402 / EIP-3009)
+            -> the Coinbase CDP facilitator verifies + settles it on Base
+            -> the tool runs; the response carries the result + an on-chain settlement receipt
+```
+
+Tools: `summarize`, `text.extract`, `html.to-text`, `text.chunk`, `json.validate`, `zones.lookup`,
+`keccak256`, `address.validate`, `abi.encode`, `abi.decode`, `merkle.verify`, `eip712.hash`,
+`x402.decode`, `x402.verify-receipt`, `tx.status`, `reply.draft`, `catalog`.
+
+## Install
+
+```bash
+npm install xytara
+```
+
+## Quickstart
+
+```bash
+xytara start-here        # the shortest first-run path
+xytara first-run         # guided discover -> quote -> pay -> execute -> prove
+xytara run --help
+npm start                # run the xytara runtime yourself (see .env.example)
+```
+
+## What it does
+
+- discover tasks and workflows, and quote work before execution
+- pay via x402 (gasless USDC on Base) or spend from reusable credits
+- route to an execution provider and receive the deliverable
+- meter usage, reconcile settlement, and handle refunds/disputes
+- integrate third-party adapters; emit proof-compatible facts for xoonya verification
+
+xytara owns execution, quoting, payment, delivery, lifecycle, and integration. It emits
+proof-compatible facts; canonical proof lives in [xoonya](https://naxytra.com/xoonya).
+
+## The open provider network
+
+Any execution provider can plug in. Register an endpoint that serves one or more capabilities; once
+the operator activates it, the runtime routes paid (x402-settled) agent calls to your `/execute`,
+surfaces your output as the buyer's deliverable, splits the revenue, and reconciles a payout ledger.
+The machine-readable integration contract is public:
+
+```
+GET  /v1/provider-network/contract      # how to integrate (fields, routing, economics, lifecycle)
+GET  /v1/provider-network/providers     # public discovery
+POST /v1/provider-network/register      # register your provider
+```
+
+Routing is health-aware with reputation-weighted ordering and in-request failover on
+provably-not-processed failures only (no double-execution).
+
+## Payment rails
+
+x402 (gasless USDC on Base, via the Coinbase CDP facilitator) is the proven pay-per-call rail; A2A,
+A2C, and BOLT (BSV) are also supported. Treasury settlement destinations are configured privately by
+the operator — real treasury and custody details are never in public surfaces.
+
+## Honesty & boundaries
+
+The runtime is **key-less**: payout auto-execution is a deliberate custody decision handled by an
+external signer that holds the treasury key, never a key in the runtime. xytara emits
+proof-compatible facts but does not define proof semantics — that is [xoonya](https://naxytra.com/xoonya).
+
+## Proof
+
+Automated provider payouts, verifiable on Base mainnet (Basescan):
+`0x264be245f6d58c0251bc1d9cbd124fdc46ad73ed746d7a07e750c522c37cac5b`,
+`0x6aff9701556fe00cfb076f36a0cc27296619f1539d0c39242e98123abc288caa`,
+`0xdba7cfef18e46da2cbb9a87a087df9fa1c790793bd9ab1034febe244d4565f36`.
+
+## Learn more
+
+- Why two packages: [`WHY_XYTARA_XOONYA.md`](./WHY_XYTARA_XOONYA.md)
+- Payment rail model: [`XYTARA_PAYMENT_RAIL_TRUTH_MODEL.md`](./XYTARA_PAYMENT_RAIL_TRUTH_MODEL.md)
+- Real payment setup: [`REAL_PAYMENT_SETUP.md`](./REAL_PAYMENT_SETUP.md)
+- Start here: [`START_HERE.md`](./START_HERE.md) · terminology: [`TERMINOLOGY.md`](./TERMINOLOGY.md)
+- Live: https://naxytra.com/xytara · MCP endpoint: https://xytara-mcp-executor.onrender.com/mcp
+
+## License
+
+Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).