dbzero 0.2.4__tar.gz → 0.3.0__tar.gz

dbzero-0.3.0/AGENTS.md

@@ -0,0 +1,71 @@
+# dbzero
+
+dbzero is a state management system for persisting process state without a database. It lets Python processes keep their in-memory state durable across restarts — no separate DB server, schemas, or ORM. The core is C++ with Python bindings. See https://docs.dbzero.io for user-facing documentation.
+
+## Development workflow
+
+### TDD is required
+
+When implementing new features, follow test-driven development:
+
+1. Write a failing test first (Python tests in `python_tests/`, C++ tests under `tests/` / `subprojects/`).
+2. Implement the minimum code to make the test pass.
+3. Refactor while keeping tests green.
+
+All tests must pass before a change is considered complete.
+
+### Building
+
+- Debug build: `./scripts/build.sh`
+- Release build: `./scripts/build.sh -r`
+- Release build with C++ unit test binary: `./scripts/build.sh -r -t`
+
+### Running tests
+
+- Python tests: `./scripts/run_tests.sh`
+- C++ tests after a `-t` build: `./build/release/tests.x`
+- During development, do not run stress tests by default; they are intentionally slow. Run focused tests specific to the feature or refactor being worked on before finalization.
+- If any C++ source under the native/core part of the project was modified, also run the C++ test suite (do not rely on the Python tests alone to cover native changes).
+
+Never mark a task done while tests are failing.
+
+## Implementation notes
+
+### Temporary immutable objects design
+
+When working on immutable objects, use `design/IMMUTABLE_OBJECTS_DESIGN.md` as the implementation design reference. This file is temporary and should be removed after the feature is complete.
+
+### v_object constructor conventions
+
+Types derived from `v_object` should follow the project-wide constructor pattern:
+
+- New durable instances are constructed from `Memspace &` plus any type-specific creation arguments.
+- Existing durable instances are reopened from `mptr` plus any type-specific runtime dependencies.
+
+### C++ style
+
+- Use camelCase for local helper variables, lambdas, and method names in C++ code.
+
+### Python binding wrapper access
+
+When accessing a C++ object stored inside a Python wrapper, use `ext()` for read-only operations and for operations that are explicitly documented as non-mutating wrapper/runtime attachment updates.
+
+Use `modifyExt()` for real object mutations, especially durable state changes. Do not use `const_cast` on `ext()` to call a mutating method. If a wrapper currently exposes only a const object but needs a mutating API, change the wrapper type or access path so the mutation can go through `modifyExt()`.
+
+### Python C API safety helpers
+
+When iterating over Python objects in C++, use `Py_FOR(item, iterator)` from `PySafeAPI.hpp` with an owned iterator, for example `auto iterator = Py_OWN(PyObject_GetIter(obj));`. The loop owns each yielded item and avoids manual `Py_DECREF` paths.
+
+For Python container/object writes, use the `PySafe_*` helpers from `PySafeAPI.hpp` instead of the raw C API when a helper exists, such as `PySafeList_SetItem`, `PySafeTuple_SetItem`, `PySafeDict_SetItem`, `PySafeDict_SetItemString`, `PySafeSet_Add`, and `PySafeModule_AddObject`.
+
+### MorphingBIndex: address and type can change on mutation
+
+A `MorphingBIndex` does not behave like a typical container. On mutation (`insert`, `erase`) it may morph into a different internal storage variant (itty / array_2..4 / vector / bindex), and the morph can change both its **address** and its **type**.
+
+Consequences for any code that mutates a `MorphingBIndex`:
+
+- Any externally stored `{address, type}` pair referring to the bindex is potentially invalidated after every `insert` or `erase` call. Lookups through a stale pair read pre-mutation storage and return wrong data.
+- A live handle to the bindex remains valid across the mutation and reflects the new storage; prefer re-reading `bindex.getAddress()` / `bindex.getIndexType()` from the handle over trusting any previously captured copy.
+- Destructive shortcuts (destroying and rebuilding the whole bindex, or erasing it entirely from its parent) avoid the issue since no stale reference remains.
+
+When adding a new mutating path that operates on a `MorphingBIndex`, treat re-syncing any externally held `{address, type}` as mandatory, not an optimization. Collection-specific handling (where these pairs live, which paths must re-sync) is documented at the top of the relevant `.cpp` files.