chore: import upstream snapshot with attribution

examples/python/postgres/postgres.py

@@ -0,0 +1,136 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.postgres import PostgresConfig, PostgresResource
+
+load_dotenv(".env.development")
+
+config = PostgresConfig(
+    dsn=os.environ["POSTGRES_DSN"],
+    max_read_rows=200,
+    max_read_bytes=1024 * 1024,
+)
+resource = PostgresResource(config=config)
+
+
+async def _run(ws, cmd):
+    print(f"\n>>> {cmd}")
+    r = await ws.execute(cmd)
+    out = (await r.stdout_str()).strip()
+    err = await r.stderr_str()
+    if out:
+        for line in out.splitlines()[:10]:
+            print(f"  {line[:140]}")
+        total = len(out.splitlines())
+        if total > 10:
+            print(f"  ... ({total} lines total)")
+    if err:
+        print(f"  [stderr] {err.strip()[:160]}")
+    if not out and not err:
+        print(f"  (empty, exit={r.exit_code})")
+    return r
+
+
+async def main():
+    ws = Workspace({"/pg": resource}, mode=MountMode.READ)
+
+    print("=" * 60)
+    print("LISTING (ls / tree)")
+    print("=" * 60)
+
+    await _run(ws, "ls /pg/")
+    await _run(ws, "ls /pg/public/")
+    await _run(ws, "ls /pg/public/tables/")
+    await _run(ws, "ls /pg/public/views/")
+    await _run(ws, "tree -L 2 /pg/public/")
+
+    print("\n" + "=" * 60)
+    print("SYNTHETIC JSON (database.json + per-entity schema.json)")
+    print("=" * 60)
+
+    await _run(ws, "cat /pg/database.json | head -n 30")
+
+    table = "context_info"
+    sch = f"/pg/public/tables/{table}/schema.json"
+    await _run(ws, f'cat "{sch}" | head -n 25')
+
+    print("\n" + "=" * 60)
+    print("STAT and METADATA")
+    print("=" * 60)
+
+    fp = f"/pg/public/tables/{table}/rows.jsonl"
+    await _run(ws, f'stat "{fp}"')
+
+    print("\n" + "=" * 60)
+    print("HEAD / TAIL / WC (predicate pushdown to SQL)")
+    print("=" * 60)
+
+    await _run(ws, f'head -n 3 "{fp}"')
+    await _run(ws, f'tail -n 3 "{fp}"')
+    await _run(ws, f'wc -l "{fp}"')
+
+    print("\n" + "=" * 60)
+    print("CAT with SIZE GUARD")
+    print("=" * 60)
+    print("(this should error: table has more rows than max_read_rows=200)")
+
+    await _run(ws, f'cat "{fp}"')
+
+    print("\n" + "=" * 60)
+    print("GREP at different scopes (ILIKE pushdown)")
+    print("=" * 60)
+
+    await _run(ws, f'grep system "{fp}"')
+    await _run(ws, f'grep -c system "{fp}"')
+    await _run(ws, 'grep system /pg/public/tables/')
+    await _run(ws, 'grep system /pg/public/')
+
+    print("\n" + "=" * 60)
+    print("RG at schema scope")
+    print("=" * 60)
+
+    await _run(ws, "rg system /pg/public/")
+
+    print("\n" + "=" * 60)
+    print("JQ over rows.jsonl (slice with head first to stay under guard)")
+    print("=" * 60)
+
+    await _run(ws, f'head -n 20 "{fp}" | jq -r ".[] | .id"')
+    await _run(ws, f'head -n 20 "{fp}" | jq -r ".[] | .file_name"')
+
+    print("\n" + "=" * 60)
+    print("FIND")
+    print("=" * 60)
+
+    await _run(ws, 'find /pg/public/tables/ -name rows.jsonl')
+
+    print("\n" + "=" * 60)
+    print("CD + relative paths")
+    print("=" * 60)
+
+    await ws.execute("cd /pg/public/tables")
+    await _run(ws, "pwd")
+    await _run(ws, "ls")
+
+    await resource.accessor.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/postgres/postgres_fuse.py

@@ -0,0 +1,103 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import json
+import os
+
+from dotenv import load_dotenv
+
+from mirage import Mount, MountMode, Workspace
+from mirage.resource.postgres import PostgresConfig, PostgresResource
+
+load_dotenv(".env.development")
+
+config = PostgresConfig(
+    dsn=os.environ["POSTGRES_DSN"],
+    max_read_rows=1_000_000,
+    max_read_bytes=512 * 1024 * 1024,
+)
+resource = PostgresResource(config=config)
+
+with Workspace({"/pg/": Mount(resource, mode=MountMode.READ,
+                              fuse=True)}) as ws:
+    mp = ws.fuse_mountpoint
+
+    print(f"=== FUSE MODE: mounted at {mp} ===\n")
+
+    print("--- os.listdir() root ---")
+    for e in os.listdir(mp):
+        print(f"  {e}")
+
+    print("\n--- read database.json ---")
+    with open(f"{mp}/database.json") as f:
+        db_json = json.loads(f.read())
+    print(f"  database: {db_json['database']}")
+    print(f"  schemas: {db_json['schemas']}")
+    print(f"  tables: {len(db_json['tables'])} | "
+          f"views: {len(db_json['views'])} | "
+          f"relationships: {len(db_json['relationships'])}")
+
+    if "public" in db_json["schemas"]:
+        tables = os.listdir(f"{mp}/public/tables")
+        print(f"\n--- public.tables: {len(tables)} entries ---")
+        for t in tables[:5]:
+            print(f"  {t}")
+
+        if tables:
+            target = tables[0]
+            entity_dir = f"{mp}/public/tables/{target}"
+
+            print(f"\n--- ls {entity_dir} ---")
+            for e in os.listdir(entity_dir):
+                print(f"  {e}")
+
+            sch_path = f"{entity_dir}/schema.json"
+            print(f"\n--- read {sch_path} ---")
+            with open(sch_path) as f:
+                sch = json.loads(f.read())
+            print(f"  name={sch['name']} kind={sch['kind']}")
+            print(f"  columns: {len(sch['columns'])}")
+            print(f"  primary_key: {sch['primary_key']}")
+            print(f"  rows: {sch['row_count_estimate']}")
+
+            rows_path = f"{entity_dir}/rows.jsonl"
+            print("\n--- read rows.jsonl (may hit size guard) ---")
+            try:
+                with open(rows_path) as f:
+                    text = f.read().strip()
+                if text:
+                    lines = text.splitlines()
+                    print(f"  rows: {len(lines)}")
+                    for line in lines[:3]:
+                        try:
+                            doc = json.loads(line)
+                            print(f"  {json.dumps(doc)[:120]}")
+                        except json.JSONDecodeError:
+                            print(f"  {line[:120]}")
+                else:
+                    print("  (empty)")
+            except Exception as exc:
+                print(f"  guard fired: {str(exc)[:160]}")
+
+    print(f"\n>>> FUSE mounted at: {mp}")
+    print(">>> Open another terminal and try:")
+    print(f">>>   ls {mp}/")
+    print(f">>>   cat {mp}/database.json | jq .schemas")
+    print(f">>>   head -n 3 {mp}/public/tables/<table>/rows.jsonl")
+    print(">>> Press Enter to unmount and exit...")
+    input()
+
+    records = ws.ops.records
+    total = sum(r.bytes for r in records)
+    print(f"\nStats: {len(records)} ops, {total} bytes transferred")

examples/python/postgres/postgres_vfs.py

@@ -0,0 +1,117 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.postgres import PostgresConfig, PostgresResource
+
+load_dotenv(".env.development")
+
+config = PostgresConfig(
+    dsn=os.environ["POSTGRES_DSN"],
+    max_read_rows=200,
+    max_read_bytes=1024 * 1024,
+)
+resource = PostgresResource(config=config)
+
+
+async def main():
+    with Workspace({"/pg/": resource}, mode=MountMode.READ) as ws:
+        vos = sys.modules["os"]
+        print("=== VFS MODE: open() reads from Postgres ===\n")
+
+        print("--- os.listdir(/pg) — root entries ---")
+        for e in vos.listdir("/pg"):
+            print(f"  {e}")
+
+        print("\n--- read /pg/database.json ---")
+        with open("/pg/database.json") as f:
+            db_json = json.loads(f.read())
+        print(f"  database: {db_json['database']}")
+        print(f"  schemas: {db_json['schemas']}")
+        print(f"  tables: {len(db_json['tables'])} | "
+              f"views: {len(db_json['views'])} | "
+              f"relationships: {len(db_json['relationships'])}")
+
+        if "public" not in db_json["schemas"]:
+            print("\nno public schema")
+            return
+
+        print("\n--- os.listdir(/pg/public) ---")
+        for e in vos.listdir("/pg/public"):
+            print(f"  {e}")
+
+        print("\n--- os.listdir(/pg/public/tables) ---")
+        tables = vos.listdir("/pg/public/tables")
+        for t in tables[:5]:
+            print(f"  {t}")
+        if len(tables) > 5:
+            print(f"  ... ({len(tables)} total)")
+
+        if not tables:
+            print("no tables in public")
+            return
+
+        target = tables[0]
+        entity_dir = f"/pg/public/tables/{target}"
+
+        print(f"\n--- os.listdir({entity_dir}) ---")
+        for e in vos.listdir(entity_dir):
+            print(f"  {e}")
+
+        sch_path = f"{entity_dir}/schema.json"
+        print(f"\n--- read {sch_path} ---")
+        with open(sch_path) as f:
+            sch = json.loads(f.read())
+        print(f"  name={sch['name']} kind={sch['kind']}")
+        print(f"  columns: {[c['name'] for c in sch['columns'][:6]]}" +
+              (" ..." if len(sch["columns"]) > 6 else ""))
+        print(f"  primary_key: {sch['primary_key']}")
+        print(f"  foreign_keys: {len(sch['foreign_keys'])}")
+        print(f"  row_count_estimate: {sch['row_count_estimate']}")
+
+        rows_path = f"{entity_dir}/rows.jsonl"
+        print("\n--- open() rows.jsonl (may hit size guard) ---")
+        try:
+            with open(rows_path) as f:
+                content = f.read()
+            lines = [ln for ln in content.strip().split("\n") if ln.strip()]
+            print(f"  rows returned: {len(lines)}")
+            for line in lines[:3]:
+                doc = json.loads(line)
+                print(f"  {json.dumps(doc)[:120]}")
+        except Exception as exc:
+            print(f"  guard fired: {str(exc)[:160]}")
+
+        print("\n--- bash history ---")
+        with open("/.bash_history") as f:
+            for i, line in enumerate(f):
+                if i >= 6:
+                    break
+                print(f"  {line.rstrip()[:120]}")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, {total} bytes transferred")
+
+    await resource.accessor.close()
+
+
+asyncio.run(main())