Review a policy change

Your refund policy moved from version 14 to version 15. Legal asks which refunds were decided under version 14, and how they ended. Each intent records the policy it read as an input (policy:refund at a version), so a query on that input lists them. You will record five decisions across both versions, list the ones under version 14, and join them to their outcomes.

Prerequisites

CLI

The tenbri CLI, jq and openssl:

cargo install tenbri-cli --version 0.1.0-beta.1 --locked

Python

Python 3.10 or later.

pip

pip install --pre tenbri

uv

uv add --prerelease allow tenbri

poetry

poetry add --allow-prereleases tenbri

TypeScript

Node 22.18 or later, which runs .ts files directly, in a project with "type": "module" (npm pkg set type=module).

npm

npm install tenbri@next

pnpm

pnpm add tenbri@next

yarn

yarn add tenbri@next

bun

bun add tenbri@next

REST

curl, jq, and a tenbrid serving the stream with a token for you (tenbrid over REST sets one up):

cargo install tenbri-server --version 0.1.0-beta.1 --locked

In every terminal:

export TENBRI_KEYS=./keys
export TENBRI_DIGEST_KEY='a 32-byte secret, kept apart....'

Steps

1. Record decisions under both versions.

   Each decision is an intent that read policy:refund at a version, then its outcome: ok or refused.

   CLI

   The decide helper writes an intent with the keyed digest of the policy text it read, then its outcome.

   decide.sh

   tenbri init audit/support > init.out
   PIN=$(sed -n 's/^stream key fingerprint (pin it): //p' init.out)
   
   decide() { # charge, policy version, status
     digest="hmac-sha256:$(printf 'refund policy, version %s' "$2" \
       | openssl dgst -sha256 -hmac "$TENBRI_DIGEST_KEY" -r | cut -d' ' -f1)"
     id=$(tenbri append audit/support <<EOF | jq -r .id
   {"kind":"decision","phase":"intent","source":"sdk",
    "principal":{"kind":"agent","id":"support-assistant"},
    "action":{"type":"issue_refund","target":"stripe:charge/$1"},
    "inputs":[{"ref":"policy:refund","version":"$2","digest":"$digest"}]}
   EOF
   )
     tenbri append audit/support <<EOF > /dev/null
   {"kind":"decision","phase":"outcome","source":"sdk","intent":"$id","status":"$3",
    "principal":{"kind":"agent","id":"support-assistant"},
    "action":{"type":"issue_refund","target":"stripe:charge/$1"}}
   EOF
   }
   
   decide ch_1001 14 ok
   decide ch_1002 14 refused
   decide ch_1003 15 ok
   decide ch_1004 14 ok
   decide ch_1005 15 refused

   source decide.sh

   Python

   run.read pins the policy text the agent read to its next decision. Raising Refused inside the decision records the outcome as refused.

   decide.py

   import os
   
   from tenbri import Refused, Tenbri
   
   DECISIONS = [  # charge, policy version, status
       ("ch_1001", "14", "ok"),
       ("ch_1002", "14", "refused"),
       ("ch_1003", "15", "ok"),
       ("ch_1004", "14", "ok"),
       ("ch_1005", "15", "refused"),
   ]
   
   log = Tenbri.open(
       "./audit/support",
       create=True,
       digest_key=os.environ["TENBRI_DIGEST_KEY"].encode(),
   )
   print("pin this:", log.fingerprint)
   
   with log.run("agent:support-assistant") as run:
       for charge, version, status in DECISIONS:
           run.read("policy:refund", version, f"refund policy, version {version}")
           try:
               with run.decision("issue_refund", f"stripe:charge/{charge}"):
                   if status == "refused":
                       raise Refused(f"policy {version} says no")
           except Refused:
               pass
   log.close()

   python decide.py

   pin this: sha256:b548a90ee31e0ba79ee424cc485eb5b0385e2b8713b053c4c1ac284c67a29b5f

   TypeScript

   run.read pins the policy text the agent read to its next decision. Throwing Refused inside the decision records the outcome as refused.

   decide.ts

   import { Refused, Tenbri } from 'tenbri'
   
   const decisions = [ // charge, policy version, status
     ['ch_1001', '14', 'ok'],
     ['ch_1002', '14', 'refused'],
     ['ch_1003', '15', 'ok'],
     ['ch_1004', '14', 'ok'],
     ['ch_1005', '15', 'refused'],
   ]
   
   const log = await Tenbri.open('./audit/support', {
     create: true,
     digestKey: process.env.TENBRI_DIGEST_KEY!,
   })
   console.log('pin this:', log.fingerprint)
   
   await log.run({ principal: 'agent:support-assistant' }, async (run) => {
     for (const [charge, version, status] of decisions) {
       run.read('policy:refund', { version, content: `refund policy, version ${version}` })
       try {
         await run.decision({ action: 'issue_refund', target: `stripe:charge/${charge}` }, async () => {
           if (status === 'refused') throw new Refused(`policy ${version} says no`)
         })
       } catch (e) {
         if (!(e instanceof Refused)) throw e
       }
     }
   })
   await log.close()

   node decide.ts

   pin this: sha256:0823b1cf12c6a78c060c8a942a97aef22acdd91530f85def7461d9beba9d5879

   REST

   Write the decisions with any of the other tabs, or with POST /v1/streams/support/intents and /outcomes as in tenbrid over REST. Then serve the stream:

   tenbrid --config tenbrid.toml

2. List the decisions under version 14, and join them to their outcomes.

   The input filter is ref@version. The inputs are on the intents; each outcome names its intent by id, so read every issue_refund entry once and join on it.

   CLI

   query prints one JSON object per line: the entry, its seq, its entry hash, its verification, and as_of (what the answer is current to). With --key and --verify, every row is checked against the pinned fingerprint.

   tenbri query audit/support --input policy:refund@14 --key $PIN --verify \
     | jq -c '{seq, id: .entry.id, target: .entry.action.target, verification}'

   {"seq":3,"id":"01M5CWMYAHYECM0BSJK1NVGYEF","target":"stripe:charge/ch_1001","verification":"verified"}
   {"seq":5,"id":"01M5CWMYCCWGQ2HAG6Y39JHKAF","target":"stripe:charge/ch_1002","verification":"verified"}
   {"seq":9,"id":"01M5CWMYG4S718BMP25J3ZCPAV","target":"stripe:charge/ch_1004","verification":"verified"}

   Count per version. A bare ref, --input policy:refund, matches any version:

   tenbri query audit/support --input policy:refund@14 --key $PIN --verify | jq -s length
   tenbri query audit/support --input policy:refund@15 --key $PIN --verify | jq -s length
   tenbri query audit/support --input policy:refund --key $PIN --verify | jq -s length

   3
   2
   5

   Join to the outcomes:

   tenbri query audit/support --action issue_refund --key $PIN --verify | jq -s -c '
     map(.entry) as $all
     | $all[] | select(.phase == "intent" and any(.inputs[]?; .ref == "policy:refund" and .version == "14")) as $i
     | $all[] | select(.intent == $i.id)
     | {target: .action.target, status}'

   {"target":"stripe:charge/ch_1001","status":"ok"}
   {"target":"stripe:charge/ch_1002","status":"refused"}
   {"target":"stripe:charge/ch_1004","status":"ok"}

   --status refused lists only the refused outcomes, across both versions.

   Python

   inputs takes "ref@version" strings or (ref, version) pairs; several must all match.

   review.py

   import os
   
   from tenbri import Tenbri
   
   with Tenbri.open("./audit/support", key=os.environ["PIN"]) as log:
       intents = log.query(inputs=["policy:refund@14"])
       print(len(intents), "decisions read policy:refund at version 14")
   
       outcomes = {
           m.entry["intent"]: m.entry
           for m in log.query(action="issue_refund")
           if m.entry.get("phase") == "outcome"
       }
       for m in intents:
           intent = m.entry
           print(m.verification, intent["seq"], intent["action"]["target"], outcomes[intent["id"]]["status"])

   PIN=sha256:b548a90ee31e0ba79ee424cc485eb5b0385e2b8713b053c4c1ac284c67a29b5f python review.py

   3 decisions read policy:refund at version 14
   verified 3 stripe:charge/ch_1001 ok
   verified 5 stripe:charge/ch_1002 refused
   verified 9 stripe:charge/ch_1004 ok

   TypeScript

   inputs takes 'ref@version' strings or [ref, version] pairs; several must all match.

   review.ts

   import { Tenbri } from 'tenbri'
   
   const log = await Tenbri.open('./audit/support', { key: process.env.PIN! })
   const intents = await log.query({ inputs: ['policy:refund@14'] })
   console.log(intents.length, 'decisions read policy:refund at version 14')
   
   const outcomes = new Map(
     (await log.query({ action: 'issue_refund' }))
       .filter((m) => m.entry.phase === 'outcome')
       .map((m) => [m.entry.intent, m.entry]),
   )
   for (const { verification, entry: intent } of intents) {
     console.log(verification, intent.seq, intent.action?.target, outcomes.get(intent.id)?.status)
   }
   await log.close()

   PIN=sha256:0823b1cf12c6a78c060c8a942a97aef22acdd91530f85def7461d9beba9d5879 node review.ts

   3 decisions read policy:refund at version 14
   verified 3 stripe:charge/ch_1001 ok
   verified 5 stripe:charge/ch_1002 refused
   verified 9 stripe:charge/ch_1004 ok

   REST

   GET /entries takes the same filters as query parameters (input, action, status, after_seq, limit and more). A bare input=policy:refund matches any version.

   export TENBRI_URL=http://127.0.0.1:7070
   export TOKEN=tnbt_…   # your token
   curl -s "$TENBRI_URL/v1/streams/support/entries?input=policy:refund@14" \
     -H "Authorization: Bearer $TOKEN" \
     | jq -c '.entries[] | {seq, id: .entry.id, target: .entry.action.target, verification}'

   {"seq":3,"id":"01M5CWMYAHYECM0BSJK1NVGYEF","target":"stripe:charge/ch_1001","verification":"verified"}
   {"seq":5,"id":"01M5CWMYCCWGQ2HAG6Y39JHKAF","target":"stripe:charge/ch_1002","verification":"verified"}
   {"seq":9,"id":"01M5CWMYG4S718BMP25J3ZCPAV","target":"stripe:charge/ch_1004","verification":"verified"}

   Join to the outcomes:

   curl -s "$TENBRI_URL/v1/streams/support/entries?action=issue_refund" \
     -H "Authorization: Bearer $TOKEN" | jq -c '
     [.entries[].entry] as $all
     | $all[] | select(.phase == "intent" and any(.inputs[]?; .ref == "policy:refund" and .version == "14")) as $i
     | $all[] | select(.intent == $i.id)
     | {target: .action.target, status}'

   {"target":"stripe:charge/ch_1001","status":"ok"}
   {"target":"stripe:charge/ch_1002","status":"refused"}
   {"target":"stripe:charge/ch_1004","status":"ok"}

   A response holds up to 100 entries by default (limit, at most 1000); when more match, pass its next_after_seq as after_seq for the next page.

What happened

Each intent recorded the exact policy version it read, with a keyed digest of its text, inside a signed entry, so the list cannot be edited after the fact without failing verification. The query matched ref and version exactly, and every row was checked against the pinned fingerprint. The digest also lets you prove later which policy text the agent saw, if you keep the text and the digest key.

Related

• Streams and entries
• Entry format
• CLI reference
• API reference
• Adapters: the Claude Agent SDK, OpenAI Agents SDK and LangGraph adapters record each tool call as a decision for you.