data.Store: support opt-in insert/upsert for unknown pipeline push ids

Context

Realtime stores can receive unsolicited server pushes through the existing Neo.data.Pipeline -> Neo.data.Store path. Today that path is useful for record updates that are already present in the store, but it cannot surface a server-created record in a bound view unless application code reloads or patches the store separately.

The current implementation is intentionally conservative, and the source already marks the missing insert behavior as a future enhancement:

if (record) {
    record.set(data)
} else {
    // Future enhancement: handle inserts based on a config (e.g. autoInsertPushes)
    // me.add(data);
}

Live source check: src/data/Store.mjs:1131 currently looks up the pushed key and only calls record.set(data) when the record already exists. src/data/Pipeline.mjs:211 processes unsolicited connection pushes through the parser/normalizer path and forwards the shaped data as a push event. learn/guides/datahandling/DataPipelines.md:192 documents websocket push reactivity for existing records, but does not define safe insert or upsert semantics for unknown keys.

The Problem

Neo.data.Store#onPipelinePush() drops keyed pushes whose id is not already present in the store. That default is safe, but it leaves a framework gap for realtime CRUD stores: a server-pushed create event cannot appear in the bound grid/table through the standard pipeline path.

Application code can work around this with custom listeners, explicit reloads, or request/response patching, but the framework primitive should be available at the store level so applications can opt into well-defined behavior for newly-created records.

The Architectural Reality

• Neo.data.Pipeline#onConnectionPush() receives unsolicited connection push data, optionally runs parser and normalizer steps, then fires push with the shaped payload.
• Neo.data.Store#afterSetPipeline() subscribes the store to pipeline push events.
• Neo.data.Store#onPipelinePush() extracts data[me.getKeyProperty()], calls me.get(id), and updates only existing records.
• Unknown keyed pushes are currently ignored.
• Store already has local and remote projection controls that affect safe insertion semantics: filters, sorters, remoteFilter, remoteSort, currentPage, and pageSize.
• Existing unit coverage includes test/playwright/unit/data/PipelinePush.spec.mjs for pipeline push forwarding and test/playwright/unit/data/StorePush.spec.mjs for updating existing records through record.set().

The Fix

Add an explicit store-level opt-in for unknown keyed push records.

One possible API shape:

pushInsertStrategy: false | 'insert' | 'upsert' | 'reload' | 'reloadWhenUncertain'

A smaller first pass is also acceptable:

autoInsertPushes: false

The implementation must keep the default behavior unchanged. When opt-in behavior is enabled, unknown keyed pushes may be inserted/upserted only under documented, fail-safe projection rules.

Contract Ledger

Decision Record Impact

none

Acceptance Criteria

• Existing onPipelinePush() update behavior for known ids remains unchanged by default.
• Unknown keyed pushes are ignored by default.
• A store-level opt-in can insert or upsert unknown keyed push records.
• Local filters and local sorters have defined behavior for pushed inserts/upserts.
• A pushed record that fails a local filter does not become visible in the local filtered projection.
• Remote filters, remote sorting, and pagination do not silently corrupt the visible projection when membership/order is uncertain.
• Tests cover existing id update, unknown id ignored by default, opt-in insert/upsert, local filtered-out push handling, and remote-filter or paginated uncertainty.
• learn/guides/datahandling/DataPipelines.md documents websocket push insert/upsert semantics, defaults, and caveats.

Out of Scope

• Designing a full server mutation-event protocol for every CRUD operation.
• Making blind insertion the default behavior for all stores.
• Replacing the existing request/response RPC flow.
• Solving authorization or transport-level event validation.

Avoided Traps

• Do not auto-add every unknown id. Filtered stores, remotely sorted stores, paginated stores, and incomplete payloads make blind insertion incorrect.
• Do not treat delete or invalidate payloads as full records.
• Do not hide uncertainty behind a successful local insert when the server owns the projection.

Creation Checks

• Live latest-open sweep: checked the latest 20 open GitHub issues at 2026-07-01T13:12:44Z; no equivalent issue found.
• Live issue search: searched for onPipelinePush autoInsertPushes pipeline push Store; no equivalent issue found.
• Local content sweep: searched committed issue/discussion snapshots for onPipelinePush, autoInsertPushes, pushInsertStrategy, unknown keyed push, unknown id, and pipeline push; no equivalent issue found.
• Knowledge Base sweep: found closed related pipeline-update context (#9564, #9449), but no equivalent unknown-id insert/upsert issue.
• A2A in-flight sweep: checked recent messages for overlapping lane claims immediately before creation; no competing claim found.

Related

• src/data/Store.mjs
• src/data/Pipeline.mjs
• learn/guides/datahandling/DataPipelines.md
• test/playwright/unit/data/StorePush.spec.mjs
• test/playwright/unit/data/PipelinePush.spec.mjs

Handoff Retrieval Hint: "Store onPipelinePush unknown keyed websocket push insert upsert projection"