PromptPackSource CRD

A PromptPackSource publishes PromptPacks for one logical pack. A git or oci source polls its upstream for a compiled pack.json and creates an immutable PromptPack version, plus a backing ConfigMap, for each new version it finds. A project source resolves an authored Arena project in its workspace and creates one live PromptPack that points at it. PromptPackSource is an Enterprise CRD, reconciled by the Arena controller.

API version

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: PromptPackSource

Short name: pps (e.g. kubectl get pps).

Spec

Field	Type	Description
`type`	`git` \| `oci` \| `project`	Required. Selects the source variant. Exactly the matching `git`, `oci` or `project` block must be set (CEL-validated).
`git`	object	Git source: `url`, optional `ref` (`branch`/`tag`/`commit`), `path` (directory holding `pack.json`), `secretRef`, or instead `connectionRef` (see Git sources).
`oci`	object	OCI source: `url`, `insecure` (default `false`), `secretRef`.
`project`	object	Arena project source. See `project`.
`packName`	string	Required. The logical pack every created PromptPack carries in `spec.packName`. Immutable for a `project` source (CEL-validated). A `packName` holds either published versions (`git`, `oci`, the deploy API) or one live pack, never both: a source whose `packName` already has the other kind reports `PackNameConflict` and creates nothing.
`interval`	duration	Poll interval (e.g. `5m`); pattern `^([0-9]+(\.[0-9]+)?(ms\|s\|m\|h))+$`. Required for `git` and `oci` (CEL-validated). A `project` source ignores it.
`timeout`	duration	Per-fetch timeout (default `60s`).
`suspend`	bool	Stop reconciling when `true` (default `false`).
`historyLimit`	int32 (min 0)	Superseded versions kept per `packName` before garbage collection (default `10`). A version an AgentRuntime references, or one superseded less than 24 hours ago, is kept regardless.

`project`

Field	Type	Description
`project.id`	string	Required. The ArenaProject’s name, in the source’s namespace. Pattern `^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$`, at most 253 characters. Immutable.
`project.user`	string	Required. The pseudonym of the user whose workspace of the project the live pack compiles from: a dev agent is per project and per user, and a project has no shared copy to compile instead. Set by the deploy API from the caller’s verified token, never from a request body. Lower-case letters and digits (pattern `^[a-z0-9]+$`), at most 64 characters. Immutable.

A project source fetches nothing and is never polled. The controller checks that the ArenaProject exists and checks the user’s workspace of it (arena/workspaces/<id>/<user>) has a config.arena.yaml. For a hosted project whose workspace that user has never opened, it first clones the workspace from the project’s repository. For an external project in that state it creates nothing and reports ProjectNotFound, because the clone needs the user’s own git credential. It does not compile the project. It also ensures the workspace content claim (workspace-<namespace>-content) exists, creating the PVC itself when the install has a StorageManager: the live pack’s agent mounts that claim read-only to compile the project, and nothing else creates it for a workspace whose first arena use is a dev agent. It then creates one PromptPack named pp-<hash> (from packName and live), with version: live and:

spec:
  source:
    type: live
    live:
      sourceRef: <PromptPackSource name>
      project:
        id: <project.id>
        user: <project.user>

The source is the PromptPack’s controller owner, so deleting the source deletes the pack. The pack’s spec is immutable, and later reconciles leave it unchanged. A project source creates no ConfigMap and garbage-collects no versions.

Status

Field	Description
`phase`	`Ready` or `Error`. `Pending` for a source suspended before its first sync.
`observedGeneration`	Last spec generation the controller has processed.
`artifact`	`git`/`oci` only: the fetched `revision`, `version`, `checksum`, `size` and `lastUpdateTime`.
`lastSyncedVersion`	The version most recently created. `live` for a `project` source.
`versionsMaterialized`	Number of PromptPacks this source has created.
`lastFetchTime` / `nextFetchTime`	`git`/`oci` only: timestamps of the latest and next scheduled fetch.
`conditions[type=Ready]`	True once the current version (or the live pack) exists.

`Ready` reasons for a `project` source

Reason	Status	Meaning
`Ready`	True	The live PromptPack exists and serves the project
`ProjectNotFound`	False	No ArenaProject named `project.id` in the source’s namespace, no workspace directory for the user’s workspace of the project, or an external project whose workspace that user has not opened yet
`ConfigNotFound`	False	The user’s workspace of the project has no `config.arena.yaml`
`ContentStorageUnavailable`	False	The arena controller was started without workspace content storage, or the workspace content claim (`workspace-<namespace>-content`) the live pack’s agent mounts does not exist and this source could not create or find one: no Workspace owns the namespace, the Workspace has `spec.storage` unset, or a direct-NFS install (no `StorageManager`) has no claim someone provisioned by hand
`InvalidProject`	False	`project` is missing, `project.user` is empty, the workspace, namespace, `project.id` or user is not a valid path segment, or creating the user’s workspace of a hosted project failed
`LivePackConflict`	False	A PromptPack with the live pack’s name exists and is not this source’s
`PackNameConflict`	False	`packName` already has published PromptPack versions

A git or oci source whose packName already has a live PromptPack reports PackNameConflict too, fetches nothing, and checks again at its next interval.

A project source is reconciled again when its spec changes, its live PromptPack is deleted, or its namespace’s Workspace or workspace content PVC changes — so a ContentStorageUnavailable report clears as soon as the claim appears, without polling. It is not re-checked on a timer otherwise.

Example

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: PromptPackSource
metadata:
  name: support-bot-dev
  namespace: dev-agents
spec:
  type: project
  packName: support-bot-dev
  project:
    id: support-bot
    user: 3f9a1c0b7d2e4a65