feat(pre-registration): expose hashJson + canonicalize for arbitrary content signing (#32)

The canonicalize+sha256 logic that signManifest is built on is general enough
that consumers signing arbitrary structured content (artifact bundles,
production packets, dataset versions, etc.) end up reimplementing it from
scratch. Two cases I checked while making this change:

  - physim/apps/server/src/lib/manifest.ts re-implements canonicalize+sha256
    for production-packet attestation, with an inline comment noting that
    agent-eval's signer is shaped for HypothesisManifest only.
  - phony/products/builder/api/src/eval/champion-sign.ts re-implements the
    same canonicalize+sha256 (sync variant) before wrapping in Ed25519.

Both pieces of duplication go away if the generic primitive is exposed.

This change:

  - Lifts the previously-private `canonicalize(v: unknown)` to an exported
    function. Recursive key-sort, primitives pass through, arrays preserve
    order. Behavior unchanged from the inlined version.

  - Adds `hashJson<T>(obj: T): Promise<string>` — sha256 hex (full 64 chars)
    over the canonicalized JSON encoding. The same primitive signManifest is
    built on, refactored to call through.

  - Naming: I went with `hashJson` rather than `hashContent` because
    prompt-registry already exports `hashContent(s: string)` for the
    truncated 12-char prompt-id helper. Different semantics (string in,
    short id out) — the two coexist, named for what each actually does.

Backward compat: signManifest / verifyManifest output bit-for-bit identical
hashes (verified by a new test that compares hashJson(base) directly against
signManifest(base).contentHash). All 827 existing tests still pass.

Tests added:
  - canonicalize sorts keys recursively + preserves array order + passes primitives
  - hashJson is stable across key insertion order
  - hashJson(base) === signManifest(base).contentHash (composition guarantee)
  - hashJson and prompt-registry's hashContent are independent (different return shape)

Author: drewstone

src/index.ts

@@ -497,7 +497,13 @@ export type {
   CrossTraceDiffOptions,
 } from './cross-trace-diff'
 
-export { signManifest, verifyManifest, evaluateHypothesis } from './pre-registration'
+export {
+  signManifest,
+  verifyManifest,
+  evaluateHypothesis,
+  hashJson,
+  canonicalize,
+} from './pre-registration'
 export type {
   HypothesisManifest,
   SignedManifest,

src/pre-registration.ts

@@ -72,6 +72,55 @@ export interface HypothesisResult {
   notes?: string
 }
 
+/**
+ * Deterministic JSON canonicalization — sort object keys recursively.
+ *
+ * Two semantically-equal objects produce byte-identical canonicalized output;
+ * this is what makes a content-hash stable across encoders, key insertion
+ * orders, and runtime versions. Exported for any consumer that needs the same
+ * canonicalization guarantee outside the manifest-signing path (e.g., signing
+ * an artifact bundle, hashing a dataset version, etc.).
+ */
+export function canonicalize(v: unknown): unknown {
+  if (v === null || typeof v !== 'object') return v
+  if (Array.isArray(v)) return v.map(canonicalize)
+  const keys = Object.keys(v as Record<string, unknown>).sort()
+  const out: Record<string, unknown> = {}
+  for (const k of keys) out[k] = canonicalize((v as Record<string, unknown>)[k])
+  return out
+}
+
+/**
+ * SHA-256 hex (full 64 chars) over the canonicalized JSON encoding of `obj`.
+ *
+ * The same primitive `signManifest` and `verifyManifest` are built on, exposed
+ * directly so consumers signing arbitrary structured content (artifact bundles,
+ * production packets, dataset manifests, etc.) don't have to re-derive
+ * canonicalize+sha256 from scratch.
+ *
+ * Stable across:
+ *   - object key insertion order (canonicalization sorts keys recursively)
+ *   - encoder choice (UTF-8 via TextEncoder, fixed)
+ *   - runtime (uses the Web Crypto subtle digest, present in Node ≥18 and browsers)
+ *
+ * Naming note: `hashJson` rather than `hashContent` because `hashContent` is
+ * already taken in `prompt-registry.ts` for the truncated 12-char prompt-id
+ * helper, which has different semantics (string input, short return). Both
+ * coexist; `hashJson` is the right name when you mean "canonicalize then hash."
+ *
+ * @example
+ *   const hash = await hashJson({ id: '1', kind: 'spec' })
+ *   // 'a3f1...' (64 hex chars)
+ */
+export async function hashJson<T>(obj: T): Promise<string> {
+  const canonical = canonicalize(obj)
+  const bytes = new TextEncoder().encode(JSON.stringify(canonical))
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
 /**
  * Sign a manifest with a SHA-256 content hash.
  *
@@ -83,12 +132,7 @@ export interface HypothesisResult {
  * hashing on both sides.
  */
 export async function signManifest(m: HypothesisManifest): Promise<SignedManifest> {
-  const canonical = canonicalize(m)
-  const bytes = new TextEncoder().encode(JSON.stringify(canonical))
-  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
-  const hash = Array.from(new Uint8Array(digest))
-    .map((b) => b.toString(16).padStart(2, '0'))
-    .join('')
+  const hash = await hashJson(m)
   return { ...m, contentHash: hash, algo: 'sha256-content' }
 }
 
@@ -133,12 +177,3 @@ export async function evaluateHypothesis(
     rejectionReasons: reasons,
   }
 }
-
-function canonicalize(v: unknown): unknown {
-  if (v === null || typeof v !== 'object') return v
-  if (Array.isArray(v)) return v.map(canonicalize)
-  const keys = Object.keys(v as Record<string, unknown>).sort()
-  const out: Record<string, unknown> = {}
-  for (const k of keys) out[k] = canonicalize((v as Record<string, unknown>)[k])
-  return out
-}

tests/tier2.test.ts

@@ -11,7 +11,9 @@ import {
 } from '../src/counterfactual'
 import { crossTraceDiff } from '../src/cross-trace-diff'
 import {
+  canonicalize,
   evaluateHypothesis,
+  hashJson,
   signManifest,
   verifyManifest,
   type HypothesisManifest,
@@ -172,4 +174,37 @@ describe('pre-registration', () => {
       evaluateHypothesis(tampered, { n: 30, effect: 0.003, pValue: 0.01 }),
     ).rejects.toThrow(/tampered|hash/i)
   })
+
+  it('canonicalize sorts keys recursively and produces stable encoding', () => {
+    const a = canonicalize({ b: 2, a: { y: [3, 2, 1], x: 'k' } })
+    const b = canonicalize({ a: { x: 'k', y: [3, 2, 1] }, b: 2 })
+    expect(JSON.stringify(a)).toBe(JSON.stringify(b))
+    // Arrays preserve order (canonicalization sorts object keys, not array elements).
+    expect(JSON.stringify(canonicalize([3, 1, 2]))).toBe('[3,1,2]')
+    // Primitives pass through.
+    expect(canonicalize(42)).toBe(42)
+    expect(canonicalize('s')).toBe('s')
+    expect(canonicalize(null)).toBe(null)
+  })
+
+  it('hashJson is stable across key insertion order — the property signManifest depends on', async () => {
+    const ordered = await hashJson({ b: 2, a: 1 })
+    const reordered = await hashJson({ a: 1, b: 2 })
+    expect(ordered).toBe(reordered)
+    expect(ordered).toMatch(/^[0-9a-f]{64}$/)
+  })
+
+  it('hashJson matches signManifest contentHash for the same payload — generic primitive composes with the manifest signer', async () => {
+    const signed = await signManifest(base)
+    const direct = await hashJson(base)
+    expect(signed.contentHash).toBe(direct)
+  })
+
+  it('hashJson and prompt-registry hashContent are independent functions — different return shape', async () => {
+    // Regression: don't accidentally collapse the two. hashContent (prompt-registry)
+    // returns a 12-char id over a string. hashJson (here) returns 64 hex chars over
+    // canonicalized JSON.
+    const long = await hashJson('x')
+    expect(long).toMatch(/^[0-9a-f]{64}$/)
+  })
 })