Recourse Lang

A formal deliberation language for structured discourse and collaborative reasoning.

Philosophy

Recourse Lang treats deliberation as a cycle of claims and structured responses (recourses). Every contribution is code that explicitly defines its relationship to the whole debate.

• Action-Oriented: You don't just comment; you take structured action: CHALLENGE, SUPPORT, QUESTION, AMEND
• Evidence-First: Every claim requires structured reasoning with sources
• Portable: Export deliberations as .rsc files that any tool can analyze

Installation

npm install recourse-lang

Syntax

Commands

PROPOSE claim ("statement") { ... }     # Start a new claim
CHALLENGE claim ("target-id") { ... }   # Raise objection
SUPPORT claim ("target-id") { ... }     # Endorse with evidence  
AMEND claim ("target-id") { ... }       # Propose modification

Inside Blocks

because ("reason text")                 # Supporting reason
sources ["url1", "url2"]                # Evidence URLs
tags [tag1, tag2, tag3]                 # Categorization
question ("question text")              # Structured question
propose ("amended statement")           # For AMEND commands

Example

# City Bike Program Deliberation

PROPOSE claim ("We should invest in a city-wide bike-sharing program.") {
  because ("It reduces traffic congestion and carbon emissions.")
  sources ["https://example.com/study-on-bike-shares"]
  because ("It improves public health by encouraging physical activity.")
  sources ["https://cdc.gov/physical-activity"]
  tags [transportation, environment, budget]
}

CHALLENGE claim ("claim-abc-123") {
  because ("The initial investment is too high for our current budget.")
  sources ["https://city.gov/budget-report-2024"]
  question ("Has a cost-benefit analysis been done for our specific city?")
}

SUPPORT claim ("claim-abc-123") {
  because ("Portland saw 15% increase in local business revenue near bike stations.")
  sources ["https://portland-study.com/economic-impact"]
}

AMEND claim ("claim-abc-123") {
  propose ("We should pilot a bike-sharing program in the downtown district first.")
  because ("A pilot program would limit initial cost and allow us to gather data.")
}

Usage

import { parse, execute, serializeToRSC, toGraph } from 'recourse-lang';

const code = `
PROPOSE claim ("AI will transform education") {
  because ("Personalized learning at scale becomes possible")
  sources ["https://example.com/ai-education"]
  tags [ai, education]
}
`;

// Parse and execute
const ast = parse(code);
const document = execute(ast, "AI Education Debate", "user-alice");

// Serialize to .rsc file
const rscContent = serializeToRSC(document);

// Generate graph for visualization
const { nodes, edges } = toGraph(document);
// edges are color-coded: red=CHALLENGE, green=SUPPORT, amber=AMEND

Programmatic API

import {
  createEmptyDocument,
  createClaim,
  createChallenge,
  createSupport,
  createAmend,
  createBecause,
  createSource,
  addClaim,
  addRecourse,
} from 'recourse-lang';

// Create document
let doc = createEmptyDocument("My Deliberation");

// Add claim programmatically
const claim = createClaim(
  "We need better public transit",
  [createBecause("Reduces emissions", [createSource("https://study.com", "academic")])],
  ["transit", "environment"],
  "user-bob"
);
doc = addClaim(doc, claim);

// Add challenge
const challenge = createChallenge(
  claim.id,
  [createBecause("Cost is prohibitive")],
  undefined,
  "user-carol"
);
doc = addRecourse(doc, challenge);

Command Types

| Command | Role | |---------|------| | PROPOSE | Start a new claim | | CHALLENGE | Raise objection | | SUPPORT | Endorse with evidence | | AMEND | Propose modification | | EVIDENCE | Attach proof | | RESPONSE | Address a challenge | | ENDORSE | Express support position | | DISSENT | Express opposition | | STATUS | Query state | | RESOLVE | Close deliberation |

Graph Visualization

The toGraph() function returns nodes and edges for visualization:

• Nodes: Claims and recourses
• Edges: Color-coded by command type
  • 🔴 Red: CHALLENGE
  • 🟢 Green: SUPPORT
  • 🟠 Amber: AMEND
  • 🔵 Blue: PROPOSE
  • 🟣 Purple: EVIDENCE

Analysis Tools

import {
  detectContradictions,
  findEvidenceGaps,
  findSynthesisOpportunities,
  getChallengeCount,
  getSupportCount,
  hasUnresolvedChallenges,
  getClaimsByTag,
  getClaimsByAuthor,
} from 'recourse-lang';

// Find claims lacking evidence
const gaps = findEvidenceGaps(document);

// Find synthesis opportunities (challenges + amendments)
const opportunities = findSynthesisOpportunities(document);

// Get stats
const challenges = getChallengeCount(document, claimId);
const supports = getSupportCount(document, claimId);

File Format (.rsc)

Export deliberations as portable .rsc JSON files:

import { serializeToRSC, parseFromRSC } from 'recourse-lang';

// Export
fs.writeFileSync('debate.rsc', serializeToRSC(document));

// Import
const document = parseFromRSC(fs.readFileSync('debate.rsc', 'utf-8'));

License

MIT