@adrkit/evaluator 0.1.0

package/src/catalog.ts

@@ -0,0 +1,263 @@
+/**
+ * @adrkit/evaluator — fixed Pass 0 catalog.
+ *
+ * The eleven rule ids (fixed rubric order + fixed severity), the exhaustive,
+ * namespaced reason-code catalog, the per-rule primary-reason precedence, and the
+ * eight ordered routing triggers. These are the frozen contract vocabulary
+ * (data-model §7/§8/§11; research §R12). Adding or renaming a code is a versioned
+ * contract change, never a silent edit.
+ */
+
+import type { Severity } from '@adrkit/core';
+
+/** The eleven rubric rule ids, in fixed order (FR-002, C11). */
+export const RULE_IDS = [
+  'schema-valid',
+  'id-unique',
+  'supersession-consistent',
+  'no-orphan-refs',
+  'affects-resolvable',
+  'affects-overlap',
+  'scope-hierarchy',
+  'assertions-compile',
+  'assertions-pass',
+  'decider-resolvable',
+  'expiry-sane',
+] as const;
+
+export type RuleId = (typeof RULE_IDS)[number];
+
+/** Fixed severity per rule. Present on a result only when `status === 'fail'`. */
+export const RULE_SEVERITY: Readonly<Record<RuleId, Severity>> = {
+  'schema-valid': 'error',
+  'id-unique': 'error',
+  'supersession-consistent': 'error',
+  'no-orphan-refs': 'error',
+  'affects-resolvable': 'warn',
+  'affects-overlap': 'warn',
+  'scope-hierarchy': 'error',
+  'assertions-compile': 'error',
+  'assertions-pass': 'warn',
+  'decider-resolvable': 'warn',
+  'expiry-sane': 'info',
+};
+
+/** The eight Pass-0-provable escalation triggers, in fixed order (C4, R10). */
+export const ROUTING_TRIGGERS = [
+  'one-way-door',
+  'cost-threshold',
+  'security-surface',
+  'data-residency',
+  'regulatory',
+  'contradicts-accepted-adr',
+  'agent-authored-production',
+  'human-requested',
+] as const;
+
+export type Pass0EscalationReason = (typeof ROUTING_TRIGGERS)[number];
+
+/**
+ * Exhaustive, stable, namespaced reason codes (data-model §11). The order within a
+ * rule's group is that rule's primary-reason precedence: the aggregate `reason` is
+ * the first code in this order among the sub-findings that share the winning status.
+ */
+export const REASON_CODES = [
+  // schema-valid
+  'schema-valid.ok',
+  'schema-valid.file-read',
+  'schema-valid.parse-error',
+  'schema-valid.contract-error',
+  // id-unique
+  'id-unique.ok',
+  'id-unique.collision',
+  // supersession-consistent
+  'supersession-consistent.ok',
+  'supersession-consistent.dangling-superseded-by',
+  'supersession-consistent.non-reciprocal',
+  'supersession-consistent.cycle',
+  // no-orphan-refs
+  'no-orphan-refs.ok',
+  'no-orphan-refs.dangling-supersedes',
+  'no-orphan-refs.dangling-relates-to',
+  'no-orphan-refs.federated-log-absent',
+  // affects-resolvable
+  'affects-resolvable.ok',
+  'affects-resolvable.zero-targets',
+  'affects-resolvable.backing-absent',
+  'affects-resolvable.resolver-absent',
+  // affects-overlap (special primary precedence, §3.1)
+  'affects-overlap.accepted-intersection',
+  'affects-overlap.no-accepted-corpus',
+  'affects-overlap.backing-absent',
+  'affects-overlap.none',
+  // scope-hierarchy
+  'scope-hierarchy.ok',
+  'scope-hierarchy.contradicts-org-assertion',
+  'scope-hierarchy.evidence-absent',
+  'scope-hierarchy.engine-absent',
+  'scope-hierarchy.source-absent',
+  'scope-hierarchy.base-input-absent',
+  'scope-hierarchy.proposed-input-absent',
+  'scope-hierarchy.not-applicable-scope',
+  // assertions-compile
+  'assertions-compile.ok',
+  'assertions-compile.none',
+  'assertions-compile.no-source',
+  'assertions-compile.ambiguous-source',
+  'assertions-compile.parse-error',
+  'assertions-compile.engine-absent',
+  'assertions-compile.source-absent',
+  // assertions-pass
+  'assertions-pass.ok',
+  'assertions-pass.none',
+  'assertions-pass.evaluates-false',
+  'assertions-pass.evaluation-error',
+  'assertions-pass.engine-absent',
+  'assertions-pass.input-absent',
+  // decider-resolvable
+  'decider-resolvable.ok',
+  'decider-resolvable.none-declared',
+  'decider-resolvable.zero-match',
+  'decider-resolvable.ambiguous-match',
+  'decider-resolvable.directory-absent',
+  // expiry-sane
+  'expiry-sane.ok',
+  'expiry-sane.past-or-equal',
+  // shared not-evaluated
+  'not-evaluated.schema-invalid',
+  'not-evaluated.prereq-failed',
+  // routing evidence (escalate)
+  'route.escalate.one-way-door',
+  'route.escalate.cost-threshold',
+  'route.escalate.security-surface',
+  'route.escalate.data-residency',
+  'route.escalate.regulatory',
+  'route.escalate.contradicts-accepted-adr',
+  'route.escalate.agent-authored-production',
+  'route.escalate.human-requested',
+  // routing evidence (not-proven)
+  'route.evidence.one-way-door.not-proven',
+  'route.evidence.cost-threshold.not-proven',
+  'route.evidence.security-surface.not-proven',
+  'route.evidence.data-residency.not-proven',
+  'route.evidence.regulatory.not-proven',
+  'route.evidence.contradicts-accepted-adr.not-proven',
+  'route.evidence.agent-authored-production.not-proven',
+  'route.evidence.human-requested.not-proven',
+  // route targets
+  'route.target.not-required',
+  'route.target.deciders',
+  'route.target.codeowners',
+  'route.target.catalog-owner',
+  'route.target.unresolved',
+] as const;
+
+export type ReasonCode = (typeof REASON_CODES)[number];
+
+const REASON_CODE_SET: ReadonlySet<string> = new Set(REASON_CODES);
+
+export function isReasonCode(value: string): value is ReasonCode {
+  return REASON_CODE_SET.has(value);
+}
+
+/**
+ * Per-rule primary-reason precedence, derived from the catalog groupings above.
+ * The aggregate reason is the first entry present among the winning-status
+ * sub-findings; a clean rule with no sub-findings uses its first (`.ok`) entry,
+ * except `affects-overlap`, whose fixed precedence is documented in §3.1.
+ */
+export const RULE_REASON_PRECEDENCE: Readonly<Record<RuleId, readonly ReasonCode[]>> = {
+  'schema-valid': [
+    'schema-valid.ok',
+    'schema-valid.file-read',
+    'schema-valid.parse-error',
+    'schema-valid.contract-error',
+  ],
+  'id-unique': ['id-unique.ok', 'id-unique.collision'],
+  'supersession-consistent': [
+    'supersession-consistent.ok',
+    'supersession-consistent.dangling-superseded-by',
+    'supersession-consistent.non-reciprocal',
+    'supersession-consistent.cycle',
+  ],
+  'no-orphan-refs': [
+    'no-orphan-refs.ok',
+    'no-orphan-refs.dangling-supersedes',
+    'no-orphan-refs.dangling-relates-to',
+    'no-orphan-refs.federated-log-absent',
+  ],
+  'affects-resolvable': [
+    'affects-resolvable.ok',
+    'affects-resolvable.zero-targets',
+    'affects-resolvable.backing-absent',
+    'affects-resolvable.resolver-absent',
+  ],
+  'affects-overlap': [
+    'affects-overlap.accepted-intersection',
+    'affects-overlap.no-accepted-corpus',
+    'affects-overlap.backing-absent',
+    'affects-overlap.none',
+  ],
+  'scope-hierarchy': [
+    'scope-hierarchy.ok',
+    'scope-hierarchy.contradicts-org-assertion',
+    'scope-hierarchy.evidence-absent',
+    'scope-hierarchy.engine-absent',
+    'scope-hierarchy.source-absent',
+    'scope-hierarchy.base-input-absent',
+    'scope-hierarchy.proposed-input-absent',
+    'scope-hierarchy.not-applicable-scope',
+  ],
+  'assertions-compile': [
+    'assertions-compile.ok',
+    'assertions-compile.none',
+    'assertions-compile.no-source',
+    'assertions-compile.ambiguous-source',
+    'assertions-compile.parse-error',
+    'assertions-compile.engine-absent',
+    'assertions-compile.source-absent',
+  ],
+  'assertions-pass': [
+    'assertions-pass.ok',
+    'assertions-pass.none',
+    'assertions-pass.evaluates-false',
+    'assertions-pass.evaluation-error',
+    'assertions-pass.engine-absent',
+    'assertions-pass.input-absent',
+  ],
+  'decider-resolvable': [
+    'decider-resolvable.ok',
+    'decider-resolvable.none-declared',
+    'decider-resolvable.zero-match',
+    'decider-resolvable.ambiguous-match',
+    'decider-resolvable.directory-absent',
+  ],
+  'expiry-sane': ['expiry-sane.ok', 'expiry-sane.past-or-equal'],
+};
+
+/** Trigger → its proven escalate reason code. */
+export const ROUTE_ESCALATE_CODE: Readonly<Record<Pass0EscalationReason, ReasonCode>> = {
+  'one-way-door': 'route.escalate.one-way-door',
+  'cost-threshold': 'route.escalate.cost-threshold',
+  'security-surface': 'route.escalate.security-surface',
+  'data-residency': 'route.escalate.data-residency',
+  regulatory: 'route.escalate.regulatory',
+  'contradicts-accepted-adr': 'route.escalate.contradicts-accepted-adr',
+  'agent-authored-production': 'route.escalate.agent-authored-production',
+  'human-requested': 'route.escalate.human-requested',
+};
+
+/** Trigger → its not-proven evidence reason code. */
+export const ROUTE_EVIDENCE_NOT_PROVEN_CODE: Readonly<Record<Pass0EscalationReason, ReasonCode>> = {
+  'one-way-door': 'route.evidence.one-way-door.not-proven',
+  'cost-threshold': 'route.evidence.cost-threshold.not-proven',
+  'security-surface': 'route.evidence.security-surface.not-proven',
+  'data-residency': 'route.evidence.data-residency.not-proven',
+  regulatory: 'route.evidence.regulatory.not-proven',
+  'contradicts-accepted-adr': 'route.evidence.contradicts-accepted-adr.not-proven',
+  'agent-authored-production': 'route.evidence.agent-authored-production.not-proven',
+  'human-requested': 'route.evidence.human-requested.not-proven',
+};
+
+/** The rubric version recorded on `Pass0Report` (part of the deterministic payload). */
+export const RUBRIC_VERSION = '0.1.0' as const;

package/src/compare.ts

@@ -0,0 +1,13 @@
+/**
+ * @adrkit/evaluator — deterministic string comparison.
+ *
+ * `String.prototype.localeCompare` (no locale) is ECMA-402 implementation-/ICU-/locale-
+ * dependent and non-injective (`"\u00e9".localeCompare("e\u0301") === 0`), so it cannot
+ * back a byte-for-byte "across machines" guarantee (FR-005) or the envelope hash
+ * recomputation. Every ordering that feeds canonical bytes or a hash MUST use this pure
+ * code-unit comparator instead.
+ */
+
+export function byCodeUnit(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/crypto/sha256.ts

@@ -0,0 +1,101 @@
+/**
+ * @adrkit/evaluator — pure SHA-256.
+ *
+ * A dependency-free, deterministic SHA-256 over byte arrays / UTF-8 strings, used to
+ * verify the Rego-Wasm policy envelope hashes without importing any Node builtin or
+ * touching I/O (keeps the evaluator purity gate green). Not a general crypto surface.
+ */
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+  0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+  0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+  0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+  0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+  0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+  0xc67178f2,
+]);
+
+function rotr(x: number, n: number): number {
+  return (x >>> n) | (x << (32 - n));
+}
+
+export function sha256Bytes(message: Uint8Array): Uint8Array {
+  const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+
+  const length = message.length;
+  const bitLength = length * 8;
+  const paddedLength = ((length + 8) >> 6) + 1;
+  const padded = new Uint8Array(paddedLength * 64);
+  padded.set(message);
+  padded[length] = 0x80;
+  const dv = new DataView(padded.buffer);
+  dv.setUint32(padded.length - 4, bitLength >>> 0, false);
+  dv.setUint32(padded.length - 8, Math.floor(bitLength / 0x100000000), false);
+
+  const w = new Uint32Array(64);
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    for (let i = 0; i < 16; i += 1) w[i] = dv.getUint32(offset + i * 4, false);
+    for (let i = 16; i < 64; i += 1) {
+      const a = w[i - 15] as number;
+      const b = w[i - 2] as number;
+      const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+      const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+      w[i] = ((w[i - 16] as number) + s0 + (w[i - 7] as number) + s1) >>> 0;
+    }
+    let a = h[0]!;
+    let b = h[1]!;
+    let c = h[2]!;
+    let d = h[3]!;
+    let e = h[4]!;
+    let f = h[5]!;
+    let g = h[6]!;
+    let hh = h[7]!;
+    for (let i = 0; i < 64; i += 1) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + S1 + ch + (K[i] as number) + (w[i] as number)) >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) >>> 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = (d + t1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0]! + a) >>> 0;
+    h[1] = (h[1]! + b) >>> 0;
+    h[2] = (h[2]! + c) >>> 0;
+    h[3] = (h[3]! + d) >>> 0;
+    h[4] = (h[4]! + e) >>> 0;
+    h[5] = (h[5]! + f) >>> 0;
+    h[6] = (h[6]! + g) >>> 0;
+    h[7] = (h[7]! + hh) >>> 0;
+  }
+
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  for (let i = 0; i < 8; i += 1) outView.setUint32(i * 4, h[i]!, false);
+  return out;
+}
+
+function toHex(bytes: Uint8Array): string {
+  let hex = '';
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, '0');
+  return hex;
+}
+
+export function sha256Hex(message: Uint8Array): string {
+  return toHex(sha256Bytes(message));
+}
+
+const encoder = new TextEncoder();
+
+export function sha256HexUtf8(text: string): string {
+  return sha256Hex(encoder.encode(text));
+}

package/src/identity/directory.ts

@@ -0,0 +1,69 @@
+/**
+ * @adrkit/evaluator — identity directory resolution.
+ *
+ * Pure resolution over an immutable identity-directory snapshot (R9). Resolves a
+ * principal ref (a direct human or a team) to a single active human, or reports
+ * zero/ambiguous. Used by `decider-resolvable` and named-human routing. No I/O.
+ */
+
+import type { IdentityDirectorySnapshot, Principal, PrincipalRef } from '../types.ts';
+
+export type IdentityResolution =
+  | { readonly status: 'resolved'; readonly human: PrincipalRef }
+  | { readonly status: 'zero' }
+  | { readonly status: 'ambiguous' };
+
+/** Indexed, pure view over an identity snapshot. */
+export interface IdentityIndex {
+  resolveToActiveHuman(ref: PrincipalRef): IdentityResolution;
+  isActiveHuman(ref: PrincipalRef): boolean;
+  isTeam(ref: PrincipalRef): boolean;
+}
+
+export function buildIdentityIndex(directory: IdentityDirectorySnapshot): IdentityIndex {
+  const principalsById = new Map<PrincipalRef, Principal>();
+  for (const principal of directory.principals) {
+    principalsById.set(principal.id, principal);
+  }
+  const teamMembersById = new Map<PrincipalRef, readonly PrincipalRef[]>();
+  for (const team of directory.teams) {
+    teamMembersById.set(team.id, team.members);
+  }
+
+  function isActiveHuman(ref: PrincipalRef): boolean {
+    const principal = principalsById.get(ref);
+    return principal !== undefined && principal.kind === 'human' && principal.active;
+  }
+
+  function isTeam(ref: PrincipalRef): boolean {
+    if (teamMembersById.has(ref)) return true;
+    const principal = principalsById.get(ref);
+    return principal !== undefined && principal.kind === 'team';
+  }
+
+  function activeHumansForTeam(ref: PrincipalRef): PrincipalRef[] {
+    const members = teamMembersById.get(ref) ?? [];
+    const seen = new Set<PrincipalRef>();
+    const humans: PrincipalRef[] = [];
+    for (const member of members) {
+      if (seen.has(member)) continue;
+      if (isActiveHuman(member)) {
+        seen.add(member);
+        humans.push(member);
+      }
+    }
+    return humans;
+  }
+
+  function resolveToActiveHuman(ref: PrincipalRef): IdentityResolution {
+    if (isTeam(ref)) {
+      const humans = activeHumansForTeam(ref);
+      if (humans.length === 1) return { status: 'resolved', human: humans[0] as PrincipalRef };
+      return humans.length === 0 ? { status: 'zero' } : { status: 'ambiguous' };
+    }
+    if (isActiveHuman(ref)) return { status: 'resolved', human: ref };
+    return { status: 'zero' };
+  }
+
+  return { resolveToActiveHuman, isActiveHuman, isTeam };
+}

package/src/index.ts

@@ -0,0 +1,81 @@
+/**
+ * @adrkit/evaluator — public surface.
+ *
+ * Exports the pure `evaluatePass0` entry point, the immutable contract types, the
+ * fixed catalogs, the deterministic port interfaces, and the pure in-process port
+ * factories the CLI composes at its impure boundary. It exports NO CLI, CI, adapter,
+ * or executable snapshot-bundle loader (T011) — those impurities live in `@adrkit/cli`.
+ */
+
+export { evaluatePass0 } from './pass0.ts';
+
+// Fixed catalogs (data-model §7/§8/§11).
+export {
+  RULE_IDS,
+  RULE_SEVERITY,
+  ROUTING_TRIGGERS,
+  REASON_CODES,
+  RULE_REASON_PRECEDENCE,
+  ROUTE_ESCALATE_CODE,
+  ROUTE_EVIDENCE_NOT_PROVEN_CODE,
+  RUBRIC_VERSION,
+  isReasonCode,
+  type ReasonCode,
+  type RuleId,
+  type Pass0EscalationReason,
+} from './catalog.ts';
+
+// Canonical key helpers.
+export {
+  makeAssertionKey,
+  assertionKeyForAssertion,
+  isCanonicalAssertionKey,
+  parseAssertionKey,
+  canonicalTargetKey,
+} from './keys.ts';
+
+// Immutable contract types + deterministic port interfaces.
+export type * from './types.ts';
+
+// Pure composition helpers (deterministic; no I/O). The CLI builds registries from
+// these — never from snapshot JSON.
+export {
+  createTargetResolutionRegistry,
+  emptyTargetResolutionRegistry,
+} from './targets/registry.ts';
+export { createPathTargetResolver } from './targets/path.ts';
+export { createPackageTargetResolver } from './targets/package.ts';
+export {
+  makeTargetId,
+  normalizePathId,
+  resolveRecordTargets,
+  anyMatcherInert,
+  type RecordTargetResolution,
+  type MatcherResolution,
+} from './targets/canonical.ts';
+export {
+  createAssertionEngineRegistry,
+  emptyAssertionEngineRegistry,
+  type AssertionEnginePorts,
+} from './assertions/registry.ts';
+export { createJsonPathEngine } from './assertions/jsonpath.ts';
+export { validateRegoWasmPolicyEnvelopeV1, type EnvelopeValidation } from './assertions/rego.ts';
+export { computeAssertionOutcomes, type AssertionOutcomes } from './assertions/evaluate.ts';
+export {
+  buildIdentityIndex,
+  type IdentityIndex,
+  type IdentityResolution,
+} from './identity/directory.ts';
+
+// Canonical serialization + ordering (deterministic bytes; R11).
+export {
+  canonicalize,
+  canonicalStringify,
+  canonicalBytes,
+  serializeReport,
+  serializePatch,
+  serializeArtifacts,
+  type CanonicalArtifacts,
+} from './report/serialize.ts';
+export { compareRuleFindings, sortRuleFindings } from './report/order.ts';
+export { aggregate, type SubResult } from './report/aggregate.ts';

package/src/keys.ts

@@ -0,0 +1,55 @@
+/**
+ * @adrkit/evaluator — canonical key helpers.
+ *
+ * The compact assertion key and the canonical target key are the two identity
+ * strings that keep the report byte-stable and collision-safe (data-model §4/§5).
+ * Both are pure string functions.
+ */
+
+import type { Adr, Assertion } from '@adrkit/core';
+import type { AssertionKey, CanonicalTargetId, CanonicalTargetKey } from './types.ts';
+
+/** Compact standard `JSON.stringify([log ?? "", path, id])` — no added whitespace. */
+export function makeAssertionKey(
+  log: string | undefined,
+  path: string,
+  id: string,
+): AssertionKey {
+  return JSON.stringify([log ?? '', path, id]);
+}
+
+/** The canonical assertion key for one assertion declared on one record. */
+export function assertionKeyForAssertion(record: Adr, assertion: Assertion): AssertionKey {
+  return makeAssertionKey(record.log, record.path, assertion.id);
+}
+
+/**
+ * A key is canonical iff parsing it yields exactly three strings AND the original
+ * key is byte-equal to the compact re-serialization. Whitespace-padded or otherwise
+ * noncanonical spellings are rejected, never normalized.
+ */
+export function isCanonicalAssertionKey(key: string): boolean {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(key);
+  } catch {
+    return false;
+  }
+  if (!Array.isArray(parsed) || parsed.length !== 3) return false;
+  if (!parsed.every((part): part is string => typeof part === 'string')) return false;
+  return JSON.stringify(parsed) === key;
+}
+
+/** Parse a canonical assertion key back into its three string components. */
+export function parseAssertionKey(
+  key: string,
+): { readonly log: string; readonly path: string; readonly id: string } | undefined {
+  if (!isCanonicalAssertionKey(key)) return undefined;
+  const [log, path, id] = JSON.parse(key) as [string, string, string];
+  return { log, path, id };
+}
+
+/** Stable `${kind}:${id}` serialization used for equality/intersection/ordering. */
+export function canonicalTargetKey(id: CanonicalTargetId): CanonicalTargetKey {
+  return `${id.kind}:${id.id}`;
+}