@pepys/kit 0.0.0-stage → 0.0.1

package/src/fact-envelope-cases.json

@@ -0,0 +1,464 @@
+{
+  "cases": [
+    {
+      "title": "accepts a webhook fact ID",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "accepts an observation fact ID",
+      "envelope": {
+        "id": "observation:0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "accepts an enrichment fact ID",
+      "envelope": {
+        "id": "enrichment:b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "accepts a manual fact ID",
+      "envelope": {
+        "id": "manual:c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "accepts an event fact ID",
+      "envelope": {
+        "id": "event:boxxy:evt-0001",
+        "type": "boxxy.attempt.started",
+        "v": 1,
+        "api": "boxxy/1",
+        "entity": "boxxy:item:0193a1b2-0000-7000-8000-000000000001",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "accepts an event fact ID whose event ID holds a colon and a dot",
+      "envelope": {
+        "id": "event:telemetry:claude_code.api_request:req_01",
+        "type": "telemetry.claude_code.api_request",
+        "v": 1,
+        "api": "otlp-logs/1",
+        "entity": "telemetry:session:s-9",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "accepts an event fact ID whose event ID is a hash key",
+      "envelope": {
+        "id": "event:telemetry:codex.sse_event:h-5e1c9a07",
+        "type": "telemetry.claude_code.api_request",
+        "v": 1,
+        "api": "otlp-logs/1",
+        "entity": "telemetry:session:s-9",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "accepts an actor and a cursor",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {},
+        "actor": "github:user:583231",
+        "cursor": "page-7"
+      },
+      "isValid": true
+    },
+    {
+      "title": "accepts fractional seconds",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00.123456Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "accepts a leap day",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2028-02-29T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "refuses an ID of no fact kind",
+      "envelope": {
+        "id": "not-a-fact-id",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a manual fact ID with a short hash",
+      "envelope": {
+        "id": "manual:abc",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a webhook fact ID with an upper-case source",
+      "envelope": {
+        "id": "webhook:GitHub:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a webhook fact ID with a line feed",
+      "envelope": {
+        "id": "webhook:github:d\n1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a webhook fact ID with a carriage return",
+      "envelope": {
+        "id": "webhook:github:d\r1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a webhook fact ID with a line separator",
+      "envelope": {
+        "id": "webhook:github:d\u20281",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a webhook fact ID with a paragraph separator",
+      "envelope": {
+        "id": "webhook:github:d\u20291",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an event fact ID with no event ID",
+      "envelope": {
+        "id": "event:boxxy:",
+        "type": "boxxy.attempt.started",
+        "v": 1,
+        "api": "boxxy/1",
+        "entity": "boxxy:item:0193a1b2-0000-7000-8000-000000000001",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an event fact ID with an upper-case source",
+      "envelope": {
+        "id": "event:Boxxy:evt-0001",
+        "type": "boxxy.attempt.started",
+        "v": 1,
+        "api": "boxxy/1",
+        "entity": "boxxy:item:0193a1b2-0000-7000-8000-000000000001",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an empty type",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an envelope version other than 1",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 2,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an api that is not text",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": 7,
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an entity ID with no kind",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an entity ID whose source is a fact kind",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "manual:pr:7",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an entity ID whose source is the event fact kind",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "event:x:y",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an actor that is an event fact ID",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {},
+        "actor": "event:boxxy:evt-0001"
+      },
+      "isValid": false
+    },
+    {
+      "title": "accepts an entity ID whose source only starts with a fact kind",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "events:x:y",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": true
+    },
+    {
+      "title": "refuses an actor that is not an entity ID",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {},
+        "actor": "github:7"
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a time with no seconds",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a time with an offset",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00+01:00",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a day the calendar lacks",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-02-30T10:30:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses the hour 24",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T24:00:00Z",
+        "payload": {}
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a cursor that is not text",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {},
+        "cursor": 3
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses a field the envelope lacks",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z",
+        "payload": {},
+        "extra": 1
+      },
+      "isValid": false
+    },
+    {
+      "title": "refuses an envelope without a payload",
+      "envelope": {
+        "id": "webhook:github:d-1",
+        "type": "github.pull_request.opened",
+        "v": 1,
+        "api": "github/2022-11-28",
+        "entity": "github:pull_request:77",
+        "at": "2026-10-02T10:30:00Z"
+      },
+      "isValid": false
+    }
+  ]
+}

package/src/facts/build-enrichment-fact-id.ts

@@ -0,0 +1,15 @@
+import { toTagged } from '@zgeoff/std';
+import type { FactID } from '../ids/types.ts';
+import { buildFactHash } from './build-fact-hash.ts';
+
+interface EnrichmentFactIDParts {
+  job: string;
+  jobVersion: string;
+  inputHash: string;
+}
+
+export function buildEnrichmentFactID(parts: EnrichmentFactIDParts): FactID {
+  const hash = buildFactHash([parts.job, parts.jobVersion, parts.inputHash]);
+
+  return toTagged<FactID>(`enrichment:${hash}`);
+}

package/src/facts/build-event-fact-id.ts

@@ -0,0 +1,11 @@
+import { toTagged } from '@zgeoff/std';
+import type { FactID } from '../ids/types.ts';
+
+interface EventFactIDParts {
+  source: string;
+  event: string;
+}
+
+export function buildEventFactID(parts: EventFactIDParts): FactID {
+  return toTagged<FactID>(`event:${parts.source}:${parts.event}`);
+}

package/src/facts/build-fact-hash.ts

@@ -0,0 +1,6 @@
+import { createHash } from 'node:crypto';
+
+export function buildFactHash(fields: readonly string[]): string {
+  // A JSON array keeps each field's boundary, which a delimiter-joined string would let a field forge.
+  return createHash('sha256').update(JSON.stringify(fields)).digest('hex');
+}

package/src/facts/build-manual-fact-id.ts

@@ -0,0 +1,7 @@
+import { toTagged } from '@zgeoff/std';
+import type { ClientID, FactID, RequestID } from '../ids/types.ts';
+import { buildFactHash } from './build-fact-hash.ts';
+
+export function buildManualFactID(client: ClientID, request: RequestID): FactID {
+  return toTagged<FactID>(`manual:${buildFactHash([client, request])}`);
+}

package/src/facts/build-observation-fact-id.ts

@@ -0,0 +1,15 @@
+import { toTagged } from '@zgeoff/std';
+import type { EntityID, FactID } from '../ids/types.ts';
+import { buildFactHash } from './build-fact-hash.ts';
+
+interface ObservationFactIDParts {
+  source: string;
+  entity: EntityID;
+  sourceUpdateTime: string;
+}
+
+export function buildObservationFactID(parts: ObservationFactIDParts): FactID {
+  const hash = buildFactHash([parts.source, parts.entity, parts.sourceUpdateTime]);
+
+  return toTagged<FactID>(`observation:${hash}`);
+}

package/src/facts/build-webhook-fact-id.ts

@@ -0,0 +1,11 @@
+import { toTagged } from '@zgeoff/std';
+import type { FactID } from '../ids/types.ts';
+
+interface WebhookFactIDParts {
+  source: string;
+  deliveryID: string;
+}
+
+export function buildWebhookFactID(parts: WebhookFactIDParts): FactID {
+  return toTagged<FactID>(`webhook:${parts.source}:${parts.deliveryID}`);
+}

package/src/facts/parse-fact-envelope.ts

@@ -0,0 +1,44 @@
+import { toTagged } from '@zgeoff/std';
+import { z } from 'zod';
+import { parseEntityID } from '../entity-ids/parse-entity-id.ts';
+import type { EntityID, FactID } from '../ids/types.ts';
+import type { FactEnvelope, Result } from '../types.ts';
+
+const factIDPattern = new RegExp(
+  ['^(?:webhook|event):[a-z][a-z0-9_]*:.+$', '^(?:observation|enrichment|manual):[0-9a-f]{64}$']
+    .map((pattern) => `(?:${pattern})`)
+    .join('|'),
+  'u',
+);
+
+const factIDSchema = z
+  .string()
+  .regex(factIDPattern, 'not a fact ID')
+  .transform((text) => toTagged<FactID>(text));
+
+const entityIDSchema = z
+  .string()
+  .refine((text) => parseEntityID(text).ok, 'not an entity ID')
+  .transform((text) => toTagged<EntityID>(text));
+
+const factEnvelopeSchema = z.strictObject({
+  id: factIDSchema,
+  type: z.string().min(1),
+  v: z.literal(1),
+  api: z.string().min(1),
+  entity: entityIDSchema,
+  actor: entityIDSchema.optional(),
+  at: z.iso.datetime(),
+  cursor: z.string().optional(),
+  payload: z.unknown().refine((payload) => payload !== undefined, 'a fact needs a payload'),
+});
+
+export function parseFactEnvelope(input: unknown): Result<FactEnvelope<unknown>, z.ZodError> {
+  const parsed = factEnvelopeSchema.safeParse(input);
+
+  if (!parsed.success) {
+    return { ok: false, failure: parsed.error };
+  }
+
+  return { ok: true, value: parsed.data };
+}

package/src/facts/parse-stream-name.ts

@@ -0,0 +1,33 @@
+import type { Result } from '../types.ts';
+
+const partPattern = /^[a-z][a-z0-9_]*$/u;
+
+interface StreamNameParts {
+  source: string;
+  family: string;
+}
+
+type StreamNameFailure =
+  | { reason: 'malformed' }
+  | { reason: 'invalid-source' }
+  | { reason: 'invalid-family' };
+
+export function parseStreamName(text: string): Result<StreamNameParts, StreamNameFailure> {
+  const parts = text.split('.');
+
+  if (parts.length !== 3 || parts[0] !== 'facts') {
+    return { ok: false, failure: { reason: 'malformed' } };
+  }
+
+  const [, source = '', family = ''] = parts;
+
+  if (!partPattern.test(source)) {
+    return { ok: false, failure: { reason: 'invalid-source' } };
+  }
+
+  if (!partPattern.test(family)) {
+    return { ok: false, failure: { reason: 'invalid-family' } };
+  }
+
+  return { ok: true, value: { source, family } };
+}

package/src/generators/build-payload-shape.ts

@@ -0,0 +1,75 @@
+import { P, match } from 'ts-pattern';
+import { z } from 'zod';
+
+// What the glue makes of a payload schema. The log keeps a payload as the sender sent it, so the
+// shape follows the input side of the schema: a field with a default may be absent.
+export type PayloadShape =
+  | { kind: 'string' }
+  | { kind: 'number' }
+  | { kind: 'boolean' }
+  | { kind: 'literal'; values: readonly (string | number | boolean)[] }
+  | { kind: 'object'; fields: readonly PayloadField[] }
+  | { kind: 'array'; element: PayloadShape }
+  | { kind: 'nullable'; inner: PayloadShape }
+  | { kind: 'unknown' };
+
+export function buildPayloadShape(schema: z.core.$ZodType): PayloadShape {
+  // A string format, such as `z.uuid()`, is no ZodString in zod 4, but shares the core class.
+  return match(schema)
+    .with(P.instanceOf(z.core.$ZodString), () => ({ kind: 'string' as const }))
+    .with(P.instanceOf(z.ZodNumber), () => ({ kind: 'number' as const }))
+    .with(P.instanceOf(z.ZodBoolean), () => ({ kind: 'boolean' as const }))
+    .with(P.instanceOf(z.ZodLiteral), (literal) => buildLiteralShape([...literal.def.values]))
+    .with(P.instanceOf(z.ZodEnum), (enumeration) =>
+      buildLiteralShape(Object.values(enumeration.def.entries)),
+    )
+    .with(P.instanceOf(z.ZodObject), (object) => ({
+      kind: 'object' as const,
+      fields: Object.entries<z.core.$ZodType>(object.shape).map(([name, field]) =>
+        buildPayloadField(name, field),
+      ),
+    }))
+    .with(P.instanceOf(z.ZodArray), (array) => ({
+      kind: 'array' as const,
+      element: buildPayloadShape(array.element),
+    }))
+    .with(P.instanceOf(z.ZodNullable), (nullable) => buildNullableShape(nullable.unwrap()))
+    .otherwise(() => ({ kind: 'unknown' as const }));
+}
+
+function buildLiteralShape(values: readonly unknown[]): PayloadShape {
+  const literals = values.filter(
+    (value) => typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean',
+  );
+
+  return literals.length === values.length && literals.length > 0
+    ? { kind: 'literal', values: literals }
+    : { kind: 'unknown' };
+}
+
+export interface PayloadField {
+  name: string;
+  shape: PayloadShape;
+  isOptional: boolean;
+}
+
+function buildPayloadField(name: string, schema: z.core.$ZodType): PayloadField {
+  return match(schema)
+    .with(P.instanceOf(z.ZodOptional), (optional) => ({
+      name,
+      shape: buildPayloadShape(optional.unwrap()),
+      isOptional: true,
+    }))
+    .with(P.instanceOf(z.ZodDefault), (withDefault) => ({
+      name,
+      shape: buildPayloadShape(withDefault.unwrap()),
+      isOptional: true,
+    }))
+    .otherwise(() => ({ name, shape: buildPayloadShape(schema), isOptional: false }));
+}
+
+function buildNullableShape(schema: z.core.$ZodType): PayloadShape {
+  const inner = buildPayloadShape(schema);
+
+  return inner.kind === 'unknown' ? inner : { kind: 'nullable', inner };
+}