Evidence boundary
This system breakdown analyzes the OpenWiki lifecycle engine (src/generation), grounded claims subsystem (src/claims and src/okf), confined agent runner (src/agent), and MCP host integration (src/integrations/mcp) at commit 27d835cc617019795065ea0b30d9eb23e62b9789 (release v0.4.0).
1. Resumable .run.json Lifecycle & Source-Drift Invalidation
Documentation agents that generate dozens of wiki pages in a single monolithic conversation inevitably suffer from context exhaustion, partial writes on crash, and silent staleness when code changes mid-run. OpenWiki replaces monolithic prompting with a deterministic, crash-resumable state machine persisted in openwiki/.run.json (src/generation/repository-run.ts):
Two ordering invariants govern repository-run.ts:
- Claims Preflight Precedes Update No-Op Detection:
During openwiki update, prepareClaimsRuntime() audits every existing .claims/*.json sidecar before getUpdateNoopStatus() checks git rev-parse HEAD. Even if no Git commits occurred since .last-update.json, any unresolved or stale repo:// claim forces an active run and automatically injects repair PageJob entries via addRequiredClaimIssueJobs().
2. Whole-Plan Invalidation on Source Drift:
Both resumeRepositoryRun() and finishRepositoryRun() recompute createRepositorySourceFingerprint(). If any non-ignored repository file changed while the agent was authoring pages, requireStableSourceFingerprint() deletes state.plan, reverts phase to "planning", persists the updated .run.json, and throws a conflict RepositoryRunError. And .run.json is unlinked strictly as the final statement of finishRepositoryRun()—any earlier failure leaves the checkpoint intact for deterministic resumption.
2. Per-Page Worker Isolation & Non-Delegating Middleware
Whether driven natively via runNativeRepositoryGeneration() (src/agent/repository-runner.ts) or externally over MCP (src/integrations/mcp/server.ts), OpenWiki never reuses an agent thread across pages:
- Read-Only Planner Agent: Receives
PLANNER_FILESYSTEM_TOOLS(read_file,ls,glob,grep) andsubmit_plan. It cannot mutate any files. - Single-Page Scoped Writer Agents: For each pending
PageJob,runNativeRepositoryGeneration()constructs a fresh DeepAgents instance whoseOpenWikiLocalShellBackendrestrictswritableWikiPagesto[job.path]. - Stripping Subagent Delegation: Because
deepagentsmounts a general-purposetasksubagent tool by default,repository-runner.tsinjectsNO_DELEGATION_MIDDLEWAREto striptaskfrom every model call:
If a worker submits invalid YAML frontmatter or unresolvable repo:// evidence to submit_page, createSubmissionRejection() converts the RepositoryRunError into an error-status ToolMessage with concrete retry instructions, keeping the single-page worker loop alive until assertPageClaimsDurable() passes.
3. Grounded Claims Engine, repo-lines-v1 Relocation & OKF Projection
Every factual page under /openwiki/ is paired with a machine-owned sidecar under openwiki/.claims/<page>.json. When a worker submits claims (ProposedPageClaim[]), RepositoryEvidenceResolver (src/claims/evidence/repository/resolver.ts) resolves repo://path#Lstart-Lend citations without trusting the LLM:
- 7-Field Context-Hash Relocation (
repo-lines-v1:sha256:): Line numbers shift whenever upstream files are edited above a cited function. When establishing a line-range citation,RepositoryEvidenceResolvercomputes the SHA-256 digest of the selected lines plus 7 relocation metadata fields (LineRangeVersionMetadata):selectedLineCount,firstSelectedLineHash, andlastSelectedLineHashprecedingContextLineCountandprecedingContextHash(up to 3 lines before the span)followingContextLineCountandfollowingContextHash(up to 3 lines after the span) On subsequent runs, if the original line numbers no longer matchcontentHash, the resolver scans the file using the first/last line hashes and 3-line boundary context hashes to deterministically relocate the span or classify the claim asstale/unresolved.
- Dual-Digest Synchronization & Transactional Rollback:
During
finalize(),synchronizeClaimsVerification()(src/okf/claims-verification.ts) projects{ by: "openwiki/0.4.0", at: ... }into each Markdown file's YAML frontmatterverifiedlist while retaining any human or third-party verifier stamps. Because modifying frontmatter changes the Markdown file's bytes,finalizeVerificationProjection()immediately callssession.refreshPageVersions()to updatepageVersion(sha256:<64-hex>) inopenwiki/.claims/<page>.json. If any sidecar hash refresh fails,rollbackClaimsVerification()restores the exact pre-projection Markdown bytes.
4. Defense-in-Depth Confinement: OpenWikiLocalShellBackend
Because OpenWiki documents arbitrary repositories, all repository source files and commit messages are treated as untrusted evidence that may contain indirect prompt injection payloads. OpenWikiLocalShellBackend (src/agent/docs-only-backend.ts) wraps the DeepAgents LocalShellBackend with three non-bypassable security gates:
.openwikiignoreRead & Discovery Gate:read,write,edit,uploadFiles, anddownloadFileshard-deny any path matching.openwikiignore. Discovery tools (ls,glob,grep) silently filter out ignored paths and reject unbounded root globs (**/*) or.gitmetadata scans.docsOnly&writableWikiPagesWrite Confinement: In repository mode, writes and edits outside/openwiki/(or outside the active job's singlewritableWikiPagesentry) are rejected before touching the OS filesystem.- Hidden
.claimsSidecars & Anchored Shell Allowlist: Theopenwiki/.claimsdirectory is completely hidden from agent filesystem tools and blocked viareferencesClaimsState()regex checks. Furthermore, whenever.openwikiignorerules are active, arbitrary shell execution is disabled and restricted to a strict 2-command anchored allowlist (/^pwd$/uand/^git\s+(?:--no-pager\s+)?rev-parse\s+HEAD$/u), preventing shell-based exfiltration of ignored secrets.
Continue Reading
All Blog PostsInside Agent Protocol: OpenAPI Control Plane, RFC 8610 CDDL Streaming & Thread Checkpoint Architecture
A production teardown of LangChain Agent Protocol (v0.1.6)—deconstructing the 5-router OpenAPI control plane, thread checkpoint branching, 9-channel RFC 8610 CDDL streaming, subgraph causation edges, and AST topological code generation.
Inside Autonomous Agentic Code Editor: AST Indexing, Diff Generation, and Sandbox Verification
A commit-pinned examination of autonomous agentic code refactoring architectures detailing tree-sitter AST symbol indexing, unified diff generation, and isolated sandbox execution loops.
Inside Apache Kafka Partition Storage & Zero-Copy Engine
An evidence-audited, 20-diagram interactive system breakdown tracing sequential commit log append (.log, .index, .timeindex), Linux sendfile() zero-copy page cache transfers, Producer RecordAccumulator memory pools, Consumer Group Cooperative Rebalancing, and KRaft quorum leader fencing.
