matrx-records 0.1.1__tar.gz

matrx_records-0.1.1/.gitignore

@@ -0,0 +1,345 @@
+*.pyc
+secrets/
+ignore/
+temp/
+logs/
+# The broad `logs/` rule above is for RUNTIME log output, but it also matched
+# the dashboard's SOURCE directory and silently swallowed an entire feature's
+# files (only the pre-existing index.tsx stayed tracked), breaking the prod
+# Docker build with "Could not resolve ./structured-tab". Re-include the source.
+!apps/dashboard/src/features/logs/
+!apps/dashboard/src/features/logs/**
+todo
+text_notes/
+aidream/secrets/2.env
+automation_matrix/matrix_processing/temp/*
+cd
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.venv/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+# The blanket lib/ rule above is from the standard Python .gitignore template
+# and was silently swallowing TS source under the SPA `src/lib/` folders.
+# Re-allow them explicitly so frontend builds don't ship without their lib layer.
+!apps/dashboard/src/lib/
+!apps/dashboard/src/lib/**
+!apps/dashboard/src/features/crawler/lib/
+!apps/dashboard/src/features/crawler/lib/**
+!apps/workflow-studio/src/lib/
+!apps/workflow-studio/src/lib/**
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+ai/tests/clean_response.json
+ai/tests/cx_storage_response.json
+ai/tests/execution_test.py
+ai/tests/final_response.json
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env_remote
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env.armanonly
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# random armani files
+/armani_dev/secrets/
+/armani/
+/_armani/
+
+
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.vscode/
+/node_modules/
+
+# Frontend pnpm workspace (apps/) — node_modules at the workspace root and any
+# member, plus Vite caches and build output. The unified lockfile (apps/pnpm-lock.yaml)
+# IS committed; everything below is regenerated.
+#
+# 🚨 BOTH SPELLINGS. `node_modules/` with the slash matches a DIRECTORY only, so
+# a SYMLINK named `node_modules` slipped straight past it: five of them — each
+# an absolute path into one machine's checkout — were committed on main and
+# broke `pnpm install --frozen-lockfile` on every CI runner, where the symlink
+# is dangling and pnpm's `mkdir` of it answers ENOENT. Every package release was
+# blocked by it. The bare spelling below matches the symlink too.
+node_modules
+node_modules/
+apps/**/.vite/
+apps/**/dist/
+.vite/
+
+dump.rdb
+
+frontend/
+
+# AME Temp Files and directory structure
+# Ignore all files in the temp directory and its subdirectories
+/temp/**/*
+/tmp/**/*
+
+# Allow .gitkeep files to retain directory structure
+!/temp/**/.gitkeep
+!/tmp/**/.gitkeep
+
+# Armani
+.history*
+.history/
+/local_data/
+local_reports_data/
+webscraper/quick_scrapes/temp/
+automation_matrix/ai_apis/fireworks/_dev/*
+automation_matrix/ai_apis/fireworks/_dev/fireworks_sample.py
+*.pdf
+*.flac
+*.mp3
+*.wav
+miniconda.sh
+/database/python_sql/temp_data/
+ .history*
+ .history/
+.history/
+
+_dev/
+/_dev/
+requirements_filtered.txt
+
+# matrx-dev-tools backups
+.env-backups/
+# Matrx Ship config (contains API key)
+.matrx-ship.json
+
+# Matrx config (contains API keys)
+.matrx.json
+.matrx-tools.conf
+
+# Claude Code local worktrees and per-user settings
+.claude/worktrees/
+.worktrees/
+.claude/settings.local.json
+
+# Append-only snapshots from matrx_utils.update_history (unbounded; do not commit)
+common/utils/data_in_code/data_history.json
+packages/matrx-utils/matrx_utils/data_in_code/data_history.json
+
+# Tool-dispatch debug logs — one file per server start, never committed
+.matrx-debug/
+# Per-definition BEFORE snapshots written by a live migration script. They are
+# the recovery record for one machine's run, not repo content — the durable
+# audit trail is the `metadata.migrations` stamp on the row itself.
+.matrx-migrations/
+
+# Trial Bench records written on THIS machine — the trial's JSON record, its §8
+# report and the index that finds them (aidream/services/masterworks/bench/index.py,
+# and the runs a product-started trial writes beside it). They are never repo
+# content: a record carries every arm's full text INCLUDING the expert's ground
+# truth, which is material deliberately withheld from the Rulebook, and a trial
+# that matters is published deliberately under common-docs/projects/<its trial>/.
+# Untracked-but-not-ignored meant one `git add -A` away from committing an
+# expert's withheld work.
+.matrx/bench/
+
+# macOS Finder metadata
+.DS_Store
+**/.DS_Store
+
+# Environment files
+.env
+.env.*
+*.env
+*.env.*
+
+# Keep safe templates trackable
+!.env.example
+!.env.sample
+!.env.template
+
+# Never commit local OAuth client/token artifacts
+credentials.json
+token*.pickle
+token*.json
+tests_trials/rag_tests/kg_export_output/
+
+# Pooler-contamination watch output (machine-local evidence, not source)
+db/evidence/
+
+# Pooler contamination evidence — machine-local forensic capture, not source
+db/evidence/
+db/mirror/.env.mirror
+supabase/.temp/
+**/supabase/.temp/
+# Packed npm artifacts. Kept locally for a one-time bootstrap publish; never
+# committed (they are large binaries regenerable with `pnpm pack`).
+apps/shared/*/*.tgz
+
+# Guard forcing-function scratch packages. These tests plant real files inside
+# the real tree the guard scans (a temp dir would prove nothing) and delete
+# them in teardown — ignoring them keeps the auto-commit tooling from
+# capturing one mid-run.
+_kind_boundary_scratch*/
+_kind_marker_law_scratch*/
+
+# packed npm tarballs are build output, never source (doctrine: typescript-package-standard)
+*.tgz
+
+# Peers' kit scratch witnesses. A `.kit-<name>-witness.XXXXXX/` directory is a
+# full COPY of kit/src planted inside the packages tree — three of them held a
+# duplicate `format.ts` on 2026-09-12 — and it sits in the `check:package-twins`
+# scan ROOT. `git ls-files` only reaches TRACKED files, so the guard never saw
+# them; the risk was a broad `git add` committing three formatter twins in one
+# stroke, which is the exact class that guard exists to stop. Ignored, never
+# deleted: they are another agent's evidence.
+apps/shared/.kit-*-witness.*/
+
+# Agent worktrees. Extra checkouts of this same repo, never product source.
+# They live at .wt/<slug> (disk-groom). Committing the folder would add a
+# second copy of the entire tree and a symlink into common-docs.
+.wt/
+.matrx/fixer-dispatch.json
+.matrx/fixer-ledger.json
+
+# Release streak ledger (scripts/release_repeats.py): per-machine state, never committed
+.matrx/release-repeats.json
+.matrx/release-repeats.json.tmp
+.matrx/fixer-ledger.json

matrx_records-0.1.1/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: matrx-records
+Version: 0.1.1
+Summary: The records server: the eight agent verbs over the custom record store's doors, the merge-field resolver, and the record workflow nodes
+Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
+Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
+Author-email: Matrx <admin@aimatrx.com>
+Maintainer-email: Matrx <admin@aimatrx.com>
+License: MIT
+Keywords: agents,custom-data,matrx,merge-field,records
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Requires-Dist: matrx-files>=0.2.262
+Requires-Dist: matrx-orm>=3.1.219
+Requires-Dist: matrx-utils>=2.0.64
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: agent
+Requires-Dist: matrx-ai>=0.5.504; extra == 'agent'
+Requires-Dist: matrx-connect>=0.1.185; extra == 'agent'
+Provides-Extra: graph
+Requires-Dist: matrx-graph>=0.2.263; extra == 'graph'
+Description-Content-Type: text/markdown
+
+# matrx-records
+
+The **records server**: the record read/write paths, the eight agent verbs and their
+generated tool cache, the merge-field resolver and its provenance writer, and the record
+workflow nodes.
+
+It is imported by the app and never imports it. It talks to the database only through
+`matrx-orm`, and only through the `custom.*` store's own doors, under the operating
+person's own principal — there is no agent identity and there are no service roles.
+
+```python
+from matrx_records import Principal, RecordStore
+
+store = RecordStore(Principal(user_id=uid, organization_id=org, claims=jwt_claims))
+tables = await store.table_list()
+```
+
+Host wiring is one call at startup:
+
+```python
+from matrx_records import configure_records
+configure_records(database="supabase_automation_matrix", session_factory=my_act_as_user)
+```
+
+## The scope system, read from the store (SCOPES-READS-SERVER)
+
+Every server reader of scopes reads `matrx_records.store.scopes.ScopeReader` — never the old
+`context.*` tables. A scope type is a Table the context system keeps, a scope a Record of it, a
+context item a Field; the reader answers in the old column names:
+
+```python
+from matrx_records.store.scopes import ScopeReader
+
+reader = ScopeReader.for_ambient(user_id=uid)          # the operating person, or the run's person
+types = await reader.types(org_ids)                     # lists: the contract RPCs, one statement
+scopes = await reader.scopes(org_ids, type_ids=[tid])
+docs = await reader.scope_documents([org], type_ids=[tid])  # every Record WITH its values
+one = await reader.scopes_by_id([sid])                  # by id, in whichever org it opens in
+items = await reader.items(org, [tid])                  # Fields, with the old value_type word
+```
+
+Values kept as files are read whole with `ScopeReader.whole_value(scope, key)`.
+The old scope tables are retired (2026-10-05); the store is the only writer, so there is nothing to compare against.
+
+## The server half — routing an existing record path (CUT-N-13)
+
+An `aidream` path that reads or writes records asks the gateway, and the gateway decides
+**per caller**: the record store when `custom/system_enabled` resolves on for that
+person's organization, the path's own existing body when it does not.
+
+```python
+from matrx_records.server import route_read
+
+rows = await route_read(
+    source="context.scopes",                       # the legacy relation
+    match={"id": scope_id},
+    legacy=lambda: Scopes.filter(id=scope_id).values("id", "name"),
+)
+```
+
+`legacy` is the OFF arm, so today's behaviour is unchanged while the knob is false and it
+is impossible to route a path without naming what it used to do. **The ramp is per SOURCE:**
+the switch says the organization keeps its data in the store, not that every relation has
+moved, so a source with no Table of its own slug is *not adopted yet* and keeps reading and
+writing today's tables — the `Route` says so, with the remedy. Only a source whose Table
+exists resolves through the store (`RecordsGateway.route_for`; feedback f35b12ec). `attrs=True` when the
+legacy arm hands back model instances; `RecordsGateway.read_joined(...)` for a path whose
+legacy arm is a SQL `JOIN` across two record-bearing relations.
+
+Which paths those are is a **query**, never a list:
+
+```python
+from matrx_records.server import the_enumeration
+
+for path in await the_enumeration():
+    print(path.relative_path, path.sources, path.routed)
+```
+
+It intersects matrx-orm's model registry with `platform.deprecated_relations` (the
+platform's own supersession register) and then reads the repository's import graph.
+`tests/test_server_paths_against_the_store.py` is parametrized over it, so a path nobody
+repointed fails by name and a legacy relation declared tomorrow pulls its paths in with
+no code change.
+
+## The outside door's verbs (TABLE-API-1, 2026-09-29)
+
+The table API and the AI Matrx MCP (aidream `services/table_api`) reach the store only through
+these, as the person: `table_read` (a Table's words, Fields and choice options), `record_page`
+(`custom.read_records_page`: filter, search, sort, page, total), `record_headers_of` (version and
+timestamps), `table_of`, `records_holding` (ids per key value, one statement), `record_change_many`
+and `record_upsert` (one transaction; advisory lock on the key; a person's verb, or an agent's
+only with `change_approval` saying nobody is asked) and `record_archive` (a person's archive /
+restore; an agent uses `record_delete`, which asks first).
+

matrx_records-0.1.1/README.md

@@ -0,0 +1,94 @@
+# matrx-records
+
+The **records server**: the record read/write paths, the eight agent verbs and their
+generated tool cache, the merge-field resolver and its provenance writer, and the record
+workflow nodes.
+
+It is imported by the app and never imports it. It talks to the database only through
+`matrx-orm`, and only through the `custom.*` store's own doors, under the operating
+person's own principal — there is no agent identity and there are no service roles.
+
+```python
+from matrx_records import Principal, RecordStore
+
+store = RecordStore(Principal(user_id=uid, organization_id=org, claims=jwt_claims))
+tables = await store.table_list()
+```
+
+Host wiring is one call at startup:
+
+```python
+from matrx_records import configure_records
+configure_records(database="supabase_automation_matrix", session_factory=my_act_as_user)
+```
+
+## The scope system, read from the store (SCOPES-READS-SERVER)
+
+Every server reader of scopes reads `matrx_records.store.scopes.ScopeReader` — never the old
+`context.*` tables. A scope type is a Table the context system keeps, a scope a Record of it, a
+context item a Field; the reader answers in the old column names:
+
+```python
+from matrx_records.store.scopes import ScopeReader
+
+reader = ScopeReader.for_ambient(user_id=uid)          # the operating person, or the run's person
+types = await reader.types(org_ids)                     # lists: the contract RPCs, one statement
+scopes = await reader.scopes(org_ids, type_ids=[tid])
+docs = await reader.scope_documents([org], type_ids=[tid])  # every Record WITH its values
+one = await reader.scopes_by_id([sid])                  # by id, in whichever org it opens in
+items = await reader.items(org, [tid])                  # Fields, with the old value_type word
+```
+
+Values kept as files are read whole with `ScopeReader.whole_value(scope, key)`.
+The old scope tables are retired (2026-10-05); the store is the only writer, so there is nothing to compare against.
+
+## The server half — routing an existing record path (CUT-N-13)
+
+An `aidream` path that reads or writes records asks the gateway, and the gateway decides
+**per caller**: the record store when `custom/system_enabled` resolves on for that
+person's organization, the path's own existing body when it does not.
+
+```python
+from matrx_records.server import route_read
+
+rows = await route_read(
+    source="context.scopes",                       # the legacy relation
+    match={"id": scope_id},
+    legacy=lambda: Scopes.filter(id=scope_id).values("id", "name"),
+)
+```
+
+`legacy` is the OFF arm, so today's behaviour is unchanged while the knob is false and it
+is impossible to route a path without naming what it used to do. **The ramp is per SOURCE:**
+the switch says the organization keeps its data in the store, not that every relation has
+moved, so a source with no Table of its own slug is *not adopted yet* and keeps reading and
+writing today's tables — the `Route` says so, with the remedy. Only a source whose Table
+exists resolves through the store (`RecordsGateway.route_for`; feedback f35b12ec). `attrs=True` when the
+legacy arm hands back model instances; `RecordsGateway.read_joined(...)` for a path whose
+legacy arm is a SQL `JOIN` across two record-bearing relations.
+
+Which paths those are is a **query**, never a list:
+
+```python
+from matrx_records.server import the_enumeration
+
+for path in await the_enumeration():
+    print(path.relative_path, path.sources, path.routed)
+```
+
+It intersects matrx-orm's model registry with `platform.deprecated_relations` (the
+platform's own supersession register) and then reads the repository's import graph.
+`tests/test_server_paths_against_the_store.py` is parametrized over it, so a path nobody
+repointed fails by name and a legacy relation declared tomorrow pulls its paths in with
+no code change.
+
+## The outside door's verbs (TABLE-API-1, 2026-09-29)
+
+The table API and the AI Matrx MCP (aidream `services/table_api`) reach the store only through
+these, as the person: `table_read` (a Table's words, Fields and choice options), `record_page`
+(`custom.read_records_page`: filter, search, sort, page, total), `record_headers_of` (version and
+timestamps), `table_of`, `records_holding` (ids per key value, one statement), `record_change_many`
+and `record_upsert` (one transaction; advisory lock on the key; a person's verb, or an agent's
+only with `change_approval` saying nobody is asked) and `record_archive` (a person's archive /
+restore; an agent uses `record_delete`, which asks first).
+

matrx_records-0.1.1/matrx_records/__init__.py

@@ -0,0 +1,49 @@
+"""matrx-records — the records server.
+
+The record read/write paths, the eight agent verbs and their generated tool cache, the
+merge-field resolver and its provenance writer, and the record workflow nodes. Imported
+by the app; it never imports the app (the package paradox — see the repo's CLAUDE.md).
+
+THE FOUR THINGS IN HERE, and the one sentence each that says why they are together:
+
+``principal`` / ``errors``
+    Whose authority a call runs under, and how the store's own refusal is carried out
+    whole instead of being flattened into "write failed".
+``store``
+    The eight verbs — ``table_list``, ``metadata_search``, ``record_read``,
+    ``record_write``, ``record_delete``, ``record_aggregate``, ``field_propose``,
+    ``table_propose`` — over the store's doors and over nothing else.
+``agent``
+    ONE action-dispatched tool, ``records``, generated from each Table's own structure,
+    cached, and invalidated by the registry's structure-change notification.
+``merge``
+    The merge-field resolver: sources, semantic types and modifiers; one DAG, one
+    precedence ladder, one memoized triple per turn, one provenance row per value.
+
+Nothing here opens a privileged connection or takes an organization from a payload.
+"""
+
+from matrx_records.errors import StoreRefusal, refusal_from
+from matrx_records.principal import (
+    Actor,
+    Principal,
+    acting_as,
+    configure_records,
+    records_database,
+)
+from matrx_records.store import RecordStore, RecordView, ResolvedValue
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Actor",
+    "Principal",
+    "RecordStore",
+    "RecordView",
+    "ResolvedValue",
+    "StoreRefusal",
+    "acting_as",
+    "configure_records",
+    "records_database",
+    "refusal_from",
+]