# A small factory integration reference

Laufwerk persists workflow execution. Your integration still owns queue ordering, external idempotency, and publication policy. Keep those concerns explicit rather than adding a second workflow database.

`receipts.ts` illustrates the external boundary using an atomic claim and a retained receipt. Run `bun test examples/factory-reference` from the Laufwerk repository. The tests need neither GitHub credentials nor the private to-do repository. The in-memory store is a test double: production claim/read/complete must be an external durable service with atomic claims. A pending receipt never proves that an operation failed.

Call `publishOnce` inside a named Effect Activity. Derive its key from business identity (for example `issue-3-initial`), not a random value generated during execution. The returned external PR identity is the Activity's result. If the connection is lost after publication, the pending receipt blocks a new publication; inspect the remote system before completing that receipt. A new local process or pruned local history cannot erase the external evidence.

For GitHub, use stable branch/PR identity and search for an existing PR/merge receipt before creating another. GitHub comments alone are not an atomic distributed lock. The to-do factory is deliberately a single host protected by `flock`; the same assumptions must hold if adapting its receipt pattern. This example does not claim arbitrary external APIs execute exactly once.

A single-host dispatcher follows these rules:

1. Reconcile the oldest unfinished run before considering new issues, including runs whose issues no longer match the label query.
2. A surviving worker lease is a queue barrier. A waiting human interaction or uncertain external outcome also pauses dispatch; repeatedly calling resume does not resolve either.
3. On a settled failed attempt, require an explicit new attempt key. Keep external completion/failure receipts beyond local runtime retention so an old issue does not look new.
4. Pin issue content, base SHA and candidate SHA. Run deterministic verification and independent review against that candidate. A negative review means repair; provider failure means a bounded fresh review, not repeating implementation.
5. Before merge, recheck author/label, issue content, base, candidate and every required CI result. Never silently rebase reviewed code or treat skipped checks as success.
6. Keep GitHub credentials on the host. Run candidate code and tests in the isolated workspace. Explicit write-back occurs only after verification/review, into an isolated checkout.
7. Remove completed staging directories. Retain active, uncertain and recent failed evidence; local cleanup must not reset external idempotency.

The local to-do factory has regression coverage for these rules and live restart-during-CI evidence. It is an application integration, not an extra core Laufwerk subsystem. Adapt the small receipt boundary and the invariants to your external API rather than copying an entire application.