Skip to content

docs(legal): amend tenant legal documents & consent versioning spec - #100

Open
patrykbojczuk wants to merge 7 commits into
developfrom
pb/consent-ledger-module
Open

docs(legal): amend tenant legal documents & consent versioning spec#100
patrykbojczuk wants to merge 7 commits into
developfrom
pb/consent-ledger-module

Conversation

@patrykbojczuk

@patrykbojczuk patrykbojczuk commented Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown

Summary

Reframes this spec as an amendment on the merged upstream design
(.ai/specs/2026-08-18-tenant-legal-documents-and-consent-versioning.md, PR open-mercato#5364), which places
legal documents in content, controller identity in directory, and the append-only consent ledger
in auth (with onboarding/checkout consumers, host-based public-page resolution, integrity seals,
and pseudonym-salt GDPR erasure). We keep that placement and infrastructure wholesale and add four
capabilities on top. Spec only; no code.

Changes

  • Rework .ai/specs/2026-08-20-legal-documents-consent-ledger.md into a delta on the base spec, adding:
    • Per-language append-translation content rows in content (a locale can be added to a live
      version without a new version; each row write-once and separately hashed).
    • Cross-document references + closure consent: a legal:<kind>[:<version>][?lang=<code>] token
      incorporates another legal document; accepting the primary records consent for its whole closure
      under one action, in auth.
    • Open consent metadata (unsealed, e.g. { source:'payment', paymentId }, cleared on erasure)
      and an off-session standing-consent check for charges taken with no user present.
    • Any-language input (ISO 639-1) for content locales.
  • Supersede the earlier standalone-legal-module draft (single module, dotted-decimal versions, own
    consent command/tables, client-only deeplink tokens, lighter erasure note) - all replaced by the base
    spec's placement, integer versioning, DI consentLogService, host resolution, and salt erasure.

Specification

Does a spec exist for this feature/module?

  • Yes (this amends the merged 2026-08-18-tenant-legal-documents-and-consent-versioning.md)

Spec file path: .ai/specs/2026-08-20-legal-documents-consent-ledger.md

Testing

Documentation/spec only - no code changed, so no build or tests were run.

Checklist

  • This pull request targets develop.
  • I have read and accept the Open Mercato Contributor License Agreement (see docs/cla.md).
  • I updated documentation, locales, or generators if the change requires it.
  • I added or adjusted tests that cover the change.
  • I added or updated integration tests in .ai/qa/tests/.
  • I created or updated the spec in .ai/specs/ with a changelog entry.
  • Priority set: priority-low.
  • Risk set: risk-low (a design amendment document; no code, schema, or API surface).
  • QA routing set: skip-qa (documentation only).

Design System Compliance

  • N/A - no UI in this change.

Linked issues

None.

@patrykbojczuk
docs(legal): add spec for documents & consent ledger module
bdf6655 
Add the spec for a new upstream `legal` core module: a versioned,
append-only legal-documents ledger plus an append-only consent ledger.
Versions are effective-date-aware dotted-decimal; per-language content
lives in append-only translation rows (a new language is an insert, not
an edit); documents reference each other via stable
legal:<type>[:<version>] tokens resolved client-side. Recording consent
captures the accepted document and its reference closure under one
action id. No backend deeplink config; append-only, audit-logged,
not-undoable commands.
@patrykbojczuk patrykbojczuk added documentation Improvements or additions to documentation risk-low skip-qa QA not required review Ready for code review labels Aug 20, 2026
@patrykbojczuk
docs(legal): specify open consent metadata (e.g. payment id linkage)
a5875e0 
Make the consent `metadata` field explicit: an open, caller-supplied
JSON object stored verbatim on every row of an acceptance, for
provenance and linking a consent to the business event that required it
(notably a payment authorization carrying the payment id). The core
module neither enumerates a closed source set nor interprets metadata.
@patrykbojczuk
docs(legal): add optional pinned display language to reference tokens
f9ce674 
Extend the reference token grammar to legal:<type>[:<version>][?lang=<code>]
so a reference can pin the referenced document's display language (for
"governed by the English version" clauses), overriding the reader's
locale with default-locale fallback. References become
{ type, version?, language? }; <type> now also forbids '?'; a pinned
lang need not exist at publish. Updates discrepancy checks, consent
closure resolution, and tests accordingly.
@patrykbojczuk
docs(legal): add consent pre-check, retention stance, and render/coup…
336f037 
…ling notes

Enrich the spec with generalizable design details:
- assertConsentCurrent / POST /api/legal/consents/verify: validate a
  consent map is complete and effective without recording, so an
  irreversible flow (e.g. a payment) rejects a stale consent up front.
- Data protection & retention: append-only consent is retained under
  right-to-erasure; metadata/placeholder_values are the only free-form
  fields; no encryption map (justified N/A); a future subscriber to the
  platform privacy.subject.erased event can pseudonymize + scrub while
  keeping the evidence skeleton.
- renderedContent substitution semantics (unknown token left literal,
  no re-substitution); effectiveFrom clock-skew grace; and the
  cross-module coupling pattern (record/verify via command bus, react to
  legal.consent.recorded).
@patrykbojczuk
docs(legal): scope consent pre-check to off-session charges
3527f8a 
The on-session gate is the consent recorded when the payment intent is
minted; a separate pre-check there is redundant. Reframe
assertConsentCurrent / POST /api/legal/consents/verify as a standing-consent
check (does the user already hold a current consent for a type + its
active closure) for off-session/recurring charges and re-consent prompts,
where money moves with no user present to consent.
@patrykbojczuk
docs(legal): reframe spec as amendment on landed tenant-legal-documen…
4f32e78 
…ts design

Upstream PR open-mercato#5364 merged a full design that spreads legal documents
(content), controller identity (directory), and the consent ledger
(auth) across existing modules with host-based public-page resolution,
integrity seals, and pseudonym-salt GDPR erasure. Rework our spec as an
amendment on that base: keep its placement and GDPR/host/seal/identity
design wholesale, and add four deltas - per-language append-translation
content rows, legal:<kind>[:<version>][?lang=<code>] reference tokens +
closure consent, open consent metadata + off-session standing-consent
check, and any-language (ISO 639-1) input. Supersede the earlier
standalone-legal-module draft.
@patrykbojczuk patrykbojczuk changed the title docs(legal): spec for documents & consent ledger module docs(legal): amend tenant legal documents & consent versioning spec Aug 28, 2026
@patrykbojczuk
docs(legal): explain why append-translation avoids false re-consent
2dfee9f 
Add the rationale for appending a locale to a live version instead of
cutting a new one: a version bump is the re-consent signal, so a new
version to add a language would force everyone who accepted the prior
version to re-consent to text that is byte-identical in the locale they
actually saw - a false re-consent. Appending a write-once content row
leaves existing rows and the consents that pin them untouched.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation review Ready for code review risk-low skip-qa QA not required

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@patrykbojczuk