citation-evidence/src/shared/ids.ts

/**
 * Branded ID types and the `newId(kind)` factory.
 *
 * Implements the identifier portion of `wiki/SharedContracts.md` §1 and
 * `wiki/ArchitectureOverview.md` §3.2. Each branded type is structurally a
 * `string` but nominally distinct, so passing an `AnnotationId` where a
 * `DocumentId` is required is a compile-time error.
 */

declare const __brand: unique symbol;

type Brand<K, T extends string> = K & { readonly [__brand]: T };

export type DocumentId = Brand<string, "DocumentId">;
export type RepresentationId = Brand<string, "RepresentationId">;
export type AnnotationId = Brand<string, "AnnotationId">;
export type EvidenceItemId = Brand<string, "EvidenceItemId">;
export type EvidenceSetId = Brand<string, "EvidenceSetId">;
export type EvidenceLinkId = Brand<string, "EvidenceLinkId">;
export type CitationCardId = Brand<string, "CitationCardId">;
export type CitationRecoveryAttemptId = Brand<string, "CitationRecoveryAttemptId">;

export type IdKindMap = {
  document: DocumentId;
  representation: RepresentationId;
  annotation: AnnotationId;
  evidence: EvidenceItemId;
  "evidence-set": EvidenceSetId;
  "evidence-link": EvidenceLinkId;
  "citation-card": CitationCardId;
  "citation-recovery": CitationRecoveryAttemptId;
};

export type IdKind = keyof IdKindMap;

const PREFIXES: Record<IdKind, string> = {
  document: "doc",
  representation: "rep",
  annotation: "ann",
  evidence: "ev",
  "evidence-set": "evset",
  "evidence-link": "evlink",
  "citation-card": "card",
  "citation-recovery": "crec",
};

/**
 * Mint a new branded identifier of the requested kind.
 *
 * IDs use the shape `<prefix>_<uuid>` so they are human-recognizable when
 * they show up in logs, URLs, or stored JSON.
 */
export function newId<K extends IdKind>(kind: K): IdKindMap[K] {
  return `${PREFIXES[kind]}_${crypto.randomUUID()}` as IdKindMap[K];
}