Skip to content

Service rules

What every deployed service MUST do, whatever it is written in. These constrain shape, not language.

Provenance and observability

SERVICE-1: A service MUST be able to say what version it is

  • Every Go binary MUST link lyceum.technology/daedalus/version.
  • It MUST report the stamped values both ways: a build-info line at startup, and the Prometheus build_info gauge.
  • A Python service MUST carry the same values from package metadata and the LYC_BUILD_VERSION/LYC_BUILD_COMMIT environment.
  • If a service reports 0.0.0 or unknown, then the build is broken.

How the values get in: container images.

Enforcement: Review only. stream_execlet is an approved exclusion.

SERVICE-2: A service MUST expose /metrics

  • This binds every service, including one with nothing else to serve.
  • A service that exposes no metrics MUST NOT exist.
  • At minimum the endpoint serves the build_info gauge (SERVICE-1) and the process metrics.
  • You MUST use daedalus/metrics.MustNewRegistry and a small promhttp endpoint.
  • DO NOT invent a path to Grafana. One exists for every Cloud Run service in Terraform.

Enforcement: Review only.

Runtime

Configuration comes from the environment or a mount (BUILD-22). A service runs as UID 65532 (BUILD-20). Both are enforced in the image.

SERVICE-3: A service MUST shut down gracefully on SIGTERM

  • You MUST stop accepting work, finish or requeue what is in flight, then exit.
  • An entrypoint MUST forward the signal.

Enforcement: the shared Dockerfiles for signal delivery. Review only for the handling.

SERVICE-4: A service MUST NOT keep persistent state on local disk

  • State that survives a restart MUST live in a data store the environment provides.
  • A container filesystem is scratch space.

Enforcement: Review only.

Shared code

SERVICE-5: Use daedalus, do not reinvent it

  • Before you write a component, you MUST check whether daedalus_go/ ⧉ already provides it.
  • DO NOT reimplement what daedalus provides.
  • If daedalus does not do what you need, then extend daedalus.

Enforcement: Review only.

SERVICE-6: A service MUST NOT invent its own authentication layer

  • DO NOT write your own auth. inference_proxy is debt, not precedent.
  • If no shared mechanism fits, then the escalation path is the DRI. Agree the mechanism there before you write code.

Enforcement: Review only.

SERVICE-7: Every internal interface MUST have a machine-checkable schema

  • You MUST commit a Protobuf or OpenAPI schema beside the service that serves it.
  • You MUST change it compatibly (CHANGE-3).
  • Transport is not the rule. gRPC and REST both satisfy it.
  • A contract that exists only in the calling code does not satisfy it.
  • This binds every new interface. The existing interfaces without a schema are tracked debt.

Enforcement: Review only. A schema-diff check is the gate this wants. See enforcement gaps.

SERVICE-8: Services MUST authenticate to each other by identity, not shared secret

  • A service MUST prove who it is with a Google-signed ID token.
  • The callee MUST authorise with IAM. On Cloud Run that is roles/run.invoker.
  • DO NOT add a shared *_SERVICE_TOKEN. It cannot be attributed, scoped or revoked per peer.
  • If a peer has no Google identity, such as a machine outside GCP, then a per-peer secret is the exception.
  • That secret MUST be scoped to the one peer, and the DRI MUST approve it.

Enforcement: Review only. The existing tokens across Iris are tracked debt.

SERVICE-9: Stateless services MUST run on Cloud Run

  • If a service cannot run on Cloud Run, then it MUST publish its artefact to an Artifact Registry generic repository.
  • It MUST then deploy from a pinned version.
  • DO NOT deploy a binary copied out of a build directory.
  • A service that could run on Cloud Run but runs on k3s or a VM today is an exception and tracked debt.
  • It follows the pinned-artefact bullets above until it moves.

Enforcement: Review only. See where services run.

SERVICE-10: Every service SHOULD name one point of contact

  • You SHOULD record the point of contact with the service.
  • One person or team MAY be the point of contact for several services.
  • A service SHOULD NOT name two points of contact.

Enforcement: Review only.

Business logic

SERVICE-11: The edge carries edge concerns only

  • The edge MUST hold authentication, quotas and routing only.
  • Business logic MUST live in the service that owns the domain.
  • DO NOT add new functionality to /app. It is being dismantled.
  • DO NOT adopt a managed API gateway product.

Enforcement: Review only. See CHANGE-5 and /app.