Codex integration guide

Work with a topology in Codex

Give Codex intent and constraints; let it inspect the manifest, change typed declarations, validate, and show the resulting architectural diff.

When to use

Use this sequence for both small edits and multi-service scenarios.

Behavior

Codex first inspects .service-architect/project.yaml and the project structure without executing arbitrary Python.
It edits declarations in their owning modules and keeps pipeline-local connections beside pipeline streams.
Validation returns stable machine-readable diagnostics; Codex resolves exact rule metadata before changing the model again.
Export writes canonical YAML atomically. Generation is a separate explicit operation that returns a ZIP artifact.

Recommended sequence properties

Each step has a bounded responsibility.

PropertyTypeDescription

InspectLocal, passive

Discover the manifest, entrypoint, output path, and cached ServiceGen metadata.

AuthorLocal edit

Use typed factories and object references to express the requested topology.

ValidateLocal execution

Run the trusted entrypoint in the bounded validation process and collect SG_* diagnostics.

ExportLocal write

Write canonical YAML for Designer or source control.

GenerateAuthorized API

Request target-language source and save the returned project ZIP.

Example

Create an Orders service with an HTTP input, validate the request,
process inventory reservations in parallel using the Inventory Workers pool
with priority 10, publish the result to Kafka, and route failures to an Error stream.
Validate the topology and show the architectural changes before exporting YAML.