TheSoftware LensSee engineering differently

One hire, step by step

The examples of SaaCIP 0.1, in the order they happen. Each step says who does what, then shows the real documents and messages produced at that moment. Every file is checked against its schema with the published validator, and the receipts are really signed with an example key that is published for that purpose and must never be used for a real hire. All names are made up.

The story: a hirer takes a capability called example-log-watch, from Example Provider, on a 14-day trial to watch the logs of its api service in prod-eu. It finds one problem, reports it, asks to restart the service, a person approves, the restart works, the person judges the finding real, and the trial ends with a statement.

One hire over the HTTP binding

One hire over the HTTP bindingCapabilityHubPeople at the hirer0 before the hire: the capability manifest, the declared actions file, and the hirer creating the hire and getting an enrolment tokenPOST enrol/ enrol-request (terms inside)201 enrol-response: credential, settings1hire_startedenrolledPOST heartbeat/ heartbeat200 heartbeat-response: settings2PUT work-items/<ref>/ report201 report-response: hub_ref3opens a ticketwork_item_reportedPOST approvals/ approval-request201 approval (pending)4approval_requesteda person approvesGET inbox/200 inbox: approval decided, outcome5a person judges the itemruns the actionaction_takenfeedback_appliedPOST inbox/ack/ ack200 ack-response6POST statement/ statement-request (final)200 statement-response: ended7hire_endedany error: problem (RFC 9457)

The seven calls of the Resident binding in the order they happen, with the schema name on each arrow and the receipts the capability writes on the left. Steps are numbered 0 to 8, as in the walkthrough. Open full size

0Before the hire

The provider, then the hirer. Nothing runs yet.

The provider publishes a capability manifest: what the capability does, what it may read, every action it could ever propose, and what data stays and leaves. A person at the hirer reads it, then writes and approves the declared actions file: the only commands the capability will ever be allowed to run. Finally the hirer creates the hire at its hub (a 14-day trial, who approves, who judges) and is shown a one-time enrolment token, enrol_..., which it passes to the capability it is about to start.

capability-manifest.example.yamlthe capability's CV, as the provider writes it

Written in YAML with comments, converted to JSON before it is published. Note autonomy.max: 3 and the two declared actions: this is what the hirer can see before deciding.

# A capability manifest, as its provider writes it (YAML).
# It is converted to JSON before it is published or sent.
protocol: saacip/0.1
id: example-log-watch
name: Example Log Watch
version: 1.0.0
provider: Example Provider
description: >
  Watches logs inside the hirer's environment, reports what is unusual to the
  hirer's help desk and acts only through actions a person declared in advance.
profiles: [resident]
hire_kinds: [task, trial, standing]
autonomy:
  default: 1        # report only
  max: 3            # act within declared limits, only if the hirer allows it
work_items:
  kind: incident
declared_actions:   # a summary of the declared actions file
  - id: restart-api
    title: Rolling restart of the api service
    reversible: true
    auto_allowed: true
  - id: clear-tmp
    title: Clear temporary files on the worker volume
    reversible: false
    auto_allowed: false
data:
  stays: "in the hirer's environment: logs, baselines, receipts, signing key"
  leaves_by_default: "nothing; redacted work item summaries to the hirer's help desk when one is set"
connectors: [file, cloud-logs, mcp]
ext:
  com.example.support:      # an extension: ignored by anyone who does not understand it
    hours: business
    timezone: Europe/Dublin

Schema: capability-manifest · File: capability-manifest.example.yaml · Check it: python validate.py capability-manifest capability-manifest.example.yaml

declared-actions.example.yamlthe complete list of things it may do

Two actions. restart-api is reversible and may run alone at most twice a day; clear-tmp deletes files, so it always waits for a person. The {service} placeholder can only be filled from services.

# The only things the capability can ever do. A person writes and approves this file
# before the hire. Commands are argument lists (no shell). {service} is only ever
# filled with a name from "services".
actions:
  - id: restart-api
    title: Rolling restart of the api service
    match: ["connection pool exhausted", "OutOfMemory"]
    services: [api]
    command: [kubectl, rollout, restart, "deployment/{service}", -n, prod]
    reversible: true          # a rolling restart can be repeated or rolled back safely
    auto_allowed: true        # may run by itself at autonomy level 3 ...
    max_per_day: 2            # ... at most twice in one UTC day

  - id: clear-tmp
    title: Clear temporary files on the worker volume
    match: ["No space left on device"]
    services: [worker]
    command: [kubectl, exec, "deployment/{service}", -n, prod, --, find, /tmp/work, -mtime, "+1", -delete]
    reversible: false         # deleted files do not come back: always waits for approval
    auto_allowed: false

Schema: declared-actions · File: declared-actions.example.yaml · Check it: python validate.py declared-actions declared-actions.example.yaml

1Enrol

The capability, once. The hub checks and answers.

The capability starts inside the hirer's environment, discovers its one source (a log file) and builds its terms: the kind of hire, the autonomy ceiling, what it reads, what leaves, and the public key that will sign its receipts. It sends the terms with the enrolment token. The hub checks the protocol version, the profile and that the terms match the hire the hirer created (a 14-day trial), then answers with a credential, agent_..., and the hirer's current settings. The capability writes its first two receipts.

The terms of a hire, annotated

The terms of a hire, annotated{  "protocol": "saacip/0.1",  "profile": "resident",  "kind": "trial",  "term": {"days": 14},  "autonomy_ceiling": 2,  "dry_run": false,  "connectors": [{    "id": "api-logs", "kind": "file", "version": "1.0.0",    "signals": ["logs"], "scopes": ["read"],    "data_location": "a log file on a volume mounted int...",    "auth": "file system permission (read-only mount)"  }],  "data_leaving": "work item summaries (redacted) to th...",  "model": "offline",  "public_key": "3RsIo8MiE66DyZ...LfkNc=",  "environment": "prod-eu"}Which rules applythe protocol version and the profile, agreed atenrolment (sections 6.2, 10.1)The hireits kind and how long it lasts: a 14-day trial(section 6.1)How much it may dothe highest autonomy level ever allowed, andwhether actions are only simulated (section 9)What it readsone manifest per connector: the source, what itcan read, where the data stays, how it signs in(Resident profile)What leaves, and to wherein plain words, everything that leaves the hirer'senvironment, including any model (section 12)Evidence and placethe key that signs this hire's receipts, and wherethe capability runs (section 7.3)

terms.example.json, shortened. Six groups of members, each tied to the section that defines it. The capability builds this document, sends it at enrolment and keeps it in its first receipt. Open full size

terms.example.jsonthe contract for this hire, built by the capability

Compare it with the picture above. autonomy_ceiling: 2 means a person must approve every action; the hub can lower that, never raise it. This hirer chose dry_run: false, so approved actions really run; the core recommends starting a new hire with true.

{
  "protocol": "saacip/0.1",
  "profile": "resident",
  "kind": "trial",
  "term": {
    "days": 14
  },
  "autonomy_ceiling": 2,
  "dry_run": false,
  "connectors": [
    {
      "protocol": "saacip/0.1",
      "id": "api-logs",
      "kind": "file",
      "version": "1.0.0",
      "signals": [
        "logs"
      ],
      "scopes": [
        "read"
      ],
      "data_location": "a log file on a volume mounted into the capability; read in place",
      "auth": "file system permission (read-only mount)"
    }
  ],
  "data_leaving": "work item summaries (redacted) to the hirer's help desk; nothing else",
  "model": "offline",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "environment": "prod-eu"
}

Schema: terms · File: terms.example.json · Check it: python validate.py terms terms.example.json

connector-manifest.example.jsonthe one source it will read, as carried inside the terms
{
  "protocol": "saacip/0.1",
  "id": "api-logs",
  "kind": "file",
  "version": "1.0.0",
  "signals": [
    "logs"
  ],
  "scopes": [
    "read"
  ],
  "data_location": "a log file on a volume mounted into the capability; read in place",
  "auth": "file system permission (read-only mount)"
}

Schema: connector-manifest · File: connector-manifest.example.json · Check it: python validate.py connector-manifest connector-manifest.example.json

enrol-request.example.jsonPOST enrol/: the token, the versions it speaks, and the terms
{
  "enrolment_token": "enrol_8yQm...shown-once-by-the-hub",
  "protocol_versions": [
    "saacip/0.1"
  ],
  "profile": "resident",
  "version": "1.0.0",
  "terms": {
    "protocol": "saacip/0.1",
    "profile": "resident",
    "kind": "trial",
    "term": {
      "days": 14
    },
    "autonomy_ceiling": 2,
    "dry_run": false,
    "connectors": [
      {
        "protocol": "saacip/0.1",
        "id": "api-logs",
        "kind": "file",
        "version": "1.0.0",
        "signals": [
          "logs"
        ],
        "scopes": [
          "read"
        ],
        "data_location": "a log file on a volume mounted into the capability; read in place",
        "auth": "file system permission (read-only mount)"
      }
    ],
    "data_leaving": "work item summaries (redacted) to the hirer's help desk; nothing else",
    "model": "offline",
    "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
    "environment": "prod-eu"
  }
}

Schema: enrol-request · File: enrol-request.example.json · Check it: python validate.py enrol-request enrol-request.example.json

enrol-response.example.json201: the credential and the settings

agent_token is shown once. settings.autonomy_level: 2 with a ceiling of 2 gives an effective level of 2.

{
  "protocol": "saacip/0.1",
  "profile": "resident",
  "agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd",
  "agent_token": "agent_Qe4c7v1Zr0VJ2bq9tN6yXw3kHf8sLp5uYa1dC0mGiE",
  "settings": {
    "autonomy_level": 2,
    "hire_kind": "trial",
    "trial_days": 14,
    "poll_seconds": 60
  }
}

Schema: enrol-response · File: enrol-response.example.json · Check it: python validate.py enrol-response enrol-response.example.json

receipt: hire_startedthe first line of the chain, carrying the full terms
{
  "body": {
    "expires": 1794474000,
    "hire_id": "hire-74804b49c3",
    "terms": {
      "autonomy_ceiling": 2,
      "connectors": [
        {
          "auth": "file system permission (read-only mount)",
          "data_location": "a log file on a volume mounted into the capability; read in place",
          "id": "api-logs",
          "kind": "file",
          "protocol": "saacip/0.1",
          "scopes": [
            "read"
          ],
          "signals": [
            "logs"
          ],
          "version": "1.0.0"
        }
      ],
      "data_leaving": "work item summaries (redacted) to the hirer's help desk; nothing else",
      "dry_run": false,
      "environment": "prod-eu",
      "kind": "trial",
      "model": "offline",
      "profile": "resident",
      "protocol": "saacip/0.1",
      "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
      "term": {
        "days": 14
      }
    }
  },
  "id": "rcpt-49f23486900f",
  "kind": "hire_started",
  "prev": "0000000000000000000000000000000000000000000000000000000000000000",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "purpose": {
    "autonomy_level": 2,
    "environment": "prod-eu",
    "kind": "trial",
    "why": "hire"
  },
  "signature": "hcG1oUeh+BS36E6yEMZsY51/ADBgpNgtqAYRAkCxFZXJ1+eE9aS0JW7EWds25m5PUNHWkxLHGmJ/5fwG8+7KCA==",
  "ts": 1793264400
}

Line 1 of 7 in receipt.example.jsonl. Its prev is 64 zeros: the first line of the chain. Stored as one canonical JSON line; shown here indented. Schema: receipt.

receipt: enrolledthe hub accepted
{
  "body": {
    "agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd",
    "hub": "https://acme.hub.example.com/saacip/",
    "protocol": "saacip/0.1"
  },
  "id": "rcpt-505f36f31b33",
  "kind": "enrolled",
  "prev": "5e3d14813ffc33a2e7846524ca121236e44818934ce982a19838b23680fe54fd",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "purpose": {
    "why": "hire"
  },
  "signature": "321CcQlVLwcJUi5Bzy08N1muqdkUERGJhtDw+ow6u4UZg2ceR69DZiuV7fNcMSVW0/YwMwFD+UEOKfjxKv6+Dw==",
  "ts": 1793264401
}

Line 2 of 7 in receipt.example.jsonl. Its prev is the SHA-256 of line 1 as stored. Stored as one canonical JSON line; shown here indented. Schema: receipt.

2Heartbeat

The capability, every few minutes.

A heartbeat tells the hub the capability is alive, how each connector is doing, the current counts, and the hash of its latest receipt line, so the hub holds a checkpoint of the chain. The reply carries the hirer's current settings, which is how a person lowering the autonomy level at the hub reaches the capability within minutes, and release_requested.

heartbeat.example.jsonPOST heartbeat/: health, counters, receipt_head

This particular heartbeat was sent after step 4: its counters show one item reported and one approval awaiting, and receipt_head is the hash of line 4 of the chain.

{
  "status": "ok",
  "connectors": [
    {
      "id": "api-logs",
      "kind": "file",
      "ok": true,
      "detail": "read 1,204 lines in the last minute"
    }
  ],
  "counters": {
    "findings": 1,
    "reported": 1,
    "judged": 0,
    "real": 0,
    "false_alarms": 0,
    "share_real": null,
    "actions": {
      "awaiting": 1
    }
  },
  "receipt_head": "6e2a78590e39407150dee55d3d66bfa7ebb97b8639ed561f3e8183830cdc9de7",
  "hire": {
    "id": "hire-74804b49c3",
    "kind": "trial",
    "status": "active",
    "expires": 1794474000.0
  }
}

Schema: heartbeat · File: heartbeat.example.json · Check it: python validate.py heartbeat heartbeat.example.json

heartbeat-response.example.json200: the settings as they stand now
{
  "settings": {
    "autonomy_level": 2,
    "hire_kind": "trial",
    "trial_days": 14,
    "poll_seconds": 60
  },
  "release_requested": false
}

Schema: heartbeat-response · File: heartbeat-response.example.json · Check it: python validate.py heartbeat-response heartbeat-response.example.json

3Report

The capability, when it finds something. A person at the hub sees a ticket.

At 09:15 the connector reads 22 new lines like the record below: a database connection pool exhausted, a pattern never seen before in api. The capability gives the finding a ref, wi-5516e077e5, and reports it with PUT work-items/wi-5516e077e5/. The hub opens ticket TKT-2026-0042 and answers with that number. Because the ref is the capability's own, sending the same report again after a network failure would add nothing: the hub already knows the ref.

record.example.jsonone line read from the log, in the shape every connector uses
{
  "ts": 1793265292.0,
  "source": "api-logs",
  "service": "api",
  "kind": "log",
  "level": "ERROR",
  "body": "database connection pool exhausted after 30s (active=50, request_id=9f3c1a)",
  "attributes": {
    "pod": "api-7d9f6b5c4-x2k8q",
    "version": "2.4.1"
  }
}

Schema: record · File: record.example.json · Check it: python validate.py record record.example.json

report.example.jsonPUT work-items/<ref>/: subject, description, priority
{
  "subject": "[prod-eu] A new error pattern in api",
  "description_html": "<p>A new error pattern in api, seen 22 times in one minute.</p><p><b>Likely cause:</b> started shortly after the deploy of 2.4.1.</p>",
  "priority_level": 3
}

Schema: report · File: report.example.json · Check it: python validate.py report report.example.json

report-response.example.json201: the hub's own reference for the item
{
  "hub_ref": "TKT-2026-0042",
  "status": "open",
  "created": true
}

Schema: report-response · File: report-response.example.json · Check it: python validate.py report-response report-response.example.json

receipt: work_item_reportedwhat was found, what was decided, and the hub's reference

The receipt records the evidence and the explanation, and that the decision was await_approval: the next step.

{
  "body": {
    "created": true,
    "decision": "await_approval",
    "evidence": [
      {
        "count": 22,
        "kind": "new_error",
        "level": "ERROR",
        "template": "database connection pool exhausted after <NUM><UNIT> (active=<NUM>, request_id=<HEX>)"
      }
    ],
    "explanation": {
      "by": "offline",
      "confidence": "medium",
      "headline": "A new error pattern in api",
      "likely_cause": "started shortly after the deploy of 2.4.1"
    },
    "hub_ref": "TKT-2026-0042",
    "service": "api"
  },
  "id": "rcpt-fbe0ab16ddff",
  "kind": "work_item_reported",
  "prev": "f8e90402e8173150a0daea7c5485046e1dc5018e7cbcaf26f666e2a9a5318f9a",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "purpose": {
    "autonomy_level": 2,
    "ref": "wi-5516e077e5",
    "why": "monitoring"
  },
  "signature": "vUnFGjfoJuC3OdhQI4pBPNXgjwyUaVmzP5/W7aXFEvFwuQB1NJPC8yL7vi6B53U8A5ZuwkRl2QA5jamNQsCKAg==",
  "ts": 1793265301
}

Line 3 of 7 in receipt.example.jsonl. Its prev is the SHA-256 of line 2 as stored. Stored as one canonical JSON line; shown here indented. Schema: receipt.

4Ask for approval

The capability asks; a person at the hirer decides.

The declared actions file has restart-api, whose match includes "connection pool exhausted" and whose services include api. The effective level is 2, so the capability may not run it alone: it sends an approval request with its own action_id, act-3f9a1c2b7d. The hub answers with the approval in state pending; a hub that is a help desk might also note it on the ticket. At 09:41 the on-call engineer approves it at the hub.

approval-request.example.jsonPOST approvals/: which action, for which work item
{
  "action_id": "act-3f9a1c2b7d",
  "ref": "wi-5516e077e5",
  "action": "restart-api",
  "summary": "Rolling restart of the api service"
}

Schema: approval-request · File: approval-request.example.json · Check it: python validate.py approval-request approval-request.example.json

receipt: approval_requestedthe ask, with the action's reversibility on record
{
  "body": {
    "action": "restart-api",
    "action_id": "act-3f9a1c2b7d",
    "reversible": true
  },
  "id": "rcpt-e07cb4d8bd85",
  "kind": "approval_requested",
  "prev": "e73cc733a7db6aac15dcf75a9727b9d29d71ace9545d9e03ce9cd83a86fd1552",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "purpose": {
    "ref": "wi-5516e077e5",
    "why": "remediation"
  },
  "signature": "xGe8jzLu0V4Jb389MDrRulg7Vj6W7wKgaVpWXGgYoKfs7jtbSVHblvKrxdEB3DAC4fn1kKOGevR63D4q/5LQCg==",
  "ts": 1793265302
}

Line 4 of 7 in receipt.example.jsonl. Its prev is the SHA-256 of line 3 as stored. Stored as one canonical JSON line; shown here indented. Schema: receipt.

approval.example.jsonthe hub's record of the approval, once decided

The 201 reply to the request has the same shape with status: pending and decided_by null. This is how it looks after the engineer approved.

{
  "id": "7",
  "action_id": "act-3f9a1c2b7d",
  "ref": "wi-5516e077e5",
  "action": "restart-api",
  "summary": "Rolling restart of the api service",
  "status": "approved",
  "decided_by": "on-call engineer",
  "decided_at": "2026-10-29T09:41:07Z"
}

Schema: approval · File: approval.example.json · Check it: python validate.py approval approval.example.json

5Decisions come back

The capability collects its inbox; the hub hands over what people decided.

The capability never receives a call. It asks the hub, every poll_seconds, for its inbox: approvals that were decided, outcomes that people recorded, and whether the hirer has asked it to finish. Here the inbox carries the approved action and, because the engineer later resolved the ticket as real, an outcome for the work item; in the real timeline these arrived in two collections, 09:41 and 10:31, and are shown as one inbox for brevity. Each item stays in the inbox until the capability acknowledges it, and applying one twice has no further effect.

inbox.example.jsonGET inbox/: an approval decided, an outcome recorded, no release
{
  "approvals": [
    {
      "id": "7",
      "action_id": "act-3f9a1c2b7d",
      "ref": "wi-5516e077e5",
      "action": "restart-api",
      "summary": "Rolling restart of the api service",
      "status": "approved",
      "decided_by": "on-call engineer",
      "decided_at": "2026-10-29T09:41:07Z"
    }
  ],
  "outcomes": [
    {
      "ref": "wi-5516e077e5",
      "outcome": "real",
      "action_worked": true,
      "note": "pool too small after the 2.4.1 deploy",
      "hub_ref": "TKT-2026-0042",
      "hub_status": "resolved"
    }
  ],
  "release_requested": false
}

Schema: inbox · File: inbox.example.json · Check it: python validate.py inbox inbox.example.json

outcome.example.jsona person's judgement: real, and the action worked

A hub only sends an outcome a person made. A ticket closed with nothing said produces none.

{
  "ref": "wi-5516e077e5",
  "outcome": "real",
  "action_worked": true,
  "note": "pool too small after the 2.4.1 deploy",
  "hub_ref": "TKT-2026-0042",
  "hub_status": "resolved"
}

Schema: outcome · File: outcome.example.json · Check it: python validate.py outcome outcome.example.json

6Act and learn

The capability runs the action, learns from the judgement, and acknowledges both.

Before running an approved action the capability re-checks its limits: the level is still 2 or more, restart-api is still in the file, and it has not already run twice today. All true, so it runs the command, without a shell, with {service} filled with api, and writes an action_taken receipt naming the approver. It then applies the outcome (how it learns from it is its own affair; this one records a weight before and after in the receipt body) and acknowledges both inbox items so they are not sent again.

A receipt, annotated

A receipt, annotated{  "id": "rcpt-64c55d295ef2",  "ts": 1793266870,  "kind": "action_taken",  "purpose": {"why": "remediation", "ref": "wi-5516e077e5",              "approved_by": "on-call engineer"},  "body": {"action_id": "act-3f9a1c2b7d",           "action": "restart-api",           "argv": ["kubectl", "rollout", "restart", ...],           "dry_run": false, "returncode": 0, ...},  "prev": "6e2a78590e39407150...dc9de7",  "public_key": "3RsIo8MiE66DyZ...LfkNc=",  "signature": "7+KKv9iewBDoND...dVAw=="}Identity and timeunique within the hire; seconds since 1970, to themillisecond (section 4.5)What happenedone of the fifteen core kinds (section 7.3), or aprivate kindWhy, and under what permissionthe work item it belongs to and the person whoapproved itWhat was donethe action, the exact command, and its resultThe chainSHA-256 of the previous line as stored; 64 zerosfor the firstThe signatureEd25519 over the canonical JSON of everythingabove it, with the key from the terms

The action_taken line from receipt.example.jsonl, shortened. Each line in the file is one receipt in canonical JSON; the signature verifies with the public key, and prev ties it to the line before. Open full size

receipt: action_takenthe command that ran, its result, and who approved it

Compare it with the picture above. purpose.approved_by is the person; body.argv is the exact command.

{
  "body": {
    "action": "restart-api",
    "action_id": "act-3f9a1c2b7d",
    "argv": [
      "kubectl",
      "rollout",
      "restart",
      "deployment/api",
      "-n",
      "prod"
    ],
    "dry_run": false,
    "returncode": 0,
    "stdout_sha256": "8c9d5ac0eb2ac4c9bbbb6b813ffb32e764b1d0db9a397ed32a0207970957c558"
  },
  "id": "rcpt-64c55d295ef2",
  "kind": "action_taken",
  "prev": "6e2a78590e39407150dee55d3d66bfa7ebb97b8639ed561f3e8183830cdc9de7",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "purpose": {
    "approved_by": "on-call engineer",
    "ref": "wi-5516e077e5",
    "why": "remediation"
  },
  "signature": "7+KKv9iewBDoNDaELmsY0PGrnjXZrnIZs7TuVBIJEZaRMRItX8kT2Wj/vpfKahyLVDyJmo718SQpV3tqIHdVAw==",
  "ts": 1793266870
}

Line 5 of 7 in receipt.example.jsonl. Its prev is the SHA-256 of line 4 as stored. Stored as one canonical JSON line; shown here indented. Schema: receipt.

receipt: feedback_appliedthe judgement applied: the capability learned
{
  "body": {
    "action_worked": true,
    "outcome": "real",
    "weight_after": 1.1,
    "weight_before": 1
  },
  "id": "rcpt-21bedbe059f9",
  "kind": "feedback_applied",
  "prev": "94645efba7528860ab8075d3ac284b8018760c7751719a1c3464cda0abc6c1c8",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "purpose": {
    "ref": "wi-5516e077e5",
    "why": "learning"
  },
  "signature": "kWddzB8wnvHZmioRXr9ITdCBqryzF+hXMvZbHnl1RTnyU/RdoBXjAmtfhDEIXKkYRFl1wwgsLj0wGOMAUNEFBA==",
  "ts": 1793269860
}

Line 6 of 7 in receipt.example.jsonl. Its prev is the SHA-256 of line 5 as stored. Stored as one canonical JSON line; shown here indented. Schema: receipt.

ack.example.jsonPOST inbox/ack/: the approval id and the outcome ref applied
{
  "approvals": [
    "7"
  ],
  "outcomes": [
    "wi-5516e077e5"
  ]
}

Schema: ack · File: ack.example.json · Check it: python validate.py ack ack.example.json

ack-response.example.json200: how many of each the hub marked delivered
{
  "approvals": 1,
  "outcomes": 1
}

Schema: ack-response · File: ack-response.example.json · Check it: python validate.py ack-response ack-response.example.json

7The statement

The capability, at the end. The hirer reads it.

On day 14 the trial ends. The capability builds its statement from its own receipts: one finding, one reported, one judged real, one action done. It sends it with final: true, the hub marks the hire ended, and the capability writes its last receipt and goes idle. The statement is what a review, a renewal or a bill is based on, and what a registry would turn into a track record. Every number in it can be recomputed from the receipts.

statement.example.jsonthe account of the hire, from its own records
{
  "hire_id": "hire-74804b49c3",
  "kind": "trial",
  "reason": "trial term ended",
  "track_record": {
    "findings": 1,
    "reported": 1,
    "judged": 1,
    "real": 1,
    "false_alarms": 0,
    "share_real": 1.0,
    "actions": {
      "done": 1,
      "dry_run": 0,
      "failed": 0,
      "rejected": 0,
      "refused": 0,
      "awaiting": 0
    }
  }
}

Schema: statement · File: statement.example.json · Check it: python validate.py statement statement.example.json

statement-request.example.jsonPOST statement/: the statement, final
{
  "statement": {
    "hire_id": "hire-74804b49c3",
    "kind": "trial",
    "reason": "trial term ended",
    "track_record": {
      "findings": 1,
      "reported": 1,
      "judged": 1,
      "real": 1,
      "false_alarms": 0,
      "share_real": 1.0,
      "actions": {
        "done": 1,
        "dry_run": 0,
        "failed": 0,
        "rejected": 0,
        "refused": 0,
        "awaiting": 0
      }
    }
  },
  "final": true
}

Schema: statement-request · File: statement-request.example.json · Check it: python validate.py statement-request statement-request.example.json

statement-response.example.json200: the hire is ended
{
  "status": "ended"
}

Schema: statement-response · File: statement-response.example.json · Check it: python validate.py statement-response statement-response.example.json

receipt: hire_endedthe last line of the chain, carrying the final statement
{
  "body": {
    "hire_id": "hire-74804b49c3",
    "statement": {
      "hire_id": "hire-74804b49c3",
      "kind": "trial",
      "reason": "trial term ended",
      "track_record": {
        "actions": {
          "awaiting": 0,
          "done": 1,
          "dry_run": 0,
          "failed": 0,
          "refused": 0,
          "rejected": 0
        },
        "false_alarms": 0,
        "findings": 1,
        "judged": 1,
        "real": 1,
        "reported": 1,
        "share_real": 1
      }
    }
  },
  "id": "rcpt-d381990ce7de",
  "kind": "hire_ended",
  "prev": "0744c1df41fc964748b04e1c5812471c19138694ed0751c7010141d71a00ffd7",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "purpose": {
    "reason": "trial term ended",
    "why": "hire"
  },
  "signature": "RGQNujw0bllR9M/sxhMPfO0Sy4PeMIrx9AeoKpSHOwXdcIUYvgFbaKAZ1hlLA210LGHDUzpz2+DvVkQabzJmBA==",
  "ts": 1794474000
}

Line 7 of 7 in receipt.example.jsonl. Its prev is the SHA-256 of line 6 as stored. Stored as one canonical JSON line; shown here indented. Schema: receipt.

8When things go wrong

The hub answers every error the same way.

Every error is RFC 9457 problem details: a type URI from the list of problem types, an HTTP status, a title and a detail. A capability acts on the type and the status, never on the wording. Two cases worth knowing: a refusal at enrolment (wrong version, terms that disagree with the hire, an extension the hub does not understand) never uses up the enrolment token; and a 401 is retried once before the capability concludes it has been revoked and ends the hire on its own side.

problem.example.json400: none of the offered versions is supported
{
  "type": "https://thesoftwarelens.com/saacip/0.1/errors/#unsupported-version",
  "title": "Unsupported version",
  "status": 400,
  "detail": "None of the offered protocol versions is supported.",
  "supported": [
    "saacip/0.1"
  ]
}

Schema: problem · File: problem.example.json · Check it: python validate.py problem problem.example.json

Important notice. This page is part of my ongoing research into the Agentic Economy and reflects my thinking at the time of writing. It is shared in good faith, for information and discussion. It is not legal, regulatory, technical, financial or other professional advice, and it is not a verdict on how the EU AI Act or any other law applies to any organisation, system or situation. Laws, guidance, technology and my own research all move on, and others may reach different conclusions. The examples, designs, diagrams and technology choices show one possible approach. Before relying on, adapting or applying any part of it in your own situation, you must test and verify it, design it for your own architecture, and take independent expert advice, including from qualified lawyers and from your own IT, security and data protection specialists. Any decision to act on it, and its consequences, rest with you. To the fullest extent permitted by law, the author accepts no responsibility or liability for any loss, damage or consequence arising from any use of, or reliance on, this page, which is provided without any warranty of accuracy, completeness or fitness for a particular purpose. Reading it does not create a professional or advisory relationship with the author. The views expressed are the author’s own.