@hyperscale0/adl 1.0.0-alpha.1

package/LICENSING.md

@@ -0,0 +1,51 @@
+# Licensing
+
+The code in this repository is Copyright 2026 Hyperscale LLC and is licensed
+under the GNU Affero General Public License version 3 only
+(`AGPL-3.0-only`). The full text is in [`LICENSE`](./LICENSE).
+
+## What the AGPL asks of you
+
+Two obligations matter in practice.
+
+**If you distribute a copy in object form**, modified or not, you make its
+Corresponding Source available under the same license.
+
+**If you run a modified copy as a network service**, section 13 applies: the
+users interacting with it over the network get an offer of the source of the
+version you are running. Validating adapters with an unmodified copy behind
+your own service does not trigger this. Changing the vocabulary, the registry
+loader, or the conformance runner and then serving that change does.
+
+Using `@hyperscale0/adl` as a library inside your own program is a
+combined work under the AGPL. If that does not fit how you ship, take the
+commercial license instead.
+
+## Commercial license
+
+Hyperscale LLC sells a commercial license to organisations that cannot accept
+the AGPL, for the usual reasons: a proprietary adapter that links ADL, a
+hosted service you will not open, a procurement policy that refuses copyleft.
+It grants the same code under ordinary commercial terms with no source
+obligation.
+
+Ask through <https://hyperscale0.ai>.
+
+## The license covers code, not marks
+
+"Hyperscale" is a trademark of Hyperscale LLC. A copyright license says nothing
+about trademarks in either direction, so [TRADEMARKS.md](TRADEMARKS.md) draws
+that boundary.
+
+## The format is not this implementation of it
+
+ADL the format is separate from this package, which implements it. The
+JSON Schema in [`spec/`](spec) and the conformance cases in
+[`conformance/`](conformance) are data describing a format, and anyone may
+write their own validator or registry loader against them, in any language,
+under any license, without touching this code.
+
+What you may then say about it is a trademark question, not a copyright one.
+[TRADEMARKS.md](TRADEMARKS.md) has the rule: claim that you pass a version of
+the conformance suite only when you pass that version's published cases
+unmodified.

package/README.md

@@ -0,0 +1,165 @@
+# ADL
+
+ADL, the Adapter Declaration Language: the format for describing a bank or
+provider to Hyperscale, the validator that refuses a declaration the runtime
+could not operate, and the conformance suite that says when one is ready to
+serve live money.
+
+It is the third of three. UDL describes the product, HSX scripts the money
+movement, ADL declares the provider the money moves through.
+
+**Status: alpha.** `1.0.0-alpha.1`. The surface can still change on a minor
+version until 1.0.0.
+
+## Adapter symmetry
+
+Hyperscale's own bank adapters are written against this package and nothing
+more. There is no private adapter API and no second interface for first-party
+code. When one of our adapters needs a seam ADL lacks, the seam is added here,
+in public, or it is not added.
+
+So the guide below is not a simplified account of how we do it. It is how we
+do it.
+
+## What an adapter is
+
+A declaration, not a client. A plain object saying what the provider does:
+which commands exist, how each response classifies, what the bank's status
+tokens mean, when statements can be fetched, which reference comes back on a
+debit. The runtime that executes it is generic and ships with the platform.
+
+Your adapter opens no sockets, holds no credentials, and decides nothing about
+what a payment means. It states facts, and the checks in this package prove
+those facts are complete enough for a generic runtime to poll, classify,
+reconcile, and dedupe without guessing.
+
+## Install
+
+```bash
+npm install @hyperscale0/adl
+```
+
+Every release before 1.0.0 is an alpha, and `latest` follows the newest one, so
+a bare install gets it. `npm install @hyperscale0/adl@alpha` is the explicit
+form and resolves to the same version. Pin an exact version if you need one:
+until 1.0.0 a change to the surface ships as a minor bump, not a major.
+
+No runtime dependencies, and no proprietary code imported.
+
+## The thirty-second shape
+
+```ts
+import {
+  certifyPartnerBankAdapter,
+  createProviderAdapterRegistry,
+  type ProviderAdapterVocabulary,
+} from "@hyperscale0/adl";
+
+interface MyVocabulary extends ProviderAdapterVocabulary {
+  capability: "payout_execution";
+  operation: "payout.submit";
+  resource: "payout";
+  // ...the rest of your closed unions
+}
+
+const defineAdapters = createProviderAdapterRegistry<MyVocabulary>();
+
+export const adapters = defineAdapters([
+  {
+    provider: "meridian_bank",
+    capability: "payout_execution",
+    egress: "rest",
+    operationMap: {
+      "payout.submit": {
+        operation: "payout.submit",
+        direction: "tenant_initiated",
+        envelope: "http_status_error_body",
+        statusEnquiry: {
+          keys: "provider_reference",
+          pathTemplate: "/v2/payments/{providerReference}",
+        },
+        obligationKind: "payout_submission",
+        resourceKind: "payout",
+        resourceIdPath: "payoutId",
+      },
+    },
+    webhookMap: {},
+    bindings: { payout: "claim" },
+    config: {
+      credentialRef: { source: "environment", name: "MERIDIAN_CREDENTIALS" },
+    },
+    profile: myBankProfile,
+  },
+]);
+
+for (const adapter of adapters) certifyPartnerBankAdapter(adapter);
+```
+
+`createProviderAdapterRegistry` validates at import and preserves your literal
+types. `certifyPartnerBankAdapter` throws with every gap listed at once; an
+empty finding list is the certification.
+
+## Where to go next
+
+- **[docs/authoring-guide.md](docs/authoring-guide.md)** -- the whole job, field
+  by field, with the rule that enforces each one.
+- **[examples/meridian-bank](examples/meridian-bank)** -- a complete certified
+  adapter for a bank that does not exist, with fixtures and its own tests.
+  Copy it.
+- **[conformance/cases.json](conformance/cases.json)** -- every rule as data:
+  one broken fact per case, and what each gate says about it.
+- **[spec/manifest.schema.json](spec/manifest.schema.json)** -- JSON Schema
+  2020-12 for one declaration, for authors who are not writing TypeScript.
+
+## Running conformance
+
+```bash
+bun run conformance -- ./examples/meridian-bank
+```
+
+```
+ok    meridian_bank:payout_execution
+ok    meridian_bank:bank_credit
+2 adapter(s) checked, 0 finding(s) reported
+```
+
+Exit 1 when anything reports, so it drops straight into CI.
+
+## Development
+
+```bash
+bun install
+bun run check     # spec drift, tests, types
+bun run build
+```
+
+## Versioning
+
+Semantic versioning from 1.0.0. Until then, alpha releases may change the
+surface on a minor version. Two promises hold now:
+
+- conformance codes are append-only: a released code is never renamed or
+  removed, so `switch` statements stay exhaustive;
+- removing a value from a vocabulary in `src/vocabulary.ts` is a breaking
+  change and appears in [CHANGELOG.md](CHANGELOG.md).
+
+## Contributing
+
+Issues only. Hyperscale makes the changes to the format and the package; you
+propose them in an issue carrying the provider that needs the seam and the
+conformance case it would add. [CONTRIBUTING.md](CONTRIBUTING.md) has that
+model in full, plus the loop: what earns a new field, how to regenerate the
+schema, and the CLA behind a rare accepted pull request. Participation is under
+the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+Vulnerabilities go through GitHub private reporting, never a public issue. See
+[SECURITY.md](SECURITY.md).
+
+## License
+
+AGPL-3.0-only, with a commercial license available from Hyperscale LLC for
+organisations that cannot accept the AGPL. See [LICENSE](LICENSE) for the text
+and [LICENSING.md](LICENSING.md) for which one you want and how to ask for the
+commercial one. Neither covers the Hyperscale marks;
+[TRADEMARKS.md](TRADEMARKS.md) says what that means and carries the rule for
+claiming conformance.

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Report privately through GitHub: open the **Security** tab of this repository
+and choose **Report a vulnerability**. That opens a private advisory only the
+maintainers can read.
+
+Do not open a public issue for a vulnerability, and do not include credentials
+or production data in a report.
+
+What helps: the version, what an attacker gains, and the smallest reproduction
+you have. A declaration that triggers the bug is ideal, with every locator
+value removed.
+
+We acknowledge reports within three working days and tell you what we intend
+to do. Fixes ship on the current alpha line; there are no backports before
+1.0.0.
+
+## Scope
+
+This package validates declarations. It performs no network calls, reads no
+credentials, and executes nothing an adapter author does not import
+themselves. Reports about the runtime that executes adapters belong to the
+platform, not here.
+
+`ProviderCredentialReference` stores locators only, never secret values. A
+declaration carrying a real credential is a mistake in that repository, not a
+vulnerability in this one, but tell us if ADL made it easy.

package/TRADEMARKS.md

@@ -0,0 +1,30 @@
+# Trademarks
+
+"Hyperscale" and "ADL" are trademarks of Hyperscale LLC.
+
+The AGPL covers the code in this repository and nothing else. It grants no
+right to use the Hyperscale name, the Hyperscale logo, or any other Hyperscale
+mark, and it never mentions them: a copyright license says nothing about
+trademarks either way.
+
+What that means in practice:
+
+- **Yes**, you may say your adapter is written in ADL, or that it passes
+  Hyperscale conformance. Accurate, factual references to the project are fine.
+- **No**, you may not name your package, product, service, or organization in a
+  way that suggests Hyperscale LLC published it or endorses it, and you may not
+  use the marks in a logo, domain, or app icon of your own.
+
+## Claiming compatibility
+
+An independent implementation of ADL or of its conformance
+runner may say it "passes the Hyperscale ADL conformance suite version X"
+only while it passes the published cases for that version, unmodified.
+[`conformance/cases.json`](conformance/cases.json) is the whole test: no
+skipped case, no edited expectation, no local fork of the fixtures.
+
+That claim is a statement about your implementation, so keep the marks out of
+its name and off its logo, and do not present it as endorsement or
+certification by Hyperscale LLC. We certify nothing; the suite does.
+
+Forks stay welcome. Rename the package and drop the marks.