Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 35 additions & 20 deletions backend/app/corporate_entity_ingestion.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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(
Expand All @@ -216,14 +231,14 @@ 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,
proposal.level_code,
parent_entity_id,
)
_remember_candidate(candidates, new_id, normalized_name)
return new_id
return new_id, None
26 changes: 18 additions & 8 deletions backend/app/keyman_ingestion.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -195,15 +203,15 @@ 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,
hierarchy_inference_client,
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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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,
Expand Down
87 changes: 66 additions & 21 deletions backend/app/post_summary_ingestion.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"]),
}
)
Expand Down Expand Up @@ -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
Comment on lines 447 to 474

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: Organization actors never get an affiliation reason persisted

persist_post_summary resolves affiliations (and records affiliation reasons) only for PERSON/TEAM actors (post_summary_ingestion.py). An ORGANIZATION actor carrying its own affiliated_organization_name never gets affiliation_catalog_unresolved_reason_code set, so its affiliation always renders the generic label. This mirrors pre-existing behavior, so it is not a regression, but the App.test.tsx mock sets that field on an org row, which the backend never actually produces.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

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,
Expand All @@ -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(
Expand All @@ -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)
Expand All @@ -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 "
Expand All @@ -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(
Expand All @@ -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
Expand Down Expand Up @@ -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
)
Expand All @@ -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,
Expand All @@ -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(
Expand Down
Loading