# How LoopX Manages Authority Sources and Conflict Resolution: A Deep Dive into Registry Architecture

> Discover how LoopX manages authority sources and conflict resolution with its registry architecture. Learn about configurable rules, boundary enforcement, and risk-based aggregation for seamless conflict resolution.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: deep-dive
- Published: 2026-08-07

---

**LoopX treats every authority source as a redacted, registered entity with configurable conflict rules, boundary enforcement, and risk-based aggregation to resolve conflicts at execution time.**

LoopX provides a structured framework for managing authority sources—documents, repositories, policies, or any referenceable asset—while ensuring safe multi-agent coordination through explicit conflict resolution rules. This article examines the complete authority lifecycle in `huangruiteng/loopx`, from CLI registration through runtime decision-making.

## Registering Authority Sources in LoopX

Authority source registration begins with the `register-authority-source` CLI command implemented in [`loopx/cli_commands/registry_authority.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/registry_authority.py). This command validates inputs, invokes `register_authority_source` in [`loopx/authority.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/authority.py), and appends a compact entry to the goal's `authority_sources` list.

The registration flow enforces several safeguards:

- **Identifier validation** via `validate_authority_source_id` ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/authority.py#L78‑L85))
- **Reference hashing** via `source_ref_digest` to ensure raw references are never persisted ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/authority.py#L101‑L105))
- **Compact entry creation** via `compact_registered_authority_source` ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/authority.py#L172‑L186))

### Authority Source Entry Structure

Each registered source contains these fields:

| Field | Purpose | Example Values |
|-------|---------|---------------|
| `source_id` | Unique identifier | `"doc_123"` |
| `source_kind` | Type classification | `"doc"`, `"repo"`, `"policy"` |
| `role` | Usage context | `"reference"`, `"canonical"`, `"ground"` |
| `freshness` | Temporal validity | `"current"`, `"stale"`, `"archived"` |
| `boundary` | Privacy classification | `"public"`, `"local_private"`, `"private_redacted"` |
| `revision` | Version marker | Semantic or hash-based |
| `conflict_rule` | Resolution strategy | `"token"`, `"latest"`, `"merge"` |

### Boundary Validation and Public Safety

Before persisting any entry, LoopX validates that the `boundary` belongs to the allowed set (`public`, `local_private`, `private_redacted`) ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/authority.py#L186‑L188)). For sources marked public, `validate_public_safe_text` ensures no private patterns leak into exposed fields ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/authority.py#L17‑L23)).

## Conflict Rules and Risk Assessment

LoopX conflict resolution operates at two levels: **per-source rules** and **aggregated risk**.

### Per-Source Conflict Rules

The `conflict_rule` field in each authority source entry determines how that source interacts with others. Common rules include:

- **`"token"`** — token-based exclusive access
- **`"latest"`** — automatic preference for newest revision
- **`"merge"`** — explicit multi-source combination

The rule is stored verbatim in the compact entry ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/authority.py#L183‑L190)) and consulted at execution time.

### Project-Level Conflict Risk

Each authority registry carries a `conflict_risk` field defaulting to `"unknown"`. The project map aggregates this risk across all registered sources to flag potentially dangerous configurations ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/project_map.py#L252‑L256)).

## Runtime Conflict Resolution at the Frontier

When a goal reaches its **frontier**—the decision point where the system determines whether to continue, halt, or branch—the `registry_read_instruction` in [`loopx/control_plane/goals/goal_frontier.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/goals/goal_frontier.py) governs source selection:

> *"use role, freshness, revision, boundary, gate_status, and conflict_rule to choose permitted references"* ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/goals/goal_frontier.py#L64‑L66))

This instruction ensures the planner respects:

1. **Role constraints** — only sources matching the required role are considered
2. **Freshness requirements** — stale sources may be excluded
3. **Boundary restrictions** — private sources remain encapsulated
4. **Conflict rules** — incompatible sources are filtered or sequenced

## Global Registry Synchronization

After successful local registration, `sync_project_registry_to_global` propagates authority metadata to the shared global registry ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/registry_authority.py#L46‑L51)). This ensures distributed agents operate with consistent authority awareness.

## Practical Examples

### CLI Registration (Dry Run)

```bash
loopx register-authority-source \
    --goal-id my_goal \
    --source-id doc_123 \
    --source-ref /path/to/private/doc.pdf \
    --source-kind doc \
    --role reference \
    --freshness current \
    --boundary private_redacted \
    --conflict-rule token \
    --dry-run

```

### Programmatic Registration

```python
from pathlib import Path
from loopx.authority import register_authority_source

payload = register_authority_source(
    registry_path=Path("registry.yaml"),
    goal_id="my_goal",
    source_id="doc_123",
    source_ref="/path/to/private/doc.pdf",
    source_kind="doc",
    role="reference",
    freshness="current",
    boundary="private_redacted",
    conflict_rule="token",
    dry_run=False,
)
print(payload)  # compact entry and global-sync result

```

### Inspecting Conflict Risk

```python
from loopx.project_map import load_project_map

project = load_project_map("project.yaml")
risk_level = project.get("authority_registry_conflict_risk", "unknown")
print(f"Authority conflict risk: {risk_level}")

```

## Key Source Files

| File | Responsibility |
|------|---------------|
| [`loopx/authority.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/authority.py) | Core definitions, validation, hashing, compact entry creation |
| [`loopx/cli_commands/registry_authority.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/registry_authority.py) | CLI interface, global sync integration |
| [`loopx/project_map.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/project_map.py) | Risk aggregation and authority source metrics |
| [`loopx/control_plane/goals/goal_frontier.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/goals/goal_frontier.py) | Runtime source selection using conflict rules |
| [`loopx/global_registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/global_registry.py) | Distributed registry synchronization |

## Summary

- **LoopX authority sources** are redacted, compact entries with explicit metadata fields for role, freshness, boundary, and conflict rules
- **Registration** validates identifiers, hashes raw references, and enforces public-safety constraints
- **Conflict resolution** combines per-source rules with aggregated project-level risk assessment
- **Runtime selection** at the goal frontier uses `registry_read_instruction` to filter sources by multiple criteria including conflict rules
- **Global synchronization** ensures consistent authority awareness across distributed agents

## Frequently Asked Questions

### What happens if two authority sources have conflicting rules?

The planner consults `registry_read_instruction` at the goal frontier, which evaluates `conflict_rule` alongside `role`, `freshness`, `revision`, and `boundary` to determine permitted references. Rules like `"token"` enforce exclusive access while `"latest"` prefers newer revisions. The system does not automatically resolve conflicts—it provides metadata for the planner to make context-appropriate decisions.

### Why does LoopX hash authority source references?

The `source_ref_digest` function in [`loopx/authority.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/authority.py) (`L101-L105`) hashes raw references before storage to prevent leakage of private paths or URLs. Only the compact entry with metadata and the hash persists; the original reference is discarded. This supports the `private_redacted` and `local_private` boundary classifications.

### How can I check if my project has authority conflicts?

Load the project map and inspect the `authority_registry_conflict_risk` field, which aggregates risk levels from all registered sources. The field defaults to `"unknown"` and may escalate to `"low"`, `"medium"`, or `"high"` based on source combinations. For detailed analysis, examine individual source entries and their `conflict_rule` values.

### Can I change a conflict rule after registration?

The current implementation stores `conflict_rule` verbatim in the compact entry at registration time. To modify the rule, re-register the authority source with the updated `conflict_rule` parameter. The new entry will supersede or coexist with the original based on `freshness` and `revision` metadata during frontier evaluation.