8000 GitHub - ylu999/jingu-protocol · GitHub
[go: up one dir, main page]

Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

jingu-protocol

Shared protocol types for the Jingu system.

Contains the Reasoning Provenance Protocol (RPP) — a per-call cognitive audit contract that requires every AI reasoning step to be traceable to evidence, rules, or methods before any tool or action is allowed to execute.

Every claim an AI makes must be backed by a reference.
If you can't trace it, you can't trust it.

What is RPP?

RPP is a structured audit record that an AI agent must produce alongside any action it takes. It enforces four cognitive stages before execution:

interpretation → reasoning → decision → action → response

Each stage must:

  • Have non-empty content
  • Cite at least one reference (evidence, rule, or method)
  • The decision stage must cite a rule or method (not just evidence)
  • The response content must be traceable to prior step content

A pre_tool_use hook validates the RPP block before any tool runs. Missing or invalid RPP blocks the execution.


Install

npm install jingu-protocol

Quick start

import { validateRPP } from "jingu-protocol"
import type { RPPRecord } from "jingu-protocol"

const record: RPPRecord = {
  call_id: "call-001",
  steps: [
    {
      stage: "interpretation",
      content: ["User wants to read file foo.ts"],
      references: [{ type: "evidence", source: "user_input", locator: "message.current", supports: "user asked to read foo.ts" }],
    },
    {
      stage: "reasoning",
      content: ["foo.ts likely contains the type definition we need"],
      references: [{ type: "method", method_id: "DBG-001", supports: "read before write — inspect file before modifying" }],
    },
    {
      stage: "decision",
      content: ["Read foo.ts to confirm type shape before editing"],
      references: [{ type: "rule", rule_id: "RUL-002", supports: "cite evidence for every claim before acting" }],
    },
    {
      stage: "action",
      content: ["Read foo.ts"],
      references: [{ type: "evidence", source: "file", locator: "src/foo.ts", supports: "target file for the read action" }],
    },
  ],
  response: {
    content: ["Read foo.ts to confirm type shape"],
    references: [{ type: "derived", supports: "action step states: read foo.ts" }],
  },
}

const result = validateRPP(record)
// result.overall_status: "valid" | "weakly_supported" | "invalid"
// result.failures: RPPFailure[]   — hard failures (block execution)
// result.warnings: RPPFailure[]   — soft failures (flagged but allowed)

Validation rules

Hard failures — block execution

Code What it catches
MISSING_STAGE One of the 4 required stages (interpretation, reasoning, decision, action) is absent
EMPTY_CONTENT A stage has no content entries
NO_REFERENCES A stage has no references
UNJUSTIFIED_DECISION Decision stage has only evidence refs — must have at least one rule or method
UNTRACEABLE_RESPONSE Response content cannot be traced back to any prior step
INVALID_REFERENCE A rule_id or method_id is malformed, or an evidence ref has empty source/locator

Soft failures — warnings only

Code What it catches
SUPPORTS_TOO_VAGUE A reference's supports field is under 10 characters
INFERENCE_AS_FACT Reasoning stage uses certainty language without an evidence reference
METHOD_NOT_ACTUALLY_USED A method_id is cited but the method's logic is not reflected in the content
CIRCULAR_REFERENCE Two references mutually cite each other with no external grounding
ACTION_SCOPE_VIOLATION Action proposes more than what the decision stage authorized

Reference types

type EvidenceRef = {
  type: "evidence"
  source: string      // "user_input" | "file" | "log" | "test_output" | "tool_result"
  locator: string     // file path with optional :line, log line range, etc.
  supports: string    // which specific claim this evidence supports
}

type RuleRef = {
  type: "rule"
  rule_id: string     // must match /^[A-Z]+-\d+$/ — e.g. "RUL-001"
  supports: string
}

type MethodRef = {
  type: "method"
  method_id: string   // must match /^[A-Z]+-\d+$/ — e.g. "RCA-001"
  supports: string
}

Exports

// Types
export type { RPPRecord, RPPFailure, RPPFailureCode, RPPValidationResult }
export type { EvidenceRef, RuleRef, MethodRef, Reference }
export type { CognitiveStep, ResponseStep }
export type { RPPFailureDescription }

// Functions
export { validateRPP }
export { isHardFailure }
export { RPP_FAILURE_DESCRIPTIONS }

Who uses this

Package Role
jingu-trust-gate Runs validateRPP as a pre_tool_use hook — blocks tool execution if RPP is missing or invalid
jingu-policy-core Re-exports all RPP types for consumers that import from jingu-policy-core

License

MIT

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0