Handbook

SharePoint consumer boundary

forge-lcdl exposes atomic, product-agnostic SharePoint read operations. Consumers (for example forge-knowledge-assistant) attach an authorized browser session, call governed tasks or connector functions, and map wire…

Updated

LCDL must not import consumer repos or know about deck ids, heatmaps, Copilot menu labels, or job phases.

KA Analyze / Fleet / heatmap (not SharePoint atoms): KA-ANALYSIS-CONSUMER-BOUNDARY.md ↔ KA analysis-dual-architecture.md.

Atomic capability catalog

Capability Governed task_id Connector symbol Input (summary) Output (summary)
URL normalize sharepoint_normalize_library_url sharepoint_normalize_library_urls site_url, optional library_path entry_url, reader_root, site_top
Library health sharepoint_probe_library_health SharePointReader + page_health session_ref, library URL ready, row_count, file_row_count, hints
Full folder list (REST) sharepoint_list_library_files_rest sharepoint_list_library_files_rest session_ref, site_url ReadResult.items[] (source_kind: library_rest)
Scroll link harvest sharepoint_list_library_files_scroll sharepoint_harvest_library_files_scroll session_ref, scroll options ReadResult.items[] (library_scroll)
Visible grid rows sharepoint_list_library_files_viewport sharepoint_parse_library_viewport_rows session_ref ReadResult.items[] (~30 visible)
Grid column metadata sharepoint_list_library_files_columns evaluate grid_columns session_ref items + extra.columns
List item fields (connector; task optional) sharepoint_fetch_list_item_fields page, site_top, server_relative_url OData field dict
File bytes (REST) (connector; task optional) sharepoint_download_file_rest page, site_top, href / paths bytes written to target path
File version bytes (connector) sharepoint_download_file_version_rest page, version id bytes at target
Read-only navigation policy — sharepoint_allows_readonly_navigation URL bool
In-page evaluate scripts — EvaluateScriptId in scripts/sharepoint_readonly.py live Page JSON (rows, links, health)

See SharePoint library read strategies for when to use REST vs scroll vs viewport.

Wire shape (list tasks)

All list tasks emit ReadResult-compatible JSON: items[] with title, url, source_kind, optional extra. REST items set extra.via to sharepoint_rest.

What LCDL must not know

Out of scope for LCDL Belongs in consumer
deck_id, corpus/decks/ paths Knowledge Assistant ingest
Job phases (scan, save, copilot) KA job runner
M365 Copilot ⋮ menus (Summarize, Transcript, FAQ) KA sharepoint_copilot/ until mutation policy tier
Heatmap / Partial / Complete semantics KA deck_local_storage
SQLite entity_property namespaces KA repository
Viewport sweep backlog ordering KA sharepoint_viewport_sweep

Consumer responsibilities

  1. Session — Start Edge/CDP, sign in, register_playwright_page(session_ref, page). For long library harvests on a background tab, enable LCDL focus emulation (default when FORGE_LCDL_CDP_BRING_TO_FRONT=0) — EDGE-CDP-ATTACH.md.
  2. Composition — Run atoms in order (normalize → probe → list → download → …).
  3. Mapping — Convert UnifiedItem / wire dicts → consumer models.
  4. Orchestration — Retries, remediation flows, job progress, Copilot (product-specific).

Consumer deck mapping (Knowledge Assistant)

LCDL list items expose url / href and optional unique_id (REST UniqueId or sourcedoc on Doc.aspx URLs). KA maps each file to a single deck_id via resolve_deck_id_for_sharepoint_item — see KA sharepoint-lcdl-boundary.md § Deck identity.

LCDL must not compute deck_id, open SQLite, or write under corpus/. Identity harness: KA scripts/verify-deck-identity-harness.py.

Versioning rule: If wire item shape or unique_id population changes, update this file and KA sharepoint-lcdl-boundary.md. If KA resolve/dedupe logic changes, update KA docs + harness only — not LCDL tasks.

Migration status (Knowledge Assistant)

Prompt / area LCDL atom KA status
01 URL normalize sharepoint_normalize_library_url Done — reader_entry_url → LCDL
02 Health probe sharepoint_probe_library_health Done — confirm_sharepoint_library_health
03 REST inventory sharepoint_list_library_files_rest Done — discover + sweep API map
04 Scroll harvest sharepoint_list_library_files_scroll Done — bridge harvest_sharepoint_links_via_lcdl
05 Viewport rows sharepoint_list_library_files_viewport Done — bridge evaluate / task
06 Grid columns sharepoint_list_library_files_columns Done — bridge evaluate
07 Scan merge parity REST + scroll + columns Done — compare-lcdl-ka-scan-merge.py
08 Viewport sweep composition Done — KA orchestration; atoms via bridge
09 Read-only policy sharepoint_allows_readonly_navigation Done — KA read_only_policy
10 List item fields sharepoint_fetch_list_item_fields Done — connector + bridge
11 Binary download sharepoint_download_file_rest Done — connector + bridge; KA thin delegate
12 Remediation vs health probe after remediate Done — KA gates on LCDL probe
13 Guided bridge suite all read tasks Done — pytest live marker
14–16 Bulk job / CI composition Done — KA job uses bridge