firebase-contract 0.1.0-rc.15 → 0.1.0-rc.2

package/README.md

@@ -10,7 +10,7 @@ From one contract, generate:
 - **Zod** validation schemas
 - **Data Connect** GraphQL schema (`@table`, keys, directives), query/mutation
   operations (routed per connector), and `Any`↔logical adapters
-- **Firestore** projection schemas (denormalized read model; shared field groups via fragments)
+- **Firestore** projection schemas (denormalized read model with `_meta_`)
 - **API** request/response types, request-validation Zod, and class-validator DTOs
 - **Cloud Task / Pub/Sub** payload envelopes + delivery constants
 - **SQL migrations** for constraints Data Connect can't express (composite FKs,
@@ -32,101 +32,35 @@ Provides the `firebase-contract` (alias `fbc`) CLI and a programmatic API.
 ```bash
 fbc init          # scaffold contract.yml + firebase-contract.json
 fbc validate      # parse, resolve imports, semantically validate
-fbc generate      # run every generator declared across the contract graph
+fbc generate      # run every `generate:` target declared in the contract graph
 fbc inspect       # print the normalized IR (debugging)
-fbc where <Name>  # locate the yml defining a type (logical / gqlName / fsName / table)
 ```
 
 ### One-command generation
 
-Each contract file declares the generators it uses in a top-level
-`generators:` block — a name plus an output template. Declaring a
-**document-scoped** generator (typescript, zod, …) runs it once for
-that yml; **api-scoped** generators (api-types, api-validation, api-dto,
-task-payloads) run for the entries that opt in (see below):
-
-```yaml
-# contract.yml (root)
-project:
-  aliases:
-    "#contracts/*": libs/contracts/src/*   # out templates may target aliases
-generators:
-  - { generator: typescript, out: "#contracts", split: true }
-  - { generator: api-types, out: "#contracts/api-types/{api-name}" }
-imports:
-  - ./apps/shop/data-connect/schema.yml
-```
+Each contract file can declare its own outputs in a `generate:` section —
+out dirs are relative to that yml file:
 
 ```yaml
 # apps/shop/data-connect/schema.yml
-generators:
-  - { generator: data-connect-graphql, out: src, split: true }
-  - { generator: sql-migrations, out: . }
+generate:
+  - { out: src, generators: [data-connect-graphql-split] }
+  - { out: ., generators: [sql-migrations] }
 ```
 
-- `out` resolves relative to the declaring yml; `#alias/...` prefixes resolve
-  through the **root** yml's `project.aliases` (relative to the root).
-- Api-scoped templates may use `{api-name}` (kebab-cased name) and `{path}`
-  (REST path with `{param}` segments dropped).
-- Entries reference declarations by name — nearest first (same yml → root).
-
-#### Output settings: `file`, `split`, `options`, `header`
-
-Every declaration (and any entry-level application) can reshape the output —
-the defaults reproduce each generator's built-in layout, so omitting them
-changes nothing:
-
 ```yaml
-generators:
-  - generator: api-dto
-    out: "src/entries/{path}/dto"
-    file: "{api-name}.dto.ts"   # file-name template (default shown)
-    split: true                 # one file per api (api-dto's default)
-  - generator: api-types
-    out: "#contracts/api-types"
-    file: "{api-name}.types.ts" # override the bundled default with per-api files
-    split: true
-    options:
-      typesImport: "../types"   # where `import type { … } from '…'` points
-  - generator: typescript
-    out: "#contracts"
-    file: models.ts             # rename a single-file/barrel output
-    split: true                 # document scope: per-table split layout
+# contract.yml (root)
+generate:
+  - out: libs/contracts/src
+    generators: [typescript-split, zod-split, firestore-split, id-codecs]
+imports:
+  - ./apps/shop/data-connect/schema.yml
 ```
 
-- **`file`** — output file name. Api scope: a template (`{api-name}`/`{path}`
-  allowed when `split: true`). Document scope: renames the single output file,
-  or the barrel of a split layout.
-- **`split`** — api scope: `true` emits one file per api (the `file` template
-  must contain a placeholder), `false` bundles everything into one `file`.
-  Document scope: `true` selects the generator's per-item split layout
-  (typescript, zod, firestore, data-connect-graphql, data-connect-operations)
-  and errors for generators without one.
-- **`options`** — free-form string map passed through to the generator.
-  Currently: `typesImport` (api-types, task-payloads, data-connect-operations)
-  overrides the types import path. For api-types and task-payloads this is
-  normally unnecessary: when the option is absent and a `typescript` generator
-  is declared (nearest-first: same yml → root), the import specifier is derived
-  automatically as the relative path from the output file to the declared
-  barrel — moving or renaming the barrel (`out` / `file`) re-derives it. An
-  explicit `typesImport` always wins; without a typescript declaration the
-  generator's built-in default (`./types`) applies.
-- **`header`** — per-generator banner override: `default` for the built-in
-  AUTO-GENERATED banner, any text for a custom comment, `""` to suppress the
-  banner for this generator. Wins over the contract-level `header:` and the
-  CLI `--header` flag.
-- Defaults per generator: `api-types` → `api-types.ts` bundled, `api-validation`
-  → `api-validation.ts` bundled, `task-payloads` → `task-payloads.ts` bundled,
-  `api-dto` → `{api-name}.dto.ts` split.
-- Entry-level settings override the declaration, which overrides the
-  generator's default (same nearest-first rule as `out`).
-
-`fbc generate contract.yml` materializes **all** declared outputs across the
-whole import graph in one run. Passing `-o`/`-g` switches to single-target mode
-(`fbc generate <entry> -o <dir> -g typescript,zod`). `firebase-contract.json`
-holds only a default `entry` — output routing lives in the yml `generators:`
-declarations, so a config file can never silently override them.
-
+`fbc generate contract.yml` then materializes **all** targets across the whole
+import graph in one run. Passing `-o`/`-g` switches to single-target mode
+(`fbc generate <entry> -o <dir> -g typescript,zod`), and
+`firebase-contract.json` (`entry`, `outDir`, `generators`) can hold defaults.
 
 ### Generated-file headers
 
@@ -141,34 +75,6 @@ fbc generate --header "Managed by fbc"   # custom text (multi-line ok)
 header: default        # or any text; the CLI --header flag wins
 ```
 
-Header text (contract `header:`, per-generator `header`, CLI `--header`)
-supports `${...}` template variables:
-
-| Variable | Value |
-| --- | --- |
-| `${rootContractPath}` | entry (root) yml path, relative to the root yml's directory |
-| `${currentContractPath}` | the yml the output is generated from |
-| `${allContractPath}` | import chain root → current, joined with ` -> ` |
-| `${generatedAt}` | date the file was **first** generated (carried over on regenerate) |
-| `${updatedAt}` | date the content **last changed** |
-
-A regenerate that produces identical content keeps both dates and reproduces
-the file byte-for-byte, so `--check` stays drift-free; when content changes,
-`generatedAt` is carried over from the existing file and only `updatedAt`
-moves. Date tokens accept an optional format — `${updatedAt:yyyy-mm-dd HH:mm:ss}`
-— with runs `yyyy`/`yy`, `MM`, `dd`, `HH`, `ss`, and `mm` meaning month before
-any hour token / minute after one (both `yyyy-mm-dd` and `HH:mm` read
-naturally). Default: `yyyy-MM-dd`.
-
-The `default` banner includes the source and dates:
-
-```
-// AUTO-GENERATED by firebase-contract. Do not edit by hand.
-// Source: ${currentContractPath}
-// Generated: ${generatedAt} / Updated: ${updatedAt}
-// Regenerate with: fbc generate
-```
-
 Comment syntax adapts per file type (`//` for TS, `#` for GraphQL/YAML-ish,
 `--` for SQL).
 
@@ -182,33 +88,8 @@ in other contracts (relative paths or npm packages). Imports are resolved
 transitively with cycle/duplicate detection and diamond dedup, so you can split
 a large contract across files that mirror your repo layout.
 
-**Type names are globally unique.** The namespace is flat across the whole
-import graph: defining the same name twice — same kind (`DUPLICATE_DEFINITION`)
-or across kinds/derived identifiers, e.g. an enum and a model both named
-`Status`, or two enums whose `CONSTANT_CASE` consts collide (`NAME_COLLISION`)
-— aborts generation. Uniqueness is enforced per output namespace with its
-*effective* names, so `fsName`/`gqlName` renames legitimately reuse a name in a
-different output: GraphQL names are checked per `data-connect-graphql` scope
-(services may map distinct logical names onto the same gqlName), and the
-firestore module is checked under `fsName ?? name` alongside doc names. A bare
-type reference therefore always resolves to exactly one definition — use
-`fbc where <Name>` to find it.
-
-**Unknown keys are errors.** Every key the parser does not consume is an
-`UNKNOWN_KEY` error (all reported in one pass), never silently dropped — a
-typo like `optionnal:` must not quietly turn into a required field. There is
-no `version:` field: nothing consumes one, so accepting it would only fake a
-compatibility mechanism that does not exist.
-
-**Out-of-vocabulary values are errors too.** A value outside a field's fixed
-set is `INVALID_VALUE` rather than a silent coercion: `auth: PUBILC` does not
-quietly become `NO_ACCESS`, `dir: Dsec` does not become `ASC`, and a mistyped
-`action` / `single` / `keyArg` / `style.*` is not dropped. The one exception is
-`where.op`, which is warned (`UNKNOWN_WHERE_OP`) not errored — it is emitted
-verbatim into GraphQL and the recognized-operator list may lag Data Connect, so
-a typo is surfaced without rejecting a valid-but-unlisted operator.
-
 ```yaml
+version: 1
 imports:
   - ./apps/shop/data-connect/schema.yml
   - some-shared-package/contract.yml
@@ -281,24 +162,24 @@ models:
 
 | option                              | meaning                                                  |
 | ----------------------------------- | -------------------------------------------------------- |
-| `type`                              | document | scalar name, or an enum/model name                       |
-| `optional`                          | document | value may be absent (`field?`)                           |
-| `list`                              | document | value is an array of `type`                              |
-| `id`                                | document | marks the (single) primary identifier                    |
-| `unique`                            | document | field-level unique → `@unique`                           |
-| `relation`                          | document | model-typed field is a foreign-key relation (see below)  |
-| `col`                               | document | Data Connect column dataType (Int64 PKs default to `bigserial`) |
-| `default`                           | document | `@default(expr: …)` on the DC column                     |
-| `literal`                           | document | pin to one literal value (union discriminant tags)       |
-| `nullable`                          | document | value may be `null` (`.nullable()` / `\| null`)          |
-| `description`                       | document | doc comment carried into generated output                |
-| `jsdoc`                             | document | render the description as a JSDoc block (Firestore fields) |
+| `type`                              | scalar name, or an enum/model name                       |
+| `optional`                          | value may be absent (`field?`)                           |
+| `list`                              | value is an array of `type`                              |
+| `id`                                | marks the (single) primary identifier                    |
+| `unique`                            | field-level unique → `@unique`                           |
+| `relation`                          | model-typed field is a foreign-key relation (see below)  |
+| `col`                               | Data Connect column dataType (Int64 PKs default to `bigserial`) |
+| `default`                           | `@default(expr: …)` on the DC column                     |
+| `literal`                           | pin to one literal value (union discriminant tags)       |
+| `nullable`                          | value may be `null` (`.nullable()` / `\| null`)          |
+| `description`                       | doc comment carried into generated output                |
+| `jsdoc`                             | render the description as a JSDoc block (Firestore fields) |
 | **constraints** →                   |                                                          |
-| `min` / `max`                       | document | numeric bounds                                           |
-| `minLength` / `maxLength`           | document | string/array length bounds                               |
-| `nonempty`                          | document | non-empty string/array                                   |
-| `pattern`                           | document | regex the string must match                              |
-| `email` / `url`                     | document | string format                                            |
+| `min` / `max`                       | numeric bounds                                           |
+| `minLength` / `maxLength`           | string/array length bounds                               |
+| `nonempty`                          | non-empty string/array                                   |
+| `pattern`                           | regex the string must match                              |
+| `email` / `url`                     | string format                                            |
 
 Constraints flow into the Zod schemas, the API request validation, and the
 class-validator DTOs.
@@ -307,14 +188,14 @@ class-validator DTOs.
 
 | option       | meaning                                                             |
 | ------------ | ------------------------------------------------------------------ |
-| `key`        | document | composite primary key field names (else the `id: true` field)      |
-| `table`      | document | table name override (default: snake_case pluralization)            |
-| `gqlName`    | document | GraphQL type name override                                          |
-| `fsName`     | document | Firestore-side rename (avoid collisions with table models)          |
-| `directives` | document | `multi` = each type-level directive on its own line                 |
-| `footer`     | document | trailing comment block after the closing `}` in the schema file     |
-| `indexes`    | document | composite `@index`/`@unique` (`{ fields, name?, unique?, expand? }` — `expand` renders args one per line) |
-| `sql`        | document | raw SQL constraints (see [SQL migrations](#sql-migrations))         |
+| `key`        | composite primary key field names (else the `id: true` field)      |
+| `table`      | table name override (default: snake_case pluralization)            |
+| `gqlName`    | GraphQL type name override                                          |
+| `fsName`     | Firestore-side rename (avoid collisions with table models)          |
+| `directives` | `multi` = each type-level directive on its own line                 |
+| `footer`     | trailing comment block after the closing `}` in the schema file     |
+| `indexes`    | composite `@index`/`@unique` (`{ fields, name?, unique?, expand? }` — `expand` renders args one per line) |
+| `sql`        | raw SQL constraints (see [SQL migrations](#sql-migrations))         |
 
 ### Embedded vs relation
 
@@ -392,14 +273,14 @@ Everything below exists to reproduce real hand-written `.gql` files byte-for-byt
 
 | option | meaning |
 | --- | --- |
-| `gqlName` | document | rendered operation name (the yml key stays unique across services) |
-| `footer` | document | trailing `# …` comment block after the operation |
-| `raw` | document | emit the operation body verbatim (multi-model queries, `_or` keyset cursors — field checks are skipped) |
-| `single: id \| document | key` | single-row lookup (`product(id: $id)` / `product(key: { … })`) |
-| `keyArg` / `keyVars` | document | update/delete key argument form and variable renames |
-| `whereAnd: true` | document | render conditions as an `_and: [ … ]` array |
-| `entityDir` | document | override the `operations/<entity>/` output directory |
-| `style` | document | formatting hints: `signature`, `args`, `data`, `orderBy`, `auth`, `key`, `and`, `where` (`inline`/`multi`/`compact`/`bare`) |
+| `gqlName` | rendered operation name (the yml key stays unique across services) |
+| `footer` | trailing `# …` comment block after the operation |
+| `raw` | emit the operation body verbatim (multi-model queries, `_or` keyset cursors — field checks are skipped) |
+| `single: id \| key` | single-row lookup (`product(id: $id)` / `product(key: { … })`) |
+| `keyArg` / `keyVars` | update/delete key argument form and variable renames |
+| `whereAnd: true` | render conditions as an `_and: [ … ]` array |
+| `entityDir` | override the `operations/<entity>/` output directory |
+| `style` | formatting hints: `signature`, `args`, `data`, `orderBy`, `auth`, `key`, `and`, `where` (`inline`/`multi`/`compact`/`bare`) |
 
 Inputs support `var` (variable rename), `required` (override optionality),
 `literal` (fixed value, no variable), `flat` (write the FK column directly),
@@ -415,13 +296,11 @@ name as long as their connector sets don't overlap.
 
 ## API endpoints
 
-Model application endpoints in three kind-implied sections — `apis:` (https /
-callable, keyed by REST path), `tasks:` (Cloud Tasks), and `events:` (Pub/Sub).
-The api-scoped generators — request/response types (`api-types`),
-request-validation Zod (`api-validation`), class-validator DTOs (`api-dto`),
-and payload contracts (`task-payloads`) — run for the entries that opt in via
-the section `defaults` or the entry's own `generators:`. A payload references a
-model or declares inline fields; a void response maps to `void`.
+Model application endpoints (Cloud Task / callable / https / pubsub). Generates
+request/response types (`api-types`), request-validation Zod (`api-validation`),
+class-validator DTOs (`api-dto`), and — for `task`/`pubsub` — payload contracts
+(`task-payloads`). A payload references a model or declares inline fields; a void
+response maps to `void`.
 
 ```yaml
 envelopes:
@@ -431,10 +310,9 @@ envelopes:
       opId: string
       enqueuedAt: int
 
-tasks:                                     # Cloud Tasks (kind implied)
-  defaults:
-    generators: [task-payloads]            # section default: applies to entries below
+apis:
   createCatalog:
+    kind: task                             # product | callable | https | pubsub
     envelope: RetryTaskPayload             # wraps the product data
     maxAttempts: 3
     request:
@@ -444,31 +322,17 @@ tasks:                                     # Cloud Tasks (kind implied)
     response:
       void: true
 
-events:                                    # Pub/Sub (kind implied)
   generateAiResponse:
+    kind: pubsub
     topic: ai-review-generate-response
     timeoutSeconds: 540
-    generators: [task-payloads]
-
-apis:                                      # https/callable, keyed by REST path
-  defaults:
-    generators: [api-types, api-validation]
-  /shops/{slug}:
-    operationId: getShopBySlug
-    kind: callable                         # https (default) | callable
+
+  getShopBySlug:
+    kind: callable
     request: { fields: { slug: { type: string, nonempty: true } } }
     response: { model: Shop }
-    generators:                            # entry-level wins over section defaults;
-      - api-types                          # an inline out overrides the declared template
-      - { generator: api-dto, out: "src/entries/{path}" }
 ```
 
-Generator application resolves in two tiers — the section `defaults`
-(`apis:/tasks:/events:` → `defaults.generators`) and the entry's own
-`generators:` (which replaces the defaults). `apis:` keys must be REST paths
-(`/...` or `METHOD /...` so the same route can appear once per verb) with an
-`operationId`; tasks and Pub/Sub events live in their own sections.
-
 For `createCatalog` this yields `CreateCatalogTaskData`, `CreateCatalogTaskPayload =
 RetryTaskPayload<CreateCatalogTaskData>`, and `CREATE_CATALOG_MAX_ATTEMPTS`, plus the
 request types, Zod schema, and DTO.
@@ -481,9 +345,9 @@ reality automatically:
 
 - **relations → resolved string ids** (`ownerUser` → `ownerUserId: z.string()`)
 - **timestamps → `z.date()`**, optional fields → `.nullable()`
+- a **`_meta_`** consistency envelope is attached (opt out with `meta: false`)
 - `pick` / `omit` select which base fields survive
 - inline `fields` add denormalized data (flattened DAG edges, stringified JSON)
-- `extends: [<fragment>…]` splices shared fields in (see **Fragments** below)
 
 ```yaml
 firestore:
@@ -501,13 +365,10 @@ firestore:
 ```
 
 Emits Zod schemas + inferred types, mirroring a hand-written Firestore schema
-library. (`firestore-types` is the zero-config entry point for projects that
-have not written projections yet: it re-types *every* model with the Firestore
-`Timestamp`, no `firestore:` section needed. Once you declare projections,
-prefer the `firestore` generator — it is the one that understands
-pick/omit/fsName/denormalized fields.)
+library. (The simpler `firestore-types` generator just re-types *every* model
+with the Firestore `Timestamp` and does not denormalize.)
 
-With `firestore` + `split: true`, fields whose Zod chain is **identical** to the Data
+With `firestore-split`, fields whose Zod chain is **identical** to the Data
 Connect schema are reused via `.pick()` — only representation changes are
 restated:
 
@@ -517,6 +378,7 @@ export const ShopSchema = DcShopSchema.pick({
 }).extend({
   createdAt: z.date(),
   updatedAt: z.date().nullable(),
+  _meta_: _Meta_Schema,
 })
 ```
 
@@ -533,46 +395,6 @@ Additional projection options:
 - FS-only enums render as frozen consts (`REVIEW_STATE` + `ReviewStateSchema`),
   co-located with the first projection that references them
 
-### Fragments (`fragments:` + `extends:`)
-
-A **fragment** is a named group of fields declared once and spliced into
-consumers via `extends: [<name>…]` — the way to share a common field across
-many projections (a consistency `_meta_` envelope, audit columns, …) without a
-tool-imposed convention. The fragment field's name, type, and which docs carry
-it are all yours.
-
-The value objects a fragment references can be **pinned** to a fixed split
-output via `out` (+ optional `file`) on the model declaration. A pinned value
-object is *placement-scoped*: emitted only at that location (dependency-ordered,
-with an `index.ts` barrel), imported by consumers via that directory, and
-excluded from the default `typescript`/`zod` barrels — so it lives purely in the
-firestore output. This is what lets a shared envelope sit under `firestore/_/`.
-
-```yaml
-models:
-  MetaOp:
-    out: firestore/_          # → firestore/_/_meta_.ts (+ firestore/_/index.ts)
-    file: _meta_.ts
-    fields:
-      id: { type: string }
-  Meta:
-    out: firestore/_
-    file: _meta_.ts
-    fields:
-      scope: { type: float, nullable: true }
-      op: { type: MetaOp, nullable: true }
-
-fragments:
-  meta:
-    fields:
-      _meta_: { type: Meta }
-
-firestore:
-  Shop:
-    from: Shop
-    extends: [meta]            # appends `_meta_: MetaSchema` (imported from './_')
-```
-
 ## Discriminated unions
 
 ```yaml
@@ -624,19 +446,14 @@ project:
   idCodec:
     minLength: 8
     alphabet: <your-shuffled-sqids-alphabet>
-  aliases:
-    "#contracts/*": libs/contracts/src/*
 ```
 
 - `services` (`name`/`database`) feed the `FIRESTORE_DATABASES` constants in the
-  split `firestore` barrel.
+  `firestore-split` barrel.
 - `idCodec` pins the Sqids settings as a contract constant; when present, the
   `id-codecs` generator also emits a self-contained `id-core.ts` (the
   encode/decode primitives), so nothing about id encoding lives outside the
   contract.
-- `aliases` maps `#alias/...` out-template prefixes to paths relative to the
-  **root** yml, so imported contracts can target shared libs without relative
-  path gymnastics (longest prefix wins).
 - `codebases` / service `location` + `connectors` are consumed by the optional
   `config` generator (preview), which emits per-service `dataconnect.yaml`,
   per-connector `connector.yaml`, and the `FIRESTORE_DATABASES` /
@@ -648,32 +465,32 @@ project:
 
 # Generators
 
-| name                     | scope    | output                        | notes                                                  |
-| ------------------------ | -------- | ----------------------------- | ------------------------------------------------------ |
-| `typescript`             | document | `types.ts`; `split: true` → `types/<table>.ts` + barrel | interfaces + const/union enums; split co-locates enums/embedded objects per table |
-| `zod`                    | document | `schemas.ts`; `split: true` → `schemas/<table>.ts` + barrel | `z.object` schemas (constraints, `z.lazy` model refs)  |
-| `data-connect-graphql`   | document | `schema.gql`; `split: true` → `schema/<table>.gql` | `type … @table(name, key)`; `@col`/`@unique`/`@index`/`@default` |
-| `data-connect-operations`| document | `<connector>/operations.gql` + `.ts`; `split: true` → `<connector>/operations/<entity>/{queries,mutations}.gql` | queries/mutations (where ops, orderBy, limit, aggregate, exprs, inc), per connector; split matches the real Data Connect repo layout |
-| `data-connect-adapter`   | document | `data-connect-adapters.ts`    | convert `Any` rows ⇄ logical types                     |
-| `firestore-types`        | document | `firestore-types.ts`          | naive TS types with Firestore `Timestamp` (all models) |
-| `firestore`              | document | `firestore.ts`; `split: true` → `firestore/<collection>.ts` + barrel | Firestore projection Zod schemas (derived, denormalized); `extends` fragments, pinned value objects under their `out` (e.g. `firestore/_/`), DC-schema `.pick()` reuse, `FIRESTORE_DATABASES` constants in the barrel |
-| `api-types`              | api | `api-types.ts`                | endpoint request/response types                        |
-| `api-validation`         | api | `api-validation.ts`           | endpoint request-validation Zod                        |
-| `api-dto`                | api | `<operation>.dto.ts` per api  | class-validator DTO classes (NestJS `dto/` convention) |
-| `task-payloads`          | api | `task-payloads.ts`            | envelopes + `*TaskData`/`*TaskPayload` + constants     |
-| `sql-migrations`         | document | `migrations/constraints.sql`  | composite FK / CHECK / index SQL — idempotent (`IF NOT EXISTS` / `duplicate_object` guard), safe to re-apply whole |
-| `id-codecs`              | document | `id-codecs.ts` (+ `id-core.ts`) | typed per-entity id encode/decode wrappers; emits the Sqids primitives when `project.idCodec` is set |
-| `unions`                 | document | `unions.ts`                   | Zod discriminated unions + TS union types              |
-| `config`                 | document | `dataconnect.yaml`, `connector.yaml`, `constants.ts` | DC configs + sync constants (preview — see [Project config](#project-config)) |
+| name                     | output                        | notes                                                  |
+| ------------------------ | ----------------------------- | ------------------------------------------------------ |
+| `typescript`             | `types.ts`                    | interfaces + const/union enums                         |
+| `typescript-split`       | `types/<table>.ts` + `types.ts` barrel | one file per table; enums/embedded objects co-located |
+| `zod`                    | `schemas.ts`                  | `z.object` schemas (constraints, `z.lazy` model refs)  |
+| `zod-split`              | `schemas/<table>.ts` + `schemas.ts` barrel | split variant of `zod`                    |
+| `data-connect-graphql`   | `schema.gql`                  | `type … @table(name, key)`; `@col`/`@unique`/`@index`/`@default` |
+| `data-connect-graphql-split` | `schema/<table>.gql`     | same schema, one file per table (enums co-located) |
+| `data-connect-operations`| `<connector>/operations.gql` + `.ts` | queries/mutations (where ops, orderBy, limit, aggregate, exprs, inc), per connector |
+| `data-connect-operations-split` | `<connector>/operations/<entity>/{queries,mutations}.gql` | real Data Connect repo layout; shared types stay in `typescript`/`zod` outputs |
+| `data-connect-adapter`   | `data-connect-adapters.ts`    | convert `Any` rows ⇄ logical types                     |
+| `firestore-types`        | `firestore-types.ts`          | naive TS types with Firestore `Timestamp` (all models) |
+| `firestore`              | `firestore.ts`                | Firestore projection Zod schemas (derived, denormalized) |
+| `firestore-split`        | `firestore/<collection>.ts` + `firestore.ts` barrel | one file per projection; `_meta_` under `firestore/_/`; DC-schema `.pick()` reuse; `FIRESTORE_DATABASES` constants in the barrel |
+| `api-types`              | `api-types.ts`                | endpoint request/response types                        |
+| `api-validation`         | `api-validation.ts`           | endpoint request-validation Zod                        |
+| `api-dto`                | `api-dtos.ts`                 | class-validator DTO classes                            |
+| `task-payloads`          | `task-payloads.ts`            | envelopes + `*TaskData`/`*TaskPayload` + constants     |
+| `sql-migrations`         | `migrations/constraints.sql`  | composite FK / CHECK / index SQL                       |
+| `id-codecs`              | `id-codecs.ts` (+ `id-core.ts`) | typed per-entity id encode/decode wrappers; emits the Sqids primitives when `project.idCodec` is set |
+| `unions`                 | `unions.ts`                   | Zod discriminated unions + TS union types              |
+| `config`                 | `dataconnect.yaml`, `connector.yaml`, `constants.ts` | DC configs + sync constants (preview — see [Project config](#project-config)) |
 
 Each generator emits nothing when its section is absent, so a small contract
 produces a small output. Select a subset with `-g`.
 
-**Scope** decides how a `generators:` declaration takes effect: `document`
-generators run once for the yml that declares them; `api` generators run only
-for the entries that apply them (section `defaults.generators` → entry
-`generators:`, entry wins).
-
 ### The `Any` boundary
 
 Data Connect stores JSON and embedded objects as the `Any` scalar, erasing the
@@ -701,7 +518,7 @@ const result = generate('contract.yml', {
   write: true,
 })
 
-// Every generator declared across the import graph:
+// Every `generate:` target declared across the import graph:
 const all = generateAll('contract.yml', { write: true })
 ```
 

package/dist/lib/_internal/compiler/compiler.d.ts

@@ -4,7 +4,6 @@ import { RawContract } from '../parser/raw-document.js';
 import { ModuleLoader } from '../resolver/module-loader.js';
 import { GeneratedFile, GeneratorContext } from '../generators/generator.js';
 import { GeneratorRegistry } from '../generators/registry.js';
-import { HeaderPathVars } from './header-vars.js';
 export interface CompileOptions {
     /** Override module loading (defaults to the file system). */
     loader?: ModuleLoader;
@@ -30,10 +29,6 @@ export interface GenerateOptions extends CompileOptions {
     /** When true, write the generated files to disk. */
     write?: boolean;
     context?: GeneratorContext;
-    /** Header `${...}` path values; defaults to entry-only (root = current = entry). */
-    headerVars?: HeaderPathVars;
-    /** Clock for `${generatedAt}`/`${updatedAt}` stamping (tests); defaults to now. */
-    now?: Date;
 }
 export interface GenerateTargetResult {
     /** The contract file that declared this target. */
@@ -48,18 +43,16 @@ export interface GenerateAllResult {
     ok: boolean;
 }
 /**
- * Run every generator declared across the entry contract and its (transitive)
- * imports — the one-command flow: each contract file declares its generators
- * (`generators:` + section defaults / entry applications) and
- * `fbc generate <root>` materializes all of them. Output dirs resolve relative
- * to the declaring yml (or the root yml for `#alias/...` templates).
+ * Run every `generate:` target declared across the entry contract and its
+ * (transitive) imports — the one-command flow: each contract file states where
+ * its own outputs go, and `fbc generate <root>` materializes all of them.
+ * Output dirs resolve relative to the declaring yml file.
  */
 export declare const generateAll: (entryPath: string, options?: {
     registry?: GeneratorRegistry;
     write?: boolean;
     context?: GeneratorContext;
     loader?: ModuleLoader;
-    now?: Date;
 }) => GenerateAllResult;
 export interface FileDrift {
     /** Files whose on-disk content differs from the generated content. */

package/dist/lib/_internal/compiler/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/compiler/compiler.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAoB,MAAM,mBAAmB,CAAA;AAEhE,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAU,WAAW,EAAqC,MAAM,2BAA2B,CAAA;AAElG,OAAO,EAAkB,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAI3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAI5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAEL,cAAc,EAGf,MAAM,kBAAkB,CAAA;AAEzB,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,EAAE,CAAA;IACN,SAAS,EAAE,WAAW,EAAE,CAAA;IACxB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,WAAW,MAAM,EAAE,UAAS,cAAmB,KAAG,aAkBzE,CAAA;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B,oFAAoF;IACpF,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,mFAAmF;IACnF,GAAG,CAAC,EAAE,IAAI,CAAA;CACX;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,KAAK,EAAE,aAAa,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,oBAAoB,EAAE,CAAA;IAC/B,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,EAAE,EAAE,OAAO,CAAA;CACZ;AAyOD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,UAAS;IACP,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,GAAG,CAAC,EAAE,IAAI,CAAA;CACN,KACL,iBA0FF,CAAA;AAED,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,EAAE,KAAG,SAUlD,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,EAAE,CAAA;IACN,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,oFAAoF;IACpF,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB,0DAA0D;IAC1D,EAAE,EAAE,OAAO,CAAA;CACZ;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,SAAS,eAAe,KAAG,cAgEtE,CAAA"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/compiler/compiler.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAoB,MAAM,mBAAmB,CAAA;AAEhE,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAEvD,OAAO,EAAkB,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAG3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAE5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAE7D,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,EAAE,CAAA;IACN,SAAS,EAAE,WAAW,EAAE,CAAA;IACxB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,WAAW,MAAM,EAAE,UAAS,cAAmB,KAAG,aAUzE,CAAA;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,KAAK,EAAE,aAAa,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,oBAAoB,EAAE,CAAA;IAC/B,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,EAAE,EAAE,OAAO,CAAA;CACZ;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,UAAS;IAAE,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,KACjH,iBA8BF,CAAA;AAED,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,EAAE,KAAG,SAUlD,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,EAAE,CAAA;IACN,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,oFAAoF;IACpF,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB,0DAA0D;IAC1D,EAAE,EAAE,OAAO,CAAA;CACZ;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,SAAS,eAAe,KAAG,cAuCtE,CAAA"}