SectionSource Body-Free Transport Plan

Simple Summary

Phase 1D decides how SectionSource v0 may later be exposed outside direct library calls.

The decision is conservative: only body-free section metadata is eligible for transport. The local CLI and self-hosted MCP surfaces are now implemented. No hosted MCP tool, Hub endpoint, search mode, Scooling runtime behavior, body text, snippets, summaries, persistence, PageIndex, OCR, LLM call, or provider routing is added.

Technical Summary

Phase 1D accepts transport planning only. It does not implement a transport.

Body-free transport work may proceed only through separately tested implementation phases. Those implementations must expose the existing SectionSource v0 shape without adding note bodies, section bodies, snippets, exact line ranges, byte offsets, section body lengths, raw frontmatter, vectors, summaries, provider payloads, or persisted section records.

Transport Decision

The accepted transport decision is:

• Local library support is already implemented through readSectionSource.
• The local CLI surface is implemented for body-free SectionSource v0 metadata.
• The self-hosted MCP tool is implemented for body-free SectionSource v0 metadata.
• Hosted MCP, Hub REST, OpenAPI, Hub UI, canister routes, search modes, Scooling runtime consumption, PageIndex, OCR, LLM calls, external provider routing, section body reads, and snippets remain blocked.

This plan does not accept a hosted route, schema extension, hosted role change, ACL change, or Scooling adapter shape.

Allowed Future Local CLI Shape

The local CLI phase may add a body-free note-scoped command only if it:

• accepts exactly one vault-relative note path
• uses existing local config and vault resolution behavior
• reads one note through the existing local note-read path
• returns only the accepted SectionSource v0 fields
• returns body_returned: false
• returns snippet_returned: false
• exposes no body text, snippets, raw frontmatter, line ranges, byte offsets, section body lengths, summaries, vectors, provider payloads, or persistence ids
• includes seven-tier tests for the CLI surface

Allowed Future Self-Hosted MCP Shape

The self-hosted MCP phase may add a body-free note-scoped read tool only if it:

• mirrors get_note_outline, get_document_tree, and get_metadata_facets local auth and path behavior
• accepts exactly one vault-relative note path
• reads one note through the existing local note-read path
• returns only the accepted SectionSource v0 fields
• returns body_returned: false
• returns snippet_returned: false
• exposes no MCP resource URI for section bodies, snippets, or section sources
• includes seven-tier tests for the MCP surface

Hosted Transport Block

Hosted MCP and Hub transport remain blocked.

Before any hosted SectionSource transport can be proposed, a separate hosted authorization review must prove:

• active vault isolation
• effective canister user isolation
• hosted role ACL behavior
• missing and unauthorized note behavior
• no body or snippet logging
• no section body, snippet, line range, byte offset, summary, vector, provider payload, or persisted section record leakage
• multi-vault regression coverage

Search And Persistence Block

Transport planning does not approve search or persistence.

Future search or persistence work requires a separate spec because it changes deletion, export, stale-data, ranking, logging, and authorization behavior. No transport may create sidecars, indexes, vectors, memory events, summaries, provider records, or cached section payloads.

Scooling Boundary

Scooling remains blocked from live SectionSource runtime consumption until a separate Scooling phase.

A future Scooling phase must keep Scooling as a consumer through a Scooling-owned adapter. Scooling must not parse Markdown as the canonical section parser, derive canonical section ids, persist section sources as truth, expose private learner sections outside authorized contexts, or treat section text as model instructions.

Seven-Tier Test Requirements

Unit

• Transport handlers return the same SectionSource v0 schema as the library.
• Transport handlers keep body_returned and snippet_returned false.
• Transport handlers reject unsafe paths before note reads.

Integration

• CLI and self-hosted MCP surfaces reuse existing local note-read behavior.
• Missing and traversal paths reveal no extra detail beyond existing note reads.
• Future transport output matches the library output for the same note.

End To End

• Agent flows can inspect section candidates through a body-free surface.
• No agent flow receives section body text or snippets.
• Scooling fallback remains document-level or body-free until a separate Scooling phase.

Stress

• Large notes remain capped by heading count and input caps.
• Transport output size remains bounded by section count and text caps.
• Repeated transport calls are deterministic for unchanged notes.

Data Integrity

• Transport calls do not write notes, sidecars, indexes, vectors, memory, summaries, or canister state.
• Transport calls reflect current note content only.
• Persisted future phases define delete, edit, export, backup, and restore behavior before implementation.

Performance

• One-note transport calls do not scan the whole vault.
• No external provider calls occur.
• Hosted future phases must define rate limits and multi-vault isolation before exposure.

Security

• No note body text in transport output.
• No section body text in transport output.
• No snippets in transport output.
• No full frontmatter in transport output.
• No absolute filesystem paths in transport output.
• No MCP resource URI for section body or snippet data.
• Prompt-injection text remains untrusted source material.
• Hosted, Scooling, classroom, search, and persistence exposure remain blocked until separately reviewed.

Stop Conditions

Stop and re-plan if a transport proposal requires:

• returning note body text
• returning section body text
• returning snippets
• returning exact line ranges
• returning byte offsets
• returning section body lengths
• adding summaries
• adding search, vectors, indexes, persistence, sidecars, or memory events
• adding hosted MCP, Hub REST, OpenAPI, Hub UI, canister routes, or Scooling runtime code
• sending note-derived content to LLMs, OCR, PageIndex, or external providers
• weakening existing note-read authorization behavior

Acceptance Criteria

Phase 1D is accepted when:

• This plan limits future transport to body-free SectionSource metadata.
• This plan identifies local CLI and self-hosted MCP as the only eligible future transport surfaces.
• This plan keeps hosted, Hub, search, persistence, Scooling, body, snippet, provider, OCR, PageIndex, and LLM behavior blocked.
• Tests prove the current CLI and self-hosted MCP output remain body-free and hosted, Hub, and Scooling runtime transport remain blocked.
• Tests prove current SectionSource output remains body-free.

Recommendation

Phase 1E is implemented in cli/index.mjs; Phase 1G is implemented in mcp/create-server.mjs. Both are documented in docs/SECTION-SOURCE-CLI-IMPLEMENTATION-SPEC.md and docs/SECTION-SOURCE-MCP-IMPLEMENTATION-SPEC.md.

The hosted authorization review is accepted in docs/SECTION-SOURCE-HOSTED-AUTHORIZATION-REVIEW-SPEC.md.

The Scooling adapter planning boundary is accepted in docs/SECTION-SOURCE-SCOOLING-ADAPTER-PLANNING-SPEC.md.

The Scooling adapter slice is complete in the Scooling repository at commit ea5421e (Add Scooling SectionSource transport boundary).

Proceed next only with a separate hosted implementation spec if hosted SectionSource is required. Do not implement hosted, Hub, search, persistence, body reads, snippets, summaries, OCR, PageIndex, LLM calls, provider routing, or write-back behavior without that separate plan.