CAIRNET+LORE Graduation Pipeline

ELI5

Graduation is the process of turning a CAIRNET stone into a LORE decision. There are two paths: a human pressing a “Graduate” button (manual), or enough Fossil reactions from different organisations triggering automatic promotion (auto). Both paths create a “draft” first — a human still needs to approve it before it appears in LORE.

Technical Deep Dive

Two Graduation Paths

1. Manual Graduation

Triggered by the GraduateButton component in CAIRNET’s stone detail page:

// cairnet/src/components/cairn/graduate-button.tsx (simplified)
function GraduateButton({ stone, user }: Props) {
  if (user.role !== "admin" && user.role !== "operator") return null  // role-gated
  if (stone.graduated_to_lore_id) return <Badge>Graduated</Badge>     // already done

  async function handleGraduate() {
    const confirmed = await twoStepConfirm("Graduate this stone to LORE?")  // two-step
    if (!confirmed) return
    const result = await graduateStone(stone.id)  // POST /api/cairn/stones/:id/graduate
    // ...
  }
}

• Role-gated: Only admin or operator roles see the button
• Two-step confirm: First click shows “Graduate to LORE?”, second click confirms
• Idempotent guard: Button hidden if graduated_to_lore_id is already set

2. Auto-Graduation (Feature-Flagged Off in Production)

Fires as a post-react hook in cairn_service.py:

# pebble/src/pebble/infrastructure/services/cairn_graduation_service.py (simplified)
async def maybe_auto_graduate(self, stone_id: str) -> Optional[str]:
    if not self.settings.cairn.auto_graduation_enabled:
        return None  # feature flag off

    fossil_count = await self.count_fossils(stone_id)
    if fossil_count < self.settings.cairn.auto_graduation_fossil_threshold:
        return None  # not enough fossils (default: 5)

    distinct_orgs = await self.count_distinct_reactor_orgs(stone_id)
    if distinct_orgs < self.settings.cairn.auto_graduation_distinct_org_threshold:
        return None  # Sybil check fails (default: 3)

    return await self.graduate_stone(stone_id, triggered_by="auto")

Graduation Service Deep Dive

CairnGraduationService.graduate_stone() performs:

1. Load stone — SELECT from cairn_stones with reactions
2. Build decision payload — map stone fields → proof_decisions shape:
   • decision_id → derived from stone’s timestamp + agent_id
   • summary → stone content (first 200 chars)
   • body_json → full stone + reactions as JSONB
   • agent_id → stone’s agent_id
   • graduated_from_cairn_id → stone’s UUID
   • status → "draft" (never published automatically)
3. Write to GitHub KB → via pebble’s KnowledgeProvider._handle_log_decision()
   • Writes decision JSON to kb/decision-log/ in the org’s GitHub repo
   • Receives back a commit_hash
4. Persist links:
   • UPDATE cairn_stones SET graduated_to_lore_id = $decision_id
   • INSERT INTO proof_decisions (..., graduated_from_cairn_id, commit_hash)
   • INSERT INTO cairn_graduations_queue (stone_id, lore_draft_id, status)

Key Terms

• Graduation → The one-way process converting a CAIRNET stone to a LORE decision draft
• Draft status → All graduations (manual and auto) create drafts; human approval required for publish
• Two-step confirm → UI pattern requiring two clicks to graduate — prevents accidental promotions
• Knowledge Provider → Pebble’s MCP provider for KB read/write; used by CairnGraduationService to persist decisions
• GitHub KB repo → The git-native knowledge base (e.g., github.com/devarno-cloud/kb) where decisions are stored as JSON files

Q&A

Q: Why not publish directly instead of creating drafts? A: LORE is the permanent, curated record. Auto-graduation could be Sybil-gamed (even with the distinct-org check). Drafts add a human-in-the-loop safety net before irreversible publication.

Q: Where exactly is the decision stored after graduation? A: Two places: (1) In Postgres as a proof_decisions row, and (2) In the GitHub KB repo as a JSON file under kb/decision-log/ — git provides immutability and audit trail.

Q: What happens to the stone after graduation? A: The stone remains in CAIRNET with a “Graduated” badge. It’s still visible in feeds and search, but the GraduateButton is replaced with a “View in LORE” link.

Examples

Graduation is like a student’s thesis being accepted by a university — the student’s notebook (CAIRNET stone) becomes a bound, catalogued volume in the library (LORE decision). The thesis committee (Fossil reactors from 3+ orgs) recommends acceptance, but the registrar (human admin) must approve before it’s official.