Merge remote-tracking branch 'origin/main' into feat/metadata-validation

# Conflicts:
#	server/csharp/MetaObjects/CoreTypes.cs
#	server/csharp/MetaObjects/Registry.cs
#	server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java
#	server/java/metadata/src/main/java/com/metaobjects/registry/MetaDataRegistry.java
#	server/java/metadata/src/main/java/com/metaobjects/registry/TypeDefinition.java
#	server/java/metadata/src/main/java/com/metaobjects/registry/TypeDefinitionBuilder.java
#	server/python/src/metaobjects/core_types.py
#	server/python/src/metaobjects/registry.py
#	server/typescript/packages/metadata/src/registry.ts

Author: dmealing

agent-context/skills/metaobjects-authoring/SKILL.md

@@ -165,6 +165,26 @@ Reuse a constraint set across entities with an abstract `field.enum` + `extends`
 { "field.object": { "name": "address", "@objectRef": "Address", "@storage": "flattened" } }
 ```
 
+**Arrays of value objects** — set `isArray: true` with `@storage: jsonb`. The whole
+array lives in **one** jsonb column (a JSON array), never a native `jsonb[]`. The
+generated Postgres column is typed `.$type<VO[]>()` and the Zod schema is
+`z.array(<VO>InsertSchema)`:
+
+```json
+{ "field.object": { "name": "triples", "@objectRef": "Triple",
+    "@storage": "jsonb", "isArray": true } }
+```
+
+**Opaque jsonb (no value object)** — when the payload has no fixed shape (freeform
+config, passthrough metadata, an open-keyed map), do NOT use `field.object` (it
+requires `@objectRef`, and a partial VO would let the generated Zod strip unknown
+keys → data loss). Model it as a `field.string` with the physical-type override
+`@dbColumnType: jsonb` — the logical type stays string-bound, the column is jsonb:
+
+```json
+{ "field.string": { "name": "metadata", "@dbColumnType": "jsonb" } }
+```
+
 ## YAML sigil-free authoring + the coercion footgun
 
 In YAML, write the fused `type.subType` key with a **map body**, bare reserved
@@ -205,6 +225,12 @@ reference for navigation/typing/codegen only. Referential actions
 (`@onDelete`/`@onUpdate`) are NOT on `identity.reference` — they live on the
 `relationship.*` node (see Relationships below).
 
+`@references` resolves cross-package by **fully-qualified name**
+(`@references: "shared::billing::Account"`), the same rule as `extends`; a bare
+name resolves within the current package. The FK target must be an entity with a
+single-column primary key (the FK points at that PK); a target with a composite
+PK needs the explicit dotted form `@references: "pkg::Target.fieldA,fieldB"`.
+
 ```json
 { "identity.primary":   { "name": "id", "@fields": ["id"], "@generation": "increment" } }
 { "identity.secondary": { "name": "byEmail", "@fields": ["email"] } }
@@ -229,6 +255,17 @@ the two halves of one FK.
     "@cardinality": "many", "@onDelete": "cascade" } }
 ```
 
+**Adoption footgun — pin BOTH actions.** `@onDelete` and `@onUpdate` each default to
+`cascade` when omitted, but a plain SQL foreign key is `NO ACTION` on both. If you're
+adopting an existing database (matching metadata to a live schema), omitting these
+makes the metadata declare `CASCADE` where the DB has `NO ACTION` — a perpetual
+`verify --db` drift. Pin **both** explicitly to the DB's real behavior:
+
+```json
+{ "relationship.composition": { "name": "author", "@objectRef": "User",
+    "@cardinality": "one", "@onDelete": "no-action", "@onUpdate": "no-action" } }
+```
+
 ## Sources — `source.rdb` + `@kind`
 
 `source.rdb` declares where an entity's data lives. Read-only-ness derives from

agent-context/skills/metaobjects-codegen/references/typescript.md

@@ -41,13 +41,25 @@ export default defineConfig({
   dialect: "postgres",                 // "postgres" | "sqlite" | "d1" (D1 is TS-only)
   apiPrefix: "/api",                   // flows to routes AND client fetch URLs
   columnNamingStrategy: "snake_case",  // "snake_case" (default) | "literal" | "kebab-case"
+  timestampMode: "string",             // "string" (default, ISO-8601 wire contract) | "date" (Drizzle native Date)
+  pluralizeCollections: true,          // default; table VARS auto-pluralize (AgentConfig → agentConfigs)
+  collectionNameOverrides: {           // per-entity escape hatch for names the rule gets wrong
+    AuditLog: "auditLog", LlmTierConfig: "llmTierConfig",
+  },
   generators: [
     entityFile(), queriesFile(), routesFile(), barrel(),
     formFile(), tanstackQuery(), tanstackGrid(),
   ],
 });
 ```
 
+Naming + timestamp knobs are **codegen config**, not metadata attributes — a
+collection variable name and a Drizzle column mode are per-port rendering choices
+with no meaning to the other language ports, so they carry no cross-port
+conformance cost. `collectionNameOverrides` wins over `pluralizeCollections` and is
+applied consistently to the table declaration, every FK reference, the `relations()`
+block, and the inferred types.
+
 A second file, `.metaobjects/config.json`, holds static project state parseable by
 non-TS tooling; `meta init` scaffolds both plus the `metaobjects/` source dir.
 
@@ -133,3 +145,21 @@ Deterministic per dialect: `field.string` + `@maxLength` → `varchar(N)`,
 (Postgres) + `gen_random_uuid()`, `field.enum` → `varchar` + `CHECK`. Override a
 field's physical column name with `@column` on the field; the DB schema name lives
 on `source.rdb` via `@schema`.
+
+### Value-object jsonb columns
+
+A `field.object` with `@storage: jsonb` (or the default `subdocument`) becomes a
+single typed jsonb column — the referenced value-object's TS type is carried onto
+the Drizzle column via `.$type<>()`, and its Zod schema is the VO's `InsertSchema`:
+
+```ts
+// field.object @objectRef=LlmConfig @storage=jsonb
+llmConfigJson: jsonb("llm_config_json").$type<LlmConfig>(),
+// field.object @objectRef=Triple @storage=jsonb isArray=true
+triples: jsonb("triples").$type<Triple[]>(),   // one jsonb column, NOT a native jsonb[]
+```
+
+The VO type, its Zod `InsertSchema`, and this `.$type<>()` all import the VO from
+the same module (layout/package/`extStyle`-aware resolution). An opaque jsonb column
+(`field.string @dbColumnType: jsonb`) gets no `.$type<>()` — it stays `unknown`,
+which is the correct shape for freeform payloads with no fixed VO.

agent-context/skills/metaobjects-verify/references/migration.md

@@ -66,7 +66,40 @@ A clean run is silent; a failure names the drifted table/column. Bias toward
 trusting the tool — a drift failure almost always means the metadata changed and the
 DB didn't follow.
 
+## Index modeling (Postgres)
+
+Secondary indexes carry physical-shape attributes contributed by the db provider
+(they live on `identity.secondary`, not core):
+
+- `@orders` — per-key sort direction, positional to `@fields` (`["asc", "desc"]`).
+  Omit for all-ascending; drives `DESC`-ordered index keys (e.g. a recency index).
+- `@where` — a partial-index predicate (raw SQL, e.g. `"delivered_at IS NULL"`),
+  emitted as `WHERE (<pred>)`. The index then covers only matching rows.
+
+```json
+{ "identity.secondary": { "@fields": ["userId", "createdAt"],
+    "@orders": ["asc", "desc"], "@where": "archived_at IS NULL" } }
+```
+
+## Adopting an existing database (non-destructive)
+
+`meta verify --db` / `meta migrate` can reach **zero drift** against a hand-built
+schema without a rewrite:
+
+- **`meta migrate --from-db`** reverse-engineers a baseline from the live DB so the
+  first diff is empty.
+- **Auto schema-scope** — the diff manages only the schemas the metadata *declares*
+  (via `source.rdb @schema`); tables in undeclared schemas belong to another owner
+  and are left untouched. This is what lets several apps share one database, each
+  owning its own schema, with a clean per-owner `verify --db` and no manual ignore
+  lists. A downstream app that extends the toolkit's DB declares its own `@schema`,
+  models only its tables, and runs its own migrate/verify against that scope.
+- **`identity.reference @constraintName`** pins a foreign-key constraint name so the
+  metadata can match an existing DB's naming convention without a destructive
+  rename.
+
 ## Not yet shipped
 
-Triggers, generated columns, partial/exclusion/check constraints, MySQL, and data
+Triggers, generated columns, exclusion + CHECK constraints, MySQL, and data
 migrations (column-type changes needing data transformation error out with a hint).
+(Partial + descending **indexes** *are* supported — see Index modeling above.)

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -165,6 +165,26 @@ Reuse a constraint set across entities with an abstract `field.enum` + `extends`
 { "field.object": { "name": "address", "@objectRef": "Address", "@storage": "flattened" } }
 ```
 
+**Arrays of value objects** — set `isArray: true` with `@storage: jsonb`. The whole
+array lives in **one** jsonb column (a JSON array), never a native `jsonb[]`. The
+generated Postgres column is typed `.$type<VO[]>()` and the Zod schema is
+`z.array(<VO>InsertSchema)`:
+
+```json
+{ "field.object": { "name": "triples", "@objectRef": "Triple",
+    "@storage": "jsonb", "isArray": true } }
+```
+
+**Opaque jsonb (no value object)** — when the payload has no fixed shape (freeform
+config, passthrough metadata, an open-keyed map), do NOT use `field.object` (it
+requires `@objectRef`, and a partial VO would let the generated Zod strip unknown
+keys → data loss). Model it as a `field.string` with the physical-type override
+`@dbColumnType: jsonb` — the logical type stays string-bound, the column is jsonb:
+
+```json
+{ "field.string": { "name": "metadata", "@dbColumnType": "jsonb" } }
+```
+
 ## YAML sigil-free authoring + the coercion footgun
 
 In YAML, write the fused `type.subType` key with a **map body**, bare reserved
@@ -205,6 +225,12 @@ reference for navigation/typing/codegen only. Referential actions
 (`@onDelete`/`@onUpdate`) are NOT on `identity.reference` — they live on the
 `relationship.*` node (see Relationships below).
 
+`@references` resolves cross-package by **fully-qualified name**
+(`@references: "shared::billing::Account"`), the same rule as `extends`; a bare
+name resolves within the current package. The FK target must be an entity with a
+single-column primary key (the FK points at that PK); a target with a composite
+PK needs the explicit dotted form `@references: "pkg::Target.fieldA,fieldB"`.
+
 ```json
 { "identity.primary":   { "name": "id", "@fields": ["id"], "@generation": "increment" } }
 { "identity.secondary": { "name": "byEmail", "@fields": ["email"] } }
@@ -229,6 +255,17 @@ the two halves of one FK.
     "@cardinality": "many", "@onDelete": "cascade" } }
 ```
 
+**Adoption footgun — pin BOTH actions.** `@onDelete` and `@onUpdate` each default to
+`cascade` when omitted, but a plain SQL foreign key is `NO ACTION` on both. If you're
+adopting an existing database (matching metadata to a live schema), omitting these
+makes the metadata declare `CASCADE` where the DB has `NO ACTION` — a perpetual
+`verify --db` drift. Pin **both** explicitly to the DB's real behavior:
+
+```json
+{ "relationship.composition": { "name": "author", "@objectRef": "User",
+    "@cardinality": "one", "@onDelete": "no-action", "@onUpdate": "no-action" } }
+```
+
 ## Sources — `source.rdb` + `@kind`
 
 `source.rdb` declares where an entity's data lives. Read-only-ness derives from

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-verify/references/migration.md

@@ -66,7 +66,40 @@ A clean run is silent; a failure names the drifted table/column. Bias toward
 trusting the tool — a drift failure almost always means the metadata changed and the
 DB didn't follow.
 
+## Index modeling (Postgres)
+
+Secondary indexes carry physical-shape attributes contributed by the db provider
+(they live on `identity.secondary`, not core):
+
+- `@orders` — per-key sort direction, positional to `@fields` (`["asc", "desc"]`).
+  Omit for all-ascending; drives `DESC`-ordered index keys (e.g. a recency index).
+- `@where` — a partial-index predicate (raw SQL, e.g. `"delivered_at IS NULL"`),
+  emitted as `WHERE (<pred>)`. The index then covers only matching rows.
+
+```json
+{ "identity.secondary": { "@fields": ["userId", "createdAt"],
+    "@orders": ["asc", "desc"], "@where": "archived_at IS NULL" } }
+```
+
+## Adopting an existing database (non-destructive)
+
+`meta verify --db` / `meta migrate` can reach **zero drift** against a hand-built
+schema without a rewrite:
+
+- **`meta migrate --from-db`** reverse-engineers a baseline from the live DB so the
+  first diff is empty.
+- **Auto schema-scope** — the diff manages only the schemas the metadata *declares*
+  (via `source.rdb @schema`); tables in undeclared schemas belong to another owner
+  and are left untouched. This is what lets several apps share one database, each
+  owning its own schema, with a clean per-owner `verify --db` and no manual ignore
+  lists. A downstream app that extends the toolkit's DB declares its own `@schema`,
+  models only its tables, and runs its own migrate/verify against that scope.
+- **`identity.reference @constraintName`** pins a foreign-key constraint name so the
+  metadata can match an existing DB's naming convention without a destructive
+  rename.
+
 ## Not yet shipped
 
-Triggers, generated columns, partial/exclusion/check constraints, MySQL, and data
+Triggers, generated columns, exclusion + CHECK constraints, MySQL, and data
 migrations (column-type changes needing data transformation error out with a hint).
+(Partial + descending **indexes** *are* supported — see Index modeling above.)

fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -165,6 +165,26 @@ Reuse a constraint set across entities with an abstract `field.enum` + `extends`
 { "field.object": { "name": "address", "@objectRef": "Address", "@storage": "flattened" } }
 ```
 
+**Arrays of value objects** — set `isArray: true` with `@storage: jsonb`. The whole
+array lives in **one** jsonb column (a JSON array), never a native `jsonb[]`. The
+generated Postgres column is typed `.$type<VO[]>()` and the Zod schema is
+`z.array(<VO>InsertSchema)`:
+
+```json
+{ "field.object": { "name": "triples", "@objectRef": "Triple",
+    "@storage": "jsonb", "isArray": true } }
+```
+
+**Opaque jsonb (no value object)** — when the payload has no fixed shape (freeform
+config, passthrough metadata, an open-keyed map), do NOT use `field.object` (it
+requires `@objectRef`, and a partial VO would let the generated Zod strip unknown
+keys → data loss). Model it as a `field.string` with the physical-type override
+`@dbColumnType: jsonb` — the logical type stays string-bound, the column is jsonb:
+
+```json
+{ "field.string": { "name": "metadata", "@dbColumnType": "jsonb" } }
+```
+
 ## YAML sigil-free authoring + the coercion footgun
 
 In YAML, write the fused `type.subType` key with a **map body**, bare reserved
@@ -205,6 +225,12 @@ reference for navigation/typing/codegen only. Referential actions
 (`@onDelete`/`@onUpdate`) are NOT on `identity.reference` — they live on the
 `relationship.*` node (see Relationships below).
 
+`@references` resolves cross-package by **fully-qualified name**
+(`@references: "shared::billing::Account"`), the same rule as `extends`; a bare
+name resolves within the current package. The FK target must be an entity with a
+single-column primary key (the FK points at that PK); a target with a composite
+PK needs the explicit dotted form `@references: "pkg::Target.fieldA,fieldB"`.
+
 ```json
 { "identity.primary":   { "name": "id", "@fields": ["id"], "@generation": "increment" } }
 { "identity.secondary": { "name": "byEmail", "@fields": ["email"] } }
@@ -229,6 +255,17 @@ the two halves of one FK.
     "@cardinality": "many", "@onDelete": "cascade" } }
 ```
 
+**Adoption footgun — pin BOTH actions.** `@onDelete` and `@onUpdate` each default to
+`cascade` when omitted, but a plain SQL foreign key is `NO ACTION` on both. If you're
+adopting an existing database (matching metadata to a live schema), omitting these
+makes the metadata declare `CASCADE` where the DB has `NO ACTION` — a perpetual
+`verify --db` drift. Pin **both** explicitly to the DB's real behavior:
+
+```json
+{ "relationship.composition": { "name": "author", "@objectRef": "User",
+    "@cardinality": "one", "@onDelete": "no-action", "@onUpdate": "no-action" } }
+```
+
 ## Sources — `source.rdb` + `@kind`
 
 `source.rdb` declares where an entity's data lives. Read-only-ness derives from

fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-verify/references/migration.md

@@ -66,7 +66,40 @@ A clean run is silent; a failure names the drifted table/column. Bias toward
 trusting the tool — a drift failure almost always means the metadata changed and the
 DB didn't follow.
 
+## Index modeling (Postgres)
+
+Secondary indexes carry physical-shape attributes contributed by the db provider
+(they live on `identity.secondary`, not core):
+
+- `@orders` — per-key sort direction, positional to `@fields` (`["asc", "desc"]`).
+  Omit for all-ascending; drives `DESC`-ordered index keys (e.g. a recency index).
+- `@where` — a partial-index predicate (raw SQL, e.g. `"delivered_at IS NULL"`),
+  emitted as `WHERE (<pred>)`. The index then covers only matching rows.
+
+```json
+{ "identity.secondary": { "@fields": ["userId", "createdAt"],
+    "@orders": ["asc", "desc"], "@where": "archived_at IS NULL" } }
+```
+
+## Adopting an existing database (non-destructive)
+
+`meta verify --db` / `meta migrate` can reach **zero drift** against a hand-built
+schema without a rewrite:
+
+- **`meta migrate --from-db`** reverse-engineers a baseline from the live DB so the
+  first diff is empty.
+- **Auto schema-scope** — the diff manages only the schemas the metadata *declares*
+  (via `source.rdb @schema`); tables in undeclared schemas belong to another owner
+  and are left untouched. This is what lets several apps share one database, each
+  owning its own schema, with a clean per-owner `verify --db` and no manual ignore
+  lists. A downstream app that extends the toolkit's DB declares its own `@schema`,
+  models only its tables, and runs its own migrate/verify against that scope.
+- **`identity.reference @constraintName`** pins a foreign-key constraint name so the
+  metadata can match an existing DB's naming convention without a destructive
+  rename.
+
 ## Not yet shipped
 
-Triggers, generated columns, partial/exclusion/check constraints, MySQL, and data
+Triggers, generated columns, exclusion + CHECK constraints, MySQL, and data
 migrations (column-type changes needing data transformation error out with a hint).
+(Partial + descending **indexes** *are* supported — see Index modeling above.)