Skip to content

World's first open-source enterprise world model.

ADR 0071: a source may declare its names identities (#1319)

Szabo Bogdandd99aedf8751
diff --git a/docs/decisions/0054-a-source-may-push-statements-in-the-open-contract.md b/docs/decisions/0054-a-source-may-push-statements-in-the-open-contract.md
index d1c15b3b..ecccb4b7 100644
--- a/docs/decisions/0054-a-source-may-push-statements-in-the-open-contract.md
+++ b/docs/decisions/0054-a-source-may-push-statements-in-the-open-contract.md
@@ -94,3 +94,4 @@ Content-Type: application/json
- 2026-09-25 (#899, #900): typed materialization now reconciles the rows it writes along their uniqueness timelines, as the write path always did, so a later observation of a functional attribute closes the earlier one without a manual reconcile. A document version records the `doc_time` it was pushed with, and a fact's evidence date is taken from its own version, so a same-identity update no longer makes the earlier statement look simultaneous with the later one. The stored document carries the observation's identity and date ahead of the three arrays, so the same payload under a new identity is a second document, never a rename of the first.
- 2026-10-15 ([#1242](https://github.com/deeplethe/utopia/issues/1242)): a pushed signature whose phrase equals exactly one declared relation, not a state, that admits both of its ends is bound by the ontology when the document's extraction finishes, and that extraction queues `materialize`, so a base with no chat model types what it is pushed. It binds the signature as [0044](0044-the-ontology-is-a-view-over-what-documents-say.md)'s revision of decision 3 describes, reviewable like any binding; it is not a typed write, decisions 3 and 5 stand, and no other pushed phrase binds before alignment reads it.
- 2026-10-16 ([#1267](https://github.com/deeplethe/utopia/issues/1267)): decision 7 keeps a re-pushed statement's identity, but its role words stayed first-write-wins, so a re-push with a new qualifier value kept the old one; [0070](0070-a-role-word-speaks-while-its-chunk-is-live.md) proposes that a role word is recorded against its evidence chunk and speaks while that chunk is live.
+- 2026-10-19 ([#1293](https://github.com/deeplethe/utopia/issues/1293)): proposed in [0071](0071-a-source-may-declare-its-names-identities.md): a `statements` source whose config says `{"names": "identity"}` attaches its named entities by exact name and gives their names no vectors. Decision 3's "same path" stands for every other source.
diff --git a/docs/decisions/0071-a-source-may-declare-its-names-identities.md b/docs/decisions/0071-a-source-may-declare-its-names-identities.md
new file mode 100644
index 00000000..da59eb11
--- /dev/null
+++ b/docs/decisions/0071-a-source-may-declare-its-names-identities.md
@@ -0,0 +1,59 @@
+# 0071 · A source may declare its names identities
+
+- **Status**: Proposed · 2026-10-19 · [#1293](https://github.com/deeplethe/utopia/issues/1293) · open: all six decisions
+- **Written**: 2026-10-19 (conventions in the [README](README.md))
+- **Related**: [0054](0054-a-source-may-push-statements-in-the-open-contract.md) decision 3 sends pushed statements down the same resolution path as prose, and this record narrows that for one kind of source; [0041](0041-a-name-is-a-claim-about-an-entity.md) owns name facts and name-vector recall; [#1248](https://github.com/deeplethe/utopia/issues/1248) meets the same problem from the merge side; [#1296](https://github.com/deeplethe/utopia/issues/1296) measured what the recall costs; [#1308](https://github.com/deeplethe/utopia/pull/1308) is the disjointness fix that stands on its own
+
+> A backend mirrors a repository into a base and pushes `owner/repo:src/a.ts#parseDate`, `owner/repo:src/a.test.ts::adds two`, `owner/repo:specs/x/spec.md#s0003`. Each name is an identity the client already knows to be unique. Every one still goes through write-time resolution. Because they share the `owner/repo:` prefix, their name vectors sit close together, and the duplicates queue fills with pairs that can never be the same thing.
+
+## The problem
+
+0054 decision 3 is right for most pushes. A client that pushes human-style names, like `cup-7` and `kitchen table`, gains from name-vector recall exactly as prose does. What is true for some producers is narrower: *this source's* names are identities. For such a source, resolution today does three things it already knows the answer to:
+
+- **Name vectors** (`propose_by_name_vector`). Up to eight `name_vector|` pairs per mention, plus one `name_vectors::nearest` query per named entity per pushed document, even after an exact match (#1296).
+- **The single-candidate split** (`resolve_by_name`, cosine below `SIM_ATTACH`). The same file named in two payloads with different context becomes two entities with one name.
+- **Being a target.** Its names' vectors are near-neighbours for every other mention in the base, so prose mentions propose pairs against them too.
+
+## Decisions
+
+**1. The switch lives on the source.**
+
+A `statements` source whose config says `{"names": "identity"}`, next to the existing `{"extract": false}`, declares that every name it pushes identifies one thing. The default is unchanged, and every other source keeps 0054 decision 3 as it stands. The producer is the one that knows its names are identities, and one base can hold an identity source beside prose sources, so the switch is per source rather than per base. #1248 decides the merge side with the same flag.
+
+**2. An identity name attaches to its exact name, whatever the profile.**
+
+A named entity from an identity source attaches to the entity whose name equals it case-insensitively, in the declared class or with no class, and is created only when there is none. The profile similarity is not consulted, so the single-candidate split never happens for an identity source: the same name in two payloads is one entity. When the exact name already has two holders, which should be rare for identity names, the mention takes today's review path. Choosing between them would need a provenance lookup that this record does not add.
+
+**3. A name that exists only under another class is created in the declared class.**
+
+The source's class is part of its identity claim, so the entity is created in that class. The type-drift review stays, unless the two classes are declared disjoint (0016 B3): an exact name under another class is most likely a duplicate whose class was guessed, and it deserves one look.
+
+**4. An identity name has no name vector.**
+
+A mention from an identity source runs no `name_vectors::nearest` query and proposes no `name_vector|` pair. Its name facts get no vector either: `name_vectors::pending` skips a name fact that has evidence from an identity source (through `fact_evidence.document_id` to the document's source). So identity entities neither propose pairs nor become targets of one. A prose mention of the exact name still attaches by exact match (channel 1 of 0041 decision 3), so nothing that an exact name finds is lost.
+
+**5. Identity evidence wins.**
+
+One name fact can carry evidence from both an identity source and a prose document, because facts dedupe on subject, predicate and object. Such a fact gets no vector. The identity source has vouched for the name, and a prose mention still reaches it by exact match. This changes recall for prose: a prose mention of a *variant* of that name (an abbreviation, another script) no longer finds the entity through its vector, and the code PR covers that with the test `a_name_with_identity_evidence_gets_no_vector_even_when_prose_names_it_too`.
+
+**6. Switching the flag.**
+
+- **On:** the update that sets the flag also deletes the stored vectors of name facts that now have identity evidence, in the same transaction. Leaving them in place and skipping them would put an evidence join into every `nearest` query, which is the per-mention cost #1296 measured.
+- **Off:** nothing is deleted. Those name facts become pending again, and the next extraction in the base backfills their vectors through `pending`, as it does for any name whose vector is missing. Recall for them returns from then on. Pairs that were never proposed while the flag was on are not proposed in retrospect.
+
+## Not doing
+
+- **Containment for identity names.** `containment_reviews` still runs for them. #1104's next cut rewrites that predicate, and whether an identity source skips it is a separate decision after that.
+- **The single-candidate split for other sources.** Decision 2 removes it for identity sources only. Prose keeps today's split.
+
+## Dead ends
+
+- **Every `statements` push is an identity claim.** Too broad: 0054 sends pushes through the same path on purpose, and human-style names find real variants through their vectors.
+- **Skip the vector channel after any single exact match.** That is #1296 item 1. Applied to every mention it changes prose resolution, and `the_same_literal_name_is_not_proposed_twice` asserts the opposite.
+- **A per-base switch.** One base can mix an identity source with prose sources, and only the producer knows which names are identities.
+
+## Tests the code PR adds
+
+- `an_identity_source_adds_no_name_vectors_and_asks_no_neighbours`: a push from an identity source leaves no `name_vector|` rows and runs no `nearest` query.
+- `a_name_with_identity_evidence_gets_no_vector_even_when_prose_names_it_too` (decision 5).
+- Turning the flag on deletes the identity names' vectors; turning it off makes them pending again (decision 6).
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index f4ef89cb..727d60be 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -55,6 +55,7 @@ By domain; the domains are the files of [../design/](../design/README.md). **Sta
| | Record | Status | Overtaken |
|---|---|---|---|
| 0041 | [A name is a claim about an entity](0041-a-name-is-a-claim-about-an-entity.md) | In progress | |
+| 0071 | [A source may declare its names identities](0071-a-source-may-declare-its-names-identities.md) | Proposed | |
### [time](../design/time.md)