Merge remote-tracking branch 'origin/main' into claude/project-thread-g5rn8k

Author: claude

.changeset/30259-action-param-widget.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': minor
+'@objectstack/platform-objects': minor
+---
+
+feat(spec): an action param can name the widget that draws it (`widget`, same key as on a field), so a param can ask for the permission-set picker (ADR-0131 D4)
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+
+- **`@objectstack/spec`: `ActionParamSchema.widget`**, an optional string with the same key, vocabulary and meaning as `FieldSchema.widget`. It names a registered field component, looked up as `field:` plus the name, to draw the param in the action dialog instead of the `type` default. `type` stays the value's type. The case it exists for is `widget: 'permission-ref'` on a `text` param: it lists the permission sets of the security catalog and submits the chosen machine name, the picker the grant column `sys_user_permission_set.permission_set` already uses. Like the field key it is an open string: an unregistered name is kept, and the dialog draws the `type` renderer instead. A non-string is refused. A param that does not declare the key parses exactly as before. Until now a param naming `widget` was refused as an unknown key.
+- **Not read yet.** The console's param resolver does not carry the key to the dialog's widget until objectstack#30260 lands. Until then a param that declares it is drawn by its `type` renderer, and its value is submitted as before. The key's description says so, and the liveness ledger grades it `planned` with an author warning: `os validate` and `os lint` warn an author who writes it.
+- **`@objectstack/platform-objects`: the action form's Params repeater offers the key** as a `Widget` column, labelled in en, zh-CN, ja-JP and es-ES.

.changeset/30303-fls-key-extension-fields.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/lint': patch
+---
+
+fix(lint): a permission set's field key on a field that an `objectExtensions` entry adds, a sibling package's in the same artifact included, is no longer refused as `security-fls-unknown-field` (#30303)
+
+Clause-②: yes (widening: the FLS-key check accepts extension-added fields)
+Metadata-protocol: none
+
+- **Before.** The FLS-key check resolved `object.field` against the object's declared `fields` only. On a multi-package artifact, an app package's permission set naming `crm_contract.o2c_probe_note`, a field its module package adds to `crm_contract` through `objectExtensions`, failed `os build`, `os validate` and `os lint` with "crm_contract declares no field o2c_probe_note", although the runtime serves the field and the key masks it. A single-package stack's own extension fields were refused the same way.
+- **Now.** The key resolves against the object as the registry serves it: its declared fields plus every field an `objectExtensions` entry of any body of the artifact adds to it, folded as `@objectstack/objectql` folds them (fields by name; one entry per package per object, a later entry replacing an earlier one; `extend` naming the object verbatim). A field that no body declares or adds keeps the same refusal, with the same rule id, severity and message, and so does a field an entry only patches through `fieldPatches`, which adds no field. The hint's nearest name reads the served fields too.
+- **One fold.** The controlled-by-parent merge (#23210), the membership-key column check and the FLS-key check now read extensions through one shared fold in `object-graph.ts`.

.changeset/30320-ipv6-cidr-allowed-ranges.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/plugin-auth': patch
+---
+
+fix(plugin-auth): an IPv6 CIDR in the allowed IP ranges admits the IPv6 clients inside it, at the sign-in gate and at the settings save check
+
+Clause-②: no
+Metadata-protocol: none
+
+`auth.allowed_ip_ranges` (ADR-0069 D5) promises CIDR ranges, but its matcher read only IPv4 CIDR and exact addresses: an IPv6 entry such as `2001:db8::/32` was compared as text, so it never matched a real client. The sign-in gate then refused every IPv6 client the list named, and the settings save check refused the save for an administrator connected over IPv6 from inside it. `ipMatchesRange` now reads an IPv6 CIDR as the first `n` of 128 bits, and both doors use it, so they keep judging the same address the same way.
+
+- An exact IPv6 entry matches the address it denotes however it is spelled (`2001:DB8:0:0::1` matches `2001:db8::1`).
+- An IPv4-mapped address, dotted (`::ffff:203.0.113.5`) or hex (`::ffff:cb00:7105`), is still judged as the IPv4 address it maps. A zone identifier on an address (`fe80::1%eth0`) is dropped before matching.
+- Families never cross: an IPv4 range never admits a pure IPv6 address, and an IPv6 range never admits an IPv4 one.
+- An IPv6 prefix must be a whole number from 0 to 128. An entry with any other prefix matches only its base address, as it did before. IPv4 entries are read exactly as before.

content/docs/references/ui/action.mdx

@@ -141,6 +141,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities
 | **objectOverride** | `string` | optional | Snake case identifier (lowercase with underscores only) |
 | **label** | `string \| Record<string, string>` | optional | Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time |
 | **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| …>` | optional |  |
+| **widget** | `string` | optional | Widget override for this param — names a registered field component (resolved as `field:<widget>`) to draw it instead of the `type` default; same key and vocabulary as FieldSchema.widget, and `type` stays the value's type. e.g. "permission-ref" on a text param picks a permission set by name (ADR-0131 D4). Degrades to the `type` renderer when unregistered. Not read yet: until the console's action dialog passes it through, the dialog draws every param with its `type` renderer whatever this names. |
 | **required** | `boolean` | optional (default: `false`) |  |
 | **options** | `{ label: string \| Record<string, string>; value: string; visibleWhen?: string \| object }[]` | optional |  |
 | **placeholder** | `string` | optional |  |
@@ -234,6 +235,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities
 | **objectOverride** | `string` | optional | Snake case identifier (lowercase with underscores only) |
 | **label** | `string \| Record<string, string>` | optional | Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time |
 | **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| … +35 more>` | optional |  |
+| **widget** | `string` | optional | Widget override for this param — names a registered field component (resolved as `field:<widget>`) to draw it instead of the `type` default; same key and vocabulary as FieldSchema.widget, and `type` stays the value's type. e.g. "permission-ref" on a text param picks a permission set by name (ADR-0131 D4). Degrades to the `type` renderer when unregistered. Not read yet: until the console's action dialog passes it through, the dialog draws every param with its `type` renderer whatever this names. |
 | **required** | `boolean` | optional (default: `false`) |  |
 | **options** | `{ label: string \| Record<string, string>; value: string; visibleWhen?: string \| object }[]` | optional |  |
 | **placeholder** | `string` | optional |  |
@@ -370,6 +372,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities
 | **objectOverride** | `string` | optional | Snake case identifier (lowercase with underscores only) |
 | **label** | `string \| Record<string, string>` | optional | Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time |
 | **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| …>` | optional |  |
+| **widget** | `string` | optional | Widget override for this param — names a registered field component (resolved as `field:<widget>`) to draw it instead of the `type` default; same key and vocabulary as FieldSchema.widget, and `type` stays the value's type. e.g. "permission-ref" on a text param picks a permission set by name (ADR-0131 D4). Degrades to the `type` renderer when unregistered. Not read yet: until the console's action dialog passes it through, the dialog draws every param with its `type` renderer whatever this names. |
 | **required** | `boolean` | optional (default: `false`) |  |
 | **options** | `{ label: string \| Record<string, string>; value: string; visibleWhen?: string \| object }[]` | optional |  |
 | **placeholder** | `string` | optional |  |

packages/lint/src/lint-liveness-properties.test.ts

@@ -187,6 +187,34 @@ describe('lintLivenessProperties', () => {
     }).filter((f) => f.message.includes('objectName'))).toEqual([]);
   });
 
+  // #30259 — `action.params[].widget` is declared before the console's dialog
+  // reads it (#30260 adds the pass-through), so the drilled row is `planned` +
+  // `authorWarn`. Pinned through the SHIPPED ledger and an array of params, so
+  // the drill (`params.widget`) and the array fan-out both have to hold.
+  it('warns on an action param that names a widget — planned, nothing reads it yet', () => {
+    const findings = lintLivenessProperties({
+      actions: [{
+        name: 'create_user',
+        params: [
+          { name: 'email', type: 'email', required: true },
+          { name: 'permissionSet', type: 'text', widget: 'permission-ref' },
+        ],
+      }],
+    });
+    const warned = findings.filter((f) => f.message.includes('sets `params.widget`'));
+    expect(warned).toHaveLength(1);
+    expect(warned[0].rule).toBe('liveness-planned-property');
+    expect(warned[0].hint).toContain('nothing reads it yet');
+    // The live siblings the drill graded stay silent.
+    for (const key of ['name', 'type', 'required', 'options', 'helpText', 'carryOver']) {
+      expect(ruleOf(findings, `params.${key}`), key).toBeUndefined();
+    }
+    // And an action whose params name no widget draws nothing about it.
+    expect(lintLivenessProperties({
+      actions: [{ name: 'a2', params: [{ name: 'note', type: 'text' }] }],
+    }).filter((f) => f.message.includes('widget'))).toEqual([]);
+  });
+
   it('warns on an experimental prop with no authorWarn of its own (tool.outputSchema)', () => {
     // `experimental` warns implicitly — shouldWarn() treats a declared-but-
     // unenforced guarantee like an opted-in dead prop. Repointed from

packages/lint/src/object-graph.test.ts

@@ -15,6 +15,8 @@ import {
   nearestName,
   listNames,
   packagesOf,
+  objectExtensionsByTarget,
+  objectsAsServed,
   RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
 import { walkFilterFieldKeys, type FilterFieldKey } from './filter-walk.js';
@@ -345,6 +347,93 @@ describe('object-graph — packagesOf (#20206, ruling A on #15293 `5634034754`)'
   });
 });
 
+/**
+ * [#30303] The shared extension fold on junk input, beside the
+ * `indexObjectGraph` and `packagesOf` cases above. Neither export refuses
+ * anything: a malformed `packages` is {@link packagesOf}'s refusal, met by a
+ * caller that reads the bodies through it (`validateSecurityPosture` does,
+ * before either fold runs). Each shape below reads as "nothing to fold" for
+ * the part that is junk, and never throws.
+ */
+describe('[#30303] object-graph — objectExtensionsByTarget / objectsAsServed on junk input', () => {
+  const OBJ = { name: 'crm_contract', fields: { contract_no: { type: 'text' } } };
+  const EXT = { extend: 'crm_contract', fields: { note: { type: 'text' } } };
+  const served = (stack: unknown) =>
+    objectsAsServed(stack).objects.map((o) => [o.name, (o.fields as Array<{ name: string }> | Record<string, unknown>)]);
+
+  it('a null or non-record stack: no extensions, no objects', () => {
+    for (const stack of [null, undefined, 'junk', 42, []]) {
+      expect(objectExtensionsByTarget(stack).size, String(stack)).toBe(0);
+      expect(objectsAsServed(stack), String(stack)).toEqual({ objects: [], tied: new Map() });
+    }
+  });
+
+  it('packages: [null] and other non-record entries or bodies contribute nothing; a record body beside them still does', () => {
+    expect(objectExtensionsByTarget({ packages: [null] }).size).toBe(0);
+    const stack = {
+      objects: [OBJ],
+      packages: [null, 'junk', 42, [], { manifest: null }, { manifest: 'junk' }, { manifest: { objectExtensions: [EXT] } }],
+    };
+    expect([...objectExtensionsByTarget(stack).entries()].map(([t, list]) => [t, list.map((e) => [e.carrier, e.path])])).toEqual([
+      ['crm_contract', [[6, 'packages[6].manifest.objectExtensions[0]']]],
+    ]);
+    expect(objectsAsServed(stack).objects[0].fields).toEqual([
+      { name: 'contract_no', type: 'text' },
+      { name: 'note', type: 'text' },
+    ]);
+  });
+
+  it('a non-array objectExtensions folds nothing', () => {
+    for (const objectExtensions of [null, 'junk', 42, { crm_contract: EXT }]) {
+      const stack = { objects: [OBJ], objectExtensions };
+      expect(objectExtensionsByTarget(stack).size, JSON.stringify(objectExtensions)).toBe(0);
+      expect(objectsAsServed(stack).objects, JSON.stringify(objectExtensions)).toEqual([OBJ]);
+    }
+  });
+
+  it('a non-record entry, or one whose extend is not a string, is skipped; the record entry beside it is read', () => {
+    const stack = {
+      objects: [OBJ],
+      objectExtensions: [null, 'junk', 42, [], { extend: 7, fields: { x: { type: 'text' } } }, { fields: { y: {} } }, EXT],
+    };
+    expect([...objectExtensionsByTarget(stack).keys()]).toEqual(['crm_contract']);
+    expect(objectExtensionsByTarget(stack).get('crm_contract')!.map((e) => e.path)).toEqual(['objectExtensions[6]']);
+    expect(served(stack)).toEqual([['crm_contract', [{ name: 'contract_no', type: 'text' }, { name: 'note', type: 'text' }]]]);
+  });
+
+  it('junk fields add nothing: a non-collection, non-record members, a member with no name', () => {
+    for (const fields of [null, 'junk', 42, [null, 'x', 3, { type: 'text' }, { name: '', type: 'text' }]]) {
+      const stack = { objects: [OBJ], objectExtensions: [{ extend: 'crm_contract', fields }] };
+      expect(() => objectsAsServed(stack), JSON.stringify(fields)).not.toThrow();
+      expect(objectsAsServed(stack).objects[0].fields, JSON.stringify(fields)).toEqual([{ name: 'contract_no', type: 'text' }]);
+    }
+    // The array form is read by name, as the map form is.
+    const arrayForm = { objects: [OBJ], objectExtensions: [{ extend: 'crm_contract', fields: [{ name: 'note', type: 'text' }] }] };
+    expect(served(arrayForm)).toEqual([['crm_contract', [{ name: 'contract_no', type: 'text' }, { name: 'note', type: 'text' }]]]);
+  });
+
+  // `ObjectExtensionSchema.priority` is a number, so a parsed stack never
+  // carries this shape; the fold reads a non-number as absent (the default 200,
+  // as `SchemaRegistry.registerObjectExtension` does) rather than guessing.
+  it('a string priority reads as the default 200 and never throws', () => {
+    const stack = {
+      objects: [OBJ],
+      packages: [
+        { manifest: { objectExtensions: [{ extend: 'crm_contract', priority: '100', fields: { note: { type: 'text', label: 'A' } } }] } },
+        { manifest: { objectExtensions: [{ extend: 'crm_contract', priority: 150, fields: { note: { type: 'text', label: 'B' } } }] } },
+      ],
+    };
+    expect(objectExtensionsByTarget(stack).get('crm_contract')!.map((e) => [e.carrier, e.priority])).toEqual([
+      [1, 150],
+      [0, 200],
+    ]);
+    // So the string-priority entry folds LAST and its definition wins, untied.
+    const { objects, tied } = objectsAsServed(stack);
+    expect((objects[0].fields as Array<Record<string, unknown>>).find((f) => f.name === 'note')?.label).toBe('A');
+    expect(tied.size).toBe(0);
+  });
+});
+
 /**
  * [#19289] A `{ type: 'user' }` field with no `reference` is TRAVERSABLE — the
  * third defect found by the implicit-target census, and the widest-reaching of