Dynamic, explainable, audit-ready governance for equity, compensation, profit share, and participation.
BEEM determines rightful participation in ownership and compensation based on measurable contribution, responsibility, persistence, and effort decay — not fixed percentages agreed once and never revisited. It is an open-source SaaS platform suitable for founders, operators, and enterprise compensation committees who need decisions to be reconstructable and defensible.
Proportional justice, rightful due, earned participation, entrusted responsibility, reduction of ambiguity, prevention of unjust extraction — encoded as a versioned engine and a normalized schema.
License: AGPL-3.0.
- Measures contribution across 10 configurable domains (product & IP, revenue impact, strategic leadership, execution ownership, operational systems, strategic access, partnerships, capital influence, risk & commitment, foundational creation).
- Separates foundational from dynamic entitlement. Foundational earned stake persists at a durable floor; dynamic entitlement recalibrates as contribution, persistence, and recharge evolve.
- Applies effort decay via five decay classes (A–E) with a documented half-life formula:
value(t) = floor + (1 − floor) × 0.5^(age / halfLife). - Normalizes across participants with hard safety rails — max single-participant share, min participant share, required-review drift threshold.
- Produces explainable results. Every result carries per-domain breakdowns, confidence bands, a plain-language narrative, and tamper-evident input/output hashes.
- Supports scenarios. Shift the as-of date, change the half-life, or simulate dilution — compare against the baseline without writing to production.
This is not a toy calculator. The scoring engine, decay engine, and entitlement engine are versioned independently; each run records which versions were in effect so past decisions remain reproducible even as the platform evolves.
beem/
├── apps/
│ ├── web/ # Next.js 14 App Router — tenant UI + API
│ └── docs/ # public docs site
└── packages/
├── ui/ # shadcn-derived design system with entitlement-specific primitives
├── config/ # env + Tailwind preset
├── db/ # Prisma schema + tenant context helpers
├── types/ # Zod schemas + shared types
├── scoring-engine/ # contribution index (v1.0.0)
├── entitlement-engine/ # decay + foundational/dynamic split + hashing (v1.0.0)
├── audit/ # audit event recorder
└── sdk/ # typed BEEM client
Stack: Next.js 14, TypeScript strict, Tailwind, PostgreSQL, Prisma 5, BullMQ-ready, S3-compatible storage, Vitest, Playwright, Docker. Multi-tenant via a TenantContext threaded through every mutation plus a Postgres session variable (beem.workspace) set in a withTenant() helper for future row-level-security policies.
cp .env.example .env
docker compose up --buildThen in another terminal:
docker compose exec web pnpm --filter @beem/db exec prisma migrate deploy
docker compose exec web pnpm --filter @beem/db exec prisma db seedOpen http://localhost:3000 and sign in as admin@demo.beem.local / Demo1234!.
The seed creates a demo workspace ("Northwind Labs"), five participants, a balanced methodology, a portfolio of contributions, and one complete run so the dashboard is populated out of the box.
pnpm install
cp .env.example .env
# start Postgres via Docker or point DATABASE_URL at any postgres 15+ instance
docker compose up -d postgres redis minio
pnpm --filter @beem/db exec prisma migrate dev
pnpm --filter @beem/db exec prisma db seed
pnpm devCurrent Entitlement Value
= ContributionIndex × Persistence × Relevance × Recharge
ContributionIndex ∈ [0, 100] per participant
= Σ (domain_weight × max(impact, reviewer_score) × confidence) / 100
(unreviewed evidence is hedged at half confidence, never dropped)
Persistence ∈ [floor, 1]
= floor + (1 − floor) × 0.5^(age_days / half_life_days)
Relevance ∈ [0, 1]
derived from role affinity ↔ domain alignment
Recharge ∈ [0, 1]
reflects ongoing activity ("wuquf" — standing ground under decay)
Entitlement is split into:
Foundational — durable floor, protected from erosion
Dynamic — recalibrated every run
Blended — weighted mixture reported as the current value
Every methodology embeds an immutable engineConfig JSON snapshot on creation:
{
"scoringEngineVersion": "1.0.0",
"decayEngineVersion": "1.0.0",
"normalization": "strict",
"foundationalFloor": 0.2,
"minConfidence": 0.5,
"halfLifeMultiplier": 1,
"safety": {
"maxSingleParticipantShare": 0.7,
"minParticipantShare": 0.005,
"requireHumanReviewAbove": 0.15
}
}A run is never published automatically if any of the rails trip — the engine emits a global flag (info / warn / block) and the UI surfaces it prominently. Drift above requireHumanReviewAbove vs the previous run forces dual approval.
Every EntitlementRun row records inputHash and outputHash: SHA-256 of the canonical JSON payload (stably sorted keys, ISO-8601 dates). A one-byte change anywhere in the input or output invalidates the signature. Exports include both hashes, plus the engine versions, so a third party can reconstruct any past decision from the same source evidence.
Four starting points. Each rebalances the ten default domains and tunes safety rails:
| Template | Use case |
|---|---|
founder |
Early-stage startup cofounder equity. Balanced, generous single-participant cap. |
gtm |
Go-to-market earn-in. Revenue + partnerships weighted, faster decay. |
operator_investor |
Operating partner vs passive investor split. |
exec_comp |
Annual executive compensation review. Tight caps, aggressive decay. |
Authentication: Authorization: Bearer beem_live_… (scoped keys, SHA-256-stored).
GET /api/v1/runs list recent runs
GET /api/v1/runs/{id}/export?format=json|csv|pdf export a completed run
GET /api/healthz liveness + db reachability
Scopes: read:runs, read:participants, read:methodologies, *.
Exports embed the engine version strings and both hashes so a downstream cap-table tool can verify authenticity offline.
Scenarios never write EntitlementResult rows — they are ephemeral what-ifs that reuse the production engine. You can:
- shift the as-of date (
+365→ "what does entitlement look like a year from now?") - rescale the half-life multiplier (
0.5×→ stricter decay) - reserve a new-pool share (
0.10→ simulate a 10% new-hire pool)
The detail page shows baseline vs simulated side by side, flags any safety-rail trips that would fire if the scenario were applied to the live methodology, and computes per-participant deltas in percentage points.
GovernanceRules is per-workspace:
minReviewersPerRun— minimum reviewed contributions to run without hedging.requireDualApprovalAbove— drift threshold forcing two approvers.exportRetentionDays— how long exports are archived (hashes + source evidence remain reproducible regardless).allowAiAssistance— opt-in AI drafting of narrative prose. Off by default. AI never produces entitlement values.
Every material mutation emits an AuditEvent row with actor, before/after snapshots, IP, user agent, and timestamp. The /app/audit page groups events by day. Categories: methodology, participant, contribution, run, scenario, governance, access.
- Playwright end-to-end test suite (starter smoke coverage)
- PDF export with watermark
- Webhook delivery worker with exponential backoff
- OpenAPI spec + generated client
- Row-level security policy scripts
- SAML / OIDC SSO scaffolding
- Terraform module for self-hosting (starter module)
Contributions welcome. This project is AGPL-3.0; by contributing you agree your work is licensed under the same terms. Start with CONTRIBUTING.md.
Equity, compensation, and participation decisions are often ambiguous, under-documented, and hard to defend after the fact. BEEM is an opinionated attempt to replace that ambiguity with measurable, versioned, reproducible governance — without sacrificing the human judgment that reviewers bring.
If this resonates, star the repo, try the demo, and open an issue with your use case.