meeting-lab/docs/constraint-repair.md

Constraint Repair Engine V1

Constraint Repair Engine V1 is a reusable structural repair stage for JSON outputs produced by local LLM pipeline steps.

It exists for cases where a model produced semantically usable JSON, but a strict validator rejected the document because a structural invariant was violated. Typical examples are repeated identifiers, missing identifiers, empty containers or unstable item order.

The repair stage is intentionally not integrated into the production pipeline yet. It is a standalone module that future stages can opt into explicitly.

Architecture

Package:

src/meeting_lab/constraint_repair/

The package contains:

• engine.py: generic JSON repair logic and the generic repair prompt
• adapters/: thin adapters from stage-specific validator results to the generic validator report format

The engine receives exactly two logical inputs:

1. the complete original JSON output
2. a machine-generated validator report

It never reads the original transcript and never receives Meeting Context or other source material. The engine is domain-neutral: it operates on JSON pointers, list keys and validator-reported identifiers.

Validator Interface

The generic validator report has this shape:

{
  "valid": false,
  "violations": [
    {
      "type": "duplicate_id",
      "collection_pointer": "/groups",
      "id_list_key": "source_item_ids",
      "id": "item_0001",
      "occurrences": [
        {"item_index": 0, "id_index": 1},
        {"item_index": 3, "id_index": 0}
      ],
      "keep_occurrence": 0
    }
  ]
}

Supported V1 violation types:

• duplicate_id: remove repeated identifier occurrences from a list field
• missing_id: restore an identifier by appending a validator-provided item template or adding it to a validator-specified existing item
• empty_group: remove an item whose identifier list is empty
• reorder_items: reorder a collection by validator-provided keys

The report must provide enough structural information for the engine to repair the document without interpreting content.

Meeting Context Constraint Validation Extension

Meeting Context constraints can be added without making the repair engine Meeting Context aware.

The validator may inspect a stage output together with authoritative meeting_context.yaml. It then converts violations into the generic validator report format. The Constraint Repair Engine still receives only the original JSON document and the validator report.

Authoritative metadata is configuration, not meeting content. Examples include:

• participant attendance
• canonical participant identity
• aliases
• departments
• roles

Authoritative metadata may be consumed by LLMs and downstream pipeline stages. It must never be redefined, overwritten or inferred by any pipeline component.

This includes, but is not limited to:

• LLM extraction
• Canonicalizer
• Semantic Consolidator
• Constraint Repair
• Renderer

These components may consume authoritative metadata, but they must treat it as immutable configuration.

Constraint Types

participant_attendance_conflict

A known participant from Meeting Context is represented in structured output as absent, mentioned-only, external or otherwise not attending, contradicting the authoritative attendance status.

Example:

{
  "valid": false,
  "constraint_source": {
    "type": "meeting_context",
    "meeting_id": "2026-07-27-projektprozess",
    "source_file": "samples/real_live/project_process_meeting/meeting_context.yaml",
    "schema_version": "1"
  },
  "violations": [
    {
      "type": "participant_attendance_conflict",
      "severity": "error",
      "collection_pointer": "/participants",
      "item_index": 3,
      "entity_id": "bjoern",
      "display_name": "Björn",
      "matched_alias": "Björn",
      "field": "attendance_status",
      "actual_value": "absent",
      "expected_value": "present",
      "repair": {
        "operation": "set_field",
        "field": "attendance_status",
        "value": "present"
      }
    }
  ]
}

participant_unknown

A person-like entity appears in a structured participant or mentioned-person field but is not known in Meeting Context as a participant, mentioned person or alias.

Example:

{
  "type": "participant_unknown",
  "severity": "error",
  "collection_pointer": "/participants",
  "item_index": 4,
  "matched_text": "Guido",
  "repair": {
    "operation": "remove_item"
  }
}

Removal is allowed only when the unknown entity is a standalone structured participant-like item and removing it does not remove unrelated content. If the unknown name appears only inside generated prose, the repair must fail closed.

participant_alias_conflict

A structured entity reference uses an alias that maps to a different authoritative entity, or uses an ambiguous alias that cannot be resolved to exactly one Meeting Context entity.

Example:

{
  "type": "participant_alias_conflict",
  "severity": "error",
  "json_pointer": "/participants/2/entity_id",
  "matched_alias": "Johanna",
  "expected_entity_id": "jovana",
  "expected_display_name": "Jovana",
  "actual_entity_id": "unknown",
  "repair": {
    "operation": "set_field",
    "field": "entity_id",
    "value": "jovana"
  }
}

Alias repair is allowed only for structured identity fields and only when Meeting Context maps the alias to exactly one entity.

Validation Principle

The validator validates structured data whenever possible. Lexical analysis is a fallback only when no structured representation exists. The long-term objective is to reduce lexical validation over time by preserving Meeting Context metadata as structured data throughout the pipeline.

Lexical fallback may report a violation, but it must not create repair instructions that require editing generated prose.

Repair Workflow

Stage output
    ↓
Meeting Context Constraint Validator
    ↓
Generic validator report
    ↓
Constraint Repair Engine
    ↓
Meeting Context Constraint Validator

If Validator #1 succeeds, repair is skipped. If Validator #1 fails, exactly one repair pass may run when all violations map to deterministic structural operations. Validator #2 then checks the repaired document. If Validator #2 fails, the pipeline stops and reports the remaining violations.

Allowed Repairs

Allowed repairs are deterministic structural operations only:

• set a structured attendance field to the authoritative value
• set a structured entity ID to the authoritative entity ID
• move a structured participant item between participant collections
• remove a standalone structured unknown participant item
• remove empty structured participant containers
• reorder structured participant collections deterministically

Forbidden Repairs

The repair engine must never perform free-form text editing.

It must not:

• remove names from generated prose
• replace text inside prose fields
• rewrite sentences
• infer attendance from transcript content
• invent participants
• invent aliases
• merge people
• split people
• change responsibility attribution
• change fact, decision, action-item or open-question meaning
• use Meeting Context directly

If a violation exists only inside generated prose and cannot be repaired by a deterministic structural operation, the repair must fail closed and report the violation.

Integration Strategy

Minimum useful integration for the current architecture:

Semantic Consolidator
    ↓
Meeting Context Constraint Validator
    ↓
Constraint Repair
    ↓
Meeting Context Constraint Validator
    ↓
Renderer

This catches contradictions in the consolidated representation before the Working Protocol Renderer receives it. It does not require the renderer to infer attendance semantics from prose.

Future architecture:

Meeting Context metadata should remain structured throughout the pipeline so that the Renderer receives authoritative participant metadata directly instead of having to infer it from generated prose. In that architecture, Meeting Context validation can operate primarily on structured fields and use lexical analysis only as a diagnostic fallback.

Allowed Operations

The engine may:

• move identifiers
• remove duplicate identifiers
• restore missing identifiers
• remove empty containers
• reorder items

The engine must not:

• invent information
• rewrite extracted text
• reinterpret reasons or explanations
• create new semantic relationships
• split semantic relationships

Missing identifier repair is intentionally conservative. If the validator does not provide an explicit target item or an item template, the engine refuses the repair.

Generic Repair Prompt

The module defines a generic prompt contract for future model-backed repair backends. The prompt describes the task as repairing a structured JSON document from a validator report and deliberately avoids stage-specific vocabulary.

V1 unit tests assert that the prompt does not mention the current consolidation stage, Meeting Context, facts, or merge groups.

Semantic Consolidator Adapter

constraint_repair.adapters.semantic_consolidator converts the current consolidation validator shape into the generic validator report.

The adapter knows the current consolidation output field names such as groups and source_item_ids. The generic repair engine does not. This keeps stage-specific schema knowledge at the edge and preserves the repair engine as a reusable JSON utility.

The adapter currently reports:

• repeated source IDs
• missing expected source IDs
• empty source-ID containers

It does not call Ollama and does not change the production consolidation path.

Future Reuse

Future pipeline stages can reuse the same engine by writing a small adapter that maps their validator failures to the generic report format. The required contract is that the adapter reports structural locations and does not ask the engine to infer domain meaning.

Potential future uses:

• enforcing exact identifier coverage in LLM-generated grouping output
• removing empty generated containers before strict parsing
• restoring validator-known singleton items
• normalizing deterministic order after otherwise valid generation