core: strict mode still deletes out-of-vocabulary entities while edges are now preserved

[verveguy]

Feature Specification: Strict mode still deletes out-of-vocabulary entities, while edges are now preserved

Feature Branch: fabrik/issue-312
Created: 2026-08-02
Status: Draft
Input: User description: "core: strict mode still deletes out-of-vocabulary entities while edges are now preserved"

Background

#310 (merged as #311, ADR-0310) established that strict ontology mode must never destroy an extracted relation: an out-of-vocabulary edge is reclassified to UNCLASSIFIED with its original label preserved in attributes, rather than dropped.

The entity side was audited during that work and deliberately left alone — correctly, for the reason ADR-0310 gives: EntityTypeDef (crates/core/src/ontology.rs) has no aliases/keywords fields, so the alias-blindness defect #310 fixed on the edge side cannot exist for entities. That audit is locked in by strict_mode_entity_type_still_drops_not_reclassifies in crates/core/tests/ontology_integration.rs.

But the alias question and the delete-vs-reclassify question are separate, and only the first was in scope for #310. ADR-0310 itself flags this explicitly, in its own "Alternatives Considered" section: extending reclassify-not-drop to entities was "rejected as out of scope... it requires a genuine new design decision (what an UNCLASSIFIED entity type sentinel would be) that deserves its own issue." This is that issue.

The result today is an asymmetry visible in a single function: add_episode preserves every edge it cannot type, and deletes every entity it cannot type.

crates/core/src/episode.rs (strict entity filter, add_episode, ~line 201):

extraction.entities.retain(|e| {
    let normalized = normalize_entity_type(&e.entity_type);
    if vocab.contains(&normalized) { true } else { /* eprintln + drop */ false }
});

Deleting an entity is worse than deleting an edge: entities are edge endpoints, so a dropped entity cascades into edge loss. The current code makes this cascade explicit — when the strict-mode entity filter empties extraction.entities for a chunk, it also unconditionally clears extraction.edges for that chunk ("edges to avoid wasted embedding work; endpoints are gone"), destroying edges that were never themselves out of vocabulary. This is the same silent-loss shape as two defects already fixed this cycle: #306 (truncation recorded as clean) and #310 (edges deleted rather than reclassified).

Measured context from the #310 investigation: entity-type conformance is already very high — 97.5–98.9% in freeform (no ontology configured), 99.9% under open mode — so the affected population is small. That makes this cheap to fix and cheap to get wrong quietly, since the volume is low enough that nobody notices the loss.

Decision: entities reclassify, they do not drop

This spec resolves the issue's original "DECISION REQUIRED" flag on FR-001 as option (b): reclassify to a closed-vocabulary fallback entity type, with the original type preserved — mirroring ADR-0310's edge-side decision. The two options ADR-0310 also weighed for edges apply with the same outcome here, argued independently rather than assumed:

• Option (a), drop, is rejected for the reason already stated above and in the original issue: an entity is an edge endpoint, so dropping it is strictly worse than dropping an edge — it cascades into edge loss the entity's own out-of-vocabulary type had nothing to do with. Reclassify-not-drop is also the established precedent for every other automated deletion path in this service (ADR-0033, ADR-0037, ADR-0310); the entity-type filter is the one remaining path that still deletes outright.
• Option (c), retain the original (non-canonical) type, flagged some other way, is rejected for the same reason ADR-0310 rejected it for edges: it defeats the schema-closure guarantee strict mode exists to provide. open mode already pushes the extractor's raw (post-normalization) entity_type onto a node's labels with no vocabulary check at all — so labels is already open-ended under open. strict mode's entire distinguishing value, per ADR-0310's own "what strict actually buys" framing, is a closed type domain for tooling and aggregation to rely on. Retaining an arbitrary out-of-vocabulary type string under strict would make strict behaviorally indistinguishable from open for exactly the population this issue is about, which defeats the reason to run strict at all.

This mirrors ADR-0310's reasoning, but is not assumed from it — see the two paragraphs above for why the same conclusion in fact follows independently for entities. The formal decision record for this issue is docs/adr/0312-entity-strict-mode-reclassifies-not-drops.md, written during the Plan/Implement stage per this repository's convention that ADR numbers are issue numbers (see CLAUDE.md); it must state this reasoning and cite ADR-0310 as precedent, not authority.

Fallback type and preservation field

• Fallback type: entity types in this codebase are PascalCase (Person, Spacecraft; see normalize_entity_type), a different convention from relation types' SCREAMING_SNAKE_CASE (WORKS_AT, UNCLASSIFIED). The entity-side fallback introduced by this issue is a new sentinel, Unclassified, matching entity-type casing rather than reusing the relation-side UNCLASSIFIED literal. It is a genuinely new concept — there is no existing entity-side equivalent, per the issue's own FR-002.
• Structural difference from the edge case: relation_type is a single scalar column on RelatesToNode_, so ADR-0310 could simply overwrite it with the sentinel. An entity's type is not a single scalar column — it is represented as one or more entries in EntityRow.labels (Entity is always present; declared/ancestor types are appended per add_episode's label-construction logic). Reclassification here means: the out-of-vocabulary type is not appended to labels as one of its own entries (which would reopen the closed set strict is meant to guarantee); instead the Unclassified sentinel is appended in its place, alongside the always-present base Entity label.
• Preservation field: EntityRow already carries a free-form attributes: String column (Entity.attributes STRING, crates/core/src/schema.rs), the same pattern RelatesToEdge.attributes used for original_relation_type in core: strict ontology mode drops declared aliases and never tells the model the constraint #310. EntityRow.attributes exists today but is unconditionally written as the literal "{}" for every entity (crates/core/src/episode.rs, make_insert_row) — this issue is its first real consumer. The original out-of-vocabulary type is preserved there as {"original_entity_type": "<original>"}, mirroring the edge-side {"original_relation_type": "<original>"} convention exactly. No schema change is required (answers FR-003).

User Scenarios & Testing (mandatory)

User Story 1 - An entity with an unmodelled type is not destroyed (Priority: P1)

A workspace runs strict mode with an ontology that does not declare Spacecraft. The extractor returns an entity typed Spacecraft. Today that entity is silently dropped by the strict-mode filter. After this change, the entity is retained: it carries the Unclassified label instead of Spacecraft, and its original type is preserved and recoverable.

Why this priority: This is the core defect and the direct entity-side counterpart of #310's User Story 1 — the reclassify-not-drop precedent this service otherwise applies everywhere else is being violated at exactly one remaining point.

Independent Test: Run strict-mode extraction (or a full ingest) against an ontology that declares some entity types but not Spacecraft, feed it text that yields a Spacecraft-typed entity, and confirm the resulting stored entity is present — not absent — carrying Unclassified in its labels with the original type recoverable from attributes.

Acceptance Scenarios:

1. Given a strict-mode ontology that does not declare Spacecraft, When an entity is extracted with type Spacecraft, Then the entity is retained, its labels include Unclassified (not Spacecraft), and its attributes field contains {"original_entity_type": "Spacecraft"}.
2. Given the same ontology, When the extractor returns the same out-of-vocabulary type across multiple entities in one run, Then every one of them is retained under Unclassified — none are dropped.

---

User Story 2 - Edges keep their endpoints (Priority: P1)

An edge references an entity whose type is outside the vocabulary. Because the entity now survives (User Story 1), the edge retains a resolvable endpoint instead of losing it. This also removes the current cascade where the strict-mode entity filter's "no entities remain" branch unconditionally clears all edges for the chunk — a chunk can lose entities' types to reclassification without its edges being cleared, because the entities themselves are never gone.

Why this priority: The whole reason entity deletion is worse than edge deletion (Background) is this cascade. Fixing User Story 1 without confirming this consequence would leave the worse half of the original defect in place.

Independent Test: Run strict-mode extraction over text that yields at least one out-of-vocabulary-typed entity and at least one edge referencing it. Confirm the edge is inserted and resolves to the (now-retained, Unclassified) entity as its endpoint, and that edges_dropped_unresolvable does not count it.

Acceptance Scenarios:

1. Given a strict-mode ontology and an edge whose subject or object entity has an out-of-vocabulary type, When extraction completes, Then the edge is inserted with both endpoints resolved — the out-of-vocabulary-typed entity is not treated as missing.
2. Given a chunk where every extracted entity is out-of-vocabulary, When extraction completes, Then entities are retained under Unclassified (not dropped) and edges referencing them are not cleared solely because of this filter.

---

User Story 3 - The disposition is observable (Priority: P2)

The number of entities reclassified in a run is reported, in the same way edges_reclassified_unclassified now is.

Why this priority: Lower priority than User Story 1/2 because it doesn't change what gets persisted — it makes an already-correct disposition visible and auditable, mirroring the observability #310 delivered for edges.

Independent Test: Run strict-mode extraction over a corpus containing at least one out-of-vocabulary entity type. Confirm the run's result surfaces a count of reclassified entities (not merely per-entity eprintln lines).

Acceptance Scenarios:

1. Given a run in which N entities hit the out-of-vocabulary reclassification path, When the run completes, Then the run's result exposes a count of N.
2. Given a run with zero out-of-vocabulary entities, When the run completes, Then the count is 0, distinguishable from "not reported."

---

Edge Cases

• An entity type that normalizes to a declared type only after normalize_entity_type (e.g. case/separator variants) — already handled by the existing normalization-before-vocab-check order, and must keep working unchanged: normalization happens before this issue's reclassify branch, so a normalizable type never reaches it.
• An entity whose type is empty or absent: today, empty type (and the literal type "Entity") already means "no specific type" everywhere else in add_episode — no type label beyond the base Entity label is appended, in every ontology mode. Under strict, this case must not be routed through the new Unclassified reclassification path (which would incorrectly claim "there was a type and it didn't match"); it must continue to resolve as a plain, untyped Entity, consistent with open-mode behavior for the same input.
• The dedup path: a reclassified entity (labels include Unclassified, original type recoverable from attributes) must still dedup correctly against an existing entity of the same subject — including one already stored under its correct declared type, if the same real-world entity was previously extracted with an in-vocabulary type. Reclassification must not create a second, permanently-separate copy of an entity that already exists in the graph under its declared type.
• An ontology with entity types but no relation types, and vice versa: has_entity_types() gates the entity-side filter today and must continue to; an ontology declaring no entity types leaves all entities unfiltered (unaffected by this issue), independent of whether relation types are declared.
• A chunk where reclassification affects every entity: previously this emptied extraction.entities and cascaded into extraction.edges.clear(). After this change that branch should no longer be reachable via type-vocabulary rejection alone, since entities are no longer removed for their type — see User Story 2.

Requirements (mandatory)

Functional Requirements

• FR-001: Under strict mode, an entity extracted with a type outside the declared vocabulary (after normalization) MUST be retained, not dropped, per the Decision above (option (b), reclassify).
• FR-002: A retained out-of-vocabulary entity MUST carry a new closed-vocabulary fallback label, Unclassified, in place of the rejected type — not the raw out-of-vocabulary string — so strict mode's closed-label-domain guarantee (declared types + Unclassified, the entity-side counterpart of UNCLASSIFIED) is preserved. Unclassified is introduced by this issue; it has no existing precedent to reuse.
• FR-003: The entity's original out-of-vocabulary type MUST be preserved and recoverable, in EntityRow.attributes (the existing free-form STRING column already present on the Entity node table — no schema change) as {"original_entity_type": "<original>"}, mirroring the edge-side attributes.original_relation_type convention from core: strict ontology mode drops declared aliases and never tells the model the constraint #310.
• FR-004: The count of entities reclassified per FR-001–003 MUST be observable as a per-run tally (e.g. entities_reclassified_unclassified on AddEpisodeResult), mirroring edges_reclassified_unclassified, not only as a per-entity debug/eprintln line.
• FR-005: strict_mode_entity_type_still_drops_not_reclassifies (crates/core/tests/ontology_integration.rs) MUST be updated or replaced to assert the new reclassify behavior instead of today's drop behavior — it currently locks in the behavior this issue changes.
• FR-006: The strict-mode entity filter's current all-entities-empty cascade (unconditionally clearing extraction.edges for the chunk) MUST no longer be reachable via type-vocabulary rejection alone, since entities are no longer removed for their type under this change.
• FR-007: An entity whose type is empty or absent MUST continue to resolve as a plain, untyped Entity (no Unclassified label, no reclassification tally increment) under strict, consistent with its treatment in open/freeform — per the Edge Cases entry above.
• FR-008: A reclassified entity MUST remain eligible for the existing dedup path on the same terms as any other entity, including matching against an existing entity of the same subject already stored under a declared type.

Key Entities (if the feature involves data)

• Unclassified entity-type sentinel: the new closed-vocabulary fallback label assigned, per FR-002, when strict-mode extraction returns an entity type outside the declared vocabulary. The entity-side counterpart of the relation-side UNCLASSIFIED sentinel (ADR-0033/ADR-0037/ADR-0310), but a distinct value with PascalCase casing matching entity-type conventions rather than a reuse of the relation-side literal.
• Entity Out-of-Vocabulary Disposition: for an entity whose type does not match any declared name after normalization, its labels include Unclassified in place of the raw type, and attributes carries {"original_entity_type": "<original>"}.
• Entity Out-of-Vocabulary Tally: a per-run count of entities that hit the out-of-vocabulary disposition path, per FR-004.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Under strict, no extracted entity is removed from the pipeline solely because its type is outside the vocabulary.
• SC-002: Entity dispositions (the FR-004 tally) are reported as a per-run count, retrievable from the same result structure edges_reclassified_unclassified is retrievable from.
• SC-003: No change to open or freeform behavior, and no change to the rendered entity-type prompts in those modes — the open edge/entity prompts stay byte-identical to today, per the same constraint core: strict ontology mode drops declared aliases and never tells the model the constraint #310 required, so existing cassettes stay valid.
• SC-004: No regression in edges_dropped_unresolvable: with entities surviving that previously caused endpoint loss, this count must fall or hold for any given corpus, never rise.
• SC-005: For every entity reclassified under FR-001–003, the original entity type is recoverable from attributes.original_entity_type — no information is destroyed by the reclassification.
• SC-006: A reclassified entity still dedups correctly against a pre-existing entity of the same subject stored under a declared type (FR-008) — verified by at least one test covering this path.

Assumptions

• Entity-type conformance is high (97.5–99.9% per the core: strict ontology mode drops declared aliases and never tells the model the constraint #310 investigation), so the blast radius is small; this is a correctness and consistency fix, not a recall win.
• ADR-0310's reasoning is the starting point but not binding; the Decision section above argues the entity case independently rather than assuming symmetry, and concludes the same outcome (reclassify, not drop) for reasons specific to entities (edge-endpoint cascade) as well as the shared schema-closure argument.
• Quantifying how many edges today lose an endpoint specifically because their entity was dropped by this filter (the original issue's FR-006) is empirical measurement work — analogous to the corpus measurement ADR-0310 performed for edges — and is left to the Research stage rather than decided here; this spec's SC-004 makes the required direction of change (fewer or equal drops, never more) a testable regression gate regardless of the exact baseline count.
• The formal ADR (docs/adr/0312-entity-strict-mode-reclassifies-not-drops.md) is written during the Plan/Implement stage per this repository's issue-numbered-ADR convention (CLAUDE.md); this spec records the decision and reasoning it must capture, not the ADR document itself.
• Entity.attributes is currently always written as the literal "{}" for every entity (crates/core/src/episode.rs); this issue is its first real consumer, so there is no existing content to preserve or merge with when writing original_entity_type.

Out of Scope

• Any change to knowledge_canonicalize_relations or any equivalent entity-side "canonicalize" pass — none exists today, and creating one is not part of this issue.
• Retroactively reclassifying entities already dropped in production workspaces before this fix ships (no backfill/migration is included).
• Changing dedup's matching algorithm — FR-008/SC-006 require that reclassified entities remain eligible for the existing dedup path, not that dedup behavior itself changes.
• Any change to open or freeform mode entity handling, or to entity-type prompt content in those modes (see SC-003).
• Introducing aliases/keywords fields to EntityTypeDef — ADR-0310 confirmed no such fields exist and none are needed for this issue; the defect here is delete-vs-reclassify, not alias-blindness.

Source References

• crates/core/src/episode.rs — strict-mode entity filter in add_episode (~line 201) and the edge-clearing cascade in its "no entities remain" branch; make_insert_row's attributes: "{}".to_string() (the field FR-003 reuses); AddEpisodeResult (the struct FR-004 extends).
• crates/core/src/ontology.rs — EntityTypeDef, normalize_entity_type, has_entity_types, entity_type_names.
• crates/core/src/schema.rs — Entity node table's existing attributes STRING column.
• crates/core/src/types.rs — EntityRow.
• crates/core/tests/ontology_integration.rs — strict_mode_entity_type_still_drops_not_reclassifies (FR-005).
• docs/adr/0310-strict-mode-reclassifies-not-drops.md — the edge-side precedent this issue mirrors and independently re-argues for entities.
• docs/adr/0033-noise-edges-reclassified-not-deleted.md, docs/adr/0037-relation-classification-abstention-writes-unclassified.md — the reclassify-not-delete precedent line this issue is the last remaining installment of.
• Issue core: strict ontology mode drops declared aliases and never tells the model the constraint #310 / PR fix(episode): strict mode reclassifies out-of-vocab edges instead of dropping them #311 — the edge-side fix this issue completes the symmetry for.
• Issue eval/core: capture extraction failures whole, and surface truncation in the report #306 — the other silent-data-loss defect fixed this cycle (truncation recorded as clean), cited in Background as the same failure shape.

Labels

fabrik:cruise, stage:Specify:complete, stage:Research:complete, stage:Plan:complete, stage:Implement:complete

[verveguy]

🏭 Fabrik — stage: Specify
branch: fabrik/issue-312 | commit: 6696304 | main: 552be21 | 2026-08-02 13:46 UTC

Now I'll emit the FABRIK_ISSUE_UPDATE block with the finalized spec as the issue body, matching what was committed.

The spec resolves the issue's "DECISION REQUIRED" flag as option (b) — reclassify out-of-vocabulary entities to a new Unclassified sentinel label with the original type preserved in EntityRow.attributes — mirroring ADR-0310's edge-side treatment, with independent reasoning for why that conclusion holds for entities too (edge-endpoint cascade risk, plus the same schema-closure argument). This required rebasing the worktree onto origin/main first, since it hadn't yet picked up PR #311/ADR-0310, which this issue directly builds on. The spec is committed to specs/312-strict-mode-still-deletes/spec.md.

---

Used 42/100 turns, 0k input / 33k output tokens.

[verveguy]

🏭 Fabrik — stage: Research
branch: fabrik/issue-312 | commit: 6696304 | main: 552be21 | 2026-08-02 13:55 UTC

Research Findings

Relevant Code

• crates/core/src/episode.rs:191-227 — the strict-mode entity filter in add_episode, the exact target of this issue. Currently extraction.entities.retain(...) drops any entity whose normalize_entity_typed type isn't in onto.entity_type_names(); retained entities have entity_type rewritten to its normalized form. Lines 219-225 clear extraction.edges entirely if filtering empties extraction.entities (the cascade FR-006/spec calls out).
• crates/core/src/episode.rs:181-189 — the exact security pattern to mirror: original_relation_type (deserialized from untrusted raw LLM JSON via #[serde(default)], no deny_unknown_fields) is cleared unconditionally before any filtering runs, so a hallucinated/injected key can't survive to storage. This was fixed via three separate review round-trips on the edge side (commits 3d6d0cf, d179566, 74f7b9f in this branch's own history) — clearing unconditionally, gating the tally on strict mode, and counting off the right field. An original_entity_type field added the same way must get this right on the first pass.
• crates/core/src/episode.rs:229-272 — the edge-side reclassify logic (issue core: strict ontology mode drops declared aliases and never tells the model the constraint #310), the structural template this issue mirrors for entities: alias-normalize, else set sentinel + preserve original in a side field.
• crates/core/src/episode.rs:494-518 (make_insert_row) — builds EntityRow.labels from extracted.entity_type (pushes it plus any ancestor_map entries) and hardcodes attributes: "{}".to_string(). This is where the reclassified type must flow into labels: ["Entity", "Unclassified"] and attributes: {"original_entity_type": "..."}.
• crates/core/src/episode.rs:606-773 (Phase C) — mirrors where edges_reclassified_unclassified is authoritatively tallied (only after surviving self-referential/unresolvable drops); the new entities_reclassified_unclassified tally has a much simpler home since entities are never dropped downstream of the filter — it can be tallied where the filter itself runs, not deferred to Phase C, unlike the edge tally's ADR-0051-motivated deferral.
• crates/core/src/types.rs:94-99 (ExtractedEntity) — has no original_entity_type field yet (the edge-side original_relation_type precedent lives on ExtractedEdge, lines 101-118).
• crates/core/src/types.rs:27-42 (EntityRow) — attributes: String is the existing free-form column FR-003 reuses; no schema change needed (confirmed against crates/core/src/schema.rs's Entity node table).
• crates/core/src/ontology.rs:70-115 — EntityTypeDef (no aliases/keywords, confirmed), has_entity_types, entity_type_names, normalize_entity_type (PascalCase). No existing UNCLASSIFIED-equivalent constant for entities.
• crates/core/src/reprocess_relations.rs:30 — pub const UNCLASSIFIED: &str = "UNCLASSIFIED";, the relation-side sentinel this issue's Unclassified is the entity-side counterpart of (different casing, different constant, not shared).
• crates/core/src/corrections.rs:648-793 — is_off_ontology, list_entities_for_scope, ReprocessScope::OffOntology: the existing offline entity-reclassification machinery (knowledge_reprocess_entity_types). An entity labeled Unclassified is not in onto.entity_type_names(), so it will automatically surface as OffOntology for this existing pass — no new plumbing needed for that integration, but worth Plan being aware it composes for free.
• crates/core/tests/ontology_integration.rs:1003-1035 — strict_mode_entity_type_still_drops_not_reclassifies, the test FR-005 requires updating/replacing; also has the reusable test-harness pattern (make_state_with_extractor + ConfigurableExtractor) already used for the analogous edge test (strict_mode_reclassify_count_reflects_n_out_of_vocab_edges, line 637) — a good template for the new entity tests.
• crates/core/tests/ipc_parity.rs:793-800 — asserts edges_reclassified_unclassified is numeric in the knowledge_process_chunk IPC response; needs a mirrored assertion for the new field.
• crates/core/src/handlers.rs:431-441 — handle_process_chunk's response json!({...}) construction; this is the single place FR-004's new field must be added to the IPC surface.
• README.md:262-267, 296-297, 312-317 — three separate places document "strict: out-of-vocabulary entities are dropped post-extraction" as current, correct behavior; all three need updating (Documentation Impact below).

Architecture Notes

add_episode's pipeline order matters for this fix: the strict-mode entity filter (line 200) runs in Phase A, before name embeddings are computed (line 297) and before Phase B dedup (name-match or embedding-candidate resolution, lines 427-561). Because dedup resolution is keyed purely by name (get_entity_by_name_ci), not by type, a reclassified entity (type rewritten to Unclassified) dedups identically to any other entity — FR-008/SC-006 should already work with no new logic, since the type never participates in the match. The one side effect: the existing "type conflict" eprintln at lines 522-531 (fires when a name-matched existing entity's labels don't contain the extracted type) will now also fire, harmlessly, whenever an Unclassified-typed extraction happens to name-match an existing entity that already has a real declared type. This is a log-noise consideration, not a correctness one.

The label-construction closure in make_insert_row already treats entity_type == "" and entity_type == "Entity" identically — as "no specific type, don't append anything beyond the base Entity label" (line 501: if !extracted.entity_type.is_empty() && extracted.entity_type != "Entity"). The strict-mode filter itself does not currently make this distinction: normalize_entity_type("") returns "", which is not in vocab, so today, under strict, an entity with an empty/absent type is dropped outright — not treated as "no specific type." The spec's edge case / FR-007 requires the fix to introduce this distinction explicitly (skip reclassification when normalized type is empty or literally "Entity"; only reclassify a non-empty, non-matching type to Unclassified). This is new logic the current code doesn't have anywhere.

The if extraction.entities.is_empty() { ...; extraction.edges.clear(); } cascade (lines 219-225) becomes structurally unreachable via type-vocabulary rejection once the filter stops removing entities — extraction.entities.len() after the filter equals its length before, always. Per spec FR-006 (spec's numbering, not the issue's), this branch either needs deleting outright (letting Phase C's generic unresolvable-endpoint handling take over for the one remaining way extraction.entities could be empty — the extractor returning zero entities to begin with — which would then be counted via the pre-existing edges_dropped_unresolvable mechanism instead of a separate silent clear) or explicitly re-scoped. This is a design choice for Plan, not something I've resolved.

Relevant ADRs

• ADR-0310 (0310-strict-mode-reclassifies-not-drops.md): the direct precedent this issue extends. Its own "Alternatives Considered" section explicitly named entity-side reclassify-not-drop as out of scope and deferred it to "its own issue" — this one. No conflict; this issue is the anticipated follow-up.
• ADR-0033 (0033-noise-edges-reclassified-not-deleted.md) / ADR-0037 (0037-relation-classification-abstention-writes-unclassified.md): the reclassify-not-delete precedent line this issue is (per the spec) "the last remaining installment of." No conflict.
• ADR-0051 (0051-edge-endpoint-salvage-and-deferred-drop.md): established that edge-endpoint drop decisions are deferred to Phase C as the sole authoritative point — relevant context for why the edge-side edges_reclassified_unclassified tally is taken in Phase C rather than at filter time. The entity-side tally does not need this deferral (entities are never subsequently dropped once reclassified, unlike edges which can still be dropped later as self-referential or unresolvable), so counting it directly in the filter is simpler and correct — worth Plan explicitly noting why the entity tally doesn't need Phase C deferral, so a reviewer doesn't assume it's an oversight relative to the edge pattern.
• ADR-0173 / the hierarchical entity-types work (5ef79b1, "feat(ontology): add hierarchical entity types via additive multi-labeling (Ontology subtype/parent support: hierarchical entity types via additive multi-labeling #173)") — establishes the ancestor_map multi-labeling convention make_insert_row uses; Unclassified has no ancestors and needs none, but Plan should confirm ancestor_map.get("Unclassified") is simply never populated (true today, since it's not a declared EntityTypeDef) rather than requiring a defensive check.

Constraints

• SC-003 byte-identical prompt constraint: build_entity_types_section (crates/core/src/prompts/mod.rs:31-59) already has mode-aware branches for open/strict predating this issue — this issue must not touch it. The fix is entirely post-extraction (in episode.rs), not prompt-side, unlike core: strict ontology mode drops declared aliases and never tells the model the constraint #310 which required both a filter fix and a prompt fix. Confirmed no Unclassified-related prompt change is needed or wanted.
• No schema change (FR-003 confirmed): Entity.attributes STRING already exists and is currently always written as literal "{}" — this issue is its first real consumer, exactly mirroring how RelatesToEdge.attributes was first consumed by core: strict ontology mode drops declared aliases and never tells the model the constraint #310.
• IPC/protocol surface: adding entities_reclassified_unclassified to AddEpisodeResult and to handle_process_chunk's JSON response is additive to the JSON-RPC contract — existing consumers ignoring unknown fields are unaffected. (The Python-side consumer graphiti_service.py/service_protocol.py referenced in CLAUDE.md lives in a separate, sibling repo not present in this checkout — out of reach for this stage; flagged under Repositories/Documentation Impact below since it's worth a heads-up even though no code change is needed there for an additive field.)
• Test-suite update surface: crates/core/tests/ontology_integration.rs (unit-level, must update/replace strict_mode_entity_type_still_drops_not_reclassifies per FR-005, and likely add new tests mirroring the edge-side pattern at lines 634-733 for the count and reclassify-not-drop behavior) and crates/core/tests/ipc_parity.rs (IPC-surface assertion, line ~797-800 pattern) both need touching — this is the same two-file update surface core: strict ontology mode drops declared aliases and never tells the model the constraint #310 required for the edge side.

Technical Questions

• Should the if extraction.entities.is_empty() { ...; extraction.edges.clear(); } cascade (episode.rs:219-225) be deleted outright now that it's unreachable via type filtering, or kept as defensive dead code for the case where the extractor itself returns zero entities? Deleting it lets that case flow through Phase C's normal unresolvable-endpoint handling (counted in edges_dropped_unresolvable, which is arguably more observable than the current silent eprintln + clear) rather than a separate, now-narrower special case.
• Where should the Unclassified sentinel constant live — alongside normalize_entity_type in ontology.rs (parallel to nothing currently there) or colocated in episode.rs near its one usage (parallel to how edge-side UNCLASSIFIED is imported from reprocess_relations)? reprocess_relations::UNCLASSIFIED is reused by multiple modules (canonicalize.rs, episode.rs); Unclassified currently has exactly one call site, so a local const in episode.rs may be sufficient unless Plan anticipates other consumers (e.g. a future entity-side canonicalize pass, explicitly out of scope per the spec's "Out of Scope" section).
• Should the original_entity_type field added to ExtractedEntity follow the exact same unconditional-clear-before-filtering pattern as original_relation_type (episode.rs:181-189), given that pattern needed three follow-up review fixes to get right for edges? Recommend yes, applied on the first implementation pass rather than discovered via review, given the tally-gating and clearing bugs already seen on this exact shape of change in this same branch's history.

Risks

• Same class of subtle bug already hit three times on the edge side of this exact feature shape (raw-JSON field clearing, tally gating on strict mode, tally counting off the wrong field) — see the three "Fix review finding" commits in git log for episode.rs. The entity-side implementation should apply those lessons proactively rather than re-discover them.
• Empty/absent-type handling is new logic, not a preserved edge case. As detailed in Architecture Notes, the current strict-mode filter already (arguably incorrectly) drops empty-typed entities; the fix must add an explicit empty/"Entity"-literal check, not just switch drop to reclassify uniformly — a naive fix would incorrectly stamp Unclassified on entities that should resolve as plain untyped Entity.
• FR-006 quantification (issue's original numbering) — resolved via direct measurement, not left open. The committed crates/core/tests/fixtures/real_corpus_wal/ fixture (real Claude-extracted WAL, freeform/no ontology applied at capture time, 1,506 entities / 2,392 edges) ships alongside ontology.yaml, the same 12-entity-type vocabulary ADR-0310's own corpus measurement was built from. Cross-referencing the WAL's actual entity labels against that vocabulary (zero LLM calls, zero cost, fully reproducible) gives:
  • 20 of 1,506 entities (1.3%) carry a freeform type outside the 12 declared types (Service, Process, Book, Mission, Program, Requirement — all real, singular occurrences of niche types), consistent with the ontology file's own documented "top 12 cover 98.9%" comment.
  • 30 of 2,392 edges (1.3%) reference at least one of those 20 entities as an endpoint. Under today's code, extracting this exact corpus through the real strict-mode pipeline would drop those 20 entities outright and cascade into (up to) 30 edges losing a resolvable endpoint — the population edges_dropped_unresolvable would currently absorb, and that this fix should reduce toward zero (SC-004's "must fall or hold, never rise" direction, now with a concrete before/after baseline: at most 30 edges out of 2,392 in this corpus).
  • Caveat: this WAL was captured under open/freeform extraction, not real strict-mode extraction with the mode-aware entity prompt — so it's a measurement of "how many freeform-extracted entities happen to fall outside this vocabulary," used as a proxy for the population this filter acts on, not a replay of strict-mode extraction itself (no such cassette is checked into the repo, and capturing a live one is a paid operation per crates/eval/scripts/README.md, appropriately out of scope for Research). ADR-0310 itself notes prompt-awareness typically raises in-vocabulary compliance versus freeform, so this 1.3% is plausibly an upper bound on what real strict-mode extraction would produce, not an underestimate.

Documentation Impact

Yes — three separate spots in README.md currently document the behavior this issue changes, all under "## Ontology":

• Line 264: # strict: out-of-vocabulary entities are dropped post-extraction; ... (inline YAML comment in the format example) — needs updating to describe reclassify-to-Unclassified with attributes.original_entity_type preserved, mirroring the existing edge-side sentence right next to it.
• Line 297: **Ingest-time strict-mode filtering** (episode.rs) consults only aliases... — this sentence is about relation-type alias consultation specifically and may not need a change, but the surrounding "Modes" prose should be checked for entity-drop language.
• Line 317: the ### Modes table's strict row: Out-of-vocabulary entities dropped post-extraction — needs updating to the reclassify description, matching the relation-types cell's existing prose style right next to it in the same row.

No new CLI commands, config options, or IPC methods are introduced — only a new field (entities_reclassified_unclassified) on an existing response (knowledge_process_chunk), which is the same shape of doc change #310 made for edges_reclassified_unclassified (not currently visible as its own README line item, so likely no additional README line needed beyond the three above, unless Plan wants to add one explicitly).

I searched closed issues for related prior art; the most relevant are #310 (direct precedent, thoroughly covered above) and #306 ("truncation recorded as clean" — cited in this issue's own Background as the same silent-loss failure shape, no additional doc-impact signal beyond what's already captured).

Repositories

verveguy/liminis-context-graph

---

Used 60/100 turns, 0k input / 33k output tokens.