Handbook

SharePoint library read strategies

Use canonical governed task ids (sharepoint_*). Deprecated playwright_* aliases call the same runners for one release.

Updated 2026-07-06

Quick decision

SharePoint library list strategy

Choose governed REST, scroll, or viewport list tasks after URL normalization and health probing.

Need full deck/file list?The primary decision gate for inventory depth and harvest method.
M365 cookies on Playwright page? → sharepoint_list_library_files_restPrefer REST when browser session cookies authenticate OData folder walks.
REST blocked, page loaded? → sharepoint_list_library_files_scrollFall back to scroll harvest when REST is unavailable but the grid loads.
Smoke / visible rows only? → sharepoint_list_library_files_viewportRead only visible grid rows for quick smoke checks.
Before browser list:Run normalization and health probe before any browser list harvest.
sharepoint_normalize_library_url → sharepoint_probe_library_healthNormalize the library URL triple, then probe page readiness.

  Need full deck/file list?
    ├─ M365 cookies on Playwright page? → sharepoint_list_library_files_rest
    ├─ REST blocked, page loaded?       → sharepoint_list_library_files_scroll
    └─ Smoke / visible rows only?       → sharepoint_list_library_files_viewport

  Before browser list:
    sharepoint_normalize_library_url → sharepoint_probe_library_health

Governed tasks (canonical)

task_id	Produces	Typical live time	Stability	Practical item count
`sharepoint_normalize_library_url`	`entry_url`, `reader_root`, `site_top`	< 0.1 s	High	N/A (no items)
`sharepoint_probe_library_health`	`ready`, `row_count`, `file_row_count`, …	2–8 s	High (gating only)	0
`sharepoint_list_library_files_viewport`	`ReadResult.items[]`	3–10 s	Low for inventory	~30 visible
`sharepoint_list_library_files_scroll`	`ReadResult.items[]`	30–180 s	Medium	100–5000
`sharepoint_list_library_files_columns`	`ReadResult` + `extra.columns`	5–15 s	Medium	Grid row set
`sharepoint_list_library_files_rest`	`ReadResult`, `source_kind: library_rest`	10–60 s	High (if auth OK)	Full folder

Deprecated aliases (one release)

Deprecated	Use instead
`playwright_normalize_sharepoint_url`	`sharepoint_normalize_library_url`
`playwright_sharepoint_page_health`	`sharepoint_probe_library_health`
`playwright_read_items` + `library_viewport`	`sharepoint_list_library_files_viewport`
`playwright_read_items` + `library_scroll`	`sharepoint_list_library_files_scroll`
`playwright_read_items` + `library_columns`	`sharepoint_list_library_files_columns`

Generic playwright_read_items remains for outlook, teams, workday, onedrive, and classic SharePoint kinds (news, list, library).

Output shape (all list tasks)

{
  "schema_version": "1",
  "source_system": "sharepoint",
  "items": [
    {
      "schema_version": "1",
      "item_id": "sp:modern:…",
      "source_system": "sharepoint",
      "source_kind": "library_scroll",
      "item_type": "file",
      "title": "Example.pptx",
      "url": "https://tenant.sharepoint.com/…/Doc.aspx?…",
      "extra": {}
    }
  ],
  "next_cursor": null
}

REST items set source_kind to library_rest and extra.via to sharepoint_rest.

Library-layer symbols (canonical)

Symbol	Module	Role
`sharepoint_normalize_library_urls`	`connectors/sharepoint_urls.py`	URL triple
`sharepoint_detect_page_state`	`connectors/sharepoint_modern.py`	HTML health heuristics
`sharepoint_merge_page_health`	`sharepoint_modern.py`	Merge evaluate + HTML
`sharepoint_parse_library_viewport_rows`	`sharepoint_modern.py`	Viewport rows → items
`sharepoint_harvest_library_files_scroll`	`connectors/sharepoint_scroll.py`	Scroll harvest
`sharepoint_list_library_files_rest`	`connectors/sharepoint_rest.py`	OData folder walk
`sharepoint_links_to_unified_items`	`sharepoint_modern.py`	Link dicts → items

Deprecated names (normalize_sharepoint_library_url, harvest_sharepoint_links_readonly, …) remain as aliases.

Example calls

Normalize (no session):

{ "site_url": "https://contoso.sharepoint.com/sites/Engineering/Shared Documents" }

Probe health:

{
  "session_ref": "edge-session",
  "url": "https://contoso.sharepoint.com/sites/Engineering/Forms/AllItems.aspx"
}

Full folder (REST):

{
  "session_ref": "edge-session",
  "site_url": "https://contoso.sharepoint.com/sites/Engineering/Shared Documents",
  "max_depth": 4,
  "limit": 5000
}

Full folder (scroll):

{
  "session_ref": "edge-session",
  "query": {
    "site_url": "https://contoso.sharepoint.com/…",
    "max_scroll_rounds": 120,
    "stable_rounds_required": 4
  },
  "limit": 5000
}

Live benchmarks

Optional script (requires CDP + logged-in Edge). For harvest on a background tab, keep FORGE_LCDL_CDP_BRING_TO_FRONT=0 so LCDL enables focus emulation on attach — EDGE-CDP-ATTACH.md.

PYTHONPATH=src python3 scripts/benchmark-sharepoint-read-strategies.py \
  --sharepoint-url 'https://tenant.sharepoint.com/…'

Writes timing JSON under reports/sharepoint-read-benchmark.json. Embed summarized bands in this doc after a run on your tenant.

Viewport is not full inventory

sharepoint_list_library_files_viewport returns only visible grid rows (~30 on a typical screen). Use REST or scroll for backlog counts. Knowledge Assistant diagnostics call the same LCDL viewport_rows / grid_columns evaluate scripts via lcdl_sharepoint_bridge.

Listing vs binary download (consumer boundary)

Concern	Owner
Folder file list (`sharepoint_list_library_files_rest`)	LCDL governed task
Scroll / viewport / grid columns harvest	LCDL evaluate scripts + governed tasks (KA bridge only)
List item metadata (`sharepoint_fetch_list_item_fields`)	LCDL REST connector (browser cookies)
Binary download (`sharepoint_download_file_rest`, version bytes)	LCDL REST connector; KA `sharepoint_rest` thin-delegates via bridge

Full ownership matrix: SHAREPOINT-CONSUMER-BOUNDARY.md.

Deck identity (consumer): one SharePoint UniqueId → one KA deck_id via resolve_deck_id_for_sharepoint_item — see KA sharepoint-lcdl-boundary.md § Deck identity.

Forge LCDL