Compare typed FHIR references by target identity (partial #1855)

packages/flow/docs/ENSURE_RECORD.md

@@ -244,3 +244,45 @@ Measured on Medplum 5.2.8 (`benchmark/fhir_medplum/readpath/probe.json`):
   server serves (`MedplumFixture.restrict_agent`).
 - The verifier's own client reads Patient and AuditEvent, and writes
   nothing.
+
+### Reference identity
+
+A contract can supply `reference_schema: {definition, sha256}`. `definition`
+is a FHIR resource StructureDefinition snapshot; `sha256` pins its canonical
+JSON (`sort_keys=True`, separators `,` and `:`). The schema's resource type
+must match the contract. Only elements explicitly typed `Reference` receive
+reference comparisons. Sliced paths, choice types and custom target profiles
+need additional resolution support and are refused.
+
+Bind the task's target to the Reference element or its `.reference` member.
+The reader resolves each supplied and stored target before judging. Relative
+and absolute references to the same configured FHIR base identify the same
+logical resource, including references to its historical versions. Resource
+types and bases remain separate. A requested version is read and its version
+ID checked separately; duplicate identity does not depend on that version.
+An explicitly requested reference version still constrains the stored field,
+and the written record keeps its separate last-version binding. Identifier
+references need a system and value and a complete search that resolves exactly
+one target. A reference carrying both a literal and an
+identifier must resolve consistently through both. Failed reads, ambiguous
+identifiers and unsupported external or contained references stay uncertain.
+The judge reads only the collected evidence. Identity searches send local
+`Type/id` values. A search that omits a freshly read, known matching record
+is unreadable; callers of `find_matches` can supply those resource IDs through
+`expected_ids`. An initial search can be empty when no match is yet known.
+
+Within a schema-proven Reference, `display` is optional presentation text.
+It may differ only when the contract independently binds that Reference's
+target identity. The verifier does not certify that this text describes the
+target, even on a closed contract. A field named `display` elsewhere keeps its
+existing scalar comparison. Other undeclared elements remain subject to the
+closed-record check. Contracts without `reference_schema` retain their previous behavior
+and serialization.
+
+The FHIR generator accepts optional `structure_definition.json` and
+`reference_targets.json` files in its teach directory. The latter contains
+the target resources captured for its demonstration checks; runtime
+verification reads the targets again. Metadata and captured targets must be
+supplied before the generator can use reference identity. SQL generation
+continues to use declared foreign keys and unique target matches. OpenAPI
+metadata and denormalized SQL label relationships are not inferred.