Class ListOperations

Add a view's results to an existing list. Always additive — never removes existing members. Dedupes silently, so safe to re-run.

No drop-confirmation needed (this op cannot drop). The implementation pipes through ComputeDelta + ApplyDelta so it still gets the token/staleness/permission machinery for free.

Apply a previously previewed ListDelta to its target list. Enforces the full drop-row warning contract (server-side, non-bypassable):

1. The token must verify (signature + 5-min TTL).
2. If the delta would remove records, opts.ConfirmDrops must be true.
3. The target list's current membership must still equal what the preview observed — otherwise STALE_DELTA (UI is expected to re-preview and ask the user again).
4. Caller must hold Editor permission (placeholder — Phase 2 wires the real ResourcePermission check).

Only mutates when all four pass. Concurrent mutations between preview and apply surface as STALE_DELTA rather than silently overwriting.

Preview a refresh / materialization. Never mutates. Returns a fully populated ListDelta including a signed DeltaToken that ApplyDelta will accept (subject to TTL + re-computation + permission checks).

• target = 'new': equivalent to materializing a new list — every record in source becomes a ToAdd, no removals are possible.
• target = ListSource(kind:'list'): a refresh of that list against source. mode controls whether removals are allowed (Sync) or forbidden (Additive).

Preview a set-op (union / intersection / difference) across two or more sources, optionally projected into a target list. Same drop-warning semantics as ComputeDelta: any operation that would remove records from an existing target sets Counts.Remove > 0 and produces a WILL_REMOVE_RECORDS warning.

difference is left-to-right: inputs[0] − inputs[1] − inputs[2] ….

Return the current members of a list as record IDs. Convenience wrapper over ResolveSource({ kind: 'list', listId }).

Materialize a new list from a User View. Creates an MJ: List record, captures lineage when requested, and bulk-inserts the resolved members as MJ: List Details rows.

Lineage semantics:

• RememberLineage = false → one-shot copy; the list cannot be refreshed against the view later. Useful when the user explicitly wants a frozen point-in-time snapshot decoupled from the view.
• RememberLineage = true, UseSnapshot = false → list remembers SourceViewID; future refreshes re-run the live view.
• RememberLineage = true, UseSnapshot = true → list remembers SourceViewID and a JSON snapshot of the view's filter state; future refreshes re-evaluate that snapshot even if the view itself has since been edited.

Never produces drops (target is brand new) — no delta-token needed.

Refresh an existing list against its captured source view. The list must have been created with RememberLineage = true (i.e. it has a non-null SourceViewID) — otherwise this returns TARGET_NOT_FOUND.

When list.UseSnapshot = true, the source is re-evaluated against the filter snapshot captured at materialization time. When false, the live view is re-run — which means edits to the view since materialization will be reflected in the result.

In Sync mode, callers MUST pass ConfirmDrops: true or the server-side drop guard will reject the apply with DROP_NOT_CONFIRMED. On success, LastRefreshedAt and LastRefreshedByUserID are updated.

Resolve any ListSource to a concrete set of record IDs + the entity name those IDs belong to. Never mutates. Used by every higher-level operation (ComputeDelta, ComputeSetOp, audience resolution, etc.).

Record IDs are returned in MJ List Detail format — single-PK entities use the raw value; composite-PK entities use the canonical Field1|Value1||Field2|Value2 form (CompositeKey.ToConcatenatedString).