chore(flags): retire phoenix-optimistic-edits — inline the optimistic edit path (#3667)

The flag served on@100% in production (optimistic in-place content edits,
#1675, epic #1637, released), so the gate and its flag-off fallback were dead
weight. Rip both and keep only the served-on behavior (ADR 0136).

- `useFlag(PHOENIX_OPTIMISTIC_EDITS)` removed from the three call sites
  (`PanoPostDetail` post.edit + CommentEditComposer, sozluk `DefinitionCard`);
  each now passes `optimistic` unconditionally instead of spreading it away.
- `postEditOptimistic` / `bodyEditOptimistic` drop their `enabled` parameter and
  the `| undefined` return — the partial is always built.
- IaC declaration deleted: the `flags/keys.ts` const + `DECLARED_FLAGS` entry,
  the `flagship/resources.ts` config/factory/import/re-export, and the
  `alchemy.run.ts` import + stack wiring.
- `optimistic-edits.invariant.test.ts` deleted (it pinned the retired flag's
  default-off IaC record); the `optimisticEdit` unit test drops its gate cases.
- Stale prose reworded in `.patterns/fate-mutations-client.md` and
  `.glossary/TERMS.md`.

Closes #3667

Author: usirin

.glossary/TERMS.md

@@ -123,7 +123,7 @@ The vocab-free *mechanism* lives in `packages/authz`; the kamp.us *instances + s
 | LiveDO | The unified **void**-aligned live-view Durable Object — ONE class, two roles, `state.storage` KV. Fans out mutations' `live.*` events to subscribers over SSE (ADR 0037). | two classes named ConnectionDO + TopicDO (see below) |
 | ConnectionDO / TopicDO | The **former, superseded** two-class live-view design. Today there is ONE class, `LiveDO`, with two **roles** (connection, topic) dispatched via `resolveRole(state.id.name)` — not two Durable Object classes (ADR 0037). | live Durable Object class names (they are roles of LiveDO, not classes) |
 | void | The upstream live-streaming Durable Object reference (`VoidLiveStreamDurableObject`) that **LiveDO** mirrors; the design authority for LiveDO's `DEFAULT_LIMITS`, the queue-full→`410` behavior, the first-failed-probe reap, and the stale/replay model. | inventing LiveDO limits/reap semantics from scratch |
-| optimistic slice | One per-mutation optimistic-update unit (epic #1637): the client writes the mutation's effect into fate's normalized cache the instant the user acts, then **reconciles by canonical id** against the server frame (ADR 0125) — adds are **A1** client-append + canonical-id dedup (an optimistic temp node the server row replaces, no flash/dupe), deletes are **D1** reply-aware drop (a plain edge-drop for a leaf, a conservative `[silindi]` tombstone when replies are loaded), with rollback on rejection. Each slice ships dark behind its **own** default-off flag (`phoenix-optimistic-edits`, `pano-optimistic-submit`, `pano-optimistic-comment-add`/`-delete`, `phoenix-optimistic-definition-add`/`-delete`, `pano-optimistic-post-delete`); the DOM-free decision helpers live per page (`src/pages/*Optimistic*.ts`). | one shared epic-wide flag (each slice has an independent dark-ship lifecycle); a client-invented final id (the server id is canonical — the temp node reconciles to it) |
+| optimistic slice | One per-mutation optimistic-update unit (epic #1637): the client writes the mutation's effect into fate's normalized cache the instant the user acts, then **reconciles by canonical id** against the server frame (ADR 0125) — adds are **A1** client-append + canonical-id dedup (an optimistic temp node the server row replaces, no flash/dupe), deletes are **D1** reply-aware drop (a plain edge-drop for a leaf, a conservative `[silindi]` tombstone when replies are loaded), with rollback on rejection. Each slice ships dark behind its **own** default-off flag (`pano-optimistic-submit`, `pano-optimistic-comment-add`/`-delete`, `phoenix-optimistic-definition-add`/`-delete`, `pano-optimistic-post-delete`), retired once the slice releases (ADR 0136 — the in-place edit slice is retired, its optimistic path unconditional); the DOM-free decision helpers live per page (`src/pages/*Optimistic*.ts`). | one shared epic-wide flag (each slice has an independent dark-ship lifecycle); a client-invented final id (the server id is canonical — the temp node reconciles to it) |
 | role (connection / topic) | LiveDO's two roles: **connection** owns one client's SSE stream + subscriptions; **topic** owns a topic's subscriber registry, publish fan-out, and reap alarm. | |
 | shaper | Maps a DB row to an `Entity` field set (`shapers.ts`). | |
 | source | A `Fate.source(ViewClass, {id}, handlers)` loader entry delegating to Effect services (`sources.ts`); fate never queries D1. The loader half (silent reads). | a source that throws not-found |

.patterns/fate-mutations-client.md

@@ -46,18 +46,17 @@ For inserts that create an entity, give the optimistic record a temporary id (`o
 
 An **in-place field edit** (`post.edit`, `comment.edit`, `definition.edit`) is the simplest optimistic case: it's an entity-field write-back that already re-renders in place through its result `view`, so making it optimistic is *only* passing the edited fields (plus a fresh `updatedAt`) as the `optimistic` partial. No temp id, no membership change — the edited entity keeps its id, so the optimistic write and the server `live.update({changed:["body"|"title,body"]})` frame touch the **same fields on the same entity** and can't diverge. fate rolls the partial back and restores the prior text on a rejected edit (the boundary-class throw, [Errors](#errors)), so the existing inline error shows with no phantom-saved state.
 
-The load-bearing pieces are hook-free and unit-testable, mirroring `voteOptimistic`: [`src/fate/optimisticEdit.ts`](../apps/web/src/fate/optimisticEdit.ts) builds the partial (`postEditOptimistic` / `bodyEditOptimistic`) and returns `undefined` when the gate is off, so the call site spreads it away under `exactOptionalPropertyTypes`:
+The load-bearing pieces are hook-free and unit-testable, mirroring `voteOptimistic`: [`src/fate/optimisticEdit.ts`](../apps/web/src/fate/optimisticEdit.ts) builds the partial (`postEditOptimistic` / `bodyEditOptimistic`):
 
 ```tsx
-const optimistic = bodyEditOptimistic(optimisticEdits, body); // undefined when the flag is off
 await fate.mutations.definition.edit({
   input: {id, body},
-  ...(optimistic ? {optimistic} : {}),   // {body, updatedAt: <now>} when on
+  optimistic: bodyEditOptimistic(body),   // {body, updatedAt: <now>}
   view: DefinitionView,
 });
 ```
 
-The fresh `updatedAt` drives the "düzenlendi" indicator (`EditedIndicator`) instantly, consistently with the reconciled frame. Shipped dark behind the `phoenix-optimistic-edits` flag (default-off, ADR 0083; #1675, epic #1637) — off, the edit passes no `optimistic` and waits for the round-trip exactly as before.
+The fresh `updatedAt` drives the "düzenlendi" indicator (`EditedIndicator`) instantly, consistently with the reconciled frame. Shipped dark behind a per-slice flag (#1675, epic #1637), released, and the flag retired (ADR 0136) — the optimistic path is now unconditional.
 
 ## Connection membership — declarative, not imperative
 
@@ -82,7 +81,7 @@ There is no hand-written updater enumerating connection keys. For connections th
 > - **add** to a nested connection: the new node is normalized into the cache, but joins the list only via a live `appendNode` or a re-read. sözlük's `definition.add` publishes no append, so its composer **reloads after a successful add**.
 > - **delete** of a node in a nested connection: `delete: true` is **wrong-entity** for sözlük's `definition.delete`, a `Term`-returning mutation (it re-resolves the parent for fresh counts), so `delete:true` would `deleteRecord("Term", definitionId)`. The card calls delete **without** `delete:true`; the server publishes `deleteEdge("Definition", id)` on `Term.definitions`.
 >
-> Entity-field mutations (vote, edit) are unaffected: they write back through the result `view` and re-render in place. Votes are fully optimistic; the in-place edits become optimistic behind the `phoenix-optimistic-edits` flag — see [Optimistic in-place edits](#optimistic-edits).
+> Entity-field mutations (vote, edit) are unaffected: they write back through the result `view` and re-render in place. Votes and the in-place edits are both fully optimistic — see [Optimistic in-place edits](#optimistic-edits).
 
 ### Optimistic nested-connection membership (add-dedup + reply-aware delete) {#optimistic-nested-membership}
 

apps/web/alchemy.run.ts

@@ -58,7 +58,6 @@ import {
 	navIaFlag,
 	optimisticDefinitionAddFlag,
 	optimisticDefinitionDeleteFlag,
-	optimisticEditsFlag,
 	panoBaseFeedFlag,
 	panoDraftSaveFlag,
 	panoOptimisticPostDeleteFlag,
@@ -102,10 +101,6 @@ export default Alchemy.Stack(
 		// The conversion-funnel readout dark-ship flag, default-off (#1589) — the
 		// founder/mod tier-count surface gates behind this key until a human release.
 		yield* funnelReadoutFlag(flagship.appId);
-		// The optimistic in-place content-edit dark-ship flag, default-off (#1675,
-		// epic #1637) — post/comment/definition edits pass an optimistic payload only
-		// behind this key until a human release.
-		yield* optimisticEditsFlag(flagship.appId);
 		// The optimistic post.delete dark-ship flag, default-off (#1677, epic #1637) —
 		// gates the instant-feed-removal delete flow until a human release.
 		yield* panoOptimisticPostDeleteFlag(flagship.appId);

apps/web/src/components/sozluk/DefinitionCard.tsx

@@ -11,7 +11,7 @@ import {bodyEditOptimistic} from "../../fate/optimisticEdit";
 import {useDraftSubmit} from "../../fate/useDraftSubmit";
 import {codeOf, toIso} from "../../fate/wire";
 import {messageForCode, type WireMessageOverrides} from "../../fate/wireMessages";
-import {PHOENIX_OPTIMISTIC_DEFINITION_DELETE, PHOENIX_OPTIMISTIC_EDITS} from "../../flags/keys";
+import {PHOENIX_OPTIMISTIC_DEFINITION_DELETE} from "../../flags/keys";
 import {useFlag} from "../../flags/useFlag";
 import {formatAgoTR} from "../../lib/datetime";
 import {renderMarkdownInline, splitMarkdownBlocks} from "../../lib/markdown";
@@ -83,9 +83,6 @@ export function DefinitionCard(props: DefinitionCardProps) {
 	const fate = useFateClient();
 	const session = useSession();
 	const navigate = useNavigate();
-	// Dark-ship gate (#1675): with the flag off the edit passes no optimistic
-	// payload and waits for the round-trip, exactly as before.
-	const {value: optimisticEdits} = useFlag(PHOENIX_OPTIMISTIC_EDITS, false);
 	// Dark-ship gate (#1681, ADR 0125 D1): off ⇒ the card drops only when the live
 	// `deleteEdge` push / read-back lands, exactly as today.
 	const {value: optimisticDelete} = useFlag(PHOENIX_OPTIMISTIC_DEFINITION_DELETE, false);
@@ -152,12 +149,11 @@ export function DefinitionCard(props: DefinitionCardProps) {
 			setEditError(messageForCode("BODY_TOO_LONG", DEFINITION_OVERRIDES));
 			return;
 		}
-		const optimistic = bodyEditOptimistic(optimisticEdits, editBody);
 		await runEdit(
 			() =>
 				fate.mutations.definition.edit({
 					input: {id: definition.id, body: editBody},
-					...(optimistic ? {optimistic} : {}),
+					optimistic: bodyEditOptimistic(editBody),
 					view: DefinitionView,
 				}),
 			"tanım güncellenemedi",

apps/web/src/fate/optimisticEdit.test.ts

@@ -4,41 +4,31 @@ import {bodyEditOptimistic, postEditOptimistic} from "./optimisticEdit";
 /**
  * Covers the load-bearing optimistic-edit core the three Class-A edits ship
  * through (`post.edit`/`comment.edit`/`definition.edit` → `postEditOptimistic` /
- * `bodyEditOptimistic`, #1675): the dark-ship flag gate (off ⇒ no optimistic
- * payload, the pre-flag round-trip behavior; on ⇒ the edited field(s) plus a
- * fresh `updatedAt` that drives the "düzenlendi" indicator), inspected off the
- * REAL exported builders — the same functions the call sites route through, not a
- * re-implemented copy. fate's own apply/reconcile/rollback is exercised at the
- * integration tier; this pins the gate + payload shape hook-free.
+ * `bodyEditOptimistic`, #1675): the edited field(s) plus a fresh `updatedAt` that
+ * drives the "düzenlendi" indicator, inspected off the REAL exported builders —
+ * the same functions the call sites route through, not a re-implemented copy.
+ * fate's own apply/reconcile/rollback is exercised at the integration tier; this
+ * pins the payload shape hook-free.
  */
 const fixedNow = () => new Date("2026-07-02T12:00:00.000Z");
 
-describe("postEditOptimistic — the flag gate + payload for post.edit", () => {
-	it("returns undefined when the flag is off (pre-flag: wait for the round-trip)", () => {
-		expect(postEditOptimistic(false, {title: "yeni", body: "gövde"}, fixedNow)).toBeUndefined();
-	});
-
-	it("returns the edited title/body + a fresh updatedAt when the flag is on", () => {
-		expect(postEditOptimistic(true, {title: "yeni", body: "gövde"}, fixedNow)).toEqual({
+describe("postEditOptimistic — the payload for post.edit", () => {
+	it("returns the edited title/body + a fresh updatedAt", () => {
+		expect(postEditOptimistic({title: "yeni", body: "gövde"}, fixedNow)).toEqual({
 			title: "yeni",
 			body: "gövde",
 			updatedAt: fixedNow(),
 		});
 	});
 
 	it("stamps updatedAt from the injected clock (drives the edited indicator)", () => {
-		const result = postEditOptimistic(true, {title: "t", body: "b"}, fixedNow);
-		expect(result?.updatedAt).toEqual(fixedNow());
+		expect(postEditOptimistic({title: "t", body: "b"}, fixedNow).updatedAt).toEqual(fixedNow());
 	});
 });
 
-describe("bodyEditOptimistic — the flag gate + payload for comment.edit / definition.edit", () => {
-	it("returns undefined when the flag is off", () => {
-		expect(bodyEditOptimistic(false, "gövde", fixedNow)).toBeUndefined();
-	});
-
-	it("returns the edited body + a fresh updatedAt when the flag is on", () => {
-		expect(bodyEditOptimistic(true, "gövde", fixedNow)).toEqual({
+describe("bodyEditOptimistic — the payload for comment.edit / definition.edit", () => {
+	it("returns the edited body + a fresh updatedAt", () => {
+		expect(bodyEditOptimistic("gövde", fixedNow)).toEqual({
 			body: "gövde",
 			updatedAt: fixedNow(),
 		});

apps/web/src/fate/optimisticEdit.ts

@@ -1,17 +1,15 @@
 /**
  * Optimistic-edit payload builders for the three Class-A content edits
- * (`post.edit` / `comment.edit` / `definition.edit`), gated by the
- * `phoenix-optimistic-edits` dark-ship flag (#1675, epic #1637). These edits are
+ * (`post.edit` / `comment.edit` / `definition.edit`). These edits are
  * entity-field write-backs that already re-render in place through their result
- * `view` — the only gap is that no `optimistic` partial is passed, so the UI
- * waits for the round-trip. Passing the partial renders the edited body/title
- * instantly; fate rolls it back on a rejected mutation and reconciles it against
- * the server `live.update({changed:[…]})` frame (same field → no divergence).
+ * `view`; passing the partial renders the edited body/title instantly, and fate
+ * rolls it back on a rejected mutation and reconciles it against the server
+ * `live.update({changed:[…]})` frame (same field → no divergence).
  *
- * Pure + hook-free (mirroring `voteOptimistic` in `useVoteToggle`) so the flag
- * gate and the fresh-`updatedAt` — which drives the "düzenlendi" indicator
- * (`EditedIndicator`) consistently with the reconciled frame — are unit-testable
- * apart from the fate mutation and React. See `.patterns/fate-mutations-client.md`.
+ * Pure + hook-free (mirroring `voteOptimistic` in `useVoteToggle`) so the
+ * fresh-`updatedAt` — which drives the "düzenlendi" indicator (`EditedIndicator`)
+ * consistently with the reconciled frame — is unit-testable apart from the fate
+ * mutation and React. See `.patterns/fate-mutations-client.md`.
  */
 
 /** Injectable now-clock so the optimistic `updatedAt` is deterministic in tests. */
@@ -32,28 +30,15 @@ export interface BodyEditOptimistic {
 	readonly updatedAt: Date;
 }
 
-/**
- * The optimistic partial for a post edit, or `undefined` when the dark-ship flag
- * is off — the pre-flag behavior: no `optimistic` payload, the UI waits for the
- * round-trip. `undefined` lets the call site spread it away under
- * `exactOptionalPropertyTypes` (`...(optimistic ? {optimistic} : {})`).
- */
+/** The optimistic partial for a post edit — the edited title/body + a fresh `updatedAt`. */
 export function postEditOptimistic(
-	enabled: boolean,
 	fields: {readonly title: string; readonly body: string},
 	now: Now = defaultNow,
-): PostEditOptimistic | undefined {
-	return enabled ? {title: fields.title, body: fields.body, updatedAt: now()} : undefined;
+): PostEditOptimistic {
+	return {title: fields.title, body: fields.body, updatedAt: now()};
 }
 
-/**
- * The optimistic partial for a comment/definition body edit, or `undefined` when
- * the dark-ship flag is off (see {@link postEditOptimistic}).
- */
-export function bodyEditOptimistic(
-	enabled: boolean,
-	body: string,
-	now: Now = defaultNow,
-): BodyEditOptimistic | undefined {
-	return enabled ? {body, updatedAt: now()} : undefined;
+/** The optimistic partial for a comment/definition body edit (see {@link postEditOptimistic}). */
+export function bodyEditOptimistic(body: string, now: Now = defaultNow): BodyEditOptimistic {
+	return {body, updatedAt: now()};
 }

apps/web/src/flags/keys.ts

@@ -125,16 +125,6 @@ export const PHOENIX_FUNNEL_READOUT = "phoenix-funnel-readout";
  */
 export const PHOENIX_MOD_QUEUE = "phoenix-mod-queue";
 
-/**
- * Optimistic in-place content-edit dark-ship flag (#1675, epic #1637). Gates the
- * three Class-A content edits (`post.edit`, `comment.edit`, `definition.edit`)
- * that render the edited body/title instantly by passing an `optimistic` payload
- * (the seam votes already use); default-off so the edits reach production dark
- * (waiting for the round-trip, exactly as today) until a human flips it at release
- * (ADR 0083). The add/delete slices of the epic ship behind their own gates.
- */
-export const PHOENIX_OPTIMISTIC_EDITS = "phoenix-optimistic-edits";
-
 /**
  * Optimistic `definition.add` (instant term-page insert) dark-ship flag (#1679,
  * epic #1637). Gates the A1 client-append into the *nested* `Term.definitions`
@@ -339,7 +329,6 @@ export const DECLARED_FLAGS: readonly FlagDeclaration[] = [
 	{key: PHOENIX_BILDIRIM, defaultValue: false},
 	{key: PHOENIX_FUNNEL_READOUT, defaultValue: false},
 	{key: PHOENIX_MOD_QUEUE, defaultValue: false},
-	{key: PHOENIX_OPTIMISTIC_EDITS, defaultValue: false},
 	{key: PHOENIX_OPTIMISTIC_DEFINITION_ADD, defaultValue: false},
 	{key: PHOENIX_OPTIMISTIC_DEFINITION_DELETE, defaultValue: false},
 	{key: PHOENIX_REACTIONS, defaultValue: false},