Universal Agent Core
Relevant source files
The following files were used as context for generating this wiki page:
The Universal Agent Core is the primary governance and engineering framework that dictates the conduct, execution patterns, and architectural standards for agents and developers within the flext-ldap project. It establishes ~/.agents as the sole universal authority, ensuring that all AI-driven or manual operations adhere to a strict set of laws designed for reliability, idempotence, and technical rigor.
This core system integrates directly with the FLEXT framework's broader standards, enforcing rules such as "Truth with evidence," "One active intent," and "Root cause only." Within flext-ldap, this translates to a requirement for 100% module coverage, type-safe patterns (Python 3.13+), and explicit r result handling for all LDAP operations.
Sources: AGENTS.md:5-10, README.md:12-25, examples/README.md:55-65
Governance and Engineering Law
The core is governed by a set of "Inviolable Laws" that bind any agent (e.g., Claude, Gemini, GitHub Copilot) or operator. These laws prioritize the maintenance of a single source of truth (SSOT) and forbid the use of "shims," "suppressions," or "legacy workarounds."
Key Principles of Conduct
- Zero-Tolerance/Strict-Total: Every fix must address the root cause and be validated by actual command execution and exit codes.
- Fix-Forward-Only: Reverting shared work is forbidden; agents must integrate concurrent changes and stabilize the current state.
- Truth with Evidence: Claims of completion or status require the exact command, working directory, and decisive output.
- Living Documentation: Stale documentation is considered a defect. Every change that updates behavior must update the affected documentation in the same transaction.
Sources: AGENTS.md:30-45, AGENTS.md:205-235
Implementation Hierarchy
The project utilizes a tiered authority model to reconcile instructions:
The newest explicit operator instruction prevails over all lower authorities, ensuring human oversight is supreme.
Sources: AGENTS.md:125-135, AGENTS.md:200-210
Architectural Standards
The Universal Agent Core enforces specific architectural patterns to ensure the flext-ldap library remains enterprise-grade and maintainable.
Structural Protocols
Protocol definitions are organized into layers to manage dependencies and enable structural typing without circular imports.
| Layer | Focus | Description |
|---|---|---|
| Layer 0 | Domain Protocols | Pure data structures like DN, Attributes, and Entry (composed from flext-ldif). |
| Layer 1 | Service Protocols | Functional interfaces for LdapClient and LdapAdapter. |
| Layer 2 | Handler Protocols | High-level orchestration and management interfaces. |
Sources: src/flext_ldap/protocols.py:25-45
Data Flow and Result Handling
Operations within the core MUST utilize the r result pattern, which explicitly handles success and failure without relying on implicit exceptions.
A search result or operation result must contain metadata such as entries_affected, operation_type, and a descriptive message.
Sources: src/flext_ldap/protocols.py:105-130, examples/README.md:510-530
Validation and Quality Gates
The Core mandates that "Tests validate config/settings changes by construction." This means tests must never hardcode expected values that are owned by configuration files.
P0 Requirements
- SSOT Validation: Tests must read expected values from the same typed SSOT that production code consumes.
- Canonical Commands: All validation actions must run through canonical
makeverbs (e.g.,make check,make test,make val). - Binary Management: Binaries and daemons are provisioned via
ai-hub; no hardcoded product-specific code is permitted in the repo.
Sources: AGENTS.md:15-30, AGENTS.md:105-115, README.md:35-45
Test Categories
Tests are organized into a flat namespace for data-driven testing and reuse.
| Category | Constants Namespace | Purpose |
|---|---|---|
| Connection | c.Ldap.Tests.ConnectionSecurityCase | Validates SSL/TLS combinations. |
| Search | c.Ldap.Tests.SearchFilterCase | Covers equality, substring, and compound filters. |
| Infrastructure | c.Ldap.Tests.ERROR_INFRASTRUCTURE_PATTERNS | Identifies server-down or broken pipe errors. |
Sources: tests/constants.py:40-100
Summary of Operations
The Universal Agent Core ensures that flext-ldap operates as a disciplined, server-agnostic library. By enforcing structural duck-typing via protocols.py and strict engineering conduct via AGENTS.md, the core facilitates multi-agent collaboration while maintaining a "Zero-Debt" baseline. All LDAP operations, from basic CRUD to complex ACL migrations, are processed through these validated, type-safe boundaries.