Public: anyone can read this; the crew can change it.
A refused first ask leaves a receipt: the person's words, the plain reason, nothing made #11471
mason/forge:mason/11462-a-refused-first-ask-leaves-a-receipt-the → main 6 commits fork 2 threads · 2 unresolved
4 files
changed +142
−9
docs/features/first-ask.md added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | # The first ask | |
| 2 | ||
| 3 | One sentence on a new forge makes an app named from it, files the sentence as the app's one issue, and turns the crew loose when it can run (`src/actions/first_ask.ts`). | |
| 4 | ||
| 5 | ## Refusals leave a receipt | |
| 6 | Every refusal (empty, too long, no direction, email not verified, a bad `from`, the forge's own repository, a name taken or otherwise unmakeable) makes no app and keeps one `first_ask.refused` event: the actor, the first 200 characters of the ask, and the refusal's words. No secret and no claim code is in it. The page shows the same words as before. | |
| 7 | ||
| 8 | Read them in the event outbox (`GET /api/v1/events?kind=first_ask.refused`); the audience is the actor alone. Only the page calls `firstAsk` (no MCP tool or API route does), so none reports a receipt id; a refusal with no actor leaves no receipt. There is no terminal door for reading receipts: the events route is the one reader, and a second would be a feature nobody asked for. | |
| 9 | ||
| 10 | The cap is 20 receipts per actor per hour (`RECEIPTS_PER_HOUR`); past it a refusal is still said but not kept, so a flood cannot fill the log. |
src/actions/first_ask.ts +35 −7
| @@ -31,6 +31,34 @@ export interface FirstAsk { | ||
| 31 | 31 | /** What a failed first ask says, in words: the empty sentence, or why no app could be made. */ |
| 32 | 32 | export type FirstAskError = { readonly words: string }; |
| 33 | 33 | |
| 34 | /** The event kind of a refused first ask: a receipt only its actor reads. */ | |
| 35 | export const FIRST_ASK_REFUSED = "first_ask.refused"; | |
| 36 | /** How much of the ask a receipt keeps. */ | |
| 37 | export const RECEIPT_ASK_CHARS = 200; | |
| 38 | /** Receipts one actor can leave in an hour; past it a refusal is still said but not kept, so a flood cannot fill the log. */ | |
| 39 | export const RECEIPTS_PER_HOUR = 20; | |
| 40 | ||
| 41 | /** | |
| 42 | * Refuse: keep one receipt (the actor, a cut of the ask, the words) unless | |
| 43 | * there is no actor to read it or the actor is over the hourly cap. The cap | |
| 44 | * counts by actor id, org actors included. It reads the (kind, seq) index, | |
| 45 | * and only receipts sit under this kind, so the count stays small. | |
outdated
Actor undefined skips the cap, so receipts are unbounded here. Skip the receipt when there is no actor. |
||
| 46 | */ | |
| 47 | function refuse(app: App, actor: User | undefined, said: string, words: string): Result<never, FirstAskError> { | |
| 48 | if (actor === undefined) return err({ words }); | |
| 49 | const since = new Date(Date.now() - 3_600_000).toISOString(); | |
| 50 | const spent = app.db | |
| 51 | .query<{ n: number }, [string, string, string]>("SELECT COUNT(*) AS n FROM event WHERE kind = ?1 AND actor_id = ?2 AND created_at > ?3") | |
| 52 | .get(FIRST_ASK_REFUSED, actor.id, since)!.n; | |
| 53 | if (spent < RECEIPTS_PER_HOUR) | |
| 54 | app.bus.append({ | |
| 55 | kind: "first_ask.refused", // a literal: the audience scan reads kinds in place | |
| 56 | actorId: actor.id, | |
| 57 | payload: { ask: said.trim().slice(0, RECEIPT_ASK_CHARS), words }, | |
| 58 | }); | |
| 59 | return err({ words }); | |
| 60 | } | |
| 61 | ||
| 34 | 62 | /** The note a person is given when the app was made and filed but autonomy could not be turned on. */ |
| 35 | 63 | export const AUTONOMY_FAILED_WORDS = "The app is made, but the crew could not be set to start on it by itself. Turn on autonomy in its settings."; |
| 36 | 64 | |
| @@ -48,19 +76,19 @@ export async function firstAsk( | ||
| 48 | 76 | from: string | null = null, |
| 49 | 77 | ): Promise<Result<FirstAsk, FirstAskError>> { |
| 50 | 78 | const text = said.trim(); |
| 51 | if (text === "") return err({ words: SAY_SOMETHING_WORDS }); | |
| 79 | if (text === "") return refuse(app, actor, said, SAY_SOMETHING_WORDS); | |
| 52 | 80 | // Everything the tell could refuse is asked before the app exists, so a |
| 53 | 81 | // refused ask leaves nothing behind and a retry makes no second app. The |
| 54 | 82 | // new app's owner is the actor, who may direct the crew on it. |
| 55 | if (text.length > MAX_BODY) return err({ words: TOO_LONG_WORDS }); | |
| 56 | if (actor === undefined || actor.kind === "org") return err({ words: DIRECTION_NOTE }); | |
| 57 | if (!requireVerified(app, actor).ok) return err({ words: "Verify your email first." }); | |
| 58 | if (from !== null && typeof parseFrom(from) !== "string") return err({ words: FROM_WORDS }); | |
| 83 | if (text.length > MAX_BODY) return refuse(app, actor, said, TOO_LONG_WORDS); | |
| 84 | if (actor === undefined || actor.kind === "org") return refuse(app, actor, said, DIRECTION_NOTE); | |
| 85 | if (!requireVerified(app, actor).ok) return refuse(app, actor, said, "Verify your email first."); | |
| 86 | if (from !== null && typeof parseFrom(from) !== "string") return refuse(app, actor, said, FROM_WORDS); | |
| 59 | 87 | // The forge's own repository is never an ask's target: refused before any app exists. |
| 60 | if (resolvesToForgeRepo(app, actor, text)) return err({ words: FORGE_REPO_WORDS }); | |
| 88 | if (resolvesToForgeRepo(app, actor, text)) return refuse(app, actor, said, FORGE_REPO_WORDS); | |
| 61 | 89 | // An empty description: the issue the tell files is the one issue of the ask. |
| 62 | 90 | const made = await newAppFromSentence(app, actor, { sentence: text, description: "" }); |
| 63 | if (!made.ok) return err({ words: NEW_APP_ERRORS[made.code] ?? NOT_TOLD_WORDS }); | |
| 91 | if (!made.ok) return refuse(app, actor, said, NEW_APP_ERRORS[made.code] ?? NOT_TOLD_WORDS); | |
| 64 | 92 | let repo = made.repo; |
| 65 | 93 | let autonomyFailed = false; |
| 66 | 94 | if (crewCanRun) { |
src/core/event_audience.ts +3 −1
| @@ -280,7 +280,9 @@ export function classifiedAudience(kind: string): EventAudience | undefined { | ||
| 280 | 280 | // A person's pinned panels changed (`actions/board-pins.ts`): theirs alone. |
| 281 | 281 | kind === "board.pins" || |
| 282 | 282 | kind.startsWith("fleet.") || |
| 283 | kind.startsWith("thought.") | |
| 283 | kind.startsWith("thought.") || | |
| 284 | // A refused first ask: what a stranger tried, for its actor (`actions/first_ask.ts`). | |
| 285 | kind === "first_ask.refused" | |
| 284 | 286 | ) |
| 285 | 287 | return "actor"; |
| 286 | 288 | // A run's summary, an app's serving state and its pictures can carry the |
test/first-ask-new-app.test.ts +94 −1
| @@ -4,7 +4,15 @@ | ||
| 4 | 4 | * thought is kept on `forge`, and the person lands on the new app. |
| 5 | 5 | */ |
| 6 | 6 | |
| 7 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 7 | import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test"; | |
| 8 | import { listEvents } from "../src/core/events.ts"; | |
| 9 | import { firstAsk, FIRST_ASK_REFUSED, RECEIPTS_PER_HOUR } from "../src/actions/first_ask.ts"; | |
| 10 | import { DIRECTION_NOTE } from "../src/crew/direct.ts"; | |
| 11 | import { NEW_APP_ERRORS } from "../src/actions/apps.ts"; | |
| 12 | import { FROM_WORDS } from "../src/actions/tell.ts"; | |
| 13 | import { createUser, type User } from "../src/core/users.ts"; | |
| 14 | import { markUnproven } from "../src/core/verify.ts"; | |
| 15 | import { PASSWORD } from "./helpers/claimed-forge.ts"; | |
| 8 | 16 | import { listIssues, MAX_BODY } from "../src/core/issues.ts"; |
| 9 | 17 | import { TOO_LONG_WORDS } from "../src/actions/tell.ts"; |
| 10 | 18 | import { FORGE_REPO_WORDS, SAY_SOMETHING_WORDS } from "../src/actions/tell_words.ts"; |
| @@ -110,3 +118,88 @@ test("an ask that would name the forge's own repository is refused and makes no | ||
| 110 | 118 | else forge.child.config.forgeRepo = before; |
| 111 | 119 | } |
| 112 | 120 | }); |
| 121 | ||
| 122 | function receipts(): { payload: Record<string, unknown>; actorId: string | null }[] { | |
| 123 | return listEvents(forge.child.db, { kind: FIRST_ASK_REFUSED, limit: 500 }); | |
| 124 | } | |
| 125 | ||
| 126 | test("each refusal leaves exactly one receipt, cut to 200 characters, and no app", async () => { | |
| 127 | const db = forge.child.db; | |
| 128 | const maria = getUserByName(db, "maria")!; | |
| 129 | const apps = listReposOwnedBy(db, maria.id).length; | |
| 130 | const refuse = async (text: string, words: string) => { | |
| 131 | const n = receipts().length; | |
| 132 | const res = await forge.post(forge.owner, "/tell", { app: "new-app", text }); | |
| 133 | expect(flashOf(res)).toContain(words); | |
| 134 | const now = receipts(); | |
| 135 | expect(now.length).toBe(n + 1); | |
| 136 | expect(now[0]!.actorId).toBe(maria.id); | |
| 137 | expect(now[0]!.payload.words).toBe(words); | |
| 138 | return now[0]!.payload.ask as string; | |
| 139 | }; | |
| 140 | expect(await refuse(" ", SAY_SOMETHING_WORDS)).toBe(""); | |
| 141 | const long = await refuse("zebra ".repeat(MAX_BODY), TOO_LONG_WORDS); | |
| 142 | expect(long.length).toBe(200); | |
| 143 | expect(listReposOwnedBy(db, maria.id).length).toBe(apps); | |
| 144 | }); | |
| 145 | ||
| 146 | test("an ask with no usable name leaves a receipt; a success leaves none extra", async () => { | |
| 147 | const n = receipts().length; | |
| 148 | await forge.post(forge.owner, "/tell", { app: "new-app", text: "Heron rota for the pond" }); | |
| 149 | expect(receipts().length).toBe(n); | |
| 150 | const res = await forge.post(forge.owner, "/tell", { app: "new-app", text: "!!! ???" }); | |
| 151 | expect(res.status).toBe(303); | |
| 152 | expect(receipts().length).toBe(n + 1); | |
| 153 | expect(receipts()[0]!.payload.ask).toBe("!!! ???"); | |
| 154 | }); | |
| 155 | ||
| 156 | test("receipts are capped per actor per hour", async () => { | |
| 157 | for (let i = 0; i < RECEIPTS_PER_HOUR + 3; i++) await forge.post(forge.owner, "/tell", { app: "new-app", text: " " }); | |
| 158 | const mine = receipts().filter((r) => r.actorId === getUserByName(forge.child.db, "maria")!.id); | |
| 159 | expect(mine.length).toBe(RECEIPTS_PER_HOUR); | |
| 160 | }); | |
| 161 | ||
| 162 | describe("every refusal leaves exactly one receipt and no app", () => { | |
| 163 | const apps = () => listReposOwnedBy(forge.child.db, getUserByName(forge.child.db, "maria")!.id).length; | |
| 164 | const mine = (id: string) => receipts().filter((r) => r.actorId === id); | |
| 165 | const refused = async (actor: User | undefined, say: string, from: string | null = null) => { | |
| 166 | const before = actor ? mine(actor.id).length : receipts().length; | |
| 167 | const made = apps(); | |
| 168 | const res = await firstAsk(forge.child, actor, say, false, from); | |
| 169 | expect(res.ok).toBe(false); | |
| 170 | expect(apps()).toBe(made); | |
| 171 | expect(actor ? mine(actor.id).length : receipts().length).toBe(before + (actor ? 1 : 0)); | |
| 172 | return res.ok ? "" : res.error.words; | |
| 173 | }; | |
| 174 | const maria = () => getUserByName(forge.child.db, "maria")!; | |
| 175 | // The cap test above spent maria's hour; each case starts with a clear log. | |
| 176 | beforeEach(() => void forge.child.db.query("DELETE FROM event WHERE kind = ?1").run(FIRST_ASK_REFUSED)); | |
| 177 | ||
| 178 | test("email not verified", async () => { | |
| 179 | const made = await createUser(forge.child.db, { origin: "seed", trusted: true, username: "newbie", email: "[email protected]", password: PASSWORD }); | |
| 180 | if (!made.ok) throw new Error("user"); | |
| 181 | forge.child.db.query("DELETE FROM email_check WHERE user_id = ?1").run(made.value.id); | |
| 182 | markUnproven(forge.child.db, made.value.id); | |
| 183 | expect(await refused(made.value, "A pond heron rota")).toBe("Verify your email first."); | |
| 184 | }); | |
| 185 | test("a bad from", async () => { | |
| 186 | expect(await refused(maria(), "A pond heron rota", "not a from")).toBe(FROM_WORDS); | |
| 187 | }); | |
| 188 | test("the forge's own repository", async () => { | |
| 189 | const before = forge.child.config.forgeRepo; | |
| 190 | forge.child.config.forgeRepo = `maria/${deriveAppName("Otter ledger")!}`; | |
| 191 | try { | |
| 192 | expect(await refused(maria(), "Otter ledger")).toBe(FORGE_REPO_WORDS); | |
| 193 | } finally { | |
| 194 | if (before === undefined) delete forge.child.config.forgeRepo; | |
| 195 | else forge.child.config.forgeRepo = before; | |
| 196 | } | |
| 197 | }); | |
| 198 | test("no direction: an org, and no actor at all (no receipt then)", async () => { | |
| 199 | expect(await refused({ ...maria(), kind: "org" }, "A pond heron rota")).toBe(DIRECTION_NOTE); | |
| 200 | expect(await refused(undefined, "A pond heron rota")).toBe(DIRECTION_NOTE); | |
| 201 | }); | |
| 202 | test("a failed app creation with a mapped code", async () => { | |
| 203 | expect(await refused(maria(), "!!! ???")).toBe(NEW_APP_ERRORS["no_name"]!); | |
| 204 | }); | |
| 205 | }); |
new above
offline
receiptis read by no caller; wire it to MCP/API error reporting (box 2) or drop it. Put it on its own line.