Skip to content

fix(dart/a2ui_agent): reject multiple v0.9 catalogs in Express format (#3341) - #4277

Open
jihanurrahman33 wants to merge 2 commits into
a2ui-project:mainfrom
jihanurrahman33:fix/3341-dart-express-v09-catalogs
Open

jihanurrahman33 wants to merge 2 commits into
a2ui-project:mainfrom
jihanurrahman33:fix/3341-dart-express-v09-catalogs

Conversation

@jihanurrahman33

Copy link
Copy Markdown

Fixes #3341

Summary of Changes

Enforces A2uiCatalogError when multiple catalogs are passed below v1.0 across Dart Express components (ExpressFormat, ExpressCompiler, ExpressDecompiler, ExpressPromptGenerator), matching Python (check_mixed_catalogs) and TypeScript (checkMixedCatalogs).

  1. dart/a2ui_agent/lib/src/utils/catalogs.dart:
    • Added checkMixedCatalogs(List<CatalogApi> catalogs) which verifies distinct catalog IDs and requires protocol version v1.0 or later when multiple catalogs are active.
  2. dart/a2ui_agent/lib/src/inference_formats/express/:
    • format.dart: Replaced checkDistinctIds with checkMixedCatalogs.
    • compiler.dart: Enforced checkMixedCatalogs in ExpressCompiler constructor, compile(), and compileIncremental().
    • decompiler.dart: Enforced checkMixedCatalogs in ExpressDecompiler constructor and decompile().
    • prompt_generator.dart: Enforced checkMixedCatalogs in ExpressPromptGenerator.generate() and removed legacy non-standard v0.9 multi-catalog prompt generator helper _catalogsV0_9.
  3. dart/a2ui_agent/test/:
    • Unskipped test_express_create_format_rejects_several_v0_9_catalogs in request_processor_conformance_test.dart.
    • Registered multi-catalog Express conformance cases as v1.0-only for lowered v0.9 suites (matching Python's _ONE_CATALOG_PER_SURFACE handling in lowering.py).
    • Updated unit tests in express_test.dart, express_decompiler_test.dart, and generator_test.dart to assert that multiple v0.9 catalogs throw A2uiCatalogError.
  4. specification/proposals/express/a2ui_express.md:
    • Removed obsolete note claiming the Dart Express compiler does not support v1.0.

Verification

  • dart analyze across dart/a2ui_agent: 0 issues found.
  • dart format across dart/a2ui_agent: clean.
  • dart test across dart/a2ui_agent: all 1,934 tests passed.
  • dart test across dart/a2ui_core: all 2,405 tests passed.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the Dart Express compiler, decompiler, and prompt generator to enforce that multiple active catalogs are only supported when targeting A2UI v1.0 or later, introducing the checkMixedCatalogs helper to validate this constraint. The feedback highlights several redundant invocations of checkMixedCatalogs in compile, compileStep, decompile, and generate methods, noting that these checks are already performed during the instantiation of ExpressCompiler and ExpressDecompiler. Removing these duplicate validations will simplify the codebase and prevent unnecessary overhead, particularly in performance-sensitive streaming compilation paths.

Comment on lines +185 to +188
if (catalogs.isEmpty) {
throw A2uiCatalogError('Compiling Express needs at least one catalog.');
}
checkMixedCatalogs(catalogs);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The call to checkMixedCatalogs is redundant here because the ExpressCompiler constructor already validates the catalogs upon instantiation. Removing this duplicate check simplifies the method and avoids redundant validation overhead.

Suggested change
if (catalogs.isEmpty) {
throw A2uiCatalogError('Compiling Express needs at least one catalog.');
}
checkMixedCatalogs(catalogs);
if (catalogs.isEmpty) {
throw A2uiCatalogError('Compiling Express needs at least one catalog.');
}

Comment on lines +2059 to +2062
if (compiler.catalogs.isEmpty) {
throw A2uiCatalogError('Compiling Express needs at least one catalog.');
}
checkMixedCatalogs(compiler.catalogs);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The call to checkMixedCatalogs here is redundant and introduces unnecessary overhead. ExpressScopeSession is constructed with an ExpressCompiler instance, whose constructor already validates the catalogs. Since compileStep is called repeatedly for every chunk of streaming input, performing this validation on every step is inefficient.

Suggested change
if (compiler.catalogs.isEmpty) {
throw A2uiCatalogError('Compiling Express needs at least one catalog.');
}
checkMixedCatalogs(compiler.catalogs);
if (compiler.catalogs.isEmpty) {
throw A2uiCatalogError('Compiling Express needs at least one catalog.');
}

Comment on lines +105 to +108
if (catalogs.isEmpty) {
throw A2uiCatalogError('Decompiling Express needs at least one catalog.');
}
checkMixedCatalogs(catalogs);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The call to checkMixedCatalogs is redundant here because the ExpressDecompiler constructor already validates the catalogs upon instantiation. Removing this duplicate check simplifies the method and avoids redundant validation overhead.

Suggested change
if (catalogs.isEmpty) {
throw A2uiCatalogError('Decompiling Express needs at least one catalog.');
}
checkMixedCatalogs(catalogs);
if (catalogs.isEmpty) {
throw A2uiCatalogError('Decompiling Express needs at least one catalog.');
}

Comment on lines +67 to +70
if (catalogs.isEmpty) {
throw A2uiCatalogError('An Express prompt needs at least one catalog.');
}
checkMixedCatalogs(catalogs);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The call to checkMixedCatalogs is redundant here because ExpressDecompiler(catalogs) is instantiated immediately on the next line, and its constructor already performs this exact validation. Removing this duplicate check simplifies the method and avoids redundant validation overhead.

Suggested change
if (catalogs.isEmpty) {
throw A2uiCatalogError('An Express prompt needs at least one catalog.');
}
checkMixedCatalogs(catalogs);
if (catalogs.isEmpty) {
throw A2uiCatalogError('An Express prompt needs at least one catalog.');
}

@jihanurrahman33

Copy link
Copy Markdown
Author

Thanks @gemini-code-assist! The redundant calls to checkMixedCatalogs in compile, compileIncremental, decompile, and generate have been removed in commit 2adc57f. All validations now run cleanly on instantiation in ExpressCompiler, ExpressDecompiler, and ExpressFormat constructors with zero repeated overhead. All 1,934 tests and static analysis continue to pass cleanly.

@gemini-code-assist

Copy link
Copy Markdown
Contributor

Thanks for the update, @jihanurrahman33. It's great to hear that the redundant calls have been cleaned up and that the test suite remains robust. This change significantly improves the maintainability of the Express components by centralizing the catalog validation logic. Everything looks solid.

@github-actions github-actions Bot added the status: needs-triage auto-managed: https://github.com/a2ui-project/a2ui/blob/main/scripts/triage.mjs label Nov 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

📖 Docs Site Preview Deployed

Preview URL: https://a2ui.org/pr-preview/pr-4277/

Built from commit 2adc57f · Workflow run · GitHub Pages may take ~30–60s to propagate updates. This preview is removed automatically when the PR closes.

github-actions Bot added a commit that referenced this pull request Nov 17, 2026

@gspencergoog gspencergoog left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR adds checkMixedCatalogs in dart/a2ui_agent/lib/src/utils/catalogs.dart and calls it from the ExpressFormat, ExpressCompiler, and ExpressDecompiler constructors so that binding multiple catalogs targeting a protocol version before v1.0 throws A2uiCatalogError, fixing #3341. It also removes the obsolete _catalogsV0_9 multi-catalog prompt section from ExpressPromptGenerator, updates Dart unit and conformance tests for single-catalog v0.9 Express, and removes the outdated Dart v1.0 limitation note from specification/proposals/express/a2ui_express.md.

The runtime validation, conformance test updates, and specification edit match the Python and TypeScript SDKs, and all Dart/Flutter, format, static, and docs CI checks pass at 2adc57fa (health / changelog / run changelog health check failed due to no changelog entry). All four prior gemini-code-assist threads were cleanly addressed in 2adc57fa. Two low-severity documentation findings note constructor and helper doc comments that omit incompatible-version or A2uiCatalogError details. Citation audit: 0 critical/high findings checked.

🤖 Agent-generated

/// In Express, when several catalogs are active, components and function calls
/// carry per-item `catalogId` fields, which requires A2UI v1.0 or later.
///
/// Throws [A2uiCatalogError] if any catalog id repeats, or if several catalogs

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

checkMixedCatalogs calls catalogsProtocolVersion(catalogs) when catalogs.length > 1. That helper also throws A2uiCatalogError when the catalogs target incompatible protocol versions. Callers reading the docstring miss that passing catalogs of different protocol versions throws A2uiCatalogError.

Suggested change
/// Throws [A2uiCatalogError] if any catalog id repeats, or if several catalogs
/// Throws [A2uiCatalogError] if any catalog id repeats, if the catalogs target
/// different protocol versions, or if several catalogs
Details

Evidence (Read): dart/a2ui_agent/lib/src/utils/catalogs.dart:75-80 states /// Throws [A2uiCatalogError] if any catalog id repeats, or if several catalogs / /// target a version before v1.0. while line 80 calls catalogsProtocolVersion(catalogs), which throws A2uiCatalogError when catalogs target incompatible protocol versions (dart/a2ui_agent/lib/src/utils/catalogs.dart:42-45).

🤖 Agent-generated

/// The first of [catalogs] is the default for a surface that does not name
/// its catalog.
ExpressCompiler(this.catalogs);
ExpressCompiler(this.catalogs) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ExpressCompiler now calls checkMixedCatalogs(catalogs) in its constructor instead of compile(). Its constructor docstring does not document that construction throws A2uiCatalogError. Callers instantiating ExpressCompiler are not warned that construction throws A2uiCatalogError on duplicate IDs, mismatched versions, or multiple pre-v1.0 catalogs.

Suggested change
ExpressCompiler(this.catalogs) {
///
/// Throws [A2uiCatalogError] if two of [catalogs] share an id, if they
/// target different protocol versions, or if several target a version before
/// v1.0.
ExpressCompiler(this.catalogs) {
Details

Evidence (Read): dart/a2ui_agent/lib/src/inference_formats/express/compiler.dart:151-155 adds checkMixedCatalogs(catalogs); to ExpressCompiler(this.catalogs) and line 182 removes or they target different versions from compile(), leaving the constructor without a Throws [A2uiCatalogError] comment.

The same constructor contract update applies to ExpressDecompiler(this.catalogs) (decompiler.dart:58-62), ExpressFormat (format.dart:66, 80), and ExpressFormatFactory.createFormat (format.dart:45). Also, the sentence The first of [catalogs] is the default for a surface that does not name its catalog. on ExpressCompiler, ExpressDecompiler, ExpressFormat, ExpressParser, and ExpressPromptGenerator is left over from pre-v1.0 multi-catalog support. Pre-v1.0 now allows only one catalog, and v1.0 multi-catalog surfaces have no default catalog (compiler.dart:330-338).

🤖 Agent-generated

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: needs-triage auto-managed: https://github.com/a2ui-project/a2ui/blob/main/scripts/triage.mjs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[dart/a2ui_agent] ExpressFormat accepts multiple v0.9 catalogs instead of throwing A2uiCatalogError

2 participants