xml-pipeline/docs/doc_cross_check.md

AgentServer v2.1 Documentation Cross-Check

Analysis Date: January 07, 2026

Executive Summary

Overall the documentation is highly consistent and well-structured. Found minor inconsistencies and a few areas needing clarification, but no major contradictions.

---

1. CRITICAL ISSUES (Must Fix)

1.1 Missing Core Principles Document Reference

Issue: Core principles referenced everywhere but not in upload Impact: Cannot verify complete consistency Files affected: README.md, listener-class-v2.1.md, message-pump-v2.1.md Recommendation: Need to review core-principles-v2.1.md for final check

1.2 Handler Signature Inconsistency

Issue: Different handler signatures across documents

listener-class-v2.1.md:

async def handler(
    payload: PayloadDataclass,
    metadata: HandlerMetadata
) -> bytes:

self-grammar-generation.md:

def add_handler(payload: AddPayload) -> bytes:  # NOT async!
    result = payload.a + payload.b
    return f"<result>{result}</result>".encode("utf-8")

README.md:

def add_handler(payload: AddPayload) -> bytes:  # NOT async!

Conflict: Some examples show async def, others show def Resolution needed: Clarify if handlers MUST be async or can be sync Recommendation:

• If both allowed: document that sync handlers are auto-wrapped
• If async only: fix all examples to use async def

---

2. MEDIUM ISSUES (Should Fix)

2.1 HandlerMetadata Fields Discrepancy

listener-class-v2.1.md:

@dataclass(frozen=True)
class HandlerMetadata:
    thread_id: str
    from_id: str
    own_name: str | None = None
    is_self_call: bool = False

Our discussion (coroutine trust boundary):

• Handlers should receive MINIMAL context
• from_id exposes sender identity (breaks purity?)
• is_self_call implies handler knows about calling patterns

Question: Does exposing from_id violate "handlers don't know topology"?

• If yes: Remove from_id, handlers only get thread_id
• If no: Clarify why this is safe (e.g., "sender's name is not topology")

Recommendation: Document the distinction between:

• Metadata handlers CAN see (thread_id, own_name for agents)
• Metadata system keeps private (thread_path, parent, peers enforcement)

2.2 Root Tag Derivation Formula Inconsistency

configuration.md:

Root tag = {lowercase_name}.{lowercase_dataclass_name}

listener-class-v2.1.md:

{lowercase_registered_name}.{lowercase_dataclass_name}

Example from listener-class:

Registered name: calculator.add
Dataclass: AddPayload
Root tag: calculator.add.addpayload

Issue: This produces THREE dots: calculator.add.addpayload

• Is this intended? (hierarchical namespace)
• Or should it be: calculator-add.addpayload?

Recommendation: Clarify if dots in registered names are part of the root tag or if there's a separator convention

2.3 own_name Exposure Rationale

configuration.md:

agent: true → enforces unique root tag, exposes own_name in HandlerMetadata

Our discussion concluded:

• Agents don't need to know their name for self-iteration (blind routing works)
• <todo-until> is automatic self-routing

Question: Why expose own_name at all?

• Logging/audit trails?
• Self-referential prompts?
• Legacy from earlier design?

Recommendation: Either:

1. Document the specific use case for own_name
2. Or remove it if truly unnecessary

2.4 System Primitives Not Listed

Files mention but don't enumerate:

• <todo-until> - documented in discussion, not in files
• <huh> - mentioned in message-pump-v2.1.md
• Thread pruning notifications - discussed, not documented

Recommendation: Add a "System Primitives" section to core principles:

## System Primitives

The organism pre-loads the following message types with special routing:

1. **`<todo-until>`** (routing: self)
   - Enables agent iteration
   - Schema: primitives/todo-until.xsd
   - Emitters: any agent

2. **`<huh>`** (routing: sender, system-only)
   - Validation error feedback
   - Schema: primitives/huh.xsd
   - Emitters: system only

---

3. MINOR ISSUES (Nice to Have)

3.1 Thread Pruning Documentation Gap

Discussed extensively but not documented:

• When threads are pruned (on delegation return)
• UUID deletion and storage cleanup
• Optional notify_on_prune: true in YAML

Files affected: None explicitly cover this Recommendation: Add to configuration.md under listener options

3.2 Multi-Payload Extraction Details

message-pump-v2.1.md:

multi_payload_extract wraps in <dummy> (idempotent)

Question: What does "idempotent" mean here?

• If handler already wrapped in <dummy>, does it double-wrap?
• Or does it detect existing wrapper?

Recommendation: Clarify the dummy-wrapping logic

3.3 Broadcast Mechanism Not Fully Specified

configuration.md:

broadcast: true  # Shares root tag with other listeners

Questions:

• How do agents address broadcast groups?
• Do they list individual listeners or a group name?
• What happens if broadcast listener subset changes via hot-reload?

Recommendation: Add broadcast routing section to message-pump or configuration docs

3.4 Gateway vs Local Listener Routing

configuration.md shows:

listeners:
  - name: search.google
    broadcast: true

gateways:
  - name: web_search
    remote_url: ...

Agent peers list:

peers:
  - web_search  # Gateway name, not listener name

Question: How does routing distinguish:

• Local listener search.google
• Gateway group web_search
• What if names collide?

Recommendation: Document gateway resolution precedence

3.5 <respond> Tag Status Unclear

Our discussion suggested:

• Maybe there's no explicit <respond> tag
• System routes non-self/non-peer payloads to parent automatically

Files don't mention <respond> at all

Recommendation: Clarify if:

1. There IS a <respond> primitive (add to system primitives)
2. There ISN'T (document implicit parent routing)

---

4. CONSISTENCY CHECKS (All Good ✓)

4.1 XSD Validation Flow ✓

Consistent across:

• README.md: "XSD validation, no transcription bugs"
• listener-class-v2.1.md: "XSD-validated instance"
• message-pump-v2.1.md: "xsd_validation_step"

4.2 Handler Purity Principle ✓

Consistent across:

• README.md: "pure handlers"
• listener-class-v2.1.md: "pure async handler function"
• Our discussion: handlers are untrusted, coroutine captures metadata

4.3 Opaque UUID Threading ✓

Consistent across:

• README.md: "opaque UUID threading for privacy"
• listener-class-v2.1.md: "Opaque UUID matching in envelope"
• configuration.md: "Opaque thread UUIDs"

4.4 Mandatory Description ✓

Consistent across:

• README.md: "one-line human description"
• listener-class-v2.1.md: "mandatory human-readable description"
• configuration.md: "Mandatory short blurb"

4.5 Closed-Loop Pipeline ✓

Consistent across:

• README.md: "ALL messages undergo identical security processing"
• message-pump-v2.1.md: handler responses go through multi_payload_extract → route_and_process
• Our discussion: everything validates, no fast paths

---

5. MISSING DOCUMENTATION

5.1 Bootstrap Sequence

Referenced but not detailed:

• How organism.yaml is loaded
• Order of listener registration
• When pipelines start accepting messages
• System pipeline instantiation

Recommendation: Add "Bootstrap Sequence" section to configuration.md

5.2 Hot-Reload Process

Mentioned but not specified:

• How OOB hot-reload works
• What happens to in-flight messages during reload
• Schema version migration

Recommendation: Add "Hot-Reload Mechanics" section

5.3 Error Message Format

<huh> mentioned but schema not shown:

<huh>
  <error>XSD validation failed: ...</error>
  <original-attempt>...</original-attempt>
</huh>

Recommendation: Document <huh> schema in primitives section

5.4 Token Budget Enforcement

Mentioned in README:

Token budgets enforce computational bounds

Not documented:

• How budgets are tracked
• What happens when exceeded
• Per-thread vs per-agent budgets

Recommendation: Add token budget section to message-pump or core principles

5.5 Fair Scheduling Details

README mentions:

Thread-based message queue with bounded memory and fair scheduling

Not documented:

• Scheduling algorithm (breadth-first/depth-first from config?)
• Queue size limits
• Backpressure handling

Recommendation: Expand message-pump-v2.1.md with scheduling details

---

6. TERMINOLOGY CONSISTENCY ✓

Consistent Terms Used:

• "Listener" (not "handler" or "capability" inconsistently)
• "Organism" (not "system" or "platform" inconsistently)
• "Pipeline" (not "processor" or "chain")
• "Thread UUID" (not "session" or "context")
• "Peers list" (not "allowed targets" or "capabilities")

Good Naming Conventions:

• Files: kebab-case (listener-class-v2_1.md)
• Root tags: lowercase.dotted (calculator.add.addpayload)
• Registered names: dotted.hierarchy (calculator.add)
• Dataclasses: PascalCase (AddPayload)

---

7. SECURITY MODEL CONSISTENCY ✓

Handler Trust Boundary

README.md:

Handlers are untrusted code... cannot forge identity, escape thread, route arbitrarily

Our discussion:

Coroutine captures metadata before handler execution

Status: Consistent! README correctly summarizes the trust model

Topology Privacy

README.md:

Opaque UUIDs, private path registry, peers list enforcement

listener-class-v2.1.md:

Handlers receive only thread_id (opaque UUID)

Status: Consistent! Though need to clarify from_id exposure

Anti-Paperclip

README.md:

No persistent cross-thread memory, token budgets, thread pruning

Our discussion:

Thread-scoped storage, automatic cleanup, no global state

Status: Consistent!

---

8. RECOMMENDED ADDITIONS

8.1 Add to configuration.md:

listeners:
  - name: example
    notify_on_prune: boolean  # Optional: receive thread-pruned notifications

8.2 Add to listener-class-v2.1.md:

Section: "Handler Execution Model"

• Clarify async vs sync handlers
• Explain coroutine capture
• Document metadata availability vs privacy

8.3 Add to message-pump-v2.1.md:

Section: "System Primitives"

• List all magic tags (<todo-until>, <huh>)
• Document routing policies
• Explain emission restrictions

8.4 Create new file: primitives.md

Document all system primitives with:

• Schema (XSD)
• Routing policy
• Emission restrictions
• Usage examples

8.5 Add to README.md:

Section: "Computational Model" Brief explanation of:

• <todo-until> for iteration
• Blind self-routing
• Token budgets
• Thread pruning

---

9. DOCUMENTATION QUALITY SCORES

Document	Clarity	Completeness	Consistency	Overall
README.md	9/10	8/10	10/10	9/10
configuration.md	10/10	9/10	10/10	9.5/10
listener-class-v2.1.md	9/10	9/10	9/10	9/10
message-pump-v2.1.md	8/10	7/10	9/10	8/10
self-grammar-generation.md	8/10	8/10	8/10	8/10
why-not-json.md	10/10	10/10	N/A	10/10

Average: 9.1/10

---

10. CRITICAL PATH TO 1.0 RELEASE

Must Fix Before Release:

1. ✅ Resolve async vs sync handler signature
2. ✅ Clarify from_id in HandlerMetadata (privacy concern)
3. ✅ Document system primitives (<todo-until>, <huh>)
4. ✅ Add thread pruning documentation
5. ✅ Specify <respond> behavior (if it exists)

Should Fix Before Release:

6. Document bootstrap sequence
7. Document hot-reload mechanics
8. Add token budget details
9. Clarify broadcast routing
10. Add gateway resolution rules

Nice to Have:

11. Create primitives.md reference
12. Add more handler examples
13. Document fair scheduling algorithm
14. Add troubleshooting guide

---

FINAL VERDICT

The documentation is production-ready with minor fixes.

The architecture is sound, the security model is well-thought-out, and the core principles are consistently represented. The main gaps are:

1. Implementation details (bootstrap, hot-reload, scheduling)
2. System primitives (need explicit documentation)
3. Handler signature (async vs sync needs clarification)

Once core-principles-v2.1.md is reviewed and the above items addressed, this is ready for implementation and external review.

The "It just works... safely" tagline is earned. 🎯