mainsequence-metatable 0.1.11.dev22__tar.gz → 0.1.12.dev24__tar.gz

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/.agents/skills/client/metatables-local-development/SKILL.md

@@ -145,7 +145,11 @@ existing database just to obtain a clean test run.
 SQLite verifies portable application behavior, not PostgreSQL/MySQL/MSSQL-specific
 SQL, Timescale features, database roles or every concurrency behavior. Report that
 limit and use the intended engine in an isolated test database when the task
-requires those checks. Do not use the shared environment database as the default
+requires those checks. Application models keep their hosted column types: a
+PostgreSQL `JSONB` column runs as JSON, and `Numeric` runs as a SQLite number exact
+to about 15 significant digits, the precision the client's float64 frames carry on
+every engine. Unsigned 64-bit integers and arrays are rejected, naming the column.
+Revision code that runs PostgreSQL-only SQL must check `op.get_bind().dialect.name`. Do not use the shared environment database as the default
 integration-test fixture.
 
 ## Finish verification and switch back

{mainsequence_metatable-0.1.11.dev22/src/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.12.dev24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.11.dev22
+Version: 0.1.12.dev24
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/docs/adr/api/0001-unified-api-storage-and-local-sqlite.md

@@ -732,8 +732,10 @@ Both SQLite catalog mutations and table writes use explicit `BEGIN IMMEDIATE`
 transactions with foreign-key enforcement and a 30-second connection busy timeout.
 Bounded physical operations select a 5-second lock timeout. The
 catalog uses WAL. Application DDL uses the same Alembic reservation/finalization
-workflow as PostgreSQL. SQLite rejects named schemas, exact decimal, unsigned
-64-bit integer, array, PostgreSQL JSONB, and specialized index contracts.
+workflow as PostgreSQL. SQLite rejects named schemas, unsigned 64-bit integer,
+array, and specialized index contracts, naming the column or index. PostgreSQL
+JSONB is stored as JSON, and NUMERIC as SQLite numbers exact to about 15
+significant digits, the precision the client's float64 frames already carry.
 Timestamps require UTC offsets and preserve microseconds; finer precision is
 rejected rather than truncated. UUID coordinate filters use the same contract
 conversion for reads and deletes.

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/docs/client/installation-and-connection.md

@@ -93,6 +93,11 @@ guide/example snapshots in each skill's `references/` folder. The installed clie
 version is recorded in `PINNED_FROM.txt`. Skills for API implementation or
 MetaTables project development are outside this bundle.
 
+Running the command again replaces the whole `metatables` namespace: folders the
+installed client does not ship, including any added there, are removed. Keep the
+application's own skills in another `.agents/skills/` namespace; the copy never
+changes it.
+
 Use `metatables-upgrade-legacy-app` when replacing older MainSequence/MetaTables
 imports, declared SQL scopes or API-owned application migration setup. The
 [legacy application upgrade guide](upgrade-legacy-app.md) explains the current

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/docs/operations/local-runtime.md

@@ -144,6 +144,14 @@ updates and governed SQL within its dialect. PostgreSQL-specific SQL, database r
 Timescale hypertables and policies are unavailable. Select expressions and writes must
 use the API-advertised dialect; SQL is not translated between engines.
 
+Application models keep their hosted column types. A PostgreSQL `JSONB` column is
+created and decoded as JSON. `Numeric` columns are SQLite numbers, exact to about 15
+significant digits; reads return `Decimal`, and the client's frames carry them as
+float64 on every engine. Unsigned 64-bit integers and arrays have no SQLite type:
+registration rejects them with `unsupported_sqlite_type`, naming the table and
+column. Revision code running PostgreSQL-only SQL, such as `ctid` or `jsonb_*`
+functions, must branch on `op.get_bind().dialect.name`.
+
 The SQLite adapter shares the request's transaction for catalog and physical work.
 Physical savepoints preserve rollback semantics and avoid two writers competing for
 the same file. Application migration connections are blocked; see the

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence-metatable"
-version = "0.1.11.dev22"
+version = "0.1.12.dev24"
 description = "Main Sequence MetaTables Python client and standalone API"
 readme = "README.md"
 requires-python = ">=3.13"

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24/src/mainsequence_metatable.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.11.dev22
+Version: 0.1.12.dev24
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/src/metatables/api/app/routes/table_registration.py

@@ -161,7 +161,9 @@ def _registration(payload, *, indexed, actor, session, sources, creator, introsp
 def _failure(session, exc):
     session.rollback()
     if isinstance(exc, DataSourceAdmissionError):
-        raise HTTPException(exc.status_code, exc.code) from exc
+        # Contract rejections name the offending column or index, as contract validation does.
+        detail = exc.code if exc.field == "data_source" else {"code": exc.code, "field": exc.field, "message": str(exc)}
+        raise HTTPException(exc.status_code, detail) from exc
     if isinstance(exc, (DataSourceIntegrationError, PhysicalConnectionUnavailable, PhysicalTableOutcomeUnknown, SQLAlchemyError)):
         raise HTTPException(503, 'Catalog or DataSource is unavailable.') from exc
     raise HTTPException(409 if isinstance(exc, (PhysicalTableError, PhysicalIntrospectionError, TimescaleError)) else 422,

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/src/metatables/api/backend/backends/adapters/sqlite_connection.py

@@ -12,6 +12,7 @@ import time
 from collections import namedtuple
 from contextlib import contextmanager
 from datetime import date, datetime, timezone
+from decimal import Decimal
 from uuid import UUID
 
 from psycopg2 import sql
@@ -63,6 +64,11 @@ def bind_value(value):
         return json.dumps(value.adapted, separators=(",", ":"), allow_nan=False)
     if isinstance(value, (dict, list)):
         return json.dumps(value, separators=(",", ":"), allow_nan=False)
+    if isinstance(value, Decimal):
+        # SQLite stores NUMERIC as INTEGER or REAL; keep integral values exact.
+        if value == value.to_integral_value() and -(2**63) <= value < 2**63:
+            return int(value)
+        return float(value)
     return value
 
 
@@ -178,6 +184,8 @@ def register_converters():
     sqlite3.register_converter("BOOLEAN", lambda v: v == b"1")
     sqlite3.register_converter("JSON", lambda v: json.loads(v.decode()))
     sqlite3.register_converter("DATE", lambda v: date.fromisoformat(v.decode()))
+    sqlite3.register_converter("NUMERIC", lambda v: Decimal(v.decode()))
+    sqlite3.register_converter("DECIMAL", lambda v: Decimal(v.decode()))
 
 
 @contextmanager

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/src/metatables/api/backend/backends/adapters/sqlite_introspection.py

@@ -41,7 +41,9 @@ def introspect_sqlite_table(*, source, physical_schema, physical_table_name):
                     "INTEGER": "int64",
                     "JSON": "json",
                     "DATE": "date",
-                }.get(backend, "string")
+                    "NUMERIC": "numeric",
+                    "DECIMAL": "numeric",
+                }.get(backend.split("(", 1)[0].strip(), "string")
                 columns.append(
                     {
                         "name": item["name"],
@@ -118,20 +120,27 @@ def validate_sqlite_contract(contract):
     """Reject unsupported DDL before reserving catalog state or opening a store."""
     from metatables.api.backend.domain.data_source_rules import DataSourceAdmissionError
 
-    normalize_schema((contract.get("physical") or {}).get("schema"))
+    physical = contract.get("physical") or {}
+    normalize_schema(physical.get("schema"))
+    table = physical.get("table_name") or "the table"
+    # JSONB is stored as JSON and NUMERIC as SQLite numbers (about 15 significant
+    # digits, the precision the client's float64 frames already carry).
     for column in contract.get("columns", []):
         kind = str(column.get("data_type", "")).lower()
         backend = str(column.get("backend_type") or "").lower()
-        if kind in {"numeric", "decimal", "uint64"} or any(
-            t in backend for t in ("numeric", "decimal", "[]", "jsonb")
-        ):
+        if kind == "uint64" or "[]" in backend:
             raise DataSourceAdmissionError(
                 "unsupported_sqlite_type",
-                "SQLite does not support exact decimal, unsigned 64-bit integers, arrays, or PostgreSQL JSONB contracts.",
+                f"Column {column.get('name')!r} of {table} is {column.get('backend_type') or kind}; "
+                "SQLite has no unsigned 64-bit integer or array type.",
                 status_code=409,
+                field=f"table_contract.columns.{column.get('name')}",
             )
     for index in contract.get("indexes", []):
         if index.get("method") not in (None, "", "btree") or index.get("expression"):
             raise DataSourceAdmissionError(
-                "unsupported_sqlite_index", "SQLite supports column indexes only.", status_code=409
+                "unsupported_sqlite_index",
+                f"Index {index.get('name')!r} of {table} is not a column index; SQLite supports column indexes only.",
+                status_code=409,
+                field=f"table_contract.indexes.{index.get('name')}",
             )

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/src/metatables/migrations/connection.py

@@ -3,12 +3,21 @@
 from contextlib import contextmanager
 
 from sqlalchemy import create_engine, event
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.engine import make_url
+from sqlalchemy.ext.compiler import compiles
 from sqlalchemy.pool import NullPool
 
 from .tls import migration_tls_arguments
 
 
+@compiles(JSONB, "sqlite")
+def _sqlite_jsonb(_type, _compiler, **_kw):
+    # Applications declare PostgreSQL JSONB; the local runtime stores and
+    # decodes it as JSON, so models and reflected columns compare equal.
+    return "JSON"
+
+
 def version_schema(config, dialect):
     schema = config.attributes["mainsequence_migration_provider"].version_table_schema
     if dialect in {"sqlite", "mysql"} and schema in (None, "public"):

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/tests/contracts/capabilities.json

@@ -2854,7 +2854,7 @@
       "hidden": false,
       "note": "Offline client skill copying delegated to the SDK scaffold helper; bundles matching guide/example resources, supports dry-run and global JSON output, and records the installed version.",
       "tests": [
-        "tests/packaging/test_client_skills.py::test_copy_and_refresh_preserve_other_namespaces_and_deliver_portable_references",
+        "tests/packaging/test_client_skills.py::test_copy_and_refresh_replace_only_the_metatables_namespace_with_portable_references",
         "tests/packaging/test_client_skills.py::test_dry_run_reports_version_and_destinations_without_creating_project",
         "tests/packaging/test_installed_distribution.py::test_client_skills_copy_from_installed_bundle_outside_checkout"
       ]

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/tests/integrations/test_sqlite_operations.py

@@ -103,12 +103,61 @@ def test_serialized_writers_and_failed_replacement_preserve_existing_rows(sqlite
 def test_sqlite_rejects_unrepresentable_contracts_before_effects():
     for contract in (
         {"physical": {"schema": "analytics"}},
-        {"columns": [{"name": "exact", "data_type": "numeric"}]},
+        {"columns": [{"name": "unsigned", "data_type": "uint64"}]},
         {"columns": [{"name": "array", "backend_type": "INTEGER[]"}]},
         {"indexes": [{"name": "special", "method": "gin"}]},
     ):
         with pytest.raises(DataSourceAdmissionError):
             validate_sqlite_contract(contract)
+    with pytest.raises(DataSourceAdmissionError) as rejected:
+        validate_sqlite_contract({"physical": {"table_name": "positions"},
+                                  "columns": [{"name": "lots", "backend_type": "INTEGER[]"}]})
+    assert rejected.value.field == "table_contract.columns.lots"
+    assert "'lots'" in str(rejected.value) and "positions" in str(rejected.value)
+
+
+def test_sqlite_runs_postgresql_jsonb_as_json_and_numeric_as_numbers(sqlite_source):
+    source, engine = sqlite_source
+    from decimal import Decimal
+
+    from alembic.autogenerate import compare_metadata
+    from alembic.migration import MigrationContext
+    from sqlalchemy import Column, Integer, MetaData, Numeric, Table
+    from sqlalchemy.dialects.postgresql import JSONB
+
+    import metatables.migrations.connection  # noqa: F401  Registers the SQLite JSONB rule.
+    from metatables.api.backend.backends.adapters.sqlite_introspection import (
+        introspect_sqlite_table,
+    )
+
+    columns = [{"name": "payload", "data_type": "jsonb", "backend_type": "JSONB"},
+               {"name": "amount", "data_type": "numeric", "backend_type": "NUMERIC(38, 18)"}]
+    validate_sqlite_contract({"columns": columns})
+    metadata = MetaData()
+    Table("typed_numbers", metadata, Column("id", Integer, primary_key=True),
+          Column("payload", JSONB()), Column("amount", Numeric(38, 18)))
+    with engine.begin() as connection:
+        metadata.create_all(connection)
+        context = MigrationContext.configure(connection, opts={
+            "compare_type": True,
+            "include_name": lambda name, kind, _parents: kind != "table" or name == "typed_numbers",
+        })
+        assert compare_metadata(context, metadata) == []
+    snapshot = introspect_sqlite_table(source=source, physical_schema="public",
+                                       physical_table_name="typed_numbers")
+    assert {c["name"]: (c["data_type"], c["backend_type"]) for c in snapshot["columns"]} == {
+        "id": ("int64", "INTEGER"), "payload": ("json", "JSON"), "amount": ("numeric", "NUMERIC(38, 18)")}
+    inserted = execute_fixture_sql(
+        source=source,
+        operation="insert",
+        sql_text="INSERT INTO typed_numbers (id, payload, amount) VALUES (1, :payload, :amount), (2, NULL, :whole) RETURNING *",
+        parameters={"payload": {"nodes": [0.5, 1]}, "amount": Decimal("1234.000125"), "whole": Decimal("100")},
+    )["rows"]
+    assert inserted[0]["payload"] == {"nodes": [0.5, 1]}
+    assert Decimal(str(inserted[0]["amount"])) == Decimal("1234.000125")
+    selected = execute_fixture_sql(source=source, sql_text="SELECT id FROM typed_numbers WHERE amount > :limit ORDER BY amount",
+                                   parameters={"limit": Decimal("99.5")})["rows"]
+    assert [row["id"] for row in selected] == [2, 1]
 
 
 def test_sub_microsecond_timestamps_fail_before_serialization():

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/tests/packaging/test_client_skills.py

@@ -46,7 +46,7 @@ def test_dry_run_reports_version_and_destinations_without_creating_project(tmp_p
     assert not project.exists()
 
 
-def test_copy_and_refresh_preserve_other_namespaces_and_deliver_portable_references(tmp_path, monkeypatch):
+def test_copy_and_refresh_replace_only_the_metatables_namespace_with_portable_references(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     unrelated = tmp_path / ".agents/skills/mainsequence/custom/SKILL.md"
     unrelated.parent.mkdir(parents=True)
@@ -64,7 +64,8 @@ def test_copy_and_refresh_preserve_other_namespaces_and_deliver_portable_referen
     assert second.exit_code == 0, second.output
     assert not stale.exists()
     assert unrelated.read_text() == "consumer instructions"
-    assert custom.read_text() == "custom"
+    # The SDK owns the whole namespace: folders the client does not ship are removed.
+    assert not custom.parent.exists()
     pin = (bundle / "PINNED_FROM.txt").read_text()
     assert f"pinned_version={version('mainsequence-metatable')}" in pin
     assert "library_name=mainsequence-metatable" in pin

{mainsequence_metatable-0.1.11.dev22 → mainsequence_metatable-0.1.12.dev24}/uv.lock

@@ -632,7 +632,7 @@ server = [
 
 [[package]]
 name = "mainsequence-metatable"
-version = "0.1.11"
+version = "0.1.12"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },