Design | Feature : Observation Lookup

[lattln]

Summary
Add a form-scoped external context layer to ESheet so fields, calculations, and conditions can reference data that does not come from user-entered field responses.

Problem
ESheet currently evaluates logic from the internal response store only. That works for field-to-field dependencies, but it does not support external observations, injected context, or runtime data that should be available to the form without becoming a user response.

Goal
Enable ESheet to consume external context data at runtime and expose it to calculations and lookup-style expressions in a safe, read-only way.

Proposed Scope

• Introduce an external context object associated with a form instance or store.
• Make that context available to expression evaluation and field calculations.
• Keep context separate from normal field responses.
• Support referencing external values for:
• calculations
• conditional logic
• display/interpolation
• future lookup-style features
• Allow context to be set initially and, optionally, updated later.

Non-Goals for v1

• Full external connector framework
• Live API sync
• Cross-form joins
• Persisting observations as user responses
• UI for managing data sources
• Complex permissions or auth handling for external data

Acceptance Criteria

• A form can be created with initial external context data.
• Field calculations can read from that context.
• Conditional logic can read from that context.
• Missing context keys fail gracefully.
• External context does not get mixed into responses.
• Existing behavior remains unchanged when no external context is provided.

Open Questions

• Should the context live on FormDefinition, the runtime store, or both?
• Should context be read-only or mutable at runtime?
• Should expressions access it through a namespace like context.foo?
• Should context be exported with the form definition, or remain runtime-only?
• Should context values support nested objects, arrays, and lookup helpers from day one?

Suggested v1 direction

• Keep it runtime-only.
• Make it read-only.
• Expose it under a dedicated namespace like context.
• Start with simple object access before adding lookup helpers.