Stop the file-watcher's indexing lag from making freshly-written docs…#388
Merged
Conversation
…ps causing stale link/title results (PRD-7201) (#2255) * fix(open-knowledge): unify doc-existence oracle so file-index lag stops causing stale link/title results (PRD-7201) Follow-up to PR #2248 (PRD-7194). The file-watcher's file index lags in-session writes and can permanently drop the create FSEvent for a file written into a freshly-created subdir, so a brand-new doc rendered as a raw red-link name and its links could read as dead until a server restart. #2248 fixed only the dead-link endpoint; this generalizes the fix to all doc-existence consumers. Finding 1 — graph as an additive existence oracle. New BacklinkIndex.getIndexedDocNames() exposes the in-process forward-node set; collectAdmittedDocNames() unions it, so the 6 link/title consumers (brokenLinks validation x3, forward-links / link-graph / hubs title resolution) agree with the dead-link endpoint that already folds in the same set. Finding 2 — self-register at the write source. handleAgentWriteMd / handleAgentPatch / handleFrontmatterPatch register the doc they just persisted into the file index via a shared registerWrittenDocInFileIndex() (mirrors /api/create-page), closing the dropped-FSEvent gap for the write path and fixing the direct getFileIndex() consumers (ls, orphans, hubs) too. Content-scope safety: the write handlers reject only reserved system/config names, not gitignore/okignore-excluded paths, so an agent CAN write to an excluded doc — making it a forward node (and, naively, a file-index entry). Both new paths therefore gate on the same isExcluded predicate the watcher uses (precedent #55), so an excluded doc never becomes admitted and never leaks its on-disk title/frontmatter through the link/title endpoints. The existing excluded-targets test is upgraded to pin this gate against a forward node that is content-scope-excluded. * test(open-knowledge): cover the kind:update branch of file-index registration (PRD-7201) Addresses claude[bot]'s review note on #2255: the four existing cases all wire an empty file index, so registerWrittenDocInFileIndex only ever took the kind:'create' branch. Add a case that pre-seeds the doc so a re-registration (watcher dropped a later event for an already-indexed doc) takes the kind:'update' branch. --------- GitOrigin-RevId: 7101fb715a66470dcb4ba791126d361c9aa94f50
![inkeep-internal-ci[bot]](https://avatars.githubusercontent.com/in/2806322?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Automated approval from agents-private public-mirror-sync (run: https://github.com/inkeep/agents-private/actions/runs/28453373246). Source of truth is the monorepo; direct edits on inkeep/open-knowledge are overwritten on next sync.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stop the file-watcher's indexing lag from making freshly-written docs look missing across link, title, and dead-link results. The file index the watcher maintains can lag an in-session write — or permanently drop the create event for a file written into a just-created subfolder — which made a brand-new doc render as a raw red-link name (instead of its title) and could flag a valid link to it as dead, until a server restart. Two complementary fixes close the gap: doc-existence now also trusts the link graph (updated in-process on every write), and the agent write/edit/frontmatter-patch handlers register the doc they just wrote into the file index immediately, mirroring page creation. Both paths honor content-scope exclusions, so a gitignore/okignore'd doc never leaks its title through these endpoints.