# Deployment Artifact Query Guide Date: 2026-03-29 ## Purpose This guide explains what the current machine-readable deployment artifacts can answer directly. Use it when you already know the artifact set exists, but you want a fast "which file answers which question" map. ## 1. Ownership Questions Use: - `knowledge/deployment/app-delivery-object-mapping.json` - `knowledge/deployment/app-delivery-object-mapping.md` Questions answered: - Which source repo owns a deployment object such as `account-svc` or `config-service` - Which objects only resolve to a source family or delivery bundle such as `clinic` - What confidence level the current ownership conclusion has - Which files and lines justify the ownership mapping ## 2. Placement Questions Use: - `knowledge/deployment/deployment-object-environment-matrix.json` - `knowledge/deployment/deployment-environment-graph.json` Questions answered: - Which environments, clusters, and namespaces a deployment object reaches - Which top-level `ApplicationSet` files expand into which placements - Which bundle-owned internal components inherit a top-level owner mapping - Which clusters receive the most placements Practical difference: - `deployment-environment-graph.json` is the compact top-level `ApplicationSet` view - `deployment-object-environment-matrix.json` is the expanded `object x environment x cluster x namespace` view ## 3. Bundle Decomposition Questions Use: - `knowledge/deployment/deployment-bundle-decomposition.json` Questions answered: - Which internal applications sit inside a bundle such as `clinic` or `nextgen-regional-control-plane` - Which scopes, environments, clusters, and namespaces each internal component reaches - Whether a bundle component also has a direct top-level mapping in the KB - Which bundles are largest by internal component footprint ## 4. Dependency Questions Use: - `knowledge/deployment/deployment-manifest-graph.json` - `knowledge/deployment/deployment-graph.json` Questions answered: - Which deployment objects directly reference other deployment objects in manifests or configs - Whether the dependency is evidenced by service DNS, `kubernetes:///...`, HTTP URLs, CRDs, secret-store references, or normalized public endpoints - Which file and line prove the dependency - What the high-level rollout-order anchors look like after abstraction Practical difference: - `deployment-manifest-graph.json` is the low-level evidence graph - `deployment-graph.json` is the curated high-level topology graph ## 5. Validation And Trust Questions Use: - `knowledge/deployment/deployment-validation-report.json` Questions answered: - Whether top-level registry objects all have mappings - Whether manifest edges only reference known deployment objects - Whether filtered repos leaked into generated outputs - Whether generated IDs are unique - Whether bundle decomposition and top-level placement projections are internally consistent ## 6. Workflow And Regeneration Questions Use: - `construction/generate-deployment-derived-artifacts.py` - `construction/deployment-artifact-schema.md` - `construction/deployment-artifact-generation-plan.md` - `construction/deployment-artifact-validation-checklist.md` Questions answered: - How to regenerate the derived deployment artifacts - Which files are treated as source inputs versus rewritten outputs - What each machine-readable field means - Which checks should pass before trusting regenerated results ## 7. Public Entrypoint Questions Use: - `knowledge/deployment/public-entrypoint-catalog.json` - `knowledge/deployment/public-entrypoint-scan.md` Questions answered: - Which deployment objects expose ingress, gateway, HTTPRoute, GRPCRoute, or externally reachable load balancers - Which hosts, paths, backend services, and namespaces are visible from deployment manifests - Which public-looking entrypoints map back to which source owners and repo interface artifacts - Which exposures are explicit public DNS, shared-gateway paths, internal load balancers, or unresolved service-only surfaces Practical difference: - `public-entrypoint-catalog.json` is the raw machine-readable deployment-side exposure inventory - `public-entrypoint-scan.md` is the shorter summary and first-pass interpretation ## 8. Public Service Questions Use: - `knowledge/deployment/public-service-catalog.json` - `knowledge/deployment/public-service-catalog.md` Questions answered: - Which deployment objects are the strongest current candidates for user-facing or externally reachable services - Which audience bucket each candidate most likely belongs to, such as regional API, tenant data API, observability, operator API, or preview web - Which services have confirmed external hosts versus only shared-gateway paths or unresolved deployment exposure - Which interface artifacts should be opened next to inspect the API surface for a public service candidate Practical difference: - `public-service-catalog.json` is the condensed machine-readable public-service directory - `public-service-catalog.md` is the short human-readable summary ## What The Current Artifact Set Still Does Not Fully Answer Not fully solved yet: - complete runtime call graphs for every service and bundle - automatic end-to-end impact analysis from source repo change to rollout target - exact source-repo decomposition for every internal bundle component - exhaustive manifest-level dependency coverage across all addons and observability packages - exact route-to-interface matching for every public service candidate - full shared-gateway host ownership resolution for every externally reachable path