Experiment with structured legal documents

[samlown]

This draft explores how GOBL could represent and sign legal contracts without attempting to turn all legal prose into a rigid ontology.

• modernize the experimental legal package around registered normalizers and declarative rules
• add stable agreement/version identity, parties, recitals, definitions, effect, governing law, disputes, execution requirements, related documents, and digest-bound resources
• model assent as a separately signed document targeting an exact contract digest
• model human, rules-engine, or LLM analysis as replaceable non-authoritative annotations
• permit open party roles in published standard terms, bound to a concrete entity by later assent
• add generated schemas and rule documentation
• add linked examples for the Invopop Terms and a fictional negotiated SaaS agreement with payments, an SLA, service credits, support targets, liability, renewal, and counterpart execution

The approach deliberately keeps authoritative prose in the contract while using stable anchors and a separate analysis artifact for machine-extracted obligations and operational values. Lifecycle states such as signed or effective are intended to be derived from immutable contracts, assents, and external events rather than stored as mutable contract flags.

Relevant prior art considered includes OASIS LegalXML eContracts, Akoma Ntoso, LegalRuleML, ODRL, Accord Project, and CommonAccord. The Invopop fixture is an abridged, non-authoritative paraphrase of https://www.invopop.com/legal-documents#terms-and-conditions.

Pre-Review Checklist

• Opened this PR as a draft
• Read the CONTRIBUTING.md guide.
• Performed a self-review of my code.
• Added tests for normalization, validation, cross-references, assent, and analysis.
• Modified or created example GOBL documents to show the changes in use.
• Regenerated schemas, rule data, and example envelopes.
• Ran the complete Go test suite.
• Reviewed and fixed all linter warnings.
• Updated the CHANGELOG.md with an overview of the changes.
• Marked this PR as ready for review.

Verification

• mage lint
• go test ./...
• go test . -run TestConvertExamplesToJSON -update

[codecov]

Codecov Report

❌ Patch coverage is 92.57028% with 37 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.93%. Comparing base (8652979) to head (4e54b39).

Files with missing lines	Patch %	Lines
legal/rules.go	90.22%	22 Missing and 13 partials ⚠️
legal/norm.go	97.77%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #930      +/-   ##
==========================================
- Coverage   94.99%   94.93%   -0.07%     
==========================================
  Files         327      333       +6     
  Lines       17732    18230     +498     
==========================================
+ Hits        16845    17306     +461     
- Misses        547      570      +23     
- Partials      340      354      +14     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.