Third field category “internal”

[MHohenberg]

firm add currently treats fields as required or optional. Some fields (e.g., created, updated) are system-managed and shouldn’t be user-editable during interactive entry. Introduce a third category - internal - to mark fields that are set by Firm (or derived) and hidden or read-only in interactive flows.

Motivation

• Reduce friction: users shouldn’t have to tab through non-editable metadata just to reach the single optional field they actually want.
• Prevent accidental edits: timestamps and integrity fields shouldn’t be user-supplied.
• Clearer intent: schemas can express “who owns this value” (user vs. system) rather than just “is it required.”

Proposal

1) Add per-field properties:

field "created" {
  type       = "datetime"
  mode       = "internal"    # "required" | "optional" | "internal"
  compute    = "now()"       # optional: function or template
  editable   = false         # default for internal
  visible    = "hidden"      # "visible" | "hidden"
}

field "updated" {
  type       = "datetime"
  mode       = "internal"
  compute    = "now()"       # auto-set on create; update hook bumps this
  on_update  = "now()"       # recompute on mutation
}

field "name" {
  type       = "string"
  mode       = "required"    # prompted
}

field "notes" {
  type       = "string"
  mode       = "optional"    # prompted after requireds
}

Some notes:

• mode=internal implies editable=false in interactive prompts and CLI flags.
• compute/on_update let Firm populate values automatically.
• visible=hidden keeps internal fields out of firm add prompts and short views, while still persisting in the file.

2) CLI Behaviour (firm add)

Prompt order: required → optional. Internal fields are skipped.

Flags:

• --show-internal (view-only) prints computed/internal fields at the end.
• --no-optional jumps straight to save after requireds.

Validation:

• If a user provides an internal field via --field created=..., reject with a clear error: “Field ‘created’ is internal and cannot be set interactively.”

Hooks:

• On create, evaluate compute.
• On update/mutate, evaluate on_update for relevant fields.

Backward compatibility

• existing schemas default to mode="optiona" when no mode is specified, preserving behaviour

Risks / Considerations

• Need a deterministic set of compute functions (e.g. now(), uuid(), hash(fields...)) to avoid non-reproducible builds

[danielrothmann]

I think this is a solid idea. The creation time can be valuable for query, but it seems backwards for the CLI to prompt the user for the entity creation time (obviously that time is right now).

The reason I have not wanted to tackle this yet, is that created time, for example, cannot always be computed - it must be computed only once, during the act of creation. I considered hard-coding the CLI to compute some of the metadata fields on add, but it would be better to bake it into the framework as something you can customise for you needs.

Differentiating hooks in the schema between create and update, as you suggest, seems a good way to solve it in the DSL. I personally like on_create and on_update for naming.

On the grammar side, this should already be possible as nested blocks only mandate that they contain field value assignments.

A change like this would touch:

• The core schema model
• The schema field parser
• Parsed -> core schema conversion