Statics (managed sessions)

Statics are Core API records that describe platform-owned analytics surfaces backed by normal Sessions and Session Templates. Each static definition targets a template revision; static instances bind one concrete Session per scope (for example a single environment-wide instance for the pilot).

Definitions carry display metadata (title, icon, navigation section) for shells. Sessions created for static instances live in the reserved _statics system project and are hidden from normal session listings so operator dashboards stay separate from trainee session catalogs.

Presets

On startup the Core API applies JSON shipped under Presets/ beside the assembly:

1. features/ — heat package manifests (skipped if the feature internal name already exists).
2. templates/ — session-template manifests (skipped if template name exists).
3. System projects _statics, _logs, _diagnostics (created if missing; CRUD mutations are blocked on these projects).
4. statics/ — StaticManifest files (skipped if Key already exists). The shipped system dashboard preset is system-resource-monitor (Resource Monitor: one-minute refresh, template heat-system-resource-monitor-next with optional output archival; see below).

Manifest schemas include Presets/schemas/static-preset-v1.schema.json. Import and export use the same manifest shape as other portable HEAT JSON assets.

Resource Monitor

Shipped preset system-resource-monitor uses session template heat-system-resource-monitor-next, 1 minute refresh, Kubernetes Resources KPI copy, and a TimelineChart fed by historical cluster-report outputs (rollup node cluster-usage-history). Existing databases may still hold retired definitions (system-cluster-next-dashboard, system-report, or session templates heat-system-report-pilot / heat-system-report-with-cluster) until removed via the Core API or SQL; fresh installs from current presets only ship Resource Monitor and this one template.

Output volume: one-minute refresh produces roughly 1,440 cluster-report outputs per day per backing session. Use two complementary mechanisms:

Backing-session rotation (new session per period)

Statics can replace their backing Session on a schedule so each window gets a fresh DAG and output history. Configure per static in Configuration.backingSessionRotation (stored as ConfigurationJson):

{
  "backingSessionRotation": {
    "period": "24h"
  }
}

• period: rolling window (Kubernetes-style duration, e.g. 24h, 7d). After the period elapses since the last rotation (or since session creation on first run), the Core API creates a new backing session, re-points the static instance, and deletes the old session (including S3).
• alignToUtcHour (optional alternative): calendar-aligned daily windows at a UTC hour (0–23), similar to the legacy platform key below.

The shipped Resource Monitor preset sets period": "24h". This is separate from session retention on the template (which trims outputs within a session).

Legacy fallback: platform key system.statics.global_singleton_session_rotate_hour_utc still applies to GlobalSingleton statics that do not define backingSessionRotation. When neither per-static config nor the platform key is set, one backing session is kept for the life of the instance (only template upgrade or manual API replaces it).

Preset/bootstrap import does not rewrite existing static rows; update ConfigurationJson via the Core API or apply a template upgrade after changing the preset in git.

Session retention (within a session)

Session retention on the backing template can ArchiveByAge old node outputs while retention.skipArchive preserves rollup and dashboard nodes. heat-system-resource-monitor-next ships with a 7d archive threshold for long idle periods inside a single session.

Refresh and upgrades

Instances are reprocessed on an interval (pilot default 30 minutes; the Resource Monitor preset uses 1 minute) via the hosted refresh loop. When a static definition is first created (API or shipped preset import), the Core API also runs an immediate initial refresh for each new backing instance so runner tasks are enqueued without waiting for the first tick. Reprocess targets come from the static definition’s configuration JSON (Configuration in manifests, stored as ConfigurationJson). List session-template node instance names in reprocessNodeNames to limit which nodes run; if that list is empty or omitted, the platform keeps legacy behaviour and reprocesses every node in the static session (with a deprecation warning in logs).

Optional triggers reduce unnecessary work. For example triggers.onDimensionUserMembershipChange controls whether PerUser static instances reprocess when dimension membership changes for affected core user IDs (union of previous and new membership). You can set enabled to false or narrow scopeKinds when extending trigger behaviour.

Changing the backing session template for a definition is an explicit template upgrade: new Sessions are created per instance and old backing sessions are retired (session graphs are materialized at creation time).

Scope kind and instance rows

Definitions declare a scope kind (GlobalSingleton, PerProject, PerUser). Instance prototypes and rows must align: PerProject requires ScopeProjectId, PerUser requires ScopeUserId, and GlobalSingleton uses neither on the singleton row. The Core API rejects inconsistent combinations on create, update, and preset import.

Access control

Each definition stores a minimum view privilege. API responses filter definitions and instances so callers only see what their request privilege allows (aligned with Core API auth middleware).

For in-cluster callers (no X-HEAT-Request-Source: external), privilege is normally Privileged. Platform configuration system.core.internal_request_privilege may be set to System when trusted internal services (for example Heat v2 API aggregating static dashboard navigation) must read definitions gated at System minimum view privilege, without forwarding end-user JWTs to Core. Omit the key or use Privileged to keep the historical default.