The CZOA/CZOI Tutorial

This tutorial will teach you to think in CZOA — the Constrained Zoned-Object Architecture — and to build real systems with the CZOI toolkit.

It is not a reference manual. It is a journey. We start with a problem that has frustrated software architects for decades — the fragmentation of modern enterprises into incompatible silos — and we arrive at a framework that lets you build systems that are simultaneously secure, intelligent, organisation-aligned, and integrable. Along the way, you'll write code that runs. By the end, you'll be able to look at any complex organisation — a hospital, a bank, a factory, a government, a post-merger enterprise — and design a CZOI system that models it faithfully and composes it cleanly.

What you'll need

• Python 3.9 or later
• The CZOI toolkit: pip install czoi-toolkit
• Willingness to think abstractly — but we'll make every abstraction concrete.

1The Fragmentation Problem

Three engineers, one hospital network

Meet Maya, Sam, and Priya. They work at the same regional health authority but rarely talk.

Maya builds the AI triage system. Her models predict sepsis risk from vital signs with 94 % accuracy. She thinks in tensors.

Sam builds the access-control system. He knows the hospital's organisational chart down to the sub-team level. He thinks in permissions.

Priya is the integration architect. She arrived six months ago when the regional health authority was formed by merging three previously independent hospitals. Her job is to make the merged organization work as one — without rewriting any of the legacy systems, without breaking any of the pre-merger compliance certifications, and without forcing three different clinical cultures to adopt a single set of IT tools.

When flu season hits and the hospital network needs to redeploy nurses across all three legacy hospitals, three things happen: Maya's model only sees patients from the hospital where it was trained; Sam's role taxonomy doesn't span the merged organization; and Priya's integration work is stalled on legacy EMR vendors. Patients wait.

This is the fragmentation problem. Not one fragmentation, but three, each reinforcing the others.

The three fragmentations

Fragmentation 1 — Intelligence vs. security. AI models and access-control systems have evolved separately, with different abstractions, correctness criteria, and timescales.

Fragmentation 2 — Local autonomy vs. global governance. Subunits want to evolve at their own rate; governance wants a single policy. Traditional architectures force a choice.

Fragmentation 3 — Heterogeneous systems vs. coherent operations. Real organizations run on dozens of incompatible systems. Making them work together is the central challenge of modern enterprise IT.

Why the traditional answers fail

Centralize destroys local autonomy. Federate loosely abandons formal guarantees. Rewrite everything is bankrupting in practice. What is missing is a framework that preserves local autonomy while providing global integration guarantees.

The CZOA insight

Enterprise systems are a species of intelligent systems — and the same recursive structure that makes them intelligent makes them integrable.

A taste of the unification

from czoi import CZOABuilder, Application, Operation, Role, User

builder = CZOABuilder("RegionalHealthAuthority")
authority = builder.root
hospital_a = builder.add_zone("HospitalA", parent=authority)
emergency  = builder.add_zone("Emergency", parent=hospital_a, atomic=True)

# Intelligence: sepsis model
from czoi import Predictor
sepsis = Predictor("sepsis", threshold=0.85)
emergency.add_neural("sepsis", sepsis)

# Security: unified role taxonomy
app = Application("EMR", zone=authority)
prescribe = app.add_operation(Operation("prescribe"))
authority.add_application(app)
attending = Role("AttendingPhysician", zone=authority,
                 base_permissions=[prescribe])
authority.add_role(attending)

# Integration: three hospitals, one authority — same tree
alice = User("alice", roles={"AttendingPhysician"})
for z in emergency.ancestry():
    z.add_user(alice)

print(builder.permission_engine.decide(alice, prescribe, emergency).name)

2Zones: The Recursive Foundation

A zone is a system

In CZOA, every organisational unit is a zone, and every zone is a full CZOI system. A hospital's Emergency department isn't just a data structure pointing to its parent; it has its own procedures, staff, equipment, and quality metrics. The same reasoning applies to a legacy system: a 20-year-old mainframe is a full system in its own right, with its own internal logic, data, and operational cadence.

zone = (Z, R, U, A, O, N, E, Γ, Φ, Δ)

The parent-child relationship doesn't merge zones. It composes them. In an integration scenario, this composition is exactly what makes federation work: the merged authority can impose shared governance at the parent level without intruding into how each legacy system operates internally.

Three kinds of zone

• CompositeZone — a zone that may contain child zones.
• AtomicZone — a leaf zone with no children.
• AdapterZone — a leaf zone whose internal behaviour is opaque, wrapping a legacy or external system through a declared interface.

Building your first tree

from czoi import CZOABuilder

builder = CZOABuilder("Company")
root = builder.root

engineering = builder.add_zone("Engineering", parent=root)
backend = builder.add_zone("Backend", parent=engineering, atomic=True)
frontend = builder.add_zone("Frontend", parent=engineering, atomic=True)

for zone in root.walk():
    indent = "  " * zone.depth()
    kind = "atomic" if not zone.zones else "composite"
    print(f"{indent}{zone.name} [{kind}]")

Output:

Company [composite]
  Engineering [composite]
    Backend [atomic]
    Frontend [atomic]

The containment principle

U_child ⊆ U_parent

Every user of a child zone must also be a user of its parent. In an integration scenario, containment is what makes shared governance tractable: the merged authority sees every user in every legacy subsystem, but the legacy subsystems see only their own users.

from czoi import User, ZoneContainmentError

alice = User("alice", roles={"Engineer"})
for zone in backend.ancestry():
    zone.add_user(alice)

# Attempting to register a user at a child before the parent raises:
# backend.add_user(charlie)  # ZoneContainmentError

3The 10‑Tuple

S = (Z, R, U, A, O, N, E, Γ, Φ, Δ)

The ten components are minimal and orthogonal. This orthogonality is what makes CZOI composable — and therefore what makes it integrable. If two components did the same job, you'd have to decide which one to use in each context, and the system would have internal ambiguity that breaks under composition.

4Roles, Users, and Seniority

from czoi import Role, Operation, Application, CZOABuilder

builder = CZOABuilder("Bank")
bank = builder.root

app = Application("CoreBanking", zone=bank)
deposit = app.add_operation(Operation("deposit"))
withdraw = app.add_operation(Operation("withdraw"))
approve_loan = app.add_operation(Operation("approve_loan"))
bank.add_application(app)

teller = Role("Teller", zone=bank,
              base_permissions=[deposit, withdraw])
senior_teller = Role("SeniorTeller", zone=bank,
                     base_permissions=[approve_loan])
manager = Role("BranchManager", zone=bank, base_permissions=[])

manager.add_junior(senior_teller)
senior_teller.add_junior(teller)
for r in (teller, senior_teller, manager):
    bank.add_role(r)

The base permissions of a role are what you explicitly grant. The effective permissions include everything inherited from junior roles. The Manager has no base permissions of their own but inherits everything.

5Operations and the Application Boundary

app = Application("Payroll", zone=hr)
view    = app.add_operation(Operation("view_payroll"))
edit    = app.add_operation(Operation("edit_payroll"))
process = app.add_operation(Operation("process_payroll"))
approve = app.add_operation(Operation("approve_payroll"))

auditor_role.grant(view)
hr_admin_role.grant(view)
hr_admin_role.grant(edit)
hr_admin_role.grant(process)
controller_role.grant(view)
controller_role.grant(approve)

6The Permission Calculus

The permission calculus Φ is a two-stage recursive decision function:

1. Local decision. Look at the user's roles in this zone.
2. Parent override. If the local decision is inconclusive, recurse to the parent.

engine = builder.permission_engine
print(engine.decide(alice, prescribe, icu).name)          # ALLOW
print(engine.decide(bob,   prescribe, icu).name)          # DENY
print(engine.evaluate_local(bob, prescribe, icu).name)    # INCONCLUSIVE

7Neural Components

from czoi import Predictor, AnomalyDetector, RoleMiner

model = Predictor("sepsis", threshold=0.85)
model.fit(X_train, y_train, epochs=500)
model.fires({"hr": 0.9, "temp": 0.8, "lactate": 0.9})

detector = AnomalyDetector("access", input_dim=4, latent_dim=2)
detector.fit(X_normal, epochs=300)
detector.is_anomalous(x)

miner = RoleMiner(latent_dim=4, min_cluster_size=2)
result = miner.mine(X_binary, operation_names)

8Semantic Embeddings

from czoi import EmbeddingService

emb = EmbeddingService(dimension=64)
v1 = emb.embed_operation(op1)
v2 = emb.embed_operation(op2)
print(emb.similarity(v1, v2))

# Contrastive training of the global alignment functor
emb.train_alignment(positives=[(a, b)], negatives=[(a, c)])

9Adaptive Access Control

from czoi import NeuralContribution

def surge_hook(user, operation, zone, base_decision):
    if (operation.name == "prescribe"
            and user.has_role("SeniorNurse")
            and zone.properties.get("surge_active", False)):
        return Decision.ALLOW
    return base_decision

builder.permission_engine.set_neural_contribution(
    NeuralContribution(surge_hook)
)

Theorem 7 of the paper guarantees that any adaptive update which preserves monotonicity, satisfies all constraints, and maintains a complete audit trail is safe.

10Constraints via UniLog

builder.add_access_constraint("""
    signature {
        sort User;
        predicate prescribe(u: User);
        predicate dispense(u: User);
    }
    forall u: User . not (prescribe(u) and dispense(u))
""")

11Daemons and Continuous Monitoring

from czoi import Daemon, DaemonSignal

class BatteryDaemon(Daemon):
    def __init__(self, robots, threshold=0.2, parent=None):
        super().__init__("BatteryDaemon", parent=parent, interval=1.0)
        self.robots = robots
        self.threshold = threshold

    def monitor(self):
        for r in self.robots:
            if r.attributes.get("battery", 1.0) < self.threshold:
                self.emit_signal(DaemonSignal.STATE_WARNING,
                                 {"robot": r.name})

12Designing for a Domain

1. Map the organisation. Draw the reporting structure.
2. Identify the zone tree. Choose which units become zones.
3. Define roles. Enumerate job functions within each zone.
4. Enumerate operations. List the atomic actions each zone supports.
5. Grant base permissions. Assign operations to roles.
6. Write constraints. Capture policy invariants.
7. Identify adaptation points. Where will conditions change?
8. Choose neural components. Which zones benefit from learning?
9. Design daemons. What must be monitored?
10. Iterate. Validate with domain experts.

13Testing and Verification

def test_attending_can_prescribe(hospital):
    result = hospital["builder"].permission_engine.decide(
        hospital["alice"], hospital["prescribe"], hospital["emergency"],
    )
    assert result is Decision.ALLOW

def test_nurse_cannot_prescribe(hospital):
    result = hospital["builder"].permission_engine.decide(
        hospital["bob"], hospital["prescribe"], hospital["emergency"],
    )
    assert result is Decision.DENY

14Deployment Patterns

1. Embedded — inside your application process.
2. Sidecar — a separate service alongside your app.
3. Centralised — one shared permission service.
4. Hybrid — per-zone runtimes coordinated globally (recommended).

15Integrating Heterogeneous Systems

Adapter zones: the mechanism for integrating legacy systems

An adapter zone is a leaf CZOI subsystem whose internal behaviour is opaque, but whose interface — a set of roles, operations, and constraints — is declared explicitly.

from czoi import AdapterZone, Operation, Role

class LegacyHRAdapter:
    def __init__(self, connection_string):
        self.conn = legacy_connect(connection_string)

    def execute(self, operation_name, user_name, kwargs):
        if operation_name == "LegacyHR.view_employee":
            return self.conn.read_employee(kwargs["employee_id"])
        elif operation_name == "LegacyHR.edit_employee":
            return self.conn.update_employee(
                kwargs["employee_id"], kwargs["changes"],
            )
        raise ValueError(f"Unknown operation: {operation_name}")

legacy_hr = AdapterZone(
    name="LegacyHR",
    adapter=LegacyHRAdapter("sql://legacy-hr.internal"),
)

legacy_hr.expose_operations({
    "view_employee": Operation("view_employee"),
    "edit_employee": Operation("edit_employee"),
})

Federating independent subsystems

from czoi import FederationBuilder

fed = FederationBuilder("MergedHealthAuthority")
fed.adopt_subsystem(legacy_hr_a, name="LegacyRegionA")
fed.adopt_subsystem(legacy_hr_b, name="LegacyRegionB")
fed.adopt_subsystem(shared_services, name="SharedServices")

fed.share_constraint("""
    signature {
        sort User, Role;
        constant HRViewer : Role;
        constant FinanceApprover : Role;
        predicate hasRole(u: User, r: Role);
    }
    forall u: User .
        not (hasRole(u, HRViewer) and hasRole(u, FinanceApprover))
""")

fed.add_cross_zone_daemon(FederationHealthDaemon())

The Integration Theorem

Let S₁ and S₂ be two independent, soundly integrated CZOI systems with no shared operations. Then the composed federation S = S₁ ⊕ S₂ under a new common parent satisfies:

1. S is a well-formed CZOI system.
2. Every identity constraint of S₁ and S₂ holds in S.
3. Every access constraint of S₁ and S₂ holds in S.
4. Any additional constraint on the parent is enforced for both subsystems.

Corollary (Post-Merger Integration Guarantee). In a post-merger scenario where two legacy organizations are integrated under a new parent authority, if both legacy systems are soundly integrated CZOI systems, the merger preserves each legacy system's security guarantees while enabling explicit cross-system policy at the authority level.

Three integration patterns

16Cross‑Zone Reasoning

def add_gamma_mapping(
    child_zone, child_role,
    parent_zone, parent_role,
    weight=1.0,
):
    parent_ops = sorted(parent_role.base_permissions,
                        key=lambda o: o.qualified_name)
    n_transfer = max(1, int(round(weight * len(parent_ops))))
    for op in parent_ops[:n_transfer]:
        child_role.grant(op)
    child_zone._invalidate_cache()

# Developer inherits Engineer's permissions during on-call
add_gamma_mapping(dev_zone, developer, corp_zone, engineer, weight=1.0)

17Composition & Federation

• Product (×) — parallel composition. Both subsystems exist, independently.
• Coproduct (+) — alternative composition. One or the other.
• Exponential (→) — morphism objects. One subsystem governs another.

These are the three integration patterns from Chapter 15, expressed in categorical terms.

18The Category‑Theoretic View

CZOA uses category theory to make precise claims: "Any two CZOI systems can be composed"; "Composition preserves constraints"; "Integration is a morphism." These have formal proofs and algorithmic consequences.

The paper introduces F_integr: CZOA_Rec → Graph, mapping each system to its integration graph whose vertices are zones and whose edges are cross-zone integration relations. Because F_integr is a functor, any morphism between systems induces a graph homomorphism between their integration graphs.

Conclusion

You started with a problem: three fragmentations — intelligence vs. security, autonomy vs. governance, and heterogeneous systems vs. coherent operations — that cost real organizations real resources. You learned that CZOA closes all three fragmentations with a single recursive mechanism.

You built up the theory in layers, and you learned to apply it. What you can do now:

• Look at any organisation and design a CZOI model.
• Write formal constraints that capture policy — and compose them across subsystems.
• Build adaptive systems that respond to changing conditions.
• Wrap legacy systems as adapter zones without modifying them.
• Federate independent subsystems under shared governance with formal guarantees.
• Verify your designs with tests and analysis.
• Deploy CZOI systems in production — as federations when necessary.

The bigger picture

The organizations that thrive in the next decade will not be those that chose between autonomy and integration, nor between security and intelligence. They will be those that discovered how to have all four. The CZOI toolkit is one path to that discovery.

Appendices

Appendix A — Quick Reference

from czoi import (
    CZOABuilder, Application, Operation, Role, User,
    AdapterZone, FederationBuilder,
    Daemon, DaemonSignal, Predictor, AnomalyDetector, RoleMiner,
    EmbeddingService, Decision, NeuralContribution,
)

builder = CZOABuilder("Name")
zone = builder.add_zone("ZoneName", parent=builder.root, atomic=False)

Appendix B — Glossary

• Adapter Zone — a CZOI zone wrapping a non-CZOI subsystem through a declared interface.
• AtomicZone — a leaf zone with no children.
• CompositeZone — a zone that may have children.
• Containment principle — U_child ⊆ U_parent.
• Decision — ALLOW, DENY, or INCONCLUSIVE.
• Federation — a CZOI system with multiple operationally independent child zones.
• γ (gamma) mapping — an inter-zone role permission transfer.
• Integration relation (ι) — a 4-tuple (γ, C, δ, ε) defining how two sibling zones compose.
• Neural component — a learnable function inside a zone.
• Operation — an atomic permission target.
• Role — a job function within a zone.
• Seniority — the intra-zone role hierarchy.
• UniLang — the formal constraint language.
• Zone — a recursive CZOI subsystem.

Appendix C — Further Resources

Papers. Wang, H. (2025). Constrained Object Hierarchies. Computers, 14(11), 478. Wang, H. (2026). A Formalized Zoned Role-Based Framework. Computers, 15(3). Wang, H. (2026). Constrained Zoned-Object Architecture (CZOA). Preprint. Wang, H. (2026). UniLog: A Unified Logic Framework. Preprint.

Code. CZOI Toolkit · UniLog Toolkit

Background. Beer, S. (1972). Brain of the Firm. Fong & Spivak (2019). An Invitation to Applied Category Theory. Ross, Weill & Robertson (2006). Enterprise Architecture as Strategy.