@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

``bash
npm install @webwaka/core-dashboard-runtime
`

Phase 4D-1: Runtime Context Model

$3

#### 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:
`typescript
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',
});
`

$3

- ✅ 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

$3

- 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

$3

#### 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:
`typescript
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

$3

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

`typescript
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.

$3

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

---

Architecture

$3

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)

$3

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

$3

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

`bash


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