map

name	map
type	primitive
description	Apply operation to each item in Collection

Map

INPUT CONTRACT

• target: Collection (variable or ID)
• operation: Tool/primitive name (string) or dict with tool field
• out: Variable name
• Additional fields: Tool-specific parameters

REQUIREMENTS:

• target MUST be Collection
• operation MUST be valid tool/primitive name
• Operation applied to each Note in Collection

NOT SUPPORTED IN MAP:

• Collection-only primitives: size, union, intersection, difference, join, filter-structured, sort, head, flatten, split
• Control flow: if, while, wait
• Discovery/search primitives: discover-notes, discover-collections, search-within-collection
• Persistence: persist, load, index

OUTPUT

Returns Collection of Notes, each containing result from applying operation. Failed/null results excluded if filter_null=true (default).

FAILURE SEMANTICS

Empty Collection = expected when:

• All operations fail or return null
• Type contract violated

Empty ≠ error — indicates no successful results, not failure.

Actual failures: Invalid target type, unknown operation, or missing parameters.

REPRESENTATION INVARIANTS

• map(load) on search-web results returns empty (results already materialized Notes)
• Empty result from map(load) = expected behavior, not diagnostic

ANTI-PATTERNS

❌ map(target=$note, operation="refine") → Must be Collection ❌ map(target=$results, operation="load") → search-web results already Notes ❌ map(target=$coll, operation="split") → split operates on Notes, not Collections ❌ Treating empty result as error → Empty = no successful operations