This private draft exposes software-factory/provider-events. It projects one committed Branch health poll into a small immutable notification after checking caller-supplied source pins, scope and current permission. It starts no listener, subscription, model call or delivery.
Use Node.js 26.8.1 or later and install the exact reviewed local tarball in an ESM application. The package has no runtime npm dependencies. Its public declarations need no Node type declarations. The Branch health guide and Command journal guide describe the optional source composition below; projection itself opens no store.
Project a real committed poll
This executable example records an unavailable source as unknown. Its fixed instant also lets you rerun the example as the same journal command. The permission value represents a decision your trusted host obtained from its authentication and access policy; this demonstration does not authenticate a real user.
import { CommandJournal } from 'software-factory/command-journal';
import { BranchHealth, aggregateOf } from 'software-factory/branch-health';
import {
branchHealthPollPayloadDigest, projectBranchHealthPoll,
PROVIDER_EVENT_PROFILE,
} from 'software-factory/provider-events';
const at = '2026-09-28T12:00:00.000Z';
const journal = CommandJournal.open('./health.sqlite');
try {
await new BranchHealth(journal, {
reader: { async get() { return { kind: 'failed', reason: 'unavailable' }; } },
watch: [{ productId: 'my-app', repository: 'my-team/my-app', branch: 'main' }],
now: () => Date.parse(at),
}).poll();
const event = journal.readHistory(aggregateOf('my-app'))
.find(row => row.type === 'branch-health.polled');
if (!event) throw new Error('Committed poll is unavailable');
const profile = PROVIDER_EVENT_PROFILE.id;
const result = projectBranchHealthPoll({
profile, asOf: at, principalId: 'reader',
source: {
protocol: 'sf-branch-health-polled-source/1',
producerId: 'my-application', storeId: 'health-primary',
event, payloadDigest: branchHealthPollPayloadDigest(event),
},
permission: {
protocol: 'sf-provider-event-permission/1',
principalId: 'reader', producerId: 'my-application',
storeId: 'health-primary', productId: 'my-app', profile,
checkedAt: at, decision: 'allow',
},
filter: { productId: 'my-app' },
});
if (result.kind === 'notification') {
console.log(result.notification.state, result.notification.timestampBasis);
}
} finally {
journal.close();
}
The only accepted source family is branch-health.polled, event index 0 of command branch-health/poll/<productId>/<pollId> in aggregate branch-health:product:<productId>. The exact source fields are pollId, at, state, changed and snapshotDigest. The source event must come from a trusted committed-store read. Merely constructing an object and computing its digest does not prove it was committed.
occurredAt is the recorded poll-start instant, equal to pollId and at. It is not failure onset, network completion, commit time or present health. Source instants must be canonical UTC with milliseconds from 2000 through 2999 and cannot exceed caller-supplied asOf. No current clock is read.
Own permission, identity and conflicts
The host must authenticate the principal, read current permission immediately before each projection and bind that decision to the exact producer, store, Product and profile. principalId, like producer, store and Product IDs, must match the Product-ID grammar: 1–63 lowercase letters, digits or hyphens, starting with a letter or digit. Hosts map their own principals into it. checkedAt must equal asOf. This checks the declared instant; it cannot prove that host policy is truthful or fresh. A deny refuses; unknown or stale permission is unavailable. Before later delivery, the host must check then-current permission again. A notification grants no dispatch or tool authority.
Producer and store IDs name persistent owned identities, never paths. Keep the same store ID only for the same immutable history. A reset, fork or independently writable clone needs another ID. The occurrence ID binds producer, store, domain, aggregate, command, index and projection version; a local sequence alone is not globally unique. Source and notification digests are separate. Repeated projection of one valid source returns identical notification bytes, including under another permitted principal or a later evaluation instant.
The projector is stateless. It cannot detect different, freshly self-pinned source bytes presented under the same identity in separate calls. Before publication, the trusted host must durably bind the occurrence ID to its source and notification digests, refuse conflicting bytes and preserve the original. The existing immutable source store and host-owned durable admission can provide that ownership. This module creates no ledger, deduplication service or acknowledgement.
Filter one Product and read detail safely
filter.productId is required and must match both source and permission. states defaults to red, unknown, green; an explicit list must contain one to three distinct states. includeUnchanged defaults to false. A state outside the filter returns suppressed with state-filter; otherwise an unchanged poll returns suppressed with unchanged. Malformed or unauthorised source data never becomes quiet suppression.
changed retains the domain's content comparison; it is not necessarily a health-state transition. Default quietness does not prevent duplicate notifications: repeated changed polls project the same occurrence again. Opting into unchanged polls exposes their separate poll IDs. Neither suppression nor a notification describes stream completeness, cursor progress, delivery or current health.
The detail handle contains logical source identity and the historical poll pin. It is not a URL or bearer credential. A future host detail reader must re-authorise current access and resolve the exact original poll event with its pinned digest. Missing history or unknown access remains unavailable, and revoked access refuses. Branch health stores the original snapshot's digest, not its bytes; current readBranchHealth state cannot substitute for that historical snapshot. No detail endpoint is provided here.
Validate boundaries and retain history
The included dist/provider-events.d.ts declarations export projection/filter/permission/source/notification types, ProviderEventError, PROVIDER_EVENT_PROFILE and PROVIDER_EVENT_LIMITS. Inputs are exact plain data: no extra fields, getters, callbacks, promises, arbitrary URLs or private notes. IDs are lowercase alphanumeric/hyphen strings of 1–63 characters. Canonical input is bounded to 16 KiB, notification to 8 KiB and nesting to 16 levels; overflow refuses whole values. Results are frozen copies; caller objects remain unchanged.
Errors have fixed redacted messages and stable code/reason: INVALID, LIMIT, UNSUPPORTED, SOURCE_CONFLICT, FORBIDDEN, UNAVAILABLE or CORRUPT. Only sf-provider-events/branch-health-polled/1 is accepted. Another provider/profile/family needs a reviewed contract, not an arbitrary string.
parseProviderEventNotification checks the fixed v1 shape, repeated identities and digest without a current clock, source read or permission check. It preserves old interpretation but authenticates nothing. A changed record with a newly computed digest can be structurally valid; verifying its source still requires the original pinned event. Parsing history grants no access. There is no implicit protocol migration.
The tested composition uses disposable stores and recorded provider fixtures. Live GitHub, MCP compatibility, subscriptions, webhook receipt, model qualification and effects remain separate work and acceptance gates.
