Spec — koder.toml top-level category field

Normative schema for the top-level category field in every koder.toml. Drives the obligation rule for the [self_hosted] block (policies/self-hosted-first.kmd § Anti-drift heuristic) and the per-category audit selection in policies/reuse-first.kmd sub-policies.

1. Where the field lives

Top-level scalar in koder.toml, alongside [package], [app], [backlog], etc.:

# koder.toml
category = "engine"

[package]
name        = "koder-lang"
version     = "7.28.0"
…

[backlog]
prefix = "LANG"

[self_hosted]
…

The field is declarative: it does not affect build behaviour. Tooling that consumes koder.toml (koder-spec-audit, khub, kicon, etc.) reads it to decide which audits and rules apply.

2. Schema

The field is at the top level of the TOML document, not inside any table.

3. Enum values

Six canonical buckets. New buckets require an RFC amendment.

Edge cases. A module with both engine and product surfaces (e.g. engines/sdk/koder_kit ships a Flutter framework + a developer-facing CLI) declares category for the dominant consumer pathway. The other surface gains a child koder.toml if the path layout already supports sub-modules.

4. Obligation rule for [self_hosted]

When category ∈ {engine, infra-tooling} AND the module has a non-Koder external alternative that products of the Stack might otherwise reach for, the [self_hosted] block defined in policies/self-hosted-first.kmd is mandatory.

Decision tree:

category = engine | infra-tooling ?
├── no  → [self_hosted] is optional (declare anyway if module has an external counterpart)
└── yes → does an external alternative exist that products would otherwise use?
         ├── no  → [self_hosted] is optional (no decision to govern)
         └── yes → [self_hosted] is REQUIRED with at minimum:
                   • replaces (non-empty list)
                   • status (enum)
                   • gates_passed and gates_pending (may be empty arrays)

koder-spec-audit self-hosted --validate <module> enforces this in Phase 5. In Phase 4 (where this spec lands), the rule is advisory — the audit warns but does not fail.

5. Mandatoriness timeline

Backwards-compatible: existing koder.toml files without category continue to work; the audit warns but does not block.

6. Sticky retrofit policy

When a koder.toml is touched for any reason during Phase 4, the toucher SHOULD add the category field if it's missing. By Phase 5 the field is required, so opportunistic adoption smooths the transition.

7. Examples

Engine with self-hosted block

category = "engine"

[package]
name = "koder-lang"
version = "7.28.0"

[backlog]
prefix = "LANG"

[self_hosted]
replaces      = ["rust", "go", "c", "c++"]
status        = "stable"
gates_passed  = ["feature_parity:hot_path_lib", "performance:hot_path", "production_proven:kodec"]
gates_pending = ["capability:c_linking", "capability:async_runtime", "production_proven:beyond_kodec"]

Infra-tooling without external alternative

category = "infra-tooling"

[app]
slug = "koder-lock"

[backlog]
prefix = "LOCK"

# No [self_hosted] block — the tool is Koder-internal,
# no external counterpart to govern.

Product (no obligation; declared anyway for clarity)

category = "product"

[app]
slug = "kterm"
name = "Koder Term"
version = "1.3.2"

[backlog]
prefix = "KTERM"

# No [self_hosted] block — kterm IS the product, not a tech-stack
# decision being weighed against an external alternative.

8. Anti-patterns

• Declaring category and never updating when the module's role changes. An audit pass on rename/move events is recommended.
• Using category to encode multiple concerns (e.g. category = "engine-runtime-lib"). The enum is exclusive; sub-modules are the escape hatch when a module genuinely spans buckets.
• Setting category = "engine" on a Flutter app to game the obligation rule into requiring [self_hosted]. The category reflects the dominant consumer pathway, not a desired audit outcome.

9. Validation rules (enforced by audit)

koder-spec-audit self-hosted --validate (or koder-spec-audit koder-toml --validate):

1. If category present, value is in the enum.
2. If category ∈ {engine, infra-tooling} AND a [self_hosted] block exists, the block's required fields (replaces, status) are populated.
3. If category ∈ {engine, infra-tooling} AND [self_hosted] is absent, emit advisory warning (Phase 4) or strict error (Phase 5).
4. The TOML is syntactically valid (tomllib parse).

10. Relationship to other policies

• policies/self-hosted-first.kmd — consumes this field for the anti-drift heuristic and the obligation rule.
• policies/reuse-first.kmd — sub-policies under policies/reuse/ apply per-category; the category field is the structured route to "which sub-policy governs this module".
• meta/docs/stack/rfcs/policies-RFC-002-self-hosted-first.md §5 — RFC migration plan; this spec is Phase 4 product.