@a5c-ai/krate 5.0.1-staging.00fa5317c

package/docs/ontology/resource-contracts.md

@@ -0,0 +1,40 @@
+# Resource Contracts
+
+All resources use `apiVersion: krate.a5c.ai/v1alpha1`, `kind`, `metadata`, `spec`, and `status`.
+
+## Common metadata
+
+- `metadata.name` is required.
+- `metadata.namespace` defaults to `default`.
+- `metadata.labels` and `metadata.annotations` default to empty maps.
+- `metadata.resourceVersion` increments on every stored mutation.
+
+## Lifecycle contract
+
+1. Caller submits a resource mutation.
+2. Control plane normalizes metadata and validates kind support.
+3. RBAC checks `user`, verb, kind, and namespace.
+4. Admission policies evaluate in audit or enforce mode.
+5. Resource is routed to etcd or Postgres by storage class.
+6. Audit and watch events are emitted.
+7. Status is patched by controllers or workflow services.
+
+## Kind-specific contracts
+
+- `User`, `Team`, `Invite`, `IdentityMapping`, and `AuthProvider` drive sign-in, admin-managed user mapping, teams, invites, and access configuration.
+- `RepositoryPermission` and `SSHKey` reconcile repository access and key material into the repository backend.
+- `Repository` status includes Gitea backend integration and health.
+- `PullRequest` includes repository, source ref, target ref, title, and phase.
+- `Pipeline` includes repository, ref, steps, trust tier, and resume point.
+- `Job` includes service-account scopes, step name, and isolation metadata.
+- `RunnerPool` includes warm replicas, maximum replicas, and cache policy.
+- `WebhookDelivery` includes request, signature, response, phase, latency, and replay metadata.
+- `RefPolicy` and `BranchProtection` are enforced before protected writes.
+- `View` and `Selector` are label/query definitions used by UI and workflows.
+
+## Validation requirements
+
+- Unsupported kinds fail fast.
+- Missing names fail fast.
+- Selectors match labels deterministically.
+- Storage class is inspectable in status.

package/docs/ontology/resource-taxonomy.md

@@ -0,0 +1,42 @@
+# Resource Taxonomy
+
+## CRD-backed configuration resources
+
+These are low-cardinality desired-state contracts and are safe for etcd-backed storage.
+
+| Kind | Owner | Purpose |
+| --- | --- | --- |
+| `Organization` | Identity/data plane | Workspace organization, owners, teams, and default repository policy |
+| `User` | Identity | Human account profile, sign-in state, and linked identities |
+| `Team` | Identity | Team membership, maintainers, and repository permission grants |
+| `Invite` | Identity | Pending invitation, role, requested teams, and expiry |
+| `IdentityMapping` | Identity | Mapping between sign-in subjects, Kubernetes identities, and repository accounts |
+| `AuthProvider` | Identity | Installation sign-in provider status and delegated identity settings |
+| `Repository` | Data plane | Repository identity, visibility, Gitea hosting integration, object/search settings |
+| `SSHKey` | Identity/data plane | User, deploy, and automation keys reconciled into repository hosting |
+| `RepositoryPermission` | Identity/data plane | Collaborator and team grants synced to repository hosting |
+| `WebhookSubscription` | Hooks/events | Endpoint, event filters, signing configuration, retry policy |
+| `RefPolicy` | Data plane/hooks | Deny refs, force-push policy, signing and linear-history policy |
+| `BranchProtection` | Data plane/control | PR requirement and protected ref rules |
+| `RunnerPool` | Runners/CI | Runner capacity, scale limits, cache configuration |
+| `View` | Web UI | Saved triage view and presentation contract |
+| `Selector` | Web UI/control | Reusable label/query selector for workflows |
+
+## Aggregated Postgres-backed resources
+
+These are high-cardinality runtime records and must not store primary records in etcd.
+
+| Kind | Owner | Purpose |
+| --- | --- | --- |
+| `PullRequest` | Control/UI | Review unit, refs, status, checks, merge lifecycle |
+| `Issue` | Control/UI | Work item, labels, assignment, lifecycle |
+| `Review` | Control/UI | Approval/comment/change-request records |
+| `Pipeline` | Runners/CI | Pipeline run state and resume point |
+| `Job` | Runners/CI | Step execution record and service-account scope |
+| `WebhookDelivery` | Hooks/events | Durable delivery attempt, signature, response, replay chain |
+
+## Taxonomy invariants
+
+- Config resources can drive reconciliation and must remain small.
+- Aggregated resources can be listed, watched, and label-selected through the API server but store primary state outside etcd.
+- Every kind has metadata, spec, status, storage class, owner context, and executable tests.

package/docs/ontology/runners-and-ci.md

@@ -0,0 +1,29 @@
+# Runners and CI
+
+## Runner pools
+
+`RunnerPool` records declare warm replicas, maximum replicas, queue scaling, cache settings, and trust boundaries.
+
+## Pipelines
+
+`Pipeline` records represent a run for repository/ref work. They include steps, status, trust tier, and optional `resumeFrom` state for rerun/resume.
+
+## Jobs
+
+`Job` records represent executable steps. Each job receives a service-account profile derived from the pipeline trust tier.
+
+## Fork isolation
+
+- Fork PR pipelines are untrusted.
+- Untrusted jobs have `secrets: false` and `clusterApi: false`.
+- Trusted jobs may use configured scopes, but scopes remain explicit.
+
+## Scaling
+
+Queue depth maps to desired replicas within warm and max bounds. Scaling is deterministic and inspectable from pool spec/status.
+
+## Acceptance gates
+
+- Starting a fork pipeline produces jobs with no secrets and no cluster API access.
+- Rerun from a named step sets `resumeFrom`.
+- Pool replica planning respects warm and maximum replica limits.

package/docs/ontology/solution-space.md

@@ -0,0 +1,24 @@
+# Solution-Space Ontology
+
+The MVP is a deterministic Kubernetes-native contract implementation of the Krate architecture. Local tests do not require a live cluster, but the modules, chart, examples, Argo CD Application surface, and Gitea backend integration model the cluster contracts described in `docs/`.
+
+## Architectural shape
+
+- `src/resource-model.js` defines resource kinds, storage classes, metadata normalization, selectors, and Kubernetes-list output.
+- `src/control-plane.js` models create/update/status verbs, RBAC, admission, audit, storage boundary routing, and watches.
+- `src/identity-policy.js` maps OIDC identities, groups, trust tiers, service accounts, admission policies, and policy rollout.
+- `src/data-plane.js` and `src/gitea-backend.js` model repository creation, Gitea-backed Git hosting, SSH keys, collaborators/teams, branch protection, ref policy, webhooks, object metadata, and search hooks.
+- `src/runners-ci.js` models runner pools, pipelines, jobs, queue scaling, fork isolation, and rerun/resume.
+- `src/hooks-events.js` models webhook subscriptions, signing, durable deliveries, failure inspection, and replay.
+- `src/web-ui.js` models excellent UI flows as resource-backed view models.
+- `src/operations.js` and `src/argocd-gitops.js` model manifests, Argo CD GitOps Applications, observability, backup/restore, release gates, and the MVP demo.
+
+## MVP boundaries
+
+- In scope: Kubernetes resource contracts, Argo CD Application generation, Gitea API-shaped backend integration, deterministic control-plane behavior, workflow models, tests, docs coverage, and smokeable demo output.
+- Out of scope for local validation: requiring a live APIService deployment, live Argo CD controller, live Gitea server, real Postgres, real etcd, real ARC runners, and real browser rendering.
+- Required fidelity: storage classes, Gitea integration calls, Argo CD Application fields, policy decisions, eventing, and operational gates must behave like the docs even when validated through deterministic JavaScript harnesses.
+
+## Quality strategy
+
+The solution converges through ontology authoring, module implementation, acceptance tests, doc coverage, smoke output, and final quality review.

package/docs/ontology/storage-and-data-boundaries.md

@@ -0,0 +1,29 @@
+# Storage and Data Boundaries
+
+## etcd boundary
+
+etcd stores CRD-backed configuration: `Repository`, `WebhookSubscription`, `RefPolicy`, `BranchProtection`, `RunnerPool`, `View`, and `Selector`. These are low-cardinality desired-state resources.
+
+## Postgres boundary
+
+Postgres stores aggregated records: `PullRequest`, `Issue`, `Review`, `Pipeline`, `Job`, and `WebhookDelivery`. These records can be listed and watched through Kubernetes APIs but their primary storage is not etcd.
+
+## Gitea repository boundary
+
+Gitea stores repositories and terminates smart-HTTP/SSH Git traffic. Repository status points to the Gitea backend integration, protected branch state, deploy keys, collaborators/teams, webhooks, and health, while Krate routing remains stateless.
+
+## Object storage boundary
+
+Object storage contains large immutable objects such as LFS blobs, archives, and artifacts. Repository specs reference object storage configuration without embedding large data.
+
+## Search boundary
+
+Search indexing hooks observe Git and resource events. Search lag must not block Git write success.
+
+## Boundary invariant
+
+No workflow should require copying high-cardinality logs, comments, jobs, or webhook attempts into etcd.
+
+## Deterministic runtime snapshot boundary
+
+The deterministic harness can export and import a KrateRuntimeSnapshot that preserves the control-plane etcd/postgres resource split, audit log, and events. This is the executable backup/restore boundary for the current package contract; production cluster backup still requires the external Postgres, object storage, Gitea repository storage, and declarative resource backup plan described in the operations docs.

package/docs/ontology/validation-matrix.md

@@ -0,0 +1,24 @@
+# Validation Matrix
+
+| Requirement | Ontology | Implementation | Validation |
+| --- | --- | --- | --- |
+| CRD vs aggregated storage | `resource-taxonomy.md`, `storage-and-data-boundaries.md` | `src/resource-model.js`, `src/control-plane.js` | storage tests, `validate-doc-coverage.mjs` |
+| RBAC and admission | `policies-and-invariants.md` | `src/identity-policy.js`, `src/control-plane.js` | RBAC/admission tests |
+| Warm Gitea receive path | `workflows.md`, `storage-and-data-boundaries.md` | `src/data-plane.js` | Gitea backend tests |
+| BranchProtection and RefPolicy | `resource-contracts.md`, `events-and-hooks.md` | `src/data-plane.js` | protected branch/ref tests |
+| Fork CI isolation | `runners-and-ci.md` | `src/runners-ci.js` | runner scheduler tests |
+| Webhook signing/replay | `events-and-hooks.md` | `src/hooks-events.js` | webhook bus tests |
+| UI YAML transparency | `web-ui-excellent-flows.md` | `src/web-ui.js` | smoke assertions |
+| Backup/restore/release gates | `operations-and-release.md` | `src/operations.js`, `scripts/build.mjs`, `scripts/smoke.mjs` | `npm run check` with docs and ontology coverage |
+
+## Local validation commands
+
+- `npm run build`
+- `npm run validate:docs`
+- `npm test`
+- `npm run smoke`
+- `npm run check`
+
+## Green definition
+
+The project is green only when all ontology files exist, coverage terms are found in docs and source, tests pass, smoke assertions pass, and the Babysitter run returns a successful completion proof.

package/docs/ontology/web-ui-excellent-flows.md

@@ -0,0 +1,32 @@
+# Web UI Excellent Flows
+
+The UI ontology is a set of resource-backed view models rather than a hidden application state machine.
+
+## Required flows
+
+- Create and inspect a repository.
+- Open and review a pull request.
+- Inspect failed checks and rerun/resume CI.
+- Edit runner pool capacity and cache policy.
+- Inspect and replay webhook deliveries.
+- Open YAML/resource views for UI actions.
+
+## View model invariants
+
+- Dashboard cards summarize repositories, PRs, pipelines, runner pools, and webhook deliveries.
+- PR review surfaces changed files, pipeline checks, comments, and YAML.
+- Runner pool editor exposes scaling limits and resource YAML.
+- Webhook inspector exposes request, response, phase, signature, and replay action.
+- Every view includes enough resource identity for kubectl-style workflows.
+
+## Traceability
+
+`View` and `Selector` resources support saved triage and cross-repository work. UI filters should map to selector labels or query metadata.
+
+## Current executable UI contract
+
+- Breadcrumbs orient each organization and repository route.
+- `ForgeFlowRail` makes the default Git forge flow explicit: create, clone, branch, open PR, merge, deploy, and notify.
+- `RepositoryCommandBar` keeps clone, branch, watch, RBAC, PR-flow, and YAML actions visible across repository tabs.
+- Degraded-state banners render on every route that depends on the controller model, not only on the dashboard.
+- Architecture boundaries include the API controller, Kubernetes resource gateway, Kubernetes client, Kubernetes reconciler, and Git data plane.

package/docs/ontology/workflows.md

@@ -0,0 +1,39 @@
+# Workflows
+
+## Repository creation
+
+1. Repository admin creates a `Repository` resource.
+2. Control plane authorizes and stores it in etcd.
+3. Data plane provisions a Gitea repository integration and initializes repository storage.
+4. Status exposes Gitea backend integration and health.
+
+## Pull request review
+
+1. Developer creates a `PullRequest` with source/target refs and title.
+2. Admission validates required fields and policy.
+3. CI starts a `Pipeline` and one or more `Job` records.
+4. UI shows checks, changed files, comments, and YAML/resource equivalent.
+5. Branch protection requires PR flow for protected refs.
+
+## Git receive-pack
+
+1. Gitea backend resolves repository routing.
+2. `RefPolicy` denies forbidden refs or unsafe writes.
+3. `BranchProtection` blocks direct protected writes unless actor has repo-admin permission.
+4. Write event is emitted and optional search indexing hook is queued.
+
+## Webhook delivery and replay
+
+1. Repository admin creates a `WebhookSubscription`.
+2. Event dispatch signs payload and stores a `WebhookDelivery` record.
+3. Failure status remains inspectable with request/response metadata.
+4. Replay creates a new delivery using the current secret and links replay metadata.
+
+## Backup and restore
+
+1. Export CRDs and low-cardinality config.
+2. Backup Postgres aggregated records.
+3. Snapshot Gitea repository integration state.
+4. Preserve object storage.
+5. Restore API/config, Postgres, repositories, objects, then controllers.
+6. Validate by listing resources, reading refs, opening a PR, and replaying a webhook.

package/docs/ontology/world.md

@@ -0,0 +1,35 @@
+# World Ontology
+
+Krate is a Kubernetes-native forge: repositories, review, CI, policy, hooks, and operations are expressed through Kubernetes-style resources rather than a separate opaque application model.
+
+## Domain entities
+
+- **Kubernetes API server** is the interaction contract for discovery, verbs, watches, RBAC, admission, and status.
+- **etcd** stores low-cardinality configuration resources such as `Repository`, `WebhookSubscription`, `RefPolicy`, `BranchProtection`, `RunnerPool`, `View`, and `Selector`.
+- **Postgres** stores high-cardinality aggregated records such as `PullRequest`, `Issue`, `Review`, `Pipeline`, `Job`, and `WebhookDelivery`.
+- **Gitea backend** stores repositories and keeps the write path warm for `receive-pack`.
+- **Object storage** stores LFS objects, archives, and large immutable artifacts.
+- **Search index** receives repository indexing hooks without blocking Git writes.
+
+## Human actors
+
+- **Developer** opens pull requests, comments, reviews, runs pipelines, and investigates failures.
+- **Repository admin** creates repositories, branch protection, ref policies, webhook subscriptions, and triage views.
+- **Platform engineer** installs Krate, manages runner pools, admission rollout, observability, backup, and release gates.
+- **Team lead** uses views and selectors to triage cross-repository work.
+
+## Machine actors
+
+- **Controllers** reconcile resource state and patch status.
+- **Runner jobs** execute pipeline steps with scoped service-account identity.
+- **Admission policies** validate mutations in audit or enforce mode.
+- **Webhook dispatchers** sign, deliver, retry, and replay outbound events.
+- **Git clients** use smart HTTP/SSH routes resolved by the Gitea backend integration.
+
+## Non-negotiable assumptions
+
+- Kubernetes RBAC remains authoritative for user and machine actions.
+- UI state must be explainable as resources, YAML, events, and status.
+- High-cardinality activity must not overload etcd.
+- Untrusted fork work must not access secrets or the cluster API.
+- Operations must be installable, observable, backupable, restorable, and release-gated.