Download api/application_registry.py from fsanyoto/loopable: direct link, hf CLI and curl.
- Browser
- Download file 153 kB
-
https://huggingface.co/spaces/fsanyoto/loopable/resolve/main/api/application_registry.py
- Command line
-
hf download hf://spaces/fsanyoto/loopable/api/application_registry.py
-
curl -L -o application_registry.py https://huggingface.co/spaces/fsanyoto/loopable/resolve/main/api/application_registry.py
153 kB
"""Tenant-level reusable Application assets and deterministic default resolution."""
from __future__ import annotations
import base64
import copy
import hashlib
import json
from core import shares, write_execution
from core.request_timing import raise_if_resource_error
import app_rules
import app_templates as _app_templates
from modules.finance_apps import (finance_application as _finance_application,
finance_applications as _finance_applications,
finance_group as _finance_group)
from modules.finance_spine import fact_specs as _finance_fact_specs
APPLICATION_TYPES = ("chart", "route", "map", "code")
# Finance descriptors remain available to the governed fact routes.
FINANCE_TEMPLATE_KIND = "finance"
_KEY = "applications_v1"
_RECORD_PREFIX = "applications_v1_app/"
#: D-8392 (R58): the most live Apps one account may create. The cap counts per account, never per tenant.
_MAX = 500
_MAX_DISPLAY_BYTES = 512 * 1024
# Routing and Catalog are the first authored App templates. These are wire contracts, not
# executable module declarations: the client renders a trusted platform surface from the stored
# definition. ``required`` is consumed by the creation flow and enforced again below, so a
# future client cannot weaken a template by skipping a wizard step.
_TEMPLATE_CONTRACTS = {
"route": {
"kind": "route",
"label": "Routing",
"applicationType": "route",
"displayMode": "map",
"fieldRoles": [
{"key": "title", "label": "Record title", "required": True, "types": []},
{"key": "latitude", "label": "Latitude", "required": False,
"types": ["text", "int", "currency", "pct", "rating", "number", "float", "decimal"]},
{"key": "longitude", "label": "Longitude", "required": False,
"types": ["text", "int", "currency", "pct", "rating", "number", "float", "decimal"]},
{"key": "address", "label": "Address", "required": False,
"types": ["text"]},
],
"defaultPlacement": {"section": "app", "order": 0},
},
"catalog": {
"kind": "catalog",
"label": "Catalog",
# Catalog is a template discriminator over an existing trusted renderer contract. The
# client launches the Catalog surface from ``templateKind`` without growing the type
# vocabulary shared by the registry and its consumers.
"applicationType": "map",
"displayMode": "map",
"fieldRoles": [
{"key": "key", "label": "Record key", "required": True, "types": []},
{"key": "title", "label": "Record title", "required": True, "types": []},
{"key": "image", "label": "Image", "required": False,
"types": ["image", "attachment", "url", "text"]},
{"key": "sku", "label": "SKU", "required": False, "types": []},
{"key": "price", "label": "Price", "required": False,
"types": ["int", "currency", "pct", "rating", "number", "float", "decimal"]},
{"key": "category", "label": "Category", "required": False, "types": []},
{"key": "description", "label": "Description", "required": False, "types": []},
],
"defaultPlacement": {"section": "app", "order": 0},
},
}
# C1 (S79-T01): every contract carries its catalogue row's wire metadata.
_C1_WIRE_KEYS = ("connector", "connectors", "purpose", "process", "mark", "view")
# R33: Routing and Catalog read their C1 source themselves, so the wizard asks for no database.
_BUNDLED_SOURCE_LABELS = {"customer_data": "Odoo customers", "product_data": "Odoo products"}
for _kind, _contract in _TEMPLATE_CONTRACTS.items():
_contract.update({key: _app_templates.BY_KIND[_kind][key] for key in _C1_WIRE_KEYS})
_contract.update(sourceDatabase=_app_templates.source(_kind),
sourceLabel=_BUNDLED_SOURCE_LABELS[_app_templates.source(_kind)])
# Keep stored copy identities readable after a template stops accepting new Apps.
APPLICATION_WIZARD_TEMPLATE_KINDS = tuple(_TEMPLATE_CONTRACTS)
APPLICATION_TEMPLATE_KINDS = tuple(_TEMPLATE_CONTRACTS)
#: S78-T17 (C4, R20, R21): templates offered only to a tenant that passes the kind's gate.
#: They stay out of the ungated tuples above, which other gates pin to Routing and Catalog.
#: S79-T01 (C1): every connector-gated kind in `app_templates.TEMPLATES` is one of them.
BRAND_ANALYTICS_DATABASE = "ut_amzn_brand_analytics"
# Wire fields a C1 row does not carry, per gated kind.
_GATED_WIRE = {
"competitor_watch": {
"fieldRoles": [
{"key": "term", "label": "Search term", "required": True, "types": []},
],
"sourceLabel": "Amazon brand analytics",
},
}
def _source_label(database):
"""The connector table's label, so a refusal never names a `ut_` key."""
try:
from core import connector_spec
return connector_spec.spec_for(database).label
except Exception: # noqa: BLE001
return None
def _gated_contract(row):
# The screen reads the kind's own routes; the source names its connector database.
if not _app_templates.validate_connectors(row):
raise ValueError("An App template omits a source connector.")
contract = {"kind": row["kind"], "label": row["label"],
"applicationType": "map", "displayMode": "map", "fieldRoles": [],
"defaultPlacement": {"section": "app", "order": 0},
**{key: row[key] for key in _C1_WIRE_KEYS}}
if row["sources"]:
contract["sourceDatabase"] = row["sources"][0]
contract["sourceLabel"] = _source_label(row["sources"][0])
contract.update(copy.deepcopy(_GATED_WIRE.get(row["kind"], {})))
return contract
_GATED_TEMPLATE_CONTRACTS = {row["kind"]: _gated_contract(row) for row in _app_templates.TEMPLATES
if row["kind"] not in _TEMPLATE_CONTRACTS}
GATED_TEMPLATE_KINDS = tuple(_GATED_TEMPLATE_CONTRACTS)
def _template_contract(kind):
"""The contract for an ungated or gated template kind, or None."""
return _TEMPLATE_CONTRACTS.get(kind) or _GATED_TEMPLATE_CONTRACTS.get(kind)
def brand_analytics_holds(connected, enabled, refused):
"""R21: Amazon is connected, brand analytics is switched on and Amazon has not refused it."""
return connected is True and enabled is True and refused is not True
def _brand_analytics_refused(runtime):
"""True when the mirror's last brand analytics pass was refused; unreadable is no evidence."""
try:
import duckdb
from pathlib import Path
from harness import amazon_store as az, datastore
path = az._tenant_mirror_path(runtime.key, rt=runtime)
if not path.is_file():
return False
query = "SELECT phase FROM _sync_state WHERE entity = ?"
key = [az.entity_key("brand_analytics")]
if path.resolve() == Path(datastore.DB_PATH).resolve():
row = datastore.ro_cursor().execute(query, key).fetchone()
else:
with datastore.bounded_connection(duckdb.connect(str(path), read_only=True)) as cursor:
row = cursor.execute(query, key).fetchone()
return bool(row) and row[0] == "refused"
except Exception as exc: # noqa: BLE001
raise_if_resource_error(exc)
return False
def brand_analytics_offered(session):
"""R21 gate for the Competitor watch template. Any read failure withholds the template."""
try:
import connectors_amazon as cx
from routes_connectors import _entry_types
types, _scopes, failure = _entry_types(session.runtime, session.uname)
connected = failure is None and cx.ENTRY_TYPE in set(types)
enablement = cx.read_database_enablement(session.runtime)
enabled = (enablement.get("available") is True
and (enablement.get("databases") or {}).get(BRAND_ANALYTICS_DATABASE) is True)
refused = _brand_analytics_refused(session.runtime) if connected and enabled else None
return brand_analytics_holds(connected, enabled, refused)
except Exception as exc: # noqa: BLE001
raise_if_resource_error(exc)
return False
def _connector_gate(connector):
"""C1 gate: the reader has the kind's connector (F25: the connector key, never a `ut_` prefix)."""
def gate(session):
return _app_templates.connector_present(connector, session)
gate.connector = connector
return gate
def _automation_offered(session):
"""Use Automation's current account and tenant wall without a connector requirement."""
try:
session.require("automation")
return True
except Exception as exc:
raise_if_resource_error(exc)
return False
# Competitor watch's gate already requires the Amazon connection; it adds brand analytics (R21).
_TEMPLATE_GATES = {kind: brand_analytics_offered if kind == "competitor_watch"
else _automation_offered if kind == "alerts"
else _connector_gate("amazon") if kind == "amazon_operator"
else _connector_gate(contract["connector"])
for kind, contract in _GATED_TEMPLATE_CONTRACTS.items()}
#: S79-T02 (instr 20): Routing and Catalog are offered only to a reader with Odoo.
_BUNDLED_GATES = {kind: _connector_gate(contract["connector"])
for kind, contract in _TEMPLATE_CONTRACTS.items()}
def template_offered(kind, session):
"""C1 offer predicate: the module imports, the router mounted and the kind's gate holds."""
gate = _TEMPLATE_GATES.get(kind) or _BUNDLED_GATES.get(kind)
if gate is None or _app_templates.held(kind) or not _app_templates.seams_ready(kind):
return False
try:
return bool(gate(session))
except Exception as exc: # noqa: BLE001
raise_if_resource_error(exc)
return False
class ApplicationError(ValueError):
pass
def account_capacity():
"""The per-account App cap. `AIOS_APP_CAPACITY` lowers it for one server, as a lane proof does."""
import os
raw = str(os.environ.get("AIOS_APP_CAPACITY") or "").strip()
return min(int(raw), _MAX) if raw.isdigit() else _MAX
def capacity_refusal(doc, user):
"""D-8392: the sentence naming the cap when `user` already holds it, else None."""
cap = account_capacity()
held = sum(1 for app in (doc.get("applications") or {}).values()
if isinstance(app, dict) and app.get("createdBy") == user and app.get("retired") is not True)
if held < cap:
return None
return f"Your account can hold up to {cap} App{'' if cap == 1 else 's'}. Delete an App to add another."
class ApplicationRuleError(ApplicationError):
"""Expose an App rule refusal through every writer's existing error handler."""
code = "app_rule"
def __init__(self, refusal):
self.rule = refusal.rule
super().__init__(str(refusal))
APP_EXISTS_MESSAGE = "This App is already in this workspace. Ask its owner to share it."
class ApplicationExistsError(ApplicationError):
"""A live copy of this template App is in the tenant and the caller may not read it."""
code = "template_app_exists"
def __init__(self, existing=None):
super().__init__(APP_EXISTS_MESSAGE)
self.existing = existing
class _TemplateHeld(Exception):
"""A live copy of the template App holds the tenant's one slot."""
def __init__(self, live):
super().__init__("template App exists")
self.live = live
def template_identity(app):
"""Return the grouping key for template copies, including each separate Finance template."""
if not isinstance(app, dict):
return None
kind = str(app.get("templateKind") or "")
if kind == FINANCE_TEMPLATE_KIND:
key = str(app.get("financeKey") or "")
return f"{FINANCE_TEMPLATE_KIND}:{key}" if key else None
# S79-T05: a connector-gated copy is grouped too, so the App directory can show Added.
return kind if kind in APPLICATION_WIZARD_TEMPLATE_KINDS + GATED_TEMPLATE_KINDS else None
def _refuse_template_held(applications, identity):
"""Raise `_TemplateHeld` with every live copy of `identity`, oldest first, when one exists."""
if not identity:
return
live = sorted((app for app in applications.values()
if isinstance(app, dict) and app.get("retired") is not True
and template_identity(app) == identity),
key=lambda app: (str(app.get("createdAt") or ""), str(app.get("id") or "")))
if live:
raise _TemplateHeld(live)
def _sole_holder(app, copies):
"""True when every other live copy of `app`'s template is its creator's own and unshared.
Only then does a tenant share list no account a second copy of the template.
"""
creator = app.get("createdBy")
return all(other.get("id") == app.get("id")
or (other.get("createdBy") == creator
and (other.get("share") or {}).get("mode") != "tenant"
and not (other.get("share") or {}).get("users"))
for other in copies)
def own_template_apps(runtime, user, is_admin=False):
"""Return every template copy the App home lists for the caller, grouped by template identity.
`is_admin` stays for the callers and is unused: the gallery's Added and the App home share `_listed`.
"""
owned = {}
apps = sorted((app for app in load(runtime)["applications"].values() if isinstance(app, dict)),
key=lambda app: (str(app.get("createdAt") or ""), str(app.get("id") or "")))
for app in apps:
identity = template_identity(app)
if identity and _listed(app, user):
owned.setdefault(identity, []).append(
{"id": app.get("id"), "name": app.get("name"),
"deepLink": app.get("deepLink"), "sourceDatabase": app.get("sourceDatabase")})
return owned
def template_contracts(session=None):
"""The trusted renderer contracts offered by the Application creation flow.
With a session, every template is offered only when the reader has its connector (instr 20).
"""
if session is None:
return _ungated_template_contracts()
have = _app_templates.connectors_present(session)
rows = [copy.deepcopy(contract) for contract in _TEMPLATE_CONTRACTS.values()
if contract["connector"] in have]
rows.extend(copy.deepcopy(contract) for kind, contract in _GATED_TEMPLATE_CONTRACTS.items()
if template_offered(kind, session))
return rows
def _ungated_template_contracts():
return [copy.deepcopy(contract) for contract in _TEMPLATE_CONTRACTS.values()]
def finance_group():
"""The one immutable Finance group consumed by navigation and direct-link routes."""
return _finance_group()
def finance_applications(may_open=None):
"""Six separately addressable Finance application descriptors."""
return _finance_applications(may_open=may_open)
def finance_application_records(may_open=None):
"""Keep the retired Finance App projection empty for legacy callers."""
return []
_FINANCE_SCOPES = {"business_unit", "hq_consolidated", "all_channel_inventory"}
def _require_unavailable(value, context):
if not isinstance(value, dict) or value.get("state") != "unavailable":
raise RuntimeError(f"{context} must be explicitly unavailable")
if "value" in value or not value.get("missingSource"):
raise RuntimeError(f"{context} cannot fabricate a missing value")
def validate_finance_application_contract(app):
"""Fail closed when an app bypasses its declared workflow/dashboard or fact boundary."""
key = str(app.get("key") or "unknown")
mode = app.get("mode")
worklist = app.get("worklist")
dashboard = app.get("dashboard")
fact_keys = set(app.get("factKeys") or ())
if mode not in {"workflow", "dashboard"}:
raise RuntimeError(f"invalid Finance application mode for {key}")
if mode == "workflow":
if not isinstance(worklist, dict) or dashboard:
raise RuntimeError(f"invalid Finance worklist contract for {key}")
source_fact = worklist.get("sourceFact")
if source_fact:
if source_fact not in fact_keys:
raise RuntimeError(f"invalid Finance worklist source for {key}")
required = ("ownerField", "statusField", "dueDateField", "nextAction")
if not all(worklist.get(name) for name in required):
raise RuntimeError(f"incomplete Finance worklist fields for {key}")
elif worklist.get("kind") == "unavailable_requirements":
signals = worklist.get("signals")
if not isinstance(signals, list) or not signals:
raise RuntimeError(f"Finance requirements worklist {key} has no signals")
for signal in signals:
_require_unavailable(signal, f"Finance work signal in {key}")
if signal.get("scope") not in _FINANCE_SCOPES:
raise RuntimeError(f"Finance work signal in {key} has no governed scope")
if not all(signal.get(name) for name in (
"key", "label", "basisLabel", "sourceModule", "validationMethod",
"ownerRole", "status", "nextAction")):
raise RuntimeError(f"Finance work signal in {key} is ungrounded")
if signal.get("status") != "unavailable":
raise RuntimeError(f"Finance work signal in {key} claims executable state")
else:
raise RuntimeError(f"Finance worklist {key} has no governed source")
elif worklist or not isinstance(dashboard, dict):
raise RuntimeError(f"invalid Finance dashboard contract for {key}")
for section in (dashboard or {}).get("sections", []):
for metric in section.get("metrics", []):
if metric.get("sourceFact") and metric["sourceFact"] not in fact_keys:
raise RuntimeError(f"dashboard {key} references an ungoverned source fact")
if metric.get("state") == "unavailable":
_require_unavailable(metric, f"dashboard metric in {key}")
if metric.get("scope") not in _FINANCE_SCOPES:
raise RuntimeError(f"dashboard metric in {key} has no governed scope")
if not metric.get("basisLabel") or not metric.get("validationMethod"):
raise RuntimeError(f"dashboard metric in {key} is ungrounded")
for row in section.get("rows", []):
for column in ("actual", "budget", "prior"):
cell = row.get(column) or {}
if cell.get("state") == "fact" and cell.get("factKey") not in fact_keys:
raise RuntimeError(f"dashboard {key} references an ungoverned fact")
for row in section.get("planningRows", []):
if row.get("scope") not in _FINANCE_SCOPES or not row.get("basisLabel"):
raise RuntimeError(f"planning row in {key} is ungrounded")
actual = row.get("actual") or {}
if actual.get("state") != "fact" or actual.get("factKey") not in fact_keys:
raise RuntimeError(f"planning row in {key} references an ungoverned actual")
for column in ("plan", "variance", "driver"):
_require_unavailable(row.get(column), f"planning {column} in {key}")
return True
def finance_application(key, may_open=None):
"""Resolve one Finance application without constructing a Finance-home payload."""
app = _finance_application(key, may_open=may_open)
validate_finance_application_contract(app)
app["facts"] = _finance_fact_specs(app["factKeys"])
app["kpis"] = _finance_fact_specs(app["kpiKeys"])
return app
def blank_doc():
return {"schema": 1, "applications": {}, "defaults": {}}
def _stored_doc(raw):
"""Encode code App bytes for JSONB without changing the public text contract."""
doc = copy.deepcopy(raw)
applications = doc.get("applications") if isinstance(doc, dict) else None
for app in (applications or {}).values():
if not isinstance(app, dict) or app.get("type") != "code":
continue
display = (app.get("config") or {}).get("display") or {}
html = display.get("html")
if isinstance(html, str):
display["html"] = {"encoding": "utf8-base64-v1",
"data": base64.b64encode(html.encode("utf-8")).decode("ascii")}
return doc
def _update_document(runtime, mutate, *, key=_KEY):
"""Keep every registry write, including migrations, safe for JSONB storage."""
def apply(raw):
return _stored_doc(mutate(raw))
return runtime.update(key, apply)
def _clean_doc(raw):
doc = blank_doc()
if isinstance(raw, dict):
if isinstance(raw.get("applications"), dict):
doc["applications"] = copy.deepcopy(raw["applications"])
if isinstance(raw.get("defaults"), dict):
doc["defaults"] = copy.deepcopy(raw["defaults"])
if isinstance(raw.get("migrations"), dict):
doc["migrations"] = copy.deepcopy(raw["migrations"])
for app in doc["applications"].values():
if not isinstance(app, dict) or app.get("type") != "code":
continue
display = (app.get("config") or {}).get("display") or {}
html = display.get("html")
if (isinstance(html, dict) and set(html) == {"encoding", "data"}
and html["encoding"] == "utf8-base64-v1"):
display["html"] = base64.b64decode(html["data"], validate=True).decode("utf-8")
return doc
def _app_projection(app):
row = _app_templates.bound(app)
if isinstance(row, dict):
contract = _template_contract(str(row.get("templateKind") or ""))
if contract and contract.get("view") and not contract.get("fieldRoles"):
row = dict(row)
row.setdefault("fieldMap", {})
return row
def _record_documents(runtime):
"""Read independent App records through the tenant's existing document doors."""
listing = getattr(runtime, "list_keys", None)
if not callable(listing):
return {} # Legacy stores without document enumeration retain their original format.
keys = listing(_RECORD_PREFIX)
reader = getattr(runtime, "get_many", None)
records = reader(keys) if keys and callable(reader) else None
if records is None:
records = {key: _read_strict(runtime, key) for key in keys}
result = {}
for key in keys:
doc = _clean_doc(records.get(key))
if len(doc["applications"]) > 1:
raise ApplicationError("an App record must contain one App")
for identity, app in doc["applications"].items():
if (not isinstance(app, dict) or app.get("id") != identity
or app.get("tenant") != runtime.key):
raise ApplicationError("the App record does not match its tenant")
result[key] = doc
return result
def _application_key(runtime, app_id):
for key, doc in _record_documents(runtime).items():
if app_id in doc["applications"]:
return key
return _KEY
def _request_memo():
"""`(accumulator, table, epoch)` for one registry read per request, or None outside a request.
The epoch is taken before the read: a store write moves it, so a later load reads again."""
from core import request_timing
acc = request_timing.CURRENT.get()
if acc is None or acc.closed or acc.read_memo_ended:
return None
with acc.lock:
return acc, acc.__dict__.setdefault("application_registry_memo", {}), acc.read_memo_epoch
def load(runtime, *, strict=False):
"""The read door: a Routing or Catalog App carries its C1 binding (`app_templates.bound`)."""
memo, key = _request_memo(), (getattr(runtime, "key", None), id(runtime))
if memo is not None:
acc, table, epoch = memo
with acc.lock:
hit = table.get(key)
if hit and hit[0] == epoch == acc.read_memo_epoch:
return copy.deepcopy(hit[1])
try:
doc = _clean_doc(runtime.get(_KEY))
for record in _record_documents(runtime).values():
doc["applications"].update(record["applications"])
except Exception as exc:
if strict:
raise
raise_if_resource_error(exc)
return blank_doc()
doc["applications"] = {app_id: _app_projection(app)
for app_id, app in doc["applications"].items()}
if memo is not None:
with acc.lock:
table[key] = (epoch, copy.deepcopy(doc))
return doc
_AVAILABILITY_MESSAGES = {
"router_unavailable": "This App cannot open because its routes are unavailable.",
"no_grant": "Your access limit prevents this App from reading its source.",
"not_connected": "Connect the App's connector in Connectors to open this App.",
"refreshing": "This App's source is refreshing and opens when the refresh ends",
"no_rows": "This App has no source rows yet.",
"source_unavailable": "This App cannot read its source right now.",
"held": "This App is not available yet.",
}
def availability_reason(state, connector=None):
"""The public reason vocabulary contains no exception or configuration text."""
message = _AVAILABILITY_MESSAGES.get(state)
if state == "not_connected":
label = {"amazon": "Amazon", "amazon_ads": "Amazon Ads", "odoo": "Odoo"}.get(connector)
if label:
message = f"Connect {label} in Connectors to open this App."
return {"state": state, "message": message,
"lock": "Access limit" if state == "no_grant" else None}
def _mount_reason(kind):
catalogue = _app_templates.BY_KIND.get(str(kind or ""))
if catalogue and catalogue["router"] in _app_templates.router_failures():
return availability_reason("router_unavailable")
return None
def _source_rows_exist(session, sources):
"""Probe at most one row per declared mirror source in the session's tenant."""
import contextlib
import stat
import duckdb
from pathlib import Path
from core import connector_spec
from harness import amazon_store, datastore
specs = [connector_spec.spec_for(source) for source in sources]
if any(spec is None for spec in specs):
raise RuntimeError("App source is not a declared mirror table")
path = amazon_store._tenant_mirror_path(session.tenant, rt=session.runtime)
try:
mode = path.stat().st_mode
except FileNotFoundError:
return False
if not stat.S_ISREG(mode):
raise RuntimeError("App mirror is not a database file")
shared = path.resolve() == Path(datastore.DB_PATH).resolve()
cursor = (datastore.ro_cursor() if shared else
datastore.bounded_connection(duckdb.connect(str(path), read_only=True)))
with contextlib.closing(cursor):
for spec in specs:
present = cursor.execute(
"SELECT 1 FROM information_schema.tables WHERE table_schema = 'main' "
"AND table_name = ? LIMIT 1", [spec.source]).fetchone()
if present:
table = '"' + spec.source.replace('"', '""') + '"'
if cursor.execute(f"SELECT 1 FROM {table} LIMIT 1").fetchone():
return True
return False
def _reports_readable(runtime, user, is_admin):
"""Report grants admit the Reports App independently of its App sharing record."""
try:
from modules import reports
except Exception as exc: # A failed Reports import withholds its App.
raise_if_resource_error(exc)
return False
return bool(is_admin or reports.granted_keys(runtime, user))
def _readable_template_app(session, app_id):
"""Resolve App identity before reading any source or exposing a refusal."""
from deps import err
if (session.tenant != getattr(session.runtime, "key", None)
or session.tenant != getattr(getattr(session.runtime, "tenant", None), "key", None)):
raise err(404, "app_not_found", "This App is unavailable or is not shared with you.")
try:
app = load(session.runtime, strict=True)["applications"].get(app_id)
except Exception:
raise err(503, "app_unavailable", "This App cannot be read right now.") from None
if (not isinstance(app, dict) or app.get("id") != app_id or app.get("tenant") != session.tenant
or app.get("retired") is True
or not (_reports_readable(session.runtime, session.uname, session.admin)
if app.get("templateKind") == "reports"
else may_read(app, session.uname, session.admin))):
raise err(404, "app_not_found", "This App is unavailable or is not shared with you.")
kind = app.get("templateKind")
catalogue = _app_templates.BY_KIND.get(str(kind or ""))
if not catalogue or not catalogue["view"]:
raise err(404, "app_not_found", "This App is unavailable or is not shared with you.")
if kind == "alerts":
session.require("automation")
return app, catalogue
#: R62: App kinds whose readers apply a source row and field wall to their own rows.
#: Any other kind refuses its App while such a wall applies, because it cannot narrow.
NARROWING_KINDS = frozenset({"account_health", "opportunity_finder", "ranking_diagnostic", "repeat_buyers"})
def app_access(user, runtime, app, sources):
"""R46, R62: the one source-wall answer for an App, its Dashboard and its readers.
Takes a user record, not a session, so a digest can ask for any recipient. Returns
`app` and `dashboard` ("ready" or refused), the Dashboard refusal's `status`, `code`
and one-line `message`, and `narrow`: per source, the row wall and hidden field keys.
"""
from core import perm_scope, perms, route_system, user_tables
from core.request_timing import remaining_budget
user = user if isinstance(user, dict) else {}
kind = app.get("templateKind") if isinstance(app, dict) else None
granted = may_read(app, user.get("username"), perms.is_admin(user))
refusal = []
def refuse(status, code, message):
refusal.append((status, code, message))
all_units = "All" in perms.allowed_bu_labels(user)
raw_units = user.get("bus", "all")
if raw_units != "all":
from core import users
by_label = {label: key for key, label in users.BU_LABELS.items()}
identities = []
valid_units = isinstance(raw_units, (tuple, list)) and bool(raw_units)
for unit in raw_units if valid_units else ():
if type(unit) is int and unit in users.BU_LABELS:
identities.append(unit)
elif isinstance(unit, str) and unit in by_label:
identities.append(by_label[unit])
elif unit != "All":
valid_units = False
all_units = bool(valid_units and identities) and "All" in perms.allowed_bu_labels(dict(user, bus=identities))
if not all_units:
refuse(403, "app_dashboard_scope", "The Dashboard needs access to every business unit.")
elif perms.scope_agent(user) is not None:
refuse(403, "app_dashboard_scope", "The Dashboard needs access to every salesperson's records.")
if not isinstance(sources, (tuple, list)) or not sources:
refuse(503, "app_dashboard_sources", "The Dashboard has no source to read.")
sources = ()
config = getattr(getattr(runtime, "tenant", None), "config", None) or {}
enabled = config.get("modules", "all")
narrow = {}
for source in sources:
remaining_budget()
label = _source_label(source) or "a source database"
definition = user_tables.get_definition(source, st=runtime)
fields = definition.get("fields") if isinstance(definition, dict) else None
declared = perm_scope.entry(user, source) or {}
walled = bool(perm_scope.wall_declared(user, source, st=runtime, defn=definition))
rows = bool(declared.get("filter")) or bool(
fields and perm_scope.row_scope_applies(user, source, st=runtime, defn=definition))
hidden = set(declared.get("hiddenFields") or ()) | set(
perm_scope.hidden_keys(user, source, fields, st=runtime) if fields else ())
narrow[source] = {"rows": rows or (walled and not hidden), "hidden": tuple(sorted(map(str, hidden)))}
# The Dashboard totals the raw source, so it keeps the source grant and refuses any narrowing.
if (enabled != "all" and source not in (enabled or ())) or not perm_scope.may_read(user, source, st=runtime):
refuse(403, "app_dashboard_source", f"The Dashboard needs read access to {label}.")
elif not fields:
refuse(503, "app_dashboard_source", f"The Dashboard cannot read {label} right now.")
elif (declared.get("access") is False or walled or rows or hidden
or route_system.is_managed(definition) or route_system.is_managed(source)):
refuse(403, "app_dashboard_scope", f"The Dashboard needs {label} without a row or field limit.")
narrowed = any(wall["rows"] or wall["hidden"] for wall in narrow.values())
status, code, message = refusal[0] if refusal else (None, None, None)
return {"app": "ready" if granted and (kind in NARROWING_KINDS or not narrowed) else "no_grant",
"dashboard": "ready" if not refusal else "refused",
"status": status, "code": code, "message": message, "narrow": narrow}
def app_source_scope(user, runtime, source, *, app, records=None):
"""Return source fields and row identities after live admission of the named App."""
from core import perm_scope
# Importing the API adapter registers the core admission callback.
import routes_app_dashboard
fields, rows = perm_scope.scoped_app_source(
user, source, st=runtime, app_id=app.get("id") if isinstance(app, dict) else None, records=records)
identity = "__scope_key" if records is not None else "pid"
return {str(field["key"]) for field in fields if field.get("key")}, {
str(row[identity]) for row in rows if identity in row}
def readable_app(runtime, tenant, uname, is_admin, kind):
"""The caller's live readable App of `kind` in `tenant`, their own copy first, or None."""
apps = [row for _key, row in sorted(load(runtime)["applications"].items())
if isinstance(row, dict) and row.get("templateKind") == kind and row.get("tenant") == tenant
and row.get("retired") is not True and may_read(row, uname, is_admin)]
return next((row for row in apps if row.get("createdBy") == uname), apps[0] if apps else None)
def admit_app(session, app, sources, *, code):
"""R62: admit an App read on the App grant plus `app_access`, never the source open grant."""
from deps import err
if (session.tenant != getattr(session.runtime, "key", None)
or session.user.get("tenant", session.tenant) != session.tenant
or not isinstance(app, dict) or app.get("tenant") != session.tenant
or app.get("retired") is True or not may_read(app, session.uname, session.admin)):
raise err(404, f"{code}_app_not_found", "This App is unavailable or is not shared with you.")
access = app_access(session.user, session.runtime, app, sources)
if access["app"] != "ready":
raise err(403, f"{code}_limited", "This App cannot apply your access limit on its source.")
return access
def _availability_for_app(session, app, catalogue):
kind = app["templateKind"]
if _app_templates.held(kind):
return availability_reason("held")
mount = _mount_reason(kind)
if mount:
return mount
if not _app_templates.seams_ready(kind):
return availability_reason("router_unavailable")
if kind == "alerts":
return availability_reason("ready" if _automation_offered(session) else "no_grant")
from routes_connectors import _entry_types
amazon = catalogue.get("connector") in ("amazon", "amazon_ads")
dashboard = {"state": "source_unavailable", "message": _AVAILABILITY_MESSAGES["source_unavailable"]}
def reason(state, connector=None):
result = availability_reason(state, connector)
return {**result, "dashboard": dashboard} if amazon else result
try:
sources = catalogue["sources"]
if amazon:
# Availability and the Dashboard use one source-wall answer.
access = app_access(session.user, session.runtime, app, sources)
dashboard = {"state": "ready" if access["dashboard"] == "ready" else
"no_grant" if access["status"] == 403 else "source_unavailable",
"message": access["message"]}
if access["app"] != "ready":
return reason("no_grant")
else:
from core import perm_scope
for source in sources:
if (not perm_scope.may_read(session.user, source, st=session.runtime)
or perm_scope.wall_declared(session.user, source, st=session.runtime)):
return reason("no_grant")
types, _scopes, failure = _entry_types(session.runtime, session.uname)
if failure is not None:
return reason("source_unavailable")
connected = _app_templates.entry_type(catalogue["connector"]) in set(types or ())
if not connected and catalogue["connector"] == "odoo":
from routes_keychain import env_odoo_available
connected = env_odoo_available(session.runtime)
if not connected:
return reason("not_connected", catalogue["connector"])
row_sources = ((*sources, *catalogue.get("optional_sources", ()))
if kind == "repeat_buyers" else sources)
if amazon:
from harness.mirror_store import restore_in_progress
if restore_in_progress(session.tenant, catalogue["connector"]):
return reason("refreshing")
if row_sources and not _source_rows_exist(session, row_sources):
return reason("no_rows")
except Exception as exc: # noqa: BLE001
if amazon:
raise_if_resource_error(exc)
return reason("source_unavailable")
return reason("ready")
def availability(session, app_id):
"""Resolve a named App without weakening its tenant, sharing or source permissions."""
app, catalogue = _readable_template_app(session, app_id)
return _availability_for_app(session, app, catalogue)
def opening(session, app_id):
"""Return only frame metadata and availability for a standalone template App."""
app, catalogue = _readable_template_app(session, app_id)
return {"application": {
"id": app["id"], "name": app["name"], "templateKind": catalogue["kind"],
"templateView": catalogue["view"], "templateMark": catalogue["mark"],
"templateConnector": catalogue["connector"], "fieldMap": {},
"capabilities": {"read": True, "edit": may_edit(app, session.uname, session.admin)},
}, "availability": _availability_for_app(session, app, catalogue)}
def _server_origin(origin_door=None, via=None):
"""Stamp the authenticated server door without inferring it from a display label."""
door = "app" if origin_door is None and via is None else origin_door
if door not in ("app", "mcp", "loopy"):
raise ApplicationError("Set origin_door from the authenticated call path.")
if door == "mcp":
if not isinstance(via, str) or not via.strip():
raise ApplicationError("An MCP App needs its credential's label.")
label = via
else:
label = "Loopy" if door == "loopy" else "App"
return {"door": door, "label": label}
def count_by_origin(runtime, tenant):
"""Count this tenant's stored Apps per door, treating older Apps as personal builds."""
counts = {"app": 0, "mcp": 0, "loopy": 0}
for app in load(runtime)["applications"].values():
if not isinstance(app, dict) or str(app.get("tenant")) != str(tenant):
continue
origin = app.get("origin")
door = origin.get("door") if isinstance(origin, dict) else "app"
if door in counts:
counts[door] += 1
return counts
def _users(raw):
out=[]
for item in raw if isinstance(raw, (list, tuple)) else ():
got=str(item or "").strip()[:120]
if got and got not in out: out.append(got)
return out
def may_read(app, user, is_admin=False):
if not isinstance(app, dict): return False
if is_admin or app.get("createdBy") == user: return True
share=app.get("share") if isinstance(app.get("share"), dict) else {}
return share.get("mode") == "tenant" or user in set(share.get("users") or ())
def may_edit(app, user, is_admin=False):
return bool(is_admin or (isinstance(app, dict) and app.get("createdBy") == user))
def _listed(app, user):
"""R102: the App home lists what the caller owns or was shared, for an Administrator too."""
if not isinstance(app, dict) or app.get("retired") is True:
return False
if app.get("createdBy") == user:
return True
share = app.get("share") if isinstance(app.get("share"), dict) else {}
return share.get("mode") == "tenant" or user in set(share.get("users") or ())
def _is_finance(app):
return isinstance(app, dict) and app.get("templateKind") == FINANCE_TEMPLATE_KIND
def _database_free_code(app):
"""A code App can open without a database binding."""
return (isinstance(app, dict) and app.get("type") == "code"
and not app.get("compatibleDatabases"))
def _database_free(app):
"""A code App, or an App whose C1 kind names no source, opens without a database binding."""
if _database_free_code(app):
return True
row = _app_templates.BY_KIND.get(str(app.get("templateKind") or "")) if isinstance(app, dict) else None
return bool(row and not row["sources"] and not app.get("compatibleDatabases"))
def _finance_permission(app):
try:
return _finance_application(str(app.get("financeKey") or ""))["permissionKey"]
except KeyError:
return None
def _account_wall(runtime, user_record):
"""The `deps.Session.require` predicate for one account, without a request."""
from core import perm_scope
config = getattr(getattr(runtime, "tenant", None), "config", None) or {}
modules = config.get("modules", "all") if isinstance(config, dict) else "all"
def may_open(key):
if not perm_scope.nav_may_open(user_record, key, st=runtime):
return False
return modules == "all" or str(key) in {str(item) for item in (modules or [])}
return may_open
def _user_wall(runtime, user):
"""Resolve one username's wall from the account registry; fail closed on any read error."""
try:
from core import users
record = (users.registry() or {}).get(user)
if not isinstance(record, dict) or record.get("active") is False:
return lambda _key: False
public = users._public(user, record)
if public.get("tenant") != getattr(runtime, "key", None):
return lambda _key: False
return _account_wall(runtime, public)
except Exception:
return lambda _key: False
def _compat(raw, *, allow_empty=False):
values=[]
for item in raw if isinstance(raw, (list, tuple)) else ():
key=str(item or "").strip()[:120]
if key and key not in values: values.append(key)
if not values and not allow_empty:
raise ApplicationError("at least one compatible database is required")
return values
def _governed_bindings(raw, compatible, semantic_records):
"""Normalize role -> database -> approved field, refusing optimistic bindings."""
if raw in (None, {}):
return {}
if not isinstance(raw, dict):
raise ApplicationError("semanticRoleBindings must be an object")
compatible = tuple(compatible or ())
out = {}
for raw_role, raw_binding in raw.items():
role = str(raw_role or "").strip()[:80]
if not role or not isinstance(raw_binding, dict):
raise ApplicationError("every semantic role needs a binding object")
# The first Wave shape was one flat binding. Admit it only for one compatible database,
# then store the canonical per-database shape.
if "field" in raw_binding:
database = str(raw_binding.get("database") or "").strip()
if not database and len(compatible) == 1:
database = compatible[0]
bindings = {database: raw_binding} if database else {}
else:
bindings = raw_binding
if set(bindings) != set(compatible):
raise ApplicationError(
f"semantic role {role!r} must be confirmed for every compatible database")
per_database = {}
for database in compatible:
binding = bindings.get(database)
if not isinstance(binding, dict) or binding.get("confirmed") is not True:
raise ApplicationError(f"semantic role {role!r} is not confirmed for {database}")
field = str(binding.get("field") or "").strip()[:120]
records = semantic_records.get(database) if isinstance(semantic_records, dict) else None
record = (records or {}).get(f"{database}::{field}") if field else None
if not isinstance(record, dict) or record.get("state") != "approved":
raise ApplicationError(
f"semantic role {role!r} needs an approved field in {database}")
per_database[database] = {"field": field, "confirmed": True}
out[role] = per_database
return out
_CONFIG_MODE = {"chart": "chart", "route": "map", "map": "map", "code": "code"}
def _typed_config(kind, raw):
if not isinstance(raw, dict):
raise ApplicationError("config must be an object")
if set(raw) - {"schemaVersion", "display"}:
raise ApplicationError("config contains fields outside the typed Application contract")
if raw.get("schemaVersion") != 1:
raise ApplicationError("config schemaVersion must be 1")
display = raw.get("display")
if not isinstance(display, dict):
raise ApplicationError("config.display must be an object")
if str(display.get("mode") or "") != _CONFIG_MODE[kind]:
raise ApplicationError(f"{kind} config has the wrong display mode")
if kind == "code":
html = display.get("html")
if not isinstance(html, str):
raise ApplicationError("App HTML must be text.")
try:
size = len(html.encode("utf-8"))
except UnicodeEncodeError:
raise ApplicationError("App HTML must be UTF-8 text.") from None
if size > _MAX_DISPLAY_BYTES:
raise ApplicationError("App HTML exceeds the 512 KB limit.")
return {"schemaVersion": 1, "display": copy.deepcopy(display)}
if kind == "chart":
try:
app_rules.validate_chart_display(display)
except app_rules.RuleError as exc:
raise ApplicationRuleError(exc) from None
if len(json.dumps(display, ensure_ascii=False).encode("utf-8")) > _MAX_DISPLAY_BYTES:
raise ApplicationError("The Application's layout is too large to save.")
return {"schemaVersion": 1, "display": copy.deepcopy(display)}
def _allowed(compatible, allowed_databases):
return (set(compatible or ()) if allowed_databases is None
else set(compatible or ()) & set(allowed_databases))
def _contract_fields(database, semantic_records=None, field_contracts=None):
"""Return ``{field key: type}`` from a caller's already permission-scoped contract.
The nav creation door supplies its served schema fields. The older Application door supplies
governed semantic records. Supporting both here keeps one validator while never making this
registry reach around either caller's database/field wall.
"""
fields = {}
raw = ((field_contracts or {}).get(database)
if isinstance(field_contracts, dict) else None)
if isinstance(raw, dict):
raw = list(raw.values())
for row in raw if isinstance(raw, (list, tuple)) else ():
if not isinstance(row, dict):
continue
key = str(row.get("key") or row.get("field") or "").strip()
if key:
fields[key] = str(row.get("type") or row.get("dataType") or "").strip().lower()
# A served schema is authoritative, including an empty or fully hidden field list.
if isinstance(field_contracts, dict) and database in field_contracts:
return fields
records = ((semantic_records or {}).get(database)
if isinstance(semantic_records, dict) else None)
for row in (records or {}).values() if isinstance(records, dict) else ():
if not isinstance(row, dict):
continue
key = str(row.get("field") or row.get("key") or "").strip()
if key and key not in fields:
fields[key] = str(row.get("dataType") or row.get("type") or "").strip().lower()
return fields
class _ChartSchemaReader:
"""Keep schema reads on metadata doors, including inside a write preview."""
def __init__(self, runtime):
self._runtime = runtime
self.schema_only = bool(getattr(runtime, "schema_only", False))
def __getattr__(self, name):
return getattr(self._runtime, name)
def get(self, name, *args, **kwargs):
if self.schema_only and name == "user_tables":
raise AssertionError("chart schema cannot read row documents")
return self._runtime.get(name, *args, **kwargs)
def get_projection(self, name, drop=()):
if self.schema_only and name == "user_tables" and "rows" not in drop:
raise AssertionError("chart schema must omit rows")
return self._runtime.get_projection(name, drop=drop)
def get_entry(self, name, entry):
if self.schema_only and (name == "user_tables" or entry in ("rows", "cells", "overlays")):
raise AssertionError("chart schema cannot read row entries")
return self._runtime.get_entry(name, entry)
def _read_strict(self, name):
if self.schema_only and name == "user_tables":
raise AssertionError("chart schema cannot read row documents")
return self._runtime._read_strict(name)
def chart_field_contracts(session, databases):
"""Borrow the caller's schema door with a strict reader that cannot load row documents."""
from routes_customers import _AssemblyStore
from routes_nav import nav_schema
from core import user_tables
scoped = copy.copy(session)
scoped.runtime = _AssemblyStore(session.runtime, schema_only=True)
# Preview projections load whole documents, so borrow unchanged schema from their source.
if type(session.runtime).__name__ == "_PreviewRuntime":
scoped.runtime = _AssemblyStore(session.runtime._real, schema_only=True)
scoped.runtime = _ChartSchemaReader(scoped.runtime)
contracts = {}
for database in dict.fromkeys(databases or ()):
fields = copy.deepcopy(nav_schema(database, session=scoped)["fields"])
if database.startswith("ut_"):
definitions = user_tables.all_defs(st=scoped.runtime)
declared = {row["key"]: row for row in
(definitions.get(database) or {}).get("fields", [])}
# The schema door chooses readable keys; declarations supply only their options.
for field in fields:
definition = declared.get(field.get("key"), {})
for key in ("options", "choices"):
if key in definition:
field[key] = copy.deepcopy(definition[key])
contracts[database] = fields
return contracts
def _validate_chart_rules(app, *, semantic_records=None, field_contracts=None):
"""Check authored charts against caller-supplied field metadata, never stored row values."""
if app.get("type") != "chart":
return []
display = (app.get("config") or {}).get("display") or {}
if _is_finance(app) and not display.get("charts"):
return []
fields_by_database = {}
for database in app.get("compatibleDatabases") or ():
fields = {}
records = (semantic_records or {}).get(database) or {}
for row in records.values():
if isinstance(row, dict) and row.get("state") == "approved":
key = row.get("field") or row.get("key")
if key:
fields[key] = row
supplied = (field_contracts or {}).get(database) or []
for row in supplied.values() if isinstance(supplied, dict) else supplied:
if isinstance(row, dict):
key = row.get("key") or row.get("field")
if key:
fields[key] = row
fields_by_database[database] = fields
try:
app_rules.validate_text(app.get("name"), "the App name")
app_rules.validate_chart_display(display)
return app_rules.validate_chart_bindings(display, fields_by_database)
except app_rules.RuleError as exc:
raise ApplicationRuleError(exc) from None
def _validate_catalog_rules(app):
"""Check Catalog content on writes while leaving saved records readable unchanged."""
if app.get("templateKind") != "catalog":
return
try:
app_rules.validate_catalog_display(app["config"]["display"])
except app_rules.RuleError as exc:
raise ApplicationRuleError(exc) from None
def _refuse_legacy_catalog_changes(app, config):
"""Freeze the old collection before or after its first migration to independent records."""
if app.get("templateKind") != "catalog":
return
before = (app.get("config") or {}).get("display") or {}
after = config["display"]
# Compare JSON types too, so an authored numeric value cannot silently become a boolean.
if (("catalogs" in before) == ("catalogs" in after)
and json.dumps(before.get("catalogs"), sort_keys=True)
== json.dumps(after.get("catalogs"), sort_keys=True)):
return
raise ApplicationError(
"Catalogs now live in separate records, and config.display.catalogs migrates only once. "
"Existing Catalog Apps cannot change that legacy collection. "
f"Use POST /api/v1/apps/{app['id']}/catalogs or PATCH/DELETE /api/v1/catalogs/{{id}}, "
"or catalog_build, to change catalog records.")
def _template_definition(kind, payload, *, semantic_records=None, field_contracts=None,
allowed_databases=None):
"""R33: a template App binds its C1 source and fixed field map; the caller names neither."""
contract = _TEMPLATE_CONTRACTS.get(kind) or _GATED_TEMPLATE_CONTRACTS.get(kind)
if contract is None:
raise ApplicationError("application template kind is not recognized")
template_kind = str(payload.get("templateKind") or "").strip().lower()
if template_kind != kind:
raise ApplicationError(f"{kind} applications require templateKind {kind!r}")
named = str(payload.get("sourceDatabase") or "").strip()[:120]
source = _app_templates.source(kind) or named
# A C1 kind with no declared sources reads its own routes without a database binding.
sourceless = kind in _app_templates.BY_KIND and not _app_templates.BY_KIND[kind]["sources"]
if sourceless:
if named or payload.get("compatibleDatabases"):
raise ApplicationError(f"{contract['label']} reads no database. Remove the source database.")
elif not source:
raise ApplicationError("sourceDatabase is required")
elif named and named != source:
raise ApplicationError(f"{contract['label']} reads "
f"{contract.get('sourceLabel') or source} only. "
"Choose it as the source database.")
elif source not in set(allowed_databases or ()):
raise PermissionError("an Application cannot bind a database you cannot open")
if not sourceless and "compatibleDatabases" in payload:
compatible = _compat(payload.get("compatibleDatabases"))
if compatible != [source]:
raise ApplicationError("a template Application has exactly one sourceDatabase")
# A legacy caller may still send a field map: the fixed binding replaces it.
binding = {} if sourceless else _app_templates.field_binding(kind)
if binding:
available = _contract_fields(source, semantic_records, field_contracts)
if not available:
raise ApplicationError("the source database has no readable field contract")
unreadable = sorted(role["label"] for role in contract["fieldRoles"]
if role["required"] and binding.get(role["key"]) not in available)
if unreadable:
raise ApplicationError(f"{contract['label']} needs fields your account cannot read: "
+ ", ".join(unreadable) + ". Ask an administrator for access.")
raw_placement = payload.get("navPlacement") or contract["defaultPlacement"]
if not isinstance(raw_placement, dict) or set(raw_placement) != {"section", "order"}:
raise ApplicationError("navPlacement must contain section and order")
section = str(raw_placement.get("section") or "").strip().lower()
order = raw_placement.get("order")
if section != "app":
raise ApplicationError("template Applications must be placed in App")
if isinstance(order, bool) or not isinstance(order, int) or not 0 <= order <= 999:
raise ApplicationError("navPlacement order must be an integer from 0 to 999")
definition = {"templateKind": kind, "compatibleDatabases": [] if sourceless else [source],
"navPlacement": {"section": "app", "order": order}}
if kind not in _app_templates.BOUND_KINDS and not sourceless:
definition.update(sourceDatabase=source, fieldMap=binding)
return definition
def bound_application(app, available):
"""The App with its field map read against the caller's `{field: type}` schema.
A C1 binding drops an optional role the caller cannot read. A stored map stays strict.
"""
stored = bool(isinstance(app, dict) and app.get("fieldMap"))
row = _app_templates.bound(app)
contract = _template_contract(str(row.get("templateKind") or "")) or {}
roles = {role["key"]: role for role in contract.get("fieldRoles") or ()}
resolved = {}
for role, field in (row.get("fieldMap") or {}).items():
spec = roles.get(role)
if spec is None:
raise ApplicationError(f"fieldMap role {role!r} is outside the template contract")
types = set(spec.get("types") or ())
if field in available and (not types or available[field] in types):
resolved[role] = field
elif stored or spec["required"]:
raise ApplicationError(f"fieldMap role {role!r} does not name a readable source field")
return {**row, "fieldMap": resolved}
def validate_application(payload, tenant, *, semantic_records=None, field_contracts=None,
allowed_databases=None):
"""Validate the server-authored identity/tenant envelope and any template definition."""
payload = payload if isinstance(payload, dict) else {}
if "origin" in payload:
raise ApplicationError("Loopable sets origin. Remove origin from the request.")
if payload.get("id") not in (None, ""):
raise ApplicationError("application id is server assigned")
if "tenant" in payload and str(payload.get("tenant") or "") != str(tenant):
raise PermissionError("an Application cannot be created for another tenant")
template_kind = str(payload.get("templateKind") or "").strip().lower()
gated = _GATED_TEMPLATE_CONTRACTS.get(template_kind)
if gated is not None:
if str(payload.get("type") or gated["applicationType"]).strip().lower() != gated["applicationType"]:
raise ApplicationError(
f"{template_kind} template Applications require type {gated['applicationType']!r}")
return _template_definition(
template_kind, payload, semantic_records=semantic_records,
field_contracts=field_contracts, allowed_databases=allowed_databases)
if template_kind and template_kind not in _TEMPLATE_CONTRACTS:
raise ApplicationError("application template kind is not recognized")
expected_type = (_TEMPLATE_CONTRACTS[template_kind]["applicationType"]
if template_kind else "")
kind = str(payload.get("type") or expected_type).strip().lower()
if kind not in APPLICATION_TYPES:
raise ApplicationError("application type is not recognized")
if kind == "chart":
raw_config = payload.get("config")
config = _typed_config(kind, raw_config)
_validate_chart_rules(
{"type": kind, "templateKind": template_kind, "name": payload.get("name"),
"config": config, "compatibleDatabases": payload.get("compatibleDatabases")},
semantic_records=semantic_records, field_contracts=field_contracts)
if template_kind:
if kind != expected_type:
raise ApplicationError(
f"{template_kind} template Applications require type {expected_type!r}")
return _template_definition(
template_kind, payload, semantic_records=semantic_records,
field_contracts=field_contracts, allowed_databases=allowed_databases)
if any(key in payload for key in ("sourceDatabase", "fieldMap", "navPlacement")):
raise ApplicationError("only a template Application may carry template fields")
return {}
def _public(app, user, is_admin=False, *, allowed_databases=None, target_database=None,
is_default=False, readable=None):
row=copy.deepcopy(_app_projection(app))
row.setdefault("origin", None)
if row.get("type") == "code":
# Only the authenticated code door returns the body.
row["config"]["display"].pop("html", None)
compatible = [database for database in row.get("compatibleDatabases") or ()
if database in _allowed(row.get("compatibleDatabases"), allowed_databases)]
row["compatibleDatabases"] = compatible
app_readable = may_read(app, user, is_admin)
row["capabilities"]={"read":app_readable if readable is None else readable,"edit":may_edit(app,user,is_admin),
"share":may_edit(app,user,is_admin),"delete":may_edit(app,user,is_admin),
"duplicate":app_readable,"star":app_readable,
"default":bool(is_admin)}
row["starred"] = user in (app.get("starredBy") or ())
row["isDefault"] = bool(is_default)
catalogue = _app_templates.BY_KIND.get(str(row.get("templateKind") or ""))
if catalogue and catalogue["view"]:
# C2: the client mounts apps/<templateView>/AppView.tsx and fills the two marks.
row.update(templateView=catalogue["view"], templateMark=catalogue["mark"],
templateConnector=catalogue["connector"])
row["deepLink"] = f"/app/template/{row['id']}"
mount = _mount_reason(row.get("templateKind"))
if mount:
row["availability"] = mount
elif (catalogue.get("connector") not in ("amazon", "amazon_ads")
and not _database_free(app) and not compatible):
row["availability"] = availability_reason("no_grant")
if row.get("templateKind") == FINANCE_TEMPLATE_KIND:
# A Finance App is a user's own copy: owner controls apply. Defaults bind a database.
row["capabilities"]["default"] = False
row["isDefault"] = False
if row.get("type") == "code":
row["capabilities"]["default"] = False
target_database = target_database if target_database in compatible else (compatible[0] if compatible else None)
row["openTarget"]={"kind":"application","id":row["id"],"type":row["type"],
"database":target_database}
return row
#: `core.table_store.RESERVED_MEMBERS`: workspace members that are registries, not users.
_RESERVED_WORKSPACE_MEMBERS = ("__shared__", "__assigned__", "__audit__")
def dependent_view_counts(runtime, database):
"""S67-T39 / R36: {app_id: number of saved Views on `database` bound to it}, over EVERY
user's Views in that database's workspace. The Delete App dialog names this count before
confirm. None when the workspace cannot be read, so the dialog never states a guessed 0.
D-2233: it walks the Views `delete` clears, nested and `presentation` ones too, trash excepted.
"""
from core.view_templates import workspace_key
key = workspace_key(database)
if not key:
return {}
try:
doc = runtime.get(key)
except Exception:
return None
counts = {}
users = {member: bucket for member, bucket in (doc.items() if isinstance(doc, dict) else ())
if member not in _RESERVED_WORKSPACE_MEMBERS}
for view in _workspace_views(users, trash=False):
for app_id in _view_app_ids(view):
counts[app_id] = counts.get(app_id, 0) + 1
return counts
def list_apps(runtime, user, is_admin=False, *, database=None, kind=None, starred=None,
allowed_databases=None, may_open=None):
"""List Applications. Unfiltered is the App home; a database filter is how a View resolves."""
doc = load(runtime)
rows=[]
reports_reader = None
for app in doc["applications"].values():
if (isinstance(app, dict) and getattr(runtime, "key", None)
and app.get("tenant") != runtime.key):
continue
if _app_templates.held(app):
continue
if (isinstance(app, dict) and app.get("templateKind") == "alerts"
and not (may_open or _user_wall(runtime, user))("automation")):
continue
report_app = isinstance(app, dict) and app.get("templateKind") == "reports"
if report_app:
if reports_reader is None:
reports_reader = _reports_readable(runtime, user, is_admin)
if not reports_reader or app.get("retired") is True:
continue
if isinstance(app, dict) and app.get("templateKind") in ("customer_card", FINANCE_TEMPLATE_KIND):
continue
if database:
# A View resolves its App only through this read, so a retired seed stays listed here.
if not report_app and not may_read(app,user,is_admin): continue
if database not in (app.get("compatibleDatabases") or ()): continue
elif not report_app and not _listed(app, user): continue
if (not _database_free(app)
and not _allowed(app.get("compatibleDatabases"), allowed_databases)):
catalogue = _app_templates.BY_KIND.get(str(app.get("templateKind") or ""))
# An owned or shared template may explain a lost source grant without serving data.
if database or not catalogue or not catalogue["view"]:
continue
if kind and app.get("type") != kind: continue
if starred is not None and bool(user in (app.get("starredBy") or ())) != bool(starred): continue
default_key = f"{database}::{app.get('type')}" if database else ""
rows.append(_public(app,user,is_admin,allowed_databases=allowed_databases,
target_database=database,
readable=True if report_app else None,
is_default=bool(default_key and doc["defaults"].get(default_key)==app.get("id"))))
# S67-T39: the dependent-View count rides a DATABASE-filtered read only, and only for rows
# the caller may delete, so the unfiltered nav read (App home tiles) pays nothing for it.
deletable = [row for row in rows if row["capabilities"].get("delete")]
if database and deletable:
counts = dependent_view_counts(runtime, database)
for row in deletable:
row["dependentViews"] = None if counts is None else counts.get(row["id"], 0)
return sorted(rows,key=lambda x:(str(x.get("updatedAt") or ""),str(x.get("id"))),reverse=True)
def _nav_placement(app, index):
"""Put default Project manager entries first without rewriting stored placements."""
placement = app.get("navPlacement")
# Every install stores the template default {"section": "app", "order": 0}, so order 0 is the
# default here, not a choice; any other stored placement wins.
if (app.get("templateKind") == "amazon_profit"
and (not placement or placement == {"section": "app", "order": 0})):
return {"section": "app", "order": -1}
return placement or {"section": "app", "order": index}
def nav_applications(runtime, user, is_admin=False, *, may_open=None, allowed_databases=None):
"""The App home read: stored records the caller owns or was shared, never a code projection."""
return [{"id": app["id"], "name": app.get("name"),
"type": app.get("type"), "templateKind": app.get("templateKind"),
"templateConnector": (_app_templates.BY_KIND.get(
str(app.get("templateKind") or "")) or {}).get("connector"),
"deepLink": app.get("deepLink"),
"origin": "tenant",
"compatibleDatabases": app.get("compatibleDatabases") or [],
"openTarget": app.get("openTarget"),
"navPlacement": _nav_placement(app, index),
"capabilities": app.get("capabilities"), "starred": app.get("starred"),
"isDefault": app.get("isDefault")}
for index, app in enumerate(list_apps(runtime, user, is_admin,
allowed_databases=allowed_databases,
may_open=may_open))]
def _build_application(tenant, user, payload, *, semantic_records=None, field_contracts=None,
allowed_databases=None, origin_door=None, via=None):
"""Build the same validated record for authored Apps and boot migrations."""
payload=payload if isinstance(payload,dict) else {}
template_kind=str(payload.get("templateKind") or "").strip().lower()
expected_type = (_template_contract(template_kind) or {}).get("applicationType")
kind=str(payload.get("type") or expected_type or "").strip().lower()
definition = validate_application(
payload, tenant, semantic_records=semantic_records, field_contracts=field_contracts,
allowed_databases=allowed_databases)
name=" ".join(str(payload.get("name") or "").split())[:120]
if not name: raise ApplicationError("application name is required")
app_id=f"app_{write_execution.new_id()[:16]}"; now=write_execution.utcnow().isoformat()
compatible = (list(definition["compatibleDatabases"]) if definition
else _compat(payload.get("compatibleDatabases"), allow_empty=kind == "code"))
if _allowed(compatible, allowed_databases) != set(compatible):
raise PermissionError("an Application cannot bind a database you cannot open")
raw_config = payload.get("config")
if definition and raw_config is None:
raw_config = {"schemaVersion": 1,
"display": {"mode": _template_contract(template_kind)["displayMode"]}}
app={"id":app_id,"tenant":str(tenant),"type":kind,"name":name,
"compatibleDatabases":compatible,
"semanticRoleBindings":_governed_bindings(
payload.get("semanticRoleBindings"), compatible, semantic_records or {}),
"config":_typed_config(kind, raw_config),
"share":{"mode":"private","users":[]},"starredBy":[],"createdBy":user,
"createdAt":now,"updatedAt":now,"revision":1}
app.update(definition)
if definition and _template_contract(template_kind).get("deepLink"):
app["deepLink"] = _template_contract(template_kind)["deepLink"].replace("<id>", app_id)
if kind == "code":
app.update(deepLink=f"/app/code/{app_id}", origin=None)
app["origin"] = _server_origin(origin_door, via)
return app
def _code_audit_config(app):
"""Project code configuration into body-free activity metadata."""
html = app["config"]["display"]["html"].encode("utf-8")
return {"schemaVersion": 1, "display": {"mode": "code", "htmlBytes": len(html),
"htmlSha256": hashlib.sha256(html).hexdigest()}}
def _update_with_activity(runtime, app_id, user, mutate, *, via=None, on_behalf_of=None,
document_key=_KEY):
"""Log the final committed App change once, excluding previews and unbound legacy stores."""
from core.user_tables import _activity_writer
append = _activity_writer(runtime, user)
if append is None:
return _update_document(runtime, mutate, key=document_key)
app_ids = (app_id,) if isinstance(app_id, str) else tuple(app_id)
pending = {}
def snapshot(doc, identity):
app = copy.deepcopy((doc.get("applications") or {}).get(identity) or {})
if not app and document_key == _KEY:
key = _application_key(runtime, identity)
if key != _KEY:
app = _clean_doc(_read_strict(runtime, key))["applications"].get(identity, {})
if app:
if app.get("type") == "code":
app["config"] = _code_audit_config(app)
app["defaults"] = {key: value for key, value in (doc.get("defaults") or {}).items()
if value == identity}
return app
def apply(raw):
# A store replay replaces its candidate event instead of appending another one.
pending.clear()
old_doc = _clean_doc(raw)
before = {identity: snapshot(old_doc, identity) for identity in app_ids}
result = mutate(raw)
new_doc = _clean_doc(result)
for identity in app_ids:
old, after = before[identity], snapshot(new_doc, identity)
if old == after:
continue
# Keep the App name even when a large configuration exhausts C5's byte budget.
changes = {"name": {"before": old.get("name"), "after": after.get("name")}}
for key in sorted(old.keys() | after.keys()):
if key != "name" and (key not in old or key not in after or old[key] != after[key]):
changes[key] = {"before": old.get(key), "after": after.get(key)}
pending[identity] = changes
return result
result = _update_document(runtime, apply, key=document_key)
if result is not False:
for identity, changes in pending.items():
append(kind="app", object={"app": identity, "id": identity}, by=user,
via=via, on_behalf_of=on_behalf_of, changes=changes)
return result
class _AppSlotOccupied(Exception):
pass
def _create_record(runtime, app, user, *, via=None, on_behalf_of=None):
"""Claim one independently locked App slot without a registry or index write."""
legacy = _clean_doc(_read_strict(runtime, _KEY))
records = _record_documents(runtime)
combined = _clean_doc(legacy)
for record in records.values():
combined["applications"].update(record["applications"])
identity = template_identity(app)
_refuse_template_held(combined["applications"], identity)
refusal = capacity_refusal(combined, user)
if refusal:
raise ApplicationError(refusal)
if identity:
# One tenant-wide key chain per template: racing creates of one template lock the same record.
chain = f"{_RECORD_PREFIX}template/{hashlib.sha256(identity.encode('utf-8')).hexdigest()}/"
for index in range(_MAX):
def claim(raw):
doc = _clean_doc(raw)
_refuse_template_held(doc["applications"], identity)
if doc["applications"]:
raise _AppSlotOccupied() # a retired copy keeps this link of the chain
doc["applications"] = {app["id"]: app}
return doc
try:
saved = _update_with_activity(runtime, app["id"], user, claim, via=via,
on_behalf_of=on_behalf_of,
document_key=chain + str(index))
except _AppSlotOccupied:
continue
if saved is False:
raise ApplicationError("the App was not saved")
return
raise ApplicationError("the App was not saved")
owner = hashlib.sha256(user.encode("utf-8")).hexdigest()
prefix = f"{_RECORD_PREFIX}{owner}/"
occupied = {int(key[len(prefix):]) for key, doc in records.items()
if key.startswith(prefix) and key[len(prefix):].isdigit() and doc["applications"]}
legacy_count = sum(isinstance(row, dict) and row.get("createdBy") == user
and row.get("retired") is not True for row in legacy["applications"].values())
# Existing slots above a lowered capacity still consume that account's allowance.
limit = account_capacity() - legacy_count
while True:
reduced = account_capacity() - legacy_count - sum(slot >= limit for slot in occupied)
if reduced == limit:
break
limit = reduced
slots = [slot for slot in range(max(0, limit)) if slot not in occupied]
# Different creates start at different records, including when their reads race.
slots.sort(key=lambda slot: hashlib.sha256(f"{app['id']}:{slot}".encode()).digest())
for slot in slots:
def apply(raw):
doc = _clean_doc(raw)
if doc["applications"]:
raise _AppSlotOccupied()
doc["applications"][app["id"]] = app
return doc
try:
saved = _update_with_activity(runtime, app["id"], user, apply, via=via,
on_behalf_of=on_behalf_of, document_key=prefix + str(slot))
except _AppSlotOccupied:
continue
if saved is False:
raise ApplicationError("the App was not saved")
return
cap = account_capacity()
raise ApplicationError(f"Your account can hold up to {cap} App{'' if cap == 1 else 's'}. Delete an App to add another.")
def create(runtime, tenant, user, payload, *, semantic_records=None, field_contracts=None,
allowed_databases=None, via=None, on_behalf_of=None, origin_door=None, is_admin=False):
"""Create one App. A template App is one live copy per tenant: a second add returns the first."""
if getattr(runtime, "key", tenant) != tenant or getattr(getattr(runtime, "tenant", None), "key", tenant) != tenant:
raise PermissionError("an Application cannot be created for another tenant")
if (isinstance(payload, dict) and str(payload.get("templateKind") or "").strip().lower() == "alerts"
and not _user_wall(runtime, user)("automation")):
raise PermissionError("Your current rights do not allow Automation.")
app = _build_application(
tenant, user, payload, semantic_records=semantic_records, field_contracts=field_contracts,
allowed_databases=allowed_databases, origin_door=origin_door, via=via)
app_id = app["id"]
identity = template_identity(app)
if identity and not workspace_share_needs_approval(app, is_admin):
# The one template copy is listed for the whole tenant. Source walls still gate its data.
# An AI door's non-admin copy stays private until an Administrator approves the share.
app["share"] = {"mode": "tenant", "users": []}
advice = _validate_chart_rules(
app, semantic_records=semantic_records, field_contracts=field_contracts)
_validate_catalog_rules(app)
def apply(raw):
doc=_clean_doc(raw)
_refuse_template_held(doc["applications"], identity)
refusal = capacity_refusal(doc, user)
if refusal: raise ApplicationError(refusal)
doc["applications"][app_id]=app; return doc
try:
if callable(getattr(runtime, "list_keys", None)):
_create_record(runtime, app, user, via=via, on_behalf_of=on_behalf_of)
else:
_update_with_activity(runtime, app_id, user, apply, via=via, on_behalf_of=on_behalf_of)
except _TemplateHeld as exc:
# A copy the caller already lists answers first: answering another would list it a second one.
listed = next((held for held in exc.live if _listed(held, user)), None)
readable = listed or next((held for held in exc.live if may_read(held, user, is_admin)), None)
if readable is None:
raise ApplicationExistsError() from None
result = None
if (listed is None and is_admin and readable.get("createdBy") != user
and template_identity(readable) != "route"
and not workspace_share_needs_approval(readable, is_admin)):
# The tenant's one copy is listed for everyone; an admin's add shares a private legacy copy.
# Beside another account's copy it grants the admin alone, so nobody lists two.
# Routing is one private copy per account, as in `_template_share_plan`.
held_share = readable.get("share") if isinstance(readable.get("share"), dict) else {}
share = ({"mode": "tenant", "users": []} if _sole_holder(readable, exc.live)
else {"mode": "users", "users": sorted({*(held_share.get("users") or ()), user})})
try:
result = mutate(runtime, readable["id"], user, is_admin,
{"share": share}, allowed_databases=allowed_databases)
except Exception:
result = None
if result is None:
result = _public(readable, user, is_admin, allowed_databases=allowed_databases)
result["existing"] = True
return result
result = _public(app,user,allowed_databases=allowed_databases)
if app["type"] == "chart":
result["advice"] = advice
return result
def _read_strict(runtime, key):
"""Read one document so that a failure RAISES; the lenient `runtime.get` answers {} instead."""
# ⛔ D-260: `runtime.get` is the LENIENT display read. A failed hub read there answers {},
# which counted as 0 routes and wrote the one-shot marker as "no_routes", so a tenant WITH
# routes never got its App. Read STRICTLY (the timeseries_retirement._read door) so a failure
# raises into the retryable skip. Only a double exposing no strict door reads via get.
strict = getattr(runtime, "_read_strict", None)
if callable(strict):
return strict(key)
if callable(getattr(runtime, "_store", None)) and callable(getattr(runtime, "store_key", None)):
return runtime._store()._read_strict(runtime.store_key(key))
return runtime.get(key)
RETURNS_SPLIT_MARKER = "applications_returns_split_v1"
_RETURNS_LEGACY_KEYS = ("returns_repeat_settings", "returns_repeat_items", "returns_repeat_history")
class ReturnsSplitConflict(ApplicationError):
code = "returns_split_existing_returns"
def migrate_returns_split(runtime, tenant):
"""Copy legacy Returns state and split installed Apps at tenant startup or maintenance only."""
if (getattr(runtime, "key", None) != tenant
or getattr(getattr(runtime, "tenant", None), "key", tenant) != tenant):
raise PermissionError("The App migration belongs to another tenant.")
marker = _read_strict(runtime, RETURNS_SPLIT_MARKER)
if isinstance(marker, dict) and marker.get("version") == 1 and marker.get("state") == "done":
return {"outcome": "unchanged", "itemIds": copy.deepcopy(marker.get("itemIds", {}))}
if marker is not None and not isinstance(marker, dict):
raise ApplicationError("The Returns migration marker must be an object.")
def save(key, mutate):
if runtime.update(key, mutate) is False:
raise ApplicationError("The Returns migration was not saved.")
base = _read_strict(runtime, _KEY)
if base is not None and (not isinstance(base, dict)
or not isinstance(base.get("applications", {}), dict)):
raise ApplicationError("The App registry must be an object.")
documents = {_KEY: _clean_doc(base), **_record_documents(runtime)}
apps, locations = {}, {}
for key, doc in documents.items():
for identity, app in doc["applications"].items():
if (not isinstance(app, dict) or app.get("id") != identity or app.get("tenant") != tenant):
raise ApplicationError("The App record does not match its tenant.")
if identity in apps:
raise ApplicationError("The App registry contains a duplicate id.")
apps[identity], locations[identity] = app, key
originals = [app for app in apps.values() if app.get("templateKind") == "returns_repeat"]
original_ids = {app["id"] for app in originals}
original_ids.update(row["original"]["id"] for row in (marker or {}).get("apps", []))
if original_ids and any(app.get("templateKind") == "returns_refunds" and app["id"] not in original_ids
for app in apps.values()):
raise ReturnsSplitConflict("The Returns split needs a contract decision for an existing Returns and refunds App.")
if not marker:
plan = []
if originals:
from importlib import import_module
returns = import_module("modules.returns_refunds")
repeat = import_module("modules.repeat_buyers")
repeat_id = next((app["id"] for app in apps.values()
if app.get("templateKind") == "repeat_buyers"), None)
for app in originals:
replacement = returns.migrate_legacy_app(copy.deepcopy(app))
if replacement.get("id") != app["id"] or replacement.get("templateKind") != "returns_refunds":
raise ApplicationError("The Returns migration must retain the original App id.")
repeat_record = None
if repeat_id is None:
identity = "app_" + hashlib.sha256(
(tenant + "\0returns_split\0" + app["id"]).encode("utf-8")).hexdigest()[:24]
if identity in apps:
raise ApplicationError("The Repeat buyers App id is already occupied.")
repeat_record = repeat.migrate_legacy_app(copy.deepcopy(app), app_id=identity)
repeat_id = identity
plan.append({"key": locations[app["id"]], "original": copy.deepcopy(app),
"returns": replacement, "repeat": repeat_record,
"repeatKey": (_RECORD_PREFIX + repeat_id
if callable(getattr(runtime, "list_keys", None)) else _KEY)})
# Strict legacy reads finish before the first write, including the resumable plan.
legacy = [_read_strict(runtime, key) for key in _RETURNS_LEGACY_KEYS]
if any(value is not None and not isinstance(value, dict) for value in legacy):
raise ApplicationError("Legacy Returns documents must be objects.")
proposed = {"version": 1, "state": "planned", "apps": plan}
save(RETURNS_SPLIT_MARKER, lambda current: current if current else copy.deepcopy(proposed))
marker = _read_strict(runtime, RETURNS_SPLIT_MARKER)
else:
legacy = [_read_strict(runtime, key) for key in _RETURNS_LEGACY_KEYS]
if marker.get("version") != 1 or marker.get("state") not in ("planned", "done"):
raise ApplicationError("The Returns migration marker is unsupported.")
if marker["state"] == "done":
return {"outcome": "unchanged", "itemIds": copy.deepcopy(marker.get("itemIds", {}))}
copied = {"itemIds": {}}
if marker["apps"] or any(legacy):
from importlib import import_module
returns = import_module("modules.returns_refunds")
copied = returns.migrate_legacy_data(tenant, legacy_settings=legacy[0], legacy_items=legacy[1],
legacy_history=legacy[2], st=runtime)
changes = {}
repeat_ids = {app["id"] for app in apps.values() if app.get("templateKind") == "repeat_buyers"}
for row in marker["apps"]:
changes.setdefault(row["key"], []).append((row["original"]["id"], row["returns"], True))
if row["repeat"] is not None and (not repeat_ids or row["repeat"]["id"] in repeat_ids):
changes.setdefault(row["repeatKey"], []).append((row["repeat"]["id"], row["repeat"], False))
repeat_ids.add(row["repeat"]["id"])
for key, records in changes.items():
def apply(raw, records=records):
doc = _clean_doc(raw)
for identity, app, replacing in records:
current = doc["applications"].get(identity)
if replacing:
if not isinstance(current, dict) or current.get("tenant") != tenant:
raise ApplicationError("The original Returns App is unavailable.")
if current.get("templateKind") == "returns_refunds":
continue
original = next(row["original"] for row in marker["apps"]
if row["original"]["id"] == identity)
if current != original:
raise ApplicationError("The original Returns App changed during migration.")
elif current is not None:
if current != app:
raise ApplicationError("The Repeat buyers App id is already occupied.")
continue
doc["applications"][identity] = copy.deepcopy(app)
return _stored_doc(doc)
save(key, apply)
def complete(current):
if current != marker:
if isinstance(current, dict) and current.get("state") == "done":
return current
raise ApplicationError("The Returns migration plan changed.")
return {**copy.deepcopy(marker), "state": "done", "itemIds": copy.deepcopy(copied["itemIds"])}
save(RETURNS_SPLIT_MARKER, complete)
return {"outcome": "migrated", "itemIds": copy.deepcopy(copied["itemIds"])}
#: Marker of the one-copy step: each removed later copy and the kept copy that holds its slot now.
TEMPLATE_ONE_COPY_MARKER = "templateOneCopy"
#: The one-copy step deletes as the account Loopable seeds Apps under.
_ONE_COPY_ACTOR = "loopable"
def _template_double_plan(documents):
"""`[(identity, (key, kept), [(key, later), ...])]` per tenant-wide template with two live copies.
Copies sort as `_refuse_template_held` sorts them. Routing is one private copy per account by design.
"""
groups = {}
for key, doc in documents.items():
for app_id, app in doc["applications"].items():
if not isinstance(app, dict) or app.get("retired") is True:
continue
identity = template_identity(app)
if identity and identity != "route":
groups.setdefault(identity, {}).setdefault(app_id, (key, app))
plan = []
for identity, copies in sorted(groups.items()):
rows = sorted(copies.values(), key=lambda row: (str(row[1].get("createdAt") or ""),
str(row[1].get("id") or "")))
if len(rows) > 1:
plan.append((identity, rows[0], rows[1:]))
return plan
def _fold_template_copy(runtime, kept_key, kept_id, later):
"""Give the kept copy the later copy's readers and stars, and repoint its defaults."""
def fold(raw):
doc = _clean_doc(raw)
app = doc["applications"].get(kept_id)
if not isinstance(app, dict) or app.get("retired") is True:
raise ApplicationError("The kept App copy is unavailable.")
before = copy.deepcopy(app)
share = app.get("share") if isinstance(app.get("share"), dict) else {}
other = later.get("share") if isinstance(later.get("share"), dict) else {}
if share.get("mode") != "tenant":
if other.get("mode") == "tenant":
app["share"] = {"mode": "tenant", "users": []}
else:
users = [user for user in _users([
*(share.get("users") or () if share.get("mode") == "users" else ()),
*(other.get("users") or () if other.get("mode") == "users" else ()),
later.get("createdBy")]) if user != app.get("createdBy")]
if users:
app["share"] = {"mode": "users", "users": users}
stars = {*(app.get("starredBy") or ()), *(later.get("starredBy") or ())}
if stars != set(app.get("starredBy") or ()):
app["starredBy"] = sorted(stars)
if app != before:
app["revision"] = int(app.get("revision") or 0) + 1
app["updatedAt"] = write_execution.utcnow().isoformat()
return doc
return raw
_update_document(runtime, fold, key=kept_key)
def repoint(raw):
doc = _clean_doc(raw)
names = [name for name, value in doc["defaults"].items() if value == later.get("id")]
if not names:
return raw
for name in names:
doc["defaults"][name] = kept_id
return doc
if later.get("id") in _clean_doc(_read_strict(runtime, _KEY))["defaults"].values():
_update_document(runtime, repoint)
index = _read_strict(runtime, _APP_INDEX_KEY)
owners = index.get("users") if isinstance(index, dict) else None
if isinstance(owners, dict):
_move_placements(runtime, {name: {later["id"]: kept_id} for name in owners})
def remove_template_doubles(runtime, tenant):
"""Keep the oldest live copy of each tenant-wide template and delete every later copy.
`delete` keeps the later copy's databases, Views and records. A second run writes nothing.
Never raises: a failed copy is reported and retried at the next boot.
"""
if (getattr(runtime, "key", None) != tenant
or getattr(getattr(runtime, "tenant", None), "key", tenant) != tenant):
return {"outcome": "skipped", "removed": {}, "reason": "the runtime belongs to another tenant"}
try:
documents = {_KEY: _clean_doc(_read_strict(runtime, _KEY))}
documents.update(_record_documents(runtime))
except Exception as exc:
return {"outcome": "skipped", "removed": {},
"reason": f"registry read failed: {type(exc).__name__}: {exc}"}
removed, failed = {}, []
for identity, (kept_key, kept), later in _template_double_plan(documents):
for _key, app in later:
try:
_fold_template_copy(runtime, kept_key, kept["id"], app)
delete(runtime, app["id"], _ONE_COPY_ACTOR, True)
except Exception as exc:
failed.append(f"{app['id']}: {type(exc).__name__}")
print(f"[aios-api] one template copy {tenant}: {app['id']} not removed: "
f"{type(exc).__name__}")
continue
removed[app["id"]] = kept["id"]
print(f"[aios-api] one template copy {tenant}: removed {app['id']}, "
f"kept {kept['id']} ({identity})")
if removed:
def mark(raw):
doc = _clean_doc(raw)
migrations = doc.setdefault("migrations", {})
marker = migrations.get(TEMPLATE_ONE_COPY_MARKER)
marker = copy.deepcopy(marker) if isinstance(marker, dict) else {}
held = marker.get("removed") if isinstance(marker.get("removed"), dict) else {}
marker.update(removed={**held, **removed}, at=write_execution.utcnow().isoformat())
migrations[TEMPLATE_ONE_COPY_MARKER] = marker
return doc
try:
_update_document(runtime, mark)
except Exception as exc:
failed.append(f"marker: {type(exc).__name__}")
outcome = "removed" if removed else ("failed" if failed else "unchanged")
reason = ", ".join(f"{later_id} into {kept_id}" for later_id, kept_id in removed.items())
return {"outcome": outcome, "removed": removed,
"reason": "; ".join(part for part in (reason, ", ".join(failed)) if part)}
def ensure_route_application(runtime, tenant, *, accounts=None, wall=None):
"""R15: boot migrations, once per tenant, never from an Application read.
Runs the Routing seed migration, `ensure_user_app_copies`, `migrate_c1_bindings` and
`migrate_template_shares`, and folds them into one dict.
"""
result = _ensure_route_seed(runtime, tenant)
copies = ensure_user_app_copies(runtime, tenant, accounts=accounts, wall=wall)
bindings = migrate_c1_bindings(runtime, tenant)
shares = migrate_template_shares(runtime, tenant)
folded = dict(result)
folded["userCopies"] = copies
folded["c1Bindings"] = bindings
folded["templateShares"] = shares
note = "user copies " + copies["outcome"] + (
": " + copies["reason"] if copies.get("reason") else "")
note += "; C1 bindings " + bindings["outcome"] + (
": " + bindings["reason"] if bindings.get("reason") else "")
note += "; template shares " + shares["outcome"] + (
": " + shares["reason"] if shares.get("reason") else "")
folded["reason"] = result["reason"] + "; " + note if result.get("reason") else note
return folded
def _ensure_route_seed(runtime, tenant):
"""R15: migrate route references once per tenant into the seeded Routing App."""
from core import route_system
# list_routes() suppresses read errors; an unknown count must remain retryable at boot.
try:
route_doc = _read_strict(runtime, route_system.STORE_KEY)
if route_doc is None:
routes = []
elif isinstance(route_doc, dict):
routes = route_doc.get("routes", [])
else:
raise ApplicationError("route store must be an object")
if not isinstance(routes, list):
raise ApplicationError("route store routes must be a list")
route_count = len(routes)
records = _record_documents(runtime)
except Exception as exc:
return {"outcome": "skipped", "reason": f"route read failed: {type(exc).__name__}: {exc}"}
result = {}
def apply(raw):
nonlocal result
doc = _clean_doc(raw)
migrations = doc.setdefault("migrations", {})
if "routeApplication" in migrations:
result = {"outcome": "skipped", "reason": "route Application migration already applied"}
return raw
applications = dict(doc["applications"])
for record in records.values():
applications.update(record["applications"])
existing = next((app for app in applications.values()
if isinstance(app, dict) and app.get("templateKind") == "route"), None)
app_id = existing.get("id") if existing is not None else None
outcome = "existing" if existing is not None else "no_routes"
if existing is None and route_count:
refusal = capacity_refusal({"applications": applications}, "loopable")
if refusal:
raise ApplicationError(refusal)
app = _build_application(
tenant, "loopable",
{"name": "Routing", "templateKind": "route", "type": "route",
"navPlacement": {"section": "app", "order": 0}},
field_contracts={"customer_data": [
{"key": "customer", "type": "text"}, {"key": "lat", "type": "text"},
{"key": "lon", "type": "text"}]},
allowed_databases={"customer_data"})
app["share"] = {"mode": "tenant", "users": []}
app_id = app["id"]
doc["applications"][app_id] = app
outcome = "created"
result = {"at": write_execution.utcnow().isoformat(), "outcome": outcome,
"appId": app_id, "routes": route_count}
migrations["routeApplication"] = copy.deepcopy(result)
return doc
_update_document(runtime, apply)
return result
#: Marker of the Command Center seed. Once written, a deleted Command Center App is never seeded again.
COMMAND_CENTER_MARKER = "commandCenterApplication"
#: The amazon_profit App's default name, and the earlier defaults the boot migration replaces.
PROJECT_APP_NAME = _app_templates.BY_KIND["amazon_profit"]["label"]
_PROJECT_APP_PRIOR_NAME = "Project management"
_PROJECT_APP_SEED_NAMES = ("Command Center", "Amazon Command Center")
def _migrate_project_management_names(runtime):
"""Rename only earlier default names in each tenant-bound App document; a user's name stays."""
def original(app):
if not (isinstance(app, dict) and app.get("tenant") == runtime.key
and app.get("templateKind") == "amazon_profit"):
return False
# An editor save bumps revision, so the prior default name alone marks a default.
if app.get("name") == _PROJECT_APP_PRIOR_NAME:
return True
return (app.get("createdBy") == "loopable" and app.get("revision") == 1
and app.get("name") in _PROJECT_APP_SEED_NAMES)
documents = {_KEY: _clean_doc(_read_strict(runtime, _KEY)), **_record_documents(runtime)}
count = 0
for key, snapshot in documents.items():
if not any(original(app) for app in snapshot["applications"].values()):
continue
changed = []
def apply(raw):
changed.clear()
doc = _clean_doc(raw)
for app in doc["applications"].values():
if original(app):
app["name"] = PROJECT_APP_NAME
changed.append(app["id"])
return doc
if _update_document(runtime, apply, key=key) is False:
raise ApplicationError("The Project manager name was not saved.")
count += len(changed)
return count
def _adopt_project_field_order(runtime):
"""Move Projects beside each managed product ID without rewriting fields, rows or saved views."""
from core import user_tables
from modules import amazon_profit
specs = amazon_profit.table_specs()
def ordered(spec, definition):
if not isinstance(definition, dict) or definition.get("source") != user_tables.AUTOMATION_SOURCE:
return None
fields = definition.get("fields") or []
keys = [field.get("key") for field in fields]
if len(keys) != len(set(keys)) or not keys or keys[0] != spec["keyColumn"]:
return None
identity = fields[0].get("automation") or {}
if identity.get("flowId") != amazon_profit.VIA or "projects" not in keys:
return None
wanted = amazon_profit._project_field_order(keys)
defaults = [field["key"] for field in spec["fields"] if field["key"] != "projects"]
# A saved definition with another order belongs to its author.
if [key for key in keys if key != "projects"] != defaults:
return None
return wanted if wanted != keys else None
todo = [spec for spec in specs if ordered(spec, user_tables.get_definition(spec["key"], st=runtime))]
if not todo:
return 0
changed = []
def apply(raw):
changed.clear()
tables = raw if isinstance(raw, dict) else {}
for spec in todo:
table = tables.get(spec["key"])
wanted = ordered(spec, table)
if wanted:
fields = {field["key"]: field for field in table["fields"]}
table["fields"] = [fields[key] for key in wanted]
changed.append(spec["key"])
return tables
if runtime.update(user_tables.STORE_KEY, apply, flush="sync") is False:
raise ApplicationError("The Project manager field order was not saved.")
return len(changed)
def reconcile_project_management_defaults(runtime, tenant):
"""Correct only original App names and managed field defaults, without seeding or reading rows."""
if (getattr(runtime, "key", None) != tenant
or getattr(getattr(runtime, "tenant", None), "key", tenant) != tenant):
raise PermissionError("The App migration belongs to another tenant.")
return {"renamed": _migrate_project_management_names(runtime),
"reordered": _adopt_project_field_order(runtime)}
def ensure_command_center_application(runtime, tenant):
"""Reconcile Project manager defaults and seed one shared App when its table exists.
A tenant without the table gets no marker, so a later boot seeds it once the table exists.
"""
if (getattr(runtime, "key", None) != tenant
or getattr(getattr(runtime, "tenant", None), "key", tenant) != tenant):
raise PermissionError("The App migration belongs to another tenant.")
from core import user_tables
from modules.amazon_profit import TABLE_KEY
corrected = reconcile_project_management_defaults(runtime, tenant)
renamed, reordered = corrected["renamed"], corrected["reordered"]
base = _clean_doc(_read_strict(runtime, _KEY))
if COMMAND_CENTER_MARKER in (base.get("migrations") or {}):
if renamed or reordered:
return {"outcome": "migrated", "renamed": renamed, "reordered": reordered}
return {"outcome": "unchanged"}
records = _record_documents(runtime)
def _held(doc):
applications = dict(doc["applications"])
for record in records.values():
applications.update(record["applications"])
existing = next((app for app in applications.values()
if isinstance(app, dict) and app.get("templateKind") == "amazon_profit"), None)
return applications, existing
_applications, existing = _held(base)
if existing is None and not isinstance(user_tables.get_definition(TABLE_KEY, st=runtime), dict):
return {"outcome": "no_table"}
result = {}
def apply(raw):
nonlocal result
doc = _clean_doc(raw)
migrations = doc.setdefault("migrations", {})
if COMMAND_CENTER_MARKER in migrations:
result = {"outcome": "unchanged"}
return raw
applications, current = _held(doc)
if current is not None:
result = {"outcome": "existing", "appId": current.get("id")}
else:
refusal = capacity_refusal({"applications": applications}, "loopable")
if refusal:
result = {"outcome": "skipped", "reason": refusal}
return raw
app = _build_application(
tenant, "loopable",
{"name": PROJECT_APP_NAME, "templateKind": "amazon_profit",
"navPlacement": {"section": "app", "order": 0}})
app["share"] = {"mode": "tenant", "users": []}
doc["applications"][app["id"]] = app
result = {"outcome": "created", "appId": app["id"]}
migrations[COMMAND_CENTER_MARKER] = {"at": write_execution.utcnow().isoformat(), **result}
return doc
if _update_document(runtime, apply) is False:
raise ApplicationError("The Project manager App was not saved.")
return result
#: Marker of the R33 migration: the binding each rewritten App held before, and the Apps it kept.
C1_BINDINGS_MARKER = "c1Bindings"
def _c1_rewrite(app):
"""A Routing or Catalog App rewritten to its C1 binding, or None when it must stay as stored.
An App whose source or field map differs from C1 (`own_binding` non-empty) is never rewritten.
"""
if not isinstance(app, dict) or app.get("templateKind") not in _app_templates.BOUND_KINDS:
return None
if "sourceDatabase" not in app and "fieldMap" not in app:
return None
if _app_templates.own_binding(app):
return None
source = _app_templates.source(app["templateKind"])
row = copy.deepcopy(app)
row.pop("sourceDatabase", None)
row.pop("fieldMap", None)
row["compatibleDatabases"] = [source, *(database for database in app.get("compatibleDatabases") or ()
if database != source)]
return row
def _c1_plan(doc, app_ids):
"""`{id: rewritten App}` plus the stored Apps that keep a binding of their own, for one document."""
rewrites, kept = {}, []
for app_id, app in sorted(doc["applications"].items()):
if app_ids is not None and app_id not in app_ids:
continue
if not isinstance(app, dict) or app.get("templateKind") not in _app_templates.BOUND_KINDS:
continue
rewritten = _c1_rewrite(app)
if rewritten is not None:
rewrites[app_id] = rewritten
elif _app_templates.own_binding(app):
kept.append({"id": app_id, "templateKind": app["templateKind"], "name": app.get("name"),
"sourceDatabase": app.get("sourceDatabase"),
"fieldMap": copy.deepcopy(app.get("fieldMap"))})
return rewrites, kept
def migrate_c1_bindings(runtime, tenant, *, app_ids=None):
"""R33: rewrite every stored Routing and Catalog App to its C1 binding.
Writes only when an App still stores a binding equal to C1, so a second run changes nothing.
An App with its own source or field map is kept and listed. A proof run
passes `app_ids` to touch only the named Apps; the boot call never passes it.
"""
scope = None if app_ids is None else set(app_ids)
try:
doc = _clean_doc(_read_strict(runtime, _KEY))
records = _record_documents(runtime)
except Exception as exc:
return {"outcome": "skipped", "reason": f"registry read failed: {type(exc).__name__}: {exc}",
"rewritten": [], "kept": []}
rewrites, kept = _c1_plan(doc, scope)
result = {"outcome": "unchanged", "rewritten": [], "kept": kept}
if rewrites:
def apply(raw):
current = _clean_doc(raw)
planned, held = _c1_plan(current, scope)
result["kept"] = held
if not planned:
return raw
marker = current.setdefault("migrations", {}).setdefault(
C1_BINDINGS_MARKER, {"rewritten": {}, "kept": []})
for app_id, app in planned.items():
before = current["applications"][app_id]
marker["rewritten"][app_id] = {key: copy.deepcopy(before[key]) for key in
("sourceDatabase", "fieldMap", "compatibleDatabases")
if key in before}
current["applications"][app_id] = app
marker["kept"] = sorted({row["id"] for row in held} | set(marker.get("kept") or ()))
marker["at"] = write_execution.utcnow().isoformat()
result.update(outcome="migrated", rewritten=sorted(planned))
return current
_update_document(runtime, apply)
for key, record in records.items():
planned, held = _c1_plan(record, scope)
result["kept"].extend(held)
if not planned:
continue
rewritten = []
def apply_record(raw):
rewritten.clear()
current = _clean_doc(raw)
fresh, _held = _c1_plan(current, scope)
if not fresh:
return raw
marker = current.setdefault("migrations", {}).setdefault(
C1_BINDINGS_MARKER, {"rewritten": {}, "kept": []})
for identity in fresh:
before = current["applications"][identity]
marker["rewritten"][identity] = {field: copy.deepcopy(before[field]) for field in
("sourceDatabase", "fieldMap", "compatibleDatabases")
if field in before}
marker["at"] = write_execution.utcnow().isoformat()
current["applications"].update(fresh)
rewritten.extend(sorted(fresh))
return current
_update_document(runtime, apply_record, key=key)
if rewritten:
result["rewritten"].extend(rewritten)
result["outcome"] = "migrated"
if result["rewritten"]:
try:
from catalog_store import migrate_snapshots
result["catalogSnapshots"] = migrate_snapshots(runtime, result["rewritten"])
except Exception as exc:
result["catalogSnapshots"] = f"skipped: {type(exc).__name__}"
parts = [f"{len(result['rewritten'])} rewritten"] if result["rewritten"] else []
if result["kept"]:
parts.append("kept with their own binding: " + ", ".join(row["id"] for row in result["kept"]))
result["reason"] = "; ".join(parts)
return result
#: Marker of the template share migration: the copy each shareless template identity now shares.
TEMPLATE_SHARES_MARKER = "templateShares"
def _template_share_plan(documents):
"""`{document key: {app id: identity}}`: the oldest live copy of each unshared identity one account holds."""
groups = {}
for key, doc in documents.items():
for app_id, app in doc["applications"].items():
if not isinstance(app, dict) or app.get("retired") is True:
continue
identity = template_identity(app)
# Routing stays one private copy per account by design (`ensure_user_app_copies`).
if identity and identity != "route":
groups.setdefault(identity, []).append((key, app_id, app))
plan = {}
for identity, copies in sorted(groups.items()):
if any((app.get("share") if isinstance(app.get("share"), dict) else {}).get("mode") == "tenant"
for _key, _app_id, app in copies):
continue
key, app_id, app = min(copies, key=lambda row: (str(row[2].get("createdAt") or ""),
str(row[2].get("id") or "")))
# Another account's copy would list beside the shared one: that account would see two.
if _sole_holder(app, [row[2] for row in copies]):
plan.setdefault(key, {})[app_id] = identity
return plan
def migrate_template_shares(runtime, tenant):
"""Share with the tenant the oldest live copy of each unshared template identity one account holds.
Writes only a document that holds a copy to share, so a second run writes nothing.
"""
try:
documents = {_KEY: _clean_doc(_read_strict(runtime, _KEY))}
documents.update(_record_documents(runtime))
except Exception as exc:
return {"outcome": "skipped", "shared": [],
"reason": f"registry read failed: {type(exc).__name__}: {exc}"}
plan = _template_share_plan(documents)
shared = []
for key in sorted(plan, key=lambda name: (name != _KEY, name)):
flips, landed = plan[key], []
def apply(raw, flips=flips, landed=landed):
landed.clear()
current = _clean_doc(raw)
for app_id, identity in sorted(flips.items()):
app = current["applications"].get(app_id)
if not isinstance(app, dict) or app.get("retired") is True:
continue
share = app.get("share") if isinstance(app.get("share"), dict) else {}
if share.get("mode") == "tenant":
continue
app["share"] = {"mode": "tenant", "users": []}
landed.append((identity, app_id))
if not landed:
return raw
migrations = current.setdefault("migrations", {})
marker = migrations.get(TEMPLATE_SHARES_MARKER)
marker = copy.deepcopy(marker) if isinstance(marker, dict) else {}
marker["shared"] = {**(marker.get("shared") if isinstance(marker.get("shared"), dict) else {}),
**dict(landed)}
marker["at"] = write_execution.utcnow().isoformat()
migrations[TEMPLATE_SHARES_MARKER] = marker
return current
_update_document(runtime, apply, key=key)
shared.extend(app_id for _identity, app_id in landed)
return {"outcome": "migrated" if shared else "unchanged", "shared": shared,
"reason": ", ".join(shared)}
_COPIES = "userAppCopies"
_APP_INDEX_KEY = "module_index_app"
def _active_accounts(tenant):
"""`[(username, public user record)]` for this tenant's active accounts; raises if unreadable."""
from core import users
if not isinstance(users.registry(), dict):
raise ApplicationError("the account registry is unreadable")
return [(name, users._public(name, record)) for name, record in users._tenant_accounts(tenant)]
def _copy_id(tenant, old_id, username):
"""One stable id per (tenant, old App id, account), so a rerun cannot duplicate a copy."""
import hashlib
digest = hashlib.sha256(f"{tenant}\x1f{old_id}\x1f{username}".encode("utf-8")).hexdigest()
return "app_" + digest[:16]
def _seed_route_app(doc):
"""The tenant-shared Routing App the route migration seeded, or None."""
seed_id = ((doc.get("migrations") or {}).get("routeApplication") or {}).get("appId")
seed = doc["applications"].get(seed_id) if seed_id else None
if (isinstance(seed, dict) and seed.get("createdBy") == "loopable"
and (seed.get("share") or {}).get("mode") == "tenant"):
return seed
return None
def _move_placements(runtime, moves):
"""Move each account's App-home folder placement from an old App id to its copy id."""
doc = _read_strict(runtime, _APP_INDEX_KEY)
owners = (doc or {}).get("users") if isinstance(doc, dict) else None
if not isinstance(owners, dict):
return 0
if not any(old in ((owners.get(name) or {}).get("itemFolders") or {})
for name, pairs in moves.items() for old in pairs):
return 0
moved = [0]
def apply(raw):
state = copy.deepcopy(raw) if isinstance(raw, dict) else raw
buckets = state.get("users") if isinstance(state, dict) else None
for name, pairs in moves.items():
bucket = buckets.get(name) if isinstance(buckets, dict) else None
placed = bucket.get("itemFolders") if isinstance(bucket, dict) else None
if not isinstance(placed, dict):
continue
changed = False
for old, new in pairs.items():
if old in placed:
folder = placed.pop(old)
placed.setdefault(new, folder)
changed = True
moved[0] += 1
if changed:
# A client holding the old revision must reload before it writes folders again.
bucket["rev"] = int(bucket.get("rev") or 0) + 1
return state
runtime.update(_APP_INDEX_KEY, apply)
return moved[0]
def ensure_user_app_copies(runtime, tenant, *, accounts=None, wall=None):
"""Give every active account one private copy of the Routing seed, once per tenant.
The seeded Routing App becomes one private copy per active account and is then retired: hidden
from the App home but kept, so a View holding its id still resolves. Folder placements move to
the copy ids. A failed read returns a retryable `skipped` and writes no marker.
"""
try:
current = _read_strict(runtime, _KEY)
if current is not None and not isinstance(current, dict):
raise ApplicationError("the Application registry must be an object")
except Exception as exc:
return {"outcome": "skipped", "reason": f"registry read failed: {type(exc).__name__}: {exc}"}
migrations = _clean_doc(current).get("migrations") or {}
marker = migrations.get(_COPIES)
if isinstance(marker, dict) and marker.get("state") == "done":
return {"outcome": "skipped", "reason": "user App copies already applied"}
if "routeApplication" not in migrations:
return {"outcome": "skipped", "reason": "route Application migration pending"}
if isinstance(marker, dict) and isinstance(marker.get("moves"), dict):
moves = copy.deepcopy(marker["moves"])
copies = int(marker.get("copies") or 0)
else:
try:
people = list(_active_accounts(tenant) if accounts is None else accounts)
plan = [str(username) for username, _record in people]
except Exception as exc:
return {"outcome": "skipped",
"reason": f"account read failed: {type(exc).__name__}: {exc}"}
if not plan:
return {"outcome": "skipped", "reason": "no active accounts"}
landed = {}
def apply(raw):
doc = _clean_doc(raw)
state = doc.setdefault("migrations", {})
if isinstance(state.get(_COPIES), dict):
landed.update(copy.deepcopy(state[_COPIES]))
return raw
now = write_execution.utcnow().isoformat()
seed = _seed_route_app(doc)
moves, made = {}, 0
for username in plan:
pairs = moves.setdefault(username, {})
if seed is not None:
new_id = _copy_id(tenant, seed["id"], username)
pairs[seed["id"]] = new_id
if new_id not in doc["applications"]:
record = copy.deepcopy(seed)
for key in ("retired", "retiredAt"):
record.pop(key, None)
record.update(
id=new_id, createdBy=username, share={"mode": "private", "users": []},
origin=_server_origin(),
starredBy=[username] if username in (seed.get("starredBy") or ()) else [],
createdAt=now, updatedAt=now, revision=1, migratedFrom=seed["id"])
doc["applications"][new_id] = record
made += 1
if seed is not None:
seed.update(retired=True, retiredAt=now)
for key in [key for key, value in doc["defaults"].items() if value == seed["id"]]:
doc["defaults"].pop(key)
state[_COPIES] = {"state": "copied", "at": now, "accounts": len(plan),
"copies": made, "seed": seed["id"] if seed else None,
"moves": moves}
landed.update(copy.deepcopy(state[_COPIES]))
return doc
_update_document(runtime, apply)
if landed.get("state") == "done":
return {"outcome": "skipped", "reason": "user App copies already applied"}
moves, copies = landed.get("moves") or {}, int(landed.get("copies") or 0)
try:
moved = _move_placements(runtime, moves)
except Exception as exc:
return {"outcome": "skipped",
"reason": f"folder placement move failed: {type(exc).__name__}: {exc}"}
def finish(raw):
doc = _clean_doc(raw)
state = (doc.get("migrations") or {}).get(_COPIES)
if not isinstance(state, dict) or state.get("state") == "done":
return raw
state.update(state="done", moved=moved, doneAt=write_execution.utcnow().isoformat())
return doc
_update_document(runtime, finish)
return {"outcome": "copied", "copies": copies, "accounts": len(moves), "moved": moved,
"reason": f"{copies} copies for {len(moves)} accounts, {moved} folder placements moved"}
def workspace_share_needs_approval(app, is_admin=False):
"""Hold workspace sharing for an AI-built App until an Administrator answers."""
origin = app.get("origin") if isinstance(app.get("origin"), dict) else {}
return not is_admin and origin.get("door") in ("mcp", "loopy")
def _request_workspace_share(runtime, app, user):
"""Send one source-checked approval to the tenant's active Administrators."""
import tickets
from core import perms, users
try:
recipients = [name for name, record in users._tenant_accounts(runtime.key)
if perms.is_admin(record)]
if not recipients:
raise ApplicationError("No Administrator is available to approve this share.")
request = tickets.send_request(
runtime, user, recipients, "approval", "Share " + app["name"],
"Share this App with the workspace?",
source={"database": "applications", "record": app["id"]})
except (ValueError, PermissionError) as exc:
raise ApplicationError(str(exc)) from exc
return {"state": "pending", "requestId": request["id"],
"message": "This share waits for an Administrator."}
def mutate(runtime, app_id, user, is_admin, patch, *, semantic_records=None, field_contracts=None,
allowed_databases=None, target_database=None, expect=None, via=None, on_behalf_of=None,
origin_door=None):
"""Apply a patch, optionally requiring the current share's mode and users to match `expect`."""
patch=patch if isinstance(patch,dict) else {}; landed={}
advice = []
held_share = []
if "origin" in patch:
raise ApplicationError("Loopable sets origin. Remove origin from the request.")
_server_origin(origin_door, via)
immutable = sorted(set(patch) & {
"id", "tenant", "type", "templateKind", "sourceDatabase", "navPlacement",
"financeKey", "deepLink"
})
if immutable:
raise ApplicationError("Application identity and template definition are immutable: "
+ ", ".join(immutable))
def apply(raw):
held_share.clear()
landed.clear()
doc=_clean_doc(raw); app=doc["applications"].get(app_id)
if not app: raise ApplicationError("application does not exist")
if not _is_finance(app) and not _allowed(app.get("compatibleDatabases"), allowed_databases):
if not _database_free(app):
raise ApplicationError("application does not exist")
if (app.get("templateKind") in APPLICATION_TEMPLATE_KINDS + GATED_TEMPLATE_KINDS
and "compatibleDatabases" in patch):
raise ApplicationError("a template Application's sourceDatabase is immutable")
star_only = set(patch) <= {"starred"}
if star_only:
if not may_read(app,user,is_admin): raise PermissionError("application is not available")
elif not may_edit(app,user,is_admin):
raise PermissionError("application belongs to another user")
if expect is not None:
def share_state(value):
value = value if isinstance(value, dict) else {}
mode = str(value.get("mode") or "private")
return mode, _users(value.get("users")) if mode == "users" else []
# Compare the fresh share on every store replay before changing any Application field.
if share_state(app.get("share")) != share_state(expect):
raise shares.GrantsChanged(
'this item was shared with somebody else while you were editing, so nothing '
'was saved. Reopen the sharing panel to see who has access now, then make '
'your change again.')
if "name" in patch:
name=" ".join(str(patch["name"] or "").split())[:120]
if app["type"] == "chart" and not _is_finance(app):
try:
app_rules.validate_text(patch["name"], "the App name")
except app_rules.RuleError as exc:
raise ApplicationRuleError(exc) from None
if not name: raise ApplicationError("application name is required")
app["name"]=name
if "config" in patch:
config = _typed_config(app["type"], patch["config"])
_refuse_legacy_catalog_changes(app, config)
app["config"] = config
if "fieldMap" in patch:
# R33: a template App reads the fields its template names.
raise ApplicationError("This App reads the fields its template names. "
"Its field map cannot change.")
compatible = (_compat(patch["compatibleDatabases"], allow_empty=app["type"] == "code")
if "compatibleDatabases" in patch else app.get("compatibleDatabases") or [])
if _allowed(compatible, allowed_databases) != set(compatible):
raise PermissionError("an Application cannot bind a database you cannot open")
if "semanticRoleBindings" in patch or "compatibleDatabases" in patch:
bindings = patch.get("semanticRoleBindings", app.get("semanticRoleBindings"))
app["semanticRoleBindings"]=_governed_bindings(
bindings, compatible, semantic_records or {})
app["compatibleDatabases"] = list(compatible)
if "share" in patch:
share=patch["share"] if isinstance(patch["share"],dict) else {}
mode=str(share.get("mode") or "private")
if mode not in ("private","users","tenant"): raise ApplicationError("share mode is not recognized")
if mode == "tenant" and workspace_share_needs_approval(app, is_admin) \
and (app.get("share") or {}).get("mode") != "tenant":
held_share.append(True)
else:
app["share"]={"mode":mode,"users":_users(share.get("users")) if mode=="users" else []}
if "starred" in patch:
stars=set(app.get("starredBy") or ())
(stars.add if patch["starred"] else stars.discard)(user); app["starredBy"]=sorted(stars)
if not star_only:
advice[:] = _validate_chart_rules(
app, semantic_records=semantic_records, field_contracts=field_contracts)
_validate_catalog_rules(app)
app["revision"]=int(app.get("revision") or 0)+1
app["updatedAt"]=write_execution.utcnow().isoformat(); landed.update(app)
return doc
_update_with_activity(runtime, app_id, user, apply, via=via, on_behalf_of=on_behalf_of,
document_key=_application_key(runtime, app_id))
result = _public(landed,user,is_admin,allowed_databases=allowed_databases,
target_database=target_database)
if landed["type"] == "chart" and not set(patch) <= {"starred"}:
result["advice"] = advice
if held_share:
result["shareApproval"] = _request_workspace_share(runtime, landed, user)
result["message"] = result["shareApproval"]["message"]
return result
def duplicate(runtime, app_id, tenant, user, is_admin=False, *, semantic_records=None,
field_contracts=None, allowed_databases=None, via=None, on_behalf_of=None,
origin_door=None):
app=load(runtime)["applications"].get(app_id)
if not may_read(app,user,is_admin): raise ApplicationError("application does not exist")
if not _is_finance(app) and not _allowed(app.get("compatibleDatabases"), allowed_databases):
if not _database_free(app):
raise ApplicationError("application does not exist")
payload={"type":app["type"],"name":f"{app['name']} copy",
"compatibleDatabases":app.get("compatibleDatabases"),
"semanticRoleBindings":app.get("semanticRoleBindings"),"config":app.get("config")}
# R33: a template copy binds C1 itself, so neither the source nor the field map is copied.
for key in ("templateKind", "navPlacement", "financeKey"):
if key in app: payload[key]=copy.deepcopy(app[key])
if app.get("templateKind") not in _app_templates.BOUND_KINDS and "sourceDatabase" in app:
payload["sourceDatabase"] = app["sourceDatabase"]
return create(runtime,tenant,user,payload,
semantic_records=semantic_records, field_contracts=field_contracts,
allowed_databases=allowed_databases, via=via, on_behalf_of=on_behalf_of,
origin_door=origin_door, is_admin=is_admin)
_ANY_NAME = object()
def _workspace_views(doc, *, trash=True):
"""Every View in one workspace document: each member's Views, reserved members included.
Descends into nested folders. With `trash`, each owner's trash entries are walked too.
"""
def nested_views(rows):
for row in (rows.values() if isinstance(rows, dict) else rows if isinstance(rows, list) else ()):
if isinstance(row, dict) and ("config" in row or "presentation" in row):
yield row
elif isinstance(row, (dict, list)):
yield from nested_views(row)
for bucket in (doc.values() if isinstance(doc, dict) else ()):
if not isinstance(bucket, dict):
continue
yield from nested_views(bucket.get("views"))
held = bucket.get("trash") if trash else None
for entry in (held.values() if isinstance(held, dict)
else held if isinstance(held, list) else ()):
if isinstance(entry, dict) and isinstance(entry.get("view"), dict):
yield entry["view"]
def _view_app_ids(view):
"""The distinct App ids a View's `config` or `presentation` names."""
ids = []
for key in ("config", "presentation"):
config = view.get(key) if isinstance(view, dict) else None
ref = config.get("application") if isinstance(config, dict) else None
app_id = str(ref.get("id") or "") if isinstance(ref, dict) else ""
if app_id and app_id not in ids:
ids.append(app_id)
return ids
def _strip_view_refs(doc, app_id):
"""Remove `config.application` naming `app_id` from every View in one workspace document.
Walks every top-level member, reserved ones included, and each owner's trash entries.
Returns the number of Views changed. Mutates `doc` in place.
"""
cleared = 0
if isinstance(doc, dict):
for view in _workspace_views(doc):
changed = False
for key in ("config", "presentation"):
config = view.get(key) if isinstance(view, dict) else None
ref = config.get("application") if isinstance(config, dict) else None
if isinstance(ref, dict) and str(ref.get("id") or "") == app_id:
config.pop("application")
changed = True
if changed:
cleared += 1
return cleared
def clear_view_references(runtime, app_id, databases):
"""D-2233: drop a deleted App's id from saved Views so each opens as a plain View.
Returns `(views cleared, reasons for databases not cleared)`. Never raises.
"""
from core.view_templates import workspace_key
cleared, failed = 0, []
for database in dict.fromkeys(str(value or "") for value in databases or ()):
key = workspace_key(database)
if not key:
continue
try:
# A strict read: a failed read is reported, never counted as no reference.
if not _strip_view_refs(copy.deepcopy(_read_strict(runtime, key)), app_id):
continue
count = [0]
def apply(raw):
doc = copy.deepcopy(raw)
count[0] = _strip_view_refs(doc, app_id)
return doc if count[0] else raw
saved = runtime.update(key, apply)
if saved is False or _strip_view_refs(copy.deepcopy(_read_strict(runtime, key)), app_id):
raise ApplicationError("the View reference cleanup was not saved")
cleared += count[0]
except Exception as exc:
failed.append(f"{database}: {type(exc).__name__}")
return cleared, failed
RETIRED_KINDS_MARKER = "retireNonRoutingCatalogApps"
RETIRE_KINDS_CONFIRM = "DELETE ALL APPS EXCEPT ROUTING AND CATALOG"
def retirement_store_guard(runtime=None, tenant=None):
"""Admit only the deployment's bound store, including reads of a retirement preview."""
from core import activity_log, data_binding, store, store_pg
if runtime is not None and (not isinstance(tenant, str) or not tenant
or getattr(runtime, "key", None) != tenant
or getattr(getattr(runtime, "tenant", None), "key", None) != tenant):
raise ApplicationError("retirement runtime does not match its tenant")
bound = runtime._store() if runtime is not None else store._d()
shared = bound is store
if bound is store:
bound = store._d()
if isinstance(bound, activity_log.FixtureAdapter):
if tenant is not None and (getattr(bound, "tenant_slug", None) != tenant
or runtime.store_namespace):
raise ApplicationError("retirement runtime does not match its tenant store")
return
if isinstance(bound, store_pg.PgStore):
slug = bound.tenant_slug
if tenant is not None and (slug != tenant or runtime.key != tenant
or runtime.store_namespace):
raise ApplicationError("retirement runtime does not match its tenant store")
if (not data_binding.is_production_deployment()
and slug in store_pg.PRODUCTION_TENANTS
and not store_pg.isolated_staging_database()):
raise ApplicationError("retirement cannot read a live tenant from this deployment")
refusal = store_pg.gate_write_refusal(slug) or store_pg.write_refusal(slug)
else:
repo = getattr(bound, "repo", None)
if tenant is not None:
configured_repo = (getattr(runtime.tenant, "config", {}) or {}).get("store_repo")
namespace = "" if configured_repo or tenant == "royal-imports" else f"t/{tenant}/"
if (not repo or runtime.store_namespace != namespace
or (repo != configured_repo if configured_repo else not shared)):
raise ApplicationError("retirement runtime does not match its tenant store")
if not data_binding.is_production_deployment() and repo in data_binding.PRODUCTION_STORES:
raise ApplicationError("retirement cannot read a live store from this deployment")
refusal = data_binding.gate_write_refusal(repo) or data_binding.write_refusal(repo)
if refusal:
raise ApplicationError(refusal)
def retirement_tenants():
"""Resolve every tenant from a strict control-plane snapshot without changing its records."""
from core import store
from harness import runtime
retirement_store_guard()
records = store._read_strict(runtime.TENANTS_KEY)
if records is None:
records = {}
if not isinstance(records, dict) or any(not isinstance(rec, dict) for rec in records.values()):
raise ApplicationError("the tenant registry must be an object of tenant records")
found = []
for slug in sorted(set(runtime._BUILDERS) | set(records)):
rec = records.get(slug)
if rec is not None and rec.get("status", "active") != "active" and slug not in runtime._BUILDERS:
# Suspended logins do not exempt their stored Apps from an explicit retirement.
repo = rec.get("store_repo")
tenant = runtime._builder_from_record(slug, rec)()
rt = runtime.TenantRuntime(
key=slug, tenant=tenant,
store_namespace="" if store.backend() == "pg" or repo else f"t/{slug}/",
store_handle=store.handle(slug=slug) if store.backend() == "pg"
else store.for_repo(repo) if repo else None)
else:
rt = runtime.get_runtime(slug)
if rt.key != slug or getattr(rt.tenant, "key", None) != slug:
raise ApplicationError("retirement runtime does not match its tenant")
if rec is not None and slug not in runtime._BUILDERS:
if (getattr(rt.tenant, "config", {}) or {}).get("store_repo") != (rec.get("store_repo") or None):
raise ApplicationError("the tenant store binding changed; retry with a fresh runtime")
retirement_store_guard(rt, slug)
found.append((slug, rt))
return found
def _retirement_read(runtime, key):
raw = _read_strict(runtime, key)
if raw is None:
return {}
if not isinstance(raw, dict):
raise ApplicationError(f"{key} must be an object")
return raw
def _retirement_view_count(workspaces):
def count(node):
if isinstance(node, list):
return sum(count(value) for value in node)
if not isinstance(node, dict):
return 0
if "id" in node and ("config" in node or "presentation" in node):
return 1
return sum(count(value) for value in node.values())
return sum(count(doc) for doc in workspaces.values())
def _retirement_plan(runtime, tenant):
from core import user_tables, view_templates
retirement_store_guard(runtime, tenant)
doc = _retirement_read(runtime, _KEY)
for key in ("applications", "defaults", "migrations"):
if not isinstance(doc.get(key, {}), dict):
raise ApplicationError(f"Application {key} must be an object")
applications = doc.get("applications", {})
if any(not isinstance(app, dict) or app.get("tenant", tenant) != tenant
for app in applications.values()):
raise ApplicationError("the Application registry has an invalid tenant record")
removed = {identity: app for identity, app in applications.items()
if app.get("templateKind") not in ("route", "catalog", *GATED_TEMPLATE_KINDS)}
tables = _retirement_read(runtime, user_tables.STORE_KEY)
databases = {"customer_data", "product_data"} | {key for key in tables if key.startswith("ut_")}
for app in applications.values():
databases.update(app.get("compatibleDatabases") or ())
if app.get("sourceDatabase"):
databases.add(app["sourceDatabase"])
workspaces = {key: _retirement_read(runtime, view_templates.workspace_key(key))
for key in sorted(databases) if view_templates.workspace_key(key)}
tokens = _retirement_read(runtime, "customer_card_tokens")
public_links = sum(1 for token in tokens.values() if isinstance(token, dict)
and token.get("application") in removed
and token.get("access") in ("public", "password"))
return {"doc": doc, "removed": removed, "databases": sorted(workspaces),
"counts": {"databases": 2 + sum(key.startswith("ut_") for key in tables),
"views": _retirement_view_count(workspaces)},
"publicLinks": public_links}
def retire_kinds(runtime, tenant, user, *, is_admin=False, dry_run=True, confirm=None):
"""Preview or explicitly retire obsolete Apps while preserving every database and saved View."""
if not is_admin:
raise PermissionError("Only an Administrator may retire App kinds.")
if type(dry_run) is not bool:
raise ApplicationError("dry_run must be a boolean")
if not dry_run and confirm != RETIRE_KINDS_CONFIRM:
raise ApplicationError("Use the confirm phrase from the dry run.")
result = {"tenant": tenant, "deleted": 0, "dry_run": dry_run,
"confirm_phrase": RETIRE_KINDS_CONFIRM}
try:
plan = _retirement_plan(runtime, tenant)
removed = plan["removed"]
result.update(toDelete=len(removed), publicLinks=plan["publicLinks"],
before=plan["counts"], after=copy.deepcopy(plan["counts"]),
line=f"{tenant}: {len(removed)} Apps to delete")
if dry_run:
return dict(result, outcome="preview")
marker = plan["doc"].get("migrations", {}).get(RETIRED_KINDS_MARKER)
if isinstance(marker, dict) and marker.get("state") == "done":
if removed:
raise ApplicationError("retirement already completed but obsolete Apps were added")
return dict(result, outcome="already_completed")
from core.user_tables import _activity_writer
if removed and _activity_writer(runtime, user) is None:
raise ApplicationError("App retirement requires the tenant activity log")
# Cleanup precedes the sole registry update, so a failed clear leaves deletion retryable.
cleared = 0
for identity in removed:
count, failed = clear_view_references(runtime, identity, plan["databases"])
cleared += count
if failed:
raise ApplicationError("View cleanup failed: " + "; ".join(failed))
after = _retirement_plan(runtime, tenant)
if after["counts"] != plan["counts"]:
raise ApplicationError("Database or View counts changed during retirement; retry the dry run")
def apply(raw):
if (raw or {}) != plan["doc"]:
raise ApplicationError("Apps changed during retirement; retry the dry run")
doc = copy.deepcopy(raw or {})
for identity in removed:
doc.setdefault("applications", {}).pop(identity)
for key, identity in list(doc.get("defaults", {}).items()):
if identity in removed:
doc["defaults"].pop(key)
doc.setdefault("migrations", {})[RETIRED_KINDS_MARKER] = {
"state": "done", "at": write_execution.utcnow().isoformat(), "by": user,
"deleted": len(removed), "publicLinks": plan["publicLinks"],
"viewsCleared": cleared, "before": plan["counts"], "after": after["counts"]}
return doc
saved = _update_with_activity(runtime, tuple(removed), user, apply, via="App retirement")
if saved is False:
raise ApplicationError("the App retirement was not saved")
return dict(result, outcome="retired", deleted=len(removed), viewsCleared=cleared,
after=after["counts"])
except Exception as exc:
return dict(result, outcome="skipped", reason=f"{type(exc).__name__}: {exc}")
def delete(runtime, app_id, user, is_admin=False, *, allowed_databases=None,
confirm_name=_ANY_NAME, via=None, on_behalf_of=None):
"""Delete one App record. Its databases, Views and records stay; Views lose the dead id.
`confirm_name`, when given, must equal the stored name inside the same atomic update.
"""
removed = {}
def apply(raw):
doc=_clean_doc(raw); app=doc["applications"].get(app_id)
if not app: raise ApplicationError("application does not exist")
if not _is_finance(app) and not _allowed(app.get("compatibleDatabases"), allowed_databases):
if not _database_free(app):
raise ApplicationError("application does not exist")
if not may_edit(app,user,is_admin): raise PermissionError("application belongs to another user")
if confirm_name is not _ANY_NAME and (
not isinstance(confirm_name, str) or confirm_name != app.get("name")):
raise ApplicationError("enter the exact App name to confirm deletion")
if app.get("templateKind") == "catalog":
from catalog_store import migrate_legacy
migrate_legacy(runtime, app)
removed.update(doc["applications"].pop(app_id))
for key in list(doc["defaults"]):
if doc["defaults"][key]==app_id: doc["defaults"].pop(key)
return doc
document_key = _application_key(runtime, app_id)
_update_with_activity(runtime, app_id, user, apply, via=via, on_behalf_of=on_behalf_of,
document_key=document_key)
if document_key != _KEY:
def clear_defaults(raw):
doc = _clean_doc(raw)
doc["defaults"] = {key: value for key, value in doc["defaults"].items() if value != app_id}
return doc
if app_id in _clean_doc(_read_strict(runtime, _KEY))["defaults"].values():
_update_document(runtime, clear_defaults)
result = {"deleted": app_id}
# After the registry write: a failed clear is reported, never an undone delete.
cleared, failed = clear_view_references(runtime, app_id, removed.get("compatibleDatabases"))
if cleared:
result["viewsCleared"] = cleared
if failed:
result["viewsNotCleared"] = "; ".join(failed)
kind = removed.get("templateKind")
contract = _app_templates.BY_KIND.get(kind)
if contract and contract.get("module"):
try:
if not any(row.get("templateKind") == kind for row in load(runtime)["applications"].values()):
from importlib import import_module
module = import_module(contract["module"])
cleanup = next((getattr(module, name) for name in
("remove_app_data", "on_app_removed", "remove")
if callable(getattr(module, name, None))), None)
if cleanup is not None:
cleanup(removed.get("tenant") or runtime.key, st=runtime)
except Exception as exc:
result["appDataNotCleared"] = type(exc).__name__
return result
def set_default(runtime, database, kind, app_id, user, is_admin=False, *, allowed_databases=None,
via=None, on_behalf_of=None):
if kind not in APPLICATION_TYPES: raise ApplicationError("application type is not recognized")
if not is_admin: raise PermissionError("only a tenant admin can change Application defaults")
if database not in set(allowed_databases or ()):
raise PermissionError("that database is not available")
key=f"{database}::{kind}"
def apply(raw):
doc=_clean_doc(raw)
record_key = _application_key(runtime, app_id)
app = (doc if record_key == _KEY else _clean_doc(_read_strict(runtime, record_key)))["applications"].get(app_id)
if (not isinstance(app, dict) or not may_edit(app,user,is_admin)
or database not in (app.get("compatibleDatabases") or ())
or app.get("type")!=kind):
raise ApplicationError("application is not compatible with this default")
doc["defaults"][key]=app_id; return doc
_update_with_activity(runtime, app_id, user, apply, via=via, on_behalf_of=on_behalf_of)
return resolve_default(
runtime,database,kind,user,is_admin,allowed_databases=allowed_databases)
def resolve_default(runtime, database, kind, user, is_admin=False, *, allowed_databases=None):
if kind not in APPLICATION_TYPES:
raise ApplicationError("application type is not recognized")
if database not in set(allowed_databases or ()):
raise PermissionError("that database is not available")
doc=load(runtime); explicit=doc["defaults"].get(f"{database}::{kind}")
app=doc["applications"].get(explicit)
if app and app.get("retired") is not True and may_read(app,user,is_admin) and database in (app.get("compatibleDatabases") or ()) and app.get("type")==kind:
return {"resolution":"explicit","application":_public(
app,user,is_admin,allowed_databases=allowed_databases,target_database=database,
is_default=True)}
# A retired seed still resolves by id but is never offered as the latest default.
matches=[x for x in doc["applications"].values() if x.get("type")==kind and database in (x.get("compatibleDatabases") or ()) and may_read(x,user,is_admin) and x.get("retired") is not True]
matches.sort(key=lambda x:(str(x.get("updatedAt") or ""),str(x.get("id"))),reverse=True)
return {"resolution":"latest" if matches else "blank",
"application":_public(matches[0],user,is_admin,allowed_databases=allowed_databases,
target_database=database) if matches else None}
"""Tenant-level reusable Application assets and deterministic default resolution."""
from __future__ import annotations
import base64
import copy
import hashlib
import json
from core import shares, write_execution
from core.request_timing import raise_if_resource_error
import app_rules
import app_templates as _app_templates
from modules.finance_apps import (finance_application as _finance_application,
finance_applications as _finance_applications,
finance_group as _finance_group)
from modules.finance_spine import fact_specs as _finance_fact_specs
APPLICATION_TYPES = ("chart", "route", "map", "code")
# Finance descriptors remain available to the governed fact routes.
FINANCE_TEMPLATE_KIND = "finance"
_KEY = "applications_v1"
_RECORD_PREFIX = "applications_v1_app/"
#: D-8392 (R58): the most live Apps one account may create. The cap counts per account, never per tenant.
_MAX = 500
_MAX_DISPLAY_BYTES = 512 * 1024
# Routing and Catalog are the first authored App templates. These are wire contracts, not
# executable module declarations: the client renders a trusted platform surface from the stored
# definition. ``required`` is consumed by the creation flow and enforced again below, so a
# future client cannot weaken a template by skipping a wizard step.
_TEMPLATE_CONTRACTS = {
"route": {
"kind": "route",
"label": "Routing",
"applicationType": "route",
"displayMode": "map",
"fieldRoles": [
{"key": "title", "label": "Record title", "required": True, "types": []},
{"key": "latitude", "label": "Latitude", "required": False,
"types": ["text", "int", "currency", "pct", "rating", "number", "float", "decimal"]},
{"key": "longitude", "label": "Longitude", "required": False,
"types": ["text", "int", "currency", "pct", "rating", "number", "float", "decimal"]},
{"key": "address", "label": "Address", "required": False,
"types": ["text"]},
],
"defaultPlacement": {"section": "app", "order": 0},
},
"catalog": {
"kind": "catalog",
"label": "Catalog",
# Catalog is a template discriminator over an existing trusted renderer contract. The
# client launches the Catalog surface from ``templateKind`` without growing the type
# vocabulary shared by the registry and its consumers.
"applicationType": "map",
"displayMode": "map",
"fieldRoles": [
{"key": "key", "label": "Record key", "required": True, "types": []},
{"key": "title", "label": "Record title", "required": True, "types": []},
{"key": "image", "label": "Image", "required": False,
"types": ["image", "attachment", "url", "text"]},
{"key": "sku", "label": "SKU", "required": False, "types": []},
{"key": "price", "label": "Price", "required": False,
"types": ["int", "currency", "pct", "rating", "number", "float", "decimal"]},
{"key": "category", "label": "Category", "required": False, "types": []},
{"key": "description", "label": "Description", "required": False, "types": []},
],
"defaultPlacement": {"section": "app", "order": 0},
},
}
# C1 (S79-T01): every contract carries its catalogue row's wire metadata.
_C1_WIRE_KEYS = ("connector", "connectors", "purpose", "process", "mark", "view")
# R33: Routing and Catalog read their C1 source themselves, so the wizard asks for no database.
_BUNDLED_SOURCE_LABELS = {"customer_data": "Odoo customers", "product_data": "Odoo products"}
for _kind, _contract in _TEMPLATE_CONTRACTS.items():
_contract.update({key: _app_templates.BY_KIND[_kind][key] for key in _C1_WIRE_KEYS})
_contract.update(sourceDatabase=_app_templates.source(_kind),
sourceLabel=_BUNDLED_SOURCE_LABELS[_app_templates.source(_kind)])
# Keep stored copy identities readable after a template stops accepting new Apps.
APPLICATION_WIZARD_TEMPLATE_KINDS = tuple(_TEMPLATE_CONTRACTS)
APPLICATION_TEMPLATE_KINDS = tuple(_TEMPLATE_CONTRACTS)
#: S78-T17 (C4, R20, R21): templates offered only to a tenant that passes the kind's gate.
#: They stay out of the ungated tuples above, which other gates pin to Routing and Catalog.
#: S79-T01 (C1): every connector-gated kind in `app_templates.TEMPLATES` is one of them.
BRAND_ANALYTICS_DATABASE = "ut_amzn_brand_analytics"
# Wire fields a C1 row does not carry, per gated kind.
_GATED_WIRE = {
"competitor_watch": {
"fieldRoles": [
{"key": "term", "label": "Search term", "required": True, "types": []},
],
"sourceLabel": "Amazon brand analytics",
},
}
def _source_label(database):