Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ PyPI has had no product change since `0.25.0` — nothing is broken.
- **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + payload + relations + filter allowlist + validator + stored-proc + output-parser generators. `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.

**Cross-port conformance corpora** (every port runs the shared corpus):
- Metamodel: `fixtures/conformance/` (490 fixtures; 38 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
- Metamodel: `fixtures/conformance/` (510 fixtures; 38 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
- Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
- Persistence: `fixtures/persistence-conformance/`. **Query** scenarios run on every port (TS / C# / Java / Kotlin / Python), each provisioning its test DB by executing the committed, TS-produced `canonical/schema.postgres.sql` (Postgres only — Derby dropped for the cross-port query corpus, ADR-0015; the FR-044 `report-*` scenarios also run on SQLite, MySQL and D1 where a port has the engine, see [docs/CONFORMANCE.md](docs/CONFORMANCE.md)). The **migration** scenarios are exercised by **TS only** (TS owns schema migrations). **The corpus now gates WRITES, not just reads (SP-H):** an `op: roundtrip` scenario type INSERTs through each port's runtime/ORM write codec (NOT raw SQL), reads the row back, and asserts the wire-normalized value. The `AllTypes` entity (`roundtrip-all-types.yaml`) carries one field of **every** persistable `field.*` subtype — string/int/long/double/float/decimal/boolean/date/time/timestamp(+tz)/currency/enum/uuid/object — plus an **array-of-VO** `field.object @isArray @storage:jsonb` column (`labels`, written as 2-element / empty-`[]` / single-element arrays across the three rows) — so every subtype write+read (incl. the array-of-value-object jsonb codec) round-trips through every port against Testcontainers PG. (`field.byte`/`field.short`/`field.class` were cut as non-functional registration-only stubs — the matrix tracks only genuinely-supported subtypes; see `fixtures/registry-conformance/README.md` → "Per-subtype write-round-trip matrix".)
- API-contract: `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all green — each port runs **two lanes**: a hand-rolled reference server AND its **generated** API artifact booted over HTTP (the deployed controller/routes; TS+C# full-stack vs Testcontainers PG, Java/Kotlin/Python generated controller + in-memory repo behind the consumer seam). The generated fan-out found 10 real deployment bugs golden snapshots missed. Three sub-corpora run the **generated lane only, on all five ports** — `write-through/`, `projection/` (F22: a view-only `object.projection` serves GET list + GET by id and answers every write verb with `405 {"error": "method_not_allowed"}`) and `report/` (FR-044: a view-backed `object.report` serves GET list, answers `POST` with that same `405`, and mounts no `/{id}` route). That is deliberate, not a gap: what is under test is whether a port's GENERATOR emits those routes, and a hand-rolled reference server would answer every scenario by construction. The `m2m/` sub-corpus also gates **TPH x M:N together** (base-declared, subtype-declared, abstract-mid-declared, a non-subtype source onto a subtype TARGET, and the cross-subtype source id answering `200 []`) — the two corpora were originally built disjoint (`tph/` had no relationships, `m2m/` no discriminators), which is precisely how that defect class survived.
Expand Down
62 changes: 54 additions & 8 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,9 @@ _npm `1.3.0` (full lockstep across all 14 `@metaobjectsdev/*` publish candidates
**`metamodelVersion` moves to `1.3`.** This release adds vocabulary (`field.duration`,
`validator.exactlyOne`, `@constraintName`, `@condition`, `@maxLength` on `field.enum`,
`@sequenceStart`, `@sequenceName`, `@flattenedColumnPrefix`, the `pascal` column rule,
`@collectionName`, and the `case` and `now` expression nodes) and nothing that loaded before
stops loading. The registry gains two
`@collectionName`, the `case` and `now` expression nodes, `@segment` on `origin.first` /
`origin.aggregate`, and the `isDistinctFrom` / `isNotDistinctFrom` filter ops) and nothing that
loaded before stops loading. The registry gains two
fields on a type or attr entry, carried into the registry manifest: `implementedIn` (cross-port
vocabulary only the named ports implement so far, e.g. the `view.*` controls, `["typescript"]`) and
`ports` (vocabulary only the named ports ever act on, e.g. `@objectAdapter`, `["java", "kotlin"]`:
Expand Down Expand Up @@ -147,9 +148,13 @@ Each item below is described in full under Added, Changed or Fixed; this list is
`[csharp-only]`) and its JSON carries `ports`. `@objectAdapter` is the one there is.
- **`@collectionName`, and the `naming.collections` pluralizer.** An `object.entity`,
`object.projection` or `object.report` may name its collection in its own casing
(`"@collectionName": "CaseHistory"`); it need not be a grammatical plural. The generated C#
context uses it as the DbSet property name in place of the derived plural, and the routes, the
reverse finders and the api reference read the property through it. Absent, the project's
(`"@collectionName": "CaseHistory"`); it need not be a grammatical plural. In C# and TypeScript it
names the REST collection segment, snake_cased with an acronym-aware split (`FAQs` serves
`/faqs`, shared by `fixtures/naming-conformance/collection-segments.json`), and the reverse
finders; in C# also the DbSet property (in place of the derived plural, which the api reference
reads through it), and in TypeScript the list function, the list hook and the Drizzle table
variable. Two objects whose collection names meet are refused by name. A project that declares
neither the attr nor `naming.collections` keeps every generated name and URL. Absent, the project's
pluralizer derives the name: `"naming": { "collections": "standard" }` (the default) or `"none"`
in `.metaobjects/config.json`, or one the application registers (`registerPluralizer` in
TypeScript, `NamingStrategies.RegisterPluralizer` in C#, `NamingStrategies.registerPluralizer` in
Expand All @@ -173,9 +178,16 @@ Each item below is described in full under Added, Changed or Fixed; this list is
`operand`), and a ref in it may name another of the projection's own fields (a passthrough,
an `origin.first` or another `origin.computed`, never itself or an aggregate) before a base
field (`origin-computed-case-over-joined`, `error-origin-computed-case-mixed-types`). A
simple `case` compares a literal `when` with any `operand`, so an enum or long operand maps
its codes to labels. A `case`'s results and a `coalesce`'s arguments unify a numeric literal
with any numeric field and a `now` with a date or timestamp (`origin-computed-literal-unifies`);
simple `case` compares a literal `when` with its `operand`, so an enum or long operand maps
its codes to labels. A literal compared with a field, as a `when` against a field operand or
on either side of a comparison, must be of that field's kind and, for a `field.enum`, one of
its `@values`, the rule a validator `@condition` already follows (`ERR_INVALID_ORIGIN`,
`error-origin-computed-literal-not-enum-member`, `error-origin-computed-literal-wrong-kind`).
A `case`'s results and a `coalesce`'s arguments unify a whole-number
literal with any numeric field, a fractional literal only with a `field.double`, `field.float`
or `field.decimal` (refused beside a long, int or currency field,
`error-origin-computed-literal-fractional`), and a `now` with a date or timestamp
(`origin-computed-literal-unifies`);
- the loaders refuse what a view cannot lower: a `now` whose value is not an ISO-8601 duration
or whose `startOf` is not day, week or month (`error-origin-computed-now-bad-duration`); a
searched `case` whose `when` is not boolean (`error-origin-computed-case-non-boolean-when`);
Expand All @@ -189,6 +201,40 @@ Each item below is described in full under Added, Changed or Fixed; this list is
`error-origin-computed-node-mixed-keys`);
- a validator `@condition` still refuses `case` and `now` (`ERR_BAD_ATTR_VALUE`,
`error-validator-condition-now`): it becomes a database CHECK, which can hold neither.
- **Segments and correlated filters on origins.** An `origin.first` / `origin.aggregate` may scope
its related rows by a `@segment` declared on that entity (`ERR_INVALID_ORIGIN` otherwise), and
its `@filter` may compare a related column with a base-row field (`{ "eq": { "field":
"statusId" } }`, or the null-safe `isDistinctFrom` / `isNotDistinctFrom`, which take only such an
operand; `ERR_BAD_ATTR_FILTER` for an unknown base field or another op). Every port's loader
validates them (`origin-segment-scoped`, `origin-correlated-filter-and-segment`,
`error-origin-segment-unresolved`, `error-origin-correlated-operand-unknown`).
- **Filter paths, flattened members and inherited filters in projections.** A projection's
`@filter` key may name a field of its base entity the view does not output, or a path of to-one
hops from the base. A projection that extends another is checked against the effective (ANDed)
filter of its chain. An origin's `@from` / `@of` may name a member of a flattened value object.
Every port's loader validates them, gated by eleven new shared fixtures. A report dimension's
required flag now treats an unenforced reference, or a hop onto a TPH subtype, as possibly
missing.
- **A view the lowering cannot express is refused, not shortened.** The TypeScript view extractor
skipped any origin it could not lower, so a projection loaded clean and `meta migrate` created a
view missing a column its generated type declares. Each such shape now fails, naming the
projection and the field: an origin `@segment`, a base-row operand in an origin `@filter`, a
computed node the lowering does not support, and an unknown origin or aggregate. A projection
that extends another projection now fails too, naming the projection: the lowering reads only
the fields and `@filter` declared on the projection itself, so the view it created dropped the
inherited columns and the inherited row gate.
- **A reference over a flattened member reads the member's column.** A reference whose `@fields`
names a member of a flattened value object (`"address.countryId"`) now resolves to that member's
real column in the foreign key `meta migrate` emits, a view's join, a passthrough `@from` onto
the member, and the Drizzle key the reverse finder and `relations()` block read. Two references
onto one target now each read the join their own `@via` walked, rather than the first join to
that entity.
- **One wording for a to-many passthrough, in every port.** The refusal of a passthrough across a
reverse `@via` hop names the hop as the path wrote it and the reference it walks
(`@via hop "consents" is to-many (reverse hop over identity.reference "patient")`), and Java's and
Python's wording of the refusal now matches the other ports'. The fixtures
`error-origin-passthrough-reverse-hop` (new) and `error-origin-passthrough-to-many` pin the
message.

- **An int-backed enum can be an array.** `@intValueMap` together with `isArray: true` (the
map on the field, or inherited from a shared enum) now loads in every port instead of
Expand Down
15 changes: 9 additions & 6 deletions docs/CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l` for directory-shaped corpor

| Corpus | Fixtures | TS | Java | Kotlin | C# | Python |
|---|---|---|---|---|---|---|
| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 490 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 510 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
| [`fixtures/yaml-conformance/`](../fixtures/yaml-conformance/) | 16 | 16 / 16 | 15 / 16 (1 ledgered: `yaml-quoted-leading-zero` — Java pipeline strips quotes off `"007"`) | inherits via Java | 15 / 16 (1 ledgered: `error-yaml-coerced-hex-in-string` — YamlDotNet doesn't coerce `0xFF`) | 16 / 16 |
| [`fixtures/verify-conformance/`](../fixtures/verify-conformance/) | 45 | ✓ | ✓ | inherits via Java | ✓ | ✓ |
| [`fixtures/verify-strict-conformance/`](../fixtures/verify-strict-conformance/) | 1 | ✓ | — | — | — | ✓ |
Expand Down Expand Up @@ -148,9 +148,12 @@ canonical (`fixtures/registry-conformance/expected-registry.json`).
- `view.image`, and its `@accept`, `@aspectRatio`, `@maxBytes`, `@maxEdge`, `@store`
- *Implemented in Java only* (`implementedIn: ["java"]`): `object.* @object` (ADR-0001), the
native class an object binds to. Java's runtime acts on it; Java's own behaviour is unchanged.
- *Implemented in C# only* (`implementedIn: ["csharp"]`): `object.* @collectionName`, the
collection name the generated DbSet takes. Every port registers it and reads the `naming.collections`
key that names the default pluralizer; C# codegen does not apply that pluralizer yet.
- *Implemented in C# and TypeScript* (`implementedIn: ["csharp", "typescript"]`): `object.*
@collectionName`, an object's collection name: the REST collection segment and reverse-finder
names in both, the DbSet in C#, the list function, list hook and Drizzle table variable in
TypeScript. Both apply the `naming.collections` pluralizer to an object that declares none
(`fixtures/naming-conformance/collection-segments.json`); every port registers and type-checks
the attr and the key.
- *Loads strictly in every port.* Each port registers the `metaobjects-ui-web` provider
(`view.textarea @rows`, the `view.image` attrs) and `@object` / `@objectAdapter` on
`object.*`, loads all three fixtures strictly, and emits `implementedIn` in its manifest, which
Expand Down Expand Up @@ -354,7 +357,7 @@ unit-test runners (`bun test`, `dotnet test`, `pytest`, `mvn test`) pull Docker.

## Fixture-to-doc mapping

### `fixtures/conformance/` — metamodel loader + canonical serializer (490)
### `fixtures/conformance/` — metamodel loader + canonical serializer (510)

| Fixture prefix | Feature doc |
|---|---|
Expand Down Expand Up @@ -716,7 +719,7 @@ JSON and verify payload feeds it unchanged.

## Orphaned fixtures (tested but not yet documented)

The fixtures in the nine corpora mapped above (metamodel 490 + yaml 16 + verify 45
The fixtures in the nine corpora mapped above (metamodel 510 + yaml 16 + verify 45
+ render 18 + persistence 62 + api-contract 123 + source-resolution 25 + scope 10 +
dependency 47) each map to a feature doc, and so do the two requirement corpora, `shared-model-conformance`, the
`cube-model` corpus and `explorer-conformance`, whose case lists live in their own READMEs. None are orphaned today. The remaining
Expand Down
23 changes: 22 additions & 1 deletion docs/features/migrations/physical-naming.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ every runtime `ObjectManager` and `verify` read it, so they always produce the s
|---|---|---|---|
| `columns` | `snake_case`, `literal`, `kebab-case`, `pascal`, or a name your application registered | a field with no `@column` | `snake_case` |
| `tables` | `snake_case`, `literal`, or a name your application registered | a source with no `@table`/`@view`/`@proc`/`@function`: its `name`, else the object's name made plural | `snake_case` |
| `collections` | `standard`, `none`, or a name your application registered | an object with no `@collectionName`: the collection name the generated C# DbSet takes and a backwards `@via` hop is named by | `standard` |
| `collections` | `standard`, `none`, or a name your application registered | an object with no `@collectionName`: its collection name (see below) and the name a backwards `@via` hop is named by | `standard` |

An unknown key fails when the file is read, and so does a name no registered strategy answers.
Index and constraint names are unchanged.
Expand Down Expand Up @@ -73,6 +73,27 @@ the port's reset when it is done (`resetNamingStrategiesForTesting()`,
`NamingStrategies.ResetForTesting()`, `NamingStrategies.resetForTesting()`,
`reset_naming_strategies_for_testing()`), which leaves only the built-ins.

### Collection names

An object's collection name is its own `@collectionName`, else the `collections` pluralizer over
its name. C# and TypeScript generators read it (the other ports load and type-check both, and
act on neither yet, #549):

| Artifact | Port | `Faq` with `@collectionName: "FAQs"` | `Order` under `collections: "none"` |
|---|---|---|---|
| REST collection segment | C#, TypeScript | `/faqs` | `/order` |
| Reverse finder | C#, TypeScript | `FindFAQsByOwner` / `findFAQsByOwner` | `FindOrderByFaq` / `findOrderByFaq` |
| DbSet property | C# | `FAQs` | `Order` |
| List function, list hook, Drizzle table variable | TypeScript | `listFAQs`, `useFAQs`, `fAQs` | `listOrder`, `useOrderList`, `order` |

The REST segment is the collection name snake_cased, with a trailing plural `s` after an acronym
kept on it (`FAQs` serves `/faqs`, `TaxIDs` serves `/tax_ids`). With neither `@collectionName` nor
a `collections` setting, every name is what it has always been: the segment is the snake_cased
name made plural, as every port serves it. A list hook whose name would equal the detail hook's
takes a `List` suffix. The cases both ports run are in
`fixtures/naming-conformance/collection-segments.json`. Changing either one changes URLs and
generated names an application calls, so treat it as an API change.

A name nothing registered fails when the file is read, naming the setting, the name, the port,
and what is registered:

Expand Down
13 changes: 12 additions & 1 deletion docs/features/source-kinds.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,10 @@ emitter, two hosts.

A derived field must be **providable** — a read-capable source must be able to carry it. A
derived field on a table-only entity (no read source) is a load error
(`ERR_DERIVED_FIELD_NO_READ_SOURCE`).
(`ERR_DERIVED_FIELD_NO_READ_SOURCE`), with one exception: an `origin.first` or `origin.computed`
that a projection reaches through its `@filter` or a passthrough `@from` is inlined there, so it
needs no read source. The entity's table then gets no column for it: generated entity, DbContext,
Kotlin, Python `ObjectManager` and Java OMDB mappings leave such a field out of table reads and writes.

### Entity read-view vs projection — which to reach for

Expand Down Expand Up @@ -204,6 +207,14 @@ never itself or an aggregate), else a base field. An `origin.first` or `origin.a
`@filter`, like a projection's, may hold a relative date (`{ "now": "-P7D" }`, see
[reporting.md](reporting.md#relative-dates-in-filters)). Every port's loader validates these.

**Segments and correlated filters.** An `origin.first` or `origin.aggregate` may scope its
related rows by a `@segment` declared on that entity (ANDed with its `@filter`), and its
`@filter` may compare a related column with a base-row field
(`{ "statusId": { "eq": { "field": "statusId" } } }`); the null-safe `isDistinctFrom` /
`isNotDistinctFrom` take only such an operand. Every port's loader validates them
(`ERR_INVALID_ORIGIN` for a `@segment` the entity does not declare, `ERR_BAD_ATTR_FILTER` for
an unknown base field or another op).

**Projection row-scope `@filter` (#207).** Distinct from the *per-aggregate* `@filter` above,
an **object-level `@filter` on an `object.projection`** scopes the whole view's rows — it
lowers to the view's outer `WHERE`. This is the metadata-managed way to express a
Expand Down
Loading
Loading