feat(apollo-react): shared guardrail definitions layer and useGuardrailDefinitions [AL-574]

[andreizdrali-uipath]

Builds the shared guardrail definitions layer AL-574 asks for, in the apollo-react guardrails family. This is the seam between the /api/execution/guardrails/definitions payload and the GuardrailDefinitions GuardrailBuilder already renders. Flow and Agents each carry their own copy of this today, and the two have drifted.

Base, and what to review

Base main, 8 commits, dev-packages labelled. The first two are #1107 (a96ef79f) and #1138
(9fa10765), each now a single squashed commit; review only the last six:

• feat(apollo-react): shared guardrail definitions layer and useGuardrailDefinitions - the work.
• fix(apollo-react): review fixes for the guardrail definitions layer [AL-574] - a first pass of
  review fixes, listed under Review fixes below.
• fix(apollo-react): stop inventing map-enum bounds the range check now enforces [AL-574] - see
  Synthesized map-enum bounds below.
• feat(apollo-react): guardrail status chip, shared with #1140 and
  fix(apollo-react): render the guardrail status chip as a span, shared with #1140 - moved down
  here from feat(apollo-react): guardrail list section [AL-575] #1140 and feat(apollo-react): add-guardrail palette [AL-576] #1147, see Shared leaves move here below.
• test(apollo-react): share the canvas catalog scans across the family [AL-574] - same section.

Retargeted from feat/apollo-react-guardrails-family to main on 2026-09-11: pr-checks,
dev-publish and preview-deploy are all gated on branches: [main, 'support/**'], so against a
feature base they never ran and the absent checks meant "not run", not "passed".

For most of that time they still did not run, because every branch in this stack conflicted with
main in packages/apollo-wind/src/components/ui/select.tsx and GitHub skips the pull_request
workflows when it cannot build a test merge. That is resolved upstream as of 2026-09-14: this
branch and the three leaves all merge into main with zero conflicts, so checks and the -pr1139
preview pair should publish normally from here.

Rebased 2026-09-14 onto #1138's current head (9fa10765), which had itself moved onto #1107's
current head (a96ef79f). Both were squashed to one commit apiece and carry +556/-92 over 32
files of new content versus the head this PR previously sat on, so the 18 commits that used to be
below this work are gone. Two consequences are visible here: the form now validates number
min/max through zod in onChange mode rather than as DOM attributes, and
getOutOfRangeParameterIds has been widened to map-enum (see Synthesized map-enum bounds).
Merge order is still #1107, then #1138, then this.

Built fresh from #1107/#1138, the rescoped Jira ticket and Confluence §7.3/§7.4.5. Nothing is ported
from the closed #1132.

What lands

Module	Public surface
definitions-wire.ts	GuardrailDefinitionWire, GuardrailParameterDefinitionWire
definitions-parse.ts	parseGuardrailDefinitions
definitions-copy.ts	GUARDRAIL_COPY_EN, GUARDRAIL_COPY_EN_MESSAGES, useGuardrailDefinitionCopy
definitions-enrich.ts	enrichGuardrailDefinitions, isByoGuardrailDefinition, humanizeGuardrailParameterId, withGuardrailFolderMetadata
use-guardrail-definitions.ts	useGuardrailDefinitions

unknown payload → parseGuardrailDefinitions → enrichGuardrailDefinitions → GuardrailBuilder
                       (zod, private)          (canonical copy on lingui)
                                    useGuardrailDefinitions composes all three

Plus a README section, exports from Guardrails/index.ts (no package.json change, ./canvas/guardrails already points there), and the new guardrails.definitions.* ids in the canvas catalog.

Contract highlights

• The parser never throws. A non-array payload sets inputError; a single bad definition is dropped whole and reported in invalid, which is what both products already do entry by entry. Unknown keys stripped. Transport errors and data errors are separate channels: a malformed payload leaves error null.
• zod does not cross the boundary. The schema is private to definitions-parse.ts and pinned to the hand-written mirror by a bidirectional assignability check that sits on the hot path in toWireDefinition (so it cannot be dropped as dead code), plus two tests: a key-set assertion over both shapes, and a source-level guard that reads the folder's files and fails on a zod import outside the parser. grep zod dist/canvas/components/Guardrails/**/*.d.ts is empty.
• Enrichment is pure and exported, so Flow's vsix bridge and non-React callers use it directly. EnrichedGuardrailDefinition extends GuardrailDefinition, so its output feeds the builder unmapped.
• options.definitions skips the request entirely, which is how Agents keeps SWR, Flow studio and workbench keep react-query, and the vsix keeps postMessage.
• hiddenValidators hides nothing by default and never hides a BYO definition. Which validators a product exposes is an entitlement decision, so it stays with the caller.

One deliberate divergence from useDiscoveryModels

The context is compared by content, not identity. Keying the effect off context identity means an inline context object refetches on every render, and since every response sets state the loop never terminates. The hook test caught it at 17,640 calls before the fix. useDiscoveryModels still has this footgun; worth a separate look.

Synthesized map-enum bounds, and why they are gone

Enrichment used to give an unbounded map-enum parameter 0..1 step 0.1: some backends omit the
bounds on the threshold maps, and an unbounded numeric editor for a confidence score is a data-entry
hazard. That default was safe only while nothing enforced it, and the JSDoc said so in as many
words: "Before widening either to map-enum, replace this default with something the backend
states."

#1138 has now widened it. getOutOfRangeParameterIds covers map-enum as of 9fa10765, and hosts
gate Save on it, so a bound this layer invented would block a save over a number the backend never
published. Enrichment now passes the wire's min/max through when they are sent and leaves them
off when they are not. step stays a hint, since neither that check nor buildFieldValidation
reads it and without it a 0..1 score steps by 1.

Nothing on today's wire changes behaviour: PII's entityThresholds arrives unbounded and defaults
to 0.8, harmful content arrives with its own 0..6. What changes is that a future unbounded map
on another scale cannot be Save-gated against a number we made up. The test that pinned the old
"never checked" premise now pins the new one, including that a map on the backend's own bounds
does report.

Shared leaves move here

Two things the leaf PRs were each carrying their own copy of now land once, on the layer they all
branch from. The leaves inherit them and their own diffs shrink by the same amount.

• GuardrailStatusChip (components/guardrail-status-chip.tsx plus its test), cherry-picked
  verbatim from feat(apollo-react): add-guardrail palette [AL-576] #1147 where it was already an isolated commit. It was byte-identical on feat(apollo-react): guardrail list section [AL-575] #1140 and
  feat(apollo-react): add-guardrail palette [AL-576] #1147 and had to be kept that way by hand, one cherry-pick per edit. A <span> composed from
  wind's exported badgeVariants rather than the Badge component, which renders a <div>: the
  palette entry puts these chips inside its <button>, where flow content is invalid. Comes with
  GUARDRAIL_CHIP_GEOMETRY, extracted from guardrail-chip.tsx so the interactive and read-only
  chips stay one system. Nothing in this PR renders it yet; AL-578 and the two leaves do.
• The catalog scans (__fixtures__/catalog-coverage.ts). Every component's i18n.test.ts was
  re-implementing the same three checks over its own id prefix, about 40 lines apiece: English
  parity, orphaned ids, and translation coverage. They are reporting functions rather than
  assertions, so a failure still points at the calling test's own line. The definitions layer is the
  first caller and gains what it was missing: the orphan sweep now covers all thirteen catalogs
  instead of English alone, and there is a coverage check that pins FIPassportNumber by name
  rather than leaving the gap invisible.

Canonical copy moves onto lingui

The display copy for the six built-in validators currently lives twice, in Agents' OOB_GUARDRAILS_I8N and Flow's buildValidatorDisplayInfo. Here it is 63 lingui messages in the shared canvas catalog, so both products get the same wording and the same translations, and the strings enter the real loc pipeline instead of a host-side constant.

Message ids use raw wire values (USSocialSecurityNumber), never a transcribed slug. Transcribing is exactly how the two products ended up keying the same Finland entity as finNationalId and fiNationalId.

Translations harvested from whichever product each string was adopted from: 62 of 63 ids in each of the 12 locales. The gap is FIPassportNumber, which Agents has not had translated; it falls back to English per key. ru is empty, matching both products and this package's existing convention.

src/canvas uses no lingui macros, so lingui extract does not feed this catalog and never did: its entries are hand-authored. A test asserts the catalog matches the source in both directions, which is what extraction would otherwise do for you.

QA-visible copy changes

The two products' English differs in 17 places. Each choice is declared with a reason in definitions-parity.test.ts and asserted against both products' transcribed copy, so the suite fails on an undeclared difference, a stale declaration, or a third wording we invented.

Agents users will see: shorter validator descriptions (the "This validator is designed to..." preamble is gone from four of them); harmfulContentEntities reads "Content categories" and its thresholds "Severity thresholds"; ipEntities reads "Content types"; PII thresholds pluralized; LLM-as-judge threshold reads "Strictness"; SelfHarm reads "Self-harm"; a new LLM-as-judge cost note.

Flow users will see: three new parameter tooltips (PII, prompt-injection and harmful-content thresholds) and the Finland passport entity, which Flow renders as a raw value today.

prompt_injection keeps Agents' wording as the deliberate exception to the concision rule, because the Noma Security attribution is load-bearing.

Review fixes

The second commit, from a pass over this PR against the #1107/#1138 review threads:

• Typed the fetch mocks (vi.fn<typeof fetch>). vi.fn(async () => ...) infers a zero-parameter
  mock, so every mock.calls[i]?.[1] assertion in the hook suite was a TS2493/TS2339 under the
  repo's strict config: 10 errors CI cannot see, since tests are excluded from tsc and biome does
  not typecheck. Same class as the two Copilot catches on feat(apollo-wind): string-list field, tooltip metadata, and forms repairs #1107. Checked with a throwaway tsconfig
  that drops the test/story excludes; this PR's files are clean under it.
• loading starts true when the hook is about to fetch. It started false, so the first
  render of a self-fetching host was { definitions: [], loading: false } and a
  loading ? <Spinner/> : <Empty/> host flashed the empty state.
• refetch is a no-op while the hook is disabled. It used to issue a real request whose result
  was then discarded in favour of options.definitions.
• Docs that were stronger than the code: options.definitions is compared by identity, not
  content (pass a stable reference; an SWR or react-query result already is), a failed request keeps
  the previous results, and the zod boundary is a source-level check plus two tests.
• Named the 0..1 map-enum assumption and pinned it with a test. The third commit then removed
  the assumption outright once feat(apollo-react): guardrails component family under canvas #1138 started enforcing it, per the section above.

Verification

Re-run in full after the 2026-09-14 rebase.

• tsc --noEmit: clean.
• Throwaway tsconfig including tests and stories: clean in this PR's files. 12 remaining errors,
  all pre-existing in feat(apollo-react): guardrails component family under canvas #1138's own suites (guardrail-builder.test.tsx 7,
  form-schema-builder.test.ts 2, plus one each in guardrail-builder.stories.tsx,
  guardrail-form-layout.test.tsx and guardrail-validator-form.test.tsx). CI typechecks neither
  tests nor stories, so they are invisible to it. Nothing here touches those files.
• biome check: clean.
• Guardrails directory: 333 passing, 1 failing.
• Full package suite: 2974 passing, 9 failing.

The 9 failures are 8 + 1, and none of them are this PR's:

• 8 are the known pre-existing localStorage failures in canvas/utils/Storage.test.ts and
  canvas/hooks/useStorageState.test.ts: Node 24 ships an experimental localStorage global that
  is undefined without --localstorage-file and shadows happy-dom's.
• 1 is new and belongs to feat(apollo-react): guardrails component family under canvas #1138: guardrail-validator-form.test.tsx > localization > resolves the resolver validation messages from the catalog, not wind English renders the English
  "Must be at most 1" instead of the Japanese. It is not caused by this branch. Checked by
  swapping feat(apollo-react): guardrails component family under canvas #1138's own src/canvas/locales/* back in underneath this branch, where it fails
  identically, and re-run after a clean apollo-wind build. Worth a look upstream before feat(apollo-react): guardrails component family under canvas #1138
  merges.

Review questions

1. BYO connection and folder resolution (plan Q1). It stays host-side here, via withGuardrailFolderMetadata, because resolving it needs each product's connections API (Agents pages fetchResources, Flow calls getConnectionById). Do you want it inside the hook instead, as a resolveConnections callback?
2. Canonical copy on lingui (plan Q3). Ratifying the move means accepting the 17 divergences above, each of which changes what one product's users see. Happy to split any of them back out if a specific string should stay as it is.

Rebased 2026-09-14 onto #1138's squashed head 9fa10765. The 18 commits that used to sit
below this work are gone, so every commit above has a new sha, and the select.tsx conflict with
main that kept this stack CONFLICTING is resolved upstream: all four PRs in the stack now
merge cleanly, and pull_request workflows should fire for the first time. The content of the
first two commits is unchanged apart from the catalog rebase resolution, which keeps both #1138's
new validation strings and this PR's definitions block in all thirteen files.

[github-actions]

Apollo Coded App preview deployments are ready.

Project	Status	Preview	Updated (PT)
apollo-design	Ready	Preview · Logs	Sep 15, 2026, 04:00:16 AM
apollo-docs	Ready	Preview · Logs	Sep 15, 2026, 04:00:16 AM
apollo-landing	Ready	Preview · Logs	Sep 15, 2026, 04:00:16 AM
apollo-vertex	Ready	Preview · Logs	Sep 15, 2026, 04:00:16 AM

[github-actions]

Dependency License Review

• ✅ 1937 package(s) scanned
• ✅ No license issues found
• ⚠️ 2 package(s) excluded (see details below)

License distribution

License	Packages
MIT	1708
ISC	88
Apache-2.0	55
BSD-3-Clause	27
BSD-2-Clause	23
BlueOak-1.0.0	8
MPL-2.0	4
MIT-0	3
CC0-1.0	3
MIT OR Apache-2.0	2
(MIT OR Apache-2.0)	2
Unlicense	2
LGPL-3.0-or-later	1
Python-2.0	1
CC-BY-4.0	1
(MPL-2.0 OR Apache-2.0)	1
Unknown	1
Artistic-2.0	1
(WTFPL OR MIT)	1
(BSD-2-Clause OR MIT OR Apache-2.0)	1
CC-BY-3.0	1
0BSD	1
(MIT OR CC0-1.0)	1
MIT AND ISC	1

Excluded packages

Package	Version	License	Reason
@img/sharp-libvips-linux-x64	1.3.2	LGPL-3.0-or-later	LGPL pre-built binary, not linked
khroma	2.1.0	Unknown	MIT per GitHub repo, missing license field in package.json

[Copilot]

🟡 Changes recommended

There are confirmed behavioral bugs in the new code (unexpected refetch behavior and render-phase state updates) that should be fixed before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds a shared “guardrail definitions” layer under packages/apollo-react/src/canvas/components/Guardrails/ that parses the /api/execution/guardrails/definitions payload, enriches it with canonical (Lingui-backed) display copy, and exposes a useGuardrailDefinitions hook as the seam between host transport and GuardrailBuilder. It also extends apollo-wind’s metadata forms to support tooltips and a new string-list field type used by guardrail parameter editors.

Changes:

• Introduces wire types + zod-based non-throwing parsing, pure enrichment, and a useGuardrailDefinitions hook for fetching/composing guardrail definitions.
• Moves canonical validator copy into the canvas Lingui catalog and adds parity tests against Flow/Agents baselines.
• Enhances apollo-wind forms/UI with InfoTooltip, string-list field support, and aria-invalid styling for select/textarea.

File summaries

File	Description
pnpm-lock.yaml	Locks new deps added for guardrails UI and a11y testing.
packages/apollo-wind/src/index.ts	Re-exports new forms/types (MetadataFormProps, useWatch, StringListField*) and InfoTooltip.
packages/apollo-wind/src/components/ui/textarea.tsx	Adds aria-invalid error styling to textarea.
packages/apollo-wind/src/components/ui/select.tsx	Adds aria-invalid error styling to select trigger.
packages/apollo-wind/src/components/ui/info-tooltip.tsx	Adds reusable info-icon tooltip component for form labels.
packages/apollo-wind/src/components/ui/info-tooltip.test.tsx	Adds a11y + behavior tests for InfoTooltip.
packages/apollo-wind/src/components/ui/index.ts	Exports info-tooltip (and reorders a couple exports).
packages/apollo-wind/src/components/forms/validation-converter.ts	Extends schema conversion to treat string-list as an array type.
packages/apollo-wind/src/components/forms/string-list-field.tsx	Implements the new string-list field editor and formatTemplate helper.
packages/apollo-wind/src/components/forms/metadata-form.stories.tsx	Adds story demonstrating string-list + tooltip + controlled-host seam.
packages/apollo-wind/src/components/forms/index.ts	Exposes new forms APIs (controlled seam types, string-list exports, useWatch).
packages/apollo-wind/src/components/forms/form-schema.ts	Adds tooltip metadata, textarea constraints, multiselect copy overrides, and string-list field metadata/type.
packages/apollo-wind/src/components/forms/field-renderer.tsx	Renders required indicator + optional tooltip, wires htmlFor/id, and passes aria-invalid to select/textarea/multiselect.
packages/apollo-react/src/test/setup.ts	Registers jest-axe matchers for Vitest suites.
packages/apollo-react/src/i18n/index.ts	Exports getPreImportedMessages helper for hosts merging catalogs.
packages/apollo-react/src/canvas/locales/en.json	Adds guardrails chrome strings + canonical validator/parameter/option copy (English).
packages/apollo-react/src/canvas/components/index.ts	Exports the Guardrails canvas family from the canvas components barrel.
packages/apollo-react/src/canvas/components/Guardrails/utils.ts	Adds parameter seeding/sync/validation helpers for guardrail parameters.
packages/apollo-react/src/canvas/components/Guardrails/use-guardrail-definitions.ts	Adds useGuardrailDefinitions hook (fetch + parse + enrich + refetch).
packages/apollo-react/src/canvas/components/Guardrails/types.ts	Defines guardrail parameter and form prop types for the validator editor surface.
packages/apollo-react/src/canvas/components/Guardrails/render-parameter-bridge.tsx	Bridges host renderParameter overrides into MetadataForm custom components via context.
packages/apollo-react/src/canvas/components/Guardrails/index.ts	Public exports for the guardrails family, including the new definitions layer APIs.
packages/apollo-react/src/canvas/components/Guardrails/guardrail-validator-form.tsx	Implements validator parameter form using MetadataForm + guardrail-owned custom fields.
packages/apollo-react/src/canvas/components/Guardrails/guardrail-form-layout.tsx	Adds shared modal/inline layout wrapper for guardrail builder forms.
packages/apollo-react/src/canvas/components/Guardrails/guardrail-form-layout.test.tsx	Adds behavior + a11y tests for the shared form layout.
packages/apollo-react/src/canvas/components/Guardrails/guardrail-form-layout.stories.tsx	Adds Storybook examples for the shared form layout modes.
packages/apollo-react/src/canvas/components/Guardrails/form-schema-builder.ts	Builds MetadataForm schemas for guardrail parameters + coercion helper.
packages/apollo-react/src/canvas/components/Guardrails/form-schema-builder.test.ts	Tests schema mapping/coercion rules for guardrail parameter definitions.
packages/apollo-react/src/canvas/components/Guardrails/definitions-wire.ts	Adds hand-written wire types for the definitions endpoint payload.
packages/apollo-react/src/canvas/components/Guardrails/definitions-parse.ts	Adds zod validation + non-throwing parse result and issue reporting.
packages/apollo-react/src/canvas/components/Guardrails/definitions-parse.test.ts	Tests parsing guarantees + zod boundary constraints.
packages/apollo-react/src/canvas/components/Guardrails/definitions-parity.test.ts	Ensures canonical English matches Flow/Agents baselines and declares divergences.
packages/apollo-react/src/canvas/components/Guardrails/definitions-enrich.ts	Adds pure enrichment (copy resolution + parameter shaping + folder metadata helper).
packages/apollo-react/src/canvas/components/Guardrails/definitions-copy.test.ts	Tests copy table, message id conventions, and catalog parity.
packages/apollo-react/src/canvas/components/Guardrails/components/parameter-label.tsx	Shared parameter label renderer (required marker + info tooltip).
packages/apollo-react/src/canvas/components/Guardrails/components/mixed-scopes-banner.tsx	Adds banner for mixed-scope guardrails with “save as new” hint.
packages/apollo-react/src/canvas/components/Guardrails/components/mixed-scopes-banner.test.tsx	Tests mixed-scopes banner rendering + a11y.
packages/apollo-react/src/canvas/components/Guardrails/components/map-enum-field.tsx	Adds map-enum editor bound to sibling enum-list selection via useWatch.
packages/apollo-react/src/canvas/components/Guardrails/components/guardrail-status-banner.tsx	Adds status banners for disabled/unauthorized/feature-disabled definitions.
packages/apollo-react/src/canvas/components/Guardrails/components/guardrail-status-banner.test.tsx	Tests status banner roles and a11y.
packages/apollo-react/src/canvas/components/Guardrails/components/guardrail-scope-selector.tsx	Adds scope/tool targeting selector using chips and self-healing behavior.
packages/apollo-react/src/canvas/components/Guardrails/components/guardrail-scope-selector.test.tsx	Tests selector behavior, targeting semantics, and a11y.
packages/apollo-react/src/canvas/components/Guardrails/components/guardrail-chip.tsx	Adds chip toggle component (CVA variants) for scopes/options.
packages/apollo-react/src/canvas/components/Guardrails/components/guardrail-chip.test.tsx	Tests chip pressed state, interactions, and a11y.
packages/apollo-react/src/canvas/components/Guardrails/components/guardrail-action-section.tsx	Adds action configuration section (log/block/filter/escalate).
packages/apollo-react/src/canvas/components/Guardrails/components/guardrail-action-section.test.tsx	Tests action section branching + a11y.
packages/apollo-react/src/canvas/components/Guardrails/components/field-shell.tsx	Adds non-input “field shell” container with error border option.
packages/apollo-react/src/canvas/components/Guardrails/components/field-shell.test.tsx	Tests field shell invalid styling toggle.
packages/apollo-react/src/canvas/components/Guardrails/components/enum-list-chips-field.tsx	Adds chip-based enum-list editor for small option sets.
packages/apollo-react/src/canvas/components/Guardrails/builder-utils.ts	Adds builder helpers for defaults and required-field validation.
packages/apollo-react/src/canvas/components/Guardrails/builder-utils.test.ts	Tests builder utils behaviors and edge cases.
packages/apollo-react/src/canvas/components/Guardrails/builder-types.ts	Adds public structural types for persisted guardrail values and builder slots.
packages/apollo-react/src/canvas/components/Guardrails/fixtures/host-copy-baselines.ts	Adds transcribed Flow/Agents English baselines for copy parity tests.
packages/apollo-react/src/canvas/components/Guardrails/fixtures/definitions-wire.fixtures.ts	Adds realistic wire fixtures for parsing/enrichment/copy tests.
packages/apollo-react/package.json	Exposes ./canvas/guardrails subpath and adds deps (class-variance-authority, jest-axe, @types/jest-axe).

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

• Files reviewed: 81/82 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

📊 Coverage + size by package

Per-package coverage and bundle size on this PR. New-line coverage = of the source lines this PR adds or changes, the % hit by tests.

Package	Coverage	New-line coverage	Packed (gzip)	Unpacked	vs main
@uipath/apollo-core	—	—	42.01 MB	50.12 MB	±0
@uipath/apollo-react	45.3%	87.6% (766/874)	7.73 MB	29.86 MB	+174.2 KB
@uipath/apollo-ui-icons	—	—	2.85 MB	6.91 MB	±0
@uipath/apollo-wind	—	—	461.8 KB	2.92 MB	+1.8 KB
@uipath/ap-chat	85.8%	—	43.95 MB	56.84 MB	+26.6 KB

_{"Coverage" is each package's own coverage.include scope (e.g. apollo-core instruments only scripts/). "Packed"/"Unpacked" come from npm pack --dry-run and only cover built packages — "—" means not measured this run (package not affected / not built). "vs main" is the packed (gzipped) delta against the last successful main build (the package-sizes artifact from the Release workflow); "—" there means no main baseline was available this run. The baseline is main's latest build, not this PR's exact merge-base, so it includes any drift since the branch diverged. Packages with no vitest config are omitted.}

[github-actions]

Storybook visual diff

⚠️ Visual changes detected: 9 changed, 26 added (of 664 compared, 629 unchanged). View report

Baseline is the deployed main Storybook, so changes merged to main after this branch was last updated can also appear here. Logs

Updated (PT): Sep 15, 2026, 04:18:40 AM

[github-actions]

📦 Dev Packages

Package	Status	Updated (PT)
@uipath/apollo-react@6.45.2-pr1139.a5e4528	🟢 Published	Sep 15, 2026, 03:59:16 AM

[Copilot]

🟡 Changes recommended

Unresolved review findings include a critical stale-data risk and multiple parser, validation, synchronization, and accessibility defects.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (9)

packages/apollo-react/src/canvas/components/Guardrails/components/map-enum-field.tsx:73

• This custom numeric input is the control that renders map-enum validation errors, but it never receives aria-invalid. When error is present, the visible FormFieldError is not accompanied by the invalid state on the input, so assistive technology can miss which control is affected. Pass the error state through as aria-invalid.

            <Input
              aria-label={`${paramDef.label}: ${sourceDef?.optionLabels?.[key] ?? key}`}
              type="number"
              value={currentMap[key] ?? defaults[key] ?? paramDef.min ?? 0}
              onChange={(e) => handleThresholdChange(key, Number.parseFloat(e.target.value) || 0)}

packages/apollo-react/src/canvas/components/Guardrails/components/map-enum-field.tsx:58

• getRequiredEmptyParameterIds marks a required map-enum with no keys as invalid, and the builder passes that message through error, but this early return removes the whole FormField and its FormFieldError. Clicking Save can therefore block a required empty map-enum with no visible error. Keep a label/error shell when the source has no keys, or suppress validation for this dependent field until its source has a selection.

  if (keys.length === 0) return null;

packages/apollo-react/src/canvas/components/Guardrails/components/parameter-label.tsx:25

• InfoTooltip renders a real <button>, so putting it inside Label nests a labelable control inside a label. Clicking the tooltip can activate the associated input and exposes ambiguous label semantics to assistive technology. Render the tooltip as a sibling of the label, as FormFieldLabel does.

      {paramDef.tooltip && (
        <InfoTooltip content={paramDef.tooltip} aria-label={labels.moreInformation} />
      )}

packages/apollo-react/src/canvas/components/Guardrails/definitions-enrich.ts:145

• copy is a normal object, so an otherwise-unrecognised wire validator such as toString resolves to an inherited Object.prototype member instead of undefined. With any parameter, toParameterDefinition then reads curated.paramLabels[param.id] from that function and enrichment throws, even though the parser accepted the definition. Check that the validator is an own key before using it as curated copy so unknown wire values remain renderable.

  const curated = isByo ? undefined : copy[wire.validator];

packages/apollo-react/src/canvas/components/Guardrails/definitions-parse.ts:170

• The parser's contract says malformed entries never escape as exceptions, but readValidator(entry) is called after the safeParse try/catch. A hostile object or proxy with a throwing validator getter will therefore throw while constructing the parse issue instead of being reported in invalid. Make this helper catch property-access failures (returning undefined) before it is used for an invalid entry.
  packages/apollo-react/src/canvas/components/Guardrails/guardrail-builder.tsx:415
• The host-owned saveDisabled gate is applied to the primary button at line 428, but not to the secondary Save as new action here. When saveDisabled is true (for example while a host slot is resolving), Save as new remains enabled and handleSaveAsNew can still invoke onSaveAsNew, bypassing the documented host save gate. Include hostSaveDisabled in this action's disabled condition.
  packages/apollo-react/src/canvas/components/Guardrails/use-metadata-form-bridge.ts:72
• Object.is only provides reference equality, so a controlled host that echoes an equivalent cloned array or map treats it as changed on every render. The effect then calls setValue repeatedly despite the hook's deep-equality contract, causing unnecessary React Hook Form updates and potentially disturbing focused list/map editors. Compare structured values before calling setValue (or normalize them to stable references).
  packages/apollo-react/src/canvas/components/Guardrails/use-metadata-form-bridge.ts:74
• The controlled-value sync only iterates keys present in values; it never clears a field that the host removes from parameters. After a host drops an optional parameter (for example when normalizing empty values), the old array/map/text value remains in React Hook Form and is still shown, so the UI no longer reflects the controlled source and a later edit can re-submit stale data. Reconcile removed fields to their current defaults/empty state as well as syncing present keys.
  packages/apollo-wind/src/components/forms/validation-converter.ts:59
• Because this condition skips the refinement whenever minLength is configured, a required string with minLength: 3 accepts ' ' after satisfying the length rule. That contradicts the shared isEmptyFieldValue semantics described immediately above and lets whitespace-only required values through; the refinement should be applied regardless of minLength.

• Files reviewed: 93/94 changed files
• Comments generated: 4
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Unresolved moderate findings remain across parsing, hook behavior, form synchronization, accessibility, renderer identity, and validation.

Get a fresh assessment by requesting another Copilot review.

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (9)

packages/apollo-react/src/canvas/components/Guardrails/fixtures/definitions-wire.fixtures.ts:52

• This fixture says enrichment supplies a 0..1 bound, but definitions-enrich.ts intentionally leaves an unbounded map without min/max and only supplies the editor step hint. The stale comment contradicts the save-time validation contract documented by the new tests and can lead hosts to assume an invented range is enforced; describe the value as unbounded with a step hint instead.

      // The backend omits the bounds here; enrichment supplies 0..1 step 0.1.

packages/apollo-react/src/canvas/components/Guardrails/components/escalate-action-fields.tsx:182

• In the built-in static-recipient fallback, this Label is a sibling with no htmlFor, while the fallback Input below has neither an id nor an accessible label. Screen readers therefore cannot associate “Email address”/“Group name” with the required value control (and the searchable fallback has the same gap). Give the built-in inputs stable ids and associate the label, while keeping custom render slots responsible for their own controls.

      {/* Recipient value */}
      <FormField>
        <Label>
          {recipientTypeLabels[displayedRecipientType] ?? labels.recipientFallbackLabel}
          <RequiredIndicator />
        </Label>

packages/apollo-react/src/canvas/components/Guardrails/definitions-parse.ts:95

• The shared seeding contract explicitly handles defaultValue: null for boolean parameters, but this schema rejects such a payload before enrichment. A valid definition with a nullable boolean default is therefore dropped as invalid, so the nullability support is incomplete; accept the nullable form here and update the hand-written wire mirror to match.
  packages/apollo-react/src/canvas/components/Guardrails/definitions-parse.ts:120
• Using .min(1).optional() here rejects the entire definition when the backend sends byoValidatorName: ''; it does not normalize the empty marker to an absent value as the parser documentation claims. That removes an otherwise valid non-BYO validator from definitions instead of preserving it. Use the existing emptyToUndefined schema here and assert that the parsed result still contains the definition.
  packages/apollo-react/src/canvas/components/Guardrails/use-guardrail-definitions.ts:126
• provided === undefined cannot distinguish an omitted override from an explicitly supplied but not-yet-loaded payload. A normal SWR/React Query call such as useGuardrailDefinitions(ctx, { definitions: data }) has data === undefined on its first render, so this hook starts its own request, violating the documented no-fetch override path and potentially issuing duplicate requests. Track whether the definitions key is present and use that presence flag for both enabled and the parsed-result branch.
  packages/apollo-react/src/canvas/components/Guardrails/use-guardrail-definitions.ts:131
• useState(enabled) is evaluated only on the initial mount. If the hook starts disabled and later receives a fetch context, or if a loaded hook switches to a new request context, loading is still false for the render before the effect calls setLoading(true). This violates the documented loading contract and lets hosts flash an empty state or render stale results as settled; derive/reset loading for each new enabled request rather than only initializing it once.
  packages/apollo-react/src/canvas/components/Guardrails/use-metadata-form-bridge.ts:90
• Controlled external updates use setValue without requesting validation, so an earlier resolver error can remain in RHF after the host replaces an invalid value with a valid one. Since this bridge explicitly runs the form in onChange mode, validate the field when syncing a changed value (or explicitly clear/recompute its error).
  packages/apollo-react/src/canvas/components/Guardrails/use-metadata-form-bridge.ts:145
• setError(..., { type: 'external' }) on a registered field is removed by RHF's resolver when a later validation passes, but this effect only re-applies the message when the errors prop changes. If a caller keeps an error prop unchanged (for example, it does not provide onClearError), editing the field makes the host error disappear despite the documented "cleared only when the prop drops" contract. Re-apply host errors after validation/value changes or use an error overlay that the resolver cannot replace.
  packages/apollo-react/src/canvas/components/Guardrails/use-metadata-form-bridge.ts:90
• The sync loop only visits keys present in next, so removing a parameter from the controlled parameters array leaves its previous value registered in RHF and still visible. This violates the controlled contract for external updates; track the previous field keys and clear/reset fields that disappear (using the schema/default value) rather than treating omission as no-op.

• Files reviewed: 99/100 changed files
• Comments generated: 6
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Unresolved moderate issues remain in parsing, enrichment, hook state transitions, and map validation, plus one fixture documentation nit.

Get a fresh assessment by requesting another Copilot review.

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (7)

packages/apollo-react/src/canvas/components/Guardrails/definitions-enrich.ts:67

• This fallback does not actually humanize acronym or snake_case identifiers: IPAddress becomes I p address, and some_param remains Some_param. An otherwise valid new parameter with one of these common wire naming styles will therefore show a malformed label. Split acronym boundaries and _/- separators while lowercasing only words after the first, and add regression cases for these forms.
  packages/apollo-react/src/canvas/components/Guardrails/definitions-enrich.ts:56
• The parser normalizes an empty byoValidatorName, but this exported enrichment path accepts GuardrailDefinitionWire directly and treats byoValidatorName: '' as BYO because it only checks for undefined. A host using enrichGuardrailDefinitions without the parser would then bypass hiddenValidators and lose curated copy for a built-in definition. Keep the BYO predicate consistent with the parser by rejecting the empty string here as well.
  packages/apollo-react/src/canvas/components/Guardrails/definitions-parse.ts:120
• The parser currently rejects byoValidatorName: '' with this .min(1) schema, so the entire definition is added to invalid instead of being treated as a managed validator. That contradicts the normalization contract and the parser test; normalize the empty marker to undefined before validation rather than dropping the definition.
  packages/apollo-react/src/canvas/components/Guardrails/definitions-parse.ts:97
• The wire contract documented by this layer permits an unset boolean default, and seedGuardrailParameters already coerces a null boolean to false, but z.boolean() rejects that payload here. A backend definition with type: 'boolean' and defaultValue: null will therefore be dropped as invalid; make the hand-written wire mirror and parser schema nullable in sync.
  packages/apollo-react/src/canvas/components/Guardrails/use-guardrail-definitions.ts:131
• Because useState(enabled) is evaluated only on mount, loading is stale for one render whenever enabled or the request key changes. For example, switching from null to a context returns loading: false before the effect calls load, exposing the empty/stale state, while switching to options.definitions can return loading: true even though the supplied payload is already available. This causes the same transition flash that the initial-state fix was intended to prevent; derive the returned loading state from the current request generation or reset it synchronously when the key changes.
  packages/apollo-react/src/canvas/components/Guardrails/use-guardrail-definitions.ts:188
• When request changes, this effect starts the new fetch but leaves fetched untouched. parsed therefore continues exposing the previous request's definitions while loading is true, so switching tenant/account/base URL can render and allow editing old-context guardrails under the new context. Keep fetched data keyed to requestKey (while retaining the same-key refetch behavior), or clear it synchronously when the request key changes.
  packages/apollo-react/src/canvas/components/Guardrails/utils.ts:145
• The map editor deliberately keeps values for deselected keys until syncMapEnumParameters runs at save time, but this check scans every entry in the unsynchronized map. GuardrailBuilder calls it before that save-time reconciliation, so a user can enter an out-of-range value, deselect that key, and still be blocked by an error for a row that is no longer rendered. Validate only the keys currently selected by the map's keySource (or reconcile before checking).

• Files reviewed: 98/99 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Moderate parser, hook, humanization, fixture, and localization findings remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (10)

packages/apollo-react/src/canvas/components/Guardrails/README.md:134

• The catalog scan now iterates CANVAS_LOCALES, which contains en, ru, and 12 translated locales (14 files), not thirteen. This README claim is stale and understates the catalogs covered by the orphan sweep; update the count to match the implementation.

> `src/canvas` uses no lingui macros, so `lingui extract` does not feed this catalog: its
> entries are hand-authored. A test asserts every message reaches `src/canvas/locales/en.json`
> with the same English, and that the catalog carries no `guardrails.definitions.*` id the
> source no longer declares. That test is what extraction would otherwise be doing for you.

packages/apollo-react/src/canvas/components/Guardrails/fixtures/definitions-wire.fixtures.ts:52

• This fixture comment still describes the removed behavior: enrichment no longer supplies 0..1 bounds for this unbounded map, as the assertions below now verify. Please update the comment to say that only the 0.1 step hint is supplied and the min/max remain unset, otherwise the fixture documents the old save-blocking behavior.

      // The backend omits the bounds here; enrichment supplies 0..1 step 0.1.

packages/apollo-react/src/canvas/components/Guardrails/definitions-enrich.ts:66

• The fallback humanizer splits every uppercase character, so a valid uncurated parameter id such as APIKey becomes A p i key (and IPAddress becomes I p address). This path is used for backend parameters not yet in the curated table, so preserve consecutive-uppercase runs when inserting word boundaries.
  packages/apollo-react/src/canvas/components/Guardrails/definitions-parse.ts:192
• This contract comment is narrower than the implementation: the schemas also normalize empty byoConnectorName, byoConfigurationId, folderPath, and folderKey, and parameters defaults to []. That makes the documented wire behavior inaccurate for callers relying on the parser boundary; document these normalizations (or remove the claim that there are only two).
  packages/apollo-react/src/canvas/components/Guardrails/definitions-parse.ts:170
• The advertised “never throws” guarantee is still breakable for an object with a throwing validator getter (or proxy): safeParse can enter the catch, but readValidator(entry) then reads the same property outside any guard and throws while constructing the issue. Read the diagnostic validator defensively as well, so malformed entries are always reported rather than escaping the parser.
  packages/apollo-react/src/canvas/components/Guardrails/use-guardrail-definitions.ts:131
• useState(enabled) only applies on mount. If a host starts disabled (for example while it supplies options.definitions or has a null context) and then switches to a self-fetching context, enabled is true but loading is still false for the render before the effect calls load(). The documented loading ? ... : <Empty/> consumer can flash an empty state on that transition (and the same happens when changing request keys after a settled fetch). Track the request that has been loaded or derive a synchronous “new enabled request” state so loading is true before the effect runs.
  packages/apollo-react/src/canvas/components/Guardrails/use-guardrail-definitions.ts:117
• The hook claims the request is compared by context content, but JSON.stringify makes header insertion order part of that identity. Rebuilding equivalent headers as { Authorization, Tenant } and then { Tenant, Authorization } aborts and reissues the definitions request even though the HTTP headers are unchanged. Canonicalize the header entries (or otherwise compare them order-independently) before building this key.
  packages/apollo-react/src/canvas/components/Guardrails/use-guardrail-definitions.ts:224
• When a render switches from an active request to options.definitions or a null context, enabled becomes false immediately but these fields still return the previous request's loading/error until the passive effect runs. An in-flight request can therefore make a host show a spinner or transport error alongside the already-selected host payload for a paint; return disabled-state values synchronously (for example, mask them with enabled).
  packages/apollo-react/src/canvas/locales/de.json:268
• This translation changes the Microsoft product name from Azure AI Content Safety to Azure AI Content Security, which is a different/nonexistent service name and can mislead users about the validator dependency. Keep the product name Azure AI Content Safety in this localized description.
  packages/apollo-react/src/canvas/locales/es.json:260
• The Spanish tooltip leaves integer in English (Valor integer entre...), so this newly added localization is grammatically mixed and does not match the rest of the sentence. Use the Spanish term entero here.

• Files reviewed: 72/73 changed files
• Comments generated: 1
• Review effort level: Lite