@memberjunction/lists 0.0.1 → 5.36.0

package/README.md

@@ -1,45 +1,309 @@
 # @memberjunction/lists
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Pure TypeScript core for MemberJunction Lists. Owns list materialization,
+set algebra, delta computation, lineage tracking, refresh modes, drop
+guards, sharing, and audience resolution. Framework-agnostic — no
+GraphQL, HTTP, or Angular dependencies.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+This is the **source of truth** for the type contracts that the rest of
+the stack (the `ListOperationsResolver` in `@memberjunction/server`, the
+`GraphQLListsClient` in `@memberjunction/graphql-dataprovider`, the
+Phase-N list Actions in `@memberjunction/core-actions`, and the Angular
+components in `@memberjunction/ng-list-management`) all import from.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Installation
 
-## Purpose
+```bash
+npm install @memberjunction/lists
+```
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/lists`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## What's in here
 
-## What is OIDC Trusted Publishing?
+```
+ListOperations    → materialize / refresh / compose / preview-and-apply
+ListSharing       → direct shares, email invitations, audit log, capabilities
+AudienceResolver  → friendly-named re-export of ResolveSource (Communications)
+deltaToken        → HMAC-signed preview-token contract (server enforced)
+types             → ListSource, ListDelta, ListCapabilities, etc.
+```
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## Public API surface
 
-## Setup Instructions
+### Core types (`types.ts`)
 
-To properly configure OIDC trusted publishing for this package:
+```typescript
+type ListRefreshMode = 'Additive' | 'Sync';
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+type ListSource =
+  | { kind: 'list'; listId: string }
+  | { kind: 'view'; viewId: string; runtimeParams?: Record<string, unknown> }
+  | { kind: 'adhoc'; entityName: string; extraFilter: string };
 
-## DO NOT USE THIS PACKAGE
+interface ResolvedRecordSet {
+  EntityName: string;
+  RecordIds: string[];       // MJ: List Detail.RecordID format
+  TotalCount?: number;
+}
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+interface ListDelta {
+  TargetListId: string | null;
+  EntityName: string;
+  ToAdd: string[];
+  ToRemove: string[];
+  Unchanged: string[];
+  Counts: { Add; Remove; Unchanged; SourceTotal; TargetTotal };
+  Warnings: ListDeltaWarning[];
+  DeltaToken: string;        // HMAC, 5-min TTL
+}
 
-## More Information
+interface ApplyResult {
+  Success: boolean;
+  ResultCode: 'SUCCESS' | 'DROP_NOT_CONFIRMED' | 'STALE_DELTA' |
+              'INVALID_TOKEN' | 'PERMISSION_DENIED' | 'TARGET_NOT_FOUND' |
+              'PARTIAL_SUCCESS' | 'UNEXPECTED_ERROR';
+  Message: string;
+  CreatedListId?: string;
+  TargetListId?: string;
+  Counts?: { Added; Removed; Failed };
+  Errors?: string[];
+}
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+### `ListOperations`
 
----
+Constructor: `new ListOperations(contextUser, provider?)`.
 
-**Maintained for OIDC setup purposes only**
+```typescript
+// Read-only
+ResolveSource(source: ListSource): Promise<ResolvedRecordSet>;
+GetListMembers(listId: string): Promise<ResolvedRecordSet>;
+
+// Preview (never mutates) — returns a signed DeltaToken
+ComputeDelta(target: ListSource | 'new', source: ListSource, mode: ListRefreshMode): Promise<ListDelta>;
+ComputeSetOp(op: 'union' | 'intersection' | 'difference', inputs: ListSource[], target?: ListSource | 'new'): Promise<ListDelta>;
+
+// Commit (server enforces token validity + drop guard)
+ApplyDelta(delta: ListDelta, opts: { ConfirmDrops: boolean; DeltaToken: string }): Promise<ApplyResult>;
+
+// High-level convenience
+MaterializeFromView(viewId: string, opts: MaterializeOptions): Promise<ApplyResult>;
+AddViewResultsToList(viewId: string, listId: string): Promise<ApplyResult>;
+RefreshFromSource(listId: string, mode: ListRefreshMode, opts: { ConfirmDrops: boolean }): Promise<ApplyResult>;
+```
+
+#### The drop-row warning contract
+
+Every mutating list operation goes through `ComputeDelta` first. The
+returned `DeltaToken` is an HMAC over `{targetListId, source signature,
+mode, timestamp}` with a 5-minute TTL.
+
+`ApplyDelta` enforces, **server-side**, in this order:
+
+1. Token signature + 5-min TTL — else `INVALID_TOKEN`.
+2. Re-compute against current target state — else `STALE_DELTA`.
+3. `Counts.Remove > 0 && !ConfirmDrops` — else `DROP_NOT_CONFIRMED`.
+4. Editor permission on target (placeholder; Phase 2 wires the real
+   `ResourcePermission` check).
+
+The Angular `<mj-list-delta-confirm>` dialog is the only UI path that
+produces a valid token. The server rejects drops regardless of UI.
+
+### `ListSharing`
+
+Constructor: `new ListSharing(contextUser, provider?)`.
+
+```typescript
+type SharePermissionLevel = 'View' | 'Edit' | 'Owner';
+
+type ShareTarget =
+  | { kind: 'user'; userId: string }
+  | { kind: 'role'; roleId: string };
+
+// Direct shares (recipient already has an MJ account)
+Share(args: { ListID; Target; PermissionLevel }): Promise<ShareResult>;
+Unshare(permissionId: string): Promise<ShareResult>;
+GetSharesForList(listId: string): Promise<ListShareSummary[]>;
+GetListsSharedWithUser(): Promise<SharedListSummary[]>;
+
+// Email invitations (recipient may not yet have an account)
+Invite(args: { ListID; Email; Role: 'Editor' | 'Viewer'; TtlMs? }): Promise<InviteResult>;
+AcceptInvitation(token: string): Promise<AcceptInvitationResult>;
+RevokeInvitation(invitationId: string): Promise<ShareResult>;
+
+// Permission introspection for UI gating
+ResolveEffectivePermission(listId: string): Promise<SharePermissionLevel | null>;
+```
+
+Every mutation also writes an `MJ: Audit Logs` entry. Audit log types
+are seeded via metadata sync (see
+[`metadata/audit-log-types/.list-sharing-audit-types.json`](../../metadata/audit-log-types/.list-sharing-audit-types.json)).
+
+Direct user-shares fan out via the platform `CreateShareNotification`
+dispatcher (registered by `@memberjunction/notifications`) — recipients
+get in-app + email notifications per their preferences. Role-target
+shares are not fanned out per-user (that's a separate worker).
+
+### Capability gating
+
+UI components should derive button visibility from the caller's
+effective permission level, not from raw entity-permission flags. The
+mapping is centralized so UI and server agree:
+
+```typescript
+const level: SharePermissionLevel | null =
+  await sharing.ResolveEffectivePermission(listId);
+
+const caps: ListCapabilities = capabilitiesForLevel(level);
+// caps.CanEdit / CanRefresh / CanShare / CanDelete / CanRunOperations
+// Server-side enforcement remains the source of truth — these are a
+// UX convenience so users don't see buttons they'll be rejected on.
+```
+
+Mapping per mockup 19:
+
+| Level   | Read | Edit | Refresh | Share | Delete | Operations |
+| ------- | :--: | :--: | :-----: | :---: | :----: | :--------: |
+| Owner   | ✓    | ✓    | ✓       | ✓     | ✓      | ✓          |
+| Editor  | ✓    | ✓    | ✓       | ✗     | ✗      | ✓          |
+| Viewer  | ✓    | ✗    | ✗       | ✗     | ✗      | ✗          |
+| null    | ✗    | ✗    | ✗       | ✗     | ✗      | ✗          |
+
+### `AudienceResolver`
+
+Friendly-named entry point for resolving an `AudienceSource` (= `ListSource`)
+to a `ResolvedRecordSet`. Identical semantics to
+`ListOperations.ResolveSource`, exposed under a name that reads
+naturally for Communications and other audience-aware code.
+
+```typescript
+const resolver = new AudienceResolver(contextUser, provider);
+const result = await resolver.Resolve({ kind: 'list', listId });
+// result.RecordIds — array of record IDs in the target audience
+```
+
+### `deltaToken`
+
+Internal helpers exposed for resolver-layer use. Server bootstrap must
+set the HMAC secret:
+
+```typescript
+import { SetDeltaTokenSecret } from '@memberjunction/lists';
+
+SetDeltaTokenSecret(process.env.MJ_LIST_DELTA_SECRET);
+```
+
+Falls back to the env var `MJ_LIST_DELTA_SECRET` if no explicit call is
+made. Refuses to use a default secret — silent fallback would let a
+misconfigured server hand out forgeable tokens.
+
+## Examples
+
+### Save a view's current results as a new list with lineage
+
+```typescript
+const ops = new ListOperations(currentUser, provider);
+const result = await ops.MaterializeFromView('view-abc', {
+  ListName: 'Q4 VIP Donors',
+  Description: 'Materialized from the Q4 Donor View',
+  CategoryId: 'cat-marketing',
+  RememberLineage: true,     // can refresh from source later
+  UseSnapshot: false,        // refresh re-reads the live view
+  RefreshMode: 'Additive',   // default refresh mode for this list
+});
+// result.CreatedListId, result.Counts.Added
+```
+
+### Refresh a lineage-bearing list (Sync mode, will drop missing rows)
+
+```typescript
+const result = await ops.RefreshFromSource(listId, 'Sync', {
+  ConfirmDrops: true,    // required when Sync mode would remove records
+});
+```
+
+### Preview a 3-way intersection without committing
+
+```typescript
+const delta = await ops.ComputeSetOp('intersection', [
+  { kind: 'list', listId: 'list-a' },
+  { kind: 'view', viewId: 'view-b' },
+  { kind: 'view', viewId: 'view-c' },
+]);
+// delta.ToAdd has the resulting record IDs; nothing has been saved.
+```
+
+### Share a list with an Editor
+
+```typescript
+const sharing = new ListSharing(currentUser, provider);
+const result = await sharing.Share({
+  ListID: 'list-abc',
+  Target: { kind: 'user', userId: 'user-xyz' },
+  PermissionLevel: 'Edit',
+});
+// In-app + email notification fires automatically via the platform handler.
+```
+
+### Invite someone by email
+
+```typescript
+const inv = await sharing.Invite({
+  ListID: 'list-abc',
+  Email: 'recipient@example.com',
+  Role: 'Editor',
+  TtlMs: 7 * 24 * 60 * 60 * 1000,
+});
+// inv.Token + inv.ExpiresAt — the caller builds the accept URL.
+```
+
+## Architecture
+
+Sits at the bottom of a four-layer stack:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Angular UI (@memberjunction/ng-list-management,           │
+│  @memberjunction/ng-explorer-core, etc.)                   │
+└────────────────────────────┬───────────────────────────────┘
+                             ↓ uses
+┌────────────────────────────────────────────────────────────┐
+│  GraphQLListsClient (@memberjunction/graphql-dataprovider) │
+└────────────────────────────┬───────────────────────────────┘
+                             ↓ wire format
+┌────────────────────────────────────────────────────────────┐
+│  ListOperationsResolver (@memberjunction/server)           │
+└────────────────────────────┬───────────────────────────────┘
+                             ↓ delegates to
+┌────────────────────────────────────────────────────────────┐
+│  ListOperations / ListSharing / AudienceResolver  ← this   │
+│  (@memberjunction/lists)                                   │
+└────────────────────────────────────────────────────────────┘
+```
+
+Every layer is a thin pass-through. The Actions in
+`@memberjunction/core-actions` (`MaterializeListFromViewAction`,
+`ShareListAction`, etc.) are parallel consumers — they import directly
+from this package so AI agents, workflows, and scheduled jobs get the
+same capability as the UI.
+
+## Dependencies
+
+- `@memberjunction/core` — `Metadata`, `RunView`, `UserInfo`, `IMetadataProvider`
+- `@memberjunction/core-entities` — `MJListEntity`, `MJResourcePermissionEntity`, etc.
+- `@memberjunction/global` — class registration utilities
+
+No HTTP, no GraphQL, no Angular.
+
+## Testing
+
+```bash
+cd packages/Lists
+npm run test
+```
+
+76 vitest cases across `deltaToken` (HMAC roundtrip + secret resolution),
+`ListOperations` (math, set-ops, drop guard, materialize, refresh modes,
+snapshot vs live), `AudienceResolver`, and `ListSharing` (share / invite
+/ accept / revoke lifecycle, capability mapping).
+
+Coverage tracked at 88%+ lines; reports via `npm run test:coverage`.

package/dist/AudienceResolver.d.ts

@@ -0,0 +1,22 @@
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { AudienceSource, ResolvedRecordSet } from '@memberjunction/lists-base';
+/**
+ * Friendly-named entry point for resolving an `AudienceSource` to a
+ * `ResolvedRecordSet`. Thin re-export over `ListOperations.ResolveSource`
+ * — semantically identical, but callers reading audience-related code
+ * don't need to know about the list-operations machinery underneath.
+ *
+ * Stateless on purpose; rebuild per call. Multi-provider safe: pass the
+ * provider through and the underlying `ListOperations` will scope to it.
+ */
+export declare class AudienceResolver {
+    private readonly contextUser;
+    private readonly provider;
+    constructor(contextUser: UserInfo, provider?: IMetadataProvider);
+    /**
+     * Resolve an `AudienceSource` to the record IDs it represents +
+     * the entity those IDs belong to. Never mutates.
+     */
+    Resolve(source: AudienceSource): Promise<ResolvedRecordSet>;
+}
+//# sourceMappingURL=AudienceResolver.d.ts.map

package/dist/AudienceResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudienceResolver.d.ts","sourceRoot":"","sources":["../src/AudienceResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIpF;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;gBAE7C,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB;IAK/D;;;OAGG;IACU,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAIzE"}

package/dist/AudienceResolver.js

@@ -0,0 +1,25 @@
+import { ListOperations } from './ListOperations.js';
+/**
+ * Friendly-named entry point for resolving an `AudienceSource` to a
+ * `ResolvedRecordSet`. Thin re-export over `ListOperations.ResolveSource`
+ * — semantically identical, but callers reading audience-related code
+ * don't need to know about the list-operations machinery underneath.
+ *
+ * Stateless on purpose; rebuild per call. Multi-provider safe: pass the
+ * provider through and the underlying `ListOperations` will scope to it.
+ */
+export class AudienceResolver {
+    constructor(contextUser, provider) {
+        this.contextUser = contextUser;
+        this.provider = provider;
+    }
+    /**
+     * Resolve an `AudienceSource` to the record IDs it represents +
+     * the entity those IDs belong to. Never mutates.
+     */
+    async Resolve(source) {
+        const ops = new ListOperations(this.contextUser, this.provider);
+        return ops.ResolveSource(source);
+    }
+}
+//# sourceMappingURL=AudienceResolver.js.map

package/dist/AudienceResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudienceResolver.js","sourceRoot":"","sources":["../src/AudienceResolver.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IAI3B,YAAY,WAAqB,EAAE,QAA4B;QAC7D,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,OAAO,CAAC,MAAsB;QACzC,MAAM,GAAG,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAChE,OAAO,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/ListOperations.d.ts

@@ -0,0 +1,215 @@
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { ApplyResult, ListDelta, ListRefreshMode, ListSource, MaterializeOptions, ResolvedRecordSet, SetOpKind } from '@memberjunction/lists-base';
+/** Target argument shared by `ComputeDelta` / `ComputeSetOp`.
+ *  Server-internal — not exposed on the public type surface because no
+ *  consumer outside this package needs to compose it. */
+export type DeltaTarget = ListSource | 'new';
+/**
+ * Core list-operations engine. Pure-ish TypeScript: takes a `UserInfo` +
+ * optional `IMetadataProvider` and talks to data exclusively through
+ * `Metadata` / `RunView` / `BaseEntity`. No GraphQL, no HTTP, no Angular.
+ *
+ * Public methods are PascalCase per MJ convention. Internal helpers are
+ * camelCase. Every mutating method delegates through `ComputeDelta` →
+ * `ApplyDelta` to enforce the drop-row warning contract.
+ */
+export declare class ListOperations {
+    private readonly contextUser;
+    private readonly provider;
+    constructor(contextUser: UserInfo, provider?: IMetadataProvider);
+    /**
+     * 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`).
+     */
+    ResolveSource(source: ListSource): Promise<ResolvedRecordSet>;
+    /**
+     * Return the current members of a list as record IDs. Convenience wrapper
+     * over `ResolveSource({ kind: 'list', listId })`.
+     */
+    GetListMembers(listId: string): Promise<ResolvedRecordSet>;
+    /**
+     * 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`).
+     */
+    ComputeDelta(target: DeltaTarget, source: ListSource, mode: ListRefreshMode): Promise<ListDelta>;
+    /**
+     * 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] …`.
+     */
+    ComputeSetOp(op: SetOpKind, inputs: ListSource[], target?: DeltaTarget): Promise<ListDelta>;
+    /**
+     * 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.
+     */
+    ApplyDelta(delta: ListDelta, opts: {
+        ConfirmDrops: boolean;
+        DeltaToken: string;
+    }): Promise<ApplyResult>;
+    /**
+     * 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.
+     */
+    MaterializeFromView(viewId: string, opts: MaterializeOptions): Promise<ApplyResult>;
+    /**
+     * 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.
+     */
+    RefreshFromSource(listId: string, mode: ListRefreshMode, opts: {
+        ConfirmDrops: boolean;
+    }): Promise<ApplyResult>;
+    /**
+     * 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.
+     */
+    AddViewResultsToList(viewId: string, listId: string): Promise<ApplyResult>;
+    private resolveListSource;
+    private resolveViewSource;
+    private resolveAdhocSource;
+    /**
+     * Resolve a list's entity name from its `EntityID` foreign key.
+     * Single-entity is intentional — multi-entity lists are not supported.
+     */
+    private resolveEntityNameFromList;
+    /**
+     * Serialize a primary-key tuple into the MJ List Detail `RecordID` format.
+     * Single-PK entities return the raw value; composite-PK entities use the
+     * canonical `Field1|Value1||Field2|Value2` concatenation matching
+     * `CompositeKey.ToConcatenatedString` defaults.
+     */
+    private serializeRecordId;
+    private buildDelta;
+    private buildWarnings;
+    /**
+     * Apply a set-op across N already-resolved sources. We accept the resolved
+     * sets (not raw `ListSource[]`) so callers can decide how to handle mixed
+     * entities before we collapse identities to strings.
+     */
+    private applySetOp;
+    private detectMixedEntities;
+    private assertEntitiesMatch;
+    private verifyTokenForDelta;
+    private verifyTargetNotDrifted;
+    /**
+     * Placeholder for the Phase 2 ResourcePermission check. Phase 0 ships a
+     * stub so the call site exists and the failure mode is reachable in
+     * tests, but it currently always passes — server bootstrap MUST wire in
+     * the real check before Phase 2 ships.
+     */
+    private checkEditorPermission;
+    /**
+     * Idempotent batch apply. We persist add/remove independently so a
+     * single bad record (e.g. constraint violation) doesn't abort the whole
+     * delta — we collect failures and surface a `PARTIAL_SUCCESS` result.
+     */
+    private applyDeltaMutations;
+    /**
+     * Locate and delete the `MJ: List Details` rows that map to the given
+     * record IDs. We scope the lookup to a single `ListID` so a bad RecordID
+     * value can't accidentally drop rows from other lists.
+     */
+    private removeDeltaRecords;
+    /**
+     * Pick the source for a refresh based on the list's lineage. Live mode
+     * just points back at the original view ID. Snapshot mode reads the
+     * captured filter blob and constructs an ad-hoc source against the
+     * list's entity using whichever WHERE clause the view had at
+     * materialization time.
+     */
+    private resolveRefreshSource;
+    /**
+     * Parse the captured `SourceFilterSnapshot` and turn it into an ad-hoc
+     * `ListSource`. We prefer `customWhereClause` over `whereClause` because
+     * the custom form is the user-authored override; smart-filter clauses
+     * fall in last because they're AI-derived. Returns null if no usable
+     * clause is present (in which case the caller surfaces a clear error).
+     */
+    private buildAdhocSourceFromSnapshot;
+    /**
+     * Bump `LastRefreshedAt` + `LastRefreshedByUserID` after a successful
+     * refresh. Best-effort — a failure here doesn't roll back the apply
+     * (the records are already in the right state), but we do log it so
+     * the discrepancy is observable.
+     */
+    private stampRefreshMetadata;
+    private failure;
+    /**
+     * Load the User View and serialize its filter state into a JSON blob.
+     * We only capture the fields that actually drive the result set — grid
+     * layout, sort, and smart-filter explanation are layout/explanation
+     * metadata, not part of the filter contract, so they're omitted. The
+     * snapshot is versioned (`v: 1`) so future schema evolutions can
+     * branch on shape without breaking older snapshots.
+     */
+    private captureViewFilterSnapshot;
+    /**
+     * Create + save the parent `MJ: List` record. Lineage fields are only
+     * populated when `RememberLineage = true` on `opts` — otherwise the new
+     * list is a plain one-shot copy with no upstream reference.
+     */
+    private createListWithLineage;
+    /**
+     * Bulk-insert `MJ: List Details` rows for the given record IDs. We
+     * surface a per-record error rather than aborting the whole batch so
+     * the caller can show partial-success counts.
+     */
+    private insertListMembers;
+    private metadata;
+    private runView;
+}
+//# sourceMappingURL=ListOperations.d.ts.map

package/dist/ListOperations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListOperations.d.ts","sourceRoot":"","sources":["../src/ListOperations.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,iBAAiB,EAKjB,QAAQ,EACT,MAAM,sBAAsB,CAAC;AAS9B,OAAO,KAAK,EACV,WAAW,EAIX,SAAS,EAGT,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,EACV,MAAM,4BAA4B,CAAC;AAEpC;;yDAEyD;AACzD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC;AAE7C;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;gBAE7C,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB;IAK/D;;;;;;;;OAQG;IACU,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAiB1E;;;OAGG;IACU,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIvE;;;;;;;;;;OAUG;IACU,YAAY,CACvB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,SAAS,CAAC;IA4CrB;;;;;;;;OAQG;IACU,YAAY,CACvB,EAAE,EAAE,SAAS,EACb,MAAM,EAAE,UAAU,EAAE,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,SAAS,CAAC;IA0DrB;;;;;;;;;;;;;;OAcG;IACU,UAAU,CACrB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE;QAAE,YAAY,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAClD,OAAO,CAAC,WAAW,CAAC;IA6BvB;;;;;;;;;;;;;;;;;OAiBG;IACU,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IA0ChG;;;;;;;;;;;;;OAaG;IACU,iBAAiB,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE;QAAE,YAAY,EAAE,OAAO,CAAA;KAAE,GAC9B,OAAO,CAAC,WAAW,CAAC;IAoBvB;;;;;;;OAOG;IACU,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;YAWzE,iBAAiB;YA6BjB,iBAAiB;YAsCjB,kBAAkB;IA0BhC;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAWjC;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;YAaX,UAAU;IAwCxB,OAAO,CAAC,aAAa;IAmCrB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IA0BlB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,mBAAmB;YAQb,mBAAmB;YAoCnB,sBAAsB;IAwBpC;;;;;OAKG;YACW,qBAAqB;IAOnC;;;;OAIG;YACW,mBAAmB;IAkDjC;;;;OAIG;YACW,kBAAkB;IA0BhC;;;;;;OAMG;YACW,oBAAoB;IAqClC;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IA0BpC;;;;;OAKG;YACW,oBAAoB;IAkBlC,OAAO,CAAC,OAAO;IAIf;;;;;;;OAOG;YACW,yBAAyB;IAwBvC;;;;OAIG;YACW,qBAAqB;IA+BnC;;;;OAIG;YACW,iBAAiB;IA4B/B,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,OAAO;CAGhB"}