Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 18 additions & 6 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -27,17 +27,29 @@ jobs:
repository: ontai-dev/platform
path: platform

- name: Checkout seam-core (replace dep)
- name: Checkout seam (replace dep)
uses: actions/checkout@v4
with:
repository: ontai-dev/seam-core
path: seam-core
repository: ontai-dev/seam
path: seam

- name: Checkout wrapper (replace dep)
- name: Checkout seam-sdk (replace dep)
uses: actions/checkout@v4
with:
repository: ontai-dev/wrapper
path: wrapper
repository: ontai-dev/seam-sdk
path: seam-sdk

- name: Checkout dispatcher (replace dep)
uses: actions/checkout@v4
with:
repository: ontai-dev/dispatcher
path: dispatcher

- name: Checkout conductor-sdk (replace dep)
uses: actions/checkout@v4
with:
repository: ontai-dev/conductor-sdk
path: conductor-sdk

- name: Set up Go
uses: actions/setup-go@v5
Expand Down
62 changes: 43 additions & 19 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,55 @@
> Read ~/ontai/CLAUDE.md first. The constraints below extend the root constitutional document.

### Schema authority
Primary: docs/conductor-schema.md (conductor behavioral specification: modes, capabilities, job protocol, signing)
CRD schema authority: ~/ontai/seam-core/docs/seam-core-schema.md (Decision G: seam-core owns InfrastructureRunnerConfig, InfrastructurePackReceipt, and all cross-operator CRD type definitions)
Supporting: all operator schema docs -- conductor implements capabilities for every domain.
Read ALL schema documents before any capability implementation work begins.

Primary: `docs/conductor-schema.md` -- conductor behavioral specification: modes, capabilities, job protocol, signing, compiler subcommands, role declaration contract.

CRD schema authority: `~/ontai/seam/docs/seam-schema.md` -- seam owns RunnerConfig, DriftSignal, LineageRecord, SeamMembership, and all cross-operator CRD type definitions under `seam.ontai.dev/v1alpha1`. CRD changes require a seam PR first.

Supporting: all operator schema docs. conductor implements capabilities for every domain. Read all schema documents before any capability implementation work begins.

---

### Invariants
CR-INV-001 -- Three-mode boundary is absolute: compile, executor, agent. No mode bleed. Compile-mode clients raise a fatal error if invoked in executor or agent mode. (root INV-014)
CR-INV-002 -- talos goclient is executor and agent mode only. Never in compile mode. (root INV-013)
CR-INV-003 -- The shared library (pkg/runnerlib) provides generation logic and job-spec builders. CRD type definitions are imported from seam-core/api/v1alpha1, not defined in runnerlib. Breaking changes to generation logic or job-spec builders require a major version bump and operator dependency updates before the runner release is cut. Breaking changes to CRD types require a seam-core PR first (Decision G, Decision 11).

CR-INV-001 -- Three-mode boundary is absolute: compile, execute, agent. No mode bleed. Compile-mode clients (Helm goclient, Kustomize goclient, SOPS handler) are excluded from the Conductor binary at build time via Go build tags. Invoking them in execute or agent mode is a programming error and causes InvariantViolation.

CR-INV-002 -- talos goclient is execute and agent mode only. Never in compile mode. (root INV-013)

CR-INV-003 -- CRD type definitions are imported from `seam/api/v1alpha1`, not defined locally. The shared capability library (conductor-sdk) provides execution contracts and capability constants; it is not the schema authority. Breaking changes to CRD types require a seam PR first. Breaking changes to capability parameter schemas require documenting impact before proceeding.

CR-INV-004 -- Named capabilities are additive. New capabilities never change existing capability behavior. Existing capability parameter schemas are never modified in a breaking way.
CR-INV-005 -- The capability manifest in RunnerConfig status is self-declared by the agent on startup. Operators never hardcode capability availability assumptions.

CR-INV-005 -- The capability manifest in RunnerConfig status is self-declared by the agent on startup. Operators never hardcode capability availability assumptions. Operators raise CapabilityUnavailable and wait when a required capability is absent from the status manifest.

CR-INV-006 -- Leader election in agent mode is not optional. One leader writes to RunnerConfig status and receipt CRs. All other replicas are standby.
INV-014 -- Helm goclient and kustomize goclient are compile mode only. They exist exclusively in the Compiler binary. Excluded from Conductor at build time via Go build tags.
INV-023 -- Conductor binary supports only execute and agent modes. Compile mode attempted on Conductor causes an immediate InvariantViolation structured exit before any other initialization proceeds.
INV-024 -- Compiler and Conductor are always released together from the same source commit and carry the same version tag. Deploying mismatched versions against the same cluster is unsupported and undefined behavior.
INV-026 -- PackInstance signing and PermissionSnapshot signing are performed exclusively by the management cluster Conductor in agent mode. Target cluster Conductor verifies but never signs. Verification failure blocks receipt acknowledgement.

INV-014 -- Helm goclient and kustomize goclient are compile mode only. They exist exclusively in the Compiler binary. Excluded from Conductor at build time via Go build tags. (root INV-014)

INV-023 (conductor-specific) -- Conductor binary supports only execute and agent modes. Compile mode attempted on Conductor causes an immediate InvariantViolation structured exit before any other initialization proceeds.

INV-026 (conductor-specific) -- PackInstance signing and PermissionSnapshot signing are performed exclusively by the management cluster Conductor in agent mode. Target cluster Conductor verifies but never signs. Verification failure blocks receipt acknowledgement.

---

### Image and binary constraints

Three images from this repo (Decision 12 in root CLAUDE.md):
- Compiler: debian-slim. compile mode only. Never deployed to cluster.
- Conductor execute: debian-slim. Kueue Job pods on management cluster only.
- Conductor agent: distroless. Deployed to ont-system on every cluster.
Execute image must never be distroless. Agent image must never be debian-slim.

- Compiler (`Dockerfile.compiler`): debian-slim. Compile mode only. Never deployed to any cluster.
- Conductor execute (`Dockerfile.execute`): debian-slim. Kueue Job pods on management cluster only.
- Conductor agent (`Dockerfile.agent`): distroless. Deployed to ont-system on every cluster.

Execute image must never be distroless. Agent image must never be debian-slim. These constraints are permanent and locked.

Lab image tag for all three: `:dev`. Custom per-build tags are never committed (INV-023).

---

### Session protocol additions
Step 4a -- Read conductor-design.md in this repository.
Step 4b -- Before implementing a new named capability, verify it is not a duplicate. Check the capability table in docs/conductor-schema.md.
Step 4c -- Before modifying the shared library, assess operator impact. Document breaking vs non-breaking change in PROGRESS.md before proceeding.

Step 4a -- Read `conductor-design.md` in this repository before any implementation work.

Step 4b -- Before implementing a new named capability, verify it is not a duplicate. Check the capability table in `docs/conductor-schema.md`. Verify the constant does not already exist in `conductor-sdk/runnerlib/constants.go`.

Step 4c -- Before modifying the conductor-sdk shared library, assess operator impact. Document breaking vs non-breaking change in PROGRESS.md before proceeding. Breaking changes require all operator dependency updates before any conductor release is cut.
6 changes: 4 additions & 2 deletions Dockerfile.agent
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,12 @@
FROM golang:1.25 AS builder
WORKDIR /build
COPY conductor/ .
COPY conductor-sdk/ ../conductor-sdk/
COPY dispatcher/ ../dispatcher/
COPY guardian/ ../guardian/
COPY platform/ ../platform/
COPY seam-core/ ../seam-core/
COPY wrapper/ ../wrapper/
COPY seam/ ../seam/
COPY seam-sdk/ ../seam-sdk/
RUN CGO_ENABLED=0 GOOS=linux go build \
-trimpath \
-ldflags="-s -w" \
Expand Down
6 changes: 4 additions & 2 deletions Dockerfile.compiler
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,12 @@
FROM golang:1.25 AS builder
WORKDIR /build
COPY conductor/ .
COPY conductor-sdk/ ../conductor-sdk/
COPY dispatcher/ ../dispatcher/
COPY guardian/ ../guardian/
COPY platform/ ../platform/
COPY seam-core/ ../seam-core/
COPY wrapper/ ../wrapper/
COPY seam/ ../seam/
COPY seam-sdk/ ../seam-sdk/
RUN CGO_ENABLED=0 GOOS=linux go build \
-trimpath \
-ldflags="-s -w" \
Expand Down
6 changes: 4 additions & 2 deletions Dockerfile.execute
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,12 @@ ARG KUSTOMIZE_VERSION=5.6.0
FROM golang:1.25 AS builder
WORKDIR /build
COPY conductor/ .
COPY conductor-sdk/ ../conductor-sdk/
COPY dispatcher/ ../dispatcher/
COPY guardian/ ../guardian/
COPY platform/ ../platform/
COPY seam-core/ ../seam-core/
COPY wrapper/ ../wrapper/
COPY seam/ ../seam/
COPY seam-sdk/ ../seam-sdk/
RUN CGO_ENABLED=0 GOOS=linux go build \
-trimpath \
-ldflags="-s -w" \
Expand Down
Loading
Loading