@crediolabs/policy-synth 0.1.2 → 0.1.4

package/src/predicate/encode.ts

@@ -0,0 +1,307 @@
+// src/predicate/encode.ts - canonical predicate encoder.
+//
+// Pure function. Maps a `PredicateNode` AST to the canonical ScVal wire format
+// described in `packages/policy-interpreter/INTERPRETER_INSTALL_PARAMS.md`:
+//   - every node is a `ScVal::Vec` whose head element is the tag `ScVal::Symbol`
+//   - children of `and` / `or` are sorted ascending by their canonical XDR bytes
+//   - `in` haystacks are ALWAYS sorted by canonical XDR bytes (pure set
+//     membership); an EXACT ordered sequence is expressed as
+//     `eq(selector, literal_vec)` where the `literal_vec` element order is
+//     preserved verbatim (the order IS the semantic)
+//   - `literal_vec` encodes to a bare `ScVal::Vec` of its element encodings;
+//     order is preserved, NOT sorted
+//   - i128 uses `Int128Parts{hi: Int64 (signed), lo: Uint64 (unsigned)}`,
+//     value = hi*2^64 + lo (NOT signed-magnitude)
+//   - no `ScMap` anywhere in the predicate
+//   - `encodedPredicate = base64(root.toXDR())`,
+//     `predicateHash = sha256(raw XDR bytes)` as hex
+//
+// Caps from `PREDICATE_CAPS` are enforced BEFORE returning; a cap breach throws
+// a `ToolError` with the matching error code and `severity: 'error'`.
+
+import { createHash } from 'node:crypto'
+import { Address, xdr } from '@stellar/stellar-sdk'
+import type { ToolError } from '../errors.ts'
+import { PREDICATE_CAPS, type PredicateLeaf, type PredicateNode } from '../types.ts'
+
+export interface EncodedPredicate {
+  /** base64 of the canonical ScVal XDR of the predicate root. */
+  encodedPredicate: string
+  /** sha256 hex digest of the raw XDR bytes (post-canonicalisation). */
+  predicateHash: string
+}
+
+const INT64_MAX = (1n << 63n) - 1n
+const INT64_MIN = -(1n << 63n)
+const UINT64_MAX = (1n << 64n) - 1n
+
+/** Encode a `PredicateNode` to the canonical ScVal wire format and hash it.
+ *  Pure function: same input -> byte-identical output every run. */
+export function encodePredicate(node: PredicateNode): EncodedPredicate {
+  // --- pass 1: structural cap checks (no encoding needed) ---
+  const stats = computeStats(node)
+  if (stats.depth > PREDICATE_CAPS.MAX_DEPTH) {
+    throw capError(
+      'PREDICATE_TOO_DEEP',
+      `predicate depth ${stats.depth} exceeds MAX_DEPTH ${PREDICATE_CAPS.MAX_DEPTH}`
+    )
+  }
+  if (stats.leaves > PREDICATE_CAPS.MAX_LEAVES) {
+    throw capError(
+      'TOO_MANY_LEAVES',
+      `predicate leaf count ${stats.leaves} exceeds MAX_LEAVES ${PREDICATE_CAPS.MAX_LEAVES}`
+    )
+  }
+  for (const c of stats.inCounts) {
+    if (c.count > PREDICATE_CAPS.MAX_IN_OPERAND_COUNT) {
+      throw capError(
+        'IN_OPERAND_LIMIT',
+        `\`in\` operand count ${c.count} exceeds MAX_IN_OPERAND_COUNT ${PREDICATE_CAPS.MAX_IN_OPERAND_COUNT}`
+      )
+    }
+  }
+  // Two-round confirmation costs 2 oracle reads per UNIQUE asset referenced.
+  const oracleReads = stats.oracleAssets.size * 2
+  if (oracleReads > PREDICATE_CAPS.MAX_ORACLE_READS) {
+    throw capError(
+      'PREDICATE_ORACLE_OVER_LIMIT',
+      `oracle reads ${oracleReads} exceed MAX_ORACLE_READS ${PREDICATE_CAPS.MAX_ORACLE_READS}`
+    )
+  }
+
+  // --- pass 2: build + canonicalise the ScVal ---
+  const root = encodeNode(node)
+  const rawBytes = root.toXDR()
+  if (rawBytes.length > PREDICATE_CAPS.MAX_PREDICATE_BYTES) {
+    throw capError(
+      'PREDICATE_TOO_LARGE',
+      `predicate bytes ${rawBytes.length} exceed MAX_PREDICATE_BYTES ${PREDICATE_CAPS.MAX_PREDICATE_BYTES}`
+    )
+  }
+  const encodedPredicate = rawBytes.toString('base64')
+  const predicateHash = createHash('sha256').update(rawBytes).digest('hex')
+  return { encodedPredicate, predicateHash }
+}
+
+interface PredicateStats {
+  depth: number
+  leaves: number
+  inCounts: Array<{ count: number }>
+  /** Unique assets referenced by `oracle_price` leaves - each costs 2 reads. */
+  oracleAssets: Set<string>
+}
+
+function computeStats(node: PredicateNode): PredicateStats {
+  const inCounts: Array<{ count: number }> = []
+  const oracleAssets = new Set<string>()
+  const { depth, leaves } = walk(node, inCounts, oracleAssets)
+  return { depth, leaves, inCounts, oracleAssets }
+}
+
+function walk(
+  node: PredicateNode,
+  inCounts: Array<{ count: number }>,
+  oracleAssets: Set<string>
+): { depth: number; leaves: number } {
+  switch (node.op) {
+    case 'and':
+    case 'or': {
+      if (node.children.length === 0) return { depth: 1, leaves: 0 }
+      let maxChildDepth = 0
+      let totalLeaves = 0
+      for (const c of node.children) {
+        const child = walk(c, inCounts, oracleAssets)
+        if (child.depth > maxChildDepth) maxChildDepth = child.depth
+        totalLeaves += child.leaves
+      }
+      return { depth: maxChildDepth + 1, leaves: totalLeaves }
+    }
+    case 'not': {
+      const child = walk(node.child, inCounts, oracleAssets)
+      return { depth: child.depth + 1, leaves: child.leaves }
+    }
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte': {
+      collectOracle(node.left, oracleAssets)
+      collectOracle(node.right, oracleAssets)
+      return { depth: 1, leaves: leafCount(node.left) + leafCount(node.right) }
+    }
+    case 'in': {
+      inCounts.push({ count: node.haystack.length })
+      collectOracle(node.needle, oracleAssets)
+      let haystackLeaves = 0
+      for (const h of node.haystack) {
+        collectOracle(h, oracleAssets)
+        haystackLeaves += leafCount(h)
+      }
+      return {
+        depth: 1,
+        leaves: leafCount(node.needle) + haystackLeaves,
+      }
+    }
+  }
+}
+
+/** Leaf-count contribution of one PredicateLeaf: 1 for any flat leaf, and the
+ *  sum of element leaf counts for `literal_vec` so MAX_LEAVES caps see nested
+ *  vector elements. */
+function leafCount(leaf: PredicateLeaf): number {
+  if (leaf.kind === 'literal_vec') {
+    let total = 1 // the literal_vec itself counts as one leaf node
+    for (const el of leaf.elements) total += leafCount(el)
+    return total
+  }
+  return 1
+}
+
+function collectOracle(leaf: PredicateLeaf, oracleAssets: Set<string>): void {
+  // literal_vec is the only nested leaf; recurse so an oracle_price buried in a
+  // vector literal (which the lowering would forbid, but the cap-walker must
+  // still see) is counted toward the oracle-read budget.
+  if (leaf.kind === 'oracle_price') {
+    oracleAssets.add(leaf.asset)
+  } else if (leaf.kind === 'literal_vec') {
+    for (const el of leaf.elements) collectOracle(el, oracleAssets)
+  }
+}
+
+function encodeNode(node: PredicateNode): xdr.ScVal {
+  switch (node.op) {
+    case 'and':
+    case 'or': {
+      const encoded = node.children.map(encodeNode)
+      // sort children by their canonical XDR bytes ascending.
+      const sorted = sortByCanonicalBytes(encoded)
+      return xdr.ScVal.scvVec([symbol(node.op), xdr.ScVal.scvVec(sorted)])
+    }
+    case 'not': {
+      return xdr.ScVal.scvVec([symbol('not'), encodeNode(node.child)])
+    }
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte': {
+      return xdr.ScVal.scvVec([symbol(node.op), encodeLeaf(node.left), encodeLeaf(node.right)])
+    }
+    case 'in': {
+      const needle = encodeLeaf(node.needle)
+      // `in` is PURE set membership: the haystack is ALWAYS sorted by canonical
+      // XDR bytes ascending. An exact ordered sequence (e.g. a swap hop path)
+      // is expressed as `eq(selector, literal_vec)` where the vec's element
+      // order is preserved verbatim (handled in `encodeLeaf(literal_vec)`).
+      const haystack = sortByCanonicalBytes(node.haystack.map(encodeLeaf))
+      return xdr.ScVal.scvVec([symbol('in'), needle, xdr.ScVal.scvVec(haystack)])
+    }
+  }
+}
+
+function encodeLeaf(leaf: PredicateLeaf): xdr.ScVal {
+  switch (leaf.kind) {
+    case 'call_contract':
+      return xdr.ScVal.scvVec([symbol('call_contract')])
+    case 'call_fn':
+      return xdr.ScVal.scvVec([symbol('call_fn')])
+    case 'call_arg':
+      return xdr.ScVal.scvVec([symbol('call_arg'), xdr.ScVal.scvU32(leaf.index)])
+    case 'amount':
+      return xdr.ScVal.scvVec([symbol('amount'), scvAddressFromStrkey(leaf.token)])
+    case 'window_spent':
+      return xdr.ScVal.scvVec([
+        symbol('window_spent'),
+        scvAddressFromStrkey(leaf.token),
+        scvU64FromValue(leaf.windowSeconds),
+      ])
+    case 'now':
+      return xdr.ScVal.scvVec([symbol('now')])
+    case 'valid_until':
+      return xdr.ScVal.scvVec([symbol('valid_until')])
+    case 'invocation_count_in_window':
+      return xdr.ScVal.scvVec([symbol('invocation_count'), scvU64FromValue(leaf.windowSecs)])
+    case 'oracle_price':
+      return xdr.ScVal.scvVec([symbol('oracle_price'), scvAddressFromStrkey(leaf.asset)])
+    case 'literal_address':
+      return scvAddressFromStrkey(leaf.value)
+    case 'literal_i128':
+      return scvI128FromDecimal(leaf.value)
+    case 'literal_symbol':
+      return xdr.ScVal.scvSymbol(leaf.value)
+    case 'literal_u32':
+      return xdr.ScVal.scvU32(leaf.value)
+    case 'literal_u64':
+      return scvU64FromValue(leaf.value)
+    case 'literal_bytes':
+      return xdr.ScVal.scvBytes(Buffer.from(leaf.value, 'hex'))
+    case 'literal_vec':
+      // Bare ScVal::Vec of element encodings - order is preserved verbatim
+      // because the order IS the semantic (exact ordered sequence equality).
+      return xdr.ScVal.scvVec(leaf.elements.map(encodeLeaf))
+  }
+}
+
+function symbol(s: string): xdr.ScVal {
+  return xdr.ScVal.scvSymbol(s)
+}
+
+function sortByCanonicalBytes(values: xdr.ScVal[]): xdr.ScVal[] {
+  const pairs = values.map((v) => ({ v, bytes: v.toXDR() }))
+  pairs.sort((a, b) => Buffer.compare(a.bytes, b.bytes))
+  return pairs.map((p) => p.v)
+}
+
+function scvAddressFromStrkey(strkey: string): xdr.ScVal {
+  return xdr.ScVal.scvAddress(Address.fromString(strkey).toScAddress())
+}
+
+function scvU64FromValue(value: number | string): xdr.ScVal {
+  // The Uint64 (UnsignedHyper) constructor accepts string | bigint | number;
+  // string is safest for values > 2^53.
+  return xdr.ScVal.scvU64(new xdr.Uint64(String(value)))
+}
+
+/** Build `ScVal::I128(Int128Parts{hi, lo})` from a signed decimal string.
+ *  `Int128Parts` encodes the value as `(hi << 64) + lo` with `hi` a SIGNED
+ *  64-bit int and `lo` an UNSIGNED 64-bit int (this is NOT signed-magnitude).
+ *  The inverse split is `hi = v >> 64n` (arithmetic right shift) and
+ *  `lo = v & 0xFFFF...`. The SDK's `Int64` constructor takes a signed
+ *  bigint/string/number. */
+function scvI128FromDecimal(decimal: string): xdr.ScVal {
+  const v = BigInt(decimal)
+  const hi = v >> 64n
+  const lo = v & UINT64_MAX
+  // Guard against accidental over-range. Int128Parts.hi must be a valid Int64
+  // (-2^63 .. 2^63-1); values outside this range are invalid i128 entirely.
+  if (hi < INT64_MIN || hi > INT64_MAX) {
+    throw capError(
+      'MALFORMED_PREDICATE',
+      `literal_i128 value ${decimal} is outside the Int128 range`
+    )
+  }
+  if (lo < 0n || lo > UINT64_MAX) {
+    throw capError(
+      'MALFORMED_PREDICATE',
+      `literal_i128 value ${decimal} has an invalid Int128Parts.lo`
+    )
+  }
+  return xdr.ScVal.scvI128(
+    new xdr.Int128Parts({
+      hi: new xdr.Int64(hi),
+      lo: new xdr.Uint64(lo),
+    })
+  )
+}
+
+function capError(code: ToolError['code'], message: string): ToolError {
+  const err = new Error(message) as Error & {
+    code: ToolError['code']
+    severity: string
+    retryable: boolean
+  }
+  err.code = code
+  err.severity = 'error'
+  err.retryable = false
+  throw err
+}

package/src/predicate/index.ts

@@ -0,0 +1,3 @@
+// src/predicate/index.ts - re-export the canonical predicate encoder.
+
+export { type EncodedPredicate, encodePredicate } from './encode.ts'

package/src/review-card/builder.ts

@@ -0,0 +1,303 @@
+// src/review-card/builder.ts - deterministic, pure review-card summary
+// builder.
+//
+// `buildReviewCardSummary` renders the per-policy text the user-facing review
+// card quotes. The whole DX win of non-engineer reviewability hinges on the
+// summary being REPRODUCIBLE + TESTABLE + NON-HALLUCINABLE, so this module is
+// pure: same inputs -> byte-identical output, no clock, no randomness, no I/O.
+//
+// The builder walks two inputs and emits ONE constraint string per leaf or
+// primitive, in a fixed deterministic order:
+//
+//   1. The OZ built-in `PolicyRef`s. Each `spending_limit` primitive becomes a
+//      `spending_limit(token, limitAmount, windowSecs)` line; other OZ
+//      primitives (threshold) are skipped - the review card does not quote
+//      them (they are signer-config concerns, not transactional bounds).
+//
+//   2. The interpreter `PredicateNode`. One string per constraint leaf,
+//      rendered by enclosing-comparison kind. Templates (Task 7b):
+//        - invocation_count_in_window <= N    -> Invocations <= N per <window> seconds
+//        - call_arg[i] in [list]              -> Recipient/arg must be one of [list]
+//        - eq(call_arg[i], literal_vec[...])  -> Path must be exactly [list]
+//        - oracle_price(asset) OP price       -> Only when oracle_price(asset) OP price
+//        - call_fn == x                       -> Function must be x
+//        - call_contract == c                 -> Contract must be c
+//        - amount <= v                        -> Amount <= v
+//
+// The content hash is a stable sha256 hex of a canonical JSON of
+// { ruleName, plainEnglish, constraints, expiry, backend } - identical
+// inputs (incl. the context-rule expiry and simulation backend) -> identical
+// hash. There is no clock; the hash never includes a timestamp.
+
+import { createHash } from 'node:crypto'
+import type {
+  ContextRuleDraft,
+  OZPrimitiveConfig,
+  PolicyRef,
+  PredicateLeaf,
+  PredicateNode,
+} from '../types.ts'
+import type { SimulationResult } from '../verify/envelope.ts'
+
+export interface ReviewCardSummary {
+  ruleName: string
+  plainEnglish: string
+  constraints: string[]
+  expiry: string
+  backend: 'interpreter-v1' | 'ts-model'
+  /** Stable hash of the builder inputs - identical policy + summary = identical hash. */
+  contentHash: string
+}
+
+/** Build a deterministic review-card summary from a policy + context rule +
+ *  simulation result. Pure: same inputs -> byte-identical output. */
+export function buildReviewCardSummary(
+  predicate: PredicateNode | null,
+  policyRefs: PolicyRef[],
+  contextRule: ContextRuleDraft,
+  simulation: SimulationResult
+): ReviewCardSummary {
+  const constraints: string[] = []
+  for (const ref of policyRefs) {
+    const line = renderOzPrimitive(ref)
+    if (line !== null) constraints.push(line)
+  }
+  if (predicate !== null) {
+    walkPredicate(predicate, (node) => {
+      const line = renderConstraint(node)
+      if (line !== null) constraints.push(line)
+    })
+  }
+
+  const ruleName = contextRule.name
+  const plainEnglish = renderPlainEnglish(ruleName, constraints)
+  const expiry = renderExpiry(contextRule.validUntilLedger)
+  const backend = simulation.backend
+
+  const contentHash = computeContentHash({
+    ruleName,
+    plainEnglish,
+    constraints,
+    expiry,
+    backend,
+  })
+
+  return { ruleName, plainEnglish, constraints, expiry, backend, contentHash }
+}
+
+/** Render the OZ built-in primitive summary line. Only `spending_limit` is
+ *  quoted by the review card (it is the only primitive that defines a
+ *  transactional bound). Other primitives (threshold) are signer-config
+ *  concerns handled by the OZ adapter's own `uncovered` machinery.
+ *  Spending_limit takes `period_ledgers` on-chain (~5s/ledger); the card
+ *  states the window in seconds so the user reads it consistently with the
+ *  interpreter templates. */
+function renderOzPrimitive(ref: PolicyRef): string | null {
+  if (ref.kind !== 'oz_builtin') return null
+  const primitive: OZPrimitiveConfig = ref.primitive
+  if (primitive.primitive !== 'spending_limit') return null
+  const params = primitive.params as { spending_limit?: string; period_ledgers?: number }
+  const limit = params.spending_limit ?? '0'
+  const periodLedgers = params.period_ledgers ?? 0
+  const windowSecs = periodLedgers * 5
+  return `spending_limit(${limit}, ${windowSecs})`
+}
+
+/** Walk every comparison / membership node of the predicate and invoke
+ *  `visit` on each. The walk is depth-first, left-to-right, so the
+ *  constraint list is stable across runs. Pure boolean nodes contribute no
+ *  constraint lines themselves; their leaf children do, via the visitor. */
+function walkPredicate(node: PredicateNode, visit: (node: PredicateNode) => void): void {
+  switch (node.op) {
+    case 'and':
+    case 'or':
+      for (const child of node.children) walkPredicate(child, visit)
+      return
+    case 'not':
+      walkPredicate(node.child, visit)
+      return
+    case 'in':
+      visit(node)
+      return
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      visit(node)
+      return
+  }
+}
+
+/** Render ONE constraint sentence for ONE interpreter predicate node. The
+ *  shape of the output is pinned by Task 7b so the test suite can assert
+ *  byte-for-byte equality. Returns `null` when the node is a structural
+ *  boolean (`and` / `or` / `not`) - those are not constraint leaves. */
+function renderConstraint(node: PredicateNode): string | null {
+  switch (node.op) {
+    case 'and':
+    case 'or':
+    case 'not':
+      return null
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      return renderComparison(node)
+    case 'in':
+      return renderMembership(node)
+  }
+}
+
+function renderComparison(
+  node: Extract<PredicateNode, { op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte' }>
+): string | null {
+  const left = node.left
+  const right = node.right
+
+  // eq(call_contract, literal_address) -> Contract must be <addr>
+  if (left.kind === 'call_contract' && node.op === 'eq' && right.kind === 'literal_address') {
+    return `Contract must be ${right.value}`
+  }
+
+  // eq(call_fn, literal_symbol) -> Function must be <sym>
+  if (left.kind === 'call_fn' && node.op === 'eq' && right.kind === 'literal_symbol') {
+    return `Function must be ${right.value}`
+  }
+
+  // eq(call_arg[i], literal_vec) -> Path must be exactly [list]
+  if (left.kind === 'call_arg' && node.op === 'eq' && right.kind === 'literal_vec') {
+    return `Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`
+  }
+
+  // invocation_count_in_window <= N -> Invocations <= N per <window> seconds
+  if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
+    return `Invocations <= ${right.value} per ${left.windowSecs} seconds`
+  }
+
+  // amount <= v -> Amount <= v
+  if (left.kind === 'amount' && right.kind === 'literal_i128') {
+    return `Amount <= ${right.value}`
+  }
+
+  // oracle_price(asset) OP price -> Only when oracle_price(asset) OP price
+  if (left.kind === 'oracle_price' && right.kind === 'literal_i128') {
+    return `Only when oracle_price(${left.asset}) ${comparisonOpText(node.op)} ${right.value}`
+  }
+
+  // Any other comparison shape is a structural fail-closed: do not surface
+  // a misleading line. Cross-check still requires every leaf produce a
+  // constraint string; the only leaves we emit lines for are the ones we
+  // recognise above, so the test fixtures cover exactly the supported
+  // shapes.
+  return null
+}
+
+function renderMembership(node: Extract<PredicateNode, { op: 'in' }>): string | null {
+  // call_arg[i] in [list] -> Recipient/arg must be one of [list]
+  if (node.needle.kind === 'call_arg') {
+    const list = node.haystack.map(renderHaystackElement).join(', ')
+    return `Recipient/arg must be one of [${list}]`
+  }
+  return null
+}
+
+function renderVecElement(leaf: PredicateLeaf): string {
+  switch (leaf.kind) {
+    case 'literal_address':
+      return leaf.value
+    case 'literal_i128':
+      return leaf.value
+    case 'literal_symbol':
+      return leaf.value
+    case 'literal_u32':
+      return String(leaf.value)
+    case 'literal_u64':
+      return leaf.value
+    case 'literal_bytes':
+      return leaf.value
+    case 'literal_vec':
+      return `[${leaf.elements.map(renderVecElement).join(', ')}]`
+    case 'call_contract':
+    case 'call_fn':
+    case 'call_arg':
+    case 'amount':
+    case 'window_spent':
+    case 'now':
+    case 'valid_until':
+    case 'invocation_count_in_window':
+    case 'oracle_price':
+      return `<${leaf.kind}>`
+  }
+}
+
+function renderHaystackElement(leaf: PredicateLeaf): string {
+  if (leaf.kind === 'literal_address') return leaf.value
+  if (leaf.kind === 'literal_i128') return leaf.value
+  if (leaf.kind === 'literal_symbol') return leaf.value
+  if (leaf.kind === 'literal_u32') return String(leaf.value)
+  if (leaf.kind === 'literal_u64') return leaf.value
+  if (leaf.kind === 'literal_bytes') return leaf.value
+  if (leaf.kind === 'literal_vec') {
+    return `[${leaf.elements.map(renderHaystackElement).join(', ')}]`
+  }
+  return `<${leaf.kind}>`
+}
+
+function comparisonOpText(op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte'): string {
+  switch (op) {
+    case 'lt':
+      return '<'
+    case 'lte':
+      return '<='
+    case 'gt':
+      return '>'
+    case 'gte':
+      return '>='
+    case 'eq':
+      return '=='
+  }
+}
+
+/** Render the plain-English one-liner. Format: `<ruleName>: <constraints>`,
+ *  joined by `; ` so the user reads one sentence per constraint. */
+function renderPlainEnglish(ruleName: string, constraints: string[]): string {
+  if (constraints.length === 0) return `${ruleName}: (no constraints)`
+  return `${ruleName}: ${constraints.join('; ')}`
+}
+
+/** Render the expiry line. `null` -> "No expiry"; a ledger sequence -> the
+ *  ledger number so the user reads it in the same units the OZ context rule
+ *  applies it. */
+function renderExpiry(validUntilLedger: number | null): string {
+  if (validUntilLedger === null) return 'No expiry'
+  return `Valid until ledger ${validUntilLedger}`
+}
+
+function computeContentHash(input: {
+  ruleName: string
+  plainEnglish: string
+  constraints: string[]
+  expiry: string
+  backend: 'interpreter-v1' | 'ts-model'
+}): string {
+  return createHash('sha256').update(canonicalStringify(input)).digest('hex')
+}
+
+/** Canonical JSON with recursively sorted object keys (stable across runs). */
+function canonicalStringify(value: unknown): string {
+  return JSON.stringify(sortKeys(value))
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = sortKeys((value as Record<string, unknown>)[key])
+    }
+    return out
+  }
+  return value
+}