Human Contribution Log

The four provenance values

Every content line in every song carries one of these four values at any given moment. Section headers ([VERSE 1]) and performance directives ([WHISPER]) are not tracked — only the lyric content lines. The provenance can change over time as the line is mutated, but the value at any moment reflects WHO last touched the line.

How the percentage is computed

The aggregate %human is a simple ratio over the song's content lines:

humanContributionFraction(ledger) =
  count(entries where provenance ∈ {'human-locked', 'human-edited'})
  ÷
  count(entries)

humanContributionPct(ledger) = round(fraction × 100)

Section markers and performance directives are excluded from the denominator (they're not lyric content). Lines are counted equally regardless of length — a short hook line counts as one ledger entry, the same as a long verse line. No weighting, no adjustments.

How the ledger updates over time

When the user mutates the lyrics, the ledger reconciles via a deterministic line-by-line diff:

• Unchanged lines preserve their existing provenance. A line that was human-edited stays human-edited across subsequent forge operations until the line text itself changes.
• Changed or new lines are assigned the provenance the mutating action declares — human-edited from the textarea save path, human-locked from the line-rewrite acceptance path, ai-revised from a gauntlet pass.
• The previousText breadcrumb captures what the line was before the change. The seal can surface “originally AI wrote X, human changed to Y” without bloating the canonical entry.
• humanTouchedAt is pinned on first human contact and survives subsequent automated mutations. A line that was human-edited at 5:00 PM and then ai-revised at 6:00 PM still records 5:00 PM as the first human-touch timestamp — even though the current provenance is now AI.
• Duplicate lines (e.g. two identical chorus lines) are tracked as independent ledger entries — never collapsed. Each instance carries its own provenance.

The schema (machine-readable)

The canonical TypeScript definition lives in src/lib/contribution-ledger.ts (CC BY 4.0). External adopters implementing against this methodology should match this shape so ledgers are portable across systems:

type LineProvenance =
  | 'ai-original'    // forge produced; never touched
  | 'ai-revised'     // forge produced; gauntlet/refine modified
  | 'human-locked'   // forge produced; human approved (locked-in)
  | 'human-edited';  // human typed the line

interface LedgerEntry {
  text: string;                 // current line text
  provenance: LineProvenance;
  humanTouchedAt?: string;      // ISO; pinned on first human contact
  previousText?: string;        // breadcrumb of last change
}

interface ContributionLedger {
  version: 1;
  entries: LedgerEntry[];       // one per content line
  initiatedAt: string;          // ISO; stable across updates
  updatedAt: string;            // ISO; bumps on every reconciliation
}

How third parties can verify

The ledger is stored as a JSONB column on the song row in Supabase. The owner of the song can export it as a signed Authorship Receipt via the “Receipt” download in the dashboard (one click, JSON download). Public-song receipts are also available to any visitor — same endpoint, no auth required for songs marked public.

The receipt is a single self-contained JSON document carrying:

• The full ledger (every line, provenance, humanTouchedAt, previousText breadcrumbs).
• Aggregates recomputed server-side (humanContributionPct, countByProvenance) so the receipt's headline numbers don't depend on the verifier running the math.
• A SHA-256 contentHash of the canonical-JSON of the receipt body — recomputable by any verifier who canonicalizes-then-hashes.
• An ed25519 signature over { receiptVersion, songId, generatedAt, contentHash } — verifiable against the public key served at /.well-known/songforgeai-pubkey . The signature converts the receipt from “trust us” to “verify mathematically.”
• Cite-back to this methodology page + the canonical schema URL.

Endpoint: GET /api/songs/[id]/authorship-receipt — returns application/json with Content-Disposition: attachment. The methodology — how the number is computed from a ledger — is what's public on this page, citeable and reproducible against any compliant ledger.

The chip's three states

The ContributionChip component renders in three distinct states. Each state is a deliberate choice about what to communicate and when: