Records handed to another organization

Northwind Robotics' agent processed a set of documents for Acme under a contract. Acme's operations team wants to know what was done, when, and by what, and they do not want to take Northwind's word for it. Northwind records the work and hands Acme a link. Acme checks it, keeps it, and says so.

Northwind records the work#

One record for the job. The first entry names it and carries the fingerprint of the work order. One entry per document processed, each carrying the fingerprint of the output that was delivered. A close when the job is done.

const record = `acme-job-${jobId}`;

await pac.records.emit({
  record,
  title: `Document job ${jobId} for Acme, 18 September`,
  kind: 'job',
  occurredAt: startedAt,
  actorId: 'doc-agent-1',
  instructedBy: 'acme-work-order-771',
  payloads: [await fingerprint(workOrderBytes)],
  idempotencyKey: `${record}:open`,
});

for (const doc of processed) {
  await pac.records.emit({
    record,
    title: `Processed ${doc.name}`,
    kind: 'document',
    occurredAt: doc.finishedAt,
    actorId: 'doc-agent-1',
    instructedBy: 'acme-work-order-771',
    payloads: [await fingerprint(doc.outputBytes)],
    idempotencyKey: `${record}:${doc.id}`,
  });
}

await pac.records.emit({
  record,
  title: `Job ${jobId} delivered: ${processed.length} documents`,
  kind: 'job-close',
  lifecycle: 'closed',
  occurredAt: deliveredAt,
  actorId: 'doc-agent-1',
  instructedBy: 'acme-work-order-771',
  payloads: [await fingerprint(manifestBytes)],
  idempotencyKey: `${record}:close`,
});

Acme receives the outputs the ordinary way, by whatever channel the contract uses. The record carries their fingerprints, never the files.

Northwind shares it#

curl -X POST https://app.pacspace.io/api/v1/records/machine-action-record/acme-job-771/share \
  -H "x-api-key: $PACSPACE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "sharedWith": "Acme", "expiresInDays": 90 }'

The link goes in the delivery email. The code goes to Acme's contact by phone. Anyone at Acme with both can open the record for 90 days.

Acme checks it#

Acme's engineer opens the link and enters the code. The check runs in her browser and the first sentence tells her the count and that every entry matches what was committed. She opens the entries for the documents she cares about, sees each one's fingerprint, drops the file Acme received onto the page, and reads "This file matches an entry in the record." She does this for a few, then for all of them.

Nothing in that check asked Northwind or PacSpace whether the record was fine. Her browser recomputed the seals.

Acme keeps it#

She presses "Download history" and files the history file with the contract. She presses "Print a statement" once the daily statement covers the job, and files the page with it. The statement names the record, the count, the day, and the fingerprint of the history file she kept.

A year later, when the link has long expired, Acme's auditor runs:

npx @pacspace-io/check history.json --fingerprint 0x7079b0ac...

and gets the same check, without the link, without an account, and without PacSpace.

Acme puts its check on record#

She presses "Record that you checked this". The record now carries, for Northwind and for anyone else Northwind shares it with: "Acknowledged through the link issued to Acme, 18 September. Entry 24 was checked and it matched." Both sides now hold a record of the handover and a record of the check.

If Acme's systems do the checking#

When the receiving side is software, Northwind issues a grant instead of a link: POST .../grants with kind: "BEARER", a number of hours, and a use limit. Acme's system reads the history with ?grant= and no key of Northwind's, runs records.check or the checker, and stores the result. See Share a record.

What each side has#