feat(local-device): typed store collection evidence with revision-fenced coverage

.github/workflows/managed-connector-oci-e2e.yml

@@ -45,6 +45,14 @@ name: managed-connector OCI end-to-end (local registry; NOT GHCR, NOT Sigstore)
 # fetch. (There is no cross-repo-pins.json in THIS repo; see the pin file if that surprises you.)
 # The reasoning, the weakness of pinning an unmerged PR head, and why the connector stays `oura`
 # while data-connectors' publish pilot moved to `ynab` are all written down in the pin file.
+#
+# THE INSTALL-PATH JOURNEY (J2-install, the last three steps). The live-registry test above proves an
+# artifact installs and its entrypoint imports. The journey installs two releases through the shipped
+# collector's own function (ensureCollectionProfileInstalled), against pins the builder writes into the job's
+# temp directory. It runs each installed entrypoint and checks what the server and the device make of it. A
+# replaced digest stops counting until its own run proves it. It runs against this job's registry. Its signature
+# check is the same stub verifier, and its releases carry a fabricated signature bundle, so (1) and (2) above
+# apply to it, and it proves nothing about signatures or ghcr.io.
 
 on:
   pull_request:
@@ -56,6 +64,13 @@ on:
       - "packages/local-collector/src/managed/**"
       - "packages/local-collector/test/managed-connectors.test.ts"
       - "packages/local-collector/test/managed-connectors-live-registry.test.ts"
+      - "packages/local-collector/test/helpers/live-registry-client.ts"
+      # The install-path journey (J2-install) and the fixture it packages.
+      - "reference-implementation/test/local-device-coverage-journey.test.ts"
+      - "reference-implementation/test/helpers/install-path-fixture.ts"
+      - "reference-implementation/test/helpers/build-install-path-releases.ts"
+      # The shipped selection and binding the journey calls (selectedReleaseForPin, bindOptionalRunCoverageToRelease).
+      - "packages/local-collector/bin/pdpp-local-collector.ts"
       # This job's own control files: a PR that only edits the workflow or moves the producer pin
       # would otherwise not run the thing it changed. Same reasoning as consumer-drift-signal.yml's
       # "Producer workflows should include their own control files in triggers".
@@ -67,6 +82,11 @@ on:
       - "packages/local-collector/src/managed/**"
       - "packages/local-collector/test/managed-connectors.test.ts"
       - "packages/local-collector/test/managed-connectors-live-registry.test.ts"
+      - "packages/local-collector/test/helpers/live-registry-client.ts"
+      - "reference-implementation/test/local-device-coverage-journey.test.ts"
+      - "reference-implementation/test/helpers/install-path-fixture.ts"
+      - "reference-implementation/test/helpers/build-install-path-releases.ts"
+      - "packages/local-collector/bin/pdpp-local-collector.ts"
       - ".github/workflows/managed-connector-oci-e2e.yml"
       - ".github/managed-connector-e2e-pin.json"
   workflow_dispatch:
@@ -162,7 +182,9 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
-          node-version: "22.23.4"
+          # 24.22.1 is the version the reference-implementation job runs its tests on, and the
+          # install-path journey below is one of those tests. The producer's engines pin node 24 too.
+          node-version: "24.22.1"
 
       - name: Install this repository's dependencies
         run: npm ci --ignore-scripts
@@ -447,3 +469,59 @@ jobs:
 
           echo "OK: the consumer rejected blobs that did not hash to their pinned digests."
           rm -f proxied.txt
+
+      - name: Build the workspace packages the reference server loads
+        # The reference-implementation job builds these after `npm ci` (reference-implementation.yml). The
+        # install-path journey imports the server, which loads their dist/ output. This job runs
+        # `npm ci --ignore-scripts`, so nothing has built them yet. The root postinstall is not needed here:
+        # it fetches connector packages, and this journey runs none.
+        run: |
+          set -euo pipefail
+          npm --prefix packages/connector-protocol run build
+          npm --prefix packages/collector-runtime run build
+          npm --prefix reference-implementation/vendor/read-core run build
+          npm --prefix reference-implementation/vendor/cli run build
+          npm --prefix reference-implementation/vendor/mcp-server run build
+
+      - name: Build and push the install-path releases A and B with the producer's builder
+        # Two releases of one connector (install-path-fixture.ts): the same manifest and different code layers,
+        # so different digests. The builder is the producer's own script at the pinned revision. The packaging
+        # tree around it is the fixture's. Both releases are pushed to this job's registry, each with a signature
+        # stand-in. The pins the journey checks against are written into the work directory. The journey step
+        # reads their path from the releases file, not from the log.
+        working-directory: reference-implementation
+        env:
+          PRODUCER_GIT: ${{ github.workspace }}/data-connectors
+          PRODUCER_SHA: ${{ steps.pin.outputs.sha }}
+          RELEASES_JSON: ${{ runner.temp }}/install-path-releases.json
+        run: |
+          set -euo pipefail
+          node --import tsx test/helpers/build-install-path-releases.ts \
+            --producer-git "$PRODUCER_GIT" \
+            --producer-sha "$PRODUCER_SHA" \
+            --registry localhost:5000 \
+            --work "${RUNNER_TEMP}/install-path" \
+            --modules "$PRODUCER_GIT/node_modules" > "$RELEASES_JSON"
+
+      - name: Run the install-path journey (J2-install) through the shipped collector path
+        working-directory: reference-implementation
+        env:
+          PDPP_TEST_OCI_REGISTRY: localhost:5000
+          RELEASES_JSON: ${{ runner.temp }}/install-path-releases.json
+        run: |
+          set -euo pipefail
+          pins_path="$(node -e 'process.stdout.write(require(process.env.RELEASES_JSON).pins)')"
+          test -s "$pins_path"
+          export PDPP_TEST_INSTALL_PATH_PINS="$pins_path"
+          node --test --import tsx --test-name-pattern=J2-install test/local-device-coverage-journey.test.ts | tee result.txt
+          # The same guard as the live-registry step above: node --test exits 0 on a skipped test, so require
+          # exactly one passing test and no skips. A typo in an env var name must not turn this job green.
+          if ! grep -qE 'pass 1$' result.txt; then
+            echo "::error::the install-path journey did not report exactly one passing test" >&2
+            exit 1
+          fi
+          if ! grep -qE 'skipped 0$' result.txt; then
+            echo "::error::the install-path journey SKIPPED; its env vars did not reach it" >&2
+            exit 1
+          fi
+          rm -f result.txt

PG-PROFILE-51-REPORT.md

@@ -168,7 +168,7 @@ tail:
 
 The completed profile receipt recorded 1,034 files; that historical receipt
 is unchanged. The template equivalence registry is a different measure:
-156 eligible plus 37 cold-required files, for **193** total. The
+157 eligible plus 40 cold-required files, for **197** total. The
 handle-generation, issuance-cutover, opaque-cursor and search-index repair
 tests remain registered. These counts are recomputed from the merged registry arrays.
 

apps/console/src/app/(console)/lib/collection-report.ts

@@ -30,9 +30,9 @@
 import type { AxisChip, EvidenceTone } from "@pdpp/display";
 import { formatCoverageAxis } from "@pdpp/display";
 import type { ForwardDispositionSummary } from "./connection-evidence.ts";
-import { formatForwardDisposition } from "./connection-evidence.ts";
+import { formatForwardDisposition, withCoverageAsOf } from "./connection-evidence.ts";
 import { dispositionForInstallState } from "./connector-implementation.ts";
-import type { RefCollectionReportEntry } from "./ref-client.ts";
+import type { RefCollectionReportEntry, RefCoverageAsOf } from "./ref-client.ts";
 
 export interface StreamCollectionFacts {
   /**
@@ -292,9 +292,15 @@ export function formatStreamCollectionFacts(
      * happen, so the reference's disposition is replaced by the install blocker.
      */
     readonly connectorNotInstalled?: boolean;
+    /** The run the connection's local coverage describes (`coverage_as_of`). */
+    readonly coverageAsOf?: RefCoverageAsOf | null;
   } = {}
 ): StreamCollectionFacts {
-  const coverage = formatCoverageAxis(entry.coverage_condition);
+  const coverage = withCoverageAsOf(
+    formatCoverageAxis(entry.coverage_condition),
+    entry.coverage_condition,
+    options.coverageAsOf
+  );
   const disposition = dispositionForInstallState(
     formatForwardDisposition(entry.forward_disposition),
     options.connectorNotInstalled === true

apps/console/src/app/(console)/lib/connection-evidence.test.ts

@@ -15,6 +15,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { formatCoverageAxis, formatFreshnessAxis, formatOutboxAxis } from "@pdpp/display";
+import { formatStreamCollectionFacts } from "./collection-report.ts";
 import {
   deriveAutoPausedBanner,
   deriveConnectionNextStep,
@@ -2348,3 +2349,65 @@ test("formatSourceHeartbeat reports unknown when the server derived no health",
   assert.equal(chip.value, "unknown");
   assert.doesNotMatch(chip.label, /starting/, "an underived status is not evidence of life");
 });
+
+// Local coverage is a fact about one run, never a present-tense claim: the
+// owner sees "complete as of <time>", and the chip names the run, release and
+// revision it describes.
+const COVERAGE_AS_OF = {
+  artifact_digest: `sha256:${"a".repeat(64)}`,
+  collection_revision: 7,
+  committed_at: "2026-10-22T10:00:00.000Z",
+  evidence: "terminal_run",
+  run_id: "run-a",
+  run_sequence: 3,
+} as const;
+
+test("coverage chip reads 'complete as of <time>' when the reference names the run it describes", () => {
+  const axes = {
+    attention: null,
+    coverage: "complete",
+    freshness: "fresh",
+    outbox: "idle",
+  } as const;
+  const [coverage] = summarizeAxisChips(axes as never, {
+    coverageAsOf: COVERAGE_AS_OF,
+    isLocalDeviceBacked: true,
+  });
+  assert.equal(coverage?.label, "Coverage · complete as of 2026-10-22 10:00:00Z");
+  assert.equal(coverage?.value, "complete as of 2026-10-22 10:00:00Z");
+  assert.match(coverage?.title ?? "", /run run-a/);
+  assert.match(coverage?.title ?? "", /sha256:a{12}/);
+  assert.match(coverage?.title ?? "", /revision 7/);
+});
+
+test("coverage chip adds no as-of to unknown coverage or when the reference sends none", () => {
+  const unknown = {
+    attention: null,
+    coverage: "unknown",
+    freshness: "fresh",
+    outbox: "idle",
+  } as const;
+  const [unknownChip] = summarizeAxisChips(unknown as never, {
+    coverageAsOf: COVERAGE_AS_OF,
+    isLocalDeviceBacked: true,
+  });
+  assert.equal(unknownChip?.label, formatCoverageAxis("unknown").label);
+  const complete = {
+    attention: null,
+    coverage: "complete",
+    freshness: "fresh",
+    outbox: "idle",
+  } as const;
+  const [plain] = summarizeAxisChips(complete as never, {
+    coverageAsOf: null,
+    isLocalDeviceBacked: true,
+  });
+  assert.equal(plain?.label, formatCoverageAxis("complete").label);
+});
+
+test("per-stream coverage reads 'complete as of <time>' with the connection's as-of", () => {
+  const facts = formatStreamCollectionFacts({ coverage_condition: "complete", stream: "messages" } as never, {
+    coverageAsOf: COVERAGE_AS_OF,
+  });
+  assert.equal(facts.coverage.label, "Coverage · complete as of 2026-10-22 10:00:00Z");
+});

apps/console/src/app/(console)/lib/connection-evidence.ts

@@ -24,6 +24,7 @@ import type {
   DeviceSourceInstance,
   RefCollectionRateSnapshot,
   RefConnectionHealthSnapshot,
+  RefCoverageAsOf,
   RefDetailGapBacklog,
   RefForwardDisposition,
   RefLocalDeviceProgress,
@@ -87,12 +88,18 @@ export function outboxAxisIsApplicable(
  */
 export function summarizeAxisChips(
   axes: RefConnectionHealthSnapshot["axes"] | undefined | null,
-  options: { isLocalDeviceBacked?: boolean } = {}
+  options: {
+    coverageAsOf?: RefCoverageAsOf | null;
+    isLocalDeviceBacked?: boolean;
+  } = {}
 ): AxisChip[] {
   if (!axes) {
     return [];
   }
-  const out: AxisChip[] = [formatCoverageAxis(axes.coverage), formatFreshnessAxis(axes.freshness)];
+  const out: AxisChip[] = [
+    withCoverageAsOf(formatCoverageAxis(axes.coverage), axes.coverage, options.coverageAsOf),
+    formatFreshnessAxis(axes.freshness),
+  ];
   const attention = formatAttentionAxis(axes.attention);
   if (attention) {
     out.push(attention);
@@ -122,6 +129,39 @@ export function summarizeAxisChips(
   return out;
 }
 
+const FRACTIONAL_SECONDS = /\.\d+Z$/;
+
+/** UTC, to the second: "2026-10-22 10:00:00Z". Empty for a missing or unparseable time. */
+function formatCoverageAsOfTime(iso: string | null | undefined): string {
+  const parsed = iso ? Date.parse(iso) : Number.NaN;
+  return Number.isFinite(parsed)
+    ? new Date(parsed).toISOString().replace("T", " ").replace(FRACTIONAL_SECONDS, "Z")
+    : "";
+}
+
+/**
+ * Coverage is a fact about one run, never a present-tense claim. When the
+ * reference names the run a coverage verdict describes, the chip reads
+ * "complete as of <time>" and its title names the run, release and collection
+ * revision. Unknown coverage has no run behind it, so it is left unchanged.
+ */
+export function withCoverageAsOf(
+  chip: AxisChip,
+  axis: string | null | undefined,
+  asOf: RefCoverageAsOf | null | undefined
+): AxisChip {
+  const committedAt = formatCoverageAsOfTime(asOf?.committed_at);
+  if (!(asOf && committedAt) || axis === "unknown" || axis === null || axis === undefined) {
+    return chip;
+  }
+  return {
+    ...chip,
+    label: `${chip.label} as of ${committedAt}`,
+    title: `${chip.title} This is a fact about run ${asOf.run_id} (release ${asOf.artifact_digest}), committed at ${committedAt} as collection revision ${asOf.collection_revision}. A later run the reference has not heard about is not reflected.`,
+    value: `${chip.value} as of ${committedAt}`,
+  };
+}
+
 /**
  * Owner-facing copy for the connection-level forward disposition — the
  * reference's single answer to "what is the next run expected to do?". This is

apps/console/src/app/(console)/lib/ref-client.ts

@@ -632,6 +632,17 @@ export interface RefConnectorImplementation {
   state: "built_in" | "installed" | "local_source" | "not_installed" | "unknown";
 }
 
+/** See {@link RefConnectorSummary.coverage_as_of}. */
+export interface RefCoverageAsOf {
+  readonly artifact_digest: string;
+  readonly collection_revision: number;
+  readonly committed_at: string | null;
+  readonly evidence: "terminal_run";
+  readonly run_id: string;
+  /** The sequence the server issued to the run at its start; it decides which proof can be current. */
+  readonly run_sequence: number;
+}
+
 export interface RefConnectorSummary {
   /**
    * Owner/control-plane acquisition provenance for manual imports, device
@@ -669,6 +680,13 @@ export interface RefConnectorSummary {
    * renders no horizons rather than inventing a state. Pass-through from
    * `server/ref-control.ts#projectConnectorSummaryConnectionHealth`.
    */
+  /**
+   * What the local coverage on this row is a fact about (`LocalCoverageAsOf`
+   * in reference `server/ref-control.ts`): the run, its release digest, and the
+   * collection revision and time it was committed at. `null` or absent when no
+   * current local proof backs the coverage shown.
+   */
+  coverage_as_of?: RefCoverageAsOf | null;
   coverage_horizons?: readonly RefCoverageHorizon[];
   display_name: string;
   freshness: Record<string, unknown>;
@@ -1314,6 +1332,12 @@ export interface RefConnectionHealthSnapshot {
    */
   collection_rate?: RefCollectionRateSnapshot | null;
   conditions?: readonly RefConnectionHealthCondition[];
+  /**
+   * What `axes.coverage` is a fact about: the same value as the summary's
+   * top-level `coverage_as_of`. Optional on the mirror because a reference
+   * predating the field omits it.
+   */
+  coverage_as_of?: RefCoverageAsOf | null;
   /**
    * Additive, nullable source-pressure detail-gap backlog rollup
    * ({@link RefDetailGapBacklog}). `null` when no backlog evidence was supplied

apps/console/src/app/(console)/sources/[connector]/connection-diagnostics.tsx

@@ -28,6 +28,7 @@ import type {
   DeviceSourceInstance,
   RefActionRemediation,
   RefConnectionHealthSnapshot,
+  RefCoverageAsOf,
   RefLocalDeviceProgress,
   RefRenderedVerdict,
   RefSchedule,
@@ -71,6 +72,8 @@ export interface ConnectionDiagnosticsProps {
    * coverage-derived value, matching the per-stream lines.
    */
   connectorNotInstalled?: boolean;
+  /** The run the local coverage describes; the coverage chip reads "as of" its commit time. */
+  coverageAsOf?: RefCoverageAsOf | null;
   /**
    * Connection-summary local-device progress, including the count-backed
    * `outbox_counts` rollup. Used to show the scale of stuck work in the
@@ -105,6 +108,7 @@ export function ConnectionDiagnostics({
   connectionId,
   connectorId,
   connectorNotInstalled = false,
+  coverageAsOf = null,
   localDeviceProgress,
   now,
   providerOrigin,
@@ -163,6 +167,7 @@ export function ConnectionDiagnostics({
               connectionId={connectionId}
               connectorId={connectorId}
               connectorNotInstalled={connectorNotInstalled}
+              coverageAsOf={coverageAsOf}
               localDeviceProgress={localDeviceProgress}
               providerOrigin={providerOrigin}
               renderedVerdict={renderedVerdict}
@@ -455,6 +460,7 @@ function ProjectedStateDiagnostics({
   connectionId,
   connectorId,
   connectorNotInstalled,
+  coverageAsOf,
   localDeviceProgress,
   providerOrigin,
   renderedVerdict,
@@ -464,6 +470,7 @@ function ProjectedStateDiagnostics({
   connectionId: string | null;
   connectorId: string | null;
   connectorNotInstalled: boolean;
+  coverageAsOf: RefCoverageAsOf | null;
   localDeviceProgress: RefLocalDeviceProgress | null;
   providerOrigin: string | null;
   renderedVerdict: RefRenderedVerdict | null;
@@ -487,6 +494,7 @@ function ProjectedStateDiagnostics({
   // The diagnostics block already receives the connection's local-device
   // progress, so reuse it as the local-backing signal.
   const axisChips = summarizeAxisChips(connectionHealth.axes, {
+    coverageAsOf,
     isLocalDeviceBacked: Boolean(localDeviceProgress),
   });
   const outboxRemediation = summarizeOutboxStallRemediation(connectionHealth, localDeviceProgress);