# ZotFlow Enhancement Pack

ZotFlow Enhancement Pack is an optional companion plugin that supplies the
large, offline resources required by ZotFlow reading features such as
Structured Document Text generation.

The resource binaries are not tracked in Git. `npm run build` downloads the
exact Document Worker archive pinned by `document-worker.lock.json`, verifies
the downloaded archive, and appends the gzip/base64 data to
the released `main.js` as a marked comment trailer. The trailer includes a self-describing JSON resource directory and a fixed
112-byte v2 footer. The executable entry only tells users the Pack can remain
disabled; it contains no resource API or resource index.

## Development

```bash
npm install
npm run build
```

Downloaded archives and extracted resources are stored under `.cache/` and are
ignored by Git.

To synchronize from a ZotFlow checkout without changing the Pack version:

```bash
npm run sync:document-worker -- \
  --zotflow-lock ../document-worker.lock.json \
  --zotflow-commit local \
  --bump none
```

In CI, ZotFlow sends a `document-worker-updated` repository dispatch event.
The Pack workflow downloads the lock from that exact ZotFlow commit, updates
the Pack `dev` branch when necessary, creates the next stable patch commit and
tag, verifies a clean build, and creates a Draft Release. Publish that release
before merging the exact stable tag into Pack `master`.

Document Worker/resource changes are eligible for the automatic patch bump.
Only the current offline protocol is accepted. Unsupported
contracts stop the workflow. `sync` compares resource paths, sizes and existing
content digests, plus SDT output versions, against the source lock. Manual workflow
refs are resolved to an immutable ZotFlow commit before downloading the lock.

### Beta releases

`dev` is the only long-lived development branch. `master` contains only
published stable Pack versions. To preview or publish a manual Pack beta from a
clean, synchronized `dev` branch:

```bash
npm run beta:next -- patch
npm run beta -- patch
```

The publish command calculates the next `x.y.z-beta.N`, creates an annotated
tag, and pushes only the tag. The beta workflow writes prerelease versions only
inside its runner and publishes a non-draft prerelease.

ZotFlow beta releases also dispatch their exact compatibility contract to this
repository. If Pack `master` or an existing Pack beta is compatible, the request
is a no-op. Otherwise automation commits only the new resource lock to Pack
`dev`, creates the next beta patch tag with the same helper, and dispatches the
tag release workflow. No beta version commit or persistent beta branch is
created.

## Runtime contract

Install the Pack and keep it **disabled**. ZotFlow reads the installed
main.js through the vault adapter when an SDT resource is first needed. It
never enables or executes the Pack plugin to access its resources.

ZotFlow validates the v2 directory and exact Document Worker compatibility,
snapshots the compressed component, and decompresses requested resources in a
service inside its existing ZotFlow Worker, exposed through its existing Comlink bridge.
Document Worker consumers read the cached Blobs locally; the main thread creates
URLs only for consumers that need them. ZotFlow releases resources after their consumers
end. Updates never replace resources inside an existing Worker session.
There are no runtime downloads and no global registry.

The Pack version (currently 2.0.0) is separate from protocol 2.0 and the generated
document's SDT pack/schema versions. The Pack and
ZotFlow are developed and released against this single resource contract.

## Build and release verification

`npm run build` prepares pinned inputs, builds the offline container,
then runs `verify:pack` and `test:protocol`. All selected resources are read
back from the final main.js and checked against the lock before provenance
attestation or Draft Release creation. Stable tags create Draft Releases; beta
tags create non-draft prereleases.

Only ZIP downloads/cache reads and final resource verification scan binary
contents for integrity. Extracted cache preparation checks file existence and
size; packaging checks size. The single `postbuild` verification hashes each
decoded resource against its pinned digest. A same-size damaged cache therefore
fails final verification; regenerate the affected extracted cache before rebuilding.
Watch builds verify each output themselves.

The protocol uses three digest types: archive SHA-256 (build only), per-resource
SHA-256, and directory SHA-256 (also the runtime generation ID). It has no lock-file
or resource-list digest. ZotFlow compares resource metadata directly with its
pinned list and verifies each requested resource once, without a second CRC32
pass. With eight resources, a cached production build computes 10 SHA-256 digests
(excluding tests); initial runtime use of all resources computes nine.

The startup probe helper is a development experiment. Its generated probe
files intentionally contain filler, not a valid resource package, and must
not be published as release artifacts.