Generate an Application Through an Auditable Job
Convert one immutable specification into one reproducible artifact while making retries, model calls, and policy decisions observable.
Whole-system design
5 stable layers. Today's work is expanded and linked; the rest stays in context.
Product and authority
HelixWorks control plane
Coordinates a generation request while retaining the authoritative job and project lifecycle state.
Delivery and desired state
CI and immutable artifacts
Treats the generated output as an immutable artifact whose digest can survive retry and later promotion.
Cloud and orchestration
Compute and traffic
Platform service workloads
The generator deterministically transforms the reviewed blueprint into a content-addressed artifact.
Storage and evidence
Evidence and observability
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.