Your report changed. Where did the comment go?

Hello from the engineering team.

We want to write about the part of Deliverd we have spent the most time on and argued about the most. It is not publishing. Publishing is the easy half.

The hard half is this: a document that keeps changing is straightforward. A conversation about a document that keeps changing is not.

Your agent republishes the claims report on Friday morning. Someone left a comment on Wednesday against a sentence in section four. That sentence has been rewritten. Where does the comment go?

Getting that wrong is not a small bug. It is the difference between a tool people review work in and a tool people export out of.

Every publish is a version

Nothing is overwritten, ever. Each publish keeps its own bytes, its own file count, its own scan result and — if whoever published it said so — a line about what changed.

Two things in that table are worth pulling out.

v1 is blocked. The publish scanner found an AWS access key in it. A blocked version is not deleted and not hidden: it stays in the list as a record that it happened. But it has no Restore button and no Pin button, because there is no sequence of clicks that should ever put a leaked credential back in front of readers.

v3 is pinned, and v4 is current. These are different things, and the difference is the feature we went back and forth on longest.

• Restore moves the report back. v3 becomes the current version, and that is what everyone gets.
• Pin freezes what readers see while publishing carries on underneath. Your agent can publish v5, v6 and v7; the audience keeps seeing v3 until you unpin, and the moment you do they are on the latest.

The second one exists because of a scenario we kept hitting. The board reads the pack on Thursday morning. The agent is still improving it on Wednesday night. You do not want to stop the agent, and you do not want the numbers moving under a room full of people. Pin it Wednesday, unpin it Thursday afternoon, and nobody had to coordinate.

A comment belongs to a passage, not to a page

When you select text in a report and comment on it, we do not store "paragraph 4". We store the exact text you selected, 48 characters of context on either side of it, and where it was in the document.

That is what makes the next part possible.

The ordering matters more than the algorithm. Context beats position, because a paragraph that moved 400 lines down is still the same paragraph, while the sentence that happens to sit at the old offset is a stranger. And a fuzzy match on its own is not enough at the bottom of the ladder — the text around it has to have survived too, or we would cheerfully attach your comment to a coincidence.

We gave ourselves four rules while building it, and we would defend all four:

1. This can never fail a publish. Comment bookkeeping is not allowed to stand between an agent and a deploy. If re-anchoring falls over, the version still goes out.
2. Never overwrite the original anchor. The selection you made is stored against the version you made it against, permanently. Everything above is a reading of where it lands now, not a replacement for where it was.
3. Never silently drop a thread. The worst outcome is needs review, which is a badge, not a deletion.
4. Say so in the interface. moved and needs review are shown to the person reading, because a comment that quietly points at the wrong sentence is worse than one that admits it is lost.

Two honest caveats. We re-anchor up to 200 open threads on a publish and compute the rest when the sidebar next loads, so a report with an enormous comment history gets its answer a moment later rather than never. And 0.82 and 0.75 are judgement calls — tuned against our own documents, and we would genuinely like to know if they are wrong for yours.

Your agent can join the conversation

This is the part we are most pleased with.

An agent that has just read a report can comment on a passage, the same as a person. It has no mouse and no DOM selection, so it sends the quote instead, and the server re-reads the current version and places the anchor itself.

If that quote appears three times in the document, we refuse — and the error says it appeared three times and asks for more of the surrounding sentence. We deliberately do not fall back to attaching a general comment. An agent that asked to annotate a specific passage and was told it succeeded, when the comment actually landed nowhere in particular, has been lied to, and the reader ends up with feedback that has no visible subject.

What we are building, and what we want from you

Committed and not built yet, so you know where you stand: SCIM provisioning, OpenID Connect for organisations that need it instead of SAML, and first-party Slack and Teams apps. Slack and Teams already work through outbound webhooks today — point one at an incoming webhook URL and it posts on publish, update, share and comment — but installing a real app from their directory is not there.

Beyond that we would rather ask than guess. Four questions we are actively arguing about internally:

• When a thread comes back needs review after a publish, should that email the person who wrote it? We lean yes, and we are worried about the noise.
• If you restore v3, should threads that were resolved against v4 reopen? We record which version resolved a thread, so we can. We are not sure we should.
• Should an agent's comment reach you the same way a colleague's does, or is a separate channel for machine feedback the thing you actually want?
• Is pinning something you would use, or did we build it for ourselves?

Tell us. Get in touch, or mail us directly at support@deliverd.dev. Feature requests, disagreements and bug reports are all equally welcome — and if you have a report that breaks our re-anchoring, that is the most useful thing you could possibly send us.

We are a small team who care a lot about this. Thanks for reading.

— The Deliverd Engineering Team