@alef-prime/penalty-ledger

The accountability layer ALEF wears in public.

An append-only ledger for self-imposed penalties on AI-driven projects. Use it to compute a "reality coefficient" that drops when your engine fails publicly and recovers when penalties expire — visible to your users instead of hidden in a config.

import {
  parseLedger, activeRows, totalPenalty,
  dedupeByKey, adjustedCoeff, alreadyActive, toJsonl,
} from "@alef-prime/penalty-ledger";

// Read from disk (or DB)
const rows = parseLedger(await fs.readFile("./penalties.jsonl", "utf8"));

// Before appending a new penalty, check if one already active for this key:
if (!alreadyActive(rows, { source: "build-failed", directive: "v2.3" })) {
  await fs.appendFile("./penalties.jsonl", toJsonl({
    ts: new Date().toISOString(),
    amount: 0.1,
    reason: "build failed twice in a row",
    source: "build-failed",
    directive: "v2.3",
    expires_at: new Date(Date.now() + 3 * 24 * 3600 * 1000).toISOString(),
  }));
}

// Compute the public-facing score:
const coeff = adjustedCoeff(0.95 /* baseline accuracy */, rows);
//  → 0.85   (after one -0.1 active penalty)

Why this exists

ALEF-PRIME's reality_coeff hit 0.00 in May 2026. The Truth Arbiter said "brain dead." The actual bug: purpose_guard appended a fresh -0.1 row every round of growth-in-deficit, never deduping. Ten stacked copies of the same penalty made the coeff read zero — an artifact, not the truth.

The fix was dedupeByKey + alreadyActive. After applying both: 13 active rows → 4, coeff: 0.00 → 0.45. The lesson became this package.

API

| Function | Returns | Notes | |---|---|---| | parseLedger(text) | PenaltyRow[] | Parse newline-delimited JSON. | | activeRows(rows, now?) | PenaltyRow[] | Filter to rows still in their expiry window. | | totalPenalty(rows) | number | Sum of amount across active rows. | | dedupeByKey(rows) | PenaltyRow[] | Walk in order; per (source, directive) keep only the most recent. | | adjustedCoeff(baseline, rows) | number | max(0, min(1, baseline) − totalPenalty). | | alreadyActive(rows, key) | boolean | Use this BEFORE appending to avoid stacking. | | toJsonl(row) | string | Append-ready line. |

Recommended row shape

{
  ts: "2026-05-14T13:45:00Z",
  amount: 0.1,                     // how much to subtract from baseline
  reason: "shipped without test",  // human-readable, public
  source: "build-monitor",         // who decided to penalize
  directive: "v2.3",               // which mandate/round
  expires_at: "2026-05-17T00:00Z", // optional; permanent if absent
  red_lock: false,                 // optional UI signal: "lock the warning state"
}

Status: alpha · 0.1.0

Born from ALEF-PRIME's glass-box evolution. Sibling of @alef-prime/deploy-verify, @alef-prime/i18n-pick, @alef-prime/units. MIT.