View Layer

The .spine/view/ layer is an experimental, derived comprehension layer for fast repository reading.

It is intentionally small in the current v1.0.x line:

• .spine/view/public-surface.json
• .spine/view/risk-hotspots.json

This layer is:

• opt-in
• non-authoritative
• downstream from aggregation
• not part of the stable public artifact contract for the first open-source v1.0 release

Enable it

Use either project config or an environment override.

Project config:

{
  "artifacts": {
    "experimentalViewLayer": true
  }
}

Environment override:

SPINE_EXPERIMENTAL_VIEW_LAYER=true spine sync

If the flag is off, sync behaves as before and no .spine/view/** artifacts are produced.

What it writes

When enabled, spine sync writes:

• .spine/view/public-surface.json
• .spine/view/risk-hotspots.json

These files are generated by the normal trusted writer path and are protected together with other official .spine outputs.

public-surface

public-surface.json tries to answer:

• which files look like real repo entry surfaces
• which files deserve priority when an agent is orienting itself

Current ranking signals include:

• semantic publicSurface
• explicit path shapes such as CLI, MCP, route, config, and schema
• export count
• internal consumer count
• re-export and barrel amplification

This artifact is meant for comprehension, not enforcement.

risk-hotspots

risk-hotspots.json tries to answer:

• which files are structurally risky to change
• which files deserve early review attention

Current additive scoring factors include:

• fan-in
• fan-out
• cross-boundary density
• surface exposure
• semantic drift
• rule violations
• large-file weight
• missing adjacent tests

Each hotspot carries score breakdown details so the result stays explainable instead of acting like a black box.

Current limits

The current experimental rollout has explicit limits:

• only two view artifacts are generated
• output format may still evolve after v1.0
• no CI or governance decision should depend on .spine/view/**
• the layer should be treated as a reading aid, not a source of truth

Deferred ideas such as api-chains, dependency-summary, and structure remain out of scope for the current release line.