Generate an Application Through an Auditable Job
Convert one immutable specification into one reproducible artifact while making retries, model calls, and policy decisions observable.
System map · Day 05
Whole-system design
Five stable layers. Today's work is expanded and linked; the rest stays in context.
Product and authority
Covered — People and product entry points · Generated application planeAhead — Identity and policy
HelixWorks control plane
Source-backed today
Coordinates a generation request while retaining the authoritative job and project lifecycle state.
Delivery and desired state
Ahead — Git desired state · Argo CD reconciliation
CI and immutable artifacts
Source-backed today
Treats the generated output as an immutable artifact whose digest can survive retry and later promotion.
Cloud and orchestration
Covered — Terraform and AWS APIs · Kubernetes or EKS control planeAhead — Accounts, VPC, DNS, and private paths
Compute and traffic
Covered — Worker computeAhead — Generated app workloads · Ambient mesh data plane
Platform service workloads
Source-backed today
The generator deterministically transforms the reviewed blueprint into a content-addressed artifact.
Storage and evidence
Covered — Product data and artifactsAhead — Infrastructure state · Cluster desired and live state
Evidence and observability
Source-backed today
Records generation evidence so artifact creation cannot silently diverge from durable workflow state.
The enterprise problem and today’s slice
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.
Customer outcome and implementation focus
The customer outcome is a reviewable generate an application through an auditable job change, not a collection of requirements. This day starts with the implementation boundary, then uses the command or manifest below to produce positive, denied, and recovery evidence.
Components in focus
Generation API, job worker, evidence service, and queue/job controller; worker container compute; job and artifact database plus object storage for generated output; cache: not involved because job state transitions must be durable.
This map names the implementation boundary for this day. The service or controller changes only the state it owns; runtime and audit evidence let the operator distinguish a declared change from an effective one.
Execute an auditable generation job
Run and interrupt one generation
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
Decision rules
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.