xian-contracting

Imported from xian-technology/xian-contracting (AGENTS.md). Install upstream with npx skills add xian-technology/xian-contracting. Copyright stays with the author.

Repository Guidelines

Scope

• xian-contracting owns contract compilation, execution, storage, metering, and runtime security semantics.
• Keep node orchestration, genesis distribution, and operator workflow out of this repo.
• This repo is security-sensitive. Favor small, well-tested changes.

Shared Convention

• Follow the shared repo convention in xian-meta/docs/REPO_CONVENTIONS.md.
• Keep this repo aligned with that standard for stable root docs, backlog notes, and folder-level entrypoints.
• Follow the shared change workflow in xian-meta/docs/CHANGE_WORKFLOW.md.
• Before push, review downstream impact on xian-abci, xian-py, and xian-docs-web, and run the local validation path from this file.

Project Layout

• src/contracting/compilation/: parser, compiler, linter, and whitelist logic.
• src/contracting/execution/: runtime, executor, module loading, and tracing.
• src/contracting/storage/: drivers, ORM helpers, encoder, and LMDB-backed state storage.
• src/contracting/contracts/: package-local contract assets such as the built-in submission contract.
• tests/: unit, integration, security, and performance coverage.

Workflow

• main is the primary working branch for this repo. Stay on main unless explicitly told otherwise.
• Preserve runtime behavior deliberately. If a fix changes execution semantics, add regression tests in the same change.
• Avoid cross-repo orchestration changes here unless the ABCI or CLI layer requires a new importable primitive.
• Keep built-in contracts and storage/runtime helpers aligned with the execution model. Do not treat this repo like a general utilities package.

Validation

• Preferred setup: uv sync --group dev
• Lint: uv run ruff check .
• Format check: uv run ruff format --check .
• Tests: uv run pytest
• If you touch security boundaries or metering, run the relevant tests/security/ and tests/integration/ paths explicitly.

Notes

• The test suite now uses a repo-local HOME via tests/conftest.py, so it does not need host access to ~/.cometbft.
• Review examples/ and release helpers critically before expanding them; do not add convenience tooling that belongs in xian-cli or xian-stack.
• If you touch metering, tracing, imports, or storage encoding, assume the change is consensus-sensitive and test accordingly.

Shared Agent Practices

• Keep changes clean, modular, and professional. Prefer small, cohesive modules, clear naming, explicit boundaries, and tests over quick patches.
• When code behavior, public APIs, user workflows, operator workflows, or configuration semantics change, check whether ../xian-docs-web needs corresponding documentation updates. If this repo is xian-docs-web, update the relevant published docs in place. Write durable user/developer documentation, not a changelog entry.
• Follow ../xian-meta/docs/CODE_GRAPH_WORKFLOW.md for graph freshness and source verification. Before relying on graph results, run python3 ../xian-meta/scripts/graphify_workspace.py status --repo xian-contracting and refresh that repo if stale.
• For codebase questions, use the local graph first when graphify-out/graph.json exists: run graphify query "<question>"; use graphify affected "<symbol>" --depth 1 for direct dependents, larger depths for transitive impact, and graphify path "<A>" "<B>" --directed for call paths and graphify explain "<concept>" for focused concepts.
• Dirty graphify-out/ files are expected after hooks or incremental updates and are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
• Use graphify-out/wiki/index.md for broad navigation when it exists. Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
• For any non-trivial code change, update the local graph before final verification when graphify-out/graph.json exists. Run python3 ../xian-meta/scripts/graphify_workspace.py refresh --repo xian-contracting from the repo root; use --force only for inspected, intentional shrinkage.
• After updating the graph, check cross-repo impact before finishing: use graphify affected, inspect returned source locations, and search affected sibling repos. A missing edge or truncated result does not prove there are no other consumers.
• If graphify or dependency analysis shows affected sibling repos, update those repos in the same change when the impact is real and the fix is in scope.
• Treat graphify-out/ as a generated local artifact. Do not commit it.