refactor(api): migrate v2 knowledge operations

[TheodoreSpeaks]

Summary

• defines the complete semantic knowledge operation registry and authorized application use cases for knowledge bases, folders, documents, search, and multipart upload controls
• migrates all v2 knowledge routes to declarative JSON routes or lifecycle-specific bounded admission, with canonical workspace scoping and shared semantic audit
• adds immutable credential-bound upload sessions, fresh authorization on every control/finalization leg, current billing attribution at registration, and idempotent completion without a DB migration
• delegates trusted Copilot knowledge, VFS, and open-resource callers through the same use cases; migrates internal knowledge upload controls
• adds explicit workspace/folder/document bounds and focused principal, concealment, billing, audit, idempotency, delegation, and infrastructure-failure coverage

Deferred / non-goals

• deferred legacy internal JWT knowledge list/detail/search/document adapters whose signed context lacks authoritative workspace, audience, delegation, and execution claims
• deferred pre-tool Copilot chat knowledge context resolution because that lifecycle has no server-issued tool delegation identity
• left v1, generic folder restore/reorder/duplicate, advanced internal search, tags, connectors, chunks, upsert, bulk document actions, and unrelated v2 resource families unchanged
• no database migration required

Validation

• focused Vitest: 27 files, 283 tests passed
• Biome: 70 touched source/test files passed
• Sim type-check passed
• @sim/auth type-check passed
• bun run lint passed
• bun run check:api-validation passed
• bun run check:api-validation:strict passed
• agent stream docs and skills sync unchanged
• git diff --check passed

Notes

The direct multipart document upload remains outside the ordinary JSON lifecycle so authorization and quota admission happen before bounded body acquisition, followed by fresh authorization and billing attribution at durable registration. Search retains the v2 vector-only behavior and existing bounds/response shape.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 8, 2026 6:21pm

[cursor]

PR Summary

Medium Risk
Touches authorization, billing admission, upload finalization, and analytics across public API and Copilot paths; behavior is heavily tested but regressions in workspace scoping or idempotent completion would affect document ingestion.

Overview
Moves knowledge bases, folders, documents, search, and multipart uploads off route-local orchestration into lib/knowledge/application use cases registered via knowledgeOperations, with principals (session, API key, delegated Copilot) and shared billing/context resolution.

v2 handlers switch to defineV2JsonRoute (or lifecycle-specific admission for multipart upload/search); read paths still mask 403 as NOT_FOUND where that invariant existed. Internal UI upload routes call the same upload-session use cases with session principals and sessionId on the actor.

Upload path: quota admission before buffering on v2 multipart POST; usageAdmission: 'pre_admitted' on durable registration; completion analytics (PostHog / platform events) only when created is true so retries do not double-count. v2 contracts explicitly declare 201 for create responses.

Copilot open-resource and VFS mutate/rm paths use executeCopilotKnowledgeUseCase with tool-call delegation instead of direct service/API utils; infrastructure failures propagate, actionable orchestration errors stay user-facing.

^{Reviewed by Cursor Bugbot for commit 7216d96. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

The PR migrates v2 knowledge operations to shared authorized use cases and strengthens multipart upload completion and recovery.

• Routes knowledge-base, folder, document, search, and upload operations through declarative authorization and audit infrastructure.
• Binds upload sessions to credentials and workspace scope, reauthorizes control and finalization requests, and attributes billing at durable registration.
• Preserves failed processing dispatches as retriable finalization state and makes completion idempotent without a database migration.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

The previously reported processing-dispatch failure is now awaited, leaves the upload in retriable finalizing state, and is retried only for the exact bound pending document.

Important Files Changed

Filename	Overview
apps/sim/lib/knowledge/application/upload-sessions.ts	Adds credential-bound upload authorization, durable registration, awaited processing dispatch, and recovery of failed dispatches without reproducing the previously reported stuck-document path.
apps/sim/lib/uploads/upload-session/service.ts	Implements lease-scoped upload completion transitions that serialize finalization and preserve retriable failure state.
apps/sim/app/api/v2/knowledge/[id]/documents/route.ts	Migrates document listing and bounded multipart upload admission to the shared v2 route and knowledge-use-case infrastructure.
apps/sim/lib/knowledge/application/operations.ts	Defines the semantic knowledge operation registry used by routes and delegated callers.
apps/sim/lib/knowledge/application/authorized-knowledge-use-case.ts	Centralizes principal authorization, workspace scoping, and semantic audit behavior for knowledge operations.

Sequence Diagram

sequenceDiagram
participant Client
participant Route as Upload completion route
participant UseCase as Authorized completion use case
participant Session as Upload-session state
participant Docs as Knowledge documents
participant Queue as Processing queue
Client->>Route: Complete upload
Route->>UseCase: Execute with authenticated principal
UseCase->>Session: Claim completion lease
Session-->>UseCase: finalizing session
UseCase->>Docs: Find or register bound document
UseCase->>Queue: Await processing dispatch
alt Dispatch accepted
Queue-->>UseCase: Accepted
UseCase->>Session: Mark completed
UseCase-->>Route: Document result
Route-->>Client: Success
else Every dispatch fails
Queue-->>UseCase: Failure
UseCase->>Session: Persist failure and remain finalizing
Route-->>Client: Failure
Client->>Route: Retry completion
Route->>UseCase: Execute with fresh authorization
UseCase->>Session: Claim recovery lease
UseCase->>Docs: Load exact bound pending document
UseCase->>Queue: Retry processing dispatch
end

Loading

_{Reviews (4): Last reviewed commit: "Merge remote-tracking branch 'origin/imp..." | Re-trigger Greptile}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 8a5cea9. Configure here.}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 7216d96. Configure here.}