Interface RosterAccountStoreOptions<TRosterEntry, TCtxMeta>

Point-lookup against the adopter's roster source. Return the entry for a given account_id, or undefined when no row matches.

Called once per resolve() with an account_id-shaped reference. Wire shape { brand, operator } and missing refs do NOT call lookup; see the resolve behavior below.

Throw to signal a transient upstream failure (DB outage, network blip). The framework projects to SERVICE_UNAVAILABLE. Returning undefined is the canonical not-found path and projects to ACCOUNT_NOT_FOUND.

Convert a roster entry to the framework's Account<TCtxMeta> shape.

The adopter's roster row typically lacks ctx_metadata (which is a framework-internal field). This mapper is where the adopter populates it — upstream IDs, per-account caches, anything specialism methods will read off ctx.account.ctx_metadata later.

DO NOT put credentials in ctx_metadata. See docs/guides/CTX-METADATA-SAFETY.md for the rationale and the recommended re-derive-per-request pattern (read tokens off ctx.authInfo instead).

Adopters MAY omit authInfo from the returned Account — the framework auto-attaches the principal from ctx.authInfo when absent.

Optional list_accounts implementation. The adopter receives the wire filter + cursor request and returns a page of roster entries; the helper threads each entry through toAccount before returning.

Omit to leave list_accounts unimplemented (framework returns UNSUPPORTED_FEATURE).

Push filter + pagination down. The naive shape — fetch the full roster, filter+slice in memory — works for tens of accounts per tenant but does not scale. Adopters with a Postgres-backed roster should map filter.brand_domain / filter.operator / filter.status[] / cursor / limit to a SQL query. The helper does NOT post-filter; the adopter is the source of truth.

No default status filter. filter.status is undefined unless the buyer passed it. If you want production callers to see only active + pending_approval by default, apply that fallback inside your query — the helper passes filter through verbatim.

Handle ref-less accounts.resolve(undefined, ctx) calls — invoked by list_creative_formats, provide_performance_feedback, preview_creative, and any discovery-phase tool that does not require a buyer-selected account.

Return a synthetic publisher-wide roster entry; toAccount is applied to it before the result is returned to the framework. Return undefined to fall back to null (same as omitting this option — ctx.account is undefined in the handler).

The ref parameter is always undefined here — it is present for signature parity with the framework's resolve(ref, ctx) shape so code-generation tools produce consistent two-arg handler signatures. Ignore it (use (_ref, ctx) => ...).

Throw to signal a transient upstream failure (DB outage, network blip). The framework projects to SERVICE_UNAVAILABLE. Returning undefined is the canonical not-found path and returns null to the framework.

Brand+operator refs are not routed here. A { brand, operator } ref without an account_id still falls through to null. Adopters who need to handle brand-arm refs must override resolve on the returned store via a spread.

toAccount is called on your return value with the same ctx, identical to the lookup path. Ensure your synthesized entry satisfies all required fields of TRosterEntry.

Auth-derived lookup. If your singleton should be derived from ctx.authInfo (e.g. a per-tenant publisher account keyed on the OAuth client), and that derivation needs to re-invoke lookup, use the spread-override pattern on the returned store instead — a resolveWithoutRef that calls back into lookup is more naturally expressed as a resolve override so the call graph stays flat.

If you also override resolve on the spread, resolveWithoutRef is not called — the spread override takes precedence.

Omit when ctx.account === undefined is acceptable for ref-less tools (handlers can narrow on it and fall back to platform-level config from their closure).