Enforce parity between Knowledge YAML defaults and Config Server property events

Problem

light-knowledge has two representations of its product defaults:

1. the embedded placeholder defaults in apps/light-knowledge/config/knowledge.yml and worker.yml; and
2. the Config Server config_t / config_property_t catalog populated through Portal events.

These representations can drift in property names, value types, default values, and descriptions. Drift makes it unclear which value is the supported product default and forces operators to discover mismatches only after creating an instance snapshot.

The current contract has:

• 42 knowledge.yml leaves: 41 configurable properties plus fixed schema version: 1;
• 36 worker.yml leaves: 35 configurable properties plus fixed schema version: 1.

The fixed schema versions are intentionally not Config Server properties.

Proposed direction

Treat the light-fabric YAML placeholder defaults as the canonical, reviewable product defaults. Generate Config Server property events from those templates, or validate committed events/catalog manifests against them, so drift fails before release.

Deployment-, environment-, and instance-specific values remain overrides in Config Server snapshots and must not change the canonical product defaults.

Scope

• Flatten the configurable leaves in:
  • apps/light-knowledge/config/knowledge.yml under knowledge.*;
  • apps/light-knowledge/config/worker.yml under knowledgeWorker.*.
• Require each configurable leaf to use a whole-value ${key:default} placeholder.
• Maintain an explicit allowlist for non-configurable structural fields, currently only version.
• Derive or validate each property's:
  • fully qualified name;
  • Config Server value type;
  • typed default value;
  • active state;
  • description/example metadata.
• Generate import-ready Config Server property events, or compare the templates with the committed event-generation manifest used to produce them.
• Validate the corresponding product-version/config-property mappings when event generation is selected.
• Add an offline CI gate that reports missing, extra, type-mismatched, and default-mismatched properties.
• Document how canonical defaults differ from deployment overrides and where expected formats belong.

Acceptance criteria

• CI compares all 41 knowledge and 35 knowledgeWorker configurable properties.
• CI fails for a missing or extra property on either side.
• CI fails when a placeholder key, value type, or typed default differs from the Config Server event/catalog representation.
• version: 1 remains fixed in each YAML template and absent from Config Server properties.
• Event generation uses UUIDv7 identifiers, valid aggregate versions/nonces, and the normal Portal event-import path.
• Property descriptions carry expected formats/examples instead of using misleading example values as defaults.
• The gate is deterministic and does not require a mutable live Config Server database.
• Tests cover boolean, integer, string, null, nested keys, and defaults containing URLs/colons.
• Contributor documentation explains how to add, rename, remove, or change a Knowledge property without introducing drift.

Validation evidence expected

• parity gate passes against the committed Knowledge templates and event/catalog manifest;
• a fixture with one missing property fails;
• fixtures with type and default mismatches fail with actionable diagnostics;
• generated events pass the existing event-generation validation and database-collision checks before import.

Start with apps/light-knowledge/config/knowledge.yml and worker.yml, then trace the committed event-generation manifest and existing event-import validation. Run the current validation path and inspect how nested placeholders, types, defaults, and metadata are represented. Done means a deterministic offline parity gate covers all 41 and 35 properties, fixtures report actionable mismatches, and documentation explains safe property changes.