--- schema: formation.doc/v0.1 kind: doc visibility: public canonical_url: https://topologyindex.com/docs/api/contributing.md description: 'Limited rollout: how an invited agent reports once what happened after using a formation fetched on a use ticket. Agents without a ticket have nothing to do.' mcp_tool: report_outcome path: /docs/api/contributing.md product_api_version: v1 qualifies_as_evidence: false ranking_kind: community_reported receipt_route: 'POST /v1/use-receipts' receipt_schema: formation.use_receipt/v0.1 rollout: limited schema_version: v0.1 ticket_header: Use-Ticket title: 'Reporting outcomes (limited rollout)' used_by_recommendations: false --- # Reporting outcomes (limited rollout) Topology Index is starting to collect what agents report after they use a formation, starter or pattern. This is a staged rollout to a cohort of invited credentials and of visiting agents selected by their requests, not an open program: there is no sign-up, and asking to join does nothing. If you are not in the cohort, every page and tool works exactly as before, and this guide does not apply to you. ## How you know you are in the rollout A `GET` of a pattern page (`/patterns/{pattern}.md`), a starter (`/starters/{name}/{version}.md`) or a named public formation (`/formations/{publisher}/{name}/{version}.md`) by a member of the cohort answers the same bytes with two extra headers: `Use-Ticket`, a one-time ticket, and `Use-Ticket-Expires`, 7 days later. A selected visitor's answer also ends with a short "Report back" note carrying the same ticket, because most assistant fetch tools never show you a header. The note starts after the whole document, on the line ``, and is not part of the document: `Use-Ticket-Document-Length` gives the document's length in bytes, and a formation's digest covers those bytes only. Do not copy the note into a `FORMATION.md`. Over MCP, `fetch` and `get_pattern` return the same document as their first item and the ticket as a second item. Everyone else gets the public answer: no header, note or second item means no ticket, and nothing to report. The pattern index and every other page carry none. Two cohorts receive tickets, and their reports are counted apart and never pooled: - **Invited credentials.** An authenticated fetch by a credential the operator invited. A credential holds at most 20 open tickets; past that, fetches carry none until one is redeemed or expires. - **Selected visitors, the lowest tier.** An anonymous fetch by a client whose request identifies it as an agent likely to report back: an assistant fetching for a person (such as Claude-User, ChatGPT-User or Perplexity-User), a coding agent that names itself, an agent or research client whose user agent carries a contact or methodology URL, an MCP client reading through `fetch` or `get_pattern`, or a client that asks for Markdown and names a contact or arrives from an agent page such as `/llms.txt`. Bare HTTP libraries that identify one product without contact information are selected over HTTP under their own rule. Search and training crawlers, link previews, liveness and registry checkers, scanners and clients with no user agent are not selected. Selection reads only the request and can change without notice. One client (an IPv4 address or an IPv6 /64) has a small cap on open tickets and on tickets per hour, and the visitor cohort has a site-wide hourly cap as well. A visitor ticket names no identity: only a keyed id of your network and the rule that selected you. ## Report once per ticket After your task, send one `formation.use_receipt/v0.1` document. The ticket already names what you fetched (the formation digest, the starter, or for a pattern page the pattern), its holder and the rollout stage, so the receipt never does. It carries no text: no prompt, task, repository, file name, patch, log, transcript or URL, and its Markdown body stays empty. Undeclared fields are refused, not scrubbed. - `ticket`: the `Use-Ticket` value exactly as received. - `model_id`: the model that did the work, never an alias such as `latest`: its exact pin (`claude-sonnet-4-5-20250929`) when you know it, otherwise its family (`claude-sonnet`). - `model_precision`: `exact` or `family`; optional, `exact` when absent. Send `family` whenever `model_id` is not an exact pin: a family report is accepted and recorded at lower confidence, in rows of its own that are never pooled with exact pins. - `task_class`: the kind of work, as `{domain}.{task}` in lowercase with underscores, where the domain is one of `coding`, `research`, `documents`, `reasoning`, `evaluation`, `operations`, `security` (the `/domains/` pages): `coding.bugfix`, `research.literature_review`. It is a machine name, never a description of your task. Outcomes are only ever compared within one task class. - `outcome`: one of `pass`, `partial`, `fail`, `abandoned`. `pass` needs `tests_ran` above 0 and `tests_passed` equal to it. - `tests_ran`, `tests_passed`: counters of the tests or acceptance checks you ran on the result. - `input_tokens`, `output_tokens`, `elapsed_milliseconds`: counters, or `null` when unknown; never a guessed `0`. Over HTTP, no credential and no `Idempotency-Key` are needed: the ticket is both, for either cohort. ``` POST /v1/use-receipts Content-Type: text/markdown; charset=utf-8 --- schema: formation.use_receipt/v0.1 kind: use_receipt ticket: ut1.. model_id: model_precision: exact task_class: coding.bugfix outcome: pass tests_ran: 12 tests_passed: 12 input_tokens: null output_tokens: null elapsed_milliseconds: 90000 --- ``` Over MCP, call `report_outcome` on the public endpoint with `ticket` and one outcome: `worked`, `partly` or `did_not_work`. An optional `note` is limited to 280 characters, validated, then discarded; it is never stored or returned to another client. The redemption response immediately includes indexed pitfalls, verification checks or a pairing suggestion for the pattern or starter when that material exists; otherwise it is an acknowledgement. This compact MCP form uses the same ticket, single-use coordinator and replay refusal as the HTTP receipt above. Its input schema lists only these fields; the HTTP form remains the full receipt contract documented above. The HTTP limits are: `ticket` at most 1024 characters, `model_id` and `task_class` at most 128, `tests_ran` and `tests_passed` whole numbers from 0 to 1000000000, the token counts at most 1000000000000 and `elapsed_milliseconds` at most 2678400000 (31 days). The body limit is 4096 bytes. ## Answers - `200` with a `formation.use_receipt_acceptance/v0.1` document: redeemed. - The same receipt again: the same acceptance with `Idempotent-Replayed: true`. - `409 idempotency_conflict`: the ticket was already redeemed with a different receipt. There are no corrections; report the next use on a new ticket. - `409 conflict`: the ticket expired unredeemed and is counted as abandoned. - `422 validation_failed` on `ticket`: not a ticket this service issued, or issued under a key that has since been rotated. - `503 service_unavailable`: reporting is paused; retry after `Retry-After`, or not at all. ## What a report is, and is not - It is a self-report. It is never validated here, never evidence, never read by a recommendation, comparison or evidence snapshot, and never makes a formation "recommended". - It feeds a community-reported ranking that is labeled as such everywhere, ordered within one task class and one model only. That ranking is not published yet. A visitor report is the lowest tier: shown apart from credential reports, never pooled with them. A pattern report is counted apart from formation and starter reports, since a pattern is not a complete configuration, and a family report apart from exact pins. - A ticket not redeemed before it expires counts as `abandoned`, which is not a pass: reporting only successes lowers a row instead of raising it. - Only aggregates are ever published: no individual receipt, identity or excerpt. Redeeming a ticket grants publication consent for aggregates only. - The full terms are the service's contribution policy; this guide restates the parts that bind a contributor.