@metaobjectsdev/sdk 0.10.0 → 0.11.0

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

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

@@ -41,6 +41,11 @@ 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(),
@@ -48,6 +53,13 @@ export default defineConfig({
 });
 ```
 
+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.

package/agent-context/skills/metaobjects-prompts/SKILL.md

@@ -123,6 +123,47 @@ For the `xml`-format example above with payload `{ displayName: "Ada", postCount
 bytes. You render the prompt, call your LLM client (provider-agnostic — codegen
 emits no provider-side schema), then parse the response.
 
+## Conditional content: data and flags, never branched prose
+
+When a prompt's wording varies along some dimension — audience, tier, mode,
+locale, entitlement, a domain variant — do NOT branch the prose in code and
+concatenate strings. Branching prompt text in a service is the anti-pattern this
+pillar exists to remove: it scatters the same distinction across call sites, each
+re-encoded and free to drift, and none of it snapshot-tested. The variation
+belongs in exactly two places, with a third for the rare genuine divergence:
+
+- **Vocabulary as payload data.** The words and values that differ become typed
+  payload fields, pre-computed once from the varying dimension — a noun, a label,
+  a set of verbs (a list), an example. The template stays single and references
+  `{{term}}` / `{{#items}}…{{/items}}`. The prose *structure* is identical across
+  variants; only the data differs, so there is nothing to branch.
+- **Presence as boolean flags.** When a whole block exists-or-not for a variant,
+  gate it with a section flag the payload sets: `{{#showBlock}}…{{/showBlock}}`.
+  Reserve flags for entire blocks — never mid-sentence word swaps, which are
+  vocabulary.
+- **Variant text only when prose truly diverges.** If a section's wording — not
+  just its vocabulary — genuinely differs, select a per-variant text through the
+  provider seam (a `@textRef` variant, or an included partial) so the shared
+  prose still lives in one place. Expect to need this rarely.
+
+A single resolver maps the varying dimension to that payload (the flags + the
+vocabulary), so the distinction is defined ONCE and every template that depends
+on it stays consistent.
+
+```
+// WRONG — prose branched and concatenated in a service:
+if (tier.isPremium()) sb.append("Your plan includes priority support.");
+else                  sb.append("Upgrade any time for priority support.");
+```
+```mustache
+{{! RIGHT — text in the template; the variant is data + a flag }}
+{{supportLine}}
+{{#isPremium}}(Priority queue enabled.){{/isPremium}}
+```
+
+This stays deterministic and golden-testable per variant: render the template
+against each value of the dimension and snapshot every variant.
+
 ## `verify` fails the build on prompt-drift
 
 For every template, the verify step resolves the text, parses each `{{...}}`

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.10.0",
+    "@metaobjectsdev/metadata": "0.11.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {