@webwaka/core-dashboard-runtime

Phase 4D-1, 4D-2, 4D-3: Dashboard Runtime Context Model & Control Wiring

This package provides the canonical runtime context model for dashboard resolution and snapshot-based control injection.

Overview

The runtime context model is purely structural and contains zero decision logic. It serves as the canonical boundary between:

• Runtime state (WHO/WHEN/WHERE)
• Control engines (permissions, entitlements, feature flags)
• Dashboard resolution (WHAT to show)

Installation

npm install @webwaka/core-dashboard-runtime

Phase 4D-1: Runtime Context Model

Core API

normalizeDashboardContext(input): DashboardRuntimeContext

Validates and normalizes dashboard runtime context with strict guarantees.

Parameters:

• tenantId: string - Tenant identifier (required)
• subjectId: string - Subject identifier (required)
• subjectType: 'user' | 'service' | 'system' - Subject type (required)
• evaluationTime: number - Explicit evaluation time in milliseconds (required)
• environment: 'server' | 'client' - Execution environment (required)
• locale?: string - Locale code (optional, defaults to 'en')

Returns: Deeply frozen DashboardRuntimeContext

Example:

import { normalizeDashboardContext } from '@webwaka/core-dashboard-runtime';

const runtime = normalizeDashboardContext({
  tenantId: 'tenant-123',
  subjectId: 'user-456',
  subjectType: 'user',
  evaluationTime: Date.now(),
  environment: 'server',
  locale: 'en',
});

Guarantees

• ✅ Deterministic: No Date.now(), Math.random(), or system time
• ✅ Immutable: Deep-frozen contexts (cannot be modified)
• ✅ Nigeria-First: Currency always 'NGN'
• ✅ Type-Safe: Full TypeScript support with explicit errors
• ✅ Zero Logic: Purely structural, no decision logic

Error Types

• RuntimeContextError - Base error class
• InvalidRuntimeContextError - Validation failures
• MissingEvaluationTimeError - Missing evaluation time
• InvalidTenantError - Invalid tenant ID
• InvalidSubjectError - Invalid subject ID

Phase 4D-2/4D-3: Runtime → Control Wiring

Core API

resolveDashboardFromRuntime(declaration, runtime, snapshots): ResolvedDashboard

Resolves dashboard from explicit declaration, runtime context, and control snapshots.

Parameters:

• declaration: DashboardDeclaration - Dashboard declaration (WHAT to resolve)
• runtime: DashboardRuntimeContext - Runtime context (WHO/WHEN/WHERE)
• snapshots: ControlSnapshots - Externally-provided control snapshots

Returns: ResolvedDashboard

Example:

import {
  normalizeDashboardContext,
  resolveDashboardFromRuntime,
  type ControlSnapshots,
} from '@webwaka/core-dashboard-runtime';
import type { DashboardDeclaration } from '@webwaka/core-dashboard-control';

const declaration: DashboardDeclaration = {
  dashboardId: 'pos-dashboard',
  label: 'POS Dashboard',
  allowedSubjects: ['user', 'staff'],
  sections: [/* ... */],
};

const runtime = normalizeDashboardContext({
  tenantId: 'tenant-123',
  subjectId: 'user-456',
  subjectType: 'user',
  evaluationTime: Date.now(),
  environment: 'server',
  locale: 'en',
});

// Control snapshots are provided externally
// (from API, cache, offline storage, etc.)
const snapshots: ControlSnapshots = {
  permissions: {
    subjectId: 'user-456',
    capabilities: ['read:dashboard', 'write:dashboard'],
    deniedCapabilities: [],
  },
  entitlements: {
    tenantId: 'tenant-123',
    activeEntitlements: ['premium', 'analytics'],
    expiredEntitlements: [],
  },
  features: {
    enabledFeatures: ['new-ui', 'beta-features'],
    disabledFeatures: [],
  },
};

const resolved = resolveDashboardFromRuntime(declaration, runtime, snapshots);

generateDashboardSnapshotFromRuntime(declaration, runtime, snapshots): DashboardSnapshot

Generates a dashboard snapshot for offline evaluation.

Parameters:

• declaration: DashboardDeclaration - Dashboard declaration
• runtime: DashboardRuntimeContext - Runtime context
• snapshots: ControlSnapshots - Control snapshots

Returns: DashboardSnapshot

evaluateDashboardFromSnapshot(snapshot, evaluationTime?): ResolvedDashboard

Evaluates dashboard from a snapshot.

Parameters:

• snapshot: DashboardSnapshot - Dashboard snapshot
• evaluationTime?: number - Optional evaluation time (defaults to snapshot time)

Returns: ResolvedDashboard

Control Snapshots

The ControlSnapshots interface defines the canonical boundary between runtime wiring and control engines.

interface ControlSnapshots {
  permissions: PermissionResult;
  entitlements: EntitlementSnapshot;
  features: FeatureSnapshot;
}

Important: Control snapshots are:

• Produced elsewhere (API layer, server, edge, worker, etc.)
• Possibly backed by real engines
• Possibly loaded from cache
• Possibly evaluated offline

They are NOT produced by the runtime wiring layer.

Error Types (Phase 4D-2/4D-3)

• RuntimeWiringError - Base error for wiring failures
• RuntimeControlWiringError - Control resolution failures
• MissingRuntimeDependencyError - Missing required dependencies
• SnapshotEvaluationError - Snapshot evaluation failures

Architecture

Constitutional Layering

Phase 4D-3 formalizes snapshot-based control injection as the canonical boundary between runtime wiring and control engines.

This preserves constitutional layering:

• DashboardDeclaration answers "WHAT exists" (suite-owned)
• DashboardRuntimeContext answers "WHO/WHEN/WHERE" (core runtime)
• ControlSnapshots answer "WHAT they can see" (control engines)
• Wiring Layer orchestrates (pure adapter)

Mental Model

DashboardDeclaration (WHAT)
        +
DashboardRuntimeContext (WHO/WHEN/WHERE)
        +
ControlSnapshots (externally provided)
        ↓
resolveDashboardFromRuntime()
        ↓
ResolvedDashboard

Phase 4D-3 Clarification

Phase 4D-3 does not integrate full control engines.

It formalizes snapshot-based control injection as the canonical boundary between runtime wiring and control engines.

The runtime wiring layer:

• ✅ Accepts externally-provided control snapshots
• ✅ Remains engine-agnostic
• ✅ Preserves all Phase 4D-1 and 4D-2 guarantees
• ❌ Does NOT create control state
• ❌ Does NOT initialize permissions storage
• ❌ Does NOT define entitlements or feature flags
• ❌ Does NOT call database-backed services

Guarantees (All Phases)

• ✅ Deterministic: No Date.now(), Math.random(), or system time
• ✅ Immutable: Deep-frozen contexts
• ✅ Nigeria-First: Currency always 'NGN'
• ✅ Type-Safe: Full TypeScript support
• ✅ Zero Logic: Purely structural, no decision logic
• ✅ Snapshot Parity: Live resolution === snapshot evaluation
• ✅ Tenant Isolation: Enforced by control engines
• ✅ Pure Adapter: No hidden defaults or inferred state

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

Test Coverage:

• 65 tests (33 Phase 4D-1 + 32 Phase 4D-2/4D-3)
• All tests passing
• Determinism proven (10× tests)
• Snapshot parity verified
• Tenant isolation verified

License

UNLICENSED

Repository

https://github.com/changerplanet/webwaka-core-dashboard-runtime