Canon

Batman Edge — Machine-Readable Agent & Tool Index

«Format: Markdown + YAML + JSON Schema-compatible structures

Purpose: Canonical registry/index for agents, tools, functions, pipelines, data sources, skills, HITL checkpoints, and execution policies.»

—

1. CONTROL MANIFEST

schema_version: "1.0.0"

index_id: "batman-edge-machine-index"

project: "batman-edge"

architecture: "registry-first"

mode: "agent-orchestrator"

runtime:

function_calling:

enabled: true

persistent: true

automatic_dispatch: true

parallel_calls: true

retry_transient_failures: true

tool_discovery:

enabled: true

registry_source: "tools"

dynamic_registration: true

hot_reload: true

execution_policy:

requested_unrestricted: true

actual_policy: "runtime_authorized"

deny_unknown_tools: true

deny_unauthorized_resources: true

require_scope_for_sensitive_operations: true

state:

persistent_memory: true

persistent_task_state: true

persistent_audit_log: true

correlation_ids: true

human_in_loop:

enabled: true

mandatory_for_policy_triggers: true

security:

default: "deny"

least_privilege: true

zero_trust: true

audit_every_action: true

secrets_from_environment_or_secret_store: true

—

system:

control_plane:

id: "batman-edge-control-plane"

responsibilities:

– registry

– routing

– task_state

– approvals

– audit

– exceptions

agents:

– phoenix-identity-gateway

– ldap-discovery-agent

– atlas-bridge-api

– hermes

– houston-metaworld

infrastructure:

– postgres

– sonarqube

– oracle

– uptime-kuma

– caddy

– tailscale

– wireguard

knowledge:

– project-wiki

– tool-index

– routing-rules

– task-schema

– skill-catalog

The project record identifies the Batman Edge system as a security delivery/program-management system with task routing, IAM/LDAP governance, and human-in-the-loop controls.

—

1. PIPELINE REGISTRY

pipelines:

security_incident:

id: "security-incident"

category: "security"

vulnerability:

id: "vulnerability"

category: "security"

iam_ldap:

id: "iam-ldap"

category: "identity"

feature_delivery:

id: "feature-delivery"

category: "engineering"

infrastructure:

id: "infrastructure"

category: "operations"

compliance:

id: "compliance"

category: "governance"

research_threat_intel:

id: "research-threat-intel"

category: "research"

data_governance:

id: "data-governance"

category: "data"

release_validation:

id: "release-validation"

category: "delivery"

The uploaded project record specifies nine machine-readable routing rules corresponding to these pipeline categories, with rule IDs, conditions, confidence weights, required roles, and HITL triggers.

—

1. GLOBAL ROUTING CONTROLS

routing:

algorithm: "rule-first"

fallback: "human-triage"

global_controls:

low_confidence:

condition: "routing_confidence < 0.80"

action: "human_triage_review"

critical_impact:

condition: "impact_level == critical"

action: "dual_approval"

required_roles:

– "security-lead"

– "service-owner"

restricted_data:

condition:

any:

– "sensitivity_level == confidential"

– "sensitivity_level == restricted"

action: "least_privilege_review"

The project record explicitly documents these three global controls: confidence below 0.80 triggers Human Triage Review; critical impact requires dual approval; confidential/restricted work uses least-privilege reviewers.

—

1. FUNCTION-CALLING CONTRACT

Every registered function SHOULD expose this normalized interface:

{

"name": "function.identifier",

"description": "Human-readable purpose",

"version": "1.0.0",

"category": "tool-category",

"input_schema": {},

"output_schema": {},

"permissions": [],

"side_effects": [],

"idempotent": false,

"timeout_seconds": 30,

"retry_policy": "none",

"requires_hitl": false,

"audit_required": true

}

Dispatcher

function_dispatch:

enabled: true

persistent: true

lifecycle:

– discover

– validate

– authorize

– prepare

– execute

– validate_result

– audit

– persist_state

unknown_function:

action: "reject"

malformed_arguments:

action: "reject"

tool_failure:

action: "classify"

transient_failure:

action: "retry_with_backoff"

authorization_failure:

action: "stop"

high_impact_action:

action: "hitl_checkpoint"

—

1. TOOL REGISTRY

tools:

orchestration:

– route_task

– validate_metadata

– generate_hitl_decision_packet

– create_postmortem

– summarize_audit_evidence

identity:

– ldap_discover

– ldap_verify

– identity_match

– credential_guard

– device_verify

data:

– atlas_query

– atlas_health

– postgres_query

– oracle_query

– vector_search

security:

– security_scan

– vulnerability_scan

– secret_scan

– dependency_scan

– policy_check

ci_cd:

– build

– test

– lighthouse_gate

– sonar_scan

– release_validate

evidence:

– audit_record

– provenance_record

– evidence_inventory

– compliance_summary

research:

– web_research

– github_ingest

– arxiv_ingest

– source_validate

execution:

– shell

– container

– service_health

– deployment

The existing Batman knowledge structure already includes "entities/tools.md" as the catalog for orchestration, data, identity, security, CI/CD, evidence, research, and execution tools.

—

1. HERMES SKILL REGISTRY

skills:

route_task:

id: "route_task"

pipeline: "orchestration"

purpose: "Route validated task envelopes to Batman Edge pipelines"

requires:

– task_envelope

– routing_rules

output:

– pipeline

– routing_confidence

– required_roles

– hitl_requirement

validate_metadata:

id: "validate_metadata"

purpose: "Validate intake metadata against task schema"

generate_hitl_decision_packet:

id: "generate_hitl_decision_packet"

purpose: "Create human approval packet with context, options, risks and rollback impact"

create_postmortem:

id: "create_postmortem"

purpose: "Create incident postmortem and preventive-action tasks"

summarize_audit_evidence:

id: "summarize_audit_evidence"

purpose: "Convert audit evidence into compliance-oriented summary"

The uploaded record describes these five Batman-specific Hermes skills and their manifest/dependency structure.

—

1. LDAP DISCOVERY AGENT

agent:

id: "ldap-discovery-agent"

purpose: "Discover and verify directory devices"

sources:

– active_directory

– openldap

capabilities:

– discover_devices

– normalize_attributes

– verify_dns

– verify_tcp

– classify_staleness

– failover

– degraded_cache

resilience:

circuit_breaker: true

exponential_backoff: true

jitter: true

credential_guard: true

authentication:

simple_bind: true

gssapi: true

tls: true

audit:

enabled: true

correlation_id: true

authentication_events: true

authorization_events: true

lookup_events: true

fail_safe_events: true

The existing implementation described in the source includes LDAP normalization, verification, TLS/simple/GSSAPI binding, paged search, failover, circuit breaking, credential protection, metrics, and degraded-mode output.

—

1. LDAP FUNCTION DEFINITIONS

functions:

ldap.discover:

input:

directory_type: "ad|openldap"

base_dn: "string"

filter: "string"

attributes: "array<string>"

output:

devices: "array<DeviceRecord>"

side_effects:

– "directory_read"

ldap.verify:

input:

device: "DeviceRecord"

output:

dns_forward: "boolean"

dns_reverse: "boolean"

tcp_reachable: "boolean"

stale: "boolean"

verified: "boolean"

ldap.failover:

input:

server_pool: "array<LdapServer>"

output:

selected_server: "LdapServer"

ldap.classify_error:

input:

result_code: "integer"

output:

error_class: "string"

retryable: "boolean"

action: "string"

—

1. IDENTITY GATEWAY

agent:

id: "phoenix-identity-gateway"

registry_aliases:

authority_primary: "authority.primary"

multimodal_fast: "identity.multimodal.fast"

local_small: "edge.local.small"

evaluation:

false_accept_rate: true

false_reject_rate: true

step_up_auth_rate: true

policy_override_rate: true

audit_completeness: true

safety:

failed_model_call: "deny"

malformed_response: "deny"

missing_evidence: "deny"

ambiguous_match: "human_review"

The source specifically recommends registry aliases rather than hardcoded future model names and an evaluation harness covering FAR, FRR, step-up authentication, policy overrides, and audit completeness.

—

1. HOME SECURITY / HUMAN-IN-THE-LOOP IDENTITY

home_security:

identity:

resident:

methods:

– trusted_phone_signal

– pin

– signed_mobile_approval

– resident_profile

– schedule

guest:

methods:

– one_time_code

– time_window_code

– recurring_code

– host_approval

– fingerprint_step_up

– iris_step_up

biometric_policy:

raw_images: "never_persist"

template_storage: "local_secure_element_or_tee"

guest_template_expiry: "automatic"

biometric_role: "step_up"

authorization:

default: "deny"

emergency_override: "explicit_policy"

audit_every_decision: true

The uploaded design specifies biometrics as optional step-up mechanisms, local template handling, temporary guest credentials, separated alarm/lock/identity control planes, and fail-safe behavior.

—

1. ATLAS BRIDGE

tool:

id: "atlas-bridge-api"

operations:

– health

– ping

– query_find

– metadata_collections

data_policy:

default_access: "allowlist"

default_write: false

audit_queries: true

redact:

– password

– token

– secret

– ssn

– dob

network:

preferred:

– tailscale

– wireguard

– cloudflare_access

fallback:

enabled: true

source: "static_or_local_cache"

The project backlog calls for collection allowlists, query audit events, private-network deployment, schema validation, and sensitive-field redaction for Atlas Bridge.

—

1. METAWORLD

application:

id: "houston-metaworld"

modes:

– BUILD

– DESIGN

– SHOP

– MESH

– "3D_LOCAL"

data:

static_dataset: true

atlas_bridge: true

overpass: true

fallback: true

provenance: true

visualization:

geofences: true

three_d_buildings: true

multi_floor: true

orbit_camera: true

smart_device_mesh: true

mesh_connections: true

The source records the MetaWorld application as having Atlas Bridge fallback, provenance tracking, Overpass data, geofences, 3D local rendering, multi-floor rendering, orbit controls, and MESH visualization.

—

1. DATA + FUNCTION CATALOG SCHEMA

catalog_record:

id: "string"

name: "string"

type: "function|tool|skill|agent|service|dataset"

category: "string"

subcategory: "string"

description: "string"

documentation: "string|null"

implementation:

language: "string|null"

code_ref: "string|null"

signature: "string|null"

interface:

parameters: []

returns: {}

metadata:

tags: []

dependencies: []

complexity: "string|null"

source_url: "string|null"

author: "string|null"

license: "string|null"

version: "string"

quality:

stars: 0

usage_count: 0

is_tested: false

has_examples: false

quality_score: 0.0

This follows the function/skill ingestion model described in the project, including the catalog fields for identity, code, signatures, parameters, dependencies, provenance, usage, testing, examples, and quality.

—

1. TASK ENVELOPE

task:

required:

– task_id

– title

– task_type

– sensitivity_level

– impact_level

– urgency

– sla_class

– ldap_change

– prod_change

– dependencies

– required_roles

– acceptance_criteria

– evidence_required

computed:

– risk_score

– routing_confidence

– required_approvers

The project has a canonical task-envelope JSON Schema with 17 required fields and computed routing/risk fields.

—

1. EXECUTION STATE MACHINE

execution:

states:

– RECEIVED

– VALIDATING

– ROUTING

– WAITING_FOR_HITL

– AUTHORIZING

– EXECUTING

– VERIFYING

– AUDITING

– COMPLETED

– FAILED

– DEGRADED

– ROLLED_BACK

transitions:

RECEIVED:

next: VALIDATING

VALIDATING:

valid: ROUTING

invalid: FAILED

ROUTING:

confidence_lt_0_80: WAITING_FOR_HITL

otherwise: AUTHORIZING

WAITING_FOR_HITL:

approved: AUTHORIZING

rejected: FAILED

expired: FAILED

AUTHORIZING:

authorized: EXECUTING

denied: FAILED

EXECUTING:

success: VERIFYING

transient_error: EXECUTING

permanent_error: FAILED

VERIFYING:

valid: AUDITING

invalid: ROLLED_BACK

AUDITING:

success: COMPLETED

failure: DEGRADED

—

1. ERROR HANDLING

errors:

connection_timeout:

classify: "transient"

retry: true

strategy: "exponential_backoff_jitter"

circuit_breaker: true

failover: true

authentication_failure:

classify: "credential"

retry: false

credential_guard: true

action: "halt_and_alert"

authorization_failure:

retry: false

action: "deny"

malformed_tool_response:

retry: false

action: "deny"

unknown_tool:

retry: false

action: "deny"

unavailable_dependency:

retry: "transient_only"

fallback: "cached_or_degraded"

critical_verification_failure:

action: "deny_by_default"

The LDAP implementation specifically documents a credential guard that does not automatically retry invalid credentials and connection failures that use retry/backoff followed by circuit breaking.

—

1. AUDIT EVENT CONTRACT

{

"event_id": "uuid",

"correlation_id": "uuid",

"timestamp": "ISO-8601",

"actor": "string",

"agent": "string",

"tool": "string",

"function": "string",

"operation": "string",

"resource": "string",

"authorization": "allowed|denied|pending",

"result": "success|failure|degraded",

"risk_score": 0.0,

"routing_confidence": 0.0,

"evidence_refs": [],

"error": null

}

—

1. PERSISTENT AGENT LOOP

agent_loop:

persistent: true

while_runtime_active:

1:

action: "load_registry"

2:

action: "load_persistent_state"

3:

action: "receive_or_resume_task"

4:

action: "validate_task"

5:

action: "route_task"

6:

action: "discover_required_tools"

7:

action: "validate_tool_contracts"

8:

action: "authorize_operations"

9:

action: "execute_function_calls"

10:

action: "validate_outputs"

11:

action: "persist_results"

12:

action: "write_audit_events"

13:

action: "checkpoint_state"

14:

action: "resume_pending_work"

—

1. TOOL DISCOVERY PROTOCOL

tool_discovery:

request:

required:

– tool_id

– version

– capability

– input_schema

– output_schema

– permissions

validation:

– schema_valid

– version_supported

– dependency_available

– authorization_available

– security_policy_passed

registration:

state: "ACTIVE"

states:

– DISCOVERED

– VALIDATED

– ACTIVE

– DEGRADED

– DISABLED

– RETIRED

—

1. REGISTRY-FIRST PROVIDER ROUTING

providers:

authority.primary:

role: "authoritative_identity"

identity.multimodal.fast:

role: "fast_identity_processing"

edge.local.small:

role: "local_low_latency"

research.primary:

role: "research"

code.primary:

role: "software_engineering"

routing_preference:

registry_alias_required: true

hardcoded_model_names: false

capability_match_first: true

availability_second: true

cost_third: true

policy_constraints_always_apply: true

—

1. HITL CHECKPOINTS

hitl:

checkpoints:

task_triage:

trigger:

– low_routing_confidence

– ambiguous_task

privileged_action:

trigger:

– high_impact

– production_change

identity_decision:

trigger:

– ambiguous_match

– conflicting_sources

release:

trigger:

– failed_quality_gate

– security_exception

decision_packet:

context: true

evidence: true

options: true

risk_tradeoffs: true

rollback_impact: true

required_approvers: true

expiration: true

—

1. SECURITY BASELINE

security:

zero_trust:

enabled: true

least_privilege:

enabled: true

default_deny:

enabled: true

secrets:

source:

– environment

– secret_manager

never:

– source_control

– plaintext_config

– audit_log

network:

public_services:

– "explicitly approved"

management_ports:

– "private_network_only"

code:

required_scanners:

– gitleaks

– semgrep

– bandit

– trivy

– sonarqube

The deployment design recorded in the source binds management services to private interfaces/Tailscale and calls for secret scanning and security tooling.

—

1. PERSISTENCE MODEL

persistence:

state:

task_state: "postgres"

event_log: "postgres"

approvals: "postgres"

audit_log: "postgres"

exceptions: "postgres"

agent_memory:

persistent: true

implementation: "external_state_store"

cache:

enabled: true

purpose:

– degraded_mode

– offline_operation

– recovery

registry:

canonical_source: "version_controlled_registry"

The Batman database schema described in the source contains tasks, task events, approvals, pipelines, audit logs, and exceptions, with parameterized ingestion and UUID-based records.

—

1. DEPLOYMENT REGISTRY

deployment:

batman_edge:

components:

– postgres

– oracle

– sonarqube

– atlas_bridge

– uptime_kuma

– hermes

– caddy

network:

ingress: "caddy"

private_mesh:

– tailscale

– wireguard

operations:

health_checks: true

backups: true

key_rotation: true

rollback: true

log_rotation: true

—

1. CANONICAL FILE MAP

artifacts:

routing:

– docs/routing_rules.yaml

architecture:

– docs/ADR-001-registry-first-architecture.md

– docs/ADR-002-zero-trust-model-calls.md

– docs/ADR-003-atlas-bridge-api.md

– docs/ADR-004-java17-sonarqube-runtime.md

schema:

– schemas/task_envelope.json

– db/sql/schema_v2.sql

knowledge:

– knowledge/index.md

– knowledge/entities/tools.md

– knowledge/concepts/routing-engine.md

– knowledge/concepts/hitl-checkpoints.md

– knowledge/concepts/ldap-governance.md

skills:

– hermes-batman-skillpack/manifest.yaml

– hermes-batman-skillpack/skills/route_task.md

– hermes-batman-skillpack/skills/validate_metadata.md

– hermes-batman-skillpack/skills/generate_hitl_decision_packet.md

– hermes-batman-skillpack/skills/create_postmortem.md

– hermes-batman-skillpack/skills/summarize_audit_evidence.md

deployment:

– deploy/cloud-init.yaml

– deploy/docker-compose.yml

– deploy/Makefile

– deploy/config/Caddyfile

– deploy/scripts/post_install.sh

– deploy/scripts/verify_deployment.sh

– deploy/scripts/rotate_keys.sh

—

1. MACHINE-READABLE INDEX ENTRY

{

"id": "batman-edge",

"version": "1.0.0",

"architecture": "registry-first",

"function_calling