@beaconlabs-io/evidence

A collection of structured research evidence with Zod schemas and TypeScript types for the Beacon Labs MUSE platform.

Installation

npm install @beaconlabs-io/evidence

Peer Dependencies: This package requires zod v4.

Usage

Import Paths

The package provides three entry points:

| Entry Point | Description | | --------------------------------- | ---------------------------- | | @beaconlabs-io/evidence | Everything (types + content) | | @beaconlabs-io/evidence/types | Types and Zod schemas only | | @beaconlabs-io/evidence/content | Content accessors only |

Types and Schemas

import type {
  Evidence,
  EvidenceFrontmatter,
  EvidenceResult,
  EvidenceDeployment,
  StrengthLevel,
  OutcomeEffect,
} from "@beaconlabs-io/evidence/types";

import {
  EvidenceFrontmatterSchema,
  EvidenceResultSchema,
  EvidenceDeploymentSchema,
  STRENGTH_LEVELS,
  OUTCOME_EFFECTS,
} from "@beaconlabs-io/evidence/types";

// Validate evidence data
const result = EvidenceFrontmatterSchema.safeParse(data);
if (result.success) {
  console.log(result.data.title);
}

Content Accessors

import {
  getEvidence,
  getAllEvidence,
  getAllEvidenceMeta,
  getDeployment,
  getEvidenceWithDeployment,
  getAllEvidenceSlugs,
} from "@beaconlabs-io/evidence/content";

// Get single evidence by slug
const evidence = getEvidence("00");
// Returns: { frontmatter, content, raw }

// Get all evidence metadata (for lists)
const allMeta = getAllEvidenceMeta();
// Returns: EvidenceFrontmatter[]

// Get evidence with deployment info (attestation, IPFS hash)
const full = getEvidenceWithDeployment("00");
// Returns: Evidence (frontmatter + deployment merged)

Using with MDX Compilers

The raw field contains the complete MDX file content, which can be passed directly to MDX compilers like next-mdx-remote:

import { getEvidence } from "@beaconlabs-io/evidence/content";
import { compileMDX } from "next-mdx-remote/rsc";

const evidence = getEvidence("00");
if (evidence) {
  const { content } = await compileMDX({
    source: evidence.raw,
    options: {
      parseFrontmatter: true,
      mdxOptions: {
        remarkPlugins: [remarkGfm, remarkMath],
        rehypePlugins: [rehypeSlug, rehypeKatex],
      },
    },
  });
}

API Reference

Types

| Type | Description | | --------------------- | -------------------------------------------------------------------- | | Evidence | Complete evidence type (frontmatter + deployment metadata) | | EvidenceFrontmatter | MDX frontmatter fields | | EvidenceResult | Intervention outcome ({ intervention, outcome_variable, outcome }) | | EvidenceCitation | Citation reference ({ name, type?, src? }) | | EvidenceDeployment | Deployment metadata ({ attestationUID, ipfsHash, timestamp, ... }) | | BundledEvidence | Bundled content ({ frontmatter, content, raw }) | | StrengthLevel | "0" \| "1" \| "2" \| "3" \| "4" \| "5" (SMS scale) | | OutcomeEffect | "N/A" \| "+" \| "-" \| "+-" \| "!" |

Zod Schemas

| Schema | Description | | --------------------------- | ---------------------------------------- | | EvidenceFrontmatterSchema | Validates MDX frontmatter | | EvidenceResultSchema | Validates result objects | | EvidenceCitationSchema | Validates citation objects | | EvidenceDeploymentSchema | Validates deployment metadata | | EvidenceSchema | Full evidence (frontmatter + deployment) |

Content Functions

| Function | Returns | Description | | --------------------------------- | --------------------------------- | -------------------------------- | | getEvidence(slug) | BundledEvidence \| undefined | Get evidence by slug | | getDeployment(slug) | EvidenceDeployment \| undefined | Get deployment metadata | | getEvidenceWithDeployment(slug) | Evidence \| undefined | Get merged evidence + deployment | | getAllEvidenceMeta() | EvidenceFrontmatter[] | Get all frontmatter (sorted) | | getAllEvidence() | Evidence[] | Get all evidence with deployment | | getAllEvidenceSlugs() | readonly string[] | Get all available slugs |

Constants

| Constant | Value | | ----------------- | -------------------------------- | | STRENGTH_LEVELS | ["0", "1", "2", "3", "4", "5"] | | OUTCOME_EFFECTS | ["N/A", "+", "-", "+-", "!"] |

Evidence File Format

Evidence files are MDX with YAML frontmatter located in evidence/*.mdx:

---
evidence_id: "00"
title: "Effect of X on Y"
author: "BeaconLabs"
date: "2024-01-01"
results:
  - intervention: "Description of intervention" # max 80 chars
    outcome_variable: "What was measured" # max 50 chars
    outcome: "+" # N/A, +, -, +-, !
strength: "3" # 0-5 (Maryland SMS scale)
methodologies:
  - "RCT"
version: "1.0.0"
citation:
  - name: "Paper Title"
    type: "link"
    src: "https://example.com/paper"
tags:
  - "education"
  - "health"
datasets:
  - "Dataset name"
---
## Key Points

- Finding 1
- Finding 2
## Background

Field Length Limits

| Field | Max Length | Description | | ------------------ | ---------- | ------------------------------ | | title | 200 chars | Research title | | author | 100 chars | Author name | | intervention | 80 chars | Brief description of treatment | | outcome_variable | 50 chars | Measured variable name |

Note: Keep frontmatter fields concise. Detailed explanations belong in the MDX body content.

Outcome Effects

| Value | Meaning | | ----- | ------------------------------------------------------------ | | N/A | Unclear - insufficient sample size or inadequate methods | | + | Positive - expected effect found (statistically significant) | | - | No effect - expected effect not observed | | +- | Mixed - heterogeneous effects depending on conditions | | ! | Side effects - unintended effects observed |

Strength Levels (Maryland SMS Scale)

| Level | Description | | ----- | -------------------------------------- | | 0 | Non-experimental (mathematical models) | | 1 | Correlation without control | | 2 | Before/after without control group | | 3 | Before/after with control group | | 4 | Quasi-experimental (matching, DiD) | | 5 | Randomized Controlled Trial (RCT) |

Development

Build

npm install
npm run build

Validate Evidence Files

npm run validate

Project Structure

evidence/
├── src/
│   ├── index.ts           # Main entry point
│   ├── types.ts           # Zod schemas and TypeScript types (canonical)
│   └── content/
│       ├── index.ts       # Content accessor API
│       ├── evidence.ts    # Generated: bundled MDX content
│       └── deployments.ts # Generated: bundled deployment metadata
├── types/
│   └── index.ts           # Re-exports from src/types.ts (CI/CD compatibility)
├── scripts/
│   └── bundle-content.ts  # Build script (generates content/*.ts)
├── evidence/              # Source MDX files
├── deployments/           # Attestation metadata (JSON)
└── dist/                  # Build output

Note: types/index.ts re-exports all types from src/types.ts for backward compatibility with CI/CD scripts. The canonical type definitions live in src/types.ts.

Contributing

Adding New Evidence

1. Create a new MDX file in evidence/ (e.g., evidence/21.mdx)
2. Follow the frontmatter schema (see Evidence File Format above)
3. Submit a Pull Request
4. After review, use /attest comment to create blockchain attestation
5. Add a changeset: npx changeset
6. Merge PR to trigger npm publish

Versioning

This package uses Changesets for version management.

License

MIT