@untangle-code/config 0.0.0-stage → 0.1.1

package/schemas/config-v1.json

@@ -0,0 +1,375 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://untangle.dev/schema/config-v1.json",
+  "title": "Untangle Configuration v1",
+  "description": "JSON Schema for .untangle.json / .untangle.local.json (spec.md §4.2-4.8, product.md §11, portfolio.md §14.4). This schema is hand-authored for editor tooling (autocompletion, structural hints); it deliberately does NOT encode the 'unknown top-level field warns instead of failing' rule from spec.md §4.8 -- that rule is enforced by @untangle-code/config's own validator, not by schema validation, so additionalProperties:false here is advisory for tooling only.",
+  "type": "object",
+  "required": ["schemaVersion"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "workspaceId": { "type": "string", "minLength": 1 },
+    "projectId": { "type": "string", "minLength": 1 },
+    "repositories": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/repositoryConfig" }
+    },
+    "storage": { "$ref": "#/$defs/storageConfig" },
+    "qdrant": { "$ref": "#/$defs/qdrantConfig" },
+    "embeddings": { "$ref": "#/$defs/embeddingConfig" },
+    "index": { "$ref": "#/$defs/indexConfig" },
+    "search": { "$ref": "#/$defs/searchConfig" },
+    "graph": { "$ref": "#/$defs/graphConfig" },
+    "complexity": { "$ref": "#/$defs/complexityConfig" },
+    "changes": { "$ref": "#/$defs/changeConfig" },
+    "qualityGate": { "$ref": "#/$defs/qualityGateConfig" },
+    "contextArtifacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/contextArtifactConfig" }
+    },
+    "telemetry": { "$ref": "#/$defs/telemetryConfig" },
+    "portfolio": { "$ref": "#/$defs/portfolioConfig" }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "repositoryConfig": {
+      "type": "object",
+      "description": "spec.md §4.3",
+      "required": ["id", "path"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "minLength": 1 },
+        "label": { "type": "string" },
+        "ref": { "type": "string" },
+        "include": { "type": "array", "items": { "type": "string" } },
+        "exclude": { "type": "array", "items": { "type": "string" } },
+        "packageAliases": { "type": "object", "additionalProperties": { "type": "string" } },
+        "metadata": { "type": "object", "additionalProperties": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "storageConfig": {
+      "type": "object",
+      "description": "Search backend. Defaults to embedded LanceDB unless a legacy qdrant section is explicitly configured. An explicit backend overrides that compatibility default.",
+      "properties": {
+        "backend": { "enum": ["lancedb", "qdrant"], "default": "lancedb" },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Local LanceDB directory, relative to the repository root or absolute; URI schemes and network paths are unsupported.",
+          "default": ".untangle/index/lancedb",
+          "anyOf": [
+            { "pattern": "^[A-Za-z]:[\\\\/][^\\u0000]*$" },
+            { "pattern": "^(?!\\s*$)(?![A-Za-z][A-Za-z0-9+.-]*:)(?![\\\\/]{2})[^\\u0000]+$" }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "qdrantConfig": {
+      "type": "object",
+      "description": "spec.md §4.4",
+      "required": ["mode"],
+      "properties": {
+        "mode": { "enum": ["managed", "external"] },
+        "url": { "type": "string" },
+        "apiKeyEnv": {
+          "type": "string",
+          "description": "Name of an environment variable; never the key itself (architecture.md §23.2)."
+        },
+        "collectionPrefix": { "type": "string" },
+        "requestTimeoutMs": { "type": "integer", "minimum": 1 },
+        "maxRetries": { "type": "integer", "minimum": 0 },
+        "upsertMaxPoints": { "type": "integer", "minimum": 1 },
+        "upsertBudgetBytes": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "embeddingConfig": {
+      "type": "object",
+      "description": "spec.md §4.5",
+      "required": [
+        "provider",
+        "mode",
+        "model",
+        "dimensions",
+        "contextLength",
+        "queryPrefix",
+        "documentPrefix",
+        "includePath",
+        "batchSize",
+        "maxConnections",
+        "requestTimeoutMs"
+      ],
+      "properties": {
+        "provider": { "const": "ollama" },
+        "mode": { "enum": ["auto", "managed", "external"] },
+        "url": { "type": "string" },
+        "apiKeyEnv": {
+          "type": "string",
+          "description": "Name of an environment variable; never the key itself (architecture.md §23.2)."
+        },
+        "model": { "type": "string", "minLength": 1 },
+        "dimensions": { "type": "integer", "minimum": 1 },
+        "contextLength": { "type": "integer", "minimum": 1 },
+        "queryPrefix": { "type": "string" },
+        "documentPrefix": { "type": "string" },
+        "includePath": { "type": "boolean" },
+        "batchSize": { "type": "integer", "minimum": 1 },
+        "maxConnections": { "type": "integer", "minimum": 1 },
+        "requestTimeoutMs": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "indexConfig": {
+      "type": "object",
+      "description": "spec.md §4.6",
+      "properties": {
+        "watch": { "type": "boolean" },
+        "reconcileIntervalMinutes": { "type": "number", "minimum": 0 },
+        "maxFileSizeMb": { "type": "number", "minimum": 0 },
+        "maxGraphFileSizeMb": { "type": "number", "minimum": 0 },
+        "scanConcurrency": { "type": "integer", "minimum": 1 },
+        "embeddingConcurrency": { "type": "integer", "minimum": 1 },
+        "filesPerCheckpoint": { "type": "integer", "minimum": 1 },
+        "targetChunkTokens": { "type": "integer", "minimum": 1 },
+        "maxChunkTokens": { "type": "integer", "minimum": 1 },
+        "fallbackOverlapTokens": { "type": "integer", "minimum": 0 },
+        "includeDotFiles": { "type": "boolean" },
+        "indexExtensionless": { "type": "boolean" },
+        "extraExtensions": { "type": "array", "items": { "type": "string" } },
+        "extensionLanguageMap": { "type": "object", "additionalProperties": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "searchConfig": {
+      "type": "object",
+      "description": "Untangle decision: spec.md §13 names no SearchConfig shape.",
+      "properties": {
+        "defaultLimit": { "type": "integer", "minimum": 1 },
+        "defaultCandidateLimit": { "type": "integer", "minimum": 1 },
+        "maxCandidateLimit": { "type": "integer", "minimum": 1 },
+        "diversifyByDefault": { "type": "boolean" },
+        "minScoreDefault": { "type": "number" },
+        "relevancePolicies": {
+          "type": "object",
+          "description": "Calibrated absence decisions keyed by the exact embedding profile id and additionally bound to one workspace and collection.",
+          "propertyNames": { "type": "string", "minLength": 1 },
+          "additionalProperties": { "$ref": "#/$defs/searchRelevancePolicyBinding" }
+        },
+        "boostWeights": {
+          "type": "object",
+          "properties": {
+            "exactSymbol": { "type": "number" },
+            "exactPath": { "type": "number" },
+            "repoPriority": { "type": "number" },
+            "graphProximity": { "type": "number" },
+            "recency": { "type": "number" },
+            "duplicatePenalty": { "type": "number" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "searchRelevancePolicyBinding": {
+      "type": "object",
+      "required": ["workspaceId", "collection", "policy"],
+      "properties": {
+        "workspaceId": { "type": "string", "minLength": 1 },
+        "collection": { "type": "string", "minLength": 1 },
+        "policy": { "$ref": "#/$defs/searchRelevancePolicy" }
+      },
+      "additionalProperties": false
+    },
+    "searchRelevancePolicy": {
+      "type": "object",
+      "required": [
+        "calibrationId",
+        "minimumDenseScore",
+        "minimumDenseSpread",
+        "denseReferenceRank",
+        "minimumCandidateIdfCoverage"
+      ],
+      "properties": {
+        "calibrationId": { "type": "string", "minLength": 1 },
+        "minimumDenseScore": { "type": "number", "minimum": -1, "maximum": 1 },
+        "minimumDenseSpread": { "type": "number", "minimum": 0, "maximum": 2 },
+        "denseReferenceRank": { "type": "integer", "minimum": 2 },
+        "minimumCandidateIdfCoverage": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "graphConfig": {
+      "type": "object",
+      "description": "Untangle decision, values anchored on architecture.md §17.4 traversal limits.",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "maxTraversalDepth": { "type": "integer", "minimum": 1 },
+        "maxTraversalNodes": { "type": "integer", "minimum": 1 },
+        "maxTraversalEdges": { "type": "integer", "minimum": 1 },
+        "maxTraversalWallTimeMs": { "type": "integer", "minimum": 1 },
+        "includeDynamicImports": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "complexityConfig": {
+      "type": "object",
+      "description": "Untangle decision; product.md §11 example anchors 'enabled'/'cognitiveAlgorithm'.",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "cognitiveAlgorithm": { "type": "string" },
+        "cyclomaticVariant": { "enum": ["classic", "extended", "both"] },
+        "maintainabilityIndexEnabled": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "changeConfig": {
+      "type": "object",
+      "description": "Untangle decision; weight defaults from spec.md §17.6.",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "riskWeights": {
+          "type": "object",
+          "properties": {
+            "churn": { "type": "number" },
+            "positiveCognitiveDelta": { "type": "number" },
+            "positiveCyclomaticDelta": { "type": "number" },
+            "blastRadius": { "type": "number" },
+            "graphCentrality": { "type": "number" },
+            "semanticChange": { "type": "number" },
+            "testDistance": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        "symbolMatching": {
+          "type": "object",
+          "properties": {
+            "tokenSimilarityMin": { "type": "number", "minimum": 0, "maximum": 1 },
+            "enableEmbeddingSimilarity": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "qualityGateConfig": {
+      "type": "object",
+      "description": "spec.md §4.7",
+      "required": ["mode", "newCyclesAllowed", "minimumParseQuality", "ignoreExistingViolations"],
+      "properties": {
+        "mode": { "enum": ["off", "warn", "fail"] },
+        "newCyclesAllowed": { "type": "integer", "minimum": 0 },
+        "cognitivePerSymbolMax": { "type": "number" },
+        "cognitiveDeltaPerSymbolMax": { "type": "number" },
+        "cyclomaticPerSymbolMax": { "type": "number" },
+        "cyclomaticDeltaPerSymbolMax": { "type": "number" },
+        "maxNestingPerSymbolMax": { "type": "number" },
+        "maintainabilityIndexMin": { "type": "number" },
+        "riskScoreMax": { "type": "number" },
+        "minimumParseQuality": { "enum": ["failed", "partial", "complete"] },
+        "ignoreExistingViolations": { "type": "boolean" },
+        "include": { "type": "array", "items": { "type": "string" } },
+        "exclude": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "contextArtifactConfig": {
+      "type": "object",
+      "description": "spec.md §19.1-19.2",
+      "required": ["name", "path", "description"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "type": {
+          "enum": [
+            "auto",
+            "sql",
+            "openapi",
+            "asyncapi",
+            "protobuf",
+            "markdown",
+            "terraform",
+            "kubernetes",
+            "text"
+          ]
+        },
+        "include": { "type": "array", "items": { "type": "string" } },
+        "exclude": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "telemetryConfig": {
+      "type": "object",
+      "description": "spec.md §24: telemetry MUST default to off.",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "logLevel": { "enum": ["error", "warn", "info", "debug", "trace"] },
+        "metricsExport": { "enum": ["none", "prometheus"] }
+      },
+      "additionalProperties": false
+    },
+    "portfolioConfig": {
+      "type": "object",
+      "description": "portfolio.md §14.4 (normative shape)",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "includeTransitive": { "type": "boolean" },
+        "conventionMinRepos": { "type": "integer", "minimum": 0 },
+        "conventions": {
+          "type": "object",
+          "properties": {
+            "pinned": { "type": "array", "items": { "type": "string" } },
+            "suppressed": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": false
+        },
+        "radar": {
+          "type": "object",
+          "properties": {
+            "adoptShareMin": { "type": "number", "minimum": 0, "maximum": 1 },
+            "maintainShareMin": { "type": "number", "minimum": 0, "maximum": 1 },
+            "retireAfterDays": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "blueprint": {
+          "type": "object",
+          "properties": {
+            "weights": {
+              "type": "object",
+              "description": "MUST sum to 1.0 (±0.001) -- portfolio.md §14.4.",
+              "properties": {
+                "adoption": { "type": "number" },
+                "recency": { "type": "number" },
+                "health": { "type": "number" },
+                "versionConsistency": { "type": "number" }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "enrichment": { "$ref": "#/$defs/portfolioEnrichmentConfig" }
+      },
+      "additionalProperties": false
+    },
+    "portfolioEnrichmentConfig": {
+      "type": "object",
+      "description": "portfolio.md §13. Default fully disabled.",
+      "required": ["enabled", "registries", "cacheTtlHours", "timeoutMs"],
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "registries": {
+          "type": "array",
+          "items": { "enum": ["npm", "pypi", "crates", "maven", "nuget", "go", "composer"] }
+        },
+        "registryUrls": { "type": "object", "additionalProperties": { "type": "string" } },
+        "cacheTtlHours": { "type": "number", "minimum": 0 },
+        "timeoutMs": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/chunker-budget.ts

@@ -0,0 +1,63 @@
+/**
+ * Chunk-token budget wiring: `IndexConfig` (spec.md §4.6) →
+ * `@untangle-code/chunker`'s `ChunkerConfigInput.maxTokensPerChunk`.
+ *
+ * spec.md §4.6 defines TWO index-level chunk-size knobs —
+ * `targetChunkTokens` (a soft aim) and `maxChunkTokens` (a hard ceiling) —
+ * with their product defaults (900 / 1500) fixed exactly once, in this
+ * package's `defaults.ts` (`DEFAULT_INDEX_CONFIG`). That is the single
+ * source of truth this file wires onward.
+ *
+ * `@untangle-code/chunker` currently exposes exactly ONE budget knob,
+ * `ChunkerConfigInput.maxTokensPerChunk`, and treats it everywhere as a hard
+ * "must not exceed" ceiling (every comparison in chunker's `split.ts` and
+ * `line-fallback-strategy.ts` is `<=`). The correct mapping is therefore
+ * `maxChunkTokens → maxTokensPerChunk`. `targetChunkTokens` has no
+ * chunker-side counterpart today — the chunker does not currently support
+ * aiming below its hard ceiling — and is deliberately NOT passed here;
+ * smuggling it in as `maxTokensPerChunk` instead would silently turn a soft
+ * aim into the hard ceiling the chunker actually enforces, which is a
+ * different (smaller) budget than spec.md §4.6 configures.
+ *
+ * `@untangle-code/config` deliberately does NOT take a runtime dependency on
+ * `@untangle-code/chunker` for this: config sits below chunker in the
+ * dependency graph (chunker already depends on domain; depending on chunker
+ * from here would invert that layering for the sake of one field mapping),
+ * and chunker is maintained independently of this package. `deriveChunkerBudget`
+ * therefore returns a plain object structurally compatible with
+ * `ChunkerConfigInput` (verified in `chunker-budget.test.ts` against the
+ * fields spec.md and the chunker README actually document) rather than
+ * importing its type.
+ *
+ * Whatever code builds the indexer (constructing `ChunkerConfigInput` to
+ * pass to `@untangle-code/chunker`'s `resolveChunkerConfig`/`chunkFile`) MUST
+ * spread this function's result into that input — e.g.
+ * `resolveChunkerConfig({ ...deriveChunkerBudget(effectiveConfig.index), preparedText })`
+ * — rather than reading `index.maxChunkTokens` directly or (worse) relying
+ * on the chunker's own independent default. That is the one piece of wiring
+ * this fix cannot complete by itself: no indexer package exists in this
+ * repository yet to receive it (see this package's `package.json`
+ * `dependencies`, and `packages/`'s directory listing) — but every future
+ * caller now has exactly one function to call instead of a field name to
+ * remember, which is what keeps a changed config value from silently
+ * failing to reach the chunker.
+ */
+import type { IndexConfig } from "./types.js";
+
+/** Structurally assignable to `@untangle-code/chunker`'s `ChunkerConfigInput` — see file doc comment. */
+export interface ChunkerBudgetInput {
+  maxTokensPerChunk: number;
+}
+
+/**
+ * Derives the chunker's token-budget input from the effective `IndexConfig`
+ * (spec.md §4.6). This is the ONLY function in the codebase permitted to
+ * decide which `IndexConfig` field feeds
+ * `ChunkerConfigInput.maxTokensPerChunk` — see file doc comment for why it
+ * is `maxChunkTokens`, not `targetChunkTokens`.
+ */
+export function deriveChunkerBudget(
+  index: Pick<IndexConfig, "maxChunkTokens">,
+): ChunkerBudgetInput {
+  return { maxTokensPerChunk: index.maxChunkTokens };
+}

package/src/defaults.ts

@@ -0,0 +1,207 @@
+/**
+ * Product defaults (spec.md §4.5 "Defaultprofil für MVP"; product.md §11).
+ *
+ * These are layer 6 (lowest priority) of spec.md §4.1's six-level layering.
+ * Every field an `EffectiveUntangleConfigV1` guarantees present is defaulted
+ * here.
+ */
+import { COGNITIVE_ALGORITHM_ID } from "@untangle-code/domain";
+
+import type {
+  ChangeConfig,
+  ComplexityConfig,
+  EmbeddingConfig,
+  GraphConfig,
+  IndexConfig,
+  PortfolioConfig,
+  QdrantConfig,
+  QualityGateConfig,
+  RawConfigLayer,
+  SearchConfig,
+  StorageConfig,
+  TelemetryConfig,
+} from "./types.js";
+
+/**
+ * Embedding profile fields that are NOT part of `EmbeddingConfig` (spec.md
+ * §4.5 lists exactly ten fields, none of them `normalization` or
+ * `preparedTextVersion`) but ARE required inputs to
+ * `buildEmbeddingProfileId` (spec.md §5.7). Untangle decision: default
+ * normalization to "none" (no vector post-processing) and mint an explicit
+ * prepared-text format version so a future change to how document text is
+ * assembled can roll `embedding_profile_id` forward deliberately.
+ */
+export const DEFAULT_EMBEDDING_NORMALIZATION = "none" as const;
+export const PREPARED_TEXT_VERSION = "untangle-prepared-text-v1" as const;
+
+/** spec.md §4.5 "Defaultprofil für MVP" — Ollama, nomic-embed-text, 768 dims. */
+export const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfig = {
+  provider: "ollama",
+  mode: "auto",
+  model: "nomic-embed-text",
+  dimensions: 768,
+  contextLength: 2048,
+  queryPrefix: "search_query: ",
+  documentPrefix: "search_document: ",
+  includePath: true,
+  batchSize: 32,
+  maxConnections: 4,
+  requestTimeoutMs: 120000,
+};
+
+/**
+ * Qdrant defaults. spec.md §4.4 defines the shape but not default values;
+ * `managed` mode with no explicit `url` matches product.md §4.1's
+ * zero-config narrative (the CLI starts a managed container and fills `url`
+ * in from that at runtime — this package only supplies the mode default).
+ */
+export const DEFAULT_QDRANT_CONFIG: QdrantConfig = {
+  mode: "managed",
+  collectionPrefix: "untangle_",
+  requestTimeoutMs: 30000,
+  maxRetries: 3,
+  upsertMaxPoints: 256,
+  upsertBudgetBytes: 4 * 1024 * 1024,
+};
+
+/** Embedded search for new projects; explicit legacy Qdrant layers retain their backend. */
+export const DEFAULT_STORAGE_CONFIG: StorageConfig = {
+  backend: "lancedb",
+  path: ".untangle/index/lancedb",
+};
+
+/** spec.md §4.6; numeric defaults are an Untangle decision, chosen conservatively. */
+export const DEFAULT_INDEX_CONFIG: IndexConfig = {
+  watch: true,
+  reconcileIntervalMinutes: 30,
+  maxFileSizeMb: 5,
+  maxGraphFileSizeMb: 20,
+  scanConcurrency: 8,
+  embeddingConcurrency: 4,
+  filesPerCheckpoint: 200,
+  targetChunkTokens: 900,
+  maxChunkTokens: 1500,
+  fallbackOverlapTokens: 100,
+  includeDotFiles: false,
+  indexExtensionless: false,
+  extraExtensions: [],
+  extensionLanguageMap: {},
+};
+
+/** Untangle decision (see `types.ts` `SearchConfig` doc comment). */
+export const DEFAULT_SEARCH_CONFIG: SearchConfig = {
+  defaultLimit: 10,
+  defaultCandidateLimit: 50,
+  maxCandidateLimit: 200,
+  diversifyByDefault: false,
+  boostWeights: {
+    exactSymbol: 0.15,
+    exactPath: 0.1,
+    repoPriority: 0.05,
+    graphProximity: 0.1,
+    recency: 0.05,
+    duplicatePenalty: 0.2,
+  },
+};
+
+/** Untangle decision, values taken from architecture.md §17.4's per-query limits. */
+export const DEFAULT_GRAPH_CONFIG: GraphConfig = {
+  enabled: true,
+  maxTraversalDepth: 20,
+  maxTraversalNodes: 2000,
+  maxTraversalEdges: 4000,
+  maxTraversalWallTimeMs: 5000,
+  includeDynamicImports: true,
+};
+
+/** Untangle decision (see `types.ts` `ComplexityConfig` doc comment). */
+export const DEFAULT_COMPLEXITY_CONFIG: ComplexityConfig = {
+  enabled: true,
+  cognitiveAlgorithm: COGNITIVE_ALGORITHM_ID,
+  cyclomaticVariant: "both",
+  maintainabilityIndexEnabled: true,
+};
+
+/** spec.md §17.6 default risk score weights. */
+export const DEFAULT_CHANGE_CONFIG: ChangeConfig = {
+  enabled: true,
+  riskWeights: {
+    churn: 0.25,
+    positiveCognitiveDelta: 0.2,
+    positiveCyclomaticDelta: 0.15,
+    blastRadius: 0.15,
+    graphCentrality: 0.1,
+    semanticChange: 0.1,
+    testDistance: 0.05,
+  },
+  symbolMatching: {
+    tokenSimilarityMin: 0.6,
+    enableEmbeddingSimilarity: true,
+  },
+};
+
+/** spec.md §4.7 shape; MVP defaults chosen deliberately permissive (warn, not fail). */
+export const DEFAULT_QUALITY_GATE_CONFIG: QualityGateConfig = {
+  mode: "warn",
+  newCyclesAllowed: 0,
+  minimumParseQuality: "partial",
+  ignoreExistingViolations: true,
+};
+
+/** spec.md §24: "Telemetrie MUSS standardmäßig aus sein." */
+export const DEFAULT_TELEMETRY_CONFIG: TelemetryConfig = {
+  enabled: false,
+  logLevel: "info",
+  metricsExport: "none",
+};
+
+/** portfolio.md §14.4 defaults, spelled out explicitly. */
+export const DEFAULT_PORTFOLIO_CONFIG: PortfolioConfig = {
+  enabled: true,
+  includeTransitive: false,
+  conventionMinRepos: 2,
+  radar: {
+    adoptShareMin: 0.5,
+    maintainShareMin: 0.2,
+    retireAfterDays: 540,
+  },
+  blueprint: {
+    weights: {
+      adoption: 0.4,
+      recency: 0.2,
+      health: 0.25,
+      versionConsistency: 0.15,
+    },
+  },
+  enrichment: {
+    enabled: false,
+    registries: [],
+    cacheTtlHours: 168,
+    timeoutMs: 10000,
+  },
+};
+
+/** Current config schema version this package produces and validates against. */
+export const CURRENT_SCHEMA_VERSION = 1 as const;
+
+/**
+ * The complete product-default layer (spec.md §4.1 layer 6, lowest
+ * priority). Every optional sub-config `EffectiveUntangleConfigV1`
+ * guarantees present is defaulted here; `repositories` and
+ * `contextArtifacts` are deliberately absent (spec.md §4.3: no universal
+ * default repository set exists).
+ */
+export const PRODUCT_DEFAULT_CONFIG: RawConfigLayer = {
+  schemaVersion: CURRENT_SCHEMA_VERSION,
+  storage: DEFAULT_STORAGE_CONFIG,
+  qdrant: DEFAULT_QDRANT_CONFIG,
+  embeddings: DEFAULT_EMBEDDING_CONFIG,
+  index: DEFAULT_INDEX_CONFIG,
+  search: DEFAULT_SEARCH_CONFIG,
+  graph: DEFAULT_GRAPH_CONFIG,
+  complexity: DEFAULT_COMPLEXITY_CONFIG,
+  changes: DEFAULT_CHANGE_CONFIG,
+  qualityGate: DEFAULT_QUALITY_GATE_CONFIG,
+  telemetry: DEFAULT_TELEMETRY_CONFIG,
+  portfolio: DEFAULT_PORTFOLIO_CONFIG,
+};