aggregate_api 1.0.0__py3-none-any.whl

aggregate_api/completion.py

@@ -0,0 +1,219 @@
+"""DecL completion + lex helpers for the editor pane.
+
+Two endpoints feed off this module:
+
+* ``POST /v1/decl/complete`` -- given DecL text and a cursor
+  position, return the set of terminals that could legally appear
+  next (keyword completions for the SPA's CodeMirror integration).
+* ``POST /v1/decl/lex`` -- given DecL text, return the token stream
+  produced by Lark's lexer (used by syntax-highlighting UIs that
+  prefer server-side tokenization).
+
+Both go through Lark's :meth:`Lark.parse_interactive` API, which
+returns an :class:`~lark.parsers.lalr_interactive_parser.InteractiveParser`
+that exposes the live parse state. ``.accepts()`` returns the set
+of terminal names that would succeed at the current position --
+that's the completion menu.
+
+V1 ships keyword/terminal completions only. Knowledge-base
+identifier completions (severity names, calibrated distortions)
+are flagged in the plan as a v1.1 enhancement.
+"""
+
+from __future__ import annotations
+
+import re
+
+from lark.exceptions import UnexpectedInput
+
+# Reuse the parser instance already constructed by ``parser.py`` so
+# we don't duplicate the (somewhat expensive) Lark.open() call.
+# (Currently only used by the lex endpoint -- see notes on
+# ``complete`` for why interactive parsing isn't available.)
+from aggregate.parser import _PARSER
+
+# Reuse the curated terminal -> label table from Plan B so suggestion
+# labels are consistent with parse-error displays.
+from aggregate.parser_errors import _TERMINAL_LABELS
+
+
+# ----------------------------------------------------------------------
+# Completion classification
+# ----------------------------------------------------------------------
+# Terminals that represent generic value categories rather than fixed
+# strings. Used to tag a Completion's ``kind`` so the editor can render
+# (e.g.) keyword pills differently from "expects a number" hints.
+_LITERAL_TERMINALS = {
+    "NUMBER", "SIGNED_NUMBER", "INT", "SIGNED_INT", "FLOAT",
+    "STRING", "ESCAPED_STRING",
+}
+_IDENTIFIER_TERMINALS = {"NAME", "CNAME", "ID"}
+
+
+def _classify(terminal: str) -> str:
+    """Map a terminal name to ``'keyword' | 'identifier' | 'literal'``.
+
+    Anything not in the explicit identifier/literal sets is treated
+    as a keyword (it's either a curated DecL keyword from
+    ``decl.lark`` or an anonymous terminal -- the editor renders
+    both as "keyword" tokens).
+    """
+    if terminal in _LITERAL_TERMINALS:
+        return "literal"
+    if terminal in _IDENTIFIER_TERMINALS:
+        return "identifier"
+    return "keyword"
+
+
+#: A curated label that **starts with a quoted token**, and whatever follows it.
+#: The three shapes in the table, in the order they matter here:
+#:
+#: * ``"'agg'"``, a bare token;
+#: * ``"'approximate' (or 'approx')"``, a token and a parenthesized gloss;
+#: * ``"'**' or '^'"``, a token and an unparenthesized alternative.
+#:
+#: A fourth shape has no quoted token at all and is a **description** rather
+#: than a literal: ``"a builtin aggregate (agg.X)"``, ``"a frequency name
+#: (poisson, binomial, ...)"``. Those name a category the static pool cannot
+#: enumerate, so there is nothing to insert and :func:`complete` drops them.
+_LABEL_TOKEN = re.compile(r"^'(?P<token>[^']*)'\s*(?P<rest>.*)$")
+
+
+def _split_label(terminal: str) -> tuple[str, str | None]:
+    """Split a curated label into the token to insert and its gloss.
+
+    Parameters
+    ----------
+    terminal : str
+        Lark terminal name.
+
+    Returns
+    -------
+    (str, str or None)
+        The bare token, and the gloss with any wrapping parentheses removed.
+        The token is ``''`` when there is nothing insertable, which is an
+        anonymous terminal (``__ANON_*``) or a descriptive label; callers drop
+        those rather than offering a phrase as if it were DecL.
+
+    Notes
+    -----
+    This used to be ``_TERMINAL_LABELS[terminal].strip("'")``, and ``strip``
+    cannot do the job: it removes matching characters from the **ends** of a
+    string, so a label ending in ``)`` kept its interior quote and
+    ``'after' (profit-commission allowance)`` came back as
+    ``after' (profit-commission allowance)``. That string was then handed to
+    editors as the text to insert, so accepting the completion put a stray
+    apostrophe and a parenthetical into the program. It reads as a formatting
+    slip and it was a correctness one.
+
+    Where a label offers alternatives (``'**' or '^'``) the **first** is the
+    token and the rest becomes the gloss: both spellings parse, so either is a
+    defensible insertion, and the one the label leads with is the house form.
+    """
+    if terminal.startswith("__"):
+        return "", None
+    raw = _TERMINAL_LABELS.get(terminal)
+    if raw is None:
+        return terminal.lower(), None
+    m = _LABEL_TOKEN.match(raw.strip())
+    if m is None:
+        return "", None          # a description, not a token
+    rest = m.group("rest").strip()
+    if rest.startswith("(") and rest.endswith(")"):
+        rest = rest[1:-1].strip()
+    return m.group("token"), rest or None
+
+
+# Lark's ``parse_interactive`` is LALR-only; DecL uses Earley + dynamic
+# lexer, so we can't ask the live parser "what accepts next?". V1 ships
+# a static keyword set sourced from Plan B's terminal-label table --
+# good enough for the SPA's "show me available keywords" dropdown but
+# not context-aware. Grammar-driven completions are flagged in the plan
+# as a v1.1 enhancement (would require building a parallel LALR
+# grammar or stepping through token-by-token).
+_STATIC_KEYWORDS = sorted(
+    {
+        t for t in _TERMINAL_LABELS
+        if t.isupper() and t.isascii() and not t.startswith("__")
+    }
+)
+
+
+def complete(decl: str, cursor: int) -> list[dict]:
+    """Return completion candidates for the given cursor position.
+
+    V1 implementation: filter the static keyword pool against the
+    identifier-shaped word ending at ``cursor`` (case-insensitive
+    prefix match). When the cursor sits on whitespace / start of
+    input, the full keyword pool is returned.
+
+    Parameters
+    ----------
+    decl : str
+        Current editor content.
+    cursor : int
+        Zero-indexed character position.
+
+    Returns
+    -------
+    list[dict]
+        Sorted list of ``{text, label, detail, terminal, kind}`` dicts. Empty
+        only when no keyword starts with the current prefix.
+
+    Notes
+    -----
+    ``text`` is the bare token and is what an editor inserts; ``label`` is the
+    same token (they differ only in that ``label`` is what a menu shows) and
+    ``detail`` carries the gloss where the terminal has one. Matching is on the
+    **token**, never on the gloss, so typing ``pr`` offers ``premium`` and does
+    not also offer everything whose parenthetical happens to contain a ``pr``.
+    """
+    prefix = decl[:cursor]
+    # Identify the word the cursor is currently inside (or at the
+    # end of). Walk backwards while we still see identifier chars.
+    i = len(prefix)
+    while i > 0 and (prefix[i - 1].isalnum() or prefix[i - 1] in "._-:~"):
+        i -= 1
+    word = prefix[i:].lower()
+
+    out: list[dict] = []
+    for term in _STATIC_KEYWORDS:
+        text, detail = _split_label(term)
+        if not text:
+            continue
+        if word and not text.lower().startswith(word):
+            continue
+        out.append({"text": text, "label": text, "detail": detail,
+                    "terminal": term, "kind": _classify(term)})
+    return out
+
+
+def lex(decl: str) -> list[dict]:
+    """Tokenize ``decl`` via Lark's lexer and return token records.
+
+    Returns one dict per token::
+
+        {"type": "MIXED", "value": "mixed", "start": 7, "end": 12,
+         "line": 1, "column": 8}
+
+    A failure to tokenize (e.g. an unexpected character partway
+    through) surfaces an empty list -- callers should hit
+    ``/v1/objects`` for a proper :class:`ErrorReport`.
+    """
+    try:
+        tokens = list(_PARSER.lex(decl))
+    except UnexpectedInput:
+        return []
+    except Exception:
+        return []
+    out: list[dict] = []
+    for tok in tokens:
+        out.append({
+            "type": tok.type,
+            "value": str(tok),
+            "start": tok.start_pos or 0,
+            "end": tok.end_pos or 0,
+            "line": tok.line or 1,
+            "column": tok.column or 1,
+        })
+    return out

aggregate_api/config.py

@@ -0,0 +1,363 @@
+"""Settings for the api, driven by environment variables.
+
+The :class:`Settings` class is built on ``pydantic-settings`` --
+a small wrapper around Pydantic that reads env vars (prefixed
+``AGGAPI_``) and validates them through the usual Pydantic
+machinery. The end result is a typed, validated config object
+loaded once at process start.
+
+Flask users: this replaces ``app.config[...]``. The pattern of
+"build a settings object once, inject it everywhere" is a FastAPI
+idiom -- routes pull the live settings via the
+:func:`get_settings` dependency (used with ``Depends``), not via
+a global.
+
+To override a value at runtime, set the env var before launching
+``aggregate-api`` (e.g. ``AGGAPI_LOG2_CAP=20 aggregate-api``) or
+pass it through ``monkeypatch.setenv`` in tests.
+
+The defaults are the team-deploy preset: localhost-only bind,
+modest log2 cap, 10 s build timeout, 50 objects in the cache.
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import AliasChoices, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from .net import DEFAULT_PRIVATE_CIDRS, parse_cidrs
+
+
+class Settings(BaseSettings):
+    """Process-wide configuration.
+
+    All knobs come from env vars beginning with ``AGGAPI_``.
+    Empty strings on list-typed fields mean "unset" rather than
+    "single empty element" -- see :meth:`_parse_cors_origins`.
+    """
+
+    # ``model_config`` is the Pydantic v2 idiom for class-level
+    # config (it replaces v1's inner ``class Config``). ``env_prefix``
+    # tells pydantic-settings to look for AGGAPI_HOST -> ``host``,
+    # AGGAPI_PORT -> ``port``, etc. ``extra='ignore'`` lets us run
+    # in an environment with unrelated env vars without complaint.
+    model_config = SettingsConfigDict(
+        env_prefix="AGGAPI_",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # ------------------------------------------------------------------
+    # Network / server
+    # ------------------------------------------------------------------
+    host: str = "127.0.0.1"
+    port: int = 8000
+
+    # ------------------------------------------------------------------
+    # Build pipeline
+    # ------------------------------------------------------------------
+    # Default log2 if the client omits it.
+    log2_default: int = 16
+    # Hard cap: requests above this fail with HTTP 422 (limit_exceeded).
+    # The cap exists because 2**N grid points * sizeof(float) is the
+    # FFT memory cost; 2**20 is ~8 MB per density array and is well
+    # past anything legitimate users need on a team-deploy box.
+    log2_cap: int = 18
+    # Per-build wall-clock timeout; expires via threadpool.future.
+    build_timeout_s: float = 10.0
+
+    # How long a request waits for a cached object's lock before giving up with
+    # HTTP 503.
+    #
+    # A timeout rather than an unbounded wait, because an unbounded one could
+    # take the whole process down. `_locked_entry` holds a CacheEntry's lock for
+    # the length of a request, and FastAPI runs a sync dependency and a sync
+    # handler in two separate threadpool calls, each needing one of anyio's 40
+    # tokens. Forty requests blocked on one lock therefore hold every token, and
+    # the request that holds the lock can never get a token to reach its handler
+    # and release it. Measured at a200: 45 concurrent reads of one object left
+    # the process at 0% CPU with every sync route, `/v1/health` included,
+    # permanently unreachable. 39 survived. See dev/plan-demo-load.md item 0.
+    #
+    # Ten seconds matches the build timeout, so the two ways a request can be
+    # told "not now" expire on the same clock.
+    entry_lock_timeout_s: float = 10.0
+
+    # ------------------------------------------------------------------
+    # Cache
+    # ------------------------------------------------------------------
+    cache_max: int = 50
+
+    # ------------------------------------------------------------------
+    # Sessions
+    # ------------------------------------------------------------------
+    # How many forked recipe bases to hold, and how long an idle one lives.
+    # A fork is microseconds and a few hundred kilobytes, so the count is
+    # deliberately generous and the TTL is what bounds the memory. Eight hours
+    # outlives any sitting a browser tab survives; ttl 0 disables expiry.
+    session_max: int = 500
+    session_ttl_s: float = 28800.0
+
+    # ------------------------------------------------------------------
+    # Audit log
+    # ------------------------------------------------------------------
+    # Default is per-user data dir; resolved lazily in audit.py so the
+    # directory is only created when an AuditLog is actually opened.
+    audit_db: str = str(Path.home() / ".aggregate" / "api" / "audit.db")
+
+    # No plotting settings any more. `plot_default_format` chose svg or png for
+    # the server-rendered figure route, which left with matplotlib at a60: every
+    # chart is a document now and the browser decides how to draw and export it,
+    # so there is no server-side image format to have an opinion about.
+
+    # ------------------------------------------------------------------
+    # Charts
+    # ------------------------------------------------------------------
+    # Ceiling on the chart route's ``detail`` parameter, the target cells
+    # per axis of a reduced surface grid.
+    #
+    # A setting rather than a constant because one route serves two cases
+    # that want opposite things. Over the wire the answer is a windowed
+    # grid of a few thousand cells and a payload in kilobytes; locally it
+    # is a drill-down into fine detail on a machine where bandwidth is not
+    # a constraint, and a hard cap there would prevent a use in order to
+    # prevent nothing. What stops a client misrepresenting what it got is
+    # the document (it reports the realized ``k``, ``bs``, ``nx``, ``ny``),
+    # not this number.
+    #
+    # The public deploy sets AGGAPI_MAX_CHART_DETAIL=256, because chart
+    # GETs sit outside the Caddy rate limiter and each parameter
+    # combination is a fresh reduction. VPN and local runs keep this
+    # default. See dev/plan-3d-plot.md sections 3.1 and 7 answer 2.
+    max_chart_detail: int = 1024
+
+    # ------------------------------------------------------------------
+    # CORS
+    # ------------------------------------------------------------------
+    # Comma-separated list in the env var. Empty -> middleware skipped
+    # (same-origin deploys don't pay the per-request CORS handling).
+    # ``validation_alias`` overrides the auto-derived AGGAPI_CORS_ORIGINS_RAW
+    # name so the env var stays AGGAPI_CORS_ORIGINS (matches docs).
+    cors_origins_raw: str = Field(
+        default="",
+        validation_alias="AGGAPI_CORS_ORIGINS",
+    )
+
+    # ------------------------------------------------------------------
+    # Static files (Plan D web build)
+    # ------------------------------------------------------------------
+    # When set, overrides the importlib-resources discovery in
+    # app.py. Lets a developer point the running api at a Vite dev
+    # build sitting in a sibling tree without reinstalling.
+    static_dir: str = ""
+
+    # Whether to serve the SPA at all. False leaves the api headless: the /v1
+    # routers, /docs and /openapi.json, and nothing at /.
+    #
+    # A setting rather than a fact about the filesystem. Headless already worked
+    # by accident, because the mount in app.py is conditional on the bundle
+    # directory existing and `static/` is gitignored and built at deploy, so an
+    # install that never ran the web build is api-only. But "I did not build the
+    # SPA" is not a way to *say* headless: it cannot be set on a machine that has
+    # the bundle, it is invisible in the config, and the only explicit off was
+    # pointing static_dir at a path that does not exist. This states the
+    # intention instead.
+    #
+    # /docs is unaffected. FastAPI registers the doc routes in its constructor,
+    # before create_app mounts anything, and Starlette matches in registration
+    # order, so this only removes the catch-all at the end.
+    serve_spa: bool = True
+
+    # ------------------------------------------------------------------
+    # The library
+    # ------------------------------------------------------------------
+    # When set, the whole process reads its recipes from this .agg file instead
+    # of aggregate's bundled library.agg: the Examples dropdown, every build,
+    # and the .agg download all resolve against it (see library.py). Lets a
+    # deploy ship a curated set without rebuilding the SPA, since the menu is
+    # fetched at runtime from GET /v1/examples. Re-read on server restart.
+    #
+    # Named AGGAPI_EXAMPLES_FILE until a109, when it stopped being about
+    # examples: it feeds builds now, so it is the library. The old name is
+    # accepted for one release and warns, hence the two-name alias rather than a
+    # plain field. ``validation_alias`` bypasses ``env_prefix``, so both names
+    # are spelled in full.
+    library: str = Field(
+        default="",
+        validation_alias=AliasChoices("AGGAPI_LIBRARY", "AGGAPI_EXAMPLES_FILE"),
+    )
+
+    # ------------------------------------------------------------------
+    # The status page
+    # ------------------------------------------------------------------
+    # Which client addresses may reach /v1/status and /v1/status/page. Loopback,
+    # IPv6 loopback, and the VPN subnet from human-hints.md.
+    #
+    # A setting rather than a constant because the VPN subnet is a deployment
+    # fact, and the list is the second of three layers rather than the only one:
+    # the public Caddy block 404s the /v1/status prefix before the app is
+    # reached at all. See net.py for why this cannot be written as "allow if the
+    # peer is loopback" (both front doors proxy to 127.0.0.1, so that rule would
+    # publish the page) and for the single-hop assumption the gate rests on.
+    #
+    # ``validation_alias`` so the env var stays AGGAPI_PRIVATE_CIDRS rather than
+    # the auto-derived AGGAPI_PRIVATE_CIDRS_RAW, matching the CORS field above.
+    private_cidrs_raw: str = Field(
+        default=DEFAULT_PRIVATE_CIDRS,
+        validation_alias="AGGAPI_PRIVATE_CIDRS",
+    )
+
+    # Layer three: demand X-Aggapi-Zone: private, which the VPN Caddy block sets
+    # and the public block strips. Off by default (author ruling, 2026-08-18):
+    # layer two is sufficient, and this one couples the app to a Caddyfile edit
+    # in a way that fails closed but confusingly, the page simply stopping. It
+    # ships built and documented because it is the only layer that survives a
+    # mistake in the CIDR list, so turning it on is a setting rather than a
+    # change.
+    status_require_zone_header: bool = False
+
+    # Seconds between the page's automatic refreshes. The page carries a pause
+    # control, so this is the starting cadence rather than a policy.
+    status_refresh_s: float = 10.0
+
+    # ------------------------------------------------------------------
+    # Plugins
+    # ------------------------------------------------------------------
+    # Whether this process runs third-party `aggregate.plugins` registrations.
+    #
+    # The library deliberately does **not** auto-load on `import aggregate`, so
+    # that `build()` stays reproducible and a notebook's results are a function
+    # of the notebook's own text. The decision belongs to the host, and a server
+    # is a deployment, so it is a setting here rather than a fact about what
+    # happens to be installed.
+    #
+    # On by default: the case that exists is a local deployment running the
+    # author's own plugin packages. A plugin is Python in this process with full
+    # privileges and there is no sandbox, which is acceptable while the bind is
+    # 127.0.0.1 and the packages are the author's own, and is exactly why the
+    # allowlist below exists for the case where neither holds.
+    plugins_enabled: bool = True
+
+    # Which plugins to admit, by name. Empty means all of them, which is what a
+    # local deployment wants. A comma-separated list admits only those named, so
+    # a hosted deployment can state what it trusts rather than inheriting
+    # whatever is on the image.
+    #
+    # ``validation_alias`` so the env var stays AGGAPI_PLUGINS_ALLOW rather than
+    # the auto-derived AGGAPI_PLUGINS_ALLOW_RAW, matching the CORS and CIDR
+    # fields above.
+    plugins_allow_raw: str = Field(
+        default="",
+        validation_alias="AGGAPI_PLUGINS_ALLOW",
+    )
+
+    # ------------------------------------------------------------------
+    # Derived properties
+    # ------------------------------------------------------------------
+    @property
+    def plugins_allow(self) -> list[str] | None:
+        """Parse ``AGGAPI_PLUGINS_ALLOW`` into an allowlist, or None for all.
+
+        Returns
+        -------
+        list of str or None
+            None where the setting is empty, which is what
+            :func:`aggregate.plugins.load` takes to mean "admit everything
+            discovered". An empty *list* would mean the opposite, admit nothing,
+            so the distinction is load bearing and is not a tidied-away falsy
+            check.
+        """
+        raw = self.plugins_allow_raw.strip()
+        if not raw:
+            return None
+        return [name.strip() for name in raw.split(",") if name.strip()]
+
+    @property
+    def cors_origins(self) -> list[str]:
+        """Parse ``AGGAPI_CORS_ORIGINS`` into a list of origins."""
+        raw = self.cors_origins_raw.strip()
+        if not raw:
+            return []
+        return [o.strip() for o in raw.split(",") if o.strip()]
+
+    @property
+    def private_cidrs(self) -> tuple:
+        """Parse ``AGGAPI_PRIVATE_CIDRS`` into networks.
+
+        Raises
+        ------
+        ValueError
+            On a malformed entry, from :func:`aggregate_api.net.parse_cidrs`.
+            Loud on purpose: a typo here is a gate that allows the wrong set,
+            and a route that refuses to answer says so more clearly than a page
+            that has quietly stopped working.
+
+        Notes
+        -----
+        Parsed per read rather than cached on the instance, because ``Settings``
+        is itself the cached singleton and the list is a handful of networks. A
+        cached property here would only add a second place for a stale value to
+        live.
+        """
+        return parse_cidrs(self.private_cidrs_raw)
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return the cached process-wide settings.
+
+    ``lru_cache`` makes this an effective singleton without the
+    pitfalls of a module-level mutable -- and FastAPI's
+    ``Depends(get_settings)`` knows how to use it directly.
+
+    Tests that flip env vars via ``monkeypatch.setenv`` must call
+    :func:`get_settings.cache_clear` (handled centrally by the
+    ``client`` fixture in ``tests/api/conftest.py``) so the next
+    read re-evaluates the environment.
+
+    Notes
+    -----
+    The deprecation notice for ``AGGAPI_EXAMPLES_FILE`` lives here rather than
+    on the field, because a field validator sees only the value that won and
+    cannot tell which of the two names supplied it. Warning once per settings
+    read is right: the cache makes that once per process in production, and once
+    per case in a test that clears it.
+    """
+    if "AGGAPI_EXAMPLES_FILE" in os.environ and "AGGAPI_LIBRARY" not in os.environ:
+        warnings.warn(
+            "AGGAPI_EXAMPLES_FILE is deprecated and will be removed after one "
+            "release; use AGGAPI_LIBRARY. The setting now feeds every build, "
+            "not just the Examples menu.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    return Settings()
+
+
+# Module-level alias for code that doesn't need DI -- e.g. ``__main__.py``
+# launching uvicorn off a single ``settings.host``/``port`` read.
+# Reaches through the cache so tests with cleared cache still see
+# the right object.
+def _settings_attr(name: str):
+    """Pass-through accessor that always reads from the cached object."""
+    return getattr(get_settings(), name)
+
+
+class _SettingsProxy:
+    """Lazy attribute proxy so ``settings.host`` always hits live config.
+
+    Avoids the trap of ``settings = Settings()`` at import time, which
+    would lock in env-var values from before tests had a chance to
+    monkeypatch them.
+    """
+
+    def __getattr__(self, name):
+        return _settings_attr(name)
+
+
+settings = _SettingsProxy()

aggregate_api/cors.py

@@ -0,0 +1,61 @@
+"""CORS middleware setup.
+
+The web SPA (Plan D) can be served from the same origin as the
+api (via the conditional ``StaticFiles`` mount in ``app.py``) or
+from a different origin -- e.g. ``mynl.com/aggregate/`` calling
+``api.mynl.com``. The second case needs the browser-side CORS
+preflight handshake to succeed; this helper attaches the
+:class:`fastapi.middleware.cors.CORSMiddleware` when the operator
+has declared which origins are trusted.
+
+Same-origin deploys don't pay the per-request CORS handling
+overhead: empty ``allowed_origins`` → middleware skipped entirely.
+
+Flask users: FastAPI middleware is closer to Starlette/ASGI
+middleware than to ``@app.before_request``. The order of
+``add_middleware`` calls matters -- the *last* one added is the
+*outermost* in the request lifecycle.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+
+def install_cors(app: FastAPI, allowed_origins: list[str]) -> None:
+    """Attach ``CORSMiddleware`` if ``allowed_origins`` is non-empty.
+
+    Parameters
+    ----------
+    app : FastAPI
+        The application being configured.
+    allowed_origins : list[str]
+        Exact-match origins (``["http://localhost:5173",
+        "https://mynl.com"]``). No regex / wildcard support in v1
+        -- the team-deploy use case is two or three known origins.
+
+    Notes
+    -----
+    * ``allow_credentials=False`` because v1 has no cookies / auth.
+      With credentials enabled the browser also bars ``*`` in
+      ``allow_origins``; explicit exact-match avoids that footgun.
+    * ``allow_methods`` lists only what the api uses; OPTIONS is
+      handled automatically by CORSMiddleware for preflights.
+    * ``allow_headers`` is conservative -- if a future endpoint
+      needs ``Authorization`` etc., extend this list.
+    * ``X-Aggregate-Session`` is on that list because the SPA sends it on every
+      request, and a browser will not send a header the preflight did not allow.
+      Same-origin deploys skip this middleware entirely, so leaving it off would
+      have broken only the split-origin deploy, which is precisely the one that
+      most needs sessions to work.
+    """
+    if not allowed_origins:
+        return
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=allowed_origins,
+        allow_credentials=False,
+        allow_methods=["GET", "POST", "DELETE"],
+        allow_headers=["Content-Type", "X-Aggregate-Session"],
+    )