Skip to content

Comments: feedback beside knowledge

A comment lets you question or correct a node without editing it. The node keeps saying exactly what it said, with the same revision and the same approval, and your feedback sits next to it where every later reader, person or agent, can see it.

That one property explains most of how comments behave.

Why a comment never touches its target

Approval and minting certify a node's exact text: Hadron hashes the title, abstract and content, and a later edit makes the approval stale. If a comment were part of the node, every remark would invalidate that evidence, and a protected node, such as an approved spec, couldn't be discussed at all.

So a comment is a separate node of type comment, in the same memory as the node it concerns (its target). Writing, replying to, editing, deleting or resolving a comment changes only the comment. The target's content, revision number, approval and mint state stay byte-for-byte the same.

For the same reason a comment is never approved or minted itself, and the approve-all and mint operations skip comments entirely.

Pinned to the revision it was about

Each comment records the target revision it was written against, and a fingerprint of the target's text at that revision. When the node changes later, the comment says it was about revision 3 while the node is now at revision 5. A reader can tell at a glance whether the feedback still applies, without anyone having to tidy old comments away.

Threads travel with their node

A comment is attached to the node it concerns by that node's identity, not by its name or address. Rename the node or change its address and the discussion stays attached.

When you move a node to another memory, or merge one memory into another, its threads go with it, in the same operation, so a comment is never left behind in the old memory. Two things can't be carried, and Hadron refuses the operation instead of losing or stranding feedback:

  • A destination that can't hold comments. Private and system memories take no comments, so a node that has comment threads can't move or merge into one.
  • A merge that would fold a commented node into another. When two memories have a node at the same address, the merge combines them and one node disappears. A comment can't be re-attached to a different node, so a node that has comment threads can't be the one that disappears.

In both cases a memory admin can delete the node's threads, which clears the way, or, for a fold, rename one of the two nodes so they no longer collide. Deleted threads don't count as live feedback, so they don't block anything.

A memory merge works through its nodes in batches, so a refusal can arrive after earlier batches have committed, for example when someone comments on a node that would be folded while the merge is running. Such a refusal says so (partialMerge), the source memory is never deleted by a refused merge, and resolving the blocker and running the same merge again finishes it.

When a node itself is deleted, its threads go with it, and restoring the node brings back those threads, except any that were already deleted on their own. Deleting the node for good deletes its threads for good.

A warning, never a block

A node with open threads says so wherever someone decides whether to trust it: when an agent reads the node, and in the results of approving a whole memory or checking it before a mint, where it appears as a warning.

It never stops anything. No comment and no thread state blocks approving or minting the node. Anyone who can write to a memory can comment on its nodes, so if a comment could block, any of them could stop a mint. A visible warning gives approvers the signal without handing every commenter a veto.

Feedback, not content

Comments are opinions about a node, not facts in it. Hadron keeps them out of the way of ordinary reading:

  • Search returns content by default. You ask for comments explicitly when you want them.
  • Agents are told what they're reading. An agent that reads a node sees a one-line count of open threads, and every comment it reads comes labeled as reader feedback, not authoritative content.
  • Comments don't clutter the node tree. They're found through the node they're about.

Threads and authorship

A comment starts a thread; others reply in it. A thread is open until someone who can write to the memory marks it resolved, and it can be reopened later. A reply to a resolved thread is allowed and doesn't reopen it.

Each author holds at most one open thread per node. A second comment from the same author on the same node is refused and points to the existing thread, so one person's feedback on a node stays in one place.

The author is whoever the server can attribute:

  • a named worker, when a team worker wrote it (the person driving the worker is kept as provenance, not shown as the author);
  • otherwise you, together with the agent that wrote on your behalf, when there is one;
  • or an App, for an App key.

Only the author can edit a comment, and an edit records who edited and when (editedAt, editedBy), so a reader can tell an edited comment from one that was only resolved or reopened. Hadron keeps no history of earlier text: an edit replaces it.

The author, or a memory manager, can delete a comment. What is left depends on where it sits:

  • A reply, or a top-level comment nobody has replied to is simply gone. It no longer shows in any read, and it no longer counts as feedback.
  • A top-level comment that has live replies stays as a stub: it shows a comment was there and deleted, without its text, so the replies keep their context. The stub disappears when its last reply is deleted.

A stub is not an open thread. It isn't counted among a node's open threads, it doesn't trigger the mint and approve-all warning, and it doesn't use up its author's one open thread per node. Nobody can reply to it, resolve it or reopen it: the conversation under it is read-only. To say more, start a new thread.

Deleting a whole thread at once is a separate act for a memory admin.

What commenting doesn't do

  • It grants nothing. Being able to comment gives no right to edit, approve or mint the node.
  • It stays in one memory. A comment lives in its target's memory, so reading it needs read access to that memory. You can't comment across memories.
  • Not every memory takes comments. App, knowledge, personal and group memories do; private and system memories don't.
  • It anchors to the whole node. There's no highlighting of a character range yet. You can quote the passage you mean.