Understanding the Explicit-Intent Origin in DataLayerManager: User Intent vs. Programmatic State Changes

The explicit-intent origin is a provenance marker that distinguishes user-initiated layer state changes from programmatic background operations, ensuring the gods-eye-view system respects deliberate user actions while allowing automatic state management to proceed without interference.

The DataLayerManager in the bilawalsidhu/gods-eye-view repository tracks every layer state transition through the lens of intent origin. This architectural pattern separates direct user gestures—such as clicks, taps, or keyboard shortcuts—from automated processes like teardown routines or detection-driven updates. By flagging user-driven changes with explicitIntent: true, the system enables downstream components to treat these transitions as authoritative, suppressing conflicting automatic overrides.

What Is the Explicit-Intent Origin?

The explicit-intent origin concept categorizes all layer state modifications into two distinct provenance types. Explicit-intent changes originate from direct user interaction with the interface, carrying a boolean flag that propagates through the detection pipeline. Programmatic changes stem from code execution—automatic enable/disable logic, cleanup routines, or telemetry-driven updates—and deliberately omit this flag.

This distinction lives in the event payload structure. When the UI dispatches a layer toggle, it sets explicitIntent: true to signal that a human deliberately requested the change. Conversely, background processes leave the flag undefined or false, indicating the change emerged from system logic rather than user preference. According to the source code in src/data/layerState.js, this design ensures that "programmatic disable or teardown never reaches the explicit-intent path" (see line 656).

How the DataLayerManager Tracks Origin in layerState.js

The core state transition logic resides in src/data/layerState.js, where the reducer examines each action's origin before applying state mutations. The implementation differentiates paths based on the presence of the explicitIntent property in the action payload.

When the layerState reducer processes a layerToggle event, it inspects the action.explicitIntent field. If the flag is present and true, the reducer preserves this metadata in the resulting state object, allowing downstream consumers to recognize the user-driven nature of the change. Programmatic dispatches—such as those triggered by automatic cleanup or detection policy updates—omit this field entirely, ensuring they do not generate explicit-intent events that would interfere with context persistence or user workflow tracking.

Practical Implementation: Dispatching Explicit-Intent Events

Integrating the explicit-intent origin into your layer management code requires setting the flag during user-initiated dispatches. The following pattern demonstrates how UI components mark interactions as intentional:

// UI handler for layer toggle buttons
function onLayerToggle(layerId, enable) {
  // Originates from user gesture → mark as explicit intent
  const event = {
    type: 'layerToggle',
    layerId,
    enable,
    explicitIntent: true,   // Flags this as user-driven
  };
  dispatchLayerState(event);
}

// Inside src/data/layerState.js (simplified reducer)
function layerStateReducer(state, action) {
  if (action.type === 'layerToggle') {
    // Only preserve flag for user-initiated changes
    if (action.explicitIntent) {
      state = { 
        ...state, 
        explicitIntent: true,
        userOverride: true 
      };
    }
    // Programmatic changes flow through without the flag,
    // preventing automatic overrides from persisting as user preferences
  }
  return state;
}

This separation ensures that automatic disable operations—such as those performed during teardown or detection conflicts—do not inadvertently mark layers as user-disabled, preserving the integrity of saved user contexts.

Downstream Consumers of the Explicit-Intent Flag

Multiple subsystems consume the explicit-intent origin metadata to adjust their behavior based on whether a change represents user preference or system maintenance.

Detection Policy

The src/data/detectionPolicy.js module uses the explicit-intent flag to implement the _detectionUserOverridden logic. When a layer change carries explicitIntent: true, the detection system recognizes that the user has manually configured the view, suppressing automatic detection updates that would otherwise override the current state. This prevents the system from reverting intentional user configurations during automated scanning cycles.

Context Persistence

The src/data/contextStore.js module relies on explicit-intent markers when persisting or restoring application state. As documented in docs/CURRENT-STATE.md, the context persistence layer specifically watches for settled explicit-intent events to determine which layer states represent genuine user preferences versus transient programmatic states. Without this flag, the system would save automatic teardown states as user preferences, leading to corrupted context restoration on application restart.

Summary

• Explicit-intent origin marks layer state changes resulting from direct user interaction, distinguishing them from programmatic background operations.
• The src/data/layerState.js reducer checks the explicitIntent flag on incoming actions, with line 656 specifically documenting that programmatic paths never trigger the explicit-intent branch.
• User gestures must dispatch events with explicitIntent: true to signal deliberate configuration changes.
• Downstream components like detection policy and context persistence use this flag to suppress automatic overrides and save only user-driven states.

Frequently Asked Questions

What is the difference between programmatic and explicit-intent origins?

Programmatic origins represent changes initiated by code—such as automatic teardown, detection-driven enable/disable, or telemetry updates—while explicit-intent origins represent direct user actions like clicks or keyboard shortcuts. The DataLayerManager treats programmatic changes as background operations that should not persist as user preferences, whereas explicit-intent changes are preserved as authoritative user configuration.

How does the explicit-intent flag affect detection policy?

The detection policy module in src/data/detectionPolicy.js checks the _detectionUserOverridden state, which is set when a layer change carries the explicit-intent flag. When this flag is present, automatic detection updates are suppressed for that layer, preventing the system from overriding deliberate user configurations during subsequent automated scanning or state reconciliation cycles.

Where is the explicit-intent origin logic implemented in the codebase?

The primary implementation resides in src/data/layerState.js, specifically within the reducer logic around line 656, which contains the comment distinguishing programmatic paths from explicit-intent paths. The flag is consumed by src/data/detectionPolicy.js for override logic and src/data/contextStore.js for persistence decisions, with architectural documentation available in docs/CURRENT-STATE.md.

Why does the DataLayerManager distinguish between user actions and programmatic changes?

This distinction prevents automatic system processes—such as cleanup routines, detection conflicts, or telemetry-driven updates—from corrupting saved user preferences. Without the explicit-intent origin concept, programmatic teardowns would be persisted as user-disabled layers, causing the application to restore incorrect states on restart and undermining the reliability of context persistence across sessions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}