@pattern-stack/codegen 0.12.1 → 0.13.0

package/dist/src/index.d.ts

@@ -282,6 +282,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         scopeable: z.ZodOptional<z.ZodBoolean>;
+        surface: z.ZodOptional<z.ZodString>;
+        context: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         name: string;
         table: string;
@@ -294,6 +296,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     }, {
         name: string;
         table: string;
@@ -306,6 +310,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     }>, {
         name: string;
         table: string;
@@ -318,6 +324,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     }, {
         name: string;
         table: string;
@@ -330,6 +338,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     }>;
     fields: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodObject<{
         type: z.ZodEnum<["string", "integer", "decimal", "boolean", "uuid", "date", "datetime", "json", "entity_ref", "string_array", "enum"]>;
@@ -1511,6 +1521,24 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             }, {
                 field: string;
                 kind: "eventId";
+            }>, z.ZodObject<{
+                kind: z.ZodLiteral<"historyId">;
+                field: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                field: string;
+                kind: "historyId";
+            }, {
+                field: string;
+                kind: "historyId";
+            }>, z.ZodObject<{
+                kind: z.ZodLiteral<"syncToken">;
+                field: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                field: string;
+                kind: "syncToken";
+            }, {
+                field: string;
+                kind: "syncToken";
             }>]>;
             provenance: z.ZodOptional<z.ZodEnum<["poll", "cdc"]>>;
         }, "strip", z.ZodTypeAny, {
@@ -1526,6 +1554,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         }, {
@@ -1541,6 +1575,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         }>;
@@ -1584,6 +1624,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         };
@@ -1612,6 +1658,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         };
@@ -1692,8 +1744,6 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             value?: unknown;
         }[] | undefined;
     }>]>>>;
-    surface: z.ZodOptional<z.ZodString>;
-    context: z.ZodOptional<z.ZodString>;
     events: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         queue: z.ZodString;
@@ -2024,6 +2074,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     };
     behaviors: (string | {
         name: string;
@@ -2082,6 +2134,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         };
@@ -2112,8 +2170,6 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             value?: unknown;
         }[];
     }> | undefined;
-    surface?: string | undefined;
-    context?: string | undefined;
     events?: {
         name: string;
         queue: string;
@@ -2228,6 +2284,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     };
     relationships?: Record<string, {
         type: "belongs_to" | "has_many" | "has_one";
@@ -2286,6 +2344,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         };
@@ -2316,8 +2380,6 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             value?: unknown;
         }[] | undefined;
     }> | undefined;
-    surface?: string | undefined;
-    context?: string | undefined;
     events?: {
         name: string;
         queue: string;
@@ -2432,6 +2494,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     };
     behaviors: (string | {
         name: string;
@@ -2490,6 +2554,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         };
@@ -2520,8 +2590,6 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             value?: unknown;
         }[];
     }> | undefined;
-    surface?: string | undefined;
-    context?: string | undefined;
     events?: {
         name: string;
         queue: string;
@@ -2636,6 +2704,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     };
     relationships?: Record<string, {
         type: "belongs_to" | "has_many" | "has_one";
@@ -2694,6 +2764,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         };
@@ -2724,8 +2800,6 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             value?: unknown;
         }[] | undefined;
     }> | undefined;
-    surface?: string | undefined;
-    context?: string | undefined;
     events?: {
         name: string;
         queue: string;
@@ -2840,6 +2914,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     };
     behaviors: (string | {
         name: string;
@@ -2898,6 +2974,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         };
@@ -2928,8 +3010,6 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             value?: unknown;
         }[];
     }> | undefined;
-    surface?: string | undefined;
-    context?: string | undefined;
     events?: {
         name: string;
         queue: string;
@@ -3044,6 +3124,8 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         pattern?: string | undefined;
         patterns?: string[] | undefined;
         scopeable?: boolean | undefined;
+        surface?: string | undefined;
+        context?: string | undefined;
     };
     relationships?: Record<string, {
         type: "belongs_to" | "has_many" | "has_one";
@@ -3102,6 +3184,12 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             } | {
                 field: string;
                 kind: "eventId";
+            } | {
+                field: string;
+                kind: "historyId";
+            } | {
+                field: string;
+                kind: "syncToken";
             };
             provenance?: "poll" | "cdc" | undefined;
         };
@@ -3132,8 +3220,6 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
             value?: unknown;
         }[] | undefined;
     }> | undefined;
-    surface?: string | undefined;
-    context?: string | undefined;
     events?: {
         name: string;
         queue: string;
@@ -3712,7 +3798,9 @@ interface LoadEntitiesResult {
 /**
  * Load all entity YAML files from a directory
  */
-declare function loadEntities(entitiesDir: string): LoadEntitiesResult;
+declare function loadEntities(entitiesDir: string, opts?: {
+    excludeDirs?: string[];
+}): LoadEntitiesResult;
 interface LoadRelationshipsResult {
     relationships: ParsedRelationshipDefinition[];
     issues: AnalysisIssue[];

package/dist/src/index.js

@@ -19,14 +19,17 @@ import { join, resolve } from "path";
 function isYaml(name) {
   return name.endsWith(".yaml") || name.endsWith(".yml");
 }
-function findYamlFiles(dir) {
+function findYamlFiles(dir, opts) {
   const root = resolve(dir);
   const out = [];
+  const excluded = new Set((opts?.excludeDirs ?? []).map((d) => resolve(d)));
   const walk = (current) => {
     for (const entry of readdirSync(current, { withFileTypes: true })) {
       if (entry.isDirectory()) {
         if (entry.name.startsWith(".")) continue;
-        walk(join(current, entry.name));
+        const child = join(current, entry.name);
+        if (excluded.has(resolve(child))) continue;
+        walk(child);
       } else if (isYaml(entry.name)) {
         out.push(join(current, entry.name));
       }
@@ -79,11 +82,21 @@ var EventIdCursorSchema = z2.object({
   kind: z2.literal("eventId"),
   field: z2.string().min(1)
 });
+var HistoryIdCursorSchema = z2.object({
+  kind: z2.literal("historyId"),
+  field: z2.string().min(1)
+});
+var SyncTokenCursorSchema = z2.object({
+  kind: z2.literal("syncToken"),
+  field: z2.string().min(1)
+});
 var CursorStrategySchema = z2.discriminatedUnion("kind", [
   SystemModstampCursorSchema,
   ReplayIdCursorSchema,
   TimestampCursorSchema,
-  EventIdCursorSchema
+  EventIdCursorSchema,
+  HistoryIdCursorSchema,
+  SyncTokenCursorSchema
 ]);
 var PollDetectionSchema = z2.object({
   cursor: CursorStrategySchema,
@@ -1274,7 +1287,37 @@ var EntityConfigSchema = z3.object({
   // JOB-7: marks this entity as a valid scope target for job scoping.
   // Drives the generated ScopeEntityType union in
   // runtime/subsystems/jobs/generated/scope-entity-type.ts.
-  scopeable: z3.boolean().optional()
+  scopeable: z3.boolean().optional(),
+  // RFC-0001 §1/§8: the integration *surface* this entity belongs to
+  // (e.g. 'calendar', 'mail', 'crm'). Surfaces span provider contexts
+  // (ADR-0006) — one Google OAuth feeds calendar+mail+transcript. The union
+  // of `surface:` values across all entity YAML is the closed set that a
+  // provider's `surfaces:` must be a subset of (cross-checked in
+  // src/parser/validate-providers.ts). Optional: entities without an
+  // integration surface omit it. The surface-package *emission* convention
+  // is Track C (#329); this field is only the declarative input both tracks
+  // read. Lives inside the `entity:` block (next to `pattern:`/`name:`/`table:`).
+  surface: z3.string().optional(),
+  // Bounded-context declaration (ADR-0004) — "which bounded context this
+  // entity belongs to". This is the DURABLE decision; it is a plain
+  // bounded-context slug, NOT a folder knob. Different features consume it:
+  //
+  //   - #403 (the FIRST consumer): drives the generated code's
+  //     module output folder. clean-lite-ps nests the entity's module under
+  //     `<modules>/<context>/<entity>/` so same-context entities group
+  //     together; untagged entities stay flat (`<modules>/<entity>/`).
+  //   - ADR-0004 (deferred): a later `naming: prefix | schema` knob reads
+  //     this SAME field to drive the Postgres physical layout —
+  //     `prefix` → `pgTable('<context>__<table>')`, then the flip to
+  //     `schema` → `pgSchema('<context>').table('<table>')`. NOT wired here.
+  //
+  // Sibling to `surface:` and orthogonal to it (ADR-0006): context = model
+  // cohesion (which domain), surface = vendor composition (which integration).
+  // Lives inside the `entity:` block (next to `pattern:`/`name:`/`table:`).
+  context: z3.string().regex(
+    /^[a-z][a-z0-9_]*$/,
+    "context must be lowercase snake_case (e.g. 'integration')"
+  ).optional()
 }).strict().refine((d) => !(d.pattern && d.patterns), {
   message: "'pattern' and 'patterns' are mutually exclusive"
 });
@@ -1427,36 +1470,11 @@ var EntityDefinitionSchema = z3.object({
   // appear in `integration.providers` — see the superRefine on
   // `EntityDefinitionSchema` below.
   detection: z3.record(z3.string(), DetectionConfigSchema).optional(),
-  // RFC-0001 §1/§8: the integration *surface* this entity belongs to
-  // (e.g. 'calendar', 'mail', 'crm'). Surfaces span provider contexts
-  // (ADR-0006) — one Google OAuth feeds calendar+mail+transcript. The union
-  // of `surface:` values across all entity YAML is the closed set that a
-  // provider's `surfaces:` must be a subset of (cross-checked in
-  // src/parser/validate-providers.ts). Optional: entities without an
-  // integration surface omit it. The surface-package *emission* convention
-  // is Track C (#329); this field is only the declarative input both tracks
-  // read.
-  surface: z3.string().optional(),
-  // Bounded-context declaration (ADR-0004) — "which bounded context this
-  // entity belongs to". This is the DURABLE decision; it is a plain
-  // bounded-context slug, NOT a folder knob. Different features consume it:
-  //
-  //   - #403 (this PR, the FIRST consumer): drives the generated code's
-  //     module output folder. clean-lite-ps nests the entity's module under
-  //     `<modules>/<context>/<entity>/` so same-context entities group
-  //     together; untagged entities stay flat (`<modules>/<entity>/`).
-  //   - ADR-0004 (deferred): a later `naming: prefix | schema` knob reads
-  //     this SAME field to drive the Postgres physical layout —
-  //     `prefix` → `pgTable('<context>__<table>')`, then the flip to
-  //     `schema` → `pgSchema('<context>').table('<table>')`. NOT wired here;
-  //     #403 makes no table/column/schema changes.
-  //
-  // Sibling to `surface:` and orthogonal to it (ADR-0006): context = model
-  // cohesion (which domain), surface = vendor composition (which integration).
-  context: z3.string().regex(
-    /^[a-z][a-z0-9_]*$/,
-    "context must be lowercase snake_case (e.g. 'integration')"
-  ).optional(),
+  // NOTE: `surface:` and `context:` moved INTO EntityConfigSchema (the
+  // `entity:` block) in 0.12.2 — consumers write them next to
+  // `pattern:`/`name:`/`table:`, which is the natural place. They are
+  // read via `entity.surface` / `entity.context`. Clean break: no
+  // root-level placement is accepted.
   // v2: Domain event declarations (CODEGEN-EVOLUTION-PLAN Phase 2)
   // Generates typed event classes, handlers, and queue registration
   events: z3.array(EventDeclarationSchema).optional(),
@@ -2246,13 +2264,13 @@ function loadErrorToIssue(error) {
   }
   return issues;
 }
-function loadEntities(entitiesDir) {
+function loadEntities(entitiesDir, opts) {
   const entities = [];
   const issues = [];
   const resolvedDir = resolve2(entitiesDir);
   let files;
   try {
-    files = findYamlFiles(resolvedDir);
+    files = findYamlFiles(resolvedDir, { excludeDirs: opts?.excludeDirs });
   } catch (err) {
     issues.push({
       severity: "error",