@pepys/source-github 0.1.1 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@
 
   <p>
     <a href="../../docs/README.md">Documentation</a> •
-    <a href="../../docs/design/v1-plug-ins.md">The plug-ins of v1</a>
+    <a href="../../docs/architecture/plug-ins/github.md">The GitHub plug-in</a>
   </p>
 </div>
 
@@ -20,7 +20,23 @@ with its consumer.
 ## Install
 
 ```sh
-bun add @pepys/source-github
+bun add @pepys/source-github @pepys/kit
+bun add -d @pepys/cli
+```
+
+Add the plug-in to a deployment, then build its consumers. The build compiles each consumer, which
+needs zig and wasm-tools, as the [CLI README](../cli/README.md) says.
+
+```ts
+// deployment.ts
+import { defineDeployment } from '@pepys/kit';
+import { githubPlugin } from '@pepys/source-github';
+
+export const deployment = defineDeployment({ name: 'home', plugins: [githubPlugin] });
+```
+
+```sh
+bunx pepys build deployment.ts --out build
 ```
 
 ## Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pepys/source-github",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "The pepys GitHub plug-in: pull requests, releases, commits and deploys",
   "license": "MIT",
   "repository": {
@@ -19,16 +19,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@pepys/api": "0.1.1",
-    "@pepys/ingest": "0.1.1",
-    "@pepys/kit": "0.1.1",
+    "@pepys/api": "0.3.0",
+    "@pepys/ingest": "0.3.0",
+    "@pepys/kit": "0.3.0",
     "@zgeoff/std": "0.4.3",
     "kysely": "0.29.8",
+    "ts-pattern": "5.9.2",
     "zod": "4.6.7"
   },
   "devDependencies": {
     "@msw/data": "1.1.8",
-    "@pepys/testing": "0.1.1",
+    "@orpc/client": "2.0.0-beta.50",
+    "@pepys/testing": "0.3.0",
     "msw": "3.0.3",
     "tiny-invariant": "1.3.3"
   }

package/src/api/serve-api.ts

@@ -2,7 +2,8 @@ import { serveAPI } from '@pepys/api';
 import { defineDeployment } from '@pepys/kit';
 import { githubPlugin } from '../github-plugin.ts';
 
-serveAPI({
+await serveAPI({
   deployment: defineDeployment({ name: 'github', plugins: [githubPlugin] }),
   environment: process.env,
+  argv: process.argv.slice(2),
 });

package/src/consumers/github-pull-request.ts

@@ -104,7 +104,8 @@ function collectReleaseBumps(
   return bumps;
 }
 
-// `<owner>/<name>/releases/tag/<tag>`, up to the first character that ends a URL in text.
+// `<owner>/<name>/releases/tag/<tag>`, up to the first character that ends a URL in text. GitHub
+// serves a tag that holds `/` both escaped and unescaped, so the tag is the rest of the path.
 function parseReleaseURLPath(text: string): { repository: string; tag: string } | undefined {
   let end = text.length;
 
@@ -117,17 +118,19 @@ function parseReleaseURLPath(text: string): { repository: string; tag: string }
   }
 
   const parts = text.slice(0, end).split('/');
-  const [owner, name, releases, tagWord, tag] = parts;
+  const [owner, name, releases, tagWord] = parts;
+  const tagParts = parts.slice(4);
+  const tag = tagParts.join('/');
 
-  if (parts.length !== 5 || releases !== 'releases' || tagWord !== 'tag') {
+  if (parts.length < 5 || releases !== 'releases' || tagWord !== 'tag') {
     return undefined;
   }
 
-  if (owner === undefined || name === undefined || tag === undefined) {
+  if (owner === undefined || name === undefined) {
     return undefined;
   }
 
-  if (owner === '' || name === '' || tag === '') {
+  if (owner === '' || name === '' || tagParts.includes('')) {
     return undefined;
   }
 

package/src/families/build-family-types.ts

@@ -1,6 +1,5 @@
 import type { z } from 'zod';
 
-// One fact type per action, `github.<family>.<action>`, each with the family's payload schema.
 export function buildFamilyTypes(
   family: string,
   actions: readonly string[],

package/src/families/issue-family.ts

@@ -29,7 +29,6 @@ const payloadSchema = z.looseObject({
   issue: z.looseObject({ id: z.number().int() }),
 });
 
-// Stored with no consumer.
 export const issueFamily = defineFactFamily({
   stream: 'facts.github.issue',
   api: 'github/2022-11-28',

package/src/families/pull-request-review-family.ts

@@ -9,7 +9,6 @@ const payloadSchema = z.looseObject({
   review: z.looseObject({ id: z.number().int() }),
 });
 
-// Stored with no consumer.
 export const pullRequestReviewFamily = defineFactFamily({
   stream: 'facts.github.pull_request_review',
   api: 'github/2022-11-28',

package/src/families/workflow-run-family.ts

@@ -9,7 +9,6 @@ const payloadSchema = z.looseObject({
   workflow_run: z.looseObject({ id: z.number().int() }),
 });
 
-// Stored with no consumer.
 export const workflowRunFamily = defineFactFamily({
   stream: 'facts.github.workflow_run',
   api: 'github/2022-11-28',

package/src/generated/github-deploy-boundary.ts

@@ -85,6 +85,10 @@ export function updateGithubDeployModel(model: GithubDeployModel, message: Githu
   return message.kind === 'reset' ? initGithubDeployModel() : { ...model, input: message.input };
 }
 
+declare const factTag: unique symbol;
+
+export type FactID = string & { readonly [factTag]: 'FactID' };
+
 export interface GithubRefPushedPayload {
   ref: string;
   repository: GithubRefPushedPayloadRepository;
@@ -103,8 +107,8 @@ export interface GithubDeploymentPayloadDeployment {
 }
 
 export type GithubDeployFact =
-  | { id: string; type: 'github.ref.pushed'; entity: string; at: string; payload: GithubRefPushedPayload }
-  | { id: string; type: 'github.deployment.created' | 'github.deployment.status_created'; entity: string; at: string; payload: GithubDeploymentPayload };
+  | { id: FactID; type: 'github.ref.pushed'; entity: EntityID; at: string; payload: GithubRefPushedPayload }
+  | { id: FactID; type: 'github.deployment.created' | 'github.deployment.status_created'; entity: EntityID; at: string; payload: GithubDeploymentPayload };
 
 export function parseGithubDeployFact(factJSON: string): GithubDeployFact | undefined {
   const parsed: unknown = JSON.parse(factJSON);
@@ -127,6 +131,10 @@ function decodeGithubDeployFact(value: unknown): GithubDeployFact | undefined {
     return undefined;
   }
 
+  if (!isFactID(id) || !isFactEntityID(entity)) {
+    return undefined;
+  }
+
   if (type === 'github.ref.pushed') {
     const decoded = decodeGithubRefPushedPayload(payload);
 
@@ -150,6 +158,14 @@ function decodeGithubDeployFact(value: unknown): GithubDeployFact | undefined {
   return undefined;
 }
 
+function isFactID(text: string): text is FactID {
+  return text.length > 0;
+}
+
+function isFactEntityID(text: string): text is EntityID {
+  return text.length > 0;
+}
+
 function decodeGithubRefPushedPayload(value: unknown): GithubRefPushedPayload | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return undefined;

package/src/generated/github-pull-request-boundary.ts

@@ -45,6 +45,10 @@ export function updateGithubPullRequestModel(model: GithubPullRequestModel, mess
   return message.kind === 'reset' ? initGithubPullRequestModel() : { ...model, input: message.input };
 }
 
+declare const factTag: unique symbol;
+
+export type FactID = string & { readonly [factTag]: 'FactID' };
+
 export interface GithubPullRequestPayload {
   action: string;
   pull_request: GithubPullRequestPayloadPullRequest;
@@ -56,7 +60,7 @@ export interface GithubPullRequestPayloadPullRequest {
 }
 
 export type GithubPullRequestFact =
-  | { id: string; type: 'github.pull_request.assigned' | 'github.pull_request.auto_merge_disabled' | 'github.pull_request.auto_merge_enabled' | 'github.pull_request.closed' | 'github.pull_request.converted_to_draft' | 'github.pull_request.demilestoned' | 'github.pull_request.dequeued' | 'github.pull_request.edited' | 'github.pull_request.enqueued' | 'github.pull_request.labeled' | 'github.pull_request.locked' | 'github.pull_request.milestoned' | 'github.pull_request.opened' | 'github.pull_request.ready_for_review' | 'github.pull_request.reopened' | 'github.pull_request.resynced' | 'github.pull_request.review_request_removed' | 'github.pull_request.review_requested' | 'github.pull_request.synchronize' | 'github.pull_request.unassigned' | 'github.pull_request.unlabeled' | 'github.pull_request.unlocked'; entity: string; at: string; payload: GithubPullRequestPayload };
+  | { id: FactID; type: 'github.pull_request.assigned' | 'github.pull_request.auto_merge_disabled' | 'github.pull_request.auto_merge_enabled' | 'github.pull_request.closed' | 'github.pull_request.converted_to_draft' | 'github.pull_request.demilestoned' | 'github.pull_request.dequeued' | 'github.pull_request.edited' | 'github.pull_request.enqueued' | 'github.pull_request.labeled' | 'github.pull_request.locked' | 'github.pull_request.milestoned' | 'github.pull_request.opened' | 'github.pull_request.ready_for_review' | 'github.pull_request.reopened' | 'github.pull_request.resynced' | 'github.pull_request.review_request_removed' | 'github.pull_request.review_requested' | 'github.pull_request.synchronize' | 'github.pull_request.unassigned' | 'github.pull_request.unlabeled' | 'github.pull_request.unlocked'; entity: EntityID; at: string; payload: GithubPullRequestPayload };
 
 export function parseGithubPullRequestFact(factJSON: string): GithubPullRequestFact | undefined {
   const parsed: unknown = JSON.parse(factJSON);
@@ -79,6 +83,10 @@ function decodeGithubPullRequestFact(value: unknown): GithubPullRequestFact | un
     return undefined;
   }
 
+  if (!isFactID(id) || !isFactEntityID(entity)) {
+    return undefined;
+  }
+
   if (type === 'github.pull_request.assigned' || type === 'github.pull_request.auto_merge_disabled' || type === 'github.pull_request.auto_merge_enabled' || type === 'github.pull_request.closed' || type === 'github.pull_request.converted_to_draft' || type === 'github.pull_request.demilestoned' || type === 'github.pull_request.dequeued' || type === 'github.pull_request.edited' || type === 'github.pull_request.enqueued' || type === 'github.pull_request.labeled' || type === 'github.pull_request.locked' || type === 'github.pull_request.milestoned' || type === 'github.pull_request.opened' || type === 'github.pull_request.ready_for_review' || type === 'github.pull_request.reopened' || type === 'github.pull_request.resynced' || type === 'github.pull_request.review_request_removed' || type === 'github.pull_request.review_requested' || type === 'github.pull_request.synchronize' || type === 'github.pull_request.unassigned' || type === 'github.pull_request.unlabeled' || type === 'github.pull_request.unlocked') {
     const decoded = decodeGithubPullRequestPayload(payload);
 
@@ -92,6 +100,14 @@ function decodeGithubPullRequestFact(value: unknown): GithubPullRequestFact | un
   return undefined;
 }
 
+function isFactID(text: string): text is FactID {
+  return text.length > 0;
+}
+
+function isFactEntityID(text: string): text is EntityID {
+  return text.length > 0;
+}
+
 function decodeGithubPullRequestPayload(value: unknown): GithubPullRequestPayload | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return undefined;

package/src/generated/github-ref-boundary.ts

@@ -45,6 +45,10 @@ export function updateGithubRefModel(model: GithubRefModel, message: GithubRefMe
   return message.kind === 'reset' ? initGithubRefModel() : { ...model, input: message.input };
 }
 
+declare const factTag: unique symbol;
+
+export type FactID = string & { readonly [factTag]: 'FactID' };
+
 export interface GithubRefPushedPayload {
   ref: string;
   repository: GithubRefPushedPayloadRepository;
@@ -55,7 +59,7 @@ export interface GithubRefPushedPayloadRepository {
 }
 
 export type GithubRefFact =
-  | { id: string; type: 'github.ref.pushed'; entity: string; at: string; payload: GithubRefPushedPayload };
+  | { id: FactID; type: 'github.ref.pushed'; entity: EntityID; at: string; payload: GithubRefPushedPayload };
 
 export function parseGithubRefFact(factJSON: string): GithubRefFact | undefined {
   const parsed: unknown = JSON.parse(factJSON);
@@ -78,6 +82,10 @@ function decodeGithubRefFact(value: unknown): GithubRefFact | undefined {
     return undefined;
   }
 
+  if (!isFactID(id) || !isFactEntityID(entity)) {
+    return undefined;
+  }
+
   if (type === 'github.ref.pushed') {
     const decoded = decodeGithubRefPushedPayload(payload);
 
@@ -91,6 +99,14 @@ function decodeGithubRefFact(value: unknown): GithubRefFact | undefined {
   return undefined;
 }
 
+function isFactID(text: string): text is FactID {
+  return text.length > 0;
+}
+
+function isFactEntityID(text: string): text is EntityID {
+  return text.length > 0;
+}
+
 function decodeGithubRefPushedPayload(value: unknown): GithubRefPushedPayload | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return undefined;

package/src/generated/github-release-boundary.ts

@@ -45,6 +45,10 @@ export function updateGithubReleaseModel(model: GithubReleaseModel, message: Git
   return message.kind === 'reset' ? initGithubReleaseModel() : { ...model, input: message.input };
 }
 
+declare const factTag: unique symbol;
+
+export type FactID = string & { readonly [factTag]: 'FactID' };
+
 export interface GithubReleasePayload {
   action: string;
   release: GithubReleasePayloadRelease;
@@ -55,7 +59,7 @@ export interface GithubReleasePayloadRelease {
 }
 
 export type GithubReleaseFact =
-  | { id: string; type: 'github.release.created' | 'github.release.deleted' | 'github.release.edited' | 'github.release.prereleased' | 'github.release.published' | 'github.release.released' | 'github.release.resynced' | 'github.release.unpublished'; entity: string; at: string; payload: GithubReleasePayload };
+  | { id: FactID; type: 'github.release.created' | 'github.release.deleted' | 'github.release.edited' | 'github.release.prereleased' | 'github.release.published' | 'github.release.released' | 'github.release.resynced' | 'github.release.unpublished'; entity: EntityID; at: string; payload: GithubReleasePayload };
 
 export function parseGithubReleaseFact(factJSON: string): GithubReleaseFact | undefined {
   const parsed: unknown = JSON.parse(factJSON);
@@ -78,6 +82,10 @@ function decodeGithubReleaseFact(value: unknown): GithubReleaseFact | undefined
     return undefined;
   }
 
+  if (!isFactID(id) || !isFactEntityID(entity)) {
+    return undefined;
+  }
+
   if (type === 'github.release.created' || type === 'github.release.deleted' || type === 'github.release.edited' || type === 'github.release.prereleased' || type === 'github.release.published' || type === 'github.release.released' || type === 'github.release.resynced' || type === 'github.release.unpublished') {
     const decoded = decodeGithubReleasePayload(payload);
 
@@ -91,6 +99,14 @@ function decodeGithubReleaseFact(value: unknown): GithubReleaseFact | undefined
   return undefined;
 }
 
+function isFactID(text: string): text is FactID {
+  return text.length > 0;
+}
+
+function isFactEntityID(text: string): text is EntityID {
+  return text.length > 0;
+}
+
 function decodeGithubReleasePayload(value: unknown): GithubReleasePayload | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return undefined;

package/src/generated/github-release.sql

@@ -29,4 +29,5 @@ SELECT
   "url" AS "url",
   NULL AS "actor",
   "updated_at" AS "updated_at"
-FROM "github_release";
+FROM "github_release"
+WHERE "deleted_at" IS NULL;

package/src/github-release-consumer.ts

@@ -1,7 +1,8 @@
 import { defineConsumer, defineTable } from '@pepys/kit';
 import { releaseFamily } from './families/release-family.ts';
 
-// One row per release, never deleted: a release GitHub deleted keeps its row with `deleted_at`.
+// One row per release, never deleted: a release GitHub deleted keeps its row with `deleted_at`,
+// which leaves it out of the `entity` view.
 export const githubReleaseConsumer = defineConsumer({
   name: 'github_release',
   entry: new URL('consumers/github-release.ts', import.meta.url),
@@ -36,6 +37,7 @@ export const githubReleaseConsumer = defineConsumer({
       url: 'url',
       actor: null,
       updatedAt: 'updated_at',
+      deletedAt: 'deleted_at',
     },
   ],
   reads: ['github_release'],

package/src/ingest/build-github-fact.ts

@@ -1,16 +1,20 @@
 import { parseFactEnvelope } from '@pepys/kit';
 import type { PendingFact, StreamName } from '@pepys/kit';
 import { toTagged } from '@zgeoff/std';
+import { match } from 'ts-pattern';
 import { buildBodyHash } from '../utils/build-body-hash.ts';
 import { githubEventRules } from './github-event-rules.ts';
 
 // `delivery`: a webhook body, from the receive path or the recovery pull. `observation`: an object
-// that the resync pull read from the API, in the shape of a webhook body.
-export type GithubFactOrigin = 'delivery' | 'observation';
+// that the resync pull read from the API, in the shape of a webhook body, for a mark whose last
+// stored body has the digest `lastBodyDigest`.
+export type GithubFactOrigin =
+  | { kind: 'delivery' }
+  | { kind: 'observation'; lastBodyDigest: string | undefined };
 
 // One body of one webhook event as a fact, with an ID from the hash of the canonical body: GitHub
-// signs the body and not the delivery ID header, so only the body decides it. One delivery has one
-// ID on the receive path and on the recovery pull, and two reads of one state are one observation.
+// signs the body and not the delivery ID header, so only the body decides it. An observation's ID
+// also hashes the last stored body, so a read after a newer tied body is a fact the host applies.
 export function buildGithubFact(
   event: string,
   body: unknown,
@@ -29,10 +33,13 @@ export function buildGithubFact(
   }
 
   const envelope = parseFactEnvelope({
-    id:
-      origin === 'delivery'
-        ? `webhook:github:h-${buildBodyHash(body)}`
-        : `observation:${buildBodyHash(body)}`,
+    id: match(origin)
+      .with({ kind: 'delivery' }, () => `webhook:github:h-${buildBodyHash(body)}`)
+      .with(
+        { kind: 'observation' },
+        (observation) => `observation:${buildObservationHash(body, observation.lastBodyDigest)}`,
+      )
+      .exhaustive(),
     type: fields.type,
     v: 1,
     api: rule.family.api,
@@ -53,3 +60,9 @@ export function buildGithubFact(
     ...(fields.locator === undefined ? {} : { locator: fields.locator }),
   };
 }
+
+function buildObservationHash(body: unknown, lastBodyDigest: string | undefined): string {
+  return lastBodyDigest === undefined
+    ? buildBodyHash(body)
+    : buildBodyHash({ observed: body, lastBodyDigest });
+}

package/src/ingest/github-app/find-app-jwt.ts

@@ -1,6 +1,5 @@
 import { buildAppJWT } from './build-app-jwt.ts';
 
-// The App's JWT from the pull's env, or undefined when the private key cannot sign.
 export function findAppJWT(
   env: Readonly<Record<string, string>>,
   nowMs: number,

package/src/ingest/github-app/request-github-api.ts

@@ -1,8 +1,10 @@
 import { githubAPIURL } from './github-api-url.ts';
 
-// One answer of the GitHub REST API. `next` is the URL of the next page, from the `link` header.
+// One answer of the GitHub REST API. `text` is the body as sent, for a caller that must read a
+// number above 2^53 exactly. `next` is the URL of the next page, from the `link` header.
 export interface GithubAnswer {
   status: number;
+  text: string;
   body: unknown;
   next: string | undefined;
 }
@@ -19,13 +21,14 @@ export async function requestGithubAPI(
   const response = await sendRequest(url, token, method);
 
   if (response === undefined) {
-    return { status: 0, body: undefined, next: undefined };
+    return { status: 0, text: '', body: undefined, next: undefined };
   }
 
   const text = await response.text();
 
   return {
     status: response.status,
+    text,
     body: parseBody(text),
     next: findNextPage(response.headers.get('link')),
   };

package/src/ingest/read-github-delivery.ts

@@ -17,7 +17,7 @@ export function readGithubDelivery(delivery: Delivery): Received {
     return { kind: 'refused', status: 400, reason: 'the body is not JSON' };
   }
 
-  const fact = buildGithubFact(event, body.value, 'delivery');
+  const fact = buildGithubFact(event, body.value, { kind: 'delivery' });
 
   if (fact === 'ignored') {
     return { kind: 'ignored' };

package/src/ingest/recovery/pull-failed-deliveries.ts

@@ -1,3 +1,4 @@
+import { planAppends } from '@pepys/ingest';
 import type { PendingFact, PullContext, Pulled } from '@pepys/kit';
 import { z } from 'zod';
 import { buildGithubFact } from '../build-github-fact.ts';
@@ -18,13 +19,13 @@ export async function pullFailedDeliveries(
   cursor: string | null,
   context: PullContext,
 ): Promise<Pulled> {
-  const appJWT = findAppJWT(context.env, Date.now());
+  const appJWT = findAppJWT(context.env, context.now());
 
   if (appJWT === undefined) {
     return { kind: 'rejected', reason: 'the GitHub App private key cannot sign a token' };
   }
 
-  const seenID = cursor === null ? 0 : Number(cursor);
+  const seenID = cursor === null ? 0n : BigInt(cursor);
 
   const listed = await readDeliveriesAfter(seenID, appJWT);
 
@@ -43,20 +44,38 @@ export async function pullFailedDeliveries(
       return pickPullFailure(answer.status);
     }
 
-    const fact = buildGithubFact(detail.data.event, detail.data.request.payload, 'delivery');
+    const fact = buildGithubFact(detail.data.event, detail.data.request.payload, {
+      kind: 'delivery',
+    });
 
-    if (fact !== 'ignored' && fact !== 'invalid') {
-      facts.push(fact);
+    if (fact === 'ignored' || fact === 'invalid') {
+      continue;
     }
+
+    // The receive path answers 413 to a body this large and stores nothing; a batch that held it
+    // would be refused whole, with every other delivery and the cursor.
+    if (!planAppends([fact.fact]).ok) {
+      console.error(`the GitHub delivery ${id} is larger than one append of the log takes`);
+      continue;
+    }
+
+    facts.push(fact);
   }
 
-  const highestID = Math.max(seenID, ...listed.items.map((item) => item.id));
+  const highestID = listed.items.reduce(
+    (highest, item) => (item.id > highest ? item.id : highest),
+    seenID,
+  );
 
   return { kind: 'batch', batch: { facts }, cursor: `${highestID}`, isDone: true };
 }
 
+// A delivery ID is above 2^53, so it is read from its digits in the body, never from a number.
 const deliveryItemSchema = z.looseObject({
-  id: z.number().int(),
+  id: z
+    .string()
+    .regex(/^[1-9]\d*$/u)
+    .transform(BigInt),
   status_code: z.number().int(),
   event: z.string(),
 });
@@ -68,14 +87,14 @@ type DeliveryItem = z.infer<typeof deliveryItemSchema>;
 type DeliveryList = { kind: 'listed'; items: DeliveryItem[] } | { kind: 'failed'; status: number };
 
 // GitHub lists the newest delivery first, so the pages stop at the first one already seen.
-async function readDeliveriesAfter(seenID: number, appJWT: string): Promise<DeliveryList> {
+async function readDeliveriesAfter(seenID: bigint, appJWT: string): Promise<DeliveryList> {
   const items: DeliveryItem[] = [];
   let url: string | undefined = '/app/hook/deliveries?per_page=100';
 
   while (url !== undefined) {
     const answer: GithubAnswer = await requestGithubAPI(url, appJWT);
 
-    const page = deliveryListSchema.safeParse(answer.body);
+    const page = deliveryListSchema.safeParse(parseDeliveryList(answer.text));
 
     if (answer.status !== 200 || !page.success) {
       return { kind: 'failed', status: answer.status };
@@ -91,10 +110,29 @@ async function readDeliveriesAfter(seenID: number, appJWT: string): Promise<Deli
   return { kind: 'listed', items };
 }
 
+interface ReviverContext {
+  source?: string;
+}
+
+// `JSON.parse` rounds a number above 2^53, so each `id` keeps the source text the reviver is given.
+function parseDeliveryList(text: string): unknown {
+  try {
+    const list: unknown = JSON.parse(
+      text,
+      (key: string, value: unknown, context?: ReviverContext): unknown =>
+        key === 'id' && typeof value === 'number' ? context?.source : value,
+    );
+
+    return list;
+  } catch {
+    return undefined;
+  }
+}
+
 // oldest first, so the facts reach the log in the order GitHub sent them
-function collectFailedIDs(items: readonly DeliveryItem[]): number[] {
+function collectFailedIDs(items: readonly DeliveryItem[]): bigint[] {
   return items
     .filter((item) => item.status_code < 200 || item.status_code >= 300)
     .map((item) => item.id)
-    .toSorted((left, right) => left - right);
+    .toSorted((left, right) => Number(left - right));
 }

package/src/ingest/resync/collect-resync-targets.ts

@@ -1,11 +1,13 @@
-import type { ResyncMark } from '@pepys/kit';
+import type { EntityID, ResyncMark } from '@pepys/kit';
 
-// One marked object that the resync pull reads again: its repository, `owner/name`, and its API path.
+// One marked object that the resync pull reads again: its repository, `owner/name`, its API path,
+// and the digest of the last body ingest stored for it.
 export interface ResyncTarget {
   kind: 'pull_request' | 'release';
-  entity: string;
+  entity: EntityID;
   repository: string;
   path: string;
+  lastBodyDigest: string | undefined;
 }
 
 const locatorPatterns = [
@@ -24,7 +26,15 @@ export function collectResyncTargets(marks: readonly ResyncMark[]): ResyncTarget
       const kind = locatorPattern.kind;
 
       if (repository !== undefined && mark.entity.startsWith(`github:${kind}:`)) {
-        return [{ kind, entity: mark.entity, repository, path: locator }];
+        return [
+          {
+            kind,
+            entity: mark.entity,
+            repository,
+            path: locator,
+            lastBodyDigest: mark.lastBodyDigest,
+          },
+        ];
       }
     }
 

package/src/ingest/resync/pull-marked-objects.ts

@@ -1,6 +1,7 @@
 import type { PendingFact, PullContext, Pulled } from '@pepys/kit';
 import { z } from 'zod';
 import { buildGithubFact } from '../build-github-fact.ts';
+import type { GithubFactOrigin } from '../build-github-fact.ts';
 import { findAppJWT } from '../github-app/find-app-jwt.ts';
 import { pickPullFailure } from '../github-app/pick-pull-failure.ts';
 import { readInstallationToken } from '../github-app/read-installation-token.ts';
@@ -22,7 +23,7 @@ export async function pullMarkedObjects(
     return { kind: 'batch', batch: { facts: [] }, cursor: 'resynced', isDone: true };
   }
 
-  const appJWT = findAppJWT(context.env, Date.now());
+  const appJWT = findAppJWT(context.env, context.now());
 
   if (appJWT === undefined) {
     return { kind: 'rejected', reason: 'the GitHub App private key cannot sign a token' };
@@ -97,13 +98,11 @@ async function readObject(target: ResyncTarget, token: string): Promise<ReadObje
     return { kind: 'failed', status: answer.status };
   }
 
+  const origin: GithubFactOrigin = { kind: 'observation', lastBodyDigest: target.lastBodyDigest };
+
   if (target.kind === 'pull_request') {
     return toReadObject(
-      buildGithubFact(
-        'pull_request',
-        { action: 'resynced', pull_request: answer.body },
-        'observation',
-      ),
+      buildGithubFact('pull_request', { action: 'resynced', pull_request: answer.body }, origin),
     );
   }
 
@@ -122,7 +121,7 @@ async function readObject(target: ResyncTarget, token: string): Promise<ReadObje
     repository: { id: parsed.data.id, full_name: parsed.data.full_name },
   };
 
-  return toReadObject(buildGithubFact('release', body, 'observation'));
+  return toReadObject(buildGithubFact('release', body, origin));
 }
 
 function toReadObject(fact: PendingFact | 'ignored' | 'invalid'): ReadObject {

package/src/queries/pull-request-delivery-query.ts

@@ -1,4 +1,4 @@
-import { defineQuery } from '@pepys/kit';
+import { defineQuery, entityIDSchema, isEntityID } from '@pepys/kit';
 import { z } from 'zod';
 import { deploySignals } from '../utils/deploy-signals.ts';
 import { githubDeliveryConsumers } from './github-delivery-consumers.ts';
@@ -9,12 +9,12 @@ import {
 
 const pullRequestsSchema = z.array(z.string()).max(200);
 const nameSchema = z.string().min(1);
-const releaseSchema = z.object({ id: z.string(), tag: z.string(), at: z.string() });
+const releaseSchema = z.object({ id: entityIDSchema, tag: z.string(), at: z.string() });
 const signalSchema = z.enum(deploySignals);
-const deploySchema = z.object({ id: z.string(), at: z.string(), signal: signalSchema });
+const deploySchema = z.object({ id: entityIDSchema, at: z.string(), signal: signalSchema });
 
 const deliverySchema = z.object({
-  pullRequest: z.string(),
+  pullRequest: entityIDSchema,
   mergedAt: z.string().nullable(),
   release: releaseSchema.nullable(),
   deploy: deploySchema.nullable(),
@@ -32,7 +32,8 @@ export const pullRequestDeliveryQuery = defineQuery({
   output: z.array(deliverySchema),
   reads: githubDeliveryConsumers,
   handler: async (call) => {
-    const [first, ...rest] = call.input.pullRequests;
+    // text that is no entity ID names no stored pull request, so it has no row either way
+    const [first, ...rest] = call.input.pullRequests.filter((id) => isEntityID(id));
 
     if (first === undefined) {
       return [];

package/src/queries/select-pull-request-delivery.ts

@@ -1,3 +1,5 @@
+import { entityIDSchema } from '@pepys/kit';
+import type { EntityID } from '@pepys/kit';
 import { sql } from 'kysely';
 import type { RawBuilder } from 'kysely';
 import { z } from 'zod';
@@ -6,7 +8,7 @@ import type { DeploySignal } from '../utils/deploy-signals.ts';
 
 interface DeliveryOptions {
   // at least one
-  pullRequests: readonly [string, ...string[]];
+  pullRequests: readonly [EntityID, ...EntityID[]];
   environment: string;
 
   // Absent: a deploy of any target, and of none, counts. Given: only a deploy of that target.
@@ -14,8 +16,8 @@ interface DeliveryOptions {
 }
 
 // The statement that ties pull requests to releases and deploys. The rules it holds are in the
-// "Delivery query" section of the plug-ins design doc. Run it with `.execute(db)`, and turn its rows
-// into deliveries with the parse function below.
+// "The delivery query" section of docs/architecture/plug-ins/github.md. Run it with `.execute(db)`,
+// and turn its rows into deliveries with the parse function below.
 export function selectPullRequestDelivery(options: DeliveryOptions): RawBuilder<unknown> {
   return sql`select
     pull_request.id as "pullRequest",
@@ -115,22 +117,22 @@ function selectFirstDeployID(options: DeliveryOptions): RawBuilder<unknown> {
 }
 
 export interface PullRequestDelivery {
-  pullRequest: string;
+  pullRequest: EntityID;
   mergedAt: string | null;
-  release: { id: string; tag: string; at: string } | null;
-  deploy: { id: string; at: string; signal: DeploySignal } | null;
+  release: { id: EntityID; tag: string; at: string } | null;
+  deploy: { id: EntityID; at: string; signal: DeploySignal } | null;
 }
 
 const textSchema = z.string().nullable();
 
 // One row per pull request, as the statement selects it.
 const deliveryRowSchema = z.object({
-  pullRequest: z.string(),
+  pullRequest: entityIDSchema,
   mergedAt: textSchema,
-  releaseID: textSchema,
+  releaseID: entityIDSchema.nullable(),
   releaseTag: textSchema,
   releaseAt: textSchema,
-  deployID: textSchema,
+  deployID: entityIDSchema.nullable(),
   deployAt: textSchema,
   deploySignal: z.enum(deploySignals).nullable(),
 });