wehub-resource-sync
76 lines
2.6 KiB
Markdown
76 lines
2.6 KiB
Markdown
# Performance Notes
|
|
|
|
## Attestation SHA cache
|
|
|
|
When plan attestation is enabled, the hooks compare the approved SHA-256 hash
|
|
with the current `task_plan.md` before injecting plan content. v2.40.0 added a
|
|
small transient cache for that hash calculation.
|
|
|
|
### Location
|
|
|
|
The cache lives under the first of these that resolves:
|
|
|
|
```bash
|
|
$XDG_CACHE_HOME/pwf-sha/ # when XDG_CACHE_HOME is set
|
|
$HOME/.cache/pwf-sha/ # otherwise, when HOME is set
|
|
${TMPDIR:-/tmp}/pwf-sha/ # fallback only when neither is set
|
|
```
|
|
|
|
v2.40.0 introduced the cache under `${TMPDIR:-/tmp}/pwf-sha/`. v3.0.0 moved it to
|
|
the user-private path above so a world-writable `/tmp` can no longer be used to
|
|
poison the attestation hash. Each cache entry stores the plan file mtime on the
|
|
first line and the computed SHA-256 on the second line.
|
|
|
|
### Keying
|
|
|
|
The cache key is the first 16 hex characters of the SHA-256 of the active plan
|
|
file path (the path string, not the file contents). Each plan location gets its
|
|
own entry:
|
|
|
|
```text
|
|
task_plan.md
|
|
.planning/<plan-id>/task_plan.md
|
|
```
|
|
|
|
The stored hash is reused only when the current plan file mtime matches the
|
|
cached mtime. If the file changes, the hook recomputes `sha256sum` or
|
|
`shasum -a 256` and rewrites the cache entry. In gated mode the hook always
|
|
recomputes on a hit, so the completion gate never trusts a stale entry.
|
|
|
|
### When it helps
|
|
|
|
The cache is most useful when:
|
|
|
|
- Plan files are large.
|
|
- Windows Git Bash process startup makes repeated `sha256sum` calls expensive.
|
|
- The same attested plan fires hooks many times in one session.
|
|
|
|
### When it is break-even
|
|
|
|
For small plan files, the cache may be roughly break-even. The hook still starts
|
|
shell commands, reads the cache entry, and checks the mtime. On those paths,
|
|
Bash process startup can dominate the actual hash cost.
|
|
|
|
### Containers and CI
|
|
|
|
The cache is per-user and transient. In a container `HOME` is usually set (for
|
|
example `/root`), so the cache lives at `$HOME/.cache/pwf-sha/`. Containers, CI
|
|
jobs, and sandboxes that do not persist `$HOME` across restarts lose the cache
|
|
between runs.
|
|
|
|
That only affects speed. A cache miss recomputes the SHA-256 from the current
|
|
plan file and preserves the same attestation behavior.
|
|
|
|
### Clear or avoid reuse
|
|
|
|
Clear the cache:
|
|
|
|
```bash
|
|
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/pwf-sha/"
|
|
```
|
|
|
|
There is no separate SHA-cache toggle, and overriding `TMPDIR` does not move the
|
|
cache when `HOME` is set. The cache self-invalidates whenever the plan file mtime
|
|
changes, so editing `task_plan.md` already forces a recompute. To force a clean
|
|
state explicitly, remove the directory above.
|