diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index a805443..18c6e36 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -18,8 +18,7 @@ jobs: node-version: 20 cache: npm - run: npm ci - - run: npm run validate:schemas - - run: npm run validate:examples - - run: npm run validate:integrity + - run: npm run validate - run: npm run generate:checksums - run: git diff --exit-code -- checksums.txt + - run: npm pack --dry-run diff --git a/ONBOARDING.md b/ONBOARDING.md index 59b95e8..e2a1908 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -4,18 +4,19 @@ This document is an orientation guide for the active v1.1.0 release line. Contri ## Document scope -Use this document to understand the repository shape, release line, and maintainer intent before editing. +Use this document to understand the repository shape, release line, and published package boundary before editing. For the authoritative version policy, checksum boundary, and validation requirements, see `POLICY.md` and `SPEC.md`. ## External consumer workflow -1. Use the repository contents directly, or a published distribution only after release metadata confirms it. -2. Confirm the current line in `manifest.json` and use `schemas/v1.1.0/index.json` as the authoritative schema map. -3. Choose flat schemas under `schemas/v1.1.0/commercial//` for validator configuration. -4. Run the maintained verification commands listed in `SPEC.md` before mirroring or vendoring. -5. Treat `examples/v1.1.0/commercial//valid/` and `invalid/` as conformance fixtures. -6. Use `v1.0.0` only when compatibility with the historical nested path model is required. +1. Use `manifest.json` to confirm that `v1.1.0` is the current line. +2. Treat the shipped package surface as limited to `schemas/v1.1.0/`, `examples/v1.1.0/`, `manifest.json`, `checksums.txt`, `LICENSE`, `README.md`, and `index.js`. +3. Use `index.js` or `schemas/v1.1.0/index.json` as the package entrypoint to the current schema map. +4. Choose flat schemas under `schemas/v1.1.0/commercial//` for validator configuration. +5. Run the maintained verification commands listed in `README.md#validation-commands` before mirroring or vendoring. +6. Treat `examples/v1.1.0/commercial//valid/` and `invalid/` as conformance fixtures. +7. Treat `v1.0.0` as repository-only historical material unless a separate compatibility workflow explicitly vendors it from source. ## Maintainer workflow @@ -26,8 +27,8 @@ High-level maintainer sequence: 1. Install dependencies with `npm install`. 2. Edit schemas, examples, metadata, scripts, and docs coherently. 3. Run the canonical validation commands referenced from `README.md#validation-commands`. -4. Regenerate `checksums.txt` only when checksum-covered machine artifacts change. -5. Keep current-line teaching focused on `v1.1.0` and mark `v1.0.0` as retained legacy. +4. Regenerate `checksums.txt` when any checksum-covered published payload file changes. +5. Keep current-line teaching focused on `v1.1.0` and keep `v1.0.0` out of the shipped package boundary. ## Adding a new commercial verb @@ -36,10 +37,10 @@ High-level maintainer sequence: 3. Create matching example folders under `examples//commercial//valid` and `invalid`. 4. Add at least one valid request, one alternate valid request or receipt, one invalid request, and one invalid receipt. 5. Make every invalid example isolate a single intended failure when practical. -6. Do not add an ungoverned `examples/v1.1.0/**/ts/` surface to the current line. -7. Update `manifest.json`, `schemas//index.json`, validation expectations, and checksums. -8. Update README, INTEGRATOR, SPEC, and release-process docs if the public teaching surface changed. -9. Confirm public docs controlled by this repo still teach the exact current path model and current script names. +6. Do not add an ungoverned `examples/v1.1.0/**/ts/` surface to the active line. +7. Update `manifest.json`, `schemas//index.json`, package exports, validation expectations, and checksums. +8. Update README, SPEC, and release-process docs if the public teaching surface changed. +9. Confirm public docs controlled by this repo still teach the exact current path model and shipped package boundary. ## Version bumps @@ -47,7 +48,8 @@ High-level maintainer sequence: 2. Create a new `schemas/vX.Y.Z/` and `examples/vX.Y.Z/` tree. 3. Update `package.json`, `manifest.json`, README, SPEC, policy docs, and workflow assumptions. 4. Draft release notes and changelog updates for the new line before publication. -5. Regenerate checksums for the new current line's machine-artifact set. +5. Regenerate checksums for the new line's checksum-covered published payload. +6. Move superseded lines out of the shipped package boundary unless they are explicitly revalidated and intentionally kept. For the canonical path model and namespace rules, see `SPEC.md`. @@ -56,7 +58,7 @@ For the canonical path model and namespace rules, see `SPEC.md`. The repository does not automate publication, GitHub Release publication, IPFS pinning, CID capture, or mirror updates. If your release process uses those steps, perform them manually after the new version line has passed validation: 1. Publish the GitHub Release using `releases/v1.1.0.md` or the corresponding new-version draft. -2. Pin the checksum-covered release artifact set to IPFS, if that distribution channel is being used for the release. +2. Pin the checksum-covered published payload to IPFS, if that distribution channel is being used for the release. 3. Capture resulting CIDs in the external release record if your publication process requires them. 4. Update commandlayer.org mirrors to match the release paths exactly. 5. Update any Agent Card schema bindings that reference the superseded version. @@ -64,8 +66,8 @@ The repository does not automate publication, GitHub Release publication, IPFS p ## Release hygiene - Keep the current line obvious. -- Keep legacy lines explicitly marked as legacy. +- Keep legacy lines explicitly marked as repository-only historical material. - Keep schema paths flat and mirror-safe. -- Keep checksum scope explicit. +- Keep package surface and checksum scope explicit. - Keep GitHub Releases and repository docs in sync. - Prefer linking over duplication. diff --git a/POLICY.md b/POLICY.md index 636c460..4e144f4 100644 --- a/POLICY.md +++ b/POLICY.md @@ -1,25 +1,48 @@ # POLICY — Protocol-Commercial -This policy governs the current release line and its release-management rules. Repo-wide governance and security reporting are defined separately. +This policy governs the active release line and the canonical published package boundary. Repo-wide governance and security reporting are defined separately. ## Current line -`v1.1.0` is the current Protocol-Commercial line. +`v1.1.0` is the current Protocol-Commercial line and the only canonical published package line. -`v1.0.0` remains published for backward compatibility and audit, but it is superseded and non-canonical for new integrations. +`v1.0.0` may remain in the repository as historical source material for audit or migration reference, but it is outside the shipped npm package surface and outside the active canonical release boundary. ## Change control - No published version directory may be silently mutated after release. - Breaking or semantic changes require a new version directory. -- Release metadata, examples, schema paths, and checksums must remain internally consistent. -- Public documentation controlled by this repo must teach the same path model the repo actually ships. +- Release metadata, package contents, schema paths, examples, and checksums must remain internally consistent. +- Public documentation controlled by this repo must teach the same current-line package boundary the repo actually ships. -## Normative artifact state +## Canonical published boundary -The checksum-covered release state consists of the current schema tree, current examples tree, and `manifest.json`. `checksums.txt` is the generated ledger for that machine-artifact set. +The canonical published package surface for `v1.1.0` is limited to: -Release-defining prose docs may govern interpretation and process, but they are outside checksum coverage unless the checksum tooling is changed deliberately. +- `schemas/v1.1.0/` +- `examples/v1.1.0/` +- `manifest.json` +- `checksums.txt` +- `LICENSE` +- `README.md` +- `index.js` + +Legacy `v1.0.0` schemas, examples, and any historical TypeScript fixtures are repository-retained material only unless a future release explicitly restores them to a validated package boundary. + +## Integrity boundary + +`checksums.txt` is the generated ledger for the canonical published package payload, excluding `checksums.txt` itself. + +The checksum-covered payload consists of: + +- `schemas/v1.1.0/` +- `examples/v1.1.0/` +- `manifest.json` +- `LICENSE` +- `README.md` +- `index.js` + +Release-defining prose docs outside that list are repository guidance only and must not be described as part of the shipped or checksum-covered release payload. ## Governance threshold diff --git a/README.md b/README.md index 93f0048..21745d9 100644 --- a/README.md +++ b/README.md @@ -27,14 +27,15 @@ Protocol-Commercial is intentionally limited to protocol truth: ## Document scope -This README is a repo-wide orientation document for the current release line and its retained legacy line. +This README is a repo-wide orientation document for the active release line and its canonical published package boundary. ## Release truth - **Current canonical line:** `v1.1.0` - **Current canonical schema root:** `https://commandlayer.org/schemas/v1.1.0/` -- **Current package entrypoint:** `schemas/v1.1.0/index.json` -- **Historical legacy line:** `v1.0.0`, retained under `schemas/v1.0.0/` and `examples/v1.0.0/` +- **Current package entrypoint:** `index.js` → `schemas/v1.1.0/index.json` +- **Canonical published package surface:** `schemas/v1.1.0/`, `examples/v1.1.0/`, `manifest.json`, `checksums.txt`, `LICENSE`, `README.md`, `index.js` +- **Historical repository-only line:** `v1.0.0`, retained under `schemas/v1.0.0/` and `examples/v1.0.0/` - **Changelog:** `CHANGELOG.md` - **Release note draft for a future GitHub Release publication:** `releases/v1.1.0.md` @@ -49,7 +50,7 @@ This repository is the source of truth for those schema files and release metada ## Schema identity and trust - `https://commandlayer.org/...` is the canonical schema namespace and the normative `$id` base for this release line. -- This Git repository and its published package contents are the source of truth for those artifacts. +- This Git repository and its canonical published package contents are the source of truth for those artifacts. - External resolution of `$id` URLs is a convenience, not a trust requirement; consumers should vendor, mirror, or package-pin the repository artifacts they validate against. ## Relationship to the stack @@ -72,23 +73,23 @@ The stack story is singular: For consumers who need the shortest safe path: -1. Install the package and import the current index entrypoint using the explicit JSON path export. +1. Install the package and use the package-root export or explicit current-line schema export. ```bash npm install @commandlayer/commercial ``` ```js - import commercialIndex from '@commandlayer/commercial/schemas/v1.1.0/index.json'; + import commercialIndex from "@commandlayer/commercial"; ``` - The bare package import `@commandlayer/commercial` resolves to the same file today, but treat that shortcut as environment-dependent rather than the default documentation path. -2. Treat `schemas/v1.1.0/index.json` as the authoritative map of current schemas and verb inventory. + ```js + import commercialSchemaIndex from "@commandlayer/commercial/schemas/v1.1.0/index.json"; + ``` +2. Treat `schemas/v1.1.0/index.json` as the authoritative map of current schemas and verb inventory. The package-root `index.js` export resolves to that same file. 3. Prefer `schemas/v1.1.0/commercial//.request.schema.json` and `...receipt.schema.json` directly for validator configuration. -4. Verify the machine-artifact set before mirroring or vendoring using the canonical command surface in [Validation commands](#validation-commands). -5. Ignore `v1.0.0` unless you are maintaining compatibility with historical nested paths. Current automated validation targets `v1.1.0`; retained `v1.0.0` artifacts remain published for compatibility and audit without equal current-line guarantees. -6. Treat schemas and `manifest.json` as normative machine artifacts. Treat examples as illustrative conformance fixtures. Treat prose docs as normative interpretation and release-process guidance. - -Package-install instructions are intentionally omitted here because npm publication for `@commandlayer/commercial` could not be verified from this repository alone. +4. Verify the shipped current-line payload before mirroring or vendoring using the canonical command surface in [Validation commands](#validation-commands). +5. Ignore `v1.0.0` unless you are consulting repository-local historical material for migration work. It is not part of the canonical shipped package surface. +6. Treat schemas, examples, `manifest.json`, `README.md`, `LICENSE`, and `index.js` as the shipped release payload. Treat `checksums.txt` as the ledger for that payload. -A longer external-consumer workflow lives in `INTEGRATOR.md`. +Package-install instructions are intentionally minimal here because npm publication state for `@commandlayer/commercial` could not be verified from this repository alone. ## Commercial execution model @@ -144,7 +145,7 @@ The verbs use those layers intentionally: ```text protocol-commercial/ ├── schemas/ -│ ├── v1.0.0/ # published legacy line; historical nested layout +│ ├── v1.0.0/ # repository-only historical nested layout │ └── v1.1.0/ │ ├── index.json │ └── commercial/ @@ -164,12 +165,13 @@ protocol-commercial/ │ ├── verify.request.schema.json │ └── verify.receipt.schema.json ├── examples/ -│ ├── v1.0.0/ # published legacy line +│ ├── v1.0.0/ # repository-only historical examples │ └── v1.1.0/commercial//{valid,invalid}/ ├── manifest.json ├── checksums.txt -├── CHANGELOG.md -├── INTEGRATOR.md +├── index.js +├── LICENSE +├── README.md └── scripts/ ``` @@ -263,10 +265,10 @@ sha256sum -c checksums.txt ``` - `npm test` runs the full current-line validation aggregate (`npm run validate`). -- `npm run validate:schemas` checks current-line metadata, schema identity, layout, and manifest/index alignment expectations. +- `npm run validate:schemas` checks current-line metadata, package boundary, schema identity, layout, and manifest/index alignment expectations. - `npm run validate:examples` validates every current-line JSON valid and invalid example against the canonical schemas. -- `npm run validate:integrity` verifies the checksum file scope and hash coverage for the current release artifact set. -- `checksums.txt` intentionally covers machine-validated release payloads only: `manifest.json`, `schemas/v1.1.0/`, and `examples/v1.1.0/`. +- `npm run validate:integrity` verifies the canonical shipped payload scope and hash coverage for the current release line. +- `checksums.txt` intentionally covers the shipped payload excluding the ledger itself: `manifest.json`, `schemas/v1.1.0/`, `examples/v1.1.0/`, `LICENSE`, `README.md`, and `index.js`. ## Agent Cards and Commons alignment @@ -279,13 +281,13 @@ Protocol-Commons and Protocol-Commercial therefore tell one coherent story: - Commons defines base actions. - Commercial defines monetized overlays. - Agent Cards point at the current flat commercial schema paths. -- Legacy nested v1.0.0 paths remain published only for compatibility. +- Legacy nested v1.0.0 paths remain in the repository only as historical source material. ## Checksum boundary and provenance summary The checksum boundary is defined normatively in `SPEC.md` and governed by `POLICY.md`. -`checksums.txt` is the generated hash ledger for that machine-artifact set; it describes that surface but is not itself part of the hashed payload, so checksum verification confirms covered files only relative to the checked-in `checksums.txt` ledger and does not independently authenticate that ledger. Release-defining prose docs such as `README.md`, `SPEC.md`, `POLICY.md`, `SECURITY_PROVENANCE.md`, `INTEGRATOR.md`, and `ONBOARDING.md` are authoritative guidance, but they are outside the checksum surface unless the tooling is expanded deliberately in a later release. +`checksums.txt` is the generated hash ledger for the shipped payload; it describes that surface but is not itself part of the hashed payload, so checksum verification confirms covered files only relative to the checked-in `checksums.txt` ledger and does not independently authenticate that ledger. Repository docs outside the published package surface remain authoritative guidance inside the repo, but they are not shipped or checksum-covered unless package metadata is expanded deliberately in a later release. For external verification, the minimal path is: @@ -293,4 +295,4 @@ For external verification, the minimal path is: 2. Run `npm run validate:integrity`. 3. Run `sha256sum -c checksums.txt`. 4. Load `schemas/v1.1.0/index.json` and bind validators from the listed request and receipt schema paths. -5. Ignore `v1.0.0` unless compatibility requires the historical line. +5. Ignore `v1.0.0` unless you are consulting repository-only historical material during migration work. diff --git a/SECURITY_PROVENANCE.md b/SECURITY_PROVENANCE.md index 154c051..f77526e 100644 --- a/SECURITY_PROVENANCE.md +++ b/SECURITY_PROVENANCE.md @@ -4,18 +4,33 @@ Current release line: `v1.1.0` -Checksum-covered machine-artifact roots: +Canonical shipped npm package surface: - `schemas/v1.1.0/` - `examples/v1.1.0/` - `manifest.json` +- `checksums.txt` +- `LICENSE` +- `README.md` +- `index.js` -`checksums.txt` is the generated SHA-256 ledger for that machine-artifact set. It describes the checksum-covered payload but is not itself part of the hashed payload, so checksum verification confirms covered files only relative to the checked-in `checksums.txt` ledger and does not independently authenticate that ledger. Release-defining prose docs in the repository are intentionally outside this checksum boundary and must not be described as checksum-protected. +Checksum-covered published payload: + +- `schemas/v1.1.0/` +- `examples/v1.1.0/` +- `manifest.json` +- `LICENSE` +- `README.md` +- `index.js` + +`checksums.txt` is the generated SHA-256 ledger for that checksum-covered payload. Because the ledger describes the payload, it is not itself part of the hashed payload. Checksum verification therefore confirms the published payload relative to the checked-in `checksums.txt` ledger and does not independently authenticate that ledger. Release integrity state for this repository: - `manifest.json` marks `v1.1.0` as the current release line. -- `checksums.txt` records repository-local SHA-256 digests for the normative schema and example artifacts published from this tree. +- `checksums.txt` records repository-local SHA-256 digests for the canonical shipped payload excluding the ledger file itself. +- `index.js` resolves the package root export to `schemas/v1.1.0/index.json`. - Canonical schema `$id` values resolve to the commandlayer.org release paths for `v1.1.0`. +- Retained `v1.0.0` material is repository-only historical source and is not part of the shipped package boundary. This file makes only repository-backed claims. It does not assert external pin, CID, or public mirror state unless those values are recorded in this repository. diff --git a/SPEC.md b/SPEC.md index eee2ee3..5cd3575 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,6 +1,6 @@ # SPEC — Protocol-Commercial v1.1.0 -This document is normative for the current v1.1.0 commercial release line. +This document is normative for the active v1.1.0 commercial release line. ## 1. Scope @@ -14,24 +14,41 @@ This specification governs: - deterministic versioning rules - x402-first commercial binding expectations - validation and integrity requirements +- canonical published package boundary requirements This specification does not govern runtime transport implementation, provider policy, or legal adjudication. -## 2. Artifact scope by line +## 2. Canonical release boundary -Current normative machine-artifact line: +The canonical published package line is `v1.1.0` only. + +Canonical published package contents: - `schemas/v1.1.0/` - `examples/v1.1.0/` - `manifest.json` -- `checksums.txt` as the generated hash ledger describing that machine-artifact set +- `checksums.txt` +- `LICENSE` +- `README.md` +- `index.js` + +Checksum-covered published payload: + +- `schemas/v1.1.0/` +- `examples/v1.1.0/` +- `manifest.json` +- `LICENSE` +- `README.md` +- `index.js` + +`checksums.txt` is the generated hash ledger describing that checksum-covered payload and is therefore not itself part of the hashed payload. -Published legacy line retained but superseded: +Historical repository-only material that is outside the canonical shipped package boundary: - `schemas/v1.0.0/` - `examples/v1.0.0/` -Release-defining prose docs remain normative for interpretation, but they are outside the checksum surface unless checksum tooling is expanded intentionally. +Additional prose docs may remain authoritative for interpretation or process inside the repository, but they are outside the published package surface unless package metadata is changed deliberately in a later release. ## 3. Version and identity rules @@ -41,8 +58,9 @@ Release-defining prose docs remain normative for interpretation, but they are ou 4. A schema file path and its `$id` MUST agree exactly. 5. A v1.1.0 schema MUST NOT be mutated in place after release publication. 6. Breaking or meaning-changing edits require a new version directory. -7. `manifest.json` MUST identify the current release line and any retained legacy lines. -8. `checksums.txt` MUST enumerate the canonical machine-verifiable release artifact set and MUST NOT be described as protecting prose docs it does not hash. +7. `manifest.json` MUST identify the current release line and any retained repository-only legacy lines. +8. `checksums.txt` MUST enumerate the checksum-covered published payload exactly and MUST NOT be described as protecting files it does not hash. +9. The npm `files` surface and package exports MUST exclude non-canonical legacy lines unless those lines are revalidated and intentionally reintroduced. ## 4. Current path model @@ -59,7 +77,7 @@ The canonical current-line pattern is: - `https://commandlayer.org/schemas/v1.1.0/commercial//.request.schema.json` - `https://commandlayer.org/schemas/v1.1.0/commercial//.receipt.schema.json` -The older nested `schemas/v1.0.0/commercial//{requests,receipts}/...` structure is historical only. +The older nested `schemas/v1.0.0/commercial//{requests,receipts}/...` structure is historical repository material only. ## 5. Commercial contract requirements @@ -139,7 +157,7 @@ For current commercial capability: - Commercial defines the canonical paid request and receipt contracts. - Agent Cards SHOULD point directly at the flat v1.1.0 schema URIs published by this repository. -Historical v1.0.0 path teaching MUST NOT be presented as current commercial guidance. +Historical v1.0.0 path teaching MUST NOT be presented as current commercial guidance or as part of the active shipped package surface. ## 9. Conformance @@ -149,11 +167,12 @@ A conformant release MUST satisfy all of the following: - every declared verb has valid and invalid examples for both request and receipt artifacts - every current schema path matches its `$id` - `manifest.json` and `schemas/v1.1.0/index.json` agree on the current verb set and path inventory +- the package `files` field matches the canonical published package boundary exactly - `npm test` passes as the current-line validation aggregate - `npm run validate:schemas` passes - `npm run validate:examples` passes - `npm run validate:integrity` passes -- `sha256sum -c checksums.txt` passes for the checksum-covered machine-artifact set -- repository metadata does not drift from the published current line +- `sha256sum -c checksums.txt` passes for the checksum-covered published payload +- repository metadata does not drift from the active current line The canonical command list lives in `README.md#validation-commands`. diff --git a/checksums.txt b/checksums.txt index f25b602..8b78ab7 100644 --- a/checksums.txt +++ b/checksums.txt @@ -1,3 +1,5 @@ +c43ff17a819f42e67cc2ee01a6356ea1c6d3917d498b2fc1930a42e80075e48c LICENSE +ef319b2e98654582ad6a09a87482deb6c5ef722385357890e835242e2081093b README.md 930cbbb3992d01385c1e5a64a4a04de5bac7c68a8b59a25a6c0e5507a1cea33f examples/v1.1.0/commercial/authorize/invalid/001-authorize.request.invalid.json ef1e7e77e6c53ef918053918a1b9243505fef02a61b4899868cad36feebe42f3 examples/v1.1.0/commercial/authorize/invalid/900-authorize.receipt.invalid.json afbcee85906d0249ed0c60eecf40657832549ca8032a99154dd0e643b6d82884 examples/v1.1.0/commercial/authorize/valid/001-authorize.request.valid.json @@ -28,7 +30,8 @@ a2a5e61fa04e12786a848e03bbabbc3f9d066ca55a6f48cb1ae1140f6373bf94 examples/v1.1. 9492d90ea14ad35eeb8acd03248ce6061ccdc04a7aff4ed538d8c42be3abc015 examples/v1.1.0/commercial/verify/valid/002-verify.request.valid.json 50874f3eea69a51ac132873b05e39318e4c2241078ca5e258e466934935ec945 examples/v1.1.0/commercial/verify/valid/900-verify.receipt.valid.json 455d19ad1b7ef98e436d8f1c675fee7f2716eb17d301da8d2cc4e2e2c51e624a examples/v1.1.0/commercial/verify/valid/901-verify.receipt.valid.json -a2d3d327da30d33a96e9bc2fa9ccbc3689963c920c136df0e4ba452a7e7284da manifest.json +6b0461ac0138c9ba356cbe99ccfaa8c904296c41b6fe26808aef5bac44b29478 index.js +2a906522b85debe988ec618f7d097e491976193d3b132df408b64cde1bbd06e7 manifest.json 4d1178e63f6c5a9e1e4d9cc4d386fbad023dd5a85c000ff193285b1fed9af243 schemas/v1.1.0/commercial/authorize/authorize.receipt.schema.json ef5da55ba5acdd43e8d2715204938762a63819dd370ebc8dfedad014617259c3 schemas/v1.1.0/commercial/authorize/authorize.request.schema.json 66e39d85a503ec2fa096d789b5b3136a451387186fa33424c4bcb07ce9aea49b schemas/v1.1.0/commercial/checkout/checkout.receipt.schema.json diff --git a/index.js b/index.js new file mode 100644 index 0000000..c73e059 --- /dev/null +++ b/index.js @@ -0,0 +1,4 @@ +import commercialIndex from "./schemas/v1.1.0/index.json" with { type: "json" }; + +export default commercialIndex; +export { commercialIndex }; diff --git a/manifest.json b/manifest.json index 0bdf25c..89b94ff 100644 --- a/manifest.json +++ b/manifest.json @@ -20,7 +20,7 @@ "legacy_versions": [ { "version": "1.0.0", - "status": "published-legacy", + "status": "historical-repo-only", "schemas_root": "schemas/v1.0.0", "examples_root": "examples/v1.0.0" } diff --git a/package.json b/package.json index ebffe32..1186754 100644 --- a/package.json +++ b/package.json @@ -40,29 +40,21 @@ "x402" ], "files": [ - "schemas/", - "examples/", - "checksums.txt", + "schemas/v1.1.0/", + "examples/v1.1.0/", "manifest.json", + "checksums.txt", + "LICENSE", "README.md", - "CHANGELOG.md", - "SPEC.md", - "POLICY.md", - "GOVERNANCE.md", - "RESOLUTION.md", - "SECURITY.md", - "SECURITY_PROVENANCE.md", - "COMPLIANCE.md", - "ONBOARDING.md", - "INTEGRATOR.md" + "index.js" ], - "main": "schemas/v1.1.0/index.json", + "main": "index.js", "exports": { - ".": "./schemas/v1.1.0/index.json", + ".": "./index.js", "./manifest.json": "./manifest.json", "./checksums.txt": "./checksums.txt", - "./schemas/*": "./schemas/*", - "./examples/*": "./examples/*" + "./schemas/v1.1.0/*": "./schemas/v1.1.0/*", + "./examples/v1.1.0/*": "./examples/v1.1.0/*" }, "scripts": { "validate:schemas": "node scripts/validate-all.mjs", diff --git a/releases/v1.1.0.md b/releases/v1.1.0.md index 24655cf..33f0c50 100644 --- a/releases/v1.1.0.md +++ b/releases/v1.1.0.md @@ -7,16 +7,20 @@ Protocol-Commercial v1.1.0 is the current canonical commercial release line for Scope of this release: - flat self-contained schemas under `schemas/v1.1.0/` +- current-line examples under `examples/v1.1.0/` +- package-root entrypoint `index.js` resolving to `schemas/v1.1.0/index.json` +- published package metadata limited to `manifest.json`, `checksums.txt`, `LICENSE`, and `README.md` - explicit actor grammar: `payer`, `payee`, `merchant`, `provider`, `carrier`, `verifier` - explicit x402 payment grammar: `payment_requirement`, `payment_session`, `payment_proof` -- retained `v1.0.0` as a published legacy line for compatibility and audit -- checksum-covered machine-artifact set for schemas, examples, and `manifest.json` +- retained `v1.0.0` as repository-only historical material for audit or migration reference ## Canonical line - Current canonical line: `v1.1.0` -- Current package entrypoint: `schemas/v1.1.0/index.json` -- Historical legacy line: `v1.0.0` +- Current package entrypoint: `index.js` → `schemas/v1.1.0/index.json` +- Current canonical schema root: `schemas/v1.1.0/` +- Current canonical example root: `examples/v1.1.0/` +- Historical repository-only line: `v1.0.0` ## What changed in v1.1.0 @@ -25,7 +29,8 @@ Scope of this release: - aligned request and receipt schema identities to exact mirror-safe public paths - normalized actor and payment grammar across authorize, checkout, purchase, ship, and verify - published current-line valid and invalid conformance examples per verb -- added checksum and integrity tooling for the machine-verifiable release payload +- narrowed the npm package surface to the active `v1.1.0` line only +- aligned checksum and integrity tooling to the shipped `v1.1.0` package payload ## Validation commands @@ -38,23 +43,38 @@ npm run validate:integrity sha256sum -c checksums.txt ``` +## Published package surface + +The canonical published package surface for v1.1.0 is: + +- `schemas/v1.1.0/` +- `examples/v1.1.0/` +- `manifest.json` +- `checksums.txt` +- `LICENSE` +- `README.md` +- `index.js` + ## Checksum scope -The checksum-covered machine-artifact set for v1.1.0 is: +The checksum-covered published payload for v1.1.0 is: - `schemas/v1.1.0/` - `examples/v1.1.0/` - `manifest.json` +- `LICENSE` +- `README.md` +- `index.js` -`checksums.txt` is the generated SHA-256 ledger for that set. It describes the payload but is not itself part of the hashed payload. +`checksums.txt` is the generated SHA-256 ledger for that payload. It describes the payload but is not itself part of the hashed payload. ## Provenance summary - canonical schema `$id` values resolve to `https://commandlayer.org/schemas/v1.1.0/...` -- `manifest.json` marks `v1.1.0` as current and `v1.0.0` as retained legacy +- `manifest.json` marks `v1.1.0` as current and `v1.0.0` as retained historical repository material - `schemas/v1.1.0/index.json` and `manifest.json` agree on verb inventory and schema paths -- integrity tooling verifies both checksum scope and repository-local file hashes before publication +- integrity tooling verifies the shipped package payload before publication ## Migration note -Use `v1.1.0` for all new integrations. Keep `v1.0.0` only for backward compatibility with already-deployed consumers that still depend on the historical nested path structure. +Use `v1.1.0` for all new integrations. Keep `v1.0.0` only as repository-local historical source material unless you are performing a deliberate legacy migration outside the shipped package surface. diff --git a/scripts/generate-checksums.mjs b/scripts/generate-checksums.mjs index 4b3e2fe..e9e4e94 100644 --- a/scripts/generate-checksums.mjs +++ b/scripts/generate-checksums.mjs @@ -8,6 +8,9 @@ const OUTPUT_PATH = path.join(ROOT_DIR, "checksums.txt"); const CURRENT_VERSION = "1.1.0"; const TARGETS = [ "manifest.json", + "LICENSE", + "README.md", + "index.js", `schemas/v${CURRENT_VERSION}`, `examples/v${CURRENT_VERSION}` ]; @@ -21,13 +24,18 @@ async function walk(targetPath) { for (const entry of entries) { const fullPath = path.join(absolute, entry.name); if (entry.isDirectory()) files.push(...(await walk(path.relative(ROOT_DIR, fullPath)))); - else if (entry.isFile() && entry.name.endsWith(".json")) files.push(fullPath); + else if (entry.isFile()) files.push(fullPath); } return files; } function isCoveredReleaseArtifact(relPath) { - return relPath === "manifest.json" + return [ + "manifest.json", + "LICENSE", + "README.md", + "index.js" + ].includes(relPath) || relPath.startsWith(`schemas/v${CURRENT_VERSION}/`) || relPath.startsWith(`examples/v${CURRENT_VERSION}/`); } @@ -52,7 +60,7 @@ async function main() { if (!isCoveredReleaseArtifact(rel)) throw new Error(`unexpected checksum target: ${rel}`); } await fs.writeFile(OUTPUT_PATH, rows.map(({ hash, rel }) => `${hash} ${rel}`).join("\n") + "\n"); - console.log(`✅ Wrote ${rows.length} current-line machine-artifact checksums to ${OUTPUT_PATH}`); + console.log(`✅ Wrote ${rows.length} canonical package-payload checksums to ${OUTPUT_PATH}`); } main().catch((error) => { diff --git a/scripts/validate-all.mjs b/scripts/validate-all.mjs index e309a61..a31d807 100644 --- a/scripts/validate-all.mjs +++ b/scripts/validate-all.mjs @@ -11,6 +11,15 @@ const CURRENT_VERSION = "1.1.0"; const SCHEMAS_ROOT = path.join(ROOT_DIR, "schemas", `v${CURRENT_VERSION}`); const EXAMPLES_ROOT = path.join(ROOT_DIR, "examples", `v${CURRENT_VERSION}`, "commercial"); const EXPECTED_VERBS = ["authorize", "checkout", "purchase", "ship", "verify"]; +const EXPECTED_PACKAGE_FILES = [ + "schemas/v1.1.0/", + "examples/v1.1.0/", + "manifest.json", + "checksums.txt", + "LICENSE", + "README.md", + "index.js" +]; const CANONICAL_DEF_NAMES = [ "actor_identity", "payer_actor", @@ -53,7 +62,6 @@ function assert(condition, message) { if (!condition) throw new Error(message); } - function expectedVerbEntry(verb) { return { verb, @@ -106,15 +114,23 @@ async function validateManifest() { assert(manifest.alignment_verification === "declarative-only", "manifest alignment verification mode drift"); assert(!("aligns_with" in manifest), "manifest aligns_with field must not imply verified enforcement"); assert(JSON.stringify(manifest.verbs.map((v) => v.verb)) === JSON.stringify(EXPECTED_VERBS), "manifest verb list drift"); + for (const legacy of manifest.legacy_versions ?? []) { + assert(legacy.status === "historical-repo-only", `legacy version ${legacy.version} must be marked historical-repo-only`); + } } async function validatePackage() { const pkg = await loadJsonStrict(path.join(ROOT_DIR, "package.json")); assert(pkg.version === CURRENT_VERSION, `package version must be ${CURRENT_VERSION}`); - assert(pkg.main === `schemas/v${CURRENT_VERSION}/index.json`, "package main drift"); - assert(pkg.exports['.'] === `./schemas/v${CURRENT_VERSION}/index.json`, "package exports current entry drift"); + assert(pkg.main === "index.js", "package main must resolve through index.js"); + assert(pkg.exports["."] === "./index.js", "package root export must resolve through index.js"); assert(pkg.publishConfig?.access === "public", "package publishConfig.access drift"); - assert(pkg.files.includes("INTEGRATOR.md"), "package files must include INTEGRATOR.md"); + assert(JSON.stringify(pkg.files) === JSON.stringify(EXPECTED_PACKAGE_FILES), "package files surface drift"); + assert(!(pkg.files.includes("schemas/") || pkg.files.includes("examples/")), "package files must not expose repo-wide schema/example roots"); + assert(!(pkg.files.includes("INTEGRATOR.md") || pkg.files.includes("SPEC.md") || pkg.files.includes("POLICY.md")), "package files must exclude non-canonical prose docs"); + assert(!("./schemas/*" in pkg.exports) && !("./examples/*" in pkg.exports), "package exports must not expose wildcard legacy roots"); + assert(pkg.exports[`./schemas/v${CURRENT_VERSION}/*`] === `./schemas/v${CURRENT_VERSION}/*`, "package schema export drift"); + assert(pkg.exports[`./examples/v${CURRENT_VERSION}/*`] === `./examples/v${CURRENT_VERSION}/*`, "package example export drift"); } async function validateSchemaTree() { @@ -205,7 +221,7 @@ async function main() { const currentSchemas = await validateSchemaTree(); await validateSchemaConsistency(currentSchemas); await validateIndex(); - console.log("✅ Current release metadata, paths, schemas, and canonical $defs validated."); + console.log("✅ Current release metadata, package boundary, paths, schemas, and canonical $defs validated."); } main().catch((error) => { diff --git a/scripts/validate-integrity.mjs b/scripts/validate-integrity.mjs index 5e53558..457e8d0 100644 --- a/scripts/validate-integrity.mjs +++ b/scripts/validate-integrity.mjs @@ -8,6 +8,9 @@ const CURRENT_VERSION = "1.1.0"; const CHECKSUMS_PATH = path.join(ROOT_DIR, "checksums.txt"); const TARGETS = [ "manifest.json", + "LICENSE", + "README.md", + "index.js", `schemas/v${CURRENT_VERSION}`, `examples/v${CURRENT_VERSION}` ]; @@ -25,7 +28,7 @@ async function walk(targetPath) { for (const entry of entries) { const fullPath = path.join(absolute, entry.name); if (entry.isDirectory()) files.push(...await walk(path.relative(ROOT_DIR, fullPath))); - else if (entry.isFile() && entry.name.endsWith(".json")) files.push(fullPath); + else if (entry.isFile()) files.push(fullPath); } return files; } @@ -64,7 +67,7 @@ async function main() { assert(actualMap.get(rel) === computed, `checksum mismatch for ${rel}`); } - console.log("✅ Release checksum scope and hashes validated."); + console.log("✅ Canonical package payload checksum scope and hashes validated."); } main().catch((error) => {