SECTION-SOURCE-BODY-SNIPPET-POLICY.md
file-level
1
files
1
commits
0
hotspots
0
🧊 dead
0
💥 blast risk
| 1 | # SectionSource Body And Snippet Policy |
| 2 | |
| 3 | ## Simple Summary |
| 4 | |
| 5 | `SectionSource v0` may identify which sections exist, but it must not return section body |
| 6 | text or snippets today. |
| 7 | |
| 8 | This policy accepts a security boundary for future work: section body text is private note |
| 9 | content, snippets are not approved for v0, and no transport surface may expose either one |
| 10 | without a separate implementation spec and seven-tier tests. |
| 11 | |
| 12 | ## Technical Summary |
| 13 | |
| 14 | Phase 1C defines the policy gate that must be satisfied before any future SectionSource |
| 15 | body or snippet work. It does not add code that returns section body text, snippets, |
| 16 | summaries, vectors, line ranges, byte offsets, or persisted section records. |
| 17 | |
| 18 | The accepted v0 decision is: |
| 19 | |
| 20 | - Section body reads may be planned only for a future local-only phase that uses the same |
| 21 | authorization boundary as `readNote`. |
| 22 | - Section snippets are not accepted for v0. |
| 23 | - Hosted, MCP, CLI, Hub, search, persistence, Scooling, PageIndex, OCR, LLM, and provider |
| 24 | routing exposure remains blocked until a separate reviewed phase accepts that surface. |
| 25 | |
| 26 | ## Policy Status |
| 27 | |
| 28 | - Phase: `SectionSource v0 Phase 1C`. |
| 29 | - Status: accepted as a policy gate on local Muse `main`. |
| 30 | - Runtime change: none. |
| 31 | - Body return status: blocked in current code. |
| 32 | - Snippet return status: blocked in current code. |
| 33 | |
| 34 | ## Authorized Readers |
| 35 | |
| 36 | Section body text may be read only by a caller that is already authorized to read the |
| 37 | whole source note through the existing note-read path. |
| 38 | |
| 39 | Future section body reads must preserve these rules: |
| 40 | |
| 41 | - A section body read cannot grant more access than `readNote`. |
| 42 | - Missing, unauthorized, deleted, or traversal paths must reveal no more than existing |
| 43 | note-read behavior. |
| 44 | - Hosted behavior must prove active vault and effective canister user isolation before any |
| 45 | hosted exposure. |
| 46 | - Classroom, learner, organization, mentor, guardian, and public contexts require a |
| 47 | separate classroom policy before any section body or snippet leaves the private vault |
| 48 | context. |
| 49 | |
| 50 | ## Body Boundary Decision |
| 51 | |
| 52 | Future body reads may be planned only as full section body reads for one authorized note |
| 53 | and one deterministic section id. |
| 54 | |
| 55 | The future implementation spec must define: |
| 56 | |
| 57 | - maximum returned characters per section body |
| 58 | - maximum requested sections per call |
| 59 | - whether heading text is included with body text |
| 60 | - how sibling and descendant boundaries are handled |
| 61 | - how empty sections are represented |
| 62 | - how deleted or renamed headings invalidate section ids |
| 63 | - how the response prevents line ranges, byte offsets, and body lengths from leaking when |
| 64 | those fields are not required |
| 65 | |
| 66 | Until that future spec is accepted, `body_returned` must remain `false`. |
| 67 | |
| 68 | ## Snippet Boundary Decision |
| 69 | |
| 70 | Snippets are not accepted for `SectionSource v0`. |
| 71 | |
| 72 | A future snippet proposal must be a separate policy because snippets create extra risks: |
| 73 | |
| 74 | - they can leak sensitive content without a deliberate full-note read |
| 75 | - they can be copied into prompts and logs without context |
| 76 | - they can preserve stale private content after the source note changes |
| 77 | - they can expose private learner text in classroom workflows |
| 78 | - they can be mistaken for trusted model instructions |
| 79 | |
| 80 | Until a future snippet policy is accepted, `snippet_returned` must remain `false`. |
| 81 | |
| 82 | ## Redaction Rules |
| 83 | |
| 84 | No automatic redaction is accepted as a substitute for authorization. |
| 85 | |
| 86 | If a future phase returns section body text, redaction must be explicit and tested. The |
| 87 | future implementation spec must define: |
| 88 | |
| 89 | - what is redacted |
| 90 | - whether redaction is deterministic |
| 91 | - whether redaction happens before logging, prompts, persistence, and transport |
| 92 | - how redaction failures are surfaced |
| 93 | - whether redacted output may be exported |
| 94 | - how tests prove secrets, tokens, private keys, classroom identifiers, and protected |
| 95 | learner information are not leaked by derived surfaces |
| 96 | |
| 97 | ## Logging Rules |
| 98 | |
| 99 | Section body text and snippets are not safe to log. |
| 100 | |
| 101 | Future phases must not log: |
| 102 | |
| 103 | - section body text |
| 104 | - snippets |
| 105 | - source excerpts |
| 106 | - full frontmatter |
| 107 | - raw provider payloads |
| 108 | - line ranges or byte offsets if those fields can help reconstruct private content |
| 109 | - classroom or learner private content |
| 110 | |
| 111 | Operational logs may include bounded metadata such as schema name, vault-relative path, |
| 112 | section id, request result class, and elapsed time if those fields are already authorized |
| 113 | for the caller and do not include private body text. |
| 114 | |
| 115 | ## Prompt-Injection Rules |
| 116 | |
| 117 | All note-derived text is untrusted source material. |
| 118 | |
| 119 | Agents, hosted tools, and Scooling adapters must not treat the following as instructions: |
| 120 | |
| 121 | - heading text |
| 122 | - heading path |
| 123 | - future section body text |
| 124 | - future snippets |
| 125 | - future labels |
| 126 | - future summaries |
| 127 | |
| 128 | Tests for any future body or snippet implementation must include note content that asks the |
| 129 | agent to ignore instructions, exfiltrate secrets, bypass review, route data to cloud |
| 130 | providers, disable logging, or expose classroom data. |
| 131 | |
| 132 | ## Deletion, Export, And Staleness |
| 133 | |
| 134 | Phase 1A and Phase 1B derive section sources on demand and do not persist section records. |
| 135 | |
| 136 | Future persisted or indexed section body/snippet work must prove: |
| 137 | |
| 138 | - deleting a note deletes or invalidates all derived section data |
| 139 | - editing a note invalidates stale section boundaries and snippets |
| 140 | - changing a heading updates or invalidates descendant section ids |
| 141 | - exports label section records as derived data |
| 142 | - backups do not depend on stale sidecars to preserve user-authored notes |
| 143 | - restore flows rebuild or discard stale derived records |
| 144 | - hosted vault isolation is preserved across delete, export, backup, and restore |
| 145 | |
| 146 | ## Transport Rules |
| 147 | |
| 148 | This policy does not approve CLI, MCP, hosted MCP, Hub REST, OpenAPI, Hub UI, search, |
| 149 | Scooling, PageIndex, OCR, LLM, or external provider exposure. |
| 150 | |
| 151 | Any transport proposal must first prove: |
| 152 | |
| 153 | - caller authorization |
| 154 | - vault isolation |
| 155 | - no logging of body text or snippets |
| 156 | - no prompt treatment as trusted instructions |
| 157 | - no persistence unless a deletion and export policy is implemented |
| 158 | - seven-tier tests for that specific surface |
| 159 | |
| 160 | ## Scooling Boundary |
| 161 | |
| 162 | Scooling remains a consumer, not the canonical parser or policy owner. |
| 163 | |
| 164 | Scooling must not: |
| 165 | |
| 166 | - parse Markdown as the canonical section parser |
| 167 | - derive canonical section ids |
| 168 | - treat section body text or snippets as trusted instructions |
| 169 | - persist section bodies or snippets as truth |
| 170 | - expose learner section content outside the private authorized context |
| 171 | - bypass Knowtation authorization or human review gates |
| 172 | |
| 173 | When SectionSource body or snippet behavior is unavailable, Scooling must continue using |
| 174 | document-level retrieval or body-free `NoteOutline`, `DocumentTree`, `MetadataFacets`, and |
| 175 | `SectionSource` metadata. |
| 176 | |
| 177 | ## Seven-Tier Test Requirements |
| 178 | |
| 179 | ### Unit |
| 180 | |
| 181 | - Body and snippet flags remain false until a future body/snippet implementation exists. |
| 182 | - Policy constants and response fields are deterministic. |
| 183 | - Body caps, if later implemented, reject invalid values. |
| 184 | |
| 185 | ### Integration |
| 186 | |
| 187 | - Body/snippet policy tests use the same local note-read authorization boundary. |
| 188 | - Missing and traversal paths reveal no extra detail. |
| 189 | - Future body reads do not mutate notes, indexes, sidecars, memory, or summaries. |
| 190 | |
| 191 | ### End To End |
| 192 | |
| 193 | - Agent flows can inspect section candidates without receiving body text. |
| 194 | - Future body-read flows must prove explicit user intent before returning private content. |
| 195 | - Scooling fallback remains body-free when section bodies or snippets are unavailable. |
| 196 | |
| 197 | ### Stress |
| 198 | |
| 199 | - Large notes do not create unbounded output. |
| 200 | - Large section counts remain capped. |
| 201 | - Repeated policy checks are deterministic. |
| 202 | |
| 203 | ### Data Integrity |
| 204 | |
| 205 | - No writes occur during policy checks. |
| 206 | - Deletion, heading edits, and note edits invalidate future persisted derived data. |
| 207 | - Export labels any future persisted section records as derived data. |
| 208 | |
| 209 | ### Performance |
| 210 | |
| 211 | - Policy checks must not scan the whole vault for one-note section requests. |
| 212 | - Future body reads must stay bounded by section count and character caps. |
| 213 | - No external provider calls are allowed in v0. |
| 214 | |
| 215 | ### Security |
| 216 | |
| 217 | - No section body text in current SectionSource output. |
| 218 | - No snippets in current SectionSource output. |
| 219 | - No full frontmatter in current SectionSource output. |
| 220 | - No line ranges, byte offsets, or section body lengths in current SectionSource output. |
| 221 | - Prompt-injection text remains untrusted source material. |
| 222 | - Hosted, Scooling, and classroom exposure remain blocked until separately reviewed. |
| 223 | |
| 224 | ## Acceptance Criteria |
| 225 | |
| 226 | Phase 1C is accepted when: |
| 227 | |
| 228 | - This policy defines who may read section body text. |
| 229 | - This policy explicitly blocks snippets for v0. |
| 230 | - This policy defines body caps, redaction, prompt-injection, logging, export, deletion, |
| 231 | staleness, hosted isolation, and Scooling boundaries for future work. |
| 232 | - Tests prove current SectionSource code still returns no body text or snippets. |
| 233 | - No CLI, MCP, hosted, Hub, search, persistence, Scooling, PageIndex, OCR, LLM, or provider |
| 234 | routing is added. |
| 235 | |
| 236 | ## Recommendation |
| 237 | |
| 238 | Proceed next to body-free Phase 1D transport planning only. Do not implement body reads, |
| 239 | snippets, summaries, search, persistence, hosted exposure, Scooling runtime consumption, or |
| 240 | provider routing until a separate implementation spec and seven-tier test plan is accepted. |