# LoopX Public/Private Boundary Policy and Contract Scanning Explained

> Understand LoopX public/private boundary policy and contract scanning. Learn how LoopX prevents sensitive data leaks and ensures contract integrity with automated checks.

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

---

**LoopX enforces a strict separation between public repository code and private local state through an automated contract scanning process triggered by `loopx check`, which validates that no sensitive data leaks into tracked files while ensuring all capability contracts are structurally sound.**

The huangruiteng/loopx framework treats the repository as a public surface while keeping valuable evidence and user-specific context in private, local-only state. Understanding the LoopX public/private boundary policy is essential for preventing credential leakage and maintaining valid capability contracts. This policy is codified in [`docs/public-private-boundary.md`](https://github.com/huangruiteng/loopx/blob/main/docs/public-private-boundary.md) and enforced automatically before any merge or release.

## Understanding the LoopX Public/Private Boundary Policy

The boundary policy establishes a clear delineation between what can safely reside in version control versus what must remain in ignored local files.

### Public vs. Private Data Classification

**Public assets** (safe for the repository) include:
- Schemas, CLI code, and runtime conventions
- Adapter lifecycle rules and generic coordination logic
- Validation commands and compact status projections
- Sanitised examples that demonstrate contracts without revealing private context

**Private state** (must stay in ignored local files like `.local/…`) includes:
- Absolute local paths, internal repository names, and private URLs
- Raw logs, metrics, task IDs, and active goal state that reveals user context
- Credentials, tokens, and child-agent prompts or raw trajectories

### Core Policy Principles

Three fundamental rules govern the boundary:

1. **Sanitisation first** – Public fixtures must be stripped of private data while remaining large enough for contributors to understand the contract and reproduce the check.
2. **File-state boundary** – Anything tracked by Git is subject to the public scan; untracked files are considered private by default.
3. **Controlled overrides** – Projects can explicitly allow tracked private document URLs via `public_boundary.tracked_private_doc_urls = "allow"` in the registry, but credentials, IPs, and raw paths are never permitted in tracked files.

## How Contract Scanning Works in LoopX

Contract scanning validates that code respects the public/private boundary and that declared contracts are well-formed. This process is deliberately **read-only** to guarantee safety for CI pipelines.

### The Three-Stage Validation Process

The `loopx check` command executes three distinct phases:

1. **File-boundary scan** – Walks the Git tree, loading each tracked file and applying rules from [`docs/public-private-boundary.md`](https://github.com/huangruiteng/loopx/blob/main/docs/public-private-boundary.md). Any occurrence of private material (credential literals, real absolute paths, or private URLs) raises a boundary violation.
2. **Contract validation** – Reads capability and data contracts from the registry (see [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py)). For each contract, the scanner verifies JSON/YAML syntax correctness, presence of required fields (`artifact_kind`, `public_safe`, etc.), and consistency with the public-boundary policy.
3. **Gate enforcement** – If any violation exists, the command aborts and prints a concise report pinpointing the file and line. Only a clean scan permits PR merges, releases, or runtime execution.

### CLI Execution and Output

Run the full validation from your terminal:

```bash
loopx check

```

A successful scan reports:

```

✅ Public/Private boundary: no violations found
✅ Contract validation: 42 contracts loaded, all valid

```

On violation detection, the output identifies the specific issue:

```

❌ public/private boundary violation in examples/example-smoke.py:78
   Detected private credential token in a public fixture

```

### Python API Validation

Validate contracts programmatically without shelling out:

```python
from loopx.registry import Registry

# Load the project registry (by default reads .loopx/registry.json)

registry = Registry.load()

# Validate all contracts – raises RegistryError on failure

registry.validate_all_contracts()

```

## Configuring Boundary Overrides

To allow specific private documentation URLs in tracked files, add this override to your project registry (e.g., [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json)):

```json
{
  "public_boundary": {
    "tracked_private_doc_urls": "allow"
  }
}

```

After configuration, `loopx check` will no longer flag private URLs that are deliberately tracked, though credentials and paths remain blocked.

## Key Source Files and Architecture

The boundary enforcement relies on specific components across the codebase:

- **[`docs/public-private-boundary.md`](https://github.com/huangruiteng/loopx/blob/main/docs/public-private-boundary.md)** – Canonical policy definition describing public versus private data classifications.
- **[`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py)** – Implements contract loading and the `validate_all_contracts()` API used by the scanner.
- **[`loopx/canary/planner.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/canary/planner.py)** – Contains the rule-map that drives boundary scanning for touched files.
- **[`loopx/slash_commands.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/slash_commands.py)** – Registers the `loopx check` CLI entry-point that orchestrates validation passes.
- **[`loopx/registry_writability.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry_writability.py)** – Ensures registry writes respect the public/private policy, preventing accidental persistence of credentials.

## Summary

- The LoopX public/private boundary policy mandates that credentials, absolute paths, and active goal state remain in untracked local files while schemas and sanitised examples live in the public repository.
- The `loopx check` command performs a read-only three-stage scan: file-boundary detection, contract validation against the registry, and gate enforcement to block violations before merges or releases.
- Developers can programmatically validate contracts using `Registry.load()` and `validate_all_contracts()` from [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py), or configure limited overrides for tracked private URLs via registry settings.
- Key implementation files include [`docs/public-private-boundary.md`](https://github.com/huangruiteng/loopx/blob/main/docs/public-private-boundary.md) for policy definitions, [`loopx/canary/planner.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/canary/planner.py) for boundary rules, and [`loopx/registry_writability.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry_writability.py) for write-time policy enforcement.

## Frequently Asked Questions

### What is the LoopX public/private boundary policy?

The LoopX public/private boundary policy is a security framework defined in [`docs/public-private-boundary.md`](https://github.com/huangruiteng/loopx/blob/main/docs/public-private-boundary.md) that mandates strict separation between public repository assets (schemas, CLI code, sanitised examples) and private local state (credentials, raw trajectories, absolute paths). This ensures sensitive user data never leaks into version-controlled files while keeping the repository open-source friendly and reproducible.

### How does contract scanning validate repository safety?

Contract scanning validates repository safety through a three-stage process: first, a file-boundary scan detects private material in tracked files; second, contract validation checks JSON/YAML syntax and required fields like `artifact_kind` and `public_safe` in the registry; third, gate enforcement aborts the operation and reports violations, preventing merges or releases until all boundary breaches and structural errors are resolved.

### Can private documentation URLs be stored in tracked files?

Private documentation URLs can only be stored in tracked files if the project explicitly overrides the default policy by setting `public_boundary.tracked_private_doc_urls` to `"allow"` in the registry configuration. However, this override never permits storing credentials, IP addresses, or raw absolute paths in public files, maintaining strict security boundaries for sensitive data.

### Which source files implement the contract scanning logic?

The contract scanning logic is implemented across several key files: [`loopx/slash_commands.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/slash_commands.py) registers the `loopx check` CLI entry-point, [`loopx/canary/planner.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/canary/planner.py) contains the rule-map for boundary detection, [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) handles contract loading and validation via `validate_all_contracts()`, and [`loopx/registry_writability.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry_writability.py) ensures registry modifications respect the public/private policy.