05 — Engineering standards

Where code belongs in MiCyte, which way imports may point, and the tests and budgets that enforce both.

Layers

The host application is fnd_app/. It is not part of the public repository.

Dependency direction

Imports point inward:

tools / state_machine / host    (L3)
            │ may import
            ▼
        adapters                 (L2, implement ports)
            │ may import
            ▼
          ports                  (L2, contracts)
            │ may import
            ▼
          core                   (L1)

1. core imports only the standard library and core.
2. adapters import ports and core, never tools or the host.
3. ports import only the standard library and core.
4. Only L3 wires concrete adapters to ports.
5. micyte imports nothing from the host application.

One exception to rule 1 exists: micyte/core/instance_baseline.py imports DocumentRequirement from micyte.ports.tool_package.

Enforcement

Architecture tests in fnd_app/tests/architecture/ parse each .py file in a package with ast and fail on a forbidden import:

Each import test has the same shape: a PACKAGE_DIR, a FORBIDDEN_IMPORT_PREFIXES tuple, an allowlist function, and an ast.walk over Import and ImportFrom nodes that collects violations into a list asserted empty. A new layering rule ships with a test in this shape.

One implementation per concept

• The address, hyphae and MSS engine has one home, micyte/core/datum_semantics/engine.py. micyte/core/mss/datum_identity.py delegates to it.
• Reuse an existing module before adding one.
• Delete a stub nothing calls, or leave a one-line comment naming its caller.

Caching

Measure before optimizing. The common document is small.

• _GLOBAL_CATALOG_CACHE in micyte/adapters/sql/datum_store.py holds the loaded catalog per (db_path, tenant_id), at most two entries, until the store's memo stamp (the database file's mtime and a door version) changes.
• SqliteSystemDatumStoreAdapter.replace_single_document_efficient in the same file replaces one document without re-encoding the others. Use it when a write touches one document.

Tests

The full suite is run in memory-capped batches by scripts/health_gate.sh. CI runs .github/workflows/tests.yml. The architecture guards alone:

python -m pytest fnd_app/tests/architecture -q

Front-end budgets

The portal shell's JavaScript and stylesheet are held to gzip byte caps, declared as PORTAL_SHELL_*_BUDGET_GZIP_BYTES in the host and in benchmarks/budgets/optimization_budgets.json:

scripts/benchmarks/check_optimization_budgets.py gzips the shipped files, compares them to the caps, and fails if the two declarations disagree. test_asset_manifest_module_presence.py asserts that every manifest entry is a real file, that module ids are unique, and that no v2_portal_*.js file ships unregistered. test_optimization_budget_measurement.py asserts that the checker measures the real files.

Each shell module declares a budget_group (initial_shell or deferred_tool_renderers). Put anything not needed for first paint in the deferred group.

Checklist before a pull request

• New code is in the layer that owns the concern.
• No import points outward.
• No second implementation of something that exists.
• No orphan stubs or unregistered v2_portal_*.js files.
• No new on-disk datum authority; MOS is canonical and YAML is transport only.
• A new layering rule has its architecture test.
• New or grown shell modules are in the right budget_group and within budget.
• Pages that describe the changed code are updated in the same change.