# Session-Scoped File Upload And Paste-Source Design V01

Issue: #187

## Decision

Session-scoped file upload and paste-source handling should extend the source-grounded assistant as a bounded review input lane, not as durable corpus ingestion.

Uploaded or pasted material is a user-provided session source. It is not approved package corpus, not durable corpus ingestion, and not enterprise source authority unless separately approved through an explicit source-governance path.

The assistant may use uploaded session sources only to interpret, assess, compare, or extract evidence against approved package guidance. Uploaded material must never override package grounding rules, package citation requirements, approval boundaries, deterministic refusal behavior, source registry state, approved source sets, or package authority.

This design defines source identity, extraction, citation, privacy, retention, token/cost, validation, and refusal behavior only. It does not implement runtime upload behavior.

## Source Boundary Model

The future assistant request has three distinct source lanes:

| Source lane | Meaning | Authority | Citation class |
|---|---|---|---|
| Approved package corpus | Repo-reviewed package artifacts, context-pack rows, source maps, grounding rules, and approved reader targets. | Source of record for playbook guidance and package-defined boundaries. | `package citation` |
| Current/public source | Separately approved current or public retrieval source, if enabled by a later mode. | Contextual comparison lane only, not durable package authority by default. | `current/public citation` |
| Uploaded session source | User-uploaded file or pasted text supplied for the active assistant session. | User-provided evidence for the current review only. Not approved package corpus, not durable ingestion, and not enterprise source authority unless separately approved. | `uploaded/session citation` |

Required user-visible label:

```text
User-provided session source. Not approved package corpus. Not durable corpus ingestion. Not enterprise source authority unless separately approved.
```

Package-grounded answers must preserve the package as the source of record. Uploaded files can provide proposal facts, draft claims, architecture decisions, assumptions, missing evidence, and comparison material. They cannot create playbook doctrine.

## Supported Inputs

Initial supported source inputs:

| Input | Allowed use | Extraction behavior |
|---|---|---|
| Plain text `.txt` | Drafts, notes, requirements, review memos. | Decode as UTF-8 with replacement for invalid characters. Preserve line numbers where practical. |
| Markdown `.md` | PRDs, architecture notes, proposals, checklists. | Preserve headings, lists, tables as text, code fences as quoted text, and line anchors where practical. |
| PDF `.pdf` with extractable text | PRDs, vendor proposals, review packets, exported docs. | Extract text pages in order. Preserve page numbers. Refuse scanned/image-only PDFs unless OCR is explicitly designed later. |
| Word `.docx` | Draft docs and proposals. | Extract document text, headings, tables, and list text. Preserve heading and paragraph order. Ignore tracked-change semantics unless a later design adds redline handling. |
| CSV or TSV `.csv`, `.tsv` | Lightweight evidence tables, criteria matrices, source inventories. | Parse as rows and columns, cap cells and rows, preserve header names, and cite row numbers where possible. |
| JSON `.json` | Structured proposal facts, metadata, or review fixtures. | Parse as JSON, summarize object paths, cap depth and value length, and cite JSON pointer-like paths where possible. |
| Paste-source text | Small inline source material supplied by the user. | Treat as an uploaded/session source with an explicit title, timestamp, and content hash preview if implemented later. |

Unsupported initial inputs:

- executable files, scripts, archives, folders, email boxes, binaries, images, audio, video, encrypted files, password-protected files, malformed files, remote URLs as upload substitutes, and connector payloads
- scanned PDFs or images requiring OCR
- files whose extraction requires external retrieval, external conversion services, macros, plugins, or network calls
- private enterprise sources unless the user explicitly supplies them inside the approved session-source boundary and the future deployment privacy model allows that data class

## Size Limits

Initial limits should be conservative and visible before submission:

| Limit | Requirement |
|---|---|
| Per paste-source input | 25,000 characters before extraction. |
| Per text or Markdown file | 1 MB raw file size. |
| Per PDF or DOCX file | 5 MB raw file size and 75 extracted pages or sections. |
| Per CSV, TSV, or JSON file | 2 MB raw file size, 5,000 rows, 100 columns, and 250,000 extracted characters. |
| Per session | 5 files plus one paste-source input, 20 MB total raw input, and 120,000 extracted characters before source selection. |
| Per assistant request | Only the selected excerpts that fit the token budget may be sent to the model. |

The UI or request builder should show rejected files before provider execution. Later implementations may revise these limits only with validation updates, cost controls, and privacy review.

## Token Limits

Uploaded session sources need separate token accounting from package context.

Minimum token-budget fields:

- `package_context_tokens`
- `uploaded_session_source_tokens`
- `current_public_source_tokens`
- `user_prompt_tokens`
- `system_instruction_tokens`
- `completion_tokens`
- `total_tokens`
- `estimated_cost`
- `selected_uploaded_source_count`
- `selected_uploaded_source_token_count`
- `truncated_uploaded_source_count`
- `refused_uploaded_source_count`

Default allocation rule:

```text
Package grounding gets first claim authority.
Uploaded session source gets proposal/evidence context.
The assistant must refuse or ask for narrowing when both cannot fit safely.
```

The request builder should prefer cited excerpts over whole-file inclusion. It should summarize or chunk only after preserving source identity, page/line/row anchors, and extraction confidence.

## Parsing And Extraction Behavior

Extraction should be deterministic before model execution.

Required extracted-source record:

```json
{
  "source_class": "uploaded_session_source",
  "session_source_id": "session-file-001",
  "display_title": "Draft PRD.pdf",
  "file_type": "pdf",
  "raw_size_bytes": 524288,
  "extracted_character_count": 18000,
  "estimated_tokens": 4500,
  "extraction_method": "local_text_extract",
  "extraction_confidence": "high | partial | refused",
  "anchors_available": ["page", "line", "row", "json_path"],
  "classification_label": "user-provided session source; not approved package corpus; not durable corpus ingestion; not enterprise source authority unless separately approved",
  "retention": "session_only"
}
```

Extraction rules:

- Parse locally inside the approved runtime boundary.
- Do not call external conversion or retrieval services.
- Do not execute macros, embedded scripts, formulas, links, or attachments.
- Normalize text for search and source selection, but preserve original anchor references where practical.
- Mark extraction confidence as `partial` when tables, layout, footnotes, embedded objects, or unsupported structures may be incomplete.
- Refuse the file when extraction confidence is too low to support citation.
- Never silently promote extracted text into the approved corpus, context-pack, source registry, current-source registry, durable memory, or public docs.

## User-Visible Source Identity

Every uploaded or pasted source must display:

- source title supplied by the user or derived from the filename
- source class: `User-provided session source`
- file type or paste-source type
- extraction status: accepted, partially extracted, truncated, or refused
- raw size and extracted length
- token estimate
- retention label: `Session only`
- authority label: `Not approved package corpus`
- citation label: `Uploaded/session citation`

The answer surface should not merge uploaded sources into package-source lists. A structured review should show separate evidence sections:

1. Package says
2. Uploaded session source says
3. Assessment or synthesis
4. Missing evidence or owner decision needed

## Citation Behavior

Uploaded files must be cited separately from approved package sources.

Uploaded/session citation fields:

- `citation_class`: `uploaded/session citation`
- `source_class`: `uploaded_session_source`
- `session_source_id`
- `display_title`
- `file_type`
- `page`, `line_range`, `row_number`, `column_name`, or `json_path` where available
- `extraction_confidence`
- `retention`: `session_only`
- `authority_note`: `User-provided session source. Not approved package corpus.`

Citation rules:

- Use package citations for package guidance, criteria, doctrine, and refusal rules.
- Use uploaded/session citations for claims about the uploaded draft, PRD, proposal, evidence table, or pasted source.
- Do not let uploaded/session citations satisfy a requirement for approved package support.
- Do not cite uploaded material as current/public source evidence.
- Do not cite uploaded material as enterprise policy, approval, or source authority unless a separate approved-source workflow later promotes it.
- When package and uploaded source conflict, state the conflict and identify which claim came from which lane.

## Privacy Notice

Future UI or request text should show a notice before upload:

```text
Files and pasted text are used only as user-provided session sources for this assistant run. They are not added to the approved package corpus, not published, not durable source ingestion, and not enterprise source authority unless a separate approved source process is completed. Do not upload secrets, credentials, regulated data, or material you are not allowed to share with this assistant environment.
```

If a deployment later adds durable telemetry, saved sessions, enterprise audit logs, or file retention, that requires a separate design, visible notice, and validation update before activation.

## Retention And Non-Retention Boundary

Default retention posture:

- Keep uploaded file bytes and extracted text in active session memory only.
- Delete or discard uploaded bytes and extracted text at session end, browser refresh boundary, or configured runtime cleanup boundary.
- Do not store uploaded content in Git, context-pack, docs, releases, source registries, current-source registries, vector stores, search indexes, object stores, databases, telemetry logs, issue comments, pull requests, validation receipts, public mirrors, or model memory.
- If debugging needs metadata, store only non-content metadata unless separately approved: count, type, size, token estimate, extraction status, refusal reason, and citation count.
- Do not expose uploaded content publicly.

Non-retention does not mean the model provider retains nothing. A future runtime must disclose provider-side data handling according to the deployment's approved provider terms and enterprise policy.

## Token And Cost Accounting

Token and cost reporting should separate package context from uploaded session source context.

Minimum run summary:

| Field | Requirement |
|---|---|
| Package tokens | Count selected approved package excerpts separately. |
| Uploaded tokens | Count selected uploaded-session excerpts separately. |
| Truncation | Report whether uploaded material was truncated before provider execution. |
| Refusals | Report unsupported file, oversize file, low-confidence extraction, privacy boundary, and insufficient package support. |
| Cost estimate | Attribute estimated cost to package context, uploaded context, prompt, and completion when available. |
| Citation counts | Show package citation count and uploaded/session citation count separately. |

The assistant should refuse or ask the user to narrow files when token limits would force uncited, low-confidence, or misleading use of uploaded content.

## Validation And Refusal Behavior

Refuse before provider execution when:

- file type is unsupported
- file size, page count, row count, character count, or token estimate exceeds limits
- file is encrypted, password-protected, malformed, executable, archived, binary, image-only, or requires OCR
- extraction confidence is too low for citation
- the user asks the assistant to treat uploaded material as approved package corpus
- the user asks for durable ingestion, source registry mutation, approved source-set mutation, package-authority change, database storage, vector-store storage, Supabase storage, external retrieval, or public exposure
- the question lacks approved package support where package grounding is required
- the request asks for enterprise approval, policy approval, production approval, legal approval, security approval, data approval, GxP readiness, vendor approval, or tool approval not present in approved sources

Expected refusal language:

```text
I can use uploaded material only as a user-provided session source. It is not approved package corpus, not durable corpus ingestion, and not enterprise source authority unless separately approved.
```

Validation expectations:

- focused validator checks the design coverage, required classification labels, citation separation, privacy and retention boundaries, token/cost fields, supported and refused file types, use cases, non-goals, discoverability, receipt, and context-pack inclusion
- source-grounded assistant validators continue to prove package-only refusal and citation behavior
- context-pack validators prove generated package and docs mirrors include the note without changing package authority
- smoke expectations for a future runtime must cover accepted text/Markdown, refused unsupported file, oversize refusal, low-confidence extraction refusal, separate citation rendering, token/cost separation, and no durable storage side effects

## Expected Use Cases

The design explicitly covers these requested use cases:

- assess a draft PRD against the playbook
- assess a POC proposal against build-readiness guidance
- compare an architecture proposal to the Enterprise Architecture Review Assistant
- extract missing evidence or unanswered questions
- generate a structured review using package guidance plus uploaded user source

### Assess A Draft PRD Against The Playbook

Use package citations for playbook criteria and uploaded/session citations for PRD claims. Output a review with pass, concern, blocker, missing evidence, and not covered findings. Do not approve the PRD.

### Assess A POC Proposal Against Build-Readiness Guidance

Use the uploaded POC proposal as evidence. Compare it with approved build-readiness and operating-discipline guidance. Identify missing evidence, owner decisions, risks, and follow-up questions.

### Compare An Architecture Proposal To The Enterprise Architecture Review Assistant

Use the uploaded architecture proposal for proposal facts and cite the Enterprise Architecture Review Assistant package material for review criteria. Separate package guidance from uploaded proposal claims.

### Extract Missing Evidence Or Unanswered Questions

Identify fields, controls, owners, evaluation evidence, source authority, data classes, risk posture, validation plan, and sustainment details missing from the uploaded session source. Cite the uploaded source when showing what was present or absent.

### Generate A Structured Review Using Package Guidance Plus Uploaded User Source

Generate a review packet with source-lane sections, citation classes, missing-evidence list, refusal or narrowing notes, token/cost summary, and derivative-output label. The output remains generated review assistance, not source evidence or approval.

## Relationship To Approved Package Corpus

The approved package corpus remains the grounding authority.

Uploaded session sources:

- can supply the object being reviewed
- can supply user-provided facts for the active session
- can be cited as uploaded/session evidence
- can help identify missing evidence and unanswered questions

Uploaded session sources cannot:

- become approved corpus by upload
- become durable corpus ingestion
- mutate source registries or approved source sets
- override package grounding rules
- replace package citations
- create enterprise source authority
- approve tools, vendors, data classes, workflows, production use, policy, security posture, legal posture, regulatory posture, or GxP readiness

## Non-Goals

This design does not:

- create durable file ingestion
- add a database
- add a vector store
- add Supabase
- add an external retrieval service
- treat uploaded material as approved corpus
- expose uploaded content publicly
- store user files beyond the session
- allow uploaded material to override package grounding rules
- implement runtime upload behavior
- change source-grounded chat runtime behavior
- change provider/model configuration
- change Cloudflare configuration
- use Cloudflare CLI or API
- mutate source registries
- mutate approved source sets
- change package authority
- reopen #269
- reopen #271
- apply `codex-automerge`

## Acceptance Criteria Mapping

| Criterion | Design location |
|---|---|
| A design exists for session-scoped file upload/paste sources. | This document. |
| Uploaded source identity and citation behavior are defined. | Source Boundary Model, User-Visible Source Identity, Citation Behavior. |
| Token/cost tracking requirements are defined. | Token Limits, Token And Cost Accounting. |
| Privacy and retention boundaries are explicit. | Privacy Notice, Retention And Non-Retention Boundary. |
| Validation and smoke expectations are defined. | Validation And Refusal Behavior. |
| PR is opened and not automerged. | Validation receipt and PR closeout. |