# Deployment Artifact Schema

Date: 2026-03-29

## Purpose

This document defines the machine-readable deployment artifacts that can be regenerated from the current KB plus `app-delivery`.

It exists so downstream tooling can rely on stable field names instead of parsing markdown conclusions.

## Inputs

- `knowledge/deployment/app-delivery-object-mapping.json`
- `knowledge/deployment/deployment-manifest-graph.json`
- `knowledge/deployment/deployment-environment-graph.json`
- `app-delivery/**/app-registry/*.yaml`
- `knowledge/repos/*/meta.json`
- `knowledge/meta/repos-private.json`
- `knowledge/meta/repos-public.json`
- `.local/review-history/repos-filtered.txt`

## Regenerated Outputs

### `knowledge/deployment/app-delivery-object-mapping.json`

Added normalized fields:

- `summary`
- `objects[].mapping_id`
- `objects[].evidence[]`

`objects[].evidence[]` shape:

```json
{
  "type": "app_registry_object|kb_repo_meta|repo_catalog_entry|bundle_internal_applicationset|bundle_internal_workload|manifest_runtime_reference|source_build_definition|source_release_workflow|deployment_bundle_manifest|infra_stack_definition|externalname_proxy|bundle_runtime_note",
  "file": "relative/path",
  "line": 12,
  "detail": "short explanation"
}
```

### `knowledge/deployment/deployment-manifest-graph.json`

Added normalized fields:

- `summary.edge_id_count`
- `summary.edges_with_evidence_locations`
- `dependency_edges[].edge_id`
- `dependency_edges[].derivation_rule`
- `dependency_edges[].evidence_files[]`
- `dependency_edges[].evidence_locations[]`

`dependency_edges[].evidence_locations[]` shape:

```json
{
  "file": "app-delivery/...",
  "line": 37,
  "environment": "prod"
}
```

### `knowledge/deployment/deployment-environment-graph.json`

Purpose:

- keep the original top-level `ApplicationSet` placement projection stable
- exclude plain ArgoCD `Application` bundle aggregators from placement counts
- preserve top-level env-to-cluster coverage as a compact view

Added or normalized fields:

- `graph_version`
- `summary`
- `top_clusters_by_placement`

### `knowledge/deployment/deployment-graph.json`

Purpose:

- keep the high-level topology graph reproducible from code
- separate curated rollout-order anchors from lower-level manifest evidence

Top-level shape:

```json
{
  "date": "2026-03-29",
  "graph_version": "0.2",
  "scope": "high_level_deployment_topology",
  "summary": {},
  "nodes": [],
  "mapping_edges": [],
  "dependency_edges": []
}
```

`nodes[]` shape:

```json
{
  "id": "obj:account-svc",
  "kind": "deployment_object|source_repo",
  "label": "account-svc"
}
```

### `knowledge/deployment/deployment-object-environment-matrix.json`

Purpose:

- normalize placement data into `object x environment x cluster x namespace`
- keep bundle context explicit
- expose top-level ownership on every placement

Top-level shape:

```json
{
  "date": "2026-03-29",
  "generator": "construction/generate-deployment-derived-artifacts.py",
  "summary": {},
  "records": []
}
```

`records[]` shape:

```json
{
  "placement_id": "placement:...",
  "scope": "root|dev|staging",
  "bundle": "clinic",
  "top_level_object": "clinic",
  "registry_object": "clinic-api",
  "applicationset_name": "clinic-api",
  "registry_file": "app-delivery/clinic/app-registry/clinic-api.yaml",
  "environment": "prod-cloud",
  "cluster": "prod-clinic-cloud",
  "namespace": "clinic-prod-cloud",
  "source_path": "clinic/clinic-api/envs/prod-cloud",
  "mapping": {
    "top_level_deployment_object": "clinic",
    "mapping_type": "deployment_bundle",
    "source_repo": null,
    "source_family": "tidbcloud/clinic-cd multi-application delivery family",
    "confidence": "medium-high",
    "component_mapping_available": false
  }
}
```

### `knowledge/deployment/deployment-bundle-decomposition.json`

Purpose:

- decompose bundle-style delivery units into internal applications
- keep per-component scope, environment, cluster, and source path coverage

`bundles[]` shape:

```json
{
  "bundle": "clinic",
  "mapping": {
    "mapping_type": "deployment_bundle",
    "source_repo": null,
    "source_family": "tidbcloud/clinic-cd multi-application delivery family",
    "confidence": "medium-high"
  },
  "component_count": 15,
  "placement_count": 27,
  "scopes": ["root", "dev", "staging"],
  "components": []
}
```

### `knowledge/deployment/deployment-validation-report.json`

Purpose:

- encode consistency checks as machine-readable results
- separate hard failures from expected warnings

`checks[]` shape:

```json
{
  "name": "top_level_registry_objects_have_mapping",
  "status": "pass|warn|fail",
  "details": {}
}
```

## Stability Rules

- `mapping_id` and `edge_id` must be deterministic slugs.
- Paths are stored relative to the KB root or as `app-delivery/...`.
- `warn` means the gap is known and explainable.
- `fail` means regeneration found a contradiction that should block trust in the artifact set.