# taco3064/nibfin-core architecture

> Architecture diagram of the GitHub repository taco3064/nibfin-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taco3064/nibfin-core
- Repository: https://github.com/taco3064/nibfin-core

## Overview

Nibfin Core is an early-stage delivery engine for controlled, staged GitHub Issue work. The principal workflow begins with an Actions/controller request, adopts and validates the host and caller, admits a bounded stage using fresh GitHub observations, executes through installed adapters, records durable evidence, and performs narrowly authorized publication or merge operations. The README documents lifecycle composition and security boundaries; source excerpts directly establish controller routing and the dedicated-engine installation path. Several capability branches are documented but their detailed runtime wiring was not sampled, so those relationships are omitted or cited to the README.

Main entry points: [`src/host-launcher.mjs`](https://github.com/taco3064/nibfin-core/blob/main/src/host-launcher.mjs) (Stage launcher), [`src/stage-runtime.mjs`](https://github.com/taco3064/nibfin-core/blob/main/src/stage-runtime.mjs) (Stage runtime), [`src/security/shared-worker-admission.mjs`](https://github.com/taco3064/nibfin-core/blob/main/src/security/shared-worker-admission.mjs) (Shared job admission), [`bin/nibfin-controller.mjs`](https://github.com/taco3064/nibfin-core/blob/main/bin/nibfin-controller.mjs) (Controller CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and adoption"]
  node_controller["Controller CLI"]
  node_host_adoption["Host adoption<br/>[host-adoption.mjs]"]
  node_host_launcher["Stage launcher<br/>[host-launcher.mjs]"]
  node_issue_wake["Issue wake"]
end

subgraph group_authority["Authorization and admission"]
  node_github_reader["GitHub reader<br/>[github-read.mjs]"]
  node_approval["Native approval"]
  node_caller_source["Caller continuity<br/>[caller-source.mjs]"]
  node_shared_admission["Shared job admission"]
end

subgraph group_execution["Stage execution"]
  node_stage_runtime["Stage runtime<br/>[stage-runtime.mjs]"]
  node_native_observer["Native observer"]
  node_stage_handlers["Stage handlers<br/>[stage-handlers.mjs]"]
  node_candidate_capture["Candidate capture"]
  node_hook_adapter["Offline hooks<br/>[docker-backend.mjs]"]
end

subgraph group_isolation["Host isolation"]
  node_engine_install["Engine installer<br/>[engine-install.mjs]"]
  node_engine_host["Engine host<br/>[engine-host.mjs]"]
  node_engine_probe["Isolation probe<br/>[engine-probe.mjs]"]
  node_shared_runner["Shared Runner<br/>[shared-runner.mjs]"]
  node_source_package["Source verification<br/>[source-package.mjs]"]
end

subgraph group_evidence["Evidence and delivery"]
  node_operation_journal[("Operation journal")]
  node_evidence_store[("Evidence store<br/>[evidence-store.mjs]")]
  node_github_writes["Native writes<br/>[github-write.mjs]"]
  node_recovery_delivery["PR recovery"]
  node_identity["Evidence identity<br/>[identity.mjs]"]
end

node_actions(("GitHub Actions"))

node_actions -->|"invokes"| node_controller
node_controller -->|"launches stage"| node_host_launcher
node_controller -->|"launches wake"| node_issue_wake
node_host_launcher -->|"validates adoption"| node_host_adoption
node_host_launcher -->|"reads GitHub"| node_github_reader
node_host_launcher -->|"checks approval"| node_approval
node_host_launcher -->|"starts lifecycle"| node_stage_runtime
node_stage_runtime -->|"refreshes observations"| node_native_observer
node_stage_runtime -->|"dispatches stages"| node_stage_handlers
node_stage_runtime -->|"records operations"| node_operation_journal
node_stage_handlers -->|"captures candidate"| node_candidate_capture
node_stage_handlers -->|"runs offline hooks"| node_hook_adapter
node_shared_admission -->|"checks continuity"| node_caller_source
node_shared_admission -->|"validates workflow"| node_shared_runner
node_shared_admission -->|"reads assigned job"| node_github_reader
node_engine_install -->|"configures host"| node_engine_host
node_engine_install -->|"verifies isolation"| node_engine_probe
node_engine_host -->|"verifies installed source"| node_source_package
node_candidate_capture -->|"retains evidence"| node_evidence_store
node_stage_runtime -->|"authorizes writes"| node_github_writes
node_github_writes -.->|"publishes changes"| node_recovery_delivery
node_operation_journal -.->|"binds records"| node_identity

click node_controller "https://github.com/taco3064/nibfin-core/blob/main/bin/nibfin-controller.mjs"
click node_host_adoption "https://github.com/taco3064/nibfin-core/blob/main/src/host-adoption.mjs"
click node_host_launcher "https://github.com/taco3064/nibfin-core/blob/main/src/host-launcher.mjs"
click node_issue_wake "https://github.com/taco3064/nibfin-core/blob/main/src/host-issue-wake.mjs"
click node_github_reader "https://github.com/taco3064/nibfin-core/blob/main/src/github-read.mjs"
click node_approval "https://github.com/taco3064/nibfin-core/blob/main/src/github-approval.mjs"
click node_caller_source "https://github.com/taco3064/nibfin-core/blob/main/src/caller-source.mjs"
click node_shared_admission "https://github.com/taco3064/nibfin-core/blob/main/src/security/shared-worker-admission.mjs"
click node_stage_runtime "https://github.com/taco3064/nibfin-core/blob/main/src/stage-runtime.mjs"
click node_native_observer "https://github.com/taco3064/nibfin-core/blob/main/src/native-observer.mjs"
click node_stage_handlers "https://github.com/taco3064/nibfin-core/blob/main/src/stage-handlers.mjs"
click node_candidate_capture "https://github.com/taco3064/nibfin-core/blob/main/src/candidate-evidence.mjs"
click node_hook_adapter "https://github.com/taco3064/nibfin-core/blob/main/src/docker-backend.mjs"
click node_engine_install "https://github.com/taco3064/nibfin-core/blob/main/src/engine-install.mjs"
click node_engine_host "https://github.com/taco3064/nibfin-core/blob/main/src/engine-host.mjs"
click node_engine_probe "https://github.com/taco3064/nibfin-core/blob/main/src/engine-probe.mjs"
click node_shared_runner "https://github.com/taco3064/nibfin-core/blob/main/src/shared-runner.mjs"
click node_operation_journal "https://github.com/taco3064/nibfin-core/blob/main/src/operation-journal.mjs"
click node_evidence_store "https://github.com/taco3064/nibfin-core/blob/main/src/evidence-store.mjs"
click node_github_writes "https://github.com/taco3064/nibfin-core/blob/main/src/github-write.mjs"
click node_recovery_delivery "https://github.com/taco3064/nibfin-core/blob/main/src/recover-commit-pr.mjs"
click node_source_package "https://github.com/taco3064/nibfin-core/blob/main/src/source-package.mjs"
click node_identity "https://github.com/taco3064/nibfin-core/blob/main/src/identity.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controller,node_host_adoption,node_host_launcher,node_issue_wake toneBlue
class node_github_reader,node_approval,node_caller_source,node_shared_admission toneAmber
class node_stage_runtime,node_native_observer,node_stage_handlers,node_candidate_capture,node_hook_adapter toneMint
class node_engine_install,node_engine_host,node_engine_probe,node_shared_runner,node_source_package toneRose
class node_operation_journal,node_evidence_store,node_github_writes,node_recovery_delivery,node_identity,node_actions toneIndigo
```

## Components

### Entry and adoption

- [Controller CLI](https://github.com/taco3064/nibfin-core/blob/main/bin/nibfin-controller.mjs): `bin/nibfin-controller.mjs`
- [Host adoption](https://github.com/taco3064/nibfin-core/blob/main/src/host-adoption.mjs): `src/host-adoption.mjs`
- [Stage launcher](https://github.com/taco3064/nibfin-core/blob/main/src/host-launcher.mjs): `src/host-launcher.mjs`
- [Issue wake](https://github.com/taco3064/nibfin-core/blob/main/src/host-issue-wake.mjs): `src/host-issue-wake.mjs`

### Authorization and admission

- [GitHub reader](https://github.com/taco3064/nibfin-core/blob/main/src/github-read.mjs): `src/github-read.mjs`
- [Native approval](https://github.com/taco3064/nibfin-core/blob/main/src/github-approval.mjs): `src/github-approval.mjs`
- [Caller continuity](https://github.com/taco3064/nibfin-core/blob/main/src/caller-source.mjs): `src/caller-source.mjs`
- [Shared job admission](https://github.com/taco3064/nibfin-core/blob/main/src/security/shared-worker-admission.mjs): `src/security/shared-worker-admission.mjs`

### Stage execution

- [Stage runtime](https://github.com/taco3064/nibfin-core/blob/main/src/stage-runtime.mjs): `src/stage-runtime.mjs`
- [Native observer](https://github.com/taco3064/nibfin-core/blob/main/src/native-observer.mjs): `src/native-observer.mjs`
- [Stage handlers](https://github.com/taco3064/nibfin-core/blob/main/src/stage-handlers.mjs): `src/stage-handlers.mjs`
- [Candidate capture](https://github.com/taco3064/nibfin-core/blob/main/src/candidate-evidence.mjs): `src/candidate-evidence.mjs`
- [Offline hooks](https://github.com/taco3064/nibfin-core/blob/main/src/docker-backend.mjs): `src/docker-backend.mjs`

### Host isolation

- [Engine installer](https://github.com/taco3064/nibfin-core/blob/main/src/engine-install.mjs): `src/engine-install.mjs`
- [Engine host](https://github.com/taco3064/nibfin-core/blob/main/src/engine-host.mjs): `src/engine-host.mjs`
- [Isolation probe](https://github.com/taco3064/nibfin-core/blob/main/src/engine-probe.mjs): `src/engine-probe.mjs`
- [Shared Runner](https://github.com/taco3064/nibfin-core/blob/main/src/shared-runner.mjs): `src/shared-runner.mjs`
- [Source verification](https://github.com/taco3064/nibfin-core/blob/main/src/source-package.mjs): `src/source-package.mjs`

### Evidence and delivery

- [Operation journal](https://github.com/taco3064/nibfin-core/blob/main/src/operation-journal.mjs): `src/operation-journal.mjs`
- [Evidence store](https://github.com/taco3064/nibfin-core/blob/main/src/evidence-store.mjs): `src/evidence-store.mjs`
- [Native writes](https://github.com/taco3064/nibfin-core/blob/main/src/github-write.mjs): `src/github-write.mjs`
- [PR recovery](https://github.com/taco3064/nibfin-core/blob/main/src/recover-commit-pr.mjs): `src/recover-commit-pr.mjs`
- [Evidence identity](https://github.com/taco3064/nibfin-core/blob/main/src/identity.mjs): `src/identity.mjs`

### Other components

- **GitHub Actions**

## Connections

- GitHub Actions → Controller CLI: invokes
- Controller CLI → Stage launcher: launches stage (evidence: `bin/nibfin-controller.mjs`)
- Controller CLI → Issue wake: launches wake (evidence: `bin/nibfin-controller.mjs`)
- Stage launcher → Host adoption: validates adoption (evidence: `src/host-launcher.mjs`)
- Stage launcher → GitHub reader: reads GitHub (evidence: `src/host-launcher.mjs`)
- Stage launcher → Native approval: checks approval (evidence: `src/host-launcher.mjs`)
- Stage launcher → Stage runtime: starts lifecycle
- Stage runtime → Native observer: refreshes observations
- Stage runtime → Stage handlers: dispatches stages
- Stage runtime → Operation journal: records operations
- Stage handlers → Candidate capture: captures candidate
- Stage handlers → Offline hooks: runs offline hooks
- Shared job admission → Caller continuity: checks continuity (evidence: `src/security/shared-worker-admission.mjs`)
- Shared job admission → Shared Runner: validates workflow (evidence: `src/security/shared-worker-admission.mjs`)
- Shared job admission → GitHub reader: reads assigned job (evidence: `src/security/shared-worker-admission.mjs`)
- Engine installer → Engine host: configures host (evidence: `src/engine-install.mjs`)
- Engine installer → Isolation probe: verifies isolation (evidence: `src/engine-install.mjs`)
- Engine host → Source verification: verifies installed source (evidence: `src/engine-host.mjs`)
- Candidate capture → Evidence store: retains evidence
- Stage runtime → Native writes: authorizes writes
- Native writes → PR recovery: publishes changes
- Operation journal → Evidence identity: binds records
