diff --git a/CHANGELOG.md b/CHANGELOG.md index a9a79fa14..e0ba64723 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,20 @@ All notable changes to this project are documented here. Format follows ## [Unreleased] +### Added + +- R&R catalog links now record why they are unresolved (ADR 0141): tied + candidates, no live enrichment client, checked-but-not-corroborated, or no + matching catalog entry. The reader sees the specific reason next to an + unlinked person, organization, or affiliation instead of one flat "Not + linked to catalog" label; a historical row written before this change + keeps its prior behavior. +- `frontend/index.html` now shows a visible, styled message when JavaScript + is disabled, instead of a silent blank page. +- ADR 0142 proposes reusing the existing semantic-relationship channel with + one new `lw_plans_to_operate` predicate for planned-facility evidence, + scoped to the decision only -- no inference code ships with it. + ### Changed - Renamed "Buyer" terminology to reader/workspace naming across the frontend diff --git a/backend/app/corporate_entity_ingestion.py b/backend/app/corporate_entity_ingestion.py index bfc0e740d..f0f395dc9 100644 --- a/backend/app/corporate_entity_ingestion.py +++ b/backend/app/corporate_entity_ingestion.py @@ -113,8 +113,16 @@ async def get_or_create_corporate_entity( *, _depth: int = 0, _visited_names: frozenset[str] = frozenset(), -) -> str | None: - """Return a verified catalog id, otherwise ``None``. +) -> tuple[str | None, str | None]: + """Return ``(catalog id, unresolved reason code)``. + + The catalog id is ``None`` exactly when the reason code is one of + ADR 0141's closed values (``reason_tied_candidates``, + ``reason_no_live_client``, ``reason_not_corroborated``) -- the caller + persists that reason instead of a flat "unresolved" fact. It is + ``None, None`` only for the pure input-validation edge cases (an empty + name, or a name already in the recursion path) that never represent a + real actor mention. A unique similarity match is reused. A tied top score stays unbound and does not create a third same-named row (ADR 0026). Only a genuine @@ -126,18 +134,21 @@ async def get_or_create_corporate_entity( """ normalized_name = organization_name.strip() if not normalized_name: - return None + return None, None visit_key = normalized_name.casefold() if visit_key in _visited_names: - return None + return None, None existing = score_corporate_entity(normalized_name, candidates) if existing.kind == RESOLUTION_UNIQUE and existing.catalog_id is not None: - return existing.catalog_id + return existing.catalog_id, None if existing.kind == RESOLUTION_TIE: - return None + return None, "reason_tied_candidates" if _depth >= _MAX_HIERARCHY_DEPTH or not inference_client.available: - return None + # Excessive recursion depth is folded into the same "not attempted" + # bucket as an unconfigured client: from the reader's perspective + # both mean enrichment never ran for this specific mention. + return None, "reason_no_live_client" try: proposal = await asyncio.to_thread( @@ -149,9 +160,11 @@ async def get_or_create_corporate_entity( # A provider timeout is an unavailable enrichment channel, not a # reason to discard the source-grounded summary. Keep the actor # unbound and let an explicit retry attempt catalog enrichment later. - return None - if proposal is None or not verification_client.available: - return None + return None, "reason_no_live_client" + if proposal is None: + return None, "reason_not_corroborated" + if not verification_client.available: + return None, "reason_no_live_client" try: placement_result = await asyncio.to_thread( @@ -165,16 +178,16 @@ async def get_or_create_corporate_entity( # ingestion) -- treat it the same as "not corroborated this run": # the entity simply isn't auto-created, same conservative outcome # as a real search that found nothing. - return None + return None, "reason_no_live_client" if placement_result.status_code != STATUS_CORROBORATED: - return None + return None, "reason_not_corroborated" visited_names = _visited_names | {visit_key} parent_entity_id: str | None = None if proposal.parent_name is not None: normalized_parent = proposal.parent_name.strip() if not normalized_parent or normalized_parent.casefold() in visited_names: - return None + return None, "reason_not_corroborated" try: parent_result = await asyncio.to_thread( verification_client.verify, @@ -184,10 +197,10 @@ async def get_or_create_corporate_entity( except (HttpClientError, OSError): # Same fail-closed-without-crashing behavior as the placement # verification above. - return None + return None, "reason_no_live_client" if parent_result.status_code != STATUS_CORROBORATED: - return None - parent_entity_id = await get_or_create_corporate_entity( + return None, "reason_not_corroborated" + parent_entity_id, _parent_reason = await get_or_create_corporate_entity( conn, normalized_parent, context_text, @@ -198,7 +211,9 @@ async def get_or_create_corporate_entity( _visited_names=visited_names, ) if parent_entity_id is None: - return None + # The child's own corroboration succeeded; it's the hierarchy + # placement (ADR 0010 requires the whole chain) that didn't. + return None, "reason_not_corroborated" async with conn.transaction(): await conn.execute( @@ -216,9 +231,9 @@ async def get_or_create_corporate_entity( ) if fresh.kind == RESOLUTION_UNIQUE and fresh.catalog_id is not None: _remember_candidate(candidates, fresh.catalog_id, normalized_name) - return fresh.catalog_id + return fresh.catalog_id, None if fresh.kind == RESOLUTION_TIE: - return None + return None, "reason_tied_candidates" new_id = await _create_entity( conn, normalized_name, @@ -226,4 +241,4 @@ async def get_or_create_corporate_entity( parent_entity_id, ) _remember_candidate(candidates, new_id, normalized_name) - return new_id + return new_id, None diff --git a/backend/app/keyman_ingestion.py b/backend/app/keyman_ingestion.py index ade1044a1..e0804bdd9 100644 --- a/backend/app/keyman_ingestion.py +++ b/backend/app/keyman_ingestion.py @@ -182,11 +182,19 @@ async def _resolve_affiliated_organization( verification_client: RelationVerificationClient, hierarchy_inference_client: CorporateHierarchyInferenceClient, candidates: list[CorporateEntityCandidate], -) -> tuple[str, str, str | None]: - """Resolve one affiliation without rewriting a known raw-name tie.""" +) -> tuple[str, str, str | None, str | None]: + """Resolve one affiliation without rewriting a known raw-name tie. + + The fourth element is ADR 0141's unresolved-reason code (``None`` when + ``corporate_entity_id`` is set). The Keyman ingestion caller below does + not yet surface it -- only the R&R post-summary path + (``post_summary_ingestion.py``) does -- but the reason is real and + computed either way, so callers that need it later don't have to + re-derive it. + """ raw_outcome = score_corporate_entity(organization_name, candidates) if raw_outcome.kind == RESOLUTION_TIE: - return organization_name, organization_name, None + return organization_name, organization_name, None, "reason_tied_candidates" resolved_name = await resolve_organization_name( conn, @@ -195,7 +203,7 @@ async def _resolve_affiliated_organization( organization_name, context_text, ) - corporate_entity_id = await get_or_create_corporate_entity( + corporate_entity_id, unresolved_reason = await get_or_create_corporate_entity( conn, resolved_name, context_text, @@ -203,7 +211,7 @@ async def _resolve_affiliated_organization( verification_client, candidates, ) - return organization_name, resolved_name, corporate_entity_id + return organization_name, resolved_name, corporate_entity_id, unresolved_reason async def ingest_post_keymen( @@ -249,9 +257,11 @@ async def ingest_post_keymen( else: mentions = await asyncio.to_thread(client.extract, post_title, post_body) candidates = await _load_corporate_entity_candidates(conn) - resolved_by_mention: list[tuple[PersonMention, list[tuple[str, str, str | None]]]] = [] + resolved_by_mention: list[ + tuple[PersonMention, list[tuple[str, str, str | None, str | None]]] + ] = [] for mention in mentions: - resolved_orgs: list[tuple[str, str, str | None]] = [] + resolved_orgs: list[tuple[str, str, str | None, str | None]] = [] for organization_name in mention.affiliated_organization_names: resolved_orgs.append( await _resolve_affiliated_organization( @@ -279,7 +289,7 @@ async def ingest_post_keymen( person_id, ) resolved_names: list[str] = [] - for organization_name, resolved_name, corporate_entity_id in resolved_orgs: + for organization_name, resolved_name, corporate_entity_id, _reason in resolved_orgs: await _upsert_affiliation( conn, person_id, diff --git a/backend/app/post_summary_ingestion.py b/backend/app/post_summary_ingestion.py index f7287ade3..eb8e4b638 100644 --- a/backend/app/post_summary_ingestion.py +++ b/backend/app/post_summary_ingestion.py @@ -145,7 +145,9 @@ async def fetch_persisted_summary( role.cataloged_team_id, role.cataloged_corporate_entity_id, role.cataloged_person_id, - role.cataloged_affiliated_corporate_entity_id + role.cataloged_affiliated_corporate_entity_id, + role.catalog_unresolved_reason_code, + role.affiliation_catalog_unresolved_reason_code from post_summary_role role where role.post_id = $1 order by role.actor_name @@ -263,6 +265,14 @@ async def fetch_persisted_summary( if row["cataloged_affiliated_corporate_entity_id"] is not None else None ), + "catalog_unresolved_reason_code": ( + row["catalog_unresolved_reason_code"] if catalog_node_id is None else None + ), + "affiliation_catalog_unresolved_reason_code": ( + row["affiliation_catalog_unresolved_reason_code"] + if row["cataloged_affiliated_corporate_entity_id"] is None + else None + ), **ontology_annotations(row["actor_type_code"]), } ) @@ -427,32 +437,42 @@ async def persist_post_summary( else [] ) resolved_organization_ids: dict[int, str] = {} + resolved_organization_reasons: dict[int, str] = {} resolved_affiliation_names: dict[int, str] = {} resolved_affiliation_ids: dict[int, str] = {} + resolved_affiliation_reasons: dict[int, str] = {} for role_index, role in enumerate(summary.roles_and_responsibilities): if role.actor_type_code == ACTOR_TYPE_TEAM and is_generic_team_actor(role.actor_name): continue if role.actor_type_code != ACTOR_TYPE_ORGANIZATION: if role.actor_type_code in {ACTOR_TYPE_PERSON, ACTOR_TYPE_TEAM} and role.affiliated_organization_name: try: - _, resolved_name, corporate_entity_id = await _resolve_affiliated_organization( - conn, - role.affiliated_organization_name, - context_text, - resolution_client, - verification_client, - hierarchy_inference_client, - candidates, + _, resolved_name, corporate_entity_id, affiliation_reason = ( + await _resolve_affiliated_organization( + conn, + role.affiliated_organization_name, + context_text, + resolution_client, + verification_client, + hierarchy_inference_client, + candidates, + ) ) except (HttpClientError, OSError, TimeoutError, ValueError): # R&R affiliation is enrichment. A provider outage must # preserve the raw source name and the summary itself. - resolved_name, corporate_entity_id = role.affiliated_organization_name, None + resolved_name, corporate_entity_id, affiliation_reason = ( + role.affiliated_organization_name, + None, + "reason_no_live_client", + ) resolved_affiliation_names[role_index] = resolved_name if corporate_entity_id is not None: resolved_affiliation_ids[role_index] = corporate_entity_id + elif affiliation_reason is not None: + resolved_affiliation_reasons[role_index] = affiliation_reason continue - corporate_entity_id = await get_or_create_corporate_entity( + corporate_entity_id, unresolved_reason = await get_or_create_corporate_entity( conn, role.actor_name, context_text, @@ -462,6 +482,8 @@ async def persist_post_summary( ) if corporate_entity_id is not None: resolved_organization_ids[role_index] = corporate_entity_id + elif unresolved_reason is not None: + resolved_organization_reasons[role_index] = unresolved_reason async with conn.transaction(): await _replace_summary_projection( @@ -472,6 +494,8 @@ async def persist_post_summary( resolved_organization_ids, resolved_affiliation_names, resolved_affiliation_ids, + resolved_organization_reasons, + resolved_affiliation_reasons, ) payload = await fetch_persisted_summary(conn, post_id) @@ -482,12 +506,15 @@ async def persist_post_summary( async def _resolve_existing_cataloged_person_id( conn: asyncpg.Connection, person_name: str -) -> str | None: - """Return the earliest existing catalog person id for ``person_name``. +) -> tuple[str | None, str | None]: + """Return ``(earliest existing catalog person id, unresolved reason)``. Lookup orders by ``created_at``, then ``person_id``. This function does not insert a ``cataloged_person`` row (ADR 0009). A missing - catalog row stays unbound rather than inventing a person. + catalog row stays unbound rather than inventing a person; ADR 0141 + records that absence as ``reason_no_catalog_entry`` -- the only reason + code available here, since this lookup has no live-client dependency + to distinguish further. """ person_row = await conn.fetchrow( "select person_id from cataloged_person " @@ -496,8 +523,8 @@ async def _resolve_existing_cataloged_person_id( person_name, ) if person_row is None: - return None - return str(person_row["person_id"]) + return None, "reason_no_catalog_entry" + return str(person_row["person_id"]), None async def _replace_summary_projection( @@ -508,6 +535,8 @@ async def _replace_summary_projection( resolved_organization_ids: dict[int, str], resolved_affiliation_names: dict[int, str], resolved_affiliation_ids: dict[int, str], + resolved_organization_reasons: dict[int, str] | None = None, + resolved_affiliation_reasons: dict[int, str] | None = None, ) -> None: """Write one atomic replacement using pre-resolved shared identities.""" # Summary replacement owns only R&R projections. Keyman mentions remain @@ -700,7 +729,13 @@ async def _replace_summary_projection( cataloged_team_id = None cataloged_corporate_entity_id = None cataloged_person_id = None + catalog_unresolved_reason_code = None cataloged_affiliated_corporate_entity_id = resolved_affiliation_ids.get(role_index) + affiliation_catalog_unresolved_reason_code = ( + None + if cataloged_affiliated_corporate_entity_id is not None + else (resolved_affiliation_reasons or {}).get(role_index) + ) affiliation_name = resolved_affiliation_names.get( role_index, role.affiliated_organization_name ) @@ -715,18 +750,26 @@ async def _replace_summary_projection( cataloged_corporate_entity_id = resolved_organization_ids.get( role_index ) + if cataloged_corporate_entity_id is None: + catalog_unresolved_reason_code = (resolved_organization_reasons or {}).get( + role_index + ) elif role.actor_type_code == ACTOR_TYPE_PERSON: - cataloged_person_id = await _resolve_existing_cataloged_person_id( - conn, - role.actor_name, + cataloged_person_id, catalog_unresolved_reason_code = ( + await _resolve_existing_cataloged_person_id( + conn, + role.actor_name, + ) ) await conn.execute( "insert into post_summary_role " "(post_id, actor_name, responsibility_text, actor_type_code, " "affiliated_organization_name, cataloged_team_id, " "cataloged_corporate_entity_id, cataloged_person_id, " - "cataloged_affiliated_corporate_entity_id) values " - "($1, $2, $3, $4, $5, $6, $7, $8, $9)", + "cataloged_affiliated_corporate_entity_id, " + "catalog_unresolved_reason_code, " + "affiliation_catalog_unresolved_reason_code) values " + "($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)", post_id, role.actor_name, role.responsibility, @@ -736,6 +779,8 @@ async def _replace_summary_projection( cataloged_corporate_entity_id, cataloged_person_id, cataloged_affiliated_corporate_entity_id, + catalog_unresolved_reason_code, + affiliation_catalog_unresolved_reason_code, ) if cataloged_team_id is not None: await conn.execute( diff --git a/backend/tests/test_api.py b/backend/tests/test_api.py index 213b0300c..b3e96837b 100644 --- a/backend/tests/test_api.py +++ b/backend/tests/test_api.py @@ -172,6 +172,11 @@ / "migrations" / "0114_semantic_relationship_standard_predicates.sql" ) +_CATALOG_UNRESOLVED_REASON_MIGRATION = ( + Path(__file__).resolve().parents[2] + / "migrations" + / "0134_catalog_unresolved_reason.sql" +) def _postgres_available() -> bool: @@ -297,6 +302,7 @@ def seeded_db(demo_analyst_token): cur.execute(_SOFTWARE_AGENT_MIGRATION.read_text()) cur.execute(_SEMANTIC_RELATIONSHIP_MIGRATION.read_text()) cur.execute(_SEMANTIC_RELATIONSHIP_PREDICATES_MIGRATION.read_text()) + cur.execute(_CATALOG_UNRESOLVED_REASON_MIGRATION.read_text()) cur.execute( "insert into common_lookup_value (lookup_category, lookup_code, lookup_label) values " "('corporate_entity_level', 'group', 'Group'), " diff --git a/docker/postgres-init/migrate.sh b/docker/postgres-init/migrate.sh index 3dcab7f31..abd392d6e 100644 --- a/docker/postgres-init/migrate.sh +++ b/docker/postgres-init/migrate.sh @@ -18,7 +18,7 @@ for migration in /opt/lineageweave/migrations/*.sql; do migration_name=${migration##*/} case "$migration_name" in 0012_*|0013_*|0014_*|0015_*|0016_*|0017_*|0018_*|0019_*|0020_*|0021_*|0022_*|0023_*|0024_*|0025_*|0026_*|0027_*|0028_*|0029_*|0030_*|0031_*|0032_*|0033_*|0034_*|0035_*|0036_*|0037_*|0038_*|0039_*|0040_*|0041_*|0042_*|0043_*|0044_*|0045_*|0046_*|0047_*|0048_*|0049_*|0050_*) ;; - 0060_*|0100_*|0101_*|0102_*|0103_*|0104_*|0105_*|0106_*|0107_*|0108_*|0109_*|0110_*|0111_*|0112_*|0113_*|0114_*|0130_*|0132_*) ;; + 0060_*|0100_*|0101_*|0102_*|0103_*|0104_*|0105_*|0106_*|0107_*|0108_*|0109_*|0110_*|0111_*|0112_*|0113_*|0114_*|0130_*|0132_*|0134_*) ;; *) continue ;; esac printf 'Applying %s\n' "$migration_name" diff --git a/docs/adr/0141-catalog-unresolved-diagnosability.md b/docs/adr/0141-catalog-unresolved-diagnosability.md new file mode 100644 index 000000000..e198cc50e --- /dev/null +++ b/docs/adr/0141-catalog-unresolved-diagnosability.md @@ -0,0 +1,142 @@ +# ADR 0141 — Catalog-unresolved reason is explicit, not one flat label + +**Decision status:** Proposed +**Date:** 2026-08-22 + +## Context + +`docs/product-technical-gap-baseline.md` (§5, "R&R role/relationship +conflation and catalog-linking boundary") records a live UI/UX finding: +"카탈로그 미연결" ("Not linked to catalog", `frontend/src/i18n.ts`) is the +correct, honest label whenever a role's `catalog_node_id` is `null` +(`fetch_persisted_summary`, `backend/app/post_summary_ingestion.py`), but it +gives the reader no way to tell apart the reasons that null can happen: + +- An organization actor's mention tied two or more equally-similar catalog + candidates (`RESOLUTION_TIE`, `score_corporate_entity`, + `lineageweave/corporate_hierarchy_resolution.py`; ADR 0026 — a tie must + stay unbound, never first-win a homonym). +- `get_or_create_corporate_entity`'s `inference_client` or + `verification_client` (`backend/app/corporate_entity_ingestion.py`) + defaulted to a `Null*Client` because no live contextual-orchestrator / + SearXNG transport is wired in this environment — in that state the + function can only match an *already-cataloged* entity, never create one. +- A live client was available and was actually called, but hierarchy + inference proposed nothing, or verification declined to corroborate the + proposed placement (`placement_result.status_code != STATUS_CORROBORATED`) + — a considered "no" rather than an unattempted check. +- A person actor's name has no matching `cataloged_person` row yet + (`_resolve_existing_cataloged_person_id`) — ADR 0009 forbids inventing one. + +These are different facts a reader would act on differently ("try again once +the orchestrator is configured" vs. "this was checked and is not the same +entity" vs. "wait for another mention to disambiguate the tie"), but today +they are indistinguishable from the UI. This is a genuine information loss: +the resolution kind (`unique` / `tie` / `miss`) and the client-availability +state already exist as in-memory facts inside +`get_or_create_corporate_entity` and `_resolve_affiliated_organization` for +the duration of one call — they are simply discarded before +`_replace_summary_projection` persists the row. + +Per AGENTS.md, a schema/behavior change needs its ADR before code. This is +the ADR for that change; it does not touch extraction, the summary contract, +or catalog creation itself (those are unrelated, separately-scoped changes — +see `docs/product-technical-gap-baseline.md` §5 items 2 and 3 for the ones +this ADR deliberately does not fix). + +## Decision + +1. Add two nullable, `common_lookup_value`-backed reason columns to + `post_summary_role`, following the same pattern as ADR 0125's + `affiliation_scope_code` (`migrations/0134_catalog_unresolved_reason.sql`): + `catalog_unresolved_reason_code` (why the primary person/organization/team + actor has no catalog link) and `affiliation_catalog_unresolved_reason_code` + (why the role's *affiliated* organization, + `cataloged_affiliated_corporate_entity_id` / ADR 0127, has none). Two + columns, not one, because a role commonly has its primary actor resolved + (a known person) while its affiliation is not, or vice versa — one shared + column could not represent both states at once. The shipped "Not linked + to catalog" label (`frontend/src/components/RoleEvidence.tsx`, + `unresolvedLabel` prop) currently renders next to the *affiliation* + field, so `affiliation_catalog_unresolved_reason_code` is the column that + closes the gap-baseline finding as literally reported; + `catalog_unresolved_reason_code` closes the same gap for the primary + actor, which today shows no reason at all when unresolved. Each column is + set only when its corresponding `cataloged_*_id` column is `null`; both + stay `null` when a catalog link exists, and both stay `null` on + historical rows written before this migration (no retroactive reason is + invented for history — the frontend falls back to today's behavior, a + plain name with no reason shown, when the reason is absent). +2. Closed vocabulary, four values: + - `reason_tied_candidates` — `RESOLUTION_TIE`: two or more candidates + shared the top similarity score. + - `reason_no_live_client` — `inference_client.available` or + `verification_client.available` was `False` (including the + `HttpClientError` / `OSError` / `TimeoutError` catches that already + exist in `get_or_create_corporate_entity`, which are the same "channel + unavailable this run" fact as an unavailable client, not a decision). + - `reason_not_corroborated` — a live client ran, but inference proposed + nothing or verification returned a non-`STATUS_CORROBORATED` result. + - `reason_no_catalog_entry` — the person-catalog name lookup + (`_resolve_existing_cataloged_person_id`) found no row. This is the only + reason code available to a person actor; the resolver has no client + dependency to distinguish further, and inventing a finer distinction + here would misrepresent what the function actually checked. +3. `get_or_create_corporate_entity` returns the reason alongside the id + (`(catalog_id: str | None, reason_code: str | None)`) instead of just the + id, so the caller can persist it without re-deriving state the callee + already computed and discarded. `_resolve_affiliated_organization` grows + a fourth return element carrying the same reason for the affiliation + case (its Keyman-ingestion caller, a separate surface out of this ADR's + scope, discards it unchanged). `_resolve_existing_cataloged_person_id` + gains the equivalent single-reason return. +4. `fetch_persisted_summary`'s `payload_roles` entries add both + `catalog_unresolved_reason_code` and + `affiliation_catalog_unresolved_reason_code` (each `null` when linked or + historical). `frontend/src/api.ts` extends the role type to carry both. +5. The frontend replaces the single `unresolvedLabel` string + (`RoleEvidence.tsx`, wired from `frontend/src/App.tsx`'s R&R row + renderer) with a small lookup from reason code to one of four specific, + translated messages, falling back to today's plain rendering (no reason + shown) when the reason is `null`. The primary actor's own name gains the + same treatment where it currently shows no diagnostic at all. No + confirmation dialog, retry button, or invented certainty is added — this + is read-only diagnostic text. +6. This does not change ABAC/visibility, does not create a catalog row that + wasn't already going to be created, and does not change the tie/miss/ + corroboration policy itself (ADR 0009, 0010, 0026 govern those). It only + makes an already-computed-and-discarded fact visible. + +## Considered alternatives + +- **Do nothing; leave the flat label.** Rejected: the gap-baseline finding is + that this is undiagnosable today, and the reader currently cannot tell "not + yet possible to check" from "checked and declined." +- **Infer the reason at read time from current client configuration instead + of persisting it.** Rejected: the reason is a fact about what happened + *when the role was last persisted*, not about the reader's current + environment. A role summarized while an orchestrator was configured, then + read after it goes down, would get the wrong "no live client" reason. The + reason must be captured at write time, not derived at read time. +- **One generic "insufficient evidence" code instead of four.** Rejected: + the gap-baseline finding is specifically that a reader cannot act on an + undifferentiated null; collapsing back to one bucket reproduces the same + problem it exposed. + +## Consequences + +- Historical rows keep the honest gap ("we didn't record why") rather than a + fabricated backfilled reason; only newly-persisted summaries get the + specific code. This is consistent with how ADR 0125 handled its own + migrated column. +- `get_or_create_corporate_entity`'s signature change is a small, mechanical + ripple to its ~7 in-repo callers (`backend/app/keyman_ingestion.py`, + `backend/app/post_summary_ingestion.py`) and its existing test suite + (`tests/test_tied_organization_no_create.py` and the corporate-hierarchy + resolution tests) — each call site now reads a tuple instead of a bare id. + No test asserts on the old bare-id return shape in a way that survives + unchanged; those tests are updated alongside the implementation. +- Keyman-side organization/affiliation resolution + (`backend/app/keyman_ingestion.py`) can reuse the same reason vocabulary + later if the same undiagnosability complaint is raised there; this ADR + scopes only the R&R post-summary path the gap-baseline finding names. diff --git a/docs/adr/0142-planned-facility-project-evidence.md b/docs/adr/0142-planned-facility-project-evidence.md new file mode 100644 index 000000000..7cfea2ac0 --- /dev/null +++ b/docs/adr/0142-planned-facility-project-evidence.md @@ -0,0 +1,145 @@ +# ADR 0142 — A planned facility becomes project/entity evidence only through the existing semantic-relationship channel, with an explicit "planned" predicate + +**Decision status:** Proposed +**Date:** 2026-08-22 + +## Context + +`docs/product-technical-gap-baseline.md` (§5, item 3) records a live finding: +a key event whose text names a specific planned facility (its own example: +"X 충전소 구축 계획", i.e. "plan to build X charging station") produces +`key_events` / `key_event_details` prose only. It is never checked against +`post_project_mention` / the entity graph, so the facility itself is not +recognized as an entity, and no relationship is inferred between it and the +organization that the post's own R&R evidence says would operate it. + +The gap doc is explicit that this needs its own ADR before any inference +code, because the risky part is not rendering — it is deciding *when* text +that describes a *plan* is allowed to become a persisted *relationship*. +ADR 0010's fail-closed hierarchy-creation design exists precisely to stop an +organization mention from being auto-created without independent +corroboration; inferring an "operates" relationship from event-adjacent +context risks the same class of mistake — asserting a fact ("Org X operates +Facility Y") that the source text does not actually state ("Org X plans to +build Facility Y"). + +This ADR is scoped to the decision only. **No inference code is written as +part of this ADR** — implementing it is separately reviewed follow-up work, +per the gap doc's own instruction and AGENTS.md's ADR-first rule. + +### What already exists that this can reuse + +- `post_summary_semantic_relationship` / `SemanticRelationship` + (`lineageweave/post_summary.py`) is already a generic, closed-vocabulary, + evidence-required subject–predicate–object channel: + `SEMANTIC_RELATION_NODE_TYPES` already includes `organization`, + `industrial_asset`, `industrial_process`, `place`, and `project`; + `SEMANTIC_RELATION_PREDICATES` is a closed set of PROV-O / SKOS / SOSA / + ODRL / `lw_*` codes. A relationship row without a non-empty `evidence_text` + is rejected by `SemanticRelationship.__post_init__` today. +- `post_project_mention` already records a project name/key with its own + `mention_confidence` and `extraction_method`, independent of key events. +- Neither channel today has a predicate that means "named as the operator of + a facility this post says is only planned, not existing." + +Given this, the missing piece is not a new table or a new relationship +class — it is one new closed predicate code plus the admission rule that +governs when the extractor may emit it. + +## Decision + +1. **Reuse `post_summary_semantic_relationship`; do not add a new table.** + Add one new predicate code, `lw_plans_to_operate`, to + `SEMANTIC_RELATION_PREDICATES` and to `docs/ontology/lineageweave-kg.ttl` + (`LW.predicateCode` / `LW.predicateIri` per `semantic_predicate_annotations`'s + existing lookup contract). The subject is the organization/team actor + named in the post's own R&R evidence as the one carrying out the plan; + the object is the facility, typed `industrial_asset` (or `place` when the + text gives no asset-specific detail). +2. **The predicate name itself carries the epistemic status.** + `lw_plans_to_operate` names an announced intention, not a standing fact. + The extractor must never emit `lw_has_actor`/`org_*` operate-style + predicates for a facility the post itself describes only as planned or + under construction. If a later post's evidence says the facility is + actually operating, that is new evidence for a new relationship row (an + `lw_supports`/successor predicate is a separate, future decision if that + need materializes) — this ADR does not retroactively upgrade a prior + "planned" row. +3. **Admission rule — every one of these must hold before the relationship + is emitted:** + - The post's own text (not the operator's inference, not world knowledge) + names both the organization/team actor and the facility in the same + event or adjacent evidence span. + - The facility is also captured as a `post_project_mention` row (or is + eligible to be, at extraction time) so the entity has independent + project-evidence backing, not just a phrase inside `key_event_details`. + A facility named only in event prose, with no corresponding project + mention, does not qualify — this mirrors ADR 0010's requirement that + enrichment corroborate before binding, not merely mention. + - `confidence` reflects the extractor's own stated confidence in the + *plan-to-operate* framing specifically, not the general event + confidence. A low-confidence event does not get rounded up. + - `evidence_text` is the literal source span naming both the actor and + the facility (already required by `SemanticRelationship`, restated here + because it is the actual safety mechanism: a reviewer or a later + retraction path can always re-check the row against the exact quoted + text). +4. **Contract-version discipline applies the same way it does to the R&R + job-title/relationship-type field split.** Adding a new predicate to a + closed vocabulary that flows through the extraction prompt requires a + `POST_SUMMARY_CONTRACT_VERSION` bump and a reviewed prompt change, because + every future extraction depends on the contract version + (`lineageweave/post_summary.py`). That prompt change is the follow-up + implementation work this ADR authorizes in shape but does not itself + perform. +5. **No new organization/facility catalog row is created by this feature.** + The organization side resolves through the existing + `get_or_create_corporate_entity` path (ADR 0010, ADR 0026) exactly as any + other organization mention would; a planned-facility relationship is + never itself grounds to auto-create an ambiguous or uncorroborated + organization. If the organization side is unresolved, the relationship + row still records the raw actor name (as `SemanticRelationship` already + allows via `subject_name`) — it is enrichment, not a gate on the row + existing. + +## Considered alternatives + +- **A dedicated `project_operator_relationship` table / new relationship + class.** Rejected: `post_summary_semantic_relationship` already is that + table in shape (typed subject/object, closed predicate vocabulary, + mandatory evidence, confidence). A parallel table would duplicate the + schema, the ontology-annotation lookup, and the frontend rendering path + for no behavioral gain, and would need its own migration, API surface, and + tests that the existing channel already has. +- **Infer "operates" directly instead of "plans to operate."** Rejected: + this is exactly the fact-invention risk the gap doc calls out. The source + text supports a plan; asserting operation is a stronger claim the + evidence does not carry. +- **Do nothing; leave facility mentions as unlinked prose.** Rejected: this + is the status quo the gap doc flags as a real product gap — an + entity-and-relationship-shaped fact in the source text is currently + invisible to the ontology/entity graph. + +## Consequences + +- The next implementation step (separately reviewed, not part of this ADR) + is: bump `POST_SUMMARY_CONTRACT_VERSION`, extend the extraction prompt + with the admission rule above, add `lw_plans_to_operate` to the ontology + TTL and `SEMANTIC_RELATION_PREDICATES`, and add fixture-backed tests + proving a *plan* phrase emits the new predicate while an *existing + operation* phrase does not. +- Because the predicate is additive to an existing closed vocabulary and + channel, no migration is needed beyond the ontology TTL update and the + Python frozenset — `post_summary_semantic_relationship`'s schema already + supports an arbitrary `predicate_code` string with a foreign-key-style + check against the ontology annotation lookup at read time + (`semantic_predicate_annotations`), not at write time, so no schema + migration accompanies this ADR. +- A downside accepted here: `lw_plans_to_operate` is a LineageWeave-local + (`lw_*`) predicate, not a borrowed PROV-O/SKOS/ODRL term, because none of + the already-adopted standard vocabularies (PROV-O, SKOS, DCT, SOSA, ODRL) + has a term for an announced-but-not-yet-executed operational + relationship. This is consistent with the existing `lw_*` namespace's + purpose (`lw_has_goal`, `lw_has_next_step`, etc. are the same kind of + LineageWeave-specific narrative-structure predicate already in the + vocabulary), not a new category of exception. diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index bd6ff5f64..58b320aeb 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -147,10 +147,15 @@ exact-head protected gate. mobile Playwright checks cover the disclosure, no-unassigned-code behavior, and no horizontal overflow; the external Keyverse/OIDC runtime gate remains open below. -- **Locale document metadata — substantially present:** `i18n.ts` synchronizes - `document.documentElement.lang` after locale selection and `i18n.test.ts` - covers the supported locales. `frontend/index.html` remains an English - pre-JavaScript fallback, so a no-JavaScript locale check is still open. +- **Locale document metadata — substantially present; no-JS fallback fixed + in this worktree:** `i18n.ts` synchronizes `document.documentElement.lang` + after locale selection and `i18n.test.ts` covers the supported locales. + `frontend/index.html` now renders a visible `