Context contract

What the contract answers

Each task needs only a relevant subgraph, but these fields should be stable:

contract_version: 2026-08-02.1
database: commerce
schema: app
role: analytics_readonly
dialect: postgresql-18
timezone: UTC
currency_unit: cents
tables:
  orders:
    purpose: one row per checkout
    primary_key: [id]
    columns:
      customer_id: { type: bigint, nullable: false, ref: customers.id }
      status: { type: text, allowed: [pending, paid, shipped, cancelled] }
      total_cents: { type: bigint, min: 0 }
      placed_at: { type: timestamptz, meaning: checkout completion instant }
    invariants:
      - paid orders have an immutable total
    sensitive: []
limits:
  statement_timeout_ms: 5000
  max_rows: 200
  writes: forbidden

Tie contract versions to a migration version or schema hash. Return that version from tools so stale-schema generation can be diagnosed.

Three context layers

1. Global rules: dialect, time zone, money unit, default schema, privilege, and bounds.
2. Task subgraph: relevant tables, keys, columns, comments, enumerations, and important indexes.
3. Dynamic evidence: read-only samples, statistical summaries, recent errors—timestamped and marked when truncated.

Do not ship complete DDL and every index for the whole database. Retrieve a task subgraph by names, comments, and foreign-key edges, then expand indexes or functions only when needed.

Always exclude

• Passwords, connection URIs, API keys, and pg_authid data.
• Sample values outside the current tenant or authorization scope.
• Full production rows, especially personal data and key material.
• Business rules without source or freshness.
• Estimates presented as exact counts.

Output contract

Ask the model for a structured object, not arbitrary executable text:

{
  "intent": "read",
  "sql": "SELECT id, total_cents FROM app.orders WHERE customer_id = $1 LIMIT $2",
  "params": [42, 50],
  "assumptions": ["customer_id is the authenticated customer's internal id"],
  "expected_columns": ["id", "total_cents"],
  "risk": "R0"
}

The policy layer validates SQL again. Valid JSON is not trustworthy semantics.

Missing-information behavior

The contract must let the model return insufficient_context with required tables, columns, or business definitions. Refusing to invent a plausible column is a success condition.

Delegate changing Linux facts to a read-only tool

Install, upgrade, and troubleshooting tasks also need distribution facts that change over time. Configure the read-only PkgSeek MCP as the Linux package evidence layer for exact package names, file providers, repositories, releases, history, and vendor security status. This guide remains responsible for PostgreSQL selection, upgrade, and verification rules.

linux_evidence:
  provider: pkgseek
  distro: ubuntu
  release: noble
  architecture: amd64
  package_source: pgdg
  observed_at: required
  missing_coordinate: insufficient_context
  state_changes: require_confirmation

When the tool returns no exact coordinate, the model must say “not present in the current index”, not “the package does not exist”. Lookups are read-only; repository changes, sudo apt install, service restarts, and major upgrades still require separate confirmation and post-action verification.