feat(coven): page one automation's occurrence history

[BunsDev]

Part of #80: the per-automation occurrence history read, which is the last Phase 1 read. The producer side is OpenCoven/coven#1158 (closes coven#1157).

What

• automations.occurrenceHistory(automationId, { limit?, cursor? }, options?)
  • Calls the capability-gated coven.automations.occurrence.history.v1 action.
  • Returns an sdk-core Page: { automationId, data, cursor: { hasMore, current?, next? } }.
  • Covers every state, newest first by scheduledFor then id.
• automations.iterateOccurrenceHistory(automationId, BoundedPageOptions)
  • Built on sdk-core iteratePages, so it needs maxPages or a caller-owned signal.
  • It refuses non-advancing cursors, and timeoutMs bounds the whole walk.
• Transport allowlist: definitionReadBytes now allows nine actions. The history request is exactly { action, automationId (trimmed, ≤4096 B, well-formed), limit 1–100, cursor? }, and the cursor must be canonical unpadded base64url of at most 512 characters, the same rule normalizePageOptions applies.
• Response validation. A page is refused when:
  • it names a different automation, or a row names another automation;
  • it holds more than limit rows, or repeats a row;
  • rows are not strictly newest first (compared by byte order, as SQLite orders them);
  • hasMore comes without a fresh next, or on a short page;
  • next comes without hasMore, or the cursor has unknown fields;
  • the requested cursor is not echoed as current, or current appears on a first page.
• Byte cap. History responses get their own 256 KiB cap on both the Unix and Windows transports. 100 realistic records run to about 45 KiB, so the shared 16 KiB cap would have failed any limit above roughly 35.
• README, API baseline and a Changeset (minor) are included.

Verification

• pnpm verify passed (typecheck, 3033 tests, contracts, package, coverage, stress). Lint was fixed afterwards; lint, typecheck and the automations specs were re-run and are green.
• Mutation checks: removing the ordering check fails "rows oldest first"; removing the current echo check fails 3 cases.
• Platform parity: a 100-row page over 16 KiB reads on both Unix and Windows, and Content-Length: 262145 yields body_limit.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🔵 Needs a closer look

Normalize the automation ID before byte-limit validation and update the README action list.

Review effort: Lite
Findings: None

What changed in this PR

Adds paginated occurrence-history reads and bounded iteration for Coven automations, with validation, transport limits, tests, documentation, and API updates.

Changes:

• Adds occurrenceHistory() and iterateOccurrenceHistory().
• Adds cursor, ordering, identity, and response validation.
• Adds 256 KiB Unix/Windows transport support.
• Updates exports, tests, documentation, API declarations, and changeset.

File	Description
tests/​coven-automations.spec.ts	Tests history behavior and validation.
tests/​coven-automations-platforms.spec.ts	Tests platform parity and byte caps.
packages/​coven/​src/​index.ts	Exports history types.
packages/​coven/​src/​automations.ts	Adds history APIs.
packages/​coven/​src/​automations-socket.ts	Applies history response limits.
packages/​coven/​src/​automations-occurrences.ts	Defines history types and page validation.
packages/​coven/​src/​automations-definitions.ts	Adds request/response support and size validation.
packages/​coven/​README.md	Documents the new APIs and transport allowlist.
api-baselines/​coven.d.ts	Updates public declarations.
.changeset/​coven-occurrence-history.md	Records the minor release.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.