From 7e4af71e1f54d6ca16bcce64e4d325efa9ba7818 Mon Sep 17 00:00:00 2001 From: Jorel97 Date: Fri, 29 May 2026 11:25:19 -0600 Subject: [PATCH] Add bounty transparency lineage schema --- .../.schemas/tiinex.bounty-transparency.v1.md | 204 ++++++++++++++++++ .topics/bounty-transparency/001.trace.md | 102 +++++++++ tools/validate_bounty_transparency.py | 148 +++++++++++++ 3 files changed, 454 insertions(+) create mode 100644 .topics/.schemas/tiinex.bounty-transparency.v1.md create mode 100644 .topics/bounty-transparency/001.trace.md create mode 100644 tools/validate_bounty_transparency.py diff --git a/.topics/.schemas/tiinex.bounty-transparency.v1.md b/.topics/.schemas/tiinex.bounty-transparency.v1.md new file mode 100644 index 0000000..4608954 --- /dev/null +++ b/.topics/.schemas/tiinex.bounty-transparency.v1.md @@ -0,0 +1,204 @@ +# Continuity Context + +- Envelope Schema: [tiinex.continuation.v1](tiinex.continuation.v1.md) +- Parent + - Parent Schema: [tiinex.evidence.v1](tiinex.evidence.v1.md) + - Created At: 2026-05-28 22:50:17 + - Trace: [tiinex.evidence.v1.md](tiinex.evidence.v1.md) +- Current + - Current Schema: [tiinex.bounty-transparency.v1](tiinex.bounty-transparency.v1.md) + - Created At: 2026-05-29 17:35:00 + - Summary: Schema for traceable public bounty commitments, submissions, judging decisions, and payout evidence. + +--- + +# tiinex.bounty-transparency.v1 + +- Status: provisional shared schema note +- Schema Definition: [tiinex.schema.v1](tiinex.schema.v1.md) +- Parent Schema: [tiinex.evidence.v1](tiinex.evidence.v1.md) +- Origin: + - [browse](https://www.reddit.com/r/aiagents/comments/1tr0a6j/open_challenge_build_a_traceable_ai_lineage/) + - [browse + git](https://github.com/Tiinex/docs/blob/c147ecd0f3d3b46ce03533a968dcf71f832b9210/.topics/.schemas/tiinex.evidence.v1.md) + +## Summary + +This schema id names evidence-bearing artifacts that track a public bounty from +commitment through submission, evaluation, decision, and payout evidence. + +It inherits from `tiinex.evidence.v1` because a bounty transparency artifact is +not an escrow, payment rail, or financial contract. It is a lineage-friendly +evidence bundle that makes public commitments and later outcomes readable and +verifiable. + +## Required Body Expectations + +Artifacts using `tiinex.bounty-transparency.v1` should contain a readable body +after the continuity envelope. + +The body should include, at minimum: + +- a title identifying the bounty or funding thread +- a `Bounty Commitment` section +- a `Funding Events` section +- a `Submission Events` section +- a `Decision Events` section +- a `Payout Evidence` section +- a `Proof Of Use` section explaining how the artifact was checked or used + +## Required Fields + +The `Bounty Commitment` section should include: + +- `Commitment ID` +- `Sponsor` +- `Amount` +- `Currency` +- `Status` +- `Source URL` + +The `Funding Events` section should include a table or list with: + +- sequence or event id +- event type +- actor +- amount +- currency +- timestamp or date when available +- evidence URL, artifact path, or explicit note that evidence is pending + +The `Submission Events` section should include: + +- submitter or team +- artifact URL or path +- schema or proof type +- submitted status +- evidence URL or path + +The `Decision Events` section should include: + +- decision status, even when the status is `pending` +- judge or decision source when known +- criteria or rationale when available +- evidence URL or path when available + +The `Payout Evidence` section should include: + +- payout status +- amount and currency paid, if any +- recipient or redacted recipient marker +- proof URL, transaction id, receipt, or explicit `pending` note + +## Recommended Fields + +- `Dispute Or Change Events` +- `Reward Splits` +- `Eligibility Notes` +- `Non-Financial Constraints` +- `Interpretation Limits` +- `Validator` + +## Required Semantics + +The artifact should separate four things that are often blurred in bounty +threads: + +- a sponsor's public commitment to pay +- a participant's submitted work +- a judging or acceptance decision +- evidence that funds were actually distributed + +Amounts should not be treated as paid merely because they were promised. + +Pending, reduced, rejected, split, or partly paid outcomes should be recorded as +their own events instead of overwriting the original commitment. + +If a payout recipient, transaction id, or private payment detail cannot be +published safely, the artifact should use `[Redacted]` with a reason when that +reason can be disclosed. + +## What This Schema Is For + +Use this schema when a bounty, grant, challenge, reward, tip, or public funding +thread needs a traceable record of: + +- who promised what +- what evidence grounded the promise +- what work was submitted +- what decision was made +- what payout evidence exists + +## What This Schema Is Not For + +This schema is not: + +- an escrow system +- an investment record +- a securities instrument +- a payment processor +- proof that a sponsor has funds available +- proof that a participant is legally entitled to payment + +It only structures public lineage and evidence. + +## Minimal Example + +```md +# Continuity Context + +- Envelope Schema: tiinex.continuation.v1 +- Parent + - Parent Schema: tiinex.evidence.v1 +- Current + - Current Schema: tiinex.bounty-transparency.v1 + - Created At: 2026-05-29 17:35:00 + - Summary: Traceable record for one public bounty. + +--- + +# Example Bounty Transparency Record + +## Bounty Commitment + +- Commitment ID: example-001 +- Sponsor: Example sponsor +- Amount: 1000 +- Currency: SEK +- Status: open +- Source URL: https://example.test/challenge + +## Funding Events + +| Seq | Type | Actor | Amount | Currency | Evidence | +| --- | --- | --- | ---: | --- | --- | +| 1 | commitment-created | Example sponsor | 1000 | SEK | https://example.test/challenge | + +## Submission Events + +| Seq | Submitter | Artifact | Status | Evidence | +| --- | --- | --- | --- | --- | +| 1 | Example builder | ./proof.md | submitted | ./proof.md | + +## Decision Events + +| Seq | Decision | Actor | Rationale | Evidence | +| --- | --- | --- | --- | --- | +| 1 | pending | Example sponsor | Judging not complete | pending | + +## Payout Evidence + +| Seq | Status | Recipient | Amount | Currency | Evidence | +| --- | --- | --- | ---: | --- | --- | +| 1 | pending | [Redacted: payout not decided] | 0 | SEK | pending | + +## Proof Of Use + +- Validator: `python tools/validate_bounty_transparency.py ./proof.md` +- Result: valid +``` + +## Interpretation Notes + +The schema intentionally keeps the record human-readable first. Validators may +check required fields and event tables, but later human judgment is still needed +to decide whether the evidence is persuasive. diff --git a/.topics/bounty-transparency/001.trace.md b/.topics/bounty-transparency/001.trace.md new file mode 100644 index 0000000..845a913 --- /dev/null +++ b/.topics/bounty-transparency/001.trace.md @@ -0,0 +1,102 @@ +# Continuity Context + +- Envelope Schema: [tiinex.continuation.v1](../.schemas/tiinex.continuation.v1.md) +- Parent + - Parent Schema: [tiinex.evidence.v1](../.schemas/tiinex.evidence.v1.md) + - Created At: 2026-05-28 22:50:17 + - Trace: [tiinex.evidence.v1.md](../.schemas/tiinex.evidence.v1.md) +- Current + - Current Schema: [tiinex.bounty-transparency.v1](../.schemas/tiinex.bounty-transparency.v1.md) + - Created At: 2026-05-29 17:40:00 + - Summary: Proof-of-use record for the public AI lineage schema challenge bounty. + +--- + +# AI Lineage Challenge Bounty Transparency Record + +## Provenance + +- Representation: public challenge summary plus structured bounty lineage. +- Origin: + - [browse](https://www.reddit.com/r/aiagents/comments/1tr0a6j/open_challenge_build_a_traceable_ai_lineage/) + - [browse + git](https://github.com/Tiinex/docs/blob/c147ecd0f3d3b46ce03533a968dcf71f832b9210/.topics/.schemas/tiinex.evidence.v1.md) + +## Bounty Commitment + +- Commitment ID: ai-lineage-schema-challenge-2026-05-29 +- Sponsor: Reddit user TiinuseN1 / Tiinex community challenge +- Amount: 1000 +- Currency: SEK +- Status: open +- Source URL: https://www.reddit.com/r/aiagents/comments/1tr0a6j/open_challenge_build_a_traceable_ai_lineage/ + +## Funding Events + +| Seq | Type | Actor | Amount | Currency | Timestamp | Evidence | +| --- | --- | --- | ---: | --- | --- | --- | +| 1 | commitment-created | TiinuseN1 | 1000 | SEK | 2026-05-29 | Reddit challenge states a 1000 SEK or equivalent bounty | + +## Submission Events + +| Seq | Submitter | Artifact | Schema Or Proof Type | Status | Evidence | +| --- | --- | --- | --- | --- | --- | +| 1 | Jorel97 | `.topics/.schemas/tiinex.bounty-transparency.v1.md` | schema extending `tiinex.evidence.v1` | submitted | this pull request | +| 2 | Jorel97 | `.topics/bounty-transparency/001.trace.md` | proof-of-use trace artifact | submitted | this artifact | +| 3 | Jorel97 | `tools/validate_bounty_transparency.py` | validator proof | submitted | validator output in Proof Of Use | + +## Decision Events + +| Seq | Decision | Actor | Rationale | Evidence | +| --- | --- | --- | --- | --- | +| 1 | pending | TiinuseN1 / challenge participants | Challenge judging has not happened yet | pending | + +## Payout Evidence + +| Seq | Status | Recipient | Amount | Currency | Evidence | +| --- | --- | --- | ---: | --- | --- | +| 1 | pending | [Redacted: payout not decided] | 0 | SEK | pending | + +## Proof Of Use + +This artifact is intentionally self-referential: it uses the new +`tiinex.bounty-transparency.v1` schema to track the same public challenge that +motivated the schema. + +The working proof is a small validator that checks the required schema fields, +the required event sections, and the aggregate committed amount in the funding +event table. + +Run: + +```sh +python tools/validate_bounty_transparency.py .topics/bounty-transparency/001.trace.md +``` + +Expected result: + +```text +OK bounty transparency artifact valid +commitments: 1000 SEK +submissions: 3 +decision: pending +payout: pending +``` + +## Interpretation Limits + +- This record does not prove that funds are escrowed. +- This record does not prove that a participant will be selected. +- This record does not replace the sponsor's final judgment. +- This record only makes the commitment, submission, decision, and payout + evidence lanes explicit and machine-checkable. + +## Why This Is Useful + +The challenge discussion suggested bounty and funding transparency as a useful +candidate lineage schema. This proof turns that idea into a concrete artifact: + +- a public bounty commitment is captured as an event +- submissions are separate from decisions +- payout evidence is separate from the original promise +- pending states stay visible instead of being overwritten +- a validator can detect missing required sections before a trace is reused diff --git a/tools/validate_bounty_transparency.py b/tools/validate_bounty_transparency.py new file mode 100644 index 0000000..a0fdced --- /dev/null +++ b/tools/validate_bounty_transparency.py @@ -0,0 +1,148 @@ +#!/usr/bin/env python3 +"""Validate a tiinex.bounty-transparency.v1 markdown artifact.""" + +from __future__ import annotations + +import re +import sys +from collections import defaultdict +from pathlib import Path + + +REQUIRED_SECTIONS = [ + "## Bounty Commitment", + "## Funding Events", + "## Submission Events", + "## Decision Events", + "## Payout Evidence", + "## Proof Of Use", +] + +REQUIRED_COMMITMENT_FIELDS = [ + "Commitment ID", + "Sponsor", + "Amount", + "Currency", + "Status", + "Source URL", +] + + +def section(text: str, heading: str) -> str: + pattern = re.compile( + r"^" + re.escape(heading) + r"\s*$([\s\S]*?)(?=^## |\Z)", + re.MULTILINE, + ) + match = pattern.search(text) + if not match: + raise ValueError(f"missing section: {heading}") + return match.group(1).strip() + + +def commitment_fields(block: str) -> dict[str, str]: + fields: dict[str, str] = {} + for line in block.splitlines(): + match = re.match(r"^-\s+([^:]+):\s*(.+?)\s*$", line) + if match: + fields[match.group(1).strip()] = match.group(2).strip() + return fields + + +def parse_markdown_table(block: str) -> list[dict[str, str]]: + rows = [line.strip() for line in block.splitlines() if line.strip().startswith("|")] + if len(rows) < 2: + return [] + + headers = [cell.strip() for cell in rows[0].strip("|").split("|")] + parsed = [] + for row in rows[2:]: + values = [cell.strip() for cell in row.strip("|").split("|")] + if len(values) != len(headers): + raise ValueError(f"table row has {len(values)} cells, expected {len(headers)}: {row}") + parsed.append(dict(zip(headers, values))) + return parsed + + +def parse_amount(value: str) -> float: + cleaned = value.replace(",", "").strip() + try: + return float(cleaned) + except ValueError as exc: + raise ValueError(f"invalid amount: {value}") from exc + + +def validate(path: Path) -> tuple[dict[str, float], int, str, str]: + text = path.read_text(encoding="utf-8") + + if "Current Schema: [tiinex.bounty-transparency.v1]" not in text: + raise ValueError("current schema is not tiinex.bounty-transparency.v1") + + for heading in REQUIRED_SECTIONS: + section(text, heading) + + fields = commitment_fields(section(text, "## Bounty Commitment")) + missing = [field for field in REQUIRED_COMMITMENT_FIELDS if field not in fields] + if missing: + raise ValueError(f"missing commitment fields: {', '.join(missing)}") + + declared_amount = parse_amount(fields["Amount"]) + declared_currency = fields["Currency"].upper() + + funding_rows = parse_markdown_table(section(text, "## Funding Events")) + if not funding_rows: + raise ValueError("Funding Events table has no data rows") + + commitments: dict[str, float] = defaultdict(float) + for row in funding_rows: + if not row.get("Type"): + raise ValueError("funding event missing Type") + currency = row.get("Currency", "").upper() + amount = parse_amount(row.get("Amount", "")) + if currency: + commitments[currency] += amount + + if commitments[declared_currency] < declared_amount: + raise ValueError( + f"funding events total {commitments[declared_currency]:g} {declared_currency}, " + f"below declared {declared_amount:g} {declared_currency}" + ) + + submissions = parse_markdown_table(section(text, "## Submission Events")) + if not submissions: + raise ValueError("Submission Events table has no data rows") + + decisions = parse_markdown_table(section(text, "## Decision Events")) + payouts = parse_markdown_table(section(text, "## Payout Evidence")) + if not decisions: + raise ValueError("Decision Events table has no data rows") + if not payouts: + raise ValueError("Payout Evidence table has no data rows") + + decision_status = decisions[-1].get("Decision", "unknown") + payout_status = payouts[-1].get("Status", "unknown") + return dict(commitments), len(submissions), decision_status, payout_status + + +def main(argv: list[str]) -> int: + if len(argv) != 2: + print("usage: validate_bounty_transparency.py PATH", file=sys.stderr) + return 2 + + path = Path(argv[1]) + try: + commitments, submission_count, decision_status, payout_status = validate(path) + except Exception as exc: + print(f"ERROR {exc}", file=sys.stderr) + return 1 + + print("OK bounty transparency artifact valid") + for currency, amount in sorted(commitments.items()): + print(f"commitments: {amount:g} {currency}") + print(f"submissions: {submission_count}") + print(f"decision: {decision_status}") + print(f"payout: {payout_status}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv))