supertable 2.0.3__tar.gz → 2.0.5__tar.gz

{supertable-2.0.3/supertable.egg-info → supertable-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supertable
-Version: 2.0.3
+Version: 2.0.5
 Summary: SuperTable — versioned data lake library for SQL analytics on Parquet + Redis.
 Author: Levente Kupas
 Author-email: Levente Kupas <lkupas@kladnasoft.com>

{supertable-2.0.3 → supertable-2.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "supertable"
-version = "2.0.3"
+version = "2.0.5"
 description = "SuperTable — versioned data lake library for SQL analytics on Parquet + Redis."
 readme = "README.md"
 requires-python = ">=3.10"

{supertable-2.0.3 → supertable-2.0.5}/setup.py

@@ -19,7 +19,7 @@ long_description = readme.read_text(encoding="utf-8") if readme.exists() else ""
 
 setup(
     name="supertable",
-    version="2.0.3",
+    version="2.0.5",
     description="SuperTable — versioned data lake library for SQL analytics on Parquet + Redis.",
     long_description=long_description,
     long_description_content_type="text/markdown",

{supertable-2.0.3 → supertable-2.0.5}/supertable/__init__.py

@@ -25,7 +25,7 @@ See the ``supertable.demo`` package for runnable end-to-end demos and the
 project documentation for the full API surface.
 """
 
-__version__ = "2.0.3"
+__version__ = "2.0.5"
 
 # Re-export the core public surface so users can do ``from supertable import …``
 # instead of remembering submodule paths.

{supertable-2.0.3 → supertable-2.0.5}/supertable/processing.py

@@ -75,37 +75,129 @@ def _resolve_unified_dtype(dtypes: Set[polars.DataType]) -> polars.DataType:
     return polars.Utf8
 
 
-def _union_schema(a: polars.DataFrame, b: polars.DataFrame) -> Dict[str, polars.DataType]:
-    cols: List[str] = list(dict.fromkeys(a.columns + b.columns))
+def _union_schema_many(frames: List[polars.DataFrame]) -> Dict[str, polars.DataType]:
+    """Build a unified column-name → dtype mapping across N dataframes.
+
+    The output dict preserves first-appearance order: a column that first
+    appears in frame *i* takes position determined by frame *i*'s own order
+    relative to columns that appeared earlier.  Dtypes are widened via
+    ``_resolve_unified_dtype`` over the set of dtypes the column carries
+    across all frames that contain it.
+    """
+    seen: Set[str] = set()
+    cols: List[str] = []
+    for f in frames:
+        for c in f.columns:
+            if c not in seen:
+                seen.add(c)
+                cols.append(c)
     target: Dict[str, polars.DataType] = {}
     for c in cols:
         types: Set[polars.DataType] = set()
-        if c in a.columns:
-            types.add(a[c].dtype)
-        if c in b.columns:
-            types.add(b[c].dtype)
+        for f in frames:
+            if c in f.columns:
+                types.add(f[c].dtype)
         target[c] = _resolve_unified_dtype(types)
     return target
 
 
+def _union_schema(a: polars.DataFrame, b: polars.DataFrame) -> Dict[str, polars.DataType]:
+    return _union_schema_many([a, b])
+
+
 def _align_to_schema(df: polars.DataFrame, target_schema: Dict[str, polars.DataType]) -> polars.DataFrame:
-    exprs = []
+    """Project *df* into *target_schema*: same column names, same order, same dtypes.
+
+    For every column in *target_schema*:
+      - present in *df* with the target dtype → keep the existing series
+      - present in *df* with a different dtype → cast (strict=False, so unconvertible values become null)
+      - absent in *df*                          → fill with a typed null literal
+
+    The resulting frame's column order is **exactly** ``list(target_schema.keys())``.
+    This is the contract callers like :func:`concat_with_union` rely on:
+    ``polars.concat(..., how="vertical_relaxed")`` aligns frames *positionally*,
+    so it requires identical names at identical positions.
+
+    Implementation note: ``df.select(exprs)`` is used (not ``with_columns``).
+    ``with_columns`` preserves the input frame's column order and appends new
+    columns at the end, which silently breaks the positional-concat contract
+    when *df*'s order disagrees with *target_schema*'s order.
+    """
+    if not target_schema:
+        return df
+    # Zero-row defence: ``df.select([pl.lit(None), ...])`` on an empty frame
+    # broadcasts the literal to a single null row, which would silently turn
+    # a 0-row input into a 1-row output.  Materialise an explicit empty frame
+    # with the target schema instead.
+    if df.height == 0:
+        return polars.DataFrame(schema=target_schema)
+    exprs: List[polars.Expr] = []
     for col, dtype in target_schema.items():
         if col in df.columns:
-            if df[col].dtype != dtype:
+            if df.schema[col] != dtype:
                 exprs.append(polars.col(col).cast(dtype, strict=False))
+            else:
+                exprs.append(polars.col(col))
         else:
             exprs.append(polars.lit(None, dtype=dtype).alias(col))
-    return df.with_columns(exprs) if exprs else df
+    return df.select(exprs)
 
 
 def concat_with_union(a: polars.DataFrame, b: polars.DataFrame) -> polars.DataFrame:
+    """Vertically concatenate two frames with a unified schema.
+
+    Computes the union of *a*'s and *b*'s schemas, aligns both frames to it
+    (filling missing columns with nulls and widening conflicting dtypes), and
+    then concatenates positionally.  After the union both frames have
+    identical columns in identical positions, so the concat cannot fail with
+    ``schema names differ``.
+    """
     if a.height == 0:
         return b
     if b.height == 0:
         return a
-    target = _union_schema(a, b)
-    return polars.concat([_align_to_schema(a, target), _align_to_schema(b, target)], how="vertical_relaxed")
+    target = _union_schema_many([a, b])
+    return polars.concat(
+        [_align_to_schema(a, target), _align_to_schema(b, target)],
+        how="vertical_relaxed",
+    )
+
+
+def concat_many_with_union(frames: List[polars.DataFrame]) -> polars.DataFrame:
+    """Vertically concatenate N frames with a single unified schema.
+
+    Equivalent to repeated :func:`concat_with_union` but computes the union
+    schema once across all inputs (rather than re-deriving it pairwise), and
+    issues a single ``polars.concat``.  Use this when merging an arbitrary
+    set of parquet files with potentially different / dynamic column sets
+    (e.g. GA4-style ``param_*`` dynamic columns where each batch contains a
+    different subset of keys).
+
+    Semantics:
+      - Empty frames are skipped.
+      - If all frames are empty, an empty frame with the union schema is returned.
+      - If no frames are given, an empty zero-column frame is returned.
+
+    Note on memory: this materialises every input frame in memory at once.
+    For memory-bounded streaming compaction, callers should still iterate
+    with chunked flushes via :func:`concat_with_union` — this helper is for
+    callers that already have all frames in memory.
+    """
+    if not frames:
+        return polars.DataFrame()
+    non_empty = [f for f in frames if f.height > 0]
+    if not non_empty:
+        # All inputs are empty — return an empty frame carrying the union schema
+        target = _union_schema_many(frames)
+        return polars.DataFrame(schema=target)
+    if len(non_empty) == 1:
+        # Still project to its own schema explicitly so the output dtype map is
+        # the same shape as the multi-frame path (callers can rely on it).
+        target = _union_schema_many(non_empty)
+        return _align_to_schema(non_empty[0], target)
+    target = _union_schema_many(non_empty)
+    aligned = [_align_to_schema(f, target) for f in non_empty]
+    return polars.concat(aligned, how="vertical_relaxed")
 
 
 # =========================

{supertable-2.0.3 → supertable-2.0.5}/supertable/redis_infra.py

@@ -64,13 +64,25 @@ if settings.SUPERTABLE_LOGIN_MASK not in (1, 2, 3):
         f"Invalid SUPERTABLE_LOGIN_MASK (must be 1, 2, or 3): {settings.SUPERTABLE_LOGIN_MASK}"
     )
 
-_missing_envs: List[str] = []
-if not settings.SUPERTABLE_ORGANIZATION:
-    _missing_envs.append("SUPERTABLE_ORGANIZATION")
-if not (settings.SUPERTABLE_SUPERUSER_TOKEN or "").strip():
-    _missing_envs.append("SUPERTABLE_SUPERUSER_TOKEN")
-if _missing_envs:
-    raise RuntimeError("Missing required environment variables: " + ", ".join(_missing_envs))
+def _require_runtime_env() -> None:
+    """Validate the env vars needed to actually talk to Redis.
+
+    Called lazily by code paths that open a real Redis connection or
+    otherwise need the deployment's organization / superuser token.
+    Importing the SDK no longer fails when these are unset — only
+    running against Redis does. This keeps the module importable in
+    test, build, and inspection contexts where the runtime
+    credentials aren't (and shouldn't be) present.
+    """
+    missing: List[str] = []
+    if not settings.SUPERTABLE_ORGANIZATION:
+        missing.append("SUPERTABLE_ORGANIZATION")
+    if not (settings.SUPERTABLE_SUPERUSER_TOKEN or "").strip():
+        missing.append("SUPERTABLE_SUPERUSER_TOKEN")
+    if missing:
+        raise RuntimeError(
+            "Missing required environment variables: " + ", ".join(missing)
+        )
 
 
 def _now_ms() -> int:
@@ -297,6 +309,11 @@ def _build_redis_client() -> redis.Redis:
       If SUPERTABLE_REDIS_SENTINEL is enabled and SUPERTABLE_REDIS_SENTINELS is set,
       use the same Sentinel connection behavior as RedisCatalog (ping-probe + optional fallback).
     """
+    # Gate runtime-credential validation here so that simply importing the
+    # module (e.g. to inspect ``redis_keys`` helpers or run unit tests
+    # against the public API) does not require an organization + token to
+    # be set. Anything that actually opens a connection still fails fast.
+    _require_runtime_env()
     settings = Settings()
     url = (settings.SUPERTABLE_REDIS_URL or "").strip() or None
 

supertable-2.0.5/supertable/redis_keys.py

@@ -0,0 +1,404 @@
+# route: supertable.redis_keys
+"""
+Single source of truth for every Redis key used by SuperTable + the
+platform layer (dataisland-core).
+
+Rule (enforced by tests/test_redis_key_prefix.py):
+  Every key constructed here MUST start with one of the two recognised
+  top-level prefixes:
+    * ``supertable:`` — SuperTable SDK state (catalog, RBAC, locks,
+                       audit, share federation, table meta, …).
+    * ``dataisland:`` — platform / dataisland-core state that is not
+                       SuperTable's concern (service registry, app
+                       bootstrap config, etc.).
+  Per-app config keys (lighthouse, gatekeeper, studio, …) live under
+  their own app-name prefix and are written via the MCP server's
+  ``store_app_config`` tool — they do **not** go through this module.
+
+Hierarchy
+---------
+
+    dataisland:
+      apps:{app_name}:master_mcp                ← per-app bootstrap (one global key)
+      {org}:
+        registry:{service_type}:{host}:{pid}    ← service-instance heartbeats (TTL)
+
+    supertable:
+      {org}:                                   ← organization / company scope
+        _system_:                              ← reserved system scope (supertable-side)
+          auth:tokens                          ← organization login tokens
+        shares:doc:{share_id}
+        shares:index
+        audit:stream
+        audit:chain_head:{instance_id}
+        audit:config                           ← runtime toggle (per org)
+        spark:thrifts
+        spark:plugs
+        {sup}:                                 ← supertable scope
+          meta:root
+          meta:leaf:{simple}
+          meta:mirrors
+          meta:table_config:{simple}
+          meta:staging:{staging_name}
+          meta:staging:meta
+          meta:staging:{staging_name}:pipe:{pipe_name}
+          meta:staging:{staging_name}:pipe:meta
+          config:engine
+          lock:leaf:{simple}
+          lock:stage:{stage_name}
+          rbac:users:meta
+          rbac:users:index
+          rbac:users:doc:{user_id}
+          rbac:users:name_to_id
+          rbac:roles:meta
+          rbac:roles:index
+          rbac:roles:doc:{role_id}
+          rbac:roles:type:{role_type}
+          rbac:roles:name_to_id
+          schema:{simple}
+          table_names
+          linked_shares:doc:{link_id}
+          linked_shares:index
+          monitor:{monitor_type}
+
+Reserved supertable names
+-------------------------
+
+``_system_`` is reserved.  It MUST NOT be used as a supertable name and
+``SuperTable(..., super_name="_system_")`` raises ``ValueError``.  The
+name is reserved because we keep everything system-related — service
+registry heartbeats, organization-level auth tokens, future
+system-only scopes — under that prefix to avoid collisions with
+user-created supertables.
+"""
+from __future__ import annotations
+
+from typing import FrozenSet
+
+# The canonical SuperTable SDK prefix. Everything the SDK itself writes
+# lives under this.
+SUPERTABLE_PREFIX: str = "supertable"
+
+# The platform-layer prefix. dataisland-core writes its own
+# infrastructure (service-registry heartbeats, app-bootstrap configs)
+# here. Per-app config keys (lighthouse:*, gatekeeper:*, …) live in
+# yet another set of namespaces and are not built through this module.
+DATAISLAND_PREFIX: str = "dataisland"
+
+# Recognised top-level prefixes for assert_prefixed(). Adding a new
+# layer to the platform → extend this set.
+_RECOGNISED_PREFIXES: FrozenSet[str] = frozenset({SUPERTABLE_PREFIX, DATAISLAND_PREFIX})
+
+# The org-level system scope.  Reserved as a supertable name (see
+# ``is_reserved_super_name`` below).  Everything system-related under an
+# organization lives here so user-supplied supertable names can never
+# collide with infrastructure keys.
+SYSTEM_SCOPE: str = "_system_"
+
+# All names that may NOT be used for user-created supertables.
+RESERVED_SUPER_NAMES: FrozenSet[str] = frozenset({SYSTEM_SCOPE})
+
+
+# --------------------------------------------------------------------------- #
+# Guards
+# --------------------------------------------------------------------------- #
+
+def assert_prefixed(key: str) -> str:
+    """Raise ValueError if *key* does not start with a recognised prefix.
+
+    Recognised prefixes: ``supertable:`` (SDK state) and
+    ``dataisland:`` (platform state). Returns the key unchanged so
+    callers can write::
+
+        self.r.set(assert_prefixed(some_key), value)
+    """
+    if not isinstance(key, str):
+        raise ValueError(
+            f"Redis key violates namespace policy (must be a str): {key!r}"
+        )
+    if not any(key.startswith(p + ":") for p in _RECOGNISED_PREFIXES):
+        raise ValueError(
+            f"Redis key violates namespace policy (must start with one "
+            f"of {sorted(_RECOGNISED_PREFIXES)}): {key!r}"
+        )
+    return key
+
+
+def is_reserved_super_name(name: str) -> bool:
+    """Return True when *name* is reserved (cannot be a supertable name)."""
+    if not isinstance(name, str):
+        return False
+    return name.strip() in RESERVED_SUPER_NAMES
+
+
+# --------------------------------------------------------------------------- #
+# Per-organization system scope (registry, auth tokens, future system keys)
+# --------------------------------------------------------------------------- #
+
+def system_scope(org: str) -> str:
+    """Return the system-scope prefix for one organization."""
+    return f"{SUPERTABLE_PREFIX}:{org}:{SYSTEM_SCOPE}"
+
+
+def system_scope_pattern(org: str) -> str:
+    """SCAN pattern for everything under one org's system scope."""
+    return f"{SUPERTABLE_PREFIX}:{org}:{SYSTEM_SCOPE}:*"
+
+
+# --------------------------------------------------------------------------- #
+# Service registry (per organization) — under the dataisland: prefix
+# --------------------------------------------------------------------------- #
+#
+# Service-instance heartbeats are a *platform* concern, not a SuperTable
+# concern. They live at:
+#
+#     dataisland:{org}:registry:{service_type}:{host}:{pid}
+#
+# (No ``_system_`` segment — that segment exists only inside
+# ``supertable:{org}:`` to avoid colliding with user-created supertable
+# names. Under ``dataisland:`` there are no user supertables, so the
+# extra segment is dropped.)
+
+def registry(org: str, service_type: str, host: str, pid: int) -> str:
+    """Per-organization service registry entry.
+
+    Example::
+
+        dataisland:kladna-soft:registry:api:host1:1234
+    """
+    return f"{DATAISLAND_PREFIX}:{org}:registry:{service_type}:{host}:{pid}"
+
+
+def registry_pattern_for_org(org: str) -> str:
+    """SCAN pattern for all service-registry entries in one organization."""
+    return f"{DATAISLAND_PREFIX}:{org}:registry:*"
+
+
+def registry_pattern() -> str:
+    """SCAN pattern for service-registry entries across every organization.
+
+    Matches ``dataisland:*:registry:*`` — the cross-org pattern that
+    scanners use when no org is supplied (e.g. fleet-wide monitoring).
+    """
+    return f"{DATAISLAND_PREFIX}:*:registry:*"
+
+
+# --------------------------------------------------------------------------- #
+# App bootstrap (per application — Lighthouse, Gatekeeper, Studio, …)
+# --------------------------------------------------------------------------- #
+#
+# The very first thing an app reads on boot is its master-MCP config.
+# That happens before any org context exists, so the key sits at a
+# single global location keyed only by app_name:
+#
+#     dataisland:apps:{app_name}:master_mcp
+#
+# Written via the platform REST API (``POST /api/v1/apps/{app}/master-mcp``,
+# admin-only) and read on every app boot.
+
+def app_master_mcp(app_name: str) -> str:
+    """The platform-side key holding an app's master-MCP coordinates."""
+    return f"{DATAISLAND_PREFIX}:apps:{app_name}:master_mcp"
+
+
+# --------------------------------------------------------------------------- #
+# Organization auth (login tokens) — also under _system_ for the same reason:
+# "auth" must not collide with a possible user-created supertable called "auth".
+# --------------------------------------------------------------------------- #
+
+def auth_tokens(org: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{SYSTEM_SCOPE}:auth:tokens"
+
+
+# --------------------------------------------------------------------------- #
+# Organization scope (non-system)
+# --------------------------------------------------------------------------- #
+
+def share_doc(org: str, share_id: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:shares:doc:{share_id}"
+
+
+def share_index(org: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:shares:index"
+
+
+def audit_stream(org: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:audit:stream"
+
+
+def audit_chain_head(org: str, instance_id: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:audit:chain_head:{instance_id}"
+
+
+def audit_config(org: str) -> str:
+    """Per-organization runtime audit configuration (enable toggle, sub-flags)."""
+    return f"{SUPERTABLE_PREFIX}:{org}:audit:config"
+
+
+def spark_thrifts(org: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:spark:thrifts"
+
+
+def spark_plugs(org: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:spark:plugs"
+
+
+# --------------------------------------------------------------------------- #
+# SuperTable scope — meta
+# --------------------------------------------------------------------------- #
+
+def meta_root(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:root"
+
+
+def meta_leaf(org: str, sup: str, simple: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:leaf:{simple}"
+
+
+def meta_leaf_pattern(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:leaf:*"
+
+
+def meta_root_pattern_for_org(org: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:*:meta:root"
+
+
+def meta_mirrors(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:mirrors"
+
+
+def meta_table_config(org: str, sup: str, simple: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:table_config:{simple}"
+
+
+# --------------------------------------------------------------------------- #
+# SuperTable scope — engine config
+# --------------------------------------------------------------------------- #
+
+def config_engine(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:config:engine"
+
+
+# --------------------------------------------------------------------------- #
+# SuperTable scope — locks
+# --------------------------------------------------------------------------- #
+
+def lock_leaf(org: str, sup: str, simple: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:lock:leaf:{simple}"
+
+
+def lock_stage(org: str, sup: str, stage_name: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:lock:stage:{stage_name}"
+
+
+# --------------------------------------------------------------------------- #
+# SuperTable scope — RBAC users
+# --------------------------------------------------------------------------- #
+
+def rbac_user_meta(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:rbac:users:meta"
+
+
+def rbac_user_index(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:rbac:users:index"
+
+
+def rbac_user_doc(org: str, sup: str, user_id: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:rbac:users:doc:{user_id}"
+
+
+def rbac_username_to_id(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:rbac:users:name_to_id"
+
+
+# --------------------------------------------------------------------------- #
+# SuperTable scope — RBAC roles
+# --------------------------------------------------------------------------- #
+
+def rbac_role_meta(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:rbac:roles:meta"
+
+
+def rbac_role_index(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:rbac:roles:index"
+
+
+def rbac_role_doc(org: str, sup: str, role_id: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:rbac:roles:doc:{role_id}"
+
+
+def rbac_role_type_index(org: str, sup: str, role_type: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:rbac:roles:type:{role_type}"
+
+
+def rbac_rolename_to_id(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:rbac:roles:name_to_id"
+
+
+# --------------------------------------------------------------------------- #
+# SuperTable scope — staging / pipes
+# --------------------------------------------------------------------------- #
+
+def staging(org: str, sup: str, staging_name: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:staging:{staging_name}"
+
+
+def staging_index(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:staging:meta"
+
+
+def staging_pattern(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:staging:*"
+
+
+def staging_subkey_pattern(org: str, sup: str, staging_name: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:staging:{staging_name}:*"
+
+
+def pipe(org: str, sup: str, staging_name: str, pipe_name: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:staging:{staging_name}:pipe:{pipe_name}"
+
+
+def pipe_index(org: str, sup: str, staging_name: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:staging:{staging_name}:pipe:meta"
+
+
+def pipe_pattern(org: str, sup: str, staging_name: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:meta:staging:{staging_name}:pipe:*"
+
+
+# --------------------------------------------------------------------------- #
+# SuperTable scope — schema / table_names / linked shares
+# --------------------------------------------------------------------------- #
+
+def schema(org: str, sup: str, simple: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:schema:{simple}"
+
+
+def table_names(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:table_names"
+
+
+def linked_share_doc(org: str, sup: str, link_id: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:linked_shares:doc:{link_id}"
+
+
+def linked_share_index(org: str, sup: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:linked_shares:index"
+
+
+# --------------------------------------------------------------------------- #
+# SuperTable scope — monitoring
+# --------------------------------------------------------------------------- #
+
+def monitor(org: str, sup: str, monitor_type: str) -> str:
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:monitor:{monitor_type}"
+
+
+# --------------------------------------------------------------------------- #
+# Wildcard / SCAN helpers used by deletes
+# --------------------------------------------------------------------------- #
+
+def super_table_pattern(org: str, sup: str) -> str:
+    """Matches every key for one supertable (used by delete_super_table)."""
+    return f"{SUPERTABLE_PREFIX}:{org}:{sup}:*"

{supertable-2.0.3 → supertable-2.0.5}/supertable/super_table.py

@@ -13,6 +13,7 @@ from supertable.rbac.user_manager import UserManager
 from supertable.storage.storage_factory import get_storage
 from supertable.storage.storage_interface import StorageInterface
 from supertable.redis_catalog import RedisCatalog
+from supertable.redis_keys import is_reserved_super_name, RESERVED_SUPER_NAMES
 
 
 class SuperTable:
@@ -21,9 +22,20 @@ class SuperTable:
       - Ensures storage backend is available
       - Ensures Redis meta:root exists (no file-based meta)
       - Exposes helper to read heavy simple-table snapshots from MinIO/local via StorageInterface
+
+    Reserved supertable names (e.g. ``_system_``) are rejected up-front
+    so they can never collide with the org-level system scope where the
+    service registry, organization auth tokens, and other system-only
+    state live.
     """
 
     def __init__(self, super_name: str, organization: str):
+        if is_reserved_super_name(super_name):
+            raise ValueError(
+                f"SuperTable name {super_name!r} is reserved and cannot be created. "
+                f"Reserved names: {sorted(RESERVED_SUPER_NAMES)}"
+            )
+
         self.identity = "super"
         self.super_name = super_name
         self.organization = organization