docs(agent-context): activate field.uri/field.inet/@stringFormat guidance + audit checks (ADR-0036 Wave 3)

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

@@ -114,21 +114,27 @@ such, surfaced in the roadmap, but **non-failing** (the code works; the form is
   birthday-with-time, a recurring local schedule) → recommend **`@localTime: true`** (naive
   `timestamp without time zone`), or confirm it is genuinely meant to be an instant. Default
   `field.timestamp` is an instant; only flag when the field's meaning is clearly wall-clock.
+- A `validator.regex` (or a plain `field.string`) validating an **email** shape → recommend
+  **`@stringFormat: email`** on the `field.string` (ADR-0036 Wave 3). The native type stays
+  `string`; the per-port codegen emits the idiomatic email check — don't hand-roll the regex.
+- A `field.string` that **holds a URL / URI** → recommend **`field.uri`** (native `URI`/`Uri`,
+  URL validation) — a distinct native type + behavior is a subtype, not a validated string.
+- A `field.string` that **holds an IP address** → recommend **`field.inet`** (native IP type;
+  Postgres `inet` column).
 
 **Custom-provider vocabulary (adopters who register their own types/attrs):** check
 new/custom vocab against the ADR-0037 procedure (advisory) — e.g. *a custom subtype
 that differs from an existing one only by a property should be an attribute, not a
-subtype*; a string-shape validation (email/url) is an attribute (native type unchanged),
-not a subtype. Recommend re-shaping against the ordered test.
-
-**TODO — Wave-3 checks to add when the conventions merge (NOT yet active — these
-tokens are pending ADR-0036 Wave 3 and not yet registered; do NOT flag adopters for
-them until merged):**
-
-- An author-supplied regex validating email / url shape → flag for the forthcoming
-  `@format` string-format attribute — *pending Wave 3, not yet active*.
-- A same-pair relationship needing a stable navigation name → flag for the forthcoming
-  `@relationName` attribute — *pending Wave 3, not yet active*.
+subtype*; an email/hostname string-validation is an **attribute** (`@stringFormat`,
+native type unchanged), while a URL or IP is a **native type** (`field.uri` /
+`field.inet`, a subtype). Recommend re-shaping against the ordered test.
+
+**TODO — Wave 4 (reverse-navigation derivation), pending — not yet active.** When
+codegen derives the reverse accessor for a relationship, an adopter who hand-maintains
+a same-pair / back-reference navigation name becomes a modernization candidate. The
+reverse accessor is **derived automatically**; the override is the *optional* attribute
+**`@reverseName`** (NOT required, and NOT the old @relationName). This token is not yet
+registered — do NOT flag adopters for it until Wave 4 merges.
 
 ---
 

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

@@ -233,6 +233,9 @@ Canonical form for common field needs — reach for these before inventing anyth
 | Long / unbounded text | bare `field.string` | add `@maxLength` only when you want `varchar(N)` |
 | Nested structured value | `field.object` | `@objectRef` + `@storage` |
 | Open JSON bag (no fixed shape) | `field.string` + `@dbColumnType: jsonb` | logical type stays string; column is jsonb |
+| URL / URI | `field.uri` | native `URI`/`Uri`; `text` column; URL validation — a real native type + behavior, so a subtype (not a validated string) |
+| IP address | `field.inet` | native IP type; Postgres `inet` column |
+| Validated plain string (email / hostname) | `field.string` + `@stringFormat` | `@stringFormat: email` or `@stringFormat: hostname` — idiomatic per-port validation; don't hand-write the `validator.regex` |
 
 **Timestamps — instant by default, `@localTime` for naive wall-clock (ADR-0036 Wave 2).**
 `field.timestamp` is **instant / timezone-aware by default** (Postgres `timestamptz`;
@@ -247,7 +250,22 @@ lives in `field.timestamp` (instant by default) + the `@localTime` naive opt-out
 { "field.timestamp": { "name": "opensAt", "@localTime": true } }
 ```
 
-<!-- TODO(ADR-0036 Wave 3): add @format (string-shape email/url) / @relationName guidance when merged -->
+**String-shaped natives & validated strings (ADR-0036 Wave 3).** A URL/URI is its own
+native type with URL behavior → **`field.uri`** (subtype, step 2a), not a validated
+string. An IP address likewise → **`field.inet`**. An email or hostname is a *plain
+string that just needs validating* (native type stays `string`) → **`field.string` +
+`@stringFormat: email`/`hostname`** (validation attribute, step 2c) — let the per-port
+codegen emit the idiomatic check; don't hand-write a `validator.regex` for it.
+
+```json
+{ "field.uri":    { "name": "homepage" } }
+{ "field.inet":   { "name": "lastLoginIp" } }
+{ "field.string": { "name": "email", "@stringFormat": "email", "@required": true } }
+```
+
+<!-- TODO(ADR-0036 Wave 4 — reverse-navigation derivation): codegen derives the reverse
+     accessor automatically; @reverseName is the OPTIONAL override of that derived name
+     (not required, NOT @relationName). Add guidance when Wave 4 merges. -->
 
 **Extending the metamodel (custom providers):** the same ordered procedure above
 governs new vocabulary you register — apply it mechanically before registering

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

@@ -114,21 +114,27 @@ such, surfaced in the roadmap, but **non-failing** (the code works; the form is
   birthday-with-time, a recurring local schedule) → recommend **`@localTime: true`** (naive
   `timestamp without time zone`), or confirm it is genuinely meant to be an instant. Default
   `field.timestamp` is an instant; only flag when the field's meaning is clearly wall-clock.
+- A `validator.regex` (or a plain `field.string`) validating an **email** shape → recommend
+  **`@stringFormat: email`** on the `field.string` (ADR-0036 Wave 3). The native type stays
+  `string`; the per-port codegen emits the idiomatic email check — don't hand-roll the regex.
+- A `field.string` that **holds a URL / URI** → recommend **`field.uri`** (native `URI`/`Uri`,
+  URL validation) — a distinct native type + behavior is a subtype, not a validated string.
+- A `field.string` that **holds an IP address** → recommend **`field.inet`** (native IP type;
+  Postgres `inet` column).
 
 **Custom-provider vocabulary (adopters who register their own types/attrs):** check
 new/custom vocab against the ADR-0037 procedure (advisory) — e.g. *a custom subtype
 that differs from an existing one only by a property should be an attribute, not a
-subtype*; a string-shape validation (email/url) is an attribute (native type unchanged),
-not a subtype. Recommend re-shaping against the ordered test.
-
-**TODO — Wave-3 checks to add when the conventions merge (NOT yet active — these
-tokens are pending ADR-0036 Wave 3 and not yet registered; do NOT flag adopters for
-them until merged):**
-
-- An author-supplied regex validating email / url shape → flag for the forthcoming
-  `@format` string-format attribute — *pending Wave 3, not yet active*.
-- A same-pair relationship needing a stable navigation name → flag for the forthcoming
-  `@relationName` attribute — *pending Wave 3, not yet active*.
+subtype*; an email/hostname string-validation is an **attribute** (`@stringFormat`,
+native type unchanged), while a URL or IP is a **native type** (`field.uri` /
+`field.inet`, a subtype). Recommend re-shaping against the ordered test.
+
+**TODO — Wave 4 (reverse-navigation derivation), pending — not yet active.** When
+codegen derives the reverse accessor for a relationship, an adopter who hand-maintains
+a same-pair / back-reference navigation name becomes a modernization candidate. The
+reverse accessor is **derived automatically**; the override is the *optional* attribute
+**`@reverseName`** (NOT required, and NOT the old @relationName). This token is not yet
+registered — do NOT flag adopters for it until Wave 4 merges.
 
 ---
 

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

@@ -233,6 +233,9 @@ Canonical form for common field needs — reach for these before inventing anyth
 | Long / unbounded text | bare `field.string` | add `@maxLength` only when you want `varchar(N)` |
 | Nested structured value | `field.object` | `@objectRef` + `@storage` |
 | Open JSON bag (no fixed shape) | `field.string` + `@dbColumnType: jsonb` | logical type stays string; column is jsonb |
+| URL / URI | `field.uri` | native `URI`/`Uri`; `text` column; URL validation — a real native type + behavior, so a subtype (not a validated string) |
+| IP address | `field.inet` | native IP type; Postgres `inet` column |
+| Validated plain string (email / hostname) | `field.string` + `@stringFormat` | `@stringFormat: email` or `@stringFormat: hostname` — idiomatic per-port validation; don't hand-write the `validator.regex` |
 
 **Timestamps — instant by default, `@localTime` for naive wall-clock (ADR-0036 Wave 2).**
 `field.timestamp` is **instant / timezone-aware by default** (Postgres `timestamptz`;
@@ -247,7 +250,22 @@ lives in `field.timestamp` (instant by default) + the `@localTime` naive opt-out
 { "field.timestamp": { "name": "opensAt", "@localTime": true } }
 ```
 
-<!-- TODO(ADR-0036 Wave 3): add @format (string-shape email/url) / @relationName guidance when merged -->
+**String-shaped natives & validated strings (ADR-0036 Wave 3).** A URL/URI is its own
+native type with URL behavior → **`field.uri`** (subtype, step 2a), not a validated
+string. An IP address likewise → **`field.inet`**. An email or hostname is a *plain
+string that just needs validating* (native type stays `string`) → **`field.string` +
+`@stringFormat: email`/`hostname`** (validation attribute, step 2c) — let the per-port
+codegen emit the idiomatic check; don't hand-write a `validator.regex` for it.
+
+```json
+{ "field.uri":    { "name": "homepage" } }
+{ "field.inet":   { "name": "lastLoginIp" } }
+{ "field.string": { "name": "email", "@stringFormat": "email", "@required": true } }
+```
+
+<!-- TODO(ADR-0036 Wave 4 — reverse-navigation derivation): codegen derives the reverse
+     accessor automatically; @reverseName is the OPTIONAL override of that derived name
+     (not required, NOT @relationName). Add guidance when Wave 4 merges. -->
 
 **Extending the metamodel (custom providers):** the same ordered procedure above
 governs new vocabulary you register — apply it mechanically before registering

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

@@ -114,21 +114,27 @@ such, surfaced in the roadmap, but **non-failing** (the code works; the form is
   birthday-with-time, a recurring local schedule) → recommend **`@localTime: true`** (naive
   `timestamp without time zone`), or confirm it is genuinely meant to be an instant. Default
   `field.timestamp` is an instant; only flag when the field's meaning is clearly wall-clock.
+- A `validator.regex` (or a plain `field.string`) validating an **email** shape → recommend
+  **`@stringFormat: email`** on the `field.string` (ADR-0036 Wave 3). The native type stays
+  `string`; the per-port codegen emits the idiomatic email check — don't hand-roll the regex.
+- A `field.string` that **holds a URL / URI** → recommend **`field.uri`** (native `URI`/`Uri`,
+  URL validation) — a distinct native type + behavior is a subtype, not a validated string.
+- A `field.string` that **holds an IP address** → recommend **`field.inet`** (native IP type;
+  Postgres `inet` column).
 
 **Custom-provider vocabulary (adopters who register their own types/attrs):** check
 new/custom vocab against the ADR-0037 procedure (advisory) — e.g. *a custom subtype
 that differs from an existing one only by a property should be an attribute, not a
-subtype*; a string-shape validation (email/url) is an attribute (native type unchanged),
-not a subtype. Recommend re-shaping against the ordered test.
-
-**TODO — Wave-3 checks to add when the conventions merge (NOT yet active — these
-tokens are pending ADR-0036 Wave 3 and not yet registered; do NOT flag adopters for
-them until merged):**
-
-- An author-supplied regex validating email / url shape → flag for the forthcoming
-  `@format` string-format attribute — *pending Wave 3, not yet active*.
-- A same-pair relationship needing a stable navigation name → flag for the forthcoming
-  `@relationName` attribute — *pending Wave 3, not yet active*.
+subtype*; an email/hostname string-validation is an **attribute** (`@stringFormat`,
+native type unchanged), while a URL or IP is a **native type** (`field.uri` /
+`field.inet`, a subtype). Recommend re-shaping against the ordered test.
+
+**TODO — Wave 4 (reverse-navigation derivation), pending — not yet active.** When
+codegen derives the reverse accessor for a relationship, an adopter who hand-maintains
+a same-pair / back-reference navigation name becomes a modernization candidate. The
+reverse accessor is **derived automatically**; the override is the *optional* attribute
+**`@reverseName`** (NOT required, and NOT the old @relationName). This token is not yet
+registered — do NOT flag adopters for it until Wave 4 merges.
 
 ---
 

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

@@ -233,6 +233,9 @@ Canonical form for common field needs — reach for these before inventing anyth
 | Long / unbounded text | bare `field.string` | add `@maxLength` only when you want `varchar(N)` |
 | Nested structured value | `field.object` | `@objectRef` + `@storage` |
 | Open JSON bag (no fixed shape) | `field.string` + `@dbColumnType: jsonb` | logical type stays string; column is jsonb |
+| URL / URI | `field.uri` | native `URI`/`Uri`; `text` column; URL validation — a real native type + behavior, so a subtype (not a validated string) |
+| IP address | `field.inet` | native IP type; Postgres `inet` column |
+| Validated plain string (email / hostname) | `field.string` + `@stringFormat` | `@stringFormat: email` or `@stringFormat: hostname` — idiomatic per-port validation; don't hand-write the `validator.regex` |
 
 **Timestamps — instant by default, `@localTime` for naive wall-clock (ADR-0036 Wave 2).**
 `field.timestamp` is **instant / timezone-aware by default** (Postgres `timestamptz`;
@@ -247,7 +250,22 @@ lives in `field.timestamp` (instant by default) + the `@localTime` naive opt-out
 { "field.timestamp": { "name": "opensAt", "@localTime": true } }
 ```
 
-<!-- TODO(ADR-0036 Wave 3): add @format (string-shape email/url) / @relationName guidance when merged -->
+**String-shaped natives & validated strings (ADR-0036 Wave 3).** A URL/URI is its own
+native type with URL behavior → **`field.uri`** (subtype, step 2a), not a validated
+string. An IP address likewise → **`field.inet`**. An email or hostname is a *plain
+string that just needs validating* (native type stays `string`) → **`field.string` +
+`@stringFormat: email`/`hostname`** (validation attribute, step 2c) — let the per-port
+codegen emit the idiomatic check; don't hand-write a `validator.regex` for it.
+
+```json
+{ "field.uri":    { "name": "homepage" } }
+{ "field.inet":   { "name": "lastLoginIp" } }
+{ "field.string": { "name": "email", "@stringFormat": "email", "@required": true } }
+```
+
+<!-- TODO(ADR-0036 Wave 4 — reverse-navigation derivation): codegen derives the reverse
+     accessor automatically; @reverseName is the OPTIONAL override of that derived name
+     (not required, NOT @relationName). Add guidance when Wave 4 merges. -->
 
 **Extending the metamodel (custom providers):** the same ordered procedure above
 governs new vocabulary you register — apply it mechanically before registering

fixtures/agent-context-conformance/python/expected/.claude/skills/metaobjects-audit/SKILL.md

@@ -114,21 +114,27 @@ such, surfaced in the roadmap, but **non-failing** (the code works; the form is
   birthday-with-time, a recurring local schedule) → recommend **`@localTime: true`** (naive
   `timestamp without time zone`), or confirm it is genuinely meant to be an instant. Default
   `field.timestamp` is an instant; only flag when the field's meaning is clearly wall-clock.
+- A `validator.regex` (or a plain `field.string`) validating an **email** shape → recommend
+  **`@stringFormat: email`** on the `field.string` (ADR-0036 Wave 3). The native type stays
+  `string`; the per-port codegen emits the idiomatic email check — don't hand-roll the regex.
+- A `field.string` that **holds a URL / URI** → recommend **`field.uri`** (native `URI`/`Uri`,
+  URL validation) — a distinct native type + behavior is a subtype, not a validated string.
+- A `field.string` that **holds an IP address** → recommend **`field.inet`** (native IP type;
+  Postgres `inet` column).
 
 **Custom-provider vocabulary (adopters who register their own types/attrs):** check
 new/custom vocab against the ADR-0037 procedure (advisory) — e.g. *a custom subtype
 that differs from an existing one only by a property should be an attribute, not a
-subtype*; a string-shape validation (email/url) is an attribute (native type unchanged),
-not a subtype. Recommend re-shaping against the ordered test.
-
-**TODO — Wave-3 checks to add when the conventions merge (NOT yet active — these
-tokens are pending ADR-0036 Wave 3 and not yet registered; do NOT flag adopters for
-them until merged):**
-
-- An author-supplied regex validating email / url shape → flag for the forthcoming
-  `@format` string-format attribute — *pending Wave 3, not yet active*.
-- A same-pair relationship needing a stable navigation name → flag for the forthcoming
-  `@relationName` attribute — *pending Wave 3, not yet active*.
+subtype*; an email/hostname string-validation is an **attribute** (`@stringFormat`,
+native type unchanged), while a URL or IP is a **native type** (`field.uri` /
+`field.inet`, a subtype). Recommend re-shaping against the ordered test.
+
+**TODO — Wave 4 (reverse-navigation derivation), pending — not yet active.** When
+codegen derives the reverse accessor for a relationship, an adopter who hand-maintains
+a same-pair / back-reference navigation name becomes a modernization candidate. The
+reverse accessor is **derived automatically**; the override is the *optional* attribute
+**`@reverseName`** (NOT required, and NOT the old @relationName). This token is not yet
+registered — do NOT flag adopters for it until Wave 4 merges.
 
 ---
 

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

@@ -233,6 +233,9 @@ Canonical form for common field needs — reach for these before inventing anyth
 | Long / unbounded text | bare `field.string` | add `@maxLength` only when you want `varchar(N)` |
 | Nested structured value | `field.object` | `@objectRef` + `@storage` |
 | Open JSON bag (no fixed shape) | `field.string` + `@dbColumnType: jsonb` | logical type stays string; column is jsonb |
+| URL / URI | `field.uri` | native `URI`/`Uri`; `text` column; URL validation — a real native type + behavior, so a subtype (not a validated string) |
+| IP address | `field.inet` | native IP type; Postgres `inet` column |
+| Validated plain string (email / hostname) | `field.string` + `@stringFormat` | `@stringFormat: email` or `@stringFormat: hostname` — idiomatic per-port validation; don't hand-write the `validator.regex` |
 
 **Timestamps — instant by default, `@localTime` for naive wall-clock (ADR-0036 Wave 2).**
 `field.timestamp` is **instant / timezone-aware by default** (Postgres `timestamptz`;
@@ -247,7 +250,22 @@ lives in `field.timestamp` (instant by default) + the `@localTime` naive opt-out
 { "field.timestamp": { "name": "opensAt", "@localTime": true } }
 ```
 
-<!-- TODO(ADR-0036 Wave 3): add @format (string-shape email/url) / @relationName guidance when merged -->
+**String-shaped natives & validated strings (ADR-0036 Wave 3).** A URL/URI is its own
+native type with URL behavior → **`field.uri`** (subtype, step 2a), not a validated
+string. An IP address likewise → **`field.inet`**. An email or hostname is a *plain
+string that just needs validating* (native type stays `string`) → **`field.string` +
+`@stringFormat: email`/`hostname`** (validation attribute, step 2c) — let the per-port
+codegen emit the idiomatic check; don't hand-write a `validator.regex` for it.
+
+```json
+{ "field.uri":    { "name": "homepage" } }
+{ "field.inet":   { "name": "lastLoginIp" } }
+{ "field.string": { "name": "email", "@stringFormat": "email", "@required": true } }
+```
+
+<!-- TODO(ADR-0036 Wave 4 — reverse-navigation derivation): codegen derives the reverse
+     accessor automatically; @reverseName is the OPTIONAL override of that derived name
+     (not required, NOT @relationName). Add guidance when Wave 4 merges. -->
 
 **Extending the metamodel (custom providers):** the same ordered procedure above
 governs new vocabulary you register — apply it mechanically before registering