feat(kc): restore public upload and lifecycle APIs (SHD-1073)

README.md

@@ -18,6 +18,10 @@ The following table describes the current environment variables that we use.
 | PORT                  | Yes       | Server bind port (default: `8080`)                               |
 | VECTOR_DB_URL         | Yes       | Vector DB URL (default: `http://localhost:6334`)                 |
 | DATABASE_URL          | Yes       | Database URL used by SQLx tooling/migrations                     |
+| KNOWLEDGE_CENTER_URL | Yes | Optional fixed KC origin; see [upload orchestration](documentation/upload-lifecycle.md) |
+| KNOWLEDGE_CENTER_INTERNAL_TOKEN | With KC | Dedicated internal service bearer secret, at least 32 bytes |
+| S3_WEBHOOK_TOKEN | With KC | Dedicated notification bearer secret, distinct from the internal token and JWT secret |
+| KNOWLEDGE_CENTER_ALLOW_LOCAL_HTTP | Yes | Explicit local HTTP opt-in for KC (default: HTTPS required) |
 | MCP_SERVERS           | Yes       | Static MCP server list as JSON (unset: Kubernetes discovery), see [MCP servers](#mcp-servers) |
 | MCP_NAMESPACE         | Yes       | Namespace watched for MCP pods by Kubernetes discovery           |
 | MCP_LABEL_SELECTOR    | Yes       | Label selector of MCP pods for Kubernetes discovery              |
@@ -112,6 +116,10 @@ KC target participation, dedicated signing and service credentials, fresh collec
 access, targeted admin discovery and supported limits. Ordinary MCP behavior above
 remains the default.
 
+See [collection and upload orchestration](documentation/upload-lifecycle.md) for
+Control Panel API compatibility, KC-owned storage, upload limits and durable
+operation recovery. Ordinary startup remains available without KC.
+
 # Authentication
 
 Users and admins exchange their username and password for a one-hour JWT:

crates/shaide-db/migrations/0004_upload_operations.down.sql

@@ -0,0 +1,3 @@
+-- Explicit downgrade drops only operation fences; settle remote work first.
+DROP TABLE file_operations;
+DROP TABLE collection_operations;

crates/shaide-db/migrations/0004_upload_operations.up.sql

@@ -0,0 +1,30 @@
+-- Durable fences: no lease expiry releases a possibly accepted remote write.
+CREATE TABLE collection_operations (
+    organization_id INTEGER PRIMARY KEY REFERENCES organizations(id),
+    token TEXT NOT NULL UNIQUE,
+    kind TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    state TEXT NOT NULL DEFAULT 'active' CHECK(state IN ('active','recovery_required')),
+    error_code TEXT,
+    created_at TIMESTAMP NOT NULL DEFAULT (DATETIME('now'))
+);
+CREATE TABLE file_operations (
+    file_hash TEXT PRIMARY KEY REFERENCES files(hash),
+    organization_id INTEGER NOT NULL REFERENCES organizations(id),
+    owner_id INTEGER NOT NULL REFERENCES users(id),
+    token TEXT NOT NULL UNIQUE,
+    state TEXT NOT NULL CHECK(state IN ('presigning','reserved','uploading','uploaded','ingesting','deleting','recovery_required')),
+    expires_at INTEGER NOT NULL,
+    query_digest TEXT,
+    event_received BOOLEAN NOT NULL DEFAULT 0,
+    error_code TEXT,
+    created_at TIMESTAMP NOT NULL DEFAULT (DATETIME('now'))
+);
+CREATE INDEX file_operations_organization_id ON file_operations(organization_id);
+
+-- Legacy non-final metadata cannot establish whether a remote write finished.
+-- Preserve the rows and require scoped reconciliation before destructive work.
+INSERT INTO collection_operations (organization_id, token, kind, payload, state, error_code)
+SELECT DISTINCT organization_id, 'migration-0004-' || organization_id,
+       'legacy_recovery', '{}', 'recovery_required', 'legacy_file_outcome_unknown'
+FROM files WHERE status != 'processed';

crates/shaide-db/src/lib.rs

@@ -7,6 +7,7 @@ pub mod error;
 pub mod files;
 pub mod models;
 pub mod organizations;
+pub mod upload_lifecycle;
 mod users;
 
 use std::path::Path;

crates/shaide-db/src/organizations.rs

@@ -85,7 +85,7 @@ async fn select_organization<'e>(
     .ok_or(ShaideDBError::NotFound(Resource::Organization))
 }
 
-async fn ensure_embedding_model_exists(
+pub(crate) async fn ensure_embedding_model_exists(
     transaction: &mut Transaction<'static, Sqlite>,
     embedding_model_id: i64,
 ) -> Result<(), ShaideDBError> {
@@ -105,7 +105,7 @@ async fn ensure_embedding_model_exists(
 /// Adds the users to the organization, skipping existing memberships. Fails
 /// without writing anything else if a user does not exist. Returns the number
 /// of new memberships.
-async fn insert_memberships(
+pub(crate) async fn insert_memberships(
     transaction: &mut Transaction<'static, Sqlite>,
     organization_id: i64,
     user_ids: &[i64],