WIP: Typed responses design (ADR-0020 + glossary) #138

Draft

rosa wants to merge 1 commit from docs/typed-responses-adr into main

rosa commented

2026-08-07 21:35:48 +00:00

Owner

Captures the design for typed responses — reply / like / repost / bookmark posts — as docs only. No code yet; this is the decision record to build against.

What's here

docs/adr/0020-typed-responses-are-an-orthogonal-response.md — new ADR.
CONTEXT.md — new Response / ResponseKind / Reply / Like / Repost / Bookmark / ResponseTarget glossary terms, and a reworded Post definition (content is no longer implied mandatory).

Core decisions

A Response value object (ResponseKind + ResponseTarget) is added orthogonally to the Post aggregate — not a flat post-kind enum. Title-presence still discriminates Article/Note; the response kind is a separate axis. This corrects ADR-0001's prediction.
Content becomes optional. New aggregate invariant: content.is_some() || response.is_some() — a plain Article/Note still requires content; a bare Like need not.
At most one Response per Post (multiple targets / mixed kinds rejected, not truncated).
ResponseTarget is any absolute http(s) URL (not the stricter WebmentionTarget); SSRF stays a send-time concern.
All four kinds dispatch a webmention to their target under the existing is_publicly_listed gate; the kind lives only in the rendered mf2 class.
display_title fallback: title → content snippet → "{verb} {target host}".
Micropub-only authoring; the web editor preserves an existing Response untouched.
Invariants enforced in the Post constructor and backstopped by SQLite CHECKs.

Boundaries

Partially supersedes ADR-0007 (only the response-property rejection; the non-public-visibility rejection stays).
Inherits the scheduled-response dispatch gap documented under ADR-0006 — accepted, not worsened.

Marked WIP/draft — opening for review of the design before any implementation lands.

Captures the design for **typed responses** — reply / like / repost / bookmark posts — as docs only. No code yet; this is the decision record to build against. ## What's here - **`docs/adr/0020-typed-responses-are-an-orthogonal-response.md`** — new ADR. - **`CONTEXT.md`** — new `Response` / `ResponseKind` / `Reply` / `Like` / `Repost` / `Bookmark` / `ResponseTarget` glossary terms, and a reworded `Post` definition (content is no longer implied mandatory). ## Core decisions - A **`Response`** value object (`ResponseKind` + `ResponseTarget`) is added **orthogonally** to the `Post` aggregate — *not* a flat post-kind enum. Title-presence still discriminates Article/Note; the response kind is a separate axis. This corrects ADR-0001's prediction. - **Content becomes optional.** New aggregate invariant: `content.is_some() || response.is_some()` — a plain Article/Note still requires content; a bare Like need not. - At most **one Response per Post** (multiple targets / mixed kinds rejected, not truncated). - `ResponseTarget` is any absolute `http(s)` URL (not the stricter `WebmentionTarget`); SSRF stays a send-time concern. - **All four kinds dispatch a webmention** to their target under the existing `is_publicly_listed` gate; the kind lives only in the rendered mf2 class. - `display_title` fallback: title → content snippet → `"{verb} {target host}"`. - Micropub-only authoring; the web editor **preserves** an existing Response untouched. - Invariants enforced in the `Post` constructor **and** backstopped by SQLite `CHECK`s. ## Boundaries - **Partially supersedes ADR-0007** (only the response-property rejection; the non-public-visibility rejection stays). - Inherits the **scheduled-response dispatch gap** documented under ADR-0006 — accepted, not worsened. Marked WIP/draft — opening for review of the design before any implementation lands.

rosa added 1 commit

2026-08-07 21:35:48 +00:00

docs: record the typed-responses design (ADR-0020 + glossary)

ci/woodpecker/push/clippy Pipeline was successful

Details

ci/woodpecker/push/test Pipeline was successful

Details

5ba4a12eeb

Model reply/like/repost/bookmark as an orthogonal Response value object
(ResponseKind + ResponseTarget) on the single Post aggregate, rather than
a flat post-kind enum — correcting ADR-0001's prediction and partially
superseding ADR-0007's response-property rejection.

Adds ADR-0020 and the Response/ResponseKind/Reply/Like/Repost/Bookmark/
ResponseTarget terms to CONTEXT.md. Docs only; no code yet.

ci/woodpecker/push/clippy Pipeline was successful

Details

ci/woodpecker/push/test Pipeline was successful

Details

This pull request has changes conflicting with the target branch.

CONTEXT.md

View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Merge commit title

Merge pull request 'WIP: Typed responses design (ADR-0020 + glossary)' (#138) from docs/typed-responses-adr into main

Merge commit body

Reviewed-on: https://code.cosmicrose.dev/rosa/vernier/pulls/138

Merge pull request 'WIP: Typed responses design (ADR-0020 + glossary)' (#138) from docs/typed-responses-adr into main

Reviewed-on: https://code.cosmicrose.dev/rosa/vernier/pulls/138