Source Mode

Sources as the unit of ownership

Source mode replaces one monolithic database assumption with named sources. A source can represent a database, filesystem, code index, OpenAPI surface, or GraphJin system surface.

sources:
  - name: app
    kind: database
    type: postgres
    capabilities:
      data.read: true
      data.write: true
  - name: docs
    kind: file
    capabilities:
      files.list: true
      files.read: true

Capabilities are centralized in the source capability registry and should not be invented ad hoc by catalog, security, MCP, or config code.

Access defaults

identity:
  namespace_claim: account_id
  user_id_claim: sub

sources:
  - name: app
    kind: database
    type: postgres
    access:
      read: account
      write: blocked
      delete: blocked
      namespace_column: account_id
      missing_namespace_column: block

The generated filters use trusted identity values from the request context. Client variables named account_id or user_id are not trusted for generated source-mode checks.

Artifact identity

The artifact overlay uses trusted user_id as the primary namespace for saved-query, fragment, and workflow edits. account_id can still be stored on the artifact row as tenant metadata, but it is not the primary lookup key.

When the artifact store is present and the request has user_id, writes go to gj_artifacts. Without user_id, GraphJin keeps the development fallback behavior and writes global config files only in dev mode.

Agentic environment

GO_ENV=agentic requires agentic.yml. Agentic configs can inherit production settings and then enable model-facing discovery surfaces deliberately.

inherits: prod
mode: agentic

Source-scoped reloads

Config updates that touch only one source can use a source-scoped reload path. GraphJin stages the config, validates the runtime, swaps the changed source, and preserves unrelated sources when the transaction succeeds.