rye-agent-ops

name	rye-agent-ops
description	Operate Rye data safely for LLM agents. Use when implementing or executing agent read/write flows, connecting domain tables, selecting assertion keys, enforcing provenance, and applying agent-safe SQL patterns for context retrieval and auditable writes.

Rye Agent Ops

Session Setup (Required)

Before any query, set the session context. On stateless connections (Supabase MCP, serverless, transaction-mode poolers), this must be done in every call:

SELECT set_config('app.current_role', 'admin', false);
SELECT set_config('app.current_user_id', 'user-123', false);
SELECT set_config('app.current_teams', 'engineering', false);

Without this, RLS will block access. Use set_config() (not SET syntax) for portability.

Orient

1. Run SELECT rye_catalog() to see what's in the instance — node types, edge types, assertion types, tracked tables, and totals.
2. Use agent_node_summary(node_id, max_items) for compact context on a specific node.

Why Rye Uses SQL Helpers

Rye's durable contract lives in PostgreSQL because the database is the shared boundary used by humans, agents, admin UI, plugins, and import tools. Agents should not reimplement assertion lifecycle rules in prompts or application code. Use Rye SQL helper functions because they enforce the same behavior for every caller:

• RLS and team/classification boundaries
• append-only events
• immutable assertion content
• supersession and dispute semantics
• current versus historical versus future-effective truth
• candidate provenance and promotion traceability

Treat helper functions as the public API. Raw SQL is acceptable for reads and for simple inserts where no helper exists, but lifecycle-sensitive writes should go through the helper that owns that lifecycle.

Scoped External Agents

External runtimes should enter Rye through the secure API/MCP contract, not by choosing their own database target. Admins create an agent identity, grant domain-scoped capabilities, and issue a one-time-visible token:

./scripts/rye agents create --key sales-intake --label "Sales Intake Agent"
./scripts/rye agents grant --key sales-intake --capability rye.context.read --domain account-updates
./scripts/rye agents grant --key sales-intake --capability rye.candidate.create --domain account-updates
./scripts/rye agents issue-token --key sales-intake

The token authenticates to the API. The API then calls SQL functions that check the agent identity, domain grants, scope, and requested capability. Use:

• agent_get_context_pack(...) for scoped domain context.
• agent_submit_observation(...) for raw observed source facts.
• agent_create_candidate(...) for proposed business knowledge.
• authorize_agent_action(...) and record_agent_action(...) for API/plugin operations that need explicit allow/deny audit rows.

Do not promote authoritative facts from source text or MCP tool instructions. Promotion requires rye.candidate.adjudicate or rye.authoritative.promote over the candidate's domain/scope and should come from a reviewer or an authoritative system rule.

Candidate metadata should be business-readable and include:

• domain_keys
• source_scope
• impact_scope
• authority_basis
• speech_act
• current_or_future
• evidence_refs

Use current_or_future = 'future' or plugin scheduling helpers for planned process changes and milestones. Do not let future policy replace current answers before the effective date.

Connect Domain Tables

1. Use link_record(schema, table, id, node_type, label, properties) to connect a domain table row to the graph. Idempotent.
2. Use track_table(schema, table) to attach CDC triggers that capture INSERT/UPDATE/DELETE as graph events.

Write Events

Use record_event(...) for all event creation:

SELECT record_event(
    p_event_type := 'meeting',
    p_summary := 'Weekly sync',
    p_participant_ids := ARRAY[node1, node2]::uuid[],
    p_participant_roles := ARRAY['organizer', 'attendee']
);

Do not insert into events and event_participants separately.

Write Assertions

• Prefer record_assertion(...) for accepted assertions. It handles current, historical, candidate, and future-effective modes consistently.
• For single-valued facts, use assertion_key = 'default' unless a plugin says otherwise.
• For multi-valued facts, use stable domain keys in assertion_key.
• Use contest_assertion(...) when the new claim contradicts accepted knowledge and the correct answer is uncertain.
• Do not run direct UPDATE assertions.

Plans and Future Assertions

Separate plans from future-effective truth.

• A plan is current-visible knowledge about intended future work. Store it as a *_plan assertion or a plugin-specific plan helper.
• A future assertion is the state Rye should answer on or after a future date. Store it through record_assertion(...) with p_effective_at in the future, or through a plugin helper that delegates to record_assertion(...).

Use current reads for "what is true now":

SELECT *
FROM rye.current_valid_assertions
WHERE subject_node_id = '<node_uuid>'::uuid;

Use as-of reads for "what will be true after the cutover":

SELECT *
FROM rye.assertions_as_of('2026-10-16T00:00:00Z'::timestamptz)
WHERE subject_node_id = '<node_uuid>'::uuid;

For CRM/PM scheduling, prefer the plugin helpers:

• schedule_deal_stage_change(...)
• schedule_task_status_change(...)
• schedule_milestone_status_change(...)

These write both a current-visible plan assertion and a future-effective status or stage assertion. Do not treat a plan as already true.

Knowledge Candidates and Promotion

Use the candidate workflow when source material has plausible facts, tasks, decisions, risks, procedures, preferences, or semantic edges but the knowledge has not been accepted yet.

1. Create proposed candidates with create_knowledge_candidate(...).
2. Link candidates to source evidence with supported_by and to import/run context with derived_from using the helper function parameters.
3. Keep candidate status as proposed or needs_review until a user or trusted reviewer accepts, rejects, marks duplicate, or asks for promotion.
4. Promote accepted candidates only through:
   • promote_candidate_to_assertion(...)
   • promote_candidate_to_task(...)
   • promote_candidate_to_edge(...)
5. Store candidate provenance in promoted assertion/edge/task attrs. The helper functions already preserve candidate and source refs.
6. If source accounts or containers are still needs_confirmation, do not rely on their default context to promote knowledge. Use only item-level evidence and explicit reviewer decisions.

Candidate statuses are:

• proposed
• accepted
• rejected
• needs_review
• duplicate
• superseded

Do not bulk-promote a candidate queue just because a parser generated it. A bulk promotion must have an explicit approval decision, target shape, and provenance policy.

Provenance

• Log agent queries with log_agent_query(agent_id, query, summary, node_ids).
• Attach source_event_id to assertions when the fact came from an event.

Safety

• Keep reads scoped and ranked.
• Avoid dumping full history to the model by default.
• Gate high-risk actions behind explicit user confirmation.