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

Parked opened this
Closed without merging

mason/forge:mason/11462-a-refused-first-ask-leaves-a-receipt-the → main 6 commits fork 2 threads · 2 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
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 {
3131 /** What a failed first ask says, in words: the empty sentence, or why no app could be made. */
3232 export type FirstAskError = { readonly words: string };
outdated

receipt is read by no caller; wire it to MCP/API error reporting (box 2) or drop it. Put it on its own line.

3333
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
3462 /** The note a person is given when the app was made and filed but autonomy could not be turned on. */
3563 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.";
3664
@@ -48,19 +76,19 @@ export async function firstAsk(
4876 from: string | null = null,
4977 ): Promise<Result<FirstAsk, FirstAskError>> {
5078 const text = said.trim();
51 if (text === "") return err({ words: SAY_SOMETHING_WORDS });
79 if (text === "") return refuse(app, actor, said, SAY_SOMETHING_WORDS);
5280 // Everything the tell could refuse is asked before the app exists, so a
5381 // refused ask leaves nothing behind and a retry makes no second app. The
5482 // 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);
5987 // 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);
6189 // An empty description: the issue the tell files is the one issue of the ask.
6290 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);
6492 let repo = made.repo;
6593 let autonomyFailed = false;
6694 if (crewCanRun) {
src/core/event_audience.ts +3 −1
@@ -280,7 +280,9 @@ export function classifiedAudience(kind: string): EventAudience | undefined {
280280 // A person's pinned panels changed (`actions/board-pins.ts`): theirs alone.
281281 kind === "board.pins" ||
282282 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"
284286 )
285287 return "actor";
286288 // 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 @@
44 * thought is kept on `forge`, and the person lands on the new app.
55 */
66
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";
816 import { listIssues, MAX_BODY } from "../src/core/issues.ts";
917 import { TOO_LONG_WORDS } from "../src/actions/tell.ts";
1018 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
110118 else forge.child.config.forgeRepo = before;
111119 }
112120 });
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs