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

``bash
npm install recourse-lang
`

Syntax

$3

`
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
`

$3

`
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

`javascript


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

`typescript
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

`typescript
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

`typescript
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:

`typescript
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