collection 1.19.1: Aggregate multiple lists and maps into unmodifiable dynamic composite views using CombinedListView and CombinedMapView without copying elements.

# package:collection — CombinedListView & CombinedMapView

## Search Results

Querying `search_known_solution` for `package:collection` returned existing verified solutions covering other symbols:
- `sha256:8376217b4f599376ba9a7e40e78691ee88b2b13e999166fe688cf065e655bbc3`: PriorityQueue non-mutating iteration and heap storage order.
- `sha256:01e34c528f3558e8c8fcce7ed5aca9d49ef79c1d61128086d599b629fba42a9b`: mergeSort generic subtyping behavior.
- `sha256:de4d08928887828134110edcd137f83b030f3b508973b92860e7439bf8ec2234`: binarySearch index lookup semantics.
- `sha256:e0368138deaa5543fd8c32462b0bf325847128438b1e712d85acb689585e8feb`: CanonicalizedMap key validation handling.

No existing sample addressed unmodifiable composite aggregation views (`CombinedListView` and `CombinedMapView`).

## Pinned Release

- `collection`: `1.19.1` (resolved via `pubspec.lock`)
- `dart`: SDK `^3.5.0`

## Observed Behaviour

1. **Dynamic Unmodifiable Views Without Eager Copying**:
   - `CombinedListView` and `CombinedMapView` wrap multiple existing collections into single unified view interfaces without flattening or copying elements into memory.
   - Any structural mutation made to the underlying collections (e.g. adding elements, deleting keys) dynamically reflects in the combined view immediately, updating its `.length`, key mappings, and element lookups.

2. **Unmodifiable Enforcement**:
   - Direct mutation calls on the combined view (`add`, `[]=`, `remove`, `clear`) throw `UnsupportedError` at runtime.

3. **Key Shadowing and Fallthrough Precedence**:
   - In `CombinedMapView`, key resolution follows the sequence order of the underlying map list. The first map containing a key determines its value and entry in `.keys`.
   - When a shadowed key is removed from an earlier map, lookups for that key dynamically fall through to the next map containing it.

4. **Indexed Access Across Partitions**:
   - `CombinedListView` maps linear indices across the partitioned sublists.
   - Resizing an underlying sublist (via `insert` or `removeAt`) dynamically shifts element index mapping across subsequent sublists.

{"case":{"caseId":"case:sha256:9a1f3d8f9b86875c08769d3ece4693cc5d1821728814198c985787852b4cdef5","contract":["CombinedListView and CombinedMapView create unmodifiable views across multiple underlying collections that reflect underlying structural mutations dynamically without copying.","Direct mutation attempts on CombinedListView and CombinedMapView throw UnsupportedError.","CombinedMapView resolves duplicate keys by prioritizing the first map containing the key, falling through to subsequent maps when the key is removed from the earlier map.","CombinedListView indexes contiguous elements across nested list boundaries and dynamically updates indexing when underlying lists resize."],"goal":"Aggregate multiple lists and maps into unmodifiable dynamic composite views using CombinedListView and CombinedMapView without copying elements.","kind":"HOW","packages":["pkg:pub/collection@1.19.1"],"schemaVersion":1,"symbols":["CombinedListView","CombinedMapView"]},"contractCommand":["dart","test/contract.dart"],"environment":{"arch":"x64","ecosystem":"pub","executionContext":"dart","language":"dart","os":"linux","packageManager":"pub","runtime":"dart","schemaVersion":1},"license":"MIT-0","packages":["pkg:pub/collection@1.19.1"],"schemaVersion":1,"symbols":["CombinedListView","CombinedMapView"],"verifierAdapter":"pub@1"}

import 'package:collection/collection.dart';

/// Wraps multiple lists in an unmodifiable [CombinedListView].
List<T> createCombinedList<T>(List<List<T>> lists) {
  return CombinedListView<T>(lists);
}

/// Wraps multiple map layers (e.g. defaults overlaid by overrides) into
/// an unmodifiable [CombinedMapView] where earlier maps take precedence.
Map<K, V> createLayeredMap<K, V>(List<Map<K, V>> maps) {
  return CombinedMapView<K, V>(maps);
}

# Generated by pub
# See https://dart.dev/tools/pub/glossary#lockfile
packages:
  collection:
    dependency: "direct main"
    description:
      name: collection
      sha256: "2f5709ae4d3d59dd8f7cd309b4e023046b57d8a6c82130785d2b0e5868084e76"
      url: "https://pub.dev"
    source: hosted
    version: "1.19.1"
sdks:
  dart: ">=3.5.0 <4.0.0"

name: pub_collection_version_depth
description: CombinedListView and CombinedMapView dynamic unmodifiable view semantics in package:collection.
publish_to: none
environment:
  sdk: ^3.5.0
dependencies:
  collection: 1.19.1

import 'package:collection/collection.dart';
import '../lib/combined_views.dart';

void main() {
  const listEq = ListEquality<int>();
  const mapEq = MapEquality<String, int>();

  // 1. CombinedListView and CombinedMapView create dynamic unmodifiable views reflecting underlying mutations without copying.
  final listA = [10, 20];
  final listB = [30, 40];
  final combinedList = createCombinedList([listA, listB]);

  if (combinedList.length != 4) {
    throw StateError('Expected combinedList initial length to be 4, got ${combinedList.length}');
  }
  if (!listEq.equals(combinedList, [10, 20, 30, 40])) {
    throw StateError('Expected combinedList to contain [10, 20, 30, 40]');
  }

  // Mutate underlying list: the view reflects it dynamically
  listA.add(25);
  if (combinedList.length != 5) {
    throw StateError('Expected combinedList length to update to 5 after underlying mutation');
  }
  if (!listEq.equals(combinedList, [10, 20, 25, 30, 40])) {
    throw StateError('Expected combinedList elements to reflect underlying mutation');
  }

  final mapDefaults = {'timeout': 30, 'retries': 3, 'port': 8080};
  final mapOverrides = {'port': 9090, 'retries': 5};
  final combinedMap = createLayeredMap([mapOverrides, mapDefaults]);

  if (combinedMap.length != 3) {
    throw StateError('Expected combinedMap length to be 3 (unique keys), got ${combinedMap.length}');
  }

  // Mutate underlying map: view reflects new entries immediately
  mapDefaults['bufferSize'] = 1024;
  if (combinedMap.length != 4) {
    throw StateError('Expected combinedMap length to become 4 after adding key to underlying map');
  }
  if (combinedMap['bufferSize'] != 1024) {
    throw StateError('Expected combinedMap to resolve newly added underlying key');
  }

  // 2. Direct mutation attempts on CombinedListView and CombinedMapView throw UnsupportedError.
  bool listAddFailed = false;
  try {
    combinedList.add(50);
  } on UnsupportedError {
    listAddFailed = true;
  }
  if (!listAddFailed) {
    throw StateError('Expected UnsupportedError when calling add on CombinedListView');
  }

  bool listSetFailed = false;
  try {
    combinedList[0] = 999;
  } on UnsupportedError {
    listSetFailed = true;
  }
  if (!listSetFailed) {
    throw StateError('Expected UnsupportedError when modifying element via []= on CombinedListView');
  }

  bool listClearFailed = false;
  try {
    combinedList.clear();
  } on UnsupportedError {
    listClearFailed = true;
  }
  if (!listClearFailed) {
    throw StateError('Expected UnsupportedError when calling clear on CombinedListView');
  }

  bool mapPutFailed = false;
  try {
    combinedMap['newKey'] = 123;
  } on UnsupportedError {
    mapPutFailed = true;
  }
  if (!mapPutFailed) {
    throw StateError('Expected UnsupportedError when modifying CombinedMapView via []=');
  }

  bool mapRemoveFailed = false;
  try {
    combinedMap.remove('port');
  } on UnsupportedError {
    mapRemoveFailed = true;
  }
  if (!mapRemoveFailed) {
    throw StateError('Expected UnsupportedError when calling remove on CombinedMapView');
  }

  bool mapClearFailed = false;
  try {
    combinedMap.clear();
  } on UnsupportedError {
    mapClearFailed = true;
  }
  if (!mapClearFailed) {
    throw StateError('Expected UnsupportedError when calling clear on CombinedMapView');
  }

  // 3. CombinedMapView resolves duplicate keys by prioritizing earlier maps, falling through on removal.
  final layerHigh = {'host': 'primary.example.com', 'env': 'prod'};
  final layerLow = {'host': 'fallback.example.com', 'env': 'dev', 'region': 'us-east'};
  final layeredConfig = CombinedMapView([layerHigh, layerLow]);

  if (layeredConfig['host'] != 'primary.example.com') {
    throw StateError('Expected layerHigh to shadow layerLow for host');
  }
  if (layeredConfig['env'] != 'prod') {
    throw StateError('Expected layerHigh to shadow layerLow for env');
  }
  if (layeredConfig['region'] != 'us-east') {
    throw StateError('Expected non-shadowed key region from layerLow to be accessible');
  }

  // Removing shadowed key from layerHigh makes layerLow value visible
  layerHigh.remove('host');
  if (layeredConfig['host'] != 'fallback.example.com') {
    throw StateError('Expected host lookup to fall through to fallback.example.com after layerHigh removal');
  }

  // Adding shadowed key back to layerHigh restores its precedence
  layerHigh['host'] = 'override.example.com';
  if (layeredConfig['host'] != 'override.example.com') {
    throw StateError('Expected newly added layerHigh key to take precedence over layerLow');
  }

  // 4. CombinedListView indexes contiguous elements across nested list boundaries and dynamically updates indexing on resize.
  final sub1 = [100, 200];
  final sub2 = [300];
  final sub3 = [400, 500, 600];
  final indexedCombined = CombinedListView([sub1, sub2, sub3]);

  if (indexedCombined[0] != 100 ||
      indexedCombined[1] != 200 ||
      indexedCombined[2] != 300 ||
      indexedCombined[3] != 400 ||
      indexedCombined[4] != 500 ||
      indexedCombined[5] != 600) {
    throw StateError('Indexed access across partition boundaries failed');
  }

  // Inserting an element in sub1 shifts all subsequent indices across sub2 and sub3
  sub1.insert(1, 150); // sub1 is now [100, 150, 200]
  if (indexedCombined.length != 7) {
    throw StateError('Expected length 7 after insert into sub1');
  }
  if (indexedCombined[1] != 150) {
    throw StateError('Expected index 1 to be newly inserted 150');
  }
  if (indexedCombined[2] != 200) {
    throw StateError('Expected index 2 to be shifted 200');
  }
  if (indexedCombined[3] != 300) {
    throw StateError('Expected index 3 to be 300 from sub2 after shift');
  }
  if (indexedCombined[6] != 600) {
    throw StateError('Expected index 6 to be 600 from sub3 after shift');
  }

  // Removing an element from sub2 shifts sub3 elements left
  sub2.removeAt(0); // sub2 is now empty []
  if (indexedCombined.length != 6) {
    throw StateError('Expected length 6 after emptying sub2');
  }
  if (indexedCombined[3] != 400) {
    throw StateError('Expected index 3 to now point directly to sub3[0] (400)');
  }

  print('Contract assertions passed cleanly.');
}