SECTION-SOURCE-SCOOLING-ADAPTER-PLANNING-SPEC.md
file-level
1
files
1
commits
0
hotspots
0
🧊 dead
0
💥 blast risk
| 1 | # SectionSource Scooling Adapter Planning Spec |
| 2 | |
| 3 | ## Simple Summary |
| 4 | |
| 5 | Phase 1I plans how Scooling may later consume body-free `SectionSource v0` metadata. |
| 6 | |
| 7 | This phase does not implement Scooling runtime code, hosted MCP, Hub routes, search, |
| 8 | persistence, section bodies, snippets, summaries, PageIndex, OCR, LLM calls, or provider |
| 9 | routing. |
| 10 | |
| 11 | ## Technical Summary |
| 12 | |
| 13 | Scooling may use SectionSource only as a consumer through a Scooling-owned adapter. It must |
| 14 | not become the canonical Markdown parser, section id generator, authorization owner, |
| 15 | retrieval index, or source-of-truth store for SectionSource data. |
| 16 | |
| 17 | This planning phase accepts only the adapter boundary for a future Scooling integration. |
| 18 | The future Scooling adapter must consume a tested Knowtation transport and preserve the |
| 19 | body-free `SectionSource v0` contract: |
| 20 | |
| 21 | - request one authorized note path at a time |
| 22 | - receive only body-free section metadata |
| 23 | - treat heading text and heading paths as untrusted source material |
| 24 | - preserve fallback behavior when SectionSource is unavailable |
| 25 | - never parse Markdown as the canonical section source |
| 26 | - never persist SectionSource as truth |
| 27 | - never expose learner-private sections outside authorized contexts |
| 28 | |
| 29 | ## Planning Decision |
| 30 | |
| 31 | Phase 1I accepts Scooling adapter planning only. |
| 32 | |
| 33 | It does not approve: |
| 34 | |
| 35 | - adding Scooling runtime code |
| 36 | - adding a Scooling adapter implementation |
| 37 | - adding hosted `get_section_source` |
| 38 | - adding Hub REST, OpenAPI, Hub UI, or canister routes |
| 39 | - adding search, vectors, indexes, persistence, sidecars, or memory events |
| 40 | - returning note body text |
| 41 | - returning section body text |
| 42 | - returning snippets |
| 43 | - returning exact line ranges, byte offsets, or section body lengths |
| 44 | - adding summaries, OCR, PageIndex, LLM calls, or external provider routing |
| 45 | - writing learner knowledge back without human review |
| 46 | |
| 47 | ## Future Adapter Target |
| 48 | |
| 49 | A later Scooling phase may propose: |
| 50 | |
| 51 | ```text |
| 52 | KnowtationVaultAdapter.getSectionSource(path) |
| 53 | ``` |
| 54 | |
| 55 | The future adapter method may accept only: |
| 56 | |
| 57 | ```json |
| 58 | { |
| 59 | "path": "inbox/example.md" |
| 60 | } |
| 61 | ``` |
| 62 | |
| 63 | Field rules: |
| 64 | |
| 65 | - `path` is required. |
| 66 | - `path` must be a string. |
| 67 | - `path` must be vault-relative in the Knowtation transport being called. |
| 68 | - `path` must not be absolute. |
| 69 | - `path` must not escape the authorized vault or learner scope. |
| 70 | - No batch paths are accepted. |
| 71 | - No body, snippet, search, filter, ranking, provider, classroom, or write-back options are |
| 72 | accepted. |
| 73 | |
| 74 | ## Accepted Future Input Source |
| 75 | |
| 76 | The future Scooling adapter may consume SectionSource only from an accepted Knowtation |
| 77 | surface: |
| 78 | |
| 79 | - self-hosted MCP `get_section_source`, if the user's environment is local/self-hosted |
| 80 | - a future hosted `get_section_source`, only after its implementation spec and tests are |
| 81 | accepted |
| 82 | |
| 83 | Scooling must not derive canonical SectionSource data by: |
| 84 | |
| 85 | - parsing Markdown directly |
| 86 | - reading raw notes directly |
| 87 | - calling PageIndex or OCR |
| 88 | - using LLMs to infer section boundaries |
| 89 | - reusing stale cached section records as truth |
| 90 | - scraping rendered HTML or UI output |
| 91 | |
| 92 | ## Accepted Future Output |
| 93 | |
| 94 | The future Scooling adapter may receive only the body-free `SectionSource v0` shape: |
| 95 | |
| 96 | ```json |
| 97 | { |
| 98 | "schema": "knowtation.section_source/v0", |
| 99 | "path": "inbox/example.md", |
| 100 | "title": "Example", |
| 101 | "sections": [ |
| 102 | { |
| 103 | "section_id": "inbox-example-md:h1-example-0001", |
| 104 | "heading_id": "h1-example-0001", |
| 105 | "level": 1, |
| 106 | "heading_path": ["Example"], |
| 107 | "heading_text": "Example", |
| 108 | "child_section_ids": [], |
| 109 | "body_available": true, |
| 110 | "body_returned": false, |
| 111 | "snippet_returned": false |
| 112 | } |
| 113 | ], |
| 114 | "truncated": false |
| 115 | } |
| 116 | ``` |
| 117 | |
| 118 | ## Explicitly Excluded Output |
| 119 | |
| 120 | The future Scooling adapter must not receive or store: |
| 121 | |
| 122 | - note body text |
| 123 | - section body text |
| 124 | - snippets |
| 125 | - source excerpts |
| 126 | - full frontmatter |
| 127 | - absolute filesystem paths |
| 128 | - exact line ranges |
| 129 | - byte offsets |
| 130 | - section body lengths |
| 131 | - summaries |
| 132 | - vector scores |
| 133 | - provider payloads |
| 134 | - MCP resource URIs |
| 135 | - search results |
| 136 | - persistence ids |
| 137 | - raw upstream canister payloads |
| 138 | - classroom visibility decisions outside Scooling policy |
| 139 | |
| 140 | ## Authorization Boundary |
| 141 | |
| 142 | Scooling must treat SectionSource as private note-derived data. |
| 143 | |
| 144 | The future adapter must preserve these requirements: |
| 145 | |
| 146 | - Knowtation remains the authorization boundary for note-derived SectionSource data. |
| 147 | - Scooling may request SectionSource only for a learner, classroom, organization, and vault |
| 148 | context already authorized by the active Knowtation transport. |
| 149 | - Scooling must not bypass Knowtation path, vault, hosted, or canister-user checks. |
| 150 | - Scooling must not use SectionSource from one learner, classroom, organization, or vault in |
| 151 | another context. |
| 152 | - Missing, unauthorized, and unavailable SectionSource responses must fall back without |
| 153 | exposing private note existence beyond the accepted transport behavior. |
| 154 | - Classroom, mentor, public, and organization displays require separate Scooling policy |
| 155 | before any private section metadata is shown. |
| 156 | |
| 157 | ## Fallback Behavior |
| 158 | |
| 159 | When SectionSource is unavailable, rejected, truncated, or unsupported, Scooling must fall |
| 160 | back to already accepted body-free surfaces: |
| 161 | |
| 162 | - document-level retrieval |
| 163 | - `NoteOutline` |
| 164 | - `DocumentTree` |
| 165 | - `MetadataFacets` |
| 166 | - a "section source unavailable" display state |
| 167 | |
| 168 | Fallback must not: |
| 169 | |
| 170 | - parse Markdown to recover sections |
| 171 | - call PageIndex, OCR, LLMs, or external providers |
| 172 | - request note bodies or snippets |
| 173 | - treat absence of SectionSource as permission to reveal more detail |
| 174 | - write a replacement section index as truth |
| 175 | |
| 176 | ## Prompt-Injection Handling |
| 177 | |
| 178 | Scooling must treat every SectionSource text field as untrusted source material: |
| 179 | |
| 180 | - `title` |
| 181 | - `heading_text` |
| 182 | - `heading_path` |
| 183 | - future labels, snippets, or section bodies if separately accepted |
| 184 | |
| 185 | Prompt-like headings that ask the model to reveal secrets, bypass review, call providers, |
| 186 | alter grades, impersonate a teacher, or disable guardrails must remain inert text. They must |
| 187 | not be executed, promoted to instructions, or used to bypass human review. |
| 188 | |
| 189 | ## Deletion, Export, And Staleness |
| 190 | |
| 191 | This planning phase does not approve Scooling persistence. |
| 192 | |
| 193 | Until a separate persistence spec is accepted: |
| 194 | |
| 195 | - Scooling must not store SectionSource as truth. |
| 196 | - Scooling must not create a section sidecar. |
| 197 | - Scooling must not create a vector record from SectionSource. |
| 198 | - Scooling must not create a summary record from SectionSource. |
| 199 | - Scooling must not export SectionSource as learner-authored content. |
| 200 | - Editing or deleting a Knowtation note leaves no Scooling SectionSource artifact to clean |
| 201 | up. |
| 202 | |
| 203 | If a future Scooling phase stores derived state, it must define edit, delete, export, |
| 204 | backup, restore, and stale-data behavior before implementation. |
| 205 | |
| 206 | ## Write-Back Boundary |
| 207 | |
| 208 | SectionSource consumption must not grant write permissions. |
| 209 | |
| 210 | Future Scooling write-back flows must remain separate from SectionSource reads and must |
| 211 | continue to require proposal, conflict, denial, and human-review gates. SectionSource |
| 212 | metadata must not automatically create notes, update notes, change learner memory, alter |
| 213 | classroom records, or write educator feedback. |
| 214 | |
| 215 | ## Seven-Tier Test Requirements |
| 216 | |
| 217 | ### Unit |
| 218 | |
| 219 | - The adapter target name is documented. |
| 220 | - The accepted input is exactly one vault-relative path. |
| 221 | - The accepted output allowlist matches body-free `SectionSource v0`. |
| 222 | - `body_returned` and `snippet_returned` remain false. |
| 223 | |
| 224 | ### Integration |
| 225 | |
| 226 | - Scooling is documented as a consumer only. |
| 227 | - Knowtation remains the canonical parser and authorization boundary. |
| 228 | - Scooling runtime files remain unchanged in this planning phase. |
| 229 | - Hosted runtime files do not register hosted `get_section_source`. |
| 230 | |
| 231 | ### End To End |
| 232 | |
| 233 | - Scooling cannot consume live SectionSource in this planning phase. |
| 234 | - Scooling fallback remains document-level or body-free. |
| 235 | - No Scooling flow receives note bodies, section bodies, or snippets. |
| 236 | |
| 237 | ### Stress |
| 238 | |
| 239 | - Planning checks stay bounded to SectionSource contract files and Scooling smoke boundary |
| 240 | files. |
| 241 | - No test scans a real vault. |
| 242 | - No test calls external providers. |
| 243 | |
| 244 | ### Data Integrity |
| 245 | |
| 246 | - This planning phase writes no notes, sidecars, indexes, vectors, memory, summaries, |
| 247 | classroom records, or canister state. |
| 248 | - No cached Scooling section record is created. |
| 249 | - Export, delete, edit, backup, and restore behavior remain unchanged. |
| 250 | |
| 251 | ### Performance |
| 252 | |
| 253 | - The future adapter must request one note's SectionSource metadata at a time. |
| 254 | - The future adapter must not scan the whole vault. |
| 255 | - The future adapter must not call external providers. |
| 256 | |
| 257 | ### Security |
| 258 | |
| 259 | - Scooling runtime exposure remains blocked in this phase. |
| 260 | - No note body text appears in Scooling SectionSource output. |
| 261 | - No section body text appears in Scooling SectionSource output. |
| 262 | - No snippets appear in Scooling SectionSource output. |
| 263 | - No full frontmatter appears in Scooling SectionSource output. |
| 264 | - No absolute filesystem paths appear in Scooling SectionSource output. |
| 265 | - No MCP resource URI appears for Scooling SectionSource content. |
| 266 | - Hosted, classroom, search, persistence, write-back, and provider exposure remain blocked. |
| 267 | |
| 268 | ## Stop Conditions |
| 269 | |
| 270 | Stop and re-plan if Scooling work requires: |
| 271 | |
| 272 | - parsing Markdown as the canonical section parser |
| 273 | - deriving canonical section ids in Scooling |
| 274 | - returning note body text |
| 275 | - returning section body text |
| 276 | - returning snippets |
| 277 | - returning exact line ranges |
| 278 | - returning byte offsets |
| 279 | - returning section body lengths |
| 280 | - adding summaries |
| 281 | - adding search, vectors, indexes, persistence, sidecars, memory events, or classroom |
| 282 | records |
| 283 | - adding hosted MCP, Hub REST, OpenAPI, Hub UI, or canister routes |
| 284 | - sending note-derived content to LLMs, OCR, PageIndex, or external providers |
| 285 | - bypassing Knowtation authorization |
| 286 | - exposing private learner sections outside authorized contexts |
| 287 | - writing learner knowledge back without proposal and human-review gates |
| 288 | |
| 289 | ## Acceptance Criteria |
| 290 | |
| 291 | Phase 1I is accepted when: |
| 292 | |
| 293 | - The Scooling adapter boundary is documented before Scooling runtime exposure. |
| 294 | - The future adapter target is limited to one vault-relative note path. |
| 295 | - The future adapter output is limited to body-free `SectionSource v0` metadata. |
| 296 | - Scooling remains a consumer and not the canonical parser, authorization owner, or store of |
| 297 | truth. |
| 298 | - Fallback behavior remains body-free when SectionSource is unavailable. |
| 299 | - Tests prove no Scooling runtime, hosted runtime, Hub route, search, persistence, body, |
| 300 | snippet, provider, OCR, PageIndex, LLM, or write-back behavior was added. |
| 301 | |
| 302 | ## Recommendation |
| 303 | |
| 304 | The Scooling adapter slice is complete in the Scooling repository at commit `ea5421e` |
| 305 | (`Add Scooling SectionSource transport boundary`). |
| 306 | |
| 307 | The completed Scooling slice includes `getSectionSource`, strict body-free |
| 308 | `knowtation.section_source/v0` schema validation, REST/memory transport handling, fallback |
| 309 | unavailable state, and seven-tier coverage. No further Knowtation runtime change is needed |
| 310 | for Scooling to consume the current self-hosted SectionSource boundary. |
| 311 | |
| 312 | Proceed next to a hosted `get_section_source` implementation spec only if hosted |
| 313 | SectionSource is required. |