Document vm_today and datetime support in calculated fields

[nrichers]

Summary of changes

• New collapsible example under Calculation field type: "Example — Date arithmetic and vm_today".
• Table of names available in formulas: vm_today, date, datetime, timedelta, relativedelta.
• Two example formulas:
  1. Next review date — Approval date + interval by risk tier (Tier 1: +3 months, Tier 2: +6 months, Tier 3: +1 year).
  2. Days remaining — Countdown to next review using vm_today (updates when formula re-runs).
• Note on behavior: date fields passed in as millisecond timestamps; formula output is string (use .isoformat() for dates).

File touched: site/guide/model-inventory/_field-types.qmd.

Findings from codebase investigation

• Backend (backend/src/backend/utils/code_executor.py): Execution environment injects vm_today = date.today() and exposes date, datetime, timedelta, relativedelta (and others) into formula scope. Date fields are passed as values that require int(params.x) / 1000 for date.fromtimestamp() (JS/Python timestamp precision difference).
• Feature history: Implemented in Sprint 63 (Nov 2024), backend PR PR#1003 — Merge main into staging #1004, frontend PR docs: Show model stakeholder updates in model activity #1078. Held from release notes then; dev confirmed ready to document now.
• No library notebooks reference this — it is a platform UI feature for inventory calculated fields only.
• Reference: Andres's gist (complex + simple examples) and demo transcript (days-remaining countdown use of vm_today).

How to test

Open deploy preview → Model inventory → Field types → Calculation, expand "Example — Date arithmetic and vm_today" and confirm table + code blocks render.

[sc-7465]

[github-actions]

PR Summary

This PR introduces a new section in the documentation for the model inventory fields. The changes add detailed, practical examples on how formulas can leverage date arithmetic and the special variable vm_today for dynamic date calculations. The documentation now includes two main examples:

1. Next Review Date Calculation: Demonstrates how to compute the next review date by converting a millisecond timestamp into a date, selecting an appropriate review interval based on a risk tier (Tier 1, Tier 2, Tier 3), and outputting the next review date in ISO format. The example also gracefully handles cases where the approval date is missing or an unsupported risk tier is provided.

2. Days Remaining Countdown: Shows how to calculate the number of days remaining until the next review date. It converts an ISO formatted date back to a date object, computes the difference from the current date (vm_today), and returns the result in a human-readable format.

These enhancements provide users with clear, sample implementations that detail how to work with date and time types within formulas, thereby improving the usability and clarity of the system documentation.

Test Suggestions

• Verify that the 'Next Review Date' example returns 'N/A' when the 'dmApprovedDate' is empty.
• Test the formula with valid timestamps for each risk tier to ensure the correct interval is applied and the output matches the expected ISO format.
• Check that the risk tier not present in the provided dictionary correctly leads to an 'N/A' output.
• For the 'Days Remaining' example, simulate different values of 'nextReviewDate' relative to 'vm_today' and confirm that the countdown displays the correct number of days.
• Ensure that the conversion from timestamps to date objects and back to string formats works consistently across different date inputs.

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[github-actions]

Lighthouse check results

⚠️ WARN: Average accessibility score is 0.87 (required: >0.9) — Check the workflow run

Show Lighthouse scores

Folder depth level checked: 0

Commit SHA: 0322276

Modify the workflow to check a different depth:

• 0: Top-level navigation only — /index.html, /guide/guides.html, ...
• 1: All first-level subdirectories — /guide/.html, /developer/.html, ...
• 2: All second-level subdirectories — /guide/attestation/*.html, ...

Page	Accessibility	Performance	Best Practices	SEO
/developer/validmind-library.html	0.85	0.68	1.00	0.82
/get-started/get-started.html	0.85	0.69	1.00	0.73
/guide/guides.html	0.85	0.69	1.00	0.82
/index.html	0.93	0.65	1.00	0.82
/releases/all-releases.html	0.86	0.69	1.00	0.73
/support/support.html	0.91	0.61	1.00	0.82
/training/training.html	0.85	0.69	0.96	0.73

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview