docs(#1750): document result format and result_helper functions

[fullsend-ai-coder]

Add a "Result format" section to the policy authoring guide that documents the result object schema expected by the Conforma evaluation engine, including all fields (code, msg, effective_on, collections, term, severity) with their types and descriptions.

Document the result_helper, result_helper_with_term, and result_helper_with_severity functions from data.lib.metadata with parameter descriptions and usage guidance. Add a table mapping annotations to result fields, and a complete example showing a policy rule with result_helper.

Update the "safer version" code example in the Pitfalls section to use result_helper instead of raw {"msg": "..."} objects, demonstrating the recommended pattern with proper METADATA annotations.

---

Closes #1750

Post-script verification

• Branch is not main/master (agent/1750-doc-result-format)
• Secret scan passed (gitleaks — 71f6e6cf3f4e90d51f66207404e70034b501b3f7..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:30 AM UTC · Completed 10:43 AM UTC
Commit: 47d3320 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
unit-tests	100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[fullsend-ai-review]

Review

Findings

Low

• [technical accuracy] antora/docs/modules/ROOT/pages/authoring.adoc:102 — The Result helpers section links to policy-reference#metadata on the OPA website, but the documentation for rego.metadata.chain() lives under policy-language#metadata. The existing links in this same file (for other OPA metadata references) already use the policy-language path. Using policy-reference#metadata may land on a different section or produce a 404.
  Remediation: Change the URL from https://www.openpolicyagent.org/docs/policy-reference#metadata to https://www.openpolicyagent.org/docs/policy-language#metadata.

Info

• [edge case correctness] antora/docs/modules/ROOT/pages/authoring.adoc:73 — The effective_on field documentation states it defaults to "2022-01-01T00:00:00Z". This is accurate per the implementation in policy/lib/time/time.rego. The default is applied by the time_lib.when() function when no annotation provides an effective_on value — a minor nuance that does not constitute a functional inaccuracy for authors.

• [internal consistency] antora/docs/modules/ROOT/pages/authoring.adoc:96 — The Result object fields table describes code as formatted <package_path>.<short_name>, while the annotation mapping table says <package>.<short_name>. Both are accurate but use slightly different terminology. Cosmetic and unlikely to cause confusion.

• [Cross-reference formatting] antora/docs/modules/ROOT/pages/authoring.adoc — The new content uses <<Result helpers>> syntax for same-page cross-references. This is valid standard AsciiDoc for intra-page anchors and works in Antora. Existing xref: references in the repo are all cross-document, so there is no established contrary convention.

[fullsend-ai-review]

[low] technical accuracy

The Result helpers section links to policy-reference#metadata on the OPA website, but the documentation for rego.metadata.chain() lives under policy-language#metadata. The existing links in this same file already use the policy-language path. Using policy-reference#metadata may land on a different section or produce a 404.

Suggested fix: Change the URL from https://www.openpolicyagent.org/docs/policy-reference#metadata to https://www.openpolicyagent.org/docs/policy-language#metadata.