@atcn/subledger 1.4.1 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/README.md +11 -6
  2. package/dist/documents.d.ts +1067 -26
  3. package/dist/documents.js +121 -7
  4. package/dist/exceptions.d.ts +47 -2
  5. package/dist/exceptions.js +173 -3
  6. package/dist/expectations.d.ts +96 -0
  7. package/dist/expectations.js +236 -0
  8. package/dist/importing.d.ts +53 -0
  9. package/dist/importing.js +192 -0
  10. package/dist/index.d.ts +6 -0
  11. package/dist/index.js +6 -0
  12. package/dist/outcome.d.ts +36 -0
  13. package/dist/outcome.js +64 -0
  14. package/dist/presets.d.ts +36 -0
  15. package/dist/presets.js +192 -0
  16. package/dist/projection.d.ts +28 -3
  17. package/dist/projection.js +69 -4
  18. package/dist/rails.d.ts +108 -0
  19. package/dist/rails.js +242 -0
  20. package/dist/response.d.ts +2 -0
  21. package/dist/response.js +1 -0
  22. package/dist/rollup.d.ts +1 -1
  23. package/dist/rollup.js +10 -4
  24. package/dist/types.d.ts +279 -7
  25. package/dist/types.js +179 -6
  26. package/dist/usage.d.ts +41 -0
  27. package/dist/usage.js +86 -0
  28. package/dist/verify.d.ts +8 -1
  29. package/dist/verify.js +385 -7
  30. package/package.json +6 -4
  31. package/test-vectors/reconciliation-results.json +151 -0
  32. package/test-vectors/reconciliation.json +107 -0
  33. package/test-vectors/vectors.json +25666 -1
package/README.md CHANGED
@@ -1,11 +1,14 @@
1
1
  # @atcn/subledger
2
2
 
3
- The ATCN Agent Work Subledger. It records a task's delegations, delivery claims and financial events. Charges are matched to work through stable references, and an event is attributed only when exactly one task or delegation matches. The package also covers:
3
+ The cost record behind [ATCN](https://github.com/fadnisnikhil/atcn): one record per AI agent job, called a task. Most people use it through [`@atcn/sdk`](https://www.npmjs.com/package/@atcn/sdk) or [`@atcn/local-runner`](https://www.npmjs.com/package/@atcn/local-runner); use this package directly to build or verify the documents yourself.
4
4
 
5
- - exceptions for unmatched, ambiguous, duplicate, over-budget and other conditions;
6
- - roll-up totals;
7
- - signed task closures and provider receipts;
8
- - `verifySubledgerDocument`, the offline verifier for those documents.
5
+ A task holds:
6
+
7
+ - **delegations:** pieces of the job handed to other agents or paid APIs;
8
+ - **delivery claims:** what each provider says happened, optionally signed by the provider;
9
+ - **financial events:** charges, fees, refunds, payments, estimates and holds.
10
+
11
+ Charges are matched to work through stable references (such as the provider's job id), and a charge is attributed only when exactly one task or delegation matches. Anything that doesn't add up becomes an **exception**: an unmatched or duplicate charge, billing after a cancellation, cost over budget or over the estimate, and more. The package also computes the totals, signs task closures and provider receipts, and verifies them offline.
9
12
 
10
13
  ```bash
11
14
  npm install @atcn/subledger
@@ -19,4 +22,6 @@ if (report.unsupported_schema_version) console.log("upgrade the verifier");
19
22
  console.log(report.valid);
20
23
  ```
21
24
 
22
- Supported subledger schema versions are `1.2` and `1.3`; see [COMPATIBILITY.md](../schema/COMPATIBILITY.md). Part of [ATCN](../../README.md). Apache-2.0.
25
+ The verifier recomputes the totals, the estimate-against-actual report and the open exceptions from the records in the document, so an issuer cannot quietly drop an inconvenient one.
26
+
27
+ Supported subledger schema versions are `1.2` to `1.5`; see [compatibility](https://github.com/fadnisnikhil/atcn/blob/main/packages/schema/COMPATIBILITY.md). Part of [ATCN](https://github.com/fadnisnikhil/atcn). Apache-2.0.