Entity Identity Key

A DETERMINISTIC IDENTITY KEY for the same real-world entity as seen by two different systems -- built from a DECLARED SCHEMA of identifying fields, with an evidence floor, not from hashing whatever name string happened to be on hand.

THE SILENT FAILURE. Two systems each hold a record for the same company, person or property, and something downstream decides they are the same thing -- usually by hashing "the name" into a join key. That key is wrong IN BOTH DIRECTIONS, and it is wrong silently: nothing throws, nothing logs, the merge or the duplicate just happens.

UNICODE NORMALIZATION. A name typed on macOS and the same name typed elsewhere can differ in composed versus decomposed form. Byte equality says they are different companies; a human says they are obviously the same. The join silently fails and you get a duplicate.

And the opposite error is worse: too little evidence collapses two DIFFERENT entities into one key, and a merge is destructive -- the losing record's data is gone, with nothing recording that it existed.

SO THERE IS AN EVIDENCE FLOOR. Below it the key is refused rather than issued. A key that always exists is a key that sometimes means "these two records share a common first word", and a system built on it merges strangers.

VERIFIED: 93 tests, measured by running the suite.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function buildIdentityKey(schema: EntitySchema, values: unknown): IdentityKeyResult;
  export function buildCanonicalString(entityType: string, components: readonly ComponentResult[]): string;
  export function normalizeFieldValue(kind: FieldKind, raw: unknown): FieldNormalizeOutcome;
  export function defineEntitySchema(input: DefineEntitySchemaInput): EntitySchema;
  export function isFieldKind(value: unknown): value is FieldKind;

  export type FieldStatus = "present" | "absent" | "invalid";
  export type IdentityKeyRefusalReason = "invalid-values" | "unknown-value-keys" | "insufficient-signal";