c25. Perspective Implementation Plan

Goal

Execute the perspective augmentation by expanding the existing synthetic inventory graph first, then building one wrapper component per item type plus a second c25 experiment page dedicated to item-specific maps.

This file is the execution companion to:

• PLAN.md
• PERSPECTIVE-AUGMENTATION-PLAN.md

Execution Principle

Do not start by building ten item-specific wrappers against incomplete data.

Instead:

1. expand the synthetic scenario contract
2. keep the current inventory view rendering cleanly
3. add a second experiment page for item-specific maps
4. add one wrapper per item type, fed by view-specific data
5. tune summaries, grouping, and compression only after the data model is believable

Current File Ownership

These files already form the center of c25 and should stay the primary edit surface:

• inventoryScenarios.js Owns the scenario generator, entity catalogs, deterministic tier exports, and scenario stats.
• ExperimentsApp.vue Owns the experiment shell, scenario controls, grouping controls, and header stats.
• QMapInventoryIndex.vue Owns the public wrapper seam for inventory-shaped data.
• QMapInventoryIndexDefaults.js Owns inventory-specific visual tuning defaults.
• src/components/index.js Owns exports for the public wrapper seam.
• dev/App.vue Owns the experiment index and should expose the second c25 page once it exists.

Recommended File Split

The current synthetic generator is already carrying multiple responsibilities. Before adding six new entity families, split it into a small set of focused modules.

Recommended new files:

• dev/experiments/c25.ai-ecosystem-inventory-map/shared/inventoryCatalogs.js Owns label catalogs for models, endpoints, API keys, users, sessions, and secondary call patterns.
• dev/experiments/c25.ai-ecosystem-inventory-map/shared/inventoryActorFactories.js Owns actor builders such as createSessionActor(), createUserActor(), createModelActor(), createApiKeyActor(), createEndpointActor(), and createSecondaryCallActor().
• dev/experiments/c25.ai-ecosystem-inventory-map/shared/inventoryFlowBuilders.js Owns createFlow() plus perspective-relevant flow metadata and helper builders for relationship families.
• dev/experiments/c25.ai-ecosystem-inventory-map/shared/itemMapScenarios.js Owns view-specific synthetic data builders for item-specific wrappers.
• dev/experiments/c25.ai-ecosystem-inventory-map/ItemMapsApp.vue Owns the second experiment page for category-specific wrappers.
• dev/experiments/c25.ai-ecosystem-inventory-map/item-maps.html Second HTML entry point, mirroring the c23 two-page pattern.
• dev/experiments/c25.ai-ecosystem-inventory-map/item-maps.js Mount entry for ItemMapsApp.vue.

Keep inventoryScenarios.js as the orchestrator that:

• assembles scenario tiers
• wires catalogs and factories together
• exports AI_ECOSYSTEM_INVENTORY_SCENARIOS
• exports AI_ECOSYSTEM_INVENTORY_SCENARIO_MAP

Keep itemMapScenarios.js as the wrapper-specific scenario layer that:

• derives view-specific synthetic payloads from the richer graph
• exposes one scenario contract per item wrapper
• keeps the item-specific map page independent from the inventory-index page

Phase 1: Expand The Synthetic Graph

Files

• inventoryScenarios.js
• shared/inventoryCatalogs.js
• shared/inventoryActorFactories.js
• shared/inventoryFlowBuilders.js

Work

Add first-class actors for:

• Session
• User
• Model
• API Key
• Endpoint
• Secondary Call

Keep and preserve existing actors:

• AI Agent
• Repository
• File
• MCP Server
• Tool
• Sub-Agent

Add missing flow families:

• user -> session
• session -> agent
• session -> model
• session -> mcp-server
• session -> tool
• session -> sub-agent
• session -> repository
• session -> endpoint
• agent -> model
• model -> endpoint
• api-key -> model
• api-key -> endpoint
• api-key -> mcp-server
• secondary-call -> model
• secondary-call -> endpoint
• secondary-call -> repository
• secondary-call -> file
• secondary-call -> parent session
• secondary-call -> parent agent

Add actor tags needed for perspective grouping:

• entityType
• owner
• ownerType
• team
• businessUnit
• environment
• provider
• status
• securityTier
• capabilityClass
• modelFamily
• endpointRegion
• endpointKind
• accessMode
• sessionId
• sessionType
• repo
• callDepth
• parentCallId

Add flow tags needed for perspective summaries and filters:

• protocol
• operation
• direction
• latencyBucket
• errorState
• retryCount
• costWeight
• tokenWeight
• timeBucket
• initiatedBy
• credentialId
• parentSessionId
• parentCallId

Output Contract

Each scenario should continue returning:

• actors
• dataflows
• stats
• meta

But stats should expand to include:

• sessions
• users
• models
• apiKeys
• endpoints
• secondaryCalls
• errorCount
• retryCount
• estimatedCost
• tokenVolume

Verification

• all four deterministic tiers still compile
• current inventory map still renders
• no existing actor family disappears
• new entity families appear in every tier, including demo

Phase 2: Surface The Richer Graph In The Existing Inventory Experiment

Files

• ExperimentsApp.vue

Work

Update the header stats and scenario metadata to expose the expanded graph:

• sessions
• users
• models
• endpoints
• API keys
• secondary calls
• cost and token summaries
• retries and errors where useful

Add a compact note in the experiment header that the scenario pack now supports perspective-specific pivots.

Do not add the item-specific map UI yet. This phase is only about making the richer graph visible and sanity-checkable.

Verification

• the experiment header remains readable on desktop
• the scenario cards still feel compact
• demo, teamspace, enterprise, and global-enterprise remain easy to switch between without visual breakage

Phase 3: Create The Second c25 Experiment Page

Files

• dev/experiments/c25.ai-ecosystem-inventory-map/ItemMapsApp.vue
• dev/experiments/c25.ai-ecosystem-inventory-map/item-maps.html
• dev/experiments/c25.ai-ecosystem-inventory-map/item-maps.js
• dev/App.vue

Work

Add a second page for c25, following the c23 pattern of two experiment entry points.

This second page should:

• mount ItemMapsApp.vue
• expose a select dropdown for choosing which item-specific wrapper component to load
• keep shared scene controls where practical
• make it easy to compare wrapper behavior without editing code

Recommended page label:

• c25.ai-ecosystem-item-maps

Verification

• the experiment index shows two c25 entries
• the second entry loads independently of the inventory-index page
• switching the dropdown swaps the mounted wrapper component cleanly

Phase 4: Add One Wrapper Per Item Type

Files

• shared/itemMapScenarios.js
• src/components/index.js
• QMapInventoryIndex.vue
• new wrapper files under src/components/

Work

Create one wrapper per item type:

• QMapSessionMap.vue
• QMapAgentMap.vue
• QMapUserMap.vue
• QMapMcpServerMap.vue
• QMapModelMap.vue
• QMapApiKeyMap.vue
• QMapEndpointMap.vue
• QMapToolSkillMap.vue
• QMapRepoFileMap.vue
• QMapSecondaryCallMap.vue

Each wrapper should:

• accept a view-specific payload
• reduce it to qmap actors and dataflows if needed
• own default grouping and summary behavior for that entity family
• remain independent from experiment-local imports

itemMapScenarios.js should provide synthetic payloads shaped for each wrapper instead of forcing every wrapper to consume the entire inventory object directly.

Verification

• switching the dropdown loads a different wrapper cleanly
• each wrapper answers a visibly different question
• wrappers are data-specific, not just visual aliases of the same generic scene

Phase 5: Add Wrapper Support To The Second Experiment Page

Files

• dev/experiments/c25.ai-ecosystem-inventory-map/ItemMapsApp.vue
• shared/itemMapScenarios.js
• src/components/index.js

Work

Mount item-specific components dynamically from the select dropdown.

The second page should:

• maintain a registry from dropdown option to wrapper component
• resolve the matching view-specific synthetic payload
• pass that payload into the mounted wrapper
• keep shared controls like lighting and grouping where they make sense

Preserve QMapInventoryIndex as the original first-page wrapper. Do not collapse all item-specific maps back into it.

Verification

• changing the dropdown updates both component and payload
• each mounted wrapper renders without needing page-specific hacks
• the first c25 page remains unchanged

Phase 6: Add The Compression-Sensitive Wrappers

Files

• shared/itemMapScenarios.js
• dev/experiments/c25.ai-ecosystem-inventory-map/ItemMapsApp.vue
• possibly a new summary helper under shared/ if the experiment proves it necessary

Work

Add the harder wrappers only after the richer graph and first-wave wrappers are stable:

• Models
• Endpoints
• Users
• API Keys
• Secondary Calls

Special handling likely needed:

• API Keys may want lower-visual-weight nodes and stronger summary strips
• Secondary Calls may want collapsed chains or fan-out summaries
• Models and Endpoints may need provider-heavy grouping defaults

Verification

• the scene remains interpretable at enterprise and global-enterprise
• dense perspectives introduce summaries instead of uncontrolled node explosions

File-Level Checklist

shared/inventoryCatalogs.js

• add catalogs for users, sessions, models, API keys, endpoints, and secondary call patterns
• keep labels deterministic and varied enough to feel believable

shared/inventoryActorFactories.js

• add actor builders for all new entity families
• ensure every actor ships with the perspective tags it needs
• preserve current actor tag shape for existing entities

shared/inventoryFlowBuilders.js

• centralize flow creation
• add flow metadata fields once, not ad hoc in each scenario branch
• keep ids deterministic

inventoryScenarios.js

• refactor into orchestrator role
• import catalogs, actor factories, and flow builders
• expand each tier to include all entity families
• expand stats and meta

shared/itemMapScenarios.js

• derive wrapper-specific payloads from the richer graph
• avoid one giant generic payload for every item map
• make each wrapper's input shape intentional and easy to reason about

ExperimentsApp.vue

• add new counts to the header
• keep the existing grouping controls usable

ItemMapsApp.vue

• add the select dropdown for wrapper switching
• register each item-specific wrapper component
• pass the matching view-specific synthetic payload
• preserve shared controls where useful for comparison

item-maps.html and item-maps.js

• add the second c25 experiment entry point
• mirror the c23 two-page setup pattern

QMapInventoryIndex.vue

• keep the current inventory contract working
• do not collapse the item-specific wrappers back into this file
• keep it as the dedicated inventory/index wrapper

QMapInventoryIndexDefaults.js

• keep current defaults as the baseline inventory fallback
• keep these defaults specific to the inventory page rather than the item-specific map page

src/components/QMapSessionMap.vue through src/components/QMapSecondaryCallMap.vue

• add one wrapper component per item type
• keep props narrow and view-specific
• own grouping and summary defaults locally
• avoid experiment-local imports

src/components/index.js

• export each new wrapper component

dev/App.vue

• add a second c25 experiment entry in the dev experiment list

First Slice

The first concrete coding slice should be:

1. split inventoryScenarios.js into smaller shared modules
2. add Session, User, Model, API Key, Endpoint, and Secondary Call
3. add the missing flow families and metadata tags
4. expand scenario stats and header counts
5. scaffold the second c25 page entry point
6. verify the existing inventory surface still reads clearly in all four tiers

If that slice goes well, the next slice is the first batch of item-specific wrappers plus the dropdown-based component switcher.

Ready-To-Start Definition

We are ready to start implementation when:

• the current synthetic generator has an agreed file split
• the new entity families and flow families are accepted
• the second-page experiment pattern is accepted
• the first slice is explicitly limited to synthetic graph expansion plus experiment stats and page scaffolding

That definition is already satisfied by this plan.