C3 AI Documentation Home

Generated folder (gen/)

The gen/ folder is a special overlay directory in the C3 AI package structure. It contains automatically generated files like type metadata caches and generated source code. The folder is managed by the C3 Agentic AI Platform and should not be manually edited. This topic explains what belongs in gen/, how it is organized, and how the platform uses it.

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.

Overlay types

The C3 Agentic AI Platform recognizes these overlay types:

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

Overlay path structure

Files with overlays follow this path pattern:

Text
/packageName/[overlay]/category/subpath

Example:

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

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.

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:

Text
gen/
  cache/
    own-type-names.txt                           # Types declared in this package
    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

Cache files in gen/cache/

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

Type name caches

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

Text
User
Order
CustomWorkflow
...

Type metadata dependencies

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

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

Package lock file

resolvedVersions.json: Resolved dependency versions.

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

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:

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

File fingerprints

file-fingerprints.txt: Checksums of all package files.

Text
/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.

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/.

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:

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

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

How gen/ relates to other folders

  • Source folder (src/) Generated TypeScript definitions (gen/cache/TypeMetaDeps#dts/) provide IDE support for types declared in src/. See Source Folder.

  • Test folder (test/) Generated test caches optimize test discovery. See Test Folder.

  • Seed folder (seed/) Your package's seed data can reference types from dependency packages. See Seed Folder.

  • Metadata folder (metadata/) Generated caches include metadata indexes. See Metadata Folder.

File lifecycle

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.

Overlay precedence

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

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.

Example:

Text
If all of these exist:
- /myApp/src/User.c3typ (base)
- /myApp/test/src/User.c3typ (test remix)
- /myApp/gen/src/User.c3typ (generated)

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

Overlay combinations

Valid combinations:

  • test/ + base files
  • gen/ + base files

File resolution:

Text
test/src/User.c3typ               (test remix of base)
gen/src/dyn/Obj_abc123.c3typ      (generated dynamic type)

Accessing dependency package files

Dependency packages are separate packages with their own roots. Reference their files under the dependency package name (for example, meta://platform/src/User.c3typ), not under a dep/ path on the dependent package. Type remixes and imports resolve through the package dependency graph declared in the package manifest; see Package Manifest.

See also

Was this page helpful?