Active authoring scope

kater scope use PATH --model KIND.NAME selects an exact declaration to edit. A SQL file with one declaration infers it.

# Select one model in a file as the one you are editing
kater scope use PATH --model KIND.NAME

• A folder is only a location. A directory alone selects a browsing location and cannot infer the model you are editing. --model-type can assert the type, but it cannot stand in for identity.
• What is saved. The saved scope is version 2. It holds the connection, the full workspace path where it applies, the layer, and the declaration’s type and identity. Buffer text is never saved. Old records need a new selection.
• Which command. kater model fields returns the authoring catalog, and the old bare list command is removed. kater model list stays for general browsing.

What model fields returns

• The parts. A field response holds context, active_fields, presentation, field_catalog, blocked_sources and dependency_revision. The ACTIVE section holds the active model’s outputs.
• Sources by model type. Source and custom SQL have guidance without a source tree. Ordinary datasets show only their resolved DB dataset. Semantic models show eligible Kater datasets and other semantic models. Workspace roots show their selected shared source. Queries show the workspace root, then the eligible queries in that exact workspace.
• No loops. A model and the models that depend on it cannot become source additions. Unsupported joins and stale facts get separate explanations with actions.
• Ready fields only. Only fields whose insertion.status is ready can be added. present describes projections that exist. Readiness belongs to the current document and its dependencies, and it is refreshed after edits.

How fields are added

• Aliases are reused. Field additions reuse source aliases and bound occurrences.
• Joins need proof. Automatic joins need a unique direct or two-hop relationship, backed by exported reference lineage and proven SQL keys. They do not guess from matching names or metadata cardinality alone. Several paths need explicit SQL.
• Stars expand. A supported one-source star expands into explicit projections for edits, and keeps explicit workspace measure declarations.
• New and copied fields. They use the same checked edit.model transaction, with create_projection and duplicate_projection arrays and the current document revision. The CLI flags are --create-projection JSON and --duplicate-projection JSON. A copy targets an exact output OutputRef.
• Declarations. Field authoring uses named MEASURE and DIMENSION declarations, CUSTOM_CALCULATION in a query, and AS display labels. Find the field’s local Editing menu or exported Sources menu, then send its shared operation_id, exact target and typed parameters.
• What each operation changes. Aggregation, derive, window and calculate-at operations append a named output. Sort, filter and Filter by this number change a clause. Display format changes presentation. Configuration edits include the compiler’s expression target and the current settings.
• Prepare, then apply. Prepare returns status: prepared with a candidate contract, and apply checks revisions atomically. Source actions cannot configure the producer.