Source Mode

Sources as the unit of ownership

Source mode replaces one monolithic database assumption with named external sources. A source can represent a database, filesystem, code index, or OpenAPI surface. GraphJin system roots and workflows are built-in features configured through the optional top-level system: and workflows: sections, not sources.

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

External-source capabilities are centralized in the source capability registry. Built-in system and workflow capabilities use the separate feature capability registry. Neither category should 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.

Annotations use both identities intentionally: user_id owns an observed draft; approval publishes it to the trusted account_id. With no account identity, approved annotation visibility degrades to deployment-wide. Exact catalog detail applies that scope at query time.

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.