Generated and dependency folders (gen/ and dep/)

The gen/ and dep/ folders are special overlay directories in the C3 AI package structure. The gen/ folder contains automatically generated files like type metadata caches and generated source code. The dep/ folder provides access to files from dependency packages. Both folders are managed by the C3 Agentic AI Platform and should not be manually edited. This topic explains what belongs in these folders, how they're organized, and how the C3 Agentic AI Platform uses them.

Copy link to this section

Understanding overlays

The C3 AI package structure uses overlays to organize files by their purpose and lifecycle. Overlays are top-level directories that modify or extend the base package structure.

Copy link to this section

Three overlay types

The C3 Agentic AI Platform recognizes three overlay types:

1. test/: Test-specific files (see Test Folder).
2. gen/: Generated files (this document).
3. dep/: Dependency package files (this document).

Overlays can be nested. For example, dep/C3 Agentic AI Platform/test/ contains test files from the dependency.

Copy link to this section

Overlay path structure

Files with overlays follow this path pattern:

/packageName/[overlay]/[depPkg]/[depOverlay]/category/subpath

Examples:

/myApp/gen/cache/TypeMetaDeps%23dts/User.c3typ.d.ts
  Package: myApp
  Overlay: gen
  Category: cache
  File: TypeScript definitions for User type

/myApp/dep/C3 Agentic AI Platform/src/User.c3typ
  Package: myApp
  Overlay: dep
  Dependency: C3 Agentic AI Platform
  Category: src
  File: User type from C3 Agentic AI Platform dependency

/myApp/dep/C3 Agentic AI Platform/test/src/UserTest.c3typ
  Package: myApp
  Overlay: dep
  Dependency: C3 Agentic AI Platform
  Dep Overlay: test
  Category: src
  File: User test from C3 Agentic AI Platform dependency

Copy link to this section

The gen/ folder: Generated files

The gen/ folder contains files automatically generated by the C3 Agentic AI Platform. These files are created during package provisioning, validation, and code generation.

Copy link to this section

What belongs in gen/

Generated content includes:

• Type metadata caches (gen/cache/): Pre-computed type dependencies and metadata.
• Generated source code (gen/src/): Auto-generated type implementations.
• TypeScript definitions (gen/cache/TypeMetaDeps#dts/): Type definitions for IDE support.
• Python type stubs (gen/cache/TypeMetaDeps#pyi/): Python type hints.
• Build artifacts: Compiled code and intermediate files.

Example structure:

gen/
  cache/
    type-names.txt                               # List of all type names
    own-type-names.txt                           # Types declared in this package
    type-sub-type-names.txt                      # Type inheritance relationships
    type-annotations.txt                         # Type annotations index
    TypeMetaDeps#dts/
      User.c3typ.d.ts                           # TypeScript definitions
    TypeMetaDeps#pyi/
      User.c3typ.pyi                            # Python type stubs
    TypeMetaDeps#mixins/
      User.txt                                   # Mixin dependencies
    
  src/
    dyn/
      Obj_abc123.c3typ                          # Dynamic type definitions

Copy link to this section

Cache files in gen/cache/

The C3 Agentic AI Platform generates several cache files to optimize type loading and validation:

Copy link to this section

Type name caches

type-names.txt: All type names accessible from this package (including dependencies).

User
Order
Platform.Type
Platform.Pkg
...

own-type-names.txt: Types declared in this package only.

User
Order
CustomWorkflow
...

type-sub-type-names.txt: Type inheritance relationships.

Type: User, CustomUser, AdminUser
Type: SeedData, User, CronJob
...

type-annotations.txt: Types grouped by annotations.

@db: User, Order, Customer
@seed: CronJob, JupyterFile
...

Copy link to this section

Type metadata dependencies

TypeMetaDeps cache files store pre-computed dependencies for each type:

TypeMetaDeps#mixins/: Mixin relationships. TypeMetaDeps#refs/: Referenced types. TypeMetaDeps#dts/: TypeScript type definitions. TypeMetaDeps#pyi/: Python type stubs.

These caches enable fast type loading without re-parsing all type definitions.

Copy link to this section

Package lock file

resolvedVersions.json: Resolved dependency versions.

{
  "version": "8.6",
  "resolvedDependencies": {
    "platform": "8.6",
    "myApp": "1.0"
  }
}

Copy link to this section

Generated source code in gen/src/

The C3 Agentic AI Platform generates source code for dynamic types and runtime-specific implementations.

Dynamic types (gen/src/dyn/):

• Created by Pkg.dynamicTypeFromFields() and similar methods.
• Named with fingerprint suffixes (for example, Obj_abc123)
• Used for anonymous types and computed structures

Example:

gen/src/dyn/Obj_abc123.c3typ
entity type Obj_abc123 mixes Obj {
  name: string
  value: double
  timestamp: datetime
}

Copy link to this section

File fingerprints

file-fingerprints.txt: Checksums of all package files

/myApp/src/User.c3typ: abc123...
/myApp/seed/CronJob/BackupJob.json: def456...
...

The C3 Agentic AI Platform uses fingerprints to detect changes and trigger re-provisioning.

Copy link to this section

When gen/ files are created

The C3 Agentic AI Platform generates files during:

1. Package provisioning: Initial deployment creates all cache files
2. Type validation: Validation regenerates TypeMetaDeps caches
3. Code generation: Compile-time code generation creates runtime files
4. Type system operations: Dynamic type creation adds to gen/src/dyn/

Copy link to this section

Do not manually edit gen/

Generated files are managed by the C3 Agentic AI Platform:

• Files in gen/ are automatically created and updated.
• Manual edits will be overwritten during provisioning.
• The C3 Agentic AI Platform deletes and regenerates files as needed.
• Git should ignore the gen/ directory.

To regenerate cache files, use:

// Regenerate all caches
pkg().code().writeCaches(false);

// Regenerate file fingerprints
pkg().code().writeFileFingerprints();

Copy link to this section

The dep/ folder: Dependency files

The dep/ folder provides access to files from dependency packages. When your package depends on another package, the dependency's files appear under dep/<depPkgName>/.

Copy link to this section

What belongs in dep/

The dep/ folder contains files from declared dependencies:

Path structure: dep/<dependencyName>/<category>/<subpath>

Example:

dep/
  C3 Agentic AI Platform/
    src/
      User.c3typ                    # User type from C3 Agentic AI Platform
      Pkg.c3typ                     # Pkg type from C3 Agentic AI Platform
    seed/
      Unit/
        Unit.csv                    # Unit seed data from C3 Agentic AI Platform
    metadata/
      Role/
        C3.Admin.json              # Admin role from C3 Agentic AI Platform
  
  commonLib/
    src/
      Utility.c3typ                # Utility type from commonLib

Copy link to this section

Accessing dependency files

The C3 Agentic AI Platform automatically resolves paths to dependency files:

Direct type references:

// In myApp/src/CustomType.c3typ
type CustomType mixes Platform.User {
  // Platform.User resolves to dep/C3 Agentic AI Platform/src/User.c3typ
  customField: string
}

File paths:

Full path: meta://myApp/dep/C3 Agentic AI Platform/src/User.c3typ
Package: myApp
Overlay: dep
Dependency: C3 Agentic AI Platform
Category: src
File: User.c3typ

Copy link to this section

Dependency with test overlay

Dependencies can include test files when running in test mode:

Path structure: dep/<depName>/test/<category>/<subpath>

Example:

dep/C3 Agentic AI Platform/test/src/UserTest.c3typ

This is a test file from the C3 Agentic AI Platform dependency, accessible when your package runs in test mode.

Copy link to this section

Why dep/ is read-only

Dependency files are immutable from the dependent package:

• Files come from the dependency package's installed version.
• Changes must be made in the source dependency package.
• The dep/ folder reflects the installed dependency state.
• Remixing allows customization without modifying dependencies.

To customize dependency types:

// Instead of editing dep/C3 Agentic AI Platform/src/User.c3typ
// Create a remix in your package

type User mixes Platform.User remix {
  // Add or override fields
  customField: string
}

Copy link to this section

How gen/ and dep/ relate to other folders

Generated and dependency folders interact with the core package structure:

• Source folder (src/) Generated TypeScript definitions (gen/cache/TypeMetaDeps#dts/) provide IDE support for types declared in src/. Dependency types in dep/<pkg>/src/ can be remixed in your src/ folder. See Source Folder.

• Test folder (test/) Test overlays can appear in dependencies (dep/<pkg>/test/). Generated test caches optimize test discovery. See Test Folder.

• Seed folder (seed/) Dependency seed data in dep/<pkg>/seed/ provides initial data from dependencies. Your package's seed data can reference dependency types. See Seed Folder.

• Metadata folder (metadata/) Dependency metadata in dep/<pkg>/metadata/ provides configuration from dependencies. Generated caches include metadata indexes. See Metadata Folder.

Copy link to this section

File lifecycle

Understanding when files appear in gen/ and dep/:

Copy link to this section

Generated files (gen/)

Creation:

1. Package provisioning runs upsertAllSeed().
2. Platform validates types and generates caches.
3. Code generation creates runtime files.
4. Files written to gen/cache/ and gen/src/.

Updates:

1. Package fingerprint changes.
2. Platform detects changes during provisioning.
3. Regenerates affected cache files.
4. Updates TypeMetaDeps and related caches.

Deletion:

1. Package provisioning clears outdated caches.
2. Platform removes invalid cache files.
3. Regenerates from current package state.

Copy link to this section

Dependency files (dep/)

Creation:

1. Package declares dependency in manifest.
2. Platform loads dependency package.
3. Dependency files become accessible under dep/.
4. Path resolution includes dependency types.

Updates:

1. Dependency package version changes.
2. Platform reloads dependency.
3. Files under dep/ reflect new version.

Removal:

1. Dependency removed from manifest.
2. Platform removes dep/<depName>/ directory.
3. References to dependency types fail.

Copy link to this section

Overlay precedence

When multiple overlays contain the same file, the C3 Agentic AI Platform uses precedence rules:

Copy link to this section

Precedence order (highest to lowest)

1. Test overlay (test/): Highest precedence in test mode.
2. Base files (no overlay): Standard package files.
3. Generated overlay (gen/): Generated files.
4. Dependency overlay (dep/): Lowest precedence.

Example:

If all of these exist:
- /myApp/src/User.c3typ (base)
- /myApp/test/src/User.c3typ (test remix)
- /myApp/gen/src/User.c3typ (generated)
- /myApp/dep/C3 Agentic AI Platform/src/User.c3typ (dependency)

In test mode: test/src/User.c3typ loads
In production mode: src/User.c3typ loads

Copy link to this section

Overlay combinations

Valid combinations:

• test/ + base files
• gen/ + base files
• dep/<pkg>/ + base files
• dep/<pkg>/test/ + dep/<pkg>/ files

File resolution:

test/src/User.c3typ               (test remix of base)
gen/src/dyn/Obj_abc123.c3typ      (generated dynamic type)
dep/C3 Agentic AI Platform/src/User.c3typ       (dependency base file)
dep/C3 Agentic AI Platform/test/src/User.c3typ  (dependency test file)

Copy link to this section

See also

• Package Structure Overview
• Source Folder
• Test Folder
• Seed Folder
• Metadata Folder
• Package Manifest