Skip to content

feat: add evidence-gated voyage knowledge factory - #51

Merged
FHoffarth merged 1 commit into
developfrom
feature/voyage-knowledge-factory-v1
Aug 23, 2026
Merged

FHoffarth merged 1 commit into
developfrom
feature/voyage-knowledge-factory-v1

Conversation

@FHoffarth

Copy link
Copy Markdown
Owner

Summary

  • VoyageKnowledgeFactory v1 (ADR-0002): Introduces deterministic, automated voyage intake, canonical entity resolution, first-class gap detection, and immutable passenger knowledge pack compilation.
  • Explicit ParsedVoyageClaim Source-Binding Contract: Enforces that source authority does NOT equal proof that an artifact contains a specific claim (authority of source != evidence that source contains claim). Prevents synthesizing fake locators from user input. Statements and EvidenceEvents are authored strictly from verified ParsedVoyageClaim objects.
  • Machine-Labeled Admission Policy: Evaluates claims under fail-closed policies returning AdmissionStatus.AUTO_ADMISSIBLE or AdmissionStatus.REVIEW_REQUIRED.
  • Zero Fake Human Approval: Automated intake authors statements in EvidenceCondition.SUPPORTED with machine observer provenance (observed_by="parser:<parser_id>", human_review_state=HumanReviewState.DRAFT). No fake human reviewer or project-owner approval events are ever emitted.
  • Resolution Trust Boundary Restored: Reusable ship and port resolution (resolve_ship_identity, resolve_port) strictly requires canonical admitted truth (EvidenceCondition.SUPPORTED + HumanReviewState.APPROVED + PublishStatus.PUBLISH_ALLOWED). Storage presence (e.g. arbitrary cabin:* or venue:* records) or draft/blocked statements cannot establish identity.
  • Production vs. Test Parser Policy Separation: DEFAULT_APPROVED_VOYAGE_PARSERS whitelists only genuine production parser IDs (msc_booking_pdf_parser:v1, official_itinerary_parser:v1). Test parser admission is handled via explicit dependency injection (approved_parsers parameter) without polluting runtime defaults.
  • Dynamic UNECE-Backed Port Resolution: Resolves canonical ports dynamically against workspace statements with ISO 3166 country context; zero hardcoded port lookup tables.
  • Method.INFERRED Port Linkages: Authors canonical departure (Q-0033) and arrival (Q-0036) UN/LOCODE linkages with full input statement closure and deterministic rule hash (UNLOCODE_LINKAGE_RULE_HASH).
  • First-Class Terminal / Berth UNKNOWN Gaps: Gaps (Q-0038..Q-0041) are first-class records with explicit recheck strategies and needed source classes.
  • PassengerTripKnowledgePack Truth Boundary: Clean, immutable passenger view exposing only truth-verified facts, marking unproven fields as "UNVERIFIED" / None, and dynamic destination port infrastructure only when admitted truth.
  • Top-Level Trust Boundary: VoyageKnowledgeResult cleanly separates caller intent (input_vessel, input_departure_date, input_departure_location, etc.) from verified canonical truth (vessel, departure_date, etc.).
  • Isolated Intake & Strict Idempotency: Proves new synthetic voyage intake authors 8 canonical statements in an isolated workspace, with repeated intake producing 0 additional events or statements (res == res2).
  • Bellissima Golden Fixture Unchanged: Canonical fixture voyage:msc-bellissima:20261004-shanghai-tokyo compiles 8 verified facts without mutating evidence data.
  • Safety Safeguards: Q-0038..Q-0041 remain UNKNOWN; zero terminal/berth/route/geometry/final-cabin fabrication.

Known Non-Blocking Ontology Gap

  • Reusable Vessel Identity: Reusable vessel identity should eventually have a dedicated canonical vessel identity fact (e.g. vessel.official_name); the current Bellissima bootstrap reuses admitted voyage.vessel truth (STM-0403).

Verification

  • pytest tests/test_voyage_knowledge_factory.py tests/test_reference_voyage_port_intake.py tests/test_barcelona_human_review.py: 43 passed in 5.26s
  • pytest: 892 passed across 72 test suites in 49.54s
  • git diff --check: clean (0 whitespace warnings)

@FHoffarth
FHoffarth merged commit 3bfa08d into develop Aug 23, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant