Grill: the default ontology and a user-supplied one

[antejavor]

Part of #431

Question

What is the generic default model used before anything is learned: #353's fixed core (User, Person, the value types) alone, or a generic topic type as well? When a user supplies a schema up front (ManualStrategy), does it switch derivation off for that scope, or seed it so derivation only extends it? How is a supplied schema configured (config file, CLI)?

[antejavor]

Resolution

Grilled 2026-10-06. Builds on scope (#432), aggregation (#434) and the gate (#435).

The generic default (version 0) = fixed core + a thin generic layer, shipped by hygm.

• Fixed core (never merged or retired, outside the active-type cap): User, Person, and the value types Duration, Quantity, Money, Date, TimeWindow (The derivation contract for LlmRecommendationStrategy #353).
• Generic layer: Organization, Location, Event, plus two types flagged catch-all: Topic (a subject, idea or skill) and Artifact (a thing made or used: a tool, file, product).
• Relations: a handful of generic user-centred ones (works_on, uses, prefers, knows, attended, …), plus a value relation into each value type (happened_on→Date, lasted→Duration, costs→Money, counts→Quantity, scheduled_at→TimeWindow), so value facts are never dropped (the Run the revised derivation contract: batched propose and consolidate #372 failure). The exact names are settled when it's built.
• Learned runs may merge into or retire the generic layer like any domain type, but the catch-all flag is permanent, so the gate (Grill: the automatic gate that adopts a new model version #435) always measures catch-all share against Topic/Artifact.
• Ownership: hygm ships it as a packaged YAML loaded through ManualStrategy (e.g. hygm.default_model()), and declares the core labels and the catch-all flag that derivation and the gate read. sessions-graph takes its default from hygm. unstructured2graph's own DEFAULT_ONTOLOGY (entity-only, generic doc-to-graph, published) is left unchanged.

A user-supplied schema seeds derivation; a setting can switch it off.

• derive = "extend" | "off", default extend.
• extend: the supplied schema, validated and with the core added, becomes the user's next version in place of the generic layer. Its types are pinned: learned runs may add types beside them but never merge, rename or retire a pinned one.
• off: the schema is used exactly as given, and no derivation runs. This is how benchmarks stay on a fixed vocabulary (e.g. LongMemEval's hand YAML).

Configuration.

• config.toml: [sessions_graph.ontology] path = "…/schema.yaml", derive = "extend". File-only, per the hook config rule.
• On reconcile, if the file's content hash differs from the one on the user's current pinned version, it is validated and loaded as a new version. A supplied schema passes validate_model() only, with no outcome gate (the user chose it). Learned types carry forward unless they clash with a pinned label.
• CLI: sessions-graph ontology load --user <id> --file … [--derive off] for backfills or another user; sessions-graph ontology show --user <id> prints the adopted version.
• Removing path deletes nothing: the pinned types become ordinary learned types from the next derivation on.

Considered and not taken: core only (no catch-all for the gate to measure); the LongMemEval vocabulary as the default (the misfit BEAM exposed); off-only or extend-only with no setting; a CLI-only path; an MCP tool letting the agent change the schema.