xp-libs-analytics 0.4.0__py3-none-any.whl

xp_libs_analytics/errors/catalog.json

@@ -0,0 +1,75 @@
+{
+  "INPUT_INVALID_JSON": "Input is not valid JSON. Fix: supply one JSON object, an array of objects, or newline-delimited JSON objects. Example: [{\"value\":12},{\"value\":15}]",
+  "INPUT_INVALID_NDJSON": "One or more nonblank NDJSON lines is not a valid JSON object. Fix: put exactly one object on each line. Example: {\"value\":12} followed by a newline and {\"value\":15}.",
+  "INPUT_DUPLICATE_KEY": "A JSON object contains a repeated property name; accepting it could change query meaning. Fix: retain only one occurrence of each key. Example: {\"value\":12}, not {\"value\":12,\"value\":15}.",
+  "INPUT_UNSUPPORTED_ROOT": "The input root is not an object or an array of objects. Fix: wrap each scalar inside an object. Example: [{\"value\":12},{\"value\":15}] instead of [12,15].",
+  "INPUT_INVALID_UTF8": "Input contains invalid UTF-8 encoding. Fix: encode the JSON text as UTF-8 without invalid byte sequences. Example: json.dumps(records, ensure_ascii=False).encode('utf-8').",
+  "INPUT_INVALID_NUMBER": "Input contains a non-JSON or non-finite number. Fix: use finite JSON numbers and null for absent measurements. Example: {\"value\":null} rather than NaN or Infinity.",
+  "INPUT_TOO_DEEP": "Input JSON nesting exceeds the configured limit. Fix: flatten or select a smaller object hierarchy before ingestion. Example: {\"meta\":{\"kind\":\"a\"}}.",
+  "INPUT_TOO_WIDE": "Input contains more distinct field paths than the configured limit. Fix: project needed fields before ingestion or split the dataset into authorized smaller snapshots. Example: retain /time, /region and /value.",
+  "INPUT_RECORD_TOO_LARGE": "A single JSON record exceeds the configured record-size limit. Fix: remove oversized free-text/binary payloads or split the record. Example: keep the numeric measurements rather than embedded document bodies.",
+  "INPUT_BYTES_LIMIT": "Input payload exceeds the configured byte limit. Fix: submit fewer records or provide a trusted server-side data source. Example: register 10000 records instead of a multi-gigabyte MCP argument.",
+  "INPUT_ROWS_LIMIT": "Input has more records than the configured admission limit. Fix: reduce the batch or use a trusted server-side adapter with approved chunking. Example: register a smaller time-bounded snapshot.",
+  "DATA_FIELD_UNKNOWN": "The requested JSON Pointer does not appear in the authorized discovered schema. Fix: call analytics_describe, then use an exact listed path. Example: /metrics/latency rather than /metric/latency.",
+  "DATA_FIELD_TYPE_CONFLICT": "A field contains incompatible JSON types and cannot be used directly by this operation. Fix: select a compatible field or add an explicit permitted cast. Example: casts:[{\"field\":\"/value\",\"to\":\"float64\",\"on_error\":\"null\"}].",
+  "DATA_FIELD_NOT_SCALAR": "An operation requires a scalar field but the selected path contains an object or array. Fix: choose a scalar JSON Pointer inside the object. Example: /metrics/latency, not /metrics.",
+  "DATA_CAST_UNSUPPORTED": "The requested type cast or timestamp format is not supported. Fix: use float64, int64, string or datetime with a documented format. Example: {\"field\":\"/ts\",\"to\":\"datetime\",\"format\":\"rfc3339\",\"on_error\":\"reject\"}.",
+  "DATA_CAST_FAILED": "One or more present values cannot be converted using the declared cast. Fix: correct the records or choose on_error=null if policy permits. Example: replace {\"value\":\"unknown\"} with a number before casting to float64.",
+  "DATA_TIMESTAMP_INVALID": "The selected time field has an invalid or offset-ambiguous timestamp. Fix: use RFC3339 with Z or an explicit UTC offset, or declare a numeric epoch unit. Example: 2026-11-06T10:00:00Z.",
+  "QUERY_VERSION_UNSUPPORTED": "The query language version is not supported. Fix: call analytics_capabilities and use a listed version. Example: \"version\":\"analytics.query/v1\".",
+  "QUERY_MALFORMED": "The query object does not match the versioned contract, contains unknown properties, or has invalid data types. Fix: compare the request with the published schema. Example: use numeric \"limit\":100 rather than \"limit\":\"100\".",
+  "QUERY_UNKNOWN_OPERATOR": "A filter, aggregation, or window operator is unsupported. Fix: select an operator listed by analytics_capabilities. Example: {\"op\":\"p95\",\"field\":\"/value\",\"as\":\"p95_value\"}.",
+  "QUERY_OPERATOR_TYPE": "The selected operator cannot be applied to the field's resolved type. Fix: select a compatible field/operator or an approved explicit cast. Example: use avg on numeric /value rather than a string /label.",
+  "QUERY_INVALID_POINTER": "A field path is not a valid RFC 6901 JSON Pointer. Fix: use slash-separated tokens and escape ~ as ~0 and / as ~1. Example: /metrics/latency.",
+  "QUERY_INVALID_LITERAL": "A comparison value or membership list has an incompatible type, size, or shape. Fix: use a single typed scalar or a bounded homogeneous values list. Example: {\"field\":\"/region\",\"op\":\"in\",\"values\":[\"west\",\"east\"]}.",
+  "QUERY_PREDICATE_LIMIT": "Predicate nesting or condition count exceeds V1 limits. Fix: simplify the AND/OR tree and split unrelated investigations into separate queries. Example: one AND with two comparisons.",
+  "QUERY_ALIAS_INVALID": "An output alias is invalid, reserved, or duplicates another alias. Fix: use a unique identifier starting with a letter and containing only letters, digits or underscores. Example: \"as\":\"avg_value\".",
+  "QUERY_GROUP_INVALID": "A group-by field is absent, incompatible, duplicated, or exceeds allowed grouping dimensions. Fix: group by a small number of visible scalar fields. Example: group_by:[{\"field\":\"/region\",\"as\":\"region\"}].",
+  "QUERY_TIME_RANGE_INVALID": "The time range is missing required boundaries, has an invalid timezone, or has start at/after end. Fix: use one relative range or offset-aware start and end. Example: {\"field\":\"/ts\",\"last_minutes\":60}.",
+  "QUERY_WINDOW_INVALID": "The time window has an invalid size, step, overlap, or missing time_range. Fix: use allowed fixed durations, with step not exceeding size. Example: {\"type\":\"sliding\",\"size\":\"5m\",\"step\":\"1m\"} with a valid time_range.",
+  "QUERY_EMPTY_WINDOW_UNSUPPORTED": "Empty-window materialization is not supported for this unbounded or unconstrained group space. Fix: disable include_empty_windows or use a constrained small group set. Example: options:{\"include_empty_windows\":false}.",
+  "QUERY_HAVING_INVALID": "A HAVING condition refers to an unavailable result alias or unsupported predicate. Fix: use an alias created by an aggregation or group_by. Example: having:[{\"field\":\"events\",\"op\":\"gte\",\"value\":2}].",
+  "QUERY_ORDER_INVALID": "Order-by refers to an unknown result field or unsupported direction. Fix: sort by a declared alias or window_start/window_end. Example: order_by:[{\"field\":\"events\",\"direction\":\"desc\"}].",
+  "QUERY_LIMIT_INVALID": "The requested result limit is outside the configured range. Fix: use a positive integer within server limits. Example: \"limit\":100.",
+  "QUERY_UNSUPPORTED_FEATURE": "The request uses a capability reserved for a future version, such as joins, unions, continuous queries, or external sinks. Fix: make a V1 single-dataset snapshot query. Example: dataset: {name: observations} without sources/joins/outputs.",
+  "QUERY_TOO_EXPENSIVE": "The estimated query amplification, grouping cost, or data access exceeds the allowed budget. Fix: shorten the time range, reduce grouping dimensions, or increase the window step. Example: use a tumbling 5m window instead of many overlapping 1s windows.",
+  "ACCESS_DENIED": "The caller is not authorized to perform this operation or to access this dataset or metadata. Fix: use a dataset registered under your authenticated session or request permission from its owner. Example: query a name discovered in your authenticated context.",
+  "ACCESS_FIELD_DENIED": "A requested field or field metadata is restricted for this caller. Fix: query only fields returned by your authorized analytics_describe response. Example: remove a restricted group_by or aggregation path.",
+  "ACCESS_UPLOAD_DISABLED": "This deployment does not permit agents to upload raw JSON through MCP. Fix: ask the trusted hosting application to register records using the Python SDK and provide a context-local logical name. Example: engine.register_records(name=\"observations\", records=records).",
+  "RESOURCE_GROUPS_LIMIT": "The number of distinct groups exceeds the execution budget. Fix: remove high-cardinality group_by fields or filter to a smaller scope. Example: group by /region instead of /request_id.",
+  "RESOURCE_WINDOWS_LIMIT": "The number of generated temporal windows exceeds the limit. Fix: choose a larger step/size or reduce the time range. Example: size=5m and step=5m instead of size=1h and step=1s.",
+  "RESOURCE_RESULT_LIMIT": "The serialized result exceeds the permitted byte or row budget. Fix: reduce limit, group cardinality, or requested output fields. Example: set limit=50 and rank by a numeric aggregate.",
+  "RESOURCE_MEMORY_LIMIT": "An execution exceeded its allocated memory budget. Fix: reduce input size or query complexity and retry once if permitted. Example: aggregate a smaller authorized snapshot.",
+  "RESOURCE_TIMEOUT": "An analytical query exceeded its execution deadline. Fix: use a smaller snapshot, narrower range or fewer groups, then retry. Example: remove an expensive count_distinct on a high-cardinality field.",
+  "RESOURCE_CONCURRENCY_LIMIT": "The caller reached the allowed concurrent query count. Fix: finish or cancel an existing request and retry after backoff. Example: run one analytics_query at a time for the same dataset.",
+  "EXECUTION_CANCELLED": "The execution was canceled before completion. Fix: re-run the query only if the caller still needs it and the same logical dataset binding is valid. Example: submit the original query after an explicit cancellation acknowledgment.",
+  "EXECUTION_BACKEND_ERROR": "The analytical backend could not complete the requested operation. Fix: verify the query with analytics_validate_query and retry only if permitted; report the query_id if the failure persists. Example: rerun with a supported aggregation such as avg.",
+  "MCP_INVALID_TOOL_CALL": "The MCP tool arguments or invocation shape are invalid. Fix: list the available tools and follow the published tool input schema. Example: call analytics_describe(name=\"observations\").",
+  "MCP_UNAVAILABLE": "The MCP adapter or selected transport is unavailable. Fix: reconnect and verify the server and transport configuration. Example: start the server using the documented xp-libs-analytics entry point.",
+  "INTERNAL_ERROR": "An unexpected server error occurred; no record data is included in this message. Fix: report the query_id to the operator and avoid blind repeated retries. Example: check the server's trace for that query_id.",
+  "QUERY_YAML_INVALID": "The YAML query contains a syntax or indentation error. Fix: submit one correctly indented YAML mapping and quote ambiguous strings. Example: aggregations:\n  - op: count\n    as: rows.",
+  "QUERY_YAML_DUPLICATE_KEY": "The YAML query repeats a mapping key, so its meaning is ambiguous. Fix: keep exactly one occurrence of the key at that mapping level. Example: limit: 100 appears once, not twice.",
+  "QUERY_YAML_ANCHOR_FORBIDDEN": "YAML anchors are not supported in analytical queries. Fix: write each bounded filter or aggregation explicitly without &anchor. Example: aggregations: [{op: count, as: rows}].",
+  "QUERY_YAML_ALIAS_FORBIDDEN": "YAML aliases are not supported because they can create recursive or amplified document graphs. Fix: expand the intended bounded mapping explicitly without *alias. Example: filters: [{field: /region, op: eq, value: west}].",
+  "QUERY_YAML_TAG_FORBIDDEN": "Explicit YAML tags and tag directives are not supported. Fix: use ordinary mappings, sequences and scalar values; never use ! or !! constructors. Example: limit: 100.",
+  "QUERY_YAML_MULTI_DOCUMENT": "Only one YAML query document may be submitted at a time. Fix: remove additional document separators and send one root mapping. Example: version: analytics.query/v1 followed by dataset and aggregations in the same document.",
+  "QUERY_YAML_ROOT_INVALID": "A YAML query must be a nonempty mapping with string keys. Fix: put version, dataset, and aggregations under one top-level mapping. Example: version: analytics.query/v1.",
+  "QUERY_YAML_COMPLEXITY_LIMIT": "The YAML query exceeds permitted bytes, nesting, nodes, keys or scalar length. Fix: simplify predicates or split the investigation into separate bounded queries. Example: a single filter with two conditions.",
+  "QUERY_YAML_SCALAR_INVALID": "The YAML query contains an unsupported or non-finite scalar representation. Fix: use finite decimal numbers or quote data intended as text. Example: value: 12.5 instead of value: .nan.",
+  "DATASET_NAME_UNKNOWN": "Dataset name is not registered in this context. Fix: discover available names with analytics_list_datasets. Example: dataset: {name: observations}.",
+  "DATASET_NAME_DUPLICATE": "Dataset name is already registered in this context. Fix: choose a different name or use replace_records to publish a new snapshot. Example: replace_records(\"observations\", records).",
+  "DATASET_NAME_INVALID": "Dataset name is invalid. Fix: use 1 to 64 ASCII letters, digits, underscores or hyphens, starting with a letter. Example: observations_2026.",
+  "DATASET_SNAPSHOT_STALE": "Dataset snapshot has expired or its revision no longer matches. Fix: discover current metadata and publish or reference the current snapshot. Example: describe(\"observations\").",
+  "RESOURCE_DATASETS_LIMIT": "Named dataset budget exceeded. Fix: unregister an unused dataset before registering another. Example: unregister_dataset(\"observations\").",
+  "MATCH_PATTERN_INVALID": "String pattern is invalid. Fix: escape only percent, underscore or backslash in LIKE, and use nonempty bounded search values. Example: {field: /text, op: like, value: \"Pet%\"}.",
+  "MATCH_REGEX_INVALID": "Regex is not supported by the Rust engine. Fix: remove lookaround/backreferences or use literal matching. Example: {field: /text, op: regex, value: \"^Pet[a-z]+$\"}.",
+  "MATCH_REGEX_POLICY": "Regex or wildcard pattern exceeds host policy or is an empty-string catch-all. Fix: use a bounded selective pattern without unsupported flags. Example: {field: /text, op: contains, value: Peter}.",
+  "MATCH_NORMALIZATION_INVALID": "String normalization is incompatible with this predicate or field. Fix: normalize strings only; regex permits case handling only, and ILIKE cannot request case-sensitive matching. Example: normalization: {case_sensitive: false, unicode: nfkc, trim: true}.",
+  "MATCH_FUZZY_ALGORITHM_INVALID": "Fuzzy scorer is invalid or absent. Fix: choose an approved algorithm. Example: {field: /text, op: fuzzy, value: Peter, algorithm: ratio, min_score: 85}.",
+  "MATCH_FUZZY_THRESHOLD_INVALID": "Fuzzy similarity threshold is invalid, absent or below host policy. Fix: supply a finite numeric min_score within the allowed range. Example: {field: /text, op: fuzzy, value: Peter, algorithm: ratio, min_score: 85}.",
+  "MATCH_FUZZY_QUERY_TOO_SHORT": "Normalized fuzzy search text is shorter than host policy permits. Fix: provide longer text or use exact/literal matching. Example: {field: /text, op: eq, value: Li}.",
+  "MATCH_CANDIDATE_BUDGET_EXCEEDED": "Exhaustive string matching exceeds the host candidate, length or byte budget. Fix: narrow authorized time/nonfuzzy filters without claiming a complete result for the original scope. Example: filters: [{field: /status, op: eq, value: error}].",
+  "MATCH_COMPLEXITY_BUDGET_EXCEEDED": "Matching fields, patterns or total comparisons exceed host policy. Fix: reduce repeated matching work or narrow eligible data; result limit does not reduce scanning. Example: match: {fields: [/text], patterns: [{op: word, value: Peter}], mode: any}.",
+  "MATCH_DIAGNOSTICS_UNAUTHORIZED": "Raw matching values are not authorized by host and field disclosure policy. Fix: request redacted diagnostics. Example: options: {matching_details: {include: true, include_raw_values: false}}.",
+  "MATCH_ENTITY_INFERENCE_UNSUPPORTED": "V1 string similarity does not resolve or verify identities, aliases or entity ownership. Fix: report matching observed values without merging people. Example: {field: /text, op: fuzzy, value: Peter, algorithm: ratio, min_score: 85}."
+}

xp_libs_analytics/errors/codes.py

@@ -0,0 +1,81 @@
+"""Closed V1 code vocabulary; messages live only in catalog.json."""
+
+from enum import StrEnum
+
+
+class ErrorCode(StrEnum):
+    INPUT_INVALID_JSON = "INPUT_INVALID_JSON"
+    INPUT_INVALID_NDJSON = "INPUT_INVALID_NDJSON"
+    INPUT_DUPLICATE_KEY = "INPUT_DUPLICATE_KEY"
+    INPUT_UNSUPPORTED_ROOT = "INPUT_UNSUPPORTED_ROOT"
+    INPUT_INVALID_UTF8 = "INPUT_INVALID_UTF8"
+    INPUT_INVALID_NUMBER = "INPUT_INVALID_NUMBER"
+    INPUT_TOO_DEEP = "INPUT_TOO_DEEP"
+    INPUT_TOO_WIDE = "INPUT_TOO_WIDE"
+    INPUT_RECORD_TOO_LARGE = "INPUT_RECORD_TOO_LARGE"
+    INPUT_BYTES_LIMIT = "INPUT_BYTES_LIMIT"
+    INPUT_ROWS_LIMIT = "INPUT_ROWS_LIMIT"
+    DATASET_NAME_UNKNOWN = "DATASET_NAME_UNKNOWN"
+    DATASET_SNAPSHOT_STALE = "DATASET_SNAPSHOT_STALE"
+    DATA_FIELD_UNKNOWN = "DATA_FIELD_UNKNOWN"
+    DATA_FIELD_TYPE_CONFLICT = "DATA_FIELD_TYPE_CONFLICT"
+    DATA_FIELD_NOT_SCALAR = "DATA_FIELD_NOT_SCALAR"
+    DATA_CAST_UNSUPPORTED = "DATA_CAST_UNSUPPORTED"
+    DATA_CAST_FAILED = "DATA_CAST_FAILED"
+    DATA_TIMESTAMP_INVALID = "DATA_TIMESTAMP_INVALID"
+    QUERY_VERSION_UNSUPPORTED = "QUERY_VERSION_UNSUPPORTED"
+    QUERY_MALFORMED = "QUERY_MALFORMED"
+    QUERY_UNKNOWN_OPERATOR = "QUERY_UNKNOWN_OPERATOR"
+    QUERY_OPERATOR_TYPE = "QUERY_OPERATOR_TYPE"
+    QUERY_INVALID_POINTER = "QUERY_INVALID_POINTER"
+    QUERY_INVALID_LITERAL = "QUERY_INVALID_LITERAL"
+    QUERY_PREDICATE_LIMIT = "QUERY_PREDICATE_LIMIT"
+    QUERY_ALIAS_INVALID = "QUERY_ALIAS_INVALID"
+    QUERY_GROUP_INVALID = "QUERY_GROUP_INVALID"
+    QUERY_TIME_RANGE_INVALID = "QUERY_TIME_RANGE_INVALID"
+    QUERY_WINDOW_INVALID = "QUERY_WINDOW_INVALID"
+    QUERY_EMPTY_WINDOW_UNSUPPORTED = "QUERY_EMPTY_WINDOW_UNSUPPORTED"
+    QUERY_HAVING_INVALID = "QUERY_HAVING_INVALID"
+    QUERY_ORDER_INVALID = "QUERY_ORDER_INVALID"
+    QUERY_LIMIT_INVALID = "QUERY_LIMIT_INVALID"
+    QUERY_UNSUPPORTED_FEATURE = "QUERY_UNSUPPORTED_FEATURE"
+    QUERY_TOO_EXPENSIVE = "QUERY_TOO_EXPENSIVE"
+    ACCESS_DENIED = "ACCESS_DENIED"
+    ACCESS_FIELD_DENIED = "ACCESS_FIELD_DENIED"
+    ACCESS_UPLOAD_DISABLED = "ACCESS_UPLOAD_DISABLED"
+    RESOURCE_DATASETS_LIMIT = "RESOURCE_DATASETS_LIMIT"
+    RESOURCE_GROUPS_LIMIT = "RESOURCE_GROUPS_LIMIT"
+    RESOURCE_WINDOWS_LIMIT = "RESOURCE_WINDOWS_LIMIT"
+    RESOURCE_RESULT_LIMIT = "RESOURCE_RESULT_LIMIT"
+    RESOURCE_MEMORY_LIMIT = "RESOURCE_MEMORY_LIMIT"
+    RESOURCE_TIMEOUT = "RESOURCE_TIMEOUT"
+    RESOURCE_CONCURRENCY_LIMIT = "RESOURCE_CONCURRENCY_LIMIT"
+    EXECUTION_CANCELLED = "EXECUTION_CANCELLED"
+    EXECUTION_BACKEND_ERROR = "EXECUTION_BACKEND_ERROR"
+    MCP_INVALID_TOOL_CALL = "MCP_INVALID_TOOL_CALL"
+    MCP_UNAVAILABLE = "MCP_UNAVAILABLE"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    QUERY_YAML_INVALID = "QUERY_YAML_INVALID"
+    QUERY_YAML_DUPLICATE_KEY = "QUERY_YAML_DUPLICATE_KEY"
+    QUERY_YAML_ANCHOR_FORBIDDEN = "QUERY_YAML_ANCHOR_FORBIDDEN"
+    QUERY_YAML_ALIAS_FORBIDDEN = "QUERY_YAML_ALIAS_FORBIDDEN"
+    QUERY_YAML_TAG_FORBIDDEN = "QUERY_YAML_TAG_FORBIDDEN"
+    QUERY_YAML_MULTI_DOCUMENT = "QUERY_YAML_MULTI_DOCUMENT"
+    QUERY_YAML_ROOT_INVALID = "QUERY_YAML_ROOT_INVALID"
+    QUERY_YAML_COMPLEXITY_LIMIT = "QUERY_YAML_COMPLEXITY_LIMIT"
+    QUERY_YAML_SCALAR_INVALID = "QUERY_YAML_SCALAR_INVALID"
+
+    DATASET_NAME_DUPLICATE = "DATASET_NAME_DUPLICATE"
+    DATASET_NAME_INVALID = "DATASET_NAME_INVALID"
+
+    MATCH_PATTERN_INVALID = "MATCH_PATTERN_INVALID"
+    MATCH_REGEX_INVALID = "MATCH_REGEX_INVALID"
+    MATCH_REGEX_POLICY = "MATCH_REGEX_POLICY"
+    MATCH_NORMALIZATION_INVALID = "MATCH_NORMALIZATION_INVALID"
+    MATCH_FUZZY_ALGORITHM_INVALID = "MATCH_FUZZY_ALGORITHM_INVALID"
+    MATCH_FUZZY_THRESHOLD_INVALID = "MATCH_FUZZY_THRESHOLD_INVALID"
+    MATCH_FUZZY_QUERY_TOO_SHORT = "MATCH_FUZZY_QUERY_TOO_SHORT"
+    MATCH_CANDIDATE_BUDGET_EXCEEDED = "MATCH_CANDIDATE_BUDGET_EXCEEDED"
+    MATCH_COMPLEXITY_BUDGET_EXCEEDED = "MATCH_COMPLEXITY_BUDGET_EXCEEDED"
+    MATCH_DIAGNOSTICS_UNAUTHORIZED = "MATCH_DIAGNOSTICS_UNAUTHORIZED"
+    MATCH_ENTITY_INFERENCE_UNSUPPORTED = "MATCH_ENTITY_INFERENCE_UNSUPPORTED"

xp_libs_analytics/ingest/__init__.py

@@ -0,0 +1,309 @@
+"""Bounded JSON admission, schema discovery and owner-scoped snapshots."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+import secrets
+import threading
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any, cast
+
+from xp_libs_analytics.errors import AnalyticsError
+from xp_libs_analytics.policy import Limits, Principal, RequestBudget
+
+
+def pointer_tokens(path: str, max_depth: int = 12) -> list[str]:
+    if not path.startswith("/") or re.search(r"~(?![01])", path):
+        raise AnalyticsError("QUERY_INVALID_POINTER")
+    tokens = path[1:].split("/")
+    if len(tokens) > max_depth:
+        raise AnalyticsError("QUERY_INVALID_POINTER")
+    return [t.replace("~1", "/").replace("~0", "~") for t in tokens]
+
+
+def kind(value: Any) -> str:
+    return {
+        type(None): "null",
+        bool: "boolean",
+        int: "integer",
+        float: "float",
+        str: "string",
+        dict: "object",
+        list: "array",
+        datetime: "datetime",
+    }[type(value)]
+
+
+def reject_constant(_: str) -> Any:
+    raise AnalyticsError("INPUT_INVALID_NUMBER")
+
+
+def pairs_hook(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise AnalyticsError("INPUT_DUPLICATE_KEY")
+        result[key] = value
+    return result
+
+
+def loads(text: str) -> Any:
+    return json.loads(text, object_pairs_hook=pairs_hook, parse_constant=reject_constant)
+
+
+def admit(data: Any, limits: Limits, *, ndjson: bool = False) -> tuple[list[dict[str, Any]], int]:
+    if isinstance(data, bytes):
+        if len(data) > limits.max_bytes:
+            raise AnalyticsError("INPUT_BYTES_LIMIT")
+        try:
+            data = data.decode("utf-8")
+        except UnicodeError:
+            raise AnalyticsError("INPUT_INVALID_UTF8") from None
+    if isinstance(data, str):
+        try:
+            if len(data.encode("utf-8")) > limits.max_bytes:
+                raise AnalyticsError("INPUT_BYTES_LIMIT")
+            if ndjson:
+                data = [loads(line) for line in data.splitlines() if line.strip()]
+            else:
+                try:
+                    data = loads(data)
+                except json.JSONDecodeError as exc:
+                    if exc.msg == "Extra data" and "\n" in data:
+                        return admit(data, limits, ndjson=True)
+                    raise
+        except UnicodeError:
+            raise AnalyticsError("INPUT_INVALID_UTF8") from None
+        except (ValueError, RecursionError):
+            raise AnalyticsError(
+                "INPUT_INVALID_NDJSON" if ndjson else "INPUT_INVALID_JSON"
+            ) from None
+    if isinstance(data, Mapping):
+        data = [data]
+    if not isinstance(data, Iterable) or isinstance(data, (str, bytes)):
+        raise AnalyticsError("INPUT_UNSUPPORTED_ROOT")
+    fields: set[str] = set()
+    record_units = [0]
+
+    def check(value: Any, depth: int, path: str, ancestors: set[int]) -> Any:
+        record_units[0] += len(value) if type(value) is str else 1
+        if record_units[0] > limits.max_record_bytes:
+            raise AnalyticsError("INPUT_RECORD_TOO_LARGE")
+        if depth > limits.max_depth:
+            raise AnalyticsError("INPUT_TOO_DEEP")
+        if type(value) in (dict, list) or isinstance(value, Mapping):
+            if id(value) in ancestors:
+                raise AnalyticsError("INPUT_TOO_DEEP")
+            chain = ancestors | {id(value)}
+            if isinstance(value, Mapping):
+                result = {}
+                for k, v in value.items():
+                    if type(k) is not str:
+                        raise AnalyticsError("INPUT_UNSUPPORTED_ROOT")
+                    p = path + "/" + k.replace("~", "~0").replace("/", "~1")
+                    fields.add(p)
+                    if len(fields) > limits.max_columns:
+                        raise AnalyticsError("INPUT_TOO_WIDE")
+                    result[k] = check(v, depth + 1, p, chain)
+                return result
+            return [check(v, depth + 1, path, chain) for v in value]
+        if type(value) is float and not math.isfinite(value):
+            raise AnalyticsError("INPUT_INVALID_NUMBER")
+        if type(value) is int and not -(2**63) <= value < 2**63:
+            raise AnalyticsError("INPUT_INVALID_NUMBER")
+        if type(value) is str:
+            try:
+                value.encode("utf-8")
+            except UnicodeError:
+                raise AnalyticsError("INPUT_INVALID_UTF8") from None
+        elif type(value) not in (int, float, bool, type(None)):
+            raise AnalyticsError("INPUT_UNSUPPORTED_ROOT")
+        return value
+
+    rows: list[dict[str, Any]] = []
+    total = 0
+    for row in data:
+        record_units[0] = 0
+        if len(rows) >= limits.max_rows:
+            raise AnalyticsError("INPUT_ROWS_LIMIT")
+        if not isinstance(row, Mapping):
+            raise AnalyticsError("INPUT_INVALID_NDJSON" if ndjson else "INPUT_UNSUPPORTED_ROOT")
+        copied = check(row, 0, "", set())
+        size = len(json.dumps(copied, ensure_ascii=False, allow_nan=False).encode("utf-8"))
+        if size > limits.max_record_bytes:
+            raise AnalyticsError("INPUT_RECORD_TOO_LARGE")
+        total += size
+        if total > limits.max_bytes:
+            raise AnalyticsError("INPUT_BYTES_LIMIT")
+        rows.append(copied)
+    return rows, total
+
+
+def flatten(record: dict[str, Any], path: str = "") -> dict[str, Any]:
+    result = {}
+    for key, value in record.items():
+        p = path + "/" + key.replace("~", "~0").replace("/", "~1")
+        result[p] = value
+        if isinstance(value, dict):
+            result.update(flatten(value, p))
+    return result
+
+
+@dataclass(frozen=True)
+class DatasetHandle:
+    id: str
+    revision: int = 1
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    handle: DatasetHandle
+    owner: str
+    created: datetime
+    expires: datetime
+    payload: str
+    schema_json: str
+    row_count: int
+    byte_count: int
+    source_kind: str
+
+    def records(self) -> list[dict[str, Any]]:
+        return cast(list[dict[str, Any]], json.loads(self.payload))
+
+    def schema(self) -> dict[str, Any]:
+        return cast(dict[str, Any], json.loads(self.schema_json))
+
+
+class DatasetStore:
+    def __init__(self, limits: Limits) -> None:
+        self.limits = limits
+        self._snapshots: dict[str, Snapshot] = {}
+        self._budgets: dict[str, RequestBudget] = {}
+        self._readers: dict[str, int] = {}
+        self._retired: set[str] = set()
+        self._lock = threading.RLock()
+
+    def request_budget(self, principal: Principal) -> RequestBudget:
+        with self._lock:
+            if principal.id not in self._budgets:
+                self._budgets[principal.id] = RequestBudget(self.limits)
+            return self._budgets[principal.id]
+
+    def expire(self, now: datetime) -> None:
+        with self._lock:
+            for ident, snapshot in list(self._snapshots.items()):
+                if snapshot.expires <= now:
+                    self._retire(ident)
+
+    def _retire(self, ident: str) -> None:
+        if self._readers.get(ident, 0):
+            self._retired.add(ident)
+        else:
+            self._snapshots.pop(ident, None)
+            self._retired.discard(ident)
+
+    def acquire(self, handle: DatasetHandle, principal: Principal, now: datetime) -> Snapshot:
+        with self._lock:
+            snapshot = self.get_snapshot(handle, principal, now)
+            self._readers[handle.id] = self._readers.get(handle.id, 0) + 1
+            return snapshot
+
+    def unpin(self, handle: DatasetHandle) -> None:
+        with self._lock:
+            count = self._readers[handle.id] - 1
+            if count:
+                self._readers[handle.id] = count
+            else:
+                del self._readers[handle.id]
+                if handle.id in self._retired:
+                    self._retire(handle.id)
+
+    def register(
+        self,
+        data: Any,
+        principal: Principal,
+        now: datetime,
+        *,
+        ndjson: bool = False,
+        replaces: DatasetHandle | None = None,
+        revision: int = 1,
+    ) -> DatasetHandle:
+        rows, size = admit(data, self.limits, ndjson=ndjson)
+        flat = [flatten(row) for row in rows]
+        paths = sorted({p for row in flat for p in row})
+        schema = {}
+        for p in paths:
+            values = [row[p] for row in flat if p in row]
+            types = sorted({kind(v) for v in values})
+            nonnull = set(types) - {"null"}
+            resolved = (
+                "float"
+                if nonnull == {"integer", "float"}
+                else next(iter(nonnull))
+                if len(nonnull) == 1
+                else "null"
+                if not nonnull
+                else "mixed"
+            )
+            if resolved == "float" and any(type(v) is int and abs(v) > 2**53 for v in values):
+                raise AnalyticsError("INPUT_INVALID_NUMBER")
+            schema[p] = {
+                "types": types,
+                "type": resolved,
+                "present": len(values),
+                "null": sum(v is None for v in values),
+                "missing": len(rows) - len(values),
+            }
+        with self._lock:
+            self.expire(now)
+            old = self._snapshots.get(replaces.id) if replaces else None
+            reclaim = old.byte_count if old and not self._readers.get(old.handle.id) else 0
+            if (
+                size + sum(s.byte_count for s in self._snapshots.values()) - reclaim
+                > self.limits.max_total_bytes
+            ):
+                raise AnalyticsError("RESOURCE_MEMORY_LIMIT")
+            if (
+                sum(
+                    s.owner == principal.id and k not in self._retired
+                    for k, s in self._snapshots.items()
+                )
+                - int(old is not None and old.handle.id not in self._retired)
+                >= self.limits.max_datasets
+            ):
+                raise AnalyticsError("RESOURCE_DATASETS_LIMIT")
+            handle = DatasetHandle("ds_" + secrets.token_urlsafe(24), revision)
+            self._snapshots[handle.id] = Snapshot(
+                handle,
+                principal.id,
+                now,
+                now + timedelta(seconds=self.limits.ttl_seconds),
+                json.dumps(rows, ensure_ascii=False),
+                json.dumps(schema, sort_keys=True),
+                len(rows),
+                size,
+                "inline_json" if isinstance(data, (str, bytes)) else "in_memory",
+            )
+            if replaces:
+                self._retire(replaces.id)
+            return handle
+
+    def get_snapshot(
+        self, handle: DatasetHandle | str, principal: Principal, now: datetime
+    ) -> Snapshot:
+        ident = handle.id if isinstance(handle, DatasetHandle) else handle
+        with self._lock:
+            snapshot = self._snapshots.get(ident)
+            if snapshot is None or snapshot.owner != principal.id:
+                raise AnalyticsError("ACCESS_DENIED")
+            if snapshot.expires <= now:
+                raise AnalyticsError("DATASET_SNAPSHOT_STALE")
+            return snapshot
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)

xp_libs_analytics/interfaces.py

@@ -0,0 +1,70 @@
+"""Versioned extension seams. V1 executes exactly one snapshot and JSON sink."""
+
+from dataclasses import dataclass
+from typing import Any, Literal, Protocol, cast
+
+from xp_libs_analytics.engine.planner import LogicalPlan
+from xp_libs_analytics.policy import Limits, Principal
+
+
+@dataclass(frozen=True)
+class SourceDescriptor:
+    source_id: str
+    origin: str
+    owner: str
+    schema_hash: str
+    redacted: bool = False
+
+
+@dataclass(frozen=True)
+class InputPort:
+    source_ref: str
+    mode: Literal["snapshot"] = "snapshot"
+    schema_revision: int = 1
+    watermark_capability: bool = False
+
+
+@dataclass(frozen=True)
+class OutputPort:
+    sink_ref: str = "json-response"
+    format: Literal["json"] = "json"
+    delivery_semantics: Literal["request"] = "request"
+
+
+@dataclass(frozen=True)
+class QueryDefinition:
+    id: str
+    plan: LogicalPlan
+
+
+@dataclass(frozen=True)
+class QueryExecution:
+    id: str
+    definition_id: str
+    state: Literal["CREATED", "RUNNING", "STOPPING", "STOPPED", "FAILED"]
+
+
+class DataSource(Protocol):
+    def read(self, request: Any, principal: Principal, budget: Limits) -> Any: ...
+
+
+class ResultSink(Protocol):
+    def write(self, envelope: dict[str, Any], principal: Principal) -> dict[str, Any]: ...
+
+
+class InlineJsonSource:
+    def read(self, request: Any, principal: Principal, budget: Limits) -> Any:
+        from xp_libs_analytics.ingest import admit
+
+        return admit(request, budget)[0]
+
+
+class InMemoryObjectSource(InlineJsonSource):
+    pass
+
+
+class JsonResultSink:
+    def write(self, envelope: dict[str, Any], principal: Principal) -> dict[str, Any]:
+        import json
+
+        return cast(dict[str, Any], json.loads(json.dumps(envelope, allow_nan=False)))

xp_libs_analytics/matching/__init__.py

@@ -0,0 +1 @@
+"""Shared bounded string matching; no identity inference or cross-query cache."""