feat(file): add object_uid FK column and AIP-122 resource name support (#323)

**Because**

- Files created from blob storage uploads need a proper foreign key
relationship to the object table
- The API needs to return AIP-122 compliant resource names (e.g.,
`namespaces/{ns}/objects/{id}`) instead of raw UIDs
- The protobuf contract has changed from `object_uid` to `object`
resource name and from `knowledge_base_ids` to `knowledge_bases`
resource names
- The Object proto needs to use AIP-compliant `owner_name` and
`creator_name` instead of raw namespace/creator UIDs

**This commit**

- Adds database migration 000055 to add `object_uid` FK column to the
file table with backfill from storage_path matching
- Updates `FileModel` to include `ObjectUID` foreign key field
- Refactors `CreateFile` to:
- Parse `knowledge_base` as a resource name and extract ID using
`resource.ExtractResourceID()`
- Parse `object` as a resource name (format:
`namespaces/{ns}/objects/{id}`) and look up by hash-based ID
  - Store `ObjectUID` FK when creating files from uploaded objects
  - Return `Object` as AIP-122 resource name instead of `ObjectUid`
- Return `KnowledgeBases` as resource names instead of
`KnowledgeBaseIds`
  - Return `Collections` instead of `CollectionIds`
- Refactors `ListFiles` to populate object resource names from the new
FK relationship
- Updates `TurnObjectInDBToObjectInProto` to return:
- `OwnerName` as `namespaces/{namespace_uid}` instead of raw
`NamespaceId`
  - `CreatorName` as `users/{creator_uid}` instead of raw `Creator`
- Updates protogen-go dependency to latest version with flattened
package structure

Author: pinglin

config/config.yaml

@@ -81,7 +81,7 @@ openfga:
   host: openfga
   port: 8081
   cache:
-    enabled: false
+    enabled: true
     ttl: 60  # Permission cache TTL in seconds
 minio:
   host: minio

go.mod

@@ -13,8 +13,8 @@ require (
 	github.com/grpc-ecosystem/go-grpc-middleware v1.4.0
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.1
 	github.com/iancoleman/strcase v0.3.0
-	github.com/instill-ai/protogen-go v0.3.3-alpha.0.20260122065215-c32ea2feec1f
-	github.com/instill-ai/x v0.10.1-alpha.0.20260122090555-bea4f728b22c
+	github.com/instill-ai/protogen-go v0.3.3-alpha.0.20260125053435-9764054668e5
+	github.com/instill-ai/x v0.10.1-alpha.0.20260125054429-74b22dd4e0e8
 	github.com/knadh/koanf v1.5.0
 	github.com/mennanov/fieldmask-utils v1.1.2
 	github.com/milvus-io/milvus/client/v2 v2.6.1
@@ -221,3 +221,5 @@ require (
 	k8s.io/apimachinery v0.32.3 // indirect
 	sigs.k8s.io/yaml v1.4.0 // indirect
 )
+
+replace github.com/instill-ai/protogen-go => ../protogen-go

go.sum

@@ -419,10 +419,10 @@ github.com/iancoleman/strcase v0.3.0 h1:nTXanmYxhfFAMjZL34Ov6gkzEsSJZ5DbhxWjvSAS
 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.20260122065215-c32ea2feec1f h1:Ypnhf9ywdC2z8YLtSZytFZJjlDYH7sNDpfNv1Ul8Zpw=
-github.com/instill-ai/protogen-go v0.3.3-alpha.0.20260122065215-c32ea2feec1f/go.mod h1:bCnBosofpaUxKBuTTJM3/I3thAK37kvfBnKByjnLsl4=
 github.com/instill-ai/x v0.10.1-alpha.0.20260122090555-bea4f728b22c h1:9Z3NbM6Elzh1zlOGc7PKNP52vQPuM3pwxuj2Zsoh+aE=
 github.com/instill-ai/x v0.10.1-alpha.0.20260122090555-bea4f728b22c/go.mod h1:/xG0LMh43kyyK9jXGtV/JGd5p9GVcreSZ6GRGVbALEU=
+github.com/instill-ai/x v0.10.1-alpha.0.20260125054429-74b22dd4e0e8 h1:siGEvzgpsgvezvjJKnEv8p0s5yRn8e5tOXgkuGdCeyA=
+github.com/instill-ai/x v0.10.1-alpha.0.20260125054429-74b22dd4e0e8/go.mod h1:/xG0LMh43kyyK9jXGtV/JGd5p9GVcreSZ6GRGVbALEU=
 github.com/iris-contrib/blackfriday v2.0.0+incompatible/go.mod h1:UzZ2bDEoaSGPbkg6SAB4att1aAwTmVIx/5gCVqeyUdI=
 github.com/iris-contrib/go.uuid v2.0.0+incompatible/go.mod h1:iz2lgM/1UnEf1kP0L/+fafWORmlnuysV2EMP8MW+qe0=
 github.com/iris-contrib/jade v1.1.3/go.mod h1:H/geBymxJhShH5kecoiOCSssPX7QWYH7UaeZTSWddIk=

pkg/db/migration/000055_add_file_object_uid.down.sql

@@ -0,0 +1,3 @@
+-- Remove object_uid column and index from file table
+DROP INDEX IF EXISTS idx_file_object_uid;
+ALTER TABLE file DROP COLUMN IF EXISTS object_uid;

pkg/db/migration/000055_add_file_object_uid.up.sql

@@ -0,0 +1,15 @@
+-- Add object_uid foreign key column to file table
+-- This establishes a proper relationship between files and their blob storage objects
+ALTER TABLE file ADD COLUMN object_uid UUID REFERENCES object(uid) ON DELETE SET NULL;
+
+-- Create index for efficient joins when looking up object information for files
+CREATE INDEX idx_file_object_uid ON file(object_uid);
+
+-- Backfill existing files: match files to objects by storage_path
+-- Both file.storage_path and object.storage_path use the same format
+UPDATE file f
+SET object_uid = o.uid
+FROM object o
+WHERE f.storage_path IS NOT NULL
+  AND f.storage_path != ''
+  AND o.storage_path = f.storage_path;

pkg/db/migration/migration.go

@@ -9,7 +9,7 @@ import (
 )
 
 // TargetSchemaVersion determines the database schema version.
-const TargetSchemaVersion uint = 54
+const TargetSchemaVersion uint = 55
 
 type migration interface {
 	Migrate() error

pkg/handler/chunk.go

@@ -18,6 +18,7 @@ import (
 	artifactpb "github.com/instill-ai/protogen-go/artifact/v1alpha"
 	errorsx "github.com/instill-ai/x/errors"
 	logx "github.com/instill-ai/x/log"
+	"github.com/instill-ai/x/resource"
 )
 
 // parseChunkFromName parses a resource name of format "namespaces/{namespace}/files/{file}/chunks/{chunk}"
@@ -72,12 +73,12 @@ func convertToProtoChunk(chunk repository.ChunkModel, namespaceID, fileID string
 
 	pbChunk := &artifactpb.Chunk{
 		Name:           resourceName,
-		Id:             chunk.ID,
-		Retrievable:    chunk.Retrievable,
-		Tokens:         uint32(chunk.Tokens),
-		CreateTime:     timestamppb.New(*chunk.CreateTime),
-		OriginalFileId: chunk.FileUID.String(),
-		Type:           chunkType,
+		Id:           chunk.ID,
+		Retrievable:  chunk.Retrievable,
+		Tokens:       uint32(chunk.Tokens),
+		CreateTime:   timestamppb.New(*chunk.CreateTime),
+		OriginalFile: fmt.Sprintf("namespaces/%s/files/%s", namespaceID, chunk.FileUID.String()),
+		Type:         chunkType,
 	}
 
 	// Set markdown reference for all chunk types (content, summary, augmented)
@@ -401,9 +402,11 @@ func (ph *PublicHandler) SearchChunks(
 		)
 	}
 
+	// Extract KB ID from resource name: namespaces/{namespace}/knowledge-bases/{kb}
+	kbID := resource.ExtractResourceID(req.GetKnowledgeBase())
 	logger = logger.With(
 		zap.String("namespace", namespaceID),
-		zap.String("knowledge_base", req.GetKnowledgeBaseId()),
+		zap.String("knowledge_base", kbID),
 	)
 
 	// Get namespace
@@ -417,7 +420,7 @@ func (ph *PublicHandler) SearchChunks(
 
 	// Get knowledge base
 	ownerUID := ns.NsUID
-	kb, err := ph.service.Repository().GetKnowledgeBaseByOwnerAndKbID(ctx, ownerUID, req.GetKnowledgeBaseId())
+	kb, err := ph.service.Repository().GetKnowledgeBaseByOwnerAndKbID(ctx, ownerUID, kbID)
 	if err != nil {
 		return nil, errorsx.AddMessage(
 			fmt.Errorf("fetching knowledge base: %w", err),

pkg/handler/converter.go

@@ -84,15 +84,16 @@ func convertKBToCatalogPB(kb *repository.KnowledgeBaseModel, ns *resource.Namesp
 	// Handle optional fields
 	// Check if ActiveCollectionUID is not zero (nil UUID)
 	if kb.ActiveCollectionUID.String() != "00000000-0000-0000-0000-000000000000" {
-		knowledgeBase.ActiveCollectionId = kb.ActiveCollectionUID.String()
+		knowledgeBase.ActiveCollection = fmt.Sprintf("namespaces/%s/knowledgeBases/%s/collections/%s", namespaceID, kb.ID, kb.ActiveCollectionUID.String())
 	}
 
 	return knowledgeBase
 }
 
 // convertKBFileToPB converts database FileModel to protobuf File.
 // The `name` field is computed dynamically following other backends' patterns.
-func convertKBFileToPB(kbf *repository.FileModel, ns *resource.Namespace, kb *repository.KnowledgeBaseModel, owner *mgmtpb.Owner, creator *mgmtpb.User) *artifactpb.File {
+// The objectID parameter is the hash-based object ID (e.g., "obj-abc123") for AIP-122 compliant resource references.
+func convertKBFileToPB(kbf *repository.FileModel, ns *resource.Namespace, kb *repository.KnowledgeBaseModel, owner *mgmtpb.Owner, creator *mgmtpb.User, objectID string) *artifactpb.File {
 	// ownerName is the full namespace reference (e.g., "users/admin" or "organizations/org-id")
 	ownerName := ns.Name()
 	// namespaceID is just the ID part (e.g., "admin")
@@ -115,7 +116,7 @@ func convertKBFileToPB(kbf *repository.FileModel, ns *resource.Namespace, kb *re
 		OwnerName:        ownerName,
 		Owner:            owner,
 		Creator:          creator,
-		KnowledgeBaseIds: []string{kb.ID}, // File associated with this KB
+		KnowledgeBases: []string{fmt.Sprintf("namespaces/%s/knowledgeBases/%s", namespaceID, kb.ID)}, // File associated with this KB
 		Size:             kbf.Size,
 		ProcessStatus:    convertFileProcessStatus(kbf.ProcessStatus),
 		Aliases:          kbf.Aliases,
@@ -129,13 +130,18 @@ func convertKBFileToPB(kbf *repository.FileModel, ns *resource.Namespace, kb *re
 	if len(kbf.Tags) > 0 {
 		file.Tags = kbf.Tags
 		// Extract collection UIDs from tags with prefix "agent:collection:"
-		file.CollectionIds = extractCollectionUIDs(kbf.Tags)
+		file.Collections = extractCollectionUIDs(kbf.Tags)
 	}
 
 	if kbf.ExternalMetadataUnmarshal != nil {
 		file.ExternalMetadata = kbf.ExternalMetadataUnmarshal
 	}
 
+	// Populate object resource name if file has associated object (AIP-122 compliant)
+	if objectID != "" {
+		file.Object = fmt.Sprintf("namespaces/%s/objects/%s", namespaceID, objectID)
+	}
+
 	// Note: TotalChunks and TotalTokens are computed aggregates, not stored directly in the file model
 	// These would need to be fetched separately if needed
 

pkg/handler/file.go

@@ -30,6 +30,7 @@ import (
 	errorsx "github.com/instill-ai/x/errors"
 	filetype "github.com/instill-ai/x/file"
 	logx "github.com/instill-ai/x/log"
+	"github.com/instill-ai/x/resource"
 )
 
 // filterRequestWrapper implements filtering.Request interface to pass a custom filter string
@@ -63,6 +64,16 @@ func parseFileFromName(name string) (namespaceID, fileID string, err error) {
 	return parts[1], parts[3], nil
 }
 
+// parseObjectIDFromResourceName parses an object resource name of format "namespaces/{namespace}/objects/{object_id}"
+// and returns the object_id
+func parseObjectIDFromResourceName(name string) (objectID string, err error) {
+	parts := strings.Split(name, "/")
+	if len(parts) != 4 || parts[0] != "namespaces" || parts[2] != "objects" {
+		return "", fmt.Errorf("invalid object resource name format, expected namespaces/{namespace}/objects/{object_id}")
+	}
+	return parts[3], nil
+}
+
 // CreateFile adds a file to a knowledge base (AIP-compliant version of UploadKnowledgeBaseFile).
 // It handles file upload, validation, ACL checks, dual processing for staging/rollback KBs,
 // and auto-triggers the processing workflow.
@@ -101,8 +112,11 @@ func (ph *PublicHandler) CreateFile(ctx context.Context, req *artifactpb.CreateF
 		)
 	}
 	// ACL - check user's permission to write knowledge base
-	kbID := req.GetKnowledgeBaseId()
+	// Parse knowledge_base resource name: namespaces/{namespace}/knowledgeBases/{kb}
+	kbResourceName := req.GetKnowledgeBase()
+	kbID := resource.ExtractResourceID(kbResourceName)
 	logger.Debug("CreateFile: looking up KB",
+		zap.String("knowledge_base", kbResourceName),
 		zap.String("knowledge_base_id", kbID),
 		zap.String("namespace_uid", ns.NsUID.String()),
 		zap.String("namespace_id", ns.NsID))
@@ -282,13 +296,27 @@ func (ph *PublicHandler) CreateFile(ctx context.Context, req *artifactpb.CreateF
 
 		kbFile.CreatorUID = creatorUID
 		kbFile.StoragePath = destination
+		// Store the object FK for the new AIP-compliant object reference
+		objUID := types.ObjectUIDType(objectUID)
+		kbFile.ObjectUID = &objUID
 
 		fileSize, _ := getFileSize(req.File.Content)
 		kbFile.Size = fileSize
 	} else {
-		obj, err := ph.service.Repository().GetObjectByUID(ctx, uuid.FromStringOrNil(req.GetFile().GetObjectUid()))
+		// Parse object resource name: namespaces/{namespace}/objects/{object_id}
+		objectResourceName := req.GetFile().GetObject()
+		objectID, err := parseObjectIDFromResourceName(objectResourceName)
+		if err != nil {
+			return nil, errorsx.AddMessage(
+				fmt.Errorf("parsing object resource name: %w", err),
+				"Invalid object resource name. Expected format: namespaces/{namespace}/objects/{object_id}",
+			)
+		}
+
+		// Get object by hash-based ID
+		obj, err := ph.service.Repository().GetObjectByID(ctx, ns.NsUID, types.ObjectIDType(objectID))
 		if err != nil {
-			logger.Error("failed to get knowledge base object with provided UID", zap.Error(err))
+			logger.Error("failed to get object by ID", zap.Error(err), zap.String("object_id", objectID))
 			return nil, err
 		}
 
@@ -324,6 +352,8 @@ func (ph *PublicHandler) CreateFile(ctx context.Context, req *artifactpb.CreateF
 		kbFile.CreatorUID = obj.CreatorUID
 		kbFile.StoragePath = obj.StoragePath
 		kbFile.Size = obj.Size
+		// Store the object FK for the new AIP-compliant object reference
+		kbFile.ObjectUID = &obj.UID
 
 		req.File.Type = determineFileType(obj.DisplayName)
 
@@ -555,14 +585,23 @@ func (ph *PublicHandler) CreateFile(ctx context.Context, req *artifactpb.CreateF
 	owner, _ := ph.service.FetchOwnerByNamespace(ctx, ns)
 	creator, _ := ph.service.FetchUserByUID(ctx, res.CreatorUID.String())
 
+	// Get object ID for AIP-122 compliant resource name
+	objectResourceName := ""
+	if res.ObjectUID != nil {
+		obj, err := ph.service.Repository().GetObjectByUID(ctx, *res.ObjectUID)
+		if err == nil && obj != nil {
+			objectResourceName = fmt.Sprintf("namespaces/%s/objects/%s", namespaceID, obj.ID)
+		}
+	}
+
 	return &artifactpb.CreateFileResponse{
 		File: &artifactpb.File{
 			Id:                 res.ID,
 			Slug:               res.Slug,
 			OwnerName:          ns.Name(),
 			Owner:              owner,
 			Creator:            creator,
-			KnowledgeBaseIds:   []string{kb.ID}, // Initial KB association
+			KnowledgeBases:   []string{fmt.Sprintf("namespaces/%s/knowledgeBases/%s", namespaceID, kb.ID)}, // Initial KB association
 			Name:               fmt.Sprintf("namespaces/%s/files/%s", namespaceID, res.ID),
 			DisplayName:        res.DisplayName,
 			Type:               req.File.Type,
@@ -573,10 +612,10 @@ func (ph *PublicHandler) CreateFile(ctx context.Context, req *artifactpb.CreateF
 			TotalChunks:        0,
 			TotalTokens:        0,
 			ExternalMetadata:   res.PublicExternalMetadataUnmarshal(),
-			ObjectUid:          req.File.ObjectUid,
+			Object:             objectResourceName,
 			ConvertingPipeline: res.ConvertingPipeline(),
 			Tags:               res.Tags,
-			CollectionIds:      extractCollectionUIDs(res.Tags),
+			Collections:      extractCollectionUIDs(res.Tags),
 		},
 	}, nil
 }
@@ -906,13 +945,31 @@ func (ph *PublicHandler) ListFiles(ctx context.Context, req *artifactpb.ListFile
 			knowledgeBaseIDs = fileToKBIDs[kbFile.UID]
 		}
 
+		// Get object ID for AIP-122 compliant resource name
+		objectID := ""
+		objectResourceName := ""
+		if kbFile.ObjectUID != nil {
+			obj, err := ph.service.Repository().GetObjectByUID(ctx, *kbFile.ObjectUID)
+			if err == nil && obj != nil {
+				objectID = string(obj.ID)
+				objectResourceName = fmt.Sprintf("namespaces/%s/objects/%s", namespaceID, objectID)
+			}
+		} else if objectUID != uuid.Nil {
+			// Fallback: try to get object by UID parsed from storage path
+			obj, err := ph.service.Repository().GetObjectByUID(ctx, types.ObjectUIDType(objectUID))
+			if err == nil && obj != nil {
+				objectID = string(obj.ID)
+				objectResourceName = fmt.Sprintf("namespaces/%s/objects/%s", namespaceID, objectID)
+			}
+		}
+
 		file := &artifactpb.File{
 			Id:                 fileID,
 			Slug:               kbFile.Slug,
 			OwnerName:          ns.Name(),
 			Owner:              owner,
 			Creator:            creator,
-			KnowledgeBaseIds:   knowledgeBaseIDs,
+			KnowledgeBases:   knowledgeBaseIDs,
 			Name:               fmt.Sprintf("namespaces/%s/files/%s", namespaceID, fileID),
 			DisplayName:        kbFile.DisplayName,
 			Type:               artifactpb.File_Type(artifactpb.File_Type_value[kbFile.FileType]),
@@ -923,11 +980,11 @@ func (ph *PublicHandler) ListFiles(ctx context.Context, req *artifactpb.ListFile
 			ExternalMetadata:   kbFile.PublicExternalMetadataUnmarshal(),
 			TotalChunks:        int32(totalChunks[kbFile.UID]),
 			TotalTokens:        int32(totalTokens[kbFile.UID]),
-			ObjectUid:          objectUID.String(),
+			Object:             objectResourceName,
 			DownloadUrl:        downloadURL,
 			ConvertingPipeline: kbFile.ConvertingPipeline(),
 			Tags:               []string(kbFile.Tags),
-			CollectionIds:      extractCollectionUIDs(kbFile.Tags),
+			Collections:      extractCollectionUIDs(kbFile.Tags),
 		}
 
 		// Include status message (error or success message)
@@ -1478,7 +1535,7 @@ func (ph *PublicHandler) DeleteFile(ctx context.Context, req *artifactpb.DeleteF
 	logger, _ := logx.GetZapLogger(ctx)
 
 	// Parse resource name to get namespace_id and file_id
-	_, fileID, err := parseFileFromName(req.GetName())
+	namespaceID, fileID, err := parseFileFromName(req.GetName())
 	if err != nil {
 		return nil, errorsx.AddMessage(
 			fmt.Errorf("parsing file name: %w", err),
@@ -1772,7 +1829,7 @@ func (ph *PublicHandler) DeleteFile(ctx context.Context, req *artifactpb.DeleteF
 	}
 
 	return &artifactpb.DeleteFileResponse{
-		FileId: fUID.String(),
+		Name: fmt.Sprintf("namespaces/%s/files/%s", namespaceID, fUID.String()),
 	}, nil
 
 }
@@ -1952,8 +2009,17 @@ func (ph *PublicHandler) UpdateFile(ctx context.Context, req *artifactpb.UpdateF
 	owner, _ := ph.service.FetchOwnerByNamespace(ctx, ns)
 	creator, _ := ph.service.FetchUserByUID(ctx, updatedFile.CreatorUID.String())
 
+	// Get object ID if file has an associated object (for AIP-122 compliant resource reference)
+	objectID := ""
+	if updatedFile.ObjectUID != nil {
+		obj, err := ph.service.Repository().GetObjectByUID(ctx, *updatedFile.ObjectUID)
+		if err == nil && obj != nil {
+			objectID = string(obj.ID)
+		}
+	}
+
 	// Convert to protobuf
-	pbFile := convertKBFileToPB(updatedFile, ns, kb, owner, creator)
+	pbFile := convertKBFileToPB(updatedFile, ns, kb, owner, creator, objectID)
 
 	return &artifactpb.UpdateFileResponse{
 		File: pbFile,
@@ -2117,8 +2183,17 @@ func (ph *PublicHandler) ReprocessFile(ctx context.Context, req *artifactpb.Repr
 	owner, _ := ph.service.FetchOwnerByNamespace(ctx, ns)
 	creator, _ := ph.service.FetchUserByUID(ctx, updatedFile.CreatorUID.String())
 
+	// Get object ID if file has an associated object (for AIP-122 compliant resource reference)
+	objectID := ""
+	if updatedFile.ObjectUID != nil {
+		obj, err := ph.service.Repository().GetObjectByUID(ctx, *updatedFile.ObjectUID)
+		if err == nil && obj != nil {
+			objectID = string(obj.ID)
+		}
+	}
+
 	// Convert to protobuf response with updated file status
-	pbFile := convertKBFileToPB(&updatedFile, ns, kb, owner, creator)
+	pbFile := convertKBFileToPB(&updatedFile, ns, kb, owner, creator, objectID)
 
 	return &artifactpb.ReprocessFileResponse{
 		File:    pbFile,
@@ -2261,13 +2336,13 @@ func getPositionUnit(fileType artifactpb.File_Type) artifactpb.File_Position_Uni
 	return artifactpb.File_Position_UNIT_UNSPECIFIED
 }
 
-// Check if objectUID is provided, and all other required fields if not
+// Check if object is provided, and all other required fields if not
 func checkUploadKnowledgeBaseFileRequest(req *artifactpb.CreateFileRequest) (hasObject bool, _ error) {
 	if req.GetParent() == "" {
 		return false, fmt.Errorf("%w: parent is required", errorsx.ErrInvalidArgument)
 	}
 
-	if req.GetFile().GetObjectUid() == "" {
+	if req.GetFile().GetObject() == "" {
 		// File upload doesn't reference object, so request must contain the
 		// file contents.
 		if req.GetFile().GetDisplayName() == "" {