Factory docs, home
Page navigation

Scope: One pure committed Branch health poll projection. Build review records accepted snapshots and current verification gates. Separate private subscriptions handle lifecycle and verification; live MCP hosting and application delivery remain unqualified.

Intelligence: none — Source pins, current permission values and bounded notification fields are exact rules; a model would add authority and leak source data.

Public boundary

software-factory/provider-events exports projectBranchHealthPoll, branchHealthPollPayloadDigest, parseProviderEventFilter, parseProviderEventNotification, ProviderEventError, the frozen profile/limits and their types. Inputs are exact plain data, outputs deeply frozen copies. The projector has no callbacks, store, clock, transport or model. Its runtime closure is provider-events, provider-events-contract, strict-input, canonical-json and errors; builtins buffer/crypto only. ProductState is type-only from branch-health-contract; no polling or Journal runtime is loaded.

A pinned committed JournalEvent is accepted only for branch-health.polled, index 0, exact Product aggregate/command and five data fields. At equals pollId and is the actual recorded poll-start instant. The host owns source authenticity. Hashing an arbitrary object is not commit proof. The full event payload digest includes local sequence/version and is distinct from snapshot and notification digests.

The occurrence identity binds persistent producer/store, domain, aggregate, command/index and projection version. Trusted host ownership must keep these namespaces exclusive and durably refuse different payload/notification digests under an existing occurrence. The pure function cannot detect conflicts across calls, deduplicate or acknowledge delivery. Reset or divergent stores need new IDs. Quiet unchanged suppression does not promise no duplicates or complete coverage.

Current permission is an explicit host-supplied value bound to principal, producer/store/Product/profile and the caller's asOf. CheckedAt equality enforces only the declared checking instant; authentication and real freshness are host responsibilities. Deny refuses, unknown/stale is unavailable. Filter Product must match; states are a bounded allowlist and includeUnchanged defaults false. Source/permission validation precedes quiet filtering.

Output, refusals and history

Notifications contain one domain state/change/snapshot pin, exact poll-start time, scoped identity, source digest and a non-bearer detail handle. They contain no raw journal row, repository/provider text, URL/path, principal, permission or cursor. Detail access needs fresh host authorisation and the original historical poll event; current state cannot reconstruct an old source snapshot. No endpoint is provided.

Whole input 16 KiB, output 8 KiB, depth 16; one event/Product and at most three states. IDs 1–63 lowercase alphanumeric/hyphen; exact UTC millisecond timestamps 2000–2999. Accessors, non-JSON/exotic data, extra fields and unsupported families/profiles refuse, never truncate. Failures are fixed redacted ProviderEventError codes/reasons, not source text. Boundary validation is not a hostile Proxy sandbox.

The fixed-v1 notification parser checks shape, identity and digest without current time or permission. It does not authenticate self-consistent bytes or grant access. Retain the original pinned source for source verification. New semantics require a new profile/event identity with old readers preserved. Existing Branch health /2, Journal bytes, Factory facade, D4 and Knowledge are unchanged.

Source: docs/agents/provider-events.md