@metaobjectsdev/metadata 0.12.0 → 0.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/dist/core/field/field-definition.embedded.d.ts.map +1 -1
  2. package/dist/core/field/field-definition.embedded.js +20 -7
  3. package/dist/core/field/field-definition.embedded.js.map +1 -1
  4. package/dist/core/identity/identity-definition.embedded.d.ts.map +1 -1
  5. package/dist/core/identity/identity-definition.embedded.js +3 -0
  6. package/dist/core/identity/identity-definition.embedded.js.map +1 -1
  7. package/dist/core/object/object-definition.embedded.d.ts.map +1 -1
  8. package/dist/core/object/object-definition.embedded.js +3 -0
  9. package/dist/core/object/object-definition.embedded.js.map +1 -1
  10. package/dist/core/relationship/relationship-definition.embedded.d.ts.map +1 -1
  11. package/dist/core/relationship/relationship-definition.embedded.js +3 -0
  12. package/dist/core/relationship/relationship-definition.embedded.js.map +1 -1
  13. package/dist/core/validator/validator-definition.embedded.d.ts.map +1 -1
  14. package/dist/core/validator/validator-definition.embedded.js +10 -1
  15. package/dist/core/validator/validator-definition.embedded.js.map +1 -1
  16. package/dist/persistence/origin/origin-definition.embedded.d.ts.map +1 -1
  17. package/dist/persistence/origin/origin-definition.embedded.js +3 -0
  18. package/dist/persistence/origin/origin-definition.embedded.js.map +1 -1
  19. package/dist/persistence/source/source-definition.embedded.d.ts.map +1 -1
  20. package/dist/persistence/source/source-definition.embedded.js +1 -0
  21. package/dist/persistence/source/source-definition.embedded.js.map +1 -1
  22. package/dist/template/template-definition.embedded.d.ts.map +1 -1
  23. package/dist/template/template-definition.embedded.js +2 -0
  24. package/dist/template/template-definition.embedded.js.map +1 -1
  25. package/package.json +1 -1
  26. package/src/core/field/field-definition.embedded.ts +20 -7
  27. package/src/core/identity/identity-definition.embedded.ts +3 -0
  28. package/src/core/object/object-definition.embedded.ts +3 -0
  29. package/src/core/relationship/relationship-definition.embedded.ts +3 -0
  30. package/src/core/validator/validator-definition.embedded.ts +10 -1
  31. package/src/persistence/origin/origin-definition.embedded.ts +3 -0
  32. package/src/persistence/source/source-definition.embedded.ts +1 -0
  33. package/src/template/template-definition.embedded.ts +2 -0
package/dist/core/field/field-definition.embedded.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"field-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/field/field-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,gBAAgB,EAAE,kBAoQ9B,CAAC"}
1
+ {"version":3,"file":"field-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/field/field-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,gBAAgB,EAAE,kBAiR9B,CAAC"}
package/dist/core/field/field-definition.embedded.js CHANGED
@@ -67,6 +67,7 @@ export const FIELD_DEFINITION = {
67
67
  "dataType": "string",
68
68
  "extendsBase": true,
69
69
  "description": "Variable-length text. Binds to the native string type; DB column is VARCHAR/TEXT (use @maxLength for VARCHAR(n)).",
70
+ "whenToUse": "Plain variable-length text. Set @maxLength to size the column. The default for textual data.",
70
71
  "children": [
71
72
  {
72
73
  "type": "attr",
@@ -83,21 +84,24 @@ export const FIELD_DEFINITION = {
83
84
  "subType": "int",
84
85
  "dataType": "int",
85
86
  "extendsBase": true,
86
- "description": "32-bit signed integer. Binds to the native int type; DB column is INTEGER."
87
+ "description": "32-bit signed integer. Binds to the native int type; DB column is INTEGER.",
88
+ "whenToUse": "A whole number within +/-2^31. Use long instead if values can exceed that."
87
89
  },
88
90
  {
89
91
  "type": "field",
90
92
  "subType": "long",
91
93
  "dataType": "long",
92
94
  "extendsBase": true,
93
- "description": "64-bit signed integer. Binds to the native long/bigint type; DB column is BIGINT."
95
+ "description": "64-bit signed integer. Binds to the native long/bigint type; DB column is BIGINT.",
96
+ "whenToUse": "A whole number that may exceed 32 bits (ids, counters, epoch millis)."
94
97
  },
95
98
  {
96
99
  "type": "field",
97
100
  "subType": "double",
98
101
  "dataType": "double",
99
102
  "extendsBase": true,
100
- "description": "Double-precision (64-bit) IEEE-754 floating point. Binds to the native double/number type; DB column is DOUBLE PRECISION. Not for money — use field.currency or field.decimal."
103
+ "description": "Double-precision (64-bit) IEEE-754 floating point. Binds to the native double/number type; DB column is DOUBLE PRECISION. Not for money — use field.currency or field.decimal.",
104
+ "whenToUse": "An approximate floating-point number where exactness is not required. For money/precision use decimal."
101
105
  },
102
106
  {
103
107
  "type": "field",
@@ -112,6 +116,7 @@ export const FIELD_DEFINITION = {
112
116
  "dataType": "string",
113
117
  "extendsBase": true,
114
118
  "description": "Precision-exact decimal (use @precision/@scale). Native TS binding is string (lossless); DB column is NUMERIC(p,s); the wire form is a string. Classified DATA_TYPE_STRING so an exact decimal is never silently rounded through a double.",
119
+ "whenToUse": "A value needs exact precision (money amounts, rates, quantities). Use decimal with @precision/@scale — never double, which loses precision.",
115
120
  "rules": "The wire and native-TS form is a STRING to stay precision-exact end-to-end (Drizzle pg numeric infers as string; SP-H/ADR-0019). Set @precision (total significant digits) and @scale (digits right of the point) to drive NUMERIC(p,s).",
116
121
  "children": [
117
122
  {
@@ -137,14 +142,16 @@ export const FIELD_DEFINITION = {
137
142
  "subType": "boolean",
138
143
  "dataType": "boolean",
139
144
  "extendsBase": true,
140
- "description": "True/false flag. Binds to the native boolean type; DB column is BOOLEAN."
145
+ "description": "True/false flag. Binds to the native boolean type; DB column is BOOLEAN.",
146
+ "whenToUse": "A true/false flag."
141
147
  },
142
148
  {
143
149
  "type": "field",
144
150
  "subType": "date",
145
151
  "dataType": "date",
146
152
  "extendsBase": true,
147
- "description": "Calendar date (no time-of-day). Binds to the native date/temporal type; DB column is DATE."
153
+ "description": "Calendar date (no time-of-day). Binds to the native date/temporal type; DB column is DATE.",
154
+ "whenToUse": "A column is a calendar date with no time-of-day. Use date instead of a string."
148
155
  },
149
156
  {
150
157
  "type": "field",
@@ -158,7 +165,8 @@ export const FIELD_DEFINITION = {
158
165
  "subType": "timestamp",
159
166
  "dataType": "date",
160
167
  "extendsBase": true,
161
- "description": "Date + time-of-day instant (optionally with timezone). Binds to the native date/temporal type; DB column is TIMESTAMP(TZ). Pair with @autoSet for created/updated stamping."
168
+ "description": "Date + time-of-day instant (optionally with timezone). Binds to the native date/temporal type; DB column is TIMESTAMP(TZ). Pair with @autoSet for created/updated stamping.",
169
+ "whenToUse": "A column records an instant (created/updated at). Use timestamp so it serializes ISO-8601 with timezone consistently."
162
170
  },
163
171
  {
164
172
  "type": "field",
@@ -166,6 +174,7 @@ export const FIELD_DEFINITION = {
166
174
  "dataType": "object",
167
175
  "extendsBase": true,
168
176
  "description": "A nested structured value (set @objectRef to the target object). Storage is governed by @storage: flattened (prefixed columns), jsonb (single jsonb column, supports isArray), or subdocument (document-store hint).",
177
+ "whenToUse": "A field holds a nested structured value (or an array of them). Set @objectRef + @storage so the shape is typed and persisted (flattened/jsonb) instead of an untyped blob.",
169
178
  "rules": "Set @objectRef to the nested object's name (or FQN). @storage selects physical layout — flattened expands into prefixed parent columns (isArray must be false), jsonb stores the structured value (or array when isArray=true) in one jsonb column, subdocument emits no Postgres column. Defaults to single-jsonb-column when @storage is absent.",
170
179
  "children": [
171
180
  {
@@ -184,6 +193,7 @@ export const FIELD_DEFINITION = {
184
193
  "dataType": "object",
185
194
  "extendsBase": true,
186
195
  "description": "An open-keyed map (Record<string,V> / dict[str,V]) stored in a single jsonb column. Keys are always strings (the JSON object constraint); the value type is set by @valueType (a scalar field subtype) or @objectRef (a value-object).",
196
+ "whenToUse": "A field is an open-keyed map of values (Record<string,V>). Use it for dynamic keys instead of an untyped jsonb string.",
187
197
  "rules": "Keys are always strings. Set exactly one of @valueType (a scalar value subtype: string/int/long/double/float/decimal/boolean/date/time/timestamp/uuid) or @objectRef (a value-object name or FQN). Stored as a single jsonb column holding the JSON object — never a native array; isArray does not apply.",
188
198
  "children": [
189
199
  {
@@ -210,6 +220,7 @@ export const FIELD_DEFINITION = {
210
220
  "dataType": "long",
211
221
  "extendsBase": true,
212
222
  "description": "Stores money as integer minor units (cents). Binds to long; the client formats via @currency/@locale. Float arithmetic for money is forbidden.",
223
+ "whenToUse": "A column holds money. Use currency so it stores integer minor-units and the client formats it — never floats or hand-rolled cents math.",
213
224
  "rules": "Storage is integer minor units (cents for USD, yen for JPY) — the wire form is unchanged from long. The server never formats currency; all formatting is client-side via Intl.NumberFormat using @currency (ISO 4217) and @locale (BCP 47). Float arithmetic for money is forbidden.",
214
225
  "children": [
215
226
  {
@@ -229,6 +240,7 @@ export const FIELD_DEFINITION = {
229
240
  "dataType": "string",
230
241
  "extendsBase": true,
231
242
  "description": "String-backed enumeration constrained to a closed set of member symbols (@values). Each member is its own stored string with no name/value divergence.",
243
+ "whenToUse": "A field is a fixed, closed set of string values. Set @values so the union type, DB CHECK, and validation are generated — don't hand-roll constants + checks.",
232
244
  "rules": "Required @values is a non-empty, duplicate-free set; each member must match ^[A-Za-z_][A-Za-z0-9_]*$ so symbol == stored string in every target language. Optional FR-010/FR-011 overlays add tolerant-extract aliasing (@enumAlias), per-member docs (@enumDoc), an uncoercible-value fallback (@coerceDefault, must be one of @values), and ASCII normalization mode (@normalize).",
233
245
  "children": [
234
246
  {
@@ -255,7 +267,8 @@ export const FIELD_DEFINITION = {
255
267
  "subType": "uuid",
256
268
  "dataType": "string",
257
269
  "extendsBase": true,
258
- "description": "Logical UUID identity scalar. A bare scalar (no required attrs, no loader value-validation) — binds to TS string (no native UUID type); DB column is Postgres-native uuid."
270
+ "description": "Logical UUID identity scalar. A bare scalar (no required attrs, no loader value-validation) — binds to TS string (no native UUID type); DB column is Postgres-native uuid.",
271
+ "whenToUse": "A key or external identifier is a UUID. Use it for a typed UUID column instead of a plain string."
259
272
  }
260
273
  ]
261
274
  };
package/dist/core/field/field-definition.embedded.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"field-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/field/field-definition.embedded.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"field-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/field/field-definition.embedded.ts"],"names":[],"mappings":"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"}
package/dist/core/identity/identity-definition.embedded.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"identity-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/identity/identity-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,mBAAmB,EAAE,kBA2FjC,CAAC"}
1
+ {"version":3,"file":"identity-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/identity/identity-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,mBAAmB,EAAE,kBA8FjC,CAAC"}
package/dist/core/identity/identity-definition.embedded.js CHANGED
@@ -5,6 +5,7 @@ export const IDENTITY_DEFINITION = {
5
5
  "type": "identity",
6
6
  "subType": "primary",
7
7
  "description": "The primary key — one per entity; @fields names its column(s), @generation the value strategy.",
8
+ "whenToUse": "Every entity needs exactly one — names the primary-key field(s) and how the value is generated. Always declare it.",
8
9
  "maxOccurs": 1,
9
10
  "defaultName": "primary",
10
11
  "children": [
@@ -36,6 +37,7 @@ export const IDENTITY_DEFINITION = {
36
37
  "type": "identity",
37
38
  "subType": "secondary",
38
39
  "description": "A secondary index (unique by default via @unique).",
40
+ "whenToUse": "A column or set must be unique, or you want an index for lookups/sorting. Declare it instead of a hand-written UNIQUE constraint or CREATE INDEX.",
39
41
  "children": [
40
42
  {
41
43
  "type": "attr",
@@ -60,6 +62,7 @@ export const IDENTITY_DEFINITION = {
60
62
  "type": "identity",
61
63
  "subType": "reference",
62
64
  "description": "A foreign-key reference to another entity (@references target; @enforce toggles a physical FK).",
65
+ "whenToUse": "This entity holds a foreign key to another. Declare it to generate the FK constraint + typed navigation, instead of a loose id field you join on by hand.",
63
66
  "children": [
64
67
  {
65
68
  "type": "attr",
package/dist/core/identity/identity-definition.embedded.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"identity-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/identity/identity-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,mBAAmB,GAAuB;IACrD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,SAAS;YACpB,aAAa,EAAE,gGAAgG;YAC/G,WAAW,EAAE,CAAC;YACd,aAAa,EAAE,SAAS;YACxB,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,4GAA4G;iBAC5H;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,YAAY;oBACpB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,WAAW;wBACX,MAAM;wBACN,UAAU;qBACX;oBACD,aAAa,EAAE,+GAA+G;iBAC/H;aACF;SACF;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,WAAW;YACtB,aAAa,EAAE,oDAAoD;YACnE,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,4GAA4G;iBAC5H;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,SAAS;oBACpB,MAAM,EAAE,QAAQ;oBAChB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,2GAA2G;iBAC3H;aACF;SACF;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,WAAW;YACtB,aAAa,EAAE,iGAAiG;YAChH,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,4GAA4G;iBAC5H;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,YAAY;oBACpB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,2MAA2M;iBAC3N;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,SAAS;oBACpB,MAAM,EAAE,SAAS;oBACjB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,kQAAkQ;iBAClR;aACF;SACF;KACF;CACF,CAAC"}
1
+ {"version":3,"file":"identity-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/identity/identity-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,mBAAmB,GAAuB;IACrD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,SAAS;YACpB,aAAa,EAAE,gGAAgG;YAC/G,WAAW,EAAE,oHAAoH;YACjI,WAAW,EAAE,CAAC;YACd,aAAa,EAAE,SAAS;YACxB,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,4GAA4G;iBAC5H;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,YAAY;oBACpB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,WAAW;wBACX,MAAM;wBACN,UAAU;qBACX;oBACD,aAAa,EAAE,+GAA+G;iBAC/H;aACF;SACF;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,WAAW;YACtB,aAAa,EAAE,oDAAoD;YACnE,WAAW,EAAE,mJAAmJ;YAChK,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,4GAA4G;iBAC5H;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,SAAS;oBACpB,MAAM,EAAE,QAAQ;oBAChB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,2GAA2G;iBAC3H;aACF;SACF;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,WAAW;YACtB,aAAa,EAAE,iGAAiG;YAChH,WAAW,EAAE,2JAA2J;YACxK,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,4GAA4G;iBAC5H;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,YAAY;oBACpB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,2MAA2M;iBAC3N;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,SAAS;oBACpB,MAAM,EAAE,SAAS;oBACjB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,kQAAkQ;iBAClR;aACF;SACF;KACF;CACF,CAAC"}
package/dist/core/object/object-definition.embedded.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"object-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/object/object-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,iBAAiB,EAAE,kBA4G/B,CAAC"}
1
+ {"version":3,"file":"object-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/object/object-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,iBAAiB,EAAE,kBA+G/B,CAAC"}
package/dist/core/object/object-definition.embedded.js CHANGED
@@ -48,6 +48,7 @@ export const OBJECT_DEFINITION = {
48
48
  "subType": "entity",
49
49
  "extendsBase": true,
50
50
  "description": "An object that owns its data: own identity, writable sources, and lifecycle. The default object subtype — a bare `object:` key resolves to entity. May co-locate templates (template.prompt and friends) with the owning entity.",
51
+ "whenToUse": "The thing owns its own data and lifecycle — a table you create/read/update/delete. The default for any persisted resource.",
51
52
  "rules": "object.entity owns data — it declares its own identity, its primary source must be a writable @kind (read-only kinds may appear only in a read role), and it carries lifecycle. A field carrying origin.* is derived ⇒ read-only wherever it lives, including on an entity. Templates (template.*) may be nested so a prompt can be co-located with its owning entity. See ADR-0028 (object taxonomy).",
52
53
  "children": [
53
54
  {
@@ -87,6 +88,7 @@ export const OBJECT_DEFINITION = {
87
88
  "subType": "value",
88
89
  "extendsBase": true,
89
90
  "description": "A value object — pure shape with NO identity and NO source, ever. Constructed (by caller / assembly / embedding), never populated from a store. May `extends` an entity's fields to reuse shape. Equality is by content.",
91
+ "whenToUse": "You need a reusable typed shape with NO identity and NO table — an embedded value, a DTO, a prompt/response payload. Constructed in memory, never persisted on its own.",
90
92
  "rules": "object.value is pure shape: it NEVER declares an identity and NEVER declares a source, in any role. It is constructed — by a caller, by assembly, or by embedding — and is never populated from a backing store. It may `extends` an entity's fields to reuse their shape. @normalize is the object-level default ASCII normalization mode applied to this value's enum fields' tolerant extract (each field may still override per-field). See ADR-0028 (object taxonomy, value purity).",
91
93
  "children": [
92
94
  {
@@ -103,6 +105,7 @@ export const OBJECT_DEFINITION = {
103
105
  "subType": "projection",
104
106
  "extendsBase": true,
105
107
  "description": "A derived read-only representation of entities. Its fields are extends-bound / origin-derived / self-declared-under-external-assembly, all read-only at the subtype level. Identity is optional and MUST extend an entity identity; sources are restricted to read-only @kinds. The declared field set IS the exposure (inclusive, fail-closed).",
108
+ "whenToUse": "You need a derived, read-only view over entities — a report, summary, or joined/aggregated read model. Declare it (with origin.* children) instead of hand-writing the SELECT/joins; it stays read-only and regenerates.",
106
109
  "rules": "object.projection is a derived read-only representation: every field is extends-bound, origin-derived, or self-declared-under-external-assembly, and all are read-only at the subtype level. Identity is optional and, when present, MUST extend an entity identity. Sources are restricted to read-only @kinds. The declared field set IS the exposure — an inclusive list, fail-closed. A projection NEVER declares relationships (derivation is expressed via @via, not a relationship child) and NEVER co-locates templates — hence its child set omits both relationship and template. See ADR-0028 (object taxonomy, projection)."
107
110
  }
108
111
  ]
package/dist/core/object/object-definition.embedded.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"object-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/object/object-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,iBAAiB,GAAuB;IACnD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,MAAM;YACjB,aAAa,EAAE,kZAAkZ;YACja,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,OAAO;oBACf,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,UAAU;oBAClB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,WAAW;oBACnB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,QAAQ;YACnB,aAAa,EAAE,IAAI;YACnB,aAAa,EAAE,kOAAkO;YACjP,OAAO,EAAE,wYAAwY;YACjZ,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,cAAc;oBACtB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,UAAU;oBAClB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,eAAe;oBACvB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,mUAAmU;iBACnV;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,oBAAoB;oBAC5B,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,iUAAiU;iBACjV;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,OAAO;YAClB,aAAa,EAAE,IAAI;YACnB,aAAa,EAAE,0NAA0N;YACzO,OAAO,EAAE,2dAA2d;YACpe,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,cAAc;oBACtB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,YAAY;YACvB,aAAa,EAAE,IAAI;YACnB,aAAa,EAAE,kVAAkV;YACjW,OAAO,EAAE,ymBAAymB;SACnnB;KACF;CACF,CAAC"}
1
+ {"version":3,"file":"object-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/object/object-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,iBAAiB,GAAuB;IACnD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,MAAM;YACjB,aAAa,EAAE,kZAAkZ;YACja,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,OAAO;oBACf,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,UAAU;oBAClB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,WAAW;oBACnB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,QAAQ;YACnB,aAAa,EAAE,IAAI;YACnB,aAAa,EAAE,kOAAkO;YACjP,WAAW,EAAE,4HAA4H;YACzI,OAAO,EAAE,wYAAwY;YACjZ,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,cAAc;oBACtB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,UAAU;oBAClB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,eAAe;oBACvB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,mUAAmU;iBACnV;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,oBAAoB;oBAC5B,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,iUAAiU;iBACjV;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,OAAO;YAClB,aAAa,EAAE,IAAI;YACnB,aAAa,EAAE,0NAA0N;YACzO,WAAW,EAAE,yKAAyK;YACtL,OAAO,EAAE,2dAA2d;YACpe,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,cAAc;oBACtB,SAAS,EAAE,GAAG;oBACd,MAAM,EAAE,GAAG;oBACX,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,IAAI;iBACZ;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,YAAY;YACvB,aAAa,EAAE,IAAI;YACnB,aAAa,EAAE,kVAAkV;YACjW,WAAW,EAAE,0NAA0N;YACvO,OAAO,EAAE,ymBAAymB;SACnnB;KACF;CACF,CAAC"}
package/dist/core/relationship/relationship-definition.embedded.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"relationship-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/relationship/relationship-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,uBAAuB,EAAE,kBAoTrC,CAAC"}
1
+ {"version":3,"file":"relationship-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/relationship/relationship-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,uBAAuB,EAAE,kBAuTrC,CAAC"}
package/dist/core/relationship/relationship-definition.embedded.js CHANGED
@@ -81,6 +81,7 @@ export const RELATIONSHIP_DEFINITION = {
81
81
  "type": "relationship",
82
82
  "subType": "association",
83
83
  "description": "A plain reference to another entity — no ownership; the target has an independent lifecycle (default @onDelete restrict).",
84
+ "whenToUse": "A plain directed reference to another entity, no ownership or cascade. The lightest link — when you just need to point at another entity.",
84
85
  "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Association is a plain reference — the target's lifecycle is independent (default @onDelete restrict).",
85
86
  "children": [
86
87
  {
@@ -157,6 +158,7 @@ export const RELATIONSHIP_DEFINITION = {
157
158
  "type": "relationship",
158
159
  "subType": "aggregation",
159
160
  "description": "A shared/independent containment — the parent groups the target but does not own its lifecycle (default @onDelete set-null).",
161
+ "whenToUse": "One entity groups others it does NOT own (children outlive the parent; delete sets the FK null). Use instead of composition when there is no ownership.",
160
162
  "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Aggregation is shared/independent — the target outlives the parent (default @onDelete set-null).",
161
163
  "children": [
162
164
  {
@@ -233,6 +235,7 @@ export const RELATIONSHIP_DEFINITION = {
233
235
  "type": "relationship",
234
236
  "subType": "composition",
235
237
  "description": "An owned containment — the parent owns the target's lifecycle; deleting the parent deletes the children (default @onDelete cascade).",
238
+ "whenToUse": "You need a parent that OWNS a child collection (one-to-many, cascade on delete). Declare it to generate the FK + typed navigation instead of a bare FK field + hand-written joins.",
236
239
  "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Composition is owned lifecycle — the children do not outlive the parent (default @onDelete cascade).",
237
240
  "children": [
238
241
  {
package/dist/core/relationship/relationship-definition.embedded.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"relationship-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/relationship/relationship-definition.embedded.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"relationship-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/relationship/relationship-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,uBAAuB,GAAuB;IACzD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,cAAc;YACtB,SAAS,EAAE,MAAM;YACjB,aAAa,EAAE,iIAAiI;YAChJ,OAAO,EAAE,0uBAA0uB;YACnvB,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,aAAa;oBACrB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,6EAA6E;iBAC7F;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,qHAAqH;iBACrI;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,SAAS;oBACjB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,mMAAmM;iBACnN;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,gBAAgB;oBACxB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,oNAAoN;iBACpO;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,SAAS;oBACpB,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,yIAAyI;iBACzJ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,SAAS;wBACT,UAAU;wBACV,UAAU;wBACV,WAAW;qBACZ;oBACD,aAAa,EAAE,sIAAsI;iBACtJ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,SAAS;wBACT,UAAU;wBACV,UAAU;wBACV,WAAW;qBACZ;oBACD,aAAa,EAAE,oDAAoD;iBACpE;aACF;SACF;QACD;YACE,MAAM,EAAE,cAAc;YACtB,SAAS,EAAE,aAAa;YACxB,aAAa,EAAE,2HAA2H;YAC1I,WAAW,EAAE,2IAA2I;YACxJ,OAAO,EAAE,wlBAAwlB;YACjmB,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,aAAa;oBACrB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,6EAA6E;iBAC7F;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,qHAAqH;iBACrI;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,SAAS;oBACjB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,mMAAmM;iBACnN;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,gBAAgB;oBACxB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,oNAAoN;iBACpO;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,SAAS;oBACpB,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,yIAAyI;iBACzJ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,SAAS;wBACT,UAAU;wBACV,UAAU;wBACV,WAAW;qBACZ;oBACD,aAAa,EAAE,sIAAsI;iBACtJ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,SAAS;wBACT,UAAU;wBACV,UAAU;wBACV,WAAW;qBACZ;oBACD,aAAa,EAAE,oDAAoD;iBACpE;aACF;SACF;QACD;YACE,MAAM,EAAE,cAAc;YACtB,SAAS,EAAE,aAAa;YACxB,aAAa,EAAE,8HAA8H;YAC7I,WAAW,EAAE,yJAAyJ;YACtK,OAAO,EAAE,klBAAklB;YAC3lB,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,aAAa;oBACrB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,6EAA6E;iBAC7F;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,qHAAqH;iBACrI;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,SAAS;oBACjB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,mMAAmM;iBACnN;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,gBAAgB;oBACxB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,oNAAoN;iBACpO;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,SAAS;oBACpB,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,yIAAyI;iBACzJ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,SAAS;wBACT,UAAU;wBACV,UAAU;wBACV,WAAW;qBACZ;oBACD,aAAa,EAAE,sIAAsI;iBACtJ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,SAAS;wBACT,UAAU;wBACV,UAAU;wBACV,WAAW;qBACZ;oBACD,aAAa,EAAE,oDAAoD;iBACpE;aACF;SACF;QACD;YACE,MAAM,EAAE,cAAc;YACtB,SAAS,EAAE,aAAa;YACxB,aAAa,EAAE,sIAAsI;YACrJ,WAAW,EAAE,oLAAoL;YACjM,OAAO,EAAE,slBAAslB;YAC/lB,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,aAAa;oBACrB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,6EAA6E;iBAC7F;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,qHAAqH;iBACrI;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,SAAS;oBACjB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,mMAAmM;iBACnN;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,gBAAgB;oBACxB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,oNAAoN;iBACpO;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,SAAS;oBACpB,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,yIAAyI;iBACzJ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,SAAS;wBACT,UAAU;wBACV,UAAU;wBACV,WAAW;qBACZ;oBACD,aAAa,EAAE,sIAAsI;iBACtJ;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,SAAS;wBACT,UAAU;wBACV,UAAU;wBACV,WAAW;qBACZ;oBACD,aAAa,EAAE,oDAAoD;iBACpE;aACF;SACF;KACF;CACF,CAAC"}
package/dist/core/validator/validator-definition.embedded.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"validator-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/validator/validator-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,oBAAoB,EAAE,kBA6PlC,CAAC"}
1
+ {"version":3,"file":"validator-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/core/validator/validator-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,oBAAoB,EAAE,kBAsQlC,CAAC"}
package/dist/core/validator/validator-definition.embedded.js CHANGED
@@ -27,12 +27,14 @@ export const VALIDATOR_DEFINITION = {
27
27
  {
28
28
  "type": "validator",
29
29
  "subType": "required",
30
- "description": "Fails when the value is null/empty (NOT NULL). Equivalent to @required on the owning field."
30
+ "description": "Fails when the value is null/empty (NOT NULL). Equivalent to @required on the owning field.",
31
+ "whenToUse": "A field must be present (NOT NULL). Declare it instead of hand-writing a null/empty check."
31
32
  },
32
33
  {
33
34
  "type": "validator",
34
35
  "subType": "length",
35
36
  "description": "Bounds string length / collection size via @min/@max.",
37
+ "whenToUse": "Bound a string's length or a collection's size. Use @min/@max instead of hand-written guards.",
36
38
  "children": [
37
39
  {
38
40
  "type": "attr",
@@ -56,6 +58,7 @@ export const VALIDATOR_DEFINITION = {
56
58
  "type": "validator",
57
59
  "subType": "regex",
58
60
  "description": "Requires the value match a regular expression (@pattern).",
61
+ "whenToUse": "A string must match a pattern (email, slug, code). Set @pattern instead of hand-writing the regex test.",
59
62
  "children": [
60
63
  {
61
64
  "type": "attr",
@@ -87,6 +90,7 @@ export const VALIDATOR_DEFINITION = {
87
90
  "type": "validator",
88
91
  "subType": "numeric",
89
92
  "description": "Bounds a numeric value's magnitude via @min/@max.",
93
+ "whenToUse": "Bound a number's magnitude. Use @min/@max instead of hand-written range checks.",
90
94
  "children": [
91
95
  {
92
96
  "type": "attr",
@@ -110,6 +114,7 @@ export const VALIDATOR_DEFINITION = {
110
114
  "type": "validator",
111
115
  "subType": "array",
112
116
  "description": "Bounds the element count of an array-valued field via @min/@max.",
117
+ "whenToUse": "Bound the element count of an array field. Use @min/@max instead of a hand-written length check.",
113
118
  "children": [
114
119
  {
115
120
  "type": "attr",
@@ -133,6 +138,7 @@ export const VALIDATOR_DEFINITION = {
133
138
  "type": "validator",
134
139
  "subType": "comparison",
135
140
  "description": "Cross-field ordering: requires two sibling fields of the owning entity stand in a relational order (@left @op @right), e.g. current_hp <= max_hp or expires_at > created_at. Entity-scoped; references fields by name. Backends derive the rule (CHECK constraint, cross-field assertion) — no raw expression is stored.",
141
+ "whenToUse": "Two sibling fields must stand in an order (start <= end, currentHp <= maxHp). Declare it instead of hand-writing the cross-field assertion.",
136
142
  "rules": "@left and @right must name fields of the owning entity. @op is one of gt/gte/lt/lte/ne/eq. The comparison is null-tolerant where the backend's relational operator is (SQL: a NULL operand yields no violation).",
137
143
  "children": [
138
144
  {
@@ -173,6 +179,7 @@ export const VALIDATOR_DEFINITION = {
173
179
  "type": "validator",
174
180
  "subType": "requiredWhen",
175
181
  "description": "One-directional conditional presence: when the gating field (@when) equals @equals, the target field (@field) must be present (NOT NULL); otherwise @field is unconstrained. Mirrors JSON Schema dependentRequired / Rails validates_presence_of :x, if:. Entity-scoped; references fields by name.",
182
+ "whenToUse": "A field becomes required only when another field has a given value. Declare it instead of conditional validation code.",
176
183
  "rules": "@field and @when must name fields of the owning entity. @equals is the gating value, compared against @when's value (rendered per @when's field subtype — boolean true/false, enum/string literal, numeric literal).",
177
184
  "children": [
178
185
  {
@@ -205,6 +212,7 @@ export const VALIDATOR_DEFINITION = {
205
212
  "type": "validator",
206
213
  "subType": "presentIff",
207
214
  "description": "Biconditional presence: the target field (@field) is present (NOT NULL) if and only if the gating field (@when) equals @equals. Models paired flag/companion-column invariants, e.g. used_at present iff is_used=true. Entity-scoped; references fields by name.",
215
+ "whenToUse": "A field must be present exactly when a condition holds, absent otherwise (biconditional). Declare it instead of hand-written presence logic.",
208
216
  "rules": "@field and @when must name fields of the owning entity. @equals is rendered per @when's field subtype. Stricter than requiredWhen — also forbids @field when the condition is false.",
209
217
  "children": [
210
218
  {
@@ -237,6 +245,7 @@ export const VALIDATOR_DEFINITION = {
237
245
  "type": "validator",
238
246
  "subType": "atLeastOne",
239
247
  "description": "Cardinality of presence: at least one of the named fields (@fields) must be present (NOT NULL). Entity-scoped; references fields by name (same @fields-by-name pattern as identity.*).",
248
+ "whenToUse": "At least one of several fields must be present (email or phone). Declare it instead of hand-written OR-presence checks.",
240
249
  "rules": "@fields names two or more fields of the owning entity. Satisfied when any one of them is non-null.",
241
250
  "children": [
242
251
  {
package/dist/core/validator/validator-definition.embedded.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"validator-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/validator/validator-definition.embedded.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"validator-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/validator/validator-definition.embedded.ts"],"names":[],"mappings":"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"}
package/dist/persistence/origin/origin-definition.embedded.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"origin-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/persistence/origin/origin-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,iBAAiB,EAAE,kBAsF/B,CAAC"}
1
+ {"version":3,"file":"origin-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/persistence/origin/origin-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,iBAAiB,EAAE,kBAyF/B,CAAC"}
package/dist/persistence/origin/origin-definition.embedded.js CHANGED
@@ -10,6 +10,7 @@ export const ORIGIN_DEFINITION = {
10
10
  "type": "origin",
11
11
  "subType": "passthrough",
12
12
  "description": "A cross-entity field reference: this projection field passes a source entity's value straight through (@from), optionally reached via a relationship path (@via).",
13
+ "whenToUse": "A projection field just surfaces a field from a related entity. Declare the cross-entity passthrough instead of re-joining and re-selecting it by hand.",
13
14
  "children": [
14
15
  {
15
16
  "type": "attr",
@@ -33,6 +34,7 @@ export const ORIGIN_DEFINITION = {
33
34
  "type": "origin",
34
35
  "subType": "aggregate",
35
36
  "description": "A count/sum/avg/min/max (@agg) computed over a column (@of) reached along a relationship path (@via) from the base entity.",
37
+ "whenToUse": "A projection needs a derived count/sum/avg/min/max over related rows. Declare it instead of hand-writing the aggregate query — it stays consistent and regenerates.",
36
38
  "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly.",
37
39
  "children": [
38
40
  {
@@ -72,6 +74,7 @@ export const ORIGIN_DEFINITION = {
72
74
  "type": "origin",
73
75
  "subType": "collection",
74
76
  "description": "A relationship-derived array of nested view-objects: walks @via to produce the collection (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection.",
77
+ "whenToUse": "A projection needs an array of nested child view-objects (a parent with its children inline). Declare it instead of hand-assembling the nested query + mapping.",
75
78
  "children": [
76
79
  {
77
80
  "type": "attr",
package/dist/persistence/origin/origin-definition.embedded.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"origin-definition.embedded.js","sourceRoot":"","sources":["../../../src/persistence/origin/origin-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,iBAAiB,GAAuB;IACnD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,MAAM;YACjB,aAAa,EAAE,wOAAwO;SACxP;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,aAAa;YACxB,aAAa,EAAE,mKAAmK;YAClL,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,MAAM;oBACd,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,yHAAyH;iBACzI;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,KAAK;oBACb,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,2FAA2F;iBAC3G;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,WAAW;YACtB,aAAa,EAAE,4HAA4H;YAC3I,OAAO,EAAE,mNAAmN;YAC5N,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,KAAK;oBACb,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,OAAO;wBACP,KAAK;wBACL,KAAK;wBACL,KAAK;wBACL,KAAK;qBACN;oBACD,aAAa,EAAE,sFAAsF;iBACtG;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,IAAI;oBACZ,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,sGAAsG;iBACtH;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,KAAK;oBACb,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,wPAAwP;iBACxQ;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,YAAY;YACvB,aAAa,EAAE,4KAA4K;YAC3L,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,KAAK;oBACb,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,2LAA2L;iBAC3M;aACF;SACF;KACF;CACF,CAAC"}
1
+ {"version":3,"file":"origin-definition.embedded.js","sourceRoot":"","sources":["../../../src/persistence/origin/origin-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,iBAAiB,GAAuB;IACnD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,MAAM;YACjB,aAAa,EAAE,wOAAwO;SACxP;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,aAAa;YACxB,aAAa,EAAE,mKAAmK;YAClL,WAAW,EAAE,yJAAyJ;YACtK,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,MAAM;oBACd,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,yHAAyH;iBACzI;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,KAAK;oBACb,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,2FAA2F;iBAC3G;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,WAAW;YACtB,aAAa,EAAE,4HAA4H;YAC3I,WAAW,EAAE,qKAAqK;YAClL,OAAO,EAAE,mNAAmN;YAC5N,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,KAAK;oBACb,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,eAAe,EAAE;wBACf,OAAO;wBACP,KAAK;wBACL,KAAK;wBACL,KAAK;wBACL,KAAK;qBACN;oBACD,aAAa,EAAE,sFAAsF;iBACtG;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,IAAI;oBACZ,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,sGAAsG;iBACtH;gBACD;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,KAAK;oBACb,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,wPAAwP;iBACxQ;aACF;SACF;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,YAAY;YACvB,aAAa,EAAE,4KAA4K;YAC3L,WAAW,EAAE,iKAAiK;YAC9K,UAAU,EAAE;gBACV;oBACE,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,KAAK;oBACb,KAAK,EAAE,CAAC;oBACR,KAAK,EAAE,CAAC;oBACR,aAAa,EAAE,2LAA2L;iBAC3M;aACF;SACF;KACF;CACF,CAAC"}
package/dist/persistence/source/source-definition.embedded.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"source-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/persistence/source/source-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,iBAAiB,EAAE,kBAe/B,CAAC"}
1
+ {"version":3,"file":"source-definition.embedded.d.ts","sourceRoot":"","sources":["../../../src/persistence/source/source-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,eAAO,MAAM,iBAAiB,EAAE,kBAgB/B,CAAC"}
package/dist/persistence/source/source-definition.embedded.js CHANGED
@@ -10,6 +10,7 @@ export const SOURCE_DEFINITION = {
10
10
  "type": "source",
11
11
  "subType": "rdb",
12
12
  "description": "The relational-database paradigm source (ADR-0007): binds an object to a physical relational object. Its physical name is the @table attr (not the structural `name`), and read-only-ness is DERIVED from @kind — table is writable; view, materializedView, storedProc, and tableFunction are read-only. The @table/@kind/@role/@schema/@parameterRef attrs are contributed by the db domain provider, not by core-types.",
13
+ "whenToUse": "The entity is backed by a relational table or view. Set @table/@kind — the default persistence source for any entity.",
13
14
  "rules": "ADR-0007: source declares where an object's data lives; rdb is the relational paradigm subtype. An object may declare multiple sources, distinguished by @role, with exactly ONE @role: \"primary\" per object (write-through CQRS: a writable table for writes plus a read-only view for reads). The physical name is the @table attr (or the @kind-matching alias), never the structural `name`. Read-only-ness is derived from @kind (table → writable; view / materializedView / storedProc / tableFunction → read-only). The pre-v2 dbTable / dbView subtypes are retired."
14
15
  }
15
16
  ]
package/dist/persistence/source/source-definition.embedded.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"source-definition.embedded.js","sourceRoot":"","sources":["../../../src/persistence/source/source-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,iBAAiB,GAAuB;IACnD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,MAAM;YACjB,aAAa,EAAE,uQAAuQ;SACvR;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,KAAK;YAChB,aAAa,EAAE,4ZAA4Z;YAC3a,OAAO,EAAE,ijBAAijB;SAC3jB;KACF;CACF,CAAC"}
1
+ {"version":3,"file":"source-definition.embedded.js","sourceRoot":"","sources":["../../../src/persistence/source/source-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,iBAAiB,GAAuB;IACnD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,MAAM;YACjB,aAAa,EAAE,uQAAuQ;SACvR;QACD;YACE,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,KAAK;YAChB,aAAa,EAAE,4ZAA4Z;YAC3a,WAAW,EAAE,uHAAuH;YACpI,OAAO,EAAE,ijBAAijB;SAC3jB;KACF;CACF,CAAC"}
package/dist/template/template-definition.embedded.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"template-definition.embedded.d.ts","sourceRoot":"","sources":["../../src/template/template-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,eAAO,MAAM,mBAAmB,EAAE,kBA4BjC,CAAC"}
1
+ {"version":3,"file":"template-definition.embedded.d.ts","sourceRoot":"","sources":["../../src/template/template-definition.embedded.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,eAAO,MAAM,mBAAmB,EAAE,kBA8BjC,CAAC"}
package/dist/template/template-definition.embedded.js CHANGED
@@ -11,12 +11,14 @@ export const TEMPLATE_DEFINITION = {
11
11
  "type": "template",
12
12
  "subType": "prompt",
13
13
  "description": "An LLM-targeted renderable prompt template (FR-004). Carries the generic reference + governance attrs plus the LLM overlay (@maxTokens / @requiredSlots / @model / @responseRef). Its renderable body is required via @textRef.",
14
+ "whenToUse": "You are sending text to an LLM. Declare a prompt template with a typed payload so the prompt is versioned, drift-checked against its fields, and cache-stable — instead of string-building it in code.",
14
15
  "rules": "prompt requires @payloadRef (the typed payload it renders against) AND @textRef (the body text, provider-resolved at render time — enforced in the loader's validateTemplatePayloadRefs pass, not at the attr layer where @textRef is relaxed to optional so template.output email can omit it). @format is a closed enum keyed by the render engine's escaper. @responseRef (optional) names the response value-object the prompt expects and drives typed LLM-call trace derivation."
15
16
  },
16
17
  {
17
18
  "type": "template",
18
19
  "subType": "output",
19
20
  "description": "An output / serialization template (FR-004): every rendered artifact other than an LLM prompt — a document (email, export, docs, config) or an email. Carries the generic reference + governance attrs, the FR-010 @promptStyle, and the @kind + email part-refs.",
21
+ "whenToUse": "You render a document/email/serialized output from typed data. Declare an output template so the {{fields}} are drift-checked against the payload VO at build time.",
20
22
  "rules": "output is either a document (@kind=\"document\" or absent → renders @textRef in @format to one string) or an email (@kind=\"email\" → renders subject + html + optional text to a structured EmailDocument). The cross-field presence rule is enforced in the loader's validateTemplatePayloadRefs pass: document requires @textRef; email requires @subjectRef AND @htmlBodyRef (with @textBodyRef optional) and carries NO @textRef. @format is a closed enum keyed by the render engine's escaper; @promptStyle (FR-010) selects the output-format prompt presentation and is never emitted as comments."
21
23
  },
22
24
  {
package/dist/template/template-definition.embedded.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"template-definition.embedded.js","sourceRoot":"","sources":["../../src/template/template-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,mBAAmB,GAAuB;IACrD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,MAAM;YACjB,aAAa,EAAE,4SAA4S;YAC3T,OAAO,EAAE,gWAAgW;SAC1W;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,QAAQ;YACnB,aAAa,EAAE,iOAAiO;YAChP,OAAO,EAAE,wdAAwd;SACle;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,QAAQ;YACnB,aAAa,EAAE,mQAAmQ;YAClR,OAAO,EAAE,6kBAA6kB;SACvlB;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,UAAU;YACrB,aAAa,EAAE,oSAAoS;YACnT,OAAO,EAAE,ukBAAukB;SACjlB;KACF;CACF,CAAC"}
1
+ {"version":3,"file":"template-definition.embedded.js","sourceRoot":"","sources":["../../src/template/template-definition.embedded.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,mBAAmB,GAAuB;IACrD,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE;QACP;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,MAAM;YACjB,aAAa,EAAE,4SAA4S;YAC3T,OAAO,EAAE,gWAAgW;SAC1W;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,QAAQ;YACnB,aAAa,EAAE,iOAAiO;YAChP,WAAW,EAAE,wMAAwM;YACrN,OAAO,EAAE,wdAAwd;SACle;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,QAAQ;YACnB,aAAa,EAAE,mQAAmQ;YAClR,WAAW,EAAE,qKAAqK;YAClL,OAAO,EAAE,6kBAA6kB;SACvlB;QACD;YACE,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,UAAU;YACrB,aAAa,EAAE,oSAAoS;YACnT,OAAO,EAAE,ukBAAukB;SACjlB;KACF;CACF,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@metaobjectsdev/metadata",
3
- "version": "0.12.0",
3
+ "version": "0.12.2",
4
4
  "description": "Metamodel loader, types, and constants for the MetaObjects standard.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
package/src/core/field/field-definition.embedded.ts CHANGED
@@ -75,6 +75,7 @@ export const FIELD_DEFINITION: ProviderDefinition = {
75
75
  "dataType": "string",
76
76
  "extendsBase": true,
77
77
  "description": "Variable-length text. Binds to the native string type; DB column is VARCHAR/TEXT (use @maxLength for VARCHAR(n)).",
78
+ "whenToUse": "Plain variable-length text. Set @maxLength to size the column. The default for textual data.",
78
79
  "children": [
79
80
  {
80
81
  "type": "attr",
@@ -91,21 +92,24 @@ export const FIELD_DEFINITION: ProviderDefinition = {
91
92
  "subType": "int",
92
93
  "dataType": "int",
93
94
  "extendsBase": true,
94
- "description": "32-bit signed integer. Binds to the native int type; DB column is INTEGER."
95
+ "description": "32-bit signed integer. Binds to the native int type; DB column is INTEGER.",
96
+ "whenToUse": "A whole number within +/-2^31. Use long instead if values can exceed that."
95
97
  },
96
98
  {
97
99
  "type": "field",
98
100
  "subType": "long",
99
101
  "dataType": "long",
100
102
  "extendsBase": true,
101
- "description": "64-bit signed integer. Binds to the native long/bigint type; DB column is BIGINT."
103
+ "description": "64-bit signed integer. Binds to the native long/bigint type; DB column is BIGINT.",
104
+ "whenToUse": "A whole number that may exceed 32 bits (ids, counters, epoch millis)."
102
105
  },
103
106
  {
104
107
  "type": "field",
105
108
  "subType": "double",
106
109
  "dataType": "double",
107
110
  "extendsBase": true,
108
- "description": "Double-precision (64-bit) IEEE-754 floating point. Binds to the native double/number type; DB column is DOUBLE PRECISION. Not for money — use field.currency or field.decimal."
111
+ "description": "Double-precision (64-bit) IEEE-754 floating point. Binds to the native double/number type; DB column is DOUBLE PRECISION. Not for money — use field.currency or field.decimal.",
112
+ "whenToUse": "An approximate floating-point number where exactness is not required. For money/precision use decimal."
109
113
  },
110
114
  {
111
115
  "type": "field",
@@ -120,6 +124,7 @@ export const FIELD_DEFINITION: ProviderDefinition = {
120
124
  "dataType": "string",
121
125
  "extendsBase": true,
122
126
  "description": "Precision-exact decimal (use @precision/@scale). Native TS binding is string (lossless); DB column is NUMERIC(p,s); the wire form is a string. Classified DATA_TYPE_STRING so an exact decimal is never silently rounded through a double.",
127
+ "whenToUse": "A value needs exact precision (money amounts, rates, quantities). Use decimal with @precision/@scale — never double, which loses precision.",
123
128
  "rules": "The wire and native-TS form is a STRING to stay precision-exact end-to-end (Drizzle pg numeric infers as string; SP-H/ADR-0019). Set @precision (total significant digits) and @scale (digits right of the point) to drive NUMERIC(p,s).",
124
129
  "children": [
125
130
  {
@@ -145,14 +150,16 @@ export const FIELD_DEFINITION: ProviderDefinition = {
145
150
  "subType": "boolean",
146
151
  "dataType": "boolean",
147
152
  "extendsBase": true,
148
- "description": "True/false flag. Binds to the native boolean type; DB column is BOOLEAN."
153
+ "description": "True/false flag. Binds to the native boolean type; DB column is BOOLEAN.",
154
+ "whenToUse": "A true/false flag."
149
155
  },
150
156
  {
151
157
  "type": "field",
152
158
  "subType": "date",
153
159
  "dataType": "date",
154
160
  "extendsBase": true,
155
- "description": "Calendar date (no time-of-day). Binds to the native date/temporal type; DB column is DATE."
161
+ "description": "Calendar date (no time-of-day). Binds to the native date/temporal type; DB column is DATE.",
162
+ "whenToUse": "A column is a calendar date with no time-of-day. Use date instead of a string."
156
163
  },
157
164
  {
158
165
  "type": "field",
@@ -166,7 +173,8 @@ export const FIELD_DEFINITION: ProviderDefinition = {
166
173
  "subType": "timestamp",
167
174
  "dataType": "date",
168
175
  "extendsBase": true,
169
- "description": "Date + time-of-day instant (optionally with timezone). Binds to the native date/temporal type; DB column is TIMESTAMP(TZ). Pair with @autoSet for created/updated stamping."
176
+ "description": "Date + time-of-day instant (optionally with timezone). Binds to the native date/temporal type; DB column is TIMESTAMP(TZ). Pair with @autoSet for created/updated stamping.",
177
+ "whenToUse": "A column records an instant (created/updated at). Use timestamp so it serializes ISO-8601 with timezone consistently."
170
178
  },
171
179
  {
172
180
  "type": "field",
@@ -174,6 +182,7 @@ export const FIELD_DEFINITION: ProviderDefinition = {
174
182
  "dataType": "object",
175
183
  "extendsBase": true,
176
184
  "description": "A nested structured value (set @objectRef to the target object). Storage is governed by @storage: flattened (prefixed columns), jsonb (single jsonb column, supports isArray), or subdocument (document-store hint).",
185
+ "whenToUse": "A field holds a nested structured value (or an array of them). Set @objectRef + @storage so the shape is typed and persisted (flattened/jsonb) instead of an untyped blob.",
177
186
  "rules": "Set @objectRef to the nested object's name (or FQN). @storage selects physical layout — flattened expands into prefixed parent columns (isArray must be false), jsonb stores the structured value (or array when isArray=true) in one jsonb column, subdocument emits no Postgres column. Defaults to single-jsonb-column when @storage is absent.",
178
187
  "children": [
179
188
  {
@@ -192,6 +201,7 @@ export const FIELD_DEFINITION: ProviderDefinition = {
192
201
  "dataType": "object",
193
202
  "extendsBase": true,
194
203
  "description": "An open-keyed map (Record<string,V> / dict[str,V]) stored in a single jsonb column. Keys are always strings (the JSON object constraint); the value type is set by @valueType (a scalar field subtype) or @objectRef (a value-object).",
204
+ "whenToUse": "A field is an open-keyed map of values (Record<string,V>). Use it for dynamic keys instead of an untyped jsonb string.",
195
205
  "rules": "Keys are always strings. Set exactly one of @valueType (a scalar value subtype: string/int/long/double/float/decimal/boolean/date/time/timestamp/uuid) or @objectRef (a value-object name or FQN). Stored as a single jsonb column holding the JSON object — never a native array; isArray does not apply.",
196
206
  "children": [
197
207
  {
@@ -218,6 +228,7 @@ export const FIELD_DEFINITION: ProviderDefinition = {
218
228
  "dataType": "long",
219
229
  "extendsBase": true,
220
230
  "description": "Stores money as integer minor units (cents). Binds to long; the client formats via @currency/@locale. Float arithmetic for money is forbidden.",
231
+ "whenToUse": "A column holds money. Use currency so it stores integer minor-units and the client formats it — never floats or hand-rolled cents math.",
221
232
  "rules": "Storage is integer minor units (cents for USD, yen for JPY) — the wire form is unchanged from long. The server never formats currency; all formatting is client-side via Intl.NumberFormat using @currency (ISO 4217) and @locale (BCP 47). Float arithmetic for money is forbidden.",
222
233
  "children": [
223
234
  {
@@ -237,6 +248,7 @@ export const FIELD_DEFINITION: ProviderDefinition = {
237
248
  "dataType": "string",
238
249
  "extendsBase": true,
239
250
  "description": "String-backed enumeration constrained to a closed set of member symbols (@values). Each member is its own stored string with no name/value divergence.",
251
+ "whenToUse": "A field is a fixed, closed set of string values. Set @values so the union type, DB CHECK, and validation are generated — don't hand-roll constants + checks.",
240
252
  "rules": "Required @values is a non-empty, duplicate-free set; each member must match ^[A-Za-z_][A-Za-z0-9_]*$ so symbol == stored string in every target language. Optional FR-010/FR-011 overlays add tolerant-extract aliasing (@enumAlias), per-member docs (@enumDoc), an uncoercible-value fallback (@coerceDefault, must be one of @values), and ASCII normalization mode (@normalize).",
241
253
  "children": [
242
254
  {
@@ -263,7 +275,8 @@ export const FIELD_DEFINITION: ProviderDefinition = {
263
275
  "subType": "uuid",
264
276
  "dataType": "string",
265
277
  "extendsBase": true,
266
- "description": "Logical UUID identity scalar. A bare scalar (no required attrs, no loader value-validation) — binds to TS string (no native UUID type); DB column is Postgres-native uuid."
278
+ "description": "Logical UUID identity scalar. A bare scalar (no required attrs, no loader value-validation) — binds to TS string (no native UUID type); DB column is Postgres-native uuid.",
279
+ "whenToUse": "A key or external identifier is a UUID. Use it for a typed UUID column instead of a plain string."
267
280
  }
268
281
  ]
269
282
  };
package/src/core/identity/identity-definition.embedded.ts CHANGED
@@ -13,6 +13,7 @@ export const IDENTITY_DEFINITION: ProviderDefinition = {
13
13
  "type": "identity",
14
14
  "subType": "primary",
15
15
  "description": "The primary key — one per entity; @fields names its column(s), @generation the value strategy.",
16
+ "whenToUse": "Every entity needs exactly one — names the primary-key field(s) and how the value is generated. Always declare it.",
16
17
  "maxOccurs": 1,
17
18
  "defaultName": "primary",
18
19
  "children": [
@@ -44,6 +45,7 @@ export const IDENTITY_DEFINITION: ProviderDefinition = {
44
45
  "type": "identity",
45
46
  "subType": "secondary",
46
47
  "description": "A secondary index (unique by default via @unique).",
48
+ "whenToUse": "A column or set must be unique, or you want an index for lookups/sorting. Declare it instead of a hand-written UNIQUE constraint or CREATE INDEX.",
47
49
  "children": [
48
50
  {
49
51
  "type": "attr",
@@ -68,6 +70,7 @@ export const IDENTITY_DEFINITION: ProviderDefinition = {
68
70
  "type": "identity",
69
71
  "subType": "reference",
70
72
  "description": "A foreign-key reference to another entity (@references target; @enforce toggles a physical FK).",
73
+ "whenToUse": "This entity holds a foreign key to another. Declare it to generate the FK constraint + typed navigation, instead of a loose id field you join on by hand.",
71
74
  "children": [
72
75
  {
73
76
  "type": "attr",
package/src/core/object/object-definition.embedded.ts CHANGED
@@ -56,6 +56,7 @@ export const OBJECT_DEFINITION: ProviderDefinition = {
56
56
  "subType": "entity",
57
57
  "extendsBase": true,
58
58
  "description": "An object that owns its data: own identity, writable sources, and lifecycle. The default object subtype — a bare `object:` key resolves to entity. May co-locate templates (template.prompt and friends) with the owning entity.",
59
+ "whenToUse": "The thing owns its own data and lifecycle — a table you create/read/update/delete. The default for any persisted resource.",
59
60
  "rules": "object.entity owns data — it declares its own identity, its primary source must be a writable @kind (read-only kinds may appear only in a read role), and it carries lifecycle. A field carrying origin.* is derived ⇒ read-only wherever it lives, including on an entity. Templates (template.*) may be nested so a prompt can be co-located with its owning entity. See ADR-0028 (object taxonomy).",
60
61
  "children": [
61
62
  {
@@ -95,6 +96,7 @@ export const OBJECT_DEFINITION: ProviderDefinition = {
95
96
  "subType": "value",
96
97
  "extendsBase": true,
97
98
  "description": "A value object — pure shape with NO identity and NO source, ever. Constructed (by caller / assembly / embedding), never populated from a store. May `extends` an entity's fields to reuse shape. Equality is by content.",
99
+ "whenToUse": "You need a reusable typed shape with NO identity and NO table — an embedded value, a DTO, a prompt/response payload. Constructed in memory, never persisted on its own.",
98
100
  "rules": "object.value is pure shape: it NEVER declares an identity and NEVER declares a source, in any role. It is constructed — by a caller, by assembly, or by embedding — and is never populated from a backing store. It may `extends` an entity's fields to reuse their shape. @normalize is the object-level default ASCII normalization mode applied to this value's enum fields' tolerant extract (each field may still override per-field). See ADR-0028 (object taxonomy, value purity).",
99
101
  "children": [
100
102
  {
@@ -111,6 +113,7 @@ export const OBJECT_DEFINITION: ProviderDefinition = {
111
113
  "subType": "projection",
112
114
  "extendsBase": true,
113
115
  "description": "A derived read-only representation of entities. Its fields are extends-bound / origin-derived / self-declared-under-external-assembly, all read-only at the subtype level. Identity is optional and MUST extend an entity identity; sources are restricted to read-only @kinds. The declared field set IS the exposure (inclusive, fail-closed).",
116
+ "whenToUse": "You need a derived, read-only view over entities — a report, summary, or joined/aggregated read model. Declare it (with origin.* children) instead of hand-writing the SELECT/joins; it stays read-only and regenerates.",
114
117
  "rules": "object.projection is a derived read-only representation: every field is extends-bound, origin-derived, or self-declared-under-external-assembly, and all are read-only at the subtype level. Identity is optional and, when present, MUST extend an entity identity. Sources are restricted to read-only @kinds. The declared field set IS the exposure — an inclusive list, fail-closed. A projection NEVER declares relationships (derivation is expressed via @via, not a relationship child) and NEVER co-locates templates — hence its child set omits both relationship and template. See ADR-0028 (object taxonomy, projection)."
115
118
  }
116
119
  ]
package/src/core/relationship/relationship-definition.embedded.ts CHANGED
@@ -89,6 +89,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
89
89
  "type": "relationship",
90
90
  "subType": "association",
91
91
  "description": "A plain reference to another entity — no ownership; the target has an independent lifecycle (default @onDelete restrict).",
92
+ "whenToUse": "A plain directed reference to another entity, no ownership or cascade. The lightest link — when you just need to point at another entity.",
92
93
  "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Association is a plain reference — the target's lifecycle is independent (default @onDelete restrict).",
93
94
  "children": [
94
95
  {
@@ -165,6 +166,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
165
166
  "type": "relationship",
166
167
  "subType": "aggregation",
167
168
  "description": "A shared/independent containment — the parent groups the target but does not own its lifecycle (default @onDelete set-null).",
169
+ "whenToUse": "One entity groups others it does NOT own (children outlive the parent; delete sets the FK null). Use instead of composition when there is no ownership.",
168
170
  "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Aggregation is shared/independent — the target outlives the parent (default @onDelete set-null).",
169
171
  "children": [
170
172
  {
@@ -241,6 +243,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
241
243
  "type": "relationship",
242
244
  "subType": "composition",
243
245
  "description": "An owned containment — the parent owns the target's lifecycle; deleting the parent deletes the children (default @onDelete cascade).",
246
+ "whenToUse": "You need a parent that OWNS a child collection (one-to-many, cascade on delete). Declare it to generate the FK + typed navigation instead of a bare FK field + hand-written joins.",
244
247
  "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Composition is owned lifecycle — the children do not outlive the parent (default @onDelete cascade).",
245
248
  "children": [
246
249
  {
package/src/core/validator/validator-definition.embedded.ts CHANGED
@@ -35,12 +35,14 @@ export const VALIDATOR_DEFINITION: ProviderDefinition = {
35
35
  {
36
36
  "type": "validator",
37
37
  "subType": "required",
38
- "description": "Fails when the value is null/empty (NOT NULL). Equivalent to @required on the owning field."
38
+ "description": "Fails when the value is null/empty (NOT NULL). Equivalent to @required on the owning field.",
39
+ "whenToUse": "A field must be present (NOT NULL). Declare it instead of hand-writing a null/empty check."
39
40
  },
40
41
  {
41
42
  "type": "validator",
42
43
  "subType": "length",
43
44
  "description": "Bounds string length / collection size via @min/@max.",
45
+ "whenToUse": "Bound a string's length or a collection's size. Use @min/@max instead of hand-written guards.",
44
46
  "children": [
45
47
  {
46
48
  "type": "attr",
@@ -64,6 +66,7 @@ export const VALIDATOR_DEFINITION: ProviderDefinition = {
64
66
  "type": "validator",
65
67
  "subType": "regex",
66
68
  "description": "Requires the value match a regular expression (@pattern).",
69
+ "whenToUse": "A string must match a pattern (email, slug, code). Set @pattern instead of hand-writing the regex test.",
67
70
  "children": [
68
71
  {
69
72
  "type": "attr",
@@ -95,6 +98,7 @@ export const VALIDATOR_DEFINITION: ProviderDefinition = {
95
98
  "type": "validator",
96
99
  "subType": "numeric",
97
100
  "description": "Bounds a numeric value's magnitude via @min/@max.",
101
+ "whenToUse": "Bound a number's magnitude. Use @min/@max instead of hand-written range checks.",
98
102
  "children": [
99
103
  {
100
104
  "type": "attr",
@@ -118,6 +122,7 @@ export const VALIDATOR_DEFINITION: ProviderDefinition = {
118
122
  "type": "validator",
119
123
  "subType": "array",
120
124
  "description": "Bounds the element count of an array-valued field via @min/@max.",
125
+ "whenToUse": "Bound the element count of an array field. Use @min/@max instead of a hand-written length check.",
121
126
  "children": [
122
127
  {
123
128
  "type": "attr",
@@ -141,6 +146,7 @@ export const VALIDATOR_DEFINITION: ProviderDefinition = {
141
146
  "type": "validator",
142
147
  "subType": "comparison",
143
148
  "description": "Cross-field ordering: requires two sibling fields of the owning entity stand in a relational order (@left @op @right), e.g. current_hp <= max_hp or expires_at > created_at. Entity-scoped; references fields by name. Backends derive the rule (CHECK constraint, cross-field assertion) — no raw expression is stored.",
149
+ "whenToUse": "Two sibling fields must stand in an order (start <= end, currentHp <= maxHp). Declare it instead of hand-writing the cross-field assertion.",
144
150
  "rules": "@left and @right must name fields of the owning entity. @op is one of gt/gte/lt/lte/ne/eq. The comparison is null-tolerant where the backend's relational operator is (SQL: a NULL operand yields no violation).",
145
151
  "children": [
146
152
  {
@@ -181,6 +187,7 @@ export const VALIDATOR_DEFINITION: ProviderDefinition = {
181
187
  "type": "validator",
182
188
  "subType": "requiredWhen",
183
189
  "description": "One-directional conditional presence: when the gating field (@when) equals @equals, the target field (@field) must be present (NOT NULL); otherwise @field is unconstrained. Mirrors JSON Schema dependentRequired / Rails validates_presence_of :x, if:. Entity-scoped; references fields by name.",
190
+ "whenToUse": "A field becomes required only when another field has a given value. Declare it instead of conditional validation code.",
184
191
  "rules": "@field and @when must name fields of the owning entity. @equals is the gating value, compared against @when's value (rendered per @when's field subtype — boolean true/false, enum/string literal, numeric literal).",
185
192
  "children": [
186
193
  {
@@ -213,6 +220,7 @@ export const VALIDATOR_DEFINITION: ProviderDefinition = {
213
220
  "type": "validator",
214
221
  "subType": "presentIff",
215
222
  "description": "Biconditional presence: the target field (@field) is present (NOT NULL) if and only if the gating field (@when) equals @equals. Models paired flag/companion-column invariants, e.g. used_at present iff is_used=true. Entity-scoped; references fields by name.",
223
+ "whenToUse": "A field must be present exactly when a condition holds, absent otherwise (biconditional). Declare it instead of hand-written presence logic.",
216
224
  "rules": "@field and @when must name fields of the owning entity. @equals is rendered per @when's field subtype. Stricter than requiredWhen — also forbids @field when the condition is false.",
217
225
  "children": [
218
226
  {
@@ -245,6 +253,7 @@ export const VALIDATOR_DEFINITION: ProviderDefinition = {
245
253
  "type": "validator",
246
254
  "subType": "atLeastOne",
247
255
  "description": "Cardinality of presence: at least one of the named fields (@fields) must be present (NOT NULL). Entity-scoped; references fields by name (same @fields-by-name pattern as identity.*).",
256
+ "whenToUse": "At least one of several fields must be present (email or phone). Declare it instead of hand-written OR-presence checks.",
248
257
  "rules": "@fields names two or more fields of the owning entity. Satisfied when any one of them is non-null.",
249
258
  "children": [
250
259
  {
package/src/persistence/origin/origin-definition.embedded.ts CHANGED
@@ -18,6 +18,7 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
18
18
  "type": "origin",
19
19
  "subType": "passthrough",
20
20
  "description": "A cross-entity field reference: this projection field passes a source entity's value straight through (@from), optionally reached via a relationship path (@via).",
21
+ "whenToUse": "A projection field just surfaces a field from a related entity. Declare the cross-entity passthrough instead of re-joining and re-selecting it by hand.",
21
22
  "children": [
22
23
  {
23
24
  "type": "attr",
@@ -41,6 +42,7 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
41
42
  "type": "origin",
42
43
  "subType": "aggregate",
43
44
  "description": "A count/sum/avg/min/max (@agg) computed over a column (@of) reached along a relationship path (@via) from the base entity.",
45
+ "whenToUse": "A projection needs a derived count/sum/avg/min/max over related rows. Declare it instead of hand-writing the aggregate query — it stays consistent and regenerates.",
44
46
  "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly.",
45
47
  "children": [
46
48
  {
@@ -80,6 +82,7 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
80
82
  "type": "origin",
81
83
  "subType": "collection",
82
84
  "description": "A relationship-derived array of nested view-objects: walks @via to produce the collection (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection.",
85
+ "whenToUse": "A projection needs an array of nested child view-objects (a parent with its children inline). Declare it instead of hand-assembling the nested query + mapping.",
83
86
  "children": [
84
87
  {
85
88
  "type": "attr",
package/src/persistence/source/source-definition.embedded.ts CHANGED
@@ -18,6 +18,7 @@ export const SOURCE_DEFINITION: ProviderDefinition = {
18
18
  "type": "source",
19
19
  "subType": "rdb",
20
20
  "description": "The relational-database paradigm source (ADR-0007): binds an object to a physical relational object. Its physical name is the @table attr (not the structural `name`), and read-only-ness is DERIVED from @kind — table is writable; view, materializedView, storedProc, and tableFunction are read-only. The @table/@kind/@role/@schema/@parameterRef attrs are contributed by the db domain provider, not by core-types.",
21
+ "whenToUse": "The entity is backed by a relational table or view. Set @table/@kind — the default persistence source for any entity.",
21
22
  "rules": "ADR-0007: source declares where an object's data lives; rdb is the relational paradigm subtype. An object may declare multiple sources, distinguished by @role, with exactly ONE @role: \"primary\" per object (write-through CQRS: a writable table for writes plus a read-only view for reads). The physical name is the @table attr (or the @kind-matching alias), never the structural `name`. Read-only-ness is derived from @kind (table → writable; view / materializedView / storedProc / tableFunction → read-only). The pre-v2 dbTable / dbView subtypes are retired."
22
23
  }
23
24
  ]
package/src/template/template-definition.embedded.ts CHANGED
@@ -19,12 +19,14 @@ export const TEMPLATE_DEFINITION: ProviderDefinition = {
19
19
  "type": "template",
20
20
  "subType": "prompt",
21
21
  "description": "An LLM-targeted renderable prompt template (FR-004). Carries the generic reference + governance attrs plus the LLM overlay (@maxTokens / @requiredSlots / @model / @responseRef). Its renderable body is required via @textRef.",
22
+ "whenToUse": "You are sending text to an LLM. Declare a prompt template with a typed payload so the prompt is versioned, drift-checked against its fields, and cache-stable — instead of string-building it in code.",
22
23
  "rules": "prompt requires @payloadRef (the typed payload it renders against) AND @textRef (the body text, provider-resolved at render time — enforced in the loader's validateTemplatePayloadRefs pass, not at the attr layer where @textRef is relaxed to optional so template.output email can omit it). @format is a closed enum keyed by the render engine's escaper. @responseRef (optional) names the response value-object the prompt expects and drives typed LLM-call trace derivation."
23
24
  },
24
25
  {
25
26
  "type": "template",
26
27
  "subType": "output",
27
28
  "description": "An output / serialization template (FR-004): every rendered artifact other than an LLM prompt — a document (email, export, docs, config) or an email. Carries the generic reference + governance attrs, the FR-010 @promptStyle, and the @kind + email part-refs.",
29
+ "whenToUse": "You render a document/email/serialized output from typed data. Declare an output template so the {{fields}} are drift-checked against the payload VO at build time.",
28
30
  "rules": "output is either a document (@kind=\"document\" or absent → renders @textRef in @format to one string) or an email (@kind=\"email\" → renders subject + html + optional text to a structured EmailDocument). The cross-field presence rule is enforced in the loader's validateTemplatePayloadRefs pass: document requires @textRef; email requires @subjectRef AND @htmlBodyRef (with @textBodyRef optional) and carries NO @textRef. @format is a closed enum keyed by the render engine's escaper; @promptStyle (FR-010) selects the output-format prompt presentation and is never emitted as comments."
29
31
  },
30
32
  {