Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (a held_row_edited release refusal names its reason; registry next steps fit the release paths)

garrytanbd71e93c1f4f
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index 4cd06885c6..1310697a31 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -15,7 +15,7 @@ Under contract v1 an `error` value never changes. Where a surface sends a legacy
| `error` (frozen) | `code` (canonical) | Meaning |
|---|---|---|
-| `invalid_params` | `fact_withdrawn` | `remember`, or an owner `gbrain trust release` of a held fact, refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved, and a refused release leaves the fact held. |
+| `invalid_params` | `fact_withdrawn` | `remember`, or an owner `gbrain trust release` that writes a held fact into its entity page's `## Facts` table (a managed brain), refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved, and a refused release leaves the fact held. |
| `permission_denied` | `insufficient_scope` | The connection lacks the OAuth scope the operation requires. |
| `invalid_params` | `invalid_fence` | A facts or takes fence in the page cannot be imported without dropping or guessing rows, so the page (or the file) was not written. |
| `invalid_params` | `link_cursor_invalid` | A get_links / get_backlinks cursor was not one this listing returned: it belongs to another slug, direction, source scope or filter set, or is not a cursor. |
@@ -1371,7 +1371,7 @@ More: [docs/guides/repair.md#rename-identity](../../docs/guides/repair.md#rename
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| `remember`, or an owner `gbrain trust release` of a held fact, refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved, and a refused release leaves the fact held. | A forgotten claim stays withdrawn: remembering the same normalized text does not restore it, and a claim forgotten without an entity is withdrawn for every entity. The additive `withdrawn` object (`at`, `subject`: an entity slug or `all_entities`, `visibility`) says when and how widely the exact claim was forgotten; it covers that exact claim only, and its absence carries no meaning. | Do not retry the same text. Tell the user the claim was forgotten (withdrawn.at, withdrawn.subject); if it is still true, remember it in new words. To link a fact saved without an entity, remember it with entity and replaces set to its fact id instead of forgetting it. For a refused release, do not retry it: drop the hold (gbrain trust drop h<id>) unless the user wants the claim back in new words. | agent | `repeat the read that failed` | 1 | no |
+| `remember`, or an owner `gbrain trust release` that writes a held fact into its entity page's `## Facts` table (a managed brain), refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved, and a refused release leaves the fact held. | A forgotten claim stays withdrawn: remembering the same normalized text does not restore it, and a claim forgotten without an entity is withdrawn for every entity. The additive `withdrawn` object (`at`, `subject`: an entity slug or `all_entities`, `visibility`) says when and how widely the exact claim was forgotten; it covers that exact claim only, and its absence carries no meaning. | Do not retry the same text. Tell the user the claim was forgotten (withdrawn.at, withdrawn.subject); if it is still true, remember it in new words. To link a fact saved without an entity, remember it with entity and replaces set to its fact id instead of forgetting it. For a refused release, do not retry it: drop the hold (gbrain trust drop h<id>) unless the user wants the claim back in new words. | agent | `repeat the read that failed` | 1 | no |
### facts_absorb_write_refused
@@ -1451,7 +1451,7 @@ More: [docs/guides/retrieval-feedback.md#feedback_not_authorized](../../docs/gui
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| A fact was not indexed from the facts fence row its request names because that row no longer reads back as the fact (removed, struck, emptied, another visibility or other text), or, for an owner release of a held row, because its context or source was edited after the hold (`held_row_edited`); nothing was written, and a refused release leaves the fact held. | A facts row derives from its fence row, which Git holds. Indexing a fact at a row that now says something else would make the database disagree with the file, so the write stops and the file stays as it is. | Read the page (gbrain get <slug>) to see the row as it stands; if the fact is still wanted, remember it again, which writes it as a new row. For a refused gbrain trust release, do not remember it: run gbrain trust review, where the edited row is held separately, and release or drop the holds there. | agent | `repeat the read that failed` | 1 | no |
+| A fact was not indexed from the facts fence row its request names because that row no longer reads back as the fact (removed, struck, emptied, another visibility or other text), or, for an owner release of a held row, because its context or source was edited after the hold (`held_row_edited`, named in the message); nothing was written, and a refused release leaves the fact held. | A facts row derives from its fence row, which Git holds. Indexing a fact at a row that now says something else would make the database disagree with the file, so the write stops and the file stays as it is. For `held_row_edited` the row still reads back, but the owner approved the older context or source, so indexing it would publish content the owner did not review. | Read the page (gbrain get <slug>) to see the row as it stands; if the fact is still wanted, remember it again, which writes it as a new row. For a refused gbrain trust release, do not remember it and do not release the same hold again (it refuses the same way): drop it (gbrain trust drop h<id>). If the edit was itself held, gbrain trust review lists it separately. | agent | `repeat the read that failed` | 1 | no |
Reasons: `row_missing`, `struck`, `empty`, `visibility`, `text`, `held_row_edited`.
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index 82186c3b07..2391e66d23 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -278,10 +278,10 @@ export const CODES = {
export_limit: { class: 'caller', summary: "This migration is bounded to 5,000 active pages per source; split or use a reviewed bulk export." },
extraction_failed: { class: 'server', summary: "The accepted atom extraction failed (malformed output, or a response stopped before the end); a new attempt needs approval.", why: "The drain retries a failed managed atom batch on its own up to 3 times per content (then holds it, code held_failed); this code reports a failed explicit retry, or a failure the drain cannot attribute to a checkpoint, so the same input is not paid for again without approval." },
extractor_identity_mismatch: { class: 'server', summary: "The approved extractor differs from the installed extractor; this receipt cannot resume or admit another revision." },
- fact_withdrawn: { class: 'caller', summary: "`remember`, or an owner `gbrain trust release` of a held fact, refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved, and a refused release leaves the fact held.", why: "A forgotten claim stays withdrawn: remembering the same normalized text does not restore it, and a claim forgotten without an entity is withdrawn for every entity. The additive `withdrawn` object (`at`, `subject`: an entity slug or `all_entities`, `visibility`) says when and how widely the exact claim was forgotten; it covers that exact claim only, and its absence carries no meaning.", legacy_error: 'invalid_params', suggestion: 'Do not retry the same text. Tell the user the claim was forgotten (withdrawn.at, withdrawn.subject); if it is still true, remember it in new words. To link a fact saved without an entity, remember it with entity and replaces set to its fact id instead of forgetting it. For a refused release, do not retry it: drop the hold (gbrain trust drop h<id>) unless the user wants the claim back in new words.' },
+ fact_withdrawn: { class: 'caller', summary: "`remember`, or an owner `gbrain trust release` that writes a held fact into its entity page's `## Facts` table (a managed brain), refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved, and a refused release leaves the fact held.", why: "A forgotten claim stays withdrawn: remembering the same normalized text does not restore it, and a claim forgotten without an entity is withdrawn for every entity. The additive `withdrawn` object (`at`, `subject`: an entity slug or `all_entities`, `visibility`) says when and how widely the exact claim was forgotten; it covers that exact claim only, and its absence carries no meaning.", legacy_error: 'invalid_params', suggestion: 'Do not retry the same text. Tell the user the claim was forgotten (withdrawn.at, withdrawn.subject); if it is still true, remember it in new words. To link a fact saved without an entity, remember it with entity and replaces set to its fact id instead of forgetting it. For a refused release, do not retry it: drop the hold (gbrain trust drop h<id>) unless the user wants the claim back in new words.' },
fact_rows_collide: { class: 'caller', summary: "Carrying a page's identity across a rename would drop facts: a fence row of the old page has a different claim in the new file, or the new file does not hold it.", why: "gbrain repair rename-identity merges the two pages' facts only where both say the same thing at the same fence row; anything else would lose one side, so nothing is written.", suggestion: 'Give each old claim its own row in the new file\'s facts fence (or keep the same claim at its row), commit and sync, then preview again; or keep the old page with gbrain restore, or release the hold with --close.', docs: 'docs/guides/repair.md#rename-identity' },
fact_already_expired: { class: 'caller', summary: "The fact had already expired before this write." },
- fence_row_changed: { class: 'caller', reasons: ['row_missing', 'struck', 'empty', 'visibility', 'text', 'held_row_edited'], summary: "A fact was not indexed from the facts fence row its request names because that row no longer reads back as the fact (removed, struck, emptied, another visibility or other text), or, for an owner release of a held row, because its context or source was edited after the hold (`held_row_edited`); nothing was written, and a refused release leaves the fact held.", why: "A facts row derives from its fence row, which Git holds. Indexing a fact at a row that now says something else would make the database disagree with the file, so the write stops and the file stays as it is.", suggestion: 'Read the page (gbrain get <slug>) to see the row as it stands; if the fact is still wanted, remember it again, which writes it as a new row. For a refused gbrain trust release, do not remember it: run gbrain trust review, where the edited row is held separately, and release or drop the holds there.' },
+ fence_row_changed: { class: 'caller', reasons: ['row_missing', 'struck', 'empty', 'visibility', 'text', 'held_row_edited'], summary: "A fact was not indexed from the facts fence row its request names because that row no longer reads back as the fact (removed, struck, emptied, another visibility or other text), or, for an owner release of a held row, because its context or source was edited after the hold (`held_row_edited`, named in the message); nothing was written, and a refused release leaves the fact held.", why: "A facts row derives from its fence row, which Git holds. Indexing a fact at a row that now says something else would make the database disagree with the file, so the write stops and the file stays as it is. For `held_row_edited` the row still reads back, but the owner approved the older context or source, so indexing it would publish content the owner did not review.", suggestion: 'Read the page (gbrain get <slug>) to see the row as it stands; if the fact is still wanted, remember it again, which writes it as a new row. For a refused gbrain trust release, do not remember it and do not release the same hold again (it refuses the same way): drop it (gbrain trust drop h<id>). If the edit was itself held, gbrain trust review lists it separately.' },
fence_unrenderable: { class: 'server', summary: "A legacy fact row was not adopted into its page's facts fence because the fence codec reads the rendered row back as something other than the stored fact.", why: "The fence trims a claim, folds CRLF to LF, reads `~~x~~` as a struck row and `<br>` as a line break; a claim the codec would change by more than whitespace cannot be written into the fence without changing what it says, so the row stays a legacy row (active and searchable, nothing is lost) and is counted by doctor fence_integrity as unrenderable_legacy_facts. The same code names a planned adoption whose rendered fence does not read back as its facts; that is a gbrain planning defect, not caller input.", docs: 'docs/guides/write-refusals.md#fence_unrenderable', suggestion: 'Nothing to fix in the page: the rows stay active and searchable. Report the page slug and the reason class with the gbrain version; do not forget or expire a row to clear this count.', fix: { argv: ['gbrain', 'doctor', '--only', 'fence_integrity', '--json'], consent: [], actor: 'agent', why: 'Lists the pages whose legacy fact rows cannot be adopted into their fence and why (by fact id and reason class, never the claim text), read-only.', requires_exclusive: false } },
fact_not_found: { class: 'caller', summary: "Fact not found." },
facts_absorb_write_refused: { class: 'caller', summary: "Facts absorb refused the write." },
diff --git a/src/core/trust/release-publish.ts b/src/core/trust/release-publish.ts
index 7157a7509d..8d904ad91c 100644
--- a/src/core/trust/release-publish.ts
+++ b/src/core/trust/release-publish.ts
@@ -164,8 +164,8 @@ export async function prepareTrustReleaseMutation(engine: BrainEngine, row: Writ
const base = await materializedPage(engine, snapshot.page);
const cell = [base.compiled_truth, base.timeline ?? ''].flatMap(text => parseFactsFence(text).facts).find(f => f.rowNum === intent.row_num);
if (cell && ((cell.context ?? null) !== (str(p.context) ?? null) || (cell.source ?? FENCE_SOURCE_DEFAULT) !== (str(p.source) ?? FENCE_SOURCE_DEFAULT))) {
- throw opError('fence_row_changed', `Fence row ${intent.row_num} of ${row.slug} was edited after h${hold.id} was held; nothing was changed and the fact stays held.`,
- `The row's context or source no longer matches what h${hold.id} held, so releasing it would index content the owner did not review. Run gbrain trust review: the edit is held separately.`,
+ throw opError('fence_row_changed', `Fence row ${intent.row_num} of ${row.slug} was edited after h${hold.id} was held (held_row_edited); nothing was changed and the fact stays held.`,
+ `The row's context or source no longer matches what h${hold.id} held, so releasing it would index content the owner did not review, and releasing h${hold.id} again refuses the same way. Drop it (gbrain trust drop h${hold.id}); if the edit was itself held, gbrain trust review lists it separately.`,
{ reason: 'held_row_edited', detail: JSON.stringify({ slug: row.slug, row_num: intent.row_num, problem: 'held_row_edited' }) });
}
}
diff --git a/test/trust-release-fence.test.ts b/test/trust-release-fence.test.ts
index 0add29537e..6b09044db2 100644
--- a/test/trust-release-fence.test.ts
+++ b/test/trust-release-fence.test.ts
@@ -165,6 +165,7 @@ for (const backend of testBackends()) {
const error = await applyOwnerAction(engine, { action: 'release', ref: `h${first!.id}` }, { binding: preview.binding, confirmation: { via: 'tty' }, by: owner })
.then(() => null, (e: { code?: string }) => e);
expect(error?.code).toBe('fence_row_changed');
+ expect((error as { message?: string } | null)?.message).toContain('(held_row_edited)');
expect(await holdStatus(engine, `h${first!.id}`)).toBe('held');
expect(await factRows(engine)).toEqual([]);