simocracy-v2 · proposal-context-sidecar

Proposal-context sidecar — Phases 1–5 ship & smoke test

@daviddao

Replaces Simocracy's load-bearing #gathering-{rkey} hashtag-in-shortDescription convention with a structured org.simocracy.proposalContext sidecar lexicon. End-to-end verified live as satyam2.climateai.org on simocracy.org — including a sidecar-only proposal that resolves to its parent gathering with no hashtag fallback.

Date: 2026-05-06 · Tester: satyam2.climateai.org · Status: pass · Phases: 1–5 complete

---

Headline result

What landed

Phase	Commit	Files	Description
1	1921dd3	3	Lexicon JSON + indexer copy + types/COLLECTIONS + lib/proposal-context.ts resolver with trust gate
doc	76ecf43	1	plans/PLAN_proposal_context.md — full Phase 1–5 rollout plan
2	f6dd334	6	Form-write hooks (gathering & FtC SF) + /api/proposal-context endpoint + fetchActivityCidByUri
3	cce8a86	4	Dual-read sidecar swap in /proposals, /stats, and proposals-feed.tsx (sidecar-first, hashtag fallback)
4 (script)	87062ed	2	Idempotent backfill script scripts/backfill-proposal-context.ts
4 (run)	n/a	n/a	Backfill executed. Wrote 17 sidecars to facilitator's PDS — dry-run + real run, scanned=883, errors=0, idempotent.
5	5a2f513	5	Sidecar-driven Hyperindexer fetchers: fetchAllSimocracyProposalContexts(), fetchActivitiesByUris(), pivoted fetchSimocracyProposals + fetchProposalsByFloorTag + new fetchProposalsForGathering(uri); filterLegalProposalsForOverview takes contextKeyByUri
5	cdd7e4c	14	Drop hashtag write in both forms; drop hashtag-fallback in resolver; remove every stripContextTag regex usage and inline .replace(/#…/); D4 telemetry warning; lexicons.md + app/skill.md/route.ts updated

Phase 5 originally deferred ~2 weeks behind dual-read; ran the same day after a clean Phase-1–4 verification justified pulling it forward.

Walkthrough — live as satyam2.climateai.org

Tested on the Vercel production deploy (simocracy-v2-jorfn0t1a.vercel.app, aliased to simocracy.org) — same code path real users hit.

The form-driven path didn't land — pivoted to a script

To get an end-to-end signal in this run, I bypassed the form and wrote the three records (gathering, activity, sidecar) directly to satyam2's PDS via @atproto/api + app-password auth. Same lexicon, same indexer, same resolver, same display path — just skipping the form's fetch('/api/records') + fetch('/api/proposal-context') hops.

$ node /tmp/smoke-test/smoke.mjs
[smoke] login satyam2.climateai.org via https://climateai.org
[smoke] logged in: did:plc:cpoagodpqrgs4t7thi5z37uf
[smoke] gathering created: at://did:plc:.../org.simocracy.gathering/3ml5kam5hm62a
[smoke] activity created:  at://did:plc:.../org.hypercerts.claim.activity/3ml5kamgqi62a
[smoke] sidecar created:   at://did:plc:.../org.simocracy.proposalContext/3ml5kamp7xo2a

[verify] re-fetching each record from satyam2 PDS:
  gathering: ✅ at://did:plc:.../org.simocracy.gathering/3ml5kam5hm62a
  activity:  ✅ at://did:plc:.../org.hypercerts.claim.activity/3ml5kamgqi62a
  sidecar:   ✅ at://did:plc:.../org.simocracy.proposalContext/3ml5kamp7xo2a

Result on /proposals — both the dual-write and sidecar-only proposals resolve their parent gathering

Records-on-disk verification

Each record was confirmed with a follow-up com.atproto.repo.getRecord against satyam2's self-hosted PDS, then a GraphQL query against the Simocracy indexer. Identifying fields below.

Gathering — org.simocracy.gathering

Dual-write activity — org.hypercerts.claim.activity

Sidecar — org.simocracy.proposalContext

Indexer GraphQL response (verbatim, abridged):

{
  "$type": "org.simocracy.proposalContext",
  "subject": {
    "uri": "at://.../org.hypercerts.claim.activity/3ml5kamgqi62a",
    "cid": "bafyreicef4wagd4rqb5pfjx3bc3cmyf5by5ngxfcowvu2zfyn7ph5amdbi"
  },
  "context": {
    "$type": "org.simocracy.proposalContext#gatheringContext",
    "gathering": {
      "uri": "at://.../org.simocracy.gathering/3ml5kam5hm62a",
      "cid": "bafyreifcpednc6cmhyiqiez6vfpu342erbyobsjfmygiiyjuznb442wram"
    }
  },
  "createdAt": "2026-05-06T01:26:21.917Z"
}

Sidecar-only activity — proves the resolver is sidecar-first, not just dual-read

Findings

Reproducing

Indexer GOTCHA — variable must be named collection

The Simocracy indexer's compat GraphQL layer requires the variable to be literally named $collection, not $c or anything else. Burned 5 minutes on this during the run; it's already documented at simocracy.org/skill.md, worth re-flagging here.

# Wrong — returns total=0 silently:
{"query":"query Q($c: String!) { records(collection: $c, ...) { ... } }",
 "variables":{"c":"org.simocracy.proposalContext"}}

# Right:
{"query":"query Q($collection: String!) { records(collection: $collection, ...) { ... } }",
 "variables":{"collection":"org.simocracy.proposalContext"}}

---

Phase 4 — backfill executed

Ran npx tsx --env-file=.env.local scripts/backfill-proposal-context.ts --dry-run first to inspect intent, then dropped the --dry-run flag. Both passes converged on the same numbers — the script is idempotent.

summary scanned=883 skipped-no-tag=865 skipped-already-present=0 \
        skipped-resolve-fail=1 written=17 errors=0 dryRun=false

17 sidecars written to the facilitator's PDS (did:plc:awtx57rxuisy4sf4kzzr3uhf) — 8 binding to gatherings, 9 to FtC SF floors. The 1 resolve-fail was an orphan tag pointing at a deleted gathering (expected; no action). After triggering a per-DID indexer backfill on the facilitator's repo, the simocracy indexer reported 19 sidecars total (17 facilitator + 2 satyam2 from the earlier smoke writes). All addressable Simocracy proposals now have a structured back-pointer to their parent.

Phase 5 — sidecar-only ship

Originally a ~2-week soak. Pulled forward the same day because Phase 1–4 verification was clean and dual-read had no observable issues during the soak window. The shape of Phase 5 changed mid-flight when the agent surveyed the codebase and surfaced that the legacy #gathering-{rkey} / #ftc-sf-fN hashtag wasn't only display — it's a server-side Hyperindexer filter for four read paths (the cross-gathering proposals feed, the FtC SF floor sidebar, each gathering's proposals tab, and the per-gathering S-Process applicants modal). Dropping the hashtag write without first migrating these queries would have made every new proposal invisible.

Architectural pivot — sidecar-driven seed

The four fetchers were rewritten to source their seed set from org.simocracy.proposalContext sidecars on the simocracy indexer, then point-fetch each activity record from Hyperindexer via orgHypercertsClaimActivityByUri(uri). Hyperindexer's OrgHypercertsClaimActivityWhereInput doesn't expose a uri.in batch operator (probed at __schema; only single-URI lookups work), so the per-page-load implementation parallelises N point lookups with Promise.all — with N ≈ 19 today and capped at the existing 100/200-record paginations, this is well within budget.

Live regression check on production

Vercel auto-deployed both commits within 3 minutes of push. Verified live as satyam2.climateai.org on https://simocracy.org across four pages.

Findings (post-Phase-5)

Final state

Next steps

1. Update simocracy-indexer/docker-compose.yml to include org.simocracy.proposalContext in TAP_COLLECTION_FILTERS, matching the production env var. Local-dev parity, no infra change.
2. Adversarial test of the trust gate — write a sidecar from a third-party DID claiming someone else's proposal, verify it's silently dropped by resolveProposalContexts. Code review confirms the gate; empirical verification is still pending.
3. Investigate the agent-browser create-event dismiss as a separate UX issue. Doesn't affect human users; blocked smoke-testing the form path on prod during this run, addressed via script-driven writes instead.
4. Optional cosmetic cleanup of legacy hashtag text in old proposals' shortDescription — see Findings. Not blocking.
5. Watch Hyperindexer load if Simocracy proposal volume grows past a few hundred. Today's parallel-N point fetches are fine; at scale, a batch-URI input would help.