feat(governance): cross-organizational federation governance model (#93)

[ArokyaMatthew]

Summary

Implements cross-organizational federation governance as described in #93. Adds mutual policy enforcement, org-level trust agreements, and policy delegation for cross-organizational agent interactions.

Zero breaking changes — federation is a new additive module alongside the existing governance engine.

Problem

AgentIdentity has organization and organization_id fields but they are never used in policy enforcement. All governance is callee-only — there is no mutual enforcement, no org-scoped policy delegation, and no concept of "org A trusts org B's governance layer."

What's New

Core Module: agentmesh.governance.federation

Component	Purpose
OrgPolicy	Org-scoped policy document with rules, data classification, trust thresholds, allowlists/blocklists
OrgTrustAgreement	Bilateral trust agreement with expiration, revocation, category scoping, mutual/directional flag
PolicyDelegation	"Org A accepts org B's governance attestation for category X" with constraint checking
FederationEngine	Mutual enforcement — both caller and callee org policies evaluated, most restrictive wins
InMemoryFederationStore	In-memory persistence with full CRUD for policies, agreements, and delegations
FileFederationStore	File-based persistence loading from YAML directory structure
PolicyCategory	Extensible 9-value governance taxonomy (pii_handling, data_export, cost_control, etc.)
FederationDecision	Rich decision result with traces from both orgs

Scope Hierarchy Update

Added ORGANIZATION scope to PolicyScope enum in both agent-os and agentmesh conflict resolution:

Files Changed

File	Change
packages/agent-mesh/src/agentmesh/governance/federation.py	[NEW] Core federation module
packages/agent-mesh/tests/test_federation.py	[NEW] 49 tests
packages/agent-mesh/src/agentmesh/governance/init.py	Export federation types
packages/agent-os/src/agent_os/policies/conflict_resolution.py	Add ORGANIZATION scope
packages/agent-mesh/src/agentmesh/governance/_conflict_resolution_impl.py	Add ORGANIZATION scope (fallback)

Test Results

• 49 new tests — covers mutual enforcement, trust agreements, delegations, blocklists, fail-closed semantics, expiration, constraints, ORGANIZATION scope ranking, and edge cases
• 79 existing tests — governance, trust policy, and conflict resolution tests pass with zero regressions
• 128 total tests passing

Design Decisions

1. Fail-closed: Missing org policy → deny. This is the safest default for cross-org interactions.
2. Most restrictive wins: When merging caller + callee decisions, any deny from either side blocks the interaction.
3. Delegation overrides: A delegation only overrides a deny from the delegating org for the specific category — it cannot override the other org's policies.
4. Persistence interface: FederationStore protocol allows future SQL/Redis backends without changing the engine.
5. No breaking changes: The federation module is entirely additive. Existing PolicyEngine, TrustBridge, and all other components remain untouched.

outputs:-

Closes #93

[github-actions]

Welcome to the Agent Governance Toolkit! Thanks for your first pull request.
Please ensure tests pass, code follows style (ruff check), and you have signed the CLA.
See our Contributing Guide.

[ArokyaMatthew]

@imran-siddique , please review.

[imran-siddique]

Impressive work @ArokyaMatthew — this is a solid federation governance implementation with good architecture, fail-closed semantics, and 49 tests. Three things to fix before merge:

1. \datetime.utcnow()\ deprecated (blocking): This is deprecated in Python 3.12+ and will be removed. Replace all instances with:
\\python
from datetime import timezone
datetime.now(timezone.utc) # instead of datetime.utcnow()
\\

2. Missing error handling in \FileFederationStore._load()\ (blocking): File I/O has no try-except — corrupt YAML, permission errors, or missing files will crash silently. Wrap in try-except with logging:
\\python
try:
with open(yaml_file) as f:
policy = OrgPolicy.from_yaml(f.read())
except (OSError, yaml.YAMLError) as e:
logger.error('Failed to load policy from %s: %s', yaml_file, e)
continue
\\

3. No tests for \FileFederationStore\ (blocking): 49 tests but zero coverage on the file-based store. Please add tests using \ mp_path\ for: valid YAML loads, invalid YAML fails gracefully, missing directory doesn't crash.

Nice to have (non-blocking):

• Add org_id format validation (^[a-zA-Z0-9_-]+$)
• Document that policy YAML files must be admin-controlled (not user-editable)

The mutual enforcement model (most restrictive wins), bilateral trust agreements, and ORGANIZATION scope integration are all well-designed. Looking forward to the updated PR.

[imran-siddique]

Thanks @ArokyaMatthew — this is a substantial contribution for #93. CI is showing 5 failures (API compatibility check + AI code review). Could you:

1. Rebase on latest main (lots of changes landed recently)
2. Address any CI failures after rebase
3. Make sure the new models align with the existing \PolicyEngine\ and \AgentIdentity\ interfaces

Happy to review once CI is green. This is great work — just needs the rebase to land cleanly.