Publish evidence: quickstart, source bindings and atomic batches
This page is generated from the application (scripts/gen_evidence_docs.py): the programs, the tables and the error codes below are the ones the product serves. In the product, step 5 of the refund setup shows the…
Last changed Markdown versionllms.txt
This page is generated from the application (scripts/gen_evidence_docs.py): the programs, the tables and the error
codes below are the ones the product serves. In the product, step 5 of the refund setup shows the same programs with
your workspace's own source ids.
CommitLayer verifies what an agent did against records the agent cannot write. Two processes take part, each with its own key:
- the recorder runs in the agent's runtime and records what the agent is about to do (
POST /v1/actions); - the evidence publisher runs in your backend and publishes what your systems of record say happened
(
POST /v1/evidence/batches).
Quickstart
- In the product, choose the refund workflow, name the system behind each role and confirm the contract.
- Create the two keys and download their environment files. Each file holds one key and is read by one process.
- Attest each source your backend sends (Owner or Admin, signed in). Until then its records are stored as agent-reported and cannot satisfy the contract.
- Run the recorder program with the order and the amount.
- Run the evidence program with the same order and amount. It checks the batch, then publishes it whole.
The two environment files, as the product serves them. The key line is empty; the browser fills it with the key it just created and sends it nowhere.
commitlayer-recorder.env
# CommitLayer recorder process (the agent runtime).
# Keep this file server-side. Never put the Evidence pipeline key in this process.
COMMITLAYER_API_URL=https://api.commitlayer.ai
COMMITLAYER_WORKSPACE_ID=ten_your_workspace
COMMITLAYER_CONTRACT_ID=scop_refund_order
COMMITLAYER_RECORDER_KEY=
commitlayer-evidence.env
# CommitLayer evidence process (the evidence backend).
# Keep this file server-side. Never put the Runtime recorder key in this process.
COMMITLAYER_API_URL=https://api.commitlayer.ai
COMMITLAYER_WORKSPACE_ID=ten_your_workspace
COMMITLAYER_CONTRACT_ID=scop_refund_order
COMMITLAYER_EVIDENCE_KEY=
Every program takes ORDER_ID AMOUNT and does nothing without them: it prints its usage and exits 2. A program for
a real integration carries no sample order and no sample amount; sample values belong to the workspace sample.
| Language | Install | Record | Publish evidence | Checkpoints alone |
|---|---|---|---|---|
| Python | pip install -r requirements.txt |
python record_refund.py ORDER_ID AMOUNT |
python publish_evidence.py ORDER_ID AMOUNT |
python publish_evidence.py --checkpoint-only |
| TypeScript | npm install |
npm run record -- ORDER_ID AMOUNT |
npm run evidence -- ORDER_ID AMOUNT |
npm run evidence -- --checkpoint-only |
| REST | needs bash and curl | bash record-action.sh ORDER_ID AMOUNT |
bash publish-evidence.sh ORDER_ID AMOUNT |
bash publish-evidence.sh --checkpoint-only |
The programs pin commitlayer==0.1.5 (PyPI) and commitlayer@0.1.6 (npm), the published versions they are
certified on (scripts/certify_quickstart.py runs these exact files in two workspaces before every release).
Publish what your systems actually have
Run with an order and an amount, an evidence program publishes every record of the refund once; running it again
for the same order is the same records, and stores nothing twice. A real backend does not always have every
record. After ORDER_ID AMOUNT the three programs take the same two options:
| Option | What it publishes |
|---|---|
--reported SOURCE[,SOURCE] |
Only the records those sources have for the order. The source ids are your workspace's own (here: stripe, shopify, zendesk). A source with no record yet is left out, and its checkpoint is still sent: that is how a missing record settles FAIL at the deadline. |
--reported SOURCE --record-id ID |
One more record of that source, under the source's own id for it. A second refund on the same order is a second record, with its own reference, never a replay of the first. |
--checkpoint-only |
The checkpoints alone, after a scan that found nothing new. |
A source id the program has no record for, or --record-id without exactly one source, is
refused with the usage (exit 2) before anything is sent. Every run is still one preflight and one atomic batch.
The product shows the following beside the programs (the evidence publisher's page of the checklist, and
Connections, "Integration files"), with your workspace's own source ids; INSTALL.md carries the same text, and
GET /v1/onboarding/refund/quickstart serves it as situations. With Stripe, Shopify and Zendesk:
A refund that completed
The agent refunded the order and every system has its record.
- Record the action:
- Python:
python record_refund.py ORDER_ID AMOUNT - TypeScript:
npm run record -- ORDER_ID AMOUNT - REST (curl):
bash record-action.sh ORDER_ID AMOUNT
- Python:
- Publish:
- Python:
python publish_evidence.py ORDER_ID AMOUNT - TypeScript:
npm run evidence -- ORDER_ID AMOUNT - REST (curl):
bash publish-evidence.sh ORDER_ID AMOUNT
- Python:
Result: Pending until the records arrive, then PASS: every expected effect was observed.
A refund above the contract's limit
The agent refunds more than the largest refund the contract allows.
- Record the action:
- Python:
python record_refund.py ORDER_ID AMOUNT_ABOVE_THE_LIMIT - TypeScript:
npm run record -- ORDER_ID AMOUNT_ABOVE_THE_LIMIT - REST (curl):
bash record-action.sh ORDER_ID AMOUNT_ABOVE_THE_LIMIT
- Python:
- Publish:
- Python:
python publish_evidence.py ORDER_ID AMOUNT_ABOVE_THE_LIMIT - TypeScript:
npm run evidence -- ORDER_ID AMOUNT_ABOVE_THE_LIMIT - REST (curl):
bash publish-evidence.sh ORDER_ID AMOUNT_ABOVE_THE_LIMIT
- Python:
Result: FAIL at once on policy (the amount is above the limit); the outcome is judged apart, and reads PASS once the records arrive.
A system has no record: the refund never reached stripe
The agent says it refunded the order, and stripe has no refund for it. Publish what the other systems have, and keep sending checkpoints after every scan.
- Record the action:
- Python:
python record_refund.py ORDER_ID AMOUNT - TypeScript:
npm run record -- ORDER_ID AMOUNT - REST (curl):
bash record-action.sh ORDER_ID AMOUNT
- Python:
- Publish:
- Python:
python publish_evidence.py ORDER_ID AMOUNT --reported shopify,zendesk - TypeScript:
npm run evidence -- ORDER_ID AMOUNT --reported shopify,zendesk - REST (curl):
bash publish-evidence.sh ORDER_ID AMOUNT --reported shopify,zendesk
- Python:
- Publish (after every later scan):
- Python:
python publish_evidence.py --checkpoint-only - TypeScript:
npm run evidence -- --checkpoint-only - REST (curl):
bash publish-evidence.sh --checkpoint-only
- Python:
Result: Pending while the settlement window is open. Once stripe's checkpoint passes the settlement deadline with no refund, FAIL: the expected stripe refund is missing.
A second refund on the same order
stripe reports another refund for an order that was already refunded. Publish it under stripe's own id for that refund.
- Publish:
- Python:
python publish_evidence.py ORDER_ID AMOUNT --reported stripe --record-id SECOND_REFUND_ID - TypeScript:
npm run evidence -- ORDER_ID AMOUNT --reported stripe --record-id SECOND_REFUND_ID - REST (curl):
bash publish-evidence.sh ORDER_ID AMOUNT --reported stripe --record-id SECOND_REFUND_ID
- Python:
Result: The order's action is verified again by itself. A settled PASS becomes FAIL: a duplicate refund, with the earlier PASS kept in its version history.
Records for a different order
Your systems report a refund for another order than the one the agent acted on.
- Record the action:
- Python:
python record_refund.py ORDER_ID AMOUNT - TypeScript:
npm run record -- ORDER_ID AMOUNT - REST (curl):
bash record-action.sh ORDER_ID AMOUNT
- Python:
- Publish:
- Python:
python publish_evidence.py OTHER_ORDER_ID AMOUNT - TypeScript:
npm run evidence -- OTHER_ORDER_ID AMOUNT - REST (curl):
bash publish-evidence.sh OTHER_ORDER_ID AMOUNT
- Python:
- Publish (after every later scan):
- Python:
python publish_evidence.py --checkpoint-only - TypeScript:
npm run evidence -- --checkpoint-only - REST (curl):
bash publish-evidence.sh --checkpoint-only
- Python:
Result: Nothing of the other order is attributed to this action. It stays pending and, once the checkpoints pass its settlement deadline, settles FAIL: no record for its own order.
Records published before the sources are attested
The publisher runs before an Owner or Admin attested the evidence sources.
- Record the action:
- Python:
python record_refund.py ORDER_ID AMOUNT - TypeScript:
npm run record -- ORDER_ID AMOUNT - REST (curl):
bash record-action.sh ORDER_ID AMOUNT
- Python:
- Publish:
- Python:
python publish_evidence.py ORDER_ID AMOUNT - TypeScript:
npm run evidence -- ORDER_ID AMOUNT - REST (curl):
bash publish-evidence.sh ORDER_ID AMOUNT
- Python:
- Attest the evidence sources (checklist step 3, or Connections).
Result: Pending: the records are received and not yet eligible. Attesting verifies the action again by itself, and it settles PASS.
The settlement window is the contract's (one hour here). "Once the checkpoints pass the deadline" means: your
pipeline keeps running --checkpoint-only after its scans, and the first one after the deadline settles the
verdict. Nobody asks for a verification.
Source bindings
A contract names roles. The refund contract has three: the payment, the order and the support case. Your workspace binds each role to one exact source id when you name the system behind it. A provider's display name is never a source id: the id is the one your workspace's contract reads.
With Stripe, Shopify and Zendesk:
| Role | Provider | Source id | Fact types the contract reads | Identity link |
|---|---|---|---|---|
| payment | stripe | stripe |
refund, refund_failed |
payment_to_order: stripe to shopify |
| order | shopify | shopify |
order_cancelled, fulfillment_created, order_reopened |
none (the action's subject) |
| support | zendesk | zendesk |
status_change, reopen |
ticket_to_order: zendesk to shopify |
With "My backend will send it" for the order and the support case:
| Role | Provider | Source id | Fact types the contract reads | Identity link |
|---|---|---|---|---|
| payment | stripe | stripe |
refund, refund_failed |
payment_to_order: stripe to orders |
| order | backend | orders |
order_cancelled, fulfillment_created, order_reopened |
none (the action's subject) |
| support | backend | support |
status_change, reopen |
ticket_to_order: support to orders |
In the second workspace a record sent as shopify or zendesk is refused: those sources do not exist there, and
the evidence key is bound to orders, stripe, support. The support case is resolved
with the status resolved, not solved.
One record holds the bindings, and everything else is generated from it:
- the evidence key's scope (
fact_sources); - the
sourceof every fact and both ends of every identity link, in the programs and the per-source helpers; - the sources a checkpoint is sent for;
- the rows of the attestation screen, the contract's coverage and the Connections page.
Read it with GET /v1/evidence/source-bindings (any member), or from the preflight with the evidence key
(source_bindings, allowed_sources). record is null before a workflow is chosen.
{
"record": {
"contract": {
"contract_id": "scop_refund_order",
"version": 1,
"subject_kind": "order"
},
"source_ids": [
"stripe",
"orders",
"support"
],
"evidence_key": {
"scopes": [
"facts:write"
],
"fact_sources": [
"orders",
"stripe",
"support"
],
"evidence_class": "customer_backend"
},
"checkpoint_sources": [
"orders",
"stripe",
"support"
],
"links": [
{
"link_type": "payment_to_order",
"left": {
"source": "stripe",
"subject_kind": "payment"
},
"right": {
"source": "orders",
"subject_kind": "order"
}
},
{
"link_type": "ticket_to_order",
"left": {
"source": "support",
"subject_kind": "ticket"
},
"right": {
"source": "orders",
"subject_kind": "order"
}
}
],
"bindings": [
{
"role": "payment",
"provider": "stripe",
"source_id": "stripe",
"path": "facts_api",
"pushed": true,
"required": true,
"subject_kind": "payment",
"subject_match": "linked",
"fact_types": [
"refund",
"refund_failed"
],
"expected_effects": [
{
"code": "stripe.refund",
"fact_type": "refund",
"where": {}
}
],
"link": {
"link_type": "payment_to_order",
"source": "stripe",
"subject_kind": "payment",
"linked_source": "orders",
"linked_subject_kind": "order"
},
"evidence_key_scope": true,
"checkpoint": true
}
]
}
}
The same records() function in that workspace's Python program:
def records(order_id: str, amount: float, at: str, reported=None, record_id=None) -> tuple:
"""(identity links, facts) for one refunded order: every source's, or those of the sources in `reported`.
`record_id` is the source's own id of the one record published (a second refund has its own)."""
payment = f"pay-{order_id}"
ticket = f"ticket-{order_id}"
links = [
{"subject_id": payment, "source": "stripe", "linked_subject_id": order_id, "linked_source": "orders", "link_type": "payment_to_order"},
{"subject_id": ticket, "source": "support", "linked_subject_id": order_id, "linked_source": "orders", "link_type": "ticket_to_order"},
]
facts = [
{"source": "stripe", "subject_id": payment, "subject_kind": "payment", "fact_type": "refund", "occurred_at": at,
"attributes": {"amount": amount, "currency": "usd", "status": "succeeded"}, "raw_ref": f"stripe:refund:{payment}"},
{"source": "orders", "subject_id": order_id, "subject_kind": "order", "fact_type": "order_cancelled", "occurred_at": at,
"attributes": {"reason": "customer"}, "raw_ref": f"orders:order_cancelled:{order_id}"},
{"source": "support", "subject_id": ticket, "subject_kind": "ticket", "fact_type": "status_change", "occurred_at": at,
"attributes": {"from": "open", "to": "resolved"}, "raw_ref": f"support:status_change:{ticket}"},
]
if reported is not None:
links = [ln for ln in links if ln["source"] in reported]
facts = [f for f in facts if f["source"] in reported]
if record_id is not None:
for f in facts:
f["raw_ref"] = f"{f['source']}:{f['fact_type']}:{record_id}"
return links, facts
def options(args: list) -> tuple:
"""(reported sources or None, record id or None) from what follows ORDER_ID AMOUNT. ValueError on anything else."""
reported, record_id = None, None
while args:
name, value = args[0], (args[1].strip() if len(args) > 1 else "")
if not value or value.startswith("-"):
raise ValueError(f"{name} needs a value")
if name == "--reported" and reported is None:
reported = [s.strip() for s in value.split(",") if s.strip()]
unknown = [s for s in reported if s not in RECORD_SOURCES]
if unknown or not reported:
raise ValueError(f"unknown source: {', '.join(unknown) or value}. This workspace's sources with records: {', '.join(RECORD_SOURCES)}")
elif name == "--record-id" and record_id is None:
record_id = value
else:
raise ValueError(f"unknown option: {name}")
args = args[2:]
if record_id is not None and (reported is None or len(reported) != 1):
raise ValueError("--record-id names one record: give its one source with --reported SOURCE")
return reported, record_id
Key scopes
| Key | Scopes | Bound to | Can | Cannot |
|---|---|---|---|---|
| Runtime recorder | actions:record, actions:read |
nothing | record an action, read its verdict | publish evidence (403 insufficient_scope) |
| Evidence pipeline | facts:write |
the binding record's pushed source ids | publish links, records and checkpoints for those sources | record an action (403), publish for any other source (403 source_not_allowed) |
The product creates the evidence key with exactly the source ids of the binding record. A source a CommitLayer connector reads is not in the key's scope, and nothing can be published for it.
Attestation
A record from an evidence key counts toward a contract only once an Owner or Admin, signed in, has attested that
key for that source (POST /v1/evidence/attestations, or the attestation dialog on the evidence step). No API key
can attest. Before the attestation the batch is still accepted: its records are stored as agent-reported and the
verdict stays pending. After it, the pending actions are re-verified with no new record needed.
Once a source is attested for a key, only that key may send its checkpoint or link its records. Another evidence
key's batch for that source is rejected whole (checkpoint_not_permitted, link_not_permitted).
The atomic evidence batch: POST /v1/evidence/batches
Scope facts:write. Answers 201.
{
"workspace_id": "ten_your_workspace",
"contract_id": "scop_refund_order",
"action_id": "refund-order-1001",
"links": [{"subject_id": "pay-order-1001", "source": "stripe", "linked_subject_id": "order-1001", "linked_source": "shopify", "link_type": "payment_to_order"}],
"facts": [{"source": "stripe", "subject_id": "pay-order-1001", "subject_kind": "payment", "fact_type": "refund", "occurred_at": "2026-11-18T10:42:09Z", "attributes": {"amount": 40.0, "currency": "usd", "status": "succeeded"}, "raw_ref": "stripe:refund:pay-order-1001"}],
"observed_through": {"stripe": "2026-11-18T10:45:00Z", "shopify": "2026-11-18T10:45:00Z", "zendesk": "2026-11-18T10:45:00Z"}
}
| Field | |
|---|---|
links |
Identity links: which payment and which ticket belong to the order. Same items as POST /v1/facts links. |
facts |
Records. Same items as POST /v1/facts facts. |
observed_through |
Source id to the time that source was scanned through: the checkpoint. A source with no record in the batch is still a valid checkpoint. |
workspace_id |
Optional. Checked against the key's workspace. |
contract_id |
Optional. When given, every record's source and type is checked against what that contract reads. |
action_id |
Optional. The action the batch is evidence for; it must exist. Evidence is matched to actions by subject and identity link either way, so a pipeline that does not know the action leaves it out. |
What the endpoint guarantees:
- The whole request is validated before anything is written.
- If any item is invalid or not permitted, the whole request is rejected. No identity link is written when a fact is unauthorized, no fact when a link is invalid, no checkpoint when the batch fails.
- Links, facts and checkpoints are committed in one transaction.
- Re-verification is queued by that same transaction, so only a committed batch queues one.
- The answer has one result per item.
A committed batch answers status: "committed", written: true, and:
| Field | |
|---|---|
links[] |
index, accepted: true, status (created or exists), link_type, source, linked_source |
facts[] |
The POST /v1/facts row, plus index, accepted: true, status (stored or duplicate), duplicate |
checkpoints[] |
source, observed_through, accepted: true, status, current_observed_through, affected_action_ids |
counts |
links, facts, facts_stored, facts_duplicate, checkpoints |
affected_actions, reverify_scheduled, snapshot_versions, reverification_jobs |
The actions the batch changes, whether their re-verification is queued, and each one's current snapshot version |
Sending the same batch again is safe: a record already stored comes back accepted with status: "duplicate", and a
link that exists comes back exists.
Checkpoint statuses:
status |
|
|---|---|
advanced |
The source's checkpoint moved to the declared time. |
unchanged |
The source's checkpoint already stood at the declared time. |
already_covered |
A later checkpoint already stands (current_observed_through), so the declared one adds nothing. Not a failure. |
Preflight: POST /v1/evidence/batches/preflight
Scope facts:write. Takes the same body and writes nothing. It runs the checks workspace, contract, key_scopes, sources, fact_types, identity_links, checkpoint_permissions exactly as the batch
endpoint does before it writes, and answers 200:
{"ok": true, "written": false, "workspace_id": "ten_your_workspace",
"contract": {"contract_id": "scop_refund_order", "version": 1, "status": "active"},
"key": {"id": "key_...", "scopes": ["facts:write"], "fact_sources": ["shopify", "stripe", "zendesk"]},
"allowed_sources": ["shopify", "stripe", "zendesk"],
"checks": [{"check": "workspace", "ok": true, "errors": 0}],
"received": {"links": 2, "facts": 3, "checkpoints": 3},
"source_bindings": [], "checkpoint_sources": ["shopify", "stripe", "zendesk"]}
An empty body checks the key, the workspace and the contract alone, and is how a program reads the source ids it
may publish for. A batch that would be rejected answers with the same structured error as the batch endpoint, with
the code preflight_failed. The batch endpoint validates again by itself: the preflight is a convenience, never a
permission.
Source checkpoints
A checkpoint says "this source was scanned through this time". It is what lets a verdict settle: with a current checkpoint for every source, an expected effect that never happened settles FAIL at the deadline. Without one, CommitLayer can evaluate the records it has, but it cannot tell a missing record from a late one.
- Send
observed_throughfor every source you scanned, in every batch, including a source with nothing new. - After a scan that found nothing at all, send the checkpoints alone (
--checkpoint-onlyin the programs). - A checkpoint only moves forward. An older one is
already_covered, not an error. - Only the key a source is attested for may send its checkpoint.
The generated programs and the per-source helpers send a checkpoint with every batch.
Error messages
A rejected batch answers batch_rejected (the preflight: preflight_failed). The status is 403 when a permission
is among the reasons, else 422. details holds everything a program has to print:
{
"error": {
"code": "batch_rejected",
"message": "Nothing was written: 3 problems in this batch. This key may publish evidence for orders, stripe, support, not for shopify.",
"details": {
"written": false,
"reason": "source_not_allowed",
"summary": [
"invalid source: shopify, zendesk",
"allowed sources: orders, stripe, support",
"failed link 0 (payment_to_order stripe to shopify): source_not_allowed",
"failed checkpoint zendesk: source_not_allowed"
],
"errors": [
{
"kind": "fact",
"index": 1,
"code": "source_not_allowed",
"message": "This key may publish evidence for orders, stripe, support, not for shopify.",
"source": "shopify",
"allowed_sources": [
"orders",
"stripe",
"support"
],
"fact_type": "order_cancelled"
},
{
"kind": "link",
"index": 0,
"code": "source_not_allowed",
"message": "The link names shopify, which is not a source of this workspace. This key publishes for orders, stripe, support.",
"link_type": "payment_to_order",
"source": "stripe",
"linked_source": "shopify",
"allowed_sources": [
"orders",
"stripe",
"support"
],
"unknown_sources": [
"shopify"
]
},
{
"kind": "checkpoint",
"index": null,
"code": "source_not_allowed",
"message": "This key may publish evidence for orders, stripe, support, not for zendesk.",
"source": "zendesk",
"allowed_sources": [
"orders",
"stripe",
"support"
],
"observed_through": "2026-11-18T10:45:00Z"
}
],
"checks": [
{
"check": "workspace",
"ok": true,
"errors": 0
},
{
"check": "contract",
"ok": true,
"errors": 0
},
{
"check": "key_scopes",
"ok": true,
"errors": 0
},
{
"check": "sources",
"ok": false,
"errors": 1
},
{
"check": "fact_types",
"ok": true,
"errors": 0
},
{
"check": "identity_links",
"ok": false,
"errors": 1
},
{
"check": "checkpoint_permissions",
"ok": false,
"errors": 1
}
],
"invalid_sources": [
"shopify",
"zendesk"
],
"allowed_sources": [
"orders",
"stripe",
"support"
],
"invalid_fact_types": [],
"failed_links": [
{
"index": 0,
"code": "source_not_allowed",
"link_type": "payment_to_order",
"source": "stripe",
"linked_source": "shopify",
"message": "The link names shopify, which is not a source of this workspace. This key publishes for orders, stripe, support."
}
],
"failed_checkpoints": [
{
"code": "source_not_allowed",
"source": "zendesk",
"observed_through": "2026-11-18T10:45:00Z",
"message": "This key may publish evidence for orders, stripe, support, not for zendesk."
}
],
"received": {
"links": 2,
"facts": 3,
"checkpoints": 3
},
"accepted": {
"links": 0,
"facts": 0,
"checkpoints": 0
}
}
}
}
summary is the same error as lines to print: no line holds a double quote, a square bracket or a vertical bar, so
a shell script can split the list without a JSON parser. The generated programs print it, then exit 1.
errors[].code |
About | Status | Meaning | What to do |
|---|---|---|---|---|
workspace_mismatch |
request | 403 | workspace_id is not the workspace the key belongs to. |
Use the environment file that was downloaded with this key. |
unknown_contract |
request | 422 | contract_id names no contract of this workspace, or not the contract the action was recorded under. |
Send the contract id of the workspace's refund workflow (COMMITLAYER_CONTRACT_ID). |
not_an_action_contract |
request | 422 | contract_id names an outcome contract, which reads no pushed evidence. |
Send an action contract's id. |
contract_not_active |
request | 422 | The contract is a draft or was archived. | Activate the contract, then send the batch again. |
action_not_found |
request | 422 | action_id names no action recorded in this workspace. |
Record the action first, or leave action_id out: evidence is matched by subject and identity link. |
source_not_allowed |
fact, link or checkpoint | 403 | The source is outside the evidence key's scope; for a link, one end names a source the workspace never configured. | Use the workspace's configured source ids (allowed_sources), or bind the key to the source. |
source_served_by_connector |
fact or checkpoint | 422 | A CommitLayer connector reads this source, so nothing can be published for it. | Send nothing for that source. |
source_not_in_contract |
fact | 422 | The contract named in the request reads no record from this source. | Send records for the sources the contract reads, or leave contract_id out. |
fact_type_not_read |
fact | 422 | The contract named in the request reads no record of this type from this source. | Use one of allowed_fact_types. |
invalid_fact |
fact | 422 | The record does not match the record schema: a field is missing, too long or not an identifier. | Fix the field the message names. |
invalid_timestamp |
fact | 422 | occurred_at is not a time CommitLayer reads. |
Send an RFC 3339 time in UTC, such as 2026-11-18T10:42:09Z. |
future_timestamp |
fact | 422 | occurred_at is further in the future than the allowed clock skew. |
Send the time the record was made in its system. |
invalid_link |
link | 422 | The link does not match the link schema, or joins a record to itself. | Send two different ids and lowercase source names. |
link_not_permitted |
link | 403 | Neither end of the link is a source this key publishes for, or one end is attested for another key. | Send the link with the key that publishes one of its two sources. |
invalid_checkpoint |
checkpoint | 422 | The checkpoint's source is not an identifier, or its time cannot be read or is in the future. | Send observed_through as source to RFC 3339 time, no later than now. |
checkpoint_not_permitted |
checkpoint | 403 | The source is attested for another evidence key: only that key may say how far it was scanned. | Send the checkpoint with the attested key, or attest this key for the source. |
Other answers of these two routes:
| Status | Code | When |
|---|---|---|
| 400 | invalid_batch |
The batch holds no link, no fact and no checkpoint (the preflight accepts an empty body). |
| 403 | insufficient_scope |
The key has no facts:write scope: a recorder key. |
| 403 | sample_authorization_not_accepted |
The workspace sample's short-lived authorization was sent. |
| 422 | validation_error |
The body is not an object of the fields above (an unknown field, a list where an object belongs). |
What the generated programs print and exit with:
| Exit | When |
|---|---|
| 0 | Every link, record and checkpoint sent is accepted in the answer. |
| 1 | The API refused the batch (the structured error is printed), the answer does not account for every item sent, the other process's key is in this process, or there is no record to publish. |
| 2 | The order or the amount is missing or not valid: the usage is printed and nothing is sent. |
POST/v1/evidence/batch (deprecated)
The 0.9.56 route is kept, unchanged, for the client versions that call it (publish_batch in PyPI commitlayer
0.1.4, publishBatch in npm 0.1.5). It answers per item and is not atomic across a refused checkpoint: a caller has
to read every accepted. Every answer carries Deprecation: true and
Link: </v1/evidence/batches>; rel="successor-version". New code uses POST /v1/evidence/batches.
Python guide
Python 3.10 or later. Put the files in one folder with the two environment files beside them.
pip install -r requirements.txt
python record_refund.py ORDER_ID AMOUNT
python publish_evidence.py ORDER_ID AMOUNT
requirements.txt
commitlayer==0.1.5
record_refund.py
"""Record one refund action with the Runtime recorder key (CommitLayer quickstart, scop_refund_order v1).
Run: pip install -r requirements.txt
python record_refund.py ORDER_ID AMOUNT
Reads: commitlayer-recorder.env (COMMITLAYER_API_URL, COMMITLAYER_WORKSPACE_ID, COMMITLAYER_CONTRACT_ID, COMMITLAYER_RECORDER_KEY).
In your agent, call record_refund() just before the refund is issued, with the order the agent is refunding.
Both arguments are required: without them nothing is recorded.
"""
import os
import sys
import commitlayer
from commitlayer import CommitLayerError
USAGE = "Usage: python record_refund.py ORDER_ID AMOUNT (the order being refunded and the refund's amount, e.g. 40.00)"
def load_env(path: str, forbidden: str) -> None:
"""Read KEY=value lines from the environment file next to this program (no dependency needed)."""
here = os.path.join(os.path.dirname(os.path.abspath(__file__)), path)
if os.path.exists(here):
with open(here, encoding="utf-8") as f:
for raw in f:
line = raw.strip()
if line and not line.startswith("#") and "=" in line:
k, v = line.split("=", 1)
os.environ.setdefault(k.strip(), v.strip())
if os.environ.get(forbidden):
sys.exit(f"{forbidden} is set in this process. Keep the recorder and evidence keys in separate processes.")
def record_refund(order_id: str, amount: float) -> dict:
rec = commitlayer.recorder() # COMMITLAYER_RECORDER_KEY; the contract is COMMITLAYER_CONTRACT_ID
return rec.record_action(
subject_id=order_id,
subject_kind="order",
action_type="refund_order",
workflow_id="refund_order",
action_id=f"refund-{order_id}", # idempotent: recording the same refund again changes nothing
params={"amount": amount, "currency": "USD", "customer_id": f"customer-{order_id}"},
)
def arguments(argv: list) -> tuple:
"""(order id, amount), or exit 2 with the usage: no order and no amount is ever made up."""
try:
order_id, amount = argv[0].strip(), float(argv[1])
if len(argv) != 2 or not order_id or order_id.startswith("-") or amount <= 0:
raise ValueError
except (IndexError, ValueError):
print(USAGE, file=sys.stderr)
sys.exit(2)
return order_id, amount
def main() -> int:
order_id, amount = arguments(sys.argv[1:])
load_env("commitlayer-recorder.env", forbidden="COMMITLAYER_EVIDENCE_KEY")
try:
out = record_refund(order_id, amount)
except CommitLayerError as e:
print(f"CommitLayer refused the action: {e.status} {e.code}: {e.message}", file=sys.stderr)
return 1
except ValueError as e:
print(f"Setup problem: {e}", file=sys.stderr)
return 1
action = out["action"]
print(f"action recorded: {action['id']} (action_id {action['action_id']}, contract {action['contract_id']})")
print(f"verification: {out['verification']['status']}")
return 0
if __name__ == "__main__":
sys.exit(main())
publish_evidence.py
"""Publish the refund's evidence as one atomic batch with the Evidence pipeline key (CommitLayer quickstart,
scop_refund_order v1).
Run: pip install -r requirements.txt
python publish_evidence.py ORDER_ID AMOUNT identity links, records and a checkpoint for every source
python publish_evidence.py ORDER_ID AMOUNT --reported SOURCE[,SOURCE]
only the records those sources have for the order (a source
with no record yet is left out; its checkpoint is still sent)
python publish_evidence.py ORDER_ID AMOUNT --reported SOURCE --record-id ID
one more record of that source under the source's own id for
it: a second refund on the same order is a second record
python publish_evidence.py --checkpoint-only the checkpoints alone: "scanned, nothing new"
Reads: commitlayer-evidence.env (COMMITLAYER_API_URL, COMMITLAYER_WORKSPACE_ID, COMMITLAYER_CONTRACT_ID, COMMITLAYER_EVIDENCE_KEY).
Source ids are this workspace's own, the evidence key's scope: shopify, stripe, zendesk.
In your backend, build these records from what your systems report for the order, and send a checkpoint for every
source you scanned, even one with nothing new: that is how a missing refund settles FAIL on time.
The batch is checked first (the preflight writes nothing) and then stored whole or not at all. This program exits
nonzero when anything is refused, and when there is no record to publish.
"""
import os
import sys
from datetime import datetime, timezone
import commitlayer
from commitlayer import CommitLayerError
USAGE = (
"Usage: python publish_evidence.py ORDER_ID AMOUNT (the refunded order and the refund's amount)\n"
" python publish_evidence.py ORDER_ID AMOUNT --reported SOURCE[,SOURCE] (only the records those sources have: stripe, shopify, zendesk)\n"
" python publish_evidence.py ORDER_ID AMOUNT --reported SOURCE --record-id ID (one more record of that source, under its own id)\n"
" python publish_evidence.py --checkpoint-only (checkpoints alone, no record)"
)
SOURCES = ["shopify", "stripe", "zendesk"] # this workspace's configured source ids
RECORD_SOURCES = ["stripe", "shopify", "zendesk"] # the sources this program has a record for
def load_env(path: str, forbidden: str) -> None:
"""Read KEY=value lines from the environment file next to this program (no dependency needed)."""
here = os.path.join(os.path.dirname(os.path.abspath(__file__)), path)
if os.path.exists(here):
with open(here, encoding="utf-8") as f:
for raw in f:
line = raw.strip()
if line and not line.startswith("#") and "=" in line:
k, v = line.split("=", 1)
os.environ.setdefault(k.strip(), v.strip())
if os.environ.get(forbidden):
sys.exit(f"{forbidden} is set in this process. Keep the recorder and evidence keys in separate processes.")
def records(order_id: str, amount: float, at: str, reported=None, record_id=None) -> tuple:
"""(identity links, facts) for one refunded order: every source's, or those of the sources in `reported`.
`record_id` is the source's own id of the one record published (a second refund has its own)."""
payment = f"pay-{order_id}"
ticket = f"ticket-{order_id}"
links = [
{"subject_id": payment, "source": "stripe", "linked_subject_id": order_id, "linked_source": "shopify", "link_type": "payment_to_order"},
{"subject_id": ticket, "source": "zendesk", "linked_subject_id": order_id, "linked_source": "shopify", "link_type": "ticket_to_order"},
]
facts = [
{"source": "stripe", "subject_id": payment, "subject_kind": "payment", "fact_type": "refund", "occurred_at": at,
"attributes": {"amount": amount, "currency": "usd", "status": "succeeded"}, "raw_ref": f"stripe:refund:{payment}"},
{"source": "shopify", "subject_id": order_id, "subject_kind": "order", "fact_type": "order_cancelled", "occurred_at": at,
"attributes": {"reason": "customer"}, "raw_ref": f"shopify:order_cancelled:{order_id}"},
{"source": "zendesk", "subject_id": ticket, "subject_kind": "ticket", "fact_type": "status_change", "occurred_at": at,
"attributes": {"from": "open", "to": "solved"}, "raw_ref": f"zendesk:status_change:{ticket}"},
]
if reported is not None:
links = [ln for ln in links if ln["source"] in reported]
facts = [f for f in facts if f["source"] in reported]
if record_id is not None:
for f in facts:
f["raw_ref"] = f"{f['source']}:{f['fact_type']}:{record_id}"
return links, facts
def options(args: list) -> tuple:
"""(reported sources or None, record id or None) from what follows ORDER_ID AMOUNT. ValueError on anything else."""
reported, record_id = None, None
while args:
name, value = args[0], (args[1].strip() if len(args) > 1 else "")
if not value or value.startswith("-"):
raise ValueError(f"{name} needs a value")
if name == "--reported" and reported is None:
reported = [s.strip() for s in value.split(",") if s.strip()]
unknown = [s for s in reported if s not in RECORD_SOURCES]
if unknown or not reported:
raise ValueError(f"unknown source: {', '.join(unknown) or value}. This workspace's sources with records: {', '.join(RECORD_SOURCES)}")
elif name == "--record-id" and record_id is None:
record_id = value
else:
raise ValueError(f"unknown option: {name}")
args = args[2:]
if record_id is not None and (reported is None or len(reported) != 1):
raise ValueError("--record-id names one record: give its one source with --reported SOURCE")
return reported, record_id
def refused(e: CommitLayerError) -> int:
"""The server's structured error: nothing was written."""
print(f"CommitLayer refused the evidence: {e.status} {e.code}: {e.message}", file=sys.stderr)
details = e.details if isinstance(e.details, dict) else {}
for line in details.get("summary") or []:
print(f" {line}", file=sys.stderr)
if details.get("written") is False:
print(" nothing was written: no link, no record, no checkpoint", file=sys.stderr)
return 1
def main() -> int:
args = sys.argv[1:]
checkpoint_only = args == ["--checkpoint-only"]
links, facts = [], []
now = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
if not checkpoint_only:
try:
order_id, amount = args[0].strip(), float(args[1])
if not order_id or order_id.startswith("-") or amount <= 0:
raise ValueError
reported, record_id = options(args[2:])
except (IndexError, ValueError) as e:
if str(e) and not isinstance(e, IndexError) and "float" not in str(e):
print(str(e), file=sys.stderr)
print(USAGE, file=sys.stderr)
return 2
links, facts = records(order_id, amount, now, reported, record_id)
if record_id is not None and len(facts) != 1:
print("--record-id names one record, and that source has none or several for an order.", file=sys.stderr)
print(USAGE, file=sys.stderr)
return 2
if not facts:
print("No record to publish. To send checkpoints alone, run: python publish_evidence.py --checkpoint-only", file=sys.stderr)
return 1
load_env("commitlayer-evidence.env", forbidden="COMMITLAYER_RECORDER_KEY")
batch = {
"workspace_id": os.environ.get("COMMITLAYER_WORKSPACE_ID"),
"contract_id": os.environ.get("COMMITLAYER_CONTRACT_ID"),
"links": links,
"facts": facts,
"observed_through": {source: now for source in SOURCES},
}
try:
ev = commitlayer.evidence() # COMMITLAYER_EVIDENCE_KEY
ev.preflight_batches(**batch) # checks everything, writes nothing
out = ev.publish_batches(**batch) # one transaction: all of it or none of it
except CommitLayerError as e:
return refused(e)
except ValueError as e:
print(f"Setup problem: {e}", file=sys.stderr)
return 1
for ln in out.get("links", []):
print(f"link {ln.get('link_type')} {ln.get('source')} -> {ln.get('linked_source')}: {ln.get('status')}")
for f in out.get("facts", []):
print(f"fact {f.get('fact_id')} {f.get('source_id')}/{f.get('fact_type')}: {f.get('status')}")
for c in out.get("checkpoints", []):
print(f"checkpoint {c.get('source')} through {c.get('observed_through')}: {c.get('status')}")
print(f"affected actions: {', '.join(out.get('affected_actions') or []) or 'none'}; reverification scheduled: {out.get('reverify_scheduled')}")
# Success is every item accounted for, never the status code alone.
ok = (
out.get("written") is True
and len([x for x in out.get("links", []) if x.get("accepted")]) == len(links)
and len([x for x in out.get("facts", []) if x.get("accepted")]) == len(facts)
and {c.get("source") for c in out.get("checkpoints", []) if c.get("accepted")} == set(SOURCES)
)
if not ok:
print("The answer does not account for every link, record and checkpoint sent. Treat the batch as failed.", file=sys.stderr)
return 1
return 0
if __name__ == "__main__":
sys.exit(main())
The program calls the two endpoints by name, preflight_batches(...) and publish_batches(...), which
commitlayer has from 0.1.5. On an earlier version the same calls go through
Client.request("POST", path, batch), with the batch in the API's own field names.
TypeScript guide
Node 20 or later. The project is complete: package.json, tsconfig.json, record-refund.ts and
publish-evidence.ts, and no file is named that is not in it. tsconfig.json compiles every .ts file in the
folder, so a per-source helper put beside the programs is built with them.
npm install
npm run record -- ORDER_ID AMOUNT
npm run evidence -- ORDER_ID AMOUNT
package.json
{
"name": "commitlayer-refund-quickstart",
"private": true,
"type": "module",
"engines": {
"node": ">=20"
},
"scripts": {
"build": "tsc -p tsconfig.json",
"record": "tsc -p tsconfig.json && node dist/record-refund.js",
"evidence": "tsc -p tsconfig.json && node dist/publish-evidence.js"
},
"dependencies": {
"commitlayer": "0.1.6"
},
"devDependencies": {
"@types/node": "22.19.1",
"typescript": "5.9.3"
}
}
tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"skipLibCheck": true,
"types": [
"node"
],
"outDir": "dist",
"rootDir": "."
},
"include": [
"*.ts"
]
}
record-refund.ts
// Record one refund action with the Runtime recorder key (CommitLayer quickstart, scop_refund_order v1).
// Run: npm install
// npm run record -- ORDER_ID AMOUNT
// Reads commitlayer-recorder.env. In your agent, call recordRefund() just before the refund is issued.
// Both arguments are required: without them nothing is recorded.
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { CommitLayerError, recorder } from "commitlayer";
const USAGE = "Usage: npm run record -- ORDER_ID AMOUNT (the order being refunded and the refund's amount, e.g. 40.00)";
function loadEnv(file: string, forbidden: string): void {
// Read KEY=value lines from the environment file in the project folder (no dependency needed).
const path = join(process.cwd(), file);
if (existsSync(path)) {
for (const raw of readFileSync(path, "utf8").split("\n")) {
const line = raw.trim();
if (!line || line.startsWith("#") || !line.includes("=")) continue;
const i = line.indexOf("=");
const k = line.slice(0, i).trim();
if (process.env[k] === undefined) process.env[k] = line.slice(i + 1).trim();
}
}
if (process.env[forbidden]) {
console.error(`${forbidden} is set in this process. Keep the recorder and evidence keys in separate processes.`);
process.exit(1);
}
}
export async function recordRefund(orderId: string, amount: number) {
const rec = recorder(); // COMMITLAYER_RECORDER_KEY; the contract is COMMITLAYER_CONTRACT_ID
return rec.recordAction(null, orderId, {
subjectKind: "order",
actionType: "refund_order",
workflowId: "refund_order",
actionId: `refund-${orderId}`, // idempotent: recording the same refund again changes nothing
params: { amount, currency: "USD", customer_id: `customer-${orderId}` },
});
}
async function main(): Promise<number> {
const args = process.argv.slice(2);
const orderId = (args[0] ?? "").trim();
const amount = Number(args[1]);
if (args.length !== 2 || !orderId || orderId.startsWith("-") || !Number.isFinite(amount) || amount <= 0) {
console.error(USAGE); // no order and no amount is ever made up
return 2;
}
loadEnv("commitlayer-recorder.env", "COMMITLAYER_EVIDENCE_KEY");
try {
const out = (await recordRefund(orderId, amount)) as { action: Record<string, string>; verification: Record<string, string> };
console.log(`action recorded: ${out.action.id} (action_id ${out.action.action_id}, contract ${out.action.contract_id})`);
console.log(`verification: ${out.verification.status}`);
return 0;
} catch (e) {
if (e instanceof CommitLayerError) console.error(`CommitLayer refused the action: ${e.status} ${e.code}: ${e.message}`);
else console.error(`Setup problem: ${(e as Error).message}`);
return 1;
}
}
main().then((code) => process.exit(code));
publish-evidence.ts
// Publish the refund's evidence as one atomic batch with the Evidence pipeline key (CommitLayer quickstart,
// scop_refund_order v1).
// Run: npm install
// npm run evidence -- ORDER_ID AMOUNT identity links, records and a checkpoint for every source
// npm run evidence -- ORDER_ID AMOUNT --reported SOURCE[,SOURCE]
// only the records those sources have for the order (a source with
// no record yet is left out; its checkpoint is still sent)
// npm run evidence -- ORDER_ID AMOUNT --reported SOURCE --record-id ID
// one more record of that source under the source's own id for it:
// a second refund on the same order is a second record
// npm run evidence -- --checkpoint-only the checkpoints alone: "scanned, nothing new"
// Reads commitlayer-evidence.env.
// Source ids are this workspace's own, the evidence key's scope: shopify, stripe, zendesk.
// The batch is checked first (the preflight writes nothing) and then stored whole or not at all. This program exits
// nonzero when anything is refused, and when there is no record to publish.
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { CommitLayerError, evidence } from "commitlayer";
const USAGE =
"Usage: npm run evidence -- ORDER_ID AMOUNT (the refunded order and the refund's amount)\n" +
" npm run evidence -- ORDER_ID AMOUNT --reported SOURCE[,SOURCE] (only the records those sources have: stripe, shopify, zendesk)\n" +
" npm run evidence -- ORDER_ID AMOUNT --reported SOURCE --record-id ID (one more record of that source, under its own id)\n" +
" npm run evidence -- --checkpoint-only (checkpoints alone, no record)";
const SOURCES: string[] = ["shopify", "stripe", "zendesk"]; // this workspace's configured source ids
const RECORD_SOURCES: string[] = ["stripe", "shopify", "zendesk"]; // the sources this program has a record for
type Item = Record<string, unknown>;
function loadEnv(file: string, forbidden: string): void {
// Read KEY=value lines from the environment file in the project folder (no dependency needed).
const path = join(process.cwd(), file);
if (existsSync(path)) {
for (const raw of readFileSync(path, "utf8").split("\n")) {
const line = raw.trim();
if (!line || line.startsWith("#") || !line.includes("=")) continue;
const i = line.indexOf("=");
const k = line.slice(0, i).trim();
if (process.env[k] === undefined) process.env[k] = line.slice(i + 1).trim();
}
}
if (process.env[forbidden]) {
console.error(`${forbidden} is set in this process. Keep the recorder and evidence keys in separate processes.`);
process.exit(1);
}
}
/** The identity links and the facts for one refunded order: every source's, or those of the sources in `reported`.
* `recordId` is the source's own id of the one record published (a second refund has its own). */
function records(orderId: string, amount: number, at: string, reported: string[] | null = null, recordId: string | null = null): { links: Item[]; facts: Item[] } {
const payment = `pay-${orderId}`;
const ticket = `ticket-${orderId}`;
let links: Item[] = [
{ subject_id: payment, source: "stripe", linked_subject_id: orderId, linked_source: "shopify", link_type: "payment_to_order" },
{ subject_id: ticket, source: "zendesk", linked_subject_id: orderId, linked_source: "shopify", link_type: "ticket_to_order" },
];
let facts: Item[] = [
{ source: "stripe", subject_id: payment, subject_kind: "payment", fact_type: "refund", occurred_at: at, attributes: { amount, "currency": "usd", "status": "succeeded" }, raw_ref: `stripe:refund:${payment}` },
{ source: "shopify", subject_id: orderId, subject_kind: "order", fact_type: "order_cancelled", occurred_at: at, attributes: { "reason": "customer" }, raw_ref: `shopify:order_cancelled:${orderId}` },
{ source: "zendesk", subject_id: ticket, subject_kind: "ticket", fact_type: "status_change", occurred_at: at, attributes: { "from": "open", "to": "solved" }, raw_ref: `zendesk:status_change:${ticket}` },
];
if (reported !== null) {
links = links.filter((ln) => reported.includes(String(ln.source)));
facts = facts.filter((f) => reported.includes(String(f.source)));
}
if (recordId !== null) for (const f of facts) f.raw_ref = `${f.source}:${f.fact_type}:${recordId}`;
return { links, facts };
}
/** The reported sources and the record id from what follows ORDER_ID AMOUNT. Throws on anything else. */
function options(args: string[]): { reported: string[] | null; recordId: string | null } {
let reported: string[] | null = null;
let recordId: string | null = null;
for (let i = 0; i < args.length; i += 2) {
const name = args[i];
const value = (args[i + 1] ?? "").trim();
if (!value || value.startsWith("-")) throw new Error(`${name} needs a value`);
if (name === "--reported" && reported === null) {
reported = value.split(",").map((s) => s.trim()).filter(Boolean);
const unknown = reported.filter((s) => !RECORD_SOURCES.includes(s));
if (unknown.length || !reported.length) throw new Error(`unknown source: ${unknown.join(", ") || value}. This workspace's sources with records: ${RECORD_SOURCES.join(", ")}`);
} else if (name === "--record-id" && recordId === null) {
recordId = value;
} else {
throw new Error(`unknown option: ${name}`);
}
}
if (recordId !== null && (reported === null || reported.length !== 1)) throw new Error("--record-id names one record: give its one source with --reported SOURCE");
return { reported, recordId };
}
/** The server's structured error: nothing was written. */
function refused(e: CommitLayerError): number {
console.error(`CommitLayer refused the evidence: ${e.status} ${e.code}: ${e.message}`);
const details = (e.details ?? {}) as { summary?: string[]; written?: boolean };
for (const line of details.summary ?? []) console.error(` ${line}`);
if (details.written === false) console.error(" nothing was written: no link, no record, no checkpoint");
return 1;
}
async function main(): Promise<number> {
const args = process.argv.slice(2);
const checkpointOnly = args.length === 1 && args[0] === "--checkpoint-only";
const now = new Date(Math.floor(Date.now() / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
let links: Item[] = [];
let facts: Item[] = [];
if (!checkpointOnly) {
const orderId = (args[0] ?? "").trim();
const amount = Number(args[1]);
if (args.length < 2 || !orderId || orderId.startsWith("-") || !Number.isFinite(amount) || amount <= 0) {
console.error(USAGE);
return 2;
}
let chosen: { reported: string[] | null; recordId: string | null };
try {
chosen = options(args.slice(2));
} catch (e) {
console.error((e as Error).message);
console.error(USAGE);
return 2;
}
({ links, facts } = records(orderId, amount, now, chosen.reported, chosen.recordId));
if (chosen.recordId !== null && facts.length !== 1) {
console.error("--record-id names one record, and that source has none or several for an order.");
console.error(USAGE);
return 2;
}
if (facts.length === 0) {
console.error("No record to publish. To send checkpoints alone, run: npm run evidence -- --checkpoint-only");
return 1;
}
}
loadEnv("commitlayer-evidence.env", "COMMITLAYER_RECORDER_KEY");
const batch = {
workspaceId: process.env.COMMITLAYER_WORKSPACE_ID,
contractId: process.env.COMMITLAYER_CONTRACT_ID,
links,
facts,
observedThrough: Object.fromEntries(SOURCES.map((source) => [source, now])),
};
type Row = { accepted?: boolean; status?: string; source?: string; [k: string]: unknown };
let out: { written?: boolean; links?: Row[]; facts?: Row[]; checkpoints?: Row[]; affected_actions?: string[]; reverify_scheduled?: boolean };
try {
const ev = evidence(); // COMMITLAYER_EVIDENCE_KEY
await ev.preflightBatches(batch); // checks everything, writes nothing
out = (await ev.publishBatches(batch)) as typeof out; // one transaction: all of it or none of it
} catch (e) {
if (e instanceof CommitLayerError) return refused(e);
console.error(`Setup problem: ${(e as Error).message}`);
return 1;
}
for (const ln of out.links ?? []) console.log(`link ${ln.link_type} ${ln.source} -> ${ln.linked_source}: ${ln.status}`);
for (const f of out.facts ?? []) console.log(`fact ${f.fact_id} ${f.source_id}/${f.fact_type}: ${f.status}`);
for (const c of out.checkpoints ?? []) console.log(`checkpoint ${c.source} through ${c.observed_through}: ${c.status}`);
console.log(`affected actions: ${(out.affected_actions ?? []).join(", ") || "none"}; reverification scheduled: ${out.reverify_scheduled}`);
// Success is every item accounted for, never the status code alone.
const accepted = new Set((out.checkpoints ?? []).filter((c) => c.accepted).map((c) => c.source));
const ok =
out.written === true &&
(out.links ?? []).filter((x) => x.accepted).length === links.length &&
(out.facts ?? []).filter((x) => x.accepted).length === facts.length &&
accepted.size === SOURCES.length &&
SOURCES.every((s) => accepted.has(s));
if (!ok) {
console.error("The answer does not account for every link, record and checkpoint sent. Treat the batch as failed.");
return 1;
}
return 0;
}
main().then((code) => process.exit(code));
The program calls the two endpoints by name, preflightBatches(...) and publishBatches(...), which
commitlayer has from 0.1.6. On an earlier version the same calls go through
Client.request("POST", path, batch), with the batch in the API's own field names.
REST guide
Needs bash and curl.
bash record-action.sh ORDER_ID AMOUNT
bash publish-evidence.sh ORDER_ID AMOUNT
record-action.sh
#!/usr/bin/env bash
# Record one refund action with the Runtime recorder key (CommitLayer quickstart, scop_refund_order v1).
# Run: bash record-action.sh ORDER_ID AMOUNT (reads commitlayer-recorder.env; needs curl)
# Both arguments are required: without them nothing is recorded.
set -euo pipefail
HERE="$(cd "$(dirname "$0")" && pwd)"
usage() {
echo "Usage: bash record-action.sh ORDER_ID AMOUNT (the order being refunded and the refund's amount, e.g. 40.00)" >&2
exit 2
}
MODE="records"
if [ "$MODE" = "records" ]; then
[ "$#" -ge 2 ] || usage
ORDER_ID="$1"
AMOUNT="$2"
case "$ORDER_ID" in ''|-*|*[!A-Za-z0-9_.:-]*) usage ;; esac
case "$AMOUNT" in ''|*[!0-9.]*|*.*.*) usage ;; esac
shift 2
[ "$#" -eq 0 ] || usage
fi
if [ -f "$HERE/commitlayer-recorder.env" ]; then
set -a
# shellcheck disable=SC1090
. "$HERE/commitlayer-recorder.env"
set +a
fi
for name in COMMITLAYER_API_URL COMMITLAYER_WORKSPACE_ID COMMITLAYER_CONTRACT_ID COMMITLAYER_RECORDER_KEY; do
if [ -z "${!name:-}" ]; then echo "Missing $name: put commitlayer-recorder.env next to this script." >&2; exit 1; fi
done
if [ -n "${COMMITLAYER_EVIDENCE_KEY:-}" ]; then
echo "COMMITLAYER_EVIDENCE_KEY is set in this process. Keep the recorder and evidence keys in separate processes." >&2
exit 1
fi
NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
field() { # field NAME JSON: the first string value of that name
printf '%s' "$2" | grep -o "\"$1\": *\"[^\"]*\"" | head -n 1 | sed 's/^[^:]*: *"//; s/"$//'
}
post() { # post PATH BODY: prints the response body; a refusal prints the server's structured error and exits 1
local out status
out="$(curl -sS -w '\n%{http_code}' -X POST "${COMMITLAYER_API_URL%/}$1" \
-H "X-API-Key: ${COMMITLAYER_RECORDER_KEY}" -H "Content-Type: application/json" --data "$2")"
status="${out##*$'\n'}"
out="${out%$'\n'*}"
if [ "$status" -ge 400 ]; then
echo "CommitLayer refused $1: $status $(field code "$out"): $(field message "$out")" >&2
printf '%s' "$out" | grep -o '"summary": *\[[^]]*\]' | sed 's/^[^[]*\[//; s/\]$//; s/^"//; s/"$//; s/", *"/|/g' \
| tr '|' '\n' | sed '/^$/d; s/^/ /' >&2 || true
if printf '%s' "$out" | grep -q '"written": *false'; then
echo " nothing was written: no link, no record, no checkpoint" >&2
fi
exit 1
fi
printf '%s\n' "$out"
}
BODY="$(cat <<JSON
{"action_id": "refund-$ORDER_ID", "contract_id": "$COMMITLAYER_CONTRACT_ID", "action_type": "refund_order",
"workflow_id": "refund_order", "subject_id": "$ORDER_ID", "subject_kind": "order", "requested_at": "$NOW",
"params": {"amount": $AMOUNT, "currency": "USD", "customer_id": "customer-$ORDER_ID"}}
JSON
)"
OUT="$(post /v1/actions "$BODY")"
ACTION="$(printf '%s' "$OUT" | sed -n 's/.*"action": *{"id": *"\([^"]*\)".*/\1/p')"
echo "action recorded: $ACTION (action_id refund-$ORDER_ID, contract $COMMITLAYER_CONTRACT_ID)"
publish-evidence.sh
#!/usr/bin/env bash
# Publish the refund's evidence as one atomic batch with the Evidence pipeline key (CommitLayer quickstart, scop_refund_order v1).
# Run: bash publish-evidence.sh ORDER_ID AMOUNT identity links, records and a checkpoint for every source
# bash publish-evidence.sh ORDER_ID AMOUNT --reported SOURCE[,SOURCE]
# only the records those sources have for the order (a source with
# no record yet is left out; its checkpoint is still sent)
# bash publish-evidence.sh ORDER_ID AMOUNT --reported SOURCE --record-id ID
# one more record of that source under the source's own id for it:
# a second refund on the same order is a second record
# bash publish-evidence.sh --checkpoint-only the checkpoints alone: "scanned, nothing new"
# Reads commitlayer-evidence.env; needs curl.
# Source ids are this workspace's own, the evidence key's scope: shopify, stripe, zendesk.
# The batch is checked first (the preflight writes nothing) and then stored whole or not at all. This script exits
# nonzero when anything is refused, and when there is no record to publish.
set -euo pipefail
HERE="$(cd "$(dirname "$0")" && pwd)"
usage() {
echo "Usage: bash publish-evidence.sh ORDER_ID AMOUNT (the refunded order and the refund's amount)" >&2
echo " bash publish-evidence.sh ORDER_ID AMOUNT --reported SOURCE[,SOURCE] (only the records those sources have: ${RECORD_SOURCES// /, })" >&2
echo " bash publish-evidence.sh ORDER_ID AMOUNT --reported SOURCE --record-id ID (one more record of that source, under its own id)" >&2
echo " bash publish-evidence.sh --checkpoint-only (checkpoints alone, no record)" >&2
exit 2
}
RECORD_SOURCES="stripe shopify zendesk" # the sources this script has a record for
REPORTED=""
RECORD_ID=""
MODE="records"
if [ "$#" -eq 1 ] && [ "$1" = "--checkpoint-only" ]; then MODE="checkpoints"; fi
if [ "$MODE" = "records" ]; then
[ "$#" -ge 2 ] || usage
ORDER_ID="$1"
AMOUNT="$2"
case "$ORDER_ID" in ''|-*|*[!A-Za-z0-9_.:-]*) usage ;; esac
case "$AMOUNT" in ''|*[!0-9.]*|*.*.*) usage ;; esac
shift 2
while [ "$#" -gt 0 ]; do
[ "$#" -ge 2 ] || { echo "$1 needs a value" >&2; usage; }
case "$2" in ''|-*|*[!A-Za-z0-9_.:,-]*) echo "$1 needs a value" >&2; usage ;; esac
case "$1" in
--reported) [ -z "$REPORTED" ] || usage; REPORTED="$2" ;;
--record-id) [ -z "$RECORD_ID" ] || usage; RECORD_ID="$2" ;;
*) echo "unknown option: $1" >&2; usage ;;
esac
shift 2
done
if [ -n "$REPORTED" ]; then
for s in ${REPORTED//,/ }; do
case " $RECORD_SOURCES " in
*" $s "*) ;;
*) echo "unknown source: $s. This workspace's sources with records: ${RECORD_SOURCES// /, }" >&2; usage ;;
esac
done
fi
if [ -n "$RECORD_ID" ]; then
case "$REPORTED" in
''|*,*) echo "--record-id names one record: give its one source with --reported SOURCE" >&2; usage ;;
esac
case "$RECORD_ID" in *,*) usage ;; esac
fi
fi
if [ -f "$HERE/commitlayer-evidence.env" ]; then
set -a
# shellcheck disable=SC1090
. "$HERE/commitlayer-evidence.env"
set +a
fi
for name in COMMITLAYER_API_URL COMMITLAYER_WORKSPACE_ID COMMITLAYER_CONTRACT_ID COMMITLAYER_EVIDENCE_KEY; do
if [ -z "${!name:-}" ]; then echo "Missing $name: put commitlayer-evidence.env next to this script." >&2; exit 1; fi
done
if [ -n "${COMMITLAYER_RECORDER_KEY:-}" ]; then
echo "COMMITLAYER_RECORDER_KEY is set in this process. Keep the recorder and evidence keys in separate processes." >&2
exit 1
fi
NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
field() { # field NAME JSON: the first string value of that name
printf '%s' "$2" | grep -o "\"$1\": *\"[^\"]*\"" | head -n 1 | sed 's/^[^:]*: *"//; s/"$//'
}
post() { # post PATH BODY: prints the response body; a refusal prints the server's structured error and exits 1
local out status
out="$(curl -sS -w '\n%{http_code}' -X POST "${COMMITLAYER_API_URL%/}$1" \
-H "X-API-Key: ${COMMITLAYER_EVIDENCE_KEY}" -H "Content-Type: application/json" --data "$2")"
status="${out##*$'\n'}"
out="${out%$'\n'*}"
if [ "$status" -ge 400 ]; then
echo "CommitLayer refused $1: $status $(field code "$out"): $(field message "$out")" >&2
printf '%s' "$out" | grep -o '"summary": *\[[^]]*\]' | sed 's/^[^[]*\[//; s/\]$//; s/^"//; s/"$//; s/", *"/|/g' \
| tr '|' '\n' | sed '/^$/d; s/^/ /' >&2 || true
if printf '%s' "$out" | grep -q '"written": *false'; then
echo " nothing was written: no link, no record, no checkpoint" >&2
fi
exit 1
fi
printf '%s\n' "$out"
}
# This workspace's configured source ids: a checkpoint is sent for each.
THROUGH='"shopify": "@NOW@", "stripe": "@NOW@", "zendesk": "@NOW@"'
THROUGH="${THROUGH//@NOW@/$NOW}"
LINKS=""
FACTS=""
N_LINKS=0
N_FACTS=0
reported() { # reported SOURCE: whether that source's records are published (all of them unless --reported names some)
[ -z "$REPORTED" ] && return 0
case ",$REPORTED," in *",$1,"*) return 0 ;; esac
return 1
}
link() { # link JSON: one more identity link in the batch
LINKS="${LINKS:+$LINKS,
}$1"
N_LINKS=$((N_LINKS + 1))
}
fact() { # fact JSON: one more record in the batch
FACTS="${FACTS:+$FACTS,
}$1"
N_FACTS=$((N_FACTS + 1))
}
if [ "$MODE" = "records" ]; then
PAYMENT="pay-$ORDER_ID"
TICKET="ticket-$ORDER_ID"
if reported "stripe"; then
link "$(cat <<JSON
{"subject_id": "$PAYMENT", "source": "stripe", "linked_subject_id": "$ORDER_ID", "linked_source": "shopify", "link_type": "payment_to_order"}
JSON
)"
fi
if reported "zendesk"; then
link "$(cat <<JSON
{"subject_id": "$TICKET", "source": "zendesk", "linked_subject_id": "$ORDER_ID", "linked_source": "shopify", "link_type": "ticket_to_order"}
JSON
)"
fi
if reported "stripe"; then
fact "$(cat <<JSON
{"source": "stripe", "subject_id": "$PAYMENT", "subject_kind": "payment", "fact_type": "refund", "occurred_at": "$NOW",
"attributes": {"amount": $AMOUNT, "currency": "usd", "status": "succeeded"}, "raw_ref": "stripe:refund:${RECORD_ID:-$PAYMENT}"}
JSON
)"
fi
if reported "shopify"; then
fact "$(cat <<JSON
{"source": "shopify", "subject_id": "$ORDER_ID", "subject_kind": "order", "fact_type": "order_cancelled", "occurred_at": "$NOW",
"attributes": {"reason": "customer"}, "raw_ref": "shopify:order_cancelled:${RECORD_ID:-$ORDER_ID}"}
JSON
)"
fi
if reported "zendesk"; then
fact "$(cat <<JSON
{"source": "zendesk", "subject_id": "$TICKET", "subject_kind": "ticket", "fact_type": "status_change", "occurred_at": "$NOW",
"attributes": {"from": "open", "to": "solved"}, "raw_ref": "zendesk:status_change:${RECORD_ID:-$TICKET}"}
JSON
)"
fi
if [ -n "$RECORD_ID" ] && [ "$N_FACTS" -ne 1 ]; then
echo "--record-id names one record, and that source has none or several for an order." >&2
usage
fi
if [ "$N_FACTS" -eq 0 ]; then
echo "No record to publish. To send checkpoints alone, run: bash publish-evidence.sh --checkpoint-only" >&2
exit 1
fi
fi
BATCH="$(cat <<JSON
{"workspace_id": "$COMMITLAYER_WORKSPACE_ID", "contract_id": "$COMMITLAYER_CONTRACT_ID",
"links": [$LINKS],
"facts": [$FACTS],
"observed_through": {$THROUGH}}
JSON
)"
post /v1/evidence/batches/preflight "$BATCH" >/dev/null # checks everything, writes nothing
OUT="$(post /v1/evidence/batches "$BATCH")" # one transaction: all of it or none of it
count() { # count NAME: that number in the answer's "counts"
printf '%s' "$OUT" | sed -n "s/.*\"counts\": *{[^}]*\"$1\": *\([0-9]*\).*/\1/p"
}
echo "links accepted: $(count links) of $N_LINKS"
echo "facts accepted: $(count facts) of $N_FACTS (stored $(count facts_stored), already stored $(count facts_duplicate))"
echo "checkpoints accepted: $(count checkpoints) of 3 (shopify, stripe, zendesk)"
echo "reverification scheduled: $(printf '%s' "$OUT" | sed -n 's/.*"reverify_scheduled": *\(true\|false\).*/\1/p')"
# Success is every item accounted for, never the status code alone.
if ! printf '%s' "$OUT" | grep -q '"written": *true' || [ "$(count links)" != "$N_LINKS" ] \
|| [ "$(count facts)" != "$N_FACTS" ] || [ "$(count checkpoints)" != "3" ]; then
echo "The answer does not account for every link, record and checkpoint sent. Treat the batch as failed." >&2
exit 1
fi
Per-source helpers
The evidence step also shows one helper per source your backend sends, in each language, for a backend that
publishes one system at a time (GET /v1/onboarding/evidence-snippet). Each call is one atomic batch: the record,
the identity link to your configured order source and the source's checkpoint. Each helper also sends the
checkpoint alone. In the REST helper every ${NAME} is a value your system holds for the record; export them and
run the line for the record you send. A value that is not set stops the script before it sends anything.
send_stripe_records.sh
#!/usr/bin/env bash
# Sends the stripe records the contract scop_refund_order (version 1) reads, each as one atomic batch
# (POST /v1/evidence/batches): the record, the identity link it needs and the stripe checkpoint are stored
# together or not at all. A refused batch writes nothing.
# 1. Send each record from the backend of the system that owns it, never from the agent being checked.
# 2. Send it when the record is created or changes in that system, with the time it happened there.
# 3. Keep raw_ref the same on every retry of one record, so a retry is stored once.
# 4. Send the checkpoint after every scan of the source, also when it found nothing new: it is how a missing record settles on time.
# Run: bash send_stripe_records.sh refund
# bash send_stripe_records.sh refund_failed
# bash send_stripe_records.sh checkpoint
# Every value written as a dollar sign and a name in braces is one your own system holds for the record.
# Export them, then run the call for the record you send. A value that is not set stops the script before it sends.
set -euo pipefail
HERE="$(cd "$(dirname "$0")" && pwd)"
if [ -f "$HERE/commitlayer-evidence.env" ]; then
set -a
# shellcheck disable=SC1090
. "$HERE/commitlayer-evidence.env"
set +a
fi
if [ -z "${COMMITLAYER_EVIDENCE_KEY:-}" ]; then echo "Missing COMMITLAYER_EVIDENCE_KEY: put commitlayer-evidence.env next to this script." >&2; exit 1; fi
API="${COMMITLAYER_API_URL:-https://api.commitlayer.ai}"
# The time through which every stripe record has been sent. Now, unless you say otherwise.
OBSERVED_THROUGH="${OBSERVED_THROUGH:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"
send() { # send: the batch on stdin. Prints the answer; a refusal prints the server's error and exits 1.
local out status
out="$(curl -sS -w '\n%{http_code}' -X POST "${API%/}/v1/evidence/batches" \
-H "X-API-Key: ${COMMITLAYER_EVIDENCE_KEY}" \
-H "Content-Type: application/json" \
--data-binary @-)"
status="${out##*$'\n'}"
out="${out%$'\n'*}"
if [ "$status" -ge 400 ]; then echo "CommitLayer refused the batch ($status), nothing was written: $out" >&2; exit 1; fi
printf '%s\n' "$out"
}
case "${1:-}" in
refund)
# A refund record: send it when your system records one.
send <<JSON
{
"contract_id": "scop_refund_order",
"links": [
{
"subject_id": "${PAYMENT_ID}",
"source": "stripe",
"linked_subject_id": "${ORDER_ID}",
"linked_source": "shopify",
"link_type": "payment_to_order"
}
],
"facts": [
{
"source": "stripe",
"fact_type": "refund",
"subject_id": "${PAYMENT_ID}",
"subject_kind": "payment",
"occurred_at": "${OCCURRED_AT}",
"raw_ref": "${RECORD_ID}",
"attributes": {
"amount": ${AMOUNT}
}
}
],
"observed_through": {"stripe": "${OBSERVED_THROUGH}"}
}
JSON
;;
refund_failed)
# A refund_failed record: send it when your system records one.
send <<JSON
{
"contract_id": "scop_refund_order",
"links": [
{
"subject_id": "${PAYMENT_ID}",
"source": "stripe",
"linked_subject_id": "${ORDER_ID}",
"linked_source": "shopify",
"link_type": "payment_to_order"
}
],
"facts": [
{
"source": "stripe",
"fact_type": "refund_failed",
"subject_id": "${PAYMENT_ID}",
"subject_kind": "payment",
"occurred_at": "${OCCURRED_AT}",
"raw_ref": "${RECORD_ID}",
"attributes": {}
}
],
"observed_through": {"stripe": "${OBSERVED_THROUGH}"}
}
JSON
;;
checkpoint)
# The checkpoint alone: send it after every scan of stripe, also when it found nothing new.
send <<JSON
{
"contract_id": "scop_refund_order",
"observed_through": {"stripe": "${OBSERVED_THROUGH}"}
}
JSON
;;
*)
echo "Usage: bash send_stripe_records.sh refund" >&2
echo " bash send_stripe_records.sh refund_failed" >&2
echo " bash send_stripe_records.sh checkpoint" >&2
exit 2
;;
esac