pi-simocracy 0.5.1 → 0.6.1

package/docs/SIM_AUTHORED_PROPOSALS.md

@@ -0,0 +1,198 @@
+# Sim-authored proposals
+
+How pi-simocracy attributes a funding proposal to a sim *without*
+extending the `org.hypercerts.claim.activity` lexicon — and what
+[simocracy-v2](https://github.com/GainForest/simocracy-v2) needs to
+do to render the attribution. Same pattern as
+[sim-authored comments](./SIM_AUTHORED_COMMENTS.md), different
+subject collection.
+
+---
+
+## TL;DR
+
+When pi submits a proposal on behalf of a loaded sim, it writes
+**two** records to the user's PDS:
+
+1. **`org.hypercerts.claim.activity`** — the proposal itself, in the
+   exact shape simocracy.org's `ProposalFormDialog` already writes
+   today (`title`, `shortDescription`, optional `description` /
+   `workScope` / `contributors` / `image`, `createdAt`). Old readers
+   (Hyperindexer, the existing webapp) see this as a regular
+   user-authored proposal — graceful degradation.
+2. **`org.simocracy.history`** — sidecar record with `type:
+   "proposal"`, `subjectUri` pointing at the proposal we just wrote,
+   `simUris[]` / `simNames[]` declaring which sim spoke. New `type`
+   value, but the lexicon's `type` field is free-form string and the
+   indexer already accepts new event types as they appear.
+
+Renderers that understand the join (simocracy.org, when the planned
+change lands) will display a sim badge on the proposal card;
+renderers that don't keep showing it as a regular user proposal.
+**Zero hypercerts lexicon changes. Zero new Simocracy lexicons.**
+
+---
+
+## Why no lexicon change
+
+The `org.hypercerts.*` namespace is owned by the GainForest
+hyperindexer project, not Simocracy — extending
+`org.hypercerts.claim.activity` with a `sim` StrongRef field would
+couple two independent release cycles together for one cross-app
+feature, and the same argument made for comments
+([`SIM_AUTHORED_COMMENTS.md`](./SIM_AUTHORED_COMMENTS.md)) applies
+verbatim here.
+
+The `org.simocracy.history` lexicon already has every field we need:
+
+| Field              | Used for sim-authored proposals                              |
+|--------------------|--------------------------------------------------------------|
+| `type`             | `"proposal"` (new value — appended like other event types)   |
+| `actorDid`         | The human who submitted on the sim's behalf                  |
+| `simNames[]`       | Display name(s) of the sim(s) credited as author             |
+| `simUris[]`        | AT-URI(s) of the sim(s) — the sim-attribution key            |
+| `subjectUri`       | AT-URI of the proposal record this attribution applies to    |
+| `subjectCollection`| `"org.hypercerts.claim.activity"`                            |
+| `subjectName`      | Proposal title (denormalized for the timeline)               |
+| `proposalTitle`    | Same as `subjectName` — kept parallel to comment sidecars    |
+| `content`          | Denormalized description (so the indexer doesn't have to join across PDSs to display the timeline) |
+| `createdAt`        | ISO timestamp                                                |
+
+Use it as-is.
+
+---
+
+## Write path (pi-simocracy)
+
+Implemented by `simocracy_post_proposal` in `src/index.ts`:
+
+```ts
+// 1. The proposal — same shape as ProposalFormDialog writes today.
+const proposal = await createProposal({
+  agent, did,
+  title,
+  shortDescription,
+  description: finalDescription,   // user body + appended budget block, if any
+  workScope,
+  contributors: contributors.map((c) => ({ contributorIdentity: c })),
+  image: { $type: "org.hypercerts.defs#uri", uri: imageUri ?? DEFAULT_BANNER },
+});
+
+// 2. The sim-attribution sidecar — required, since attribution is the whole
+//    point of this tool.
+await createProposalHistory({
+  agent, did,
+  proposalUri:   proposal.uri,
+  proposalTitle: title,
+  simUri:        loadedSim.uri,
+  simName:       loadedSim.name,
+  content:       finalDescription || shortDescription,
+});
+```
+
+Both writes go to the **user's** PDS via their OAuth session — same
+auth path that already powers `simocracy_post_comment` and
+`simocracy_update_sim`. The write is gated on `/sim login` plus sim
+ownership (the sim must live in the signed-in DID's repo) — the
+sidecar uses `assertRepoOwnsSimUri` as defense-in-depth, identical
+to the comment path.
+
+If the sidecar write fails after the proposal succeeds, **the
+proposal is not rolled back** — it just shows up unattributed until
+the user retries. We don't roll back, because rolling back leaves an
+orphaned tombstone in the user's repo that's harder to reason about
+than a missing badge. The tool surfaces a `sidecarWarning` in the
+result so the LLM can decide whether to retry.
+
+### What we deliberately don't do
+
+- **Image upload from disk.** The webapp uploads to `/api/upload-blob`;
+  pi-simocracy has no equivalent and we deliberately stay
+  read-mostly on blobs. The tool accepts an https `imageUri` only,
+  with a default that mirrors the webapp's banner fallback.
+- **Adding the proposal to a floor / collection.** That's a separate
+  `org.hypercerts.claim.collection` write the webapp does via
+  `/api/ftc-sf/add-to-collection`. Out of scope for this tool; a
+  follow-up tool can chain it after the fact.
+- **Editing existing proposals.** Create-only for now.
+
+---
+
+## Read path (proposed simocracy-v2 changes)
+
+Mirrors the comment renderer change in shape, applied to the
+proposal list / detail views.
+
+### 1. Proposal list query — pull history records in parallel
+
+After fetching the proposals for a floor / collection, fetch all
+`org.simocracy.history` records (capped, like notifications does)
+and build a `Map<proposalUri, HistoryRecord>` keyed on `subjectUri`.
+Filter to `type === "proposal"` and `subjectCollection ===
+"org.hypercerts.claim.activity"`. Attach `simUri`, `simName`, and a
+resolved `simAvatarUrl` to each proposal in the response that has a
+match. Sim avatar resolution can reuse `fetchAllSimsWithMeta()` —
+no extra round-trips per proposal.
+
+### 2. Extend the proposal type
+
+```ts
+export interface ProposalRecord {
+  // …existing fields…
+  simUri?: string
+  simName?: string
+  simAvatarUrl?: string
+}
+```
+
+No change to `ProposalFormDialog` — that path stays for human
+authors. Sim-authored proposals come from the CLI today, and a
+future "submit as sim" button in the modal would bundle both writes
+the same way pi-simocracy does.
+
+### 3. Proposal card — sim badge
+
+In the proposal card component, when `proposal.simUri` is set:
+
+- Replace the author avatar with the sim's sprite (32×32 walk-1 frame).
+- Render the byline as `🐾 {simName} · drafted by @{userHandle}` so
+  attribution stays unambiguous (the sim "drafted" it; the human
+  submitted and owns the record).
+- Add a `[sim]` mono-uppercase badge alongside the existing meta
+  pills.
+- Link the sim name to `/sims/{did}/{rkey}` via the existing slug
+  resolver.
+
+Proposals without `simUri` keep rendering exactly as today — no
+regression for human-authored proposals.
+
+---
+
+## Querying sim-authored proposals
+
+For "show me everything my sim has proposed":
+
+```ts
+const histories = await fetchHistory()  // existing helper
+const mySimProposals = histories.filter(h =>
+  h.event.type === "proposal" &&
+  h.event.simUris?.includes(mySimUri)
+)
+```
+
+Each result has `subjectUri` (the proposal URI) and `content`
+(denormalized description). Resolve the proposal URI for the full
+record. Same query shape the notifications system already uses for
+chat / hearing / sprocess events — no new indexer queries needed.
+
+---
+
+## Status
+
+- ✅ Implemented in pi-simocracy `simocracy_post_proposal` (this repo)
+- 🟡 Renderer changes pending in simocracy-v2
+- 🟢 Lexicons unchanged — both repos can ship the change independently
+
+The proposal + history pair is being written today. As soon as
+simocracy-v2 lands the renderer change, every existing pi-authored
+sim proposal retro-actively gets the sim badge — no migration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simocracy",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Pi extension: load a Simocracy sim into your chat — see its pixel-art sprite render inline in the terminal and roleplay with it.",
   "type": "module",
   "author": "David Dao <david@gainforest.earth> (https://github.com/daviddao)",
@@ -32,6 +32,7 @@
   },
   "files": [
     "src/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],