docs: Calculated fields formula reference (sc-15979)

[nrichers]

What and why?

Rewrites the calculated fields formula reference so it reads as if the Starlark formula engine has always been the runtime, and adds a single short callout that names the engine and confirms that stored formulas were migrated automatically.

Relates to sc-15979

Two partials changed:

• site/guide/inventory/_field-types.qmd — Calculation field type intro rewritten in a Starlark-first voice, with a built-in helper-functions table, a single engine note callout, the Risk Tier example rewritten with dict-access syntax, the artifact panel-tabset (Severity / Due date / Custom fields) rewritten with params["finding_type"] and params["model"], and the calculation-field.png reference removed. Mirrors the same prose in the revealjs-only block.
• site/guide/inventory/_example-next-review-date-and-days-remaining.qmd — Risk Tier, Next Review Date, and Days Remaining formulas rewritten using safe_parse_date, add_months, days_between, today(), and params.get. Both embedded calculation-field screenshots removed.

Every rewritten formula was run through the canonical transpiler in validmind/backend@origin/main:scripts/starlark_validate.py and executed via StarlarkExecutor.run() against representative param sets to confirm parity with the original Python.

How to test

After the preview deploy finishes, check:

• Manage inventory fields → Inventory field types → Calculation — engine callout, helper table, Risk Tier example.
• Manage artifact fields → Artifact field types → Calculation — engine callout, helper table, Severity / Due date / Custom fields panel-tabset.
• Edit inventory fields → Example: Next review date & days remaining — Risk Tier, Next Review Date, Days Remaining formulas; link in the helper-list intro resolves to the helper table on manage-inventory-fields.

What needs special review?

1. The engine note callout in _field-types.qmd is the only place in the guide that names Starlark or mentions migration — confirm that voice is what we want and that no additional in-page hedging is required.
2. The three calculated-field screenshots (calculation-field.png, calculation-field-next-review-date.png, calculation-field-days-remaining.png) were removed pending the final formula-editor UI. Recapture and re-add in a follow-up PR once the Starlark editor ships.
3. The 15 helper signatures in the new table were lifted from backend/src/backend/utils/starlark_executor.py. Quick sanity check that the labels match what the editor autocomplete will surface.

Dependencies, breaking changes, and deployment notes

• Depends on the per-org rollout of launchdarkly.rollout.formula.starlark. The docs are written for the post-rollout world; nothing here implies a flag.
• No breaking changes for users: existing formulas were transpiled and stored as Starlark by the bulk migration in validmind/backend#3090.

Release notes

documentation

Refreshed the calculated fields formula reference: dict-access syntax, a built-in helper-functions reference, updated worked examples, and a single note acknowledging the underlying engine swap.

Future release notes (draft, not part of this PR)

The two snippets below follow the existing releases/<component>/<version>/_pr-<number>.qmd convention in the release-notes repo. They are intentionally not committed as part of this docs PR — copy them into the appropriate version folder when launchdarkly.rollout.formula.starlark has been turned on for all orgs.

releases/backend/<version>/_pr-3058.qmd

<!--- https://github.com/validmind/backend/pull/3058 - Labels: security --->

### Hardened the calculated fields formula engine

Calculated fields now run on the Starlark formula engine, a sandboxed scripting language designed for safe, embedded use. The new engine eliminates a class of code-injection risks that affected the previous Python-based engine while preserving the same \`formula(params)\` shape and supplying built-in helper functions for dates, numbers, and lists.

Existing formulas were migrated automatically — no action is required from you, and the read-only values that your calculated fields produce continue to evaluate as before.

releases/frontend/<version>/_pr-2510.qmd

<!--- https://github.com/validmind/frontend/pull/2510 - Labels: enhancement --->

### Updated the calculated fields formula editor

The formula editor in **{{< fa gear >}} Settings** now offers Starlark-native autocomplete for the \`params\` dictionary, inline suggestions for the built-in helper functions, and a **Starlark formula guide** reference panel. Older Python-style snippets that the new engine cannot accept are flagged in the editor with a hint pointing to the equivalent Starlark pattern.

Checklist

• What and why
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut
• Documentation updated (if required)

[github-actions]

PR Summary

This PR updates the documentation and examples for calculation fields within the inventory and artifact guides. The key changes include:

1. Transitioning from Python-style attribute access (e.g., params.frequencyOfValidation) to dictionary-style access (e.g., params["frequencyOfValidation"]). This update is applied consistently across all example formulas.

2. Introducing and documenting the use of built-in helper functions for date manipulation, such as today(), safe_parse_date(value), add_months(date, n), and days_between(a, b). These helpers replace previous approaches using Python's datetime classes and external libraries.

3. Updating code examples to use the Starlark syntax. The documentation now emphasizes that all formulas should be written in Starlark, with clear examples provided for calculations such as risk tier determination, next review date computation, days remaining calculation, due date adjustments, and dynamic artifact-based severity calculations.

4. Improving readability of examples by removing extraneous comments and emphasizing dictionary-style access for both inventory fields and nested artifact data (e.g., using params["model"]["fieldKey"]).

Overall, the PR enhances the accuracy of the documentation by aligning code examples with the current implementation details and best practices for writing formulas in the platform.

Test Suggestions

• Test the next review date calculation by providing valid ISO dates and various risk tiers to verify that the correct month adjustments are applied.
• Verify that the days remaining formula correctly computes the difference using the helper functions (comparing against expected output).
• Use sample data for risk tier, severity score, and due date calculations to ensure the dynamic branching in the formulas works as documented.
• Test error handling by passing empty or malformed date strings to ensure that 'N/A' is returned appropriately.
• Ensure that the updated dictionary-style accessed keys do not break existing formulas when integrated within the system.