@aiaiai-pt/design-system 0.33.0 → 0.35.0

package/components/renderer/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Block / binding model for the portal rendering engine (#73, spec §5).
+ *
+ * A page is an ordered list of **blocks**; each block is a declarative
+ * *pointer*, never baked data. The block names a widget intent (`type`,
+ * authoring hint) and a `binding` describing WHAT to render (a list of entity
+ * Z, the detail of row Y, an action form, …). Data is fetched at render time
+ * by `resolveData(block)` (see `./resolve-data.ts`) and handed to the widget
+ * the dispatcher selects (see `./dispatch.ts`). Keeping only the pointer is
+ * what makes this a template, not a page.
+ *
+ * The ontology `portal_page` rows that emit these descriptors land in #79;
+ * here the descriptors are SEEDED (same staged pattern #70/#72 used).
+ */
+/** The bounded, governed widget kinds (spec §5 catalog). */
+export type WidgetKind = "list" | "detail" | "form" | "map" | "calendar" | "kpi" | "content" | "vote" | "status" | "forms" | "hero" | "lookup" | "feed" | "filters" | "actions" | "aggregate" | "subscriptions" | "consent" | "deliveries" | "owned-list" | "feature-grid" | "cta" | "media-text" | "steps" | "testimonial" | "faq" | "logo-strip" | "media-gallery";
+/** The feed sub-views a `feed`/`filters` binding may toggle/scope (#308). */
+export type FeedView = "list" | "map";
+/** Declarative pointer — "I render <kind> of <entity|action>, scoped by filter". */
+export interface Binding {
+    kind: WidgetKind;
+    /** Ontology entity type (list/detail/vote). */
+    entity?: string | null;
+    /** Ontology action type (form). */
+    action?: string | null;
+    /**
+     * Render-time selector / scope. For the single-resource kinds
+     * (detail/status/content) this is the captured route segment (id/ref/key).
+     * For list/map/calendar it is the (future) scope expression. Real
+     * `{{tenant.scope}}` expression evaluation lands with the ontology
+     * descriptors (#79); today it is a literal.
+     */
+    filter?: string | null;
+    /**
+     * `list` only (#75 M5): page-size cap + ordering, forwarded as
+     * `?limit=` / `?order_by=` (the BFF shape-sanitises order terms and drops
+     * anything malformed). The landing's recent-feed sets `limit: 6,
+     * order: "-created_at"`.
+     */
+    limit?: number | null;
+    order?: string | null;
+    /**
+     * `detail` only (#75 M5 slice 3): child collections to embed, forwarded as
+     * `?expand=` (the BFF resolves each through its own disclosure policy row
+     * — an undisclosed child is silently absent). Each aside block requests
+     * only what it renders (gallery → ["images"]).
+     */
+    expand?: string[] | null;
+}
+/**
+ * Fail-closed blast radius (§14.8). A `structural` slot must NOT silently
+ * vanish on misconfig (it surfaces a visible error); an `optional` widget
+ * fails soft to empty. The page template (#74) sets this from the slot
+ * definition; until then a block declares its own, defaulting to `optional`.
+ */
+export type BlockImportance = "optional" | "structural";
+/** Per-block structural lock override (#74 §2.1, Gutenberg per-block lock). */
+export interface BlockLock {
+    move?: boolean;
+    remove?: boolean;
+}
+export interface Block {
+    /**
+     * Operator-authored widget hint. UNTRUSTED — it is NEVER interpolated into
+     * the DOM (TH-08). The dispatcher resolves a known-good registry `key` from
+     * the `binding` (+ a tester that MAY rank on this `type`); that literal is the
+     * only widget identifier that reaches `class`/`data-*`.
+     */
+    type: string;
+    /** Placement into the page-template slot (#74). */
+    slot: string;
+    /**
+     * Stable identifier within the slot (#74 §2.2). The override-map key — a
+     * `portal_page` (#79) addresses this block by `slot.name → block.name`.
+     * Stamped from the template's default-block `name`.
+     */
+    name?: string;
+    binding: Binding;
+    props?: Record<string, unknown>;
+    importance?: BlockImportance;
+    /**
+     * Single-H1 ownership (ARTE #2). Stamped from the owning slot — the widget
+     * renders the page's only `<h1>` here; every other heading is `<h2>`+.
+     */
+    ownsH1?: boolean;
+    /** Reserved error-summary slot (ARTE #5). Stamped from the slot. */
+    errorSummary?: boolean;
+    /** Per-block structural lock override (#74 §2.1). */
+    lock?: BlockLock;
+    /**
+     * Full-bleed band (#105 Phase 7 composition). A `bleed` block is an
+     * edge-to-edge, self-padding coloured band (a Hero / accent CallToAction). It
+     * keeps the template's vertical RHYTHM gap to/from a CONTENT band; the gap
+     * only collapses BETWEEN two adjacent bleed bands, so consecutive colour
+     * fields butt instead of leaving an awkward sliver. A template-author concern
+     * (set on the default block), not tenant content.
+     */
+    bleed?: boolean;
+}
+export interface PageDescriptor {
+    blocks: Block[];
+}
+/**
+ * Minimal ontology schema shape a tester / widget may consult. Widened in 73d
+ * when EntityList/DetailView read fields from the schema (no hardcoded
+ * entity-type unions — §14.6).
+ */
+export interface OntologySchema {
+    entity: string;
+    fields: Array<{
+        key: string;
+        type?: string;
+        [extra: string]: unknown;
+    }>;
+    [extra: string]: unknown;
+}
+/**
+ * The uniform prop contract every catalog widget receives. `resolveData`
+ * produces `{ data, schema, actionDef }`; the page passes the block's `props`
+ * through verbatim (operator config — columns, labels, …). This single shape
+ * is what lets one dispatcher mount any widget, and what each DS-backed widget
+ * wrapper adapts to its component's props.
+ */
+export interface WidgetProps {
+    data: unknown;
+    schema: OntologySchema | null;
+    actionDef: unknown | null;
+    props: Record<string, unknown>;
+    /**
+     * The vertical app segment (`occurrences`, …), threaded from the loader so a
+     * widget that POSTs back to the public surface (ActionForm → /{app}/public/
+     * submit, 73f) can build its path. Optional — read-only widgets ignore it.
+     */
+    app?: string;
+    /**
+     * Single-H1 ownership (ARTE #2), stamped from the owning slot via the
+     * block. A heading-rendering widget emits the page's `<h1>` only when this
+     * is true — otherwise `<h2>` — so composed pages (landing: hero + recent
+     * list) keep exactly one H1. Hardcoded routes that mount a widget
+     * standalone (my-reports) pass it explicitly.
+     */
+    ownsH1?: boolean;
+    /**
+     * The request's resolved locale (prefs cookie → portal default) — drives
+     * value FORMATTING only (dates). Copy localisation happens upstream
+     * (wuchale for code strings, $loc for page-row props).
+     */
+    locale?: string;
+    /**
+     * BFF path the block's data came from (#75 M5 slice 4) — paging widgets
+     * re-fetch it client-side with `?after={next_cursor}` through the same
+     * /bff proxy (graduated principal rides along for free).
+     */
+    dataPath?: string;
+    /**
+     * The request "now" as an ISO string, stamped once by the route loader
+     * (`new Date()`) — the SAME clock that feeds `resolveData` (calendar window).
+     * Threaded so time-relative widgets (PhaseTimeline open/closed/upcoming) are
+     * computed SSR-side and hydrate stable, instead of reading the browser clock
+     * (which would drift from SSR and corrupt hydration). Generic, not
+     * vertical-specific.
+     */
+    now?: string;
+}

package/components/renderer/types.ts

@@ -0,0 +1,250 @@
+/**
+ * Block / binding model for the portal rendering engine (#73, spec §5).
+ *
+ * A page is an ordered list of **blocks**; each block is a declarative
+ * *pointer*, never baked data. The block names a widget intent (`type`,
+ * authoring hint) and a `binding` describing WHAT to render (a list of entity
+ * Z, the detail of row Y, an action form, …). Data is fetched at render time
+ * by `resolveData(block)` (see `./resolve-data.ts`) and handed to the widget
+ * the dispatcher selects (see `./dispatch.ts`). Keeping only the pointer is
+ * what makes this a template, not a page.
+ *
+ * The ontology `portal_page` rows that emit these descriptors land in #79;
+ * here the descriptors are SEEDED (same staged pattern #70/#72 used).
+ */
+
+/** The bounded, governed widget kinds (spec §5 catalog). */
+export type WidgetKind =
+  | "list"
+  | "detail"
+  | "form"
+  | "map"
+  | "calendar"
+  | "kpi"
+  | "content"
+  | "vote"
+  | "status"
+  | "forms"
+  | "hero"
+  | "lookup"
+  // #105 Phase 1 (#308). A `feed` block pairs EntityList + MapView over one
+  // entity feed and toggles between them via the URL (`?view=`); resolveData
+  // resolves the ACTIVE view's underlying feed. A `filters` block renders the
+  // declared facets of a feed and writes the active filter state to the URL —
+  // the feed re-resolves server-side, so list + map share one filter channel.
+  | "feed"
+  | "filters"
+  // #105 Phase 2 (#313). An `actions` block resolves a detail row's CITIZEN
+  // ACTION availability — `/{app}/public/{entity}/{id}/actions` projects, per
+  // citizen-write placement, whether the action is OPEN on this row (the same
+  // `gate` criteria the submit enforces). SSR-resolved (no client fetch); the
+  // ActionPanel widget joins it with the operator's declared CTAs to render
+  // open links vs disabled+reason. Distinct from `detail` because it consumes
+  // the availability projection, not the row.
+  | "actions"
+  // #105 Phase 4. An `aggregate` block reads the ROWS of a public aggregate
+  // VIEW (`/{app}/public/{view}`, the #250 M3 public-view lane: self-gated by
+  // `group_by tenant_id`, no entity ACL) as PRIMARY data — distinct from a
+  // `filters` block reading a view as facet *options*. RankingBoard /
+  // ResultsChart consume the `{label, value}` projection of the rows. The view
+  // carries no per-type schema, so this never resolves a `/public/schema` path.
+  | "aggregate"
+  // #105 Phase 5. A `subscriptions` block reads the signed-in citizen's OWN
+  // notification subscriptions through the AUTHED account proxy
+  // (`/me/notifications/subscriptions`, require_auth + OWN-scoped) — NOT the
+  // public `/bff` surface. NotificationPrefs renders them as a toggle list and
+  // mutates them (POST/PATCH) through the same proxy. The first MUTATING widget
+  // kind: it carries no schema and its data path is the account lane, so
+  // resolveData handles it in a dedicated branch (never hits `bffPathForBinding`).
+  | "subscriptions"
+  // #105 Phase 5 slice 2. A `consent` block reads the signed-in citizen's OWN
+  // RGPD state through the AUTHED account proxy (`/me/consent`, require_auth +
+  // OWN-scoped): the tenant's active consent purposes joined with the caller's
+  // consent records. ConsentManager renders the toggle list and acts on it —
+  // GRANT reuses the public submit lane (the existing `grant_consent` action),
+  // REVOKE/ERASE/EXPORT ride the same `/me/consent` proxy. Like `subscriptions`
+  // it carries no schema; resolveData handles it in a dedicated branch.
+  | "consent"
+  // #252 Anexo 110 — a `deliveries` block reads the signed-in citizen's OWN
+  // notification HISTORY through the AUTHED account proxy
+  // (`/me/notifications/deliveries`, require_auth + OWN-scoped → recipient_user_id
+  // = caller sub): the `notification_delivery` ledger rows written AFTER each
+  // dispatch. Read-only (the citizen consults their history; nothing to mutate).
+  // Like `subscriptions`/`consent` it carries no schema; resolveData handles it
+  // in a dedicated branch.
+  | "deliveries"
+  // #105 — an `owned-list` block reads the signed-in citizen's OWN rows of an
+  // entity through the AUTHED account proxy (`/me/owned/{entity}`, require_auth +
+  // OWN-scoped). Unlike the my-reports public-list filter (which only works when
+  // the owner field STORES the sub), this handles a USER-ENTITY-REL owner
+  // (proposal.proponent) by resolving the caller's identity server-side. Reuses
+  // EntityListWidget (the data is `{items}` like a list); resolveData fetches the
+  // OWN lane + the public schema (for columns) in a dedicated branch. Auth-gated.
+  | "owned-list"
+  // #105 Phase 7 — the landing/content surface: presentational, marketing-grade
+  // section widgets that render PURELY from their block props (copy + media are
+  // tenant DATA). They have NO data path — resolveData short-circuits them all
+  // through the shared PRESENTATIONAL_KINDS branch (like `hero`/`lookup`), so a
+  // misconfigured one renders nothing rather than fetching. Each is its own
+  // kind (the `hero` precedent) so the registry dispatches the right widget;
+  // they drop into any vertical because they carry no entity/schema coupling.
+  | "feature-grid"
+  | "cta"
+  | "media-text"
+  | "steps"
+  | "testimonial"
+  | "faq"
+  | "logo-strip"
+  | "media-gallery";
+
+/** The feed sub-views a `feed`/`filters` binding may toggle/scope (#308). */
+export type FeedView = "list" | "map";
+
+/** Declarative pointer — "I render <kind> of <entity|action>, scoped by filter". */
+export interface Binding {
+  kind: WidgetKind;
+  /** Ontology entity type (list/detail/vote). */
+  entity?: string | null;
+  /** Ontology action type (form). */
+  action?: string | null;
+  /**
+   * Render-time selector / scope. For the single-resource kinds
+   * (detail/status/content) this is the captured route segment (id/ref/key).
+   * For list/map/calendar it is the (future) scope expression. Real
+   * `{{tenant.scope}}` expression evaluation lands with the ontology
+   * descriptors (#79); today it is a literal.
+   */
+  filter?: string | null;
+  /**
+   * `list` only (#75 M5): page-size cap + ordering, forwarded as
+   * `?limit=` / `?order_by=` (the BFF shape-sanitises order terms and drops
+   * anything malformed). The landing's recent-feed sets `limit: 6,
+   * order: "-created_at"`.
+   */
+  limit?: number | null;
+  order?: string | null;
+  /**
+   * `detail` only (#75 M5 slice 3): child collections to embed, forwarded as
+   * `?expand=` (the BFF resolves each through its own disclosure policy row
+   * — an undisclosed child is silently absent). Each aside block requests
+   * only what it renders (gallery → ["images"]).
+   */
+  expand?: string[] | null;
+}
+
+/**
+ * Fail-closed blast radius (§14.8). A `structural` slot must NOT silently
+ * vanish on misconfig (it surfaces a visible error); an `optional` widget
+ * fails soft to empty. The page template (#74) sets this from the slot
+ * definition; until then a block declares its own, defaulting to `optional`.
+ */
+export type BlockImportance = "optional" | "structural";
+
+/** Per-block structural lock override (#74 §2.1, Gutenberg per-block lock). */
+export interface BlockLock {
+  move?: boolean;
+  remove?: boolean;
+}
+
+export interface Block {
+  /**
+   * Operator-authored widget hint. UNTRUSTED — it is NEVER interpolated into
+   * the DOM (TH-08). The dispatcher resolves a known-good registry `key` from
+   * the `binding` (+ a tester that MAY rank on this `type`); that literal is the
+   * only widget identifier that reaches `class`/`data-*`.
+   */
+  type: string;
+  /** Placement into the page-template slot (#74). */
+  slot: string;
+  /**
+   * Stable identifier within the slot (#74 §2.2). The override-map key — a
+   * `portal_page` (#79) addresses this block by `slot.name → block.name`.
+   * Stamped from the template's default-block `name`.
+   */
+  name?: string;
+  binding: Binding;
+  props?: Record<string, unknown>;
+  importance?: BlockImportance;
+  /**
+   * Single-H1 ownership (ARTE #2). Stamped from the owning slot — the widget
+   * renders the page's only `<h1>` here; every other heading is `<h2>`+.
+   */
+  ownsH1?: boolean;
+  /** Reserved error-summary slot (ARTE #5). Stamped from the slot. */
+  errorSummary?: boolean;
+  /** Per-block structural lock override (#74 §2.1). */
+  lock?: BlockLock;
+  /**
+   * Full-bleed band (#105 Phase 7 composition). A `bleed` block is an
+   * edge-to-edge, self-padding coloured band (a Hero / accent CallToAction). It
+   * keeps the template's vertical RHYTHM gap to/from a CONTENT band; the gap
+   * only collapses BETWEEN two adjacent bleed bands, so consecutive colour
+   * fields butt instead of leaving an awkward sliver. A template-author concern
+   * (set on the default block), not tenant content.
+   */
+  bleed?: boolean;
+}
+
+export interface PageDescriptor {
+  blocks: Block[];
+}
+
+/**
+ * Minimal ontology schema shape a tester / widget may consult. Widened in 73d
+ * when EntityList/DetailView read fields from the schema (no hardcoded
+ * entity-type unions — §14.6).
+ */
+export interface OntologySchema {
+  entity: string;
+  fields: Array<{ key: string; type?: string; [extra: string]: unknown }>;
+  [extra: string]: unknown;
+}
+
+/**
+ * The uniform prop contract every catalog widget receives. `resolveData`
+ * produces `{ data, schema, actionDef }`; the page passes the block's `props`
+ * through verbatim (operator config — columns, labels, …). This single shape
+ * is what lets one dispatcher mount any widget, and what each DS-backed widget
+ * wrapper adapts to its component's props.
+ */
+export interface WidgetProps {
+  data: unknown;
+  schema: OntologySchema | null;
+  actionDef: unknown | null;
+  props: Record<string, unknown>;
+  /**
+   * The vertical app segment (`occurrences`, …), threaded from the loader so a
+   * widget that POSTs back to the public surface (ActionForm → /{app}/public/
+   * submit, 73f) can build its path. Optional — read-only widgets ignore it.
+   */
+  app?: string;
+  /**
+   * Single-H1 ownership (ARTE #2), stamped from the owning slot via the
+   * block. A heading-rendering widget emits the page's `<h1>` only when this
+   * is true — otherwise `<h2>` — so composed pages (landing: hero + recent
+   * list) keep exactly one H1. Hardcoded routes that mount a widget
+   * standalone (my-reports) pass it explicitly.
+   */
+  ownsH1?: boolean;
+  /**
+   * The request's resolved locale (prefs cookie → portal default) — drives
+   * value FORMATTING only (dates). Copy localisation happens upstream
+   * (wuchale for code strings, $loc for page-row props).
+   */
+  locale?: string;
+  /**
+   * BFF path the block's data came from (#75 M5 slice 4) — paging widgets
+   * re-fetch it client-side with `?after={next_cursor}` through the same
+   * /bff proxy (graduated principal rides along for free).
+   */
+  dataPath?: string;
+  /**
+   * The request "now" as an ISO string, stamped once by the route loader
+   * (`new Date()`) — the SAME clock that feeds `resolveData` (calendar window).
+   * Threaded so time-relative widgets (PhaseTimeline open/closed/upcoming) are
+   * computed SSR-side and hydrate stable, instead of reading the browser clock
+   * (which would drift from SSR and corrupt hydration). Generic, not
+   * vertical-specific.
+   */
+  now?: string;
+}

package/components/renderer/vote.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Voting-ballot helpers (#105) — pure read-path builders + ballot mapping + the
+ * public-submit cast, kept OUT of the `.svelte` widget so (a) the HTTP verbs and
+ * header literals aren't mangled by Wuchale's `.svelte` string extraction, and
+ * (b) the shaping/cast is unit-testable without mounting a component.
+ *
+ * The ballot COMPOSES two existing PUBLIC reads (no new backend): the edition
+ * row — its `current_phase` decides open/closed — and the votable-entity list
+ * (the finalists, as radio options). The cast reuses the citizen public-submit
+ * lane (the vote action's placement) — the SAME auth-optional `/bff` surface
+ * `submit_proposal` uses, so the signed-in citizen's Bearer rides along and the
+ * server stamps the one-vote pseudonym (anonymous is refused server-side).
+ *
+ * Vertical-agnostic: every entity / field / status / phase literal is block
+ * DATA (the civic page supplies proposal / proposal_edition / in_voting /
+ * voting / title), so the widget drops into any vertical with a vote action.
+ */
+/** Path-only read fetch (the resolve-data read shape). */
+export type ReadFetch = (path: string) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+/** Write fetch for the cast POST (the browser `fetch` fits). */
+export type WriteFetch = (path: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+export interface VoteOption {
+    id: string;
+    label: string;
+}
+/** The resolved ballot a `vote` block hands the widget. */
+export interface Ballot {
+    options: VoteOption[];
+    /** Voting is NOT open on this edition (current_phase ≠ the open phase). */
+    closed: boolean;
+    /** The edition id the cast writes back (carried so the widget needn't re-derive). */
+    edition: string;
+}
+/**
+ * How to SOURCE the ballot from the public surface — all DATA (the votable
+ * entity type comes from the binding; the rest from props), so no civic literal
+ * lives in code. Generic facet/field names default to the platform conventions.
+ */
+export interface VoteReadConfig {
+    /** Votable entity type (binding.entity), e.g. `proposal`. */
+    entity: string;
+    /** Edition entity type, e.g. `proposal_edition`. */
+    editionEntity: string;
+    /** Status value marking a votable option, e.g. `in_voting`. */
+    optionStatus: string;
+    /** Facet param carrying the status filter (default `status`). */
+    statusFacet: string;
+    /** Facet param carrying the edition id (default `edition.id`). */
+    editionFacet: string;
+    /** Option label field on the entity row (default `title`). */
+    labelField: string;
+    /** Edition phase field (default `current_phase`). */
+    phaseField: string;
+    /** Phase value that means voting is OPEN, e.g. `voting`. */
+    openPhase: string;
+    /** Max options to fetch (default 50). */
+    limit: number;
+}
+/** Where the cast POSTs — the placement + the vote entity's field names. DATA. */
+export interface VoteCastConfig {
+    app: string;
+    /** Citizen public-submit placement key, e.g. `civic-cast-vote`. */
+    placementKey: string;
+    /** Envelope key = the created entity type, e.g. `proposal_vote`. */
+    voteModel: string;
+    /** Field on the vote entity pointing at the chosen option, e.g. `proposal`. */
+    voteField: string;
+    /** Field on the vote entity pointing at the edition, e.g. `edition`. */
+    editionField: string;
+}
+/**
+ * Build the read config from the block (entity on the binding, the rest in
+ * props). Returns null when a REQUIRED knob is missing — resolveData then fails
+ * the block closed rather than fetch a half-configured ballot.
+ */
+export declare function voteReadConfig(entity: string | null | undefined, props: Record<string, unknown> | undefined): VoteReadConfig | null;
+/** Build the cast config from props + the widget's app. Null if misconfigured. */
+export declare function voteCastConfig(app: string | undefined, props: Record<string, unknown> | undefined): VoteCastConfig | null;
+/** The edition read — its `current_phase` decides open/closed. */
+export declare function editionReadPath(app: string, cfg: VoteReadConfig, editionId: string): string;
+/** The votable-options read — the finalists for this edition, by status facet. */
+export declare function optionsReadPath(app: string, cfg: VoteReadConfig, editionId: string): string;
+/** Map the votable-entity list into ballot options (id + a non-empty label). */
+export declare function toOptions(proposalsBody: unknown, cfg: VoteReadConfig): VoteOption[];
+/** Voting is closed unless the edition's phase equals the configured open phase
+ *  (an absent/null phase reads as CLOSED — fail-closed, matching the gate). */
+export declare function isClosed(editionRow: unknown, cfg: VoteReadConfig): boolean;
+/** The cast body: `{ <voteModel>: { <voteField>: choice, <editionField>: edition } }`. */
+export declare function castBody(cfg: VoteCastConfig, choiceId: string, editionId: string): Record<string, unknown>;
+export type CastOutcome = {
+    kind: "ok";
+}
+/** One-vote-per-edition already used (409) — a settled state, not an error. */
+ | {
+    kind: "conflict";
+}
+/** Identity missing/insufficient (401/403) — the cast needs a signed-in citizen. */
+ | {
+    kind: "auth";
+} | {
+    kind: "error";
+    status: number;
+};
+/**
+ * Cast the vote through the citizen public-submit lane. The signed-in citizen's
+ * Bearer is forwarded by the same-origin `/bff` proxy, so the server stamps the
+ * pseudonym and enforces the one-vote constraint. Maps the response to a settled
+ * outcome the widget renders (never throws on a non-OK — a 409 is expected).
+ */
+export declare function castVote(fetchImpl: WriteFetch, cfg: VoteCastConfig, choiceId: string, editionId: string): Promise<CastOutcome>;