Generate an Application Through an Auditable Job

This course is built around the public Zheta Kubernetes Lab monorepo. The excerpt below is runnable source, not pseudocode.

Source: services/control_plane/domain.py

def create(self, project_id: str, organization_id: str, name: str, actor: str, archetype: str) -> Project:
        project = Project(project_id, organization_id, name, actor, blueprint={"name": name, "archetype": archetype})
        project.collaborators.add(actor)
        with self.repository.transaction():
            self.repository.create(project)
            self._audit(project, actor, "project.created")
        return project

Code to reality

Declared intent

Create one tenant-owned project and its audit evidence as a single product operation.

Interpreter

Python executes the Forge domain model after the controller supplies authenticated command values.

Software effect

The repository durably owns the project while the event port publishes project.created evidence.

Hardware effect

The service process uses CPU and writes database pages to its persistent volume or managed database.

Observable evidence

A tenant-scoped GET plus a project.created evidence record proves both state and accountability.

The source tables below remain the detailed contract. Begin with these customer paths:

• D05-UC-01
  • Person: Application creator
  • Job: Generate a runnable application from an approved revision
  • Observable result: Run reaches succeeded with one immutable source artifact digest
• D05-UC-02
  • Person: Platform operator
  • Job: Retry interrupted generation without duplicate work or spend
  • Observable result: Same idempotency key returns the original run; approved retry resumes from recorded state

Now turn each customer job into a story with a result that an engineer can check:

• D05-US-01
  • Story: As an application creator, I want generation to name its exact inputs and output digest, so that I can review what was produced
  • Observable acceptance: Run shows revision hash, generator version, model/tool policy, artifact digest, and terminal status
• D05-US-02
  • Story: As a platform operator, I want idempotent retries, so that network failures do not duplicate artifacts or charges
  • Observable acceptance: Repeated key/input returns one run ID; conflicting input receives denial and audit trace

Finally trace each story through the system that owns its state and the evidence that proves the outcome:

• D05-FLOW-01
  • Trigger: Creator selects an approved revision and chooses Generate
  • Responsible systems: Application Catalog, Generation Orchestrator, Artifact Builder, policy validator
  • Authoritative state: Control-plane generation tables and S3-compatible artifact store
  • Owned record: GenerationRun
  • Observable evidence: Actor, revision hash, run ID, queue message ID, versions, digest, policy result, environment, timestamp, trace ID
  • Failure signal: Rejected revision, worker failure, policy violation, digest mismatch
• D05-FLOW-02
  • Trigger: Worker stops after artifact upload but before acknowledgement
  • Responsible systems: Generation Orchestrator, queue adapter, Audit Evidence
  • Authoritative state: Idempotency reservation and generation-run state
  • Owned record: SourceArtifact
  • Observable evidence: Delivery count, same artifact digest, one run, recovered status, conflicting retry denial, positive-control read
  • Failure signal: Key conflict, lease timeout, poison message, or duplicate terminal transition

Enterprise problem: Synchronous generation hides partial work, duplicated model charges, and changing inputs, so a timeout can leave customers unable to tell whether code exists or is safe to retry.

Whole-course context: The incoming artifact is a tenant-scoped project with an embedded archetype blueprint; today turns that stable input into content-addressed source.

Today’s slice: Execute the current synchronous deterministic generator through an injected port, persist its source and digest, then define the durable asynchronous run state still needed for worker-loss recovery.

End-of-day evidence: The API returns a sha256: artifact ID, restored project state references that artifact once, generated archetype tests reject unsafe output, and artifact.generated is published; no generation-run or retry receipt exists yet.

Still unsolved: The artifact is not previewed, connected to enterprise systems, published, or deployed to AWS.

Generation is a durable workflow rather than a long HTTP request. These use cases produce one artifact and contain a retry or policy failure without duplicating output.

An artifact without provenance cannot be reviewed or reproduced. These stories bind output to inputs and make retries deterministic.

The customer starts generation in Forge Studio and receives a durable run identifier immediately. Workers may fail, but the run state machine preserves what may happen next.

A queue does not own workflow truth; it only transports work. Generation Orchestrator owns the run state machine, while Artifact Builder owns deterministic packaging and object storage owns immutable bytes.

Durable retries require a stored state machine even though no generated application is running. The artifact is hosted-runtime input, not generated-app domain data.

Generated-application database: Not created in this slice — generation state belongs to the provider control plane and source artifacts belong to the hosted-runtime artifact store.

Happy-path-only tests miss the moment between artifact creation and durable workflow state. The current runnable slice is synchronous: it deterministically generates one source artifact, stores it, saves its reference, and publishes evidence. It does not yet implement the queue, worker-loss injection, or retry state machine described as the production target. Read the exact operation in services/control_plane/domain.py.

def generate(self, project: Project, actor: str) -> dict[str, str]:
    self._authorize(project, actor)
    generated = self.generator.generate(project.blueprint)
    self.artifacts.put(project.organization_id, generated["artifact_id"], generated["source"])
    artifact = {"artifact_id": generated["artifact_id"]}
    if artifact not in project.artifacts:
        project.artifacts.append(artifact)
        self.repository.save(project)
    self._audit(project, actor, "artifact.generated")
    return artifact

Use durable asynchronous jobs when work outlives an HTTP timeout or must survive worker loss. The current synchronous implementation teaches deterministic artifact identity and adapter boundaries only; do not claim retry or recovery until a durable run record, broker, idempotency key, and worker-loss test exist.