Import software-factory/operational-signals from the private package. This bounded local intake accepts caller-authenticated redacted observations and durably records Signals with cursor progress. It requires Node.js 26.8.1 or later and the existing public CommandJournal. No provider adapter, Factory, Portfolio, scheduler or model is needed. Import and construction do no I/O.
This is local synthetic source infrastructure. It does not qualify Sentry, PostHog, Datadog, live credentials, production privacy, authority or a telemetry workflow. The build review records current scope and gates.
Supply the boundary
Create or open your own journal explicitly. Keep an external, create-once witness for its real identity and generation; on restart use CommandJournal.openExisting. Missing or replaced state requires reconciliation. Commission admission must distinguish a genuinely fresh scope from a previously commissioned but missing ledger; collection permission alone cannot authorise recreating one. Never regenerate a witness to make a refused store pass.
import {
OperationalSignalIntake, sourceBindingPin, intakeRequestDigest,
} from 'software-factory/operational-signals';
// Your host supplies these declared capabilities; they are not payload claims.
export function composeIntake({ journal, boundary, clock }) {
const intake = new OperationalSignalIntake({ journal, boundary, clock });
return { intake, close: () => journal.close() };
}
boundary.binding(pin) returns the pinned historical SourceBinding; boundary.admit(request) authenticates the actual source material, current principal, scope, privacy eligibility, permissions and exact canonical page digest. Both return { state: 'ok', value } or { state: 'refused', code }. clock.now() returns a canonical UTC timestamp. All three methods are synchronous, bounded caller code. Rejected or pending native Promises are observed and refused; they do not make asynchronous ports supported. Synchronous code cannot be forcibly interrupted by this Module.
The admission request includes the actual storeHandle object. Check it against the journal your host opened, and witness that real resource using your external store anchor. Two matching strings or a marker copied with a database are insufficient. Hold your caller-owned operation lock across admission and the entire synchronous call, serialising local revocation and store replacement across processes. The installed proof uses a separate SQLite lock whose ownership ends when a process dies; it is a consumer fixture, not a new Factory ledger.
For acceptance, the Module compares principal, Product/source/environment pins, store witness, collection permission generation and redaction policy. Hashes convey neither authentication nor anonymisation. An arbitrary boundary implementation can lie: provider qualification belongs to the caller and future adapter work. Historical reads require a current independent read grant, even after collection expires; they do not contact a provider or revive collection authority.
admittedAt is the immutable eligibility and coverage capture cutoff: the binding must already be valid, and a complete terminal window must already have ended at that point. A later clock cannot legitimise earlier admission. latestAdmissionAt is a latest-start time. Current time and intrinsic event/received times are checked after callbacks and immediately before execute. At expiry, on rollback or after more than 60 seconds spent obtaining admission, a new command refuses. Local revocation is serialised by the caller's lock. Remote provider revocation and SQLite cannot be atomic; records state the witnessed permission generation and time. No Budget, provider-write or release authority is granted.
Commission, accept and recover
Build a closed SourceBinding from trusted configuration, then retain sourceBindingPin(binding).value. It pins the principal, source tenant/account/project/instance, Product/service/environment, adapter/version, redaction and permission generation, store witness, approved reference namespaces and lower-or-equal commissioned limits. References are caller-approved lower-case tokens (letters/digits separated by hyphens), up to 64 characters. Approval covers their meaning and linkage, not just their grammar.
Call commission({ operation: 'commission', commandId, binding: pin }) explicitly for a genuinely new scope. Call acceptPage({ operation: 'accept-page', commandId, binding: pin, expectedVersion, page }) under your operation lock. Retain intakeRequestDigest(command).value before dispatch. Command IDs must be unique per journal across all bindings: the journal keys receipts on the command ID alone, so reusing an ID under another binding refuses with command-conflict, and that binding's reconciliation cannot report it as committed. Results use { state: 'ok', value: { receipt, replayed } } or a fixed refusal code; exception messages and causes never escape.
Pages contain a finite UTC window, ordinal, predecessor digest, safe cursor references and at most eight observations. For source attestation, canonical page JSON uses the public Journal canonical form; flags/reasons are sorted unique tokens and observations sort by observation key, revision key, then canonical observation SHA-256 (ascending ASCII). Hash that full normalised page with SHA-256. The Module applies the same normalisation and rejects unknown fields. Preserve an observation's original observed/received metadata on retransmission. Stable source observation/revision keys and unchanged content produce a duplicate; changed content under the same immutable keys refuses the whole page. Distinct revisions are separate unassessed Signals, regardless of arrival order. There is no inferred supersession, severity, root cause, impact or repair permission.
A success atomically records the new Signals, deduplication index, per-window membership/count, checkpoint, coverage and journal receipt/outbox. A missing or reordered page, cursor mismatch or conflicting identity moves none of them. Stage sensitive cursor tokens in your approved immutable store before calling intake; the journal retains only safe references and content pins. Keep those tokens for restart. Missing, expired or changed tokens require reconciliation, never a silently fresh cursor. Token staging and the journal are separate transactions; an unused staged token is not an accepted page.
Retry the exact command only with current admission. For a lost acknowledgement after collection revocation/expiry, call reconcileCommand({ binding: pin, commandId, requestDigest }) with current read authority. It validates at most 129 history records without source contact, returning committed, not-recorded or unknown. Missing/corrupt aggregate/history is unknown, never permission to recreate it. A different digest for an existing command is a conflict. Refusal or a storage error does not prove an earlier attempt failed.
read({ binding: pin }) returns historical window summaries and the current checkpoint. history({ binding: pin, afterSequence, limit }) returns at most 32 typed records. Each read needs independent current read permission. Rebuilds neither admit work nor dispatch journal outbox events.
Coverage and privacy
A nonterminal page's source coverage attests that page and its source gaps. The resulting window remains partial with more-pages. Only a contiguous terminal chain with authenticated complete enumeration, a finished window, no omissions and known event-time membership can produce an exact count. A later complete flag removes only more-pages; earlier gaps and unknown membership persist. A new explicit reconciliation window leaves the old result unchanged. Disjoint windows make no claim about the time between them.
Counts are distinct observation revisions accounted for in that window, including already-known observations from overlapping windows. They are not source occurrence totals, customer impact or health. Exact zero requires an authenticated empty terminal window. Unavailable, unauthenticated, incomplete or unknown evidence never becomes zero. All views state their historical capture time and window.
Redact before calling intake. The closed observation allowlist contains stable key/revision digests, times, a fixed source kind, optional build/release digests, a source-attributed occurrence count, four fixed flags and originalDataReference: { namespace, keyDigest }. There is no arbitrary text, URL, metric bag, stack, user/session property, replay or model output. The Module never fetches references. Unknown fields, accessors, symbols, prototypes, byte/count overflow and invalid times refuse before persistence. Error diagnostics contain no input or caller exception text.
The journal retains immutable receipts and outbox copies. This packet therefore accepts only immutable-approved-facts: the caller must authorise retention of every fact/reference and its linkage in all copies without a future erasure duty. Timed-deletion or erasure requirements refuse commissioning. A hash is not a privacy exemption. Sensitive retrieval and retention stay separately commissioned; deleted source detail makes a reference unavailable, not a reproduction or healthy result.
Bounds and remaining work
Each binding has at most 128 accepted pages, 1,024 observation revisions and 32 windows; each window spans at most seven days. Observations are at most 1 KiB, eight/page; binding 4 KiB; command 16 KiB; state 256 KiB; receipt/event 32 KiB. Actual byte limits may refuse before count limits, particularly with overlapping-window membership. Limits may be lowered at commission, never increased in place. At capacity, prior records remain readable and exact replay remains available; there is no reset, eviction, automatic rollover, repin or adoption.
Indefinite intake, finite erasure, live provider adapters, grouping, metrics/detectors and Repair are separate packets. This entry neither expands Service access nor implements a notification dispatcher. Existing Journal, authority, Budget and publication semantics are unchanged.
operationalPageDigest(page) validates and normalises the page and returns Result<Digest> for the same canonical preimage used by intake. Observation order, flag order and coverage-reason order are normalised. The helper neither authenticates a source nor grants permission; the trusted boundary still attests the resulting digest.
