Observation coverage

This 1.2.0-draft.3 profile, observation_coverage_v1, defines an origin’s declaration of observation scope and the reporting completeness of an explicitly known cohort. It does not claim complete traffic capture, prove downstream model use, or grant access. Publication status is recorded in release status.

The normative structures are in observation.schema.json. The reference module validates the semantics, acquires a publication through verified HTTPS, retains monotonic local history and reduces authenticated inputs. Positive and negative fixtures distinguish structural validity from semantic validity. This profile is separate from agreement, asset and archive profiles; it does not add fields to their closed envelopes.

1. Three independent statements

Statement	What it establishes	What it cannot establish
Origin registry declaration	At the recorded HTTPS observation, the origin declared these observers, scopes, profiles and intervals	That every request actually crosses a declared observer, that the operator is honest, or that there are no other routes/copies
Authenticated intake	An appointed collector recorded the exact signed statement from the authenticated reporter	That a client performed its asserted action, a remote reader received all bytes, or a model used the data
Known expectation journal	A trusted ingress, admission, accepted-duty or outbox adapter identified this particular expected observation	The existence or count of undeclared traffic, hidden use, unknown operations or uninstrumented paths

These MUST remain distinct in user interfaces, reports and exports. A report that says “one of one known admissions has a terminal report” MUST NOT label that result “100% of agent traffic captured”. global_traffic_denominator and global_capture_percent are null in this reference profile. No whole-web or whole-origin capture percentage is inferred from received reports.

2. Origin publication and acquisition

The origin MAY publish https://<origin>/odexa-observation.json as application/json, alongside its native /odexa.json. This is a draft publication convention, not a registered well-known endpoint. The registry contains:

• protocol_version:"1.2.0-draft.3", profile:"observation_coverage_v1", exact same-origin registry_id and origin;
• increasing integer revision, plus the exact native policy’s policy_id, policy_revision and SHA-256 policy_digest;
• issued_at, exclusive expires_at and zero to 128 observation boundaries.

Acquisition MUST use verified, bounded, credential-free HTTPS at that exact origin and path. A redirect, transport failure, policy-digest mismatch or invalid publication fails acquisition. No provider account, payment request, service authority document or signing service is required to publish or read the registry. A registry does not appoint a contracting, payment or collection service; any operational capability still needs its separate authority and agreement contract.

fetch_registry(transport, origin, history=RegistryHistory(path), clock=...) uses the existing bounded AuthorityTransport. It retrieves the native policy and registry, checks their exact-byte binding and retains a RegistrySnapshot. The transport, clock and local storage are trusted application adapters, not wire-supplied arguments. The snapshot’s HTTPS observation is adapter testimony, not a portable signature.

The private history checks freshness after acquiring its write lock: the observation must be no more than five seconds old, not from the future, and the registry must remain unexpired. It rejects lower registry/policy revisions, same-revision byte changes, policy-lineage changes and backwards observation/recording time, including after restart. It records repeated successful observations without rewriting the original publication bytes. A locally unseen rollback cannot be detected from an old document alone; preserve the reader’s own history.

Historical history.get(origin, revision) returns the retained declaration and its original observation. It MUST NOT be represented as a fresh current declaration. Historical reduction uses that explicitly selected snapshot and retains registry_observed_at; it makes no assertion that the registry remains current. Missing current publication never silently substitutes the retained snapshot as current.

3. Boundary contract

Every boundary has an origin-qualified id, kind, observer_id, exact selected service binding, native-policy resource_ids, actions, purposes, starts_at, exclusive ends_at, declared state and explicitly supported event_profiles. Intervals lie within the registry’s policy-bound validity interval. Resource IDs must exist in the exact policy. Scope is declarative observation scope, not permission to perform the action.

Kind	Identity and supported interpretation
gateway	A named reporter with exact service binding, core event profile and matching event http.boundary_id. Only origin_observed end-client transport outcomes qualify. Upstream observations do not become end-client deliveries.
agent	A named authenticated reporter and service binding. Core use reports remain client claims. Explicit storage_sessions_v1 reports distinguish write/action claims from session start, checkpoint and cessation claims.
collector	observer_id equals the selected collector service ID. This boundary measures receipt of an exact reporter/event/payload digest, not the action asserted in that report.
unobserved	Null observer and service binding, no event profiles, and unobserved or unknown state. It creates no observer or reporting promise.

Observer states are instrumented, partial and unknown; their meaning is origin-declared, not independently certified. Empty boundaries support static policy or manifest-only publication. That mode has unknown traffic and no manufactured zero-use result. A static publisher does not need to introduce an agreement service solely to use this declaration.

The profile selectors are core for unchanged draft-3 event envelopes and storage_sessions_v1 for the explicitly selected storage assertion profile. A gateway always uses core; selected storage agreements still use core gateway transport events. An agent or collector may explicitly declare both profiles. An unknown profile is rejected, and a selected storage event cannot silently satisfy a core expectation.

For a concrete URL, all matching native-policy resource IDs must be included in a boundary’s resource scope. Action and purpose must match the requested tuple. Overlapping scopes/intervals remain listed, and per-boundary counts MUST NOT be added as if they were independent physical uses. Declared gaps remain unknown. A mixture of incompatible instrumented/unobserved declarations is conservatively labelled partial; any explicit unknown remains unknown.

4. Trusted expected observations

An expected observation is a closed record from an independently trusted local journal. Its id is a UUID; it names boundary_id, exact resource_url, one action/purpose, agreement_id, expected_at, due_at, selected event_profile, basis and a qualified subject.

The basis is one of:

• instrumented_ingress: a particular known incoming request at a declared instrumented route;
• gateway_admission: a particular durable authenticated admission, with its actual agreement ID;
• accepted_duty: a particular known operation or session obligation under an accepted agreement;
• report_outbox: an exact known report awaiting a collector receipt.

gateway_admission and accepted_duty require a non-null agreement ID. A collector receipt expectation binds the reporter’s event ID and exact original payload digest. Delivery subjects bind reporter, delivery ID and ingress. Action subjects bind reporter and operation ID. Storage subjects additionally distinguish start, checkpoint index and cessation. Unused subject fields are null. Each expectation’s basis must be appropriate to its subject.

The adapter MUST derive the expectation, agreement and deadline from its actual journal/accepted terms. It MUST NOT invent a missing-operation denominator from the set of reports that happened to arrive, take arbitrary untrusted client submissions as expected traffic, or fabricate session/operation IDs. Where no independent expected set exists, provide an empty set and report a null completion percentage. A sample’s apparent completeness is not a population capture rate.

The deadline does not come from a new registry default. Original accepted reporting, use and retention terms remain authoritative. Client-declared action completion times remain claims; timeliness derived from them must retain that qualification. Known storage checkpoint duties and parent/deadline consistency use the existing storage-session reducer, not a coverage declaration that resets acquisition or retention time.

5. Reduction and denominators

from profiles.observation_coverage import RegistryHistory, fetch_registry, reduce_coverage

snapshot = fetch_registry(transport, origin, history=RegistryHistory(private_history_path))
report = reduce_coverage(
    snapshot,
    query={"url": resource_url, "action": "retrieve", "purpose": "public_retrieval",
           "starts_at": start_utc, "ends_at": end_utc},
    verified_intakes=authenticated_intakes,
    expectations=trusted_expected_observations,
    as_of=as_of_utc,
)

The input list is deliberately named verified_intakes. The caller MUST verify collector/reporter signatures, independent identity pins, selected authority/history and exact accepted context before calling this reducer. Field names such as origin_key_verified are not authentication by themselves. The reference reducer validates structure, exact payload binding, source/assurance consistency and context, but does not replace the existing signature and authority verifiers. Anonymous/unverified reports cannot fill an authenticated expectation.

The query is one canonical same-origin URL, action, purpose and half-open interval [starts_at, ends_at), with ends_at <= as_of. It selects expectations by expected_at. A terminal observation after the query end can fulfil an expectation that began inside the cohort, provided it remains within its declared boundary interval and arrives by as_of. An unrelated observation outside the query interval is excluded. Historical policy revisions require their own matching registry snapshot; a record from a different policy revision is not silently relabelled.

Inputs are bounded to 4,096 intakes and 4,096 expectations. Reduction exposes per-boundary expected, timely, late, missing, pending, conflicted, profile/binding mismatch and unscoped counts. Unknown boundary/scope expectations remain in a separate list. A durable admission with no qualifying terminal report remains an unresolved admission; it does not imply either successful delivery or no delivery.

For each boundary:

timely_ratio = timely known expectations / all selected known expectations
received_ratio = (timely + late) known expectations / all selected known expectations

Each ratio contains explicit numerator, denominator and percent. A zero denominator gives percent:null. Pending and conflicted expectations stay in the denominator; these are current completion fractions for the named cohort, not verdicts that every not-yet-due duty was violated. Exactly-at-deadline receipt is timely. Missing means no qualifying receipt and as_of > due_at; otherwise it is pending.

observed counts eligible unique reporter/event identities in the observation interval, not unique physical uses. unexpected counts eligible observation subjects with no selected expectation and does not create a denominator. The outcomes counts describe fulfilled expectation subjects and retain separate labels for full/partial gateway writes, failed writes, response-only observations, client action completion/failure, client storage start/checkpoint/cessation, and collector receipt. A full local response write is not verified remote receipt. A completed local-write report remains an authenticated client assertion unless supported by separately declared trusted instrumentation.

6. Conflict and late-data rules

Exact intake payload retries use the earliest retained authenticated receipt time available by as_of; they do not inflate counts. Conflicting payloads under the same reporter/event identity are quarantined. Different terminal statements for the same qualified observation subject are conflicted instead of choosing one by input order. A syntactically valid report from another agreement, wrong reporter/binding or different selected profile cannot fill a known gap.

Exact expectation retries deduplicate both UUID and qualified subject. Conflicting identities or deadlines remain visible and cannot shrink the denominator or manufacture an on-time receipt. Conflicts outside the query do not poison the selected cohort. Input order does not select a winning conflicting record.

Reports received after as_of remain future data for that historical calculation. Recomputing at a later cut can change a missing report into a late receipt, but cannot retroactively make it timely. Invalid, unverified, future, unmatched and conflicting inputs have explicit diagnostics. Omitted inputs remain a caller/exporter completeness limit: a reduction proves only what follows from the provided trusted cohort and evidence.

7. Static publication, reporting-only participation and duties

A static policy or asset-manifest publisher can publish an empty or explicitly unobserved registry and remain independent of every provider. The result is a declaration with unknown traffic, not enforcement or universal measurement. A reporting-only participant can accept a free reporting agreement and send its supported signed reports to an appointed collector without a protected retrieval/token/gateway flow. Its evidence remains client claims and collector receipts; the profile does not invent gateway delivery.

The existing standalone free path and supported attribution, reporting, retention and continuing-storage duties are unchanged. Implementers MUST execute all duties of the action/profile they claim to support or decline the requested use. A registry naming transform or a model-training purpose does not implement that operation or authorise the reference client to accept an unsupported duty. The reference is not required to implement a trainer or observe undisclosed copies to express those policy terms. See agent duties, storage integration and provider handover.

8. Executed evidence and limits

The coverage tests exercise origin-only credential-free HTTPS publication, actual signed gateway/collector intake and admission correlation, actual free report-only collection, outages/policy mismatch, private history/restart and rollback, static/unobserved/partial/overlapping scope, all expected-report states, exact bytes, conflicting identities, late data, unknown profiles and storage/action separation. Permutation cases retain the same output for conflicting evidence order. The schema results independently check structural cases; their semantic annotations are separately executed by Python.

The component regression record also exercises storage-session, storage-contract, gateway-reporting and free-contract suites. This module adds one explicit publication profile without changing historical wire versions or the global signing-type registry. It does not by itself add an installed CLI command or establish independent Node implementation coverage. See current validation for current combined results and release status for release status and deployment limits.