@prisma-next/migration-tools 0.4.2 → 0.5.0-dev.10

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.4.2",
+  "version": "0.5.0-dev.10",
   "type": "module",
   "sideEffects": false,
-  "description": "On-disk migration persistence, attestation, and chain reconstruction for Prisma Next",
+  "description": "On-disk migration persistence, hash verification, and chain reconstruction for Prisma Next",
   "dependencies": {
     "arktype": "^2.1.29",
     "pathe": "^2.0.3",
     "prettier": "^3.6.2",
-    "@prisma-next/contract": "0.4.2",
-    "@prisma-next/framework-components": "0.4.2",
-    "@prisma-next/utils": "0.4.2"
+    "@prisma-next/contract": "0.5.0-dev.10",
+    "@prisma-next/framework-components": "0.5.0-dev.10",
+    "@prisma-next/utils": "0.5.0-dev.10"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
@@ -27,17 +27,29 @@
     "node": ">=20"
   },
   "exports": {
-    "./types": {
-      "types": "./dist/exports/types.d.mts",
-      "import": "./dist/exports/types.mjs"
+    "./metadata": {
+      "types": "./dist/exports/metadata.d.mts",
+      "import": "./dist/exports/metadata.mjs"
+    },
+    "./package": {
+      "types": "./dist/exports/package.d.mts",
+      "import": "./dist/exports/package.mjs"
+    },
+    "./graph": {
+      "types": "./dist/exports/graph.d.mts",
+      "import": "./dist/exports/graph.mjs"
+    },
+    "./errors": {
+      "types": "./dist/exports/errors.d.mts",
+      "import": "./dist/exports/errors.mjs"
     },
     "./io": {
       "types": "./dist/exports/io.d.mts",
       "import": "./dist/exports/io.mjs"
     },
-    "./attestation": {
-      "types": "./dist/exports/attestation.d.mts",
-      "import": "./dist/exports/attestation.mjs"
+    "./hash": {
+      "types": "./dist/exports/hash.d.mts",
+      "import": "./dist/exports/hash.mjs"
     },
     "./dag": {
       "types": "./dist/exports/dag.d.mts",

package/src/dag.ts

@@ -2,13 +2,14 @@ import { ifDefined } from '@prisma-next/utils/defined';
 import { EMPTY_CONTRACT_HASH } from './constants';
 import {
   errorAmbiguousTarget,
-  errorDuplicateMigrationId,
+  errorDuplicateMigrationHash,
   errorNoInitialMigration,
   errorNoTarget,
   errorSameSourceAndTarget,
 } from './errors';
+import type { MigrationChainEntry, MigrationGraph } from './graph';
 import { bfs } from './graph-ops';
-import type { MigrationBundle, MigrationChainEntry, MigrationGraph } from './types';
+import type { MigrationPackage } from './package';
 
 /** Forward-edge neighbours for BFS: edge `e` from `n` visits `e.to` next. */
 function forwardNeighbours(graph: MigrationGraph, node: string) {
@@ -30,17 +31,17 @@ function appendEdge(
   else map.set(key, [entry]);
 }
 
-export function reconstructGraph(packages: readonly MigrationBundle[]): MigrationGraph {
+export function reconstructGraph(packages: readonly MigrationPackage[]): MigrationGraph {
   const nodes = new Set<string>();
   const forwardChain = new Map<string, MigrationChainEntry[]>();
   const reverseChain = new Map<string, MigrationChainEntry[]>();
-  const migrationById = new Map<string, MigrationChainEntry>();
+  const migrationByHash = new Map<string, MigrationChainEntry>();
 
   for (const pkg of packages) {
-    const { from, to } = pkg.manifest;
+    const { from, to } = pkg.metadata;
 
     if (from === to) {
-      throw errorSameSourceAndTarget(pkg.dirName, from);
+      throw errorSameSourceAndTarget(pkg.dirPath, from);
     }
 
     nodes.add(from);
@@ -49,28 +50,28 @@ export function reconstructGraph(packages: readonly MigrationBundle[]): Migratio
     const migration: MigrationChainEntry = {
       from,
       to,
-      migrationId: pkg.manifest.migrationId,
+      migrationHash: pkg.metadata.migrationHash,
       dirName: pkg.dirName,
-      createdAt: pkg.manifest.createdAt,
-      labels: pkg.manifest.labels,
+      createdAt: pkg.metadata.createdAt,
+      labels: pkg.metadata.labels,
     };
 
-    if (migrationById.has(migration.migrationId)) {
-      throw errorDuplicateMigrationId(migration.migrationId);
+    if (migrationByHash.has(migration.migrationHash)) {
+      throw errorDuplicateMigrationHash(migration.migrationHash);
     }
-    migrationById.set(migration.migrationId, migration);
+    migrationByHash.set(migration.migrationHash, migration);
 
     appendEdge(forwardChain, from, migration);
     appendEdge(reverseChain, to, migration);
   }
 
-  return { nodes, forwardChain, reverseChain, migrationById };
+  return { nodes, forwardChain, reverseChain, migrationByHash };
 }
 
 // ---------------------------------------------------------------------------
 // Deterministic tie-breaking for BFS neighbour order.
 // Used by `findPath` and `findPathWithDecision` only; not a general-purpose
-// utility. Ordering: label priority → createdAt → to → migrationId.
+// utility. Ordering: label priority → createdAt → to → migrationHash.
 // ---------------------------------------------------------------------------
 
 const LABEL_PRIORITY: Record<string, number> = { main: 0, default: 1, feature: 2 };
@@ -91,7 +92,7 @@ function compareTieBreak(a: MigrationChainEntry, b: MigrationChainEntry): number
   if (ca !== 0) return ca;
   const tc = a.to.localeCompare(b.to);
   if (tc !== 0) return tc;
-  return a.migrationId.localeCompare(b.migrationId);
+  return a.migrationHash.localeCompare(b.migrationHash);
 }
 
 function sortedNeighbors(edges: readonly MigrationChainEntry[]): readonly MigrationChainEntry[] {
@@ -111,7 +112,7 @@ function bfsOrdering(
  * exists. Returns an empty array when `fromHash === toHash` (no-op).
  *
  * Neighbor ordering is deterministic via the tie-break sort key:
- * label priority → createdAt → to → migrationId.
+ * label priority → createdAt → to → migrationHash.
  */
 export function findPath(
   graph: MigrationGraph,
@@ -202,8 +203,8 @@ export function findPathWithDecision(
       if (reachable.length > 1) {
         alternativeCount += reachable.length - 1;
         const sorted = sortedNeighbors(reachable);
-        if (sorted[0] && sorted[0].migrationId === edge.migrationId) {
-          if (reachable.some((e) => e.migrationId !== edge.migrationId)) {
+        if (sorted[0] && sorted[0].migrationHash === edge.migrationHash) {
+          if (reachable.some((e) => e.migrationHash !== edge.migrationHash)) {
             tieBreakReasons.push(
               `at ${edge.from}: ${reachable.length} candidates, selected by tie-break`,
             );

package/src/errors.ts

@@ -1,10 +1,29 @@
+import { basename, dirname, relative } from 'pathe';
+
+/**
+ * Build the canonical "re-emit this package" remediation hint.
+ *
+ * Every on-disk migration package ships its own `migration.ts` author-time
+ * file. Running it regenerates `migration.json` and `ops.json` with the
+ * correct hash + metadata, so it is the right primitive whenever a single
+ * package's on-disk artifacts are missing, malformed, or otherwise corrupt.
+ * Pointing users at `migration plan` would emit a *new* package rather than
+ * heal the broken one.
+ */
+function reemitHint(dir: string, fallback?: string): string {
+  const relativeDir = relative(process.cwd(), dir);
+  const reemit = `Re-emit the package by running \`node "${relativeDir}/migration.ts"\``;
+  return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;
+}
+
 /**
  * Structured error for migration tooling operations.
  *
  * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under
- * the MIGRATION namespace. These are tooling-time errors (file I/O, attestation,
- * migration history reconstruction), distinct from the runtime MIGRATION.* codes for apply-time
- * failures (PRECHECK_FAILED, POSTCHECK_FAILED, etc.).
+ * the MIGRATION namespace. These are tooling-time errors (file I/O, hash
+ * verification, migration history reconstruction), distinct from the runtime
+ * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,
+ * etc.).
  *
  * Fields:
  * - code:     Stable machine-readable code (MIGRATION.SUBCODE)
@@ -55,7 +74,10 @@ export function errorDirectoryExists(dir: string): MigrationToolsError {
 export function errorMissingFile(file: string, dir: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {
     why: `Expected "${file}" in "${dir}" but the file does not exist.`,
-    fix: 'Ensure the migration directory contains both migration.json and ops.json. If the directory is corrupt, delete it and re-run migration plan.',
+    fix: reemitHint(
+      dir,
+      'or delete the directory if the migration is unwanted and the source TypeScript is gone.',
+    ),
     details: { file, dir },
   });
 }
@@ -63,15 +85,15 @@ export function errorMissingFile(file: string, dir: string): MigrationToolsError
 export function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {
     why: `Failed to parse "${filePath}": ${parseError}`,
-    fix: 'Fix the JSON syntax error, or delete the migration directory and re-run migration plan.',
+    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
     details: { filePath, parseError },
   });
 }
 
 export function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {
-    why: `Manifest at "${filePath}" is invalid: ${reason}`,
-    fix: 'Ensure the manifest has all required fields (from, to, kind, toContract). If corrupt, delete and re-plan.',
+    why: `Migration manifest at "${filePath}" is invalid: ${reason}`,
+    fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),
     details: { filePath, reason },
   });
 }
@@ -92,13 +114,17 @@ export function errorInvalidDestName(destName: string): MigrationToolsError {
   });
 }
 
-export function errorSameSourceAndTarget(dirName: string, hash: string): MigrationToolsError {
+export function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {
+  const dirName = basename(dir);
   return new MigrationToolsError(
     'MIGRATION.SAME_SOURCE_AND_TARGET',
     'Migration has same source and target',
     {
       why: `Migration "${dirName}" has from === to === "${hash}". A migration must transition between two different contract states.`,
-      fix: 'Delete the invalid migration directory and re-run migration plan.',
+      fix: reemitHint(
+        dir,
+        'or delete the directory if the migration is unwanted and the source TypeScript is gone.',
+      ),
       details: { dirName, hash },
     },
   );
@@ -175,14 +201,30 @@ export function errorInvalidRefValue(value: string): MigrationToolsError {
   });
 }
 
-export function errorDuplicateMigrationId(migrationId: string): MigrationToolsError {
+export function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {
   return new MigrationToolsError(
-    'MIGRATION.DUPLICATE_MIGRATION_ID',
-    'Duplicate migrationId in migration graph',
+    'MIGRATION.DUPLICATE_MIGRATION_HASH',
+    'Duplicate migrationHash in migration graph',
     {
-      why: `Multiple migrations share migrationId "${migrationId}". Each migration must have a unique content-addressed identity.`,
-      fix: 'Regenerate one of the conflicting migrations so each migrationId is unique, then re-run migration commands.',
-      details: { migrationId },
+      why: `Multiple migrations share migrationHash "${migrationHash}". Each migration must have a unique content-addressed identity.`,
+      fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',
+      details: { migrationHash },
     },
   );
 }
+
+export function errorMigrationHashMismatch(
+  dir: string,
+  storedHash: string,
+  computedHash: string,
+): MigrationToolsError {
+  // Render a cwd-relative path in the human-readable diagnostic so users
+  // running CLI commands from the project root see a familiar short path.
+  // Keep the absolute path in `details.dir` for machine consumers.
+  const relativeDir = relative(process.cwd(), dir);
+  return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {
+    why: `Stored migrationHash "${storedHash}" does not match the recomputed hash "${computedHash}" for "${relativeDir}". The migration.json or ops.json has been edited or partially written since emit.`,
+    fix: reemitHint(dir, 'or restore the directory from version control.'),
+    details: { dir, storedHash, computedHash },
+  });
+}

package/src/exports/errors.ts

@@ -0,0 +1 @@
+export { MigrationToolsError } from '../errors';

package/src/exports/graph.ts

@@ -0,0 +1 @@
+export type { MigrationChainEntry, MigrationGraph } from '../graph';

package/src/exports/hash.ts

@@ -0,0 +1,2 @@
+export type { VerifyResult } from '../hash';
+export { computeMigrationHash, verifyMigrationHash } from '../hash';

package/src/exports/io.ts

@@ -3,7 +3,7 @@ export {
   formatMigrationDirName,
   readMigrationPackage,
   readMigrationsDir,
-  writeMigrationManifest,
+  writeMigrationMetadata,
   writeMigrationOps,
   writeMigrationPackage,
 } from '../io';

package/src/exports/metadata.ts

@@ -0,0 +1 @@
+export type { MigrationHints, MigrationMetadata } from '../metadata';

package/src/exports/package.ts

@@ -0,0 +1 @@
+export type { MigrationOps, MigrationPackage } from '../package';

package/src/graph.ts

@@ -0,0 +1,19 @@
+/**
+ * An entry in the migration graph. All on-disk migrations are attested,
+ * so `migrationHash` is always a string.
+ */
+export interface MigrationChainEntry {
+  readonly from: string;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly dirName: string;
+  readonly createdAt: string;
+  readonly labels: readonly string[];
+}
+
+export interface MigrationGraph {
+  readonly nodes: ReadonlySet<string>;
+  readonly forwardChain: ReadonlyMap<string, readonly MigrationChainEntry[]>;
+  readonly reverseChain: ReadonlyMap<string, readonly MigrationChainEntry[]>;
+  readonly migrationByHash: ReadonlyMap<string, MigrationChainEntry>;
+}

package/src/hash.ts

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { canonicalizeJson } from './canonicalize-json';
+import type { MigrationMetadata } from './metadata';
+import type { MigrationOps, MigrationPackage } from './package';
+
+export interface VerifyResult {
+  readonly ok: boolean;
+  readonly reason?: 'mismatch';
+  readonly storedHash: string;
+  readonly computedHash: string;
+}
+
+function sha256Hex(input: string): string {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+/**
+ * Content-addressed migration hash over (metadata envelope sans
+ * contracts/hints/signature, ops). See ADR 199 — Storage-only migration
+ * identity for the rationale: contracts are anchored separately by the
+ * storage-hash bookends inside the envelope; planner hints are advisory
+ * and must not affect identity.
+ *
+ * The integrity check is purely structural, not semantic. The function
+ * canonicalizes its inputs via `sortKeys` (recursive) + `JSON.stringify`
+ * and hashes the result. Target-specific operation payloads (`step.sql`,
+ * Mongo's pipeline AST, …) are hashed verbatim — no per-target
+ * normalization is required, because what's being verified is "do the
+ * on-disk bytes still produce their recorded hash", not "do two
+ * semantically-equivalent migrations hash the same". The latter is an
+ * emit-drift concern (ADR 192 step 2).
+ *
+ * The symmetry across write and read holds because `JSON.parse(
+ * JSON.stringify(x))` round-trips JSON-safe values losslessly and
+ * `sortKeys` is idempotent and deterministic — write-time and read-time
+ * canonicalization produce the same canonical bytes regardless of
+ * source-side key ordering or whitespace.
+ *
+ * The `migrationHash` field on the metadata is stripped before hashing
+ * so the function can be used both at write time (when no hash exists
+ * yet) and at verify time (rehashing an already-attested record).
+ */
+export function computeMigrationHash(
+  metadata: Omit<MigrationMetadata, 'migrationHash'> & { readonly migrationHash?: string },
+  ops: MigrationOps,
+): string {
+  const {
+    migrationHash: _migrationHash,
+    signature: _signature,
+    fromContract: _fromContract,
+    toContract: _toContract,
+    hints: _hints,
+    ...strippedMeta
+  } = metadata;
+
+  const canonicalMetadata = canonicalizeJson(strippedMeta);
+  const canonicalOps = canonicalizeJson(ops);
+
+  const partHashes = [canonicalMetadata, canonicalOps].map(sha256Hex);
+  const hash = sha256Hex(canonicalizeJson(partHashes));
+
+  return `sha256:${hash}`;
+}
+
+/**
+ * Re-hash an in-memory migration package and compare against the stored
+ * `migrationHash`. See `computeMigrationHash` for the canonicalization rules.
+ *
+ * Returns `{ ok: true }` when the package is internally consistent, or
+ * `{ ok: false, reason: 'mismatch', storedHash, computedHash }` when it is
+ * not — typically a sign of FS corruption, partial writes, or a post-emit
+ * hand edit.
+ */
+export function verifyMigrationHash(pkg: MigrationPackage): VerifyResult {
+  const computed = computeMigrationHash(pkg.metadata, pkg.ops);
+
+  if (pkg.metadata.migrationHash === computed) {
+    return {
+      ok: true,
+      storedHash: pkg.metadata.migrationHash,
+      computedHash: computed,
+    };
+  }
+
+  return {
+    ok: false,
+    reason: 'mismatch',
+    storedHash: pkg.metadata.migrationHash,
+    computedHash: computed,
+  };
+}

package/src/io.ts

@@ -7,9 +7,12 @@ import {
   errorInvalidJson,
   errorInvalidManifest,
   errorInvalidSlug,
+  errorMigrationHashMismatch,
   errorMissingFile,
 } from './errors';
-import type { MigrationBundle, MigrationManifest, MigrationOps } from './types';
+import { verifyMigrationHash } from './hash';
+import type { MigrationMetadata } from './metadata';
+import type { MigrationOps, MigrationPackage } from './package';
 
 const MANIFEST_FILE = 'migration.json';
 const OPS_FILE = 'ops.json';
@@ -25,10 +28,10 @@ const MigrationHintsSchema = type({
   plannerVersion: 'string',
 });
 
-const MigrationManifestSchema = type({
+const MigrationMetadataSchema = type({
   from: 'string',
   to: 'string',
-  migrationId: 'string',
+  migrationHash: 'string',
   kind: "'regular' | 'baseline'",
   fromContract: 'object | null',
   toContract: 'object',
@@ -56,7 +59,7 @@ const MigrationOpsSchema = MigrationOpSchema.array();
 
 export async function writeMigrationPackage(
   dir: string,
-  manifest: MigrationManifest,
+  metadata: MigrationMetadata,
   ops: MigrationOps,
 ): Promise<void> {
   await mkdir(dirname(dir), { recursive: true });
@@ -70,7 +73,9 @@ export async function writeMigrationPackage(
     throw error;
   }
 
-  await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2), { flag: 'wx' });
+  await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(metadata, null, 2), {
+    flag: 'wx',
+  });
   await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });
 }
 
@@ -98,18 +103,18 @@ export async function copyFilesWithRename(
   }
 }
 
-export async function writeMigrationManifest(
+export async function writeMigrationMetadata(
   dir: string,
-  manifest: MigrationManifest,
+  metadata: MigrationMetadata,
 ): Promise<void> {
-  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(metadata, null, 2)}\n`);
 }
 
 export async function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void> {
   await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\n`);
 }
 
-export async function readMigrationPackage(dir: string): Promise<MigrationBundle> {
+export async function readMigrationPackage(dir: string): Promise<MigrationPackage> {
   const manifestPath = join(dir, MANIFEST_FILE);
   const opsPath = join(dir, OPS_FILE);
 
@@ -133,9 +138,9 @@ export async function readMigrationPackage(dir: string): Promise<MigrationBundle
     throw error;
   }
 
-  let manifest: MigrationManifest;
+  let metadata: MigrationMetadata;
   try {
-    manifest = JSON.parse(manifestRaw);
+    metadata = JSON.parse(manifestRaw);
   } catch (e) {
     throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));
   }
@@ -147,22 +152,29 @@ export async function readMigrationPackage(dir: string): Promise<MigrationBundle
     throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));
   }
 
-  validateManifest(manifest, manifestPath);
+  validateMetadata(metadata, manifestPath);
   validateOps(ops, opsPath);
 
-  return {
+  const pkg: MigrationPackage = {
     dirName: basename(dir),
     dirPath: dir,
-    manifest,
+    metadata,
     ops,
   };
+
+  const verification = verifyMigrationHash(pkg);
+  if (!verification.ok) {
+    throw errorMigrationHashMismatch(dir, verification.storedHash, verification.computedHash);
+  }
+
+  return pkg;
 }
 
-function validateManifest(
-  manifest: unknown,
+function validateMetadata(
+  metadata: unknown,
   filePath: string,
-): asserts manifest is MigrationManifest {
-  const result = MigrationManifestSchema(manifest);
+): asserts metadata is MigrationMetadata {
+  const result = MigrationMetadataSchema(metadata);
   if (result instanceof type.errors) {
     throw errorInvalidManifest(filePath, result.summary);
   }
@@ -177,7 +189,7 @@ function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOp
 
 export async function readMigrationsDir(
   migrationsRoot: string,
-): Promise<readonly MigrationBundle[]> {
+): Promise<readonly MigrationPackage[]> {
   let entries: string[];
   try {
     entries = await readdir(migrationsRoot);
@@ -188,7 +200,7 @@ export async function readMigrationsDir(
     throw error;
   }
 
-  const packages: MigrationBundle[] = [];
+  const packages: MigrationPackage[] = [];
 
   for (const entry of entries.sort()) {
     const entryPath = join(migrationsRoot, entry);

package/src/metadata.ts

@@ -0,0 +1,36 @@
+import type { Contract } from '@prisma-next/contract/types';
+
+export interface MigrationHints {
+  readonly used: readonly string[];
+  readonly applied: readonly string[];
+  readonly plannerVersion: string;
+}
+
+/**
+ * In-memory migration metadata envelope. Every migration is content-addressed:
+ * the `migrationHash` is a hash over the metadata envelope plus the operations
+ * list, computed at write time. There is no draft state — a migration
+ * directory either exists with fully attested metadata or it does not.
+ *
+ * When the planner cannot lower an operation because of an unfilled
+ * `placeholder(...)` slot, the migration is still written with `migrationHash`
+ * hashed over `ops: []`. Re-running self-emit after the user fills the
+ * placeholder produces a *different* `migrationHash` (committed to the real
+ * ops); this is intentional.
+ *
+ * The on-disk JSON shape in `migration.json` matches this type field-for-field
+ * — `JSON.stringify(metadata, null, 2)` is the canonical writer output.
+ */
+export interface MigrationMetadata {
+  readonly migrationHash: string;
+  readonly from: string;
+  readonly to: string;
+  readonly kind: 'regular' | 'baseline';
+  readonly fromContract: Contract | null;
+  readonly toContract: Contract;
+  readonly hints: MigrationHints;
+  readonly labels: readonly string[];
+  readonly authorship?: { readonly author?: string; readonly email?: string };
+  readonly signature?: { readonly keyId: string; readonly value: string } | null;
+  readonly createdAt: string;
+}