xytara 3.1.16 → 3.2.0

package/adapters/AUTHORING_GUIDE.md

@@ -1,244 +0,0 @@
-# Adapter Authoring Guide
-
-This guide describes the minimum process for a third party to build an adapter on top of `xytara`.
-
-## 1. Choose an adapter class
-
-Supported starter classes:
-
-- `execution_adapter`
-- `payment_rail_adapter`
-- `settlement_adapter`
-- `agent_protocol_adapter`
-- `identity_registry_adapter`
-
-Pick the class that matches the boundary you are integrating.
-
-## 2. Start from the manifest schema
-
-Use:
-
-- adapter-manifest.schema.json
-- integration-registration-record.schema.json
-- integration-certification-pack.schema.json
-- integration-submission-bundle.schema.json
-- integration-submission-bundle-set.schema.json
-
-Every adapter must publish a manifest that defines:
-
-- adapter identity
-- adapter class
-- interface version
-- registration contract
-- certification contract
-- compatibility
-- health contract
-- idempotency contract
-- failure contract
-- proof contract
-
-## 3. Implement the interface contract
-
-Use:
-
-- interfaces.js
-
-All adapters must provide:
-
-- `manifest`
-- `getHealth()`
-- `describeCapabilities()`
-
-Execution adapters should also provide:
-
-- `preview()`
-- `execute()`
-
-Settlement adapters should also provide:
-
-- `settle()`
-- `getFinality()`
-
-## 4. Start from an example
-
-Current examples:
-
-- example-execution-adapter.manifest.json
-- example-execution-adapter.js
-- example-settlement-adapter.manifest.json
-- example-settlement-adapter.js
-- example-third-party-registration.submission-bundle.json
-- example-third-party-acp-registration.submission-bundle.json
-- example-third-party-identity-registration.submission-bundle.json
-- example-third-party-erc8004-registration.submission-bundle.json
-- example-third-party-langchain-registration.submission-bundle.json
-- example-third-party-mpp-registration.submission-bundle.json
-- example-third-party-settlement-registration.submission-bundle.json
-
-If you want the shortest reviewable end-to-end path, use:
-
-- THIRD_PARTY_SUBMISSION_PROCESS.md
-
-## 5. Run certification
-
-Run:
-
-```bash
-npm run verify:adapters
-```
-
-That currently validates:
-
-- manifest shape
-- interface version
-- manifest/implementation agreement
-- representative health/capability behavior
-- representative method behavior for example adapters
-
-## 6. Declare registration posture
-
-Each manifest should also declare how the integration is intended to enter runtime selection:
-
-- `registration_contract.integration_id`
-- `registration_contract.integration_maturity`
-- `registration_contract.bundled`
-- `registration_contract.default_selection_enabled`
-- optional selection controls such as priority and explicit-selection posture
-
-This keeps registration explicit and makes future third-party promotion predictable.
-
-## 7. Declare certification posture
-
-Each manifest should say what level of trust it is claiming:
-
-- `reference_example`
-- `self_attested`
-- `certified`
-
-and which checks that claim is based on through:
-
-- `certification_contract.certification_scope`
-- `certification_contract.verified_with`
-- `certification_contract.last_verified_contract_version`
-
-This lets discovery and promotion make trust visible instead of hidden.
-
-## 8. Prepare a registration record
-
-Before an adapter is promoted into staging or production, create a registration record that captures:
-
-- registration state
-- maturity
-- certification state
-- bundled vs third-party posture
-- default-selection posture
-- who registered it and when
-
-Use:
-
-- integration-registration-record.schema.json
-- example-third-party-registration.record.json
-- example-third-party-settlement-registration.record.json
-
-This keeps promotion explicit and gives future registry services a stable data shape to adopt.
-
-Toolkit helpers are also available in the package surface for registry-side tooling:
-
-- `validateIntegrationRegistration(...)`
-- `validateIntegrationCertificationPack(...)`
-- `validateIntegrationSubmission(...)`
-- `importRegisteredIntegration(...)`
-- `createIntegrationRegistrySnapshot(...)`
-- `exportIntegrationRegistrySnapshot(...)`
-- `validateIntegrationSubmissionBundle(...)`
-- `createIntegrationSubmissionBundle(...)`
-- `importIntegrationSubmissionBundle(...)`
-- `exportIntegrationSubmissionBundles(...)`
-- `createIntegrationRegistrySnapshotFromBundles(...)`
-- `createIntegrationSubmissionBundleSet(...)`
-- `validateIntegrationSubmissionBundleSet(...)`
-- `exportIntegrationSubmissionBundleSet(...)`
-
-That means future registry automation can validate and normalize a manifest + registration-record pair without reimplementing the rules.
-
-## 9. Prepare a certification pack
-
-Before a staged or production registration is trusted, assemble a certification pack that records:
-
-- claimed certification state
-- certification scope
-- verification evidence and reports
-- submission timestamp and operator
-
-Use:
-
-- integration-certification-pack.schema.json
-- example-third-party-registration.certification-pack.json
-- example-third-party-settlement-registration.certification-pack.json
-
-This keeps certification evidence explicit instead of leaving it as an undocumented side channel.
-
-## 10. Assemble a submission bundle
-
-When you want one reusable handoff artifact for staging or review, combine:
-
-- manifest
-- registration record
-- certification pack
-- optional normalized snapshot entry
-
-Use:
-
-- integration-submission-bundle.schema.json
-- example-third-party-registration.submission-bundle.json
-- example-third-party-settlement-registration.submission-bundle.json
-
-This gives future integrations one predictable artifact for authoring review, staging review, or registry import.
-
-Public posture rule:
-
-- native support means `xytara` ships a bundled first-party integration in the registry
-- adapter support means the public contract and authoring path are available for that class or lane
-- third-party plugin posture means the integration should normally enter through explicit submission bundles and staged registration before default rollout
-
-Bundle-driven staging/export is also supported, so a set of reviewed third-party integrations can be turned into a normalized registry snapshot without custom glue code.
-
-If you need to hand off multiple reviewed integrations together, package them as a bundle set rather than inventing a one-off folder convention each time.
-
-Practical rule:
-
-- staged third-party integrations can be visible in discovery
-- staged third-party integrations should normally require explicit selection
-- becoming visible is not the same thing as becoming a default
-
-That keeps reviewable integrations easy to inspect without letting them quietly replace bundled defaults.
-
-## 11. Bundle-set review flow
-
-For a small multi-integration review pass, the clean sequence is:
-
-1. validate each submission bundle
-2. export a submission bundle set
-3. derive a registry snapshot from that reviewed set
-4. only then consider staging or production registration
-
-The repo-local CLI supports that review loop directly when working from a cloned `xytara` repository:
-
-```bash
-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 --notes "review batch"
-node scripts/registry_cli.js export-snapshot
-```
-
-## 12. Keep the boundary clean
-
-Adapters should integrate external systems without redefining:
-
-- proof semantics
-- quote semantics
-- core commerce lifecycle semantics
-
-They translate external systems into the stack contract. They do not replace the stack contract.
-

package/adapters/ONBOARDING_POSTURE.md

@@ -1,61 +0,0 @@
-# Adapter Onboarding Posture
-
-This note captures the current intended onboarding flow for third-party adapters.
-
-## Current onboarding path
-
-1. implement adapter against the public interface version
-2. publish a manifest that satisfies the schema
-3. validate implementation behavior with the adapter verifier
-4. confirm compatibility with the current commerce and proof contracts
-5. declare registration and certification posture in the manifest
-6. add the adapter into catalog/runtime registration only after certification passes
-
-## Current registration stance
-
-This repo does not yet provide a full public adapter registry service.
-
-The current posture is:
-
-- adapter manifests and implementations can be authored against the public contract
-- certification begins locally with `npm run verify:adapters`
-- registration posture should be declared explicitly through manifest metadata
-- promotion should also create a normalized registration record
-- runtime registration remains an explicit product step, not an implicit side effect of dropping files into the repo
-
-## Promotion model
-
-Recommended promotion flow:
-
-1. local development
-2. local certification
-3. self-attested or certified manifest posture
-4. registration record creation
-5. staging/runtime integration
-6. production registration
-
-## Review checkpoints
-
-Before a third-party integration is treated as operationally serious, we should be able to answer:
-
-- is it review-ready?
-- is it default-eligible?
-- is it production-default-ready?
-- what blockers are still present?
-
-Those answers should come from the artifact model and review helpers, not from private judgment calls.
-
-Use:
-
-- THIRD_PARTY_SUBMISSION_PROCESS.md
-
-to keep that process repeatable for external builders and internal reviewers.
-
-## Why this matters
-
-This keeps adapter support:
-
-- flexible
-- testable
-- explicit
-- less likely to drift into hidden private assumptions

package/adapters/THIRD_PARTY_SUBMISSION_PROCESS.md

@@ -1,84 +0,0 @@
-# Third-Party Submission Process
-
-This note is the shortest end-to-end path for a third party building on `xytara`.
-
-## Goal
-
-Produce one reviewable integration package that can move from local development to staging review without inventing custom process per adapter.
-
-## Submission artifact stack
-
-Every serious third-party integration should converge on four artifacts:
-
-1. adapter manifest
-2. registration record
-3. certification pack
-4. submission bundle
-
-If multiple integrations are being reviewed together, package them as a submission bundle set.
-
-## Recommended flow
-
-1. Choose the adapter class.
-2. Implement the adapter against the public interface contract.
-3. Build the manifest against the public schema.
-4. Run local verification with `npm run verify:adapters`.
-5. Create the registration record.
-6. Create the certification pack.
-7. Assemble the submission bundle.
-8. Review the bundle locally.
-9. Export a bundle set if multiple integrations are being reviewed together.
-10. Derive a registry snapshot from the reviewed bundle set.
-11. Only then consider staging registration or production-default promotion.
-
-## Review commands
-
-From a cloned `xytara` repo:
-
-```bash
-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 review-bundle --example protocol
-node scripts/registry_cli.js review-bundle --example identity
-node scripts/registry_cli.js review-bundle --example settlement
-node scripts/registry_cli.js review-bundle-set --notes "review batch"
-node scripts/registry_cli.js review-snapshot
-node scripts/registry_cli.js promotion-readiness --integration partner.protocol.acme_mcp
-```
-
-## Promotion posture
-
-These states should stay explicit:
-
-- `review_ready`
-- `default_eligible`
-- `production_default_ready`
-
-Typical staged third-party posture:
-
-- discoverable: yes
-- reviewable: yes
-- explicitly selectable: yes
-- default-eligible: no
-- production-default-ready: no
-
-That is the safe default. Promotion should be intentional.
-
-## What not to do
-
-- Do not assume discovery means default selection.
-- Do not skip the registration record and jump straight from manifest to runtime use.
-- Do not treat certification evidence as an undocumented side channel.
-- Do not add adapter-specific workflow rules when the registry model can already express the posture.
-
-## Clean handoff rule
-
-If another team receives only the submission bundle and bundle-set artifacts, they should still be able to:
-
-- validate the integration
-- inspect the claimed posture
-- understand blockers
-- derive a normalized registry snapshot
-
-That is the standard we want to preserve as the integration surface grows.

package/adapters/adapter-manifest.schema.json

@@ -1,283 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "xytara/adapter-manifest.schema.json",
-  "title": "xytara Adapter Manifest",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "adapter_id",
-    "adapter_class",
-    "adapter_version",
-    "interface_version",
-    "display_name",
-    "description",
-    "capabilities",
-    "compatibility",
-    "health_contract",
-    "idempotency_contract",
-    "failure_contract",
-    "proof_contract"
-  ],
-  "properties": {
-    "adapter_id": {
-      "type": "string",
-      "minLength": 1
-    },
-    "adapter_class": {
-      "type": "string",
-      "enum": [
-        "execution_adapter",
-        "payment_rail_adapter",
-        "settlement_adapter",
-        "agent_protocol_adapter",
-        "identity_registry_adapter"
-      ]
-    },
-    "adapter_version": {
-      "type": "string",
-      "minLength": 1
-    },
-    "interface_version": {
-      "type": "string",
-      "minLength": 1
-    },
-    "display_name": {
-      "type": "string",
-      "minLength": 1
-    },
-    "description": {
-      "type": "string",
-      "minLength": 1
-    },
-    "capabilities": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
-    "compatibility": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "node",
-        "commerce_contract",
-        "proof_contract"
-      ],
-      "properties": {
-        "node": {
-          "type": "string",
-          "minLength": 1
-        },
-        "commerce_contract": {
-          "type": "string",
-          "minLength": 1
-        },
-        "proof_contract": {
-          "type": "string",
-          "minLength": 1
-        }
-      }
-    },
-    "health_contract": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "check_kind",
-        "supports_readiness"
-      ],
-      "properties": {
-        "check_kind": {
-          "type": "string",
-          "minLength": 1
-        },
-        "supports_readiness": {
-          "type": "boolean"
-        }
-      }
-    },
-    "idempotency_contract": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "strategy",
-        "scope"
-      ],
-      "properties": {
-        "strategy": {
-          "type": "string",
-          "minLength": 1
-        },
-        "scope": {
-          "type": "string",
-          "minLength": 1
-        }
-      }
-    },
-    "failure_contract": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "categories",
-        "retryable_categories"
-      ],
-      "properties": {
-        "categories": {
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "retryable_categories": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
-        }
-      }
-    },
-    "proof_contract": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "emits_proof_compatible_facts",
-        "proof_mode"
-      ],
-      "properties": {
-        "emits_proof_compatible_facts": {
-          "type": "boolean"
-        },
-        "proof_mode": {
-          "type": "string",
-          "minLength": 1
-        }
-      }
-    },
-    "latency_class": {
-      "type": "string"
-    },
-    "pricing_basis": {
-      "type": "string"
-    },
-    "execution_modes": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
-    "required_secrets": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
-    "required_permissions": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
-    "supported_profiles": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
-    "supported_regions": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
-    "supported_settlement_modes": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
-    "registration_contract": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "integration_id",
-        "integration_maturity",
-        "bundled",
-        "default_selection_enabled"
-      ],
-      "properties": {
-        "integration_id": {
-          "type": "string",
-          "minLength": 1
-        },
-        "integration_maturity": {
-          "type": "string",
-          "enum": [
-            "reference_example",
-            "staging_candidate",
-            "production_default"
-          ]
-        },
-        "bundled": {
-          "type": "boolean"
-        },
-        "default_selection_enabled": {
-          "type": "boolean"
-        },
-        "selection_priority": {
-          "type": "integer",
-          "minimum": 0
-        },
-        "requires_explicit_selection": {
-          "type": "boolean"
-        }
-      }
-    },
-    "certification_contract": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "certification_state",
-        "certification_scope"
-      ],
-      "properties": {
-        "certification_state": {
-          "type": "string",
-          "enum": [
-            "reference_example",
-            "self_attested",
-            "certified"
-          ]
-        },
-        "certification_scope": {
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "verified_with": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "last_verified_contract_version": {
-          "type": "string",
-          "minLength": 1
-        }
-      }
-    }
-  }
-}