breakthroughs

Policy, dispatch, and traceability for targeted compute.

Install

npm install breakthroughs

For local development inside this repo:

cd packages/breakthroughs
npm test
npm pack --dry-run

What This Is

breakthroughs is a small package for codebases that want to use compute deliberately.

It helps a host system answer questions like:

• is this decision important enough to justify heavier compute
• should this packet run locally or request paid approval
• what outputs are required for the run to count
• how does the result flow back into the host system cleanly

The core idea is simple:

1. define the decision
2. define the compute packet
3. define the allowed rungs and budget policy
4. dispatch only when the packet is bounded
5. require a traceable result bundle and impact read

What This Is Not

breakthroughs is not:

• a generic job queue
• a cloud-specific SDK
• a training framework
• an excuse to spend compute without a frozen question

It is a governance and orchestration layer for targeted compute.

Core Primitives

• Decision
  • the exact question the host system is trying to answer
• ComputePoint
  • one discovered place in a repo where targeted compute may legitimately reduce uncertainty
• ProjectComputeMap
  • a repo-level catalog of discovered compute points for an agent-first system
• Rung
  • the compute tier for the packet, such as local 4090 or paid H100
• ComputePacket
  • the bounded unit of work with inputs, success bar, stop condition, and required outputs
• Policy
  • the budget and authorization logic for local and paid compute
• ResultBundle
  • the completed artifacts from execution
• ImpactRead
  • how the result changes the host system's next action

Cross-Project Shape

breakthroughs should not assume every repo uses compute for the same reason.

Two real shapes already exist behind this package:

• longevity-research
  • compute is an evidence and certification ladder
  • example question: can a bounded model separate adult human RGC state from developmental or route-like movement on honest holdouts
  • entry surfaces live in controller phases, benchmark waves, and spend-class gates
• sunflower-coda / ode-to-erdos
  • compute is part of the active theorem-pass and report-building flow
  • example question: is a problem workspace bootstrapped, theorem-pass ready, and able to emit stable wave artifacts without breaking route semantics
  • entry surfaces live inside status, setup, and pass, not as a separate operator-only lane

That means the reusable abstraction is not "GPU job."

It is:

• where in this repo does compute legitimately belong
• what question does that compute point answer
• which local or paid rungs are allowed there
• what outputs must come back for the result to count

Package Positioning

The strongest use case is not "find more places to run GPUs."

The strongest use case is:

"Use the smallest honest compute rung to reduce one exact uncertainty, then route the result back into the host system with provenance."

Quick Start

import {
  defineDecision,
  definePolicy,
  defineRung,
  defineComputePacket,
  evaluateDispatch,
} from "breakthroughs";

const decision = defineDecision({
  id: "adult-vs-developmental-rgc",
  question:
    "Does this route generalize on an adult holdout without false restoration drift?",
  requiredOutputs: [
    "run_manifest.json",
    "metrics.csv",
    "calibration.json",
    "confusion_summary.csv",
    "failure_note.md",
    "impact_note.md",
  ],
});

const localScout = defineRung({
  id: "local-4090-scout",
  label: "Local Windows 4090 scout",
  spendClass: "local_unmetered",
  admitted: true,
});

const paidTransfer = defineRung({
  id: "h100-transfer",
  label: "Paid 1x H100 transfer check",
  spendClass: "paid_metered",
  admitted: true,
});

const policy = definePolicy({
  local: {
    defaultAction: "allow",
  },
  paid: {
    defaultAction: "require_explicit_approval",
    approvedRungs: [],
  },
});

const packet = defineComputePacket({
  id: "wave-1-promotion-evidence",
  decisionId: decision.id,
  rungId: localScout.id,
  question:
    "Can a bounded model separate adult RGC state from developmental movement on an adult dataset holdout?",
  successBar: {
    aurocMin: 0.9,
    falseRestorationRateMax: 0.15,
  },
  stopCondition:
    "Hold if performance collapses on true holdouts or the signal tracks protocol more than biology.",
  requiredOutputs: decision.requiredOutputs,
});

console.log(evaluateDispatch({ decision, rung: localScout, policy, packet }));

Expected result:

{
  action: "run_local",
  spendClass: "local_unmetered",
  decisionId: "adult-vs-developmental-rgc",
  rungId: "local-4090-scout",
  requiredOutputs: [...]
}

Project Compute Maps

The package also supports repo-level compute catalogs so an agent can discover project-specific compute points before it decides whether to dispatch anything.

import {
  buildComputePointDecisionPacket,
  defineProjectComputeMap,
  findComputePoint,
} from "breakthroughs";

const projectMap = defineProjectComputeMap({
  projectId: "longevity-controller",
  label: "Partial reprogramming controller",
  repoRoots: ["/abs/path/to/longevity-research"],
  rungs: [
    {
      id: "local-4090-scout",
      label: "Local 4090 scout",
      spendClass: "local_unmetered",
      admitted: true,
    },
    {
      id: "paid-h100-transfer",
      label: "Paid H100 transfer",
      spendClass: "paid_metered",
      admitted: true,
    },
  ],
  defaultPolicy: {
    local: { defaultAction: "allow" },
    paid: {
      defaultAction: "require_explicit_approval",
      approvedRungs: [],
    },
  },
  computePoints: [
    {
      id: "adult-vs-developmental-rgc-opponent",
      label: "Adult vs developmental RGC opponent lane",
      question:
        "Can a bounded model distinguish adult human RGC state from developmental or route-like movement on honest holdouts?",
      intent: "classification",
      entrySurfaces: ["controller.phase.350.1", "orp.compute.decide"],
      triggerSignals: [
        "adult authority mini-pack frozen",
        "honest holdout split materialized",
      ],
      defaultRungId: "local-4090-scout",
      permittedRungIds: [
        "local-4090-scout",
        "paid-h100-transfer",
      ],
      requiredOutputs: [
        "run_manifest.json",
        "metrics.csv",
        "controller_impact_note.md",
      ],
      evidenceExpectation:
        "Produce a bounded result bundle that can change controller belief without overclaiming restoration.",
      stopConditions: [
        "Hold if the signal tracks protocol more than biology.",
      ],
    },
  ],
});

const point = findComputePoint(
  projectMap,
  "adult-vs-developmental-rgc-opponent",
);

const packetTemplate = buildComputePointDecisionPacket({
  projectComputeMap: projectMap,
  pointId: point.id,
  rungId: "local-4090-scout",
  successBar: { aurocMin: 0.9 },
});

console.log(packetTemplate.rung.id, packetTemplate.policy.paid.defaultAction);

See:

• repo-compute-maps.js
• breakthroughs-cross-project-compute-patterns-2026-03-25.md

A project map can now carry its own rung catalog and default policy, which means host systems like ORP can dispatch directly from a repo compute catalog instead of rebuilding that context by hand.

Included Schemas

The package now ships machine-readable schemas for:

• ComputePacket
• ComputePoint
• ProjectComputeMap
• ResultBundle
• ImpactRead
• ApprovalReceipt
• TraceabilityRecord

These can be used by host systems to validate the objects they persist or exchange across process boundaries.

Runtime Validators

The package also exports lightweight runtime validators for:

• validateDecision
• validateComputePoint
• validateProjectComputeMap
• validateRung
• validatePolicy
• validateComputePacket
• validateResultBundle
• validateImpactRead
• validateApprovalReceipt
• validateTraceabilityRecord

These are intentionally minimal and dependency-free.

Dispatch Semantics

The package intentionally distinguishes:

• compute readiness
• scientific admission
• spend authorization

A packet can be scientifically ready and still not be financially authorized.

That means a paid rung can return:

• request_paid_approval

instead of:

• run_paid

Traceability

Every completed run should produce:

• one ResultBundle
• one ImpactRead
• one traceability record linking:
  • decision
  • rung
  • packet
  • result bundle
  • impact read

For paid compute, the host system should also persist one approval receipt before dispatch.

Persistence Helpers

The package includes tiny persistence helpers for:

• buildApprovalReceipt(...)
• writeApprovalReceipt(path, receipt)
• writeResultBundle(path, bundle)
• writeTraceabilityRecord(path, record)

These are intentionally small and file-based so the host code can plug them into its own storage layer later.

ORP Integration

breakthroughs is designed to sit underneath open-research-protocol, not replace it.

The clean dependency direction is:

• open-research-protocol owns the larger research workflow, packets, and governance
• breakthroughs owns targeted-compute policy, dispatch, spend gating, and traceability

That makes the intended adoption path very simple:

1. publish breakthroughs
2. add it as a dependency in open-research-protocol
3. let ORP call breakthroughs anywhere it needs bounded compute admission, local execution, or paid approval gating

That means ORP can use breakthroughs to decide:

• whether a compute packet is bounded enough to run
• whether the packet should run locally or request paid approval
• what approval receipt is required before paid dispatch
• what traceability objects should be attached to the run

This package now includes a small ORP bridge with:

• buildOrpComputeGateResult(...)
• buildOrpComputePacket(...)

See:

• examples/orp-bridge.js

The intended long-term integration is:

1. ORP emits or receives a process-only packet describing a research task.
2. ORP calls breakthroughs for compute admission and spend-class evaluation.
3. breakthroughs returns run_local, request_paid_approval, run_paid, or hold_packet.
4. ORP embeds the resulting approval, gate, and traceability objects into its own packet and artifact flow.

Local Shell Adapter

The first execution backend in breakthroughs is the local-shell adapter.

It exists for one reason:

• after a packet is admitted for local compute, the host system still needs a small, auditable way to actually run that packet

The adapter provides:

• defineShellTask(...)
• buildShellDispatchPlan(...)
• runLocalShellPacket(...)

What it does:

• accepts one bounded local command
• runs it only after dispatch has already resolved to run_local
• captures stdout, stderr, exit code, duration, timeout state, and the packet identity
• returns a structured execution receipt the host system can persist or bridge into ORP

What it does not do:

• decide whether compute is allowed
• bypass paid approval rules
• replace the host system's artifact model

The local-shell adapter is the first "real execution hand" underneath the policy layer.

See:

• examples/local-shell.js

Recommended v0 Usage

Use breakthroughs when your host code already knows:

• the exact question
• the allowed compute tiers
• the success bar
• the stop condition
• the outputs that would change behavior

Do not use it as a substitute for defining those things.

Example

See:

• examples/ocular-opponent.js

Near-Term Roadmap

Potential next additions:

• adapters for Slurm and cloud runtimes
• spend-envelope helpers
• runtime validators against the shipped schemas
• adapter-level execution receipts

Status

This package scaffold is v0 and intentionally spec-first.

The first goal is to make the abstraction clear and useful before adding transport-specific execution backends.