provared 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## 0.5.0 (17 October 2026)
+
+- **The README's count of review rounds: 50.** The 40 recorded by
+  version 0.4.0, and 10 since: five of the Agno package, three of the
+  signer interface and two of the stub bound to the platform's own
+  record, each listed below.
+- **`provared-agno` 0.1.0, an Agno tool hook**
+  (`python/integrations/provared-agno/`): every tool call of an Agno
+  agent is checked against the slip before it runs, and a stub is
+  written once it has run. A call the slip does not allow is not run, and
+  the model is told why. Agno's own steering tools cannot carry an action
+  past the record: a hand-over, or a task in a team's task mode, goes
+  only to a member with the same writer's hooks, read from Agno's own
+  list of tasks, not from the session's copy that the model can rewrite.
+  A stub is written only once its tool has completed, even where a
+  helper agent runs inside the tool, on the same event loop or on one of
+  its own; a tool that never completes leaves none, and a cancelled tool
+  that completes all the same is recorded. Checked by an independent reviewer
+  over five rounds (faults found in the first four, the fifth clean);
+  each fault is a test, 68 in all. Not on the Python Package Index yet:
+  the README gives the command to install it from this repository.
+- **Signers: keys held elsewhere, in both languages.** Wherever a writer
+  takes `privateKeys` (`private_keys` in Python), each item may be a key,
+  as before, or a signer: an object with `key`, the public key, and
+  `sign(data)`, which gives the signature bytes. So a key may live in a
+  key service or a hardware module. `signerFromKey` (`signer_from_key`)
+  wraps a key held in memory as a signer. A record made through a signer
+  is the same record: the same content, labels and Ed25519 signature. A
+  signer is not taken on trust: before any signer is asked to sign, its
+  key must be plain data, of the method of its place, of a method the
+  device can check, and, where the writer knows it, the key the record
+  must be signed with (`bad-key`); every signature it gives is checked
+  against its key before it is used, and one of the wrong length, one
+  that does not check, something other than bytes or an error leaves no
+  record (`signature-invalid`), with the method and the key named. The
+  stub writer gives a signer 30 seconds for each signature (`signWithin`,
+  `sign_within`); after that nothing is written and the writer goes on.
+  In Python no seal is written, with keys or signers, as before. Every
+  private key that made a correct record before still does, in the same
+  way: in JavaScript a private Web Crypto key of the place's method for
+  Ed25519 and ML-DSA-87, and for a seal's SLH-DSA-SHA2-256s a Node.js
+  KeyObject or what Node.js's own signing call read before (PEM text,
+  DER bytes with their format, a JSON Web Key with its format); in Python
+  a private key of `cryptography` of the place's method. Refused now
+  (`bad-field`), though accepted before: in JavaScript, a private key of
+  another kind in a seal's SLH-DSA place, and in Python a private key of
+  another method or kind (such as Ed448 in the Ed25519 place); each made
+  a record that failed its own check. In Python, an object with only
+  `sign` now needs `key` as well: it is a signer. Anything else that is
+  neither a key nor a signer (a public key, a key of another method in
+  JavaScript's first two places, a value that only looks like a key) is
+  refused with `bad-field`, where before it failed with the platform's
+  own error. No record and no rule of the format changes. `signWithin`
+  must be 1 to 2,147,483,647 milliseconds (`bad-field`). Checked by an
+  independent reviewer over three rounds, the third clean; each fault is
+  fixed and is now a test.
+  Tests: `test/signers.test.mjs`, `test/signers-unavailable.test.mjs` and
+  `python/tests/test_signers.py`.
+- **A stub bound to the platform's own record of the call, in both
+  languages** (format description, section 27). Document names that
+  begin `provared.` are now reserved: seven are listed
+  (`provared.arguments`, `provared.http-request`,
+  `provared.http-response`, `provared.trace-id`, `provared.request-id`,
+  `provared.event-id`, `provared.error`), each with the exact text its
+  fingerprint is made from, so that someone who holds another system's
+  own log can match a stub to it. Only the three identifiers
+  (`trace-id`, `request-id`, `event-id`) pick out one call; the others
+  show only that the content matches, and the request and answer
+  fingerprints cover no header. Any other name that begins `provared.`
+  is refused (`bad-field`) in a stub, an approval and the check before
+  acting; before, it was a label. So is any of the seven but the three
+  identifiers named twice in one record. **A book written before this
+  change that holds a stub, or an approval, with such a name now fails
+  its check, and the check before acting then refuses every action
+  under it** (and a stub writer will not open on it). A checker of
+  version 0.4.0 or earlier reads the reserved names as labels.
+  `DOCUMENT_NAMES`,
+  `httpRequestFingerprint`, `httpResponseFingerprint` and
+  `identifierFingerprint` (`http_request_fingerprint` and so on in
+  Python) make the fingerprints; an HTTP request or answer is written as
+  the signature base of RFC 9421, with the Content-Digest of RFC 9530
+  over the body after any content coding, and its address is taken
+  exactly as sent; a body of null (None) is no body. The stub writer's `act`
+  takes `detailsAfter` (`details_after` in Python): up to four further
+  documents, from what the action gave back, such as the identifier a
+  platform gave the call. The stub is still checked with the whole book
+  before the action; after it, the stub is signed again with them in the
+  same call, and keeps the time the action began. If they cannot go in,
+  the stub is written without them and `detailsAfter` in the answer says
+  why: an action that was taken always gets its stub (where the second
+  signing fails, it says so: `details-not-added`). It cannot be used
+  with an approval. With it, the request may name at most 28 documents
+  (`bad-field`), and an action whose stub would leave no room for four
+  more is not taken (`too-large`); `detailsAfter` is given as long as the
+  other side is given to countersign. `recordTools` and `record_function` still name the
+  arguments `arguments` by default. Shared test files: `stub-contents.json`
+  gains cases (made again; its earlier cases are unchanged), and
+  `http-fingerprints.json` and `recorder-details-after.json` are new.
+  Checked by an independent reviewer in two rounds, the second clean.
+  Tests: `test/documents.test.mjs` and `python/tests/test_documents.py`.
+
 ## 0.4.0 (14 October 2026)
 
 - **The command-line checker counts the keys it was given.** With two

package/README.md

@@ -156,9 +156,9 @@ each part protects against, is in
 
 ## Status
 
-**Version 0.4.0, a draft.** Published as it is, by one author in their
+**Version 0.5.0, a draft.** Published as it is, by one author in their
 own time, built with AI tools since 3 October 2026; fixes as time
-allows. The code has been through 40 rounds of review by AI reviewers,
+allows. The code has been through 50 rounds of review by AI reviewers,
 each reviewer a fresh session given the code, the documents and a brief
 of what to look at; every fault was fixed, or stated as a limit, and
 kept as a test. No person other than the author has reviewed it yet.

package/docs/guide.md

@@ -6,7 +6,7 @@ Everything about the format, the library, the checker, the stub writer beside an
 
 ## Status
 
-**Version 0.4.0, a draft.** Published as it is, by one author in their
+**Version 0.5.0, a draft.** Published as it is, by one author in their
 own time; fixes as time allows. The format may still change, so do not
 rely on a draft record staying checkable.
 
@@ -151,9 +151,9 @@ be loaded from anywhere. The tool prints the file's SHA-256 fingerprint,
 so that a copy can be compared with it. (Tried on 8 October 2026 in the
 three browser builds this repository is tested with, and on 13 October
 2026 in Chrome 155, Edge 155 and Brave 155.) The file for
-version 0.4.0 is attached to the release on GitHub. Its SHA-256
+version 0.5.0 is attached to the release on GitHub. Its SHA-256
 fingerprint is
-`49da6617ff493ddda2b2b65bfb6bedebdf8cf07ea6faa32b039f065eda207307`.
+`cec1b8d5e6e7a11c00478c6e83d9f9b5963340ec656657ea0ac84f32e8e52bda`.
 
 **Run the demonstration in a browser.**
 
@@ -551,6 +551,77 @@ not a promise. The numbers `0` and `-0` share a fingerprint, as RFC
 though the tool has run and its stub is in the book. `recordTools`
 names no agent software, and works with any function.
 
+### Binding a stub to the platform's own record
+
+Where the other side will not countersign, a stub can still be matched
+with the other system's own log of the call: name, among its documents,
+the fingerprint of an identifier that both records hold. Document names
+that begin `provared.` are reserved for this (format description,
+section 27); any other such name is refused.
+
+| Name | The fingerprint of | Made with |
+|---|---|---|
+| `provared.arguments` | The call's arguments, in the one form of RFC 8785 | `argumentsFingerprint` |
+| `provared.http-request` | The request: its method, its address exactly as sent, and its body where it has one; no header | `httpRequestFingerprint` |
+| `provared.http-response` | The answer: its status code, and its body where it has one; no header | `httpResponseFingerprint` |
+| `provared.trace-id` | The trace-id of the W3C Trace Context `traceparent` header the agent's side sent (its form is not checked) | `identifierFingerprint` |
+| `provared.request-id` | An identifier the agent's side chose and sent with the call | `identifierFingerprint` |
+| `provared.event-id` | An identifier the platform gave for the call | `identifierFingerprint` |
+| `provared.error` | The error text the agent's software was given | `identifierFingerprint` |
+
+`DOCUMENT_NAMES` lists them, each with the exact text it stands for. An
+HTTP request or answer is written as the signature base of RFC 9421
+(nothing is signed with it): the address is taken exactly as it was
+sent, never rewritten, so give it in the form that was sent. A body is
+the bytes RFC 9530 digests: after any content coding (such as gzip),
+before any transfer coding; a body of `null` is no body. The three
+identifiers may be named more than once in a stub; every other reserved
+name once at most. A trace-id is fingerprinted as given: its form (32
+lower-case hexadecimal characters in the W3C standard) is not checked.
+
+An identifier that the platform gives only in its answer cannot be in a
+stub signed before the action. `act` takes `detailsAfter` for it:
+
+```js
+import { identifierFingerprint } from 'provared';
+
+const outcome = await recorder.act(
+  { action: 'provared.data.change', with: 'tickets' },
+  async () => updateTheTicket(),               // gives the platform's answer
+  { detailsAfter: async (answer) => [{ name: 'provared.event-id', sha256: await identifierFingerprint(answer.requestId) }] },
+);
+outcome.detailsAfter;   // { added: 1, problem: null }
+```
+
+The stub is still written and checked with the whole book before the
+action, so it is known to fit. After the action it is signed again with
+up to four further documents, within the same call, so that no other
+call comes between; it keeps the time the action began. If
+`detailsAfter` fails, gives no answer in the time the other side is
+given to countersign (`countersignWithin`), gives more than four
+documents, or gives one that would be refused, the stub is written
+without them, and `outcome.detailsAfter.problem` says why: an action
+that was taken always gets its stub. The request may then name at most
+28 documents of its own, and no approval may be given, because an
+approval covers exactly the documents the person saw. `detailsAfter`
+must not call the writer.
+
+A matching identifier shows that the two records speak of one call, not
+that the call did what either says: the platform's identifier is the
+platform's word. It binds the two only where the platform writes the
+same identifier into its own log; which one a platform keeps is for you
+to find out, so record both one you sent and one you were given where
+you can. Only an identifier picks out one call: a fingerprint of a
+request, an answer, the arguments or an error shows only that the
+content matches, since identical requests, and identical answers (many a
+`200` with the body `{}`), share one fingerprint. A platform that logs
+the decoded body of a compressed message will not match the body's
+fingerprint. An identifier that is short or easy to guess can be guessed
+from its fingerprint.
+
+`recordTools` still names the arguments `arguments` by default; a tool
+can name them `provared.arguments` through its own `details` function.
+
 ## How signing works
 
 - **The person** signs a slip with a passkey. A passkey signs a short
@@ -575,6 +646,107 @@ names no agent software, and works with any function.
   signatures were not checked, and does not show a pass. Node.js checks
   all of them.
 
+### Keys held elsewhere: signers
+
+The keys of an agent, a service, an organisation or a recorder need not
+sit in the memory of the program that writes the records. Wherever a
+writer takes `privateKeys` (`openRecorder`, `writeStub`, `countersign`,
+`writeRefusal`, `writeTerms`, `writePass`, `writeAcknowledgement`,
+`writeVouching`, `writeWithdrawal` and `writeSeal`), each item may be a
+key, as before, or a **signer**: an object with two members.
+
+- `key`: the public key, as a JSON Web Key in one of the shapes the
+  format allows (format description, section 3.8).
+- `sign(data)`: a promise of the signature over exactly those bytes, as a
+  `Uint8Array` or an `ArrayBuffer`.
+
+A signer lets a key live in a key service or a hardware module. Keys and
+signers may be mixed: an agent may keep its ML-DSA-87 key in a key
+service and its Ed25519 key elsewhere. `signerFromKey(alg, privateKey,
+key)` wraps a key held in memory as a signer, so that both take one path.
+
+```js
+import { openRecorder, signerFromKey } from 'provared';
+
+// "keyService.sign" stands for the service's own call. It must sign the
+// bytes themselves, not a fingerprint of them.
+const held = {
+  key: agentKeys[1],                       // the agent's ML-DSA-87 public key, as the slip names it
+  sign: (data) => keyService.sign('agent-ml-dsa-87', data),
+};
+const recorder = await openRecorder({
+  book, slip, issuerKeys,
+  privateKeys: [signerFromKey('Ed25519', ed25519PrivateKey, agentKeys[0]), held],
+  signWithin: 10000,                       // milliseconds for each signature; 30,000 by default
+});
+```
+
+A record made through a signer is the same record as one made with the
+key itself: the same content, the same labels and the same Ed25519
+signature. ML-DSA-87 and SLH-DSA signatures are made afresh each time,
+with a key or through a signer, so those differ between any two
+signings, as they always did.
+
+A signer is not taken on trust:
+
+- Its two members are read once. Its key must be exactly a key of the
+  method of its place in the list, as plain data.
+- A signer for a method this device does not have built in is refused
+  before any signer is asked to sign, since its signatures could not be
+  checked here.
+- Where the writer knows the key the record must be signed with, the
+  signer's key must be that key: the agent's keys as the slip names them,
+  or a helper's as its pass names them, in the stub writer; the keys
+  `by` names in `writeSeal`, `writeRefusal`, `writeTerms` and
+  `writeVouching`. A signer for another key is refused (`bad-key`)
+  before any signer is asked to sign. This catches the most likely
+  fault of a key held elsewhere: a mistyped key name in its settings.
+  The stub writer compares when it is opened, with the slip, or the
+  pass it acts under, as its book holds it. Opened with a pass that its
+  book does not yet hold, it compares nothing then, and refuses each
+  action (`pass-missing`), as it always did.
+- `writeStub`, `countersign`, `writePass`, `writeAcknowledgement` and
+  `writeWithdrawal`, used by themselves, cannot know which key the
+  record must be signed with. There a signer for another key gives a
+  record that fails its own check, as a wrong key in memory always did.
+- Every signature it gives is checked against its key before it is
+  used. A signature of the wrong length, one that does not check
+  (another key used, or other bytes signed, such as a fingerprint of
+  them), something other than bytes, or a `sign` that throws: no record
+  is made (`signature-invalid`), nothing is written to a book, and the
+  error names the place in the list, the method and the key's
+  thumbprint.
+- In the stub writer, a signer is given `signWithin` milliseconds for
+  each signature (30,000 by default). After that the action is not
+  taken, nothing is written, the writer goes on to its next call, and a
+  late answer is not used. A signer that calls the writer is refused at
+  once, as an action that does so is. The other writers set no time of
+  their own: a signer that never answers leaves the call waiting, so give
+  the signer's own connection a time limit.
+
+Where no record is made, signers earlier in the list may already have
+signed, and a signer that ran out of time may still sign later. So a key
+service's own log may hold signatures that match no record.
+
+A key given as before is used exactly as before: a private Web Crypto
+`CryptoKey` of the method of its place and, in a seal's SLH-DSA place, a
+private Node.js `KeyObject`, or what Node.js reads as one (PEM text, DER
+bytes with their format, or a JSON Web Key with its format). Anything
+else that is not a signer (a public key, a key of another method or
+kind, a value that only looks like a key) is refused (`bad-field`).
+
+What a signer does not change:
+
+- **The library cannot know how a key held elsewhere is kept**, who else
+  can ask for signatures with it, or whether the service keeps it safe.
+  It checks only that each signature fits the key the signer names.
+- **A record does not say where a key was kept.** A record signed
+  through a key service reads the same as one signed with a key in
+  memory, and a key set split between two places reads as one agent.
+- **Each signature costs one more check.** Measured on one computer on
+  15 October 2026: about 0.3 thousandths of a second for Ed25519, 0.6
+  for ML-DSA-87 and 2 for SLH-DSA-SHA2-256s.
+
 ## Using the library
 
 ```js
@@ -706,6 +878,10 @@ prepared, then `assembleSlip`; keep the disclosures it prepared.
 - A name in a record is a label. Only keys are checked. A vouching
   record shows which organisation stood behind a name, not how well it
   checked.
+- An identifier of another system's, named in a stub, shows that the
+  two records speak of one call, not that the call did what either
+  says. A fingerprint of a request, an answer, the arguments or an error
+  shows only that the content matches, not that it was the same call.
 
 And about time:
 

package/docs/threat-model.md

@@ -123,6 +123,60 @@ fingerprint.
 - The documents themselves. A stub holds fingerprints of documents, not
   the documents. Whoever keeps the documents must keep them.
 
+**A stub bound to the other system's own record of the call.** Where the
+other side will not countersign, a stub may name, under a reserved name
+(format description, section 27), the fingerprint of the identifier the
+platform gave the call (`provared.event-id`), of one the agent's side
+chose and sent (`provared.trace-id`, `provared.request-id`), of part
+of the request and the answer (`provared.http-request`: the method, the
+address and the body; `provared.http-response`: the status and the
+body; no header is covered), or of the error the agent was given
+(`provared.error`).
+
+- *What it shows.* Someone who holds the platform's own log can work the
+  fingerprint out again and match the two records, without either
+  side's help. For an identifier, the two speak of one call. An agent's
+  side that later claims another identifier for the call, or a platform
+  that later shows another, is caught by the mismatch.
+- *Only an identifier picks out one call.* A request, an answer, the
+  arguments or an error shows only that the content matches: identical
+  requests, and identical answers (many a `200` with the body `{}`),
+  share one fingerprint, so a match with one of them does not show that
+  it was the same call. Only `provared.trace-id`, `provared.request-id`
+  and `provared.event-id` are meant to pick out one call, and only they
+  may be named more than once in a stub.
+- *The body's bytes* are what RFC 9530 digests: the content after any
+  content coding (such as gzip) and before any transfer coding. A
+  platform that logs the decoded body of a message sent compressed will
+  not match.
+- *A trace-id's form is not checked.* The W3C standard writes it as 32
+  lower-case hexadecimal characters, but any text is fingerprinted as
+  given.
+- *What it does not show.* That the call did what either record says:
+  the platform's identifier is the platform's word, and the stub is
+  still the agent's side's word. That the platform keeps the identifier
+  at all: which one a platform writes into its log differs from one
+  platform to another, and is for whoever relies on it to find out. That
+  the fingerprint was made from the text the name says: a checker cannot
+  tell; only someone who holds that text can. An identifier that is
+  short or easy to guess gives no privacy through its fingerprint.
+- *Against A1 and A3* (the agent's own side). The binding is written by
+  the agent's side, so a dishonest one can leave it out, or name a
+  wrong identifier; only the match with the platform's log, made later,
+  catches the second. It adds nothing against an agent that writes no
+  stub.
+- *Two spellings of one address.* An HTTP address is taken exactly as it
+  was sent and never rewritten, so that two programs fingerprint the
+  same request the same way. A program that records a rewritten address
+  (`%2f` for `%2F`, a host in capitals) makes a fingerprint that will not
+  match: whoever writes the stub must give the address as sent.
+- *A reserved name not on the list* is refused (`bad-field`), so that a
+  name that may be given a meaning later cannot be used now with another;
+  so is one of the four once-only names named twice (two `provared.arguments`
+  fingerprints in one stub would leave unclear which was the call's). A
+  book written before this rule that holds such a name no longer passes
+  its check.
+
 ## 4a. Limits, conditions, approvals and the other side's records
 
 **Protects.** That what the person allowed is stated exactly, and that a
@@ -235,6 +289,25 @@ disagree about. Totals are added as whole numbers of any size.
   of the arguments fixes what was asked for without holding it; where
   the arguments are few and easy to guess, the fingerprint can be
   guessed.
+- **Documents named after the action** (`detailsAfter` in the stub
+  writer's `act`). The stub is first written and checked with the whole
+  book before the action, as always; after the action, it is signed
+  again with up to four further documents, still within the same call,
+  so that no other call comes between, and keeps the time the action
+  began. The room for them is kept beforehand: with today's limits the
+  largest stub, with 32 documents of the longest names, and a
+  countersignature still fits a line, and the writer checks this again
+  for each such call. If what `detailsAfter` gives cannot go in (it
+  fails, gives no answer within the time the other side is given to
+  countersign, gives more than four, or gives a document that would be
+  refused), the stub made before the action is written without them,
+  and the answer says why: an action that was taken always gets its
+  stub. What it gives is copied when it is read, so a later change to
+  it changes nothing. A call to the writer from inside it is refused at
+  once. It cannot be used with an approval, because an approval covers
+  exactly the documents the person saw. The stub is signed twice for
+  such an action, and only one of the two is written: a signer kept
+  elsewhere is asked once more.
 - **The check before acting refuses more in one case.** An action that
   would add to a period which a stub dated after it already overfills is
   refused, though a checker would report nothing new for it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "provared",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Proof of what an AI agent was allowed to do, and what it then did. A passkey-signed permission with limits a machine can check, a signed receipt for each action, and a free checker. Evidence, not a verdict.",
   "author": "Pavel Izmaylov",
   "license": "Apache-2.0 AND CC-BY-4.0",

package/spec/provared-format.md

@@ -440,7 +440,10 @@ checker keeps no state.
 | `pass` | For a helper agent: the pass it acts under. Optional | The fingerprint of the pass (section 25) |
 | `when` | When it was done | A time |
 
-A stub holds fingerprints of documents, never the documents.
+A stub holds fingerprints of documents, never the documents. A document
+`name` is a label chosen by whoever wrote the stub, except that names
+that begin `provared.` are reserved (section 27). The same label MAY
+appear more than once; section 27 says which reserved names may.
 
 ### 5.2 Signing and checking
 
@@ -658,6 +661,11 @@ the seal's own date (section 21.1, rule 4).
   that the organisation checked well.
 - The fingerprints of an agent's software in a slip are a statement of
   what the person approved, not proof of what ran.
+- A reserved identifier that binds a stub to another system's own
+  record of the call (section 27) shows that the two records speak of
+  one call, not that the call did what either says. A matching
+  fingerprint of a request, an answer, arguments or an error shows only
+  that the content matches, not that it was the same call.
 
 ## 14. Standards used
 
@@ -679,6 +687,8 @@ the seal's own date (section 21.1, rule 4).
 | RFC 3161; RFC 5652; RFC 5280; ITU-T X.690 | Time-stamps: the statement, its signed wrapper, the certificate, and the byte layout (DER) |
 | The OpenTimestamps proof file, version 1 (an open format; not the work of a standards body) | Block time-stamps: the steps from a fingerprint to the Merkle root of a block |
 | RFC 9901 (Selective Disclosure for JSON Web Tokens) | Covered fields |
+| RFC 9421 (HTTP Message Signatures), section 2.5, only its way of writing a message as text; RFC 9530 (Digest Fields); RFC 9110, section 5.6.2 | The texts that the reserved document names `provared.http-request` and `provared.http-response` stand for (section 27). Nothing is signed with RFC 9421 |
+| W3C Trace Context (a W3C Recommendation) | The trace-id that `provared.trace-id` stands for (section 27) |
 
 ## 15. Choices that go beyond the standards
 
@@ -735,6 +745,12 @@ is frozen.
     pass.
 18. The acknowledgement of section 26 and its label
     `vnd.provared.acknowledgement.v0+json`.
+19. The reserved document names of section 27, and the exact texts their
+    fingerprints are made from: an HTTP address taken exactly as it was
+    sent, never rewritten; a body that is present but empty given a
+    Content-Digest, and an absent body none; no header covered; SHA-256
+    only; only the three identifiers may be named more than once; the
+    form of a trace-id not checked.
 
 ## 16. The shared list: actions, kinds of action, rules of conduct
 
@@ -1718,6 +1734,112 @@ section 22. Nothing obliges an agent's side to acknowledge: a
 cancellation with no acknowledgement shows nothing about whether the
 agent's side was told.
 
+## 27. Reserved document names
+
+Where the other side of an action will not countersign, the next best
+binding is the other system's own identifier for the call, named in the
+stub by its fingerprint. An investigator who holds that system's own log
+can then work out the fingerprint again and match the two records,
+without either side's help. Only an identifier is meant to pick out one
+call. A stub may also name fingerprints of some of what was sent and
+received (the arguments; an HTTP request's method, address and body; an
+answer's status and body); those show that the content matches, not
+that it was the same call.
+
+So document names (section 5.1) that begin `provared.` are reserved. A
+document name that begins `provared.` and is not in this list MUST be
+refused (`bad-field`), in a stub, an approval (section 17) and the
+check before acting (section 20). The comparison is exact: a name in
+other letters, such as `Provared.invoice`, is a label like any other.
+`provared.trace-id`, `provared.request-id` and `provared.event-id` MAY
+each appear more than once in one stub (identifiers from two systems,
+say); every other name in the list MUST appear at most once, and a
+record that names one of them twice MUST be refused (`bad-field`), in
+the same places. The `sha256` of each is the SHA-256, in base64url, of
+exactly this text, in UTF-8:
+
+| Name | The text whose SHA-256 is given |
+|---|---|
+| `provared.arguments` | The call's arguments, written in the one form of RFC 8785 |
+| `provared.http-request` | The request, written as below, over `"@method"`, `"@target-uri"` and, where there is a body, `"content-digest"` |
+| `provared.http-response` | The answer, written as below, over `"@status"` and, where there is a body, `"content-digest"` |
+| `provared.trace-id` | The trace-id of the W3C Trace Context `traceparent` header that the agent's side sent, exactly as sent. That standard writes it as 32 lower-case hexadecimal characters; this format does not check the form, and a checker cannot |
+| `provared.request-id` | An identifier that the agent's side chose and sent with the call, exactly as sent |
+| `provared.event-id` | An identifier that the platform gave for the call, exactly as it gave it |
+| `provared.error` | The error text that the agent's software was given, exactly as given |
+
+An identifier or an error text MUST be one character or more, and
+well-formed Unicode.
+
+**How a request or an answer is written.** As the signature base of RFC
+9421 (HTTP Message Signatures), section 2.5, with no signature
+parameters. RFC 9421 is used only for this exact way of writing a
+message as text; nothing is signed with it. For each component, in the
+order given: a line `"<component>": <value>` and a line feed (0x0A);
+then the line `"@signature-params": (` with the components, each in
+double quotation marks and separated by one space, and `)`, with no line
+feed after it. The values:
+
+- `"@method"`: the method exactly as sent, a token of RFC 9110, section
+  5.6.2. Its letters are not changed, as RFC 9421, section 2.2.1, sets
+  out.
+- `"@target-uri"`: the absolute address exactly as sent. It MUST begin
+  `http://` or `https://`, hold only the visible characters of ASCII
+  (0x21 to 0x7E), and hold no fragment (`#`). It is never rewritten:
+  two spellings of one address (`%2F` and `%2f`, a host in capitals, a
+  port written or left out) give two fingerprints. Whoever writes the
+  stub MUST give the address in the form that was sent.
+- `"@status"`: the status code of the answer, a whole number from 100 to
+  599, written in digits.
+- `"content-digest"`: present only where the message has a body; a body
+  that is present and empty has one. The value is the field value of RFC
+  9530 with SHA-256 only: `sha-256=:`, the SHA-256 of the body's bytes,
+  in base64 with padding (RFC 4648, section 4), and `:`. The body's
+  bytes are what RFC 9530 digests: the content after any content coding
+  (such as gzip) and before any transfer coding. A system that keeps
+  the decoded body, where the body was sent compressed, will not match.
+
+No header is covered, and nothing else of the message: two messages
+that differ only in their headers give one fingerprint.
+
+For example, the request `POST https://example.com/foo?param=Value&Pet=dog`
+with the body `{"hello": "world"}` is written as these four lines:
+
+```
+"@method": POST
+"@target-uri": https://example.com/foo?param=Value&Pet=dog
+"content-digest": sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
+"@signature-params": ("@method" "@target-uri" "content-digest")
+```
+
+**What a binding shows, and what it does not.**
+
+- An identifier binds the two records only where the other system writes
+  the same identifier into its own log. Which one a system keeps differs
+  from one system to another, and is for whoever relies on it to find
+  out. Recording both kinds, one the agent's side chose and sent
+  (`provared.trace-id`, `provared.request-id`) and one the platform gave
+  back (`provared.event-id`), gives the better chance of a match.
+- The platform's identifier is the platform's word. A matching
+  identifier shows that the two records speak of one call, not that the
+  call did what either says.
+- Only `provared.trace-id`, `provared.request-id` and `provared.event-id`
+  are meant to pick out one call. `provared.arguments`,
+  `provared.http-request`, `provared.http-response` and `provared.error`
+  show only that the content matches: identical requests, and identical
+  answers (many a `200` with the body `{}`), share one fingerprint, so a
+  match with one of them does not show that it was the same call.
+- A fingerprint of an identifier, or of arguments, that is short or easy
+  to guess can be guessed: it hides nothing from someone who can try
+  the likely values.
+- A checker cannot see whether a fingerprint was made from the text this
+  section names: only someone who holds that text can work it out again.
+- Records written before this section was added may use names that
+  begin `provared.` that are not in the list, or name one of the four
+  once-only names twice; such records are refused, so a book that holds
+  one no longer passes its check. A checker that does not know this
+  section reads a reserved name as a label.
+
 ---
 
 Copyright 2026 Pavel Izmaylov. This document is licensed under the

package/src/dev.d.ts

@@ -50,5 +50,5 @@ export function developmentSlip(fields: DevelopmentSlipFields): Promise<Developm
 /** The stub writer opened under a development slip, in one call. */
 export function developmentRecorder(
   fields: DevelopmentSlipFields,
-  more?: { options?: CheckOptions; now?: () => number; countersignWithin?: number },
+  more?: { options?: CheckOptions; now?: () => number; countersignWithin?: number; signWithin?: number },
 ): Promise<Omit<DevelopmentSlip, 'book'> & { recorder: Recorder }>;

package/src/dev.js

@@ -110,7 +110,7 @@ export async function developmentSlip(fields = {}) {
  * The stub writer, opened under a development slip, in one call: the
  * shortest way to a first record. The same as developmentSlip followed by
  * openRecorder; "more" is passed to openRecorder (options, now,
- * countersignWithin).
+ * countersignWithin, signWithin).
  *
  * @param {object} fields the members of the slip; "actions" is required
  * @param {object} [more]