0010 Repository and Generated Source Overview

greenways-ai/v2 contains supported JavaScript and Dart workspaces under main/js/ and main/dart/, generated SQL under main/sql/, backend source and generators under backend/, and canonical maintained documentation under docs-gen/.

The backend follows a source-first generation sequence:

source definition -> validation and IR -> generator -> emitted artifact -> tests and build

gwdb owns database-facing domain definitions and behaviour. gwbuild owns validation, intermediate representations, generation, and build tasks. Generated-looking files should be traced back to their source before editing.

Exposed mutation names normally become their RPC names. When renaming a source function, preserve its published command identifier with :api/meta {:rpc/name "existing-command-name"} on the source definition. The generator uses that name for the wrapper and audit operation while calling the renamed source function. Explicit names must be lowercase hyphenated identifiers and unique within their RPC target. Regenerate RPC, XTalk, and SQL artifacts after changing the source metadata.

Portable XTalk libraries are emitted from the Foundation src-lang source into two tracked language workspaces:

ref/foundation/src-lang/xt.*
        ↓ xtalk.packages aggregate def.make projects
main/js/apps/*          # JavaScript applications
main/js/packages/*/*    # maintained JavaScript packages
main/js/libs/xt-*       # generated @xtalk/* packages
main/dart/libs/xt-*     # generated xtalk_* packages

The six package families are lang, event, net, substrate, db, and ui. Their manifests and cross-package imports are generator-owned. Run yarn xtalk:generate from main/js/; CI runs yarn xtalk:check and rejects stale output. The main package manager resolves these as workspace libraries, but the existing Statstrade browser boundary still boots its generated gwlink-remote.js and shared-worker assets. Migrating that domain bundle is a separate compatibility change; applications do not edit the emitted package files directly.

The root AGENTS.md contains the full repository instructions for Codex, Kimi, and compatible development agents.