gnomonlearn
Docs/AI & security/RFC-0009

RFC-0009 · AI Participation Contract

Versioned draft snapshot

RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.

Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.

Status Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release.

View the generated reference catalog →

Read design questions and decisions →

Status: Draft Owners: Semantic Core, Security, AI Platform

1. Scope

Defines how AI actors participate in Gnomon systems: what they are allowed to do, how their outputs are typed and bounded, what evidence they must produce, and how their capabilities are declared and enforced.

AI in Gnomon is not a magical subsystem. It is a constrained, typed actor with explicit capability declarations, an evidence obligation, and hard boundaries on what states it can create or transitions it can trigger. This RFC defines the normative contract for all AI actor participation.

This RFC applies to:

  • Agent declarations (.gnm files with top-level agent declarations per RFC-0008)
  • AI-produced gnomon instances and field values
  • LLM-assisted authoring workflows
  • Derivation pipelines that use AI models

2. Goals

  1. AI actors MUST be definable in terms that non-technical reviewers can assess
  2. AI-produced outputs MUST be structurally differentiated from human-verified data at the type level
  3. AI actors MUST NOT be able to finalize decisions or trigger high-authority actions without explicit human approval
  4. Evidence obligations (rationale, confidence, evidence links) MUST be enforceable by the compiler and runtime
  5. AI-assisted authoring MUST remain auditable and reversible

Linked References

The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.

3. Invariants

  1. Every AI actor MUST be declared as an agent with explicit permissions, prohibitions, and requirements.
  2. AI actors MUST NOT perform any action not listed in their permissions block.
  3. AI-produced fields MUST use Claim<T> wrappers (RFC-0006 §4.5) carrying at minimum confidence and source.
  4. AI actors MUST NOT trigger state transitions to terminal or high-authority states (e.g., Approved, Submitted, Finalized) without explicit human actor involvement.
  5. Agent declarations MUST be reviewed and explicitly approved before the agent is activated in non-development environments.
  6. AI-assisted authoring mutations (changes to module declarations) MUST be identifiable as AI-originated in the audit log.

4. Typed AI Protocols

AI actors do not write arbitrary data. They operate through a closed set of typed protocols. An agent declaration MUST enumerate only protocols from this set.

4.1 classify

Assign an gnomon instance or field value to one of N declared categories.

Required output: classification label, confidence, evidence links. Epistemic status of output: inferred.

4.2 extract

Extract structured field values from unstructured or semi-structured input (e.g., document OCR, natural language).

Required output: extracted value, source document reference, confidence per field. Epistemic status of output: observed (raw) or inferred (interpreted).

4.3 summarize

Produce a text summary of one or more gnomon instances.

Required output: summary text, source gnomon IDs, model ID, confidence. Epistemic status of output: inferred.

4.4 recommend

Propose a course of action with rationale.

Required output: proposed action, rationale, confidence, evidence links, explicit marking as AI-generated. Output state: MUST be a draft state; MUST require human review before finalization. Epistemic status of output: estimated.

4.5 propose

Create a draft gnomon instance for human review.

Required output: draft instance, rationale, confidence, source data references. Output state: MUST be in a Draft or equivalent non-final state. Epistemic status of output: estimated.

4.6 fill

Suggest a value for a missing or incomplete field.

Required output: suggested value, confidence, source reference. Requires: user confirmation before the suggestion is committed as asserted. Epistemic status before confirmation: estimated. After confirmation: asserted with provenance trace.

4.7 map

Map external or natural-language terminology to controlled vocabulary.

Required output: target vocabulary term, confidence, original text.

4.8 flag

Raise an ambiguity, conflict, or anomaly for human review.

Required output: description of the issue, affected gnomon IDs, severity. This is an output-only protocol; the AI MUST NOT resolve flags autonomously.

4.9 request_confirmation

Explicitly request that a human actor confirm or reject an AI-produced value or action.

Required output: value or action to confirm, rationale, confidence. Blocks downstream operations until confirmation is received.

5. Evidence Obligations

Any AI actor producing an output MUST satisfy the evidence obligation declared in its requirements block. The minimal required evidence set is:

  • confidence — numeric score or range
  • source — model ID and version, or source document reference
  • rationale — plain-language explanation of the output
  • evidence_links — references to supporting gnomon instances, documents, or claims

Outputs that do not satisfy all declared requirements MUST be rejected with diagnostic M09803.

The runtime MUST enforce evidence obligations at the point of gnomon write. It MUST NOT rely solely on agent-side honesty.

6. AI Authoring Contract

When AI tools assist with authoring Gnomon module declarations (e.g., proposing entity definitions, suggesting invariants), the following rules apply:

  1. AI-authored declarations MUST be tagged with authored_by: ai and the model ID in the compiled bundle.
  2. AI-authored declarations MUST pass the same compiler validation as human-authored declarations.
  3. AI-authored declarations MUST be reviewed by a human author before being marked as approved in the install plan.
  4. The MCP interface for AI-assisted authoring MUST return structured diagnostics and MUST NOT bypass schema validation (RFC-0000 §8).
  5. AI MUST NOT delete existing declarations autonomously; deletions require human confirmation.
  6. Every AI tool, MCP server, or automated process that produces .gnm file content MUST pass that content through gnomon fmt before writing to disk or returning it to the caller (RFC-0012 §4.6). A file produced by an AI tool that is not in canonical form is a compliance violation of this contract (diagnostic M09822).
  7. AI-authored declarations MUST use the draft epistemic modifier (RFC-0008 §11.2) until human review is complete. An AI tool MUST NOT produce a declaration without the draft modifier unless it is explicitly replacing a human-approved declaration and the replacement has itself been approved. Violation produces diagnostic M09823.

6.4 Canonical Form Requirement

Every AI tool, MCP server, or automated process that produces .gnm file content MUST pass that content through gnomon fmt before writing to disk or returning it to the caller. The formatter is defined in RFC-0012 §4.6 and enforces canonical whitespace, field ordering, and comment placement. A .gnm file produced by an AI tool that is not in canonical form MUST be rejected by the compiler with diagnostic M09822. This requirement applies regardless of whether the output is a new declaration or a modification to an existing one.

6.6 Formatter Integration Requirement

The gnomon fmt pass is a mandatory gate between AI-generated content and the Gnomon source tree. Implementations of AI authoring tools MUST invoke gnomon fmt (RFC-0012 §4.6) on their output synchronously before returning content to the caller. An AI authoring tool that bypasses this gate is non-conformant with this contract. The formatter is not advisory; its output is the only accepted form. Violations produce diagnostic M09822.

6.7 Draft Epistemic Modifier Requirement

AI-authored declarations MUST carry the draft epistemic modifier (RFC-0008 §11.2) until a human author has reviewed and explicitly approved the declaration. An AI tool MUST NOT produce or propose a declaration without the draft modifier unless it is replacing an already-approved declaration and the replacement itself has been approved through the standard review workflow. Removing the draft modifier without a recorded human approval is a compliance violation (diagnostic M09823). This requirement applies to all AI-produced declarations regardless of the authoring surface used (CLI, MCP, IDE plugin).

7. Training and Supervision

AI models used in derivation pipelines (RFC-0007 §8) MUST be declared with:

  • model ID and version
  • training data provenance (if known)
  • declared capability scope (which typed protocols it supports)
  • confidence calibration baseline (if available)

Model version changes MUST trigger re-evaluation of affected derivations. Stale derivations (derived from an older model version) MUST be detectable (RFC-0007 §11, M07621).

Diagnostics

The diagnostic catalog for this RFC is authored in the structured Lean module and rendered in reference catalog § Diagnostics. Inline mentions in the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog at render time.

9. Security and Authorization

9.1 Baseline Authorization Rules

  1. Agent capability scope MUST be enforced at the runtime boundary, not only at authoring time.
  2. AI actors MUST be subject to the same RLS and authorization policies as human actors.
  3. Agent activation in non-development environments MUST require a deployment approval step in the install plan (RFC-0005).
  4. AI-produced Claim<T> values on a gnomon whose epistemic_status is estimated or inferred MUST NOT be used in authorization decisions without explicit adjudication by a human or rule-based actor. The field’s own status follows the RFC-0006 ClaimStatus flow; estimated and inferred are not ClaimStatus states.
  5. Evidence obligations are security constraints, not merely documentation; their enforcement is normative.

9.2 Prompt Injection Prevention

Prompt injection is the class of attacks where adversarial content embedded in external data (documents, user input, API responses) is interpreted as instruction by an AI agent, causing it to perform unauthorized actions.

  1. Input boundary isolation: An agent MUST NOT concatenate raw user input or untrusted external document content directly into a prompt template. All variable substitutions into prompt templates MUST pass through the declared PromptVariable type contract (RFC-0010 §4.6 defines the PromptVariable IR struct; runtime enforcement of the type constraint is governed by the kernel’s validation responsibilities per RFC-0010 §6.6); untyped interpolation is forbidden.
  2. Instruction/data separation: Prompt templates MUST structurally separate the instruction portion (authored at declare time) from the data portion (populated at runtime). Templates that embed runtime data in positions where an LLM treats it as instruction are non-conformant.
  3. Output sanitization: An agent that writes a Claim<T> field MUST strip or escape any content in the value or rationale fields that contains Gnomon DSL syntax, shell metacharacters, or instruction-like patterns before writing. The kernel MUST reject claim writes where the value exceeds a length bound appropriate to the declared type (String, Number, etc.).
  4. Diagnostic: M09830 is emitted when a prompt template variable lacks a declared type constraint. M09831 is emitted when a Claim<T> write contains a value that fails output sanitization.

9.3 Agent Privilege Escalation Prevention

Privilege escalation occurs when an AI agent invokes another agent (or presents itself as a different actor) with broader permissions than its own declared scope.

  1. Delegation prohibition: An agent MUST NOT invoke another agent on behalf of a human actor unless the human actor has explicitly confirmed the delegation as a Command through the runtime (RFC-0010 §6.3). Agents MUST NOT chain-invoke other agents autonomously without a human confirmation gate between invocations that cross a trust boundary.
  2. Scope non-expansion: When agent A invokes agent B, the effective permission set of the invocation is the intersection of A’s declared capabilities and B’s declared capabilities. Neither agent may grant the other capabilities beyond its own declaration.
  3. Actor identity enforcement: An agent MUST submit commands with its own declared actor identity. Submitting a command with a different actor identity (human, role, or other agent) MUST produce a kernel rejection (M09832) regardless of the command’s declared permissions.
  4. Capability declaration exhaustiveness: The set of ActionTypes an agent may invoke is derived from the ActionType entries in its permissions rule-block (RFC-0008 §8.10). Any attempt by the agent to submit a Command for an ActionType not covered by its permissions block MUST be rejected by the kernel before precondition evaluation (M09833).

9.4 Input Anomaly Detection

  1. An agent that produces Claim<T> values SHOULD declare an anomaly_policy on its output fields specifying:
    • max_value_length — maximum character count for string fields
    • allowed_confidence_range — [min, max] range for confidence scores
    • disallowed_patterns — list of regex patterns whose presence in a value MUST cause the write to be rejected
  2. A module MAY declare a module-level anomaly policy (via a policy declaration) that applies to all AI-produced claim writes in the module. This overrides any default thresholds.
  3. The runtime MUST enforce declared anomaly policies before the kernel processes the Claim<T> write. Violations MUST produce diagnostic M09834 and MUST NOT allow the write to proceed.
  4. Conformant implementations SHOULD log all rejected writes with the violating pattern for audit review.

10. Compatibility and Migration

  1. Adding a new protocol to the canonical typed protocol set is a non-breaking change.
  2. Removing a protocol requires migrating all agent declarations that use it.
  3. Tightening evidence obligation requirements (adding mandatory fields) is a breaking change for existing agents.
  4. Changing a confidence threshold in a policy is not a breaking change but MUST be reflected in the install plan diff.