Community Wall — HiveJournal Surface Spec

Status: PROPOSED — for owner review (drafted 2026-07-19). This resolves the five open questions the cross-product contract left to "the HJ owner to decide." Nothing here is built. It is the concrete surface proposal PorchHearth is waiting on before it finalizes GET /api/v1/public/needs and confirms its owner's nod.

Contract (single source of truth): ../../../crosstalk/contracts/community-wall.md (mesh split, the 10 binding bright lines, post/feed types). This doc LINKS that contract; it does not restate or fork it. Read the contract first.
Owner: HiveJournal (the surface + the consent/safety boundary — non-delegable). Engine: PorchHearth (meals / give-aways / needs primitives).
Gate: build authorized on neither side until (a) this surface is owner-approved and (b) counsel clears the neighbor-safety model. This doc is (a)'s input.

1. What the surface IS — a new authenticated `/community` area

Recommendation: a distinct, authenticated /community route inside the HiveJournal app — its own left-nav/tab entry, gated behind sign-in + verified neighbor membership (§2). Not a page anyone can reach logged-out; not indexable.

Explicitly rejected alternatives (and why):

❌ A block/feed on the Family Wall. Bright line #2. The Family Wall is single-household, token-authed, family-private, and runs unattended where kids tap it. Neighbor-to-neighbor commerce there is a category error. The Community Wall never ships as a family-display block. (See [FAMILY_WALL] docs for the contrast.)
❌ A wall "device profile" (community mode) as the v1 shape. Tempting to reuse the wall device-identity work, but a shared/ambient screen is the worst first place to put a surface whose entire risk model is identity + location disclosure between strangers. A personal, authenticated, per-user app area is the correct v1. A curated read-only "community mode" wall screen (meals this week, nothing tappable-to-transact) is a plausible later phase, not v1.

Why a route, not a separate app: it reuses HJ auth, the existing nav shell, report/block plumbing we already have elsewhere, and the server-proxy pattern (§4). Lowest new surface area for the highest safety control.

Route sketch

/community                      → the wall: meals + give-aways + needs, scoped to your area
/community/onboarding           → verify you're a real local neighbor (§2)
/community/post/new             → create a give-away / need (Phase 1+, adult-gated)
/community/thread/[id]          → in-app relay thread for a claim/handoff (Phase 2, counsel-gated)
/community/settings             → coarse area, radius, mute, leave

All under an auth + membership guard. robots: noindex on every route.

2. Membership / verification — "verified neighbor" without over-collecting PII

Goal: establish real, local, adult membership while staying inside bright lines 1/3/5/10 (no public address, minors never a counterparty, coarse-only public, real neighbors only). Tiered, least-PII-first:

Tier	How you join	What we store	What it unlocks
T0 — Browse	Signed-in HJ user, self-set coarse area (city/ZIP centroid, never exact)	City-centroid lat/lng only (privacy floor — matches the Citizen Scientist map rule: city-centroid, never exact)	Read the area feed (meals via engine reads)
T1 — Verified neighbor	One of: (a) link a PorchHearth account, (b) invite from an existing T1 neighbor, (c) coarse address verify (postcard code / geo-proximity check)	Verification method + timestamp; still no exact address on any public record	Post give-aways/needs, claim, in-app relay
T2 — Trusted	T1 + N completed handoffs, no reports	Trust counter	Meet-safe defaults relaxed slightly (still opt-in)

Adult gate (bright line #3): T1 requires an adult account. Households with child accounts: the child never sees/uses /community; neighbor-pickup flows are adult-only. Anything child-reachable stays counsel-gated (photo-frame precedent).
Address (bright lines 1/5/6/9): exact address is never stored on a post or public record. It surfaces just-in-time to the two counterparties only, on a mutual accept, and is dropped/expired after the handoff completes.
Least-PII default: prefer PorchHearth-account-link or neighbor-invite over address verification; only fall to postcard/geo verify if a member wants T1 without a PorchHearth account.

3. Geography scoping — coarse centroid + radius

Public/feed view: coarse only — city/neighborhood centroid + a display handle, matching PorchHearth's engine floor (approx location, ~1.1km obfuscation, exact address withheld until a confirmed transaction).
Membership scope: a member sees posts within a radius of their coarse home centroid. Default proposal: 5 mi, member-adjustable 1–15 mi in /community/settings. Radius (not polygon) for v1 — a neighborhood-polygon model is a later refinement.
Read call carries the coarse geo, never exact: we pass the centroid + radius to the engine (geo=<lat,lng>&radius_mi=), never a precise home point.

4. Embed mechanism — server-proxied JSON reads (About-That posture)

Confirmed with PorchHearth: server-proxied JSON HTTP reads, HJ holds none of the engine's logic and never forks listings/needs.

Reads (HJ server → PorchHearth public façade; render in HJ UI):

GET <porchhearth-base>/api/v1/public/listings?geo=<lat,lng>&radius_mi=<n>   # meals — LIVE (post-type #1)
GET <porchhearth-base>/api/v1/public/needs?geo=<lat,lng>&radius_mi=<n>      # give-aways + mutual-aid — PorchHearth to BUILD against this spec

Both return coarse location only, per-IP throttled, no PII. HJ proxies server-side (never browser-direct) so we can attach membership scoping + caching and keep the engine base URL a single config value.

Writes (Phase 2, counsel-gated) — proxy-authed, HJ server → engine only:

POST <porchhearth-base>/api/v1/public/<claim|order>
Headers: X-QS-Proxy-Secret: <shared secret>  ·  X-<site/surface>-Ref: <ref>

Same proxy-authed posture as the meals/stay order/booking paths (neighborhood-meals-embed.md, neighborhood-stay-embed.md) and the partner-provisioning.md trust model where money/PII is involved. A neighbor claiming a give-away / offering to fill a need rides this path — never a browser-direct write, never before counsel clears.

5. Counsel gate — what must clear before any neighbor-facing launch

Read-only browsing (T0/T1 reading the meals + needs feeds) can be built and smoke-tested behind the membership guard. Neighbor-facing WRITES and any real-world handoff stay dark until counsel signs off on:

Stranger real-world handoffs (porch pickups, meeting strangers) — bright line #4/#7.
Progressive identity/location disclosure + in-app relay — bright lines #1/#5/#6.
Minors-in-household exposure — bright line #3.
Report/block + a trust signal shipping at launch, not as v2 — bright line #8.

6. Proposed phasing

Phase	Scope	Gate
0 — Read-only meals	`/community` + membership T0/T1; render the LIVE `/public/listings` meals feed, coarse. No writes.	Owner-approve this spec
1 — Needs + give-aways (read)	Add the `/public/needs` feed once PorchHearth ships it; posting give-aways/needs is HJ-native compose → engine write (still Phase-2-gated to publish)	PorchHearth owner nod + endpoint live
2 — Claims / handoffs (write)	In-app relay threads, mutual accept, just-in-time location, report/block, meet-safe defaults	Counsel clearance
later	Read-only curated "community mode" wall screen (non-transactional)	separate review

7. Data model (HJ side, sketch — not final)

Everything below lives HJ-side; the engine owns listings/needs/orders. New tables (migration numbers TBD at build):

community_members — user_id, coarse_lat, coarse_lng (centroid only), radius_mi, tier, verification_method, verified_at, is_adult.
community_reports / community_blocks — report/block plumbing (launch req).
Handoff/relay threads (Phase 2) reference engine order/claim IDs; no exact address column ever persists past handoff completion (bright line #9).

Reuse the city-centroid privacy helper from the Citizen Scientist map (never store exact lat/lng). Reuse existing report/block patterns where they exist.

8. Open decisions for the owner (sign-off needed)

Surface shape — confirm /community authenticated route (§1) vs. any preference for a different container.
Default radius — 5 mi proposed (§3); adjust?
T1 verification — which methods to offer at launch (PorchHearth-link / invite / address-verify), and whether address-verify is in v1 at all.
Phase-0 go — is read-only meals-feed build authorized once this is approved, or hold the entire surface until counsel clears writes too?

On owner sign-off, I send the finalized surface shape to PorchHearth so it builds /public/needs against §4, and (if Phase-0 is authorized) begin the read-only /community build HJ-side. No write path until counsel clears (§5).