Dashboard Runtime Context Model - Phase 4D-1
npm install @webwaka/core-dashboard-runtimePhase 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.
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)
``bash`
npm install @webwaka/core-dashboard-runtime
#### 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',
});
`
- ✅ 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
- RuntimeContextError - Base error classInvalidRuntimeContextError
- - Validation failuresMissingEvaluationTimeError
- - Missing evaluation timeInvalidTenantError
- - Invalid tenant IDInvalidSubjectError
- - Invalid subject ID
---
#### 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 declarationruntime: DashboardRuntimeContext
- - Runtime contextsnapshots: ControlSnapshots
- - Control snapshots
Returns: DashboardSnapshot
#### evaluateDashboardFromSnapshot(snapshot, evaluationTime?): ResolvedDashboard
Evaluates dashboard from a snapshot.
Parameters:
- snapshot: DashboardSnapshot - Dashboard snapshotevaluationTime?: number
- - Optional evaluation time (defaults to snapshot time)
Returns: ResolvedDashboard
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.
- RuntimeWiringError - Base error for wiring failuresRuntimeControlWiringError
- - Control resolution failuresMissingRuntimeDependencyError
- - Missing required dependenciesSnapshotEvaluationError
- - Snapshot evaluation failures
---
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)
``
DashboardDeclaration (WHAT)
+
DashboardRuntimeContext (WHO/WHEN/WHERE)
+
ControlSnapshots (externally provided)
↓
resolveDashboardFromRuntime()
↓
ResolvedDashboard
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
---
- ✅ 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
---
`bashRun tests
npm test
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
---
UNLICENSED
---
https://github.com/changerplanet/webwaka-core-dashboard-runtime