Walkthrough: verify a hook release seal

Can you prove, byte for byte, that a hook release is exactly what was sealed — and when it is not, name the file that changed? This walkthrough does both, read-only, against a real sealed release: the one installed on this machine under ~/Library/Application Support/Tama/hooks-runtime/releases/. Every command below was executed with tama hooks integrity; outputs are shown as the command prints them, with that release directory abbreviated to $R and the identifiers of one machine's release written as placeholders: <release id> for the sealed digest, <drifted digest> for a digest that differs from it, <commit> for the source revision and <sealed at> for the seal's time. The identity model is concepts/seal; the command is in scripts.

#1. Read the seal

The manifest at the release root records the identity the tree must digest to:

$ cat "$R/release.json"
{
  "catalogUpdatedAt": "<catalog time>",
  "catalogVersion": 1,
  "packageVersion": "<version>",
  "releaseId": "<release id>",
  "schema": "ai.wisent.tama.hook-release.v1",
  "sealedAt": "<sealed at>",
  "sourceDirty": false,
  "sourceRevision": "<commit>"
}

releaseId is the SHA-256 tree digest over every file except release.json and bin/ — relative path, permission bits, and bytes, each length-framed (concepts/seal).

#2. Verify the intact release

$ tama hooks integrity --release "$R"
release root: $R
recorded releaseId: <release id>
actual tree digest: <release id>
sealed at: <sealed at>
source revision: <commit>
source dirty: false
result: intact
$ echo $?
0

The digest is the one the installer computes, so an intact report is the installer's own verdict.

#3. Drift one byte and catch it

Work on a mtime-preserving copy — never edit a real release directory (hook-releases):

$ cp -pR "$R" walk1
$ printf '\n' >> walk1/shared-hooks/omp-shared-hooks.js
$ tama hooks integrity --release walk1
release root: walk1
recorded releaseId: <release id>
actual tree digest: <drifted digest>
sealed at: <sealed at>
source revision: <commit>
source dirty: false
result: DRIFTED
written after the seal:
  shared-hooks/omp-shared-hooks.js
$ echo $?
1

One appended newline changed the whole identity, and the report names the one file written after the seal. The installer meeting this tree would refuse with Bundled Tama hook release failed its integrity check (runbook); this walkthrough is how you find out which file earned that refusal.

#4. Drift a permission bit and catch that too

The digest covers each file's mode, so a chmod with identical bytes is still drift — the case least likely to be guessed from a byte-comparison mental model:

$ cp -pR "$R" walk2
$ chmod 755 walk2/shared-hooks/registry.json
$ tama hooks integrity --release walk2
release root: walk2
recorded releaseId: <release id>
actual tree digest: <drifted digest>
sealed at: <sealed at>
source revision: <commit>
source dirty: false
result: DRIFTED
no file is newer than the seal -- the drift is a permission change, a deletion, or a file whose timestamp was preserved on copy
$ echo $?
1

No file is newer than the seal, and the report says exactly what that means: the drift is a mode change, a deletion, or a timestamp-preserving copy — mtime cannot attribute it, but the digest still refuses it.

#5. What to do with a real mismatch

Nothing in a release directory is repairable in place: the recovery for a genuinely drifted release is reinstalling the same verified app artifact (operations). To check what is already installed under ~/Library/Application Support/Tama, continue with walkthrough-runtime-status.