[nagisml]

Closes #1185. Part of #938.

Stacked on #1188 (feature/rename-set-companion-table). Until that is merged, this PR also shows its commit. Please review/merge #1188 first.

What

The macro API from v1.22.0 needs a way to deprecate things. This PR adds that mechanism, as proposed in #1185. Nothing in API 4 is deprecated.

Registry

• deprecated: Optional[tuple[int, str]] (API version, what to use instead) on ApiFunction and Param (runtime.py) and on CacheField (cache_data.py). The header keys move into a new HEADER_KEYS registry in metadata.py, with the same field.
• API_STABLE = {4: "1.22.0"} in runtime.py: which API version went stable in which release.
• REMOVED in runtime.py: functions removed after their deprecation period, kept here so a call gets a clear error.
• deprecation.py: the message texts, so the runtime, the Macro manager and the CI helpers word them the same.

Warnings in the macro output

• A deprecated function's first call in a run prints one line, and the function works as before:
  opensak.old_name is deprecated since API 5 and will be removed in a later version; use opensak.new_name() instead (line 12)
• A macro started with opensak.run_macro() gets its own warning, which names its file: (child.lua, line 3).
• Functions written in Lua (e.g. opensak.transaction) get the warning from a small Lua wrapper, so their errors don't pass through Python and still name the macro line.
• Parameters: the function calls rt._deprecated_param(func, param) where it maps the old name to the new one.
• Header keys: printed once when the macro starts, and shown in the Macro manager (warning icon and tooltip in the "Needs API" column). The tooltip has one new text, macro_mgr_deprecated_keys, in all languages (machine-translated).
• Cache fields: no run-time warning, since watching every key read would slow down large loops. They are marked in the docs and editor files, and by the CI helpers.

Removed functions

opensak.old_name stays nil, so if opensak.old_name then still works. Calling it stops the macro with
opensak.old_name was removed in API 6; use opensak.new_name() instead
instead of Lua's attempt to call a nil value. To keep both, a metatable on opensak (and its sub-tables) notes which removed name was looked up, and the runtime rewrites Lua's error message. A macro that catches the error with pcall still sees Lua's original message.

Docs and editors (api_docs.py)

• api.md: "4, deprecated in 5" in the function table, and Deprecated in API version 5: use opensak.new_name(). at the top of the function's section. Deprecated parameters, cache fields and header keys are marked too, and a short paragraph explains the deprecation rules.
• Lua Language Server stub: ---@deprecated Use opensak.new_name(), so calls are shown struck through in VS Code.
• Notepad++: the calltip starts with (deprecated). UltraEdit's wordfile has no calltips, so nothing changes there.

As CONTRIBUTING asks, docs/macros/api.md and macros/types/ are left to the Macro API docs workflow.

CI: API baseline

The N1 baseline didn't exist yet, so this adds a small one:

• api_baseline.py takes a snapshot of the API: functions with their parameters, cache fields and header keys, each with its deprecation version and feature flag. The committed snapshot is tests/fixtures/macro_api_baseline.json.
• test_api_matches_the_committed_baseline accepts additions, deprecations, and changes to beta-only entries (feature-flagged). It also accepts a removal once the deprecation's API version is in API_STABLE and a later API version went stable too; the function must then be in REMOVED. It fails on any other removal or rename, including moving a stable function behind a feature flag.
• scripts/update_macro_api_baseline.py rewrites the baseline. Run it when a stable release ships a new API version; it refuses while the API breaks the current baseline. A test fails if the baseline is older than the newest API_STABLE entry.

For OpenSAK-Macros

metadata.deprecated_names() lists everything deprecated. metadata.find_deprecated(text) returns (line, message) for deprecated header keys, function calls and cache field reads in a macro, so the repository CI can warn. Parameters are positional and can't be found this way. metadata.py now imports deprecation.py, and deprecated_names() needs OpenSAK installed.

Tests

• 41 new tests in test_macro_deprecation_1185.py. Nothing in API 4 is deprecated, so they mark registry entries as deprecated with monkeypatch. They cover the warnings (once per run, the line, Lua functions, run_macro, parameters, header keys), removed functions, the Macro manager marker, the docs and editor output, deprecated_names() / find_deprecated(), and the baseline rules.
• Full unit suite passes locally: 7800 passed, 122 skipped.
• Whole-repo mypy: clean.