Final Structure Migration¶

This page explains how to move code written for 0.93a6 and earlier mixed layouts to the final semantic structure introduced on the current pre branch.

What changed¶

Cullinan no longer keeps historical root-level wrappers such as:

cullinan.app
cullinan.application_model
cullinan.public_api
cullinan.module_scanner
cullinan.scan_stats
cullinan.scanner
cullinan.compat

The maintained structure is now centered on:

cullinan.application
cullinan.web
cullinan.core
cullinan.runtime
cullinan.transport
cullinan.testing
cullinan.support

Why this was removed¶

The previous layout left new semantic packages and historical wrappers side by side. That made the package tree harder to understand, encouraged old imports to remain in use, and kept the codebase in a long-lived intermediate state.

Cullinan now treats the semantic packages as the real structure rather than as facades placed on top of legacy files.

Old-to-new path mapping¶

Old path	New path
`cullinan.app`	top-level `cullinan` startup API (`configure`, `run`, `get_asgi_app`)
`cullinan.application_model`	`cullinan.application`
`cullinan.public_api`	`cullinan.application.public`
`cullinan.module_scanner`	`cullinan.runtime.module_scanner`
`cullinan.scan_stats`	`cullinan.runtime.scan_stats`
`cullinan.scanner`	`cullinan.runtime.scanner`
`cullinan.controller`	`cullinan.web.controller`
`cullinan.middleware`	`cullinan.web.middleware`
`cullinan.params`	`cullinan.web.params`
`cullinan.gateway`	`cullinan.web.gateway`
`cullinan.handler`	`cullinan.web.handler`
`cullinan.adapter`	`cullinan.transport.adapter`
`cullinan.service`	`cullinan.core` (`@service`) / `cullinan.core.services` (`Service`, registry helpers)
`cullinan.config`	`cullinan.support.config`
`cullinan.exceptions`	`cullinan.support.exceptions`
`cullinan.path_utils`	`cullinan.support.path_utils`

Common migration rewrites¶

Application startup¶

# Before
from cullinan.public_api import run

# After
from cullinan import run

Runtime model helpers¶

# Before
from cullinan.application_model import Application

# After
from cullinan.application import Application

Web-facing APIs¶

# Before
from cullinan.controller import controller
from cullinan.params import Body

# After
from cullinan.web import controller, Body

Advanced transport integration¶

# Before
from cullinan.adapter import ASGIAdapter

# After
from cullinan.transport.adapter import ASGIAdapter

Mental model change¶

Do not treat the migration as “find another old import that still works.”

The new rule is:

business application startup lives in top-level cullinan
business web development lives in cullinan.web
IoC/DI and lifecycle live in cullinan.core
discovery and scanning live in cullinan.runtime
server integration lives in cullinan.transport
support utilities live in cullinan.support

If existing code still depends on removed root-level wrappers, migrate the import instead of reintroducing the wrapper.