feat(rag): implement zero-downtime KB update framework with system config management (#275)

## Because

- **System configuration updates require zero-downtime**: RAG systems
need to update embedding models/configurations without service
interruption or data loss
- **Multi-tenant systems need audit trails**: System administrators need
visibility into which embedding system each KB is using and historical
changes
- **Rollback capability is critical**: Production systems require the
ability to revert to previous configurations if updates fail or cause
issues
- **Test reliability must be deterministic**: Integration tests were
flaky due to race conditions, zombie resources, and incomplete error
handling

## This commit

### 🎯 Core Framework: Zero-Downtime KB Update System

- **Implements 6-phase staging-based update workflow** (Prepare →
Reprocess → Synchronize → Validate → Swap → Cleanup) that enables live
system configuration changes without downtime
- **Adds dual-processing mechanism** where files uploaded during updates
are processed for both production and target (staging/rollback) KBs to
prevent data loss
- **Implements atomic 3-step resource swap** using temporary UID to
exchange resources between KBs while keeping production KB UID constant
for ACL preservation
- **Adds rollback retention system** with configurable retention periods
and automatic/manual cleanup workflows for rollback KBs

### 🔧 System Configuration Management API

- **Adds new `System` database table and models** (migration 000037) to
manage embedding configurations as first-class entities with UID and ID
- **Implements `ExecuteKnowledgeBaseUpdate` admin API** to trigger
system-wide or selective KB updates to new system configurations
- **Implements `GetKnowledgeBaseUpdateStatusAdmin` API** to monitor
update progress across all KBs with status details, error messages,
current/previous system IDs
- **Implements `SetRollbackRetentionAdmin` API** to dynamically adjust
rollback retention periods with flexible time units
(seconds/minutes/hours/days)
- **Implements `PurgeRollbackAdmin` API** for immediate manual cleanup
of rollback KBs
- **Implements `AbortKnowledgeBaseUpdateAdmin` API** to safely cancel
in-progress updates with proper staging KB cleanup
- **Adds `system_uid` foreign key to KB table** linking each KB to its
embedding system for audit trails and update tracking
- **Adds `previous_system_uid` tracking** to record the system before
updates/rollbacks for historical audit

### 📊 Database Schema Changes

- **Migration 000037**: Renames `embedding_config` to `system_config`,
adds `system_uid` and `previous_system_uid` to KB table, adds
`update_error_message` for failure diagnostics
- **Adds `rollback_retention_until` timestamp field** for per-KB
retention customization
- **Implements atomic transactional deletion** with row-level locking
(`SELECT ... FOR UPDATE`) to prevent TOCTOU race conditions

### 🐛 Critical Bug Fixes

- **Fixes workflow defer block to ALWAYS set terminal status** even when
staging KB creation fails, preventing tests from timing out waiting for
status updates
- **Fixes teardown to only wait for production KB workflows** (not
staging KBs), eliminating false "workflows still running" messages
- **Fixes `SetRollbackRetentionAdmin` to update rollback KB retention**
(not production KB) so cleanup workflows check the correct field
- **Fixes `RescheduleCleanupWorkflow` to use `TerminateWorkflow`**
instead of `CancelWorkflow` for synchronous termination before starting
new workflow
- **Implements explicit hard-delete for staging KB cleanup** in
`CleanupOldKnowledgeBaseActivity` to remove zombie files (soft-delete
doesn't cascade)
- **Implements hard-delete in `DeleteAllKnowledgeBaseFiles`** using
`Unscoped()` for physical file removal during cleanup

### 🧹 Code Quality & Maintenance

- **Removes all deprecated file process statuses**
(`FILE_PROCESS_STATUS_CONVERTING`, `FILE_PROCESS_STATUS_WAITING`,
`FILE_PROCESS_STATUS_SUMMARIZING`) from codebase and tests
- **Reverts preset pipeline initialization method** (from commit
[`89d528f`](89d528f))
to fix initialization race conditions
- **Optimizes `GetKnowledgeBaseUpdateStatusAdmin` API** to pre-fetch
systems into cache, eliminating N+1 query problem
- **Renames `upgrade` terminology to `update`** throughout codebase for
consistency (upgradeCompleted → updateCompleted)

Author: pinglin

Dockerfile

@@ -33,6 +33,12 @@ RUN --mount=type=bind,target=. \
     go build -ldflags "-X main.serviceVersion=${SERVICE_VERSION} -X main.serviceName=${SERVICE_NAME}-worker" \
     -o /${SERVICE_NAME}-worker ./cmd/worker
 
+RUN --mount=type=bind,target=. \
+    --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/root/.cache/go-build \
+    GOOS=$TARGETOS GOARCH=$TARGETARCH CGO_ENABLED=0 \
+    go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
+
 FROM golang:${GOLANG_VERSION}
 
 USER nobody:nogroup
@@ -45,6 +51,7 @@ COPY --from=build --chown=nobody:nogroup /${SERVICE_NAME}-migrate ./
 COPY --from=build --chown=nobody:nogroup /${SERVICE_NAME}-init ./
 COPY --from=build --chown=nobody:nogroup /${SERVICE_NAME}-worker ./
 COPY --from=build --chown=nobody:nogroup /${SERVICE_NAME} ./
+COPY --from=build --chown=nobody:nogroup /go/bin/grpcurl /usr/local/bin/
 
 COPY --chown=nobody:nogroup ./config ./config
 COPY --chown=nobody:nogroup ./pkg/db/migration ./pkg/db/migration

Dockerfile.dev

@@ -16,6 +16,9 @@ ARG TARGETOS TARGETARCH K6_VERSION XK6_VERSION XK6_SQL_VERSION XK6_SQL_POSTGRES_
 # air
 RUN --mount=target=. --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/go/pkg GOOS=$TARGETOS GOARCH=$TARGETARCH go install github.com/cosmtrek/air@v1.49.0
 
+# grpcurl
+RUN --mount=target=. --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/go/pkg GOOS=$TARGETOS GOARCH=$TARGETARCH go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
+
 # k6
 RUN --mount=target=. --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/go/pkg GOOS=$TARGETOS GOARCH=$TARGETARCH go install go.k6.io/xk6/cmd/xk6@v${XK6_VERSION}
 RUN --mount=target=. --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/go/pkg GOOS=$TARGETOS GOARCH=$TARGETARCH xk6 build v${K6_VERSION} \

Makefile

@@ -104,8 +104,10 @@ integration-test:		## Run integration tests in parallel using GNU parallel
 		integration-test/rest-kb-e2e-file-process.js \
 		integration-test/rest-file-reprocess.js \
 		integration-test/rest-kb-delete.js \
-		integration-test/grpc-kb-update.js 2>&1 | tee /tmp/artifact-integration-test.log; \
-	bash integration-test/report-summary.sh /tmp/artifact-integration-test.log
+		integration-test/grpc-kb-update.js \
+		integration-test/grpc-system-config-update.js \
+		integration-test/grpc-system-admin.js 2>&1 | tee /tmp/artifact-integration-test.log; \
+	bash integration-test/scripts/report-summary.sh /tmp/artifact-integration-test.log
 
 .PHONY: help
 help:       	 				## Show this help

cmd/init/main.go

@@ -60,7 +60,7 @@ func main() {
 	defer cancel()
 	ctx = metadata.AppendToOutgoingContext(ctx, "Instill-Service", "instill")
 
-	upserter := &pipeline.PipelineReleaseUpserter{
+	upserter := &pipeline.ReleaseUpserter{
 		FS:                          pipeline.PresetPipelinesFS,
 		PipelinePublicServiceClient: pipelinePublicServiceClient,
 	}

cmd/worker/main.go

@@ -177,6 +177,7 @@ func main() {
 	w.RegisterActivity(cw.DeleteKBEmbeddingRecordsActivity)     // Delete all embedding records
 	w.RegisterActivity(cw.SoftDeleteKBRecordActivity)           // Soft-delete the KB record itself
 	w.RegisterActivity(cw.PurgeKBACLActivity)                   // Remove all ACL permissions for KB
+	w.RegisterActivity(cw.ClearProductionKBRetentionActivity)   // Clear retention field on production KB after rollback cleanup
 
 	// ===== RAG update activities =====
 	// Activities for knowledge base update workflow (6-phase)
@@ -197,6 +198,7 @@ func main() {
 
 	// File Metadata and Setup Phase
 	w.RegisterActivity(cw.GetFileMetadataActivity)                // Fetch file metadata from database
+	w.RegisterActivity(cw.FindTargetFileByNameActivity)           // Find target file for dual-processing coordination
 	w.RegisterActivity(cw.GetFileContentActivity)                 // Retrieve file binary content from MinIO
 	w.RegisterActivity(cw.DeleteOldConvertedFilesActivity)        // Remove previous conversion artifacts
 	w.RegisterActivity(cw.CreateConvertedFileRecordActivity)      // Create DB record for converted file

go.mod

@@ -13,10 +13,12 @@ require (
 	github.com/google/go-cmp v0.7.0
 	github.com/grpc-ecosystem/go-grpc-middleware v1.4.0
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.1
-	github.com/instill-ai/protogen-go v0.3.3-alpha.0.20251021120500-309474e9c8c4
+	github.com/iancoleman/strcase v0.3.0
+	github.com/instill-ai/protogen-go v0.3.3-alpha.0.20251025213338-ef545c5cfb61
 	github.com/instill-ai/usage-client v0.4.0
 	github.com/instill-ai/x v0.10.1-alpha
 	github.com/knadh/koanf v1.5.0
+	github.com/mennanov/fieldmask-utils v1.1.2
 	github.com/milvus-io/milvus-sdk-go/v2 v2.4.2
 	github.com/minio/minio-go/v7 v7.0.92
 	github.com/openai/openai-go/v3 v3.4.0
@@ -147,6 +149,7 @@ require (
 	golang.org/x/sys v0.33.0 // indirect
 	golang.org/x/text v0.26.0 // indirect
 	golang.org/x/time v0.11.0 // indirect
+	google.golang.org/genproto v0.0.0-20250303144028-a0af3efb3deb // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20250603155806-513f23925822 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250603155806-513f23925822 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

go.sum

@@ -67,7 +67,11 @@ github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XL
 github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
 github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
 github.com/cncf/udpa/go v0.0.0-20201120205902-5459f2c99403/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk=
+github.com/cncf/udpa/go v0.0.0-20210930031921-04548b0d99d4/go.mod h1:6pvJx4me5XPnfI9Z40ddWsdw2W/uZgQLFXToKeRcDiI=
 github.com/cncf/xds/go v0.0.0-20210312221358-fbca930ec8ed/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs=
+github.com/cncf/xds/go v0.0.0-20210922020428-25de7278fc84/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs=
+github.com/cncf/xds/go v0.0.0-20211001041855-01bcc9b48dfe/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs=
+github.com/cncf/xds/go v0.0.0-20211011173535-cb28da3451f1/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs=
 github.com/cockroachdb/datadriven v1.0.2/go.mod h1:a9RdTaap04u637JoCzcUoIcDmvwSUtcUFtT/C3kJlTU=
 github.com/cockroachdb/errors v1.9.1 h1:yFVvsI0VxmRShfawbt/laCIDy/mtTqqnvoNgiy5bEV8=
 github.com/cockroachdb/errors v1.9.1/go.mod h1:2sxOtL2WIc096WSZqZ5h8fa17rdDq9HZOZLBCor4mBk=
@@ -113,6 +117,7 @@ github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1m
 github.com/envoyproxy/go-control-plane v0.9.9-0.20201210154907-fd9021fe5dad/go.mod h1:cXg6YxExXjJnVBQHBLXeUAgxn2UodCpnH306RInaBQk=
 github.com/envoyproxy/go-control-plane v0.9.9-0.20210217033140-668b12f5399d/go.mod h1:cXg6YxExXjJnVBQHBLXeUAgxn2UodCpnH306RInaBQk=
 github.com/envoyproxy/go-control-plane v0.9.9-0.20210512163311-63b5d3c536b0/go.mod h1:hliV/p42l8fGbc6Y9bQ70uLwIvmJyVE5k4iMKlh8wCQ=
+github.com/envoyproxy/go-control-plane v0.10.2-0.20220325020618-49ff273808a1/go.mod h1:KJwIaB5Mv44NWtYuAOFCVOjcI94vtpEz2JU/D2v6IjE=
 github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
 github.com/envoyproxy/protoc-gen-validate v1.2.1 h1:DEo3O99U8j4hBFwbJfrz9VtgcDfUKS7KJ7spH3d86P8=
 github.com/envoyproxy/protoc-gen-validate v1.2.1/go.mod h1:d/C80l/jxXLdfEIhX1W2TmLfsJ31lvEjwamM4DxlWXU=
@@ -299,10 +304,12 @@ github.com/hjson/hjson-go/v4 v4.0.0 h1:wlm6IYYqHjOdXH1gHev4VoXCaW20HdQAGCxdOEEg2
 github.com/hjson/hjson-go/v4 v4.0.0/go.mod h1:KaYt3bTw3zhBjYqnXkYywcYctk0A2nxeEFTse3rH13E=
 github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
 github.com/hydrogen18/memlistener v0.0.0-20200120041712-dcc25e7acd91/go.mod h1:qEIFzExnS6016fRpRfxrExeVn2gbClQA99gQhnIcdhE=
+github.com/iancoleman/strcase v0.3.0 h1:nTXanmYxhfFAMjZL34Ov6gkzEsSJZ5DbhxWjvSASxEI=
+github.com/iancoleman/strcase v0.3.0/go.mod h1:iwCmte+B7n89clKwxIoIXy/HfoL7AsD47ZCWhYzw7ho=
 github.com/imkira/go-interpol v1.1.0/go.mod h1:z0h2/2T3XF8kyEPpRgJ3kmNv+C43p+I/CoI+jC3w2iA=
 github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
-github.com/instill-ai/protogen-go v0.3.3-alpha.0.20251021120500-309474e9c8c4 h1:tEPHqGxFwKeHEm3OhZ+WLRRmQ9BY0i1u48VNO59N0oY=
-github.com/instill-ai/protogen-go v0.3.3-alpha.0.20251021120500-309474e9c8c4/go.mod h1:bCnBosofpaUxKBuTTJM3/I3thAK37kvfBnKByjnLsl4=
+github.com/instill-ai/protogen-go v0.3.3-alpha.0.20251025213338-ef545c5cfb61 h1:lF9/5s8EjAldcIQYA8XtiET/5v/lqrL3c2TbaBJqeOA=
+github.com/instill-ai/protogen-go v0.3.3-alpha.0.20251025213338-ef545c5cfb61/go.mod h1:bCnBosofpaUxKBuTTJM3/I3thAK37kvfBnKByjnLsl4=
 github.com/instill-ai/usage-client v0.4.0 h1:xf1hAlO4a8lZwZzz9bprZOJqU3ghIcIsavUUB7UURyg=
 github.com/instill-ai/usage-client v0.4.0/go.mod h1:zZ9LRoXps2u63ARYPAbR2YvqTib3dWJLObZn+9YqhF0=
 github.com/instill-ai/x v0.10.1-alpha h1:15+SntJqoh1ab+QhS8OdoagyUMhR8NU4UV12Xt43qmo=
@@ -409,6 +416,8 @@ github.com/mattn/go-sqlite3 v1.14.16/go.mod h1:2eHXhiwb8IkHr+BDWZGa96P6+rkvnG63S
 github.com/mattn/goveralls v0.0.2/go.mod h1:8d1ZMHsd7fW6IRPKQh46F2WRpyib5/X4FOpevwGNQEw=
 github.com/matttproud/golang_protobuf_extensions v1.0.1/go.mod h1:D8He9yQNgCq6Z5Ld7szi9bcBfOoFv/3dc6xSMkL2PC0=
 github.com/mediocregopher/radix/v3 v3.4.2/go.mod h1:8FL3F6UQRXHXIBSPUs5h0RybMF8i4n7wVopoX3x7Bv8=
+github.com/mennanov/fieldmask-utils v1.1.2 h1:f5hd3hYeWdl+q2thiKYyZZmqTqn90uayWG03bca9U+E=
+github.com/mennanov/fieldmask-utils v1.1.2/go.mod h1:xRqd9Fjz/gFEDYCQw7pxGouxqLhSPrkOdx2yhEAXEls=
 github.com/microcosm-cc/bluemonday v1.0.2/go.mod h1:iVP4YcDBq+n/5fb23BhYFvIMq/leAFZyRl6bYmGDlGc=
 github.com/microsoft/go-mssqldb v1.7.2 h1:CHkFJiObW7ItKTJfHo1QX7QBBD1iV+mn1eOyRP3b/PA=
 github.com/microsoft/go-mssqldb v1.7.2/go.mod h1:kOvZKUdrhhFQmxLZqbwUV0rHkNkZpthMITIb2Ko1IoA=
@@ -782,6 +791,7 @@ golang.org/x/sys v0.0.0-20200615200032-f1bc736245b1/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20200625212154-ddb9806d33ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210119212857-b64e53b001e4/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210303074136-134d130e1a04/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -858,6 +868,9 @@ google.golang.org/genproto v0.0.0-20200526211855-cb27e3aa2013/go.mod h1:NbSheEEY
 google.golang.org/genproto v0.0.0-20210602131652-f16073e35f0c/go.mod h1:UODoCrxHCcBojKKwX1terBiRUaqAsFqJiF615XL43r0=
 google.golang.org/genproto v0.0.0-20210624195500-8bfb893ecb84/go.mod h1:SzzZ/N+nwJDaO1kznhnlzqS8ocJICar6hYhVyhi++24=
 google.golang.org/genproto v0.0.0-20210909211513-a8c4777a87af/go.mod h1:eFjDcFEctNawg4eG61bRv87N7iHBWyVhJu7u1kqDUXY=
+google.golang.org/genproto v0.0.0-20220531173845-685668d2de03/go.mod h1:yKyY4AMRwFiC8yMMNaMi+RkCnjZJt9LoWuvhXjMs+To=
+google.golang.org/genproto v0.0.0-20250303144028-a0af3efb3deb h1:ITgPrl429bc6+2ZraNSzMDk3I95nmQln2fuPstKwFDE=
+google.golang.org/genproto v0.0.0-20250303144028-a0af3efb3deb/go.mod h1:sAo5UzpjUwgFBCzupwhcLcxHVDK7vG5IqI30YnwX2eE=
 google.golang.org/genproto/googleapis/api v0.0.0-20250603155806-513f23925822 h1:oWVWY3NzT7KJppx2UKhKmzPq4SRe0LdCijVRwvGeikY=
 google.golang.org/genproto/googleapis/api v0.0.0-20250603155806-513f23925822/go.mod h1:h3c4v36UTKzUiuaOKQ6gr3S+0hovBtUrXzTG/i3+XEc=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20250603155806-513f23925822 h1:fc6jSaCT0vBduLYZHYrBBNY4dsWuvgyff9noRNDdBeE=
@@ -874,6 +887,7 @@ google.golang.org/grpc v1.33.1/go.mod h1:fr5YgcSWrqhRRxogOsw7RzIpsmvOZ6IcH4kBYTp
 google.golang.org/grpc v1.36.0/go.mod h1:qjiiYl8FncCW8feJPdyg3v6XW24KsRHe+dy9BAGRRjU=
 google.golang.org/grpc v1.38.0/go.mod h1:NREThFqKR1f3iQ6oBuvc5LadQuXVGo9rkm5ZGrQdJfM=
 google.golang.org/grpc v1.40.0/go.mod h1:ogyxbiOoUXAkP+4+xa6PZSE9DZgIHtSpzjDTB9KAK34=
+google.golang.org/grpc v1.46.2/go.mod h1:vN9eftEi1UMyUsIF80+uQXhHjbXYbm0uXoFCACuMGWk=
 google.golang.org/grpc v1.73.0 h1:VIWSmpI2MegBtTuFt5/JWy2oXxtjJ/e89Z70ImfD2ok=
 google.golang.org/grpc v1.73.0/go.mod h1:50sbHOUqWoCQGI8V2HQLJM0B+LMlIUjNSZmow7EVBQc=
 google.golang.org/grpc/examples v0.0.0-20220617181431-3e7b97febc7f h1:rqzndB2lIQGivcXdTuY3Y9NBvr70X+y77woofSRluec=
@@ -890,6 +904,8 @@ google.golang.org/protobuf v1.25.0/go.mod h1:9JNX74DMeImyA3h4bdi1ymwjUzf21/xIlba
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
 google.golang.org/protobuf v1.27.1/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
+google.golang.org/protobuf v1.28.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
+google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
 google.golang.org/protobuf v1.36.6 h1:z1NpPI8ku2WgiWnf+t9wTPsn6eP1L7ksHUlkfLvd9xY=
 google.golang.org/protobuf v1.36.6/go.mod h1:jduwjTPXsFjZGTmRluh+L6NjiWu7pchiJ2/5YcXBHnY=
 gopkg.in/alecthomas/kingpin.v2 v2.2.6/go.mod h1:FMv+mEhP44yOT+4EoQTLFTRgOQ1FBLkstjWtayDeSgw=

integration-test/const.js

@@ -89,6 +89,9 @@ export const sampleCsv = encoding.b64encode(
 export const samplePdf = encoding.b64encode(
   open(`${__ENV.TEST_FOLDER_ABS_PATH}/integration-test/data/sample.pdf`, "b")
 );
+export const sampleMultiPagePdf = encoding.b64encode(
+  open(`${__ENV.TEST_FOLDER_ABS_PATH}/integration-test/data/sample-multi-page.pdf`, "b")
+);
 export const samplePpt = encoding.b64encode(
   open(`${__ENV.TEST_FOLDER_ABS_PATH}/integration-test/data/sample.ppt`, "b")
 );
@@ -131,9 +134,13 @@ export const db = sql.open(driver, `postgresql://postgres:password@${dbHost}:543
 import { randomString } from "https://jslib.k6.io/k6-utils/1.1.0/index.js";
 
 // Add randomization to prevent collisions between parallel/sequential test runs
-// This allows tests to run without waiting for cleanup workflows
+// Generate unique prefix per test file to avoid parallel test interference
 // Format: test-{4 random chars}- = 11 chars, leaving 21 chars for catalog-specific names
-export const dbIDPrefix = `test-${randomString(4)}-`;
+// CRITICAL: Each test MUST call this in setup() to get a unique prefix
+// DO NOT create a const export - it would be shared across all parallel tests!
+export function generateDBIDPrefix() {
+  return `test-${randomString(4)}-`;
+}
 
 // Pretty banner for k6 checks table; accounts for default left indent
 export function banner(title) {