vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(forge): reframe changelog-style asides as present-tense gotchas

Browse source
This commit is contained in:
iris 2026-08-15 11:46:51 +02:00 • committed by mara
commit 93bb3a294f
1 changed files with 19 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

35
docs/forge.md
View file

@ -51,9 +51,9 @@ read it without touching c0re's host-side credential store.
Two things live in the `agent-configs` Forgejo organization: Two things live in the `agent-configs` Forgejo organization:
- A config repo per agent (`agent-configs/<name>`). As of #1787 the - A config repo per agent (`agent-configs/<name>`). The
agent is a **write collaborator on its own** repo — it can push agent is a **write collaborator on its own** repo — it can push
config-change branches and (once #1838 P2 lands) open config PRs — but config-change branches and (once config-PR support lands) open config PRs — but
`main` is branch-protected core-only: only hive-c0re's verify-and-ff-push `main` is branch-protected core-only: only hive-c0re's verify-and-ff-push
merge handler lands on `main`, an operator-team approval is required, and merge handler lands on `main`, an operator-team approval is required, and
the agent can neither push `main` directly nor self-merge. `main` is the agent can neither push `main` directly nor self-merge. `main` is
@ -118,19 +118,20 @@ That size property is the whole point. A container rebuild starts the
poller with no memory of what it delivered, re-scans `?all=false`, and poller with no memory of what it delivered, re-scans `?all=false`, and
finds nothing stale — the delivered threads are already read on forge. finds nothing stale — the delivered threads are already read on forge.
Forge's own read-state is thus the durable, cross-rebuild record of Forge's own read-state is thus the durable, cross-rebuild record of
what's been delivered; there is **no persisted cursor**. (This what's been delivered; there is **no persisted cursor**.
replaced an earlier design that left threads unread and leaned on a
persisted dedup cursor: a rebuild that lost the cursor re-delivered the
entire still-unread backlog as fresh wakes — the notification flood of
#2593 / #2106.)
**Read-before-comment coupling, dropped on purpose.** The old design **Gotcha:** don't reintroduce a persisted dedup cursor here. A design
left threads unread so the hive-forge read-before-comment guard (which that leaves threads unread and tracks delivery via a separately-persisted
keys off forge unread-state) would force the agent to view a thread cursor is fragile — losing that cursor across a rebuild re-delivers the
before commenting. That coupling is gone: the broker wake already agent's entire still-unread backlog as a flood of fresh wakes. Forge's
carries the notification body, so *delivery is the read*. An agent that own read-state is the only durable record this design needs.
wants the full thread still runs `hive-forge comments` / `view`; the
guard no longer blocks a first comment on a freshly-delivered thread. **Read-before-comment guard doesn't block a fresh wake.** hive-forge's
read-before-comment guard (which keys off forge unread-state) does not
force the agent to view a thread before commenting on it: the broker
wake already carries the notification body, so *delivery is the read*.
An agent that wants the full thread still runs `hive-forge comments` /
`view`.
**In-process dedupe (tiny, ephemeral).** A single-process map (thread **In-process dedupe (tiny, ephemeral).** A single-process map (thread
id → last-delivered `updated_at`) guards the narrow window where a id → last-delivered `updated_at`) guards the narrow window where a
@ -244,8 +245,8 @@ A notification carrying a `latest_comment_url` normally takes the comment
path. But a merged/closed subject **keeps** its `latest_comment_url` set, path. But a merged/closed subject **keeps** its `latest_comment_url` set,
so a just-merged PR that had any prior discussion would route to the so a just-merged PR that had any prior discussion would route to the
comment path and render `[comment on PR]` (with a stale pre-merge comment comment path and render `[comment on PR]` (with a stale pre-merge comment
body) instead of `[PR merged]` — the agent never learns its PR merged body) instead of `[PR merged]` — the agent never learns its PR merged.
(#2495). So when the notification IS the merge/close transition — its So when the notification IS the merge/close transition — its
event time (`updated_at`) is within `NEW_ITEM_TOLERANCE_SECS` of the event time (`updated_at`) is within `NEW_ITEM_TOLERANCE_SECS` of the
subject's `closed_at` (set for both `merged` and `closed`) — the subject's `closed_at` (set for both `merged` and `closed`) — the
state-change path wins even with a comment url present state-change path wins even with a comment url present
@ -280,7 +281,7 @@ A review submitted with **no body** carries no `latest_comment_url`,
so it misses the comment path and lands on the state-change path with so it misses the comment path and lands on the state-change path with
`state == "open"` — exactly like a freshly opened PR. Labeling that `state == "open"` — exactly like a freshly opened PR. Labeling that
`new PR` is misleading: agents dismiss it as a duplicate of the `new PR` is misleading: agents dismiss it as a duplicate of the
original open notification and miss the review (#1637). So the `open` original open notification and miss the review. So the `open`
state only earns the `new <kind>` label when the notification's event state only earns the `new <kind>` label when the notification's event
time (`updated_at`) is within `NEW_ITEM_TOLERANCE_SECS` (120s) of the time (`updated_at`) is within `NEW_ITEM_TOLERANCE_SECS` (120s) of the
subject's `created_at`. Anything later is labeled `activity on <kind>` subject's `created_at`. Anything later is labeled `activity on <kind>`